Cline SDK 自动化实践基于 .cron.md 与 .event.md 文件规格构建定时与事件驱动的 Agent 任务【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline本文基于 Cline 仓库中的自动化示例目录sdk/examples/cron/展开系统讲解 Cline 文件式自动化file-based automation的两种规格格式——周期任务.cron.md与事件驱动任务.event.md——的完整字段、节流机制、启用方式与运行报告机制并结合cline/core中的规格解析器、事件入口与报告写入器源码说明一份 Markdown 规格从落盘到执行的全过程。读完后你可以直接复制模板搭建自己的周期性代码审查、依赖检查或 GitHub 事件响应流水线。两种自动化规格命名即触发方式Cline 自动化支持两类文件规格均放在~/.cline/cron/或 workspace 作用域下的对应目录由 hub 或 SDK 拾取周期规格.cron.md——按 cron 表达式定时运行事件驱动规格.event.md——放在events/子目录当归一化事件normalized event被摄入时触发。触发方式由文件路径本身推断。在 cron-spec-parser.ts 中可以看到inferTriggerKindFromPath的实现逻辑if (normalized.startsWith(events/) normalized.endsWith(.event.md)) { return event; } if (normalized.endsWith(.cron.md)) { return schedule; } return one_off;从源码结构看路径规则很明确events/*.event.md是事件规格*.cron.md是周期规格而两者都不是例如.cline/cron/name.md无.cron中缀则被推断为one_off——一次性规格。因此一次性任务的官方写法是保存为.cline/cron/name.md并省略schedule字段。此外解析器还有一个重要的健壮性设计单个坏文件不会抛异常而是产生带error消息的CronSpecParseResult由对账器reconciler将parse_statusinvalid持久化记录而不是静默丢弃状态——这意味着写错字段名的规格在报告中可查而不是消失了。模板总览从目标选规格sdk/examples/cron/目录提供了 10 个周期规格与 5 个事件规格模板覆盖日常开发自动化的常见场景目标规格调度模式代码审查daily-code-review工作日 9 AMact更新 CHANGELOGchangelog-generator周五 6 PMact安全检查dependency-check周一 10 AMact验证测试test-coverage-report每天 10 PMact性能追踪performance-baseline每天 2 AMact类型检查type-check-strict每天 6 AMplan风格审计code-style-audit周三 3 AMact找死代码dead-code-finder周日 4 AMplan文档检查documentation-check周四 5 AMplan周度战报weekly-metrics-summary周五 5 PMactPR 审查pr-reviewPR 打开时actPR changelog 检查pr-changelog-checkPR 打开时actPR 覆盖率pr-test-coveragePR 更新时act注意mode列的差异质量检查、审计类任务多用act可执行命令、可写文件而类型检查、死代码查找、文档审计等只报告不建议直接改的任务用plan只分析产出报告不执行变更动作。周期任务模板详解daily-code-reviewdaily-code-review.cron.md 是官方给出的生产就绪示例完整的 YAML frontmatter 加正文如下--- id: daily-code-review title: Daily Code Review workspaceRoot: /absolute/path/to/repo schedule: 0 9 * * MON-FRI tools: run_commands,read_files mode: act enabled: true modelSelection: providerId: cline modelId: anthropic/claude-opus-4.7 timeoutSeconds: 1800 systemPrompt: You are a precise automation agent that reports only actionable review findings. maxIterations: 20 tags: - automation - review metadata: owner: platform notesDirectory: /absolute/path/to/notes extensions: - rules - skills - plugins source: user --- Review the open pull requests, identify the highest-risk changes, run the relevant checks if needed, and write a concise summary of findings.逐字段解读schedule: 0 9 * * MON-FRI——标准 5 段 cron 表达式分、时、日、月、星期工作日早 9 点运行tools: run_commands,read_files——把 Agent 的工具权限收窄到执行命令 读文件源码中该字段接受逗号分隔字符串或数组两种写法见 cron-spec-parser.ts 的normalizeStringList字符串会按逗号拆分并去重设为空会禁用工作类工具适合纯只读审计mode: act——允许执行命令可选值还有plan只分析和yolo默认权限最宽timeoutSeconds: 1800——单次运行 30 分钟超时modelSelection——为本任务单独指定 provider/model覆盖默认模型适合重活给强模型、轻活用便宜模型的成本策略notesDirectory——持久化的自动化笔记目录用于跨多次运行保存状态例如上次检查到哪maxIterations: 20——限制 Agent 迭代轮数防止失控循环extensions: [rules, skills, plugins]——为该运行注入项目的规则、技能与插件上下文YAML 正文frontmatter 之后的 Markdown 内容就是发给 Agent 的 prompt 主体。使用方式mkdir -p ~/.cline/cron cp sdk/examples/cron/daily-code-review.cron.md ~/.cline/cron/ # 编辑规格设置 workspaceRoot、model 等 # 规格在启动时对账reconcile下次运行自动入队其余周期模板各司其职的九份规格模板调度做什么changelog-generator.cron.md周五 6 PM审查apps/cli/自上次 CHANGELOG 以来的提交按 Feature / Fix / Breaking 格式在CHANGELOG.md顶部追加条目明确要求不改package.json版本号、不覆盖既有条目dependency-check.cron.md周一 10 AM检查过期包、安全漏洞、未使用依赖与主版本升级产出按优先级排序的行动报告test-coverage-report.cron.md每天 10 PM跑全量测试、生成覆盖率报告识别补测薄弱文件输出带可视化指示的 Markdown 摘要performance-baseline.cron.md每天 2 AM测量构建耗时、包体积、冷启动性能指标超阈值时告警type-check-strict.cron.md每天 6 AMplan以严格编译选项报告全部类型错误并按问题类型归类渐进式提升类型安全而不阻塞开发code-style-audit.cron.md周三 3 AM跑 ESLint 与 Prettier识别未使用代码与反模式汇总违规摘要dead-code-finder.cron.md周日 4 AMplan识别未使用的导出、不可达代码与废弃模式区分可安全删除与需人工复核documentation-check.cron.md周四 5 AMplan分析文档完整度、缺失的 JSDoc、过时文档与整体文档结构weekly-metrics-summary.cron.md周五 5 PM汇总一周的提交、覆盖率、性能、PR 活动与贡献者统计生成带 top contributors 与趣闻的团队周报以changelog-generator为例可以看到规格正文就是结构化的任务指令它规定输出格式## [VERSION] (YYYY-MM-DD) Feature/Fix/Breaking 列表、边界约束不改版本号、不覆盖旧条目、只关注用户可见变更并通过metadata.targetFile/metadata.trackDirectory两个自定义字段把写哪个文件、看哪个目录固化下来——metadata是任意对象适合把任务参数与指令正文解耦。事件驱动规格触发、过滤与节流事件驱动规格位于.cline/cron/events/子目录事件被摄入ingest后触发。核心示例 pr-review.event.md--- id: pr-review title: Review New Pull Requests workspaceRoot: /absolute/path/to/repo cwd: /absolute/path/to/repo event: github.pull_request.opened filters: repository: acme/api pullRequest: baseBranch: main debounceSeconds: 30 dedupeWindowSeconds: 600 cooldownSeconds: 120 maxParallel: 2 mode: act enabled: true modelSelection: providerId: cline modelId: anthropic/claude-opus-4.7 timeoutSeconds: 1800 maxIterations: 20 tags: - automation - github - review metadata: owner: platform source: normalized-event-ingress --- Review the opened pull request from the trigger event context. Summarize the highest-risk changes, call out missing tests or migration risks, and recommend the next action for the author.事件专属字段的语义可以直接在 cron-event-ingress.ts 的实现中一一对应event——触发的事件类型必填例如github.pull_request.opened、local.manual_testfilters——按事件字段收窄匹配范围支持点路径如pullRequest.baseBranch: maindebounceSeconds: 30——debounce 窗口内合并事件等 30 秒看是否还有后续事件再触发源码中debounceSeconds ?? 0默认 0 即立即触发dedupeWindowSeconds: 600——10 分钟内的重复事件直接跳过cooldownSeconds: 120——一次运行结束后 2 分钟内不再接受触发maxParallel: 2——最多 2 个并发运行默认不限。这四个节流参数在源码中均以 0 为默认值即不写就不生效模板中显式声明是为了让行为可预期。其余事件模板local-manual-test.event.md——本地冒烟测试用事件类型local.manual_test按filters: { topic: cron-feature-2 }匹配事件负载字段debounceSeconds: 0立即触发、maxIterations: 5快速结束便于不依赖任何外部服务验证事件链路local-plugin-event.event.md——配合 automation-events.ts 插件测试插件发事件链路事件类型local.plugin_event按topic: plugin-demo匹配pr-changelog-check.event.md——PR 打开到main时触发若 PR 改了源码但没更新 CHANGELOG则发评论建议应补充什么若已更新则校验格式pr-test-coverage.event.md——PR 打开或更新时触发对比 PR 分支与 main 的覆盖率评论指出新代码的覆盖/未覆盖情况、覆盖率影响百分比、覆盖率下降的文件与补测建议。事件从哪里来归一化事件有四条摄入路径见 READMEGitHub App 或 webhook 接收器插件发出的事件sdk/examples/plugins/automation-events.tsConnector 适配器SDK 的cline.automation.ingestEvent()接口——在 automation.ts 中ClineCoreAutomationController.ingestEvent把事件转交给CronService.ingestEvent同步返回归一化事件、去重判定duplicate、命中的规格 id 列表matchedSpecIds、入队运行queuedRuns与抑制记录suppressions调用方可以据此做可观测性处理。本地手动注入一条测试事件的示例来自 READMEmkdir -p ~/.cline/cron/events cp sdk/examples/cron/events/local-manual-test.event.md ~/.cline/cron/events/ # 另起一个 shell向 hub 注入测试事件 node -e const { HubWebSocketClient } require(cline/core); const client new HubWebSocketClient(ws://localhost:8000); client.send(cron.event.ingest, { eventType: local.manual_test, envelope: { subject: test, topic: cron-feature-2, message: hello } }); 完整字段参考公共字段两种规格通用字段类型必填说明idstring是唯一标识字母数字、连字符titlestring是人类可读标题workspaceRootstring是项目绝对路径modestring否yolo默认、act或plantoolsstring/array否逗号分隔的工具名置空禁用工作类工具systemPromptstring否自定义系统提示词modelSelectionobject否{ providerId, modelId }为单次运行覆盖模型/供应商maxIterationsnumber否迭代轮数上限timeoutSecondsnumber否运行超时extensionsarray否rules、skills、pluginstagsarray否任意分组标签metadataobject否自定义元数据周期专属字段.cron.md字段类型说明schedulestring必填。5 段 cron 表达式分、时、日、月、星期timezonestring可选。IANA 时区如America/New_York缺省使用系统时区事件专属字段.event.md字段类型说明eventstring必填。事件类型如github.pull_request.opened、local.manual_testfiltersobject可选。按事件字段匹配支持点路径debounceSecondsnumber可选。N 秒内合并事件默认 0dedupeWindowSecondsnumber可选。N 秒内跳过重复事件默认 0cooldownSecondsnumber可选。运行后等待 N 秒默认 0maxParallelnumber可选。最大并发运行数默认不限工具白名单参考tools字段可用的工具名read_files——读取文件内容search_codebase——跨项目搜索run_commands——执行 shell 命令fetch_web_content——抓取 URLapply_patch——应用代码补丁editor——编辑文件skills——调用自定义技能ask_question——向用户提问submit_and_exit——结束运行安全实践上只读审计类规格安全扫描、文档审计只给read_files,search_codebase可改文件的任务changelog 生成再叠加editor需要跑测试/构建的才加run_commands——最小权限原则直接写在 frontmatter 里。从零启用五步走1. 建立规格目录mkdir -p ~/.cline/cron/events2. 复制一个模板定时任务daily-code-review.cron.mdGitHub 事件pr-review.event.md本地测试local-manual-test.event.md插件事件local-plugin-event.event.md3. 定制规格设置workspaceRoot为项目路径非默认模型时设置modelSelection更新filters匹配你的仓库/分支调整超时、迭代数与工具限制打磨 YAML 正文即 prompt。4. 启用自动化——三种入口任选Hub 方式new HubWebSocketServer({ cronOptions: { workspaceRoot: /absolute/workspace } });SDK 方式const cline await ClineCore.create({ automation: true, // 启用自动化 // ... 其他选项 });源码中automation: true会被normalizeAutomationOptions归一化为空对象{}即启用全部默认行为见 automation.ts。CLI 方式cline --enable-automation5. 监控运行完成与失败的运行都会写入.cline/cron/reports/run-id.md包含 YAML frontmatterrun ID、状态、耗时、token 用量、工作摘要、工具调用与结果事件触发时还会附带触发事件上下文。报告路径的默认值~/.cline/cron/reports/run-id.md在 cron-report-writer.ts 中定义传入{ scope: workspace, workspaceRoot }可改为写到 workspace 旁。底层机制一份规格如何被执行sdk/ARCHITECTURE.md的 File-Based And Event-Driven Automation 一节把这条流水线描述得很清楚核心组件都位于packages/core/src/cron/下规格解析器cron-spec-parser.ts解析 YAML frontmatter 正文为CronSpec判别联合类型one_off | schedule | event类型定义在cline/shared存储层sqlite-cron-store.ts管理cron.db默认.cline/data/db/cron.dbschema 来自 cron-schema.ts对账器cron-reconciler.ts扫描配置的 cron 规格目录默认全局~/.cline/cron/workspace 作用域时可指向项目内这就是规格在启动时对账、下次运行自动入队的实现来源监视器cron-watcher.ts基于node:fs的递归 watch规格文件改动后热更新物化器cron-materializer.ts把文件触发的规格转为排队的cron_runs——一次性规格每个(spec_id, ...)至多一条运行记录周期规格借助时区感知的getNextCronTime定义于 scheduler.ts计算下次触发时间事件入口cron-event-ingress.ts接收已归一化的事件按 debounce / dedupe / cooldown / maxParallel 策略决定是否触发。对外暴露的是 SDK 面cline.automation.*系列接口内部统一由 cron-service.ts 的CronService承载——这也解释了为什么 Hub、SDK、CLI 三种启用方式最终走的是同一套文件规格体系。实战组合一周的全自动化排班README 给出了多规格组合的完整开发自动化排班周一 10 AM → dependency-check.cron.md (检查依赖) 周二 3 AM → code-style-audit.cron.md (Lint 与格式化) 周三 5 AM → documentation-check.cron.md (文档覆盖) 周四 4 AM → dead-code-finder.cron.md (找清理机会) 周五 6 PM → changelog-generator.cron.md (自动生成 changelog) 每天 2 AM → performance-baseline.cron.md (跟踪性能指标) 每天 10 PM → test-coverage-report.cron.md (覆盖率趋势) 每天 6 AM → type-check-strict.cron.md (类型安全) 每个 PR 上 → pr-changelog-check.event.md (校验 CHANGELOG) → pr-test-coverage.event.md (覆盖率影响)按角色的推荐组合团队负责人dependency-check周度安全审查dead-code-finder季度清理规划performance-baseline系统健康QA 工程师test-coverage-report趋势跟踪pr-test-coveragePR 级反馈后端团队performance-baseline构建耗时、API 响应时间type-check-strict类型安全前端团队performance-baseline包体积、冷启动code-style-audit风格一致性。两个最小示例照着改就能用每日安全审计周期规格--- id: daily-security-audit title: Daily Security Audit workspaceRoot: /path/to/repo schedule: 0 2 * * * # 每天 2 AM tools: read_files,search_codebase mode: act timeoutSeconds: 3600 extensions: - skills --- Search for hardcoded secrets, outdated dependencies, and insecure patterns. Report findings to the team.注意这里刻意只给read_files,search_codebase两个只读工具——安全扫描不应有改文件的权限。main 分支所有新 PR 的审查事件规格--- id: pr-security-review title: Security Review for PRs workspaceRoot: /path/to/repo event: github.pull_request.opened filters: pullRequest: baseBranch: main cooldownSeconds: 300 maxParallel: 3 --- Summarize the changes, check for security risks, and recommend approval or changes.小结与延伸阅读Cline 的自动化把何时运行、用什么模型、允许哪些工具、prompt 是什么全部沉淀为可版本管理的 Markdown 文件周期规格靠 cron 表达式事件规格靠归一化事件加上四段式节流参数运行结果统一落盘为带 frontmatter 的报告文件天然可审计。由于触发方式由文件路径推断、坏规格只降级不崩溃这套机制对文件即配置的运维习惯非常友好。进一步阅读sdk/ARCHITECTURE.md——运行时架构与自动化流程细节sdk/examples/plugins/automation-events.ts——插件发事件的完整示例sdk/examples/cron/README.md——本文章对应的官方示例索引sdk/packages/core/src/cron/service/cron-service.ts——CronService核心服务实现【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考