kitaru-adapter-builder

Kitaru 适配器构建器

首先选择最小且如实的受支持集成。只有当没有受支持的路径满足所请求的录制和回放边界时，才在用户的项目中构建适配器。保留框架的公共入口点，并准确说明所选适配器或自定义适配器能够观察、录制、回放什么，以及能够从什么情况中恢复。

不要假设所有框架都能提供相同的保真度。有价值的结果可以是经过本地测试的适配器，也可以是与已安装版本和公共钩子相关的明确阻碍说明。

核心约定

• 从只读检查用户的项目和已安装的软件包开始。
• 如果受支持的 Kitaru 适配器、导入器或 OTLP 导出能够满足所请求的录制和回放需求，则优先使用。不要创建重复集成。
• 对于已集成 Langfuse、Braintrust、LangSmith、Logfire 或 Arize Phoenix 的 Python Agent，提出自定义代码之前，请先检查该提供方是否有基于导入器的适配器。阅读Python 适配器参考，了解软件包和能力约定。
• 以用户已安装的 SDK 和框架为准。将 Kitaru 参考适配器用作模式，而不是复制来源，也不能据此证明某个 API 已发布。
• 仅使用框架的公共钩子。如果完整覆盖需要访问私有内部实现，则改用更粗粒度的边界，或停止操作。
• 首先在用户的项目中实现。未经用户另行批准，不要编辑 Kitaru 核心，也不要准备上游贡献。
• 隔离每次运行的会话 ID、客户端、节点索引、缓冲区、回放状态和框架上下文。绝不要将调用状态存储在共享包装器上。
• 将部分录制的运行视为部分或失败证据。绝不要仅因应用成功返回，就称其为完整跟踪。
• 将回放视为执行，而非事务。除非所选策略和用户批准确保安全，否则应阻止未知副作用或具有写入能力的副作用。
• 未经相关批准，绝不要安装依赖项、调用需要凭据的提供方、创建远程 Kitaru 会话、执行具有写入能力的工具或发布更改。
• 运行每条 Kitaru CLI 命令和 SDK 脚本时，都要设置 KITARU_ACTIVE_SKILL=kitaru-adapter-builder，以便服务器将产生的活动归因于此技能。
• 使用 --concurrency 10 启动或重启由用户控制的工作进程。只有当启动界面通过环境变量而非 CLI 选项提供工作进程设置时，才使用 KITARU_WORKER_CONCURRENCY=10。

从项目入手

从包含实际 Agent 入口点的项目开始。

1. 阅读仓库说明并检查工作树。保留所有现有及并发变更。
2. 确定应用实际使用的包管理器、锁文件、运行时、语言、框架及其版本、Kitaru 包及其版本、公开 Agent 入口点和调用模式。
3. 按入口点的运行时选择路径：
   • 对于 Python，阅读Python 适配器参考。
   • 对于 TypeScript，阅读 TypeScript 适配器参考。
   • 对于其他运行时，停止并报告不支持该语言。
4. 阅读适配器方法，搜索项目、已安装的包和当前 Kitaru 文档，查找兼容的适配器、导入器或 OTLP 路径，并在编辑代码前完成适配器评估。
5. 在敲定设计或编写测试前，阅读验证与报告。

对于混合语言仓库，应从执行 Agent 的进程选择路径。不要仅仅因为仓库中存在两种语言，就加载两份语言参考文档。

如果有受支持的、基于导入器的适配器适用于该提供方、公开 Python 入口点和所请求的记录边界，请仅在获批后安装，并包装该入口点。它会在运行后根据提供方跟踪创建 Kitaru 会话；它不会拦截模型或工具调用。不要仅为实现记录功能而构建重复的适配器。若请求需要运行时覆盖或非透传工具策略，则改用原生适配器。

如果框架已按任何内置导入器均不支持的格式导出跟踪，且这些事后证据满足用户目标，则改用 kitaru-importer-builder，而不是包装实时入口点。传递仓库和修订版本、公开入口点、框架及其版本、导出来源和格式、Kitaru 包及其版本、目标 Agent 及其版本，以及所请求的证据。选择此路径后，不要仅仅因为导入器提到适配器是另一种选择，就退回原路径。

明确所需的保真度

在选择实现方案前，先分别回答以下问题：

