经验卡库 MiHjy12138/DSH-agent-procedures

agent-procedures

给 AI 智能体用的文件化经验库 —— 让它不再重复踩同一个坑。

这不是技能，不是记忆插件，不是知识库，不是 RAG。它只是一套放在文件里的经验卡 + 一个索引 + 一条触发约定。

目录

1. 要解决的问题
2. 机制：三个零件
3. 设计原则：为什么是这样做
4. 反模式：不要做什么
5. 实测数据
6. 最容易失效的一环：收尾补卡
7. 快速上手
8. 已知短板
9. 能不能用在别的智能体上

一、要解决的问题

现象

智能体会反复踩同一个坑，而且往往在同一个项目里踩两次。

真实案例（脱敏）：一个智能体需要抓取某站点的分享页。

- 第一次：直抓页面 → 只拿到空壳（SPA）；试了 4 个错误的接口端点 → 全部返回 200 和同样的空壳；又试了浏览器渲染兜底 → 失败；最后靠一个第三方渲染代理走通。9 次尝试。
- 第二次（几周后、另一个会话、另一个分享链接）：直抓页面 → 空壳；试错误端点 → 空壳；换浏览器抓取 → 报错；6 次尝试后才走通，而且解法跟第一次不一样（这次是某个正确端点直连成功）。

两次都不知道对方存在。两条路都没留下字据。

为什么会这样

三个原因，缺一不可：

1. 会话是会结束的。 上下文一压缩、一会话一关，过程就没了。留下的只有结论，而结论往往没写。
2. 文档是为「怎么做」写的，不是为「别怎么做」写的。 技能、手册、README 都教正向流程；而智能体的时间大多花在试错上。试错的知识无处安放。
3. 搜索救不了。 就算能把历史会话全文检索出来，智能体也没法在动手前「检索」——它不知道该搜什么。你必须先知道坑的存在，才能去搜它。

第 3 点最关键：记忆是被动的，而触发必须是主动的。

为什么不做成技能

技能和经验的适用时机不同：

| | 技能 | 经验卡 |
| 回答 | 这件事怎么做 | 上次我是怎么趟过来的 |
| 触发 | 任务类型匹配 | 现象匹配（通常是失败现象） |
| 内容 | 步骤 | 首选姿势 + 反面清单 |
| 更新 | 版本化 | 复发时增补 |

技能的写法是「从头做一遍」，而经验卡的核心是反面清单——那些试过并且失败的路。这部分在技能体系里没有位置。

二、机制：三个零件

<工作区>/ AGENTS.md ← 钩子：4 行，常驻 procedures/ INDEX.md ← 索引：只登记「易混现象」，不逐卡列（见零件 1） <分类>-<现象>.md ← 卡：每张 ≤ 2 KB，命中才读 _模板.md ← 新卡骨架

零件 1：索引（INDEX.md）

索引不是卡片目录。卡名（分类-现象）和每张卡开头的 > 触发： 行已经承载了全部现象词 —— 索引只干一件卡名干不了的事：给容易混的几对现象消歧。

| 现象 | 读哪张 |
| 页面返回 200 却只有壳 / SPA / 分享链接 | 抓取-网页与分享链接 |
| 连接本身就失败（证书 / 超时 / 装不上） | 工具-本机连不上 GitHub |

一句话：现象词归卡，消歧归索引。 索引因此不随卡数增长 —— 新卡进库改的是文件名，不用回来改这张表。

为什么不逐卡列现象（2026-10-15 实测，21 张卡规模）：

| 层 | 体积 |
| 逐卡列现象的索引（含 markdown 语法与链接标签） | 2368 字 |
| 卡内「触发」行合计（同一批现象词的真正载体） | 1712 字 |
| 列目录看卡名（ls） | 484 字 |

逐卡索引 = 触发行的手工副本：同一批现象词写两遍，还得每次整表读。实测里智能体自己绕过它去 ls —— 它算得比谁都清楚。改成消歧层之后，索引从 5.2 KB 掉到 0.8 KB，此后不再随卡数增长。

