@oj-module/cli 0.2.18 → 0.2.23

package/devkit/README.md

@@ -2,14 +2,14 @@
 
 面向用 `ojm` 开发前后端一体工程的开发者与 AI agent。本目录是**源文件**，
 发布时由 cli 的 `prepack`（`packages/cli/scripts/sync-devkit.mjs`）把其中
-**ojm 侧的 5 个文件**同步进 `packages/cli/devkit/`，随 `@oj-module/cli`
+**ojm 侧的 6 个文件**同步进 `packages/cli/devkit/`，随 `@oj-module/cli`
 发布，再由 `ojm init` 分发到工程内。
 
 整棵树覆盖前后端两侧，但仍是**两套独立分发的 skill**（同名不同物，别混）：
 
 | 侧 | 本仓位置 | 用户工程里的落点 | 分发链 |
 |---|---|---|---|
-| ojm 模块开发（前端模块、契约、前后端对接） | 本目录顶层 5 个文件 | `.claude/skills/ojm-module-dev/` | `@oj-module/cli` 包 → `ojm init` 第 4b 步 |
+| ojm 模块开发（前端模块、契约、前后端对接） | 本目录顶层 6 个文件 | `.claude/skills/ojm-module-dev/` | `@oj-module/cli` 包 → `ojm init` 第 4b 步 |
 | oj API 开发（后端 handler、全局对象、配置、测试） | `oj-api-dev/` 子目录（快照） | `.claude/skills/oj-api-dev/` | **oj 二进制自带**（`bin/devkit/`）→ `ojm init` 第 4 步 |
 
 > **`oj-api-dev/` 子目录是快照，不是本仓维护的文档**：它与本机 oj 的
@@ -24,7 +24,7 @@
 | 文件 | 用途 |
 |---|---|
 | `SKILL.md` | Claude Code 等 agent 的 skill 入口：工作流、红线、新模块 checklist、陷阱速查，按章节号引用手册 |
-| `manual.md` | 模块开发手册（12 章）：工程结构（含 §1.7 handler 四红线——oj 运行时实测钉出，后端必读）、写模块、契约与代码生成（含 §3.10 旧 contract.ts 工程迁移指南）、provider 接管（覆盖框架内置功能）、布局、i18n、构建发布、排查、CLI 子命令参考（ojm 原生命令 vs oj 透传命令）、方案包打包与分发、签名与信任 |
+| `manual.md` | 模块开发手册（13 章）：工程结构（module-root 单树 + 两处产物根；含 §1.7 handler 四红线——oj 运行时实测钉出，后端必读；§1.8 `#` 别名与 TS 投影）、写模块、契约与代码生成（含 §3.10 旧 contract.ts 工程迁移指南）、provider 接管（覆盖框架内置功能）、布局、i18n、构建发布、排查、CLI 子命令参考（ojm 原生命令 vs oj 透传命令）、方案包打包与分发、签名与信任 |
 | `framework-dev.md` | 框架贡献者路线（**仅框架仓库**）：改 `packages/runtime`、`packages/cli` 时的入口与红线 |
 | `module-dev-and-cdn-playground.md` | 教学文档：开发态 ≠ 分发态、「怎么安装自己的模块 / 会不会重复」、本地 CDN 市场链路五步跑通（setup → publish → build-index → verify → 安装） |
 | `sql-builder-missing-capabilities-pr.md` | 构造器能力缺口 PR 参考（**仅框架仓库**）：7 项诉求的闭环记录 |
@@ -108,6 +108,6 @@ flowchart LR
   框架贡献者要把本仓快照同步到新版：从 `~/.local/share/oj/devkit/` 整目录覆盖
   `docs/devkit/oj-api-dev/`（10 个文件，保持逐字节一致以便对账）。
 
