kitaru-adapter-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kitaru adapter builder

Kitaru 适配器构建器

Build the smallest honest adapter inside the user's project. Preserve the framework's public entrypoint and report exactly what the adapter can observe, record, replay, and recover from.

Do not assume every framework can support the same fidelity. A useful result is either a locally tested adapter or a precise blocker tied to the installed versions and public hooks.

在用户项目内构建最小可用的合规适配器。保留框架的公开入口点，并准确报告适配器可观察、记录、重放以及恢复的内容。

不要假设所有框架都能支持相同的保真度。有效的结果要么是经过本地测试的适配器，要么是与已安装版本和公开钩子相关的明确阻塞点。

Core contract

核心约定

Start with read-only inspection of the user's project and installed packages.
Prefer supported Kitaru adapters, importers, or OTLP export when they meet the requested recording and replay needs. Do not create a duplicate integration.
Treat the user's installed SDK and framework as authority. Use Kitaru reference adapters as patterns, not as source to copy or as proof of a published API.
Use only public framework hooks. Offer a coarser boundary or stop when complete coverage would require private internals.
Implement in the user's project first. Do not edit Kitaru core or prepare an upstream contribution unless the user separately approves that work.
Keep per-run session IDs, clients, node indexes, buffers, replay state, and framework context isolated. Never store invocation state on a shared wrapper.
Treat a partially recorded run as partial or failed evidence. Never call it a complete trace because the application returned successfully.
Treat replay as execution, not a transaction. Block unknown or write-capable side effects unless the selected policy and user approval make them safe.
Never install dependencies, call credentialed providers, create a remote Kitaru session, execute write-capable tools, or publish changes without the relevant approval.
Run every Kitaru CLI command and SDK script with
```
KITARU_ACTIVE_SKILL=kitaru-adapter-builder
```
set so the server attributes the resulting activity to this skill.
Start or restart a user-controlled worker with
```
--concurrency 10
```
. Use
```
KITARU_WORKER_CONCURRENCY=10
```
only when the launch surface exposes worker settings through environment variables instead of CLI options.

从只读检查用户项目和已安装包开始。
当已支持的Kitaru适配器、导入器或OTLP导出满足记录和重放需求时，优先使用它们。不要创建重复集成。
将用户已安装的SDK和框架视为权威。仅将Kitaru参考适配器作为模式参考，而非可复制的源码或已发布API的证明。
仅使用框架的公开钩子。当完整覆盖需要依赖私有内部逻辑时，提供更粗略的边界或停止开发。
首先在用户项目内实现。除非用户单独批准，否则不要修改Kitaru核心代码或准备上游贡献。
隔离每次运行的会话ID、客户端、节点索引、缓冲区、重放状态和框架上下文。绝不要在共享包装器上存储调用状态。
将部分记录的运行视为部分或失败的证据。绝不要因为应用成功返回就称其为完整追踪。
将重放视为执行过程，而非事务。除非所选策略和用户批准确保安全，否则阻止未知或具备写入能力的副作用。
未经相关批准，绝不要安装依赖、调用需要凭证的提供商、创建远程Kitaru会话、执行具备写入能力的工具或发布变更。
运行所有Kitaru CLI命令和SDK脚本时，设置
```
KITARU_ACTIVE_SKILL=kitaru-adapter-builder
```
，以便服务器将相关活动归因于该技能。
使用
```
--concurrency 10
```
启动或重启用户控制的工作进程。仅当启动界面通过环境变量而非CLI选项暴露工作进程设置时，才使用
```
KITARU_WORKER_CONCURRENCY=10
```
。

Route from the project

从项目切入

Begin in the project that contains the real agent entrypoint.

Read the repository instructions and inspect the working tree. Preserve all existing and concurrent changes.
Identify the package manager, lockfile, runtime, language, framework and version, Kitaru package and version, public agent entrypoint, and invocation modes the application actually uses.
Route by the entrypoint's runtime:
- For Python, read the Python adapter reference.
- For TypeScript, read the TypeScript adapter reference.
- For another runtime, stop with an unsupported-language report.
Read the adapter method, search the project, installed packages, and current Kitaru documentation for a compatible adapter, importer, or OTLP path, and create the adapter assessment before editing code.
Read validation and reporting before finalizing the design or writing tests.

