dsh-goal-guard

后台子代理还在跑时，别让 goal 自动续跑被烧掉。

DeepSeek Harness（DSH / Cordis）插件。在「派发后台 continuable 子代理 → 结束回合 → 等结算通知」 这种委托纪律下，goal-round-driver 会在母会话每次回到 idle 时注入一轮 <goal_round>—— 它不知道还有未结算的子代理。本插件在等待窗口内进程内解除 goal 的自动续跑 （goals.disarm，不产生耐久事件、不改 phase/revision），全部子代理结算后自动恢复 （goals.resume）。

为什么需要它（这是核心缺口，不是某个插件的私有 workaround）

@deepseek-ai/dsh-goal-round-driver 的 readyToDrive 只检查

return ctx.fiber.state === 2 && !state.stopping
  && ctx.agents.get(state.agent.id) === state.agent
  && state.agent.status === "idle"
  && !state.competingQueued

——没有子代理维度：该包不注入 subagents，Config 也只有 defaultMaxGoalRounds， 没有任何原生开关。而模型工具层的 update_goal(pause/resume) 要求「直接人类回合」， 模型自救不了。

远端实测（web profile，子代理运行期间）复现：

+ 66ms  agent/created   origin=subagent depth=1        ← 子代理诞生
+ 72ms  agent/status    running (子代理)
+209ms  <goal_round> round=1 注入                      ← ★ 子代理仍在跑，driver 照注入
+859ms  agent/error     QUOTA (子代理)
+943ms  user/message    sourceKind=subagent-settled     ← 结算通知

装上本插件后同一场景：窗口内零注入，且结算后 goal 自动回到 armed（见下方验收记录）。

行为

时机	动作
子代理诞生（agent/created 带 origin='subagent' + parentSession）	母会话 goal 若 active + armed → 抢先 disarm（母会话仍在 running，零竞态；覆盖 subagent / subagent_fork / workflow 等所有派发路径）
goal 被 arm 但已有子代理在跑（goal/changed 采纳）	立即 disarm（堵住「先派子代理、后 arm goal」的窗口）
idle / 结算通知（agent/status idle、subagent-settled、turn/end）	有 running 子代理 → 保持 disarm；无 running 子代理 → 自动 resume
agent/error、回合 max-tokens / aborted	毒化：不再自动 resume（不覆盖 harness 的熔断决定，交人类）
agent/disposed、agent/session-start	整段窗口状态作废（新 epoch 不继承）

安全不变量

goals.resume 在服务层没有人类门（人类门在 dsh-tool-goal），所以本插件只重新武装 自己刚 disarm 过的、id + revision 完全一致、且仍为 active + disarmed 的 goal。 goal 被清 / 被编辑 / complete / blocked / paused / 被第三方重新武装 → 一律清 mark 交人类， 绝不猜。「还有子代理在跑」用 subagents.listDescendants(...) 的 activity === 'running' 判定；查询失败按「未知」处理，未知不构成 disarm 或 resume 的理由。

安装

# 方式一：DSH 插件管理器（写入 profile 依赖 + bundle 装配）
dsh plugin --profile web add /path/to/dsh-goal-guard

# 方式二：dsh-super-injector（运行时注入，免重启）
dev_inject_plugin /path/to/dsh-goal-guard

# 方式三：作为 profile patch overlay 挂载
dsh web --patch ./cordis.patch.yml

cordis.patch.yml 把本插件插到 profile 根 roster。挂载位置很重要：dsh-scope 的准入规则是

const tag = scopeOf(ctx);
if (tag === void 0) return true;          // 未打标的监听器 → 全局准入

只有未打标的监听器才能收到根会话的 agent/status；被打标的 ctx 只收其作用域链后代的事件。

配置

# profile patch / 插件 config
- id: dsh-goal-guard
  config:
    enabled: true              # 总开关；关闭即退回原生行为
    statusRoute: true          # 注册 /dsh-goal-guard/api/status
    tool: true                 # 注册 goal_guard 工具
    watchdogIntervalMs: 30000  # 看门狗周期；0 = 关闭
    maxWindowMs: 1800000       # 窗口超时告警阈值

