Cline 定时自动化实战：dependency-check 依赖健康巡检 Cron Spec 全解析

本文以 Cline SDK 官方示例 dependency-check.cron.md（每周依赖健康巡检）为主体，完整拆解这份 Markdown 自动化规范的每个 frontmatter 字段与提示词正文，并结合 @cline/core 中 cron 子系统（解析器、调度器、运行器、报告写入器）的真实源码，说明一个 .cron.md 文件从落盘到被解析、校验、入队、执行、产出报告的完整链路。读完本文，你可以直接复制该模板为自己的项目配置定时依赖巡检，并理解每个配置项在底层是如何生效的。

一、示例规范全文：一份"生产可用"的依赖巡检 Spec

sdk/examples/cron/dependency-check.cron.md 是 Cline Automation Examples 目录下"每周安全巡检"场景的官方模板。其完整内容如下（可直接复制）：

---
id: dependency-check
title: Weekly Dependency Health Check
workspaceRoot: /absolute/path/to/repo
schedule: "0 10 * * MON"
tools: run_commands,read_files
mode: act
enabled: false
modelSelection:
  providerId: cline
  modelId: anthropic/claude-opus-4.7
timeoutSeconds: 1800
maxIterations: 15
tags:
  - automation
  - security
  - dependencies
metadata:
  owner: platform
---
Run a comprehensive dependency health check:

1. Check for outdated packages: `npm outdated` (or yarn/pnpm equivalent)
2. Check for security vulnerabilities: `npm audit`
3. List packages with available major version upgrades
4. Identify unused dependencies (if possible)
5. Check for dependency conflicts or duplicate packages

Provide a summary report covering:
- Critical security vulnerabilities (if any)
- Count of outdated packages by severity (minor, patch, major)
- Recommended immediate actions
- Packages safe to update to latest versions

Focus on actionable insights. Ignore known false positives and dev-only dependencies.

这份规范分为两部分：YAML frontmatter 声明"何时、如何、用哪个模型"执行，Markdown 正文则是发给 Agent 的任务提示词（prompt）。下面逐字段拆解，并对照源码说明每个字段被谁消费、如何校验。

1. 调度相关字段

字段	示例值	说明
id	dependency-check	规范唯一标识（字母数字与连字符），在 解析器 中若省略则回退为文件相对路径（见 cron-spec-parser.ts#L294-L295）
title	Weekly Dependency Health Check	人类可读标题；省略时回退为 id 或文件名主干（cron-spec-parser.ts#L395-L398），并会出现在每次运行报告的标题中
workspaceRoot	/absolute/path/to/repo	必填，目标项目绝对路径，运行时作为工作目录（cwd）。解析器中缺失会直接判定为 invalid（cron-spec-parser.ts#L353-L363），错误信息为 workspaceRoot is required
schedule	"0 10 * * MON"	.cron.md 规范必填，5 段 cron 表达式（分、时、日、月、周），即"每周一上午 10:00"。缺失时报错 schedule is required for *.cron.md specs（cron-spec-parser.ts#L421-L430）
timezone	（本例省略）	可选 IANA 时区（如 America/New_York），缺省使用系统时区。表达式与时区在解析阶段即被校验，见下文调度器小节

一个容易忽略的细节：文件名后缀决定触发类型。cron-spec-parser.ts 中的 inferTriggerKindFromPath（L28-L39）按路径推断：位于 events/ 且以 .event.md 结尾的是事件驱动规范；以 .cron.md 结尾的是周期调度规范；普通 .md 则是"一次性（one-off）"规范。而且 schedule、timezone 是仅 .cron.md 允许的字段（L297-L310），写在事件规范里会解析失败——这从源码层面保证了三类规范（.cron.md / .event.md / 一次性）字段的互斥边界。

2. 执行约束字段

