Cline SDK 事件驱动自动化local-plugin-event示例中插件事件发射、规范匹配与入库去重全解【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline本文以 Cline 仓库中的事件驱动自动化示例规范sdk/examples/cron/events/local-plugin-event.event.md为核心完整讲解一份.event.md规范如何由插件持续发射local.plugin_event事件、如何在入库层经过 filters 匹配与 dedupe/cooldown 节流后物化为自动化运行。读完后你可以复制该示例在自己的项目中跑通插件发事件 → 规范触发 → 生成报告的完整事件驱动链路并理解每个节流字段的底层实现语义。一、规范文件本体local-plugin-event.event.md全字段解读这份示例位于 local-plugin-event.event.md是一个典型的YAML frontmatter Markdown prompt 正文结构的文件。完整内容如下--- id: local-plugin-event title: Local Plugin Event workspaceRoot: /absolute/path/to/repo cwd: /absolute/path/to/repo event: local.plugin_event filters: topic: plugin-demo dedupeWindowSeconds: 5 cooldownSeconds: 5 maxParallel: 1 tags: - local - plugin - automation metadata: source: examples/plugins/automation-events.ts --- Summarize the local plugin event and report the event subject, topic, and message payload.逐字段说明字段的完整类型约束见 AutomationEventSpec 类型定义字段取值作用idlocal-plugin-event规范唯一标识字母数字与连字符是运行记录与报告中的稳定外部身份titleLocal Plugin Event人类可读标题用于列表 API 与报告展示workspaceRoot/absolute/path/to/repo运行时执行所针对的项目绝对路径示例中是占位符复制后必须替换cwd同workspaceRoot工作区内的运行目录运行时默认回退到workspaceRooteventlocal.plugin_event必填。触发的事件类型事件入库后按此类型检索候选规范filterstopic: plugin-demo可选过滤器支持点路径匹配事件字段用于在多个同类型规范间精确区分dedupeWindowSeconds5同一dedupeKey在 5 秒内重复到达时跳过防止同批事件重复触发cooldownSeconds5一次运行结束后 5 秒内不再接受新触发避免运行期间事件积压maxParallel1该规范最多 1 个并发运行保证插件事件串行处理tagslocal/plugin/automation自由标签用于分组检索metadatasource: examples/plugins/automation-events.ts自定义元数据按 JSON 原样持久化这里标记了事件来源插件正文 promptSummarize the local plugin event...就是运行期 Agent 收到的任务指令让 Agent 总结本次被触发的本地插件事件并报告事件的 subject、topic 与消息载荷。这与插件实际发射的事件字段见下文第二节一一对应。该示例的定位在 cron 示例总览中有明确说明Test spec for plugin-emitted events. Pairs withplugins/automation-events.ts.即它与 automation-events.ts 配对使用专门验证插件发出事件这一自动化来源且不依赖 GitHub 等外部服务——这也是它和local-manual-test.event.md走 WebSocket 手动注入local.manual_test事件的区别所在。二、事件源头automation-events.ts插件如何发射事件automation-events.ts 演示了插件侧的两件事声明归一化事件类型、周期性发射事件。其头部注释给出了本地演示的完整命令序列cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/automation-events.ts --cwd . mkdir -p .cline/cron/events cp examples/cron/events/local-plugin-event.event.md .cline/cron/events/local-plugin-event.event.md perl -0pi -e s#/absolute/path/to/repo#$PWD#g .cline/cron/events/local-plugin-event.event.md CLINE_LOCAL_EVENT_INTERVAL_MS2000 cline -i wait for the plugin event其中perl一行把规范中的占位路径/absolute/path/to/repo批量替换为当前项目路径CLINE_LOCAL_EVENT_INTERVAL_MS2000控制发射间隔。2.1 注册事件类型registerAutomationEventType插件在setup(api, ctx)阶段调用api.registerAutomationEventType({...})向 ClineCore 自动化子系统声明归一化事件类型local.plugin_eventapi.registerAutomationEventType({ eventType: local.plugin_event, source: local-plugin, description: Local normalized event emitted by a plugin, attributesSchema: { type: object, properties: { topic: { type: string } }, required: [topic], }, examples: [ /* 示例事件含 subject: plugin-demo、attributes: { topic: plugin-demo } */ ], });要点该 API 要求插件 manifest 声明capabilities: [automationEvents]否则注册会直接抛错。这一能力门控在 contribution-registry.ts 中强制执行registerAutomationEventType: (eventType) { if (!entry.manifest.capabilities.has(automationEvents)) { // 抛出 registerAutomationEventType requires the \automationEvents\ capability }attributesSchema声明了topic必填——这正好对应规范中filters.topic的匹配依据examples提供了一份完整示例事件供文档与工具链理解该事件形状的契约。2.2 周期性发射ctx.automation.ingestEvent当环境变量CLINE_LOCAL_EVENT_INTERVAL_MS为正数且运行上下文存在ctx.automation与会话 ID 时插件启动一个setInterval每intervalMs毫秒调用一次ingestEventvoid ctx.automation?.ingestEvent({ eventId: local-plugin-${Date.now()}, eventType: local.plugin_event, source: local-plugin, subject: plugin-demo, occurredAt: new Date().toISOString(), dedupeKey: local-plugin:plugin-demo, attributes: { topic: plugin-demo }, payload: { message: Hello from a plugin-emitted automation event. }, });三个对规范行为有直接影响的字段dedupeKey: local-plugin:plugin-demo是常量。若发射方不传dedupeKey入库层会按${eventType}:${source}:${subject ?? eventId}生成默认值见 cron-event-ingress.ts 的 normalizeEvent其中包含时间戳eventId默认 key 每次都会不同。插件显式固定 key正是为了让规范的dedupeWindowSeconds: 5能生效间隔 2 秒发射一次落在同一 5 秒去重窗口内的事件会被合并抑制。attributes.topic plugin-demo是filters.topic: plugin-demo的匹配来源。payload.message对应 prompt 中要求 Agent 报告的 message payload。此外插件用stopLocalEmittersMap 按 sessionId 记录清理函数重复setup时先停掉旧定时器再建新定时器避免同一会话内事件叠加发射。三、入库层实现事件如何命中规范并物化运行事件到达后由 CronEventIngress 处理。该类的注释明确其职责边界持久化收到的事件后为匹配的 event 规范物化cron_runs排队记录它刻意不执行 Agent执行由常规 runner 的 claim 循环负责。 对local-plugin-event这次触发而言完整链路是归一化与幂等去重。ingestEvent先 trim 各字段、把occurredAt归一为 ISO 时间非法值回退为接收时刻再写入事件日志表若同一eventId已存在直接返回duplicate: true不再进入匹配。按事件类型检索候选规范。store.listEventSpecsForType(local.plugin_event)取出所有监听该类型的规范local-plugin-event即其中之一。filters 匹配。automationEventMatchesFilters对filters的每个键做递归匹配。resolveFilterValue的取值顺序见 cron-event-ingress.ts是attributes中的直接键 →payload中的直接键 → 事件信封的点路径 →attributes点路径 →payload点路径。因此filters: { topic: plugin-demo }命中attributes.topic。不匹配的规范会被记为filter_mismatch抑制。三重节流materializeForSpec见 cron-event-ingress.tsdebounceSeconds本示例为 0未启用把窗口内重复触发合并为一个延后调度dedupeWindowSeconds: 5以specId dedupeKey为维度查询最近 5 秒内是否已有运行有则返回dedupe_window抑制cooldownSeconds: 5以specId为维度不区分 dedupeKey查询冷却期内的运行有则返回cooldown抑制。每次被抑制都会以CronEventSuppression记录原因dedupe_window/cooldown/filter_mismatch事件日志的处理状态会落成unmatched/queued/suppressed/failed之一便于排查为什么这条事件没触发运行。物化运行记录。通过节流后调用store.enqueueRun({ specId, specRevision, triggerKind: event, triggerEventId, scheduledFor })把事件与规范版本绑定进入常规 runner 队列执行。规范中的maxParallel: 1则是并发层面的约束限制该规范同时运行的数量。这套行为有专门的单测覆盖包括去重窗口、冷却与过滤器匹配等用例可参见 cron-event-ingress.test.ts。事件信封的完整字段eventId、eventType、source、subject、occurredAt、payload、attributes、dedupeKey定义在 AutomationEventEnvelope。四、启用自动化并观察运行报告规范放到.cline/cron/events/后需要自动化子系统处于开启状态cron 示例总览给出三种启用方式// Hubnew HubWebSocketServer({ cronOptions: { workspaceRoot: /absolute/workspace } })// SDK const cline await ClineCore.create({ automation: true });# CLI cline --enable-automation配合示例头部注释里的本地演示命令CLINE_LOCAL_EVENT_INTERVAL_MS2000 cline -i wait for the plugin event插件在会话中持续每 2 秒发射一个事件规范在 5 秒去重窗口 5 秒冷却 单并发的节流下被稳定触发而不是一次事件对应一次运行——这正是该示例把三个节流参数都设为小正数而非默认 0的用意用最小代价演示完整的防风暴语义。运行完成后报告写入.cline/cron/reports/run-id.md包含YAML frontmatter运行 ID、状态、耗时、token 用量、工作摘要、工具调用与结果以及事件触发场景下的触发事件上下文——对这份示例来说报告正文就是 Agent 对 subjectplugin-demo、topicplugin-demo和消息载荷Hello from a plugin-emitted automation event.的总结。五、从示例看.event.md的通用字段约定以local-plugin-event为最小参照事件驱动规范的字段约定如下摘自 cron 示例总览 的 Field Reference字段类型说明eventstring必填事件类型如本例local.plugin_event、GitHub 场景的github.pull_request.openedfiltersobject可选匹配事件字段支持点路径debounceSecondsnumber可选N 秒内合并事件默认 0dedupeWindowSecondsnumber可选N 秒内跳过重复事件默认 0cooldownSecondsnumber可选运行结束后等待 N 秒再触发默认 0maxParallelnumber可选最大并发运行数默认不限制通用字段id、title、workspaceRoot、mode、tools、systemPrompt、modelSelection、maxIterations、timeoutSeconds、extensions、tags、metadata在事件规范与周期规范间共享本示例使用了其中tags与metadata两项未写mode时按运行时默认处理。事件来源不限于插件同一套入库接口也接收 GitHub App/webhook 接收器、Connector 适配器以及 SDK 侧cline.automation.ingestEvent()的事件。local-plugin-event的价值在于它把整条链路事件类型声明 → 归一化发射 → 持久化 → filters 匹配 → 节流 → 运行物化 → 报告产出收敛在本地即可完成是排查事件为什么没触发/被抑制时最合适的最小复现样例配套的 cron-event-ingress.test.ts 则提供了各节流分支的可验证行为依据。【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考