dsh-turn-guard — turn 级单步超时插件（防模型退化死循环）

dsh 的 turn 级单步超时插件：对 agent 会话的每一步（step）施加超时控制——当某一步运行超过配置时限，强制中断（agent.cancel），防止模型退化导致的无意义死循环。

背景与动机

dsh 的 turn（一次对话）由 agent-loop 的 while(true) 驱动，没有总时长/最大步数上限（设计上支持长编码任务）。模型退化时（陷入循环、持续生成无意义内容），turn 无限运行，无兜底。

真实事故：webhook 处理退款短信时，模型（deepseek-v4-flash:0731）陷入调查循环 → 推理退化输出 "nope" 无限重复 → 无任何兜底，用户手动中断。

本插件目标：防止模型退化导致的无意义死循环——每一步（step）若超过配置时限即强制中断，正常处理不受影响。

设计原则

• 插件化：不改 dsh 本体，全部通过插件扩展（dsh 事件机制 + agent.cancel 公开方法）
• 无配置 = 不干预：某会话没配超时，等同 web 会话行为（模型自主跑，可手动停）
• 解耦：turn-guard 不感知会话类型（无前缀映射）；各入口插件负责把自己的超时配置挂到 agent，turn-guard 只读 agent 上的配置
• 可扩展：未来新会话类型/新守卫（步数上限、循环检测）零 turn-guard 改动

架构总览

┌─ 各入口插件（imessage / webhook / heartbeat / dreaming）─────────────┐
│  settings 段加 stepTimeoutSec（设置页可编辑，单位：秒）               │
│  创建/恢复 agent 后：                                                 │
│    agent.__pluginConfig.turnGuard = { stepSec: <自己的值> }           │
└──────────────────────────────────────────────────────────────────────┘
                           ↓（agent 挂配置）
┌─ dsh-turn-guard 插件（零映射）────────────────────────────────────────┐
│  ctx.on("session/event") 监听 step/start、step/end、turn/end          │
│  agents.get(session.id) → 读 agent.__pluginConfig?.turnGuard?.stepSec │
│    ├── 有值 → step/start 起定时器（stepSec × 1000 ms），               │
│    │        step/end 清；超时 agent.cancel({kind:'hook'})             │
│    └── 无值 → 不干预（等同 web）                                      │
└──────────────────────────────────────────────────────────────────────┘

配置项（单位：秒）

插件	settings 段	默认
imessage	imessage.stepTimeoutSec	0（不限制）
webhook	webhook.hooks.<id>.stepTimeoutSec（每个 hook 独立）	0（不限制）
heartbeat	heartbeat.stepTimeoutSec	0（不限制）
dreaming	dreaming.stepTimeoutSec	0（不限制）

0 / 未配置 = 不限制（等同 web 会话行为）。设置页（Settings → 各插件）均有「单步超时（秒）」输入框，getConfig 自动回填当前值，保存即热生效（无需重启）。

工作机制

agent 通用扩展容器 __pluginConfig

• 作用：agent 上的插件共享扩展配置（不止 turn-guard 用，未来插件都用）
• 结构：按插件名分区 { turnGuard: { stepSec }, loopGuard: {...}, xxx: {...} }
• 挂载方式：Object.defineProperty(agent, "__pluginConfig", { enumerable: false, writable: true, configurable: true })——不可枚举，避免被遍历/序列化干扰
• 生命周期：纯内存属性，不持久化。resume 恢复的 agent 是新对象——各入口插件在 create + resume + 复用所有路径统一挂载（幂等）
• 会话独立：每个 agent 绑定唯一 session，多会话并发互不影响

单步超时逻辑

// session/event 里识别 step 边界（窄短路：assistant/chunk 等高频事件直接 return）
if (event.type === "step/start") {
  const agent = agents.get(session.id);
  const sec = agent?.__pluginConfig?.turnGuard?.stepSec;
  if (!sec) return; // 无配置不干预
  timers.set(session.id, setTimeout(() => {
    agent.cancel({ kind: "hook", reason: `step timeout (${sec}s)` });
  }, sec * 1000)); // 底层 setTimeout 需要毫秒，这里转换
} else if (event.type === "step/end" || event.type === "turn/end") {
  clearTimeout(timers.get(session.id));
}

cancel 语义

• agent.cancel({kind:"hook", reason}) 是 AgentCancelCause 的合法值，中止整个 turn（abort signal → turnEnds={kind:"aborted"} → turn/end 落盘）
• 默认清 inbox（keepInbox: false）：模型已退化时 pending 消息留着只会继续跑
• step/end 在 agent-loop 的 finally 里必发（完成/失败/取消/max-tokens 都到）——定时器必然被清理，无泄漏

行为矩阵

会话类型	配置	行为
gateway-*（imessage）	有（如 300s）	每步超 300 秒打断
webhook-*	有（每 hook 可配）	同上
heartbeat-*	无（默认）	不限制
dreaming-*	有（如 600s）	每步超 600 秒打断
session-*（web）	永远不管	不限制（交互式）

结构

dsh-turn-guard/
├── index.js              # host 插件：session/event 监听 + 定时器 + agent.cancel
├── cordis.patch.yml      # 插入 host 插件行
└── package.json          # dsh.bundle

纯 host 插件（无 client/设置页——配置入口在各入口插件的设置页）。

依赖 dsh 服务（host）

agents（通过 agents.get(session.id) 取 agent 读配置；session/event 事件由 sessions 服务经 ctx 广播）

技术核实（源码依据）

• step/start/step/end 事件真实存在且必然成对（dsh-agent-loop turn() 里 step/end 在 finally 发出，完成/失败/取消/max-tokens 都到）
• agent.cancel({kind:"hook", reason}) 是 AgentCancelCause 合法值，中止整个 turn（abort signal → turnEnds={kind:"aborted"} → turn/end 落盘）
• ctx.on("session/event", (session, event) => ...) 订阅姿势与官方 dsh-agent-instructions 同款
• 事件频率不是问题：step 粒度 = 一次 LLM 请求 + 工具执行（秒级），set/clearTimeout 微秒级；真正火线是 assistant/chunk（每 token 一条），handler 窄短路只处理 step/start/step/end/turn/end

安装

主实例 profile 挂载（dependencies + bundles 两处）：

dsh plugin --profile web add /Users/fatatalia/project/dsh-turn-guard

或手动加 package.json 的 dependencies（"dsh-turn-guard": "link:..."）+ dsh.profile.bundles。

验证

• 正常路径不误伤：正常任务快速完成，定时器设置/清除无副作用
• 超时路径：临时把某会话 stepTimeoutSec 设小（如 3），发一条需要长时间推理的指令，确认：
  • 会话日志 turn/end reason={"kind":"aborted","reason":{"kind":"hook","reason":"step timeout (3s)"}}
  • step/end 在 finally 正常发出（定时器无泄漏）
  • agent 回 idle

已知局限与未来扩展

• 单步超时只防"单步卡死/持续输出"（如模型在一步内无限生成）——防不住多步快速循环（每一步都快速完成）
• 未来扩展（同插件零改动）：
  • 步数上限：__pluginConfig.turnGuard.maxSteps，step/start 计数超限 cancel（防多步无限循环）
  • 循环特征检测：相同工具调用重复 N 次 → cancel（更精准）

相关

• 方案文档（设计稿 + 实现状态）：docs/turn-guard-plan.md（在代码东工作区）
• 前置修复（入口层兜底）：dsh-webhook deliver 工具调用轮次上限（15 轮）
• 事故记录：webhook 模型循环事故（2026-08-21）