我以前也收藏命令。
临时排完一个问题，把最后跑通的那行 Shell 粘进当天笔记；遇到一条以后可能有用的命令，再补一句“下次还能这么做”。文件越来越多，真正需要时，我还是会翻历史、搜日报，或者重新查一遍文档。
后来我才意识到：我缺的不是另一个收藏夹，而是一条把“执行过的字符串”加工成“以后敢再用的知识”的流水线。
这条流水线至少要回答五个问题：
这条命令当时想解决什么问题？
哪些参数只是一次性的，哪些结构值得复用？
它是否夹带主机、路径、账号、令牌或业务数据？
下次应该按什么意图把它找回来？
保存之后，什么时候还要再看一遍？
如果这些问题没有答案，Shell history 再完整，也只是历史；Markdown 再多，也只是堆积。
先说明证据边界：本文来自我的实现日志、一次同步产物和一组本地构建截图。日志记录了我做过什么，截图证明当时界面上能看到什么；没有源码、运行日志或可复现启动步骤的部分，我不会把它写成已经独立复验的事实。
一、收藏命令为什么总会失效
终端历史擅长记录“发生过什么”，却不负责保存“为什么这么做”。同一条命令换了目录、机器、版本或权限，风险可能完全不同。
按日期写的笔记也有类似问题。人回忆时先想到的是“导出 Docker 镜像”“排查端口占用”，未必记得当时写的是 docker save 还是别的子命令。你想按意图搜索，笔记却按日期组织。
更麻烦的是，真实命令天然可能带有不该长期保存的东西：
内网地址、主机名和用户名；
Token、API Key、Cookie 和连接串；
本机绝对路径、仓库名和项目名；
命令参数里的业务正文或数据标识。
所以我把“入口处最小化收集和脱敏”设为这套个人工具的安全政策：原始字符串一旦被持久化、同步或传给模型，暴露面就会扩大，事后删除不能替代入口控制。这是我的设计选择，不是适用于所有威胁模型的通用结论。
如果你只需要更好地搜索历史，先评估 Atuin；如果只是保存少量参数化片段，Pet 这类 snippet manager 已经覆盖了保存、标签、搜索和执行。我想补的是后半段：命令被找回来以后，怎样经过脱敏、归并、解释和复习，才有资格成为长期知识。
二、先把“历史”和“知识”拆开
在我的实现记录里，这套工具叫 cmdbook。我把数据拆成四类对象，并给 Command Family 区分“草稿”和“已确认”两种状态：
Usage Event：某条命令在某个时间、环境里被用过。它是证据，不是知识条目。
Inbox Item：经过第一轮脱敏、等待人处理的候选项。它可以被修正、丢弃或归档。
Command Family：按意图和主命令归并的条目；归并后先是草稿，只有最终人工确认后才成为长期知识，例如
docker save。Variant：同一命令族在不同参数结构、前置条件或风险边界下的变体。
这个拆分很重要。
如果把每次执行都直接写成一篇笔记，知识库会退化成另一份 Shell history；如果一开始就把相似命令强行合并，又会丢掉真正不同的参数结构和适用边界。
更稳妥的路径是：事件先进入待整理池，人工纠正脱敏后归并为草稿命令族；经过检索预览和复习排期，最终确认才把草稿提升为长期知识。
三、一条命令怎样进入知识库
1. 采集时先筛选，不要先全量囤积
我的实现日志记录了两种入口：主动记录，以及从 history、Shell hook 或手动同步的 WSL/SSH 记录中生成候选项。
主动记录。 下面的 GIF 从空表单开始，依次输入通用命令 docker logs api --tail 100、一行用途，再展开“完整资料”字段。画面停在填写阶段，没有点击“先保存”或“AI 整理”。
快速记录局部：填写命令和用途，再展开完整资料；点击图片可查看未裁剪 GIF。
被动收集。 另一张截图显示了本机 history、WSL 和 SSH 三个导入入口，以及 Shell、风险、敏感状态筛选控件。侧栏计数是 205 待整理，但当前截图没有拍到具体条目行，也没有执行导入或筛选。为了让手机端看清，下面把同一张实机截图里的计数和三个导入入口纵向拼接；点击图片仍可查看未裁剪原图。
待整理池局部：205 条待整理计数和三个导入入口；点击图片可查看含筛选控件的未裁剪原图。
按实现日志，被动收集不等于无条件入库。像 cd、ls 这种高频低信息命令，失败退出且没有诊断价值的命令，或匹配排除规则的命令，都可以在进入待整理池前过滤。
日志还记录了这个版本采用的持久化边界：原始字符串只在本地采集过程中短暂停留，写入 SQLite 之前先做规则脱敏，持久化的第一站是“脱敏后的待整理项”。这项行为来自作者日志，不是上面的截图可以证明的。
2. 自动脱敏之后，仍要让人纠正
规则适合做第一层过滤，例如把疑似令牌替换成 <TOKEN>，把主机替换成 <HOST>，把绝对路径替换成 <PATH>。
正则可能漏报，也可能误报。因此我的实现记录把人工纠正放在待整理池里：人可以补掉漏出的敏感值，也可以恢复被过度替换、但确实需要保留的普通参数。
按该版本的设计，只有经过这一步，候选项才允许继续归并或交给 AI 生成说明草稿；导出和同步仍要等最终人工确认。整条处理顺序是：
本地采集
-> 写入前自动脱敏
-> 持久化脱敏后的待整理项
-> 人工纠正
-> 归并草稿命令族
-> 可选 AI 草稿
-> 检索预览 / 安排复习
-> 最终人工确认进入长期知识库
-> 备份 / Markdown 同步3. 按“意图 + 命令族 + 参数变体”归并
假设历史里出现过两条命令：
docker save -o "${ARCHIVE_A}" "${IMAGE_A}:${TAG_A}"
docker save -o "${ARCHIVE_B}" "${IMAGE_B}:${TAG_B}"Docker CLI 的版本固定文档把 -o / --output 定义为把输出写入文件。把具体镜像名、标签和归档路径泛化以后，这两条记录具有相同的命令结构和选项集合。
它们应该是两个 Usage Event、一个 Variant，而不是两篇几乎相同的笔记。
一个可复用条目至少应该包含：
意图：这条命令要解决什么问题；
命令模板：哪些值必须替换；
参数解释：关键选项分别做什么；
环境要求：Shell、操作系统、工具版本和权限；
风险提示：输出是否覆盖、操作是否可逆、目标是否安全；
来源与最近使用：它是否仍来自真实工作，而不是过期摘抄；
熟练度与复习时间：这条知识是否还需要重新确认。
4. AI 只写草稿，不替人定稿
命令解释很适合让 AI 起草，因为结构相对固定：意图、参数、场景、注意事项、环境要求。
但“说明生成”并没有在目标环境里执行或验证命令，也不知道本机的真实版本和权限。它生成的解释只能是候选内容。正确顺序应该是：
输入：已经脱敏的单条命令模板
输出：结构化说明草稿
核验：人对照 --help 或官方文档，确认后再归档我的密钥政策是：API Key 留在本机受控配置里，不进入 SQLite、备份、Markdown 导出或同步目录。其他部署方式需要按自己的密钥管理和威胁模型重新评估。
5. 搜索只是入口，复习才让知识再次出现
按实现记录，命令库计划支持三种找法：
按命令名搜索，例如
docker save；按中文意图搜索，例如“导出镜像”；
按分类、标签、环境、风险和熟练度筛选。
实机截图能确认的范围更窄：左侧是快速记录，右侧同时出现一个空搜索框，以及分类、标签、环境、熟练度、风险、敏感六类筛选和命令族结果卡片。因为搜索框为空，它没有演示中文意图查询或一次实际筛选。
命令库局部：一个空搜索框、六类筛选和命令族结果卡片；点击图片可查看未裁剪原图。
我的工作日志还记录了 FTS5 搜索、中文别名、复习优先级、最近复习时间和下次复习计划等实现与测试轨迹。这是作者自述记录；没有源码、运行日志或复现步骤，它不能升级为独立验证，更不能证明某种复习算法已经改善了记忆效果。
我更愿意把“复习”理解成一个朴素机制：让危险、说明不完整、长期没用或尚不熟练的条目，重新出现在人面前。实机页显示的是第 1/7 张 docker pull 卡片，题面要求先回忆用途、关键参数和风险。下面的局部图能清楚看到“显示答案”和“稍后再看”，未裁剪原图右上角还显示“打开详情”。
复习卡片局部：先回忆用途和风险，再选择显示答案或稍后再看；点击图片可查看含“打开详情”的未裁剪原图。
四、这次真正做出了什么
我的工作日志记录了一条密集的实现轨迹：cmdbook 从 CLI、Web 页面和 SQLite 数据层开始，逐步补上 history 导入、待整理池、命令族和参数变体、工作流、Hook 管理、脱敏校正、组合筛选、FTS5 搜索、复习计划、备份、Obsidian 同步和 AI 说明草稿。这仍是作者日志口径，不等于这些功能已经被当前源码或可复现运行独立验证。
直接产物能验证的范围更窄：一次同步生成的 Markdown 索引列出了 7 个命令族，包括 docker pull、docker save、uv add 和 python，当时工作流列表仍为空。
这三个证据层级不能混在一起：
工作日志只能证明“作者记录了哪些实现和测试”；
生成的 Markdown 只能证明“某次同步产出了哪些条目”；
实机素材只能证明“当时可见的界面和交互状态”。
由于没有源码提交号、可复现启动步骤或端到端日志，整条数据生命周期仍不能写成已经独立复验。
五、哪些地方不要自动化到底
以下内容不应该因为进入知识库就自动获得可信度：
会删除、迁移、发布、改权限或修改数据的命令；
没有在目标环境验证过的命令；
从网络复制、但没有版本和来源的片段；
含有真实 Shell history 的原始文件；
AI 生成但尚未对照文档核验的解释。
团队 Runbook 也不是个人命令库的自然升级版。团队场景需要权限、审计、版本发布和执行审批，不能直接共享个人历史来替代。
六、什么时候根本不必自己造
如果需求只是更快地搜索历史，先评估 Atuin；如果只是保存和执行少量参数化片段，先评估 Pet 或同类工具。
只有当你明确需要“写入前脱敏、人工纠正、命令归并、结构化解释、复习和 Markdown 投影”这一整条生命周期，而且现成工具无法覆盖时，自建一层才可能值得。
即使决定自建，也不要从漂亮界面开始。我会按这个顺序做最小版本：
本地采集和写入前脱敏；
脱敏后的待整理池与人工纠正；
命令族归并、搜索和归档；
Web 整理页与复习状态；
最后再接 AI 草稿、备份和 Obsidian 同步。
先验证一个问题就够了：下一次忘记命令时，它能否让我比翻聊天记录和日报更快找到一个经过确认的答案？
七、复盘：不要收藏字符串，要保存判断
Shell history 保存发生过的事；片段管理器保存以后可能执行的事；个人知识库还要保存为什么这么做、什么时候不能这么做，以及这条经验是否被重新确认过。
真正值得复用的不是 cmdbook 这个名字，也不是某个技术栈，而是三条设计原则：
原始记录和长期知识必须分层。
敏感信息要在持久化、同步和模型调用之前处理。
AI 负责生成结构化草稿，人负责决定什么可以成为知识。
别再把命令收藏进一个更大的抽屉。让它先经过筛选、脱敏、归并和确认，再进入一个以后敢搜索、敢复用、也值得复习的系统。