Cline 定时自动化实战：用 weekly-metrics-summary 规格自动生成团队周度指标报告

在 Cline 的自动化体系中，sdk/examples/cron/ 目录提供了一批可直接复用的定时任务规格（recurring spec）模板。本文以其中的 weekly-metrics-summary.cron.md 为主线，讲清一份定时 Agent 规格如何从 frontmatter 配置、指标收集提示词，到由 hub/SDK/CLI 触发执行并落盘运行报告的全链路，帮助你在自己的项目中落地"每周五自动生成团队开发指标周报"这类周期性自动化。

一、规格全貌：一份可复制的 .cron.md 定时任务

Cline 的定时任务以"Markdown frontmatter + 提示词正文"的形式定义。weekly-metrics-summary 的完整规格如下（摘自 weekly-metrics-summary.cron.md）：

---
id: weekly-metrics-summary
title: Weekly Project Metrics Summary
workspaceRoot: /absolute/path/to/repo
schedule: "0 17 * * FRI"
tools: run_commands,read_files,search_codebase
mode: act
enabled: false
modelSelection:
  providerId: cline
  modelId: anthropic/claude-opus-4.7
timeoutSeconds: 1800
maxIterations: 20
tags:
  - automation
  - metrics
  - team
metadata:
  owner: leadership
  reportFormat: markdown
---
Generate a fun and insightful weekly metrics summary for the team:

Collect metrics from the past 7 days:

1. **Code Activity:**
   - Total commits this week
   - Lines added/deleted
   - Most active contributors
   - Most modified files

2. **Quality Metrics:**
   - Test pass rate
   - Test coverage trend (up/down %)
   - New issues introduced vs. fixed
   - Type check errors (trend)

3. **Performance:**
   - Build time trend
   - Bundle size changes
   - Performance regressions detected

4. **Pull Requests:**
   - PRs opened vs. closed
   - Average review time
   - PRs by author
   - Most reviewed files

5. **Development Velocity:**
   - Story points completed (if using)
   - Bugs fixed vs. features added
   - On-schedule vs. blocked tasks

Create a fun markdown report with:
- 🏆 Top contributor of the week (most commits/reviews)
- 📈 Metrics trending up/down with arrows
- 🎯 Week's accomplishments summary
- ⚠️  Metrics needing attention
- 💡 Insights (e.g., "Performance improved 5% this week!")
- 🔥 "Hot spots" (most frequently modified files)

Include emoji indicators and fun facts:
- 🚀 Most commits in a single day
- 👀 Most reviewed PR
- 🐛 Most bug fixes by individual

Make it celebratory but data-driven. Perfect for team morale on Friday!

它的设计意图在 cron 示例目录 README 中有明确定位："每周五下午 5 点运行，收集一周的提交、测试覆盖、性能、PR 活动和贡献者数据，生成带 emoji、最佳贡献者、指标趋势和趣味事实的庆祝式 Markdown 报告"，适用于团队士气激励、研发速度跟踪和周五站会/团队频道播报。

值得注意的一个细节是模板中 enabled: false。在解析器里，enabled 字段缺省为 true，显式置为 false 表示"已登记但暂不激活"——从 cron-spec-parser.ts 的实现看：

enabled:
    typeof frontmatterData.enabled === "boolean"
        ? frontmatterData.enabled
        : true,

所以复制模板后，你至少要做三处修改：把 workspaceRoot 改成你项目的绝对路径、把 enabled 改为 true，以及按团队实际情况调整 modelSelection。

二、frontmatter 字段逐项解析

下表将模板中的每个 frontmatter 字段与其在源码中的解析行为对应起来（解析逻辑见 parseCronSpecFile，字段总览另见 README 的 Field Reference）：

