MiHjy12138/DSH-agent-procedures

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

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

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

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

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

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

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

三个原因，缺一不可：

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

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

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

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

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

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

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

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

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

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

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

# 分类-现象

> **触发**：<任务里会出现的现象>
> **验证**：<怎么确认这次真的成了——别拿「没报错」当成了>

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

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

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

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

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

往 agent 的指令文件（AGENTS.md / CLAUDE.md / 等价物）里加一段。4 条约定：

## 经验流程（procedures）

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

- **动手前**：任务撞上「网页抓不到正文 / 插件改了不生效」这类现象，先**搜**触发词，别凭记忆答：
  拿任务里的现象词搜 `procedures/*.md`（Windows：`Select-String -Path procedures\*.md -Pattern "<现象词>"`），
  命中哪张 read 哪张。卡少或搜不动时，列目录看文件名挑卡，一样算数。
- **踩到坑的当时**：只要不是「照着卡做就顺了」而是又试错了几轮 → 立刻往 `procedures/_inbox.md` 记一行。
  **别等收尾** —— 收尾要靠回忆，回忆不可靠。**记一行也算数。**
  **记 inbox 是记笔记、不是"动手改文件"** —— 就算被要求「只读 / 先别动手」，也照记不误。
- **收尾时（是检查，不是回忆）**：看 `_inbox.md` —— 够格的照 `_模板.md` 整理成卡
  （**文件名就是索引**：`分类-现象`），小意外留着下次。
- **不扫描、不复制**：不做启动式全库扫描；检索一律**定向** —— 拿现象词去搜，命中几张读几张。

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

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

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

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

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

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

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

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

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

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

推论：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

所以分工要固定：

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

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

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

结果：

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

这个选择其实更省：卡少时，文件名已经足够自解释 —— 列目录 484 字 vs 读索引 5.2 KB。

2026-10-15 复测（21 张卡）走的还是这条路，于是索引被改了：不再逐卡登记现象，只留几对易混现象的消歧（2368 字 → 约 260 字）。

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

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

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

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

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

1. 绑到一个会说出口的具体动作上。

   • ❌「任务结束时」—— 太抽象，没有时刻
   • ✅「在你说出『完成 / 搞定了 / 修好了』之前」—— 绑定到 agent 自己的产出动作

2. 写成必须回答的问题，而不是待办事项。

   • ❌「记得总结经验」
   • ✅「这次踩的坑，第二次了吗？」—— 问句逼出判断，判断逼出动作

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

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

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

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

那次实测的任务是「把一个文件备份到某个目录」—— 一个必然失败的操作（目标目录被沙箱的完整性层拦住）。会话全文只有两条真人消息，都没有「经验」二字；它自己排查出根因（区分了「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/。没有工具的话，肉眼看一眼它有没有列/读那个目录。

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

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

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

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

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

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

如果已经积累了大量历史会话，别从零开始——从旧会话里挖。

tools/scan-sessions.mjs 能解压并检索某类 agent 的会话日志（详见 tools/README.md，注意其中标注的失效风险）。典型的用法是先按主题扫：

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

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

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

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

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

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

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

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

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。但淘汰必须由人决定——自动删卡是比过期更坏的问题。

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

具体怎么用：

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

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

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

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

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

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

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

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

本仓库出处那个环境用的是自己写的轻量记忆架构（只记事实与偏好，不碰经验沉淀），所以两者并行没有冲突。换成一个"什么都往里记"的重量级插件时，冲突点通常不在技术层，而在同一份上下文预算被两边抢——上之前先量一下它每轮的固定开销。

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

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

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

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