MLflow Claude Code Tracing 配置指南用 mlflow-claude-code setup 技能为 Claude Code 开启 MLflow Tracing【免费下载链接】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本篇技术指南以 MLflow 仓库中 Claude Code 集成的setup技能文档libs/typescript/integrations/claude-code/skills/setup/SKILL.md为骨架系统讲解如何通过mlflow-claude-code setup命令行工具为 Claude Code 配置 MLflow Tracing覆盖 CLI 全部参数、校验规则、配置文件写入位置与优先级、以及 Stop Hook 背后的 trace 生成原理。读完本文你将能够独立完成从安装、交互式收集配置、执行 setup 到用 status 验证生效配置的完整闭环。一、setup 技能是什么setup是随mlflow/claude-code包分发的 Claude Code 技能Skill之一其 frontmatter 声明如下SKILL.md--- name: setup description: Configure MLflow tracing for Claude Code. disable-model-invocation: true ---关键信息有三点name: setup技能标识符与 CLI 的setup子命令同名description明确技能职责——为 Claude Code 配置 MLflow tracingdisable-model-invocation: true模型Claude不得自主调用该技能必须由用户显式提出配置 MLflow tracing 的需求后才允许运行。这决定了该技能的使用边界它不是一个随意触发的小工具而是用户主动发起配置 MLflow tracing这一意图时的标准操作流程。其姊妹技能 status 技能 则用于事后查看当前生效的 tracing 配置。二、技能定义的标准工作流原技能文档给出了 4 步执行流程SKILL.md运行mlflow-claude-code setup --help读取可用选项逐一询问用户每个必需值不得静默采用默认值——所有值都必须来自用户使用收集到的选项运行mlflow-claude-code setup回显 CLI 输出并简要说明配置文件路径、tracking URI、experiment以及下一次 Claude 对话即启用 tracing。这套流程的先看 help、再逐个询问、不擅自选默认值的设计与 CLI 实现中的强制校验一一对应源码 cli.ts 中明确要求 Required values (all must come from the user; do not pick defaults silently)并列出三项必填约束Scope作用域必须传--project或--user其中之一Tracking URI必须传--tracking-uriExperiment实验必须传--experiment-id或--experiment-name其中之一。缺少任何一项命令都会报错并以退出码 1 结束这一点在 setup.ts 中有硬性校验缺失 scope、缺失 tracking URI、experiment 二选一未满足、两个 experiment 参数同时传入均被拒绝。三、前置准备在运行 setup 之前需要先完成安装与基础环境准备见 README.md# 安装 Claude Code 集成包 npm install mlflow/claude-code # 如需同时追踪 Claude Agent SDK 的 query 调用还需安装 SDK可选 npm install anthropic-ai/claude-agent-sdk该包暴露的 CLI 二进制名为mlflow-claude-codepackage.json 中bin字段指向./bundle/cli.cjs运行时要求 Node.js 18。其次需要一个 MLflow Tracking Server。如果没有现成的服务可以启动一个本地实例例如http://localhost:5000。CLI 支持三类 tracking URIcli.tsdatabricksDatabricks 默认工作区依赖本地已配置的 Databricks CLI 认证databricks://profile指定 Databricks 配置文件中的某个 profile绝对 http(s) URL指向自建或托管的 MLflow Tracking Server。需要说明的是本文只介绍配置操作本身mlflow/claude-code负责的是把配置写入 Claude Code 设置文件并驱动 trace 上报实际的实验/追踪数据持久化依赖你指向的 Tracking Server。四、完整命令行参考运行mlflow-claude-code setup --help或无参数运行mlflow-claude-code即可看到全部选项源码实现在 cli.ts完整整理如下选项说明必填性-p, --project写入./.claude/settings.json仅当前仓库生效二选一必填-u, --user写入~/.claude/settings.json对所有仓库生效二选一必填--tracking-uri uriMLflow tracking URI取值见上文三类必填--experiment-id id使用已存在的 MLflow experiment按 ID与下方二选一--experiment-name n按名称复用或创建 MLflow experiment与上方二选一--trace-location loc可选Databricks Unity Catalog trace location格式catalog.schema.table_prefix可选--workspace ws可选Databricks 工作区标识可选-h, --help打印帮助信息可选参数解析逻辑见 setup.ts每个选项的取值紧跟在旗标之后特别地--trace-location后缺值会被视为空字符串从而主动触发校验失败而不是被静默忽略源码注释明确说明这是有意为之避免配置错误无声消失。官方使用示例cli.ts# 示例 1项目级配置指向本地 tracking server按名称创建 experiment $ mlflow-claude-code setup --project --tracking-uri http://localhost:5000 \ --experiment-name my-exp # 示例 2用户级配置指向 Databricks按 experiment ID 复用 $ mlflow-claude-code setup --user --tracking-uri databricks --experiment-id 12345 # 示例 3用户级配置 Unity Catalog trace location $ mlflow-claude-code setup --user --tracking-uri databricks \ --experiment-id 12345 --trace-location my_catalog.my_schema.my_prefix五、配置校验规则源码级在执行写入前CLI 会逐项校验输入全部通过才落盘setup.ts作用域校验--project与--user必须且只能传一个否则报Error: must pass --project or --user.Tracking URI 必填缺失时报Error: --tracking-uri is required.Tracking URI 合法性必须等于databricks、以databricks://开头或为 http/https 绝对 URL。isValidTrackingUri的实现位于 config.ts非法的 URI 会被拒绝Experiment 二选一--experiment-id与--experiment-name同时传入报Error: pass only one of --experiment-id or --experiment-name.都不传则报Error: must pass --experiment-id or --experiment-name.Trace location 格式若传了--trace-location必须严格符合catalog.schema.table_prefix三段点分格式。parseTraceLocationconfig.ts要求恰好三段且每段非空——因为 SDK 不会自动创建 UC trace location三段缺一不可。这些规则在单元测试 tests/setup.test.ts 中逐一得到验证缺少 scope、缺少 tracking URI、缺少 experiment、experiment 冲突、非法 tracking URI、--trace-location缺值与格式非法全部断言退出码为 1 且不产生设置文件。六、experiment 的解析与自动创建当用户只提供--experiment-name而没有--experiment-id时setup 会通过 MLflow Client 与 Tracking Server 交互config.ts先按名称查询getExperimentByName若已存在复用其 experiment ID若不存在调用createExperiment自动创建并在 CLI 输出中提示Created MLflow experiment name (id)。因此--experiment-name是按名复用或创建--experiment-id则是直接用已有实验。setup 结束后会在标准错误输出一段配置摘要setup.ts内容为Current configuration Tracing enabled: true Settings file: path Tracking URI: uri Experiment ID: id Experiment name: name # 若提供 Trace location: loc # 若提供 Workspace: ws # 若提供这正是技能工作流第 4 步要求回显 CLI 输出时应当向用户呈现的核心信息。七、配置写入位置与 settings.json 结构resolveSettingsPathconfig.ts决定设置文件的落盘位置--project当前工作目录/.claude/settings.json仅对当前项目生效--user用户主目录/.claude/settings.json对该机器上所有项目生效。写入采用增量合并方式writeTracingSettingsconfig.ts会先读取已有 settings.json 的env字段然后仅更新相关键、保留其余键最后以带缩进的 JSON 写回并创建缺失目录。一个典型的--project配置结果对应测试 tests/setup.test.ts 的断言如下{ env: { MLFLOW_CLAUDE_TRACING_ENABLED: true, MLFLOW_TRACKING_URI: http://localhost:5000, MLFLOW_EXPERIMENT_ID: resolved-id, MLFLOW_EXPERIMENT_NAME: my-experiment } }涉及的完整环境变量键定义在 config.ts环境变量作用写入时机MLFLOW_CLAUDE_TRACING_ENABLED总开关true表示启用总是写入trueMLFLOW_TRACKING_URI上报 trace 的目标 tracking URI总是写入MLFLOW_EXPERIMENT_ID目标 experiment ID提供 experiment ID 时写入MLFLOW_EXPERIMENT_NAME目标 experiment 名称提供 experiment name 时写入MLFLOW_TRACE_LOCATIONUnity Catalog trace locationV4 trace ID 通道仅当提供且合法时写入写入前会 trimMLFLOW_WORKSPACEDatabricks 工作区标识仅当提供时写入值得注意的细节MLFLOW_TRACE_LOCATION一旦设置trace 将走Unity Catalog table-prefix 目的地V4 trace ID而非 experiment-backed 的 V3 路径而该 UC location 必须已在工作区预置好SDK 不会自动创建见 config.ts 的注释。此外当配置中未提供某键时写入逻辑会删除settings.json 中该键的旧值delete env[...]避免残留过期配置。八、配置生效优先级getEffectiveTracingConfigconfig.ts实现了运行时配置合并优先级从高到低为环境变量进程环境中直接设置的MLFLOW_*键优先于一切文件配置项目级设置项目/.claude/settings.json用户级设置~/.claude/settings.json。具体规则若项目级配置存在任意 tracing 键则整体覆盖用户级对应字段环境变量中的MLFLOW_TRACKING_URI、MLFLOW_EXPERIMENT_ID等非开关键用??语义覆盖未定义时才回退到文件值而开关键MLFLOW_CLAUDE_TRACING_ENABLED只要环境变量存在就以环境变量为准。MLFLOW_CLAUDE_TRACING_ENABLED的取值识别true、1、yes大小写不敏感见 config.ts。九、验证配置status 命令配置完成后可用mlflow-claude-code status验证生效配置输出源码见 setup.tsMLflow Tracing Status Enabled: true Source: project # 配置来源environment / project / user / none Settings file: /path/to/.claude/settings.json Tracking URI: http://localhost:5000 Experiment ID: 123 Experiment name: my-exp Trace location: ... Workspace: ...Source字段直接反映第八节的优先级裁决结果来自环境变量为environment来自项目文件为project来自用户文件为user完全未配置为none此时会提示Tracing is disabled. Run mlflow-claude-code setup to configure it.。这正是 status 技能 要求助手向用户概括的内容tracing 是否启用、配置来源、当前生效的 tracking URI 与 experiment 设置。十、幕后机制配置如何变成 trace配置完成后下一次 Claude 对话即自动产生 trace的机制如下Stop Hook 挂载mlflow/claude-code打包了插件级 Stop Hookhooks/hooks.json在 Claude 对话会话结束时执行node ${CLAUDE_PLUGIN_ROOT}/bundle/stop.cjsHook 执行链路stop.ts 从 stdin 读取transcript_path与session_id先经isTracingEnabled()判断开关再ensureInitialized()校验配置并初始化 MLflow见 config.ts此时会自动开启异步 trace 日志MLFLOW_ENABLE_ASYNC_TRACE_LOGGINGtrue并在已配置 experiment ID 时走免网络请求的快速路径最后调用processTranscript解析会话 transcriptSpan 结构生成tracing.ts 以claude_code_conversation为根 AGENT span为每次含文本的助手回复生成llmLLM span记录 model、messages、token usage、按模型目录费率计算的成本为工具调用生成tool_nameTOOL span记录输入输出、错误异常并通过 Task 工具对应的parentToolUseID分组生成嵌套的 sub-agent AGENT span元数据与成本聚合trace 级元数据包含 session ID、当前用户、工作目录、permission mode、Claude Code 版本并把各 span 成本聚合成 trace 总成本写入元数据最后flushTraces()上报。这一链路解释了为什么 setup 配置tracking URI experiment是 tracing 生效的唯一必要前提Hook 与 span 生成逻辑是打包自带的用户只需完成 setup 即可获得完整的对话级追踪。十一、常见错误与排查结合 setup.ts 与测试用例常见失败场景与提示如下场景CLI 报错处理建议未传--project/--usermust pass --project or --user.补传作用域参数未传--tracking-uri--tracking-uri is required.补传 tracking URIURI 非法如not-a-uriinvalid --tracking-uri使用databricks/databricks://profile/ http(s) URLexperiment 参数冲突或缺失pass only one of --experiment-id or --experiment-name./must pass --experiment-id or --experiment-name.二选一trace-location 缺值或格式非法invalid --trace-location使用catalog.schema.table_prefix三段格式若 setup 成功但 trace 未出现优先用mlflow-claude-code status检查Enabled与Source确认生效配置确实来自预期层级若Source: none则说明配置文件未被读取到。十二、总结setup技能以显式用户意图触发 逐步收集用户参数 CLI 落盘校验的方式把 Claude Code 接入 MLflow Tracing 的配置过程收敛为一条可靠命令--project/--user决定生效范围--tracking-uri决定数据去向--experiment-id/--experiment-name决定实验归属--trace-location/--workspace按需扩展 Databricks 场景。配合status技能与 Stop Hook 的自动上报机制即可实现配置一次、每次对话自动追踪的 Agent 可观测性闭环。【免费下载链接】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 Claude Code Tracing 配置指南：用 mlflow-claude-code setup 技能为 Claude Code 开启 MLflow Tracing
MLflow Claude Code Tracing 配置指南用 mlflow-claude-code setup 技能为 Claude Code 开启 MLflow Tracing【免费下载链接】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本篇技术指南以 MLflow 仓库中 Claude Code 集成的setup技能文档libs/typescript/integrations/claude-code/skills/setup/SKILL.md为骨架系统讲解如何通过mlflow-claude-code setup命令行工具为 Claude Code 配置 MLflow Tracing覆盖 CLI 全部参数、校验规则、配置文件写入位置与优先级、以及 Stop Hook 背后的 trace 生成原理。读完本文你将能够独立完成从安装、交互式收集配置、执行 setup 到用 status 验证生效配置的完整闭环。一、setup 技能是什么setup是随mlflow/claude-code包分发的 Claude Code 技能Skill之一其 frontmatter 声明如下SKILL.md--- name: setup description: Configure MLflow tracing for Claude Code. disable-model-invocation: true ---关键信息有三点name: setup技能标识符与 CLI 的setup子命令同名description明确技能职责——为 Claude Code 配置 MLflow tracingdisable-model-invocation: true模型Claude不得自主调用该技能必须由用户显式提出配置 MLflow tracing 的需求后才允许运行。这决定了该技能的使用边界它不是一个随意触发的小工具而是用户主动发起配置 MLflow tracing这一意图时的标准操作流程。其姊妹技能 status 技能 则用于事后查看当前生效的 tracing 配置。二、技能定义的标准工作流原技能文档给出了 4 步执行流程SKILL.md运行mlflow-claude-code setup --help读取可用选项逐一询问用户每个必需值不得静默采用默认值——所有值都必须来自用户使用收集到的选项运行mlflow-claude-code setup回显 CLI 输出并简要说明配置文件路径、tracking URI、experiment以及下一次 Claude 对话即启用 tracing。这套流程的先看 help、再逐个询问、不擅自选默认值的设计与 CLI 实现中的强制校验一一对应源码 cli.ts 中明确要求 Required values (all must come from the user; do not pick defaults silently)并列出三项必填约束Scope作用域必须传--project或--user其中之一Tracking URI必须传--tracking-uriExperiment实验必须传--experiment-id或--experiment-name其中之一。缺少任何一项命令都会报错并以退出码 1 结束这一点在 setup.ts 中有硬性校验缺失 scope、缺失 tracking URI、experiment 二选一未满足、两个 experiment 参数同时传入均被拒绝。三、前置准备在运行 setup 之前需要先完成安装与基础环境准备见 README.md# 安装 Claude Code 集成包 npm install mlflow/claude-code # 如需同时追踪 Claude Agent SDK 的 query 调用还需安装 SDK可选 npm install anthropic-ai/claude-agent-sdk该包暴露的 CLI 二进制名为mlflow-claude-codepackage.json 中bin字段指向./bundle/cli.cjs运行时要求 Node.js 18。其次需要一个 MLflow Tracking Server。如果没有现成的服务可以启动一个本地实例例如http://localhost:5000。CLI 支持三类 tracking URIcli.tsdatabricksDatabricks 默认工作区依赖本地已配置的 Databricks CLI 认证databricks://profile指定 Databricks 配置文件中的某个 profile绝对 http(s) URL指向自建或托管的 MLflow Tracking Server。需要说明的是本文只介绍配置操作本身mlflow/claude-code负责的是把配置写入 Claude Code 设置文件并驱动 trace 上报实际的实验/追踪数据持久化依赖你指向的 Tracking Server。四、完整命令行参考运行mlflow-claude-code setup --help或无参数运行mlflow-claude-code即可看到全部选项源码实现在 cli.ts完整整理如下选项说明必填性-p, --project写入./.claude/settings.json仅当前仓库生效二选一必填-u, --user写入~/.claude/settings.json对所有仓库生效二选一必填--tracking-uri uriMLflow tracking URI取值见上文三类必填--experiment-id id使用已存在的 MLflow experiment按 ID与下方二选一--experiment-name n按名称复用或创建 MLflow experiment与上方二选一--trace-location loc可选Databricks Unity Catalog trace location格式catalog.schema.table_prefix可选--workspace ws可选Databricks 工作区标识可选-h, --help打印帮助信息可选参数解析逻辑见 setup.ts每个选项的取值紧跟在旗标之后特别地--trace-location后缺值会被视为空字符串从而主动触发校验失败而不是被静默忽略源码注释明确说明这是有意为之避免配置错误无声消失。官方使用示例cli.ts# 示例 1项目级配置指向本地 tracking server按名称创建 experiment $ mlflow-claude-code setup --project --tracking-uri http://localhost:5000 \ --experiment-name my-exp # 示例 2用户级配置指向 Databricks按 experiment ID 复用 $ mlflow-claude-code setup --user --tracking-uri databricks --experiment-id 12345 # 示例 3用户级配置 Unity Catalog trace location $ mlflow-claude-code setup --user --tracking-uri databricks \ --experiment-id 12345 --trace-location my_catalog.my_schema.my_prefix五、配置校验规则源码级在执行写入前CLI 会逐项校验输入全部通过才落盘setup.ts作用域校验--project与--user必须且只能传一个否则报Error: must pass --project or --user.Tracking URI 必填缺失时报Error: --tracking-uri is required.Tracking URI 合法性必须等于databricks、以databricks://开头或为 http/https 绝对 URL。isValidTrackingUri的实现位于 config.ts非法的 URI 会被拒绝Experiment 二选一--experiment-id与--experiment-name同时传入报Error: pass only one of --experiment-id or --experiment-name.都不传则报Error: must pass --experiment-id or --experiment-name.Trace location 格式若传了--trace-location必须严格符合catalog.schema.table_prefix三段点分格式。parseTraceLocationconfig.ts要求恰好三段且每段非空——因为 SDK 不会自动创建 UC trace location三段缺一不可。这些规则在单元测试 tests/setup.test.ts 中逐一得到验证缺少 scope、缺少 tracking URI、缺少 experiment、experiment 冲突、非法 tracking URI、--trace-location缺值与格式非法全部断言退出码为 1 且不产生设置文件。六、experiment 的解析与自动创建当用户只提供--experiment-name而没有--experiment-id时setup 会通过 MLflow Client 与 Tracking Server 交互config.ts先按名称查询getExperimentByName若已存在复用其 experiment ID若不存在调用createExperiment自动创建并在 CLI 输出中提示Created MLflow experiment name (id)。因此--experiment-name是按名复用或创建--experiment-id则是直接用已有实验。setup 结束后会在标准错误输出一段配置摘要setup.ts内容为Current configuration Tracing enabled: true Settings file: path Tracking URI: uri Experiment ID: id Experiment name: name # 若提供 Trace location: loc # 若提供 Workspace: ws # 若提供这正是技能工作流第 4 步要求回显 CLI 输出时应当向用户呈现的核心信息。七、配置写入位置与 settings.json 结构resolveSettingsPathconfig.ts决定设置文件的落盘位置--project当前工作目录/.claude/settings.json仅对当前项目生效--user用户主目录/.claude/settings.json对该机器上所有项目生效。写入采用增量合并方式writeTracingSettingsconfig.ts会先读取已有 settings.json 的env字段然后仅更新相关键、保留其余键最后以带缩进的 JSON 写回并创建缺失目录。一个典型的--project配置结果对应测试 tests/setup.test.ts 的断言如下{ env: { MLFLOW_CLAUDE_TRACING_ENABLED: true, MLFLOW_TRACKING_URI: http://localhost:5000, MLFLOW_EXPERIMENT_ID: resolved-id, MLFLOW_EXPERIMENT_NAME: my-experiment } }涉及的完整环境变量键定义在 config.ts环境变量作用写入时机MLFLOW_CLAUDE_TRACING_ENABLED总开关true表示启用总是写入trueMLFLOW_TRACKING_URI上报 trace 的目标 tracking URI总是写入MLFLOW_EXPERIMENT_ID目标 experiment ID提供 experiment ID 时写入MLFLOW_EXPERIMENT_NAME目标 experiment 名称提供 experiment name 时写入MLFLOW_TRACE_LOCATIONUnity Catalog trace locationV4 trace ID 通道仅当提供且合法时写入写入前会 trimMLFLOW_WORKSPACEDatabricks 工作区标识仅当提供时写入值得注意的细节MLFLOW_TRACE_LOCATION一旦设置trace 将走Unity Catalog table-prefix 目的地V4 trace ID而非 experiment-backed 的 V3 路径而该 UC location 必须已在工作区预置好SDK 不会自动创建见 config.ts 的注释。此外当配置中未提供某键时写入逻辑会删除settings.json 中该键的旧值delete env[...]避免残留过期配置。八、配置生效优先级getEffectiveTracingConfigconfig.ts实现了运行时配置合并优先级从高到低为环境变量进程环境中直接设置的MLFLOW_*键优先于一切文件配置项目级设置项目/.claude/settings.json用户级设置~/.claude/settings.json。具体规则若项目级配置存在任意 tracing 键则整体覆盖用户级对应字段环境变量中的MLFLOW_TRACKING_URI、MLFLOW_EXPERIMENT_ID等非开关键用??语义覆盖未定义时才回退到文件值而开关键MLFLOW_CLAUDE_TRACING_ENABLED只要环境变量存在就以环境变量为准。MLFLOW_CLAUDE_TRACING_ENABLED的取值识别true、1、yes大小写不敏感见 config.ts。九、验证配置status 命令配置完成后可用mlflow-claude-code status验证生效配置输出源码见 setup.tsMLflow Tracing Status Enabled: true Source: project # 配置来源environment / project / user / none Settings file: /path/to/.claude/settings.json Tracking URI: http://localhost:5000 Experiment ID: 123 Experiment name: my-exp Trace location: ... Workspace: ...Source字段直接反映第八节的优先级裁决结果来自环境变量为environment来自项目文件为project来自用户文件为user完全未配置为none此时会提示Tracing is disabled. Run mlflow-claude-code setup to configure it.。这正是 status 技能 要求助手向用户概括的内容tracing 是否启用、配置来源、当前生效的 tracking URI 与 experiment 设置。十、幕后机制配置如何变成 trace配置完成后下一次 Claude 对话即自动产生 trace的机制如下Stop Hook 挂载mlflow/claude-code打包了插件级 Stop Hookhooks/hooks.json在 Claude 对话会话结束时执行node ${CLAUDE_PLUGIN_ROOT}/bundle/stop.cjsHook 执行链路stop.ts 从 stdin 读取transcript_path与session_id先经isTracingEnabled()判断开关再ensureInitialized()校验配置并初始化 MLflow见 config.ts此时会自动开启异步 trace 日志MLFLOW_ENABLE_ASYNC_TRACE_LOGGINGtrue并在已配置 experiment ID 时走免网络请求的快速路径最后调用processTranscript解析会话 transcriptSpan 结构生成tracing.ts 以claude_code_conversation为根 AGENT span为每次含文本的助手回复生成llmLLM span记录 model、messages、token usage、按模型目录费率计算的成本为工具调用生成tool_nameTOOL span记录输入输出、错误异常并通过 Task 工具对应的parentToolUseID分组生成嵌套的 sub-agent AGENT span元数据与成本聚合trace 级元数据包含 session ID、当前用户、工作目录、permission mode、Claude Code 版本并把各 span 成本聚合成 trace 总成本写入元数据最后flushTraces()上报。这一链路解释了为什么 setup 配置tracking URI experiment是 tracing 生效的唯一必要前提Hook 与 span 生成逻辑是打包自带的用户只需完成 setup 即可获得完整的对话级追踪。十一、常见错误与排查结合 setup.ts 与测试用例常见失败场景与提示如下场景CLI 报错处理建议未传--project/--usermust pass --project or --user.补传作用域参数未传--tracking-uri--tracking-uri is required.补传 tracking URIURI 非法如not-a-uriinvalid --tracking-uri使用databricks/databricks://profile/ http(s) URLexperiment 参数冲突或缺失pass only one of --experiment-id or --experiment-name./must pass --experiment-id or --experiment-name.二选一trace-location 缺值或格式非法invalid --trace-location使用catalog.schema.table_prefix三段格式若 setup 成功但 trace 未出现优先用mlflow-claude-code status检查Enabled与Source确认生效配置确实来自预期层级若Source: none则说明配置文件未被读取到。十二、总结setup技能以显式用户意图触发 逐步收集用户参数 CLI 落盘校验的方式把 Claude Code 接入 MLflow Tracing 的配置过程收敛为一条可靠命令--project/--user决定生效范围--tracking-uri决定数据去向--experiment-id/--experiment-name决定实验归属--trace-location/--workspace按需扩展 Databricks 场景。配合status技能与 Stop Hook 的自动上报机制即可实现配置一次、每次对话自动追踪的 Agent 可观测性闭环。【免费下载链接】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），仅供参考