零件 2：卡

每张 ≤ 2 KB，六段固定结构：

分类-现象

触发：<任务里会出现的现象> 锚点：<任务里会原样出现的字：域名 / 命令名 / 扩展名 / 报错原文> 验证：<怎么确认这次真的成了——别拿「没报错」当成了>

首选 <可直接复制的那一条：命令 / 参数 / 路径。不带解释。>

被挡时 <首选被挡时的兜底，1~2 条，按方便程度排。>

别再来
| 弯路 | 为什么不通 |
| <真试过并失败的> | <报错原文 / 为什么不成立> |

注意
- <为什么会错 —— 这条最贵>
- <判据是什么>

证据：<会话 id / commit / 文件路径>

锚点行是 2026-10-23 补的，起因是一次检索失败：任务里只有一个仓库链接、没有任何现象词，钩子没被触发，智能体直接去试工具，连撞几个卡里明写着不通的路子才回到卡库。

它解决的是「卡名说得清、任务词对不上」这一类：卡名 抓取-<平台> 走 CLI 里没有「链接」「装不装」这些词，但锚点行可以列那个平台的域名和安装写法。

写法两条：

- 只写任务里会原样出现的字 —— 英文与符号为主：域名、命令名、扩展名、报错原文、字段名。中文描述不算锚点。
- 一张卡 5–8 个，多了等于没写。

代价：每张卡多一行（约 60–100 字节），换来的是一层可精确 grep 的索引。

零件 3：钩子

往智能体的指令文件（AGENTS.md / CLAUDE.md / 等价物）里加一段。4 条约定（第 1 条 2026-10-23 重写过，原因见下）：

经验流程（procedures）

各工作区 procedures/ 存踩过的坑，不常驻注入，按需读。

- 动手前 · 两步，别只做第二步：
- ① 冷启动：任务里出现 URL / 仓库链接 / 「装不装、值不值得装」 这类动作时，还没撞上任何现象就先搜一次（按任务里的名词），命中就直接打开第一张；第一次失败后必须回头查一次卡库，再动手修。
- ② 撞上现象（网页抓不到正文 / 改了不生效 / 报错原文）： grep -il "锚点.<任务词>" procedures/.md —— 只搜锚点行，一次一张；没命中再退回全文 grep -il "<任务词>" procedures/.md （Windows 无 grep：Select-String -Path procedures\.md -Pattern "锚点.<任务词>"）。
★ 搜的是任务词，不是「触发」这个字面词 —— 搜它只会把每张卡的触发行打出来，等于没筛。
★ 别用 glob / 列目录挑卡 —— 列名看不到锚点。
- 两步都不常驻、不列全库、不新增读卡工具 —— 仍是定向检索。
- 踩到坑的当时：只要不是「照着卡做就顺了」而是又试错了几轮 → 立刻往 procedures/_inbox.md 记一行。
别等收尾 —— 收尾要靠回忆，回忆不可靠。记一行也算数。
记 inbox 是记笔记、不是"动手改文件" —— 就算被要求「只读 / 先别动手」，也照记不误。
- 收尾时（是检查，不是回忆）：看 _inbox.md —— 够格的照 _模板.md 整理成卡（文件名就是索引：分类-现象），小意外留着下次。
- 不扫描、不复制：不做启动式全库扫描；检索一律定向 —— 拿现象词去搜，命中几张读几张。

第 1 条为什么要重写：原版写的是「任务撞上某个现象 → 搜现象词」。实测发现两个坑：

1. 冷启动漏检：任务里只有链接、没有现象词时，这句根本不会触发。智能体直接去试工具，撞了四堵墙才回卡库 —— 而卡里明写着前三堵不通。
2. 「搜」被写成动作而不是命令：智能体可能用 ls / glob 列文件名（看着像在搜，其实没筛），或者把 -Pattern 写成字面词「触发」（命中所有卡，等于没筛）。必须给确切命令，别只给动词。

