instrument

Instrument — 添加 Opik 追踪并验证真实追踪记录

完成标准： 一条具有代表性且安全执行的路径会生成追踪记录，并在 Opik 中得到确认，同时返回直接追踪链接。如果无法安全或自主完成验证，请在遇到第一个真正的阻碍时停止，并且只返回一个具体的下一步操作。仅修改代码不算成功。

执行原则：执行时立场鲜明，代码更改保持克制，常规决策自动处理，坚决验证价值——但绝不运行不安全的内容。

输入

入口只有 /instrument（可选 /instrument <path>）。推断其他所有信息；仅将以下内容视为用户可能提供的可选覆盖项，而非必需的设置：

• 目标路径（默认：项目根目录）· 项目名称（默认：根据仓库推断）· 运行命令（默认：推断出的安全路径）· migrate_prompts（默认：false）。

不要把推断变成问卷。只有遇到真正无法推断的阻碍时才提问（见阻碍）。

激活范围 — 仅限以下工作

1. 配置 Opik（唯一真实来源）

• 如果 ~/.opik.config 存在或已设置 OPIK_API_KEY，则按原样使用。
• 否则运行官方配置流程：opik configure（Python）／npx opik-ts configure（TypeScript）。
• **开始添加追踪前验证配置：**运行 opik healthcheck——它会验证配置、安装情况以及后端／工作区的连通性。如果失败，请在该阻碍处停止，并先修复配置或连通性，再添加任何追踪。
• 仅当项目已经采用此模式时，才添加项目本地的 .env 变量。绝不引入第二种配置机制；绝不在不同机制之间复制机密值。

2. 检测语言和框架

Python（*.py、pyproject.toml）或 TypeScript（*.ts、package.json）。根据导入识别 LLM 框架并选择其集成：

导入	集成
openai / anthropic	track_openai / track_anthropic
langchain / langgraph	OpikTracer 回调
crewai / dspy / google-genai / bedrock / llama_index / litellm	track_crewai / OpikCallback / track_genai / track_bedrock / LlamaIndexCallbackHandler / OpikLogger
TS: opik-openai / opik-vercel / opik-langchain	trackOpenAI / OpikExporter / OpikCallbackHandler

完整列表：阅读 ../opik/references/integrations.md（opik 技能，安装在此技能旁边）。如果该文件不存在，则阅读 https://www.comet.com/docs/opik/integrations/overview——绝不要仅仅因为无法访问参考资料，就在具有原生集成的框架上使用手动 span。如果项目已经添加了埋点，则进行审查并仅补充缺失部分——不要重复添加埋点。

3. 添加最少量的追踪

按以下顺序执行决策：

1. 对于提供方 LLM span，优先使用框架原生集成。
2. 仅对集成未覆盖的编排／工具添加手动 @opik.track span（type="tool" / "llm" / "guardrail"）。直接使用 @opik.track 会生成默认 span 类型 general——这适合入口点／编排器。
3. 绝不对同一操作进行两次埋点（不要在 track_openai 上再添加 @opik.track(type="llm")）。
4. 每个可独立运行的 Agent／服务标记一个入口点——不一定是每个仓库一个。
5. 相对于框架装饰器（例如 @app.route）的装饰器顺序取决于框架——请针对具体框架进行验证；不要假设存在通用顺序。
6. 脚本：在末尾执行 flush（opik.flush_tracker() / await client.flush()）。在 @opik.track 中使用 LiteLLM 时，传入 metadata={"opik": {"current_span_data": get_current_span_data()}}，否则追踪记录会成为孤立记录。

做出能让一条有代表性的路径生成追踪记录的最小改动。

4. 安装 Opik 软件包（默认）

通过仓库检测到的软件包管理器（pip / uv / poetry / npm / pnpm / yarn），按照项目的常规做法，仅添加必需的 Opik 软件包。保留锁文件；不要运行通用升级；不要全局安装；谨慎处理异常的生命周期脚本。明确说明这项变更（例如“已将 opik 添加到 pyproject.toml”）。如果环境阻止安装 → 阻塞，并给出唯一且准确的命令。

5. 运行安全且有代表性的路径

推断一条安全命令——优先选择现有的测试、示例或开发脚本，其次选择有界的单请求入口点。绝不运行任何看起来用于生产环境或会执行不可逆／高成本操作的内容（写入、发送邮件、购买、大量 API 调用）。如果无法推断安全路径 → 阻塞（“哪个开发命令可以安全地运行此 Agent？”）。打印命令，然后运行。

如果运行需要 大模型提供商凭据（例如 OPENAI_API_KEY）而该凭据缺失，则视为阻塞——应用无法生成追踪记录。请注意，某些 SDK 客户端会在构造时（模块加载时）报错，早于任何 span 运行，因此不会有部分追踪记录可供等待：返回阻塞状态，并给出唯一的下一步，不要等待一个从未发生的刷新操作。

