kitaru-guided-tour

Kitaru 引导游览

先让用户获得顿悟，再讲解完整方法。使用 Kitaru 的 PydanticAI returns Agent 示例，从已记录的轨迹开始，经过简短的预备前端审查和可复用的评估器，最终得到一个范围明确的实验结果。

体验约定

• 假设用户尚未阅读示例 Agent，也不了解 Kitaru 的工作方式。根据审查中可见的证据解释每个示例，将内部名称转换为通俗说法，绝不要求用户依赖缺失的代码或产品背景来理解问题。
• 做一位友好的向导，而不是隐形的自动化执行器。在每个重要的转换节点，解释本次导览正在做什么、这一步为何重要、它展示了哪个 Kitaru 概念，以及用户接下来可以看到或做什么。常规命令只需简要提及。
• 如果用户当前的指示明确偏好简洁或不作解释，则在开始导览前说明这一冲突。只询问一次：“这次引导游览最适合简要解释每个新概念及其重要性。导览期间，我可以比平时多作一些说明，同时简要处理常规命令和状态更新吗？”如果用户同意，则将其视为仅对本次导览有效的风格澄清，而不是忽略无关或更高优先级指示的许可。如果用户拒绝，仍应保持简洁，但要提供理解每个检查点所需的最低限度说明。
• 命名产品对象时，使用 Kitaru 中已有的名称。不要为步骤、摘要或集合杜撰标签，也不要把内部实现细节说成 Kitaru 概念。优先使用“以下是这次实验将要执行的内容”这样的通俗句子，而不是“回放运行卡片”。
• 先讲用户即将发现什么，而不是安装或评估术语。
• 只讲解当前操作所需的概念。等用户亲身体验到更深入的 Kitaru 对象为何重要后，再进行说明。
• 为审查者准备有用的观察和精确的证据锚点。告知他们这些是 Agent 预先准备的笔记，最终判断由人作出；只需告知一次。
• 使用 Kitaru 前端三次：用于调查审查、队列和评估器结果，以及已完成的实验运行。提供直接链接，解释用户看到的内容，然后暂停，等待他们返回。不要为了常规对象而中断导览去访问前端。
• 首次导览仅包含三个会话：一个影响重大的问题、一个细微的证据解读要点，以及一个可接受的反例。
• 在不重新生成轨迹或调用付费模型的前提下，取得有用的评估器结果。继续进行一次范围明确的回放，但在创建实验或启动付费或真实执行前，简要说明拟议的运行并征求同意。
• 在进行模型驱动的回放之前，确认工作器运行时具备所需的提供商凭据，但不要泄露机密信息。如果无法确认凭据是否可用，请让用户配置凭据并重启工作器，然后停止，不要创建实验或启动运行。
• 启动或重启由用户控制的工作器时，使用 --concurrency 10。只有当启动界面通过环境变量而非 CLI 选项提供工作器设置时，才使用 KITARU_WORKER_CONCURRENCY=10。
• 保留用户当前选中的健康 Kitaru 服务器，无论它是本地服务器还是云端服务器。不要仅仅因为快速入门示例介绍了本地快速入门就切换服务器。
• 优先恢复已持久化的 Agent、导入、会话、精确匹配标注、队列、评估器版本、实验和运行，而不是创建替代项。只有当本次对话中包含调查的准确 ID，或用户明确指出该调查就是他们的审查时，才恢复调查及其判定。
• 对明确预览过的教程写入操作，优先一次性征求综合授权。不要把导览变成一连串的权限提示。

加载导览参考资料

• 在首次面向用户进行说明前，阅读 references/tutorial-narration.md，并在设置、审查、评估器结果和实验结果各环节中遵循其中的教学节奏。
• 在开始设置前，或在判断该目录是否为快速入门示例时，阅读 references/starter-template.md。
• 在选择会话、撰写观察、创建审查或生成 AHA 前，阅读 references/tour-method.md。
• 在执行任何 Kitaru CLI 或 MCP 操作前，阅读 references/kitaru-operations.md。以已安装的架构为准。

确定教程路线

从只读操作开始。