这段常驻的成本约 0.6 KB。全部机制里唯一常驻的东西。

三、设计原则：为什么是这样做

这一节是本文档的重点。模板谁都能抄，判断标准抄不走。

原则 1：索引常驻、卡按需 —— 成本结构决定形态

一句话：让索引小到可以随时读，让卡大到只在需要时读。

具体数字（实测，21 张卡规模）：

| 层 | 何时进上下文 | 大小 |
| 钩子 | 每一轮 | ≈ 0.6 KB |
| 索引（消歧层） | 撞上经验类任务才读一次 | ≈ 0.8 KB（不随卡数增长） |
| 单张卡 | 触发词命中才读 | 1.4 ~ 3.5 KB |
| 全部卡 | 21 张全被撞上才会发生 | ≈ 43 KB |

对比：把全部卡塞进指令文件 = 每轮多付 43 KB。差 50 倍以上，而且大部分轮次根本用不上。

最后那行不是预算，是不可达的对照线。 不命中的卡永远不会进上下文 —— 真实账单只有「钩子 + 索引 + 命中的那几张」。它存在的唯一意义，是跟"全量常驻"作对比。

推论：索引必须比它索引的东西小得多。如果索引涨到和卡一样大，机制就退化成"每次都读全部" —— 这正是把索引从「逐卡目录」降级成「消歧层」的原因（见零件 1）。

原则 2：判据是「复发」

只踩过一次的坑先别成卡，除非代价极大。

为什么：孤例可能是巧合（环境抖动、一次性状态）。而复发说明这是结构性的——同样的条件会再次出现。

实测印证：有一张卡之所以够格，是因为在同仓库的 git 历史里找到了第二次——同一个病、不同的字符、不同的脚本，各触发一次失败。那次 commit 才是这张卡存在的理由。

推论：
- 收尾补卡时先问「这个坑第二次了吗」
- 孤例先记进临时的留痕（如 memory/），等复发再升格成卡

原则 3：删叙述，不删内容

这是精简卡片时唯一需要守的线。

| 删（叙述） | 留（内容） |
| 踩坑史整节 | 命令原文、参数、路径 |
| 实测输出的完整前后对照 | 报错原文 |
| 背景铺垫、「为什么写这张卡」 | 判据（怎么确认成功） |
| 重复叙述（同一结论说三遍） | 会话 id / commit（可回溯） |

判断方法：如果删掉它，执行者下次会做错——那就留。 如果只是"读起来更完整"，删。

实测（2026-10-14，当时 13 张卡）：从 77.8 KB 压到 26.6 KB（−65%），平均每张 2 KB，命令与报错原文一字未动。

原则 4：机制与数据分层 —— 这样新工作区零配置接入

机制（钩子）放全局，数据（索引 + 卡）放各工作区。

好处：新增一个工作区时，只需要建 procedures/ 目录，钩子那句写的是「该区的 procedures/」，自动生效，不用动指令文件。

反过来做（每个工作区各写一份机制说明）会导致：三份重复维护、且每份都要占常驻预算。

原则 5：不主动扫描

不要做"启动时扫描经验库"这种事。

- 扫描是一个动作，要多花一轮往返
- 而索引本来就是（或即将是）上下文的一部分——"扫描"应该是阅读，不是检索
- 「扫一次然后记住」更糟：上下文一压缩记忆就丢，而现实在变（新卡加入），记性反而变成过期缓存

唯一该付的钱：命中触发词后读整张卡。不命中，一分不花。

四、反模式：不要做什么

这一节比上一节更重要。大多数"改进"都会破坏这套机制。

❌ 反模式 1：把索引（或卡片）常驻注入

每轮多付 1~3 KB，且违反"按需"的全部意义。

❌ 反模式 2：把"读卡"包成一个工具

这条最隐蔽，因为它伪装成"提供能力"。

注册一个 lookup_procedure(query) 工具看起来最正统——但它有个致命细节：工具的 schema 本身常驻 system prompt。也就是说，注册工具 = 把「按需读的目录」变成「每一轮都列出来的目录」。