6. 验证数据接入

确认追踪记录确实已到达——不要想当然。优先使用 SDK 验证：它已作为插桩的一部分安装，无需增加其他环节；而 Opik MCP 是可选的，且可能尚未连接。

import opik
client = opik.Opik()

tid = "<trace_id>"                          # the tracer logs a trace URL/id when the run flushes — use that
detail = client.get_trace_content(tid)      # TracePublic: exposes project_id, NOT project_name (accessing .project_name raises)
spans = client.search_spans(trace_id=tid)   # spans come from a SEPARATE call, not from the trace object
# Reconstruct the tree via each span's parent_span_id (the root span has none); check the expected types (general -> tool/llm).

若要查找最新的追踪记录，而不是使用已知 ID，请使用客户端的追踪搜索功能（例如 search_traces），并将范围限定在项目内。也可以在 Opik MCP 已连接时，先用 list 列出最近的追踪记录，再用 read 读取最新记录。

追踪记录是异步生成的——运行后等待几秒，并确保刷新操作已执行。

7. 报告结果

返回简短的用户可读结果和追踪链接（见 输出），然后给出唯一的一项扩展建议。

阻塞情况

确实无法继续时，应在最早的阻塞点停止，并且只给出一个下一步——绝不要提供清单——同时仍需报告已完成的变更。示例：

• “运行 opik configure，然后重新运行 /instrument。”
• “使用 uv sync 安装依赖项，然后重新运行 /instrument。”
• “哪个开发命令可以安全地运行此 Agent？”
• “已完成插桩和安装，但运行需要提供商凭据——设置 OPENAI_API_KEY（或相关提供商密钥），然后重新运行。”
• “已完成插桩并运行，但此环境无法查询 Opik——打开项目并确认追踪记录 <id> 已到达。”

扩展——追踪记录生成后（只提供一项建议，不要层层引导）

激活期间不要迁移提示词、添加线程或扩展 span。验证完成后，集中提供一项你发现的改进建议，例如：

追踪已验证。我还发现了进一步完善的机会：3 个提示词库候选项、缺少对话线程关联，以及 2 个未追踪的工具。要扩展吗？

输出

**面向用户：**简短的自然语言消息——说明已完成的插桩内容、追踪链接，以及唯一的扩展建议；若受阻，则说明唯一的下一步和已完成的变更。不要返回原始 JSON。

底层（用于组合／评估）的简易状态模型：

• status：verified | blocked | already_verified | unsupported
• changes：files_changed、dependency_added、config_source、entrypoints_instrumented、integrations_added
• verification：command_run、trace_id、trace_url
• blocker：reason、next_step
• expansion_opportunities：prompts、threads、spans

不变量：verified 必须包含 trace_id／trace_url；blocked 必须且只能包含一个 next_step，并且仍需报告 changes；already_verified 表示已有插桩已运行并确认；unsupported 需说明不支持的语言／结构，且不得修改任何内容。

示例

普通情况——不使用大模型框架。 一个 Python 脚本，包含 retrieve() 工具和本地 generate()。没有可封装的提供方 → 在 retrieve 上添加 @opik.track(type="tool")，在入口点添加裸装饰器 @opik.track（→ general），在 __main__ 中刷新；运行 uv add opik；运行脚本；通过 SDK 确认 general → tool → llm 跟踪；返回链接。→ verified。

框架——OpenAI。 from openai import OpenAI。使用原生集成：client = track_openai(OpenAI())；不要为调用大模型的函数添加装饰器（集成会跟踪该函数）；标记入口点；安装 opik；运行。如果缺少 OPENAI_API_KEY，OpenAI() 会在构造时引发异常 → blocked：“设置 OPENAI_API_KEY，然后重新运行”（报告已进行的修改）。

已完成埋点。 已存在 @opik.track / track_openai。仅进行审查——补上缺失的入口点或刷新操作，不要重复埋点；运行并验证。→ already_verified。

反模式

重复包装（集成和同一调用上的手动 span）；孤立的 LiteLLM 跟踪（缺少 current_span_data）；脚本中缺少刷新操作；覆盖或重复配置；仅为强行生成跟踪而运行不安全的路径或生产路径；只需安装 opik 时却大范围升级依赖；激活过程中迁移提示词。

参考资料

SDK 详情见与此技能一同安装的 opik 技能。直接读取文件——路径相对于此文件：../opik/references/tracing-python.md、../opik/references/tracing-typescript.md、../opik/references/integrations.md、../opik/references/observability.md。如果宿主的技能目录结构不同，请找到 opik 技能的 references/ 目录。

如果未安装 opik 技能，请在报告中说明，并使用 https://www.comet.com/docs/opik/，不要凭记忆作答。