In a mixed repository, route from the process that executes the agent. Do not load both language references merely because both languages exist somewhere in the repository.

If the framework already exports traces in a format no built-in importer supports and that post-hoc evidence meets the user's goal, continue with

kitaru-importer-builder

instead of wrapping the live entrypoint. Carry forward the repository and revision, public entrypoint, framework and version, export source and shape, Kitaru package and version, target agent and version, and requested evidence. Choose this route once; do not bounce back merely because the importer mentions an adapter as an alternative.

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

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

在混合仓库中，从执行Agent的进程切入。不要仅仅因为仓库中同时存在两种语言就加载两种语言的参考文档。

如果框架已以内置导入器不支持的格式导出追踪数据，且该事后证据满足用户目标，则继续使用

kitaru-importer-builder

而非包装实时入口点。传递仓库和修订版本、公开入口点、框架及其版本、导出源和格式、Kitaru包及其版本、目标Agent及其版本，以及所需证据。一旦选择此路径，不要仅仅因为导入器提到适配器作为替代方案就来回切换。

Establish the requested fidelity

明确所需的保真度

Separate these questions before choosing an implementation:

Question	Possible answer
Recording boundary	Whole invocation, turn, model step, tool call, subagent call, or coarser span
Replay tier	Input rerun, turn replay, framework-native boundary replay, finer checkpoint replay, or not claimed
Tool visibility	Local tools, MCP tools, provider-native tools, hidden framework tools, or unknown
Invocation modes	Async, sync, streaming, manual iteration, batch, handoff, resume, interrupt, or durable execution
Failure policy	Kitaru failure fails the invocation, or recording is best effort with an explicit degraded result

Do not use “replay” without naming the tier. Running the same root input again is an input rerun, not deterministic replay.

For streaming, keep three claims separate:

the application still yields tokens or events;
the adapter observes the stream through completion, failure, cancellation, and abandonment;
replay reproduces the original chunks or timing.

Supporting one does not prove the others.

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

问题	可能的答案
记录边界	完整调用、轮次、模型步骤、工具调用、子Agent调用，或更粗粒度的跨度
重放层级	输入重跑、轮次重放、框架原生边界重放、更细粒度的检查点重放，或不支持
工具可见性	本地工具、MCP工具、提供商原生工具、隐藏框架工具，或未知
调用模式	异步、同步、流式、手动迭代、批量、移交、恢复、中断，或持久化执行
失败策略	Kitaru失败导致调用失败，或记录为最大努力模式并返回明确的降级结果

不要在未指定层级的情况下使用“重放”一词。再次运行相同的根输入属于输入重跑，而非确定性重放。

对于流式场景，需区分三个声明：

应用仍会生成令牌或事件；
适配器能够全程观察流，包括完成、失败、取消和终止；
重放能够复现原始块或时序。

支持其中一项并不意味着支持其他项。

Stop before writing code when necessary

在必要时停止编写代码

Stop and give the exact reason when any of these apply:

a compatible existing adapter, importer, or OTLP route satisfies the request;
the project is not Python or TypeScript;
no usable public Kitaru SDK contract is installed or approved for installation;
the framework exposes no public hook at the required boundary;
the only Python entrypoint is synchronous and the available Kitaru contract is async, with no documented safe async framework hook;
the requested behavior depends on hidden provider or framework activity;
replay safety requires match cardinality, occurrence identity, or another Kitaru contract the installed SDK does not expose;
an incomplete imported baseline cannot prove the calls needed for effectful replay;
the required dependency is unpublished and the user has not approved a local tarball or workspace-link path.

Do not replace a missing SDK contract with handwritten REST calls, an improvised event-loop bridge, private framework imports, or copied draft plugin code.

当出现以下任一情况时，停止操作并给出确切原因：

兼容的现有适配器、导入器或OTLP路径可满足需求；
项目并非Python或TypeScript；
未安装或未批准安装可用的Kitaru SDK公开契约；
框架在所需边界处未暴露任何公开钩子；
唯一的Python入口点是同步的，而可用的Kitaru契约是异步的，且无文档化的安全异步框架钩子；
所需行为依赖于提供商或框架的隐藏活动；
重放安全性需要匹配基数、事件标识或已安装SDK未暴露的其他Kitaru契约；
不完整的导入基线无法证明有效重放所需的调用；
所需依赖未发布，且用户未批准本地压缩包或工作区链接路径。

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

