revolution-framework git:20261016.debc2d4A

Immutable. This exact content never changes and is served at /api/v1/blob/46b9a94344567d27.

---
name: revolution-framework
description: 本指南适用于 Revolution（RevolutionFramework / Rev 前缀）Unity 游戏框架的开发、排错、架构选型与代码审查。任务涉及 Assets/Revolution、RevInitialize、RevScope / RevDomain / RevLogic（自定义游戏域、业务单元、FSM 游戏流程联动）、RevLightFSM / RevLightStackFSM / RevHeavyFSM、RevUI（面板、数据刷新、控件事件、动画、横竖屏 Canvas）、RevResManager / RevPool（资源、引用计数、AB 打包、Android Shader）、RevTimer / RevMono / RevEvent（owner 与域清理）、RevServices / RevServiceLocator、RevTask、RevScene、RevInput、RevSound、RevSequence、RevGM、RevDataTableManager、RevLog、RevAppLifecycle、RevStripGuard，或 RevHotUpdate 扩展包（四个资源钩子、候选版本激活门禁、差量与跨启动续传、本地 CDN Demo）时使用。也适用于平台与 IL2CPP 裁剪适配、工程外纯 C# 断言、文档同步和按本框架规范生成代码。即使未明确提到 Revolution，只要涉及上述类型或目录，也应使用本 skill。
---

# Revolution 框架开发 Skill

Revolution 是一套**从零手写、可读可测、无魔法**的 Unity 游戏框架（C#）：**20 个功能模块 + 1 个启动门面（`RevInitialize`），共 21 个 Runtime 目录**。
2026-10-16 已跟踪源码快照：Runtime **199** 个 `.cs`、Editor **44** 个 `.cs`、独立扩展包 `RevHotUpdate` **20** 个 `.cs`；Demo 仍为 **18 个 `.unity` 场景**，新增 `RevScopeFlowDemo.cs` 挂任意场景运行，不计作独立场景。

> 按需读取 `Facade/` 文件头与对应 Demo；不要为了了解框架通读内核。
> **以当前源码和 Git 跟踪清单为准**：README、历史测试数字与设计方案可能滞后；不得把方案或未提交自动化草稿当作已落地能力。

它的三条设计取向直接决定你该怎么写代码：

1. **模块化、门面唯一**：每个模块只暴露一个门面（`RevTimer` / `RevResManager` / `RevUI` …），业务只碰门面，内核（`Core` / `Implementation`）不改也不读。
2. **失败必须可见**：不吞异常、不静默 return —— 失败一律给原因枚举 / 句柄字段 / 返回值，日志有唯一出口 `RevLog`。
3. **内核尽量不依赖引擎**：路径、句柄、槽位表、池引擎、日志/计时器内核是纯 C#，**能链接进普通 .NET 工程跑断言**（见 `references/verify-and-test.md`）。

## 模块总览（21 个 Runtime 目录，一张表找全）

> "我想做 X → 用哪个门面"。签名与最小示例在对应参考文件里；**没有合适模块就先用"服务 + 面板"实现，不要先动框架**。

