用 Cline 定时 Agent 搭建性能基线监控：解析 performance-baseline.cron.md 自动化模板

2026-09-06 18:22:07作者：柯茵沙

Cline 以 Markdown 文件（.cron.md）作为"定时 Agent 自动化规范"（Automation Spec）的载体，让开发者可以用纯文本定义一个"每天凌晨自动测量构建耗时、bundle 体积与冷启动时间、并按阈值检测性能回退"的无人值守任务。performance-baseline.cron.md 正是仓库中针对**性能敏感型项目（CLI、库、服务）**提供的开箱即用示例。读完本文，你将掌握这份 spec 的逐字段含义、性能回归判定策略、把它部署到 ~/.cline/cron/ 并接入 Hub / SDK / CLI 的完整流程，以及其背后解析、存储、调度、执行的源码机制。

一、这份 spec 是什么：从示例文件定位其角色

在 sdk/examples/cron/README.md 的自动化示例总表中，performance-baseline 被标注为：

目标	Spec 文件	计划	模式
⚡ 跟踪性能	`performance-baseline`	每天凌晨 2 点	act

README 对其适用场景给出了精确定位："Best for: CLI tools, libraries, or services where performance is critical."（最适合 CLI 工具、库或对性能要求苛刻的服务），并在"团队分工"一栏中分别建议：后端团队用它观测"构建时间、API 响应时间"，前端团队用它盯"bundle 体积、冷启动"。在 sdk/ARCHITECTURE.md 的自动化架构介绍中，这类文件被称为"文件驱动与事件驱动自动化（ClineCore / CronService）"子系统下以 .cron.md 结尾的定时（schedule）型 spec。

整份 spec 由两部分组成：开头的 YAML frontmatter（元数据，配置"何时跑、用什么模型跑、跑多久、允许用哪些工具"），以及正文 Markdown body（即真正的任务 prompt，告诉 Agent"具体要测量什么、记录什么、如何判定回退"）。下面逐层拆解。

二、frontmatter 逐字段解读：让定时任务"可配置、可约束"

原文件头部的 YAML frontmatter 是理解整个自动化运行模型的关键，全文复制并逐项注解如下：

---
id: performance-baseline          # 全局唯一标识（字母数字与连字符）；未显式声明时解析器回退到相对路径
title: Track Performance Metrics  # 人类可读的标题
workspaceRoot: /absolute/path/to/repo  # 必填：Agent 的工作目录（即构建命令的执行 cwd）
schedule: "0 2 * * *"             # cron 表达式：每天凌晨 2:00
tools: run_commands,read_files,editor  # 白名单：本次运行仅允许这三种工具
mode: act                         # 运行模式：act（可执行命令并修改文件）
enabled: false                    # 默认停用，复制后按需开启
modelSelection:                  # 为本次运行覆盖默认模型
  providerId: cline
  modelId: anthropic/claude-opus-4.7
timeoutSeconds: 2400              # 单次运行最长 2400 秒（40 分钟）
maxIterations: 20                 # Agent 最大迭代轮次，防止失控循环
tags:
  - automation                    # 任意标签，用于分组检索
  - performance
  - monitoring
metadata:                         # 任意自定义元数据，原样随 spec 存储
  owner: platform
  metricsFile: .perf-baseline.json  # 团队自定义：记录结果文件的路径
---

1. 触发类型由文件名推断：`.cron.md` 即定时任务

