kitaru-replay-experiment

Kitaru 回放实验

针对已知案例测试一个候选条件，并说明现有证据是有所改善、变差、存在权衡，还是仍无法得出结论。不要做出部署决策。

核心约定

• 从已接受的行为、确切的队列版本、确切的评估器版本和参数，以及一项候选变更开始。仅在用户提出要求时，才建议一项范围明确的候选方案。
• 回放会对每个历史会话，从其存储的顶层输入开始一个全新的 Agent 任务，并应用覆盖项。它不会恢复任意检查点、对话、进程内存、适配器实例状态、文件系统或外部世界状态。
• 在询问是否运行实验之前，先确认适配器支持情况及其构建路径。共享的回放架构并不能证明适配器支持所请求的覆盖项或工具来源。
• 每次使用工具的运行都必须明确指定工具策略。若未指定，则会解析为在当前服务上实时透传；将其作为隐式默认值并不安全。
• 保留并传递确切的 ID、版本、评估器参数、运行规范证据、工具策略、失败情况和缺失结果。
• 执行前说明远程写入、模型和工作进程的计算、成本的不确定性，以及可能产生的实时影响。对此说明后的一次批准即可涵盖实验创建和运行启动；任何会产生外部影响的工具路径都需要单独批准。
• 仅使用 Kitaru 已确立的产品术语。不要为摘要或步骤创造标签，例如“运行卡片”“结果卡片”“Agent 指纹”或“执行校验和”。不要用听起来更亲切的别名（例如“已接受的基线”）替代 Kitaru 对象；必要时先解释官方术语，然后始终如一地使用该术语。面向用户时，应使用日常语言描述将要发生的事情以及用户必须做出的决定。
• 优先使用原生 Kitaru MCP 操作。若 MCP 未提供内置等待或其他能力，则使用结构化 CLI。若已安装的架构与参考资料不一致，请核实已安装的架构。
• 运行每条 Kitaru CLI 命令和 SDK 脚本时，都要设置 KITARU_ACTIVE_SKILL=kitaru-replay-experiment，以便服务将产生的活动归属到此技能。
• 使用 --concurrency 10 启动或重启用户控制的工作进程。只有在启动界面通过环境变量而非 CLI 选项提供工作进程设置时，才使用 KITARU_WORKER_CONCURRENCY=10。
• 绝不能通过直接 REST 调用或临时本地状态，绕过缺失的适配器、证据、比较结果或产品约定。

仅在需要时加载参考资料

• 在执行任何 Kitaru 操作或声称适配器具备某项能力之前，阅读 references/experiment-contract.md。
• 在选择比较类型、解读相互矛盾的结果、增加重复次数或评估用户定义的门槛之前，阅读 references/experiment-method.md。

确定起始状态

从只读操作开始。复用调查检查点或用户请求中的确切标识符，然后重新读取每个对象。

确定以下内容：

1. 已接受的行为和预期用途：探索、已知案例回归，还是用户精确定义的门槛；
2. 确切的队列版本 ID 和有序案例数；
3. 一个确切的候选 Agent 版本 ID，以及当前公开的运行规范和能力；
4. 确切的评估器版本 ID、父级 Agent 范围、参数，以及有关其检查内容和局限性的事实证据；
5. 一个拟议的重放覆盖项及其预期效果；
6. 适配器和构建路径；
7. 候选对象可能调用的每个工具，以及一项明确覆盖所有工具的策略。

如果尚未接受任何行为或队列，请转到 kitaru-investigation。如果不存在合适的评估器，或当前评估器不足以支撑预期的声明，请使用其评估器流程。如果用户只需要探索性结果，请提出降低声明标准，而不是强行走完验证流程。

如果实验或运行已存在，请重新读取并继续监督或解读。实验一旦有了运行，其配置便会冻结，因此对于实质上有所变更的候选对象、评估器集合、覆盖项或工具策略，请创建新实验。

批准前，重新读取每个评估器父级。只有其 agent_id 与实验的 Agent 匹配时，范围限定的评估器才符合条件。agent_id 为 null 的对象只可能是候选全局范围，因为删除范围限定评估器的 Agent 也会清除此字段。只有可信的创建记录或已知的默认目录身份能够证明其范围有意设为全局，或者在重新验证其标准、实现以及对实验 Agent 的预期复用方式后，才使用范围为 null 的父级。在创建实验前拒绝范围不匹配或未经验证的对象，不要寄希望于服务器报错；并在可恢复技术记录中保留已验证的范围及任何全局可移植性证据。

