前言¶

在 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。