判据：任何让"未被使用的卡"进入上下文的方案，都是倒退——不管它叫注入、叫工具、还是叫索引。

❌ 反模式 3：写成"通用常识"

在任何一台机器上都成立的经验不算卡。

- ❌「记得处理编码」（废话，人人都该知道）
- ✅「本机控制台是 GBK，Python 打印某个区间之外的符号会让进程非零退出，于是测试被误判为失败」（这台机器、这个行为）

判据：如果换个环境这句话照样成立，它不是卡，是常识。

❌ 反模式 4：把卡片写成复盘报告

卡的目标读者是下次执行的智能体，不是评审。

- 卡 ≤ 2 KB
- 没有「踩坑史」（必要信息折进「注意」）
- 没有「实测输出」（只留结论与关键原文）
- 没有「为什么写这张卡」

❌ 反模式 5：只有正面流程，没有反面清单

反面清单是这套机制相对技能体系的唯一增量。一张只有「首选」的卡等于一份不完整的技能。

每条弯路必须写清「为什么不通」——不是「我试过不行」，而是「报错原文是 X / 机制上是 Y 所以不成立」。前者下次还会有人试。

❌ 反模式 6：把「不被读」当成罕见情况

有人会问：卡放在文件里，它真的会去读吗？不会总是。钩子是「约定」不是「强制」——模型可能跳过、触发词可能对不上、任务级指令可能优先（例如任务明令只读时，它连 _inbox.md 都不会写）。

把这条代价摆上台面，而不是假装没有：

| 方案 | 每轮固定成本 | 换到的东西 |
| 本机制：钩子常驻 + 卡按需读 | 约 0.5 KB | 「可能不读」，但读的时候只付被读到的那张 |
| 全塞进指令文件 | 约 26 KB（卡再多还涨） | 「一定在上下文里」，但会挤掉真正要紧的东西 |

50 倍的成本差就是这套机制成立的理由。反过来说：如果某天发现它完全不读卡，该查的是钩子和触发词，不是把卡塞进注入层——那是用 26 KB 掩盖一个「钩子没写对」的问题。

同理，「卡过时了怎么办」也不该靠自动删：删卡的判据（对象真的没了 / 已被别的卡覆盖 / 有没有别处引用）都需要人判断。智能体出清单 → 人审 → 才动，见「7. 定期体检」。

❌ 反模式 7：把写卡权限整个交给智能体

入卡也要人审，不只是删卡。

听上去很顺：让智能体踩到坑就自己写卡、自己整理 inbox。实际结果是库会快速膨胀，而且膨胀出来的多半是「它这一轮学到的」而不是「你下次真的会再踩的」。

本仓库出处那个库的实测（2026-10-18）：一次精简就移出约四分之一的卡 —— 其中部分是对象已经卸载的软件、部分重复、部分是一次性完成后不会再用的操作。这些卡都是当时看着很该记的，是时间证明它们不该留。

所以分工要固定：

| 谁 | 做什么 |
| 智能体 | 踩坑当下记一行 inbox（门槛极低）；定期跑 procedures-audit.mjs / procedures-review.mjs 出清单 |
| 人 | 决定哪一行升成卡、哪张卡该补该并该退役。入库和出库都要过这道门 |

代价是每次要花几分钟看清单。换来的是库不会长成一个「什么都有、什么都不精」的垃圾场——而这个代价，比一年后重读 80 张废卡便宜得多。

❌ 反模式 8：把「搜」写成动词，不给确切命令

「先搜触发词」听着够清楚，落地时会变形，实测见过三种：

| 变形 | 结果 |
| ls / glob 列文件名 | 看着像在搜，其实没筛 —— 列完还得靠猜 |
| -Pattern 写成字面词「触发」 | 命中每一张卡，等于没筛 |
| 搜完不打开 | 搜 ≠ 读，两个动作要分开写 |

给命令，不给动词。

