LouisHaoL/cloudcli-timer-agent

cloudcli-timer-agent — CloudCLI 定时任务插件

dsh-timer-agent 的 CloudCLI 插件移植版:把「Scheduled Prompt」(cloudcli-cron)换成一个支持真正 5 段 cron 的定时任务板。架构与 cloudcli-cron 同构(manifest.json + tab 客户端 + 常驻 server 进程),域模型与调度语义直接移植自 dsh-timer-agent 的零依赖 core。

它解决什么

Scheduled Prompt 只支持 daily/weekly/monthly 等预设枚举,不支持 cron 表达式;本插件恢复 dsh-timer-agent 的完整能力:

- 5 段 cron(分 时 日 月 周, / /n / a-b / 逗号列表,day+weekday OR 语义)+ 新建/编辑页的预设下拉(每天 09:00 / 每小时 / 每 10 分钟 / 每周一 09:00 / 工作日 09:00 / 月初 10:00)
- 一次性任务:只设执行时间(新建页"一次性"模式,默认当前 +1h),到点执行一次后任务自动归档;成功/失败/手动执行都会消耗这次机会;详情页可手改执行时间
- 两种任务类型:
- AI Agent 任务(默认):到点把 prompt 喂给配置的 CLI({{prompt}} 占位或 stdin 注入),支持每任务覆盖 CLI 命令/参数/超时
- 普通任务(命令):到点直接 spawn 命令 + 参数(不经过 AI、不消耗额度),stdout/stderr 尾部(≤16k 字符)与退出码入账
- 跳过一次:详情页一键跳过下一个触发点,之后照常(一次性任务没有"下一次",不提供)
- 执行历史:每次触发的结果/耗时/输出尾部/错误原因(上限 200 条)
- 收件箱自动派发:inbox: true 的任务进入队列,按 priority+difficulty+等待时长打分,空闲时自动跑最高分;可用 targetProject 指定执行所在目录
- 立即执行 / 暂停 / 恢复 / 归档 / 搜索

[!WARNING]
普通任务会在本机以当前用户权限执行任意命令,没有沙箱或白名单。 台账 ~/.cloudcli-timer-agent/jobs.json 可被篡改即等价于本机任意代码执行;HTTP API 仅监听 127.0.0.1 且无鉴权。只填你审查过的、无人值守安全的命令。

安装

方式一:作为插件市场添加(推荐)
claude plugin marketplace add LouisHaoL/cloudcli-timer-agent
claude plugin install cloudcli-timer-agent

方式二:clone 到 CloudCLI 插件目录后构建
git clone https://github.com/LouisHaoL/cloudcli-timer-agent ~/.claude-code-ui/plugins/cloudcli-plugin-timer-agent
npm install && npm run build

方式三:本目录已构建好,直接拷贝/链接到 ~/.claude-code-ui/plugins/ 即可

插件目录、服务器端路由判定均由此目录加载(~/.claude-code-ui/plugins/);server 的台账则在 ~/.cloudcli-timer-agent/jobs.json(可用环境变量 TIMER_AGENT_HOME 覆盖,冒烟测试即用临时目录)。

重启 CloudCLI,插件页出现「Timer Agent」标签即生效。

调度语义(继承 dsh-timer-agent)

- server 每 30s 一拍;执行完全由持久化的 nextRunAt 驱动,cron/固定间隔只负责计算它;at-most-once:先顺延(一次性任务为消耗)nextRunAt 再触发,崩溃不会重复触发
- 错过即跳过:server 停机期间到点的任务不补跑(重启后仅执行已顺延到期的那一次)
- 一次性任务:nextRunAt 即整个调度;触发一次即消耗,执行结算(成功/失败)后任务归档,手动执行同样消耗;运行中到点不消耗,下一拍重试;nextRunAt 可在详情页/PATCH nextRunAt 手改
- 暂停保留 nextRunAt(不再清空);恢复基于真实上次执行时间(最后一条 execution.startedAt,回退 lastTriggeredAt)重算,错过不补跑,跳到下一个未来时间点(一次性任务恢复后仍按原时刻触发,哪怕已过期——恢复即有意补发)
- 固定间隔锚定上次触发:下次 = 上次触发 + N;停机/暂停/长任务跨过的空窗按整间隔叠加到未来,网格永不漂移到"当前时间";手动执行也算上次触发(下次 = 手动时刻 + N)
- 任务运行中到点 → 跳过本次,等下一个 cron 匹配点(一次性任务保持待发,下一拍重试)
- cron 按本机本地时间解析;归档后恢复:循环任务按真实上次执行重算,一次性任务无事可重算、保持原样

