前言¶

在 DSH 场景中，一次失败往往不是单独一行错误。它可能发生在工具调用、回合结束或 Agent 运行时错误，并且需要结合失败前发生了什么、项目当时状态、运行环境和插件组合来判断。普通错误日志往往只有“最后哪里炸了”。

dsh-failure-capsule 是 YiHarvest 维护的 DeepSeek Harness 插件，MIT 许可。它在工具或 Agent 失败时生成脱敏 ZIP 证据包。已针对 @deepseek-ai/dsh@0.1.0-rc.7 的原生 session/event 与 agent/error 接口验证。

这是什么¶

dsh-failure-capsule 是本地优先的故障证据包插件。它在失败发生后，把相关信号整理成一个 ZIP，并写入本机目录。

它不修改 Harness 核心，不上传数据，也不调用模型诊断故障。

核心功能¶

下面介绍它的默认行为和能力：

• 在 tool/result 且 isError=true、turn/end / error、turn/end / blocked、turn/end / interrupted、agent/error 时生成故障证据包 ZIP。turn/end / aborted 默认不触发，可配置开启。
• 本地优先：ZIP 只写本机，没有网络请求和遥测后端。
• 默认脱敏敏感字段、凭据、token、AWS access key、环境变量赋值、URL 用户密码、私钥块和本机路径。
• 采集 Git 证据、运行时信息、Loader 插件清单和有界 Session Event timeline。
• 可用本地 source map 反解压缩后的 JS 栈帧。
• 支持通过 cordis.patch.yml 覆盖配置。

采集和触发也有边界：

• Timeline 默认最多 80 条事件。
• 每条 Git 命令默认最多 512 KiB，达到预算会终止命令并明确标注截断。
• Git 通过参数数组直接执行，不经过 shell，不读取未跟踪文件内容，也不运行 hook 或 textconv。
• 相同 Session Event 在一个插件生命周期内只生成一次；agent/error 会短暂等待对应的 turn/end，避免同一失败重复打包。
• 错误配置在插件加载时直接失败，不静默回退。
• 插件卸载时会等待已启动的证据包写入结束。

安装与启用¶

需要 Node ^22.19.0 || >=24.0.0。

Web 与 headless 是两个独立 profile，需要分别安装：

dsh plugin --profile web add dsh-failure-capsule
dsh plugin --profile headless add dsh-failure-capsule

安装后先检查组合层配置：

dsh --profile web --dump-config

输出中应出现：

id: failure-capsule
name: dsh-failure-capsule

如果使用本地 tarball 验证：

dsh plugin --profile web add ./dsh-failure-capsule-0.2.1.tgz
dsh --profile web --dump-config

典型用法¶

先安装插件，再正常使用 DSH。失败发生后，插件默认把证据包写入：

.dsh/failure-capsules/

可以按下面步骤查看：

1、确认失败类型，是 tool/result 工具失败、turn/end 回合失败，还是 agent/error。
2、打开对应 ZIP，查看失败前后的 Session Event timeline、Git 证据、运行时信息和 Loader 插件清单。
3、如果失败携带压缩后的 JS 栈，查看本地 source map 反解后的栈帧。
4、分享前人工检查 ZIP 内容，尤其是自由文本、源代码 diff 和自定义插件事件。

如果需要在某个 profile 中调整配置，可以在该 profile 的 cordis.patch.yml 中用 row id failure-capsule 覆盖整段配置。

适用场景与注意¶

这个插件适合需要离线排查 DSH 工具失败、回合失败或 Agent 运行时错误的场景。它把证据留在本机，不上传数据，也不调用模型诊断故障。

使用前注意：

• 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。
• 自动脱敏不能证明 ZIP 中绝对没有业务秘密，分享前仍应人工检查。
• 需要 Node ^22.19.0 || >=24.0.0。
• 已针对 @deepseek-ai/dsh@0.1.0-rc.7 的原生 session/event 与 agent/error 接口验证；兼容性和安全性仍应以可复现测试与源码审查为准。
• 在 Awesome DSH Plugins Radar 等目录中被收录只代表可发现，不等同于兼容或安全背书。

结尾¶

dsh-failure-capsule 把失败前的事件、项目状态、运行时信息和插件组合放进一个本地脱敏 ZIP，适合在 DSH profile 中做离线故障复盘。

仓库地址：https://github.com/YiHarvest/dsh-failure-capsule