-> 本目录顶层 5 个文件是**自包含**的：业务工程拿到即可读懂，不需要工程仓库里的
+> 本目录顶层 6 个文件是**自包含**的：业务工程拿到即可读懂，不需要工程仓库里的
 > 其它文档。`oj-api-dev/` 子目录是 oj 侧快照，同样自包含（其自身 README 即索引），
 > 但不随 cli 包发货、仅本仓参考。维护者视角的内容来源整理在 `framework-dev.md`（仅本仓）。

package/devkit/SKILL.md

@@ -17,8 +17,9 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 
 1. **读章**：建模块 → 手册 §2；加接口（handler .schema → oj openapi → 生成 → 对接）→ §3；
    接管通知/上传/菜单 → §4；换布局或加插槽 → §5；排查 → §8。
-2. **建目录**：前端 `web/src/<模块名>/`（`entry.ts` 必备，`pages/`、`locales/` 按需）；
-   后端 `api/src/<模块名>/`（目录镜像路由的 `api.ts`，动词挂 `.schema`）。
+2. **建目录**：一个目录 = 一个模块——前端一侧 `src/<模块名>/web/`（`entry.ts` 必备，
+   `pages/`、`locales/` 按需），后端一侧 `src/<模块名>/api/`（目录镜像路由的 `api.ts`，
+   动词挂 `.schema`）。两侧可只存在一侧。
    `entry.ts` 是模块元数据**唯一来源**——没有单独的 `package.json` / `meta.json`。
 3. **对接四步流水线**（加接口就背这条）：
    ```
@@ -29,19 +30,21 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
    flowchart LR
      A["handler 动词写 .schema（入参）+ 平级 .response（出参）"] --> B["写业务逻辑 api.ts"]
      B --> C["oj openapi 生成 openapi.json（唯一事实源）"]
-     C --> D["ojm api 生成 web/src/模块/__client"]
-     D --> E["entry.ts onInit：createModuleClient(ctx) 一次"]
-     E --> F["web.config.ts 登记模块（漏了静默不加载）"]
+     C --> D["ojm api 生成 src/模块/web/__client"]
+     D --> E["entry.ts onInit：create&lt;模块&gt;Client(ctx) 一次"]
+     E --> F["web.config.ts 登记模块（可选覆盖；扫描为真源）"]
    ```
-4. **登记**：往工程根 `web.config.ts` 的 `modules` 数组加一项。**漏了这步模块静默不加载、全程不报错。**
-5. **验证**：`pnpm dev`（前端 devServer **5174** + oj 后端 **9778**，端口以 `api/config.yaml` 为准）
+4. **登记**：往工程根 `web.config.ts` 的 `modules` 数组加一项（module-root 布局里 `ojm build/dev`
+   以扫描 `src/*/web/entry.ts` 为真源，登记项排前面、其余按扫描顺序追加；历史布局则必须登记）。
+   **要「不构建」写 `enabled: false`——注释掉无效。**
+5. **验证**：`pnpm dev`（前端 devServer **5174** + oj 后端 **9778**，端口以工程根 `config.yaml` 为准）
    → 登录 `admin / 123456` → 按 §8.1 五步清单核对。
 
 ## 红线（不可违反）
 
-- **登记**：模块必须写进 `web.config.ts` 的 `modules`（`enabled` 缺省即启用，显式
-  `enabled: false` 才禁用）。文件写完 ≠ 模块会跑。
+- **登记**：`web.config.ts` 的 `modules`（`enabled` 缺省即启用，显式 `enabled: false` 才禁用）。
   清单**先后顺序就是接管优先级**（同一入口先注册者生效，无优先级数字可填）。
+  历史布局漏登记 = 模块安静不加载；module-root 下登记是可选的，但**排序仍靠它**。
 - **`home` / `login` 模块必须保留**：shell 预构建把 `/` 重定向到 `/home`，且宿主只消费
   模块路由、不挂内置登录页。删掉它们 → 登录回跳落错误边界、`/login` 无路由可跳。
 - **布局级路由 handle 必写 `layout: "container"`**：不写页面会裸渲染（无侧边栏/页签），
