writing-livekit-scenarios

编写模拟场景

场景由模拟用户的**instructions**（用户身份和需求）以及 agent_expectations（成功的判定标准）组成。模拟会让真实 Agent 运行这个场景，再由大模型评判器为对话记录打分。

每次运行的结果都可以丢弃。场景文件才会一直保留：它会在差异中接受审查，未来多年都可能重新运行，还能捕捉到那些悄悄破坏功能的提示词编辑。

编写文件前，请使用 reading-livekit-docs 查阅准确的架构和 CLI 标志。字段名和命令会变更，因此此技能不重复列出。概括来说，一个文件是一组命名场景。每个场景包含模拟用户的指令、通过标准，以及可选的分组标签和 Agent 可在运行时读取的场景数据。如果 CLI 提议为文件中的场景添加稳定 ID，请接受并提交。

从生成的基线开始

不要从空文件开始。LiveKit 的生成器会读取 Agent 的源代码，并生成质量不错的初稿，速度比手动编写十个场景快得多：

lk agent simulate text -n 10    # confirm the exact flags with --help

从源代码生成会将代码上传到 LiveKit Cloud，以便生成器读取代码，因此 CLI 会先请求确认。运行前请告知用户，并允许他们拒绝。有些代码不能离开本机；遇到这种情况，就手动编写场景。对于非交互式运行，可使用标志跳过提示。

运行结束后，CLI 会告知生成的场景保存位置，或者询问是否将它们保存到项目中。无论哪种情况，都要将该文件放入代码库，作为起点。

你无法引导生成器。它会从代码中推断意图，因此生成的是看似合理的对话，而不是该 Agent 用户实际会进行的对话；它也不知道用户担心什么。请将生成结果视为草稿：

1. 阅读每个场景，删除无关内容。没读过的文件算不上测试套件。
2. 明确含糊的预期。 如果评判器无法判定 agent_expectations，每次运行的评判结果就会不一致。这是场景不稳定的最主要原因。
3. 补上生成器遗漏的内容。 生成结果往往偏向顺利的路径。references/risk-coverage.md 说明了如何将 Agent 的约束转化为检查清单，并为每一项编写一个场景。
4. 补上用户担心的内容。 如果用户尚未说明，请询问他们想重点测试什么。这就是由人引导的测试套件优于自动生成套件的原因。

询问要测试什么

用户知道哪些流程总是出问题、哪位客户提出过抱怨，以及他们对哪些更改感到担忧。请主动询问，并通过增加场景数量和深度，让测试套件侧重于相关领域。

聚焦能够增加覆盖率，但绝不能减少对 Agent 硬性限制的覆盖。如果用户没有偏好，就广泛生成，并告知用户你已这样做。

根据 Agent 的能力编写场景

开始编写前，先使用常规工具在本地阅读 Agent 的代码。了解用户可以提出什么请求（能力）、哪些请求会被拦截（约束：必需步骤、不可用项目名称、上限、资格条件），以及 Agent 必须拒绝哪些请求。

约束最重要。如果场景要求 Agent 做它做不到的事，只有在预期结果是 Agent 明确说明做不到 时，场景才有效。否则，Agent 正确行事时，测试反而会失败。

测试范围包括可从会话入口访问的 Agent，以及它移交任务的 Agent 和等待其完成的任务。请忽略目录中的其他类、未使用的导入和示例文件。

编写模拟用户可遵循的指令

有两种形式，具体使用哪一种取决于场景的用途。详情和示例见 references/scenario-craft.md。

• 要点式指引适用于按最终状态评分的确定性流程。结构化模板（角色设定、开场白、仅在被询问时透露的事实、按顺序排列的步骤、条件式回应）能让角色模型保持一致，并使运行结果可重复。
• 角色设定段落加目标适用于只根据对话评分的开放式和对抗式场景，你希望模拟用户能够即兴应对。

无论采用哪种形式，目标都应是向 Agent 提出的请求，而不是 Agent 自己要执行的操作。使用 Agent 所属领域中的真实值，并假设没有任何先前状态。在整个测试套件中改变角色、情绪和难度，不要让十个场景都像是同一个配合度很高的来电者。

