快速开始
Weftale 是一个面向视觉小说（ADV）类内容的通用框架：剧本播放、演出、音频、文本排版、存档，以及后续阶段的玩法、在线与创作工具。它把「框架能力」与「具体内容」分开：框架只识别内部协议，外部输入先经隔离翻译层转换；扩展单元按四档模型装载，并在装载时经过准入判定与信任裁决。
本页只回答三件事：这是什么、需要什么、怎样在五分钟内跑起来。更细的环境说明见环境与依赖，命令清单见安装、运行与构建。
这是什么
| 维度 | 说明 |
|---|---|
| 定位 | 通用 ADV 运行时与扩展生态，不绑定任何具体输入源 |
| 内核 | Cordis 插件内核；大插件之间只经 ctx 交流 |
| 运行环境 | 纯浏览器是功能基线；Tauri 2 宿主只补浏览器做不到的差异 |
| 扩展单元 | 数据包、资源包、插件、Mod 四档，装载时统一准入 |
| 内容策略 | 仓库不含第三方内容；内置原创示例「一封晚到的信」可完整体验基础流程 |
| 当前阶段 | Phase 0、Phase 1、Phase 2 已完成；Phase 3 实现中 |
框架最重要的取舍是「大插件焊死、小插件可变」：大插件集合在构建期由根插件名单（RPM）确定，启动时核对清单与入口哈希；第三方不能新增大插件，只能通过数据包、资源包、插件与 Mod 扩展能力。详见根插件名单（RPM）与大插件与小插件。
五分钟跑起来
前置条件
需要 Node.js 24.x、Rust 稳定版 1.82 及以上，并为 Rust 安装 wasm32-unknown-unknown 目标。缺少任一项，npm install 之后的首次构建会失败。完整说明见环境与依赖。
cd weftale
npm install
npm run dev开发服务器会同时启动两个源，终端应出现类似输出：
外壳：http://localhost:5173/ 信任页源：http://localhost:5174/打开 http://localhost:5173/。启动阶段会依次显示「正在校验产物」「正在装载根插件」，随后进入「框架就绪」。内置示例「一封晚到的信」会自动装载，无需再准备任何外部内容。
在章节「一封晚到的信 · 路口」卡片中点击「进入本章」即可开始播放；完成该章后，「一封晚到的信 · 钟声」会接续。首次启动还会自动套用内置默认皮肤。首次运行的具体界面与装载流程见首次运行。
5174 不是第二个应用
http://localhost:5174/ 是独立源的信任页。它由外壳以 iframe 嵌入，只在外壳需要用户裁决或打开信任管理时显示；单独打开它不会进入应用，也不应把它当作开发入口。
想先确认环境是否完整，可以再跑两条只读检查：
npm run typecheck
npm testtypecheck 成功时没有额外输出；npm test 会同时跑 Node 与浏览器两个项目，浏览器专用用例在 Node 项目下跳过，因此看到「跳过」不等于失败。测试说明见安装、运行与构建。
启动后先看什么
| 界面元素 | 位置 | 作用 |
|---|---|---|
| 启动阶段卡 | 主区域上方 | 显示校验、装载、就绪或拒绝启动的状态与原因 |
| 章节目录 | 主页主区域 | 列出当前已装载的剧本章节；不可播放的章节标「尚未开放」 |
| 「离线导入」 | 顶栏 | 选择包目录或 ZIP，装载外部扩展单元 |
| 「离线翻译」 | 顶栏 | 打开离线翻译作业看板，把输入源资源写成数据包与资源包 |
| 「信任管理」 | 顶栏 | 打开信任页的撤销入口，查看并清除已记录的发布者密钥 |
| 「日志」 | 顶栏 | 查看装载结果、拒绝原因与运行观测，最多保留最近 300 条 |
| 已装载单元列表 | 主区域下方 | 显示单元名称、ID、版本与档位，并提供「卸载」 |
| 独立设置 | 主页快捷入口 | 调整声音、文字、主题、缩放、皮肤与界面实现，返回键退回主页 |
| 设置抽屉 | 播放界面内 | 与独立设置共用五条音量、逐字速度、自动等待与快进策略 |
顶栏的「线路（暂未提供）」以及独立设置中的下载线路、账号分组是置灰入口，属于后续阶段能力。主页、独立设置与剧情已由导航栈驱动；进入独立设置会暂时隐藏外壳的运行信息、阶段卡与单元列表，返回后恢复。更多界面说明见首次运行。
当前进度
状态只取「已完成／测试中／实现中／未实现」；「已完成」指网页与宿主两端的契约测试都通过。
| 阶段 | 目标 | 状态 |
|---|---|---|
| Phase 0 | 内核与契约 | 已完成 |
| Phase 1 | 翻译层与剧本播放 | 已完成 |
| Phase 2 | 演出与音频 | 已完成 |
| Phase 3 | 玩法与内容 | 实现中 |
| Phase 4 | 进度进阶与平台适配 | 未实现 |
| Phase 5 | 在线与运营 | 未实现 |
| Phase 6 | 创作与后台 | 未实现 |
阶段范围与出口条件见阶段总览与当前状态与测试。本页不把单项通过当作整体验收。
接下来读什么
| 你的目标 | 建议顺序 |
|---|---|
| 先把本机跑通 | 环境与依赖 → 安装、运行与构建 → 首次运行 |
| 判断一个扩展属于哪一档 | 概念地图 → 四档扩展模型 → policy 与写边 |
| 制作可装载的包 | 分发包与包结构 → 包清单与目录 → 装载原因码 |
| 读或改框架代码 | 架构总览 → 大插件与小插件 → 大插件总表 → 接口命名规范 |
| 理解信任与签名 | 信任与签名 → 装载管线与 guard → 装载原因码 |
| 参与项目 | 参与贡献 → 反馈渠道 |
一条推荐的完整路径
第一次接触
/guide/requirements
-> /guide/install
-> /guide/first-run
-> /concepts/four-tiers
-> /concepts/packaging
准备写扩展
/concepts/policy-and-writes
-> /concepts/slots
-> /reference/manifest
-> /architecture/loader-guard
-> /reference/error-codes
准备读代码
/architecture/
-> /architecture/rpm
-> /plugins/kernel
-> /plugins/scriptplay
-> /plugins/asset先记住四条约定
- 状态词有固定含义。 「已完成」不是「代码写完了」，而是网页与宿主两端的契约测试都通过；其余阶段只能写「测试中」「实现中」或「未实现」。
- 仓库不含第三方内容。 剧本、图像、音频与安装包都不进仓库；测试夹具只使用自己编的最小数据。外部内容由你在本机选择并装载。
- 网页是基线。 核心层只依赖浏览器能力；宿主差异集中在
src/host/与src-tauri/。网页端的行为不是桌面端的简化版。 - 写边是流程约束，不是安全边界。 插件与 Mod 和框架运行在同一个 JavaScript realm，没有技术隔离；只装载你愿意执行其代码的单元。
遇到问题
| 现象 | 先看 |
|---|---|
| 端口被占用、依赖装不上、wasm32 缺失 | 故障排查 |
| 装载被拒绝、为什么要求裁决 | 常见问题、装载原因码 |
| 不清楚某个名词 | 术语速查 |
| 想确认当前实现边界 | 当前状态与测试 |
文档与代码不一致时，以代码与测试为准；欢迎经反馈渠道指出具体位置与复现步骤。