这些字段并不是随意解析的。类型定义位于 sdk/packages/shared/src/cron/cron-spec-types.ts，其中 CronTriggerKind = "one_off" | "schedule" | "event"，而"走哪种触发"由文件路径约定决定：*.cron.md → 定时；events/*.event.md → 事件驱动；.cline/cron/ 下其它 *.md → 一次性任务。解析函数 inferTriggerKindFromPath 的实现见 sdk/packages/core/src/cron/specs/cron-spec-parser.ts。因此，本文件的调度字段只有放在 .cron.md 后缀下才合法——解析器会强制校验："schedule is required for *.cron.md specs"，而把 schedule/timezone 写在事件或一次性 spec 中会被判定为非法（见同文件 SCHEDULE_ONLY_FIELDS 校验逻辑）。

2. 关键字段的约束与默认值（来自解析器源码）

对照 cron-spec-parser.ts 的实现，可得到以下经过校验的事实：

workspaceRoot 必填：缺省即返回 workspaceRoot is required 错误；同时旧字段 cwd 已被移除，注释明确指出"cron specs use workspaceRoot as cwd"。
prompt 来源：frontmatter 中的 prompt 字段或 Markdown body 二选一，二者皆缺则解析失败。本文件未声明 prompt，因此正文内容就是任务 prompt。
mode 默认 yolo，合法值为 act / plan / yolo；本文件显式使用 act（可执行构建命令并落盘结果文件）。
tools 为空字符串/空数组会禁用全部工作工具；声明工具名必须在默认工具集内，否则报 unknown tool(s): ...。本文件限定了 run_commands（跑构建）、read_files（读历史基线）、editor（更新 JSON 结果）三种。
maxIterations / timeoutSeconds 按正整数取整，非正数会被忽略并回退为默认。
enabled 为布尔值，未声明时默认 true；示例文件刻意写成 false，让用户复制后再显式开启，避免误启用写死的工作区路径。
metadata 是任意 Record<string, unknown>，会被原样保留——示例里用 metricsFile: .perf-baseline.json 记录结果落盘位置，是一种值得借鉴的团队约定。

3. schedule 表达式的校验与可用值

schedule 为五段 cron（分、时、日、月、星期），解析时会调用 validateCronSchedule(schedule, timezone)（见 sdk/packages/core/src/cron/specs/cron-spec-parser.ts）做合法性校验，非法表达式直接记为解析错误。timezone 可选，缺省使用系统时区。常见的等价调度写法可参考 docs/sdk/guides/scheduled-agents.mdx 中的 cron 速查表：0 9 * * MON-FRI（工作日 9 点）、0 */6 * * *（每 6 小时）、0 0 1 * *（每月 1 日零点）等。若希望"每个工作日清晨跑一次基线"，把示例改为 schedule: "0 9 * * MON-FRI" 即可。

三、任务主体：一份"性能测量 + 回归判定"的 Agent prompt

frontmatter 之下的正文没有代码，而是一段面向 Agent 的结构化指令（performance-baseline.cron.md）。它把"性能基线巡检"拆成了四个可执行动作与三组判定规则：

1. 采集四类指标

1. 构建项目并计时：npm run build
2. Bundle 体积分析（如适用）：运行带体积报告的 bundler
3. 若为 CLI/服务端工具，测量冷启动时间
4. 运行仓库中已有的性能基准测试（若存在）

2. 落盘基准 JSON

Create or update `.perf-baseline.json` with:
{
  "timestamp": "ISO-8601",
  "buildTime": "milliseconds",
  "bundleSize": "bytes",
  "coldStart": "milliseconds",
  "metrics": {...}
}

这是一个约定俗成的数据契约：timestamp 用 ISO-8601 时间戳标识"这一次测量的快照时间"，buildTime / coldStart 以毫秒为单位，bundleSize 以字节为单位，metrics 作为扩展对象收纳仓库自定义的其它性能指标。该文件被命名为 .perf-baseline.json（点号开头），通常应加入 .gitignore，因为它是机器产生的运行时状态而非源码。

3. 按阈值做回归判定

构建时间较前一日基线增幅 >10% → 标记为 warning（警告）；
bundle 体积增幅 >5% → 标记为 concern（需关注）；
判定基准是"与前一天基线对比"（Compare to previous day's baseline）。

4. 输出结论