字段	模板取值	含义与源码行为
id	weekly-metrics-summary	规格唯一标识（字母数字与连字符）。解析时若缺省，会回退用相对路径作为 externalId
title	Weekly Project Metrics Summary	人类可读标题；缺省时回退为 id，再回退为文件名主干
workspaceRoot	/absolute/path/to/repo	必填。Agent 运行的工作目录绝对路径；源码中缺省会直接判为无效规格（workspaceRoot is required）。注意旧字段 cwd 已被移除，使用会报 field "cwd" is no longer supported
schedule	"0 17 * * FRI"	.cron.md 必填。5 段式 cron 表达式，此处为每周五 17:00。解析阶段会调用 validateCronSchedule 实际推算下一次触发时间来验证表达式合法性，非法表达式会被记录为 parse_status='invalid' 而非丢弃
timezone	（未设置）	可选，IANA 时区名（如 America/New_York），缺省用系统时区。源码用 Intl.DateTimeFormat 校验时区名有效性
tools	run_commands,read_files,search_codebase	逗号分隔的工具白名单。本任务允许执行命令（跑 git 统计、测试）、读文件、搜代码库，但不给 apply_patch/editor，即只读采集、不改动仓库。写入非法工具名会直接报错 unknown tool(s): ...
mode	act	只接受 act/plan/yolo 三值，缺省为 yolo。act 表示允许执行操作但受工具白名单约束
enabled	false	布尔开关，缺省 true。模板默认停用，避免复制后误触发
modelSelection	cline / anthropic/claude-opus-4.7	为本次运行覆盖默认的 provider/model。解析器将其规范为 { providerId, modelId } 结构
timeoutSeconds	1800	运行超时 30 分钟。指标采集需要跑 git log、测试统计等耗时命令，故给足时间；解析要求为正整数
maxIterations	20	Agent 最大迭代轮数，防止指标采集无限循环
tags	automation, metrics, team	任意分组标签，用于检索归类
metadata	owner: leadership 等	自由键值元数据，模板用它标注报告责任人与报告格式

此外还有模板未用到的可选项：systemPrompt（自定义系统提示词）、notesDirectory（跨次运行持久化笔记，多轮状态）、extensions（可取 rules/skills/plugins）、prompt（frontmatter 内提示词，若缺失则自动以 Markdown 正文作为 prompt——本模板正是正文承载提示词）。

关于触发类型的判定，inferTriggerKindFromPath 依据文件名区分三类：events/ 下的 *.event.md 为事件驱动；*.cron.md 为周期调度；其余 .md 为一次性任务（one-off，可省略 schedule）。并且字段有严格的类型隔离：schedule/timezone 只允许出现在 *.cron.md 中，事件类字段（event、filters、debounceSeconds 等）只允许出现在 *.event.md 中，混用会判为无效。

三、提示词正文：指标采集与报告风格的设计

正文部分就是 Agent 每次运行时收到的完整提示词，它把"采集什么"和"怎么呈现"拆成了两层：

采集层（过去 7 天的五类指标）：

1. 代码活动：总提交数、增删行数、最活跃贡献者、修改最频繁的文件；
2. 质量指标：测试通过率、覆盖率趋势（升降百分比）、新增 vs 修复的 issue 数、类型检查错误趋势；
3. 性能：构建时间趋势、bundle 体积变化、检测到的性能回退；
4. Pull Request：开启 vs 关闭数量、平均评审时长、按作者的 PR 分布、被评审最多的文件；
5. 研发速度：完成的故事点（如适用）、修复 bug vs 新增功能、按期 vs 阻塞任务。

呈现层（"庆祝但数据驱动"的报告风格）：要求输出含 🏆 本周最佳贡献者、📈 带方向箭头的指标趋势、🎯 本周成就摘要、⚠️ 需关注指标、💡 洞察（如"性能本周提升 5%"）、🔥 热点文件，以及趣味事实：🚀 单日最多提交、👀 被评审最多的 PR、🐛 个人最多 bug 修复。

从工具白名单反推执行路径：run_commands 支撑 git log/git shortlog 之类的提交统计和测试/构建命令执行，read_files + search_codebase 支撑对覆盖率报告、构建产物等文本产物的读取与分析。如果你要落地到自己的项目，最实用的做法是按仓库实际能力裁剪这五类指标——比如没有覆盖率工具就去掉 Quality 部分，改为聚焦提交与 PR 维度——而不是照搬全部条目。

