Cline 定时代码审查自动化：daily-code-review Cron 规格深度解析与执行原理

2026-09-06 16:02:31作者：乔或婵

本文以 Cline SDK 仓库中的自动化规格示例 daily-code-review.cron.md 为主体，逐字段剖析这份"工作日早 9 点自动审查 Pull Request"的生产级定时任务配置是如何定义、校验并执行的；并结合 @cline/core 的规格解析器、cron 调度器与运行报告写入器的源码，还原从 .cron.md 文件落盘到报告产出 .md 的完整链路。读完后你可以直接照抄该规格模板搭建自己的定时自动化，并理解每个 frontmatter 字段在引擎内部的真实作用。

完整规格文件：一份可直接复制的定时代码审查定义

该示例文件是一份标准的"Markdown + YAML frontmatter"规格：frontmatter 描述"何时跑、用什么模型跑、能用哪些工具"，正文即提交给 Agent 的提示词（prompt）。完整内容如下（来自仓库原文件）：

---
id: daily-code-review
title: Daily Code Review
workspaceRoot: /absolute/path/to/repo
schedule: "0 9 * * MON-FRI"
tools: run_commands,read_files
mode: act
enabled: true
modelSelection:
  providerId: cline
  modelId: anthropic/claude-opus-4.7
timeoutSeconds: 1800
systemPrompt: You are a precise automation agent that reports only actionable review findings.
maxIterations: 20
tags:
  - automation
  - review
metadata:
  owner: platform
notesDirectory: /absolute/path/to/notes
extensions:
  - rules
  - skills
  - plugins
source: user
---
Review the open pull requests, identify the highest-risk changes, run the
relevant checks if needed, and write a concise summary of findings.

在规格示例目录的 README 中，该示例被定位为"production-ready example"（生产级参考模板），是十来个定时/事件示例中唯一被完整拆解的规格，其关键字段即上文所列的 schedule、tools、mode、timeoutSeconds、modelSelection 与 notesDirectory。下面逐字段结合源码说明它们的含义与校验规则。

身份与目录字段

id: daily-code-review：规格的稳定外部标识。从 cron-spec-parser.ts 可见，若未写 id，解析器会回退为规格文件相对路径作为 externalId；title 同理可回退到文件名字干。
workspaceRoot: /absolute/path/to/repo：必填。解析器对缺失 workspaceRoot 的文件会直接判定为无效并记录错误（见 parseCronSpecFile）。它决定了自动化运行时的工作目录——源码注释明确指出旧字段 cwd 已移除，"cron specs use workspaceRoot as cwd"（字段校验逻辑）。
notesDirectory: /absolute/path/to/notes：持久化笔记目录，用于跨多次运行保存中间状态（多次运行之间共享记忆），README 将其描述为"Durable automation notes for multi-run state"。
source: user：规格来源标记，缺省即 user（解析器默认值，common 字段组装处）。运行报告写入器会用 source === "hub-schedule" 区分"数据库中由 schedule 工具创建的虚拟规格"与"磁盘上的文件规格"（见 cron-report-writer.ts）。
enabled: true：开关字段，缺省为 true；置为 false 后该规格不再被物化入队（materializer 的过滤条件只挑选 enabled: true 且解析有效的规格）。
tags 与 metadata：任意分组标签与自定义元数据（如本例的 owner: platform），仅用于组织与管理。

调度字段：schedule 与 MON-FRI 的解析原理

schedule: "0 9 * * MON-FRI" 表示工作日（周一至周五）每天 9 点整触发。Cline 对 cron 表达式的处理在 scheduler.ts 中实现，几个关键点：

严格 5 段：minute hour day month day-of-week，缺少字段或超范围会抛错（parseCron），例如分钟 0–59、小时 0–23、日 1–31、周 0–6。
支持英文名称：月份支持 jan–dec，星期支持 sun–sat（大小写不敏感），这正是 MON-FRI 这种星期区间写法能生效的原因（DOW_NAMES 与名称解析）；同时也支持 */5、1-5、N/M 步进等常见写法。
时区可选：frontmatter 还可加 timezone（IANA 时区名，如 America/New_York），缺省用系统时区。带时区时引擎用 Intl.DateTimeFormat 做分钟级扫描计算下一次触发点（getNextCronTimeByMinuteScan）。
规格校验时机：schedule 只在 *.cron.md 规格中合法。解析器在解析阶段就调用 validateCronSchedule 试算下一次触发时间——如果 4 年内算不出任何触发点，整个规格会被判定为无效，而不是等到运行时才失败。

