当前标准：scenario-training.v1
情景训练是与深度阅读、生词本平级的独立模块。代码维护世界状态和学习证据，LLM 负责理解、表达与点评，
两者不能互相越权。
规范层级
| 优先级 | 来源 | 负责内容 |
|---|---|---|
| 1 | 本页与场景编写标准 | 产品逻辑、内容标准和编写流程 |
| 2 | scenario-training.v1 合同、Pydantic 模型和模板编译器 | 字段、引用、枚举和机器可执行约束 |
| 3 | RakullDataAssets 仓 catalog/scenarios/（物化到 .data-assets/catalog/scenarios/）中的已发布场景样板 | 完整、可运行的参考实现 |
| 4 | 自动测试 | Director 路径、权限、幂等、音频资产和 UI 行为的回归保证 |
.cursor/plans/ 只记录决策过程，不是规范来源。历史方案与当前实现冲突时，以当前合同、编译器和测试为准。
决策演进
| 阶段问题 | 现行结论 |
|---|---|
| 自由聊天和文章解析边界不清 | Scenario Training 独立拥有模板、状态机、会话、目标和报告，不复用 Reader pipeline |
| LLM 台词与状态脱节 | 使用 Interpreter → Deterministic Director → Renderer；LLM 永远没有状态迁移权 |
| 一个大目标被一句话误判完成 | Objective 可以拆成 Evidence；证据不足保持进行中，跳过只能显式标记为 skipped |
| 等待 API 时画面静止、点评倒序 | 用户消息乐观显示，按状态轮换 waiting cue；Coach 点评按 Turn sequence 正序追加 |
| 台词让角色“瞬移”到下一地点 | 移动、拿取、递交和支付由 Scene Action 触发，必须满足 state、Slot 和 Objective 前置条件 |
| 所有 NPC 回复都临时生成，既慢又不稳定 | 确定性服务行为使用三种预审固定表达；音频在首次使用时懒生成，并按不可变模板版本共享；只有上下文回答使用 Renderer |
| 场景只是一次性聊天 | 尝试、文字记录和报告保留到账号删除；动态音频字节在结算后滚动保留 24 小时；结算产生最小化 production_evaluated 画像事件 |
| 缺少现实背景、统一教材和可复用入口 | 每个场景有简短开场、事件驱动的信息揭示、官方来源文化事实、按严重度执行的双角色审查和一份通过 Director 的通关标准教材 |
| 多地点场景被塞进一个大状态机 | 使用 journey-map.v2 在 Scenario 外按日章编排选择、事件和跨地点顺序，Agent 不决定跨场景跳转 |
运行架构
正常语言轮次先完成 Interpreter，再由 Director 决定状态、Objective、Slot 与npc_act。如果 Act 是动态的，
Renderer 与 Coach 并行；如果 Act 是固定的，直接选择审核过的变体，同时只运行 Coach。固定变体没有就绪音频时，首次实际使用才
调用一次 Azure TTS，成功后按不可变模板版本和变体共享。最终结果作为一个事务提交，相同 turn_id 重试不能再次调用模型。
Scene Action 不经过 Interpreter 或 Coach。它只改变代码已经声明的物理世界；若触发固定 NPC Act，则不调用 LLM，已有共享音频时
也不调用 TTS，只有该固定变体首次缺少音频时才懒生成。只有显式声明为上下文行为时才使用 Renderer 和动态 TTS。
端到端运行路线
三档训练共用这条路线。simulation 可以隐藏教师 guidance，但不能隐藏剧情成立所需的信息。进入场景前已经知道、且理解第一步
必需的事实放在简短开场中；设备画面、人物动作、选项、限制和后续流程在实际发生时通过 NPC、持久舞台事件、Stage Behavior 或
Scene Action 揭示。每一步到下一步必须有剧情推进说明、可见动作选项，或属于现实中极其自然的反应。若学习者必须看到隐藏提示才
知道接下来为什么这样做，缺陷属于模板，而不是学习者。
创建与修改场景的发布门
任何新建或修改的场景都必须先让开场背景读起来简短、连贯、容易进入角色。它只写进入前已经知道、且理解第一步必需的事实，不 罗列未来分支、设备操作、临时限制或完整流程。之后才出现的信息必须在发生时由 NPC、Stage Behavior、持久舞台描写或 Scene Action 当场呈现。背景不能包含日语答案、语法讲解、内部规则或“请说某句话”；训练前只显示 Objective 名称，语言 hint/example 留在 guided/assisted 会话内。 发现缺口时先判断信息出现的正确时机：开场必需事实才补背景；人物动作、设备画面与现场变化补成事件或 NPC 承接；主动的物理步骤 补成 Scene Action；只有合理反应仍无法连贯处理时，才增加或放宽分支。隐藏 guidance、语言提示和例句不算故事修复。 场景必须锚定真实机构、场所、品牌或有官方流程的公共服务，规则精度不得超过一手来源：品牌说明不能自动变成某门店保证，现场 差异要保留条件并由学习者询问。另须把所有事件标成learner、NPC 或 environment；只有学习者本人要做或要说的内容可以成为
按钮、Objective、guidance 或必答。工作人员动作属于 NPC Act/Stage Behavior，设备与环境变化属于舞台事件。每个 NPC 问句也要
确认确实是向顾客询问，而非把工作人员内部步骤错发给学习者。
自动测试通过后冻结候选并记录 scoped SHA-256。每轮并发使用两名全新、独立、只读且互不沟通的审查者：日本本地人先看日文开场，
核对一手来源适用范围、常识、服务方式、日本现实及员工/顾客职责；中国游客先看中文开场是否通顺、合理、容易代入，再逐状态检查
每一步是否由剧情事件、动作选项或极其自然的反应承接，并确认每个可见按钮、提示、Objective 和必答确实属于学习者本人。作用域内
任何修改都会使旧哈希的 PASS 作废。默认只有同一哈希连续两轮、每轮两人全部 PASS 才可发布；
若某个完整失败轮次的所有已接受问题都只是 minor，且随后只修这些问题及直接必要的测试/文档，则新哈希只需一轮全新双角色
复审全部 PASS。任何 major、blocker 或更广改动都会恢复连续两轮要求。第二轮或 minor 修复轮都必须使用全新审查者，作者不能
自我代演缺失角色。作用域外无关文件不影响哈希。完整流程见
场景编写标准。
四类事件不要混用
| 类型 | 是否持久化 | 用途 |
|---|---|---|
dialogue | 是 | 学习者与 NPC 的真实台词；学习者 Turn 可以带 Coach 点评 |
scene_action | 是 | 进入、靠近、拿取、递交等物理动作及舞台描写 |
support | 是 | 慢速重说、提示、示例、暂停等用户主动请求的帮助 |
| waiting cue | 否 | API 等待期间的临时演出；不能预告结果，也不进入历史、Coach 或报告 |
代码与模型职责
| 能力 | 代码负责 | LLM 负责 |
|---|---|---|
| 理解用户 | 校验合法 move/slot、过滤非法输出 | 识别意图、槽位和表达信号 |
| 推进剧情 | state、Objective、Evidence、Scene Action、CAS、幂等 | 无 |
| NPC 回复 | 选择 Act、固定变体、事实范围、失败兜底 | 只表达已指定的动态 Act 和 Stage Behavior |
| 教师点评 | 绑定原 Turn、排序、降级 | 判断自然度并给出语法、用词、礼貌和语境建议 |
| 帮助动作 | 有模板内容时直接返回 | 仅在确需个性化解释时使用 |
| 报告 | 通关结果、计数、Objective 和画像事件 | 总结代码提供且带 Turn ID 的证据 |
会话、难度与永久记录
- 同一用户、同一场景最多有一个
active或pausedSession。 - guided、assisted、simulation 共用一套状态机，只改变提示可见性、NPC 句长和修复策略。
- 推荐档位来自自报等级、相关 Skill 的生产能力、最近报告和挑战偏好；用户仍可覆盖。
- 中途结束生成
ended_early报告但不解锁答案；正式passed才永久解锁绑定模板版本的标准教材。 - 模板、知识包、Session、Turn 和报告均按版本或账号生命周期保存；固定音频首次使用时懒生成并随模板版本共享。动态音频从结算时 起滚动保留 24 小时，到期只清除字节；手工重新生成会从生成时重算窗口。发布版本不能原地改写。
当前样板与边界
仓库提供一组已发布的完整样板，包括 7-Eleven 购物、成田与羽田机场交通咨询、酒店提前到店寄存、东京站失物申报、 FamilyMart 黑猫宅急便寄件、Gusto 候位点餐结账、横滨站 Suica 余额不足出站处理、塔之泽一之汤本馆入住， 明治神宫参拜与御朱印、新宿出口问路，以及東横INN完整入住。它们都包含四语言沉浸介绍、 3–5 条官方来源文化事实、三档训练、每个非终止状态至少五条 waiting cue、固定/动态 NPC Act、数据库音频资产和可执行教材。 当前不包含语音输入、口音评分、Realtime 全双工对话、立绘或背景图、多人会话和管理员跨用户读取原始对话。 标准教材暂不提供音频。Azure TTS 目前仍直接朗读显示文本，统一的日语多音词/专名读音规划尚未实现；固定音频在提交前 必须人工试听，动态音频不能被当作发音评测依据。仓库不保存音频二进制。 下一步创建或审查场景时，使用场景编写标准，字段细节查阅vibe-coding-workspace/requirements/functions/scenario_training/contracts-v1.md。
跨场景故事线的日章、接口、探索和揭示规则见Journey Map v2。