dsh-timer-agent

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.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

Read the full README on GitHub →