另外注意字段边界约束：schedule/timezone 出现在事件类规格中、或 event/filters/debounceSeconds 等字段出现在 .cron.md 中，解析器都会拒绝（SCHEDULE_ONLY_FIELDS / EVENT_ONLY_FIELDS 检查），并给出形如 field "schedule" is only allowed on *.cron.md specs 的明确错误。

能力与行为控制：tools、mode、maxIterations、timeoutSeconds

tools: run_commands,read_files：把本次自动化的能力限制在"执行命令 + 读文件"两项——对代码审查场景足够，又避免自动化持有编辑/写补丁等更高危能力。两个实现细节值得注意：
- 逗号分隔字符串与 YAML 数组两种写法都支持（normalizeStringList 会把字符串按逗号拆分并去重）；
- 工具名必须落在引擎的默认工具名集合内，否则解析报错 unknown tool(s): ...（normalizeToolList）。
- 空列表则禁用一切工作类工具（README 字段表说明）。
mode: act：本例取 act（执行命令）。解析器允许的取值是 act / plan / yolo，缺省为 yolo（normalizeMode 与默认值）。plan 用于只分析不动手的任务（如同目录的 type-check-strict.cron.md），act 则允许实际执行，是本审查任务"run the relevant checks if needed"的前提。
maxIterations: 20：单轮运行的迭代上限，防止任务失控地无限调用工具。
timeoutSeconds: 1800：30 分钟硬超时。两者都要求是正整数，解析器用 asPositiveInt 过滤，非法值会被静默忽略（common 字段组装），因此建议写正整数。

模型与提示词：modelSelection、systemPrompt、正文 prompt

modelSelection 支持 providerId + modelId 两个子字段，为这一次运行覆盖全局默认模型。本例指定 Cline 平台上的 anthropic/claude-opus-4.7，意味着每天早上的审查固定用同一档模型，结果可预期、成本可控。解析器要求至少提供其中一个字段，否则该字段整体被丢弃（normalizeModelSelection）。
systemPrompt：叠加在默认系统提示之上的自定义指令。本例写明"You are a precise automation agent that reports only actionable review findings."，把输出约束为"只报可执行的发现"，减少噪声。
正文即 prompt：frontmatter 之后的 Markdown 正文（可省略 frontmatter 里的 prompt 字段）就是发给 Agent 的任务指令。本例正文只有两行——审查开放的 PR、找出最高风险改动、必要时运行相关检查、输出简明摘要。解析规则见 prompt 回退逻辑：优先取 frontmatter 的 prompt，否则取非空的正文；两者都没有则规格无效。

扩展能力：extensions

extensions: [rules, skills, plugins] 声明本次运行加载哪几类项目扩展。合法取值只有 rules、skills、plugins 三种（CRON_EXTENSION_KINDS），出现其他值会解析报错。三者全开意味着该自动化会继承仓库 .cline 下的自定义规则、技能与插件——对代码审查来说，规则文件里沉淀的团队审查标准会在每次运行中自动生效。

解析与调度：这份规格在引擎内部如何流转

理解规格字段后，再看它们在 @cline/core 中的真实生命周期，能解释几个常见疑问。

解析器：从不抛异常，坏文件也会被"记住"

