用 MLflow Tracing 自动观测 OpenCode 智能体会话mlflow/opencode 插件接入与原理全解析【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflowMLflow 在 libs/typescript/integrations/opencode 目录下提供了mlflow/opencodeTypeScript 插件可对 OpenCode 终端智能体工具的对话会话进行自动埋点会话空闲idle时自动创建 MLflow Trace完整记录用户提示词、助手回复、LLM 调用的 token 用量、工具调用及其结果和会话元数据。本文以该插件为骨架结合其源码实现src/index.ts与测试用例tests/index.test.ts展开读完即可完成接入、掌握其配置参数含义并理解 trace/span 数据模型与增量去重机制可直接在生产工作流中落地智能体可观测性。一、插件定位为 OpenCode 补齐智能体可观测性mlflow/opencode是 MLflow Tracing 体系下的 OpenCode 集成包package.json 中描述为 OpenCode integration package for MLflow Tracing版本 0.4.0。它的核心价值在于零侵入开发者无需修改 OpenCode 内部的任何调用逻辑只要把插件挂载进 OpenCode 的插件配置再设定两个环境变量后续每个会话的完整执行过程就会被自动上报到 MLflow。插件自动捕获四类数据源自 README用户提示词与助手响应User prompts and assistant responses带 token 用量的 LLM 调用LLM calls with token usage工具调用及结果Tool invocations and results会话元数据Session metadata从实现上看它直接复用mlflow/coreTypeScript SDK依赖声明为mlflow/core: ^0.4.0见 package.json并通过 OpenCode 官方插件协议peerDependencyopencode-ai/plugin: ^1.0.0暴露一个事件型插件。整体链路可概括为OpenCode 会话 → 触发 session.idle 事件 → 插件拉取会话消息 → 用 mlflow/core 构建 AGENT/LLM/TOOL 三层 span → flushTraces() 上报 MLflow二、安装与快速接入三步让 OpenCode 会话自动入 Trace1. 安装插件在项目或全局中安装插件及其底层 SDKnpm install mlflow/opencode mlflow/core注意源码头部注释明确要求同时安装两个包见 src/index.ts因为插件运行期会从mlflow/core导入init、startSpan、withSpan、updateCurrentTrace、flushTraces、SpanType、SpanAttributeKey等符号。2. 注册到 opencode.json在 OpenCode 的配置文件opencode.json中声明插件{ plugin: [mlflow/opencode] }插件导出的是MLflowTracingPlugin默认导出同名函数见 src/index.tsOpenCode 加载后会调用该函数并注入插件客户端client插件据此订阅事件钩子。3. 设置环境变量export MLFLOW_TRACKING_URIhttp://localhost:5000 export MLFLOW_EXPERIMENT_ID1234. 正常运行 OpenCode之后正常使用 OpenCode 即可无需任何额外操作——插件只在会话变为空闲时触发追踪Run OpenCode normally - traces are created automatically when sessions become idle.README三、配置参数详解三个环境变量与底层解析逻辑插件完全通过环境变量配置README 原文即为 The plugin is configured via environment variables变量必填说明MLFLOW_TRACKING_URI是MLflow tracking server 地址例如http://localhost:5000MLFLOW_EXPERIMENT_ID是MLflow 实验 IDMLFLOW_OPENCODE_DEBUG否设为true时开启调试日志结合 src/index.ts 的ensureInitialized()实现可以进一步确认这三个变量的真实行为两个必填项缺一不可函数按顺序检查MLFLOW_TRACKING_URI与MLFLOW_EXPERIMENT_ID任一缺失都会返回falseSDK 初始化被跳过该次事件直接放弃处理。测试用例 tests/index.test.ts 也分别验证了未设置 TRACKING_URI 时不拉取消息和未设置 EXPERIMENT_ID 时不拉取消息两个分支。初始化是惰性且只做一次的initialized标志位保证 SDK 只在首次收到session.idle事件时初始化一次成功设置后不再重复调用init({ trackingUri, experimentId })。调试日志刻意静默插件默认不做任何控制台输出原因是避免污染 OpenCode 的 TUI 界面源码注释 Silent plugin - no console output to avoid TUI interference。只有MLFLOW_OPENCODE_DEBUG true时才会通过console.error输出[mlflow]前缀的调试信息例如SDK initialized successfully、Creating trace for session: xxx、Created trace: xxx等。调试输出统一走console.error而非console.log同样是为减少对终端 UI 的干扰。取值建议MLFLOW_TRACKING_URI需要指向一个已运行的 MLflow server本地mlflow server默认监听 5000 端口MLFLOW_EXPERIMENT_ID可先在 MLflow UI 中创建实验后取得数字 ID或通过mlflow experiments create创建。四、运行原理session.idle 事件驱动的自动追踪管线插件不是一个持续运行的 trace 采集器而是一个事件响应器。其完整工作流如下订阅事件钩子MLflowTracingPlugin返回{ event }钩子OpenCode 每次产生事件都会回调。事件过滤只有event.type session.idle才会继续处理且事件属性中必须携带sessionID否则直接返回对应 src/index.ts。测试明确覆盖了非 session.idle 事件不处理与无 sessionID 不处理两条路径。SDK 惰性初始化调用ensureInitialized()环境变量不满足则放弃。拉取会话消息通过插件客户端调用client.session.messages({ path: { id: sessionID }, query: { limit: 1000 } })一次最多取 1000 条消息。增量判定与去重将当前消息总数与该会话上次已处理数量比对详见下文第六节无新消息则跳过。构建 Trace 并上报对新消息调用processSession()构建 trace 后调用flushTraces()刷入 MLflow。其中processSession()src/index.ts是核心建链逻辑它有几个值得注意的防御性前置校验消息列表为空 → 跳过找不到任何user角色消息 → 跳过无用户输入就没有对话可追踪提取不到用户提示词文本 → 跳过。时间信息贯穿整个链路OpenCode 消息自带毫秒级时间戳info.time.created/completed插件通过timestampToNs()统一换算为纳秒NANOSECONDS_PER_MS 1e6后写入 span 的startTimeNs/endTimeNstrace 的起止时间分别取本批首条消息的created与末条消息的completed缺失时回退到created。五、Trace 数据模型AGENT 父 Span LLM/TOOL 子 Span 三层结构每个 OpenCode 会话在 MLflow 中落地为一个 trace其内部呈1 个 AGENT 父 span N 个 LLM/Tool 子 span的树状结构。1. 父 Spanopencode_conversation通过withSpan()创建名为opencode_conversation、spanType: SpanType.AGENT的父 spansrc/index.tswithSpan( (parentSpan) { /* 创建子 span、附加元数据、结束父 span */ }, { name: opencode_conversation, inputs: { prompt: userPrompt }, startTimeNs: createdNs, spanType: SpanType.AGENT, }, );选择withSpan而非startSpan是有意为之它会让父 span 成为 OTel 上下文中的当前 span从而允许插件通过公开 APIupdateCurrentTrace而非侵入InMemoryTraceManager内部为整个 trace 附加元数据。父 span 结束时写入outputsparentSpan.setOutputs({ response: finalResponse || Conversation completed, status: completed, });2. Trace 级元数据与预览通过updateCurrentTrace写入四类信息src/index.ts字段值说明metadata[mlflow.trace.session]sessionId关联 OpenCode 会话 IDmetadata[mlflow.trace.user]process.env.USER当前系统用户requestPreview用户提示词前 1000 字符便于在 UI 快速预览responsePreview助手最终回复前 1000 字符有最终回复时才写入MAX_PREVIEW_LENGTH 1000是预览内容的上限常量。源码注释特别说明插件刻意用 metadata 键mlflow.trace.session/mlflow.trace.user而非updateCurrentTrace的sessionId/user便捷参数是因为后者以及TraceMetadataKey枚举只在更新的mlflow/core版本中存在而这两个 metadata 键在各发布版本中保持稳定从而兼容更广的 SDK 版本范围。3. LLM Spanllm_call对每条助手消息只要含文本、工具调用或 reasoning 中任一内容创建一个llm_callspanSpanType.LLM记录src/index.tsinputs.model${providerId}/${modelId}如anthropic/claude-3-opusinputs.messages重建的对话历史见下文会话历史重建attributesmodel、providertoken 用量通过SpanAttributeKey.TOKEN_USAGE写入由buildTokenUsage()组装。token 用量的字段结构buildTokenUsage{ input_tokens: 输入 token 数, output_tokens: 输出 token 数, total_tokens: input output reasoning, // reasoning 计入总量 cache_read_tokens: 缓存读取数, // 有缓存信息时才有 cache_write_tokens: 缓存写入数, // 有缓存信息时才有 }LLM span 的outputs采用OpenAI chat-completion 消息形状choices[0].message这是与 codex、qwen-code 等其他集成保持一致的关键设计源码注释明确指出这一点目的是让 MLflow 的Chat 视图能正确渲染工具调用{ role: assistant, content: 文本内容无文本时为 null, reasoning: 推理内容仅当存在 reasoning part 时, tool_calls: [ { id: callID, type: function, function: { name: 工具名, arguments: JSON 字符串化的输入 } } ] }一个细节只有文本的工具调用消息同样会被记录为 LLM span。源码注释解释了原因——像 prometheus 这类 agent 会连续多次发出工具调用而不夹带文本若跳过这些消息会导致大量 span 缺失、trace 空洞。对应测试 should create LLM span for tool-call-only assistant messages 专门复现并回归了这一场景。4. Tool Spantool_对每条工具调用 part 创建tool_工具名spanSpanType.TOOL记录src/index.tsinputs工具入参state.inputattributestool_name、tool_idcallID、statuscompleted/error等outputs按状态区分——completed时写result与titleerror时写error信息时间state.time.start/end换算为纳秒。5. 会话历史重建为了让每次 LLM 调用的inputs.messages呈现完整上下文插件实现了reconstructConversationMessages()src/index.ts将 OpenCode 的消息数组转换为标准对话格式user消息拼接全部文本 partassistant消息content拼接文本 partreasoning拼接推理 part存在时tool消息将已完成status completed的工具调用转为{ role: tool, tool_call_id, content: 输出 }。测试用例用一段用户提问 → 助手推理并调用工具 → 助手自主续作再调工具 → 汇总 → 追问 → 回复的 8 条消息序列逐条断言了重建后历史中 3 条 user、4 条 assistant、2 条 tool 消息的完整结构与顺序可作为理解该逻辑的最佳示例见 tests/index.test.ts。六、增量追踪与去重机制避免重复 Trace 的工程细节OpenCode 的session.idle事件在一个会话中可能多次触发每次用户停止交互都可能空闲。若每次空闲都全量建 trace会造成大量重复。插件的解决方案是基于消息计数的增量追踪const processedMessageCounts new Mapstring, number();逻辑如下src/index.ts拉取全部消息后取其总数messageCount与processedMessageCounts中该会话上次已处理数量lastProcessedCount比较若messageCount lastProcessedCount说明没有新消息直接返回同一轮次不会被处理两次否则用allMessages.slice(lastProcessedCount)只取新增的消息建 trace并更新计数计数器使用LRU 语义维护每次事件都会先delete再set将该会话移到 Map 末尾保证活跃会话即便没有新消息不会被提前淘汰Map 超过 50 个会话时逐出最久未访问的条目防止长期运行造成内存泄漏。测试对此有直接覆盖should not process the same turn twice同一会话同消息数第二次触发不新增 span与 should process new messages in existing session追加消息后再次触发只处理增量。值得注意的是由于 trace 的起止时间取自本批新消息的首尾时间戳增量上报的每个 trace 天然按对话轮次切分便于在 UI 中按轮查看。七、查看 TraceMLflow UI 侧操作追踪数据上报后按 README 的说明启动 MLflow server 并打开 UImlflow server # 浏览器打开 http://localhost:5000在 MLflow UI 中进入对应实验MLFLOW_EXPERIMENT_ID指定的实验即可看到 OpenCode 会话生成的 trace 列表。得益于第五节的 span 结构与 OpenAI 消息形状设计可以在 Chat 视图中直接回放整个智能体对话用户提示、assistant 的推理与回复、工具调用的入参与结果按时间线排列同时可查看每次 LLM 调用的model、provider与token_usage明细以及 trace 级的mlflow.trace.session/mlflow.trace.user元数据用于按会话、按用户筛选。八、边界行为与异常处理源码级确认结合 src/index.ts 与 tests/index.test.ts 的 Edge Cases 分组插件对以下边界情况均有明确行为场景行为环境变量缺失静默跳过调试模式仅输出[mlflow]日志不拉消息、不建 trace非session.idle事件 / 无sessionID直接返回空消息数组不建 trace会话中无 user 消息不建 traceuser 消息无文本内容不建 trace消息缺少parts字段优雅降级不建 trace工具调用缺少state仍创建 tool span用默认值兜底status: unknown、空输出拉取消息失败data为空放弃本次处理不影响插件运行工具状态为errortool span 的 outputs 记录error字段而非 result此外插件还有一处兼容性设计值得留意调试模式下即使 SDK 初始化失败也只会输出日志而不会抛出异常打断 OpenCode 主流程消息处理循环外包了 try/catch任何单个会话的处理异常都不会影响后续事件。九、测试与工程质量mlflow/opencode的测试体系tests/index.test.ts通过 mockmlflow/core模块与 mock OpenCode 插件客户端覆盖了以下分组插件初始化导出函数形态、返回 Promise 及 event 钩子环境变量处理三个分支缺 URI / 缺 ID / 双全下的行为事件过滤事件类型与 sessionID 校验LLM 调用追踪文本回复、token 用量、多轮会话多 span、不同模型openai/gpt-4、reasoning 内容、纯 reasoning 无文本等工具调用追踪completed / error / 多工具连续调用 / 文本工具混合 / Edit、Write、Bash 等常见工具Agent 工作流完整LLM工具回复链路、多步 agentRead→Edit→回复逐条建 LLM span、纯工具调用消息不丢 span重复轮次防护同轮不重复处理、新消息增量处理Trace 元数据mlflow.trace.session/mlflow.trace.user/ 双 preview 断言时间信息span 与 tool span 的纳秒时间戳会话历史重建含 reasoning、tool result 的完整历史结构。mock 定义见 tests/mocks/opencode-ai/plugin.ts其中PluginClient接口给出了插件所依赖的 OpenCode 客户端能力session.messages印证了插件与 OpenCode 协议的最小耦合面。十、源码路径索引如需深入源码可按以下路径继续探索插件主体实现libs/typescript/integrations/opencode/src/index.ts插件测试含大量可参考的消息构造辅助函数libs/typescript/integrations/opencode/tests/index.test.ts插件元信息版本、依赖、Node 版本要求18、Apache-2.0 许可证libs/typescript/integrations/opencode/package.json底层 TypeScript SDK 核心init位于 libs/typescript/core/src/core/config.tsstartSpan/withSpan/updateCurrentTrace位于 libs/typescript/core/src/core/api.tsflushTraces位于 libs/typescript/core/src/core/provider.tsSDK 使用概览libs/typescript/core/README.md同类智能体集成参考同为 OpenAI 消息形状设计libs/typescript/integrations/qwen-code结语mlflow/opencode展示了事件驱动 增量建链的智能体可观测性集成范式以 OpenCode 的session.idle事件为触发点用约 600 行的单文件实现把会话消息完整映射为 AGENT/LLM/TOOL 三层 trace 结构并通过 OpenAI chat-completion 消息形状保持与 MLflow Chat 视图及其他集成的一致性。对于希望以低成本获得 OpenCode 开发过程全量可观测、可复盘、可评估能力的团队而言这是一条开箱即用的路径——安装一个包、配置一行 JSON、导出两个环境变量即可。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 MLflow Tracing 自动观测 OpenCode 智能体会话：@mlflow/opencode 插件接入与原理全解析
用 MLflow Tracing 自动观测 OpenCode 智能体会话mlflow/opencode 插件接入与原理全解析【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflowMLflow 在 libs/typescript/integrations/opencode 目录下提供了mlflow/opencodeTypeScript 插件可对 OpenCode 终端智能体工具的对话会话进行自动埋点会话空闲idle时自动创建 MLflow Trace完整记录用户提示词、助手回复、LLM 调用的 token 用量、工具调用及其结果和会话元数据。本文以该插件为骨架结合其源码实现src/index.ts与测试用例tests/index.test.ts展开读完即可完成接入、掌握其配置参数含义并理解 trace/span 数据模型与增量去重机制可直接在生产工作流中落地智能体可观测性。一、插件定位为 OpenCode 补齐智能体可观测性mlflow/opencode是 MLflow Tracing 体系下的 OpenCode 集成包package.json 中描述为 OpenCode integration package for MLflow Tracing版本 0.4.0。它的核心价值在于零侵入开发者无需修改 OpenCode 内部的任何调用逻辑只要把插件挂载进 OpenCode 的插件配置再设定两个环境变量后续每个会话的完整执行过程就会被自动上报到 MLflow。插件自动捕获四类数据源自 README用户提示词与助手响应User prompts and assistant responses带 token 用量的 LLM 调用LLM calls with token usage工具调用及结果Tool invocations and results会话元数据Session metadata从实现上看它直接复用mlflow/coreTypeScript SDK依赖声明为mlflow/core: ^0.4.0见 package.json并通过 OpenCode 官方插件协议peerDependencyopencode-ai/plugin: ^1.0.0暴露一个事件型插件。整体链路可概括为OpenCode 会话 → 触发 session.idle 事件 → 插件拉取会话消息 → 用 mlflow/core 构建 AGENT/LLM/TOOL 三层 span → flushTraces() 上报 MLflow二、安装与快速接入三步让 OpenCode 会话自动入 Trace1. 安装插件在项目或全局中安装插件及其底层 SDKnpm install mlflow/opencode mlflow/core注意源码头部注释明确要求同时安装两个包见 src/index.ts因为插件运行期会从mlflow/core导入init、startSpan、withSpan、updateCurrentTrace、flushTraces、SpanType、SpanAttributeKey等符号。2. 注册到 opencode.json在 OpenCode 的配置文件opencode.json中声明插件{ plugin: [mlflow/opencode] }插件导出的是MLflowTracingPlugin默认导出同名函数见 src/index.tsOpenCode 加载后会调用该函数并注入插件客户端client插件据此订阅事件钩子。3. 设置环境变量export MLFLOW_TRACKING_URIhttp://localhost:5000 export MLFLOW_EXPERIMENT_ID1234. 正常运行 OpenCode之后正常使用 OpenCode 即可无需任何额外操作——插件只在会话变为空闲时触发追踪Run OpenCode normally - traces are created automatically when sessions become idle.README三、配置参数详解三个环境变量与底层解析逻辑插件完全通过环境变量配置README 原文即为 The plugin is configured via environment variables变量必填说明MLFLOW_TRACKING_URI是MLflow tracking server 地址例如http://localhost:5000MLFLOW_EXPERIMENT_ID是MLflow 实验 IDMLFLOW_OPENCODE_DEBUG否设为true时开启调试日志结合 src/index.ts 的ensureInitialized()实现可以进一步确认这三个变量的真实行为两个必填项缺一不可函数按顺序检查MLFLOW_TRACKING_URI与MLFLOW_EXPERIMENT_ID任一缺失都会返回falseSDK 初始化被跳过该次事件直接放弃处理。测试用例 tests/index.test.ts 也分别验证了未设置 TRACKING_URI 时不拉取消息和未设置 EXPERIMENT_ID 时不拉取消息两个分支。初始化是惰性且只做一次的initialized标志位保证 SDK 只在首次收到session.idle事件时初始化一次成功设置后不再重复调用init({ trackingUri, experimentId })。调试日志刻意静默插件默认不做任何控制台输出原因是避免污染 OpenCode 的 TUI 界面源码注释 Silent plugin - no console output to avoid TUI interference。只有MLFLOW_OPENCODE_DEBUG true时才会通过console.error输出[mlflow]前缀的调试信息例如SDK initialized successfully、Creating trace for session: xxx、Created trace: xxx等。调试输出统一走console.error而非console.log同样是为减少对终端 UI 的干扰。取值建议MLFLOW_TRACKING_URI需要指向一个已运行的 MLflow server本地mlflow server默认监听 5000 端口MLFLOW_EXPERIMENT_ID可先在 MLflow UI 中创建实验后取得数字 ID或通过mlflow experiments create创建。四、运行原理session.idle 事件驱动的自动追踪管线插件不是一个持续运行的 trace 采集器而是一个事件响应器。其完整工作流如下订阅事件钩子MLflowTracingPlugin返回{ event }钩子OpenCode 每次产生事件都会回调。事件过滤只有event.type session.idle才会继续处理且事件属性中必须携带sessionID否则直接返回对应 src/index.ts。测试明确覆盖了非 session.idle 事件不处理与无 sessionID 不处理两条路径。SDK 惰性初始化调用ensureInitialized()环境变量不满足则放弃。拉取会话消息通过插件客户端调用client.session.messages({ path: { id: sessionID }, query: { limit: 1000 } })一次最多取 1000 条消息。增量判定与去重将当前消息总数与该会话上次已处理数量比对详见下文第六节无新消息则跳过。构建 Trace 并上报对新消息调用processSession()构建 trace 后调用flushTraces()刷入 MLflow。其中processSession()src/index.ts是核心建链逻辑它有几个值得注意的防御性前置校验消息列表为空 → 跳过找不到任何user角色消息 → 跳过无用户输入就没有对话可追踪提取不到用户提示词文本 → 跳过。时间信息贯穿整个链路OpenCode 消息自带毫秒级时间戳info.time.created/completed插件通过timestampToNs()统一换算为纳秒NANOSECONDS_PER_MS 1e6后写入 span 的startTimeNs/endTimeNstrace 的起止时间分别取本批首条消息的created与末条消息的completed缺失时回退到created。五、Trace 数据模型AGENT 父 Span LLM/TOOL 子 Span 三层结构每个 OpenCode 会话在 MLflow 中落地为一个 trace其内部呈1 个 AGENT 父 span N 个 LLM/Tool 子 span的树状结构。1. 父 Spanopencode_conversation通过withSpan()创建名为opencode_conversation、spanType: SpanType.AGENT的父 spansrc/index.tswithSpan( (parentSpan) { /* 创建子 span、附加元数据、结束父 span */ }, { name: opencode_conversation, inputs: { prompt: userPrompt }, startTimeNs: createdNs, spanType: SpanType.AGENT, }, );选择withSpan而非startSpan是有意为之它会让父 span 成为 OTel 上下文中的当前 span从而允许插件通过公开 APIupdateCurrentTrace而非侵入InMemoryTraceManager内部为整个 trace 附加元数据。父 span 结束时写入outputsparentSpan.setOutputs({ response: finalResponse || Conversation completed, status: completed, });2. Trace 级元数据与预览通过updateCurrentTrace写入四类信息src/index.ts字段值说明metadata[mlflow.trace.session]sessionId关联 OpenCode 会话 IDmetadata[mlflow.trace.user]process.env.USER当前系统用户requestPreview用户提示词前 1000 字符便于在 UI 快速预览responsePreview助手最终回复前 1000 字符有最终回复时才写入MAX_PREVIEW_LENGTH 1000是预览内容的上限常量。源码注释特别说明插件刻意用 metadata 键mlflow.trace.session/mlflow.trace.user而非updateCurrentTrace的sessionId/user便捷参数是因为后者以及TraceMetadataKey枚举只在更新的mlflow/core版本中存在而这两个 metadata 键在各发布版本中保持稳定从而兼容更广的 SDK 版本范围。3. LLM Spanllm_call对每条助手消息只要含文本、工具调用或 reasoning 中任一内容创建一个llm_callspanSpanType.LLM记录src/index.tsinputs.model${providerId}/${modelId}如anthropic/claude-3-opusinputs.messages重建的对话历史见下文会话历史重建attributesmodel、providertoken 用量通过SpanAttributeKey.TOKEN_USAGE写入由buildTokenUsage()组装。token 用量的字段结构buildTokenUsage{ input_tokens: 输入 token 数, output_tokens: 输出 token 数, total_tokens: input output reasoning, // reasoning 计入总量 cache_read_tokens: 缓存读取数, // 有缓存信息时才有 cache_write_tokens: 缓存写入数, // 有缓存信息时才有 }LLM span 的outputs采用OpenAI chat-completion 消息形状choices[0].message这是与 codex、qwen-code 等其他集成保持一致的关键设计源码注释明确指出这一点目的是让 MLflow 的Chat 视图能正确渲染工具调用{ role: assistant, content: 文本内容无文本时为 null, reasoning: 推理内容仅当存在 reasoning part 时, tool_calls: [ { id: callID, type: function, function: { name: 工具名, arguments: JSON 字符串化的输入 } } ] }一个细节只有文本的工具调用消息同样会被记录为 LLM span。源码注释解释了原因——像 prometheus 这类 agent 会连续多次发出工具调用而不夹带文本若跳过这些消息会导致大量 span 缺失、trace 空洞。对应测试 should create LLM span for tool-call-only assistant messages 专门复现并回归了这一场景。4. Tool Spantool_对每条工具调用 part 创建tool_工具名spanSpanType.TOOL记录src/index.tsinputs工具入参state.inputattributestool_name、tool_idcallID、statuscompleted/error等outputs按状态区分——completed时写result与titleerror时写error信息时间state.time.start/end换算为纳秒。5. 会话历史重建为了让每次 LLM 调用的inputs.messages呈现完整上下文插件实现了reconstructConversationMessages()src/index.ts将 OpenCode 的消息数组转换为标准对话格式user消息拼接全部文本 partassistant消息content拼接文本 partreasoning拼接推理 part存在时tool消息将已完成status completed的工具调用转为{ role: tool, tool_call_id, content: 输出 }。测试用例用一段用户提问 → 助手推理并调用工具 → 助手自主续作再调工具 → 汇总 → 追问 → 回复的 8 条消息序列逐条断言了重建后历史中 3 条 user、4 条 assistant、2 条 tool 消息的完整结构与顺序可作为理解该逻辑的最佳示例见 tests/index.test.ts。六、增量追踪与去重机制避免重复 Trace 的工程细节OpenCode 的session.idle事件在一个会话中可能多次触发每次用户停止交互都可能空闲。若每次空闲都全量建 trace会造成大量重复。插件的解决方案是基于消息计数的增量追踪const processedMessageCounts new Mapstring, number();逻辑如下src/index.ts拉取全部消息后取其总数messageCount与processedMessageCounts中该会话上次已处理数量lastProcessedCount比较若messageCount lastProcessedCount说明没有新消息直接返回同一轮次不会被处理两次否则用allMessages.slice(lastProcessedCount)只取新增的消息建 trace并更新计数计数器使用LRU 语义维护每次事件都会先delete再set将该会话移到 Map 末尾保证活跃会话即便没有新消息不会被提前淘汰Map 超过 50 个会话时逐出最久未访问的条目防止长期运行造成内存泄漏。测试对此有直接覆盖should not process the same turn twice同一会话同消息数第二次触发不新增 span与 should process new messages in existing session追加消息后再次触发只处理增量。值得注意的是由于 trace 的起止时间取自本批新消息的首尾时间戳增量上报的每个 trace 天然按对话轮次切分便于在 UI 中按轮查看。七、查看 TraceMLflow UI 侧操作追踪数据上报后按 README 的说明启动 MLflow server 并打开 UImlflow server # 浏览器打开 http://localhost:5000在 MLflow UI 中进入对应实验MLFLOW_EXPERIMENT_ID指定的实验即可看到 OpenCode 会话生成的 trace 列表。得益于第五节的 span 结构与 OpenAI 消息形状设计可以在 Chat 视图中直接回放整个智能体对话用户提示、assistant 的推理与回复、工具调用的入参与结果按时间线排列同时可查看每次 LLM 调用的model、provider与token_usage明细以及 trace 级的mlflow.trace.session/mlflow.trace.user元数据用于按会话、按用户筛选。八、边界行为与异常处理源码级确认结合 src/index.ts 与 tests/index.test.ts 的 Edge Cases 分组插件对以下边界情况均有明确行为场景行为环境变量缺失静默跳过调试模式仅输出[mlflow]日志不拉消息、不建 trace非session.idle事件 / 无sessionID直接返回空消息数组不建 trace会话中无 user 消息不建 traceuser 消息无文本内容不建 trace消息缺少parts字段优雅降级不建 trace工具调用缺少state仍创建 tool span用默认值兜底status: unknown、空输出拉取消息失败data为空放弃本次处理不影响插件运行工具状态为errortool span 的 outputs 记录error字段而非 result此外插件还有一处兼容性设计值得留意调试模式下即使 SDK 初始化失败也只会输出日志而不会抛出异常打断 OpenCode 主流程消息处理循环外包了 try/catch任何单个会话的处理异常都不会影响后续事件。九、测试与工程质量mlflow/opencode的测试体系tests/index.test.ts通过 mockmlflow/core模块与 mock OpenCode 插件客户端覆盖了以下分组插件初始化导出函数形态、返回 Promise 及 event 钩子环境变量处理三个分支缺 URI / 缺 ID / 双全下的行为事件过滤事件类型与 sessionID 校验LLM 调用追踪文本回复、token 用量、多轮会话多 span、不同模型openai/gpt-4、reasoning 内容、纯 reasoning 无文本等工具调用追踪completed / error / 多工具连续调用 / 文本工具混合 / Edit、Write、Bash 等常见工具Agent 工作流完整LLM工具回复链路、多步 agentRead→Edit→回复逐条建 LLM span、纯工具调用消息不丢 span重复轮次防护同轮不重复处理、新消息增量处理Trace 元数据mlflow.trace.session/mlflow.trace.user/ 双 preview 断言时间信息span 与 tool span 的纳秒时间戳会话历史重建含 reasoning、tool result 的完整历史结构。mock 定义见 tests/mocks/opencode-ai/plugin.ts其中PluginClient接口给出了插件所依赖的 OpenCode 客户端能力session.messages印证了插件与 OpenCode 协议的最小耦合面。十、源码路径索引如需深入源码可按以下路径继续探索插件主体实现libs/typescript/integrations/opencode/src/index.ts插件测试含大量可参考的消息构造辅助函数libs/typescript/integrations/opencode/tests/index.test.ts插件元信息版本、依赖、Node 版本要求18、Apache-2.0 许可证libs/typescript/integrations/opencode/package.json底层 TypeScript SDK 核心init位于 libs/typescript/core/src/core/config.tsstartSpan/withSpan/updateCurrentTrace位于 libs/typescript/core/src/core/api.tsflushTraces位于 libs/typescript/core/src/core/provider.tsSDK 使用概览libs/typescript/core/README.md同类智能体集成参考同为 OpenAI 消息形状设计libs/typescript/integrations/qwen-code结语mlflow/opencode展示了事件驱动 增量建链的智能体可观测性集成范式以 OpenCode 的session.idle事件为触发点用约 600 行的单文件实现把会话消息完整映射为 AGENT/LLM/TOOL 三层 trace 结构并通过 OpenAI chat-completion 消息形状保持与 MLflow Chat 视图及其他集成的一致性。对于希望以低成本获得 OpenCode 开发过程全量可观测、可复盘、可评估能力的团队而言这是一条开箱即用的路径——安装一个包、配置一行 JSON、导出两个环境变量即可。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考