前言¶
在 DeepSeek Harness（DSH）里跑长任务时，agent loop 本身不会对两类异常做调控：模型可能「想完就停」——推理写满后正常结束 turn，却没有正文和工具调用；也可能进入推理死循环——重复空转，单次 step 可堆积极大量推理块与字符，持续数分钟。配合 DeepSeek V4 Flash 且 reasoningEffort: max 时，这两种情况更常见。社区插件 dsh-run-guard 在流式调用与 turn 生命周期两端补齐：guard（刹车） 拦截死循环，continue（油门） 在合理条件下自动续跑，并与上游错误恢复共用每 turn 重试预算。下面介绍它的定位、能力与安装配置方式。
这是什么¶
dsh-run-guard 是 DSH 生态下的插件包，维护者在社区目录中以 PrismLean 呈现；源码与说明见 GitHub 仓库（README 中的发布安装指向 Dis2017/dsh-run-guard 标签）。插件要求宿主 dsh 0.2.0-rc.2 及以上（peerDependencies 在安装与启动时校验，版本不匹配会被拒绝加载或需 exact-version 豁免）。许可证为 MIT。
一句话定位：Agent 运行节奏守护——一体两面，避免长任务中「停不下来」与「不干活」。
核心功能¶
资料中列出的能力如下，刹车与油门共用状态感知，设计上互不误触：guard 以 error 结束 turn 时，continue 不会在 completed 路径上误推；continue 拉起的 turn 若再次死循环，guard 仍会拦截。
| 能力 | 方向 | 说明 |
|---|---|---|
| guard | 拦截推理死循环 | 监听 llm/stream，滑动窗口重复率 + 硬性上限；死循环约在 1～2 秒内中断（非空转数分钟），中断后默认每 turn 2 次自动重试（可配），仍失败则停止并给出中文原因 |
| recovery | 上游失败重试 | PI_AI_ERROR 等瞬时错误（可扩展白名单）自动重试，与 guard 共用每 turn 上限 |
| continue | 防止提前停摆 | turn 正常结束后自动续跑：有未完成 todo 时注入状态；无 todo 但「想完就停」时注入简洁提示续跑 |
| pause_work | 人工暂停 | 模型可调用 pause_work 主动暂停，两路自动逻辑均不再继续 |
挂接的扩展点包括：llm/stream（guard）、agent/request-error（recovery）、session/event 与 systemPrompt.context（continue）、tools.register（pause_work）、plugins.row.config（Web 配置卡片，key 为 dsh-run-guard#run-guard）。
安装与启用¶
官方 README 推荐的 GitHub 发布版安装命令如下（勿自行拼接 owner/repo）：
dsh plugin --profile web add "github:Dis2017/dsh-run-guard#v0.2.1"
dsh plugin add 检测到包内 dsh.bundle 后会自动挂载到 profile 的 bundles 列表。
验证步骤：
- 重启 GUI（或等待 dsh-hmr 完成配置重载）。
- 打开 设置 → 插件，确认
dsh-run-guard为 Mounted / Enabled。 - 展开 bundle 的 run-guard 行，在配置页编辑总开关、Guard、Continue 等项；保存后 dsh 写回 profile patch 并重载插件，无需重启进程。
从 dsh 0.2.0-rc.2 起，配置入口在 Plugins 页面由插件注册的 client 组件提供，不再依赖宿主按 schema 自动生成设置页；仅标记 .volatile() 的字段支持在线编辑。
本地开发可用绝对路径挂载（改 ~/.dsh/profiles/web/cordis.patch.yml，将 name 指向 lib/index.js），资料中有完整 YAML 示例。
配置项¶
在 Plugins 页面编辑，由 Cordis Loader 按插件导出的 Config schema 解析 profile patch。全部字段与默认值如下：
| 配置项 | 默认 | 说明 |
|---|---|---|
enabled |
true |
总开关 |
guard.enabled |
true |
死循环拦截 |
guard.windowChars |
2000 |
滑动窗口大小（字符） |
guard.substrLen |
32 |
重复检测子串长度 |
guard.repeatRatio |
0.7 |
窗口重复率阈值（≥ 触发） |
guard.checkEvery |
50 |
每 N 块检测一次 |
guard.maxBlocks |
10000 |
单次调用推理块数硬上限 |
guard.maxChars |
500000 |
单次调用推理字符数硬上限 |
guard.maxGuardRetries |
2 |
每 turn 中断后自动重试上限（0 禁用） |
guard.autoRetryErrors |
["PI_AI_ERROR"] |
额外自动重试错误码白名单 |
continue.enabled |
true |
自动继续 |
continue.maxAutoFollowups |
3 |
有 todo 时连续无产出续跑上限 |
正常使用无需额外 API：死循环会被快速中断并重试（界面可见事件）；「想完就停」后会收到续跑提示。需要停顿时让模型调用 pause_work 即可。
适用场景与注意¶
适合谁：在 DSH Web profile 上跑长链路 agent、使用高 reasoning 配置，且遇到过死循环或 turn 提前结束留下未完成任务的用户。
权限与安全：插件与当前 dsh 进程同权运行，安装前应阅读源码与 MIT 许可证，确认发布来源。DSH 社区目录（如 SkillHub 条目）为独立站点，与 DeepSeek / 幻方无官方从属关系，并非官方应用商店。
版本与依赖：@deepseek-ai/* 须为 peerDependencies（宿主单例）；若 profile 顶层出现第二份 @deepseek-ai/dsh-tools，可能触发 Cannot read properties of undefined (reading 'prepare')，需按 README 清理重复安装。
存量会话：未装 guard 前产生的巨型死循环推理可能拖慢 GUI；guard 只保证之后不再产生。0.1.x 时代错误的 llm/retry 写法可能导致会话格式校验失败，升级插件后新中断不再损坏日志，已损坏会话需人工订正或归档（README 提供 zstd + grep 诊断命令）。
结尾¶
dsh-run-guard 在 DSH「一切皆插件」的思路下，用 guard、recovery、continue 与 pause_work 把长任务里的「停不下来」和「想完就停」收成可配置、可观测的行为。需要安装与细节时，可看社区目录页 PrismLean/dsh-run-guard 与 GitHub 仓库。
