前言¶
在 DeepSeek Harness（DSH）里跑智能体时，模型有时会反复提交同一套无效工具调用：缺参数、编辑校验失败、工具名空或不存在、MCP 会话过期等。Harness 会按轮次把错误回给模型，但对话仍可能继续，同一错误再试多轮，浪费请求又难以及时介入。
社区插件 dsh-retry-guard（维护者 sjh9714，分类：工作流）针对的是：连续三次、工具名、参数与失败内容完全一致 的工具错误。默认只观测并在回合结束时提示；可选 Pause 在第三次失败后阻止下一轮模型步启动，便于你在 Trajectory 里查原始失败、修原因后再在 Chat 发新指令。下面介绍定位、能力与安装配置。
这是什么¶
dsh-retry-guard 是面向 DSH Web 的非官方社区插件（MIT 许可，DeepSeek 未背书）。一句话：观测相同的工具失败，并可选地在 Harness 的下一步模型步之前暂停。
- 包名：
dsh-retry-guard（npm 发布，alpha标签对应当前预发布；资料中版本示例为0.1.0-alpha.2） - 支持目标：DSH Web 0.2.0-rc.2、Node.js 24
- 无需单独账号、API Key 或联网运行插件逻辑；安装依赖时需要能访问 npm registry
DSH 生态强调「一切皆插件」；SkillHub 目录页 与 GitHub 仓库为社区维护，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
触发条件（同一 agent、同一 turn 内）¶
三次连续失败须同时满足（README「Behavior」节）：
- 相同工具名
- 参数为递归 key 排序后的 JSON，内容一致
- 失败内容完全一致
- 「失败」指 DSH 将工具结果标为
isError: true（普通 Bash 退出码 1 等不在此列的边界见仓库文档）
中间若有成功调用，计数会重置（例如 MCP 会话错误在资料中的 bounded 实验里即如此）。
两种模式¶
| 模式 | 第三次连续相同工具错误之后 |
|---|---|
| Observe（默认） | 工作继续；本回合结束时出现 Retry Guard 通知 |
| Pause（需手动开启并保存） | 不启动下一步模型步；通知含失败工具、次数、时间及原始 event/call 引用 |
插件只识别重复错误并提示或暂停，不会自动分析或修复原因；修复后需在 Chat 发送新指令，失败调用不会自动重放。
维护者 bounded 实验（非生产会话统计）¶
维护者在 DSH 0.2.0-rc.2（2026-10-02） 上对照七则公开讨论中的失败模式做了 bounded 实验（scripted model、真实校验器/agent loop，无 API Key）。README 表格摘要：缺 run_code 描述、无效 Edit、空工具名、连续 MCP 会话错误等场景下，Pause 往往把同类重复调用从约 6 次压到 3 次；Observe 仍保留 6 次调用并附加通知。每次改参数的失败、纯文本循环、Bash 权限类旧报告在当前版本未复现或未纳入检测等限制，见 reported-cases.md。
安装与启用¶
前提：本机已有 DSH Web 0.2.0-rc.2，运行在 Node.js 24。发布包内含构建好的 JavaScript，无需 git clone 或本地编译。
在 DSH Web 界面安装¶
- 打开 Plugins → Add plugin，在 Package name or address 填入下面包名，点 Install。
- 安装完成后点 Enable now（仅安装文件不会启用插件）。
- 在 Plugins 中打开 dsh-retry-guard bundle，进入其 dsh-retry-guard 组件（Configure）。
- 默认保持 Observe；若要阻断重复失败，选 Pause 并 Save settings。
- 正常对话即可，无需单独命令唤起 Retry Guard。
包名（资料原文）：
dsh-retry-guard@alpha
若要固定版本，资料给出示例：
dsh-retry-guard@0.1.0-alpha.2
终端安装¶
CLI 安装后需重启 DSH Web，再按上文打开 Configure 设置模式：
dsh plugin --profile web add dsh-retry-guard@alpha
说明：须通过 DSH 插件管理器安装并激活 bundle；在无关项目里 npm install 不会在 DSH 中生效。DSH 0.2.0-rc.2 不会自动更新已装插件；换版本需卸载旧 bundle 再装目标版本并确认保存的模式。
本地 tgz 备选¶
早期 v0.1.0-alpha.1 归档仍可用。下载 .tgz 与 SHA256SUMS 后，在下载目录执行：
dsh plugin --profile web add ./dsh-retry-guard-0.1.0-alpha.1.tgz
典型用法与修复流程¶
安装并启用后无需额外 API。当某工具连续三次返回相同错误（例如同一缺参校验失败）：
- Observe：留意回合结束时的 Retry Guard 通知，对话仍会继续。
- Pause：第三步失败后下一步模型步不会启动；在通知中记下工具名与 record 引用。
- 在 Trajectory 中查看原始失败（仓库 demo.md 有 walkthrough；通知暂无一键跳转）。
- 修正根因（参数、编辑内容、MCP 会话、工具可用性等）后，在 Chat 发送新的用户指令继续。
维护者提供的 deterministic fixture 中：Observe 为 6 次工具调用 / 7 次模型请求；Pause 为 3 / 3，修复指令后再有一次成功调用——仅为 fixture 计数，不能泛化为通用省 token 承诺。演示 GIF 与 20 秒录屏 使用故意失败的本地工具与 scripted model，无 API Key。
适用场景与注意¶
更适合
- 你在 DSH Web 0.2.0-rc.2 上开发或调试智能体，且常遇到完全相同的工具错误被连续重试。
- 希望先只观测重复失败（默认），确认模式后再开 Pause 硬性停步。
不适合或需另寻方案
- 每次失败参数或文案在变、成功搜索重复执行、普通 Bash 非零退出、仅 assistant 文本循环、工具 markup 出现在普通文本里而未产生 native 工具结果等（见 reported-cases.md 共 12 类场景说明）。
安全与信任
- 插件在当前 DSH 进程权限下运行；安装前建议阅读 GitHub 源码 与 MIT 许可证，自行判断是否纳入工作流。
- 社区插件，独立维护；安装依赖需 registry 访问，运行 guard 本身不强制外网。
结尾¶
dsh-retry-guard 把「连续三次相同工具错误」从默默重试变成可观测、可选暂停的检查点，适合在 DSH 智能体工作流里控制无效工具循环。目录与文档：
