sapdon 3.3.3 → 3.5.0

package/doc/dev/workflow.md

@@ -0,0 +1,257 @@
+# Sapdon 框架开发工作流
+
+本文档记录 Sapdon 框架自身的开发流程与经验，帮助贡献者快速上手。
+
+---
+
+## 1. 核心原则
+
+**永远只修改 `src/` 下的源码，不要直接修改 `prod/` 或 `node_modules/`。**
+
+- `prod/` 是构建产物，由 `npm run build` 自动生成，手动编辑会被覆盖。
+- 项目中的 `node_modules/@sapdon/*` 是从 `prod/` 同步的副本，手动编辑会被 `sapdon lib` 覆盖。
+
+---
+
+## 2. 框架自身的构建流程
+
+```
+npm run build
+  │
+  ├─ tsc          → src/ → dist/  (TypeScript 编译)
+  ├─ tsc-alias    → 解析路径别名
+  └─ rollup       → dist/ → prod/ (打包为 ESM bundle)
+       ├─ prod/cli/start.js   CLI 入口
+       ├─ prod/cli/index.js   CLI 库
+       ├─ prod/core/index.js  @sapdon/core
+       ├─ prod/oc/index.js    @sapdon/runtime
+       ├─ prod/utils/index.js @sapdon/utils
+       └─ prod/*/index.d.ts   TypeScript 声明文件
+```
+
+构建命令在 `scripts/build.cjs` 中定义。
+
+---
+
+## 3. 全局 CLI 与本地开发
+
+全局安装的 `sapdon` 命令通常通过 **junction 软链接** 指向仓库目录：
+
+```
+C:\nodejs\node_modules\sapdon  →  D:\Projects\sapdon
+```
+
+这意味着：
+- 修改 `src/` 后只需 `npm run build` 重建 `prod/`，全局 CLI 立即生效，无需重新 `npm i -g`。
+- 如果不是 junction 链接（例如直接 npm publish 后安装），需要把新 `prod/` 覆盖到全局安装目录，或重新 `npm i -g sapdon`。
+
+---
+
+## 4. 项目侧同步新库
+
+在示例项目或用户项目中，使用框架新功能前，需要将 `prod/` 同步到项目的 `node_modules/@sapdon/`。有两种方式：
+
+### 方式一：`npm i`（推荐）
+
+项目 `package.json` 的 `postinstall` 脚本会自动执行 `sapdon lib`：
+
+```json
+{
+  "scripts": {
+    "postinstall": "sapdon lib"
+  }
+}
+```
+
+`npm i` 会触发 `postinstall`，将 `prod/` 下的库复制到 `node_modules/@sapdon/`：
+
+| 源路径 | 目标路径 |
+|--------|----------|
+| `prod/core/` | `node_modules/@sapdon/core/` |
+| `prod/cli/` | `node_modules/@sapdon/cli/` |
+| `prod/oc/` | `node_modules/@sapdon/runtime/` |
+
+### 方式二：手动执行 `sapdon lib`
+
+```bash
+sapdon lib
+```
+
+效果相同，适合在 `npm i` 之后快速刷新库。
+
+### 然后编译项目
+
+```bash
+sapdon compile       # 仅构建，不启动 HMR
+# 或
+npm run build        # 构建 + 启动开发服务器（HMR）
+```
+
+---
+
+## 5. 完整开发循环
+
+当修改框架源码时，完整的开发和验证流程如下：
+
+```
+1. 修改 src/ 下的源码
+2. npm run build              # 重建 prod/
+3. 进入示例项目目录
+4. npm i                      # 触发 postinstall → sapdon lib，同步新库
+   # 或：sapdon lib            # 手动同步
+5. sapdon compile             # 验证构建结果
+6. 确认无误后提交 PR
+```
+
+---
+
+## 6. 常见坑点
+
+### 6.1 修改了 prod/ 但项目没生效
+
+`prod/` 是构建产物，手动修改会被下次 `npm run build` 覆盖。务必回到 `src/` 修改，然后重建。
+
+### 6.2 手动修改了 node_modules/@sapdon/*
+
+`node_modules/@sapdon/*` 是 `sapdon lib` 的输出，运行 `npm i` 或 `sapdon lib` 会覆盖所有手动修改。
+
+### 6.3 编译后服务器不退出
+
+`sapdon compile` 默认构建完成后自动退出。如果服务器一直占端口，检查 `build.config` 中是否设置了 `buildOptions.keepServer: true`。
+
+### 6.4 新建项目后忘记同步库
+
+使用 `sapdon create` 创建新项目后，`postinstall` 会自动执行 `sapdon lib`。如果手动创建项目或删除了 `node_modules`，需要重新 `npm i` 或手动运行 `sapdon lib`。
+
+### 6.5 manifest.json 不会随 dependencies 变化重新生成
+
+`src/cli/build.js` 中 manifest 只在**不存在时**才生成（`if (pathNotExist(manifestPath))`），目的是保留 uuid。因此修改 `build.config` 里的 `@minecraft/server` 版本后，旧 manifest 会被保留、新版本不生效。
+
+**解决**：手动删除 `dev/<name>_BP/manifest.json` 后重新 `sapdon compile`。删除 manifest 不影响 uuid（uuid 缓存在 `dev/.sapdon` 等目录，由 `loadOrCreateUuids` 复用）。
+
+### 6.6 方块脚本事件不存在（blockTick / blockUpdate）与自定义组件注册时机
+
+`world.afterEvents.blockTick` 与 `world.afterEvents.blockUpdate` **在任何版本都不存在**（包括 @minecraft/server 1.19.0）。调用会报 `cannot read property 'subscribe' of undefined`。
+
+**正确做法**：使用**自定义组件**（custom components）：
+- 方块 JSON 加扁平化自定义组件（V2，format_version ≥ 1.21.90）：`"sapdon:xxx_tick": {}`
+- 脚本在 `system.beforeEvents.startup` 注册（需 **@minecraft/server ≥ 2.0.0**）：
+  ```js
+  import { system } from "@minecraft/server";
+  system.beforeEvents.startup.subscribe((init) => {
+      init.blockComponentRegistry.registerCustomComponent('sapdon:xxx_tick', { onTick, onPlayerInteract, ... });
+  });
+  ```
+- `onTick` 由 `minecraft:tick` 组件驱动（两者共存），`onPlayerInteract` 替代 `world.afterEvents.itemUseOn`
+
+**注册时机是关键**：`startup`（2.0.0+）在方块 JSON 被加载/校验**之前**触发，此时注册自定义组件才能让 Schema 识别。用 `world.beforeEvents.worldInitialize`（1.x 时代的入口）注册会在方块 JSON 校验之后，报 `this component was found in the input, but is not present in the Schema`。
+
+**版本对应关系**（@minecraft/server → Minecraft 稳定版）：`2.0.0`→1.21.90/1.21.100，`2.6.0`→1.26.20，`2.8.0`→1.26.30，`2.9.0`→1.26.40。声明版本≤游戏支持的版本即可。
+
+### 6.7 build.config 带 UTF-8 BOM 导致 JSON 解析失败
+
+如果 `build.config` 被以带 BOM 的 UTF-8 保存（如某些编辑器/命令输出），`JSON.parse` 会报 `Unexpected token ''`。
+
+**解决**：字节级剥离 BOM（重新保存为无 BOM 的 UTF-8）。注意 `ConvertTo-Json | Out-File` 或部分重定向写法会引入 BOM；编辑此类配置文件时用无 BOM 编码保存。
+
+---
+
+## 7. 实战案例
+
+### 案例 1：修复方块 JSON 报错（Minecraft 1.26.20+）
+
+**问题**：Minecraft 从 format version 1.26.20 起，`minecraft:material_instances` 的 `ambient_occlusion` 不接受布尔值，必须是 0.0–10.0 浮点数。
+
+**修复位置**：`src/cli/load.ts`（方块 JSON 生成逻辑）。
+
+**修复前**：
+```ts
+ambient_occlusion: this.options.ambient_occlusion ?? true
+// 生成: "ambient_occlusion": true  ← Minecraft 1.26.20+ 报错
+```
+
+**修复后**：
+```ts
+ambient_occlusion: "number" == typeof i ? i : !1 === i ? 0 : 1
+// 生成: "ambient_occlusion": 0  ← 合法浮点数
+```
+
+### 案例 2：新增 keepServer 配置项
+
+**需求**：`sapdon compile` 构建完成后 dev server 不退出，一直占端口 49037。需要加开关控制是否常驻。
+
+**修改文件**：
+- `src/cli/meta/buildConfig.ts`：在 `BuildOptions` 中新增 `keepServer?: boolean` 字段。
+- `src/cli/build.js`：在 `buildProject()` 末尾添加自动退出逻辑，默认 `keepServer` 为 false 时 `process.exit(0)`。
+- `src/templates/js_sapdon/build.config` 和 `src/templates/ts_sapdon/build.config`：在模板中新增 `keepServer` 字段及注释。
+
+**使用方式**：
+```json
+{
+  "buildOptions": {
+    "keepServer": false,  // 默认 false，构建完成后自动退出；true 保持服务器常开（配合 useHMR）
+    "useHMR": true
+  }
+}
+```
+
+### 案例 3：修复 keepServer 自动退出导致脚本未打包
+
+**问题**：`sapdon compile` 加入 `keepServer: false` 自动退出后，`dev/<name>_BP/scripts/index.js` 经常缺失或内容为旧版本。
+
+**根因**：`src/cli/build.js` 的 `bundleScripts()` 调用异步的 `scriptBundler[elementType](...)` 时**没有 `await`**。之前服务器一直常驻（不退出），异步打包有足够时间完成，问题被掩盖；开启自动退出后，`process.exit(0)` 在异步 rollup 写入完成前就终止了进程，导致打包文件未写入。
+
+**修复**：在 `bundleScripts()` 中 `await` 异步调用，并提前 `fs.mkdirSync` 创建输出目录（rollup 不会自动创建父目录）：
+
+```js
+async function bundleScripts(useJs=false) {
+    const elementType = useJs ? 'js' : 'ts'
+    const projectPath = getProjectPath()
+    const buildConfig = getBuildConfig()
+    const { scriptEntry, scriptOutput, buildMode } = buildConfig.buildOptions
+    const targetPath = path.join(getBuildDirBp(), scriptOutput)
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true })
+    await scriptBundler[elementType](   // ← 必须 await，否则进程退出导致打包中断
+        path.join(projectPath, scriptEntry),
+        targetPath,
+        buildMode === 'dev' ? true : false
+    )
+}
+```
+
+**排查经验**：当框架新增 `process.exit(0)` 类逻辑时，要检查所有异步操作是否都被 `await`。现象是"同步创建的目录存在，但异步写入的文件缺失"。
+
+### 案例 4：数字电路方块报 `subscribe of undefined` / `not present in the Schema` → 自定义组件 + @minecraft/server 2.x
+
+**问题**：`examples/digitCircuit` 的 `scripts/index.js` 中 `world.afterEvents.blockTick.subscribe(...)` 报 `TypeError: cannot read property 'subscribe' of undefined`；改用 `world.beforeEvents.worldInitialize` 注册自定义组件后又报 `sapdon:wire_tick: this component was found in the input, but is not present in the Schema`。
+
+**根因（三层）**：
+1. **API 版本被 manifest 门控**：`build.config` 里声明 `@minecraft/server: 1.8.0`，Bedrock 运行时只暴露该版本的 API 表面。`blockTick`/`blockUpdate` 即使在新版本也不存在（1.19.0 的 `.d.ts` 中确认无此事件），但 `registerCustomComponent` 需要 ≥1.9.0。
+2. **事件选错**：正确的 tick 机制是自定义组件的 `onTick`，而非 afterEvents。
+3. **注册入口太晚**：`world.beforeEvents.worldInitialize` 在方块 JSON 校验之后触发，Schema 不认自定义组件。必须用 **`system.beforeEvents.startup`（@minecraft/server ≥ 2.0.0）**，它在方块 JSON 加载前触发。
+
+**修改文件**：
+- `examples/digitCircuit/build.config`：`@minecraft/server` `1.8.0` → `2.6.0`（对应游戏 1.26.20），并**删除旧 manifest** 强制重新生成（见 6.5）。同时把 `package.json` devDependency 同步为 `2.6.0`（精确版本，保证类型与运行时一致）。
+- `lib/wire.js`、`main.mjs`：给方块加 `BlockComponent.setCustomComponents(["sapdon:wire_tick"])` / `["sapdon:gate_tick"]`，生成扁平化自定义组件 JSON：
+  ```json
+  "components": { "sapdon:wire_tick": {}, "minecraft:tick": { "interval_range": [5, 10], "looping": true } }
+  ```
+- `scripts/index.js`：在 `system.beforeEvents.startup` 注册：
+  ```js
+  import { Direction, system } from "@minecraft/server";
+  system.beforeEvents.startup.subscribe((init) => {
+      init.blockComponentRegistry.registerCustomComponent("sapdon:wire_tick", {
+          onPlayerInteract(event) { /* 右键设信号 15 */ },
+          onTick(event) { /* 传播信号 */ }
+      });
+      init.blockComponentRegistry.registerCustomComponent("sapdon:gate_tick", {
+          onTick(event) { /* 重算 AND/OR/NOT */ }
+      });
+  });
+  ```
+
+**要点**：
+- 扁平化自定义组件（`"id": {}` 直接写在 `components`）是 format_version 1.21.90+ 的 V2 规范，与框架 `setCustomComponents` 的输出一致，`minecraft:custom_components` 数组写法已废弃。
+- 注册入口用 `system.beforeEvents.startup`（`StartupEvent.blockComponentRegistry`），与 `src/oc/builtin/index.ts` 的 `registerBuiltinComponents()` 一致；`src/cli/load.js` 自动生成的注册模板也用的是 startup，版本升级后该模板可直接使用。
+- `onPlayerInteract` 替代 `world.afterEvents.itemUseOn`（右键交互即触发，无需手持特定物品）。
+- 验证手段：检查生成的 `dev/<name>_BP/manifest.json` 版本号、方块 JSON 的 `components` 里是否含自定义组件、打包后的 `scripts/index.js` 是否含 `system.beforeEvents.startup` 与 `registerCustomComponent`。

