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
- 到点触发 → 向设置任务的会话注入提示（
agent.inject()，通知型，不打断工作流）
- 若设置者正在跑子代理 → 提示注入到活跃子代理
- 等待 veto 窗口：任何 agent 仍在 running 就持续延长；全部 idle 后走完
vetoWindowSeconds
- 窗口内无人 veto → 执行
command；有人 veto → 跳过本次（重复型任务重排下一周期）
veto 通道（任一即可）：
timer_veto 工具（主代理/有该工具的代理）- bash 在工作区创建标记文件
.timer-veto-<name>（子代理 toolFilter 白名单场景）
- 全局
vetoDir 下创建 <name> 文件（外部手动）
任务数据含会话归属，默认存于用户家目录（os.homedir() 解析，可通过配置覆盖）；动作命令由使用方自行指定，插件本身不内置任何外部调用。
安全说明 / Security notes
- 插件执行的命令完全由
timer_schedule 的调用方（代理/用户）指定——请只调度你信任的命令
- 默认语义是"无人 veto 则执行"（fail-open 倾向），请为关键动作设置合理的重复周期与宽限
- 数据文件仅本用户可写；发布版本不含任何个人配置或凭据
License
MIT