@@ -49,16 +52,16 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 - **注册时机**：一切 `ctx.register.*` 必须在 `lifecycle.onInit` 内、且在 onInit 返回前完成。
   拖到 `onActivate` 或某个异步回调里注册不保证生效。`onInit` 签名是 **async**（返回
   `Promise<void>`）——漏写 `async` 会被 `tsc` 以 TS2322 拦下，范本见模板
-  `web/src/notification/entry.ts`。
+  `src/notification/web/entry.ts`。
 - **一模块一 client**：`create<Module>Client(ctx)` 只在 onInit 里创建一次。
   页面/组件/事件回调里**不要**再创建——会覆盖 request 单槽。页面里直接 import 裸函数调用。
 - **只创建自己模块的 client**：A 模块的 onInit 里创建 B 模块的 client 会 DEV 告警。要别家接口，
   走「B 自己注册 provider、A 消费 provider」的正路。
 - **既然接管就整套接管**：`ctx.register.*Provider` 的方法一个都不能少，不做「只接管读、写还用框架的」。
-- **生成物勿手改**：`web/src/<模块>/__client/**` 重跑即覆盖（eslint 已忽略）。改需求 = 改 handler 的
+- **生成物勿手改**：`src/<模块>/web/__client/**` 重跑即覆盖（eslint 已忽略）。改需求 = 改 handler 的
   `.schema`，重跑 `oj openapi` + `ojm api`。`openapi.json` 由 `oj openapi` 生成（oj 内省 `.schema` 的权威产物）。
-  唯一例外是 `api/**/api.ts` stub——文件头带 `// ojm-api:stub` 指纹的 stub 被人工动过后，工具**永不写永不删**。
-- **前缀约束**：API 前缀由**后端模块目录名**推导（`api/src/order/**` → `/order`，**不是** `/api/order`）。
+  唯一例外是 `src/<模块>/api/**/api.ts` 的 stub——文件头带 `// ojm-api:stub` 指纹、被人工动过后，工具**永不写永不删**。
+- **前缀约束**：API 前缀取模块 `manifest.yaml` 的 `name`（**约定与目录名一致**；`src/order/api/**` → `/order`，**不是** `/api/order`）。
   handler `.schema` / 路由须落在该目录内，否则 oj 路由表与生成物对不上、人话报错。
 - **不返回数据的接口不写 `.response`**：平级声明位直接省略即可（oj v0.1.72+；旧 `.schema.response` 通道仍兼容）；校验一律放后端。
 - **上传文件**：当前 `ojm api` 的 openapi 流水线不生成 form 通道的前端 client（文件部件不进 JSON Schema），
@@ -70,30 +73,30 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
   写走契约 client（`ojm api` 生成模块自有 `__client`，或复用 runtime 导出的 `api/rbac` / `api/user`），
   绝不 import 框架 `#src/*`**——设计动机与红线见手册 §2.8。
 - **后端方法名是 `del`，不是 `delete`**（写成 `delete` 返回 405）。
-- **加一张新表是三件套，不是只写 `schema.yaml`**：`migrations/{seq:04}__*.sql`（DDL 的真正定义（实际 SQL），
+- **加一张新表是三件套，不是只写 `schema.yaml`**：`src/<模块>/api/migrations/{seq:04}__*.sql`（DDL 的真正定义（实际 SQL），
   DDL 只进 migrations）+ `schema.yaml`（声明，与 migration 逐字段一致）+ `manifest.yaml` 的 `tables:`
   （与 schema 双向一致）。少一个就建不出表或启动失败。见手册 §1.5。
 - **`seed.sql` 每次启动都重放**，必须幂等（`INSERT OR IGNORE`）；它按 `;` 朴素切分，
   注释里不许出现分号字面量。
 - **handler 四红线（manual §1.7，oj 运行时实测）**：① 未捕获异常恒 500 不读
