dsh-tick

dsh plugin --profile web add dsh-tick

<div align="center">

dsh-tick

在 DSH 会话里安排定时任务：到点后自动向当前会话注入一段提示词，唤醒模型去执行。

[English](README.en.md) · 中文





<img src="assets/01-dock-collapsed.png" alt="输入框上方的定时任务面板（折叠状态）" width="660">

_{输入框上方的折叠摘要行 —— 点它展开即可管理任务。}

</div>

---

这是什么

你想让 AI「5 分钟后检查一下构建队列」、「今晚 11 点汇总今天的工作」、

或者「每隔 10 分钟看一眼部署状态」——说一次就行，到点它自己会做。

dsh-tick 把定时能力做进当前会话：到点后，你设定的那段提示词会被注入会话，

唤醒模型执行。任务存在会话自己名下，不会串到别的会话。

---

三种定时模式

模式 · 你怎么说 · 行为

延迟 · 「2 分钟后检查构建队列」 · 倒计时结束后执行一次

固定时刻 · 「今天 23:00 汇总工作」 · 到那个时刻执行一次

重复 · 「每 30 分钟看一眼部署」 · 按固定间隔反复触发，直到你暂停或删除

延时上限 30 天（超过会被拒绝，并提示你改用固定时刻模式）；周期不限时长。

想等更久，请用「固定时刻」模式指定一个绝对时刻。

小提示：周期间隔想设得很长时请留意——DSH 关闭期间计时会冻结，

想让周期任务严格按间隔跑，得让它一直开着。

---

三条管理路径

同一批任务，随你用哪种方式管：

1. 输入框上方的面板 —— 点开就能看剩余时间、暂停、编辑、删除；

2. /schedule 命令 —— 不用打开面板，在聊天框里直接建；

3. 让 AI 自己管 —— 你的助手可以直接创建、查询、暂停、删除任务。

/schedule +30m 检查构建队列
/schedule +2h30m 汇总今天的改动
/schedule every 10m 看一眼部署状态
/schedule @2026-09-21T09:00:00+08:00 早会前汇总未完成项
/schedule list

时长写法用 s / m / h（例如 +30m、+2h30m），也接受中文

「秒 / 分钟 / 小时」（例如 +30分钟、+1小时）。不支持 d（天）——

要等一天以上，用「固定时刻」模式给一个绝对时刻更稳妥。

---

装好之后

暂停与恢复会冻结剩余时间：暂停一个还剩 4 分钟的任务，明天再恢复，

它仍然等 4 分钟——不会因为过了一夜就立刻触发。

DSH 关掉时计时冻结（延迟与重复模式）。重新打开后任务会变成已暂停状态，

不会在你不在的时候突然触发。固定时刻的任务如果在那期间到点了，

会标记为已超时并等你处理。

上图里三行分别是：已暂停（重复任务）、已超时（固定时刻，跨重启错过的）、

已暂停（延迟）。侧栏底部的红点数字是所有会话里的超时总数。

已超时的任务点一次播放按钮就等于「立即执行」——不会另外再等时间。

---

安装

dsh plugin --profile web add dsh-tick

装好后重启 DSH 即可。

需要 DSH 0.1.5-rc.2 以上（0.1.5 与 0.2.0 均已实测支持，见下方「兼容的 DSH 版本」）。

插件不修改 settings.yaml，卸载时随插件目录一起消失，不留残留。

---

配置

插件自带一个配置文件（在插件自己的目录下，不写进 DSH 的 settings）：

{
  // 注入给模型的提示词用什么语言：'en'（默认）| 'zh' | 'custom'
  "serverPromptLanguage": "en",

  // ── 下面三道闸的默认值是**保守**的，按你的习惯自行调整 ──
  "maxTasksPerSession": 50,      // 每个会话最多存多少个任务
  "maxActivePerSession": 10,     // 同时处于启用态的任务上限
  "maxInjectionsPerMinute": 1,   // 每分钟最多注入几次（防自我循环）

  "heartbeatMs": 15000,          // 心跳间隔：DSH 关闭期间计时的精度
  "graceMs": 60000,              // 到点判定的宽限，避免把刚触发误判成错过
  "showDock": true,              // 是否显示输入框上方的面板
  "showSidebarSummary": false,   // 侧栏底部汇总入口（默认关闭）
  "allowAiCreate": true          // 是否允许 AI 创建任务
}

⚠️ 三道闸默认是保守值（maxTasksPerSession: 50、maxActivePerSession: 10、

maxInjectionsPerMinute: 1）。它们的作用是兜住 AI 的批量误建与自我循环，

不是性能限制。日常使用如果觉得紧，直接改大即可——这是给你自己的安全绳，

不是产品硬约束。

这些配置项改完即生效，无需重启 DSH。

注入语言（serverPromptLanguage）

决定模型看到的提示词用什么语言，与界面语言相互独立：

取值 · 效果

"en"（默认） · 英文

"zh" · 中文

"custom" · 用你自己的模板

默认英文是与 DSH 官方 goal / todo / schedule 保持一致的做法——

它们的界面有中英双语，但注入给模型的提示词始终是英文。

选 custom 后会生成一份带完整中文注释的模板文件，改完即生效、无需重启。