四、部署与启用：从模板到实际运行

按 cron 示例 README 给出的标准流程：

mkdir -p ~/.cline/cron
cp sdk/examples/cron/weekly-metrics-summary.cron.md ~/.cline/cron/
# 编辑规格：设置 workspaceRoot 绝对路径、enabled: true、按需调整 modelSelection

周期规格默认存放在全局 ~/.cline/cron 目录，hub/SDK 启动时会做 reconcile（对账）：扫描该目录、解析每个规格并自动入队下一次运行——规格文件的增删改会被持久化记录（含内容哈希 sha256(frontmatter + body)），解析失败的文件不会丢失状态而是标记为 parse_status='invalid'。这一机制在 cron-reconciler.ts 与配套的 cron-reconciler.test.ts 中有完整实现与测试覆盖。

启用自动化有三条途径（与 Scheduled Agents 指南 一致）：

• CLI：cline --enable-automation；
• SDK：ClineCore.create({ automation: true }) 后使用 cline.automation 进行规格对账与运行查询；
• Hub 服务：构造 HubWebSocketServer 时传入 cronOptions（如 workspaceRoot）。

五、运行产物：每次执行都会落一份 Markdown 报告

每次运行（无论成功还是失败）都会由 cron-report-writer.ts 在 <cron-specs-dir>/reports/<run-id>.md（默认即 ~/.cline/cron/reports/<run-id>.md）写出一份运行报告。对 weekly-metrics-summary 来说，周五 17:00 触发后，你可以直接打开这份报告查看：

• YAML frontmatter：runId、specId、title、status（completed/FAILED）、schedule、model、sessionId、startedAt/completedAt 等；
• Job 区：定义来源（文件路径或 cron.db 托管调度）、工作区、调度表达式、所用模型，并用围栏代码块原样收录本次提示词；
• Summary 区：Agent 最终输出的那份"庆祝式周报"正文；
• Usage 区：输入/输出/缓存 token、总花费、耗时；
• Tool Calls 区：逐条列出调用过的工具、各自耗时与错误信息；
• 失败时额外有 Error 区，记录错误上下文与堆栈。

这意味着周报"给团队看的内容"（Summary 里的 markdown 报告）与"运维审计信息"（token 花费、工具调用链）分离在同一份文件的两个层面，便于把 Summary 直接贴进团队频道，同时保留可追溯的执行记录。

六、Cron 表达式速查与验证前提

本模板的 "0 17 * * FRI" 是 5 段式（分 时 日 月 周）表达式，表示每周五 17:00 触发。常用写法参考 scheduled-agents 文档：

表达式	含义
0 9 * * MON-FRI	工作日每天 9 点
0 */6 * * *	每 6 小时
0 8 * * MON	每周一 8 点
30 17 * * *	每天 17:30
0 0 1 * *	每月 1 日零点

源码侧的验证链路是：解析规格时调用 validateCronSchedule，内部通过 getNextCronTime 真实推算下一次触发时间——表达式或时区非法即判定规格无效。因此写规格时若不确定表达式，最稳妥的方式是先本地对账一次，观察 ~/.cline/cron/reports/ 是否生成了预期运行。

小结：如何基于此模板扩展自己的指标周报

1. 复制 weekly-metrics-summary.cron.md 到 ~/.cline/cron/，改 workspaceRoot、enabled: true；
2. 按项目实际能力裁剪正文中的五类指标，保留"数据驱动 + 庆祝风格"的报告骨架；
3. 若指标采集涉及大量命令（覆盖率、构建统计），确认 timeoutSeconds: 1800 与 maxIterations: 20 够用，并可给 mode: act + 只读工具白名单兜底，确保自动化不会意外修改仓库；
4. 用 cline schedule trigger <schedule-id> 手动触发一次做验收，再等待周五定时触发；
5. 通过 ~/.cline/cron/reports/ 下的运行报告核查 Summary 输出质量、token 成本与工具调用链，迭代提示词。

相关延伸阅读：Cline 自动化示例总览、定时 Agent 官方指南、规格解析器源码 与 运行报告写入器源码。