- 先搜触发词，命中哪张读哪张
+ grep -il "锚点.<任务词>" procedures/.md # 只搜锚点行，命中就打开第一张
+ grep -il "<任务词>" procedures/.md # 没命中再退全文

判据：这条命令跑一遍，输出里应当只有 1–2 个文件名。输出几十个 = 它没有在筛。

五、实测数据

以下都来自真实运行，不是估算。

端到端验证：机制真的会被触发吗

方法：新开一个会话，一次性抛出 5 个分属不同卡片的现象 + 1 个不命中任何卡片的问题；同时用探针监控该会话的工具调用。

结果：

| 观察项 | 结果 |
| 是否触发 | 首轮就查了 procedures 目录（无人提醒，靠指令文件里的钩子） |
| 命中率 | 5 道题 → 5/5 读到了对应卡 |
| 判断分层 | 先粗读 5 张，再按题精读第 6 张 |
| 对照题 | 不命中任何卡的问题 → 没有乱翻（去查了外部工具，没读卡） |
| 代价 | 读 6 张卡 ≈ 12 KB |

冷启动：只有链接、没有现象词（2026-10-23）

方法：干净上下文的智能体，只给一个仓库链接 + 一句「看看这个该不该装」，同一句话测三遍（改钩子前 / 改后 / 再收紧）。

| 版本 | 第一步 | 撞墙次数 | 读到卡 |
| 现象驱动（原钩子） | 直接抓网页 | 4 | 0 |
| 加「冷启动」 | grep 任务词 | 1 | 第 4 步才读 |
| 再加「搜完必须打开第一张」「别用 glob」 | grep 任务词 | 0 | 第 3 步 |

中间那一堵墙的原因值得记：智能体搜了（用 glob 列文件名），但没打开卡就先试了个想当然的地址。搜≠读，两个动作要分开写。

锚点层 vs 全文层（同一任务词）

| 任务词类型 | 只搜锚点行 | 全文搜 |
| 表格类（Excel） | 1 张 | 1 张 |
| 编码缩写（BOM） | 1 张 | 多张，含无关卡 |
| 报错短语（Access denied） | 1 张 | 2 张 |

全文搜会撞上正文里偶然提到的词；锚点行是卡自己声明的入口，不是碰巧出现过的字。

一个反面样本：任务说「跑一下看看」时，它会跳过卡

同一批检验里，问「跑一句 python 看 stdout 编码」，智能体没读卡就去跑实验，测了普通中文（不崩），结论写成「默认不会非零退出」。而卡里写的报错原文是 'gbk' codec can't encode character —— 指的是 gbk 编不了的字符（emoji 之类），拿 emoji 一测就 exit=1。

判据是「读卡」，不是「做实验」 —— 实验只覆盖你想到的那个变量。这条也反过来提醒：钩子里让智能体「验证」时，先让它把卡读完。

索引 vs 目录：一个意外发现

那次验证里，智能体没有读 INDEX.md，而是直接 ls 目录挑卡。

这个选择其实更省：卡少时，文件名已经足够自解释 —— 列目录 484 字 vs 读索引 5.2 KB。
2026-10-15 复测（21 张卡）走的还是这条路，于是索引被改了：不再逐卡登记现象，只留几对易混现象的消歧（2368 字 → 约 260 字）。

别把「没人读索引」当成机制失败 —— 先问：索引里还剩多少是卡名说不出来的东西？

2026-10-23 修正：这个结论有前提。 列目录只在「任务词 ≈ 卡名里的词」时省。任务里只有一个平台链接、卡名里没有对应词时，列目录挑不出来 —— 实测中 agent 列完文件名仍然去试了已知不通的工具；同一任务改用 grep -il "锚点.*<任务词>" 一次命中。

结论保留一半：不为「没人读索引」去补胖索引（这条仍成立），但也别把「列目录」当成检索（这条推翻）。两张卡都叫 工具-… 时，列目录分不出该读哪张；锚点行能。

精简的量化