预检能力与安全性

在批准或付费执行前，拒绝不受支持的适配器条件。返回确切的阻塞原因和范围最小的受支持替代方案。若适配器或构造路径尚未解决，不要让用户继续批准。

在提出配置前，从候选版本的运行规范中读取 runtime_capabilities。 这两个字段的默认值均为 true。如果 overrides 为 false，且拟议的重放包含覆盖项，则停止。如果 tool_policies 为 false，且并非每个策略条目都明确设为透传，则停止。由导入器支持的 适配器版本会将两者都声明为 false：它们只能在不带覆盖项、且工具实时透传的情况下再次运行 Agent。说明这种实时执行的风险，并取得所需批准；不要提供历史记录、静态结果或 LLM 工具结果作为替代方案。

解析候选进程所需的模型提供商和凭据。当环境提供安全的就绪信号时，验证工作进程是否可用该凭据，但不要读取、显示或生成密钥值的指纹。编码 Agent 能看到的凭据，或存储在项目文件中的凭据，并不能证明已经运行的工作进程继承了该凭据。如果无法获取或验证工作进程的就绪状态，请让用户配置凭据并重启或配置工作进程，然后在创建实验或启动运行前停止。

对于使用工具的 Agent：

• 选择能够验证假设的工具来源。不要仅仅因为有可用的基线，就默认使用记录的历史。
• 如果候选版本可能改变工具选择或参数，对于已验证为确定性且隔离的本地固定数据，优先使用明确的透传。说明这仍会执行工具代码，指出其影响，并将其与外部实时系统区分开。
• 当固定记录的工具结果是预期比较的一部分，且适配器支持时，使用限定于基线的记录历史。说明查找会匹配先前调用；它不会恢复基线状态，也不允许使用新参数。
• 除非有意执行实时调用，否则历史或静态结果未命中时使用 fail 或 error_result。
• 将 on_miss=passthrough 视为实时透传，并单独进行把关。
• 警告：队列范围或 Agent 范围的历史可能借用过时状态或其他案例的状态。匹配依据为工具名称和规范化后的 JSON 参数。基线范围会按记录顺序重放每次完全相同的调用；更广的范围会选择该范围内最新的匹配项。
• 将 LLM 生成的结果视为合成条件，而非对历史外部世界的还原。
• 将工具执行失败与 Agent 质量问题分开处理。

检查参数完全相同的重复调用是否可能合理地返回不同值。基线范围会按顺序重放每次此类调用各自记录的结果；更广的范围则会对每次调用都返回最新的匹配项。基线范围是最窄的历史来源，但这并不能证明存储的结果仍然忠实。

如果透传和历史记录都适用，但会改变实验的含义，请说明具体差异，并询问用户希望采用哪种条件，除非已验证的项目专属约定明确选择了其中一种。

向用户确认运行

请求批准前，先用通俗易懂的语言向用户简要总结。尽量使用几个项目符号，而不是表格。仅包括：

• 正在测试的变更及其要回答的问题；
• 队列和评估器版本，以及案例数量；
• 每个新任务的起始状态，以及不会恢复的重要状态；
• 工具的行为方式，包括任何可能的外部影响；
• 预期的大模型和工作者工作量，以及成本的不确定性；以及
• 此项比较能够和不能够得出的结论。

只有在用户需要核实决策，或这些信息揭示了重大限制时，才提供确切的 Agent、实验或适配器详情。完整 ID、版本、参数、配置哈希和适配器证据应保存在可恢复的技术记录中，不要让用户在常规探索性运行前阅读全部内容。

在内部使用规范序列化，对完整的公开运行规范和能力模型进行哈希处理。不要解析或公开机密。在创建实验前以及开始执行前，立即重新读取这两个模型并比较哈希。如果任一模型发生变化，则批准失效，并说明具体是哪项配置发生了变化，但不要将哈希称为产品对象。确切的 Agent 版本 ID 标识的是可变配置，而不是不可变的可复现制品；这些检查无法冻结或证明工作者之后解析的配置。对于用户定义的门禁或实时影响运行，必须要求不可变的运行时身份，否则应将用途限制为探索。缺少该身份时，报告观察到的违规情况，但对于门禁应返回 cannot evaluate。对于探索性运行，保留已批准的哈希，在结算后重新读取模型；如果观察到漂移，则返回 inconclusive。

