dsh-time-watchdog

给 DSH 加一只计时看门狗：记录本轮对话从 turn/start 开始已经运行了多久，并据此做四件事：

• 模型侧：clock_elapsed 工具，随时读到本轮已用时间。
• 模型侧：/set-time 设定的分段提醒，在每步之前向模型注入一条隐藏提示词，催它收尾。
• 人侧：聊天气泡上方的卡片——周期显示「本轮已运行多久」，以及每条提示词发出时提示「提示词已发送」。
• 人侧：设置页里可编辑的 4 种提示词模板 + Toast 开关。

English (short): A turn timer for DeepSeek Harness. It folds turn/start into a session projection to answer "how long has this turn been running", exposes that as the clock_elapsed tool, and uses agent/pre-step to inject wrap-up prompts on a /set-time <t1> <t2> <t3> schedule. Two cards above the composer show run-time and "prompt sent"; four prompt templates are editable in Settings. No network, no telemetry, config is one JSON file under ~/.dsh/storages/.

安装

dsh plugin --profile <你的 profile> add dsh-time-watchdog

装完重启 DSH 桌面进程（宿主侧 lib/index.js 是 ESM，刷新页面不够）。

也可以直接从本仓库装（想跟 main 最新代码时）：

dsh plugin --profile <你的 profile> add git+https://github.com/aawef/dsh-time-watchdog.git

本地开发：从源码目录接线

# 1. 接到 profile（junction，不需要管理员权限）
powershell -Command "New-Item -ItemType Junction -Path \"$env:USERPROFILE\.dsh\profiles\<profile>\my-plugins\dsh-time-watchdog\" -Target \"<本目录绝对路径>\""

# 2. 在 ~/.dsh/profiles/<profile> 里加依赖并装
#    package.json → dependencies:  "dsh-time-watchdog": "file:../web/my-plugins/dsh-time-watchdog"
#    package.json → dsh.profile.bundles:  追加 "dsh-time-watchdog"
pnpm install

它做什么

能力	说明
计时	折叠单元 watchdog 在 turn/start 记下时刻，在 turn/end 结算总耗时
读数	工具 clock_elapsed 返回本轮已用时间（进行中持续累计，已结束冻结）
周期卡片	/clock 设的间隔，弹卡显示已运行时长
收尾提醒	/set-time <t1> <t2> <t3> 三段式排程，到点注入提示词
提示词定制	4 种模板（开始 / 未超时周期 / 首次超时 / 超时后周期），设置页可改
配置	~/.dsh/storages/dsh-time-watchdog.json

计时口径

与 DSH Web 客户端右上角那个「深度求索中，用时 12s」完全一致：

• 起点 = turn/start 事件的时刻；
• 只有轮处于 open 状态才继续计时，turn/end 之后读数冻结；
• 向下取整到秒。

区别只在于取数方式：客户端读的是浏览器内存里的 timeline 投影（宿主侧不存在等价物）， 本插件自己折叠一个 session projection 存时刻，因此读数 O(1) 且不碰 session.eventAt()（该 API 已标 @deprecated，注释写明 "new calls are prohibited"）。

工具

clock_elapsed

无参数。返回：

{
  "turn": 7,
  "running": true,
  "elapsedMs": 93000,
  "elapsedSeconds": 93,
  "elapsedText": "1m 33s"
}

模型读到的正文是「第 7 轮：本轮进行中，已运行 1m 33s（93000 ms）。」，JSON 作为第二段附在后面供解析。

running: false 表示本轮已结束，elapsedMs 是这一轮的总耗时。

收尾提醒：/set-time

/set-time <t1> <t2> <t3>

每段可写裸秒数 30，也可写复合时长 30s、2m、1h、1h20m30s （单位大小写不敏感，顺序必须 h→m→s，允许跳级如 1h30s）。

参数	含义
t1	到 t2 之前，每 t1 提醒一次
t2	预期可工作时间（截止点）
t3	超过 t2 之后，每 t3 提醒一次；t3 <= 0 关闭这一档

示例：/set-time 30s 5m 1m（等价于 /set-time 30 300 60）= 预期 5 分钟， 期间每 30 秒提醒一次；到 5 分钟发一次「首次超时」，之后每 60 秒再催一次。 长跨度直接写 /set-time 10s 1h20m30s 2m。

参数上限 86400 秒（24 小时）。

生效规则（只对一轮生效）

下达时机	行为
当前没有进行中的对话	挂起，等下一轮 turn/start 时才真正开始计时
当前有进行中的对话	从指令发出时刻起算，并立即注入「计时已生效」提示词
该轮 turn/end	计划被清理，不会沿用到后续轮次；要再次生效必须重新执行

未指定的两份提醒（开始、首次超时）在每轮里各只发一次。

边界情况

• t1 >= t2：跳过「未超时周期提醒」这一档（否则它永远不触发，等于骗人）。
• t3 <= 0：「首次超时」照发，「超时后周期」关闭。
• 长工具执行期间不触发：提醒只在 agent/pre-step 发生，工具跑完进入下一步时才会到点。
• 到达截止点只是注入提示词，不会中止模型或强制结束本轮。

实现要点

• 通道是 agent/pre-step（与官方 dsh-time-context 同一条路）。pre-step 能替换进入该步的消息， 所以注入的提醒会在同一个模型请求里被读到，而不是等到下一个请求。
• 注入用 createUserMessage({ source: { kind: "dsh-time-watchdog", form: "notice", summary } })。 source.kind !== "user" 的 user/message 在客户端归为 context 节点、不渲染成聊天气泡—— 所以模型读得到、界面上看不到，正是「隐藏提示」要的效果。
• 计划（t1/t2/t3、deadline、已发档位）存在内存的 Map<sessionId, plan> 里， 不写 session 事件：命令本身不改事件流，而计划的生命周期完全由 turn 边界决定。
• 排程是纯函数 stepPlan(plan, now)，输入当前时刻，输出「该不该提醒 + 新计划」， 因此可以完全脱离时钟被测。
• 到达截止点后每 t3 秒一条，一轮最多十几条 user/message，是有意的取舍 （要「每次提醒都进模型上下文」就不可能不落历史）。