字段	示例值	底层行为
tools	run_commands,read_files	工具白名单。支持逗号分隔字符串或 YAML 数组（normalizeStringList，cron-spec-parser.ts#L99-L120），每个名称必须属于合法工具集合，否则整体报错 unknown tool(s): ...（L124-L132）。运行期转换为工具策略：白名单外的所有工具被禁用，ask_question 因无人值守被强制禁用，详见运行器小节
mode	act	仅允许 act / plan / yolo（normalizeMode，L92-L97），非法值报 mode must be one of: act, plan, yolo。省略时默认 yolo（L401）。act 表示允许执行命令；依赖巡检需要跑 npm outdated / npm audit，所以这里用 act 而非只读的 plan
enabled	false	布尔值，缺省为 true（L411-L414）。示例自带 false，意味着复制模板后若忘记开启，规范永远不会被入队——materializer 只处理 enabled: true 的规范，见下文
modelSelection	{ providerId: cline, modelId: anthropic/claude-opus-4.7 }	覆盖本次运行的模型/供应商。解析器只接受 providerId、modelId 两个字符串键（normalizeModelSelection，L81-L90）
timeoutSeconds	1800	单次运行超时（30 分钟），必须是正数（asPositiveInt，L155-L160）。运行器用 withTimeout 竞速包装整个会话轮次，超时抛 cron run timed out（cron-runner.ts）
maxIterations	15	Agent 最大迭代轮数上限，同样是正整数（L404）
systemPrompt	（本例省略）	可选自定义系统提示词，字符串，空白会被忽略（L402）
tags	automation, security, dependencies	任意分组标签，解析为字符串数组（normalizeTags，L66-L72）
metadata	{ owner: platform }	自由元数据对象，仅接受非数组对象（normalizeRecord，L74-L79），本例用于标记归属团队

frontmatter 之外还有一个隐式约定：正文即 prompt。解析器规定 prompt 必须来自 frontmatter 的 prompt 字段或 Markdown 正文，二者皆空则解析失败（cron-spec-parser.ts#L338-L351）。本示例选择正文承载提示词，这也是 自动化示例 README 推荐的方式——提示词用自然语言写，可读性最好。

3. 提示词正文：五步检查 + 结构化报告

正文部分是这份示例真正的"业务逻辑"，值得逐条对照理解：

检查步骤（交给 Agent 的五项任务）

1. 检查过期包：npm outdated（或 yarn/pnpm 等价命令）；
2. 检查安全漏洞：npm audit；
3. 列出有可用大版本（major）升级的包；
4. 尽可能识别未使用的依赖；
5. 检查依赖冲突或重复包。

报告要求（Agent 产出物）

• 严重安全漏洞（若有）；
• 按严重级别（minor / patch / major）统计的过期包数量；
• 建议的立即处理动作；
• 可安全升级到最新版本的包清单。

最后一句约束值得借鉴：Focus on actionable insights. Ignore known false positives and dev-only dependencies.（聚焦可执行的洞察，忽略已知误报与纯开发依赖）。这是对 LLM 输出的"降噪指令"，避免周报式的噪音报告。配合 tools: run_commands,read_files 的白名单，Agent 被限定只能执行命令和读文件——它能跑 npm outdated/npm audit、读 package.json 做未使用依赖分析，但不能改文件、不能打补丁，巡检天然是只读安全的。

二、调度器如何理解 0 10 * * MON

schedule 字段在解析阶段就会通过 scheduler.ts 中的 validateCronSchedule 严格校验（cron-spec-parser.ts#L431-L443）。从源码结构看，Cline 没有引入第三方 cron 库，而是自实现了一个纯函数解析器：

• parseCronField（scheduler.ts#L1-L76）逐字段展开，支持 *（全量展开）、a-b（区间）、a/step（步进）、a,b,c（列表）四种语法的组合；
• 月份和星期支持英文缩写：MONTH_NAMES/DOW_NAMES（L78-L93），所以 "0 10 * * MON" 中的 MON 会被解析为星期值 1；
• 数值越界、倒序区间、非法步进都会抛出带上下文的错误，如 Invalid cron value "X" for range [min-max]（L18-L20）；
• 5 个字段全部必填，缺字段时报 missing field N（L111-L120）。

校验失败的规范不会让 hub 崩溃——解析器"从不抛异常"，而是返回带 error 的 CronSpecParseResult，由对账器（reconciler）把该文件持久化记录为 parse_status='invalid'（见 cron-spec-parser.ts 顶部注释 L16-L26）。也就是说，改坏了 schedule 表达式只会让这一份规范失效并留痕，不影响其他规范。

timezone 字段允许用 IANA 时区名固定巡检时刻，对跨时区团队尤其有用：不设时区时按宿主系统时区的周一 10:00 触发。

三、从落盘到执行：这份 Spec 的完整运行链路

理解执行链路，才能解释"为什么示例默认 enabled: false"以及"运行结果去哪儿看"。以下全部来自 @cline/core 的 cron 子系统源码：

1. 发现与解析：hub/SDK 启用自动化后，会扫描 cron 规范目录（默认为全局 ~/.cline/cron/，见 cron-report-writer.ts 注释 L14-L19 与 shared storage 的 resolveCronSpecsDir）。每个文件经过 parseCronSpecFile 解析，并计算 frontmatter 与正文的 SHA-256 内容哈希（computeContentHash，cron-spec-parser.ts#L185-L194），用于检测文件变更并驱动重新对账。