若检测到回归，给出发现与优化建议（Report findings with recommendations for optimization）。这正是把 Cline 当作"夜间值班性能工程师"的价值所在：Agent 不仅测数，还会结合 read_files 读历史、run_commands 复现、editor 更新基线，最终交付一份带建议的报告。

四、它是如何被定时执行的：CronService 运行链路

从 sdk/ARCHITECTURE.md 可梳理出这条 spec 从"文件"到"运行"的完整链路：

Spec 解析：cron/specs/cron-spec-parser.ts 把 YAML frontmatter + body 解析为 CronSpec 判别联合（one_off | schedule | event），类型定义在 @cline/shared 的 src/cron/cron-spec-types.ts。
持久化存储：cron/store/sqlite-cron-store.ts 把解析结果写入 cron.db（默认位置 .cline/data/db/cron.db），连解析失败的 spec 也会以 parse_status='invalid' 被持久记录，绝不静默丢弃状态。
Reconciler 对账：cron/specs/cron-reconciler.ts 扫描配置的 spec 目录（默认全局 ~/.cline/cron/，也可通过 workspace 作用域配置），增量同步文件与 DB。
Watcher 监听：cron/specs/cron-watcher.ts 用 node:fs 递归 watch 该目录——把 spec 文件放进目录后无需重启，启动时与运行期都会自动对账，下一次运行自动入队。
Materializer 物化：cron/runner/cron-materializer.ts 把文件触发的 spec 转成排队中的 cron_runs，定时型按 timezone 感知的 getNextCronTime 计算下一次触发。
Runner 执行：cron/runner/cron-runner.ts 轮询 cron.db、原子抢占待运行任务、新建会话执行 prompt（自动化运行会显式以 mode: "automation" 持久化每一次运行记录与触发来源）。
报告输出：cron/reports/cron-report-writer.ts 把完成的运行写入 .cline/cron/reports/<run-id>.md，包含运行 ID、状态、耗时、token 用量、工作摘要与工具调用记录——也就是你查"昨晚 2 点那次基线巡检到底发现了什么"的地方。
服务编排：cron/service/cron-service.ts 统管以上各组件；SDK 侧由 ClineCore.create({ automation }) 持有生命周期并暴露 cline.automation.* 方法。