| 我想… | 门面 | 一句话 | 速查位置 |
|---|---|---|---|
| 启动游戏、初始化框架 | `RevInitialize` | 启动入口调一次，装配资源系统策略 | `startup-and-platform.md` §1 |
| 切后台 / 回前台处理 | `RevAppLifecycle` | `Paused` / `Resumed` / `Quitting` 事件 + 后台时长 | `startup-and-platform.md` §2 |
| 确认代码裁剪没误伤 | `RevStripGuard` | 真机启动自检关键类型，缺了报人话 | `startup-and-platform.md` §3 |
| 打日志 | `RevLog` | 五级 + tag + 重复抑制 + 环形缓冲 | `modules-core.md` §1 |
| 多久之后 / 每隔多久 | `RevTimer` | 四时间域，owner/scope 防泄漏 | `modules-core.md` §2 |
| 纯 C# 类要每帧回调 / 协程 | `RevMono` | 不摆物体拿 Update/LateUpdate/FixedUpdate | `modules-core.md` §3 |
| 频繁创建销毁的对象 | `RevPool` / `RevRefPool` | GameObject 池（可 `[RevPoolPrefab]` 按类型取）/ 纯 C# 池 | `modules-core.md` §4 |
| 一对多解耦通知 | `RevEvent` | 字符串事件名，派发中可安全增删 | `modules-core.md` §5 |
| 跨界面共享的业务能力（注册 / 取用 / 用完注销） | `RevServices`（默认）/ `RevServiceLocator`（作用域·进阶） | 一行 `Register`、一行 `GetRequired`、一行 `Unregister`；每局一份才用 Builder | `modules-core.md` §6 |
| await 一帧 / 等待 / 取消 | `RevTask` | 轻量单线程异步（框架唯一异步基建） | `modules-core.md` §7 |
| 切场景 | `RevScene` | 进度永远 0~1，切前按约定清理 | `modules-core.md` §8 |
| 键鼠 / 触屏 / 手柄 / 手势 | `RevInput` | 动作名绑定 + 屏蔽栈 | `modules-core.md` §9 |
| 播音效 / BGM | `RevSound` | 一行播放，2D/3D/BGM，音量总线 | `modules-content.md` §1 |
| 状态切换（流程 / AI） | `RevLightFSM` / `RevLightStackFSM` / `RevHeavyFSM` | 类型名统一 `FSM`；宿主驱动 | `modules-content.md` §2 |
| 游戏域与无界面业务单元 | `RevScope` / `RevLogic` / `RevLogicBase` | 自定义字符串域、统一回收；FSM 管状态，域管生命周期 | `modules-core.md` §12、`playbooks.md` R19 |
| 加载资源 | `RevResManager` | 逻辑路径 + 引用计数 + 分组卸载 | `modules-content.md` §3、`resource-and-ab.md` |
| 单例 | `RevSingleton*` | 三个基类（优先服务定位器） | `modules-content.md` §4 |
| 做界面 | `RevUI` / `RevUIPanel` | 声明式面板、数据单向流、动画库 | `modules-content.md` §5、`ui-and-layering.md` |
| 一串动作（播放→等待→并行） | `RevSequence` | 不可变蓝图 + 取消收尾契约 | `modules-content.md` §6 |
| 运行时调试指令 | `RevGM` | 一行注册，游戏内 / 编辑器共用 | `modules-content.md` §7 |
| 读配置表 | `RevDataTableManager` | 表也是资源，走资源系统 | `modules-content.md` §8 |
| 资源热更（扩展包） | `RevHotUpdate` | 清单 + 差量下载 + 版本目录 | `modules-content.md` §9、`hot-update.md` |

## 第一步：30 秒分诊——先判断"用户要的是哪一类事"，再只读对应那一个文件

> **读文件的原则（渐进式）**：先读本文件的总览表 + 铁律；**只读分诊命中的那一个文件**；不要为了"了解框架"通读 `references/` 或源码。
> 需要大范围搜索源码之前，先问自己：这个问题在下表的哪一行？

| 用户在说什么 | 类型 | **先读这个**（读完通常就够了） |
|---|---|---|
| "帮我写个 XX 功能 / 怎么实现 XX / 我想做 XX" | **写功能** | `references/playbooks.md`（20 个任务配方，自带选型、标准写法与验证） |
| 自定义域 / 大厅战斗切换 / FSM 联动 / 无界面业务 Logic | **作用域流程** | `references/modules-core.md` §12 + `references/playbooks.md` R19 |
| "XX 和 YY 用哪个 / 该不该用事件 / 要不要新建 System" | **选型** | `references/decision-guide.md` §1 对照表 |
| "框架有没有 XX 能力 / 能不能 XX"（尤其是你不确定 API 存不存在时） | **查边界** | `references/decision-guide.md` §2「不存在 / 不做」清单（防幻觉） |
| "XX 不工作 / 出现 XX 现象 / 报错 XX / 编辑器好真机坏" | **排错** | `references/troubleshooting.md`（症状 → 原因 → 先查什么） |
| "帮我审查这段代码 / review" | **审查** | `REFERENCE_GUIDELINES.md`（四段式输出） |
| 要完整签名 / 全部重载 / 精确参数 | **查 API** | `references/modules-core.md` 或 `references/modules-content.md`（门面签名 + 铁律） |
| 启动入口 / 切后台 / 出包 / 小游戏 / 代码裁剪 | **平台与真机** | `references/startup-and-platform.md` + `templates/RevBoot.cs.txt` |
| 加载资源 / 打包 AB / ResMap / 编辑器直读差异 | **资源专题** | `references/resource-and-ab.md` |
| 面板传数据 / 刷新时机 / 动画 / Part / Back / 横竖屏选择及预览 | **UI 专题** | `references/ui-and-layering.md` |
| 接热更 / 排查热更 | **热更专题** | `references/hot-update.md` |
| 编辑器菜单（打包 / 导表 / GM 面板 / UI 生成器 / 平台工具） | **工具** | `references/editor-tools.md` |
| 代码 / 注释规范（**本项目硬规范**） | **规范** | `references/code-style.md` |
| 怎么证明"改对了" / 提交推送 | **验证交付** | `references/verify-and-test.md` |
| 权威文档 / 全局文档在哪 | **找文档** | `references/docs-map.md` |

