用途：在 @prefactor/core 之上构建自己的 provider 适配器包，让应用在不依赖现有适配器的情况下，对 agent、llm、tool 工作流进行插桩。触发场景包括新增 provider 包、用 core 插桩某 provider、框架缺少 Prefactor 适配器、用 Prefactor 构建自定义 SDK 集成。
核心原则：core 处理追踪基础设施，适配器只负责映射 provider 特有 API。
工作流：①定义适配器边界，保持薄封装，只做请求/响应映射、中间件钩子和载荷适配，生命周期、上下文、序列化与传输复用 core，span 类型使用 provider 前缀（如 <provider>:agent、<provider>:llm、<provider>:tool）；②创建小型适配器包（例如 prefactor-provider-<provider>），含 src/index.ts 入口、src/<provider>-middleware.ts 包装、tests/ 和依赖 @prefactor/core 的 package.json，使用 ESM 导入导出且相对导入带显式 .js，仅从 src/index.ts 导出稳定入口；③用 core 原语实现插桩，依赖 core 做追踪、上下文传播、配置和传输，适配器辅助 API（如 init、withSpan）须绑定同一 tracer 源，在适配器外层调用 core 的 withSpan 时传入显式 tracer，用 SpanContext.runAsync(...) 包裹 provider 执行路径以保持父子 span，采集输入输出和用量元数据并做截断/脱敏，出错时记录 span 失败并重新抛出原错误，流式 provider 需在完成、取消、流出错时结束 span；④在集成测试或本地冒烟脚本中验证父子 span 关系、成功与错误的 span 完成、流式终止路径、载荷采集与限制、provider 前缀 span 类型，并确认遥测经配置的 Prefactor 传输发出；⑤上线前加固：确保插桩不导致用户请求崩溃、span 只结束一次、密钥脱敏且载荷有界、重抛错误时保留原始堆栈与类型。
参考：references/provider-package-checklist.md 提供实现清单。常见错误：按 provider 重新实现追踪生命周期而非复用 core；使用通用 span 名称而非 provider 前缀类型；采集原始载荷而不截断/脱敏；插桩后吞掉 provider 错误。