本页是创建、修改和审查 Scenario Training 场景的权威人工流程。字段格式由 scenario-training.v1 合同和模板编译器决定；不要从旧计划复制字段或逻辑。

​
一个完整场景包含什么

层必备内容
身份与介绍场景 ID、版本、领域、时长、学习者身份、四语言两行引子和六段沉浸介绍
真实世界entry state、位置/环境 state、Scene Action、动作前置条件和持久舞台描写
学习任务Slot、Objective、Evidence、accepted move、提示、示例和关联 Skill
语言流程state 允许的 move、Transition、进入 state 的主动 NPC Act、乱序修复路径
角色NPC 姓名、职责、人格、主动程度、禁区、声音和允许的 Stage Behavior
回复策略单一目标的 NPC Act、必要关键词、固定三变体或动态事实边界、静态兜底
等待与支持每个非终止 state 至少五条四语言 waiting cue、三档 guidance 和帮助动作
知识稳定剧情事实、3–5 条文化事实、官方 HTTPS 来源、核验与过期时间
教材一份从入口到正式通关的标准对话，含动作、日语、假名、翻译和表达说明

​
现实、背景与接续强制门

场景能编译只说明引用和状态图合法，不代表故事读起来顺，也不代表学习者知道下一步为什么会发生。创建或修改场景时，先做一份 信息放置表：每个事实何时产生、谁能看到、何时会被使用，以及应放在开场、NPC 台词、Stage Behavior/舞台描写还是 Scene Action 中。后续要求学习者给出的目的地、预约名等事实，必须在需要前已经可见、由 NPC 给出选项，或能从现场直接观察，不能让 学习者临场编造。 场景不得用作者虚构的酒店、商店、交通机构或服务规则冒充日本现实。先选定真实存在的机构、场所、品牌，或有官方公开流程的 服务体系，再建立真实原型来源表。每一条场所事实、服务规则、工作人员提问和当前承诺都要对应当期官方或一手来源，并标明适用 精度：全国法规、品牌全店、具体门店，或受时间、房态、库存、设备与现场人员判断影响的条件事实。品牌 FAQ 只能支持品牌级结论； 具体门店承诺必须有该门店依据。无法确认的门店差异应写成条件式现场询问，不能捏造成固定流程、一定提供的设施、凭证或承诺。NPC 使用“前台工作人员”“店员”等匿名岗位，不得虚构姓名后把角色描述成真实机构的真实员工。 同时建立角色动作归属表，逐项标注 learner、NPC 或 environment：可见提示、NPC 问句、Scene Action 按钮、Objective、 guidance、必答信息、NPC Act、Stage Behavior 和物理结果都必须入表。只有学习者本人要说或要做的行为，才能成为 Scene Action、 Objective、学习者 guidance 或必答项。工作人员执行的核对、复印、扫码、打印、递交等行为放进 NPC Act、NPC 台词或 Stage Behavior；设备自动变化和现场事件放进舞台描写或 Stage Behavior。逐句检查每个 NPC 问句：它必须确实是工作人员会向顾客提出、 而且顾客有资格回答的问题，不能把工作人员内部决定、设备操作指令或作者提示变成学习者任务。 开场背景的职责是让人顺畅进入故事，而不是预先解释整个状态机。它只写学习者在进入场景前已经知道、且理解第一步必需的事实： 此刻大致在哪里、扮演什么角色、眼前想做什么，以及促使自己开始行动的直接状况。继续复用六段 immersive_briefing，不另造结构， 但各段保持简短并避免重复：
  • setting 与 atmosphere 只建立开场地点和眼前氛围；
  • learner_role 只交代开始行动所需的身份、当下目标或动机；
  • immediate_situation 只交代开场瞬间发生的事和第一步面对的问题；
  • expected_flow 只给一条简短的现实方向，不罗列未来分支、设备操作或完整办理顺序；
  • cultural_context 只补充开场就必须理解的日本常识及其适用边界。
