dsh-milestone-guard

dsh-milestone-guard

阶段性结论软强制守卫插件（Milestone Progress Soft-Enforcement Guard for DeepSeek Harness）

dsh-milestone-guard 是一个面向 DeepSeek Harness (DSH) 的轻量级 Cordis 插件。它通过 「System Prompt 常驻规范注入 + tools/post-execute 瀑布流软强制纠偏提醒 + GUI 可视化热更新配置」 的机制，解决思考模型（Reasoning Models）在长链路 Agent 任务中常见的两大痛点：

1. 黑盒静默调用工具（Silent Tool Calling）：模型将所有推理过程隐藏在 <thought> 块内，随后直接跳到 <call:...> 发起数十次工具调用而不输出任何人类可见正文；当 GUI 默认折叠思考过程时，用户只能看到一排工具刷屏，无法获知上一步验证的结论或下一步意图。
2. 纯文本汇报导致回合误判中断（Premature Turn Termination）：当开发者在 Prompt 中要求模型“汇报阶段性进展”时，模型容易单独输出一条不带工具调用的纯文本消息，导致 Agent 主循环误判当前回合（Turn）已结束而提前停顿。

---

核心效果对比 (Before vs. After)

---

工作原理 (Architecture)

flowchart LR
    A["1. System Prompt 常驻注入<br/>ctx.systemPrompt.section"] --> B["LLM 生成回复<br/>(Thought + Text? + Tool Calls)"]
    B --> C["2. 工具执行后拦截<br/>ctx.on('tools/post-execute')"]
    C --> D{"最新 assistant/message<br/>是否包含非空可见 Text 块?"}
    D -- "是 (合规)" --> E["重置连续静默计数<br/>原样透传 downstream"]
    D -- "否 (漏发阶段性结论)" --> F{"WeakMap (agent, turn, step)<br/>同一步去重 & maxSilentSteps 检查"}
    F -- "同一步已提醒 / 未超容忍步数" --> E
    F -- "触发纠偏" --> G["前置注入 notice 提醒至<br/>downstream.additionalContexts"]

关键技术设计

• 零损耗软强制（Non-blocking Soft Enforcement）：不在 tools/pre-execute 阶段粗暴阻断（block）工具执行，而是让工具正常执行完毕后，在 tools/post-execute 阶段向 downstream.additionalContexts 前置附加一条 notice 提醒消息，兼顾执行效率与纠偏效果。
• 步级并发去重与防内存泄漏：当模型在同一个 (turn, step) 中并发调用多个工具（如同时调用 5 次 read）时，基于 WeakMap<Agent, State> 按 (agent, turn, step) 去重，确保同一步只评估并注入一次提醒，且随 Agent 实例销毁自动回收内存。
• GUI 可视化配置与 .volatile() 热更新：内置客户端配置组件（lib/client.js），在 DeepSeek Harness「插件 → 已安装 → 阶段性结论守卫」页面直接提供可视化配置表单，修改后无需重启会话即可实时生效。
• 零外部强依赖与多版本兼容：
  • 自动兼容 session.events（数组属性）、session.snapshotEvents()（DSH 0.1.5+ / 0.2.0+ 方法）与 session.log；
  • 对 @deepseek-ai/dsh-llm 和 @deepseek-ai/schemastery 提供宿主动态解析与内置零依赖 Fallback（含 toJSON() 与 Standard Schema ~standard 协议），可在纯 Node.js 环境独立运行和测试。

---

安装与配置 (Installation & Configuration)

方式一：在 DeepSeek Harness GUI 中安装与可视化配置

1. 在 DeepSeek Harness「插件 (Plugins) → 添加插件」中填入本地路径或仓库地址进行安装。
2. 点击「插件 → 已安装 → 阶段性结论守卫 (dsh-milestone-guard)」，即可在详情面板中直接修改：
   • 最大连续静默步数 (maxSilentSteps)
   • System Prompt 排序权重 (sectionOrder)
   • 自定义软强制提醒文案 (reminderText)

方式二：在 cordis.patch.yml 中配置

- id: milestone-guard
  name: dsh-milestone-guard
  config:
    enabled: true
    locale: zh
    sectionOrder: 180
    maxSilentSteps: 0
    ignoreTools: []

---

配置项说明 (Configuration Options)

---

开发与测试 (Development & Testing)

本项目使用 Node.js 原生测试运行器（node:test），无需安装额外测试框架即可验证全部核心行为：

npm test

License

MIT