2. 物化入队：cron-materializer.ts 是"何时创建运行记录"的唯一决策点。materializeAll()（L35 起）只挑选 triggerKind: "schedule"、enabled: true、parseStatus: "valid" 三类条件同时满足的规范来计算下次运行时间并入队——这就是模板里 enabled: false 的完整语义：文件已就位、已解析，但不会占用任何执行资源。把示例中该行改为 true（或直接删除，因缺省即为 true）即可激活。

3. 轮询与认领：cron-runner.ts 是一个触发源无关的执行器，"每 N 秒轮询 cron.db，原子认领队列中的运行，执行后事务性持久化状态"（文件头部注释 L25-L32）。默认轮询间隔 15 秒、认领租约 90 秒（L34-L35），多个运行器实例可安全共存。

4. 工具策略的落实：buildToolPolicies（cron-runner.ts#L61-L85）精确实现了 tools 白名单语义——若指定了 tools，先以 "*": { enabled: false, autoApprove: true } 全量禁用，再逐个开启白名单内工具；ask_question 被强制禁用，注释写明"定时运行是无人值守的，不能等待人工响应"（L72-L77）；mode: yolo 时额外放开 submit_and_exit。因此 dependency-check 运行时，Agent 唯一可用的工作工具就是 run_commands 和 read_files，且所有调用自动批准、无需交互。

5. 超时与迭代上限：整个会话轮次被 withTimeout（L106-L122）包装，timeoutSeconds: 1800 到期即拒绝并标记失败；maxIterations: 15 约束 Agent 的工具调用轮数，两者共同兜底"依赖检查跑飞"的场景。

6. 报告落盘：每次完成或失败，cron-report-writer.ts 会在 <cron-specs-dir>/reports/<run-id>.md（默认 ~/.cline/cron/reports/）写入 Markdown 报告，含 YAML frontmatter（运行 ID、状态、耗时、token 用量）、执行摘要、工具调用与结果；写入前对用户可控文本做转义（escapeMarkdownInline，L79-L83），防止规范标题里的特殊字符破坏报告结构。数据库仍是操作事实源，报告是可再生的派生产物（注释 L16-L19）。

四、部署步骤与启用自动化

结合 sdk/examples/cron/README.md 的官方指引，在自有项目中启用这份依赖巡检模板：

# 1. 创建规范目录（全局）
mkdir -p ~/.cline/cron

# 2. 复制模板（路径以仓库 sdk/examples/cron/ 为源）
cp sdk/examples/cron/dependency-check.cron.md ~/.cline/cron/

# 3. 编辑规范（必须改）：
#    - workspaceRoot → 你的项目绝对路径
#    - enabled → true（或直接删除该行，缺省即启用）
#    - modelSelection → 你可用的 providerId/modelId
#    - schedule/timezone → 按需调整

然后按集成方式之一开启自动化：

• Hub 中：

new HubWebSocketServer({
  cronOptions: { workspaceRoot: "/absolute/workspace" }
});

• SDK 中：

const cline = await ClineCore.create({
  automation: true,  // Enable automation
  // ... other options
});

规范在启动时对账（reconcile）并自动入队下一次运行，无需手动触发。运行结束后到 ~/.cline/cron/reports/ 查看 dependency-check 的巡检报告：严重漏洞、分级过期统计、建议动作一目了然。

更多上下文可参考 sdk/ARCHITECTURE.md 中 automation 一节的运行时架构说明，以及同目录下的事件驱动示例 plugins/automation-events.ts——若希望把"发现严重漏洞"进一步升级为即时事件响应，可以在巡检报告基础上接入事件规范。

五、实践要点小结

1. 模板默认禁用是刻意设计：enabled: false 让示例可以安全地随仓库分发而不产生运行；复制后第一件事就是将其改为 true。
2. workspaceRoot 是硬性必填：它既是解析校验项，也是运行时的工作目录（cwd），旧字段 cwd 已被移除，使用会直接导致解析失败（cron-spec-parser.ts#L211-L222）。
3. act + 只读工具白名单是安全巡检的正确组合：允许执行 npm 命令，同时通过工具策略杜绝写操作。
4. timeoutSeconds: 1800 与 maxIterations: 15 要按项目规模调整：大型 monorepo 的 npm audit 可能超过 30 分钟，此时应调大超时或改用 pnpm 系工具。
5. 改坏了规范不会拖垮其他规范：解析失败只把单个文件标记为 invalid 并留痕，其余规范照常调度——这是"永不抛异常"解析器设计带来的运维友好性。
6. 提示词正文决定报告质量：示例中"按 severity 分级统计 + 只报可执行建议 + 忽略 dev-only 依赖"的写法，是定制其他巡检类规范（如许可证检查、lockfile 漂移）时值得直接套用的模板。