付款选项、设备画面、NPC 正在做的动作、临时限制和后续流程等未来信息，应在实际出现时由确定性的 Stage Behavior、持久舞台描写、 NPC 台词或 Scene Action 当场揭示。背景不得包含目标日语、假名、语法讲解、标准答案、内部 Slot/分支规则，或“请说/请问某句话” 一类语言指令。训练前只展示 Objective 名称；提示和例句只属于会话内 guided/assisted 帮助，不能拿它们填补剧情信息。 同一句话可以同时提供多个合法 Slot/Evidence；即使某项属于后面且不相邻的步骤，清楚表达后也必须一直保留到现实效果落实，只有 含糊或矛盾时才能再次确认。移动、拿取、递交、收取寄存凭证、主动选择拿小票、支付和离场等学习者动作必须由 Scene Action 发生； 终端自动打印小票属于环境事件，除非学习者确实选择拿取，否则不能变成必答或必做项。每一步到下一步必须至少满足一项： 刚发生的剧情或舞台事件已经把变化说清楚、界面给出了可见 Scene Action，或该反应在现实中极其自然而无需额外解释。NPC 一旦指出 某个地点或物品，就要立即开放自然的物理反应，除非现场存在可见的现实限制。不得把内部状态机顺序伪装成文化规则写进背景。 最后一轮对话之后也要完成现实中的离场、移动或交接，才能进入报告。 作者在开发中可以反复用 simulation 自查，但自查不能代替下面的独立发布门。任何需要猜目的地、重复已完成信息、凭空知道下一步 的节点都必须返工。 返工先判断信息应该出现的时间，而不是默认扩写开场：进入前就知道且理解第一步必需的事实才补进背景；人物动作、设备画面、现场 变化或临时限制应补成当场可见的 Stage Behavior/舞台事件或 NPC 承接；主动移动、拿取、交付和操作应补成 Scene Action。只有一种 合理反应经过这些处理仍无法承接时，才增加或放宽 state/Transition 分支。隐藏 guidance、语言提示和例句都不能算剧情修复。

​
按严重度执行的双角色发布门

Agent 审查只处理每个 scenario_id 的最新版。本次存在新候选时选择其中最高的 template_version； 没有新候选时使用 latest_published_version。每个情景只向审查 Agent 提供一个版本，旧模板、历史知识包、 Session、报告和音频不进入审查上下文、候选清单或 scoped SHA-256。这个边界只限制 Agent 辅助的语义与现实审查； 历史版本仍保留并继续参加自动兼容性、导入和存储测试。 自动测试全部通过后，先列出本次候选范围，将受影响 fixture/知识包、改变可见体验或反应路径的代码、Skill/Docs 及验收测试按路径 排序，对“路径 + 文件字节”计算并记录一个 scoped SHA-256。审查期间候选保持冻结；其中任一内容、代码、测试、Skill 或 Docs 发生 变化，之前的 PASS 全部作废，连续通过计数清零。 每一轮必须并发启动两名全新、只读且互不沟通的审查者。无需随机年龄、性别、职业或旅行人格；两人的职责固定而且不能互相替代：
  • 日本本地人先检查日文开场是否自然，再核对真实机构及一手来源的适用范围，并审查常识性错误、店员/工作人员的服务方式、 工作人员与顾客职责、日本现场与物理流程是否可信。报告应 指出具体 state、可见依据和现实偏差；语言学习难度或分支偏好不属于这个角色的裁决范围。
  • 中国游客先检查中文开场是否通顺、合理、容易进入角色，再沿所有可见路线逐状态检查流程，并逐项确认所有可见按钮、提示、 Objective 和必答信息确实属于学习者本人。每个下一步必须由剧情推进说明、 当场出现的舞台/NPC 事件、可见动作选项承接，或属于现实中极其自然的反应；若需要隐藏 guidance、标准教材或作者意图才知道该做 什么，则判定 FAIL。
两人不能看到对方报告、前轮意见、处理结论、标准教材、隐藏 guidance、Objective、Slot、预期答案或作者路线。每份独立报告记录 轮次、共同哈希、审查范围、所走路线、state、可见依据、困惑或现实错误、严重度和总体 PASS/FAIL。主代理必须等两份报告全部到齐 后再统一汇总，给每条意见写处理方式，随后集中修改一次并重跑测试；不能看完一份就边审边改。 一轮只有两人对同一哈希全部 PASS 才算通过，不按多数投票。默认情况下，第一轮通过后保持候选字节不变，第二轮更换两名全新 审查者；只有同一哈希连续两轮、四名审查者全部 PASS 才允许发布。唯一的降级规则是：某个完整失败轮次中所有已接受问题都只是 minor，且下一批修改只修这些问题及其直接必要的测试或文档时，新哈希只需一轮全新双角色复审全部 PASS。旧哈希的 PASS 不会 继承；若出现 major、blocker、无关功能或更广行为修改，立即恢复连续两轮要求。并发资源不足时暂停验收，作者不得自行扮演 缺失角色后宣称通过。完整执行格式见 .cursor/skills/scenario-authoring/references/audit-protocol.md。

​
十二步编写流程

​
1. 调查真实场合

