前言¶

在 DSH 这类智能体运行时里，工具调用失败并不罕见。更麻烦的是，失败原因可能并不变，只是参数换了，模型还会继续重试。

dsh-failbook 针对这个问题做了一层记录与拦截：把工具调用失败写进账本，按失败原因聚类，并在同一失败签名反复出现时注入建议性提醒。它不替代工具执行，也不修改工具结果，只在失败发生时提供可见的记录和下一轮请求里的上下文。

这是什么¶

dsh-failbook 是一个 DeepSeek Harness（DSH）插件，用于记录工具调用失败、按失败签名聚类，并在重复失败时进行失败感知重试拦截。插件包含 Web UI 设置面板，MIT 许可，零配置开箱即用。

仓库地址在 G1en-114/dsh-failbook。

核心功能¶

下面是它已确认提供的主要能力：

1. 自动记录工具调用失败
   包括结构化错误、非零退出码、沙箱拒绝、常见错误文本。

2. 失败签名聚类
   同一失败原因会被归到同一个桶，不会只因参数不同而散落成多个条目。

3. 跨会话持久化
   通过官方 ctx.storageDomain 存储，可跨会话持久化；没有该服务时自动降级为内存账本。

4. 失败感知重试拦截
   同一签名在近窗口内失败达到阈值时，注入建议性提醒。

5. Web UI 面板
   设置页提供失败账本面板，可查看 Top 失败签名、次数、近窗口、最近时间，并支持静音、单删和清空。

6. 静音与排除
   误报桶可以一键静音，也可以通过 excludeTools / patterns 做更细的控制。

7. 保守检测
   设计原则是宁可漏判，不要误判，只认确凿的失败标记。

安装与启用¶

安装命令：

dsh plugin --profile web add "github:G1en-114/dsh-failbook#main"

这条命令会把插件加入 web profile 的 DSH 配置。

如果不使用安装命令，也可以手动编辑配置目录中的 cordis.patch.yml，插入以下内容：

- insert:
    - id: failbook
      name: dsh-failbook
      config:
        enabled: true

重启 dsh web 后，打开：

设置 → 失败账本

可以看到失败账本面板。

典型配置¶

插件默认启用。已确认的默认配置包括：

enabled: true
retryGuardThreshold: 2
reminderCooldownSec: 300
reminderLocale: "zh"
exitFailureMin: 2
excludeTools:
  - todo_write
maxBuckets: 1000

其中几个关键项：

• enabled：总开关。
• retryGuardThreshold：近窗口内同一签名失败达到该次数后触发提醒。
• reminderCooldownSec：同一桶两次提醒之间的最小冷却时间。
• reminderLocale：提醒文案语言，示例中可用 "en"。
• exitFailureMin：退出码达到该值时才记为失败。
• excludeTools：不追踪的工具列表。
• maxBuckets：账本桶数量上限，超出后按最近使用淘汰。

如果想让拦截更激进，可以改成：

- insert:
    - id: failbook
      name: dsh-failbook
      config:
        exitFailureMin: 1
        retryGuardThreshold: 1
        reminderLocale: "en"

这个示例把退出码 1 也纳入失败判断，并把触发提醒的阈值降到 1 次。

运行方式与边界¶

dsh-failbook 的提醒通过 additionalContexts 注入。它不修改工具结果，也不打断工具执行管线，只在模型下一轮请求时提供可见的上下文。

它还有几条比较明确的安全边界：

• Web API 仅回环地址可访问。
• 账本只保存截断后的预览。
• 完整命令输出不会离开宿主。
• 没有 ctx.storageDomain 服务时，会自动降级为进程内 / 内存账本。降级后记录与拦截功能不变，但重启会清空。

开发与验证¶

仓库提供了本地开发与验证命令：

npm install
npm test
npm run test:integration
npm run build

其中 npm test 用于运行测试，npm run test:integration 用于集成验证，npm run build 用于构建。

package.json 中可见依赖包括：

"@deepseek-ai/schemastery": "^3.18.1",
"zod": "^4.4.3"

资料中 peerDependencies 不完整，本文不据此补充完整依赖列表。

适用场景与注意¶

它适合这类使用场景：

• 使用 DSH Web 配置，希望看到失败记录面板。
• 希望把工具失败从临时日志变成可查询的账本。
• 希望减少模型在同类错误上反复重试。
• 需要对某些工具或错误模式做静音和排除。

使用前需要注意：

• 插件运行在 DSH 宿主侧，并以当前 dsh 进程权限运行。
• 安装前应检查源码、依赖和许可证。
• 许可证为 MIT。
• 如果你依赖跨会话持久化，需要确认当前环境是否提供 ctx.storageDomain；没有该服务时会退化为内存账本。

结尾¶

dsh-failbook 的价值在于把“工具失败”变成可追踪、可聚合、可提醒的账本记录。它不改变 DSH 的执行模型，而是在失败发生之后提供一层结构化的反馈。

相关链接：

• GitHub 仓库：https://github.com/G1en-114/dsh-failbook
• 目录页线索：https://www.skillhub.cn/plugins/G1en-114/dsh-failbook（该 URL 来自线索，未在已抓取资料中核实）