dsh-timer-agent — DSH 定时任务 × AI Agent 引擎

中文 | English

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

它做什么

到点(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.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 仅做鸭子类型调用，分叉包无影响）

…