dsh-cron-manager

DeepSeek Harness 插件：把 cron 表达式变成模型可查询的确定性问题。解析字段表、生成英文描述、计算下次触发时间戳。

三个工具都是纯函数：不读取系统时钟、不读写 crontab、不起子进程、不联网；解析结果放在一个有上限的内存表（memo）里复用。因此测试完全离线且可重复。

安装

npx -y @deepseek-ai/dsh plugin --profile web add @qingshanjiluo/dsh-cron-manager

工具

工具名	参数	返回
cron_parse	expression	五个字段表（minute / hour / dayOfMonth / month / dayOfWeek，含 raw、kind、all、展开后的 values、text）、description、以及 valid / error
cron_describe	expression	一句英文描述 description 与分句 clauses（时间、日、月）
cron_next	expression、fromMs、可选 n	从参考时刻（epoch 毫秒，不含该时刻）起的下 n 次触发时间：timestampsMs + timestampsIso，附 zone / zoneOffsetMinutes / note

表达式解析为纯计算，非法表达式返回 valid: false + error，不抛异常。

支持的语法

• 5 字段：minute hour day-of-month month day-of-week（不支持前导秒字段）。
• 列表 1,15、区间 9-17、步长 */5、5-20/10、以及 Vixie 的 5/10（即 5-最大/10）。
• ? 等同 *；JAN–DEC、SUN–SAT 名称（大小写不敏感）；星期 7 归一为周日 0。
• 宏：@yearly @annually @monthly @weekly @daily @midnight @hourly（@reboot 明确拒绝，它不是时间表达式）。
• 日/星期同时受限时按标准 cron 的**并集（或）**语义匹配，描述里会写明 “either match fires”。
• 不支持 Quartz 的 L / W / n#d（报错时单独提示，不会与 JUL、WED 混淆）。

配置

配置项	类型	默认值	说明
defaultZone	string	UTC	cron 字段按哪个墙上时间匹配。仅支持固定偏移：UTC / Z / GMT / [+-]HH / [+-]HH:MM / [+-]HHMM；不处理 DST，无法识别时回退 UTC 并在 note 中说明
defaultCount	number	5	cron_next 未传 n 时返回的触发次数
maxCount	number	50	cron_next 的 n 上限，超出会被裁剪并写入 note

cron_next 以 UTC 毫秒/ISO 返回，但字段匹配发生在 defaultZone 的偏移墙上时间；因此参考时刻必须由调用方以 fromMs 显式传入，工具自身从不读时钟。

示例

// cron_parse { "expression": "*/15 9-17 * * 1-5" }
// -> "Every 15 minutes of hours 09, 10, 11, 12, 13, 14, 15, 16 and 17 on Mon, Tue, Wed, Thu and Fri."

// cron_next { "expression": "0 0 * * *", "fromMs": 1704067200000, "n": 2 }
// -> ["2024-01-02T00:00:00.000Z", "2024-01-03T00:00:00.000Z"]

开发与验证

npm install --no-audit --no-fund
npx tsc --noEmit
npm run build          # -> lib/index.js + lib/index.d.ts
npx vitest run         # 离线单元测试
node scripts/load-smoke.mjs   # 加载构建产物并断言注册了 3 个工具

本插件为纯主机工具插件（无浏览器 UI、无设置页）。若某个插件需要访问网络或外部命令（如 crontab、远端调度服务），运行时必须提供对应的外部工具或服务；本仓库的测试全部通过注入参数（fromMs 等）保持离线与确定性。

License

MIT