create-provider-package-with-core

使用 Core 创建 Provider 包

基于 @prefactor/core 构建自己的 Provider 适配器包。

核心原则：@prefactor/core 负责处理追踪基础设施，而你的适配器负责映射 Provider 特有的 API。

触发短语

当请求中包含以下模式时，应用此技能：

• “添加一个新的 Provider 包”
• “使用 @prefactor/core 为 Provider X 添加检测”
• “我的框架没有 Prefactor 适配器”
• “使用 Prefactor 构建自定义 SDK 集成”

工作流

1. 定义适配器边界。
2. 在项目中创建一个小型适配器包。
3. 使用 Core 原语实现检测。
4. 在应用中验证追踪行为。
5. 加固以用于生产环境。

1) 定义适配器边界

• 保持适配器精简：负责请求／响应映射、中间件钩子和负载适配。
• 复用 @prefactor/core 处理生命周期、上下文、序列化和传输行为。
• 使用带 Provider 前缀的 Span 类型（<provider>:agent、<provider>:llm、<provider>:tool）。

2) 创建一个小型适配器包

在应用或工作区中创建专用模块／包（例如 prefactor-provider-<provider>）：

• src/index.ts 公共入口
• src/<provider>-middleware.ts Provider 集成封装
• tests/，用于覆盖追踪行为
• package.json，声明对 @prefactor/core 的依赖

使用以下包接口：

• 使用 ESM 导入／导出；相对导入必须显式添加 .js。
• 仅从 src/index.ts 导出稳定的适配器入口。

3) 使用 Core 原语实现检测

• 依赖 @prefactor/core 提供追踪、上下文传播、配置和传输辅助功能。
• 如果适配器提供 init + withSpan 之类的辅助 API，请确保它们绑定到同一个 tracer 来源；如果在适配器辅助函数之外调用 Core 的 withSpan，请传入显式的 tracer。
• 使用上下文包装 Provider 执行路径（SpanContext.runAsync(...)），以保持父／子 Span 关系。
• 在可用时捕获输入／输出和用量元数据；应用截断／脱敏保护措施。
• 出错时，记录 Span 失败数据并重新抛出原始错误。
• 对于流式 Provider，在完成、取消和流错误时结束 Span。

4) 在应用中验证追踪行为

在集成测试或本地冒烟脚本中进行验证：

• 父／子 Span 关系
• 成功和错误时 Span 的结束情况
• 流式处理完成／取消／错误的终止路径
• 负载捕获和限制
• 带 Provider 前缀的 Span 类型

确认遥测数据通过已配置的 Prefactor 传输方式发出。

5) 加固以用于生产环境

发布前，请确认：

• 检测绝不会导致用户请求崩溃
• Span 恰好结束一次
• 密钥已脱敏，且负载大小受到限制
• 重新抛出错误时保留原始堆栈／类型

快速参考

决策	放置位置
可复用的追踪／上下文辅助功能	@prefactor/core
Provider 请求／响应映射	你的适配器包
Span 生命周期逻辑	@prefactor/core + 精简封装调用
仅限 Provider 的中间件／封装	你的适配器包

参考资料

• 使用 references/provider-package-checklist.md 查看实现检查清单。

常见错误

• 为每个 Provider 重新实现追踪生命周期，而不是复用 Core。
• 使用通用 Span 名称，而不是带 Provider 前缀的类型。
• 捕获原始负载但不进行截断／脱敏。
• 在检测后吞掉 Provider 错误。