Cline 定时自动化实战：documentation-check 文档覆盖率审计 Cron 规格深度解析

在 Cline 的自动化体系中，documentation-check.cron.md 是一个按周调度运行的"文档覆盖率审计"规格（spec）：它让 Agent 每周四凌晨自动扫描代码库的公共 API 文档、JSDoc 注释与 README 结构，以 plan 模式产出一份只含建议、不做修改的审计报告。读完本文，你将完整掌握该规格每个 YAML 字段的语义与校验规则、审计提示词的四步工作方法，以及 Cline 从磁盘扫描、规格解析、排队执行到落盘报告的完整实现链路，可以直接把它改造成自己项目的文档治理定时任务。

一、它是什么：一个定时触发的只读审计任务

sdk/examples/cron/ 目录下汇集了 Cline 的两类自动化模板：

• Recurring specs（.cron.md）——按 cron 表达式定时运行，documentation-check 即属此类；
• Event-driven specs（.event.md）——由事件（如 PR 打开）触发。

按文件名约定，解析器会推断触发类型：*.cron.md → schedule，events/*.event.md → event，其余 .md → one_off（一次性任务）。这一逻辑实现在 cron-spec-parser.ts 的 inferTriggerKindFromPath 中，对应的类型定义在 cron-spec-types.ts 的 CronScheduleSpec 接口里：调度类规格比普通规格多出 schedule（必填）与 timezone（可选，IANA 时区，缺省用系统时区）两个字段。

在 Cline 官方给出的"完整开发自动化套件"编排中（见 README 的 Practical Automation Workflows 一节），documentation-check 被安排在每周固定时段与 dependency-check、dead-code-finder、code-style-audit 等规格组合运行，形成无人值守的持续质量监控，而不需要开发者记得手动跑检查。

二、规格文件逐字段解读

以下是该规格的完整 frontmatter（摘自 documentation-check.cron.md）：

---
id: documentation-check
title: Documentation Coverage Audit
workspaceRoot: /absolute/path/to/repo
schedule: "0 5 * * THU"
tools: run_commands,read_files,search_codebase
mode: plan
enabled: false
modelSelection:
  providerId: cline
  modelId: anthropic/claude-opus-4.7
timeoutSeconds: 1800
maxIterations: 25
tags:
  - automation
  - documentation
  - quality
metadata:
  owner: documentation
  checkAreas:
    - publicAPIs
    - complexFunctions
    - typeDefinitions
    - modules
---

结合源码中的解析与校验逻辑，各字段的准确含义如下：

字段	本规格取值	语义与源码依据
id	documentation-check	规格的唯一标识。缺省时解析器会回退为文件相对路径（externalId 逻辑）
title	Documentation Coverage Audit	人类可读标题；缺省依次回退到 id 或文件名主干
workspaceRoot	/absolute/path/to/repo	必填。项目绝对路径，审计时 Agent 的工作目录。解析器对缺失会直接判为无效：workspaceRoot is required。注意旧字段 cwd 已被移除，写了会报 no longer supported; cron specs use workspaceRoot as cwd
schedule	"0 5 * * THU"	每周五点前的周四 05:00 运行。标准 5 段 cron 表达式（分 时 日 月 周）；scheduler.ts 的 validateCronSchedule 会在解析期做严格校验，字段数不对会抛 expected 5 fields 错误，规格被标记为 invalid 而非静默丢弃
tools	run_commands,read_files,search_codebase	工具白名单。解析器按逗号切分并去重，且每个名字必须属于内置默认工具集，否则报 unknown tool(s)。留空数组则禁用一切工作工具（见 README Field Reference）
mode	plan	只允许 act / plan / yolo 三种取值；不写时默认为 yolo。本规格取 plan，即"只提建议、不落改动"
enabled	false	布尔值。不写时默认为 true；这里显式关闭，说明模板默认处于停用状态，复制后需改为 true 才会真正生效
modelSelection	cline / claude-opus-4.7	为本次运行覆盖默认的 provider 与模型。解析器要求对象结构，providerId 与 modelId 至少写一项，否则该项视为未设置
timeoutSeconds	1800	单次运行超时 30 分钟。解析为正整数（asPositiveInt），非法值被忽略；运行器内部用 Promise.race 实现超时打断
maxIterations	25	Agent 最大迭代轮数，防止审计任务无限循环。同样是正整数约束
tags	automation / documentation / quality	任意字符串数组，用于分组归类
metadata	owner、checkAreas	自由结构的自定义元数据。checkAreas 列出本次审计聚焦的四个领域：公共 API、复杂函数、类型定义、模块

一个容易忽略的细节：解析器还做字段归属校验——schedule、timezone 只允许出现在 *.cron.md 里，event、filters、debounceSeconds 等只允许出现在 .event.md 里，写错文件类型会直接判为无效规格。因此本规格的 schedule 字段与 .cron.md 后缀是严格配套的。

此外，解析结果会计算 contentHash（frontmatter 归一化 JSON + 正文的 sha256，见 computeContentHash）。从源码结构看，该哈希用于后续对比规格是否发生变更，是"改文件即生效"机制的基础。

三、审计提示词：四步检查法与报告结构

frontmatter 之后的 Markdown 正文就是交给 Agent 的提示词（prompt 字段缺省时取正文），本规格定义了一套结构化的文档审计流程：

第 1 步——公共 API 文档检查，覆盖：

• 公共模块导出的函数
• 类与接口
• 类型定义与泛型
• 装饰器与注解

第 2 步——识别缺失文档，聚焦四类缺口：

• 没有 JSDoc 注释的公共函数
• 缺少解释的复杂函数
• 没有描述文本的公共类型
• 没有 README 或头注释的导出模块

第 3 步——评估现有文档质量，不只查"有没有"，还查"好不好"：

• JSDoc 缺少 @param / @return 标签
• 与代码实际行为脱节、过时的注释
• 文档中可能已失效的代码示例
• 指向已删除代码的文档链接

第 4 步——分析文档结构，审视项目级文档资产：主 README 的质量与完整度、架构文档、Contributing 指南是否存在、API 参考文档、Changelog 维护情况。

执行完成后，规格要求生成一份带固定章节的审计报告：

• 按模块统计的文档覆盖率
• 未文档化的 Top 10 公共 API
• 缺少描述的类型清单
• 含复杂逻辑、需要解释的文件
• 过时文档实例清单

以及四条改进建议维度：高优先级项（无文档的公共 API）、文档风格改进点、JSDoc 模板建议、需要更新的链接。最后一句 Use plan mode to suggest improvements without applying changes 与 frontmatter 的 mode: plan 相互呼应，双重强调"只审计、不修改"。

四、底层执行链路：规格如何变成一次审计运行

理解规格被加载和执行的完整路径，有助于判断任务出问题时该查哪里。

1. 启动对账（Reconcile）。 cron-reconciler.ts 在启动时扫描规格目录（默认为全局 ~/.cline/cron/），逐个解析 Markdown 文件并 upsert 进 SQLite 存储（cron.db）。文件监听器（watcher）的事件只是触发单个文件重新对账，数据库才是运行时的操作真相源；扫描时会显式跳过 reports/ 子目录，避免把生成的报告当成规格。

2. 解析与容错。 cron-spec-parser.ts 对单个文件"永不抛异常"：坏文件会产出带 error 消息的解析结果，让存储层把 parse_status='invalid' 持久化下来，而不是静默丢状态。YAML frontmatter 解析失败、workspaceRoot 缺失、cron 表达式非法等都会走这条通道，因此一个写错的规格不会拖垮其他任务的调度。

3. 运行与工具策略。 cron-runner.ts 轮询 cron.db（默认 15 秒间隔）、原子领取排队任务，并按规格的 tools 字段构建工具策略（buildToolPolicies）：

• 若规格未写 tools，则所有工具启用并自动批准；
• 若写了白名单（本规格即此类），则先禁用全部工具，再逐个启用列出的三个，其余工具一律不可用——审计任务因此被严格限制在"跑命令、读文件、搜代码"的能力圈内，没有编辑工具，从机制上保证了它改不了你的代码；
• 无论何种配置，ask_question 工具都被强制禁用，因为定时运行是无头（headless）场景，不可能等待人工应答；
• submit_and_exit 仅在 yolo 模式下启用，plan 模式下同样不可用。

超时则由 timeoutSeconds 经 withTimeout 包装实现，到点即判定失败。

4. 报告落盘。 每次完成或失败，cron-report-writer.ts 都会写出 .cline/cron/reports/<run-id>.md，内容包括：

• YAML frontmatter：runId、specId、状态、触发方式、起止时间、模型、会话 ID 等；
• 任务摘要：定义来源、workspaceRoot、schedule 表达式、模型与 Prompt 原文；
• 正文：触发事件上下文（事件类规格）、失败错误、最终总结（审计结论）、token 用量与成本、逐条工具调用及耗时。

也就是说，每周四凌晨跑完的审计结论，最终会以一份带完整运行元数据的 Markdown 报告形式沉淀下来，可被人工审阅、归档或喂给下一次改进。

五、把它跑起来：从模板到生效的完整步骤

按 README 给出的流程，启用这个文档审计任务需要四步：

mkdir -p ~/.cline/cron
cp sdk/examples/cron/documentation-check.cron.md ~/.cline/cron/

然后编辑 ~/.cline/cron/documentation-check.cron.md：

1. 把 workspaceRoot 改为你的项目绝对路径；
2. 把 enabled: false 改为 enabled: true（模板默认停用）；
3. 按需调整 modelSelection、schedule、timeoutSeconds、maxIterations 和 tools；
4. 保留或细化正文中的审计步骤，使其贴合你的技术栈（例如把"JSDoc"换成你项目的实际注释规范）。

规格启用自动化有三种入口：

• Hub：构造 HubWebSocketServer 时传入 cronOptions: { workspaceRoot: "..." }；
• SDK：ClineCore.create({ automation: true, ... })；
• CLI：cline --enable-automation。

启动后规格即被对账入队，下一次运行时间自动排定——周四 05:00 到点后无需人工干预，运行结果自动写入 ~/.cline/cron/reports/。如果只想先验证一次、不想等调度，也可以按 README 的说明把文件另存为不带 .cron 中缀的 .cline/cron/<name>.md 并去掉 schedule 字段，变成一次性（one_off）规格执行。

六、使用注意与可改造点

结合解析器的校验规则，使用该模板时有几个实践要点：

• 默认是停用的。enabled: false 是模板的刻意设计，避免复制后未经修改就以别人的 workspaceRoot 跑任务；不写 enabled 时默认为 true，两者行为不同；
• plan 模式 + 三工具白名单是安全组合。审计任务不碰写工具、不能提问、不能 submit_and_exit，即使提示词被模型自由发挥也无法产生副作用；若你希望它"边审计边补文档"，应把 mode 改为 act 并在 tools 中加入 editor 或 apply_patch，但建议先用只读版本观察几轮报告质量；
• metadata.checkAreas 是提示词与元数据的双通道。它既供人阅读分组，也可在定制提示词时与四步检查法互相引用，扩展审计范围（如"文档 i18n 一致性"）时保持结构一致；
• 修改文件即生效。reconciler 基于内容哈希感知规格变化，调整 schedule 或提示词后无需重启逻辑以外的额外操作（启动对账与文件监听两条通道共同保证状态同步）；
• 配合完整套件使用。documentation-check 与 dead-code-finder.cron.md、code-style-audit.cron.md、type-check-strict.cron.md 等规格可在同一套 cron 体系中错峰编排，形成覆盖文档、风格、类型、依赖与性能的完整质量巡检。

整套自动化架构（事件信封、运行时流程）的更多细节可进一步参考 sdk/ARCHITECTURE.md 与 sdk/examples/cron/README.md 的字段参考表。