@oj-module/cli 0.2.20 → 0.2.25

package/devkit/manual.md

@@ -39,6 +39,7 @@
 ├── tests/                 # 后端 BDD 测试（node:sqlite 内存库 + 真实迁移建表）
 ├── src/
 │   ├── tsconfig.json      # 后端 typecheck 工程（extends 上两者，exclude */web）
+│   ├── .ojm-builtin.json  # 框架自带方案名单（init 派生，可手改/删除；打包排除 + info 折叠，见 §11）
 │   ├── styles.css
 │   ├── _platform/         # 框架级：users 表 / rbac / 市场编排 / 生命周期
 │   │   ├── api/           #   + _shared/（respond、service/、site-facade）
@@ -74,7 +75,19 @@
 > **历史布局仍被识别**：`web/src/<name>`（uni-dev）与 `web/<name>`（框架根仓）照旧可用，
 > 只是 `ojm init` 不再产出。两套源码树**互斥**——同时存在时 `ojm` 直接报错，而不是静默选一个。
 
-登录账号 `admin / 123456`。端口：前端 devServer **5174**，oj 后端 **9778**
+登录账号：**账号名=内置角色名**一一对应，口令均 `123456`，且全部**免首登改密**（must_change=0，纯开发便利，勿用于生产）：
+
+| 账号 | 角色 | 能干什么 |
+|---|---|---|
+| `superadmin` | superadmin | 全部能力（含安全组设置、成员资格管理） |
+| `admin` | admin | 日常管理（不含 superadmin 专属项） |
+| `editor` | editor | 页面门编辑级 |
+| `viewer` | viewer | 页面门访客级 |
+
+> 旧脚手架库（admin 绑 superadmin / must_change=1）**无需手工迁移**：seed 每次启动幂等重放，
+> 自动收敛为账号名=角色名并清零 must_change（`DELETE` 旧绑定 + `UPDATE`，见 `_platform/api/seed.sql`）。
+
+端口：前端 devServer **5174**，oj 后端 **9778**
 （以工程根 `config.yaml` 的 `server.port` 为准）。
 
 ### 1.2 两个模块体系，同名不同物
@@ -93,6 +106,33 @@
 历史布局下两侧分居 `web/src/<模块>/` 与 `api/src/<模块>/`——**同一个名字、两个目录**，
 是布局迁移时最容易对不上的地方。
 
+#### manifest.yaml 与 solution.yaml：两种身份，别混淆
+
+工程里会出现两个名字里带 "manifest" 的文件，用途**完全不同**，混用会出构建/运行期怪问题：
+
+| 文件 | 层级 | 身份 | 谁读它 | 写什么 |
+|---|---|---|---|---|
+| `src/<模块>/api/manifest.yaml` | **模块级**（每个后端模块一份） | oj **原生七键**清单（`name`/`desc`/`version`/`tables`/…） | **oj 运行时**——按 `manifest.yaml` 枚举发现并校验 api 后端模块 | 模块名、版本、表清单（与 `schema.yaml` 双向一致，§1.5） |
+| `solution.yaml`（`src/<模块>/` 或工程根） | **方案级**（整个方案一份） | 方案包契约（身份 / 路由 / api 段 / web 段 / 权限 / …） | **`ojm build --bundle`**——打包入口与契约校验 | 方案名、版本、`api` 段（模块+前缀+tables+deps+anonymous）、`web` 段（entry/css/integrity）、`routes`、`health` |
+
+关键区别与红线：
+
+- **模块级 `manifest.yaml` 是 oj 发现 api 后端的唯一真源**：`ojm dev/build` 递归扫描
+  `src/<模块>/api/manifest.yaml` 认领后端模块；oj 启动也用它做强校验（`name ==` 目录名、版本同源）。
+  它**只能有 oj 原生七键**，写任何方案级字段（`routes` / `permissions` / …）都会被拒启。
+- **方案级契约以前也叫 `manifest.yaml`（工程根）**，但它会和上面的「oj 按 `manifest.yaml` 枚举 api 模块」
+  撞名：**工程根再放一份 `manifest.yaml` 当 bundle 契约，会被 oj 的搜索枚举误当成 api 模块**，污染后端发现。
+  所以解决方案统一改名为 **`solution.yaml`**，`ojm build --bundle` 优先认它（`manifest.yaml` 仅作旧方案回退）——
+  **后端按 `manifest.yaml` 枚举 api、打包按 `solution.yaml` 取契约**，两条枚举互不干扰。
+  **位置**：单模块方案推荐放 `src/<模块>/solution.yaml`（契约与所打包模块同位）；`ojm build --bundle`
+  也兼容工程根 `solution.yaml`，以及两处的 `manifest.yaml` 回退。**模块级契约只认 `src/<模块>/` 根下、
+  绝不进 `<模块>/api/`**——否则照样会和 oj 的 api 枚举撞车。
+- 进包后文件名固定回到 `manifest.yaml`（安装侧只认这个名字）：`ojm build --bundle` 把工程根或
+  `src/<模块>/` 下的 `solution.yaml`（或旧 `manifest.yaml`）拷贝进 tgz 内的 `<name>-<version>/manifest.yaml`，安装器/市场仍按老名字消费。
+
+> 一句话：**`manifest.yaml` 是给 oj 认模块用的（模块级、七键、oj 枚举）；`solution.yaml` 是给 `ojm build --bundle`
+> 打包用的（方案级、工程根）。两者文件名不同、层级不同、读者不同，别写错层。**
+
 ### 1.3 后端路由 = 目录镜像
 
 ```
@@ -1377,12 +1417,15 @@ useEffect(() => {
 pnpm dev               # 开发：devServer + oj 后端（src/<模块>/api 保存即热更）
 # 交互快捷键（仅 TTY 终端启用，类 Vite）：
 #   r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开    q  退出（oj 一并终止）
+# 提示行常驻终端最末行（滚动区），日志在其上方滚动不会被顶走（ojm ≥ 0.2.22）
 # Ctrl+C（SIGINT）/ kill（SIGTERM）终止 dev 时，前端与后端 oj 一起终止：
 # 先关 SSE 通道 → 停 oj 子进程 → 打印「后端 oj 已随前端一起终止」，不留 oj 孤儿占端口
 pnpm build             # = ojm build：oj build（生成 routes.js）+ 前端全站合并到 web/dist
 pnpm preview           # = ojm preview：oj migrate（verify 闸）→ oj serve 单服务（API + 静态 SPA 同进程）
 pnpm typecheck         # = tsc --noEmit（前端工程）
 pnpm typecheck:api     # = tsc --noEmit -p src/tsconfig.json（后端工程，见 §6.5）
+pnpm new               # = ojm new <name>：脚手架内生成用户方案骨架（见 §10.1）
+pnpm bundle            # = ojm build --bundle：打包全部用户方案（自带方案自动排除，见 §11）
 pnpm exec ojm info     # 版本矩阵 + 模块清单（报障用）
 pnpm exec ojm vendor   # 下载/重装 oj 二进制
 ```
