dsh-timer-task

DeepSeek Harness (dsh) 定时任务插件：让代理自己编排"到点执行某命令"的重复任务，触发前会询问代理是否阻止（veto），代理无法响应时才真正执行。

A DeepSeek Harness (dsh) plugin that lets the agent schedule recurring timer tasks ("run this command when due"). Before a firing executes, the owning session (or its blocking subagent) is prompted and may veto it; only when nobody vetoes does the action run.

功能特性 / Features

• 三个模型可调用工具 / Three model-facing tools:
  • timer_schedule — 设置定时任务，三种生命周期（见下）
  • timer_cancel — 取消任务
  • timer_veto — 阻止本次触发
• 触发前注入询问（主代理或活跃子代理），提示词包含任务目的（description）与本次 veto 的后果
• 动态 veto 窗口：只要有 agent 仍在运行（工作未完成）就自动延长，全部空闲后再走固定宽限
• 执行完成后向设置会话注入结果通知
• 任务持久化到磁盘，dsh 重启不丢

任务生命周期 / Task lifecycles

模式	参数	veto 后	执行成功后
一次性	（默认）	任务结束，不再询问	任务结束
执行即收工（最常用）	untilDone: true	每 interval_minutes 重新询问	任务自动结束
周期循环	repeat: true	每 interval_minutes 重新询问	继续循环，直到 timer_cancel

description 参数用于说明任务目的（如"编译完成后关闭云构建实例"），每次触发都会随提示注入给代理，代理无需自行猜测。

典型场景 / Typical use case

夜间无人值守跑长任务（如编译）时，让代理设置一个"每 30 分钟自动关机"的定时任务：

timer_schedule(name="auto-shutdown",
  command="bash /path/to/your/stop-instances.sh",
  delay_minutes=30, repeat=true)

• 任务还在跑（子代理活跃）→ 触发时子代理收到注入，判断"工作未完成"→ veto → 跳过本次
• 全部工作完成 / 代理停摆（如 API 余额耗尽）→ 无人 veto → 自动执行关机 → 止损

安装 / Install

# 从 GitHub 安装
dsh plugin --profile <name> add github:YOUR_NAME/dsh-timer-task

# 或本地路径
dsh plugin --profile <name> add /path/to/dsh-timer-task

在 profile 的 cordis.patch.yml（或插件自带 patch）中启用 timer-task 条目后重启 dsh。

配置 / Configuration

配置项	默认	说明
vetoWindowSeconds	60	全部 agent 空闲后，无人 veto 的宽限窗口（秒）
checkIntervalSeconds	20	定时器检查周期（秒）
vetoDir	~/.dsh/plugins/dsh-timer-task/veto	全局 veto 标记目录（插件进程可写）
persistFile	~/.dsh/plugins/dsh-timer-task/tasks.json	任务持久化文件

工作原理 / How it works

1. 到点触发 → 向设置任务的会话注入提示（agent.inject()，通知型，不打断工作流）
2. 若设置者正在跑子代理 → 提示注入到活跃子代理
3. 等待 veto 窗口：任何 agent 仍在 running 就持续延长；全部 idle 后走完 vetoWindowSeconds
4. 窗口内无人 veto → 执行 command；有人 veto → 跳过本次（重复型任务重排下一周期）

veto 通道（任一即可）：

• timer_veto 工具（主代理/有该工具的代理）
• bash 在工作区创建标记文件 .timer-veto-<name>（子代理 toolFilter 白名单场景）
• 全局 vetoDir 下创建 <name> 文件（外部手动）

任务数据含会话归属，默认存于用户家目录（os.homedir() 解析，可通过配置覆盖）；动作命令由使用方自行指定，插件本身不内置任何外部调用。

安全说明 / Security notes

• 插件执行的命令完全由 timer_schedule 的调用方（代理/用户）指定——请只调度你信任的命令
• 默认语义是"无人 veto 则执行"（fail-open 倾向），请为关键动作设置合理的重复周期与宽限
• 数据文件仅本用户可写；发布版本不含任何个人配置或凭据

License

MIT