package/doc/guidebook.md

@@ -0,0 +1,294 @@
+# SapdonGuideBook —— 帕秋莉式手册框架类
+
+`SapdonGuideBook` 是 Sapdon 提供的**帕秋莉式手册（Guidebook）**框架类。它让你用**纯数据声明**的方式，快速做出一本"分类索引 → 词条列表 → 内容页"的三层手册，并内置多种页类型、分页与导航。
+
+- **三层结构**：`INDEX`（分类索引）→ `CAT`（词条列表）→ `ENT`（词条内容页）。
+- **浏览器式导航**：每屏固定 `prev / home / next`，`home` 随时回首页。
+- **多种页类型**：`text` / `crafting` / `spotlight` / `image`。
+- **自动分页**：正文超过一屏自动翻页；分类词条超过 8 条自动分页。
+- **路由驱动**：运行时通过 Server Form 的 `body` 路径 + 按钮槽位显隐，无需每个页面单独写路由。
+
+> 示例见 `examples/guidebook_demo`（打开游戏手持木棍右键即可看到成品）。
+
+---
+
+## 1. 引入
+
+```ts
+import { SapdonGuideBook } from '@sapdon/core'
+import { registry } from '@sapdon/core'
+```
+
+配套类型：
+```ts
+import type { GuideBookCategory, GuideBookChapter, GuideBookPageType } from '@sapdon/core'
+```
+
+---
+
+## 2. 快速开始
+
+在项目的 `main.ts`（框架构建入口）里：
+
+```ts
+import { SapdonGuideBook, registry } from '@sapdon/core'
+
+const book = new SapdonGuideBook('mymod:book', [320, 207], 'textures/ui/book_back')
+
+book.build([
+    {
+        id: 'intro', title: '介绍', icon: 'textures/items/book_writable',
+        introLines: ['欢迎使用这本手册。', '它由 SapdonGuideBook 构建。'],
+        chapters: [
+            { name: '这是什么', icon: 'textures/items/book_writable', lines: ['这是一本帕秋莉式手册。', '分三层：索引→列表→内容。'] },
+            { name: '如何打开', icon: 'textures/items/paper', lines: ['手持木棍右键打开本手册。'] },
+        ],
+    },
+])
+
+registry.submit()
+```
+
+### 构造函数签名
+
+```ts
+new SapdonGuideBook(
+    identifier: string,                          // "namespace:name"，如 "mymod:book"
+    size: [number, number] = [320, 207],         // 手册画布尺寸
+    background: string = 'textures/ui/book_back' // 背景贴图
+)
+```
+
+### 常用方法
+
+| 方法 | 说明 |
+|---|---|
+| `.build(categories: GuideBookCategory[])` | 传入分类数据，生成全部页面；返回 `this` |
+| `.enableDebug()` | 开启调试（显示 `#form_text` 当前值 / 格子描边） |
+| `.getSystem()` | 返回内部 `UISystem` |
+
+调用链结束前记得 `registry.submit()`，把注册的 UI 数据提交给构建工具生成 `book.json`。
+
+---
+
+## 3. 数据结构
+
+### `GuideBookCategory`（分类）
+
+```ts
+interface GuideBookCategory {
+    id: string            // 路由 id（英文，如 "intro"），唯一
+    title: string         // 中文标题（索引卡名称 / 左页标题）
+    icon: string          // 索引卡图标贴图路径
+    introLines: string[]  // 分类简介（左半页逐行渲染）
+    chapters: GuideBookChapter[]  // 词条列表
+}
+```
+
+### `GuideBookChapter`（词条）
+
+```ts
+interface GuideBookChapter {
+    name: string          // 词条名（列表行 / 内容页标题）
+    icon: string          // 列表行图标
+    lines: string[]       // 正文（text 页逐行渲染）
+    pageType?: 'text' | 'crafting' | 'spotlight' | 'image'  // 默认 text
+    craft?: { grid: string[]; output: string }  // crafting 页
+    spotlight?: { icon: string; desc: string }  // spotlight 页
+    image?: { texture: string; caption: string } // image 页
+}
+```
+
+> ⚠️ 词条名 **不要以 `#` 开头**（如 `#foo 门控`）。Bedrock 会把以 `#` 开头的文本当作绑定，渲染成空。需要表现 `#` 时放在句子中间或写成 `foo 门控`。
+
+---
+
+## 4. 页类型（`pageType`）
+
+| `pageType` | 说明 | 相关字段 |
+|---|---|---|
+| `text`（默认） | 逐行渲染正文，支持分页 | `lines` |
+| `crafting` | 3×3 合成台 + 箭头 + 单个产物格 | `craft.grid`（9 项，空位 `''`）+ `craft.output` |
+| `spotlight` | 大图标 + 描述 | `spotlight.icon` + `spotlight.desc`（含 `\n` 会多行） |
+| `image` | 整页图 + 说明 | `image.texture` + `image.caption` |
+
+`crafting` 示例：
+
+```ts
+{
+    name: '合成示例', icon: 'textures/items/iron_ingot', pageType: 'crafting',
+    craft: {
+        grid: ['textures/items/iron_ingot','textures/items/iron_ingot','textures/items/iron_ingot',
+               'textures/items/iron_ingot','','textures/items/iron_ingot',
+               'textures/items/iron_ingot','','textures/items/iron_ingot'],
+        output: 'textures/items/iron_leggings',
+    },
+    lines: ['铁锭 → 铁护腿'],
+}
+```
+
+---
+
+## 5. 路由协议（运行时）
+
+手册内容由**固定布局 + 门控**驱动：布局容器按 `body` 路径显隐，按钮按 `form_button_text` 精确显隐。具体由项目的 `scripts/index.ts` 用 `ActionFormData` 发射。
+
+- **`title`**：固定为 `sapdon_ui:<name>`（如 `sapdon_ui:book`）。
+- **`body`（路径）**：
+  - `"INDEX"` → 分类索引页
+  - `"CAT:<id>|p<N>"` → 分类页（`N` 为分类页码，`p0` 左简介右列表）
+  - `"ENT:<id>:<gi>|p<N>"` → 词条内容页（`gi` 为词条序号，`N` 为内容页码）
+
+### 按钮槽位（顺序固定）
+
+| 页面 | 槽位 |
+|---|---|
+| INDEX | `[no_prev, no_home, no_next, idx0..3]`（三导航全隐藏） |
+| CAT | `[prev\|no_prev, home, next\|no_next, <id>_e<num>...]` |
+| ENT | `[prev, home, next\|no_next]` |
+
+占位键 `no_prev / no_home / no_next` 不代表任何注册按钮，从而让对应导航按钮**隐藏**。
+
+### 分页规则
+
+- **CAT 列表**：每列最多 8 行。`p0` 右列 8 行；`p1+` 左 8 + 右 8（=16 行/页）。
+- **ENT 正文（text）**：左右半页各最多 5 行，先填左半页、超出再填右半页；**整体超过 10 行才分页**。
+
+运行时脚本里需要维护两个与 `main.ts` 数据对齐的量：
+
+```ts
+// scripts/index.ts
+const CATS = ["intro", "pages", "routing", "controls"];                 // 与 main.ts 分类 id 对齐（含顺序）
+const CAT_CHAPTERS: Record<string, number> = { intro: 4, pages: 6, routing: 6, controls: 6 }; // 每分类词条数
+const ENT_PAGES: Record<string, number> = { pages_e4: 2 };              // 需要多页的 text 词条 → 页数(ceil(lines/10))
+```
+
+> 若某 text 词条行数超过 10，`main.ts` 会用 `ENT_PAGES` 里的页数来让 next/prev 生效。忘加会导致分页无法翻动。
+
+---
+
+## 6. 手写运行时路由（`scripts/index.ts` 参考）
+
+项目里还需一个"脚本入口"（build.config 的 `scriptEntry`），示例为 `scripts/index.ts`，用木棍右键打开手册：
+
+```ts
+import { world, Player } from "@minecraft/server";
+import { ActionFormData } from "@minecraft/server-ui";
+
+const CATS = ["intro", "pages", "routing", "controls"];
+const CAT_CHAPTERS = { intro: 4, pages: 6, routing: 6, controls: 6 };
+const ENT_PAGES = { pages_e4: 2 };
+const TITLE = "sapdon_ui:book";
+const NO_PREV = "no_prev", NO_HOME = "no_home", NO_NEXT = "no_next";
+
+function openIndex(p: Player): void {
+    const f = new ActionFormData().title(TITLE).body("INDEX");
+    f.button(NO_PREV); f.button(NO_HOME); f.button(NO_NEXT);
+    CATS.forEach((_, i) => f.button(`idx${i}`));
+    f.show(p).then((r) => {
+        if (r.canceled) return;
+        const s = r.selection!;
+        if (s >= 3 && s - 3 < CATS.length) openCat(p, CATS[s - 3], 0);
+        else openIndex(p);
+    });
+}
+
+function openCat(p: Player, id: string, page: number): void {
+    const total = CAT_CHAPTERS[id] ?? 0;
+    const start = page === 0 ? 0 : 8 + (page - 1) * 16;
+    const end = Math.min(start + (page === 0 ? 8 : 16), total);
+    const f = new ActionFormData().title(TITLE).body(`CAT:${id}|p${page}`);
+    f.button(page > 0 ? "prev_button" : NO_PREV);
+    f.button("home_button");
+    f.button(end < total ? "next_button" : NO_NEXT);
+    for (let i = start; i < end; i++) f.button(`${id}_e${i}`);
+    f.show(p).then((r) => {
+        if (r.canceled) return;
+        const s = r.selection!;
+        if (s === 0 && page > 0) openCat(p, id, page - 1);
+        else if (s === 1) openIndex(p);
+        else if (s === 2 && end < total) openCat(p, id, page + 1);
+        else if (s >= 3) { const gi = start + (s - 3); if (gi < total) openEnt(p, id, gi, page, 0); }
+    });
+}
+
+function openEnt(p: Player, id: string, gi: number, fromPage: number, ep: number): void {
+    const pc = ENT_PAGES[`${id}_e${gi}`] ?? 1;
+    const f = new ActionFormData().title(TITLE).body(`ENT:${id}:${gi}|p${ep}`);
+    f.button("prev_button"); f.button("home_button");
+    f.button(ep < pc - 1 ? "next_button" : NO_NEXT);
+    f.show(p).then((r) => {
+        if (r.canceled) return;
+        const s = r.selection!;
+        if (s === 0) ep > 0 ? openEnt(p, id, gi, fromPage, ep - 1) : openCat(p, id, fromPage);
+        else if (s === 1) openIndex(p);
+        else if (s === 2 && ep < pc - 1) openEnt(p, id, gi, fromPage, ep + 1);
+    });
+}
+
+world.afterEvents.itemUse.subscribe((e) => {
+    if (e.itemStack.typeId === "minecraft:stick" && e.source.typeId === "minecraft:player")
+        openIndex(e.source as Player);
+});
+```
+
+---
+
+## 7. 完整教程（从零做一个手册）
+
+**步骤 1：创建项目**
+```bash
+sapdon create my_guide
+cd my_guide
+```
+
+**步骤 2：在 `main.ts` 里声明手册**
+```ts
+import { SapdonGuideBook, registry } from '@sapdon/core'
+
+const book = new SapdonGuideBook('my_guide:book', [320, 207])
+
+book.build([
+    {
+        id: 'start', title: '开始', icon: 'textures/items/book_writable',
+        introLines: ['我的第一本手册。'],
+        chapters: [
+            { name: '序言', icon: 'textures/items/book_writable', lines: ['欢迎使用 SapdonGuideBook。'] },
+            { name: '合成演示', icon: 'textures/items/iron_ingot', pageType: 'crafting',
+              craft: { grid: ['textures/items/iron_ingot','','','','','','','',''], output: 'textures/items/iron_ingot' },
+              lines: ['一格铁锭 → 输出铁锭。'] },
+        ],
+    },
+])
+
+registry.submit()
+```
+
+**步骤 3：写运行时路由**（见第 6 节 `scripts/index.ts`），并把 `CATS` / `CAT_CHAPTERS` / `ENT_PAGES` 对齐到你的分类与词条数。
+
+**步骤 4：构建 & 进游戏**
+```bash
+sapdon build ./
+```
+进入游戏手持**木棍**右键即可打开手册。
+
+**步骤 5（可选）：`build.config` 配置**
+```json
+{
+  "buildOptions": {
+    "buildEntry": "main.ts",
+    "scriptEntry": "scripts/index.ts",
+    "scriptOutput": "scripts/index.js",
+    "buildMode": "dev"
+  }
+}
+```
+
+---
+
+## 8. 常见问题
+
+- **词条文字为空 / 显示异常**：词条名或文案以 `#` 开头会被当作绑定。去掉开头的 `#`。
+- **合成页输出是品红/黑格**：`craft.output` 引用了一个不存在的贴图。换成有效的（如 `textures/items/iron_leggings`）。
+- **文本词条点 next 翻不动**：`ENT_PAGES` 里没给它配页数。`ENT_PAGES[`${catId}_e${gi}`] = Math.ceil(lines.length / 10)`。
+- **想显示字面 `#`**：不要放在字符串开头，如 `form_text 门控`。

