Cline 事件驱动自动化本地验证：详解 local-manual-test 事件规范与 cron.event.ingest 接入链路

Cline 事件驱动自动化本地验证详解 local-manual-test 事件规范与 cron.event.ingest 接入链路【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline本篇技术文章以 Cline SDK 的本地手动事件测试规范 local-manual-test.event.md 为主体逐字段解析这份事件驱动event-driven自动化规格的全部配置项并结合 CronEventIngress 源码与核心测试用例讲清一个事件从ingestEvent注入到匹配规范、去重节流、入队执行的完整链路。读完本文你可以在不依赖任何外部服务GitHub、Webhook 等的前提下完成一次事件驱动自动化的端到端本地冒烟验证。一、规范本体local-manual-test.event.md 是什么事件驱动规范是 Cline 自动化体系中的第二类 spec第一类是按 cron 表达式周期执行的.cron.md。它由 YAML frontmatter声明触发条件与运行参数 正文作为该次运行的任务提示词组成。sdk/examples/cron/README.md 将local-manual-test定位为Local test spec for verifying event-driven automation without external services——即一个零外部依赖的本地事件测试模板。完整规范内容如下原文件仅 28 行此处完整继承并逐项展开--- id: local-manual-test title: Local Manual Event Test workspaceRoot: /absolute/path/to/repo cwd: /absolute/path/to/repo event: local.manual_test filters: topic: cron-feature-2 debounceSeconds: 0 dedupeWindowSeconds: 60 cooldownSeconds: 0 maxParallel: 1 mode: act enabled: true modelSelection: providerId: cline modelId: anthropic/claude-opus-4.7 timeoutSeconds: 300 maxIterations: 5 tags: - automation - local-test metadata: owner: platform source: local-smoke-test --- Use the normalized trigger event context to confirm event-driven automation is working locally. Summarize the event id, subject, topic, and payload message.这份规范的关键设计点event: local.manual_test是一个纯本地事件类型不绑定任何外部事件源filters.topic: cron-feature-2要求注入事件时 payload/attributes 中带有topic: cron-feature-2才会命中debounceSeconds: 0表示事件到达即触发不做合并等待正文提示词明确要求 Agent 输出event id、subject、topic、payload message——这正好构成了事件上下文是否被规范化注入到会话的验收断言。二、字段逐项解析每个参数控制什么结合 README.md 的 Field Reference 与 cron-event-ingress.ts 的实现各字段语义如下字段本规范取值含义与行为idlocal-manual-test规范唯一标识字母数字与连字符用于去重键、报告与查询titleLocal Manual Event Test人类可读标题出现在运行记录中workspaceRoot绝对路径占位符运行会话挂载的项目根目录复制模板后必须改成本地仓库路径cwd同workspaceRoot会话工作目录eventlocal.manual_test必填。事件类型只有该类型的归一化事件才会进入本规范的候选集filters{ topic: cron-feature-2 }可选过滤条件支持点路径逐项与事件的attributes→payload→ 信封字段做匹配debounceSeconds0合并窗口窗口内的后续同键事件不新建 run而是把已入队 run 的scheduledFor后移见下文源码0 表示立即触发dedupeWindowSeconds60去重窗口同一 dedupe key 在 60 秒内只触发一次窗口内的后续事件被抑制cooldownSeconds0运行级冷却距该规范上一次运行不足 N 秒则抑制0 表示不冷却maxParallel1该规范最大并发 run 数1 即串行modeact运行模式act可执行工具/plan只规划/yolo默认enabledtrue开关禁用后对账reconcile阶段跳过该规范modelSelectioncline提供商 anthropic/claude-opus-4.7覆盖本次运行的模型/提供商不写则用全局默认timeoutSeconds300单次运行 5 分钟超时maxIterations5迭代上限——测试规范故意设小保证冒烟失败时快速收敛tags/metadataautomation、local-testowner: platform、source: local-smoke-test分组标签与自由元数据不影响触发逻辑其中值得注意的工程取舍是dedupeWindowSeconds: 60与debounceSeconds: 0组合——事件到达立即入队但 60 秒内重复事件相同 dedupe key会被丢弃。这意味着连发 10 次测试事件只会跑一次验证即时触发的同时也验证了去重逻辑。2.1 dedupe key 从哪里来cron-event-ingress.ts 的normalizeEvent中若事件未显式提供dedupeKey引擎会按以下规则派生const dedupeKey trimOrUndefined(event.dedupeKey) ?? ${eventType}:${source}:${subject ?? eventId};即local.manual_test:local:manual smoke test这类形式。因此同一 subject 的重复事件自然落进同一个去重窗口这正是dedupeWindowSeconds: 60能生效的前提。2.2 filters 如何匹配resolveFilterValuecron-event-ingress.ts#L113-L144按优先级解析过滤键先查event.attributes的直接键再查event.payload的直接键然后按点路径依次在事件信封合成对象、attributes、payload中逐级下钻。matchesExpected支持数组任意命中与对象逐键全等的递归匹配。对本规范而言注入事件只要在attributes或payload中带topic: cron-feature-2filters即命中否则被记录为filter_mismatch抑制项。三、本地跑通从零到触发一次运行以下操作步骤完整继承自 README.md 中针对local-manual-test的 Usage 章节。第 1 步复制并修改规范mkdir -p ~/.cline/cron/events cp sdk/examples/cron/events/local-manual-test.event.md ~/.cline/cron/events/编辑复制后的文件把workspaceRoot/cwd两个占位符/absolute/path/to/repo改成本地仓库的绝对路径需要时调整modelSelection。规范放在.cline/cron/events/下会被 hub 或 SDK 在启动对账时拾取。第 2 步启用自动化三种入口任选其一README Enable automation 节Hub 方式new HubWebSocketServer({ cronOptions: { workspaceRoot: /absolute/workspace } })SDK 方式ClineCore.create({ automation: true, ... })CLI 方式cline --enable-automation。第 3 步注入测试事件README 给出的 Hub WebSocket 注入方式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 } }); cron.event.ingest是 Hub 协议中的标准命令定义在 sdk/packages/shared/src/hub.ts 的联合类型中第 599 行附近。事件来源除了这条 WebSocket 通道README 还列出了GitHub App / webhook 接收器、插件自发事件参见 plugins/automation-events.ts、Connector 适配器。第 4 步验收事件到达后Agent 会话以act模式运行最多 5 轮迭代、5 分钟超时运行结束或失败后报告写入.cline/cron/reports/run-id.md包含 YAML frontmatterrun ID、状态、耗时、token 用量、工作摘要、工具调用与结果事件触发型运行还会附带触发事件上下文对照规范正文提示词验收报告应能总结出注入事件的 id、subjecttest、topiccron-feature-2与 payload 消息hello。SDK 直接调用ingestEvent的方式在核心测试中有完整示例见下文第五节。四、引擎侧原理一个事件如何变成一次运行从源码结构看事件处理由 CronEventIngress 承担类注释明确其职责边界先持久化事件再匹配规范并为匹配规范物化materializequeued runs本层刻意不执行 Agent执行归 runner 的认领循环所有。ingestEvent的完整管线为归一化normalizeEventtrim 各字段、校验occurredAt的 ISO 格式非法则回退为接收时刻、补全dedupeKey、仅当payload/attributes是普通对象时才保留持久化并判重store.insertEventLog落库。若该事件已存在直接返回duplicate: true抑制原因为duplicate_event不再走匹配流程——这保证了事件日志的幂等按事件类型取候选规范store.listEventSpecsForType(eventType)。对本规范而言即取所有event: local.manual_test的规范逐规范判定filters不匹配 → 抑制原因filter_mismatch匹配后进入materializeForSpecL290-L356依次执行三级节流debouncedebounceSeconds 0时查找该 spec dedupe key 下已入队的 run存在则把其scheduledFor推进到max(原值, receivedAt debounce)并更新触发事件引用——即拖尾合并事件风暴收敛为一次延迟运行本规范取 0跳过此步scheduledFor receivedAt立即可认领dedupe windowdedupeWindowSeconds: 60生效——若 60 秒内该 dedupe key 已有事件 run抑制原因dedupe_windowcooldowncooldownSeconds: 0不检查三级全过 →store.enqueueRun({ triggerKind: event, triggerEventId, ... })入队回写事件日志状态unmatched无规范匹配/queued有 run 入队/suppressed全部被抑制/failed处理抛错并记录匹配数、入队数、抑制数。四个抑制原因枚举duplicate_event | filter_mismatch | dedupe_window | cooldownL23-L27正是本地冒烟时最直接的观测点连发重复事件应看到dedupe_window改错 topic 应看到filter_mismatch重复 eventId 应看到duplicate_event——一次测试即可覆盖全部触发与抑制路径。架构层面的完整描述可参考 sdk/ARCHITECTURE.md 的 automation 一节其中指出事件经cron.event.ingest命令进入。五、测试佐证ClineCore 如何验证该链路sdk/packages/core/src/ClineCore.test.ts 中的用例exposes event automation through ClineCore instead of CronService与本文档规范一一对应// 写入与 local-manual-test 同构的规范event: local.manual_test, filters.topic: cron-feature-2 const core await ClineCore.create({ automation: { cronDir, // root/.cline/cron reportsDir, // root/.cline/cron/reports dbPath, // root/.cline/data/db/cron.db autoStart: false, pollIntervalMs: 10_000, }, }); await core.automation.reconcileNow(); const result core.automation.ingestEvent({ eventId: evt_local_1, eventType: local.manual_test, source: local, subject: manual smoke test, occurredAt: 2026-04-24T10:00:00.000Z, attributes: { topic: cron-feature-2 }, // 命中 filters.topic }); expect(result.matchedSpecIds).toHaveLength(1); expect(result.queuedRuns).toHaveLength(1);断言要点ingestEvent同步返回matchedSpecIds与queuedRuns且各为 1——filters 的topic从attributes解析命中start()后runner 认领 run 并真正发起会话测试进一步断言host.runTurn的 prompt 包含Trigger event:L784-L789即触发事件上下文被规范化地注入了运行提示词——这正对应规范正文要求 Agent 总结的 normalized trigger event context目录布局约定规范放.cline/cron/events/报告落.cline/cron/reports/状态库在.cline/data/db/cron.dbSQLite与 sqlite-cron-store 的持久化设计一致。六、与相邻模板的对比与调参建议维度local-manual-testpr-reviewlocal-plugin-event事件类型local.manual_test手动注入github.pull_request.opened外部 webhooklocal.plugin_event插件自发过滤条件topic: cron-feature-2仓库/分支/labels 等topic: plugin-demo节流参数debounce 0 / dedupe 60 / cooldown 0debounce 30 / dedupe 600 / cooldown 120dedupe 5 / cooldown 5并发maxParallel: 1maxParallel: 2maxParallel: 1用途本地冒烟参数取最小/零值保证即时与可重复生产 PR 评审宽节流防打扰验证插件事件管道调参建议基于源码语义调试阶段保持debounceSeconds: 0接入真实高频事件源如 webhook 重试时提高 debounce 让事件风暴收敛为一次延迟运行dedupeWindowSeconds与cooldownSeconds的差别在于前者按dedupe key事件级去重后者按spec规范级冷却——同一规范下不同 subject 的事件也会受 cooldown 约束验证多规范并发时可将maxParallel提至 2 以上对照pr-review的取法冒烟场景保持maxIterations: 5、timeoutSeconds: 300的小值避免坏提示词消耗过多 token。小结local-manual-test.event.md 虽只有 28 行却是一个自洽的事件驱动自动化验收用例local.manual_test事件类型 topic过滤保证零外部依赖且断言面清晰debounce 0 / dedupe 60 / maxIterations 5的组合兼顾即时性与快速收敛。配合cron.event.ingestHub或core.automation.ingestEvent()SDK注入事件再检查.cline/cron/reports/run-id.md中是否包含触发事件上下文即完成一次覆盖归一化 → 判重 → 过滤 → 节流 → 入队 → 执行 → 报告全链路的本地验证。相关入口文档sdk/examples/cron/README.md、sdk/ARCHITECTURE.md。【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考