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

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

【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline

本文以 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 漂移）时值得直接套用的模板。

【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline