Cline 定时自动化实战：用 code-style-audit.cron.md 搭建每周代码风格与 Lint 巡检

本文以 Cline 仓库中的现成自动化规格文件 code-style-audit.cron.md 为主体，完整拆解这份「代码风格与 Lint 审计」cron spec 的每一个 YAML 字段、Prompt 正文与执行边界，并结合 cron-spec-parser.ts、cron-runner.ts 等源码，说明 Cline 是如何把这样一个 Markdown 文件解析为计划任务、按白名单限制工具、在无头环境下执行并产出可归档的审计报告，最终帮助读者在自己的项目中复刻一套可运行的周期性代码质量巡检。

一、这个 spec 是干什么的

在 Cline 的自动化体系中，code-style-audit 是一个「周期性规格」（recurring spec），文件以 .cron.md 结尾，表示按 cron 表达式定时触发（同目录下还有 dead-code-finder、type-check-strict 等姊妹任务，完整清单见 cron/README.md）。它的设计目标是：每周三凌晨 3 点自动执行一轮 ESLint / Prettier 检查，找出未使用变量、死代码、遗留 TODO/FIXME、生产代码中的 console.log、无解释的魔法数字等常见问题，并生成一份包含违规统计、趋势对比和分级建议的 Markdown 报告。

示例索引中对该任务的定位是：

Goal	Spec	Schedule	Mode
Audit style	code-style-audit	Wednesday 3 AM	act

也就是说，0 3 * * WED（每周三 03:00）与 mode: act（允许实际执行命令）是该 spec 的两个核心运行特征。

二、完整 spec 逐字段解析

下面先给出原文档的完整内容，再逐字段说明其含义与源码中的默认值：

---
id: code-style-audit
title: Code Style and Linting Audit
workspaceRoot: /absolute/path/to/repo
schedule: "0 3 * * WED"
tools: run_commands,read_files
mode: act
enabled: false
modelSelection:
  providerId: cline
  modelId: anthropic/claude-opus-4.7
timeoutSeconds: 1800
maxIterations: 20
tags:
  - automation
  - quality
  - style
metadata:
  owner: development
  reportFormat: markdown
---
Run comprehensive code style and linting checks:

1. Run ESLint: `npm run lint` or `eslint .`
2. Run Prettier check: `prettier --check .` or equivalent
3. Check for common issues:
   - Unused variables or imports
   - Dead code
   - TODO/FIXME comments left in main branch
   - Console.log statements in production code
   - Magic numbers without explanation

Generate a report showing:
- Linting violations by rule (top 10)
- Files with most violations
- Formatting inconsistencies
- Pattern analysis (e.g., common TODO reasons, unused import patterns)

Provide statistics:
- Total violations found
- Fixable vs non-fixable violations
- Trend compared to previous week (if data exists)

Recommendations:
- Quick wins: violations that can be auto-fixed
- Standards improvements: patterns to establish
- Review-needed: complex issues requiring human judgment

2.1 身份与调度字段

字段	本 spec 取值	作用
id	code-style-audit	规格唯一标识，限字母数字与连字符；缺省时解析器会以文件相对路径兜底（见 cron-spec-parser.ts）
title	Code Style and Linting Audit	人类可读标题，用于报告与 UI 展示
workspaceRoot	/absolute/path/to/repo	必填：任务运行的项目绝对路径；解析器在缺失时会直接报错 workspaceRoot is required（cron-spec-parser.ts）。注意旧字段 cwd 已被移除，若再写 cwd 会被判为 invalid spec
schedule	"0 3 * * WED"	5 段 cron 表达式，.cron.md 规格必填；validateCronSchedule 会在解析阶段校验（cron-spec-parser.ts）
enabled	false	示例默认禁用，避免拷贝即运行；解析器中该字段缺省为 true

关于 schedule 的取值范围，可以直接从调度器源码确认：scheduler.ts 中 parseCron 强制要求恰好 5 段，依次为分钟（0–59）、小时（0–23）、日（1–31）、月（1–12，支持 jan–dec 缩写）、星期（支持 sun–sat 缩写），支持 *、逗号列表、- 区间和 / 步进。因此 "0 3 * * WED" 即「每周三凌晨 3 点整」。可选的 timezone 字段（IANA 时区名，如 America/New_York）在本 spec 中未设置，默认使用系统时区——跨时区团队部署时建议显式声明。

2.2 执行边界字段

字段	本 spec 取值	作用与源码依据
tools	run_commands,read_files	工具白名单，逗号分隔。源码会校验每个名字必须在默认工具集中，未知名字直接使 spec 失效（cron-spec-parser.ts）。白名单语义见下文第三节
mode	act	取值只能是 act / plan / yolo，缺省为 yolo（[cron-spec-parser.ts](https://gitcode.com/GitHub_Trending/cl/cline/blob/be59305d7a632759e163012eeecddda59bc02cfe/sdk/packages/core/src/cron/specs/cron-spec-parser.ts?utm_source=gitcode_repo_files#L381-L391, L401)）。act 表示允许执行命令但受确认策略约束，plan 只做分析不改动，yolo 全放开
modelSelection	{ providerId: cline, modelId: anthropic/claude-opus-4.7 }	为本次运行覆盖默认模型/提供商，解析为 { providerId, modelId } 对象（cron-spec-parser.ts）
timeoutSeconds	1800	单次运行 30 分钟超时，必须是正整数，否则被忽略（cron-spec-parser.ts）。对全仓库 lint 这类重任务足够宽裕
maxIterations	20	智能体迭代次数上限，防止无界循环消耗 token
tags	automation, quality, style	任意分组标签，便于按标签筛选规格
metadata	{ owner: development, reportFormat: markdown }	自由元数据对象，不进运行时逻辑，供团队自记（如报告格式约定）

Prompt 的载体也值得注意：解析器优先取 frontmatter 中的 prompt 字段，没有则取 Markdown 正文（cron-spec-parser.ts）。本 spec 使用正文作为指令，这正是 cron spec 的典型写法——frontmatter 管「怎么跑」，正文管「跑什么」。

三、Prompt 正文：审计清单与报告规范

正文（即第三节标题下的内容）定义了这次自动运行的全部工作契约，可以拆成三段：

1. 检查步骤

• 运行 ESLint：npm run lint 或 eslint .
• 运行 Prettier 检查：prettier --check . 或等价命令
• 人工可读层排查五类常见问题：未使用变量/导入、死代码、主分支遗留的 TODO/FIXME、生产代码中的 console.log、无解释的魔法数字

2. 报告必须包含的内容

• 按规则聚合的 Top 10 lint 违规
• 违规最多的文件
• 格式不一致项
• 模式分析（如 TODO 的常见成因、未使用导入的分布模式）

3. 统计与分级建议

• 总违规数、可自动修复 vs 不可自动修复、与上一周的环比趋势（有数据时）
• 三档建议：Quick wins（可自动修复）、Standards improvements（应固化为团队规范的模式）、Review-needed（需要人工判断的复杂问题）

这套「检查 → 报告 → 统计 → 分级建议」的 Prompt 结构是该目录多份 spec 共用的模板：模型跑完工具调用后，把 finalText 与工具调用记录一并写入运行报告（见第五节），所以 Prompt 对输出结构的约束直接决定了 .cline/cron/reports/ 里那份归档报告的可读性。

四、白名单语义：tools 如何限制这次运行

tools: run_commands,read_files 的运行时含义在 cron-runner.ts 的 buildToolPolicies 中可以完整验证：

• 若 spec 未声明 tools，策略为 { "*": { autoApprove: true } }——所有工具默认可用且自动批准；
• 若声明了 tools（如本 spec），策略先设为「全部禁用」，再逐项将白名单内工具置为 enabled: true, autoApprove: true；
• 由于定时运行是无头（headless）的，无法等待人工回答，ask_question 工具会被强制禁用；
• 仅 mode: yolo 时额外放开 submit_and_exit。

对本 spec 而言，这意味着智能体只能执行 shell 命令（跑 lint）和读文件（收集结果），不能改文件、不能发问——与「审计只读」的定位精确匹配。如果你希望让它在周三顺手把可自动修复的违规直接修掉，需要把 apply_patch / editor 加入 tools 并评估 mode，但那样报告性质就会从「审计」变为「审计+修复」，建议拆成独立 spec。

执行层还有几个默认值值得知晓（[cron-runner.ts](https://gitcode.com/GitHub_Trending/cl/cline/blob/be59305d7a632759e163012eeecddda59bc02cfe/sdk/packages/core/src/cron/runner/cron-runner.ts?utm_source=gitcode_repo_files#L34-L36, L186-L208)）：runner 默认每 15 秒轮询一次 cron.db 认领到期的 run，认领租约 90 秒，全局并发默认上限 10；到点后通过既有 runtime handlers 创建新会话执行，timeoutSeconds: 1800 由 withTimeout 包装实现。

五、如何部署与查看运行结果

按 cron/README.md 的标准流程：

mkdir -p ~/.cline/cron
cp sdk/examples/cron/code-style-audit.cron.md ~/.cline/cron/

然后编辑拷贝出的 spec：把 workspaceRoot 改成你项目的绝对路径，按团队情况调整 modelSelection，并把 enabled 改为 true。规格在启动时对账（reconcile），下次触发点自动入队；对账与解析由 cron-reconciler.ts 与 cron-spec-parser.ts 协同完成，解析失败的单个文件只会把自身标记为 invalid，不会拖垮其他 spec。

启用自动化的三种入口（详见 scheduled-agents 指南）：

// Hub（hub-spoke 架构中的后台进程）
new HubWebSocketServer({
  cronOptions: { workspaceRoot: "/absolute/workspace" }
});

// SDK
const cline = await ClineCore.create({ automation: true });

# CLI
cline --enable-automation

运行结束后，每次 run（无论成功或失败）都会落一份 Markdown 报告到 ~/.cline/cron/reports/<run-id>.md（cron-report-writer.ts），内含 run 状态、耗时、token 用量、Prompt 要求生成的完整正文以及逐条工具调用记录——本 spec 的「Top 10 违规 + 三档建议」就是写在这份报告里。数据库（cron.db）仍是操作态事实源，报告是派生产物。

若只想先手动验证一次而不等周三凌晨，可以把 spec 另存为不带 .cron 中缀的 <name>.md 并去掉 schedule 字段，作为一次性（one-off）规格运行（触发类型由文件名推断，见 cron-spec-parser.ts）。

六、落地建议

1. 时区与窗口：0 3 * * WED 依赖系统时区，多机/CI 环境务必显式加 timezone；凌晨执行也便于在周一例会前拿到「周末累积 + 一周中段」的风格基线。
2. 模型选择：示例用 anthropic/claude-opus-4.7 跑审计这类需要归纳判断的任务；纯统计性巡检可换轻量模型控制成本，modelSelection 就是为此设计的按 spec 覆盖项。
3. 与姊妹任务组合：README 推荐的一周组合中，code-style-audit（周三）与 type-check-strict（每日 6 点，plan 模式）、dead-code-finder（周日，plan 模式）形成互补——前者管「写法一致」，后者管「类型安全」与「代码瘦身」，可按团队节奏启用。
4. 保持只读定位：维持 tools: run_commands,read_files + mode: act 的白名单组合，让审计结果进入人工评审，而不是让智能体在凌晨自动改写代码。

七、相关资源

• 原文档：code-style-audit.cron.md
• 全部示例与字段参考：sdk/examples/cron/README.md
• 规格解析：cron-spec-parser.ts
• 调度表达式解析：scheduler.ts
• 运行器与工具策略：cron-runner.ts
• 报告写入：cron-report-writer.ts
• 定时 Agent 官方指南：docs/sdk/guides/scheduled-agents.mdx