前言¶
在 DeepSeek Harness（DSH）中，智能體經常需要連續調用工具：執行命令、讀取文件、嘗試不同 API 或方案。某些嘗試失敗後，模型仍可能在同一會話或後續會話裏重複相同路徑。已有做法可能只在會話內提醒字節級重複，或依賴人工記住“這條路不通”；@akslcw/dsh-negative-ledger 的目標是把這類“已證僞路徑”持久化下來，並綁定證據和重試條件。
下面介紹這個插件的定位、核心機制、安裝方式、典型用法和適用邊界。本文基於已覈實的插件資料整理，不補充未確認的數據、星標數或用戶反饋。
這是什麼¶
- 名稱：
@akslcw/dsh-negative-ledger - 維護者：
akslcw - 許可證：
MIT - 定位：Agent negative-knowledge ledger for DeepSeek Harness。
- 核心作用：記錄失敗路徑，包括 failed commands、missing files、rejected approaches、unavailable APIs；每條記錄附帶證據和重試條件；當證據變化時，結論自動失效；重試成功後，事實被標記爲 resolved。
它明確不是：
- Not memory：不保存正向知識，也不做語義召回。
- Not a cache：保存的是結論，不是工具結果。
- Not a bug regression tracker：覆蓋工具調用和文件讀取，不侷限於修復嘗試。
核心機制¶
下面從“記錄、匹配、攔截、失效”四步說明。
1、記錄失敗路徑¶
插件只記錄已證僞路徑，而不是所有工具調用。可記錄的類型包括：
- failed commands
- missing files
- rejected approaches
- unavailable APIs
每條記錄會帶證據和重試條件。後續判斷是否重複嘗試，會依賴 fingerprint：
- 命令類嘗試：基於 normalized command plus cwd
- 文件類嘗試：基於 file path
2、匹配相同嘗試¶
當同一個 fingerprint 再次出現時，插件會判斷該失敗結論是否仍然有效。若證據未變化，則進入提示或攔截流程；若證據已變化，則結論失效，允許重試。
3、warn 與 block¶
插件提供 off、warn、block 三種模式：
warn：默認模式。在tools/post-execute上附加additionalContexts，不阻塞調用，也不改寫工具結果。block：在tools/pre-execute階段拒絕調用，發生在 dispatch 之前。off：完全關閉記錄與攔截。
4、證據變化後自動失效¶
如果記錄所依賴的證據發生變化，插件會自動 invalidates 相關結論，並允許重試。如果重試成功，事實被標記爲 resolved。
後端與接口¶
插件提供兩套 store 後端：
- SQLite 後端：支持 WAL、revision-based optimistic concurrency、operation receipts、retry leases、JSONL import。
- Legacy JSONL 後端：single-process，適用於單寫入場景。
Engine API 暴露以下方法：
getFact
queryFacts
commitAttemptDecision
recordFact
transitionFacts
settleLease
summarize
CLI 提供以下命令，並可選擇 SQLite 或 JSONL 後端：
list
show <id>
stale
stats
共享與安全邊界¶
- Ledger 在多個 agent 之間共享，子代理不會重複父代理已經失敗的嘗試。
- Claims 不嵌入原始命令文本；面向模型的預覽會做控制字符清理和長度限制。
- 原始命令保留在 ledger 文件中，作爲 fingerprint 使用；文件以
0600權限寫入0700目錄內。 - Ledger 將事實渲染爲 quoted data，不作爲 instructions 執行。
- Single-writer JSONL 只適用於 legacy backend；SQLite 後端支持多進程，使用 WAL。
安裝與啓用¶
DSH 的插件機制允許通過 profile 安裝和啓用擴展。本插件的安裝命令爲：
dsh plugin --profile <name> add @akslcw/dsh-negative-ledger
該命令會安裝插件，並激活其 bundle layer。插件包內提供 cordis.patch.yml，由 dsh.bundle manifest 聲明。
安裝後，可以先查看配置，再啓動 DSH：
dsh --profile <name> --dump-config
dsh --profile <name>
移除插件：
dsh plugin --profile <name> remove @akslcw/dsh-negative-ledger
運行環境要求：
Node ^22.19.0 || >=24.0.0
兼容性方面，插件已用 @deepseek-ai/dsh-tools 0.1.1-rc.2 測試，並聲明 optional peer range：
@deepseek-ai/dsh-tools >=0.1.1-rc.2 <0.2.0
pnpm 注意事項¶
pnpm >=11 可能將 ignored build scripts 變成硬錯誤，導致 add 失敗：
ERR_PNPM_IGNORED_BUILDS: better-sqlite3
資料說明，better-sqlite3 提供官方 prebuilds，該 ignored script 本身不會觸發編譯。若遇到該錯誤，可在 profile 目錄中執行：
pnpm config set --location project strict-dep-builds false
然後重新運行安裝命令：
dsh plugin --profile <name> add @akslcw/dsh-negative-ledger
如果改爲允許 build，則會從源碼編譯 better-sqlite3，並要求 C++ toolchain。
典型用法¶
CLI 查詢 ledger¶
在源碼倉庫內，可直接使用 CLI：
node src/cli.ts --dir .ledger stats
完整形式爲：
node src/cli.ts [--dir <path>] [--backend sqlite|jsonl] <list | show <id> | stale | stats>
其中：
list：列出事實，包括 status、kind、id、claim。show <id>：查看單條事實。stale：查看因證據變化而失效的事實。stats：查看攔截相關計數，例如 duplicate failures observed、warnings emitted、calls denied。
演示與 smoke 命令¶
資料中給出的可執行示例包括：
node demos/run-demos.ts
node smoke/real-mount.ts
powershell -File smoke/plugin-add-smoke.ps1
其中 powershell -File smoke/plugin-add-smoke.ps1 用於 clean-environment 端到端 smoke，覆蓋 add、layer、headless warn、SQLite ledger、remove 後 profile 仍可啓動等流程。
覆蓋配置行¶
插件提供 negative-ledger 配置行，支持以下鍵：
backend
mode
dir
commandRetryAfterMs
commandTools
readTools
後續 layer 可以按 id 覆蓋 negative-ledger 行，並重新聲明所有改動的配置鍵。例如只想調整 mode 時，不要只在 patch 裏寫一個孤立鍵；應在覆蓋行中完整表達新的 config，避免被整體替換後丟失其他鍵。
默認行爲上：
warn是默認模式，不會阻塞調用。block會在tools/pre-execute拒絕調用。off會關閉記錄和攔截。- Auto-recorded command facts 的
commandRetryAfterMs默認是 5 分鐘。 never和manual保留給顯式、可信作者記錄的事實。
適用場景與注意¶
適合使用本插件的場景包括：
- DSH 智能體反覆調用相同失敗命令。
- 文件不存在或路徑不可用，但 agent 仍會重複讀取。
- 某些 API 或方案在當前環境不可用，希望把“不要立刻再試”作爲證據綁定的約束。
- 多 agent 或 subagent 場景中，不希望子代理重複父代理已經失敗的嘗試。
- 需要可查詢、可統計、可隨證據變化而失效的負面事實記錄。
需要注意的邊界：
- 它不是正向記憶系統，不保存“什麼能做”的知識。
- 它不是緩存，不替代工具結果存儲。
- 它不是 bug regression tracker，不面向測試失敗或修復迴歸本身。
- 插件以當前 DSH 進程權限運行，安裝前應檢查源碼和
MIT許可證，確認其行爲符合本機安全要求。 - 資料中
Known limitations and deferred work部分被截斷，無法確認所有限制；使用前建議直接查看倉庫 README。 - DSH 生態通常以插件擴展 harness 能力；本文提到的插件屬於社區/插件線索生態，不應理解爲 DeepSeek 或幻方官方應用商店。
結尾¶
@akslcw/dsh-negative-ledger 的價值在於：它把失敗嘗試轉化爲可追蹤、可失效、可共享的負面事實。它不替代記憶、緩存或迴歸追蹤，而是針對“agent 反覆嘗試同一條已證僞路徑”的問題，提供證據綁定的 DSH 插件方案。
相關鏈接：
- GitHub：https://github.com/akslcw/dsh-negative-ledger
- 插件線索目錄頁：https://www.skillhub.cn/plugins/akslcw/dsh-negative-ledger
注：該目錄頁鏈接來自插件線索，未出現在已抓取資料正文中，訪問前請自行確認。
