用途
Instrument 用于给一个已有应用接入 Opik 追踪，并验证一条真实的 trace 确实上报成功。它的定义完成标准是：一条代表性、可安全执行的路径产生 trace，并在 Opik 中得到确认，同时返回直接的 trace 链接。仅修改代码不算成功。如果无法安全或自主完成验证，应停在第一个真实阻塞点，并返回恰好一个具体的下一步。
主要能力
- 配置 Opik：若 ~/.opik.config 存在或已设置 OPIK_API_KEY，则直接使用；否则运行官方配置流程（Python 用 opik configure，TypeScript 用 npx opik-ts configure），并在接入追踪前用 opik healthcheck 验证配置、安装与后端/工作区可达性。
- 检测语言与框架：识别 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 各有对应集成；TS 侧有 opik-openai/opik-vercel/opik-langchain。
- 添加最小追踪：优先使用框架原生集成处理 provider LLM span；仅对集成未覆盖的编排/工具添加手动 @opik.track span（type="tool"/"llm"/"guardrail"），裸 @opik.track 产生默认 general 类型，适合入口/编排器。不重复追踪同一操作，每个可独立运行的 agent/service 标记一个入口点。
- 安装 Opik 包：通过项目检测到的包管理器（pip/uv/poetry/npm/pnpm/yarn）仅添加所需的 Opik 包，保留 lockfile，不做通用升级，不全局安装。
- 运行安全代表性路径：优先使用已有测试、示例或开发脚本，其次是有界的单请求入口；绝不运行看起来像生产或不可逆/昂贵操作（写入、发邮件、购买、批量 API 调用）的路径。
- 验证上报：优先用 SDK 验证（已随接入安装），通过 client.get_trace_content(tid) 获取 trace 详情，用 client.search_spans(trace_id=tid) 单独获取 span，并通过 parent_span_id 重建树。trace 是异步的，运行后需等待几秒并确保 flush 已执行。
- 报告：返回简短的人类可读结果与 trace 链接，然后给出一次扩展提议。
使用方式
入口为 /instrument（可选 /instrument <path>）。其余信息自行推断，仅将以下视为可选覆盖项：目标路径（默认项目根）、项目名（默认从仓库推断）、运行命令（默认推断的安全路径）、migrate_prompts（默认 false）。不要将推断变成问卷，仅在遇到真正无法推断的阻塞时才询问。
适用场景
- 为已有 Python 或 TypeScript 应用接入 Opik 追踪。
- 项目使用 OpenAI、Anthropic、LangChain、LangGraph、CrewAI、DSPy、Google GenAI、Bedrock、LlamaIndex、LiteLLM 等框架时，使用对应原生集成。
- 项目已有部分追踪时，仅审计并补充缺失部分，不重复接入。
限制
- 若配置、安装或后端可达性检查失败，需停在阻塞点先修复。
- 若运行需要 LLM provider 凭证（如 OPENAI_API_KEY）而缺失，属于阻塞；部分 SDK 客户端在构造（模块加载）时即抛错，不会有部分 trace 可等待。
- 若无法推断安全路径，属于阻塞。
- 激活期间不迁移 prompt、不添加线程、不扩大 span 范围。
- 反模式包括：双重包装、LiteLLM trace 孤立（缺少 current_span_data）、脚本缺少 flush、覆盖或重复配置、为强制产生 trace 而运行不安全/生产路径、仅需 opik 时做广泛依赖升级、激活期间迁移 prompt。
输出
面向用户：简短消息，说明接入了什么、trace 链接，以及一次扩展提议（若阻塞，则给出单个下一步及已做更改）。底层为小型状态模型：status（verified | blocked | already_verified | unsupported）、changes、verification、blocker、expansion_opportunities。不变量：verified 必须带 trace_id/trace_url；blocked 必须带恰好一个 next_step 并仍报告更改；already_verified 表示已有接入被运行并确认；unsupported 说明不支持的语言/形态且不做任何修改。
参考
SDK 细节位于与本技能并排安装的 opik 技能中，路径相对于本文件：../opik/references/tracing-python.md、../opik/references/tracing-typescript.md、../opik/references/integrations.md、../opik/references/observability.md。若 opik 技能未安装，应在报告中说明，并使用 https://www.comet.com/docs/opik/ 而非凭记忆工作。