前言¶

在 DeepSeek Harness（DSH）里跑智能体，工具调用失败很常见：沙箱边界、受限 token、路径解析、编码或网络问题，往往在同一个项目里反复出现。手写 AGENTS.md 能固定一部分规则，但运行时新冒出来的坑，很难靠人工及时补全。

下面介绍的 dsh-pitfall-memory（维护者 baizhu66018，社区分类：记忆）面向这类问题：在运行中捕获工具失败，归并成可复用的 lesson，并在后续会话里通过 briefing 注入上下文，尽量让同一类坑只踩一次。它不是 AGENTS.md 的替代品——后者是你手写的规则；本插件从实际失败里补全手写文件尚未覆盖的部分。

DSH 生态主张「一切皆插件」；插件目录在 SkillHub 等独立站点展示，与 DeepSeek / 幻方无官方从属关系。

这是什么¶

dsh-pitfall-memory 是 DSH 的长期失败记忆插件。简介（与仓库一致）：Long-term failure memory for DeepSeek Harness: captures tool failures, folds them into reusable lessons with session/daily/weekly summaries, and injects a briefing into later sessions.

数据在每次读取时做四层收敛，没有单独维护的手写文档树：

L1 observation   raw failure evidence: command, output, exit code
        │  rule classification + signature normalization
L2 lesson        one row per signature: symptom + the fix, with an occurrence count
        │  grouped by root cause
L3 pattern       why this area keeps failing (restricted token / sandbox boundary / runtime resolution …)
        │  first sentence of each fix, ranked by severity
L4 rule          the executable short list shown first in the briefing

核心功能¶

失败捕获与分类¶

开启 capture 后，插件记录工具失败证据（命令、输出、退出码等），经 16 条内置分类规则归一化 signature。覆盖沙箱越界、受限 token（管道、pip、mkdtemp 等）、运行时解析（如 store-aliased python）、CJK 编码、Git 身份、网络与凭据错误、未知工具等；未识别的条目落入两类 fallback，不会被丢弃。

首次运行且存储为空时，若 seed 为 true，会预置 14 条与本类环境相关的已知坑，首会话即可收到 briefing。

注入通道¶

Briefing 注册为动态上下文片段，随每次请求的 Current runtime context 快照下发，不依赖插件加载时机，重启后恢复的会话同样有效：

ctx.inject(['systemPrompt'], (scope) => {
  scope.systemPrompt.context({ name: 'pitfall:briefing', order: 950, text: render })
})

README 说明：仅通过 agent/pre-step 返回额外 messages 在测试中无法进入会话日志；应使用 systemPrompt.context（与内置 sandbox-policy、user-approval、subagent 等插件一致）。

三类摘要¶

工具与 Web 设置¶

模型可调用的工具包括：

重启 DSH 后，Settings → Plugins → Pitfall memory 出现两个标签页：Lessons（计数、状态筛选、symptom/fix 展开、re-activate / resolve / mute）与 Summaries（最新日/周摘要及 regenerate）。设置页后端通过 webServer.register 挂载 JSON API（如 /dsh-pitfall-memory/api/overview、/list、/summaries、/set-status、/refresh）；带 Origin 的请求须与 loopback Host 一致，否则 403。

安装与启用¶

插件以当前 DSH 进程权限运行；安装前请自行审阅 GitHub 源码 与 MIT 许可证。要求 Node.js >= 20（见 package.json）。

在插件仓库目录执行官方安装脚本（不要凭名称拼接 dsh plugin add）：

node scripts/install.mjs --dry-run      # preview the plan
node scripts/install.mjs                # copy into <profile>/node_modules and add to dsh.profile.bundles

然后重启 DSH。Briefing 与 pitfall_* 工具会立即可用；设置页需在重启后出现，因为 dsh-client-modules 仅在进程启动时扫描 dsh.client 声明。

配置与存储¶

行配置在 cordis.patch.yml，可在 profile 的 patch 里按 id pitfall-memory 覆盖。常用字段如下（默认值以 README 为准）：

默认存储目录 <profile>/.dsh-pitfall-memory/ 含 lessons.json（源数据）、lessons.md、observations.ndjson（约 1 MB 轮转）、state.json、summaries/、.heartbeat.jsonl。Lesson 归属最近含 .git 或 AGENTS.md 的祖先项目；scope: global 的 lesson 全局生效。

典型用法与排查¶

1. 按上文完成 install.mjs 并重启，确认 briefing 出现在系统上下文中。
2. 故意触发一次已知会失败的工具调用，观察是否写入 observation 并在后续会话 briefing 中出现对应 rule。
3. 用 pitfall_remember 补充模型已确认的「根因 + 修复」；用 pitfall_resolve 管理状态。
4. 会话结束前可用 pitfall_review / pitfall_summary 查看本 session 或日/周汇总。
5. 在设置页 Lessons / Summaries 做 mute、resolve 或 regenerate daily/weekly。

异常时运行：

node scripts/doctor.mjs

会依次检查 bundle 挂载、lesson 存储、heartbeat（apply-ok → context-render → settings-api-mounted）、dsh.client 声明；也可手工查看 .heartbeat.jsonl。

仓库提供 50 个纯 Node 测试（无需 DSH 运行时），可按 README 逐文件执行，例如 node test/detect.test.mjs；在 Windows 受限 token 下勿用 node --test test/（可能 EPERM）。

适用场景与注意¶

适合：长期在同一 DSH profile 与项目里开发，希望把重复工具失败变成可检索、可注入的教训，并配合日/周回顾整理规则。

注意：briefing 有字节上限，低频或 minOccurrences 较高的 lesson 可能暂时不出现在注入列表；子智能体默认不注入（injectIntoSubagents: false）。与手写 AGENTS.md 分工明确——插件补运行时缺口，重要稳定规则仍建议人工写入 AGENTS.md（weekly 摘要会提示可提升的规则）。

当前 package 版本 0.4.0，GitHub 星标为 0（以目录页为准），不代表功能完整性；以 README 与测试为准。

结尾¶

dsh-pitfall-memory 把「失败 → lesson → pattern → rule」做成每次读取时自动收敛的流水线，并通过 pitfall:briefing 进入后续会话，减少在同一环境重复踩坑。进一步了解可访问 SkillHub 目录页 与 GitHub 仓库；中文说明见仓库内 README.zh.md。