Agent 任务的执行模型

- 执行档 = 任务级 cli 覆盖 → server 默认 profile(~/.cloudcli-timer-agent/profile.json,可用 PUT /v1/profile 写)→ 内置默认(claude --print)
- args 是模板:{{prompt}} / {{workdir}} / {{title}} / {{taskId}} / {{session}} / {{scheduledFor}};没有 {{prompt}} 占位时 prompt 走 stdin
- 续聊(continuity):把 args 模板写成例如 --print --resume {{session}},任务上填 session 字段
- 执行档与 prompt 里的 CLI 一律用绝对路径(插件 server 的 PATH 往往不全,如 D:\env\nodejs\node.exe)
- 默认超时 10 分钟,到点 SIGTERM 记为 cancelled;可按任务/按 profile 覆盖

HTTP API(回环,server 随机端口,宿主经 rpc 代理访问)

| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /health | 健康检查 |
| GET | /v1/jobs | 刷新并返回全部任务 |
| POST | /v1/jobs | 创建任务(runAt = 一次性执行时间,ms epoch 或 ISO;优先级 interval > cron > runAt) |
| PATCH | /v1/jobs/:id | 更新({"skipNext":true} = 跳过一次;{"nextRunAt":…} = 手改下次执行时间,仅固定间隔/一次性) |
| DELETE | /v1/jobs/:id | 删除 |
| POST | /v1/jobs/:id/actions/{pause,resume,run-now,archive,restart} | 操作 |
| GET/PUT | /v1/profile | server 默认 CLI 执行档 |
| GET/PUT | /v1/dispatch | 读取/保存派发策略与队首任务预览 |

独立调试:node dist/server.js,stdout 首行 {"ready":true,"port":N}(cloudcli-cron 同款握手)。注意 host 实例与独立实例共用一份台账,别同时跑两个,避免重复触发。

结构

manifest.json          # CloudCLI 插件清单(slot: tab / entry / server)
src/
├── index.ts           # 客户端入口:mount/unmount(宿主契约)
├── types.ts           # PluginAPI / PluginModule(照 cloudcli-cron 契约)
├── shared/
│   ├── schedule.ts    # 5 段 cron 解析 + nextRunAt(移植自 dsh-timer-agent)
│   ├── jobs.ts        # 任务域模型 + 状态机(移植 + 跳过一次/触发来源)
│   ├── command.ts     # 引号感知参数切分 + 输出截尾(移植)
│   └── scoring.ts     # 收件箱打分(priority+difficulty+等待时长)
├── server.ts          # server 入口:握手 + 30s ticker
├── server/
│   ├── store.ts       # ~/.cloudcli-timer-agent/jobs.json 原子写 + 损坏降级
│   ├── scheduler.ts   # at-most-once 调度 / runRequestedAt 手动通道 / skip-once
│   ├── runner.ts      # spawn 执行(agent 模板/stdin + command),超时/结算
│   ├── dispatch.ts    # 收件箱派发策略持久化 + 队首候选挑选
│   └── http.ts        # 回环 HTTP API
└── client/
├── api.ts         # api.rpc 封装
├── app.ts         # 任务板 UI(列表/新建(cron 预设)/详情(历史/跳过一次))
└── styles.ts      # 内联样式(随主题 dark/light)

与参照实现的关系

| | scheduled-prompt (cloudcli-cron) | 本插件 |
|---|---|---|
| 调度 | 枚举预设(无 cron) | 5 段 cron + 预设下拉生成表达式 |
| 台账 | 每 workspace 一个 JSON | 单一 jobs.json(任务自带 workdir) |
| 执行 | executionProfile spawn CLI | 同款 spawn 模型 + 任务级 CLI 覆盖 / {{session}} 续聊 |
| 防重 | occurrenceKey + 内存去重 | 先顺延 nextRunAt 的 at-most-once(dsh 语义) |
| 跳过 | — | 跳过一次 |
| UI 插件契约 | mount/unmount + rpc 代理 | 相同 |

已知限制

- 任务只在 server 进程存活时触发(宿主开着才拉起 server;错过不补跑)
- 「续聊」依赖目标 CLI 自己的会话管理(--resume 等),插件只透传 {{session}}