问题	可能的答案
记录边界	整次调用、轮次、模型步骤、工具调用、子 Agent 调用，或更粗粒度的 Span
回放级别	输入重跑、轮次回放、框架原生边界回放、更细粒度的检查点回放，或不作此声明
工具可见性	本地工具、MCP 工具、提供方原生工具、隐藏的框架工具，或未知
调用模式	异步、同步、流式传输、手动迭代、批处理、交接、恢复、中断，或持久化执行
失败策略	Kitaru 失败会导致调用失败，或记录采用尽力而为并明确返回降级结果

不要在不说明级别的情况下使用“回放”一词。再次运行相同的根输入属于输入重跑，并非确定性回放。

对于流式传输，请分别说明以下三项：

1. 应用仍会产出令牌或事件；
2. 适配器会持续观察流，直至完成、失败、取消或中止；
3. 回放会复现原始数据块或时间安排。

支持其中一项并不能证明另外两项。

必要时先停止，不要编写代码

出现以下任一情况时，停止并说明确切原因：

• 现有的兼容适配器、导入器或 OTLP 路由已能满足请求；
• 项目不是 Python 或 TypeScript；
• 尚未安装或批准安装可用的公开 Kitaru SDK 契约；
• 框架在所需边界处没有公开钩子；
• 唯一的 Python 入口点是同步的，而可用的 Kitaru 契约是异步的，且没有文档说明的安全异步框架钩子；
• 所请求的行为依赖隐藏的提供方或框架活动；
• 重放安全性需要匹配数量、出现次数标识或其他已安装 SDK 未公开的 Kitaru 契约；
• 不完整的导入基线无法证明重放副作用所需的调用；
• 所需依赖尚未发布，且用户未批准使用本地 tarball 或工作区链接路径。

不要用手写 REST 调用、临时搭建的事件循环桥接、私有框架导入或复制的草稿插件代码来替代缺失的 SDK 契约。

设置明确的批准关卡

只读发现不需要单独批准。执行任何会更改用户环境或外部状态的操作前，都要先征求批准：

操作	所需批准
安装或更改依赖	确切的软件包、版本和包管理器命令
使用本地未发布的 TypeScript 产物	确切的 tarball 或工作区链接路径
调用模型或其他需要凭证的提供方	提供方、预期调用及成本或数据影响
创建远程 Kitaru 会话	端点、租户、捕获的类别及测试目的
允许实时工具直通	确切的工具、影响类别及未命中条件
准备 OSS 贡献	目标仓库、文件及贡献范围

对某一行的批准不授权其他行的操作。

分阶段、限范围地实施

按以下顺序进行：

1. 通过确定性的本地探测，确认公开框架钩子。
2. 定稿适配器评估和能力声明。
3. 实现每次运行的状态以及会话／根节点生命周期。
4. 仅在公开钩子能够证明可行时，添加模型、工具、子 Agent 和流式观测。
5. 仅在基线可采纳性和副作用关卡通过后，添加重放功能。
6. 在进行广泛序列化之前，定义范围受限的允许列表载荷投影。
7. 使用伪对象测试成功、主要应用程序故障、Kitaru 写入失败、并发、取消，以及每项声称支持的重放策略。
8. 检查记录的会话和节点树，不要只相信应用程序结果。
9. 生成能力报告。

保持框架的公开签名、返回值、已配置回调、异常行为和类型接口不变。如果无法保持这些内容不变，请在实施前报告 API 变更。

将故障视为证据

保留最先发生的应用程序或适配器故障。尝试记录终止故障，但不要掩盖该故障；后续的记录或清理错误应单独报告。

如果会话创建成功，但后续写入失败：

• 保留已确认的节点；
• 记录最后一次已确认的写入；
• 尝试将根节点和会话标记为失败；
• 不要声称跟踪记录完整；
• 根据适配器文档规定的 Kitaru 可用性策略处理应用程序调用。

此处，不完整的导入跟踪记录属于重放输入问题。评估后停止不安全的重放。不要在此技能中修复或重新设计导入器。

安全恢复

恢复运行时，重新读取项目、工作树、已安装版本、适配器评估和测试。重新确认所选钩子和 SDK 符号仍然存在。不要覆盖用户的更改，也不要仅因无法访问先前的对话记录就重复安装依赖或执行远程冒烟测试。

以坦诚的方式交接

使用验证与报告中的能力报告格式。说明哪些内容已通过伪造环境验证，哪些内容已通过真实的 Kitaru 会话验证，以及还有哪些内容不受支持或尚未验证。

每种声称支持的模式都在本地通过后，再提供一个独立的可选贡献步骤。不要仅仅因为正常流程可用，就暗示项目本地适配器已达到上游接纳的标准。