前言¶

在 DSH 里跑长链路 Agent 时，常见的问题不是「模型不够聪明」，而是行为失控：同一句话反复输出、同一工具带着相同参数来回点、工具结果在几个固定值之间振荡，或者模型口头说「完成」却没有任何可核对的工具证据。单靠提示词很难稳定拦住这些情况，需要在 Harness 层做监听与干预。

下面介绍社区插件 dsh-shepherd（维护者 Boris-boomer）。它在 DSH 侧组合循环守护与模式守卫，对思考流和工具调用流做实时检测，并按严重程度选择警告、阻断单次工具调用或终止本轮生成。SkillHub 将其归类为工作流插件；仓库当前版本为 0.5.0，许可证 MIT，GitHub 星标为 0（以目录页与仓库公开信息为准）。

这是什么¶

dsh-shepherd 的定位是 Agent 行为守卫：专为 DeepSeek Harness 设计，用来减少死循环、空转和「无证据完成」。目录页英文简介为「Orchestration and management plugin for DSH agent workflows」；package.json 中的描述进一步概括为：7 个循环/空转/假完成检测器，以及 planning / coding / verify 模式守卫与原生审批熔断。

插件依赖 DSH 生态中的 Cordis 与 Typert 协议（peerDependencies 要求 @deepseek-ai/cordis 4.x、@deepseek-ai/dsh-typert-protocol 0.2.x），并在 Web 客户端注入悬浮审计控制台（dsh.client 配置）。

七大循环检测器¶

插件监听 Agent 的流式文本与工具执行事件。README 列出的七类检测器如下，名称与触发条件以仓库文档为准：

1. 文本重复（A）：输出大量完全相同文本块或字符周期。
2. 工具重复（B）：反复调用同一工具，且分页或重试参数构成周期时被忽略。
3. 无进展（C）：连续多次工具结果无变化，或在少数固定值之间振荡。
4. 工具超时（D）：单次工具调用超过预设阈值仍未返回。
5. 无落地（E）：多轮生成既无可见文本也无工具调用，纯思考空转。
6. 硬上限（F）：单轮步数或总耗时达到配置的安全上限。
7. 无证据完成（G）：宣称完成或已修复，但本回合内缺少成功工具调用作为证据，或写操作后未验证。

为减少误杀，实现上会剥离时间戳、UUID、耗时等易变字段后再计算状态指纹，以便区分合法轮询与真实死锁。

三级模式守卫¶

除循环检测外，插件支持在悬浮窗中切换工作模式，约束高风险工具：

README 举例：编码模式下可将 execute_command、pytest 列入黑名单，由用户审批后再执行。

干预方式与工作流程¶

检测命中后，仲裁层结合置信度与历史触发次数决定干预级别，而不是一律中断：

• 警告：注入系统提示，不打断生成。
• 阻断：在工具执行前拒绝，仅拦截单次调用。
• 终止：取消本轮生成并注入强指令。

文档中的处理链路可概括为：状态采集 → 对工具结果做指纹剥离与哈希 → 仲裁决策 → 分发上述三种干预。

同一 Agent 被强行打断的次数可通过 maxInterruptsPerAgent 封顶，避免「打断套娃」。

配置示例¶

阈值与模式均在 DSH 插件配置中调整。README 给出的典型结构如下：

{
  "loop": {
    "enabled": true,
    "maxInterruptsPerAgent": 3,
    "noEvidence": { "keywords": ["完成", "done"] }
  },
  "mode": {
    "enabled": true,
    "mode": "planning",
    "blacklist": ["execute_command", "pytest"]
  }
}

说明（均来自 README 参数说明）：

• loop.enabled / mode.enabled：分别开关循环守护与模式守卫。
• maxInterruptsPerAgent：同一 Agent 允许的最大强制打断次数。
• noEvidence.keywords：配合「无证据完成」检测器使用的完成类关键词。
• noProgress.window：连续多少次无进展结果触发报警（字段名在说明中出现，具体默认值以插件 schema 或源码为准）。
• mode.mode：当前模式，示例为 planning。
• mode.blacklist：编码模式下需人工审批的工具名列表。

启用后，Web 端悬浮窗支持拖拽、改参，并查看最近的工具拦截记录。

安装与启用¶

DeepSeek Harness 采用「一切皆插件」的扩展方式；社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系，安装前请自行阅读仓库源码与 MIT 许可证。

目录页提供「发送给 DeepSeek Harness 安装」的说明，插件标识为 Boris-boomer/dsh-shepherd。按页面指引让 Harness 安装该插件即可；具体 CLI 或配置入口以你使用的 DSH 版本文档为准，此处不拼接未在官方资料中出现的安装命令。

安装后若需改前端资源，维护者在仓库中使用 pnpm build 构建；这与终端用户使用插件无直接关系。

典型用法¶

1. 在插件配置中开启 loop.enabled 与 mode.enabled，按任务阶段将 mode.mode 设为 planning、coding 或 verify。
2. 长任务或易反复读文件的 Agent：保持循环检测开启，必要时调低无进展窗口或超时阈值（在配置 schema 允许范围内）。
3. 编码阶段：在 mode.blacklist 中登记终端、测试等工具，利用审批或熔断避免未审查的执行。
4. 验证阶段：切换到 verify，放行测试与命令类工具，同时仍保留「无证据完成」等检测，避免未跑测试就宣告结束。

noEvidence.keywords 可按团队用语补充中英文完成表述，与检测器 G 配合使用。

适用场景与注意¶

适合：多步工具链、自动修 bug、批量读写的 Agent 工作流；需要在 Harness 层统一治理循环与阶段权限的团队。

注意：

• 插件以当前 DSH 进程的权限运行，模式守卫与黑名单只能约束 Agent 可见的工具面，不能替代操作系统级隔离。
• 干预会改变模型轨迹；maxInterruptsPerAgent 等上限是为平衡安全与可用性，过严可能打断合法的长轮询。
• peer 依赖版本需与本地 DSH / Cordis 匹配，升级 Harness 后应核对插件是否仍兼容。

维护者本地开发可运行 pnpm test（Node 原生测试，无第三方测试框架）验证守卫逻辑；普通用户以发布包为准即可。

结尾¶

dsh-shepherd 把循环、空转、假完成等异常收拢到一套可配置的检测与分级干预里，并用 planning / coding / verify 三态限制高风险工具，适合作为 DSH 工作流里的行为护栏。

• 目录页：https://www.skillhub.cn/plugins/Boris-boomer/dsh-shepherd
• 源码与文档：https://github.com/Boris-boomer/dsh-shepherd