kitaru-importer-builder

Kitaru 导入器构建器

将有代表性的提供方数据转化为经过本地验证的 Kitaru 导入器，用于静态导出或有界 API 查询。明确呈现从源证据到规范化会话的处理路径，让用户了解哪些内容得以保留、哪些经过近似处理，以及哪些内容不可用。

默认在本地完成。只有在用户提出要求并分别批准每项操作后，才注册代码或上传跟踪数据。

核心约定

• 将已安装的 Kitaru 版本及其离线架构视为权威依据。将仓库示例用作参考模式，而非命令或字段已安装的证明。
• 将跟踪内容视为敏感信息。不要将原始导出纳入版本控制；将样例数据写入目标仓库前先做脱敏处理。
• 将解析与数据获取分开。解析器接收字节和参数，不执行网络调用、文件系统写入、子进程或凭据读取；可选的 fetch(query) 方法可以读取提供方凭据并请求 API 负载。
• 编写代码前先梳理数据源。记录可接受的负载形状、身份标识、层级结构、排序、节点字段、状态、完整性，以及有意不支持的数据。
• 优先使用私有的单文件脚本导入器。只有用户已有分发需求，且工作进程能够安装一个精确固定版本时，才使用软件包。
• 保留有价值的不完整证据。区分无法读取的负载、无效条目，以及有效但不完整的会话。
• 谨慎关联跟踪。仅有共同键并不足够；还必须具备数据源实例范围和有意义的轮次顺序。
• 未经明确确认，不要覆盖现有导入器文件、注册可执行代码、上传跟踪数据或重试部分导入。
• 安装精确版本的导入器依赖项前，以及运行本地导入器测试前，分别征求同意。
• 在无凭据的隔离环境中运行对任何不可信或新生成导入器的本地测试，包括当前任务中创建的代码。如果无法提供这种隔离，则停止操作。
• 将本地导入器测试视为在受限子进程中执行代码，而非安全沙箱。
• 只有本地操作成功后，才提出打包或向上游贡献的选项。二者均不得作为完成任务的必要条件。
• 运行每条 Kitaru CLI 命令和 SDK 脚本时，都要设置 KITARU_ACTIVE_SKILL=kitaru-importer-builder，以便服务将产生的活动归属到此技能。
• 使用 --concurrency 10 启动或重启用户控制的工作进程。只有当启动界面通过环境变量而非 CLI 选项提供工作进程设置时，才使用 KITARU_WORKER_CONCURRENCY=10。

保持体验清晰

• 开篇说明当前状态和下一步决策。
• 只索取仓库、提供方文档、样例或已安装 Kitaru 架构无法确定的证据。
• 用简洁的表格展示映射和保真度决策，不要直接倾倒源记录。
• 清楚呈现确切 ID、版本、警告和恢复标识符。
• 说明每项结论来自提供方文档、样例导出、已安装的 Kitaru，还是推断。
• 缺少功能、权限、源样例或工作进程路由时，停在有用的本地检查点。

按需加载参考资料

• 在搭建脚手架、测试、注册或导入前，阅读 references/importer-contract.md。其中包含解析器约定、能力指纹、安装模式、命令、身份标识的影响，以及远程状态边界。
• 在映射源记录、重建图结构、关联轮次、推导状态或报告保真度前，阅读 references/normalization-patterns.md。
• 在编写样例数据和断言、执行不熟悉的代码、处理格式错误或不完整的跟踪，或从部分远程导入中恢复前，阅读 references/failure-and-validation.md。

确定起始状态

从只读操作开始。

1. 确定目标仓库、提供方或格式、代表性导出文件，以及导入会话的预期用途。
2. 检查已安装的 Kitaru 版本、离线命令架构和解析器导入路径。
3. 在 references/importer-contract.md 中构建能力指纹。
4. 检查现有的本地导入器文件。如果已配置 Kitaru 连接，也要检查已安装的导入器目录。在自定义开发之前，检查静态解析和受支持的 API 获取方式。如果某个合适的精确版本导入器可以接受观察到的载荷形状，或可以获取所需的跟踪记录，请停止操作，并将其返回给调用工作流，而不是另行搭建导入器。如果没有可用连接，则继续本地工作流，无需发现注册表。
5. 否则，决定是为现有自定义导入器添加一个版本，还是创建一个新的私有名称。
6. 在覆盖路径或更改已安装的 Kitaru 版本之前停止。