提醒卡片（toast）

两张卡片

卡片	触发	内容
已运行	本轮进行中，每 /clock 秒	本轮对话已运行 Xm Ys（+ 第 N 轮）
已发送	宿主每注入一条提醒（投影 injectSeq +1）	「提示词已发送」；在设置页打开「显示详细内容」后，卡片里还会带上本条提示词的正文

两张都停留 5 秒（HOLD_MS）后消失。

设间隔

命令	效果
/clock 30	每 30 秒弹一次
/clock 2m	每 2 分钟弹一次
/clock off 或 /clock 0	关闭
/clock	回显当前设置

允许 1–3600 秒。设为 off 时周期卡片完全不出现。

行为

• 只在本轮进行中计时；turn/end 之后不再弹。
• 第一次弹卡在「本轮开始后 t 秒」，之后每 t 秒一次，间隔从上次弹卡时刻算，不累积漂移。
• 换到新一轮时，弹卡基线清零，从新的 turnStartedAt 重新算。
• /clock 改完配置，页面最迟 3 秒（CONFIG_POLL_MS）跟上，不需要刷新。

实现要点

• 卡片挂在 conversation.input.overlay（composer 卡片顶部的零高锚点 data-composer-overlay），子元素用 bottom:100% 浮在输入框上方。
• 客户端读的是 useProjection("watchdog")，所以 watchdog 折叠单元必须带 wire 块； 没有 wire 的单元是 host-only，浏览器端读到 undefined。
• 客户端拿不到宿主内存，配置走同源 /dsh-time-watchdog/api/config。
• 样式只用 --dsw-alias-* 主题变量，不 require 任何 Harness Client 包。

设置页

设置 → 「计时与收尾提醒」（settings.section 槽位，id dsh-time-watchdog，order 92）。

• 编辑 4 种提示词模板，改动即时保存
• 「恢复默认模板」把四个文本框填回默认值（仍需点保存）
• 「发送提示词时显示 Toast」开关（关掉后不弹卡片，注入与计时逻辑不受影响）
• 「在『提示词已发送』卡片里显示详细内容」开关（默认关；开了就带上本条提示词正文）
• 说明区列出 /set-time 的参数语义与「只对一轮生效」的规则

占位符

占位符	替换成
&t1& &t2& &t3&	本次配置的三个参数，渲染成紧凑时长（30s / 1m30s / 1h20m30s）
&t4&	未超时时 = 剩余时间；超时后 = 已超时时间，格式同上

四个占位符都自带单位，模板里不要再写「&t2& 秒」，否则会渲染成「1m30s 秒」。

保存前不校验；注入前统一替换。渲染后会再扫一遍清掉残留的 &tN&， 所以就算模板里写了不存在的 &t9& 也不会把占位符漏给模型。

HTTP 端点

/dsh-time-watchdog/api/config

方法	行为
GET / POST	返回 { ok, intervalSeconds, toastOnPrompt, toastDetail, templates, defaults, templateKeys }
PUT	局部更新（body 里给哪些字段就改哪些），返回更新后的完整配置

webServer 缺席（CLI / 无 UI 组合）时端点不注册，插件其余功能照常。

生效规则

文件	改完之后
lib/index.js / src/*	重启桌面进程
lib/client.js	刷新页面（客户端资源是 no-cache 的）
package.json	重启；改了依赖还要 pnpm install
cordis.patch.yml	重启

注意：~/.dsh/profiles/desktop/node_modules/dsh-time-watchdog 是 pnpm 装出来的副本， 不是软链。改完源目录要重新 pnpm install（或手 copy）才会进宿主。

配置文件

~/.dsh/storages/dsh-time-watchdog.json

{
  "intervalSeconds": 30,
  "toastOnPrompt": true,
  "toastDetail": false,
  "templates": {
    "start": "…",
    "before": "…",
    "firstOverdue": "…",
    "afterOverdue": "…"
  }
}

intervalSeconds: null = 周期卡片关闭；toastDetail: true = 「已发送」卡片带正文。文件坏了/读不到时一律退回默认值，不影响插件加载。 设置页保存时会写全四个模板，所以文件里看到的一定是完整形状。

测试

node --test "tests/*.test.mjs" "tests/*.mjs"

文件	条数	覆盖
tests/watchdog.test.mjs	14	折叠单元与读数口径
tests/timing.test.mjs	24	/set-time 解析、模板渲染、stepPlan 排程决策
tests/client.test.mjs	16	客户端纯函数（vm 沙箱里求值 lib/client.js）
tests/client.render.test.mjs	13	迷你 React 渲染卡片，验证弹/不弹/撤/换轮
tests/config.test.mjs	10	/clock 参数解析与配置归一化
tests/host.test.mjs	12	假 ctx 跑 apply()，验证注册、折叠、命令回执、pre-step 注入

前五个都不 import 宿主包，在插件目录内即可跑；host.test.mjs 需要能解析 @deepseek-ai/dsh-llm 与 dsh-tools（只在 profile 的 node_modules 下成立）， 解析不到时整组 skip 而不是报错。

源目录跑 78 条（77 pass + 1 skip）——那 1 skip 就是 host.test.mjs 整组； 在 profile 的 node_modules 副本里跑同一套命令是 89 条全绿。 （npm 包里不含 tests/，所以用 npm 装出来的副本要跑测试得先把 tests/ 拷进去。）