先选定真实机构、具体场所、品牌或公开服务体系，确认地点、参与者、谁通常先说话、NPC 会主动向顾客问什么、用户必须实际做什么。 交通、酒店、品牌服务和运营信息只使用官方或一手来源；来源精度必须与结论一致。具体门店没有明确依据时，不得把品牌通则写成该店 保证，而应保留条件并让顾客现场询问。价格、时刻、库存和支付支持等易变信息不写成永久事实。 同时写信息放置表。区分进入前已知、现场可见、NPC 提供和玩家主动做出的事实；若后续状态要求一个具体答案，必须说明学习者会在 需要前从哪里得知，但不要把所有未来事实都塞进开场背景。 产出一段现实流程，例如：到达大厅 → 走向咨询台 → 工作人员先询问目的地 → 比较线路 → 指引购票和乘车方向。

​
2. 画位置与物理状态图

先画世界，再写台词。移动、拿取、递交、排队、抵达柜台和支付等动作必须是 Scene Action 或已建模的物理事件， 不能因为用户说了「会計お願いします」就让角色从货架区瞬移到收银台。 每个 Scene Action 声明：可用 state、所需 Slot/Objective、可选的精确 required_slot_values、玩家可见按钮和描写、目标 state、静态 Slot 更新， 以及是否触发一个 NPC Act。缺任一条件时，动作既不能显示也不能执行。 如果场景动作依赖路线、支付、加热或袋子的具体选择，它也必须用 required_slot_values 匹配精确值，不能只检查 Slot 存在。 零售结账还要核对可见的物理顺序：商品扫码和金额生成在付款前，收费袋子要扫码，付款后要真正装袋或交接商品。微波炉等定时流程运行时，现实中可以并行的结账不应被写成无原因的全程等待；物理结果在它真正完成的节点落实。

​
3. 定义训练合同

写清楚学习者在这个场景真正要练什么，而不是只写“完成购物”。每个目标应对应可观察的语言行为，例如询问位置、 回答服务问题、说明支付方式或确认取回流程。确定必修与可选目标，并为报告和画像配置 linked_skill_ids。

​
4. 把复合目标拆成 Evidence

需要多次行为才能完成的 Objective 必须拆成单调累积的布尔 Evidence。例如“询问便当和饮料的位置”需要两条独立证据； 只问可乐时保持 1/2 available，不能提前显示完成。可选目标被绕过时只能标记 skipped，不能伪装成 completed。

​
5. 定义 Slot、Move 和 Transition

  • Slot 的描述必须告诉 Interpreter 何时可以提取，非关键 Slot 非法时只丢弃该 Slot。
  • known_moves 是模板全局可识别意图，allowed_moves 是当前 state 能推进的意图。
  • 已知但顺序不对的 move 应进入当前 state 的修复 Act，不推进状态。
  • 每条 Transition 明确 from state、move、required slot、to state、完成/跳过的 Objective 和可选 NPC Act。
  • 只要路线、支付、预约、加热、袋子或餐具等具体选择会改变 Transition 或 Scene Action 分支，就用 required_slot_values 校验精确值；只检查 Slot 是否存在，会让相反选项误入该分支。键必须同时出现在 required_slots 中，值必须符合该 Slot 的类型或枚举。

​
6. 设计 NPC 人格与主动性

Persona 至少包含礼貌等级、主动程度、句长、服务习惯、禁止行为和真实示例。NPC 必须保持场景角色身份，一次只完成一个 服务行为、一次只问一个问题；语言难度可以降低句长和词汇，但不能把日语改得不自然，也不能突然变成老师。 Stage Behavior 只描述角色能做的可见动作，如点头、核对商品或指向柜台，并提供四语言静态兜底。动作不能暗示尚未发生的结果。

​
7. 为每个 NPC Act 选择交付方式

条件使用方式例子
台词由流程确定、无需读取变化事实fixed_variants欢迎、加热、袋子、餐具、支付、告别
必须结合用户槽位或知识包事实回答llm商品位置、路线比较、具体寄存说明
固定 Act 提供恰好三种人工审核表达：简短易懂、标准服务表达、更礼貌/完整表达；覆盖 guided、assisted、simulation， 变体继承 NPC 声音，不携带音频路径或文件哈希。动态 Act 声明明确目标、事实边界、允许的 Stage Behavior、必要关键词和失败兜底； Renderer 只能表达这些输入，不能选择 state 或 Objective。

​
8. 编写 state guidance 与 waiting cue