1. 在候选 Kitaru 检出目录中查找该示例。如果都没有找到，则通过可信来源查看当前快速入门示例 README。若提示词中提到 PydanticAI returns agent 示例、其 URL 或 returns agent 导览，则视为用户有意采用此路线；不要仅因检出目录不存在就停止。检查本地前置条件，在当前工作区中选择一个新的 kitaru 目标目录，并预览克隆 Kitaru、进入 examples/python/pydantic_ai_ticket_resolver 以及同步其冻结环境的操作。先征求一次同意。获批后，克隆 Kitaru，根据可信来源验证示例目录，然后再安装并验证冻结环境。绝不覆盖已有目标目录。诊断 Kitaru 服务连通性前，必须完成此源码设置。只有当示例目录符合 starter-template.md 中的约定时，才使用此路线。
2. 根据 starter-template.md 和 kitaru-operations.md，确认示例环境、CLI、工作进程和 MCP 软件包均已就绪。安装整个冻结的示例环境，不要零散添加软件包。更改环境或主机 MCP 配置前，先说明并征求同意。如果 CLI 可以完成导览，则优先使用 MCP，但 MCP 并非必需。如果添加或更改了主机 MCP 配置，请告知用户重启或重新加载编码 Agent 宿主进程或 IDE，保留恢复检查点，并且不要声称当前任务可以发现新工具。
3. 检查 Kitaru 的连通性，并继续使用已选定且健康的服务。只有在未选定任何可用服务时，才提供示例的隔离本地服务选项；启动或选择该服务前，先征求同意。随后检查确切注册的 returns-resolver Agent 版本、相关导入任务，以及带有 returns-baseline 标签的全部已导入数据。
4. 恢复匹配的持久状态。仅执行经过验证的示例 README 中缺少的设置步骤；在更改环境、启动服务、注册或导入前，先作出清楚说明并征求同意。
5. 如果示例经过实质性定制、用户提供了自己的 Agent 或证据，或所需结论需要有依据的开放式调查，则停止并转至 kitaru-investigation。

在快速入门路线中，不要让首次使用的用户选择框架、追踪提供方、审查方法或抽样策略。

用三个简短环节帮助用户了解情况

选择导览前，说明：

1. 示例 Agent 使用查找、策略、发货、退款、换货和升级工具，处理合成的退货与配送请求。
2. Kitaru 保留了十次完整的历史运行，其中包括理解实际发生情况所需的模型和工具证据。
3. 编码 Agent 将在 Kitaru 中准备三条观察；用户将检查证据，并判断每个完整会话是可接受、有问题还是不确定。

然后继续。暂时不要解释队列或评估器版本。

准备一次引导式评审

按照 tour-method.md 检查每条候选跟踪记录，并整理出包含三个会话的引导流程。撰写前，简要预览每个会话中发生了什么、为何重要，以及将重点展示哪些证据。面向首次接触该 Agent 和 Kitaru 的读者撰写预览。避免制定详尽的调查计划。

只询问一次，确认是否：

• 将三个会话中的 Agent 观察结果作为普通 Kitaru 注释添加；
• 使用准备好的问题和重点内容创建一个固定调查；
• 打开生成的前端评审。

获得批准后，通过已验证的操作创建或恢复注释和调查。Agent 观察记录应简短，并以 Agent observation: 开头，确保脱离当前聊天时仍能理解。绝不要替用户写下结论。

转交给前端

先给出直接的评审操作。采用以下对话形式：

打开引导式评审： 在 Kitaru 中评审

我已准备好重点观察内容。你需要检查跟踪记录中的证据，并为每个会话选择 可接受、有问题 或 不确定。除非你想补充或更正内容，否则可以将书面回答留空。

完成最后一个会话后，选择 完成，然后回到这里，我会告诉你这些判断能带来什么。

暂停。如果前端路由正常运行，不要在聊天中重复评审内容。

创建并运行评估器

用户返回后：

1. 重新读取调查、按顺序排列的会话、手动注释、问题与回答的覆盖情况，以及结论的覆盖情况。
2. 开门见山地说明用户的决定。解释每个结论现在如何与促使开展评审的具体记录证据并列呈现。
3. 如果用户已评判所有建议的队列成员，其中至少包括一个有问题的目标和一个可接受的反例，则提出一个最能解释差异的可观察行为。将其转化为可复用检查前，简短确认一次。
4. 如果用户认可该行为，则根据已确认的目标会话和反例会话创建一个精确的队列版本。编写代码前，先检查已安装的评估器目录。
5. 选择已验证的全局评估器或同一 Agent 的评估器；或者创建一个范围限定为此次引导流程中已注册 Agent 的精简确定性评估器。测试它，注册一个不可变版本，验证其返回的 Agent 范围，并在准备好的、属于同一 Agent 的完整基线样本中运行它。
6. 先报告有用的结果：匹配了多少个会话、哪些已评审示例可以解释结果，以及一项重要局限。通过 kitaru-operations.md 解析队列和评估器链接。

