opik-instrument

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

完成定义： 一条有代表性且安全执行的路径会生成跟踪记录，在 Opik 中确认无误，并返回直接跟踪链接。如果无法安全或自主地完成验证，请在第一个真正的阻碍处停止，并且只返回一个具体的后续步骤。仅修改代码不算成功。

执行方式：执行时果断明确，代码更改时谨慎保守，常规决策时自动处理，验证价值时毫不妥协——但绝不通过运行不安全的操作来实现。

输入

入口点仅为 /opik-instrument（可选添加 /opik-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. 脚本：在末尾刷新（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？”）。先打印命令，然后运行。

如果运行需要 LLM 提供方凭据（例如 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)
project = client.rest_client.projects.get_project_by_id(detail.project_id).name
spans = client.search_spans(project_name=project, trace_id=tid)   # SEPARATE call; without project_name it searches the default project and returns nothing
# 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，然后重新运行 /opik-instrument。”
• “使用 uv sync 安装依赖，然后重新运行 /opik-instrument。”
• “哪个开发命令可以安全地运行此 Agent？”
• “已完成插桩和安装，但运行需要提供方凭据 — 设置 OPENAI_API_KEY（或相应提供方的密钥），然后重新运行。”
• “已完成插桩并运行，但此环境无法查询 Opik — 打开项目并确认跟踪记录 <id> 已到达。”

扩展 — 跟踪记录到达后（只提一次，不要连续引导）

激活期间不要迁移提示词、添加线程或扩展 span。验证完成后，将发现的问题合并为一条扩展建议，例如：

跟踪已验证。我还发现了进一步完善的机会：3 个 Prompt Library 候选项、缺少对话线程关联，以及 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/，不要凭记忆作答。