## 不确定时怎么办：反幻觉协议（写代码前必过）

这个框架的 API 有些**看起来该有、其实没有**（例如 `RevEvent.AddOnce`、`RevHeavyFSMGroup`、`IRevHotSink`、`RevSound` 的"在播数量"查询）。写代码前按顺序做：

1. **用到的每个 `Rev*` API，都能在 `references/` 里找到签名或 Demo 原样代码**——找不到就**不要凭印象写**；
2. 找不到时，先用可用的符号导航定位定义，再读取对应 `Facade/` 或实际定义文件；符号服务不可用时转精确文本查找。确认参数、命名空间、约束和清理契约后再写；
3. 疑似框架未提供的能力先查 `references/decision-guide.md` §2；确认未做后采用已有替代方式，不发明同名 API；
4. 文档与源码冲突时以代码为准；区分技术方案中的目标设计、已提交实现和未完成草稿；
5. 优先参照真实 Demo，但对采用的 API 重新核实；存在 Demo 不等于本轮已经编译、运行或真机验证；
6. 模块规模用当前源码与 Git 跟踪清单核对；历史断言/性能数字标明验证时间与覆盖范围，不直接当作当前 CI 证据。

## 技术铁律（写代码必须遵守）

1. **使用公开入口**：业务使用各模块门面，以及 `RevScope` / `RevLogic`、公开 FSM 类型与状态基类；不直接创建内部内核、反射绕开契约或直接读资源文件。
2. **失败必带原因**：资源看 `handle.ErrorReason`，GM 看 `RevGMResult.Message`，热更看 `result.Error` / `LastError`；Android AB 问题同时查 `RevLog` 的 `Res` 标签。业务拒绝给出明确原因。
3. **先确定生命周期归属**：对象级用显式 owner + 对应清理；域级可用活动 `RevScope` 兜底 + `Exit`；Logic 用基类携带自身 owner 的 `After/Every/Listen`。显式 owner 优先，不能假设有域就能收走所有对象。匿名 lambda 需要保存同一委托或按 owner/域清理；资源取用与释放仍须配对。
4. **资源只写逻辑路径**：用生成的常量（`RevResPath.*`，见 `Assets/Revolution/Generation/RevResPath.cs`）或"两段式" `Load(根目录, 资源名, 类型, 分组)`；**禁止**自己拼 `StreamingAssets` / `Application.dataPath` 路径读资源（缓存、引用计数、平台差异、热更都会失效）。
5. **UI = 一个面板类 + 职责钩子**：`[RevUIPanel]` 声明路径、`[RevBind]` 绑节点、`OnBindView` 只装配、`OnRefreshView` 只落屏、`OnClick` 只转发；数据**单向** `SetData → OnDataChanged → RefreshView`；**框架不提供 `System` / `BusinessLogic` 层**（结论见 `references/ui-and-layering.md`）——跨界面复用的能力交给**服务定位器**，只属于这一屏的流程留在面板里。
   **刷新时机三条（新手最易混）**：① 框架**不监听数据对象内容**——`OnRefreshView` 只在"打开 / 面板开着时 `SetData` / 手动 `RefreshView()`"这三个时机被调；② **原地改数据字段（`Data.Count++`）必须手动 `RefreshView()`**，换新对象走 `SetData` 才自动刷（`OnDataChanged` 里**不要**再手动 `RefreshView()`，会画两遍）；③ **`SetData` 写在业务侧"数据产生的地方"**（点击回调 / 网络回包），不写在面板里；面板是数据的消费方。详见 `references/ui-and-layering.md` §1.1。