Use explicit approval gates

使用明确的审批关卡

Read-only discovery does not need a separate approval. Ask before each action that changes the user's environment or external state:

Action	Required approval
Install or change a dependency	Exact package, version, and package-manager command
Use a local unpublished TypeScript artifact	Exact tarball or workspace-link path
Call a model or other credentialed provider	Provider, expected calls, and cost or data consequence
Create a remote Kitaru session	Endpoint, tenant, captured categories, and test purpose
Permit live tool passthrough	Exact tools, effect class, and miss condition
Prepare an OSS contribution	Target repository, files, and contribution scope

Approval for one row does not authorize another.

只读发现无需单独审批。在执行任何会改变用户环境或外部状态的操作前，需先征得同意：

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

某一行的审批并不授权其他行的操作。

Implement in bounded checkpoints

分阶段实现

Use this order:

Confirm the public framework hook with a deterministic local probe.
Freeze the adapter assessment and capability claims.
Implement per-run state and the session/root lifecycle.
Add model, tool, subagent, and stream observation only where public hooks prove it.
Add replay only after the baseline-admissibility and side-effect gates pass.
Define bounded, allowlisted payload projections before broad serialization.
Test success, primary application failure, Kitaru write failure, concurrency, cancellation, and every claimed replay policy with fakes.
Inspect the recorded session and node tree rather than trusting only the application result.
Produce the capability report.

Keep the framework's public signature, return value, configured callbacks, exception behavior, and type surface intact. If preserving them is not possible, report the API change before implementing it.

按照以下顺序执行：

用确定性本地探针确认框架的公开钩子。
冻结适配器评估和能力声明。
实现每次运行的状态以及会话/根生命周期。
仅在公开钩子可证明的位置添加模型、工具、子Agent和流观察逻辑。
仅在基线可接受性和副作用检查通过后添加重放功能。
在进行广泛序列化前，定义有界的、白名单式的负载投影。
使用模拟对象测试成功场景、主要应用失败场景、Kitaru写入失败场景、并发场景、取消场景，以及所有声明的重放策略。
检查记录的会话和节点树，而非仅依赖应用结果。
生成能力报告。

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

Handle failures as evidence

将失败视为证据

Preserve the first application or adapter failure. Attempt terminal failure recording without masking that failure, and report later recording or cleanup errors separately.

If session creation succeeds and a later write fails:

retain already confirmed nodes;
record the last confirmed write;
try to mark the root and session failed;
do not claim the trace is complete;
apply the adapter's documented Kitaru-availability policy to the application invocation.

An incomplete imported trace is a replay-input problem here. Assess it and stop unsafe replay. Do not repair or redesign the importer inside this skill.

保留首次应用或适配器失败的记录。尝试记录终端失败而不掩盖该失败，并单独报告后续的记录或清理错误。

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

保留已确认的节点；
记录最后一次确认的写入；
尝试标记根节点和会话为失败；
不要声称追踪已完成；
将适配器文档化的Kitaru可用性策略应用于应用调用。

不完整的导入追踪属于此处的重放输入问题。评估该问题并停止不安全的重放。不要在此技能内修复或重新设计导入器。

Resume safely

安全恢复

On a resumed run, re-read the project, working tree, installed versions, adapter assessment, and tests. Recheck that the chosen hooks and SDK symbols still exist. Do not overwrite user changes or repeat dependency installation and remote smoke tests merely because an earlier transcript is unavailable.

在恢复运行时，重新读取项目、工作树、已安装版本、适配器评估和测试内容。重新检查所选钩子和SDK符号是否仍然存在。不要仅仅因为早期记录不可用就覆盖用户变更或重复依赖安装和远程冒烟测试。

Finish with an honest handoff

以诚实的交接收尾

Use the capability-report format in validation and reporting. State what was verified with fakes, what was verified against a real Kitaru session, and what remains unsupported or unverified.

After every claimed mode passes locally, offer a separate optional contribution step. Do not imply that a project-local adapter is upstream-ready merely because the happy path works.

使用验证与报告文档中的能力报告格式。说明哪些内容已通过模拟对象验证、哪些内容已通过真实Kitaru会话验证，以及哪些内容仍不受支持或未验证。