前言¶
DeepSeek Harness (DSH) 是一个以插件为中心的框架。在开发智能体应用时，经常会遇到需要周期性执行任务或处理定时触发器的场景。cofy-x/dsh-cron 插件解决了这个问题，它是一个为 DSH Automation 提供的持久化日历触发器适配器，能够将一次性或重复的日历事件转化为幂等的会话运行。
它是什么¶
- 名称: cofy-x/dsh-cron
- 分类: 工作流
- 简介: 提供 DSH Automation 的定时任务能力，支持模型调用和 Shell 命令管理，可向 Agent 会话注入后续任务。
- 许可证: MIT
安装与前置要求¶
安装前需要确认环境满足以下条件：
* Node.js 24 或更高版本
* DSH 版本 0.1.5-rc.1 或更高版本（0.1.x 系列）
* dsh-automation 0.2.x
先安装 dsh-automation，再安装本插件。命令如下：
dsh plugin --profile web add dsh-automation@next
dsh plugin --profile web add @cofy-x/dsh-cron
核心功能¶
该插件主要提供以下能力：
- 灵活的调度格式：支持标准的五字段 Cron 表达式、RFC 3339 时间戳以及 IANA 时区，支持夏令时计算。
- 双重管理方式：提供 Shell 命令（如
/cron add）和 Model Tools（如cron_add、cron_update、cron_list、cron_remove）供用户管理任务。 - 持久化与幂等性：每次日历触发都会持久化运行记录，即使进程在提交后崩溃重启，也能根据作业 ID 和时间戳恢复，保证幂等的会话运行。
- 容错策略：采用 “Latest-only catch-up” 策略，错过 recurring 任务的旧时间点不会重播，仅执行最新的到期任务；一次性任务触发后保留历史。
- 浏览器任务中心：通过
dsh.clientmanifest 为浏览器提供任务管理界面。
使用示例¶
通过 Shell 命令创建任务非常直观。以下是一些典型用法：
# 每周一到周五的上午 9 点总结项目状态
/cron add 0 9 * * 1-5 Summarize the project status
# 设置上海时区，每周五下午 6 点 30 分准备周报
/cron add tz=Asia/Shanghai 30 18 * * 5 Prepare the weekly report
# 设置具体的执行时间（RFC 3339 格式）
/cron add-at 2026-09-01T09:00:00+08:00 Run the release checklist
管理任务（暂停、恢复、删除）的命令如下：
/cron pause cron-1
/cron resume cron-1
/cron remove cron-1
配置与限制¶
插件提供了以下配置项（默认值）：
| Key | Default | Meaning |
|---|---|---|
dataDir |
$DSH_HOME/cron |
持久化作业存储和调度器锁目录 |
defaultTimeZone |
host zone | Cron 表达式未指定时使用的时区 |
maxJobs |
64 |
最大活跃作业数 |
minIntervalMinutes |
1 |
最小 recurring 间隔（分钟） |
defaultCwd |
none | 浏览器/API 任务的绝对回退工作目录 |
reconcilePollMs |
1000 |
Automation 事件流轮询间隔 |
maxRunHistory |
100 |
每个作业保留的终端运行历史 |
并发限制方面，每个作业使用 cron:<job-id> 作为并发键，默认限制为 1 个并发作业。最大活跃作业数为 64。
总结¶
cofy-x/dsh-cron 是一个为 DeepSeek Harness 提供可靠定时任务能力的插件。它通过持久化记录和幂等性设计，确保了任务调度的稳定性，适合需要在 Agent 工作流中集成周期性逻辑的场景。
