前言¶
在 DSH 的插件化使用方式中，定时任务通常有两个具体需求：一是希望按 cron 周期自动执行一段写好的 prompt，而不是每次从页面手动触发；二是执行过程最好落在真实 agent 会话里，保留会话或项目上下文。
dsh-timer-agent 是一个 DSH Web GUI 插件，提供 host 常驻定时任务引擎：dsh web 服务启动即生效，浏览器 GUI 关闭也照常触发。下面介绍它的功能、安装方式和需要注意的限制。
这是什么¶
dsh-timer-agent 由 LouisHaoL 维护，许可证为 MIT。它把 5 段 cron 调度、真实 agent 会话执行、模型工具 timer_agent 和 Web GUI 任务面板放在同一个插件里，用于完成“到点自动执行 prompt，也能到点直接运行命令”的无人值守任务。
核心功能¶
定时调度¶
- 支持 5 段 cron：分、时、日、月、周。
- 支持
*、*/n、a-b、逗号列表。 - 提供 cron 预设下拉：每天 09:00、每小时、每 10 分钟、每周一 09:00。
任务目标¶
- 指定已有会话：每次触发继续该对话，选中会话即钉住该对话。
- 指定项目 workdir：在该项目内新建会话运行。
- 两者都留空：在默认工作空间新建会话发起新对话。
- 目标树选择器按项目分组，可折叠，可选已有会话或新增会话。
管理入口¶
- Web GUI 侧边栏出现「定时任务」入口，任务面板提供列表、搜索过滤、详情页。
- 详情页支持 cron 编辑、执行历史、跳转会话 transcript、立即执行、重置、删除。
- 对话中可通过
timer_agent模型工具管理任务，动作包括create/list/update/pause/resume/archive/restart/remove/run。 - 插件会注册
plugin:timer-agent播报段，向 agent 告知本插件能力与协作方式。
普通命令任务¶
除 AI Agent 任务外，还支持普通任务（命令）：到点直接 spawn 命令+参数，可选工作目录、超时，不经过 AI、不消耗额度。stdout / stderr 尾部（≤16k 字符）与退出码随执行记录入账。
安装与启用¶
先获取插件目录，再使用本机绝对路径安装：
dsh plugin --profile web add link:<本目录绝对路径>
安装后重启 dsh web。侧边栏出现「定时任务」入口即生效。
典型用法¶
创建 AI Agent 定时任务¶
1、在 DSH 对话中调用 timer_agent 工具，使用 create 动作创建任务。
2、填写 5 段 cron，例如：
0 9 * * *
prompt 必须自包含，不能依赖现场提问。
3、选择目标：已有会话、项目 workdir，或两者都留空使用默认工作空间。
4、保存后等待到点触发，也可以在任务详情页使用“立即执行”。
创建普通命令定时任务¶
1、使用 timer_agent 或 Web GUI 新建普通任务（命令）。
2、填写命令+参数，必要时指定工作目录和超时。
3、到点触发后，执行记录会保留 stdout / stderr 尾部（≤16k 字符）和退出码。
适用场景与注意¶
dsh-timer-agent 适合在受控的本机或私有环境中使用。它适合把自包含的 prompt 定时交给 agent 会话执行，也适合定时运行自己审查过的脚本。
使用前请检查源码与许可证。该插件中普通任务会在你的机器上以当前用户权限执行任意命令，没有任何沙箱或白名单。API 路由仅回环 + 同源可访问，但仍需要注意以下限制：
- 任何能新建/编辑任务的人、能调用
timer_agent工具的 agent 会话、能访问回环 API 的本机进程，都可能让任意程序定时运行。 - 任务台账
~/.dsh/timer-agent/jobs.json可被篡改即等价于本机任意代码执行；谨慎使用。 - 不要把该插件暴露给不可信环境。
- 定时执行依赖
dsh web服务进程存活；服务停了不触发，重启后只跑已顺延到期的任务，错过即跳过。 - 任务运行中到点跳过本次，等下一个 cron 匹配点。
- AI Agent 任务执行消耗 API 额度；定时执行无人在场，prompt 必须自包含、不可提问。
结尾¶
dsh-timer-agent 的价值在于把 DSH 的定时执行从页面操作变成 host 常驻引擎，并让 agent 能在对话中直接创建和管理同一批任务。许可证为 MIT。
GitHub 仓库：https://github.com/LouisHaoL/dsh-timer-agent
社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系；本文不附未核实的目录页 URL。