-  `err.status`——业务错误必须经 `respond()` 收口 `json.fail`；② 相对 import 按
-  **目录**解析（多一层 `../` 就 route error）；③ 模块级 `let`/`Map` 不跨请求存活
-  （oj 每请求重建模块）——跨请求状态必须落库；④ 模块级禁止触碰运行时全局
-  （`jwt`/`axis`/`bcrypt`），`oj build` introspect 空沙箱会炸。
+  `err.status`——业务错误必须经 `respond()` 收口 `json.fail`；② 跨模块引用走
+  `#/<模块名>/…` 别名（相对 import 按**目录**解析，多一层 `../` 就 route error）；
+  ③ 模块级 `let`/`Map` 不跨请求存活（oj 每请求重建模块）——跨请求状态必须落库；
+  ④ 模块级禁止触碰运行时全局（`jwt`/`axis`/`bcrypt`），`oj build` introspect 空沙箱会炸。
 
 ## 重启边界（最容易卡住新人）
 
 | 改动 | 生效方式 |
 |---|---|
-| 已有 `api.ts` 的**文件内容** | 保存即热更 |
-| **新增/删除**后端模块目录 | **必须重启 `ojm dev`** |
+| 已有 `api/**/api.ts` 的**文件内容** | 保存即热更 |
+| **新增/删除**后端模块目录（`src/<模块>/api`） | **必须重启 `ojm dev`** |
 | 改 `schema.yaml` / `migrations/` / `config.yaml` | **必须重启** |
-| 前端 `web/src/**` | 模块重建 + 浏览器自动刷新 |
+| 前端 `src/<模块>/web/**` | 模块重建 + 浏览器自动刷新 |
 
 ## 新模块 checklist
 
-- [ ] `web/src/<模块>/entry.ts` 默认导出 `defineModule({ name, version, routes, i18n?, lifecycle? })`
-- [ ] `web.config.ts` 的 `modules` 里已登记且 `enabled: true`
+- [ ] `src/<模块>/web/entry.ts` 默认导出 `defineModule({ name, version, routes, i18n?, lifecycle? })`
+- [ ] `web.config.ts` 的 `modules` 里已登记（`enabled` 缺省即启用；module-root 下扫描已能捡到，登记用于排序/覆盖）
 - [ ] 路由 `handle.layout` 选对了（有页面用 `"container"`；无页面模块 `routes: []`）
 - [ ] 菜单标题用命名空间语法 `"<模块名>:menu.<key>"`，且 `locales/<lang>.json` 里有这个 key
 - [ ] 有接口 → handler 动词挂了 `.schema`（入参）+ 平级 `.response`（出参，oj v0.1.72+）→ `oj openapi` + `ojm api` 跑过 → onInit 里 `create<Module>Client(ctx)`
@@ -105,10 +108,10 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 
 存量工程用 `api/src/<模块>/contract.ts`（`defineApi` + zod）声明契约——翻译层已删除，
 `ojm api` 不再读取它。迁移五步：① 盘点端点 → ② 入参译到 `.schema`、`data` 译到平级
-`.response`（zod→JSON Schema 对照表）→ ③ `oj openapi -c api/config.yaml -d api/src -b /api -o openapi.json`
-→ ④ `ojm api` + 前端调用点改 `camelCase(operationId)` → ⑤ 删 `contract.ts` 与旧产物
+`.response`（zod→JSON Schema 对照表）→ ③ `oj openapi -c config.yaml --module-root src -b /api -o openapi.json`
+（历史布局 `-d api/src`）→ ④ `ojm api` + 前端调用点改 `camelCase(operationId)` → ⑤ 删 `contract.ts` 与旧产物
 （per-module `routes.json` / `openapi.yaml`），`ojm api --check` 零漂移。
-前置：oj ≥ 0.1.73、框架包 ≥ 0.1.20。完整字段映射与丢失面清单见 **manual.md §3.10**。
+前置：oj ≥ 0.1.73（迁到 module-root 布局需 ≥ 0.1.85）、框架包 ≥ 0.1.20。完整字段映射与丢失面清单见 **manual.md §3.10**。
 
 ## 常见陷阱速查
 
