定时任务 LittleBlackTong/dsh-plugin-cron

dsh-plugin-cron-scheduler

一个面向 DeepSeek Harness 的 cron 调度插件：按 cron 表达式为 agent 任务排班——可通过自然语言或侧边栏 UI 完成——每个任务在合适的时间向目标会话注入一条用户消息，触发完整的 agent 轮次。

DeepSeek Harness 的「定时任务」插件：按 cron 表达式给 agent 排班——到点往目标会话注入一条 user 消息，触发完整一轮 agent 执行（调工具、写文件、拉数据、生成报告，什么都行）。创建方式双通道：对话里自然语言说一句，或侧边栏底部「定时任务」列表里点「新建」。

怎么工作

- Host 平面：持久化 JSON store（/cron-jobs.json，原子写）+ 每任务一条 ctx.timer 定时链 + 到点 agent.followup() 注入合成 user 消息（source.kind === 'plugin'）。
- 会话策略：
- new（默认）：每次触发开一个新会话，干净隔离；
- fixed：绑定指定会话，累积上下文。绑定会话时是下拉选择（列出所有存活会话的标题），不用手填 session id。
- 错过不补跑：DSH 不是常驻服务，进程关闭期间的 tick 直接跳过，重启后从当前时间往后算，绝不开机风暴。
- 并发保护：同一任务上一次触发还没结束，新 tick 跳过并记 skippedAt，不重复执行。
- 执行历史（v0.2.0）：每次触发记录 lastRunStatus（成功/失败/跳过）+ 错误信息 + runCount，侧边栏列表里直接看到「上次: 成功 2026-09-09 10:30」，失败还会显示错误摘要。
- 手动触发（v0.2.0）：列表里「跑」按钮或对话里 cron_manage run 立即执行一次，不改变既定排班。
- 双通道创建：cron_manage 工具（对话自然语言）+ 侧边栏 UI（表单），共享同一套 Host CRUD。
- UI 位置：注册到侧边栏底部（sidebar.footer.action，新 id cron-hotplug），任务列表直接内联显示在侧栏里（新建/编辑/删除/启停/立即运行都在其中），与 Cordis Plugin 面板并列，不覆盖、不替换它。任务多时列表在容器内滚动，不会撑爆侧栏。
- 自适应（v0.2.9）：侧栏宽度可拖动，列表按容器实测宽度自动分档（ResizeObserver），任何宽度都不溢出、编/删 始终可点：

| 容器宽度 | 显示 |
| ≥ 300px | 名称 + Cron 表达式 + 上次状态 + 编/删 |
| 220–299px | 名称 + 状态 + 编/删（表达式收进 tooltip） |
| v0.2.8 曾把列表搬到 shell.overlay 弹层（footer 只留入口），v0.2.9 按反馈回退为内联列表，自适应能力保留。

安装

dsh plugin --profile add dsh-plugin-cron-scheduler

（包内置 dsh.bundle manifest，dsh plugin add 自动挂进 profile 的 bundles 层；dsh-market 里的一键安装同此通道。）

重启 DSH 后生效。之后在侧边栏底部「定时任务」列表里管理任务，保存即生效（无需重启）。

⚠️ 不要再往 profile 的 cordis.patch.yml 里手写 - insert: {id: dsh-cron, ...}：那会与 bundle manifest 的自动挂载产生两条同名 entry，整个 profile 会以 duplicate loader entry id "dsh-cron" 启动失败。运行期任务数据走 /cron-jobs.json；覆盖 composition 键（如 configFile）用不带 insert 的 id 覆盖条目。

对话用法（自然语言）

阿周：每周一 10:30 帮我导出上一周的 ZDP 数据小蓝：（调用 cron_manage 工具）已创建「每周导出ZDP上周数据」，下次执行：下周一 10:30

支持的 cron_manage action：create / list / update / delete / toggle / run。

cron 表达式是标准 5 字段（分 时 日 月 周）：

│ │ │ │ └─ 周几 (0-7，0 和 7 = 周日) │ │ │ └─── 月 (1-12) │ │ └───── 日 (1-31) │ └─────── 时 (0-23) └───────── 分 (0-59)

支持单值、范围（1-5）、步进（/5）、列表（1,3,5）、通配（）。例：

| 表达式 | 含义 |
| 0 10 * * | 每天 10:00 |
| 30 10 * 1 | 每周一 10:30 |
| /5 * * | 每 5 分钟 |
| 0 17 * 5 | 每周五 17:00 |

配置

| 键 | 默认 | 含义 |
| configFile | /cron-jobs.json | 任务数据文件路径（仅 composition 配置） |
| cwd | process.cwd() | new 策略新建会话的工作目录 |

⚠️ 新建会话（new 策略）必须补齐三样，否则那个 agent 一定是残的：

| 缺什么 | 后果 |
| agent preset（agentPresets.mount） | 工具集退化成空的全局层——只剩全局注册的工具，没有 shell/read 等标准工具 |
| 模型选择（agentDefaultModel + 装钩子） | persona 段的 {{model}} 取不到值，第一轮直接报错 |
| cwd（meta.cwd） | persona 段的 {{cwd}} 取不到值，第一轮直接报错 |

插件会自动补齐这三样（默认 preset / 默认模型 / cwd 不配则用 process.cwd()）。

为什么不用 settings 面板的通用 namespace？DSH 的 settings wire 只服务一张硬编码白名单（WEB_SETTINGS_NAMESPACES），插件无法把自有 namespace 暴露给浏览器写入。本插件因此在 host 自建了 /api/cron/ 路由，侧边栏 UI 直连该路由。

HTTP API

| Method | Path | 说明 |
| GET | /api/cron/jobs | 列出全部任务 |
| POST | /api/cron/jobs | 新建任务 |
| PUT | /api/cron/jobs/:id | 更新任务 |
| DELETE | /api/cron/jobs/:id | 删除任务 |
| POST | /api/cron/jobs/:id/run | 立即运行一次 |
| GET | /api/cron/sessions | 列出存活会话（固定会话下拉用） |
| GET | /api/cron/events | SSE 推送 jobs-changed |

开发

node --test 'test/.test.js'

已知边界

- 任务只在 DSH 进程活着时存在（app 关了就停，错过不补跑）。
- nextRunAt / skippedAt 是易失字段（进程内），重启后按当前时间重新计算。
- 固定会话若绑定了一个已不存在的会话，触发时会自动新建并回写 fixedSessionId。
- 到点触发需要目标 session 能启动 agent（有 agent 工厂 + 持久化后端）；无可用 agent 时记为「失败」并记录原因，不会崩溃。
- 版本要求：DSH session format v4（官方 DeepSeek Harness 0.1.7+）。注入消息的 source 使用 producer-owned kind plugin:cron；v4 拒绝 v3 的 {kind:'plugin', plugin:'cron'} wrapper，报 format v4 message requires a producer-owned source kind（被包成 code: "UNKNOWN"，界面显示为 ... source kind UNKNOWN）。v4 与 v3 白名单互斥，无法同时兼容两版；0.2.9 及更早版本在 v4 上会触发该错误。

License

MIT