若该文件损坏，插件会把它改名保留为 .bad-<时间戳>、重新生成为初始模板，

并在对话窗口提示一次。

---

界面语言

面板、侧栏、/schedule 回执都会跟随 DSH 的语言设置

（设置 → 通用 → 语言），中文 / English 都支持。

未做过语言选择时默认中文。

注入给模型的提示词用的是上面的 serverPromptLanguage，

与界面语言互不影响。

---

与 DSH 的边界

• 不往会话日志里写自定义事件：任务状态存在插件自己的目录里。

DSH 的会话日志有事件类型白名单，插件没有公开途径登记自己的类型。

• 注入消息标记为插件来源，不伪装成用户发言。会话记录里始终能区分

「你说的」与「定时器注入的」。

• 不占用官方 dsh-schedule：官方那套是宿主级持久提醒（跨会话、可唤醒冷会话），

本插件是会话内定时任务。两者定位不同，同时开启会让你和 AI 面对两套定时系统。

---

附：为什么没有「会话行内」的图标

会话列表里不会出现定时任务的图标。这不是遗漏，而是官方机制本身做不到。

DSH 的侧栏只开放 6 个插槽，其中会话列表区 sidebar.workspaces 是 single

插槽且已被官方独占：single 的语义是"渲染优先级胜者"，

第二个注册者是替换而非并列，无法增量添加；而会话行内部没有 slot 渲染点。

唯一可行的路径是 DOM 注入（依赖压缩后的哈希类名），改版即碎、失效时还静默无提示，

代价大于收益，故不做。官方 goal 与 todo 也没有会话行内图标。

替代品：侧栏底部的跨会话汇总入口（即 showSidebarSummary，默认关闭）。

打开后它会显示所有会话的待执行 / 已超时总数，点开可展开跨会话列表并跳转。

用的是官方 sidebar.footer.action 插槽，零 DOM 依赖——把上面配置里的

showSidebarSummary 改为 true 即可。

---

已知限制

• 计时依赖 DSH 运行：延迟与重复模式在 DSH 关闭期间冻结计时，

需要它按真实时间流逝的话，得保持 DSH 开启。

• 不扫描历史积压：DSH 关闭期间错过的重复轮次全部丢弃，不会在重开后补跑。
• 注入频率默认每分钟 1 次（maxInjectionsPerMinute）：

设了比这更短的周期，实际触发会被限流。要跑更快就调大这个值。

• 时长不支持 d（天）：用 h（如 +48h）或「固定时刻」模式。

---

更新日志

v1.1.0（2026-11-04）— 后台唤醒 + 收起态倒计时

① 新增「允许后台唤醒」配置项（默认开启）

以前任务到期时，如果目标会话没有在界面上打开，插件拿不到该会话的执行主体，

于是只能等你点开会话之后才"突然一起触发"。

现在默认会在任务到期时主动唤醒该会话并准时投递。这走的是官方

sessionController.resolveAgent()（契约原文：Resolve or resume one ordinary Session），

与官方 dsh-schedule 的做法一致。

若你希望插件保持安静、只在已打开的会话里投递，把 data/config.json 的

allowBackgroundWake 改为 false 即可——此时任务不会丢，仍保持逾期状态，

等你打开会话后照常触发。

② 修复收起状态下倒计时不刷新

输入框上方的折叠摘要行本来就在显示"下一个任务还有多久"，但此前只有展开时才

每秒刷新，收起时数字会僵住直到下一次轮询。现在只要存在待执行任务，收起状态也会

每秒正常走字（只重渲染，不发请求）。

---

v1.0.3（2026-11-03）— 修复 DSH 0.2.1 下注入失败

症状：升级到 DSH 0.2.1 后，任务到点触发时整轮报错：

本轮运行失败  format v4 message requires a producer-owned source kind

原因：0.2.1 启用了会话格式 v4，废弃了消息来源的 kind: 'plugin' 写法，

改为要求「生产者自有的 kind」。插件原先注入的 { kind: 'plugin', plugin: 'tick' }

正好是被拒绝的那一种，因此注入这一步失败（任务本身能正常计时、正常标记完成，

只有"把提示词送进会话"这一环挂了）。

修复：改用 { kind: 'plugin:tick' }。这个形状不是随手取的，而是

DSH 自己把旧数据迁移到 v4 时产生的同一种形状（迁移函数对 plugin:'tick'

就是返回 plugin:tick），所以与官方语义完全一致。会话记录里仍能一眼认出

「这是插件注入的」，也绝不会被误当成你的发言。

兼容性（同一份代码，无需按版本装不同包）：

DSH 版本 · 状态

0.1.5-rc.2 · ✅ 支持（该版对消息来源无运行期校验）

0.2.0 · ✅ 支持（该版已可用 describe() 读配置，见下）

0.2.1-rc.5 · ✅ 支持（即本次修复的目标版本）

跨版本能力检测自动选路，不依赖版本号：

· 0.1.x · 0.2.x

读界面语言 · settings.get('locale') · settings.describe()（get 已被移除）

语言变更通知 · settings.watch(cb) · settings/document-updated 事件（watch 已被移除）

其余用到的官方 API（defineTool / ctx.tools.register / createUserMessage /

connection.fetch.register / ctx.slots.register / ctx.locale.*）

…(truncated)