@@ -137,25 +140,26 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 | 移动端侧边栏「不见了」 | 移动端进抽屉、iPad 默认折叠、可关 | 正常；别硬编码侧栏宽度，用 content-width |
 | 覆盖 `container` 后通知铃/页签没了 | 覆盖了内置外壳，自带 chrome 全失效 | 别覆盖；要加东西用 `header-actions` 插槽 |
 | 自定义布局里子页面空白 | 组件没渲染 `<Outlet/>` | 补 `<Outlet/>` |
-| 登录 401 且 msg 不是 `invalid credentials` | `/auth/*` 不在 `anonymous_paths` | 加进 `api/config.yaml`，重启 |
+| 登录 401 且 msg 不是 `invalid credentials` | `/auth/*` 不在 `anonymous_paths` | 加进工程根 `config.yaml`，重启 |
 | WS 连接 401（「文件在却连不上」） | 模块写了 `ws.ts`，但其 `/ws` 路由不在 `anonymous_paths`（oj v0.1.30+ WS 握手也过鉴权） | 匿名 WS 加进 `anonymous_paths`；受保护 WS 带 Bearer/Cookie 是正当用法。`ojm api --check` 会对此 warn |
 | 登出/回登录页落空，或登录后落错误边界 | 工程缺 `login` / `home` 模块 | 在 `web.config.ts` 保留两者 |
-| 通知铃 404 `no route matched` | 缺 root 级 `/api/notifications` | 补 `api/src/notifications` 模块 |
-| `oj serve` 启动即退，报 `config uses removed server.* site keys (v0.1.58): api_prefix` | 用了 oj v0.1.58 起删除的旧站点键（`api_prefix`/`app_path`/`app_prefix`/`static_sites`/`app_spa_fallback`） | 改 `server.api_prefix: /api` 为顶层 `mounts: [{prefix: "/api", api: "src"}]`；迁移完整 YAML 由报错给出 |
-| 改完 `mounts:` 仍全 404 | `api:` 指向目录不是 oj 启动目录下的 `src` | `mounts[].api` 写 `"src"`，`-c` 指向 `api/config.yaml`（ojm dev/preview 已内置） |
-| `oj serve` 启动即退，报 `module '_shared' missing manifest.yaml` | 把共享后端代码放到了顶层 `api/src/_shared/`（oj 把 `api/src` 顶层目录都当模块，缺 `manifest.yaml`） | 嵌进所属模块目录：`api/src/<模块>/_shared/`，相对导入 |
-| 后端 `import '@oj-module/runtime/...'` 报 `escapes project root` | oj 解析裸 specifier 以 `api/` 为项目根并钳制不越界，`@oj-module/runtime` 符号链接在 `packages/runtime`（项目根外） | 后端原语/类型放 `api/src` 内相对导入；跨模块共享类型仍以 runtime 为单一真源，两端形状手动同步 |
+| 通知铃 404 `no route matched`（`/api/notifications`） | 前端 `notification` 模块没加载 / 没注册 `notificationsApi`，回落到内置只读兜底；脚手架不再提供 root 级 `/api/notifications` | 保留 `src/notification/web/entry.ts` 的登记 + onInit 注册四方法；后端由 `src/notification/api` 出 `/api/notification/*` |
+| `oj serve` 启动即退，报 `config uses removed server.* site keys (v0.1.58): api_prefix` | 用了 oj v0.1.58 起删除的旧站点键（`api_prefix`/`app_path`/`app_prefix`/`static_sites`/`app_spa_fallback`） | 改 `server.api_prefix: /api` 为顶层 `mounts:`（module-root 写 `{prefix: "/api", api: "api/dist"}`；历史布局写 `api: "src"`、源码交给 `-d`）；迁移完整 YAML 由报错给出 |
+| 改完 `mounts:` 仍全 404 | `api:` 指向目录不对（相对 config 所在目录） | module-root 指向产物目录 `"api/dist"`、历史布局指向源码树 `"src"`；`-c` 指向工程根 `config.yaml`（ojm dev/preview 已内置）。module-root 模板**故意不写 api 挂载**（源码交给 `--module-root src`、产物交给 `--api-path api/dist`，同时出现会报 module declared in multiple places） |
+| `oj serve` 启动即退，报 `module '_shared' missing manifest.yaml` | 把共享后端代码放到了扫描根顶层（`src/_shared/`）——oj 把扫描根下的顶层目录都当模块；历史布局是 `api/src/_shared/` | 嵌进所属模块：`src/<模块>/api/_shared/`（历史布局 `api/src/<模块>/_shared/`），用 `#<本模块>/...` 别名 |
+| 后端 `import '@oj-module/runtime/...'` 报错或装到站点后崩 | 那是浏览器侧包（React / 浏览器全局），且方案包 tgz 不带 `node_modules` | 后端原语/类型放本模块 `api/_shared/`，跨模块用 `#/<模块名>/_shared/...`；跨端共享类型以 runtime 为单一真源、两端形状手动同步 |
 | 跨用户删/读他人通知不报错却像没生效 | 原语对不存在/非本人的行 `UPDATE 0` 行返回 `ok`，没区分归属 | 原语（`delNotice`/`markRead`）返回 `boolean`/`count`，端点据 `false`/`0` 映射 `json.fail(403, "forbidden")` |
 | handler 写了动词子目录（`read/api.ts` 这类） | 旧形态（oj v0.1.64 前） | 按 manual §3.9「DDD 判据速查」reshape：同聚合多动词收模块根嵌套组，`del` 保留键例外 |
 | 业务错误恒 `{"code":500}`（401/403/409 全变 500） | handler 抛异常被 oj 一律抹 500，不读 `err.status` | service 抛 `Error & {status}`，handler 经 `respond()` 收口（manual §1.7-1） |
