Cline SDK 事件系统详解从 AgentRuntimeEvent 到 CoreSessionEvent 的三层事件架构【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/clineCline SDK 的事件系统分为三层独立运行时Agent类发出的AgentRuntimeEvent、兼容旧版的内部适配层AgentEvent以及ClineCore面向订阅者的CoreSessionEvent。本文基于官方 SDK 技能参考文档与仓库源码完整梳理三层事件的类型定义、映射关系与订阅方式帮助你根据所用入口new Agent(...)还是ClineCore选择正确的事件 API正确实现流式文本渲染、工具调用日志、Token 用量与成本追踪等常见集成场景。一、三层事件体系总览Cline SDK 的哪一层事件会被发出取决于你使用的是独立的Agent类还是ClineCore会话门面。两者的事件类型形状不同不可混用如果你使用订阅方式接收的事件文本流式事件独立Agentagent.subscribe()AgentRuntimeEventassistant-text-deltaClineCorecline.subscribe()CoreSessionEventchunk其中payload.type text三层结构可以概括为Layer 1 —AgentRuntimeEventAgent类通过agent.subscribe()直接发出是运行时的一手事件源Layer 2 —AgentEventClineCore内部的RuntimeEventAdapter将 Layer 1 事件翻译成的旧版legacy格式订阅者不直接接触该层Layer 3 —CoreSessionEventClineCore通过cline.subscribe()发出的更高层会话事件当运行在 hub 模式时还有 Layer 3b 的 Hub 事件投影。二、Layer 1AgentRuntimeEvent独立 AgentAgentRuntimeEvent由Agent类经agent.subscribe()发出是直接使用new Agent(...)时的主要事件接口。每一个事件都携带一个snapshot字段其值为当前AgentRuntimeStateSnapshot即运行时的完整状态快照。在源码中AgentRuntimeEvent是一个判别联合discriminated union完整定义位于 agent.ts。其全部变体如下。2.1 Run 生命周期{ type: run-started, snapshot } { type: run-finished, snapshot, result: AgentRunResult } { type: run-failed, snapshot, error: Error }其中AgentRunResult在 agent.ts 中定义包含agentId、runId、statuscompleted | aborted | failed、iterations、outputText、messages与usage等字段。源码中run-failed变体还带有可选的errorClass字段context_window_exceeded | auth | unknown用于标识 provider 侧错误类别便于宿主机做针对性恢复或提示。2.2 Turn回合{ type: turn-started, snapshot, iteration: number } { type: turn-finished, snapshot, iteration: number, toolCallCount: number }iteration标识当前是第几轮模型请求—工具执行循环turn-finished额外携带本轮的工具调用次数toolCallCount可用于判断该轮是否发生了工具执行。2.3 文本流式// 流式文本增量生成过程中以 chunk 形式到达 { type: assistant-text-delta, snapshot, iteration: number, text: string, accumulatedText: string } // 流式推理增量模型使用扩展思考时 { type: assistant-reasoning-delta, snapshot, iteration: number, text: string } // 模型完成后发出的完整助手消息 { type: assistant-message, snapshot, iteration: number, message: AgentMessage, finishReason: string }从 agent.ts 的完整定义可以看出assistant-reasoning-delta实际上还携带accumulatedText、redacted推理内容是否被 provider 脱敏与metadata字段assistant-message的finishReason类型为AgentModelFinishReason即stop | tool-calls | max-tokens | aborted | error。此外源码中还定义了文档未重点列出的assistant-media变体用于承载模型生成的媒体内容media: GeneratedMedia。流式渲染时通常只需assistant-text-delta的text字段做增量输出而accumulatedText可用于全量重绘或状态记录。2.4 消息// 每当任何消息用户或助手被加入会话历史时触发 { type: message-added, snapshot, message: AgentMessage }AgentMessage的定义见 agent.ts包含id、roleuser | assistant | tool、contentAgentMessagePart[]可含文本、推理、图片、文件、工具调用/结果等部件、createdAt时间戳以及可选的metricsToken 用量与成本与modelInfo。2.5 工具事件{ type: tool-started, snapshot, toolCall: { toolName: string, toolCallId: string, input: unknown } } { type: tool-updated, snapshot, toolCall: { toolName: string, toolCallId: string }, update: string } { type: tool-finished, snapshot, toolCall: { toolName: string, toolCallId: string }, message: AgentMessage }三个事件构成一次工具调用的完整生命周期tool-started给出工具名、调用 ID 与输入参数tool-updated携带执行过程中的进度更新update字段tool-finished的message字段为AgentMessage其content中包含tool-result部件可从源码 agent.ts 看到该部件携带output、isError与executionclient | provider标识执行方是 SDK 客户端还是模型 provider等信息。2.6 用量Usage{ type: usage-updated, snapshot, usage: { inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number, totalCost?: number, }, }对照源码 agent.tsusage的标准形状AgentUsage继承自AgentTokenUsage后者包含inputTokens、outputTokens、cacheReadTokens、cacheWriteTokens与可选的reasoningTokenCountprovider 报告的隐藏推理 TokenAgentUsage在其上追加totalCost。2.7 状态通知{ type: status-notice, snapshot, message: string, metadata?: Recordstring, unknown }status-notice用于运行时向订阅者推送状态类消息例如自动压缩上下文等场景metadata.reason字段从源码适配逻辑看可取auto_compaction、manual_compaction、compaction_budget_emergency等值见 runtime-event-adapter.ts 中的resolveStatusNoticeReason。2.8 订阅agent.subscribe() 与 hooks必须在使用run()之前注册监听器以免错过早期事件。const agent new Agent({ providerId: anthropic, modelId: claude-sonnet-4-6, apiKey: process.env.ANTHROPIC_API_KEY, systemPrompt: You are a helpful assistant., tools: [], }) agent.subscribe((event) { switch (event.type) { case assistant-text-delta: process.stdout.write(event.text) break case tool-started: console.log(\nUsing tool: ${event.toolCall.toolName}) break case usage-updated: console.log(Cost: $${event.usage.totalCost?.toFixed(4)}) break case run-finished: console.log(\nDone: ${event.result.status}) break } }) const result await agent.run(Hello!)除了subscribe()还可以通过 hooks 接收事件。与subscribe()不同hooks 中的事件回调会被 await因此可以写成异步函数const agent new Agent({ ...config, hooks: { onEvent: async (event) { // 与 subscribe() 相同的 AgentRuntimeEvent 类型 }, }, })这一区别对集成很重要subscribe()的监听器是同步通知适合打日志和渲染hooks.onEvent会被运行时等待完成适合需要阻塞语义的场景如遥测上报后再继续。三、Layer 2AgentEventClineCore 内部适配层使用ClineCore时RuntimeEventAdapter会将 Layer 1 事件翻译成旧版格式AgentEvent。订阅者不直接与该层交互——它被投影到 Layer 3 的CoreSessionEvent中供订阅。主要映射关系如下AgentRuntimeEventLayer 1AgentEventLayer 2turn-startediteration_startturn-finishediteration_endassistant-text-deltacontent_starttextassistant-messagecontent_endtexttool-startedcontent_starttooltool-updatedcontent_updatetooltool-finishedcontent_endtoolusage-updatedusage带计算的增量run-finisheddonerun-failederrorrun-started、message-added被抑制不发出这一层存在的意义是向后兼容如果在其他文档中见到content_update、iteration_start这类事件名它们指的是这一层而非agent.subscribe()所发出的类型。3.1 源码验证RuntimeEventAdapter 的有状态翻译该层的完整实现位于 runtime-event-adapter.ts其中有几个值得注意的实现细节1. 每个订阅者一个适配器实例且是有状态的。RuntimeEventAdapter类L174-L285的translate(event)方法可能返回 0、1 或 2 个AgentEvent——因为一条assistant-message若同时包含文本与推理部件会分别产生content_endtext和content_endreasoning两条事件而run-started与message-added返回空数组即被有意抑制。2. 用量增量是算出来的。Layer 1 的usage-updated携带的是累计快照而旧版usage事件同时要求本轮增量和累计总量。适配器内部保存上一次累计值lastUsage用本次快照减去上次快照得到 deltatranslateUsage并对 Token 与成本增量做Math.max(0, ...)兜底增量为零时置为undefined。3. 工具耗时在适配层补全。Layer 1 的tool-finished不携带durationMs。适配器在tool-started时记录Date.now()以toolCallId为键在tool-finished时计算并填入durationMstranslateToolFinished。4. 每次新 run 开始时重置状态。reset()方法会清零lastUsage与toolStartedAt保证跨 run 不残留脏状态。5. 文件头部注释解释了与规划文档的偏差。值得注意的是 文件头注释assistant-text-delta并不是首个 delta 发 content_start后续发 content_update而是每一个文本 delta 和推理 delta 都发content_start——因为旧版类型AgentContentUpdateEvent.contentType被硬编码为tool文本增量无法走content_update。适配器选择保留所有旧版消费方依赖的可观察行为。这解释了上表中assistant-text-delta → content_start (text)的映射为何对每个 delta 都成立。源码还提供了一个无状态便捷函数toLegacyAgentEventL452-L458仅适用于单事件的一次性翻译此时无法计算 usage 增量与 durationMs生产代码必须使用RuntimeEventAdapter处理多事件运行。四、Layer 3CoreSessionEventClineCore 订阅者CoreSessionEvent由ClineCore经cline.subscribe()发出是更高层的会话事件形状如下type CoreSessionEvent | { type: chunk; payload: SessionChunkEvent } | { type: agent_event; payload: { sessionId: string, event: AgentEvent } } | { type: ended; payload: SessionEndedEvent } | { type: team_progress; payload: SessionTeamProgressEvent } | { type: status; payload: { sessionId: string, status: string } } | { type: hook; payload: SessionToolEvent }其中关键 payload 类型为interface SessionChunkEvent { type: text | reasoning text: string sessionId: string } interface SessionEndedEvent { sessionId: string finishReason: completed | max_iterations | aborted | mistake_limit | error result?: AgentResult }在仓库源码中CoreSessionEvent的当前定义位于 types/events.ts。可以推断该类型随 SDK 演进有所扩展当前版本还包含pending_prompts、pending_prompt_submitted、session_snapshot等变体且agent_event的 payload 在团队场景下额外携带teamAgentId与teamRolelead | teammate字段SessionChunkEvent/SessionEndedEvent的字段在内部实现中也带有stream、chunk、reason、ts等更贴近宿主传输层的属性。以你使用的 SDK 版本实际类型定义为准即可。4.1 订阅示例cline.subscribe((event) { switch (event.type) { case chunk: if (event.payload.type text) { process.stdout.write(event.payload.text) } break case ended: console.log(Finished: ${event.payload.finishReason}) break } })由于ClineCore是会话门面一个实例可承载多个会话因此cline.subscribe()支持按会话过滤cline.subscribe(handler, { sessionId: specific-session-id })不传过滤条件时handler 会收到所有会话的事件可通过 payload 中的sessionId自行分发。五、Hub EventsLayer 3b当ClineCore运行在 hub 模式通过backendMode: hub或在 hub 可用时的auto下事件会通过 WebSocket 以HubEventName类型投影传输例如assistant.delta、iteration.started、tool.started等。对使用者而言这层是透明的无论你处于何种后端模式cline.subscribe()给你的始终是CoreSessionEvent不需要针对 hub 模式改写订阅代码。Hub 事件投影的实现可参考仓库中的 hub-server-transport.ts 与 session-event-projector.ts。六、结果类型差异独立Agent与ClineCore返回的结果类型不同取文本时的属性名也不同这是集成中最容易踩的坑API结果类型文本属性agent.run()AgentRunResultresult.outputTextcline.start()/cline.send()AgentResultresult.textAgentRunResult的完整字段agentId、runId、status、iterations、outputText、messages、usage可参考 agent.ts。七、常见集成模式7.1 流式文本独立 Agentagent.subscribe((event) { if (event.type assistant-text-delta) { process.stdout.write(event.text) } })7.2 流式文本ClineCorecline.subscribe((event) { if (event.type chunk event.payload.type text) { process.stdout.write(event.payload.text) } })7.3 用量追踪独立 Agentagent.subscribe((event) { if (event.type usage-updated event.usage.totalCost) { console.log(Running cost: $${event.usage.totalCost.toFixed(4)}) } })由于usage-updated携带的是累计值该模式输出的是运行至今的总成本而非单轮增量——单轮增量需要自行保存上次值做差Layer 2 的适配器正是这么做的。7.4 工具调用日志独立 Agentagent.subscribe((event) { if (event.type tool-started) { console.log(Tool started: ${event.toolCall.toolName}) } if (event.type tool-finished) { console.log(Tool finished: ${event.toolCall.toolName}) } })八、小结与延伸阅读Cline SDK 事件系统的核心要点先选入口再选事件层new Agent(...)订阅AgentRuntimeEventassistant-text-delta流文本ClineCore订阅CoreSessionEventchunk流文本。两者形状不同不可混用。Layer 2 是兼容层AgentEventiteration_start、content_update等旧事件名只存在于ClineCore内部的RuntimeEventAdapter翻译链中其有状态特性usage 增量计算、工具耗时补全是理解为什么 usage 事件同时带增量和累计值的关键。hub 模式对订阅者透明cline.subscribe()恒定返回CoreSessionEvent。结果类型不同AgentRunResult.outputTextvsAgentResult.text。仓库中相关的深入文档Agent 运行时参考Agent 运行时总览ClineCore 参考ClineCore 会话管理Plugins 参考插件钩子与生命周期事件Production 参考生产环境的可观测性实践。核心类型定义与适配实现可分别查看 AgentRuntimeEvent 联合类型、CoreSessionEvent 定义 与 RuntimeEventAdapter 实现。【免费下载链接】clineAutonomous coding agent as an SDK, IDE extension, or CLI assistant.项目地址: https://gitcode.com/GitHub_Trending/cl/cline创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考