dsh-timer-agent — DSH 定时任务 × AI Agent 引擎
中文 | English
一个 DeepSeek Harness (DSH) Web GUI 插件:调研 NousResearch/hermes-agent 的 cron 系统后,按其「定时器 ↔ Agent 协同」思路实现的 host 常驻定时任务引擎——dsh web 服务启动即生效,GUI 页面关闭也照常触发。
新建任务弹窗:项目/会话树 + Agent 预设 + cron 定时(截图数据已脱敏)
它做什么
到点(5 段 cron)通过真实 agent 会话执行你写好的 prompt:
- 指定已有会话 → 每次触发继续该对话,具备上下文连续性(hermes cron 的 continuity 形态)
- 指定项目 workdir → 每次在该项目内新建会话运行(自动加载其 AGENTS.md)
- 两者都留空 → 每次触发在默认工作空间新建会话发起新对话
对话中可直接用 timer_agent 工具管理任务(create / list / update / pause / resume / remove / run);Web GUI 侧边栏「定时任务」面板管理同一批任务——一个台账,三个入口(工具 / WebUI / 文件)。
两种任务类型
- AI Agent 任务(默认):到点驱动真实 agent 会话执行 prompt,消耗 API 额度
- 普通任务(命令):到点直接 spawn 运行你指定的
命令 + 参数(可选工作目录、超时),不经过 AI、不消耗额度;stdout/stderr 尾部(≤16k 字符)与退出码随执行记录入账。适合自包含的脚本(下载、导出、续期等)
[!WARNING]
普通任务会在你的机器上以当前用户权限执行任意命令,没有任何沙箱或白名单。 任何能新建/编辑任务的人(你自己、能调用 timer_agent 工具的 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 播报段,agent 知晓本插件能力与协作方式
- 安全:API 路由仅回环 + 同源可访问(与 dsh-ssh 同防线)
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 | Master switch: ticker + tool + routes. Set false to disable the engine without uninstalling. |
| announceToAgent | boolean | true | Inject a system-prompt section announcing the plugin's capabilities to the agent. |
Tools
timer_agent
Manage the scheduled jobs the host ticker owns (the same rows the web GUI「定时任务」panel renders).
Parameters:
action (string, required): create / list / update / pause / resume / archive / restart / remove / runjob_id (string): job id, required for all actions except create/list (get ids from list; never guess)prompt (string): for create — the full self-contained prompt the scheduled run executes; for update — replacement; for run — transient context for that single fireschedule (string): 5-field cron, e.g. 0 9 * * *; required for createname (string): short human titleworkdir (string): absolute project directory the run's session works in (empty = default workspace)session (string): pin an existing session id — every run continues that conversation
Returns: { kind, job?, jobs?, error? } — summarized job row(s) or a structured error message.
构建
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.1.1-rc.2（dsh.compatibility.dshReleases 精确声明 compatible；其他版本未验证，视为 unknown）
- Node.js：
>=22（engines.node；仓库内测试依赖 Node 22+ 的 type-stripping 能力）
- 系统：开发验证环境为 Windows 10/11；macOS/Linux 未验证
依赖：
- 运行时依赖仅
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.5.0 发布于 commit 88ce4c30f54a257143dd80262cf7044aff431372。
已知限制
- 定时执行依赖
dsh web 服务进程存活(服务停了自然不触发;重启后只跑已顺延到期的任务,错过即跳过)
- 任务运行中到点跳过本次,等下一个 cron 匹配点
- 执行消耗 API 额度;定时执行无人在场,prompt 必须自包含、不可提问
致谢
License
MIT