6. **异步只用 `RevTask`**：`await RevTask.Delay/Yield`、`await RevScene.LoadAsync(...)`、`await RevHotUpdate.InitializeAsync(...)`；**不要**引入 `System.Threading.Tasks.Task`、不要用协程写业务（`RevMono.StartCoroutine` 只用于桥接旧代码）。取消用 `RevCancellationTokenSource` + `token.ThrowIfCancelled()`。
7. **事件**：`string` 事件名（常量集中在一个类里）+ **同一事件名只能有一种签名**；只在主线程注册/派发；派发过程中可以安全增删（框架做了标记删除），但回调里别做重活。
8. **时间**：`RevTimer.After/Every` 必须能停（owner、计时器 scope 或活动游戏域）；UI 倒计时/超时用 `RevTimeDomain.Unscaled`；`At(...)` 前先 `SyncServerTime`。域 `SetTickEnabled(false)` 不会暂停计时器。
9. **服务**：**默认用 `RevServices`**——一行 `RevServices.Register<IX, X>()`、一行 `RevServices.GetRequired<IX>()`、不用了 `RevServices.Unregister<IX>()`（**不要**为此写静态类 + `static readonly` 缓存 + 链式 `Build()`）。纪律：**全局服务集中在启动入口注册；跟着模块 / 场景走的服务，谁注册谁注销**（`owner: this` + `OnDestroy` 里 `UnregisterAllOf(this)`）；重复注册当场报错（要换先 `Unregister`）；`Register<I>(已有实例)` 注销时**不** `Dispose`，`Register<I, T>()` / 工厂注销时 `Dispose`；**不要把取到的服务长期存成字段**（注销后它是已 `Dispose` 的对象）。必需依赖用 `GetRequired<T>()`（没注册当场炸），可选能力用 `Get<T>()` / `TryGet<T>()`。**只有**要"同一个服务类型每局 / 每个场景各一份"或"单测另建隔离容器"时，才用 `RevServiceLocator.Create()…Build()` + `CreateScope()`（`AddScoped` 的服务必须在作用域的 `using` 里取）。
10. **编辑器 vs 真机**：编辑器默认**只**注册 `RevEditorResPolicy`（AssetDatabase 直读，AB/Resources 完全不参与）；要看 AB / 热更效果，必须开 `RevResBootstrap.UseABInEditor = true`（菜单 `Revolution.Tools/资源/AB 加载模式（编辑器）`）。另外**编辑器里平台名恒为 `PC`**（`RevHotPlatform` 带 `!UNITY_EDITOR`）。
11. **不新增分层、不新增门面**：不要给框架加 `System` / `BusinessLogic` 这样的层，也不要给某个模块加"第二套加载 API"（会立刻长成第二套系统）。真需要扩展时，优先**服务 + 约定**，其次才是框架改动。
12. **改框架要照既有形状**：目录分层 `Core`（数据与契约）/ `Facade`（对外入口）/ `Implementation`（实现）/ `Interfaces`（接口）/ `Support`（宿主适配）；每个文件**开头写清"为什么这么写"**；新增资产要带 `.meta`（文件夹 meta 一律是**同级** `<文件夹名>.meta`）。
13. **启动只调一次 `RevInitialize.Initialize()`**：它只装配资源系统策略；**不要**再直接调 `RevResBootstrap.Instance.Init()`，也不要去"手动初始化"其它模块（`RevEvent` / `RevInput` / `RevTimer` / `RevUI` / `RevPool` / `RevAppLifecycle` 都已自动就位，重复启动反而会清监听）。骨架见 `templates/RevBoot.cs.txt`。
14. **切后台 / 回前台用 `RevAppLifecycle` 事件，不要自己写 `OnApplicationPause` / `OnApplicationFocus`**：框架已对"Pause 与 Focus 同时到达"去重；`Quitting` 移动端不保证触发，数据要随存随写。
15. **面向真机 / 小游戏 / WebGL 写代码**：不引入 `Thread` / `Task`（小游戏单线程）、不依赖同步加载（用 `LoadAsync` / `GetAsync` / `OpenAsync`）、不依赖文件日志；**主推关闭 Managed Stripping**（开了就生成 `link.xml` 并看 `RevStripGuard` 自检）。清单见 `references/startup-and-platform.md` §4–5。
16. **对象池按类型取优先**：预制体脚本上写 `[RevPoolPrefab(root, name, Group = ...)]`，业务 `RevPool.Get<T>()` / `GetAsync<T>(cb)` / `Clear<T>()` / `DestroyPool<T>()`，取用与清理处都不写路径字符串（特性**不继承**，子类要自己写；同一预制体只能被一个类声明）。
17. **域与流程分工**：用业务 `const string` 定义域，不扩改 `RevDomain`；FSM 管状态、`RevScope` 管回收、`RevLogicBase` 管域业务。联动不接入 Scope 内核；域服务显式指定 owner。域兜底需 `TakeOverOwner = true`（默认），资源按组回收还需配置非 `Unknown` 的 `Reclaim`；关闭兜底后用 `Attach` 和显式归属。
18. **横竖屏由项目选择**：首次 Open/Preload 前配置 `RevUISetting.CanvasOrientation`；默认 `Auto`，也可固定 `Portrait` / `Landscape` 或保持 `UseDesign`。只影响根画布缩放，不修改设备方向或自动重排布局。
19. **热更先验证再激活**：保留清单门禁、完整候选快照校验与失败回退；四钩子指向一致的活动版本。当前没有 `ProbeBundles` 业务资源探针，桥的 `Reset()` 也不等于解除四委托。灰度、签名、按标签下载等方案能力不写成已实现 API。
20. **本地编辑器版本不入库**：`ProjectVersion.txt` 已取消跟踪；不重新提交或用 `git checkout --` 还原它，不擅自回滚用户的包源、包锁定与设置。既有版本守护与此策略存在冲突，见 `verify-and-test.md`。

