kitaru-importer-builder
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseKitaru importer builder
Kitaru导入器构建工具
Turn a representative provider export into a locally validated Kitaru importer. Keep the path from source evidence to normalized sessions explicit so the user can see what is preserved, approximated, or unavailable.
Finish locally by default. Register code or upload trace data only when the user asks and approves each action separately.
将具有代表性的供应商导出数据转换为经过本地验证的Kitaru导入器。保持从源证据到标准化会话的路径清晰可见，以便用户了解哪些内容被保留、近似或无法获取。
默认在本地完成操作。仅当用户提出请求并单独批准每项操作时，才注册代码或上传跟踪数据。
Core contract
核心约定
- Treat the installed Kitaru version and its offline schema as authoritative. Use repository examples as patterns, not proof that a command or field is installed.
- Treat trace content as sensitive. Keep raw exports out of version control and redact fixtures before writing them into the target repository.
- Keep export acquisition outside the importer. The parser consumes static bytes and parameters without network calls, filesystem writes, subprocesses, or credential reads.
- Map the source before writing code. Record accepted payload shapes, identity, hierarchy, ordering, node fields, status, completeness, and intentionally unsupported data.
- Prefer a private, single-file script importer. Use a package only when the user already has a distribution reason and the worker can install one exact pinned version.
- Preserve useful incomplete evidence. Distinguish an unreadable payload, an invalid item, and a valid but incomplete session.
- Join traces conservatively. A common key is insufficient without source-instance scope and meaningful turn order.
- Do not overwrite an existing importer file, register executable code, upload trace data, or retry a partial import without an explicit checkpoint.
- Ask separately before installing the exact importer dependencies and before running a local importer test.
- Run any untrusted or newly generated importer, including code created in the current task, only in a credential-free isolated environment. Stop if that isolation is unavailable.
- Treat local importer testing as code execution in a bounded child process, not as a security sandbox.
- Offer packaging or upstream contribution only after local success. Do not make either a completion requirement.
- Run every Kitaru CLI command and SDK script with set so the server attributes the resulting activity to this skill.
KITARU_ACTIVE_SKILL=kitaru-importer-builder - Start or restart a user-controlled worker with . Use
--concurrency 10only when the launch surface exposes worker settings through environment variables instead of CLI options.KITARU_WORKER_CONCURRENCY=10
- 以已安装的Kitaru版本及其离线架构为权威依据。将仓库示例视为参考模式，而非命令或字段已安装的证明。
- 将跟踪内容视为敏感数据。避免将原始导出数据纳入版本控制，在将测试用例写入目标仓库前先进行脱敏处理。
- 将导出数据获取流程与导入器分离。解析器仅处理静态字节和参数，不进行网络调用、文件系统写入、子进程操作或凭证读取。
- 在编写代码前先梳理源数据结构。记录已确认的负载格式、标识信息、层级关系、排序规则、节点字段、状态、完整性以及有意不支持的数据类型。
- 优先选择私有单文件脚本导入器。仅当用户已有分发需求且可安装指定的固定版本时，才使用包形式的导入器。
- 保留有用的不完整证据。区分不可读负载、无效条目和有效但不完整的会话。
- 保守地合并跟踪数据。仅靠通用键不足以完成合并，还需源实例范围和有意义的轮次顺序。
- 若无明确的检查点，不得覆盖现有导入器文件、注册可执行代码、上传跟踪数据或重试部分导入操作。
- 在安装确切的导入器依赖项和运行本地导入器测试前，需分别征得用户同意。
- 仅在无凭证的隔离环境中运行任何不受信任或新生成的导入器（包括当前任务中创建的代码）。若无法提供隔离环境，则停止操作。
- 将本地导入器测试视为在受限子进程中执行代码，而非安全沙箱。
- 仅在本地测试成功后，才提供打包或上游贡献选项。不得将这两项作为完成任务的强制要求。
- 运行所有Kitaru CLI命令和SDK脚本时，需设置，以便服务器将相关活动归因于本技能。
KITARU_ACTIVE_SKILL=kitaru-importer-builder - 使用启动或重启用户控制的worker。仅当启动界面通过环境变量而非CLI选项暴露worker设置时，才使用
--concurrency 10。KITARU_WORKER_CONCURRENCY=10
Keep the experience clear
保持体验清晰
- Lead with the current state and the next decision.
- Ask only for evidence that the repository, provider documentation, sample, or installed Kitaru schema cannot establish.
- Show mapping and fidelity decisions in compact tables rather than dumping source records.
- Keep exact IDs, versions, warnings, and recovery identifiers visible.
- State whether each claim comes from provider documentation, a sample export, installed Kitaru, or an inference.
- Stop at a useful local checkpoint when a capability, permission, source sample, or worker route is missing.
- 先告知当前状态和下一步决策。
- 仅询问仓库、供应商文档、样本或已安装Kitaru架构无法确定的信息。
- 以紧凑表格形式展示映射和保真度决策，而非直接输出源记录。
- 确保确切的ID、版本、警告和恢复标识可见。
- 说明每项声明的来源：供应商文档、样本导出数据、已安装的Kitaru，或推断结果。
- 当缺少功能、权限、源样本或worker路由时，在有用的本地检查点停止操作。
Load references only when needed
仅在需要时加载参考文档
- Read references/importer-contract.md before scaffolding, testing, registering, or importing. It contains the parser contract, capability fingerprint, installation modes, commands, identity consequences, and remote-state boundaries.
- Read references/normalization-patterns.md before mapping source records, rebuilding a graph, joining turns, deriving status, or reporting fidelity.
- Read references/failure-and-validation.md before writing fixtures and assertions, executing unfamiliar code, handling malformed or incomplete traces, or recovering from a partial remote import.
- 在搭建、测试、注册或导入前，阅读references/importer-contract.md。该文档包含解析器约定、功能指纹、安装模式、命令、标识影响和远程状态边界。
- 在映射源记录、重建图谱、合并轮次、推导状态或报告保真度前，阅读references/normalization-patterns.md。
- 在编写测试用例和断言、执行不熟悉的代码、处理格式错误或不完整的跟踪数据，或从部分远程导入中恢复前，阅读references/failure-and-validation.md。
Resolve the starting state
确定初始状态
Start read-only.
- Identify the target repository, provider or format, representative export, and intended use of the imported sessions.
- Inspect the installed Kitaru version, offline command schema, and parser import path.
- Build the capability fingerprint in references/importer-contract.md.
- Inspect existing local importer files. When a Kitaru connection is already configured, also inspect the installed importer catalog. If a suitable exact importer version accepts the observed payload shape, stop and return it to the calling workflow instead of scaffolding another one. When no connection is available, continue the local workflow without requiring registry discovery.
- Otherwise, decide whether to add a version to an existing custom importer or create a new private name.
- Stop before overwriting a path or changing the installed Kitaru version.
If importer scaffolding, local testing, registration, exact-version import, or the required parser types are absent, name the missing capability. Do not give draft commands as though they were released. The user may choose a compatible Kitaru environment separately.
If routed the user here, retain the agent and investigation context. Return to the investigation only after relevant sessions are actually usable.
kitaru-investigationIf the source exists only behind a live framework entrypoint and no usable static export can meet the user's goal, continue with . Carry forward the repository and revision, public entrypoint, language, installed framework and Kitaru versions, requested evidence, target agent and version, and investigation goal. Choose this route once; do not bounce back merely because the adapter mentions importers as an alternative.
kitaru-adapter-builder初始阶段仅执行只读操作。
- 确定目标仓库、供应商或格式、代表性导出数据以及导入会话的预期用途。
- 检查已安装的Kitaru版本、离线命令架构和解析器导入路径。
- 构建references/importer-contract.md中的功能指纹。
- 检查现有本地导入器文件。若已配置Kitaru连接，还需检查已安装的导入器目录。若有合适的精确导入器版本可处理当前负载格式，则停止搭建新导入器，将其返回给调用工作流。若无可用连接，则继续本地工作流，无需进行注册表发现。
- 否则，决定是为现有自定义导入器添加版本，还是创建新的私有名称。
- 在覆盖路径或更改已安装的Kitaru版本前停止操作。
若缺少导入器搭建、本地测试、注册、精确版本导入或所需的解析器类型，请明确指出缺失的功能。不得将草稿命令当作已发布命令提供。用户可自行选择兼容的Kitaru环境。
若用户是通过路由至此，请保留Agent和调查上下文。仅当相关会话实际可用后，才返回调查流程。
kitaru-investigation若源数据仅存在于实时框架入口点后，且无可用的静态导出数据能满足用户目标，则继续使用。传递仓库和修订版本、公共入口点、语言、已安装的框架和Kitaru版本、请求的证据、目标Agent和版本以及调查目标。仅选择此路由一次；不得仅因适配器提及导入器作为替代方案而来回切换。
kitaru-adapter-builderAcquire a safe representative sample
获取安全的代表性样本
Prefer an existing static export. When the provider offers only an authenticated or paginated API, treat export acquisition as a separate task with its own approval, credentials, pagination, rate limits, and resumability.
Before writing a fixture:
- Keep the raw export outside the repository.
- Minimize it to the smallest records that preserve the behavior under test.
- Redact prompts, completions, tool arguments and results, end-user identifiers, credentials, provider-specific secrets, span and resource attributes, request and response headers, URLs and query strings, file contents and attachments, and error or exception details.
- Review the minimized fixture for residual secrets and direct identifiers.
- Preserve field shapes, relationships, and ordering evidence needed by assertions.
Do not place provider credentials in shell arguments, importer parameters, fixtures, inline dependency metadata, uploaded source, or logs.
优先使用现有静态导出数据。若供应商仅提供需认证或分页的API，则将导出数据获取视为单独任务，需单独获得批准，并处理凭证、分页、速率限制和可恢复性。
在编写测试用例前：
- 将原始导出数据存放在仓库外。
- 将其最小化为能保留测试行为的最小记录集。
- 脱敏提示词、补全内容、工具参数和结果、终端用户标识、凭证、供应商特定密钥、跨度和资源属性、请求和响应头、URL和查询字符串、文件内容和附件，以及错误或异常详情。
- 检查最小化后的测试用例是否残留密钥和直接标识。
- 保留断言所需的字段格式、关系和排序证据。
不得将供应商凭证放入shell参数、导入器参数、测试用例、内联依赖元数据、上传源或日志中。
Record the source map
记录源映射
Before implementation, produce this checkpoint:
| Decision | Evidence and chosen behavior |
|---|---|
| Payload shapes | Supported export variants and representative redacted files |
| Source instance | Account, workspace, project, collector, or explicit override |
| Session identity | Native session, thread, or conversation ID; trace fallback |
| Turn order | Provider sequence, or one trustworthy clock domain and precision |
| Root and hierarchy | Root selection, parent field, missing-parent and cycle behavior |
| Node mapping | Span, LLM, tool, and subagent fields plus bounded metadata |
| Status and error | Root outcome and descendant-failure semantics |
| Completeness | Missing hierarchy, payloads, tools, usage, cost, or timestamps |
| Safety limits | Numeric byte, record-count, and nesting-depth limits |
| Installation | Script dependencies or exact package and worker route |
Mark every relevant source field as mapped, preserved as bounded metadata, or intentionally unsupported. Ground expected mappings in provider documentation or an independently reviewed sample, not only in the implementation's own output.
在实现前，完成以下检查点：
| 决策项 | 证据及选定行为 |
|---|---|
| 负载格式 | 支持的导出变体及代表性脱敏文件 |
| 源实例 | 账户、工作区、项目、收集器，或显式覆盖设置 |
| 会话标识 | 原生会话、线程或对话ID；跟踪数据备选方案 |
| 轮次顺序 | 供应商提供的序列，或可信的时钟域及精度 |
| 根节点与层级 | 根节点选择、父字段、缺失父节点和循环处理行为 |
| 节点映射 | 跨度、LLM、工具和子Agent字段，以及有限元数据 |
| 状态与错误 | 根节点结果及子节点失败语义 |
| 完整性 | 缺失的层级、负载、工具、使用情况、成本或时间戳 |
| 安全限制 | 字节数、记录数和嵌套深度的数值限制 |
| 安装方式 | 脚本依赖项，或精确包及worker路由 |
将每个相关源字段标记为已映射、作为有限元数据保留，或有意不支持。预期映射需基于供应商文档或独立审核的样本，而非仅依赖实现自身的输出。
Implement the smallest coherent importer
实现最小化的连贯导入器
- Scaffold a script only after the installed schema confirms the command and destination.
- Keep one top-level parser entrypoint with the installed signature.
Parser - Parse the complete payload into deterministic source groups.
- Validate identities and graph structure before yielding a session.
- Yield valid sessions and isolated item failures incrementally.
- Keep provider-specific helpers private to the file unless package mode is already justified.
- Use only safe deserializers. Reject unsafe formats or convert them in the separate acquisition step.
- Apply the declared byte limit before decoding, enforce the depth limit during tokenization or decoding before full materialization, and apply the record limit before expensive normalization.
Use references/normalization-patterns.md for identities, joins, topology, status, metadata, readiness, and content digests.
- 仅在已安装的架构确认命令和目标后，才搭建脚本。
- 保留一个符合已安装签名的顶级解析器入口点。
Parser - 将完整负载解析为确定性源组。
- 在生成会话前验证标识和图谱结构。
- 逐步生成有效会话和孤立的条目失败信息。
- 除非已证明需要包模式，否则将供应商特定的辅助函数设为文件私有。
- 仅使用安全的反序列化器。拒绝不安全格式，或在单独的获取步骤中进行转换。
- 在解码前应用声明的字节限制，在令牌化或解码期间（完全实例化前）执行深度限制，在昂贵的标准化操作前应用记录限制。
使用references/normalization-patterns.md处理标识、合并、拓扑、状态、元数据、就绪状态和内容摘要。
Validate locally
本地验证
Use two layers of evidence:
- Provider-grounded assertions verify normalized values, identity, ordering, topology, status, warnings, readiness, and digest behavior.
- The installed local importer test verifies that Kitaru can load the entrypoint and that yielded values satisfy its runtime types.
Cover the applicable cases from references/failure-and-validation.md. At minimum include one complete item, one valid incomplete item, and one invalid item or payload boundary. Add joining, changed-content, and graph cases when the source supports them.
Do not treat a successful local importer test as semantic proof. Inspect the yielded sessions and compare them with the source map.
使用两层证据：
- 基于供应商的断言验证标准化值、标识、排序、拓扑、状态、警告、就绪状态和摘要行为。
- 已安装的本地导入器测试验证Kitaru能否加载入口点，以及生成的值是否满足其运行时类型要求。
覆盖references/failure-and-validation.md中的适用场景。至少包含一个完整条目、一个有效的不完整条目，以及一个无效条目或负载边界。当源数据支持时，添加合并、内容变更和图谱相关场景。
不得将本地导入器测试成功视为语义正确性的证明。需检查生成的会话并与源映射进行对比。
Report the local checkpoint
报告本地检查点
Return a compact report:
| Area | Result |
|---|---|
| Importer | Path and entrypoint |
| Supported source | Provider, export variants, and source-instance rule |
| Identity | Session and node ID derivation; rerun behavior |
| Joining | Key, scope, order, fallback, or not applicable |
| Fidelity | Complete, partial, and intentionally unsupported fields |
| Replay readiness | Ready, partial, or unavailable with concrete reasons |
| Validation | Assertions and installed Kitaru test results |
| Remote state | None, unless separately approved |
This is a successful authoring milestone. The importer becomes usable in a remote Kitaru deployment only after registration and an observed smoke import.
返回简洁报告：
| 领域 | 结果 |
|---|---|
| 导入器 | 路径及入口点 |
| 支持的源 | 供应商、导出变体及源实例规则 |
| 标识 | 会话和节点ID推导逻辑；重运行行为 |
| 合并 | 键、范围、顺序、备选方案，或不适用 |
| 保真度 | 完整、部分及有意不支持的字段 |
| 重放就绪状态 | 就绪、部分就绪，或不可用并说明具体原因 |
| 验证 | 断言及已安装Kitaru的测试结果 |
| 远程状态 | 无，除非单独获得批准 |
这是一个成功的创作里程碑。导入器仅在注册并完成观测性冒烟导入后，才能在远程Kitaru部署中使用。
Gate remote registration
远程注册的准入控制
Proceed only when the user requests registration.
Before approval, show:
- the active Kitaru principal and target tenant or project;
- importer name, stable nonempty provider, exact source path, entrypoint, and dependency route;
- whether this creates a parent plus first version or another immutable version;
- that executable source or a package reference becomes remote state;
- the exact installed command and the receipt fields that will be preserved.
Require a stable nonempty provider before registration when remote deduplication or retry safety matters. Current Kitaru accepts an omitted provider, but provider-less imports are not reliably deduplicated. After approval, register once. Preserve the importer ID, exact version, source digest, and any blob or task identifiers. If parent creation succeeds and version creation fails, do not repeat the parent-creation command blindly.
仅当用户请求注册时才继续操作。
在获得批准前，展示：
- 当前Kitaru主体及目标租户或项目；
- 导入器名称、稳定非空供应商、精确源路径、入口点及依赖路由；
- 此操作是创建父级及首个版本，还是另一个不可变版本；
- 可执行源或包引用将成为远程状态；
- 确切的已安装命令及将保留的回执字段。
当远程去重或重试安全性至关重要时，注册前需提供稳定非空的供应商。当前Kitaru接受省略供应商的情况，但无供应商的导入无法可靠去重。获得批准后，仅注册一次。保留导入器ID、精确版本、源摘要及任何 blob 或任务标识。若父级创建成功但版本创建失败，不得盲目重复父级创建命令。
Gate the first smoke import separately
首次冒烟导入的单独准入控制
Proceed only when the user also approves uploading a bounded redacted payload.
Show the exact importer version, agent version, target tenant or project, payload, parameters, persistence, expected session identities, and the fact that this skill has no automatic cleanup path. When the installed schema exposes , require one unique durable smoke tag and include because current post-import tagging requires it. If tagging is unavailable, require a disposable agent or a clearly marked isolated source identity instead. Do not write minimized smoke fixtures into the ordinary production session population without a marker that the investigation flow can exclude.
--tag--waitCreate one import job and wait only through the installed supported mechanism. A local wait timeout does not stop the remote job. Preserve the smoke tag plus the blob, job, task, session, and terminal receipt identifiers. Tag application can fail after session import succeeds, so retain the session receipt and report that partial state rather than rerunning the import.
Classify the result as created, skipped duplicate, failed, or still running. Inspect representative imported sessions rather than trusting counts alone.
仅当用户同时批准上传受限脱敏负载时才继续操作。
展示确切的导入器版本、Agent版本、目标租户或项目、负载、参数、持久化设置、预期会话标识，以及本技能无自动清理路径的事实。当已安装的架构暴露选项时，需指定一个唯一的持久冒烟标签并添加，因为当前导入后标记需要此选项。若无法标记，则需使用一次性Agent或明确标记的隔离源标识。不得将最小化的冒烟测试用例写入常规生产会话集合，除非添加调查流程可排除的标记。
--tag--wait创建一个导入任务，并仅通过已安装的支持机制等待完成。本地等待超时不会停止远程任务。保留冒烟标签以及blob、任务、会话和终端回执标识。标记应用可能在会话导入成功后失败，因此需保留会话回执并报告此部分状态，而非重新运行导入。
将结果分类为已创建、已跳过重复项、失败或仍在运行。需检查代表性的导入会话，而非仅依赖计数。
Recover without compounding partial state
恢复时避免复合部分状态
Before proposing any retry, classify each relevant external identity:
| State | Meaning |
|---|---|
| Untouched | No session exists and the item did not run |
| Complete | Session and expected nodes exist |
| Skipped duplicate | The same nonempty provider and external ID already existed |
| Stale duplicate | Existing digest differs or the local joined export contains more turns |
| Incomplete | Session exists but expected node ingestion did not finish |
| Unrecoverable here | Installed Kitaru exposes no safe repair or deletion path |
Remember that session creation can succeed before node ingestion fails. With a stable nonempty registered provider, a direct rerun may then skip the existing external ID instead of repairing the session. Without one, a rerun may create another session instead. A growing joined conversation can produce a skip while the existing session contains fewer turns. Compare readable digest and trace-count metadata before classifying the skip; if the installed surface cannot expose that metadata, do not use incremental joined-conversation imports. Preserve evidence, patch and version the importer locally if needed, and propose only recovery operations the installed product actually exposes.
在提出任何重试建议前，对每个相关外部标识进行分类：
| 状态 | 含义 |
|---|---|
| 未处理 | 无会话存在且条目未运行 |
| 已完成 | 会话及预期节点均存在 |
| 已跳过重复项 | 相同的非空供应商和外部ID已存在 |
| 陈旧重复项 | 现有摘要不同，或本地合并的导出数据包含更多轮次 |
| 不完整 | 会话存在但预期节点导入未完成 |
| 无法在此恢复 | 已安装的Kitaru未提供安全的修复或删除路径 |
请记住，会话创建可能在节点导入失败前成功。若有稳定非空的已注册供应商，直接重运行可能会跳过现有外部ID而非修复会话。若无供应商，重运行可能会创建另一个会话。不断增长的合并对话可能会导致跳过，而现有会话包含的轮次更少。在分类跳过情况前，对比可读摘要和跟踪计数元数据；若已安装的界面无法暴露该元数据，则不要使用增量合并对话导入。保留证据，若需则在本地修补并版本化导入器，仅提出已安装产品实际支持的恢复操作。
Finish
完成
When local validation or the requested smoke import succeeds:
- Return the exact artifacts, supported source shapes, fidelity limits, and verification results.
- Return the durable smoke tag, every smoke-test session ID, and any disposable-agent or isolated-source marker. Route the user back to when usable non-smoke sessions now exist, carrying the exclusion set forward.
kitaru-investigation - Ask whether they want to keep the importer private, package it for their environment, or consider contributing it upstream.
- Do not publish, contribute, or broaden provider support without a separate request.
当本地验证或请求的冒烟导入成功时：
- 返回确切的工件、支持的源格式、保真度限制及验证结果。
- 返回持久冒烟标签、所有冒烟测试会话ID，以及任何一次性Agent或隔离源标记。当可用的非冒烟会话存在时，将用户路由回，并传递排除集合。
kitaru-investigation - 询问用户是否希望将导入器设为私有、为其环境打包，或考虑向上游贡献。
- 若无单独请求，不得发布、贡献或扩展供应商支持。