需要注意：本模板属于定时任务（schedule），与 events/*.event.md（如 PR 打开时触发评审）是两条不同触发路径，两者通过 sdk/examples/cron/README.md 中的字段速查表区分——定时型额外要求 schedule，事件型额外要求 event 与 debounceSeconds/dedupeWindowSeconds/cooldownSeconds/maxParallel 等限流字段。

五、部署与运行：三种启用方式

1. 放置 spec 文件（通用前提）

官方推荐把 spec 放入用户级自动化目录：

mkdir -p ~/.cline/cron
cp sdk/examples/cron/performance-baseline.cron.md ~/.cline/cron/

然后编辑副本，至少要完成三件事：把 workspaceRoot 改为项目绝对路径；把 enabled 改为 true；按需把 modelSelection 换成你有权限调用的模型。随后 spec 会在启动时被 reconcile，下一次 cron 触发即自动入队执行（参考 sdk/examples/cron/README.md）。若只想跑一次临时巡检，可另存为 .cline/cron/<name>.md（去掉 .cron 中缀）并省略 schedule 字段，它会被推断为一次性任务。

2. 分别在 Hub / SDK / CLI 中开启自动化

根据 sdk/examples/cron/README.md 与 docs/sdk/guides/scheduled-agents.mdx，三种运行载体启用方式如下：

Hub（自建调度服务）：构造时传入 cron 工作区：

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

SDK（程序化接入）：创建 ClineCore 时打开 automation 并启动调度：

import { ClineCore } from "@cline/sdk";

const cline = await ClineCore.create({
  clientName: "perf-baseline-runner",
  automation: true,
});

await cline.automation.start();
// cline.automation 提供 reconcile、事件摄取、运行列表等入口

CLI（命令行一键启用）：

cline --enable-automation

适用范围提醒：该定时 Agent 能力目前覆盖 Cline SDK、CLI 与 Kanban，VSCode / JetBrains 扩展尚不适用（见 docs/cli/scheduling.mdx 的 Warning）。

3. 另一种等效方式：`cline schedule create`

若不喜欢维护 spec 文件，也可用 CLI 调度命令创建等效任务。参照 docs/cli/scheduling.mdx，等价于本模板的调度可以这样创建：

cline schedule create "Performance baseline" \
  --cron "0 2 * * *" \
  --prompt "构建项目并计时(npm run build)，做 bundle 体积与冷启动分析，
           更新 .perf-baseline.json，若相对前一日基线构建时间增幅超10%
           或 bundle 增幅超5% 则给出优化建议" \
  --workspace /path/to/repo

随后用 cline schedule list / cline schedule trigger <id> / cline schedule executions <id> 等命令管理运行与历史。两种方式殊途同归：程序化 hub 调度同样落入 cron_specs（source 为 hub-schedule），并经由同一套 cron_runs 管线执行。

六、把模板落地到真实项目的实战建议

结合本模板与仓库实践，给出几条可直接照做的工程化建议：

先验证 build 命令可被无人值守执行：npm run build 必须在无 TTY 环境下稳定、幂等地完成。若你的构建需要环境变量，应保证运行 Hub 的常驻进程环境里已就绪，或在 spec 的 body 中写明前置步骤。
为 bundle 体积配好稳定测量口径：模板第 2 步要求"bundler 带 size 报告"。仓库自身就大量依赖构建产物（如 vscode/esbuild.mjs、vscode-rollout/esbuild.mjs），实际项目可改用 esbuild --metafile、Vite/Rollup 的 size 插件等固定工具，保证每天产出的是同口径字节数，否则 5% 阈值判定会失真。
冷启动测量只对 CLI/Server 有意义：若项目是纯 Web 应用，第 3 步可从 body 中删去，避免 Agent 无谓消耗迭代次数。
把 metadata.metricsFile 与 body 中的路径保持一致：示例约定结果统一写在 .perf-baseline.json，Agent 依据 body 描述"与前一天对比"，意味着该文件必须在多次运行间持久存在——确保 .cline 工作区没有把 .perf-baseline.json 当临时产物清理掉。
先手工触发验证再开放调度：初次接入时用 cline schedule trigger <id>（或直接跑一次 body 里的步骤）确认 .perf-baseline.json 结构与阈值逻辑符合预期，再放心让它每天凌晨 2 点自动执行；毕竟 mode: act 意味着 Agent 有执行命令并修改文件的权限，tools 白名单（run_commands,read_files,editor）与 maxIterations: 20 是防失控的重要护栏。
与其他巡检任务编排成"开发自动化套件"：sdk/examples/cron/README.md 给出了典型编排：Daily 2 AM → performance-baseline 负责指标、Daily 10 PM → test-coverage-report 负责覆盖率、Daily 6 AM → type-check-strict 负责类型安全——凌晨低谷期集中执行，早上团队到岗即可看到昨夜巡检报告（.cline/cron/reports/<run-id>.md）。

七、结语

performance-baseline.cron.md 虽只有不足 50 行，却完整示范了 Cline 定时自动化三大设计要点：YAML frontmatter 表达运行约束（调度、模型、工具白名单、超时与迭代上限）、Markdown body 表达任务意图（测什么、怎么测、如何判定）、结果文件表达状态（跨运行的性能基线）。把它复制进 ~/.cline/cron/ 并开启 automation，即可获得一个长期值守、自动比对昨日基线、按 >10% / >5% 阈值告警并给出优化建议的"夜间性能巡检员"——对 CLI 工具、库与对性能敏感的服务而言，这是一种几乎零维护成本的持续性能回归防线。