| 批次 | 前 | 后 | 降幅 |
| 文件类 ×4 | 26.1 KB | 9.3 KB | −64% |
| 脚本类 ×4 | 19.5 KB | 8.1 KB | −59% |
| 工具类 ×4 | 29.6 KB | 8.1 KB | −73% |
| 合计 ×13 | 77.8 KB | 26.6 KB | −65% |

砍掉的是叙述，命令、路径、判据、报错原文一字未动。

六、最容易失效的一环：收尾补卡

这套机制有两条约定，它们的触发可靠性差得很远。这一节比前面所有模板都重要。

实测对比

| 约定 | 时机 | 实测结果 |
| 动手前读卡 | 任务撞上某个现象 | 首轮自发触发 —— 5 道题命中 5/5，无人提醒 |
| 收尾时补卡 | 任务结束 | 两次实测都没自发 —— 一次是任务里真没坑（这个正确），一次是真踩了坑却没想起（漏了） |

为什么差这么多

「动手前读卡」是任务驱动的：任务描述里出现「网页只有壳」，索引左列也写着同一句话 —— 匹配自动发生，外部输入触发了它。

「收尾补卡」没有触发点。活干完了，没有任何外部信号提示「你刚才踩了个坑」。它只能靠 agent 自己回想 —— 而自觉不可靠。

三条强化写法

1. 绑到一个会说出口的具体动作上。
- ❌「任务结束时」—— 太抽象，没有时刻
- ✅「在你说出『完成 / 搞定了 / 修好了』之前」—— 绑定到 agent 自己的产出动作

2. 写成必须回答的问题，而不是待办事项。
- ❌「记得总结经验」
- ✅「这次踩的坑，第二次了吗？」—— 问句逼出判断，判断逼出动作

3. 给一个比「写卡」轻得多的兜底。 一张合规的卡要 ≤ 2 KB、六段结构、报错原文 —— 门槛太高时，人（和 agent）会直接跳过。
所以在工作区放一个 procedures/_inbox.md：收尾时只在里面记一行（现象 + 一句话解法）。整理成卡留到下次开工 —— 那时你正好在读索引，顺手就做了。

一句话

别指望 agent「想起来」补卡。要么绑到它会说出口的动作上，要么把门槛降到一行字。

templates/AGENTS-snippet.md 里已经按这三条写好了，直接用。

实测补记：inbox 兜底才是主力路径

上面三条是推导出来的，后来被实测验证了一次，结论有修正：

| 路径 | 实测结果 |
| 收尾时写卡 | 只在有人提示时发生 —— 会话里说一句「看看有没有经验记录」就立刻做得很好；没人提就不做 |
| 踩坑当下记 inbox | ✅ 自发发生，全程无提示 |

那次实测的任务是「把一个文件备份到某个目录」—— 一个必然失败的操作（目标目录被沙箱的完整性层拦住）。会话全文只有两条真人消息，都没有「经验」二字；它自己排查出根因（区分了「DACL 全绿」与「Low IL 没传播」），自己决定记进 _inbox.md，并在回复里主动说明「下次直接认指纹」。

两个修正：

1. inbox 不是兜底，是主力。 原本把它当「来不及时的降级」，实测发现它是唯一被观察到的自发路径。写一张 ≤ 2 KB 的合规卡是个大动作，门槛太高会被跳过；记一行不会。
2. 时机应该再提前：踩坑当时就记，不要等收尾。 收尾需要「回忆」，而回忆不可靠；踩坑当下记，根本不会忘。

所以更实用的写法是：踩到坑的当时就往 _inbox.md 记一行；收尾时只做一次检查（看 inbox 有没有待整理的），而不是指望收尾能想起发生过什么。

七、快速上手

给负责安装的 agent（如果你是 agent，先读这段）

这个包需要你完成两件事，缺一不可：

1. 把钩子写进指令文件 —— 把 templates/AGENTS-snippet.md 的内容原样写进 AGENTS.md（或 CLAUDE.md / 等价物）。优先写全局那一份，这样所有工作区共享机制、新工作区零配置接入。
2. 在需要它的工作区建目录 —— 建 procedures/，放入 templates/INDEX.template.md 与 templates/card-template.md 的内容。