## 代码与注释规范（本项目硬规范，必须遵守）

1. **方法签名的 `(` 与参数不换行**：默认写一行；**只有太长（显示宽度 > 约 160 列）才换行**。长消息/长参数先提成局部变量，让"调用/抛出"本身保持单行。
2. **方法体必须带大括号**，哪怕只有一行（`if (x) return;` ✗ → `if (x) { return; }` ✓）。
3. **核心 / 关键 / 容易踩坑或被忽略的地方要写详细注释，面向小白**：解释"为什么这么做 / 不这么做会怎样"，而不是复述代码。
4. 新框架类型用 `Rev` 前缀、FSM 缩写用大写；既有 FSM 物理文件名仍保留 `Fsm` / `StateMachine`，不要顺手改资产路径。框架命名空间 `Revolution`，扩展包 `Revolution.HotUpdate`，Demo 用 `Revolution.Demo.<模块>`；业务状态、业务域常量名按项目约定。
5. 中文注释、术语与文档保持一致（"门面 / 句柄 / 分组 / 逻辑路径 / 大版本锚定"…）。
6. 详细正反例与自检脚本思路见 `references/code-style.md`。

## 开发行为准则

以下四条偏向"稳"而不是"快"。琐碎任务自行判断。

### 1. 先想清楚再写

不要假设、不要藏疑惑、把取舍摆出来。动手前先明确：

- **模块选型**：这是"多久之后"（`RevTimer`）、"每帧"（`RevMono`）、"等一个异步结果"（`RevTask`）、还是"一次变化多处反应"（`RevEvent`）？
- **生命周期归属**：跟界面走的放面板；无界面、活一段玩法的用 `RevLogicBase` 归域；跨域能力放服务。一次性顺序流程用序列，阶段切换用 FSM。
- **失败出口**：失败时业务要拿到什么？（原因枚举 / 回调 / 异常 / 重试）
- **编辑器与真机差异**：这次改动在"编辑器直读"和"AB 模式"下都成立吗？

### 2. 最简优先

写解决问题的最少代码，不做没人要的抽象/配置/"以后可能用得上"。判断法：**加第四个监听者时，广播方要不要改代码？** 要改就别上事件。

### 3. 外科手术式改动

只动该动的：不顺手"美化"相邻代码、不重构没坏的、不删既有死代码（发现了**报告**即可）；匹配既有风格；自己改动造成的孤立引用要清掉。**改完要同步文档**（见下）。

### 4. 目标驱动、可验证

把任务变成可验证目标，别停在"能跑"：

```text
1. 读该模块《使用说明》→ 验证：写法与文档一致（门面、参数、清理方式）
2. 写代码 → 验证：Unity 编译 0 error（必要时用工程外桩工程先编译一遍纯 C# 部分）
3. 跑对应 demo 场景 → 验证：屏幕上"日志/结果"符合预期
4. 要动框架内核 → 验证：工程外纯 C# 断言全过（见 references/verify-and-test.md）
5. 交付 → 验证：文档 / demo / GM 命令 / change 说明同步
```

## 典型工作流

### A. 写新功能（7 步）

1. **定位模块 / 配方**：先在 `references/playbooks.md` 找对应任务（R1~R20）；无对应配方时用模块总览，按面板/服务/域 Logic 选择归属，不先改框架。选型拿不准读 `references/decision-guide.md` §1。
2. **需要完整细节时读该模块的《使用说明》**（`references/docs-map.md` 给路径）——它是权威，本 skill 只是索引。
3. **找最近的 demo**（`Assets/Revolution.Demo/<模块>.Demo/`，18 个可运行场景；`playbooks.md` 每节都写了"抄哪个 Demo"）照着写。
   **要动框架本身（修 bug / 加功能）时，先查 `Assets/Revolution/CHANGELOG.md` 与 `Revolution.Document/bug修复日志/`**：这个模块以前修过什么、现行契约是什么——避免重复踩坑，也避免给"已修复的缺陷"写绕过代码（见 `references/pitfalls.md` 末尾"现行契约速查"）。
