前言¶
在 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
注：该目录页链接来自插件线索，未出现在已抓取资料正文中，访问前请自行确认。