如果缺少导入器脚手架搭建、本地测试、注册、精确版本导入或所需的解析器类型，请指出缺失的能力。不要把草拟命令说成已发布的命令。用户可以另行选择兼容的 Kitaru 环境。

如果 kitaru-investigation 将用户引导至此处，请保留 Agent 和调查上下文。只有在相关会话确实可用后，才返回调查流程。

如果源数据可通过运行中的 Langfuse、Braintrust、LangSmith、Logfire 或 Arize Phoenix Python 入口点访问，请先使用 kitaru-adapter-builder 检查提供方导入器包的 [adapter] extra。此受支持的路径会在每次运行后记录提供方跟踪记录；它不是自定义解析器。请保留 仓库和修订版本、提供方、公开入口点、已安装的 Kitaru 版本、目标 Agent 及其版本，以及所需的证据。

如果既没有静态导出文件，也没有提供方 API 数据，而目标需要新的进程内记录， 请继续使用 kitaru-adapter-builder。请保留仓库和 修订版本、公开入口点、语言、已安装的框架和 Kitaru 版本、 所需的证据、目标 Agent 及其版本，以及调查目标。选择此路径后，不要仅仅因为适配器将导入器列为替代方案就返回上一步。

获取安全的代表性样本

解析器测试优先使用现有的脱敏导出文件。对于 API 数据源，请先检查已安装导入器的获取支持和提供方连接架构。只有在该路径不足时，才构建自定义获取方法。使用模拟的提供方响应进行本地测试；实时获取需要经过授权且范围有限的查询，并具备提供方凭据、分页、速率限制和重试控制。

编写样本数据前：

1. 将原始导出文件保存在仓库之外。
2. 将其精简为能保留待测行为的最少记录。
3. 对提示词、补全内容、工具参数和结果、终端用户标识符、凭据、提供方专属机密、跨度和资源属性、请求和响应标头、URL 和查询字符串、文件内容和附件，以及错误或异常详情进行脱敏。
4. 检查精简后的样本，确认其中没有残留机密或直接标识符。
5. 保留断言所需的字段形状、关系和顺序证据。

不要将提供方凭据放入 shell 参数、导入器参数、样本数据、内联依赖元数据、上传的源代码或日志中。

记录源映射

实现前，先生成此检查点：

决策	证据与选定行为
负载形态	支持的导出变体和有代表性的脱敏文件
源实例	账户、工作区、项目、收集器或显式覆盖项
会话标识	原生会话、线程或对话 ID；跟踪 ID 作为回退
轮次顺序	提供方序列，或一个可信的时钟域及精度
根节点与层级	根节点选择、父级字段、缺失父级和循环的处理方式
节点映射	Span、LLM、工具和子 Agent 字段，以及有界元数据
状态与错误	根节点结果和后代失败语义
完整性	缺失的层级、负载、工具、用量、费用或时间戳
安全限制	数值型字节数、记录数和嵌套深度限制
安装	脚本依赖项，或准确的软件包和 Worker 路由

将每个相关源字段标记为已映射、保留为有界元数据，或有意不支持。预期映射应以提供方文档或经过独立审核的样本为依据，而不能只依赖实现自身的输出。

实现最小且完整的导入器

1. 只有在已安装的架构确认命令和目标位置后，才创建脚本框架。
2. 上传场景使用一个可调用的解析器；或者，按照已安装的契约，公开带有 parse 和可选 fetch 方法的导入器对象。
3. 将完整负载解析为确定性的源分组。
4. 生成会话前，先验证标识和图结构。
5. 增量生成有效会话，并隔离单项失败。
6. 除非已证明有必要采用软件包模式，否则将特定于提供方的辅助函数保留在文件内部。
7. 仅使用安全的反序列化器。拒绝不安全格式，或在单独的获取步骤中将其转换。
8. 在解码前应用已声明的字节限制；在完整物化前，于分词或解码过程中执行深度限制；并在开销较大的规范化之前应用记录数限制。

身份、关联、拓扑、状态、元数据、就绪度和内容摘要请参阅 references/normalization-patterns.md。

本地验证

使用两层证据：

1. 基于提供方资料的断言，用于验证规范化值、身份、顺序、拓扑、状态、警告、就绪度和摘要行为。
2. 已安装的本地导入器测试，用于验证 Kitaru 能否加载入口点，以及生成的值是否符合其运行时类型。

覆盖 references/failure-and-validation.md 中适用的情形。至少包括一个完整项、一个有效但不完整的项，以及一个无效项或负载边界情形。如果源支持关联、内容变更和图结构情形，也应加入测试。