4. 写代码，守住上文的铁律与规范。
5. **自我审查**：过一遍 `REFERENCE_GUIDELINES.md` 的清单。
6. **验证**：编译 + demo 场景 / GM 面板 / 工程外断言。
7. **同步文档**：改了行为 → 改该模块《使用说明》；改了设计 → 改《架构解析》；同时更新 md 与 html（`Revolution.Document`，在线站会自动发布）。

### B. 审查代码

读 `REFERENCE_GUIDELINES.md`，按"严重问题 → 规范问题 → 潜在风险 → 优化建议"输出；重点看：owner/scope 清理、成对 Release、事件签名与重复订阅、时间域、编辑器/真机差异、异常是否被吞。

### C. 排错（先查表，再走 30 秒顺序）

**先在 `references/troubleshooting.md` §1 按现象找行**（按 UI / 输入 / 计时器 / 资源 / 对象池 / 场景 / 音效 / 状态机 / 序列 / 热更分组，60+ 条）；表里标"（已修）"的现象，在最新代码上仍出现 → 多半是**业务侧绕过了契约**，不是框架 bug。找不到对应行再走：

1. `RevLog` 里的 tag 过滤（模块都有自己的 tag：`Scene` / `ActionSequence` / `HotUpdate`…）。
2. 句柄原因：`handle.ErrorReason`（资源）、`RevGMResult.Message`（GM）、`RevHotUpdate.LastError` + `RevHotUpdate.Dump()`（热更）。
3. 能力自检接口：`RevTimer.Count` / `RevMono.Count` / `RevEvent.GetListenerCount(名字)` / `RevResManager.CachedCount` / `RevPool.DumpStats()` / `RevUI.DumpStats()` / `RevScope.Dump()` / `RevScope.LastCloseReport.ToText()` / `RevLogic.Count` / `RevLog.Dump()` / `RevAppLifecycle.PauseCount` / `RevStripGuard.Dump()`。
4. 复现：打开对应 demo 场景点按钮；或写一条 GM 命令直接在编辑器面板里跑。

### D. 交付

- 代码 + **文档（md & html）** + 必要时 demo/GM 命令；改了 `CHANGELOG.md` 的"未发布"段（新增 / 修复 / 变更）；
- 里程碑提交按仓库既有风格写提交信息（**统一中文**、说清"为什么"与验证数据）；
- ★ **Windows PowerShell 提交中文信息的坑**：`git commit -m "中文…"`（尤其多行）会被本地编码搞成乱码或直接解析失败。**正确做法**：把信息写进 UTF-8 文本文件，用 `git commit -F 文件` 提交，**提交后删掉该文件**（先 `git add` 再建临时文件，或把它放进 `.gitignore`，否则会被 `git add -A` 误带进提交）；
- 安装/分发走**四条**生成分支（改 `main`，不要往生成分支上提交）：`package`（框架本体）、`demo`（示例工程）、`hotupdate`（热更扩展包）、`skill`（本 skill）。

## 参考文件导航

"何时读哪个文件"已在上面的**分诊表**里给全了，这里只列清单（避免重复）：

- **按任务找**（优先）：`references/playbooks.md`（20 个配方）· `references/decision-guide.md`（选型 + 不存在清单）· `references/troubleshooting.md`（症状速查）
- **查 API 与专题**：`references/modules-core.md` · `references/modules-content.md` · `references/startup-and-platform.md` · `references/resource-and-ab.md` · `references/ui-and-layering.md` · `references/hot-update.md`
- **规范与交付**：`references/code-style.md` · `references/editor-tools.md` · `references/verify-and-test.md` · `references/docs-map.md` · `references/pitfalls.md`（坑位 + 已修复缺陷的现行契约）
- **审查**：`REFERENCE_GUIDELINES.md`
- **骨架模板**（`templates/`）：`RevBoot.cs.txt`（启动入口）· `RevXxxPanel.cs.txt`（UI 面板）· `RevXxxService.cs.txt`（业务服务）· `RevXxxDemo.cs.txt`（Demo 场景脚本）· `offline-harness/`（工程外断言工程）