
Cline 事件驱动自动化实战用 pr-changelog-check 规范自动审查 PR 的 CHANGELOG 更新【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline本篇基于 Cline 仓库中的事件驱动自动化示例 pr-changelog-check.event.md完整讲解这份“PR 自动检查 CHANGELOG”规范的字段配置、检查逻辑与部署方式并结合 cron 事件入口层 与 自动化控制器 的源码说明事件如何被去重、过滤、限流并落地为一次 Agent 运行。读完后你可以直接复制该模板到自己的仓库搭建一套“PR 修改代码却漏更 CHANGELOG 时自动在 PR 上提醒”的事件驱动自动化。规范是什么事件驱动的 CHANGELOG 守卫Cline 的自动化Automation体系支持两类规格文件spec定时规格.cron.md——按 cron 表达式周期运行如每日代码审查、周五生成 changelog事件规格.event.md——当某个“归一化事件”被摄入ingest时触发。本文章的主体pr-changelog-check属于第二类的典型应用每当一个 PR 打开github.pull_request.opened且满足过滤条件时自动运行一次 Agent 任务检查该 PR 是否同步更新了 CHANGELOG并把结论以 PR 评论形式反馈给作者。在 sdk/examples/cron/README.md 的选型表中它被定位为 “Check PR changelog / On PR opened / act 模式”。完整规范原文与逐字段解析先给出规范文件的完整内容YAML frontmatter 是配置正文是给 Agent 的提示词--- id: pr-changelog-check title: Check for Changelog Updates in PRs workspaceRoot: /absolute/path/to/repo event: github.pull_request.opened filters: repository: your-org/your-repo pullRequest: baseBranch: main debounceSeconds: 10 cooldownSeconds: 60 maxParallel: 3 modelSelection: providerId: cline modelId: anthropic/claude-opus-4.7 tags: - automation - github - documentation metadata: owner: development --- Automatically check if a PR that modifies code also updates the CHANGELOG: 1. Detect if the PR modifies source files (src/, lib/, etc.) 2. Check if the PR also includes changes to CHANGELOG.md or relevant changelogs 3. If significant code changes but no changelog update: - Extract a summary of the changes - Suggest what should be added to CHANGELOG - Request the author to add an entry 4. If CHANGELOG is updated: - Verify the format matches the project style - Check that entry is concise and user-facing - Ensure version number is appropriate Provide feedback as a comment on the PR: - ✅ CHANGELOG properly updated - ⚠️ No CHANGELOG changes detected - please add an entry - CHANGELOG entry format seems off - consider [example] This helps maintain an up-to-date CHANGELOG without manual reminders.下面按字段组逐一说明其含义与在事件入口层的实际作用。身份与工作区字段字段示例值说明idpr-changelog-check唯一标识规范要求字母数字加连字符titleCheck for Changelog Updates in PRs人类可读标题workspaceRoot/absolute/path/to/repo必填Agent 运行时的项目绝对路径复制模板后必须改成自己的仓库路径mode本规范省略缺省为yolo同目录的姊妹示例 pr-review.event.md 显式写了mode: act允许执行命令。README 的选型表把本规范标注为act模式因为“在 PR 上发表评论”需要执行 GitHub 相关命令modelSelection{ providerId: cline, modelId: anthropic/claude-opus-4.7 }为本规范单独覆盖模型/提供方不影响全局默认模型tags/metadataautomation、github、documentationowner: development分组标签与自定义元数据便于管理和检索事件触发与过滤字段字段示例值说明eventgithub.pull_request.opened事件规格必填。事件类型即触发器filtersrepository: your-org/your-repopullRequest.baseBranch: main过滤条件只在指定仓库、且目标分支为main的 PR 上触发。替换为你自己的 org/repofilters的匹配并非简单的键值相等——从 cron-event-ingress.ts 的resolveFilterValue和matchesExpected实现可以看到过滤键支持点路径如pullRequest.baseBranch会依次在事件的attributes、payload中按路径取深层字段getPath按.逐段下钻期望值支持数组语义为“任一匹配即可”、嵌套对象递归要求所有键匹配以及普通标量严格相等比较。因此pullRequest: { baseBranch: main }这一层对象过滤会被递归展开为“事件属性中的pullRequest.baseBranch必须等于main”。限流三兄弟debounce / dedupe / cooldown事件类规范独有的四个字段README 的 Field Reference 给出完整清单默认值均为 0/不限字段本规范取值默认值作用debounceSeconds100合并事件收到事件后等待 N 秒期间同一 dedupeKey 的新事件不新建 run而是把已有排队 run 的scheduledFor顺延dedupeWindowSeconds未设置0滑动窗口去重N 秒内同一 dedupeKey 的事件直接跳过cooldownSeconds600运行冷却某次 run 之后 N 秒内不再为该规范触发新 run不限 dedupeKeymaxParallel3不限该规范最多并发 3 个 run这三者的行为在入口层源码中有精确对应。materializeForSpeccron-event-ingress.ts按顺序执行debounce 分支若debounceSeconds 0且已存在同一(specId, dedupeKey)的排队 run则调用updateQueuedEventRunForDebounce将scheduledFor更新为max(原 scheduledFor, receivedAt debounceSeconds)并复用该 run——本规范设为 10 秒意味着 PR 打开后 10 秒内的抖动事件如重复 webhook 推送会合并成一次检查dedupe 分支若dedupeWindowSeconds 0且窗口内已有同 dedupeKey 的 run则以dedupe_window原因抑制cooldown 分支若cooldownSeconds 0且冷却窗内该 spec 已跑过 run则以cooldown原因抑制——本规范的 60 秒冷却防止作者连续开 PR 或对同一 PR 反复操作时刷屏评论均通过后才调用enqueueRun落库一条triggerKind: event的 runscheduledFor为receivedAt debounceSeconds无 debounce 则立即。抑制原因会被完整记录CronEventSuppressionReason类型为duplicate_event | filter_mismatch | dedupe_window | cooldowncron-event-ingress.ts配合事件日志可审计“某个事件为什么没触发”。事件从摄入到运行的完整链路规范只是声明真正把pr-changelog-check跑起来的是事件摄入链路。第一步事件归一化CronEventIngress.ingestEvent首先调用normalizeEventcron-event-ingress.ts校验eventId/eventType/source规范化occurredAt为 ISO 时间戳并在未显式提供dedupeKey时按${eventType}:${source}:${subject ?? eventId}自动生成。随后store.insertEventLog做持久化先于匹配“Durable ingress for normalized automation events”——先落库再匹配即使后续处理失败也有事件日志可查。若该eventId已存在直接返回duplicate: true且抑制原因为duplicate_event。第二步规范匹配与 run 物化入口层通过store.listEventSpecsForType(eventType)取出所有声明event: github.pull_request.opened的规范逐个做automationEventMatchesFilters过滤匹配上的逐个走materializeForSpec即上一节讲的 debounce/dedupe/cooldown 判定。最终事件日志状态被写成三态之一unmatched无规范匹配、queued有 run 入队、suppressed全部被抑制。第三步谁来执行需要注意入口层的职责边界源码注释明确写着 “It deliberately does not execute agents; the normal runner claim loop owns execution”——摄入层只负责把cron_runs物化进队真正的 Agent 执行由 cron runner 的 claim 循环领取。每次 run 结束后报告会写入 cron-report-writer.ts 描述的~/.cline/cron/reports/run-id.mdworkspace scope 下则写到工作区旁报告中包含 YAML frontmatterrun ID、状态、耗时、token 用量、执行摘要、工具调用记录以及触发事件上下文——对事件驱动规范这意味着事后排查“这次检查为什么给出 ⚠️ 结论”时可以在报告里看到当时的 PR 事件 payload。事件从哪里来摄入渠道按 sdk/examples/cron/README.md 的说明归一化事件有四条摄入渠道GitHub App 或 webhook 接收器——pr-changelog-check的生产用法GitHub 推送pull_request.opened后由接收端归一化为AutomationEventEnvelope含eventType、subject如仓库名、attributes含pullRequest.baseBranch等并摄入插件事件——参考 automation-events.ts 插件自行emitConnector 适配器SDK 编程式摄入——cline.automation.ingestEvent(event)。该方法在 automation.ts 中由ClineCoreAutomationController.ingestEvent实现它委托CronService.ingestEvent并把入口层结果映射为对外 API 的ClineAutomationEventIngressResultevent、duplicate、matchedSpecIds、queuedRuns、suppressions供调用方判断事件是否真正触发了运行。本地无外部依赖地验证这套链路可以使用同目录的 local-manual-test.event.mdevent: local.manual_testdebounceSeconds: 0立即触发配合 hub WebSocket 客户端发送cron.event.ingest消息来演练而不必真的接 GitHub webhook。提示词设计一个双向的检查清单规范的正文部分就是 Agent 的系统级任务说明其价值在于定义了双向验证而非单向提醒方向一代码改了但 CHANGELOG 没改最常见的漏更新场景检测 PR 是否修改了源码文件src/、lib/等检查 PR 是否包含CHANGELOG.md或相关 changelog 的变更若有实质性代码变更但没有 changelog 更新提取变更摘要 → 建议应补充的条目 → 要求作者补写。方向二CHANGELOG 改了但质量不佳校验条目格式是否符合项目风格检查条目是否简洁、面向用户user-facing确认版本号是否恰当。最后以三种标准化的 PR 评论反馈✅ CHANGELOG properly updated通过⚠️ No CHANGELOG changes detected - please add an entry漏更新 CHANGELOG entry format seems off - consider [example]格式存疑并给出示例这套“三种状态 给出示例”的反馈设计使得 Agent 的评论对作者是可行动的actionable不是干巴巴地说“格式不对”而是附一个参照示例。它与 changelog-generator.cron.md定时从近期 commit 自动生成 changelog 条目形成互补——一个在 PR 关口“防守”一个在周五“主动生成”组合起来即可覆盖 README “Practical Automation Workflows” 中推荐的完整自动化套件里的 changelog 维护部分。部署步骤# 1. 创建事件规格目录 mkdir -p ~/.cline/cron/events # 2. 复制模板 cp sdk/examples/cron/events/pr-changelog-check.event.md ~/.cline/cron/events/ # 3. 编辑 spec # - workspaceRoot 改成你项目的绝对路径 # - filters.repository 改成 your-org/your-repo # - 按需要调整 debounceSeconds / cooldownSeconds / maxParallel # - 接入 GitHub App 或 webhook把 pull_request.opened 归一化后摄入启用自动化运行时三选一见 README// SDKClineCore 开启 automation const cline await ClineCore.create({ automation: true, // 布尔值会被 normalizeAutomationOptions 归一为空选项对象 });// Hub带 cronOptions 启动 new HubWebSocketServer({ cronOptions: { workspaceRoot: /absolute/workspace } });# CLI cline --enable-automation启动后 spec 会在 reconcile 阶段被加载此后每个满足过滤条件的github.pull_request.opened事件都会按“debounce 10s 合并 → 60s 冷却 → 最多 3 并发”的节奏触发一次 changelog 检查运行报告落在~/.cline/cron/reports/供追溯。适用边界与调整建议结合仓库事实使用这份模板时需要注意事件载荷契约filters的pullRequest.baseBranch能否命中取决于你的 webhook 接收端把 PR 属性放进了事件的attributes还是payload入口层会按attributes→payload→ 顶层字段的顺序解析点路径。接入 GitHub webhook 时应先本地ingestEvent一条样例事件用返回的suppressions中是否出现filter_mismatch来验证载荷结构模型与预算modelSelection固定了模型timeoutSeconds、maxIterations、tools如限制为run_commands,read_files只读工具 评论所需工具在本模板中均未显式设置生产环境建议像 pr-review.event.md 那样显式补齐timeoutSeconds: 1800、maxIterations与mode: act多仓库复用同一事件类型下多条规范会被逐一匹配listEventSpecsForType返回全部候选因此不同仓库可各建一份 spec通过filters.repository区分互不干扰但共享各自独立的冷却与并发预算非阻塞定位该自动化以“评论提醒”而非“卡 CI”的方式工作README 对姊妹规范 pr-test-coverage 也强调 “helpful rather than blocking”适合作为 changelog 维护的第一道自动化防线最终质量把关仍由 reviewer 完成。小结pr-changelog-check.event.md是 Cline 事件驱动自动化.event.mdspec的一个可直接上生产的模板它用eventfilters精确声明触发条件github.pull_request.opened、指定仓库、目标分支main用debounceSeconds/cooldownSeconds/maxParallel控制触发节奏10 秒合并、60 秒冷却、3 并发用双向检查清单式的提示词定义了 Agent 的具体职责与三态 PR 评论输出。其背后是 cron 事件入口层 提供的“先持久化、再过滤匹配、后物化 run”的可靠链路以及 ClineCore 自动化 API 暴露的编程式摄入入口。复制模板、改三个占位值workspaceRoot、filters.repository、模型、接上 webhook即可获得一个无需人工催促的 CHANGELOG 守卫。【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考