不要将本地导入器测试成功视为语义正确性的证明。检查生成的会话，并将其与源映射进行比较。

汇报本地检查点

返回一份简明报告：

领域	结果
导入器	路径和入口点
支持的源	提供方、导出变体和源实例规则
标识	会话和节点 ID 的派生方式；重新运行行为
关联	键、作用域、顺序、回退方式，或不适用
保真度	完整、部分和有意不支持的字段
回放就绪度	就绪、部分就绪或不可用，并说明具体原因
验证	断言和已安装的 Kitaru 测试结果
远程状态	无，除非另行批准

这是一次成功的开发里程碑。只有完成注册并观察到一次试运行导入后，导入器才能在远程 Kitaru 部署中使用。

阻止远程注册

仅在用户请求注册时继续。

获得批准前，展示：

• 当前 Kitaru 主体以及目标租户或项目；
• 导入器名称、非空且稳定的 provider、确切源路径、入口点和依赖路径；
• 此操作会创建一个父项及其首个版本，还是另一个不可变版本；
• 可执行源代码或软件包引用将成为远程状态；
• 确切的已安装命令，以及将保留的回执字段。

当远程去重或重试安全性很重要时，注册前必须要求提供非空且稳定的 provider。当前 Kitaru 接受省略 provider，但不带 provider 的导入无法可靠去重。获得批准后，仅注册一次。保留导入器 ID、确切版本、源摘要，以及任何 blob 或任务标识符。如果父项创建成功而版本创建失败，不要盲目重复父项创建命令。

单独阻止首次冒烟导入

仅当授权涵盖上传有界的脱敏载荷或获取精确、有界的 provider 选择时继续。对于实时获取，先检查导入器，并且仅在获批的工作进程环境中使用预期的 provider 凭据；本地生成代码测试仍须保持无凭据。

展示确切的导入器版本、Agent 版本、目标租户或项目、载荷或查询与连接、参数、持久化方式、预期的会话标识，以及此技能没有自动清理路径这一事实。当已安装架构提供 --tag 时，必须要求一个唯一且持久的冒烟标签，并包含 --wait，因为当前导入后的打标签操作需要它。如果无法打标签，则必须使用可弃置的 Agent，或使用明确标记的隔离源标识。不要将精简后的冒烟夹具写入普通生产会话集合，除非附带可供调查流程排除的标记。

创建一个导入作业，并且仅通过已安装且受支持的机制等待。本地等待超时不会停止远程作业。保留冒烟标签以及 blob、作业、任务、会话和终止回执标识符。会话导入成功后，标签应用仍可能失败，因此应保留会话回执并报告这种部分状态，而不是重新运行导入。

将结果归类为已创建、重复项已跳过、失败或仍在运行。检查有代表性的导入会话，不要只依赖计数。

恢复时避免加重部分状态

提出任何重试前，先对每个相关外部标识进行分类：

状态	含义
未触及	不存在会话，且该项未运行
完成	会话及预期节点均存在
已跳过重复项	相同的非空 provider 和外部 ID 已存在
过期重复项	现有摘要不一致，或本地联接导出包含更多轮次
不完整	会话存在，但预期节点的摄取尚未完成
此处无法恢复	已安装的 Kitaru 未提供安全的修复或删除路径

请记住，会话创建可能在节点摄取失败前成功。如果已注册的 provider 非空且稳定，直接重跑可能会跳过现有外部 ID，而不是修复会话。如果没有这样的 provider，重跑可能会创建另一个会话。不断增长的联接对话可能导致跳过导入，而现有会话包含的轮次数更少。对照可读的摘要和跟踪计数元数据后，再判定为跳过；如果已安装的界面无法提供这些元数据，请勿使用增量式联接对话导入。保留证据；如有需要，在本地修补并为导入器创建新版本；仅提出已安装产品实际提供支持的恢复操作。

完成

本地验证或所请求的冒烟导入成功后：

1. 返回准确的产物、支持的源格式、保真度限制和验证结果。
2. 返回持久化的冒烟标签、每个冒烟测试会话 ID，以及任何一次性 Agent 或隔离源标记。如果现在存在可用的非冒烟会话，请将用户引导回 kitaru-investigation，并一并保留排除集。
3. 询问他们希望将导入器保持为私有工具、为其环境打包，还是考虑向上游贡献。
4. 未经单独请求，不得发布、贡献或扩大提供方支持范围。