@bepack/cli 0.1.0-beta.0 → 0.1.0-beta.2

package/reference.md

@@ -81,6 +81,16 @@ export default defineConfig({
 });
 ```
 
+#### bepack.config.ts 支持的语法范围
+
+`.ts` 配置文件通过 Node 原生 type-stripping 加载，**只支持"可擦除"的 TypeScript 语法**：
+
+- ✅ `import type`、类型标注、`interface` / `type`、`satisfies`、as 断言
+- ✅ 带类型的箭头函数参数（如 `(ctx: { cwd: string }) => ...`）
+- ❌ 运行时产生代码的 TS 语法：`enum`（建议用 `as const` 对象）、带代码的 `namespace`、构造参数属性、legacy decorators
+
+复杂 config（或依赖运行时逻辑的配置）建议把逻辑抽到独立的 `.mjs`/`.js` 模块再在 config 里 import，或直接使用 `bepack.config.mjs` / `bepack.config.js`。
+
 生成的包类型可通过以下方式使用：
 
 ```json
@@ -121,7 +131,15 @@ type UserConfig = {
             /** BP 编译配置（入口、TypeScript 检查、Rolldown 选项）。 */
             compile?: {
                 entry: string;
+                /**
+                 * 标识符引用替换（条件编译，推荐）。
+                 * 值为 JavaScript 表达式字符串（如 `{ __TARGET__: JSON.stringify("server") }`）。
+                 * 只替换**表达式位置的标识符引用**——`declare` 类型声明、对象键、字符串字面量、注释均不受影响。
+                 * 与顶层 `replace` 并存；同一 key 不能同时配在两者中。
+                 */
+                define?: Record<string, string>;
                 tsconfig?: string;
+                /** 打包前是否运行 tsc 类型检查。默认 true（即默认会跑）。 */
                 typecheck?: boolean;
                 preserveModules?: boolean;
                 external?: (string | RegExp)[];
@@ -134,10 +152,29 @@ type UserConfig = {
                 };
                 /** 编译脚本输出目录，相对于 BP root。默认 "scripts"。 */
                 scriptOutputDir?: string;
+                /**
+                 * 额外的 Rolldown 选项（对象），或自定义函数 (options, context) => options。
+                 * 在 BePack 生成的选项之上增量合并；input 与输出位置字段由 BePack 管理。
+                 */
+                rolldown?: RolldownOptions | RolldownCustomizeFunction;
+                /** Rolldown 配置文件路径（相对项目根或绝对路径），支持 .ts/.mts/.js/.mjs。 */
+                rolldownConfig?: string;
             };
             /** 所有 BP 依赖都在此声明——包括清单依赖和纯代码依赖。 */
             dependencies?: Record<string, "stable" | "beta" | "preview" | string>;
-            achievement?: boolean;
+            /**
+             * manifest 生成策略。
+             * - `merge: "preserve"`（默认）：增量合并，保留用户手写字段。
+             * - `merge: "clean"`：从配置全量重建，非 managed 条目丢弃，改用 `extra*` 字段显式声明。
+             * - `minEngineVersion`：clean 模式下的 `header.min_engine_version`（format 2 自动转数组）。
+             */
+            manifest?: {
+                merge?: "preserve" | "clean";
+                minEngineVersion?: string;
+                extraDependencies?: Record<string, unknown>[];
+                extraModules?: Record<string, unknown>[];
+                extraHeader?: Record<string, unknown>;
+            };
             /** 额外的打包/复制文件列表（在默认 include 基础上追加）。 */
             include?: string[];
         };
@@ -147,6 +184,16 @@ type UserConfig = {
             uuid: string;
             moduleUuid: string;
             pbr?: boolean;
+            /** 资源包可应用范围，写入 manifest header 的 `pack_scope`。默认 "any"。 */
+            packScope?: "world" | "global" | "any";
+            /** manifest 生成策略，与 bp 同构。 */
+            manifest?: {
+                merge?: "preserve" | "clean";
+                minEngineVersion?: string;
+                extraDependencies?: Record<string, unknown>[];
+                extraModules?: Record<string, unknown>[];
+                extraHeader?: Record<string, unknown>;
+            };
             /** 额外的打包/复制文件列表。 */
             include?: string[];
         };