最常见的失败是只建了目录、忘了写钩子 —— 没有钩子，那些文件永远不会被读。

装完必须自检：新开一个会话，问一个应该命中卡片的现象，看它会不会去读 procedures/。没有工具的话，肉眼看一眼它有没有列/读那个目录。

1. 建目录

在每个需要它的工作区里：

procedures/
INDEX.md ← 消歧表，可以从空表开始 _模板.md

索引和模板直接复制 templates/ 下的两份。卡攒多了、开始分不清「项目专属」和「通用」时，看 templates/CLASSIFY.md 的判据。

2. 挂钩子

把 templates/AGENTS-snippet.md 的内容粘进 agent 的指令文件：

- 放在全局（~/.agent/AGENTS.md 之类）→ 所有工作区共享机制
- 或者放各工作区 → 只在需要时加载

推荐前者：机制只写一次，数据仍按工作区分。

3. 先挖一批历史（可选）

如果已经积累了大量历史会话，别从零开始——从旧会话里挖。
tools/scan-sessions.mjs 能解压并检索某类 agent 的会话日志（详见 tools/README.md，注意其中标注的失效风险）。典型用法是先按主题扫：

node tools/scan-sessions.mjs calls <workspace> "<关键词正则>"

然后按「复发」判据筛选——同一个现象在多个会话里出现过的，才值得成卡。

4. 写第一批卡

从最近踩过的坑开始，2~3 张就够，不要一次写 13 张。

每张照 _模板.md 写，写完用「反模式 4」自查一遍：有没有叙事、有没有实测输出、有没有"为什么写这张卡"。

5. 验证它真的会被用

tools/procedures-probe.mjs 是配套探针：盯住新会话，看它有没有主动去读 procedures。

新开一个会话，问 3~5 个分属不同卡片的现象，然后看探针输出里有没有 <<< HIT。一行都没有 = 钩子没生效，或者触发词写得不像"任务里会出现的词"。

6. 收尾补卡

任务收尾时只看一眼 _inbox.md：里面有够格的（复发的 / 代价大的）→ 整理成正式卡并加索引；只是小意外的 → 留着下次再说。

注意时机：别指望收尾能「回忆」起踩过什么坑——实测证明那不可靠。踩到坑的当时就往 _inbox.md 记一行，收尾只是检查。

7. 定期体检（攒到十几张以后）

node tools/procedures-audit.mjs # 静态：结构缺段、断链、体积、触发词覆盖、对象失效、结论偏旧

七项检查、只出清单，不写、不删、不改任何卡。退出码 1 表示有 P0/P1，可接 CI。

为什么淘汰不能自动化：删一张卡的判据是「对象真的没了 / 它已经被别的卡覆盖 / 有没有别处引用它」——这三件都要人判断。实测反例：一张讲 A 软件魔改的卡，对象卸载后确实该退役，但它同时是全局钩子里某条诊断的落点，删了会断链。所以正确姿势是 agent 出清单 → 人审 → 才动，工具只负责把清单出全。

八、已知短板

诚实列出来，免得你踩进去：

1. 索引容易被绕过。 卡名自解释时，列目录比读索引省（实测 484 字 vs 5.2 KB）。所以索引只留卡名说不了的消歧 —— 它的价值不在"列全"，在"分辨"。
2. 依赖 agent 的自律。 钩子是"约定"，不是"强制"。如果模型不照做，机制就不生效——探针存在的意义就是能发现这件事。
3. 触发词匹配是模糊的。 现象描述写得不好，就匹配不上；这是这套机制里最需要反复调的部分，也是它唯一的"手艺"。
4. 跨工作区不会自动共享。 全局钩子让机制通用，但卡是按工作区存的——一个坑在 A 区踩过，B 区不会自动看到。想共享得放在全局目录（本仓库不推荐，会破坏按需）。
5. 工具层会随宿主升级失效。 scan-sessions.mjs / procedures-probe.mjs 依赖特定 agent 的会话日志格式；procedures-audit.mjs 只看文件、跨平台通用。所有工具都只是附件，核心机制不依赖任何工具。
6. 卡会过期，而且不会自己消失。 绑版本、路径、产物名的卡隔一阵就失效；失效后留在库里会误导下一次。现行缓解：分层给不同复核期（_layers.md）+ 定期跑 procedures-audit.mjs。但淘汰必须由人决定——自动删卡是比过期更坏的问题。