然后展示 kitaru-operations.md 中定义的队列和评估器页面。说明队列会固定用户评判过的示例，而评估器页面会记录确切的可复用规则。暂停并等待用户返回后，再准备实验。

如果结论不支持存在问题，或用户否定了所提议的行为，不要强行将评估器纳入流程。展示有用的否定结果：准备调查的疑虑未通过人工评审。可以再提供一次范围明确的预备评审，或者在此处圆满结束。

如果评审尚未完成，则在行为确认、创建队列或开展评估器工作之前停止。报告已保存的结论所表明的内容，并保留相同的评审链接以供完成。

对象名称前先用日常语言说明。例如：

你认为两个会话有问题，因为 Agent 绕过了审批。Kitaru 已将这些判断与策略和退款事件一同保存。我把这种行为转化成了可复用检查，并在记录的 10 个会话中发现 2 个存在相同模式。

之后再说明，固定下来的示例构成一个队列，可复用检查则是一个评估器版本。

用一次实验收尾

用户从队列和评估器页面返回后：

1. 说明记录的会话展示了此前发生的情况；实验会基于相同的已存储顶层输入启动新任务，以测试一项条件变更。
2. 根据已接受的行为，提出一项小幅候选变更。不要启动自动提示词搜索，也不要引入无关的模型变更。
3. 使用 kitaru-replay-experiment 继续操作，传入确切的已接受行为、队列版本、评估器版本、父级 Agent 范围和参数、候选 Agent 版本、拟议覆盖项，以及明确的工具策略。对于经过验证的快速入门示例，六种工具均使用直通模式：每项任务都会针对一个全新的内存模拟存储调用确定性本地函数，且不会影响外部系统。不要悄悄将这些调用替换为基于记录历史的匹配。
4. 让该技能验证适配器支持情况，并简要说明拟议的运行。说明提供方和工作进程的就绪情况、模型工作、成本的不确定性、未恢复的状态以及可能产生的工具影响。在创建实验或开始运行之前，取得该技能要求的批准。
5. 运行结束后，先从 kitaru-operations.md 中的实验页面开始讲解。说明重放了哪些记录案例、发生了哪些变化、候选方案的表现如何，以及结果无法证明什么。暂停并等待用户返回，然后回答他们的问题，并在最终摘要中保留确切的实验和运行 ID。

正常的成功导览会在用户查看完此实验结果后结束。如果用户拒绝运行，或执行受阻，应保留拟议的条件以及队列和评估器链接，不要声称实验已完成。

之后，通过 kitaru-investigation 提供 使用我自己的 Agent，沿用导览中对方法的解释，但不包含任何基于合成数据得出的结论。

妥善处理失败情况

• 如果示例设置不完整，说明当前检查点以及唯一缺少的操作。不要罗列通用设置清单。
• 如果导入的会话或完整节点负载不可用，应在编造观察结果之前停止。
• 如果注释或调查写入操作可能已成功，但响应丢失，应先重新读取状态，再重试。
• 如果无法解析审查 URL，应保留已创建的调查，并报告交接失败的情况，同时提供确切 ID 和一项重试操作。
• 如果有用的会话不足三个，应采用内容较少但真实的导览，并说明缺少了什么教学环节。
• 如果用户只完成了部分审查就停止，应总结已持久化的评定及其目前已表明的内容。为剩余环节提供相同链接，但不要扣留部分成果，也不要把已准备好的观察结果说成缺失的人类判断。
• 如果用户不同意 Agent 的观察，应将其更正视为课程的一部分。不要为预先准备的备注辩护，也不要悄悄将其改成用户的结论。
• 如果适配器支持、模型凭据、工作进程或安全的工具策略阻碍了实验，应保留拟议的条件并说明缺少的条件。不要退而使用实时直通模式，也不要宣称导览已完成。