@@ -174,6 +221,11 @@ type UserConfig = {
                 name?: string | { bp?: string; rp?: string };
             }
         >;
+        /**
+         * 复制到开发目录时也生成 __brarchive 归档，方便实机验证"打包后的形态"。
+         * 默认关闭；要求与 pack.optimize 相同的 min_engine_version >= 1.26.40。
+         */
+        optimize?: boolean | PackOptimizeOptions;
     };
 
     dev?: {
@@ -187,6 +239,24 @@ type UserConfig = {
     pack?: {
         name?: string;
         outDir?: string;
+        /**
+         * 把包内散文件打成 __brarchive 归档（Minecraft 官方 pack optimizer 的行为）。
+         * 默认关闭。开启后 BePack 会往产物 manifest 写入
+         * header.pack_optimization_version = "0.1.0"（这是让引擎读归档的开关）。
+         * 只影响 pack 产物；复制到开发目录默认不优化，可用 copy.optimize 开启。
+         */
+        optimize?: boolean | {
+            /** 额外保留"散文件 + 归档存根"的目录（默认按包类型内置列表）。传 false 表示全部只进归档。 */
+            keepLoose?: string[] | false;
+            /** 这些目录完全不归档，只留散文件。默认无。 */
+            exclude?: string[];
+            /** 是否压缩 JSON 条目。默认 true。 */
+            minifyJson?: boolean;
+            /** 产物 manifest 里 header.pack_optimization_version 的取值。默认 "0.1.0"。 */
+            packOptimizationVersion?: string;
+            /** 关闭 min_engine_version < 1.26.40 时的兼容性警告。默认 false（会警告但照常输出）。 */
+            allowUnsupportedTarget?: boolean;
+        };
     };
 };
 ```
@@ -363,6 +433,18 @@ export default defineConfig({
 4. 内置 `minecraft-vanilla-data` — `@minecraft/vanilla-data` 的 stable/preview 解析
 5. 内置 `exact-version` — 任意精确版本说明符
 
+### 依赖错误排查
+
+`UNSUPPORTED_DEPENDENCY` 报错会附带**当前可用的 catalog 包列表**与扩展指引：
+
+```txt
+[Error] foo-pkg is not a managed dependency.
+  → Managed packages: @minecraft/server, @minecraft/server-ui, ...
+  → Add a missing package to install.dependencyCatalog, or remove it from packs.bp.dependencies.
+```
+
+执行 `bepack config --summary`（或 `bepack config --json`）可查看当前生效的完整依赖目录（内置 + 插件 + 自定义 `install.dependencyCatalog`）与解析器注册顺序。
+
 ## 清单管理
 
 `bepack manifest` 和 `bepack install` 可以创建和修补清单。
@@ -401,7 +483,6 @@ BP 清单受控字段：
 - 脚本模块
 - BePack 管理的 `@minecraft/*` 依赖
 - BP/RP 相互依赖
-- `metadata.product_type`（仅在 `achievement: true` 时）
 
 RP 清单受控字段：
 
@@ -411,6 +492,7 @@ RP 清单受控字段：
 - `header.uuid`
 - `header.version`
 - `header.min_engine_version`
+- `header.pack_scope`（当 `packs.rp.packScope` 配置时）
 - 资源模块
 - RP/BP 相互依赖
 - `capabilities: ["pbr"]`（当 `pbr: true` 时）
@@ -419,11 +501,40 @@ RP 清单受控字段：
 
 当同时配置了 BP 和 RP 时，BePack 会维护它们 header UUID 之间的相互依赖。
 
-成就元数据：
+### manifest 生成策略
+
+`packs.bp.manifest` / `packs.rp.manifest` 控制清单如何与已有文件合并：
+
+| 条目来源 | `merge: "preserve"`（默认） | `merge: "clean"` |
+| -------- | --------------------------- | ---------------- |
+| `header.name` / `description` / `uuid` / `version` | config | config |
+| `header.min_engine_version` | 保留旧文件值 | config（缺省用默认值，可用 `minEngineVersion` 显式指定） |
+| managed 依赖 / module | 重建 | 重建 |
+| 非 managed 条目（手写依赖、额外 module、capabilities 等） | **保留** | **丢弃**，改用 `extra*` 字段显式声明 |
+| 其他 config 的残留（双配置交替构建） | 保留 → 污染 | **清除** |
+
+`clean` 模式下可用的补充字段：
+
+- `minEngineVersion`：写 `header.min_engine_version`。SemVer 字符串（如 `"1.21.80"`），format 2 自动转 `[1, 21, 80]`。
+- `extraDependencies`：原样追加到 `dependencies`（非 catalog 依赖）。
+- `extraModules`：原样追加到 `modules`（如自定义 script 模块）。
+- `extraHeader`：合并进 `header`（如 `pack_scope`）。
+
+推荐用法——双配置交替构建时，用 `clean` 的一侧从配置全量生成，杜绝另一侧 config 的残留：
+
+```ts
+// bepack.server.config.ts
+export default defineConfig({
+    packs: {
+        bp: {
+            root: "bp",
+            manifest: { merge: "clean", minEngineVersion: "1.21.80" },
+        },
+    },
+});
+```
 
-- `packs.bp.achievement: true` 添加 `metadata.product_type = "addon"`。
-- 每个受管理的 Script API 依赖必须使用 `stable` 说明符。
-- 如果在启用成就时使用了 `beta` 或 `preview` 依赖，BePack 会抛出 `ACHIEVEMENT_REQUIRES_STABLE_API`。
+client 侧保持默认 `preserve`（尊重手写 manifest），server 侧 `clean`（从配置全量生成），无需再写外部清理脚本。
 
 ## 构建
 
@@ -432,23 +543,28 @@ RP 清单受控字段：
 ```txt
 清单修补
 hooks.beforeBuild
-类型检查
+类型检查（tsc --noEmit，默认开启）
 Rolldown 构建
 hooks.afterBuild
 可选复制
 可选打包
 ```
 
+> **默认会运行 TypeScript 类型检查。** 只要配置了 `packs.bp.compile`，`bepack build` 与 `bepack dev` 都会在 Rolldown 打包**之前**执行 `tsc --noEmit`；检查失败会以 `TYPECHECK_FAILED` 终止本次构建，不会产出残缺脚本。跳过方式：CLI `--skip-typecheck`，或 `packs.bp.compile.typecheck: false`。注意类型检查与打包是两件独立的事——自定义 Rolldown 选项、替换 `rolldown` 配置都不会关闭它，要关只能显式配置。
+
 CLI 选项：
 
 - `--mode <value>`：执行模式，透传给 Hook 上下文（`HookContext.mode`）。不设则为 `undefined`。Hook 内自行判断是否执行特定逻辑。
+- `--rolldown-config <path>`：临时指定 Rolldown 配置文件，覆盖 `packs.bp.compile.rolldownConfig`（`bepack dev` 同样支持）。
+- `--optimize`：与 `--pack` / `--copy` 一起使用时，把产物（或开发目录）优化为 `__brarchive/` 归档（`--no-optimize` 可覆盖配置）。详见《打包》一节的 Pack 优化。
 
 类型检查行为：
 
-- 默认：系统 `tsc --noEmit`。
+- **默认：系统 `tsc --noEmit`（`packs.bp.compile.typecheck` 默认为 `true`）。** 只有显式设置 `typecheck: false` 或传 `--skip-typecheck` 才会跳过。
 - `build.useNpx: true` 或 `--use-npx`：`npx tsc --noEmit`。
 - `packs.bp.compile.cache`：增量编译缓存配置。`cache.dev`（默认 `true`）控制 dev 模式；`cache.build`（默认 `false`）控制 build 模式。`cache.file` 指定 `.tsbuildinfo` 路径。`bepack build --cache` / `--no-cache` 可覆盖 build 模式。`dev` 命令默认启用缓存。
 - 缺少 `tsconfig.json` 会提前失败，返回 `TYPECHECK_FAILED`。
+- 类型检查在 `hooks.beforeBuild` 之后、Rolldown 之前运行；`--dry-run` 会跳过它。
 
 Rolldown 行为：
 
@@ -459,12 +575,12 @@ Rolldown 行为：
 - `packs.bp.compile.scriptOutputDir` 控制编译脚本输出目录（相对于 BP root），默认 `"scripts"`。manifest 中的 script 模块 `entry` 路径也会随之更新为 `<scriptOutputDir>/<entry文件名>.js`。
 - 外部包来自 `packs.bp.compile.external`，默认情况下也来自受管理的依赖目录。
 - `packs.bp.compile.minify: true` 或 `--minify` 启用 Rolldown 代码压缩，输出更小的 JS 文件。
-- 字符串替换通过顶层 `replace` 配置：`replace.values` 支持字面量或接收已解析 config 的函数；`replace.builtins` 可开启 `**VERSION**`、`**NAME**`、`**UUID**`、`**DESCRIPTION**`。未配置替换时不会创建 replace plugin。`**DESCRIPTION**` 优先使用 `packs.bp.description`，再回退到根 `description`。
+- 字符串替换通过顶层 `replace` 配置：`replace.values` 支持字面量或接收已解析 config 的函数；`replace.builtins` 可开启 `**VERSION**`、`**NAME**`、`**UUID**`、`**DESCRIPTION**`。未配置替换时不会创建 replace plugin。所有替换 key 都按**字面精确匹配**（不做单词边界匹配），因此自定义值可以放心使用 `**自定义标记**` 这类被非单词字符包围的 token，例如 `replace.values: { "**AUTHOR**": "Your Name" }`。`**DESCRIPTION**` 优先使用 `packs.bp.description`，再回退到根 `description`。**feature flag / 条件编译请优先用 `packs.bp.compile.define`**（详见《构建注入与条件编译》），`replace` 保留给模板 token 等文本级替换。
 - 构建完成后显示输出文件的大小统计（单文件显示路径和体积，多文件显示总文件数和总体积）。
 
 > 注意：构建命令（`build` / `dev`）不再要求 BP 必须存在。如果项目只有 RP 或 BP 没有配置 `compile`，则跳过编译流程，只执行 manifest 修补和可选的文件复制/打包。
 
-`packs.bp.compile.externalDependencies` 默认为 `true`，因此内置的 `manifest: true` 受管理包（例如 `@minecraft/server`、`@minecraft/server-ui`、`@minecraft/server-net`）不会被内联打包。`manifest: false` 的包（例如 `@minecraft/vanilla-data`）可以被内联打包。设置 `externalDependencies` 为 `false` 可自定义，或通过 `packs.bp.compile.external` 添加额外条目。
+`manifest: true` 的受管理包（例如 `@minecraft/server`、`@minecraft/server-ui`、`@minecraft/server-net`）**始终**作为 external 写入 rolldown，不会被内联打包；`manifest: false` 的包（例如 `@minecraft/vanilla-data`）可以被打包进产物。需要额外的 external 时，通过 `packs.bp.compile.external` 追加字符串或正则。
 
 `build.timing: true` 或 `--timing` 可在构建时显示各步骤的耗时明细，便于排查性能瓶颈：
 
@@ -476,6 +592,182 @@ timing    rolldown        45 ms
 
 `--timing` 同样支持 `bepack dev` 命令。
 
+## 自定义 Rolldown 配置
+
+`packs.bp.compile` 覆盖了常见场景，Rolldown 的完整能力通过三个入口开放：
+
+- `packs.bp.compile.rolldown`：内联选项对象，或自定义函数；
+- `packs.bp.compile.rolldownConfig`：Rolldown 配置文件路径（相对项目根或绝对路径）；
+- CLI：`bepack build --rolldown-config <path>` / `bepack dev --rolldown-config <path>`，临时替换配置文件。
+
+> 自定义 Rolldown 配置**不会**关闭类型检查：`bepack build` / `bepack dev` 依然会先执行 `tsc --noEmit`（默认开启，详见《构建》一节）。
+
+### 对象形式
+
+```ts
+packs: {
+    bp: {
+        compile: {
+            entry: "src/main.ts",
+            rolldown: {
+                resolve: { alias: { "@lib": "./src/lib" } },
+                treeshake: { moduleSideEffects: false },
+                output: { sourcemap: true },
+            },
+        },
+    },
+}
+```
+
+### 函数形式
+
+函数接收当前已合并的选项与上下文，返回值再按同样的规则合并一次；返回空则不做改动：
+
+```ts
+packs: {
+    bp: {
+        compile: {
+            rolldown(options, context) {
+                if (context.command === "dev") return { output: { sourcemap: true } };
+                return {};
+            },
+        },
+    },
+}
+```
+
+上下文 `RolldownCustomizeContext` 字段：`command`（`"build"` / `"dev"`）、`mode`（CLI `--mode`）、`target`、`entry`、`outDir`、`outFile`、`preserveModules`，路径均为绝对路径。
+
+### 配置文件
+
+配置文件由 Rolldown 自带的加载器读取，因此 `.ts` / `.mts` / `.js` / `.mjs` 都支持，默认导出可以是选项对象、单元素数组或函数（与 `rolldown.config.ts` 用法一致）：
+
+```ts
+// rolldown.bp.config.ts
+import { defineConfig } from "rolldown";
+
+export default defineConfig({
+    resolve: { alias: { "@lib": "./src/lib" } },
+});
+```
+
+- 只支持**单个**配置：导出多元素数组会报 `CONFIG_INVALID`（BePack 每次只构建一个 BP）。
+- `.ts` 配置文件会先被 Rolldown 打包成 `rolldown.config.<hash>.js` 再导入，随后删除；`dev` watcher 已忽略该临时文件。
+- 优先级：`--rolldown-config` > `compile.rolldownConfig` > `compile.rolldown`。
+
+### 合并规则
+
+BePack 先生成基础选项，再把自定义选项合并上去：
+
+| 字段 | 规则 |
+| --- | --- |
+| `plugins` | 追加在 BePack 插件（replace / define）之后 |
+| `external` | 取并集（字符串去重，`RegExp` 原样保留） |
+| `transform`、`resolve`、`experimental`、`checks`、`optimization`、`watch`、`moduleTypes`、`output` | 一层深合并；其中 `transform.define` 按 key 合并，不会清掉 `compile.define` |
+| 其它字段 | 用户值直接覆盖 |
+
+函数返回值按同一规则合并——因此只能追加，不能移除 BePack 的插件或受管理的外部依赖。
+
+### 受保护字段
+
+以下字段由 BePack 管理，配成其它值会报 `CONFIG_INVALID`（manifest 的 script entry、复制、打包、dev 监听都依赖它们）：
+
+| 字段 | 替代方式 |
+| --- | --- |
+| `input` | `packs.bp.compile.entry` |
+| `output.file` / `output.dir` | `packs.bp.compile.scriptOutputDir` |
+| `output.preserveModules` / `output.preserveModulesRoot` | `packs.bp.compile.preserveModules` |
+| `output.entryFileNames` | manifest script entry 假定"每个源模块一个 `.js`" |
+| `output.format` | Script API 只支持 ESM |
+| `output` 数组（多输出） | 不支持，BePack 只写一个输出 |
+
+## 构建注入与条件编译
+
+BePack 提供两种编译期注入机制，**建议按用途选择**：
+
+| 对比 | `replace`（顶层） | `define`（`packs.bp.compile.define`） |
+| ---- | ---------------- | ------------------------------------- |
+| 替换目标 | 所有出现位置（声明、注释、字符串内也换） | **仅标识符引用**（表达式位置） |
+| `declare const __T__: ...` | 被破坏（`declare const "client"`） | **保留**（typecheck 正常） |
+| `if (__T__ === "server")` | 可折叠 | 可折叠 |
+| 典型用途 | 模板 token、历史兼容 | **feature flag / 条件编译（推荐）** |
+| 冲突规则 | — | 与 `replace.values` 同一 key 同时配置会报错 |
+
+### define 用法
+
+`define` 的值是 **JavaScript 表达式字符串**，写入前 BePack 会做语法校验并定位报错：
+
+```ts
+export default defineConfig({
+    packs: {
+        bp: {
+            compile: {
+                entry: "src/main.ts",
+                define: {
+                    __TARGET__: JSON.stringify("server"), // → '"server"'
+                    __FLAG__: "true",                     // → true
+                },
+            },
+        },
+    },
+});
+```
+
+`declare` 声明可以留在源码里，typecheck 与运行时都正常：
+
+```ts
+declare const __TARGET__: "server" | "client";
+
+if (__TARGET__ === "server") {
+    console.log("server-only path");
+}
+```
+
+编译产物只替换引用：对象键、字符串字面量、注释中的同名 token 均不受影响。
+
+### 双产物示例（一次构建产出 server / client 两份脚本）
+
+利用两套 config + 共享的 `declare` 声明：
+
+```ts
+// src/main.ts
+declare const __TARGET__: "server" | "client";
+export const target = __TARGET__;
+```
+
+```ts
+// bepack.server.config.ts
+export default defineConfig({
+    name: "my-addon-server",
+    packs: {
+        bp: {
+            root: "bp",
+            compile: { entry: "src/main.ts", define: { __TARGET__: JSON.stringify("server") } },
+        },
+    },
+});
+```
+
+```ts
+// bepack.client.config.ts —— 同上，仅 define 值改为 JSON.stringify("client")
+```
+
+```bash
+bepack build --config bepack.server.config.ts
+bepack build --config bepack.client.config.ts
+```
+
+## Tree-shaking 与产物裁剪
+
+BePack 默认 `preserveModules: true`，Rolldown 仍会做 tree-shaking：
+
+- **未引用的模块**（import 了但没有任何导出被使用）不会出现在输出目录。
+- **死代码导出**（同模块内未被引用的导出）被剔除。
+- **动态 `import()`** 会拆分为独立 chunk 输出（如 `dynamic.js`），并按需加载。
+- 结果：输出目录 = 仅存活模块 + 动态 import chunk。
+
+验证方法：构建后检查 `<packs.bp.root>/<scriptOutputDir>`（默认 `bp/scripts`）下的文件列表，对比源码模块数。
+
 ## 开发模式
 
 `bepack dev`：
@@ -483,6 +775,7 @@ timing    rolldown        45 ms
 - 在监视前先执行一次初始构建（manifest + 若有 compile 则编译）。
 - 支持 `--skip-typecheck` 跳过类型检查（与 `build` 命令一致）。
 - 支持 `--mode <value>`，用法与 `build` 命令相同，透传给 Hook 上下文。初始构建和后续增量重建均会传入该值。
+- 支持 `--optimize`：每次自动复制都生成 `__brarchive/` 归档（等价于 `copy.optimize: true`，`--no-optimize` 可覆盖配置）。
 - 默认监视的路径：
     - `packs.bp.compile.entry` 所在目录（仅在 BP 配置了 compile 时，TypeScript 源码变化 → 触发编译）
     - BP 的默认 include 列表 + `packs.bp.include` 中的文件/文件夹（不含 `scripts` 和 `manifest.json`）
@@ -516,6 +809,12 @@ export default defineConfig({
 
 **如果没有配置任何复制目标，`bepack copy` 会报错。** 复制前会验证目标目录是否存在，不存在则报错。
 
+CLI 选项：
+
+- `--target <target>`：指定复制目标。
+- `--all`：复制到所有目标。
+- `--optimize`：复制时生成 `__brarchive/` 归档（`--no-optimize` 覆盖配置），详见下文《复制时也做 Pack 优化》。
+
 ### 内置目标
 
 - `win`
@@ -610,7 +909,7 @@ copy: {
 ```
 scripts  manifest.json  animation_controllers  animations  biomes
 blocks  entities  functions  items  loot_tables  pack_icon.png
-recipes  spawn_rules  structures  texts  trading
+recipes  shapes  spawn_rules  structures  texts  trading
 feature_rules  features  worldgen
 ```
 
@@ -658,6 +957,25 @@ dev: {
 
 `build.copy` 和 `dev.copy` 默认为 `false`（不复制）。`true` 表示使用 `copy.defaultTarget`，字符串表示使用指定目标。
 
+### 复制时也做 Pack 优化
+
+复制到开发目录默认是"散文件"形态，与发布产物（可能带 `__brarchive/`）不同。为了让开发者能在实机里提前验证**打包后的形态**，可以单独开启 `copy.optimize`：
+
+```ts
+copy: {
+    defaultTarget: "minecraft",
+    optimize: true,          // 或与 pack.optimize 相同的选项对象
+},
+```
+
+```bash
+bepack copy --optimize               # 临时开启（--no-optimize 覆盖配置）
+bepack build --copy --optimize       # build 的 --optimize 同时作用于 pack 与 copy
+bepack dev --optimize                # dev 的每次自动复制也生成归档
+```
+
+行为与 `pack.optimize` 完全一致（同一套镜像规则、排除表、JSON 压缩、1.26.40 门槛），区别只是输出到开发目录而不是 `.mcpack`。默认不保留散文件，因此开发目录里的形态与发布产物一致；需要同时保留散文件时用 `optimize: { keepLooseFiles: true }`。
+
 ## 打包
 
 `bepack pack` 创建：
@@ -685,6 +1003,72 @@ pack: {
 
 打包输入配置必须显式指定，且输入路径必须存在。这可以防止意外打包猜测的默认目录。
 
+### Pack 优化（`__brarchive`）
+
+Minecraft 1.26.40 起官方提供 **Pack Optimization**：把包里的散文件装进 `__brarchive/` 归档，并对 JSON 做压缩。BePack 可以在打包时做同样的事：
+
+```ts
+pack: {
+    outDir: "dist",
+    optimize: true,               // 或传入下面的选项对象
+}
+```
+
+```bash
+bepack pack --optimize            # 临时开启（--no-optimize 可覆盖配置里的开启状态）
+bepack build --pack --optimize    # 构建后打包并优化
+```
+
+产物结构（只影响 `.mcpack` / `.mcaddon` 内部，磁盘上的包目录**不会被修改**）：
+
+```txt
+manifest.json                     # 包根散文件保持原样，并写入 pack_optimization_version
+functions/diag_fn.mcfunction      # 按路径引用的目录：散文件保留（归档里只登记文件名）
+texts/en_US.lang
+__brarchive/entities.brarchive    # 注册表型目录：完整内容进归档，散文件删除
+__brarchive/entities/sub.brarchive   # 每个目录一个归档，镜像目录树
+```
+
+规则：
+
+- **开关是产物 `manifest.json` 里的 `header.pack_optimization_version`**，BePack 默认写入 `"0.1.0"`。只有这个字段能让引擎从 `__brarchive/` 读取注册表；写成游戏版本号（如 `"1.26.40"`）无效。它只写进产物，磁盘上的 `manifest.json` 不受影响。
+- `header.min_engine_version` **不参与判断**（原版 `vanilla` 行为包是 `[1,13,0]` 且带归档）。低于 1.26.40 时只是打印一条警告：旧客户端没有归档支持，只能看到保留散文件的那部分。
+- 每个目录（递归）生成 `<包根>/__brarchive/<相对目录>.brarchive`，条目名是**裸文件名**（如 `entities.brarchive` 里是 `zombie.json`），按名称排序；文件名最多 247 字节。
+- 包根散文件（`manifest.json`、`pack_icon.png` 等）不归档；已存在的 `__brarchive/` 内容原样保留。
+- **按路径引用**的目录会把散文件留在原处，归档里只写一条 **0 字节存根**（登记文件名）——这是原版 `structures/**`、`sounds/**`、`texts` 的做法。默认列表：
+    - 行为包：`functions`、`loot_tables`、`structures`、`texts`
+    - 资源包：`font`、`materials`、`sounds`、`texts`、`textures`
+- 其余目录（`entities`、`items`、`blocks`、`recipes`、`shapes`、`spawn_rules`、`trading`、`models`、`ui`、`particles`、`render_controllers` 等）归档**完整内容并删除散文件**。
+- JSON 条目会被压缩（`{ "a": 1 }` → `{"a":1}`），非 JSON（`.lang`、二进制、`MCB`）原样存储；JSON 解析失败时也原样存储，不会损坏文件。
+
+想调整时用这些选项：
+
+| 选项 | 作用 |
+| --- | --- |
+| `keepLoose: ["blocks"]` | 额外把某些目录改成"散文件 + 存根" |
+| `keepLoose: false` | 不保留任何散文件（产物最小，全部只进归档） |
+| `exclude: ["blocks"]` | 这些目录完全不归档，只留散文件 |
+| `keepLooseFiles: true` | 归档 + 完整散文件都写（体积最大，兼容 1.26.40 之前的旧客户端） |
+| `minifyJson: false` | 不压缩 JSON 条目（排查问题用） |
+| `packOptimizationVersion: "0.2.0"` | 改用其它优化版本号 |
+
+**实机验证（1.26.40 客户端，内置 `@minecraft/server` 探针脚本）**：
+
+| 内容 | 存放方式 | 结果 |
+| --- | --- | --- |
+| `blocks/`、`items/`、`entities/`、`recipes/` | 归档完整内容、删除散文件 | ✅ `BlockTypes/ItemTypes/EntityTypes.get()` 与 `spawnEntity()` 全部通过；配方也从归档正常解析 |
+| `functions/`、`loot_tables/` | 散文件 + 归档存根 | ✅ `/function`、`/loot spawn … loot …` 均返回 success=1 |
+| `structures/` | 散文件 + 归档存根 | ⚠️ `/place structure` 在本机返回 success=0（原版对照名称带 `/` 需要加引号，未能取得正向对照），建议自行用结构方块验证 |
+| `texts/` | 散文件 + 归档存根 | ✅ 散文件 `.lang` 正常（中文客户端需自带 `zh_CN.lang`，否则显示 key） |
+
+> **`scripts/` 默认也会归档**（官方 `behavior_packs/editor` 就是这样，且实测脚本模块可从归档加载）；上面的探针为了确保一定输出，用的是 `keepLoose: ["scripts"]`。如果你的脚本在归档后不执行，加 `keepLoose: ["scripts"]` 即可。
+>
+> **注意模块 UUID 不能重复**：手写 `manifest.json` 里的 `data`/`resources` 模块 UUID 必须和 `packs.bp.moduleUuid`（脚本模块）不同，否则引擎会丢掉脚本模块且没有明显报错。
+
+> **兼容性**：能读 `__brarchive/` 的客户端才有完整内容；1.26.40 之前的客户端只能看到"保留散文件"的目录。设 `allowUnsupportedTarget: true` 可关闭 min_engine_version 警告。
+>
+> 同一套选项也适用于复制：见《复制》一节的[复制时也做 Pack 优化](#复制时也做-pack-优化)。
+
 ## 钩子
 
 支持的钩子：
@@ -742,6 +1126,22 @@ hooks: {
 
 未传入 `--mode` 时，`mode` 为 `undefined`，保持完全向后兼容。
 
+#### `--mode` 取值约定
+
+BePack 对 `mode` 的取值**不做语义判断**，以下只是社区推荐约定（可自定义）：
+
+| mode | 语义 |
+| ---- | ---- |
+| `development` | 开发构建（默认不传时的常见取值），跳过发布相关动作 |
+| `release` / `template` | 发布 / 模板构建，可跳过复制、跳过打包 |
+| 自定义任意字符串 | 由钩子内自行判断 |
+
+要点：
+
+- `mode` 透传给**同一命令的所有相关钩子**（如 `build` 的 `beforeBuild` / `afterBuild`；`dev` 的初始构建与增量重建）。
+- 判断用 `===` 精确匹配；未传 `--mode` 时 `mode === undefined`，可当作默认分支。
+- 不要依赖 `mode` 来区分命令——命令用 `ctx.command`（`"build"` / `"dev"` / ...）判断。
+
 ## 输出与错误
 
 常规模式下，CLI 输出使用彩色阶段标签和时间戳。
@@ -767,7 +1167,6 @@ UNSUPPORTED_DEPENDENCY
 DEPENDENCY_VERSION_INVALID
 DEPENDENCY_REQUIRES_INSTALL
 SAPI_VERSION_NOT_FOUND
-ACHIEVEMENT_REQUIRES_STABLE_API
 TYPECHECK_FAILED
 BUILD_FAILED
 COPY_TARGET_NOT_FOUND