定时任务引擎 LouisHaoL/dsh-timer-agent

dsh-timer-agent — DSH 定时任务 × AI 智能体引擎

一个 DeepSeek Harness (DSH) Web GUI 插件：调研 NousResearch/hermes-agent 的 cron 系统后，按其「定时器 ↔ 智能体协同」思路实现的 host 常驻定时任务引擎——dsh web 服务启动即生效，GUI 页面关闭也照常触发。

新建任务弹窗：项目/会话树 + 智能体预设 + cron 定时（截图数据已脱敏）

它做什么

到点（5 段 cron）通过真实智能体会话执行你写好的提示词：

- 指定已有会话 → 每次触发继续该对话，具备上下文连续性（hermes cron 的 continuity 形态）
- 指定项目 workdir → 每次在该项目内新建会话运行（自动加载其 AGENTS.md）
- 两者都留空 → 每次触发在默认工作空间新建会话发起新对话

对话中可直接用 timer_agent 工具管理任务（create / list / update / pause / resume / remove / run）；Web GUI 侧边栏「定时任务」面板管理同一批任务——一个台账，三个入口（工具 / WebUI / 文件）。

两种任务类型

- AI 智能体任务（默认）：到点驱动真实智能体会话执行提示词，消耗 API 额度
- 普通任务（命令）：到点直接 spawn 运行你指定的 命令 + 参数（可选工作目录、超时），不经过 AI、不消耗额度；stdout/stderr 尾部（≤16k 字符）与退出码随执行记录入账。适合自包含的脚本（下载、导出、续期等）

[!WARNING]
普通任务会在你的机器上以当前用户权限执行任意命令，没有任何沙箱或白名单。 任何能新建/编辑任务的人（你自己、能调用 timer_agent 工具的智能体会话、能访问回环 API 的本机进程）都能让任意程序定时运行。请只填入你审查过的、无人值守安全的命令；不要把该插件暴露给不可信环境；任务台账 jobs.json 可被篡改即等价于本机任意代码执行。谨慎使用。

架构（hermes-agent cron 同构）