parseCronSpecFile 的设计原则是"永不因单个坏文件抛错"：任何解析失败（YAML 语法错误、缺 workspaceRoot、非法 mode、cron 表达式无法计算触发点等）都会返回带 error 信息的 CronSpecParseResult，由协调器（reconciler）把 parse_status='invalid' 持久化下来，而不是静默丢弃。文件类型由路径推断：*.cron.md → 定时（schedule），events/*.event.md → 事件（event），其余 .md → 一次性（one_off）（inferTriggerKindFromPath）。

每次解析还会计算 contentHash——对 frontmatter 做按键排序的规范化 JSON 加正文取 sha256（computeContentHash），用于识别"规格是否被修改过"，从而驱动版本（revision）更新。

到点触发与追补策略

规格被持久化后，CronMaterializer 负责把"到期的规格"转化为运行队列中的一条 run 记录。对定时规格它实现的是"启动时最多补跑一次过期任务，然后推进"的策略（源码注释称 one overdue catch-up on startup, then advance）：如果 hub 进程在 9 点没开、10 点才启动，会补跑一次昨晚错过的审查，而不是把整周积压全部重放。单个过期/损坏的规格也不会阻塞其他规格入队（materializeAll 的容错循环）。

运行报告：每次执行落盘为 Markdown

每次完成或失败的运行都会写一份报告到 <cron-specs-dir>/reports/<run-id>.md，默认即 ~/.cline/cron/reports/<run-id>.md（writeCronRunReport）。报告结构由源码可精确确认：

YAML frontmatter：runId、specId、scheduleId、title、triggerKind、status、definitionSource，可选 sourcePath、workspaceRoot、schedule、timezone、model（providerId/modelId 拼接）、sessionId、startedAt/completedAt（buildFrontmatter）；
Job 段落：定义来源、工作区、调度、模型、会话，并附完整 Prompt 代码块；
Summary 段落：Agent 最终输出（即本次审查发现）；
Usage 段落：输入/输出/缓存 token、总成本、耗时（buildBody）；
Tool Calls 段落：逐条列出工具调用名、耗时与错误。

也就是说，"daily-code-review 昨天发现了什么、花了多少钱、调了哪些命令"都能在对应报告里查到，且源码注释明确数据库（cron.db）仍是操作事实源，报告是派生产物。

部署与启用：让 daily-code-review 真正跑起来

方式一：文件式规格（本例的标准用法）

按示例目录 README 给出的步骤：

mkdir -p ~/.cline/cron
cp sdk/examples/cron/daily-code-review.cron.md ~/.cline/cron/
# 编辑规格：把 workspaceRoot 指向你的仓库绝对路径、按需调整 modelSelection 等
# 规格在启动时被 reconcile，下一次运行时间自动入队

启用自动化有三条入口（README "Enable automation" 一节）：

Hub：new HubWebSocketServer({ cronOptions: { workspaceRoot: "/absolute/workspace" } })
SDK：ClineCore.create({ automation: true, ... })
CLI：cline --enable-automation

需要修正的两个示例占位：workspaceRoot 与 notesDirectory 中的 /absolute/path/to/repo、/absolute/path/to/notes 是占位路径，必须改成真实绝对路径，否则语义上不成立（workspaceRoot 是必填硬校验字段）。

此外 README 还说明了一次性任务（one-off）的写法：保存为 .cline/cron/<name>.md（不带 .cron 中缀）并省略 schedule 字段，适合"只跑一次"的临时审查。

方式二：CLI schedule 向导（不落文件，存数据库）

如果不想维护 Markdown 文件，Cline CLI 提供等价的交互/命令行方式创建调度（详见 scheduling 文档），例如：

cline schedule create "Daily Code Review" \
  --cron "0 9 * * MON-FRI" \
  --prompt "Review the open pull requests, identify the highest-risk changes, and write a concise summary of findings" \
  --workspace /path/to/repo \
  --model anthropic/claude-opus-4.7

此类由 hub 管理的调度以虚拟来源路径 hub/schedules/<id>.cron.md 记录在 cron.db 中（报告写入器源码中有对应区分逻辑），用 cline schedule list / trigger / pause / resume / delete / executions 管理，而不是编辑文件。适用前提需注意：官方文档声明该调度能力当前仅适用于 Cline SDK、CLI 与 Kanban，暂不适用于 VSCode/JetBrains 扩展。

小结与扩展参考

这份 daily-code-review.cron.md 展示了 Cline 自动化规格的完整形态：cron 表达式 + 星期名称区间、工具白名单、act 模式、30 分钟超时、20 次迭代上限、按运行覆盖模型、加载 rules/skills/plugins 扩展、持久笔记目录；
字段合法性由 cron-spec-parser 在解析期全量校验，调度合法性由 scheduler 保证（含 IANA 时区），到期与补跑由 cron-materializer 执行，结果以 Markdown 报告落盘（cron-report-writer）；
同目录还有 changelog-generator、dependency-check、test-coverage-report、type-check-strict 等十余个可组合的定时模板，以及事件驱动示例（github.pull_request.opened 触发），可按示例 README 的字段参考表自行裁剪；
更上层的概念介绍见 Scheduled Agents 指南与 CLI Scheduling 文档。