-| dev 日志 route error（Cannot find module）/ 端点 404 | handler 相对 import 多一层——按**目录**解析 | 按 manual §1.7 深度表改 |
+| dev 日志 route error（Cannot find module）/ 端点 404 | handler 相对 import 多一层——按**目录**解析 | 改用 `#/<模块名>/…` 别名（与深度无关）；存量代码按 manual §1.7 深度表改 |
 | 限速/节流/计数真实请求下永不累积（测试全绿） | 模块级 `Map`/`let` 不跨请求存活（每请求重建模块） | 状态落库（模板迁移 0009 先例）或 oj 持久面 |
 | `ojm build` 报 `introspect api.ts: jwt not configured` | 模块级语句碰运行时全局，introspect 空沙箱炸 | 移进 handler 函数体内（manual §1.7-4） |
 | 页签怎么点都关不掉、无报错提示 | `beforeClose` 守卫 fail-safe 否决（守卫抛错按取消处理） | 先查控制台 `[tabs] beforeClose` 报错；确认弹窗逻辑与 `resolve(true/false)` 收口（manual §6.4） |
 
 ## 手册
 
-`manual.md`（同目录）共 12 章：1 工程结构（含 **§1.7 handler 四红线**——oj 运行时实测钉出，
-后端 handler 必读）/ 2 写前端模块 / 3 契约与代码生成 / 4 接管框架内置功能（provider）/
-5 布局与插槽 / 6 i18n 与样式 / 7 构建与发布 / 8 排查 / 9 参考 / 10 CLI 子命令参考
-（ojm 原生命令 vs oj 透传命令的差异区分）/ 11 方案包打包与分发 / 12 签名与信任。
+`manual.md`（同目录）共 13 章：1 工程结构（module-root 单树 / 两处产物根 / **§1.7 handler 四红线** /
+**§1.8 `#` 别名与 TS 投影**——oj 运行时实测钉出，后端 handler 必读）/ 2 写前端模块 /
+3 契约与代码生成 / 4 接管框架内置功能（provider）/ 5 布局与插槽 / 6 i18n 与样式 / 7 构建与发布 /
+8 排查 / 9 参考 / 10 CLI 子命令参考（ojm 原生命令 vs oj 透传命令的差异区分）/
+11 方案包打包与分发 / 12 签名与信任 / 13 方案菜单归组规则。