┌─ dsh web 宿主进程 ────────────────────────────────┐ │ 60s ticker（常驻，GUI 关闭也运行） │ │ ├─ HostJobStore ~/.dsh/timer-agent/jobs.json │ │ │ (原子写，损坏降级不崩溃) │ │ ├─ TimerRunner at-most-once：先顺延 nextRunAt │ │ │ 再触发；运行中跳过；错过即跳过 │ │ │ ├─ agents.resume（钉住会话） │ │ │ └─ agents.create + workspaceRegistry │ │ │ (新会话挂到正确项目) │ │ ├─ timer_agent 工具（模型可调用） │ │ └─ /api/dsh-timer-agent/* 路由（仅回环） │ └────────────────────────┬──────────────────────────┘ │ HTTP 轮询镜像（5s） ┌─ 浏览器半边（薄）────────┴──────────────────────────┐ │ 侧边栏入口 + 任务面板（React） │ │ 可折叠项目/会话树 · cron 预设 · 执行历史 │ └───────────────────────────────────────────────────┘

执行结算通过 session/event（turn/end 的 reason.kind）判定成功/失败，失败原因精确写入台账。

功能

- 定时执行：5 段 cron（分 时 日 月 周，支持 / /n / a-b / 逗号列表）+ 预设下拉（每天 09:00 / 每小时 / 每 10 分钟 / 每周一 09:00，新建与编辑页均有）
- 三种执行模式：新建页下拉选择 Cron / 固定间隔 / 一次性（紧跟「启用定时执行」，未勾选时禁用）；固定间隔按上次触发时刻堆整周期，不随重启漂移
- 一次性任务：只设一个执行时间（默认当前 +1 小时），触发一次即自动归档——无论成功、失败还是手动「立即执行」，都算消耗；适合"做完即走"的收尾脚本与提醒
- 下次执行时间可编辑：固定间隔与一次性任务可在详情页手动改下次执行时间；Cron 模式严格遵守表达式（服务端拒绝手改）
- 暂停/恢复语义：暂停保留下次执行时间；恢复基于真实上次执行时间重算，错过的执行不补跑，直接跳到下一个未来时间点
- 目标树选择器：按项目分组的可折叠树，每组含「新增会话」+ 该项目已有会话（按最近活跃排序）；选中会话即钉住该对话
- 任务面板：列表（标题/状态/下次运行/执行次数）、搜索过滤、详情页（cron 编辑/执行历史/跳转会话 transcript/立即执行/重置/删除）
- 模型工具：任何对话中 timer_agent 直接创建与管理定时任务
- 系统提示注入：host 半边注册 plugin:timer-agent 播报段，智能体知晓本插件能力与协作方式
- 安全：API 路由仅回环 + 同源可访问（与 dsh-ssh 同防线）

v0.8.0 变更（兼容 dsh 0.2.0-rc.2）

适配 dsh 0.2.0-rc.2（自 v0.7.0 的 dsh 0.1.5-rc.2 跨两个 minor 升级，两处破坏性变化）：
- settings 服务重构：宿主移除 SettingsProvider.installSection 运行时注册，换为 SettingsForms——插件配置改由 cordis loader 按导出的 Config schema 声明式注入（值写在 profile patch 的插件行上，改动即重载插件 fiber），client 端配置表单由 SettingsForms 自动生成。本插件删除 installSection 注册与 settings 注入，enabled/announceToAgent 语义不变
- schemastery 分叉包切换：dsh 0.2.0 把 @deepseek-ai/schemastery fork 收紧到 ~3.18.4（3.18.3/4 引入 Mode/SchemaOutput 类型体系），与原版 schemastery 同名声明合并后 typecheck 冲突。插件改用 fork 与宿主同源（运行时行为不变，宿主对 schema 本就鸭子类型调用）
- 其余宿主面逐一核对不变：服务注入名（settings 移除后为四项）、webServer 路由、systemPrompt.section、tools.register、session/event/turn/end、client 端 slots/sessions 注入与 /plugins/<id>/client.js 服务路径；dsh.compatibility.dshReleases 声明更新为 0.2.0-rc.2
- peer/dev 依赖对齐 dsh 0.2.0-rc.2 配对版本（cordis ~4.0.4、全部 @deepseek-ai/dsh- 对齐 0.2.0-rc.2）
- 宿主侧加法扩展（本插件不消费、不受影响）：tools 新增 cancel 决策与 projectContent 投影；system-prompt 新增 interpolate 选项与 TOOL_COMPUTER_USE/MCP_SERVERS 段位；ui-settings 新增 settings.launcher slot 与 configForms（原 settingsScope 改名）

向下兼容：任务台账格式无变化，v0.7.0 及更早的 ~/.dsh/timer-agent/jobs.json 升级即用。真机验证：隔离 DSH_HOME 分别起 dsh web 0.2.0-rc.2 与 0.1.5-rc.2，插件均正常挂载、/api/dsh-timer-agent/jobs 200、台账零副作用；更旧版本 dsh 请用 v0.7.0。

v0.7.0 变更（兼容 dsh 0.1.5-rc.2）

适配 dsh 0.1.5-rc.2（自 v0.6.0 的 dsh 0.1.2-rc.1 跨四个 minor 升级，宿主插件面 API 几乎全部稳定，仅两处破坏性变化）：

- agents 的 cancel(cause)：宿主把自由文本 cause 换成了稳定意图枚举（user/parent/hook/disposed）。本插件的超时取消迁移为 { kind: 'hook', reason: … }（无人到场的自动取消并携带原因）
- 冷读服务拆分：sessionPersistence.inspect 被移除。钉住会话恢复时的预设重建改走 sessionQuery.readSession（完整事件流，agent-preset/selected 仍生效）；宿主未挂 sessionQuery 时回退 sessionPersistence.stat 读 header
- 其余宿主面（五项服务注入名、webServer 路由、systemPrompt.section、tools.register、session/event/turn/end、agentDefaultModel/llm/agentPresets、followup 消息形状）经逐一核对全部不变；dsh.compatibility.dshReleases 声明更新为 0.1.5-rc.2
- peer/dev 依赖对齐 dsh 0.1.5-rc.2 配对版本（cordis ^4.0.2）；插件继续使用 schemastery（宿主运行时对 schema 仅做鸭子类型调用，分叉包无影响）

向下兼容：任务台账格式无变化，v0.6.0 及更早的 ~/.dsh/timer-agent/jobs.json 升级即用；仅在 dsh ≥ 0.1.5 上验证，旧版 dsh 请用 v0.6.0。

v0.5.0 变更与向下兼容

变更

- 执行模型改为完全依赖持久化的下次执行时间(nextRunAt):cron / 固定间隔只用于计算它,到期即触发
- 新增一次性任务(runAt 创建 / timer_agent 的 run_at 参数):触发一次即归档;手动执行同样消耗
- 暂停不再清空下次执行时间;恢复改为基于真实上次执行时间(executions 最后一条的 startedAt,回退 lastTriggeredAt)重算,错过不补跑
- 固定间隔 / 一次性任务的下次执行时间支持手动修改(PATCH nextRunAt / 工具 next_run_at);Cron 严格按表达式,拒绝手改
- 一次性任务对「跳过一次」无意义(跳过即等于不执行),UI 隐藏该按钮、服务端拒绝

向下兼容

- 旧版本台账无需迁移,升级即用:v0.4.0 及更早的 cron / 固定间隔 / 暂停态行全部原样保留;空白脏行仍被丢弃(与旧版一致),损坏台账依旧降级不崩溃
- 旧版代码路径不可能写出一次性任务的行形态(cron 与 interval 皆空且带时间),不存在旧任务被误判为一次性而自动归档的风险
- 唯一注意:升级后若回滚到 v0.4.0,一次性任务的排程会被旧版校验丢弃(任务变回未排程);cron / 固定间隔任务不受影响

安装

dsh plugin --profile web add link:<本目录绝对路径>

安装后重启 dsh web,侧边栏出现「定时任务」入口即生效(浏览器侧改动强刷 Ctrl+F5 即可)。

Configuration

| Option | Type | Default | Description |
| enabled | boolean | true | 总开关：ticker + 工具 + 路由。设为 false 可停用引擎，无需卸载。 |
| announceToAgent | boolean | true | 注入一段 system-prompt，向智能体声明插件能力。 |

工具

timer_agent

管理宿主 ticker 持有的定时任务（与 web GUI「定时任务」面板渲染的是同一批记录）。

参数：
- action（string，必填）：create / list / update / pause / resume / archive / restart / remove / run
- job_id（string）：任务 id，除 create/list 外所有动作都必填（id 从 list 获取，不要猜）
- prompt（string）：create 时填定时运行执行的完整自包含提示词；update 时填替换内容；run 时填该次触发的临时上下文
- schedule（string）：5 字段 cron，例如 0 9 * ；create 时必填
- name（string）：简短的人类可读标题
- workdir（string）：运行会话所在的绝对项目目录（留空 = 默认工作区）
- session（string）：钉住已有会话 id —— 每次运行都延续该对话

返回： { kind, job?, jobs?, error? } —— 摘要后的任务记录，或结构化错误信息。

构建

pnpm install
pnpm run build # lib/index.js(host) + lib/client.js(浏览器,CSS 已内联)
pnpm run typecheck
pnpm test # 49 项行为级 E2E(fake host faces,无需 dsh 运行时)
pnpm run smoke-test # 静态结构冒烟(23 项)

E2E 覆盖：cron 解析与下次运行计算（本地时间语义）、台账原子写与损坏降级、at-most-once 调度触发、钉住会话 resume、turn/end 成功/失败结算（含失败原因入账）、运行中拒绝重复触发、禁用调度不触发、手动触发通道、workdir 传递、timer_agent 工具全动作（含非法参数拒绝）、HTTP 路由 CRUD + run + 回环/同源防线 + 非法输入 400。

与 hermes-agent cron 的对应关系

| hermes-agent | 本插件 |
| gateway 进程内 60s ticker | dsh web 宿主进程内 60s ticker |
| 触发即新 AIAgent(platform=cron) 会话 | agents.create/resume 真实 dsh 会话 |
| ~/.hermes/cron/jobs.json 台账 | ~/.dsh/timer-agent/jobs.json(原子写) |
| at-most-once(先推进 next_run_at) | 先顺延 nextRunAt 再触发 |
| claim 去重 + 心跳 | 运行中跳过 + 5s 手动触发快通道 |
| deliver 回投/指定平台续跑 | 钉住会话 / workdir 新会话 / 默认空间 |
| cron_hint → notepad → script 组装 prompt | 自包含 prompt(无人在场,不可提问) |
| turn/end reason.kind=error 结算 | 同款 session/event 结算 |

兼容性、依赖与权限声明

兼容范围（声明于 package.json）：

- DSH：0.2.0-rc.2（dsh.compatibility.dshReleases 精确声明 compatible；其他版本未验证，视为 unknown）
- Node.js：>=22（engines.node；仓库内测试依赖 Node 22+ 的 type-stripping 能力）
- 系统：开发验证环境为 Windows 10/11；macOS/Linux 未验证

依赖：

- 运行时依赖仅 @deepseek-ai/schemastery（配置 schema 校验，与宿主同源的分叉包），随包安装，无 install/postinstall/prepare 生命周期脚本
- @deepseek-ai/ 与 react 均为 peerDependencies,由 dsh 宿主提供,插件不禁用、不替换、不重复安装任何官方组件
- 不执行任何安装期构建、下载或远程安装;构建产物 lib/ 直接随源码入库

权限披露（源码静态扫描可见的四类信号，均为插件功能所需）：

- 文件：任务台账 ~/.dsh/timer-agent/jobs.json 的原子读写（store）；不触碰 dsh 核心目录与其他 Profile 文件
- 命令：command 型任务通过 spawn 执行任务作者填写的命令（cwd 可指定 workdir，继承宿主 process.env）；prompt 型任务通过 dsh session API 执行，不直接起 shell
- 网络：仅 localhost —— web GUI 调用同源 /api/dsh-timer-agent/* 路由 + 宿主经 dsh client 调用本地 dsh 服务；不连任何外部服务
- 凭据：子进程继承宿主 process.env（dsh 凭据经环境变量传给 CLI）；插件自身不读取、不记录、不持久化任何凭据或密钥

失败边界：服务进程停止即不触发（错过即跳过）；台账损坏时降级为空表并备份原文件；运行中到点跳过本次；手动触发与 ticker 触发走同一 at-most-once 通道，不会重复执行。

源码版本锚：v0.8.0 发布于 tag v0.8.0。

已知限制

- 定时执行依赖 dsh web 服务进程存活（服务停了自然不触发；重启后只跑已顺延到期的任务，错过即跳过）
- 任务运行中到点跳过本次，等下一个 cron 匹配点
- 执行消耗 API 额度；定时执行无人在场，prompt 必须自包含、不可提问

致谢

- NousResearch/hermes-agent — cron 架构范本
- dsh-web-ui 全家桶（dsh-ssh / dsh-client-ui-task-board）— host 服务、路由注册、侧边栏注入与预设下拉的工程先例

License

MIT