摘要显示后，只请求一次批准。如果直通模式可能影响外部系统，则另行请求批准所列出的实时工具及其影响。经验证的隔离式本地模拟执行可由首次批准涵盖。

创建并监督一次运行

获得批准后：

1. 创建一个实验，指定确切的 Agent 父项、重放覆盖设置、明确的工具策略，以及评估器版本和参数。
2. 重新读取实验，并验证服务端解析出的配置符合预期。
3. 在内部重新检查候选运行规范和能力模型的哈希。
4. 针对确切的队列版本和候选 Agent 版本启动一次运行。对于常规比较场景，使用 baseline_evaluation_mode=if_missing；只有在决策需要重新计算基线测量结果时才使用 force；仅在不打算与基线进行比较时才使用 none。
5. 持续监视异步运行，直到运行完成、失败、取消、达到约定的停止条件，或本地等待超时。
6. 读取运行结果以及所有用于统计已完成、失败、取消和缺失案例的分页重放任务。
7. 在结算后重新读取候选运行规范和能力模型。报告任何观察到的漂移，并说明仍存在瞬时变更未被检测到的剩余风险。

默认只运行一次。仅当随机性可能改变重要结论或临界结论时，才增加预先声明的匹配重复运行，并事先批准额外工作量和成本。

仅在用户提出要求或达到已批准的停止条件时取消运行。取消会保留证据。删除具有破坏性，不等同于取消。

读取精确证据

对于每个案例，解析与预期评估器版本 ID 和参数关联的评估结果。只有当会话、评估器版本和参数都匹配时，if_missing 才可以采用现有基线结果；回放链接会记录本次运行所采用或新生成的精确测量结果。

将运行聚合结果用作固定摘要：它只读取由回放链接关联的测量结果，不会因对相同会话进行后续评估而改变，并且除了结果名称和数据类型外，还会按评估器版本分组。确认实验的评估器参数，然后读取精确的逐会话证据，以检查配对变化、失败、已取消案例和缺失情况。每个比率旁都要显示原始计数和分母。失败、已取消和缺失结果不计入质量分母。

检查候选提示词、评估器提示词、示例、工具装置、历史记录范围和相关轨迹系列是否存在数据泄漏。探索阶段应发出警告。只有在预期用途会造成重大影响时，才要求解决问题或缩小声明范围。

说明结果

报告：

• 精确的实验和运行 ID、群组版本、候选版本、评估器版本及参数、工具策略和运行规格证据；
• 比较类型，以及恢复了哪些状态、未恢复哪些状态；
• 改进、退步、未变化、失败、已取消和缺失的案例数；对于非终态运行，还要报告待处理或评估中的案例数；
• 重要的配对案例变化和保护措施结果；
• 评估器的局限、溯源缺口和已知执行差异；
• 一个结论：improved、regressed、trade-off 或 inconclusive；
• 仅当用户提供了适用的门槛时，才报告是否meets、does not meet 或 cannot evaluate 该确切门槛；
• 一个有用的下一步行动。

不要说 ship。部署由用户负责。Kitaru 目前不提供公开的胜出者、发布策略、统计显著性或 CI 退出判定。

如果运行停滞、失败、已取消或仍不完整，请返回其当前精确状态、已完成、失败、已取消、缺失、待处理和评估中的计数、可恢复标识符，以及最小且安全的下一步操作。将已取消案例排除在质量分母之外，不要将其归入失败或缺失案例。如果回放揭示了真正的新行为或含糊行为，应将精确的会话证据交给范围受限的后续 kitaru-investigation，而不是悄悄更改评估器。

按要求推荐一个候选方案

按以下优先顺序选择：

1. 澄清含糊的指令或工具描述；
2. 添加一个小型、无数据泄漏的示例或确定性保护措施；
3. 更改一个流水线组件或模型设置；
4. 只有在较简单的干预无效后，才考虑更大幅度的结构或模型变更。

不要启动自动提示词搜索、级联、微调计划或多候选方案竞赛。