Phase 1 翻译层与剧本播放
Phase 1 把「外部的输入源」变成「框架自己看得懂的通用内容」，并让这份内容真正跑起来：从归档识别、隔离翻译，到剧本 IR、剧本 VM、对话框渲染、分支与槽位存档。完成之后，框架第一次具备读完一个完整章节的能力。
状态：已完成。
目标与非目标
目标
- 定义稳定的剧本 IR v1，并用 JSON Schema 固化其形状。
- 让翻译器只在隔离环境中运行，输入、输出与墙钟均受预算约束。
- 把翻译产物写成数据包与资源包，交给正常装载管线处理，而不是绕过 guard。
- 提供剧本 VM、条件求值、旗标、章节推进与槽位存档的最小闭环。
- 让对话框、选项与文本渲染通过实现位替换，验证「插件换实现」的扩展模型。
非目标
- 不实现立绘、背景、转场、镜头、音频与完整排版；这些属于 Phase 2。
- 不实现战斗、地图、养成、图鉴与第三方玩法模块。
- 不实现云存档、孤儿 GC 完整版与多端同步。
- 不实现完整剧情编辑器界面；本阶段只提供文档模型。
覆盖的大插件
| 大插件 | 本阶段职责 |
|---|---|
| Translate | 格式识别、归档解析、隔离编解码、翻译规则、产物生成 |
| ScriptPlay | 剧本 VM、指令集、分支与旗标、对话框与选项渲染、章节推进 |
| Asset | 最小资源取得：bytes、text、json，内置包与 pack: fetcher |
| Save | 槽位存档、旗标持久化与旗标归属登记 |
| Text | 最小文本渲染与样式 |
| Author | 剧情编辑器文档模型 editor:doc |
交付内容清单
| 交付 | 大插件 | 关键接口或产物 | 状态 |
|---|---|---|---|
| 剧本 IR v1 契约 | — | 契约文档与 schema/ir-1.schema.json | 已完成 |
| 格式识别与归档解析 | Translate | translate:detect、translate:archive | 已完成 |
| 隔离编解码器 | Translate | translate:codec@1、沙箱 iframe 与专用 Worker | 已完成 |
| 翻译规则与翻译执行 | Translate | translate:resolve-rule、translate:run | 已完成 |
| 翻译产物生成 | Translate | translate:emitter@1、数据包与资源包落盘 | 已完成 |
| Asset 最小版 | Asset | asset:acquire、bytes／text／json、builtin 包 | 已完成 |
| 剧本 VM 与指令集 | ScriptPlay | script:vm、script:command-set@1 | 已完成 |
| 分支、条件与旗标 | ScriptPlay、Save | script:resolve-condition、state:flags | 已完成 |
| 对话框与选项 UI | ScriptPlay | dialog:renderer@1、choice:renderer@1 | 已完成 |
| 最小文本渲染 | Text | text:view | 已完成 |
| 槽位存档与归属登记 | Save | save:slots、save:backend@1、save:orphans | 已完成 |
| 剧情编辑器文档模型 | Author | editor:doc | 已完成 |
出口条件
- [x] 能通关一条含至少一个分支的示例剧本。
- [x] 能在分支点存档，并在读档后回到该分支点。
- [x] 翻译产物以数据包与资源包落盘，而不是以私有格式直接注入运行时。
- [x] 翻译器在隔离环境中运行；超过墙钟、输入或输出预算时正确中止。
- [x] 替换
dialog:renderer@1后外观改变，且该替换被判定为插件而非 Mod。 - [x] 翻译产物装载时照常经过 guard，不自动装载未裁决的产物。
- [x] 旗标命名空间在清单中声明，Save 记录归属；卸载单元不会删除进度。
当前状态与证据
| 证据类型 | 位置或内容 | 结论 |
|---|---|---|
| IR 与 Schema | test/contract/ir.test.ts、schema/ir-1.schema.json | 通过 |
| 隔离翻译 | test/contract/isolated-codec.test.ts、codec-output.test.ts、isolation.test.ts、translate.test.ts | 通过 |
| Asset 最小版 | test/contract/asset.test.ts、asset-redirect.test.ts | 通过 |
| 剧本播放 | test/contract/scriptplay.test.ts、scriptplay-stop.test.ts、playback-renderers.test.ts | 通过 |
| 存档与旗标 | test/contract/save.test.ts、save-indexeddb.test.ts、flag-namespaces.test.ts、slot-integrity.test.ts | 通过 |
| 编辑器文档模型 | test/contract/author.test.ts | 通过 |
| 测试记录 | 见当前状态与测试 | 两端契约测试通过 |
本阶段完成后，platform:resolve-asset-url 随 Asset 管线一并落地，用于包内逻辑地址的重定向与缓存失效。
尚未完成与风险
| 项目 | 说明 |
|---|---|
| 完整编辑器 | editor:doc 只是文档模型，没有可视化编辑界面；完整编辑器属于 Phase 6。 |
| 表现层能力 | 立绘、背景、特效、音频与复杂排版不在本阶段，相关指令在 Phase 2 才形成完整表现。 |
| 翻译器覆盖面 | 隔离框架与预算已就位；新增输入源需要新的编解码器与翻译规则，按同一契约接入。 |
| 预算调参 | 墙钟与输入／输出预算有默认值，也允许在限定范围内调整；过大的预算会延长失败反馈时间。 |
| 产物未被签名 | 数据包与资源包不要求签名；代码单元仍然按 release／debug 规则核验。 |