前言¶
在 DeepSeek Harness（DSH）里跑智能体时，工具一旦反复失败，模型往往不会回到系统提示里读「失败两次就停」这类规则——它主要在读自己的推理链。表现上常见同一命令换参数再试、推理里出现大量短句重复，而会话仍在空转。单靠 prompt 很难从内部打断这种「连续失败循环」。
dsh-fail-guard 是社区维护的工作流类插件：从外部监听工具结果，当同一工具连续失败达到阈值时，向对话注入一段结构化的停手说明，让智能体转向汇报而不是继续第四种拼写方式。下面介绍它的定位、安装与配置，以及使用时需要接受的边界。
这是什么¶
- 名称：dsh-fail-guard（仓库 FenrirCait/dsh-fail-guard）
- 维护者：FenrirCait
- 分类：工作流（社区目录 SkillHub 条目）
- 一句话：在智能体对同一工具连续失败 N 次后停止继续重试，改为推送四段式停手指令（尝试过什么 / 完整错误 / 初步原因猜测 / 需要你做什么）。
插件通过 dsh.bundle 挂载 cordis.patch.yml，在 Cordis 侧拦截工具结果并计数，不依赖你在 profile 里手写 patch。
核心功能¶
外部打断，而非 prompt 规则¶
README 说明：连续失败时模型往往读的是自己的 thinking，而不是当时的系统提示，因此「失败两次就停」写进 prompt 在该状态下通常无效；中断必须由插件从会话外部注入。
连续失败计数与重置¶
- 计数按会话、默认按工具分别统计（可通过配置改为全工具共用一个计数器）。
- 任意一次该工具（或全局，取决于配置）成功会清零计数。
- 触发停手后，计数会重新开始；再次连续失败到阈值会再次触发——它不是速率限制器，而是可重复触发的 guard。
什么算一次「失败」¶
满足任一条件即计入：
message.isError === truemeta.opsShell.exitCode存在且非零
两者都要考虑：shell 退出码为 1 时未必带 isError；部分工具级错误也没有 exit code。
停手时注入的内容¶
达到阈值后，插件向对话推送内置或可配置的 stopText（四段式说明）和面板上的 stopSummary（一行摘要），目的是让智能体汇报而不是再试同一种思路。
明确不做什么（Limits）¶
- 不会撤销「刚刚已经失败」的那次工具调用。
- 不判断失败是否「合理」——非零退出码即算。
- 不会重置整段对话；停手指令相当于又多一条用户侧消息。
- 触发后若继续失败，会重新计数并可能再次触发。
当前 package 版本为 0.2.0（以仓库 package.json 为准），许可证 MIT。
安装与启用¶
在 DSH 桌面 profile 下执行官方安装命令：
dsh plugin --profile desktop add dsh-fail-guard
安装后重启一次 DSH。cordis.patch.yml 经 dsh.bundle 清单应用，一般无需手动改 profile 里的 patch 列表。
插件以当前 DSH 进程权限运行；安装前建议浏览仓库源码并确认 MIT 许可证与行为是否符合你的环境策略。社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系。
配置¶
在客户端 Plugins → dsh-fail-guard → details 中编辑。字段标记为 .volatile()：保存后立即生效，无需重启。
| Key | 默认值 | 含义 |
|---|---|---|
threshold |
2 |
连续失败多少次后停手 |
sameToolOnly |
true |
按工具分别计数；设为 false 则所有工具共用一个计数器 |
stopText |
内置 | 注入对话的停手正文 |
stopSummary |
内置 | 面板一行摘要 |
debug |
false |
是否把事件、计数、触发写入日志 |
logFile |
<plugin dir>/fail-guard.log |
debug 写入路径 |
也可直接在 cordis.patch.yml 中写插件 config，例如：
- id: dsh-fail-guard
config:
threshold: 3
典型用法：保持默认 threshold: 2、sameToolOnly: true，在智能体容易对 Shell 或某固定工具死磕的任务里启用；若希望「任意工具加起来连续失败 N 次就停」，将 sameToolOnly 设为 false 并按需调高 threshold。排查计数行为时可临时打开 debug 并查看 logFile。
适用场景与注意¶
适合：长会话、多步工具链、容易出现同一命令反复改参数仍失败的工作流；希望失败循环由外部 guard 切断、让模型输出结构化错误汇报的场景。
注意：
- 误报：任何非零 exit 都算失败，包括你可能认为「可接受」的退出码。
- 不会阻止失败当次调用已完成的事实；停手发生在下一次模型决策之前（通过注入消息影响后续轮次）。
- peer 依赖包括
@deepseek-ai/cordis、@deepseek-ai/dsh-agent、@deepseek-ai/dsh-llm等，需与当前 DSH 版本兼容（见仓库package.json）。
README 中引用的观测数据（例如某 74 轮会话里短句片段占比随连续失败上升）来自插件作者自测描述，用于解释现象，并非对你环境的保证。
结尾¶
dsh-fail-guard 把「同一工具连续失败」从 prompt 规则里拆出来，用 Cordis 插件在外部计数并在阈值处注入四段式停手指令，减少智能体在错误参数上无限重试。安装命令以 README 为准，配置可在 UI 即时生效。
