首次运行
本页按第一次打开应用的顺序，说明界面上有什么、每一步背后发生了什么，以及哪些结果需要你本人裁决。所有界面元素都以当前内置外壳与信任页的代码为依据；没有实现的入口会明确标为置灰或「暂未提供」。
启动前
先按安装、运行与构建启动开发服务器：
cd weftale
npm run dev然后在浏览器打开 http://localhost:5173/。http://localhost:5174/ 是信任页源，不需要单独打开；它由外壳以 iframe 嵌入，需要裁决或管理时才显示。
启动过程
启动不是「加载一个页面」这么简单。外壳会先校验产物，再装载根插件，最后装载内置包：
| 阶段 | 界面标题 | 实际动作 |
|---|---|---|
| 校验产物 | 正在校验产物 | 读取 rpm.json，核对构建渠道、清单哈希与 Kernel 入口哈希 |
| 装载根插件 | 正在装载根插件 | 与宿主握手，读取官方签名清单，逐个装载 RPM 中的根插件 |
| 就绪 | 框架就绪 | 内置数据包与皮肤资源包装载完成，进入主页并应用已保存的界面设置 |
| 拒绝 | 已拒绝启动 | 任一校验失败；界面显示原因码，并明确不加载任何根插件 |
启动失败时，主区域会显示类似「已拒绝启动」的标题与原因码，并提示「为保护你的设备，未加载任何根插件。」右侧与底部的装载列表不会留下半启动的根代码。原因码的含义见装载原因码。
拒绝启动不是「再点一次就好」
拒绝启动通常意味着产物、渠道或清单不一致。先确认前端与宿主渠道匹配、dist/ 不是旧产物，再重启；反复刷新不会绕过校验。
外壳一眼
进入「框架就绪」后，界面分为顶栏、左侧信息栏、主区域与底栏。首次启动会自动套用「核心内置默认皮肤」；后续启动遵循你保存的选择。
顶栏
| 胶囊按钮 | 当前行为 |
|---|---|
| 日志 | 打开「运行日志（最近 300 条）」，显示装载结果、拒绝原因与观测记录 |
| 离线导入 | 打开「离线导入扩展单元」，选择目录或 ZIP |
| 离线翻译 | 打开「离线翻译作业看板」 |
| 信任管理 | 请信任页打开撤销入口，列出你记录过的发布者密钥 |
| 线路（暂未提供） | 置灰；下载线路属于后续阶段 |
Aa 100% | 在 90%、100%、110%、125% 之间切换显示比例 |
| 浅色／深色 | 切换主题；信任页会跟随同一枚举值切换 |
日志里的「观测记录」只是留痕，不代表已经阻止了某次调用。不要把观测条数当作拒绝条数。
竖屏时顶栏按钮折行排列。进入独立设置后顶栏与底栏保留；小屏剧情播放时两者隐藏，为播放区留出空间。
左侧信息栏
左栏列出运行环境、构建渠道、构建标识、已装载扩展单元数量、官方签名清单状态与信任存储位置。窄屏时这部分折叠为「运行环境：… · 已装载 … 项」的胶囊，点击展开。
主区域
主页主区域包含：
- 阶段卡：显示当前启动或装载状态；
- 章节目录：只列当前实际登记的章节，显示数据包来源；可播放章节标「已开放」，点「进入本章」开始；不可播放的章节标「尚未开放」，不从条件猜测解锁说明；
- 快捷入口：「存读档」打开 20 个手动存档槽，「设置」进入独立设置界面；
- 任务与已装载单元列表：显示装载状态、拒绝原因或单元名称、ID、版本、档位与「卸载」。
没有章节时，主页明确提示没有登记的剧本章节，并提供离线导入与信任状态入口。不会预置编队、战斗等尚未交付的玩法入口。
底栏固定显示「信任存储：独立源隔离 · 安全确认只在独立信任页内完成」与当前构建渠道／标识。
章节目录属于可选择实现的主页；运行信息、阶段卡、任务与单元列表属于外壳控制面。切换主页实现不会移走这些控制入口。独立设置会暂时隐藏左侧信息栏、阶段卡、任务与停靠栏，返回主页后恢复。
内置示例「一封晚到的信」
内置示例是随产物一起装载的原创数据包，不依赖任何外部内容：
| 项 | 内容 |
|---|---|
| 包 ID | framework.sample |
| 名称 | 一封晚到的信 |
| 版本 | 1.0.0 |
| 档位 | 数据包（datapack） |
| 旗标命名空间 | sample |
| 章节 | 「一封晚到的信 · 路口」「一封晚到的信 · 钟声」 |
可以体验什么
- 在「一封晚到的信 · 路口」章节卡中点击「进入本章」开始播放；
- 阅读两段旁白与信使的台词，随后出现三选一的分支；
- 选择「沿河边走，听听水声」或「穿过小巷，看看街灯」，分别写入
sample:route旗标； - 「打开锁着的捷径」需要
sample:key旗标；未满足时显示「需要钟楼钥匙」并禁用； - 完成「路口」后，「钟声」作为后续章节可用；走到结尾会显示「本段剧本已结束」。
这个示例覆盖剧本 IR 的台词、选项、旗标、条件边与章节接续，不包含剧情图像、音频与字体资源。随应用装载的 framework.skins 提供界面皮肤贴图，不能代替舞台、音频或剧情资源替换测试。示例的包清单与文件表可在 builtin/framework.sample/pack.json 查看。
播放中的基本操作
| 操作 | 结果 |
|---|---|
| 点击对话框或播放区空白处 | 推进一句 |
| 点击选项 | 进入对应分支 |
| 「菜单」 | 返回主页、存读档、打开播放设置或继续播放 |
| 「存读档」 | 打开 20 个手动槽；自动与快速槽当前置灰 |
| 「设置」 | 打开声音与排版设置抽屉 |
| 浏览器首次出声前 | 显示「点击解锁音频」胶囊；任一次操作后解锁 |
画面组的「恢复本组默认」经确认后恢复浅色主题、100% 缩放与默认界面实现，并清除皮肤选择记录，重新套用内置默认皮肤；缺少默认皮肤时使用内置样式。该操作不清除存档或已装载单元。
返回与关闭
主页、独立设置和剧情使用同一导航栈。设置左上角的「返回」退回上一层；剧情通过菜单里的「返回主页」离开，离开时停止播放。
Esc 与 Android 物理返回键在普通界面中按当前状态处理：先关闭常规模态层；剧情对话框隐藏时先恢复显示，自动／快进开启时先退出该模式，其他情况下打开播放菜单；独立设置退回上一层；主页栈底吸收按键，不退出应用。
独立信任页显示期间，Android 物理返回键会转交该页，效果与 Esc 相同：拒绝当前裁决或关闭信任管理页，永不批准。此时底下的剧情、菜单与导航栈不响应这次按键。
信任页为什么是独立源
信任页不是外壳里的一个普通弹窗，而是另一个源里的文档：
| 运行形态 | 信任页源 | 信任存储 |
|---|---|---|
| 网页开发 | http://localhost:5174 | 信任页独立源的 IndexedDB |
| Tauri 桌面／移动 | 独立自定义协议源 | Rust 侧持有的应用数据文件 |
外壳通过 iframe 把信任页嵌进来，并用 MessageChannel 建立专用通道。信任页顶部固定显示「🛡 独立安全源：…」与「外壳与扩展代码无法读取本页内容；信任记录只能在本页点击写入」。外壳可以请求裁决、读取相关快照、更新官方签名清单与请求打开撤销入口，但不能代替用户写入个人信任记录。
已建立连接后的非交互调用（签名清单、快照和主题）每次最多等待 10 秒，超时会拒绝并丢弃迟到应答；用户点选的裁决与信任管理操作没有自动期限，直到用户响应或信任页关闭。
这也是为什么开发服务器要同时起两个端口：如果信任页与外壳同源，扩展代码就可能接触到信任 UI 与存储，独立源就失去意义。
装载外部包
网页端
- 点击顶栏「离线导入」；
- 在「离线导入扩展单元」中选择「选择目录…」或「选择 ZIP 文件…」；
- 目录选择使用浏览器的目录上传能力，ZIP 只接受
.zip； - 选好后，外壳把来源交给 Kernel，逐个单元解析清单、核验签名并做准入判定；
- 成功的单元进入已装载列表，被拒绝的单元在任务槽中保留原因码。
网页端具备 OPFS 时即可列出此前写入站点私有存储的已完成包；写出入口还要求 Web Locks。缺少 OPFS 时两者都不可用；缺少 Web Locks 时仍可装载已保存包或选择外部目录、ZIP，但会明确显示当前宿主不支持写出产物。
Tauri 端
Tauri 端有两种来源：
- 原生文件选择器：与网页端一样选择目录或 ZIP；
- 应用数据目录
packs/：打开导入窗口时会列出已保存的包，点「装载」即可。
导入窗口以选择器与已保存包列表为准；离线翻译看板另支持把目录或 ZIP 拖入。
装载结果如何看
- 每个单元独立判定，不因为同包内另一个单元成功就沿用结果；
- 代码单元只允许一个打包后的单文件 ESM 入口；多文件入口或缺失入口会被判为清单不合法；
- 已装载单元显示「未签名，名称未经核验」时，表示它没有可用签名，名称不能作为身份依据；
- 点「卸载」只撤销该单元的作用域；它写入的旗标归属会被标为孤儿，但不会删除任何进度。
未签名单元如何裁决
需要你确认时，信任页会显示一个不可被外壳伪造的对话框。对话框的标题、按钮与规则由触发原因决定：
| 触发原因 | 对话框标题 | 同意按钮 | 额外规则 |
|---|---|---|---|
| 官方清单外的发布者（TOFU） | 首次装载第三方扩展（TOFU） | 信任此公钥并装载 | 记录公钥；同一发布者同一密钥后续不再询问 |
| 未签名单元首次装载 | 未签名单元首次装载批准 | 批准并记录归档哈希 | 记录归档哈希；内容变化后需重新批准 |
| 未签名单元内容变化 | 未签名单元内容已变化，需要重新批准 | 批准并记录归档哈希 | 会逐项展示变化，需重新核对 |
| 同名异钥 | 发布者签名密钥冲突（同名异钥） | 信任新密钥（覆盖旧记录并留痕） | 覆盖旧记录须二次确认 |
| 敏感能力或机制写边 | 扩展申请需要你同意的权限 | 同意并装载 | 展示能力卡与 trusted 目标 |
共同规则：
- 默认焦点在「拒绝」，按 Esc 等同于拒绝；
- 同意按钮先锁定倒计时（通常 1.5–2 秒），倒计时结束前不可点击；
- 信任页可见区域不足、页面不可见或内置字体未加载时，所有写操作锁定；
- 拒绝不会留下半装载的单元；批准后装载器会重读信任快照并重新判定；
- 清除信任记录只影响以后的装载，不卸载正在运行的单元。
批准未签名单元不等于确认它安全
信任页记录的是「你见过这份归档并同意执行」，不是安全审计。插件与 Mod 和框架运行在同一个 JavaScript realm，没有技术隔离；只装载你愿意执行其代码的单元。
独立设置与播放设置
在主页点击「设置」进入独立设置界面，无需先播放剧情。它包含五组：
| 分组 | 当前内容 |
|---|---|
| 声音通道 | 五条音量滑杆 |
| 文字与阅读 | 逐字速率、自动等待、快进策略与语言选择 |
| 画面与皮肤 | 浅深主题、显示比例、皮肤与界面实现选择 |
| 下载线路、账号 | 置灰并标「暂未提供」 |
声音、文字与画面各有「恢复本组默认」，点击后先确认。语言可跟随系统或选择已装载语言表提供的语言；它决定剧本与扩展文本的取用，不会翻译外壳自身的中文界面。
播放界面工具条或菜单里的「设置」仍打开「声音与排版设置」抽屉。抽屉与独立设置共用以下数值；打开抽屉不会暂停剧情与背景音乐，拖动即生效，无需确认。
| 分组 | 可调项 | 范围与默认 |
|---|---|---|
| 音频通道音量 | 总音量 Master、背景音乐 BGM、动作音效 SE、角色语音 Voice、环境声 Ambient | 0–100%，默认均为 100% |
| 文本逐字速率与自动／快进策略 | 逐字速率（CPS） | 0–120 字/秒，默认 40；0 等同「立即显示」 |
| 同上 | 自动播放等待 | 0.5–5.0 秒，默认 1.5 秒 |
| 同上 | 快进跳过未读剧本 | 默认关闭；关闭时遇到未读台词会停顿 |
设置保存在外壳本地存储中；下次启动时读回并逐项校验，不合格的项回落到默认值。音频服务尚未就绪时，音量滑杆置灰并显示「音频暂不可用」。
皮肤与界面实现
在「画面与皮肤」选择「核心内置默认皮肤」、其他已登记皮肤或「内置样式（不换皮）」。首次启动自动使用默认皮肤；显式选择不换皮后，刷新也保留该选择。所选皮肤所属单元卸载时先回到内置样式，选择仍保留，重新装载后恢复。无法读取皮肤时不阻止启动，原因写入顶栏「日志」。
当前已提交版本的「画面与皮肤 → 恢复本组默认」将主题设为浅色、比例设为 100%、界面实现设为「跟随默认」，并选择不换皮。恢复首次启动默认皮肤的调整尚未纳入本页代码基线；需要默认皮肤时可直接选中它。
「界面实现」只在某个界面有多个候选，或已保存的实现已卸载时显示。用户选择优先，其次是数据包指定，再次是内置实现；卸载所选实现时暂按默认显示，重新装载后恢复选择。皮肤调整外观，界面实现决定由哪一条已登记实现绘制界面。接口与约束见 Platform。
离线翻译看板
顶栏「离线翻译」打开「离线翻译作业看板」。它把输入源资源转换成框架可消费的数据包与资源包，但不会自动装载产物。
基本流程
- 把输入源目录或 ZIP 拖入看板，或点「选择目录…」「选择 ZIP 文件…」；
- 看板先做格式识别，列出识别结果、置信度与规则来源；
- 选择要使用的规则；置信度低于 100% 时会提示部分识别文件缺失，需要再点「仍然发起」；
- 作业按四道工序推进：识别与核验、剧本解析与 IR 转换（隔离 Worker）、资源字节搬运与 VPath 映射、封装清单与写出产物；
- 完成后列出写出的数据包与资源包；逐个点「装载」后，才进入正常的准入与信任流程。
预算与落盘
| 项 | 默认 | 可调范围 |
|---|---|---|
| 墙钟执行时间 | 30 分钟 | 30–240 分钟 |
| 输入数据总量 | 1 GiB | 1–8 GiB |
| 输出产物总量 | 1 GiB | 1–8 GiB |
网页端产物只有在 OPFS 与 Web Locks 都可用时写入站点私有存储（OPFS）；Tauri 端写入应用数据目录的 packs/。网页完成标记不超过 4 KiB，已完成列表最多 10,000 个；Tauri 暂存最多 16 个、合计 4 GiB，空闲 1 小时回收。写出失败时可以只重试写出，已写出的包不会重写；超预算时隔离环境会被终止，未提交的暂存会被清理。
没有装载对应规则数据包时，看板会提示「没有翻译规则能识别这个输入」，此时应先装载规则包，或换一个输入。翻译层的规则、预算与产物边界见翻译层。
当前未提供的入口
线路、自动与快速存档、云存档、孤儿 GC、输入路由、性能分级、账号、热更新、社交、活动、支付、完整编辑器、本地化工作台、运营后台，以及 Collection 的玩法，均未实现。Explore 已有地图、热区、会话内道具与剧情导航，但不提供地图存档或跨进程恢复；Growth 已实现等级与强化，觉醒、装备、技能强化与 Battle 数值交界未实现；Extra 已完成受控生命周期，不代表完整玩法内容。置灰入口与这些缺口一致；阶段边界以阶段总览与当前状态与测试为准。
下一步
- 想制作自己的包：分发包与包结构 → 包清单与目录
- 想判断扩展档位：四档扩展模型 → policy 与写边
- 遇到启动或装载问题：故障排查 → 常见问题
- 想理解信任判定：信任与签名 → 装载管线与 guard