package/doc/hello_sapdon/hello_sapdon.md

@@ -106,7 +106,7 @@ hello_sapdon/
   ]
 }
 ```
-- **buildMode**：构建模式。设置为 `"development"` 时，构建程序将根据 `main.mjs` 中的内容构建 Addon 包，并将输出到 `buildDir` 指定的文件夹中；设置为 `"debug"` 时，仅将 `dev` 文件夹的内容输出到指定路径。
+- **buildMode**：构建模式。`"dev"`（默认）执行 `main.mjs` 生成所有 JSON；`"prod"` 生成 JSON 并压缩脚本；`"debug"` 跳过代码执行，仅将 `dev/` 输出到游戏目录。
 - **buildEntry**：构建入口文件的路径，即您编写模组内容的文件。
 - **scriptEntry**：脚本入口文件的路径。
 - **buildDir**：构建输出文件夹的路径，构建好的 Addon 包将输出到此文件夹。
@@ -118,9 +118,9 @@ hello_sapdon/
 1. 打开 `main.mjs` 文件。
 2. 写入以下内容以创建一个基础物品：
    ```javascript
-   import { ItemAPI } from "../src/core";
+   import { ItemAPI, ItemCategory } from "../src/core";
 
-   ItemAPI.createItem("hello_sapdon:my_item", "items", "masterball");
+   ItemAPI.createItem("hello_sapdon:my_item", ItemCategory.Items, "masterball");
    ```
    这段代码将创建一个名为 `my_item` 的物品，其命名空间为 `hello_sapdon`，类型为 `items`，并使用 `masterball` 作为图标。