用途
本技能面向这样一种场景：现有智能体在没有 Prefactor 的情况下已经可以正常工作，现在需要为其补充追踪能力，以记录运行（runs）、LLM 调用、工具调用和失败信息，同时尽量不改变原有行为。
核心原则是：对边界进行埋点，而不是对业务逻辑进行埋点。
主要能力
- 为现有智能体添加顶层 run span，并在 LLM 与工具边界添加子 span。
- 保持上下文传播，确保父子追踪树结构完整。
- 使用带包前缀的 span 类型（如 langchain:、ai-sdk:、openclaw:*）。
- 记录错误元数据，并重新抛出原始错误。
- 在成功、错误、取消以及流式终止路径上正确结束 span。
- 支持内置适配器与自定义 @prefactor/core 适配器两种路径。
使用方式
- 使用 skills/bootstrap-existing-agent-with-prefactor-cli/SKILL.md 引导 Prefactor 凭据（prefactor setup 或 prefactor setup --create）。
- 检查项目，并使用项目现有的包管理器（bun、npm、pnpm 或 yarn）安装匹配的 Prefactor 适配器。
- 确定运行时路径：内置适配器（@prefactor/langchain、@prefactor/ai、@prefactor/openclaw、@prefactor/claude）或自定义 @prefactor/core 适配器。
- 添加一个顶层 run span，并在 LLM/工具边界周围添加子 span。
- 保持上下文传播和带包前缀的 span 类型。
- 记录错误元数据并重新抛出原始错误。
- 在成功、错误、取消和流式终止路径上结束 span。
- 在项目的构建/测试/类型检查流程中验证，然后使用 prefactor agent_instances list --agent_id <agent_id> 和 prefactor agent_instances agent_context <instance_id> 确认追踪。
前置条件
在埋点之前，确保已根据 prefactor setup 输出设置以下运行时凭据：
- PREFACTOR_API_URL
- PREFACTOR_API_TOKEN
- PREFACTOR_AGENT_ID
- PREFACTOR_AGENT_IDENTIFIER（来自 setup；通常为 1.0.0）
同时确保已通过项目的包管理器安装依赖：
- @prefactor/langchain、@prefactor/ai、@prefactor/openclaw、@prefactor/claude 之一
- 仅当没有内置适配器可用时，才使用 @prefactor/core
实现规则
优先使用内置适配器，而不是低层级的 @prefactor/core：
- LangChain -> @prefactor/langchain
- AI SDK -> @prefactor/ai
- OpenClaw -> @prefactor/openclaw
当存在适配器时，从同一个选定的适配器包（@prefactor/ai 或 @prefactor/langchain）导入 init、withSpan 和 shutdown。
除非向 withSpan 传入显式 tracer，否则不要将适配器的 init 与从 @prefactor/core 导入的 withSpan/shutdown 混用。原因是：混用辅助函数导入可能导致 “No active tracer found”（例如存在嵌套的包实例时），从而丢失手动自定义 span。
保持导入为包内局部且显式，例如：
import { init, withSpan, shutdown } from '@prefactor/ai'; // 或 import { init, withSpan, shutdown } from '@prefactor/langchain';
这种混用导入的 tracer 风险适用于适配器式流程（@prefactor/ai、@prefactor/langchain），不适用于 @prefactor/openclaw 插件运行时模型。
如果不存在内置适配器，请遵循 skills/create-provider-package-with-core/SKILL.md。
保持 provider span 类型带包前缀（langchain:、ai-sdk:、openclaw:*）。
在活动上下文中运行嵌套工作，以保持父/子追踪树完整。
安全地捕获输入/输出（脱敏密钥，强制截断限制）。
埋点绝不能导致用户代码崩溃。
与自定义 Provider 技能配合使用
有时需要同时使用两个技能。
- 如果框架/provider 已受 Prefactor 适配器支持，直接使用本技能。
- 如果框架/provider 尚不受支持，先使用 skills/create-provider-package-with-core/SKILL.md 构建自定义适配器，然后使用本技能用该适配器为现有智能体埋点。
不受支持时的推荐顺序：
- 使用 @prefactor/core 创建 provider 适配器。
- 将适配器集成到现有智能体入口点。
- 在真实执行中验证 run/llm/tool/error span。
编码工具触发短语
如果用户提出以下任一请求，则应用本技能：
- “instrument this existing agent”
- “this agent already works, add prefactor tracing”
- “wrap this existing langchain/ai agent with prefactor”
- “add tracing for tool calls and runs”
- “tool calls are missing in my coding tool timeline”
验证
运行等效的项目验证命令（例如 build、typecheck 和 tests）。
同时至少运行一次真实的智能体请求，并确认：
- 存在顶层 run span
- 子 llm/tool span 正确嵌套
- 成功和失败时都出现终止状态
适用场景
- 已有可运行智能体，需要补充运行、LLM 调用、工具调用和失败追踪。
- 使用 LangChain、AI SDK、OpenClaw 或 Claude 等已有适配器的框架。
- 需要为编码工具时间线补齐工具调用记录。
- 框架/provider 暂不受支持时，先构建自定义适配器再埋点。
限制与注意事项
- 埋点必须只针对边界，而不是每个辅助函数。
- 不要使用通用 span 类型。
- 不要在记录日志后吞掉异常。
- 不要遗漏流式取消/错误的完成路径。
- 混用适配器与 @prefactor/core 的辅助函数导入可能导致 tracer 丢失。
- 埋点绝不能导致用户代码崩溃。
参考资料
- 关于面向编码工具的关键词覆盖和触发措辞，请阅读 references/coding-tool-triggers.md。
- 关于执行清单和失败诊断，请阅读 references/instrumentation-checklist.md。