每个非终止 state 都要有当前任务、提示和示例。guided 直接显示完整内容，assisted 显示简短任务并允许展开，simulation 默认隐藏。 完成一个节点后立即切换 guidance，不能继续提示已经完成的动作。 每个非终止 state 至少匹配五条四语言 waiting cue。它们只能描述角色正在查看、确认或准备回应，不得包含 NPC 台词、问句、 教学点评或“已经支付/找到了”等未确认结果。

​
9. 编写沉浸介绍、知识与本地化

  • 两行情景引子负责地点、声音、人物和眼前状况；六段 immersive_briefing 共同组成一个简短、不重复的开场，只交代进入前已知且 理解第一步必需的事实。未来的设备画面、人物动作、选项和限制在发生时由舞台事件、NPC 或 Scene Action 呈现。
  • 每个场景绑定 3–5 条文化事实；事实与剧情知识分开，不能参与状态推进或被 Renderer 当作实时运营承诺。
  • 用户可见内容提供 zh-CN、zh-TW、en、ja 四种语言。
  • UI 不直接显示 passed、natural、needs_work、Skill ID 等内部值；数字必须带名称与量纲，例如“适配分：55/100”。

​
10. 审核语音与保留策略

仓库不得提交 WAV、MP3 或其他音频二进制，也不得在 fixture 中保存音频路径和哈希。固定话术在首次实际使用时通过 Azure 生成 24 kHz、48 kbps、单声道 MP3，并按场景、模板版本和变体存入 Data Server，后续 Session 共享复用。 动态 NPC 音频属于会话私有资产：active/paused 期间保留，结算后滚动保留 24 小时，过期只删除音频字节，永久保留文字、点评和报告。 手工重新生成会从生成时重新计算 24 小时。逐条试听角色、语速、停顿和多音词；当前 TTS 尚无统一读音规划器，发现错误读音时 不能仅凭模型猜测后发布，应修正或暂缓语音。真实 Azure 调用可能产生费用，仍需用户明确授权。

​
11. 编写标准对话教材

每个模板版本只有一份 reference_lesson。Scene Action step 引用真实 action；Learner Turn 声明日语、假名、四语言翻译/说明、 recognized move、合法 Slot、期望 state 和 NPC Act。固定回复引用真实 variant；动态回复只引用当前 state/move 可用的知识事实。 教材不是“看起来合理”的示例。模板编译器会用生产 Director 逐步执行，最终必须进入合法 final state 并完成全部 required Objective。

​
12. 编译、现实审查和验收

对每个 state 回答五个问题：
  1. 进入前实际发生了什么？
  2. 学习者此刻能看到和知道什么？
  3. 下一步是否需要尚未发生的物理动作？
  4. 现实中此刻谁先说话，NPC 为什么会这样回应？
  5. 这一步只完成了有证据的目标吗？
随后覆盖正常路径、缺前置条件、跳步、乱序 move、无法识别、模型/TTS 故障和幂等重试。使用真实模型验收时，还要检查 NPC 主动性、 一次一问、事实边界和 Coach 是否只评价学习者。 作者先执行 simulation 无提示盲走，逐状态确认下一步由剧情事件、可见动作或极其自然的反应推出，并确认最后一段 NPC 对话会显示 一个现实的接续动作，而不是直接跳转到报告。自动检查稳定后再冻结候选，默认执行双轮双角色发布门；只有上一完整失败轮次全部是 minor 且修订范围仅限这些问题时，修复后的新哈希才可改为一轮全新双角色复审。

​
版本与数据规则

  • 新场景从 template_version: 1 开始；发布前可以迭代 draft。
  • 已导入的 published 模板和知识包不可原地修改；内容变化创建新版本，旧 Session 和报告继续绑定旧版本。
  • 开发阶段确需覆盖 fixture 时，必须先说明会删除哪些 Scenario 表数据并获得明确授权；不得触碰文章、生词本或用户画像。
  • Skill 和启动脚本都不能自动清空数据库、生成付费音频或运行真实外部模型。

​
验证命令

至少运行模板编译和 Data Server 导入校验： 
cd rakull_server/immersive_study_server
uv run pytest -q tests/unit_test/test_scenario_contracts.py

cd ../data_server
uv run pytest -q tests/unit_test/test_storage_scenario.py
改动 Director、Agent 编排、Data 事务或 Flutter 交互时，再运行对应服务全量测试、Ruff、Flutter analyze/test 和 git diff --check。 现有已发布模板分别展示便利店购物、机场交通、酒店寄存、车站问路与失物申报、便利店宅急便寄件、餐厅用餐、完整酒店入住、 Suica 余额不足出站处理、温泉旅馆入住和明治神宫参拜与御朱印的完整做法； 选择与新场景物理流程最接近的一个作为参考，不要机械复制另一场景的状态图。