观测

• GET /dsh-goal-guard/api/status → { ok, loggerPresent, guarded, tracked, states, diag }
• 工具 goal_guard：action=status 看守卫状态；action=resume 立即重新评估并尝试恢复 （模型自查「为什么 goal 没继续」用）
• 告警走 ctx.logger.warn 并额外落 console.warn：某些宿主不把插件 logger 输出落到 可见位置，而「resume 失败 / 窗口卡住」是本功能唯一的人工可见面，不能丢

兼容性

项	值
dsh.engines.dsh	>=0.1.7-rc.1 <0.2
peer	@deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/schemastery
必需服务	无（goals / agents / subagents / tools / webServer 全部可选且惰性解析）

验收记录（2026-10-15，远端测试环境）

被测形态 = 真实部署形态：插件放进 profiles/node_modules/，按包名由 profile 根 roster 挂载； 验收夹具另挂一个探针插件造激励（自建 root agent → 派 continuable 子代理 → arm goal）， 不依赖 LLM 成功（远端凭证余额不足，回合以 QUOTA 失败，但生命周期事件齐全）。

场景	窗口内 <goal_round> 注入	disarm 时点	结算后 resume	判定
基线（无插件，探针实测）	1	—	—	病根复现
adopt（先派子代理 → 再 arm goal）	0	arm 后 +15ms	✅ armed	PASS
proactive（先 arm goal → 立刻派子代理）	0	子代理 agent/created 时（早于 spawn 时间戳）	✅ armed	PASS

对照数字：driver 从 goal/changed 到排队轮次约 178ms（内部有 await sessions.flush() 检查点）， 守卫 disarm 在 15ms 内完成 → 赢约 160ms。/api/status 实测 HTTP 200， diag spawned:1 / windowDisarms:1 / resumes:1 / resumeFails:0 / watchdogTicks:2。

复现（夹具在 test/remote/）：

# 远端：<DSH_HOME> 指向测试 home，dsh 用部署树里的 bin
scp -r lib package.json <remote>:<profile>/node_modules/dsh-goal-guard/
scp test/remote/goal-guard-accept.mjs test/remote/patch.yml <remote>:/root/test-env/
ssh <remote> 'cd /root/test-env && GG_ACCEPT_MODE=adopt dsh web --patch /root/test-env/patch.yml --port 3099 --no-open'
# 报告：/root/test-env/accept-out/report.json（看 verdict.pass）

开发

bash scripts/build.sh        # src/ → lib/（从部署树链类型依赖，用全局 tsc）
npx tsc -p tsconfig.json --noEmit
npm test                     # node --test（先 build 再 test，测的是 lib/ 产物）

本仓库不 npm install：scripts/build.sh 从 ~/.dsh/profiles/node_modules 或 /usr/lib/node_modules/@deepseek-ai/dsh/node_modules 探测一份 DSH 依赖树，把 @deepseek-ai/* 软链进本地 node_modules 后用系统 tsc 编译。lib/ 是产物但入库 （files 含 lib），这样 dsh plugin add / git 直装不需要构建步骤。

两个踩过的坑（都来自真实部署，别重犯）

1. 不要 import 'schemastery'。部署树里没有顶层 schemastery 包，只有 @deepseek-ai/schemastery（官方包与已发布第三方插件一律 import 这个 scoped 名）。 用顶层名会「本地构建通过、真机 failed to import」——本插件第一版就是这样在远端被拒的。 同理：不要靠 build 时生成的 node_modules/<name> 软链在运行期解析裸名。
2. 服务句柄必须惰性取。实测 headless profile 在 apply() 时 goals/agents/subagents/tools 全部尚未就绪（到 agent/created 才齐）； 装配期抓死句柄会直接坏掉。本插件的 inject 因此留空。

License

BSD-3-Clause