@@ -1616,6 +1659,28 @@ export default async (path: string, html: string) => {
 > release 下只有 `routes.js` 里的路由存在，目录镜像路由不生效——所以参数路由要先
 > `ojm build` 再测（见 §7）。
 
+#### `ojm build --bundle [name]`
+
+打包**方案包**（solution bundle，可分发产物；语义细节见 §11）。只组装不构建，先 `ojm build` 再打包。
+
+- `--bundle` 无参：工程根有 `solution.yaml` 则只打根契约（旧单方案行为零变化）；
+  否则收集 `src/*/` 下全部**用户方案**契约逐个打包（框架自带方案自动排除，日志注明「框架自带，跳过」）。
+- `--bundle <name>` / `--bundle=<name>`：只打 `src/<name>/solution.yaml` 这一份（manifest.yaml 回退）。
+- 两段式：全部契约校验通过才开始写盘；零用户方案时报错指路 `ojm new`。
+
+#### `ojm new <name> [--layout container|none] [--api]`
+
+脚手架内生成一份用户方案骨架（module-root 布局）：`src/<name>/solution.yaml` +
+`web/{entry.ts,pages/,locales/}`（`--api` 再加 `api/{manifest.yaml,api.ts}`）。
+生成即被扫描收录，补产物后 `ojm build --bundle <name>` 直接可打（round-trip）。
+非 module-root 布局拒绝（会先要求迁移）；名字撞内置方案 / 保留名 / 已存在目录都会拒绝。
+```bash
+ojm new crm --layout container   # 建 src/crm/ 骨架
+pnpm dev                         # 看效果
+ojm build --bundle crm           # 打包
+```
+
+
 #### `ojm preview [port]`
 
 生产形态预览（设计 §6，2026-10-19 单服务化）：
@@ -1647,9 +1712,11 @@ export default async (path: string, html: string) => {
 
 生成物重跑即覆盖（eslint 已忽略）；唯一例外是带 `// ojm-api:stub` 指纹的 stub，人碰过则工具永不写删。
 
-#### `ojm info`
+#### `ojm info [--all]`
 
 输出版本矩阵（`@oj-module/cli` / `@oj-module/runtime` / 钉版 `@plane/*` / `oj` 二进制）与模块清单。
+module-root 下数据源是「扫描 + `web.config.ts` 登记」并集（未登记的用户模块也可见）。
+框架自带方案默认折叠为一行计数（`--all` 展开平铺）。
 **报障用**：拿不准「工程里到底装了什么版本、哪些模块被登记」时，先 `ojm info` 贴出来。
 
 #### `ojm vendor [tag] [--force]`
@@ -1697,20 +1764,22 @@ export default async (path: string, html: string) => {
 ### 10.3 本地市场链路：`ojm market` 子命令
 
 `market` 是一组**本地模拟 CDN + 市场链路**工具，专供作者在本机验证「方案包能不能发、能不能装」，
-**不触碰真实生产 CDN**。所有产物落在工程根 `cdn/`（由 `config.yaml` 的 `/cdn` 挂载直出），
-首跑用 `market setup` 把系统设置 `framework.market_cdn_url` 指过去即可在本地市场页看到。
+**不触碰真实生产 CDN**。所有产物落在工程根 `cdn/`（由 `config.yaml` 的 `/cdn` 挂载直出）。
+**脚手架 seed 的 `framework.market_cdn_url` 缺省即相对路径 `/cdn`（本站点自供），起站即市场可用，
+无需 setup**；只有指向外部真 CDN 时才需要 `market setup` 改写设置。
 
-> 跑任何子命令前先 `ojm market setup` 一次（把模拟 CDN 地址写进站点配置）。
+> `market setup` 已非必需（见上）；它只剩「指向外部真 CDN」一个场景。
 > 想看「这个包到底能不能装」而不污染工程，用 `ojm market trial`（一次性隔离站点，跑完即毁）。
 > 每个子命令都能 `ojm market <sub> --help` 单独看帮助。
 
 | 子命令 | 一句话 |
 |---|---|
-| `ojm market setup [--url <站点>] [--user <u> --pass <p>] [--new-pass <p>]` | 把 `framework.market_cdn_url` 指向本地 `cdn/`；首跑若账号处于首次改密期会先自动改密再写入 |
+| `ojm market setup [--url <站点>] [--user <u> --pass <p>] [--new-pass <p>]` | **外部真 CDN 场景才需要**：把 `framework.market_cdn_url` 改写为绝对地址；账号须 **superadmin**（该设置安全组仅 superadmin 可写，admin 角色会被 403）；首跑若账号处于首次改密期会先自动改密再写入 |
 | `ojm market publish [--fixture <name>@<version>] [--real <方案工程>] [--id <key>] [--key <pem>] [--rebuild-index] [--check]` | 把方案包落进 `cdn/` 并做包级 detached 签名；**不碰索引**（索引由 `build-index` 重建，避免多人发布互相覆盖） |
 | `ojm market build-index [--id <key>] [--key <pem>] [--check]` | 扫描 `cdn/*.tgz`、提取包内 manifest，全量重建 `bundles.yaml` + `manifests.yaml` 并签名；结果只取决于目录内容，连续执行字节一致 |
 | `ojm market verify [--file <tgz>] [--rebuild-index]` | 离线验包（不起站点、不装、不要凭据）：sha256 完整性 / 包级 Ed25519 验签 / 索引验签 / manifest 结构分列输出；`--rebuild-index` 额外比对重建索引与盘上索引的漂移 |
 | `ojm market trial [--fixture <name>@<version>] [--keep]` | 在一次性隔离站点里跑完整安装，跑完即毁；`--keep` 保留现场供排查 |
+| `ojm market walkthrough [--fixture <name>@<version>] [--only <op>] [--keep] [--strict]` | 隔离站点上 14 项全套自检（主链 9：index/install/reinstall/enable/verify/history/upgrade/rollback/uninstall；负向 5：tamper/nosig/badindex/stranger/evil——预期失败口径，防线没拦住才算 FAIL）；AC 表 + 失败文案脱敏落盘 `logs/walkthrough-<ts>.md`；`--only` 单跑验原子性 |
 
 - `--fixture <name>@<version>`：用内置合成包（无需先 build）；`--real <方案工程>`：先 `ojm build --bundle` 再拿真实产物。
 - `--id <key>` / `--key <pem>`：包级签名身份（与 `ojm sign` 同体系，默认取 `~/.ojm/keys`）。
@@ -1722,25 +1791,44 @@ export default async (path: string, html: string) => {
 ## §11 方案包：打包与分发
 
 「站点级构建」见 §7；本节讲**方案包**（solution bundle）——单方案的可分发产物与到达站点的方式。
+一个脚手架可放多份用户方案（`ojm new` 逐个生成，各自一份 `src/<name>/solution.yaml`），
+`ojm build --bundle` 无参时全部打包、逐个校验独立出包；框架自带方案自动排除（名单见
+`src/.ojm-builtin.json`，`ojm info` 默认折叠自带模块）。
+**从开发到发布的完整过程视角（含签名与私钥保存纪律）见**
+[`docs/guides/solution-dev-build-publish.md`](../guides/solution-dev-build-publish.md)。
 
 ### 11.1 打包：`ojm build --bundle`
 
 ```bash
 ojm build --bundle            # --out <dir> 缺省工程根 dist/（方案包输出目录，与后端产物 api/dist 无关）
-# [ojm] 方案包已生成 → dist/<name>-<version>.tgz
+ojm build --bundle crm        # 只打 src/crm/ 这一份；--bundle=crm 等价
+# [ojm] 方案包已生成 → dist/<name>-<version>.tgz（多份用户方案时逐份输出，共打包 N 份）
 # [ojm] sha256：…（确定性打包：同源同字节）
+# 没有可打包的用户方案时：报错指向 ojm new（不静默产出空批次）
 ```
 
 > `--bundle` 只**组装**，不重跑构建：入包内容取自 `api/dist/<name>-<version>/` 与
 > `web/dist/modules/<name>/`——先 `ojm build` 再打包。
 
-- 打包即校验（fail-fast，坏清单出不了包）：方案 manifest 契约校验（字段齐全 / 类型白名单 /
-  保留名 / 键空间 → 可读违规清单）→ 文件面校验（`api.tables` ↔ `schema.yaml`、locales 双语齐备）。
+- **契约入口（按优先级）**：`src/<模块>/solution.yaml` ≻ 工程根 `solution.yaml` ≻
+  `src/<模块>/manifest.yaml` ≻ 工程根 `manifest.yaml`（方案级；`manifest.yaml` 为旧方案回退）。
+  **单模块方案推荐把契约放在 `src/<模块>/solution.yaml`**——契约与它所打包的模块同位，最直观。
+  文件名刻意避开 `manifest.yaml`：oj 按 `manifest.yaml` 枚举发现 api 后端模块（§1.2），工程根若放一份
+  bundle 契约会污染那条搜索枚举；故用 `solution.yaml` 隔开两条枚举——**后端按 `manifest.yaml` 枚举 api、
+  打包按 `solution.yaml` 取契约**，不再冲突。模块级契约同样**只认 `src/<模块>/` 根下、绝不进 `<模块>/api/`**，
+  否则会与 oj 的 api 枚举撞车。tgz 内固定写回 `manifest.yaml`（安装侧只认这个名字）。
+- **两段式**：先对全部目标契约跑完校验（纯读零写盘），全绿才开始逐个写 tgz——任一校验失败
+  dist/ 零增量，报错指名失败方案（发布者不会把半截批次扫进 CDN 索引）。校验项（fail-fast，
+  坏清单出不了包）：方案 solution 契约（字段齐全 / 类型白名单 / 保留名 / 键空间 → 可读违规清单）
+  → 文件面（`api.tables` ↔ `schema.yaml`、locales 双语齐备）→ 模块级契约 `name` 必须 === 目录名。
+- 框架自带方案不参与打包：`src/.ojm-builtin.json` 名单内的模块契约被跳过（逐条日志）；
+  该文件由 `ojm init` 从模板白名单派生，**可手改/删除**（删名 = 恢复参与打包），重跑 init 缺失才补写。
+  它只是打包排除 / info 折叠提示，**不是安全边界**：文件永不入包，安装侧信任链（签名 + 信任库 + TOFU）与它无关。
 - **只出包不签名**——签名见 §12（关注点分离：作者签名是显式动作，不是构建副产品）。
 - 产物内 `manifest.yaml` 的 `archive` 段是 **Form A**（仅 `file`）；`sha256`/`size` 由
   file 源上传时点补齐（宿主安装器）或发布通道 Form B 自带。
-- **入包红线**：`*.pem` / `*.key` / `.env` / `id_ed25519` / `id_rsa` 等私钥形态文件禁入包
-  （与 `modules.json` 禁入同款自检）——私钥入包即信任根基烧毁。
+- **入包红线**：`*.pem` / `*.key` / `*.p12` / `*.pfx` / `.env` 系 / `id_ed25519` / `id_rsa`
+  等私钥形态文件禁入包（与 `modules.json` 禁入同款自检，0.2.23 起扩面）——私钥入包即信任根基烧毁。
 
 ### 11.2 两种分发源
 
@@ -1850,7 +1938,7 @@ ojm keygen --id <publisher>.<key-name>
 ojm sign dist/<name>-<version>.tgz --id <publisher>.<key-name> --check
 
 # ③ 安装/分发：.sig 自动探测随包上传
-ojm install dist/<name>-<version>.tgz --url <站点> --user admin --pass …
+ojm install dist/<name>-<version>.tgz --url <站点> --user superadmin --pass …
 ```
 
 宿主验签六码（失败文案双语，`--locale` 切换）：`sig_missing`（缺签）/ `sig_alg`（算法

package/devkit/module-dev-and-cdn-playground.md

@@ -68,15 +68,15 @@
 
 模板自带一个**本地模拟 CDN**（工程根 `cdn/` + 工程根 `config.yaml` 里的 `/cdn` 挂载），配上 `ojm market` 四条命令，就能在本地复刻「发包 → 上架 → 索引 → 安装」全链路。不需要外部服务。
 
-### 4.1 全流程（五步）
+### 4.1 全流程（五步，step 1 已省）
 
 ```bash
-# 0) 起站点（dev 或 serve 均可；市场地址必须指向 oj 子进程的端口，见 §5.1）
+# 0) 起站点（dev 或 serve 均可）
 ojm dev
 
-# 1) 打开市场地址：把 framework.market_cdn_url 指向 http://127.0.0.1:9778/cdn
-#    站点管理员首次登录处于改密悬挂期时会自动改密换全权 token
-ojm market setup --user admin --pass 123456 --new-pass <你的口令>
+# 1) 【免 setup】脚手架 seed 的 framework.market_cdn_url 缺省即 /cdn（本站点自供，
+#    dev 形态 ojm 已把 /cdn 反代给 oj 子进程）。只有指向外部真 CDN 时才需要：
+#    ojm market setup --user superadmin --pass 123456 --new-pass <你的口令>
 
 # 2) 发包：合成 fixture（或 --real 走 ojm build --bundle）→ 确定性 tgz → 包级签名
 #    --rebuild-index 顺带重建索引
@@ -93,7 +93,7 @@ ojm market verify --rebuild-index
 
 | 命令 | 做什么 | **不**做什么 |
 |---|---|---|
-| `market setup` | 写系统设置 `framework.market_cdn_url` | 不改写工程根 `config.yaml`（`/cdn` 挂载由模板自带） |
+| `market setup` | 写系统设置 `framework.market_cdn_url`（**外部真 CDN 场景才需要**；脚手架缺省 /cdn 免 setup） | 不改写工程根 `config.yaml`（`/cdn` 挂载由模板自带） |
 | `market publish` | 落 `<name>-<version>.tgz` + 包级 `.tgz.sig` | **不碰索引**（索引是共享单文件，多人发布会互相覆盖） |
 | `market build-index` | 扫 `cdn/*.tgz` 提取包内 manifest，全量重建两份索引并签名 | 不落包 |
 | `market verify` | 完整性 / 包级签 / 索引签 / manifest 结构四类校验 + 漂移检出 | 不起站点、不装、不访问任何远端 |
@@ -111,9 +111,9 @@ ojm market verify --rebuild-index
 
 ## 5. 两个已经踩过的坑（别再踩）
 
-### 5.1 dev 形态下，`/cdn` 不在 dev server 上
+### 5.1 dev 形态下，`/cdn` 由 oj 子进程直出（ojm 已代为反代）
 
-`ojm dev` 的 Node 服务在 **5174**，只把 `/api` 反代给 oj 子进程；`/cdn` 是 **oj 的挂载**，只在 oj 子进程（`config.yaml` 的 `server.port`，默认 9778）上成立。所以市场地址**必须写绝对 URL** 且端口取自 config——写成相对 `/cdn` 的话，dev 下取到的是 index.html，报出来是难懂的 YAML 解析错，不是干净 404。`market setup` 已按 config 推导，别手改。
+`ojm dev` 的 Node 服务在 **5174**，把 `/api` 与 `/cdn`（config 有 `/cdn` 挂载时）一并反代给 oj 子进程；`/cdn` 是 **oj 的挂载**，直出工程根 `cdn/`。`framework.market_cdn_url` 写成相对路径 `/cdn`（seed 缺省值）时，服务端按**请求源**补全同源绝对 URL 再拉取——dev 下请求走 5174，反代链路内透传，拿到的是真索引。2026-10-23 之前 dev 只反代 `/api`，相对基址会拿到静态层回落的 index.html（难懂的 YAML 解析错）——该坑已由 dev 反代 + 消费侧 `withSiteOrigin` 补全闭环。历史上下文：`market setup` 写绝对地址（`http://<host>:<config server.port>/cdn`）依旧兼容可用。
 
 ### 5.2 CDN 里摆了 `.tgz.sig` 侧车，不等于能装
 
@@ -165,7 +165,7 @@ node "$CLI_PKG/bin/ojm.mjs" market verify --rebuild-index
 node "$CLI_PKG/bin/ojm.mjs" build                 # 生成 api/dist + web/dist（含 api/dist/versions.json）
 # config：platform.root 改成 api/dist（安装目标恒为 release 部署，root 必须与 --api-path 同源）
 (bin/oj serve -c config.yaml -b /api --api-path api/dist --console-log &)
-node "$CLI_PKG/bin/ojm.mjs" market setup --url http://127.0.0.1:9778 --user admin --pass 123456 --new-pass <新口令>
+node "$CLI_PKG/bin/ojm.mjs" market setup --url http://127.0.0.1:9778 --user superadmin --pass 123456 --new-pass <新口令>
 # 市场页点安装 → 首次停在「待信任」→ 核对指纹 → ojm trust confirm --task <id> → 重试 → done
 ```
 
@@ -174,7 +174,7 @@ node "$CLI_PKG/bin/ojm.mjs" market setup --url http://127.0.0.1:9778 --user admi
 | # | 现象 | 根因 / 正确做法 |
 |---|---|---|
 | ① | `oj build` 报 `tables 声明 "x" 不在 schema.yaml` | oj 用 `schema.yaml` 做表结构真源，`manifest.tables` 只是引用面；补 `schema.yaml`（`tables: {<t>: {pk, columns}}`），与迁移语句对齐 |
-| ② | `oj build` 成功但 `routes.js` 是空表、dist 里没有 handler | **只编译 `.ts` handler**；写成 `ping/api.js` 会被静默丢弃 → 改 `api.ts` |
+| ② | `oj build` 成功但 `routes.js` 是空表、dist 里没有 handler | **只编译 `.ts` handler**；写成 `ping/api.js` 会被静默丢弃 → 改 `api.ts`。另一同形坑（构建也零报错）：`api.ts` 写成裸具名导出（`export async function ping`）——oj 内省只读 **default export** 且链尾动词须在 METHODS 白名单（get/post/put/del/patch/head/options），裸导出的函数根本不在表里 → 改成 `const ping = { async get() {...} }; export default { ping }`（`ojm new --api` 骨架即此形状） |
 | ③ | `build --bundle` 报 `缺少 src/<name>/web/locales/…`（历史布局是 `web/src/<name>/locales/…`） | manifest 一旦引用 `title_key`/`label_key` 就必须双语 locale（后端方案也要）；且 key 必须**嵌套** `{"menu":{"main":"…"}}`，平铺 `"menu.main"` 查不到 |
 | ④ | 安装 POST 返回 200，但 `market/task` 恒 404 | 宿主 config 缺 `fs:` 段 → 安装器落盘被 jail 拒、失败发生在任务文件写入前；0.2.13 起模板自带，旧工程手补 |
 | ⑤ | 安装卡 `preflight`：`无法读取宿主 runtime 版本` | 安装器读 `api/dist/versions.json`；0.2.13 起 `ojm build` 双落点（旧版手抄 `web/dist/versions.json`） |

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.20",
-  "description": "React Antd Admin 模块工程命令行工具（含预构建宿主 shell-dist）",
+  "version": "0.2.25",
+  "description": "React Antd 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
     ".": {
@@ -49,9 +49,10 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.2.20",
+    "@oj-module/runtime": "0.2.25",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
+    "cac": "^6.7.14",
     "esbuild": "^0.28.2",
     "tailwindcss": "^4.3.0",
     "tsx": "^4.23.12",
@@ -97,7 +98,6 @@
     "zustand": "^5.0.13"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "scripts": {

package/shell-dist/assets/runtime.js

@@ -204,6 +204,7 @@ var init_site_base = __esmMin((() => {
 * 子路径部署（/oj/wiki/...）下直接与 loginPath 比较恒为 false，401 时会重复 goLogin。
 * React 组件内请用 `useLocation()`（react-router 已剥离 basename），无需本函数。
 *
+* @param pathname 原始路径（含部署 base，如 `location.pathname`）
 * @param base 部署 base，恒以 `/` 结尾；缺省取 `resolveSiteBase()`（部署期注入优先，
 * 见 utils/site-base.ts —— runtime 产物里的 `import.meta.env.BASE_URL` 是构建期
 * 内联的 `/`，子路径部署下直接用它恒错）
@@ -303,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.20",
+			"version": "0.2.25",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-22 12:17:23"
+		"lastBuildTime": "2026-10-23 15:39:15"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -429,7 +430,7 @@ function PageError({ error, resetErrorBoundary }) {
 	};
 	useEffect(() => {
 		if (enableDynamicTitle) document.title = t("exception.pageErrorTitle");
-	}, [enableDynamicTitle]);
+	}, [enableDynamicTitle, t]);
 	return /* @__PURE__ */ jsx(Result, {
 		status: "error",
 		icon: /* @__PURE__ */ jsx("div", {
@@ -3495,7 +3496,7 @@ function useCurrentRoute() {
 	const matches = useMatches();
 	return useMemo(() => {
 		return matches[matches.length - 1];
-	}, [matches, location]);
+	}, [matches]);
 }
 var init_use_current_route = __esmMin((() => {}));
 //#endregion
@@ -3595,7 +3596,7 @@ function useCssVar(name, root = defaultRoot, options = {}) {
 	}), [name, root]);
 	useEffect(() => {
 		if (options?.initialValue) controls.set(options.initialValue);
-	}, [options?.initialValue]);
+	}, [options?.initialValue, controls]);
 	useEffect(() => {
 		return () => controls.remove();
 	}, [controls]);
@@ -3656,7 +3657,7 @@ var init_dom = __esmMin((() => {}));
 * @en Get the style of the layout content area
 */
 function useLayoutContentStyle() {
-	const contentElement = useRef(null);
+	const contentElementRef = useRef(null);
 	const [visibleDomRect, setVisibleDomRect] = useState(null);
 	const resizeObserverRef = useRef(null);
 	const contentHeightControls = useCssVar(CSS_VARIABLE_LAYOUT_CONTENT_HEIGHT);
@@ -3673,7 +3674,7 @@ function useLayoutContentStyle() {
 		};
 	}, [visibleDomRect]);
 	const debouncedCalcHeight = useDebounceFn((_entries) => {
-		const rect = getElementVisibleRect(contentElement.current);
+		const rect = getElementVisibleRect(contentElementRef.current);
 		setVisibleDomRect(rect);
 		if (rect) {
 			contentHeightControls.set(`${rect.height}px`);
@@ -3681,10 +3682,10 @@ function useLayoutContentStyle() {
 		}
 	}, { wait: 16 });
 	useEffect(() => {
-		if (contentElement.current && !resizeObserverRef.current) {
+		if (contentElementRef.current && !resizeObserverRef.current) {
 			const resizeObserver = new ResizeObserver(debouncedCalcHeight.run);
 			resizeObserverRef.current = resizeObserver;
-			resizeObserver.observe(contentElement.current);
+			resizeObserver.observe(contentElementRef.current);
 		}
 		return () => {
 			resizeObserverRef.current?.disconnect();
@@ -3692,7 +3693,7 @@ function useLayoutContentStyle() {
 		};
 	}, [debouncedCalcHeight]);
 	return {
-		contentElement,
+		contentElementRef,
 		overlayStyle,
 		visibleDomRect
 	};
@@ -4173,7 +4174,7 @@ function KeepAliveLayer() {
 		(aliveRef.current?.getCacheNodes?.())?.forEach((node) => {
 			if (!openTabs.has(node.cacheKey)) aliveRef.current?.destroy(node.cacheKey);
 		});
-	}, [openTabs]);
+	}, [openTabs, aliveRef]);
 	/**
 	* 关闭多 tab 功能时，清空所有非当前页面缓存
 	*/
@@ -4181,10 +4182,18 @@ function KeepAliveLayer() {
 		if (!tabbarEnable) (aliveRef.current?.getCacheNodes?.())?.forEach((node) => {
 			if (node.cacheKey !== cacheKey) aliveRef.current?.destroy(node.cacheKey);
 		});
-	}, [tabbarEnable]);
+	}, [
+		tabbarEnable,
+		aliveRef,
+		cacheKey
+	]);
 	useEffect(() => {
 		if (tabbarEnable && isRefresh) aliveRef.current?.refresh();
-	}, [isRefresh]);
+	}, [
+		isRefresh,
+		aliveRef,
+		tabbarEnable
+	]);
 	const keepAliveExclude = useMemo(() => {
 		/**
 		* 不开启多 tab 时不需要 KeepAlive，把所有路由放进 exclude 仅保留切换动画
@@ -4212,7 +4221,7 @@ var init_keep_alive_layer = __esmMin((() => {
 //#region src/layout/layout-content/index.tsx
 function LayoutContent() {
 	const { token: { colorBgLayout } } = theme.useToken();
-	const { contentElement } = useLayoutContentStyle();
+	const { contentElementRef } = useLayoutContentStyle();
 	const enableFooter = usePreferencesStore((state) => state.enableFooter);
 	const fixedFooter = usePreferencesStore((state) => state.fixedFooter);
 	/**
@@ -4221,7 +4230,7 @@ function LayoutContent() {
 	*/
 	return /* @__PURE__ */ jsx("main", {
 		id: ELEMENT_ID_MAIN_CONTENT,
-		ref: contentElement,
+		ref: contentElementRef,
 		className: "relative overflow-y-auto overflow-x-hidden grow",
 		style: { backgroundColor: colorBgLayout },
 		children: /* @__PURE__ */ jsx(Scrollbar, { children: /* @__PURE__ */ jsx(GlobalSpin, { children: /* @__PURE__ */ jsxs("div", {
@@ -4447,7 +4456,11 @@ function GlobalSearch() {
 	useKeyPress("downarrow", handleDown);
 	useEffect(() => {
 		if (!keyword.length && Array.isArray(searchHistory)) setResultOptions(searchMenuList.filter((item) => searchHistory?.includes(item.key)));
-	}, [keyword, searchHistory]);
+	}, [
+		keyword,
+		searchHistory,
+		searchMenuList
+	]);
 	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("div", {
 		onClick: () => setOpen((open) => !open),
 		className: "group flex justify-center items-center gap-2 md:bg-colorBgLayout px-3 py-1.5 rounded-full cursor-pointer text-colorTextSecondary hover:text-colorText md:mr-2.5",
@@ -5113,18 +5126,18 @@ function Sidebar() {
 				name: item.name,
 				checked: item.value,
 				onChange: handleChange,
-				children: item.label,
-				disabled: item.disabled
+				disabled: item.disabled,
+				children: item.label
 			}, item.name);
 		}),
 		/* @__PURE__ */ jsx(SwitchItem, {
 			name: "sidebarTheme",
 			checked: sidebarTheme === "light",
 			onChange: (name, value) => setPreferences(name, value ? "light" : "dark"),
-			children: t("preferences.sidebar.sidebarTheme"),
 			disabled: !sidebarEnable,
 			unCheckedChildren: /* @__PURE__ */ jsx(RiContrastFill, {}),
-			checkedChildren: /* @__PURE__ */ jsx(RiMoonIcon, {})
+			checkedChildren: /* @__PURE__ */ jsx(RiMoonIcon, {}),
+			children: t("preferences.sidebar.sidebarTheme")
 		}),
 		/* @__PURE__ */ jsx(NumberInputSpinner, {
 			min: 40,
@@ -5702,7 +5715,7 @@ function UserMenu({ ...restProps }) {
 		}
 		if (key === "personal-center") navigate("/personal-center/my-profile");
 	};
-	const altView = useMemo(() => isWindowsOs() ? "Alt" : "⌥", [isWindowsOs]);
+	const altView = useMemo(() => isWindowsOs() ? "Alt" : "⌥", []);
 	const items = [{
 		label: t("personal-center:menu.personalCenter"),
 		key: "personal-center",
@@ -5973,7 +5986,7 @@ function LayoutMenu({ mode = "inline", autoExpandCurrentMenu, handleMenuSelect,
 		isMobile,
 		sidebarCollapsed
 	]);
-	const handleOpenChange = (keys) => {
+	const handleOpenChange = useCallback((keys) => {
 		/**
 		* 1. 手风琴模式，点击菜单项，自动关闭其他菜单
 		* 2. 非手风琴模式且菜单是收起的，鼠标悬浮菜单自动关闭其他菜单
@@ -5992,7 +6005,12 @@ function LayoutMenu({ mode = "inline", autoExpandCurrentMenu, handleMenuSelect,
 				if (currentCloseKey) setOpenKeys(menuParentKeys[currentCloseKey]);
 			}
 		} else setOpenKeys(keys);
-	};
+	}, [
+		accordion,
+		sidebarCollapsed,
+		openKeys,
+		menuParentKeys
+	]);
 	const menuOpenProps = useMemo(() => {
 		if (autoExpandCurrentMenu) return {
 			openKeys,
@@ -6019,7 +6037,8 @@ function LayoutMenu({ mode = "inline", autoExpandCurrentMenu, handleMenuSelect,
 	}, [
 		matches,
 		sidebarCollapsed,
-		getSelectedKeys
+		getSelectedKeys,
+		accordion
 	]);
 	return /* @__PURE__ */ jsx(Menu, {
 		/**
@@ -6552,7 +6571,6 @@ function useDropdownMenu() {
 	}, [
 		t,
 		activeKey,
-		homePath,
 		openTabs
 	]);
 	/**
@@ -6569,6 +6587,8 @@ function useDropdownMenu() {
 		[TabActionKeys.CLOSE_OTHERS]: closeOtherTabs,
 		[TabActionKeys.CLOSE_ALL]: closeAllTabs
 	}), [
+		refresh,
+		setIsRefresh,
 		removeTab,
 		closeRightTabs,
 		closeLeftTabs,
@@ -6814,7 +6834,7 @@ function LayoutTabbar() {
 			hash: ""
 		};
 		navigate(key + historyState.search + historyState.hash);
-	}, [openTabs]);
+	}, [openTabs, navigate]);
 	/**
 	* 处理标签页编辑（关闭）
 	* @param {React.MouseEvent | React.KeyboardEvent | string} key - 被编辑的标签页的key
@@ -6941,7 +6961,8 @@ function LayoutTabbar() {
 		location,
 		currentRoute,
 		setActiveKey,
-		addTab
+		addTab,
+		activeKey
 	]);
 	return /* @__PURE__ */ jsx("div", {
 		className: classes.tabsContainer,
@@ -7023,7 +7044,7 @@ function ContainerLayout() {
 		if (screens.lg && !screens.xl) setPreferences("sidebarCollapsed", true);
 		else if (screens.xl) setPreferences("sidebarCollapsed", false);
 		else if (screens.xs || screens.sm && !screens.md) setPreferences("sidebarCollapsed", false);
-	}, [screens]);
+	}, [screens, setPreferences]);
 	const sidebarEnableState = useMemo(() => !isTopNav && sidebarEnable, [isTopNav, sidebarEnable]);
 	const computedSidebarWidth = useMemo(() => {
 		if (isMaximize || isMobile) return 0;
@@ -7049,7 +7070,7 @@ function ContainerLayout() {
 		let height = 48;
 		if (tabbarEnable) height += 35;
 		return height;
-	}, [tabbarEnable, 35]);
+	}, [tabbarEnable]);
 	useEffect(() => {
 		setLayoutHeaderHeight(isMaximize ? 35 : headerWrapperHeight);
 	}, [headerWrapperHeight, isMaximize]);
@@ -7934,7 +7955,7 @@ async function generateRoutesFromBackend(backendRoutes) {
 	/**
 	* 转换路由配置
 	* @param route 原始路由配置
-	* @param parentPath 父级路径（用于嵌套路由）
+	* @param parentComponentPath 父级组件路径（用于嵌套路由）
 	* @returns 转换后的路由配置
 	*/
 	const transformRoute = async (route, parentComponentPath) => {
@@ -8853,9 +8874,10 @@ async function handleErrorResponse(response) {
 			openMustChangeModal();
 			return response;
 		}
+		if (response.status === 403) return response;
 		const json = data;
 		message$1.error(json.msg || response.statusText);
-	} else message$1.error(response.statusText);
+	} else if (response.status !== 403) message$1.error(response.statusText);
 	return response;
 }
 var init_error_response = __esmMin((() => {
@@ -8918,8 +8940,6 @@ var init_remember_route = __esmMin((() => {
 * 必须带上部署 base（`resolveSiteBase()`）：子路径部署下 `location.href = "/login"`
 * 会跳到宿主机根，而不是 `/oj/login`。不能用 `import.meta.env.BASE_URL`——预构建
 * 产物里它是构建期内联的 `/`。
-*
-* @returns 无返回值
 */
 function goLogin() {
 	useAuthStore.getState().reset();
@@ -9022,6 +9042,8 @@ function onRefreshFailed(error) {
 * 订阅者对象应包含 resolve 和 reject 方法。
 *
 * @param subscriber 订阅者对象，包含 resolve 和 reject 方法
+* @param subscriber.resolve 当 token 刷新成功时调用的函数，传入新的 token
+* @param subscriber.reject 当 token 刷新失败时调用的函数，传入错误信息
 */
 function addRefreshSubscriber(subscriber) {
 	refreshSubscribers.push(subscriber);
@@ -9447,6 +9469,10 @@ function useAccess() {
 * 权限验证组件
 *
 * @param AccessControlProps 权限验证组件的属性
+* @param AccessControlProps.type 权限类型，默认为 code
+* @param AccessControlProps.codes 权限值，可以是字符串或字符串数组
+* @param AccessControlProps.children 有权限时渲染的子组件
+* @param AccessControlProps.fallback 无权限时显示的内容
 * @returns 若子组件存在，并且传入的权限值有效，则返回子组件；否则返回 null
 */
 function AccessControl({ type = "code", codes, children, fallback }) {
@@ -9800,7 +9826,7 @@ function BasicTable(props) {
 		if (enableFooter && fixedFooter) return 40;
 		return 0;
 	}, [enableFooter, fixedFooter]);
-	const getPaginationProps = () => {
+	const getPaginationProps = useCallback(() => {
 		if (props.pagination === false) return false;
 		return {
 			placement: ["bottomStart"],
@@ -9810,7 +9836,7 @@ function BasicTable(props) {
 			showTotal: (total) => t("common.pagination", { total }),
 			...props.pagination
 		};
-	};
+	}, [props.pagination, t]);
 	/**
 	* @description 计算分页器的高度
 	* 如果分页器被禁用，则返回 0，否则根据分页器的大小返回相应的高度

package/shell-dist/index.html

@@ -5,9 +5,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-oCauQheXzDS2E/yd7smCtg=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-rkh8kQ0W+uFw3wTdIkSSUA=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
 
-		<script type="importmap" nonce="oCauQheXzDS2E/yd7smCtg==">{
+		<script type="importmap" nonce="rkh8kQ0W+uFw3wTdIkSSUA==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",