package/devkit/framework-dev.md

@@ -1,7 +1,8 @@
 # 框架贡献者路线（仅本仓）
 
 > 读者：改 `packages/runtime/`、`packages/cli/` 的人。
-> **业务工程里用不到本文件**——那些工程只有 `web/src` + `api/src`，
+> **业务工程里用不到本文件**——那些工程是「一棵源码树 + 一个配置」：
+> `src/<模块>/{api,web}` + 工程根 `config.yaml`（历史布局为 `web/src` + `api/src`），
 > 没有 `packages/`。业务开发看 `SKILL.md` + `manual.md`。
 
 ## §1 先读哪份文档
@@ -20,7 +21,7 @@
 > ⚠️ 那两份 guide 有**已知陈旧处**，以源码为准：
 > dev 端口实际是 **3333**（guide 写的 5173 已过时；注意与 `ojm dev` 的前端 devServer
 > **5174** 不是一回事——前者是本仓 vite，后者是业务工程 devServer）；包版本以
-> `packages/*/package.json` 为准（撰写时实际 **0.2.8**，仅供参考，以当前 package.json 为准）。
+> `packages/*/package.json` 为准（撰写时实际 **0.2.20**，仅供参考，以当前 package.json 为准）。
 
 ## §2 两包结构与依赖方向
 
@@ -103,7 +104,7 @@ pnpm test tests/shell                       # 宿主全量
 | 不变式 | 说明 |
 |---|---|
 | scoped request 在 onInit 绑定 | `onInit` 里绑定 scoped request |
-| 契约前缀字面相等 | uni-dev 形态 `apiPrefix` 必须字面等于目录名 |
+| 契约前缀字面相等 | 路由前缀取 `manifest.yaml` 的 `name`（0.1.85 起与目录名脱钩）；uni-dev 历史形态下 `apiPrefix` 必须字面等于目录名 |
 | 模块仅 import 三类（`#src` 双声明） | `#src/*` 由 package.json `imports` 与 vite alias 双声明 |
 | 模块元信息从 entry.ts 解析 | 模块 name/version 从 `entry.ts` 解析（esbuild bundle + 真实 `import()`） |
 | 生产产物不含 fake | 生产构建不含 fake 代码（**有测试断言产物里无 fake**） |
@@ -138,7 +139,7 @@ pnpm test tests/shell                       # 宿主全量
 **一键发布**：`node scripts/publish-packages.mjs`（lockstep 门禁 → 构建 → 守卫测试 →
 runtime → cli → registry 复核；`--dry-run` 只演练）。下面的手动步骤是它的展开参考。
 
-- **两包**同版本号（`@oj-module/runtime` + `@oj-module/cli`，当前 `0.2.8`），后续发版保持
+- **两包**同版本号（`@oj-module/runtime` + `@oj-module/cli`，当前 `0.2.20`），后续发版保持
   lockstep；`@plane/kit` / `@plane/editor` 不在发布集内（脚本里已注释）。
 - **必须 `pnpm publish`**——用 `npm publish` 会漏出 `workspace:*` / `catalog:` 字面量。
 - **顺序：先 `runtime` 后 `cli`**。`runtime` 未公开时，新 `cli` 的精确依赖会悬空，
@@ -186,7 +187,7 @@ runtime → cli → registry 复核；`--dry-run` 只演练）。下面的手动
 
 ## 附：本 devkit 内容来源（维护者看）
 
-`docs/devkit/` 是**自包含**的交付文档（顶层 5 个文件，含
+`docs/devkit/` 是**自包含**的交付文档（顶层 6 个文件，含
 `sql-builder-missing-capabilities-pr.md` 这份构造器能力缺口 PR 参考），业务工程拿到即可读懂，不依赖工程仓库里的其它文档。
 另有 `oj-api-dev/` 子目录是 oj 侧 devkit 的快照（10 文件，仅本仓参考、不发货），
 结构说明见 `README.md`。