九、能不能用在别的 agent 上

机制通用，工具专用。 这套东西分两层，移植性完全不同：

| 层 | 内容 | 移植性 |
| 机制 | 索引 + 卡片 + 指令文件里的钩子 | ✅ 通用 —— 只要那个 agent 会读 AGENTS.md（或 CLAUDE.md / 等价物），机制就成立 |
| 工具 | tools/ 里的三个脚本 | ⚠️ 混合 —— procedures-audit.mjs 只看卡文件、跨平台通用；scan-sessions.mjs / procedures-probe.mjs 依赖特定宿主的会话日志格式，换 agent 会作废 |

具体怎么用：

- Claude Code / Cursor / Codex / Gemini CLI 等 —— 把 templates/AGENTS-snippet.md 写进它认的那个指令文件即可。工具那层跳过：它们各有自己的会话记录方式，想「从历史挖经验」得自己写扫描器（或干脆不挖，从当下开始积累）。
- DeepSeek Harness —— 全套可用，tools/ 就是为它写的。
- 其他任何东西 —— 机制照样成立，你需要自己解决「怎么从历史会话里挖经验」这一步。

多 agent 环境：每个 agent 都要单独验一遍钩子

「机制通用」不等于「装上就灵」。 不同 agent 对指令文件的处理差异很大：

- 有的会读 AGENTS.md 但不一定读 CLAUDE.md（或者反过来）；
- 有的读了指令文件，但遇到现象时不会主动去 grep procedures/；
- 有的在只读沙箱里连 _inbox.md 都写不了。

所以钩子要在每个你实际在用的 agent 里各验一次，验法很简单：新开一个会话，给它一个「分属某张卡的现象词」，看它会不会去读那张卡。不读就是没生效——这时候要改的是那个 agent 的钩子位置或措辞，别急着加卡。

tools/procedures-probe.mjs 只能验 DeepSeek Harness（它读 DSH 的会话日志）；其他 agent 请用最原始的办法：人肉观察它有没有去读。

与记忆插件的关系：只在「功能重叠」时才冲突

这是被问得最多的一个问题，答案很简单：

只有一种情况会冲突——那个记忆插件本身就带「经验沉淀 / 教训记录 / 错误归档」功能。 两边都在收"踩过的坑"，就会重复记、甚至互相踩。那种情况下选一个，别两个都上。

其余情况不冲突，因为它们管的不是同一件事：

| | 记什么 | 什么时候用 |
| 记忆插件 | 事实、偏好、项目结构、用户习惯 | 每轮都可能在用 |
| 本机制 | 试过并且失败的路、判据、可抄的命令 | 撞上现象才查 |
本仓库出处那个环境用的是自己写的轻量记忆架构（只记事实与偏好，不碰经验沉淀），所以两者并行没有冲突。换成一个「什么都往里记」的重量级插件时，冲突点通常不在技术层，而在同一份上下文预算被两边抢——上之前先量一下它每轮的固定开销。

为什么机制这么容易移植：它不依赖任何 API、插件系统、数据库，也不依赖特定的模型能力。只依赖两样东西——文件，和智能体会读指令文件这个事实。

这也是本仓库名字带宿主前缀、内容主体却不绑宿主的原因：名字标的是工具那一层，方法论属于所有人。

授权

MIT。拿去用，改了不用告诉我。

如果这套东西帮你省下了一次重复踩坑，那就是它存在的全部意义。