将场景拆分为多个集合，每个集合一个文件

运行命令接受一个场景文件，因此一个文件就是一次运行。按你想要分别运行的方式拆分，通常不是按主题拆分。

最重要的划分依据是评分方式：

• 驱动具体工具流程并达到确定性最终状态的场景，同时根据最终状态和对话评分（见下文“让 Agent 使用场景”）。
• 只根据 agent_expectations 评分的开放式和对抗式场景。

这些场景需要不同形式的指令、不同的 Agent 接线方式，而且通常采用不同的运行节奏，因此应放在不同的文件中。第二个划分依据是运行节奏：合并前运行的小型集合，以及发布前运行的完整集合。

为每个文件设置一个描述该集合的 name，它会作为运行标签。在文件内，使用 tags 进行筛选。添加 feature 标签，以便失败时能定位到负责该功能的 Agent 部分；也可以添加其他筛选标签（渠道、难度）。在文件开头添加注释，记录该集合的假设：固定日期、必需的环境变量，以及其预期结果依赖的内容。

确保场景可重复

无论是现在还是几个月后，场景都应产生相同的结果。

• 使用绝对日期，并固定 Agent 的时钟（通常通过环境变量），确保可用性和预期结果始终一致。相对日期会逐渐失效。
• **不要让场景访问真实后端。**改为从场景中植入确定性状态（见下文“让 Agent 使用场景”）。
• **在 CLI 支持的情况下，保持 id 稳定。**标签和指令会改变，而 id 用于关联场景历次运行。彻底重写的场景属于新场景，应分配新的 id。

让 Agent 使用场景

场景文件本身无法解决两个问题。访问真实后端的场景每次运行的评分都会不同，而只读取对话记录的评审器可能会让预订了错误会议室的运行通过。这两个问题都应在 Agent 代码中解决：在入口点顶部的一个分支中完成以下操作：

1. 检测作业上下文中的模拟。在生产环境中，该检查会返回空值，其他行为不会改变。
2. 植入场景中每个场景的数据（例如虚拟日历、内存数据库）作为状态，Agent 的真实工具会像往常一样读取这些数据。
3. 在整个会话期间模拟工具，这样工具选择仍在测试范围内，而执行结果则具有确定性。
4. 在模拟结束回调中评估最终状态。比较 Agent 最终产生的状态与场景预期状态，不同则判定运行失败。你的检查可以让评审器通过的运行失败，但无法挽救被评审器判定失败的运行。

这只适用于工具流程场景。开放式和对抗式场景只根据对话评分。references/connecting-the-agent.md 详细介绍了全部内容，包括如何确认接线已生效。通过 reading-livekit-docs 查询当前 API 名称。

从真实故障中扩充测试套件

最有价值的场景描述了出错的情况。Agent 上线后，应从录制的会话中提取场景，而不是凭空编造更多场景。如果 CLI 支持，可使用子命令从录制的会话中生成场景（查看 lk agent simulate --help）。生成的场景描述的是一次调用，因此要将其扩展到所代表的一类调用，并将预期细化为你希望强制执行的规则。

每个修复的生产环境 Bug 都应在文件中添加一个永久场景。

不要编写糟糕的测试

评估器会根据 agent_expectations 为 Agent 打分，因此不严谨的预期会惩罚正确行为：

• 对于防护措施和负面案例，Agent 拒绝、升级处理或不编造数据才算通过。预期应如此编写。
• 切勿编写只有 Agent 做出不当行为才能满足的预期，例如陈述其无法获知的数据，或给出具体的医疗、法律或财务指示。如果通过意味着必须做出不当行为，那么这个场景就是错误的。
• 从用户的角度根据结果进行评判。不要规定措辞。

参考资料

• references/risk-coverage.md — 将约束转化为检查清单并确保覆盖全面
• references/scenario-craft.md — 指令形式、角色多样性、音频专属场景
• references/connecting-the-agent.md — Agent 端代码：检测、播种、模拟、评估最终状态

相关技能

• 运行模拟：running-livekit-simulations
• Schema 和 CLI 说明：reading-livekit-docs