@oj-module/cli 0.2.63 → 0.2.66

package/devkit/README.md

@@ -2,14 +2,14 @@
 
 面向用 `ojm` 开发前后端一体工程的开发者与 AI agent。本目录是**源文件**，
 发布时由 cli 的 `prepack`（`packages/cli/scripts/sync-devkit.mjs`）把其中
-**ojm 侧的 9 个文件**同步进 `packages/cli/devkit/`，随 `@oj-module/cli`
+**ojm 侧的 10 个文件**同步进 `packages/cli/devkit/`，随 `@oj-module/cli`
 发布，再由 `ojm init` 分发到工程内。
 
 整棵树覆盖前后端两侧，但仍是**两套独立分发的 skill**（同名不同物，别混）：
 
 | 侧 | 本仓位置 | 用户工程里的落点 | 分发链 |
 |---|---|---|---|
-| ojm 模块开发（前端模块、契约、前后端对接） | 本目录顶层 9 个文件 | `.claude/skills/ojm-module-dev/` | `@oj-module/cli` 包 → `ojm init` 第 4b 步 |
+| ojm 模块开发（前端模块、契约、前后端对接） | 本目录顶层 10 个文件 | `.claude/skills/ojm-module-dev/` | `@oj-module/cli` 包（全部 10 个）→ `ojm init` 第 4b 步（只分发其中 6 个，见下） |
 | oj API 开发（后端 handler、全局对象、配置、测试） | `oj-api-dev/` 子目录（快照） | `.claude/skills/oj-api-dev/` | **oj 二进制自带**（`bin/devkit/`）→ `ojm init` 第 4 步 / `ojm vendor` 装·升后同步（0.2.57 起共用 `syncOjDevkit`，全量 `.md` **覆盖**——文档始终与已装 oj 版本一致） |
 
 > **`oj-api-dev/` 子目录是快照，不是本仓维护的文档**：它与本机 oj 的
@@ -33,6 +33,12 @@
 | `wecom-daikaifa.md` | 企业微信代开发集成：**凭据清单**（8 项 `vars`，按 Tier A/B/C 分层的来源与必填时序 + 可信域名/可信 IP 备案）、首次开通顺序（含 `suite_ticket` 依赖与引导期死锁的破法）、**用户 / 开发 / 部署三角色手册**、错误文案速查、与自建应用共存的语义变化 |
 | `wecom-internal-app.md` | 企业微信**企业内部应用（自建应用）**集成：5 项 `wecom_corp_*` 凭据 + 2 项复用、回调只填「通讯录同步」一处、「验证并接入」四步自检、可见范围与可信 IP/域名、单企业私有化的边界（自建应用收不到成员变更事件）、共存配置、故障速查 |
 
+> 上表 9 项 + 本文件 `README.md` = 顶层 10 个文件，全部随 cli 包发货。
+> `ojm init` 第 4b 步**只分发其中 6 个**给业务工程：`SKILL.md` / `manual.md` / `README.md` /
+> `wecom-daikaifa.md` / `wecom-internal-app.md` / `publish-walkthrough.md`。
+> 其余 4 个（`framework-dev.md`、`menu-rules.md`、`module-dev-and-cdn-playground.md`、
+> `sql-builder-missing-capabilities-pr.md`）是框架贡献者或专题材料，只在 cli 包内可取。
+
 后端 handler 本身的写法（`json` 信封、`db` 查询、`manifest.yaml`、`oj test`）、
 站点挂载（`mounts`）、密钥信封（`secrets`）、vars、cors、schema 校验、broker/tasks/oidc/ws 等
 属于 **`oj-api-dev` skill** 的范围——`ojm init` 已把它装到工程的
@@ -115,6 +121,6 @@ flowchart LR
   框架贡献者要把本仓快照同步到新版：从 `~/.local/share/oj/devkit/` 整目录覆盖
   `docs/devkit/oj-api-dev/`（oj v0.1.116 起 12 个文件，保持逐字节一致以便对账）。
 
-> 本目录顶层 9 个文件是**自包含**的：业务工程拿到即可读懂，不需要工程仓库里的
+> 本目录顶层 10 个文件是**自包含**的：业务工程拿到即可读懂，不需要工程仓库里的
 > 其它文档。`oj-api-dev/` 子目录是 oj 侧快照，同样自包含（其自身 README 即索引），
 > 但不随 cli 包发货、仅本仓参考。维护者视角的内容来源整理在 `framework-dev.md`（仅本仓）。

package/devkit/SKILL.md

@@ -70,8 +70,10 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 - **上传文件**：当前 `ojm api` 的 openapi 流水线不生成 form 通道的前端 client（文件部件不进 JSON Schema），
   惯例走 antd `Upload` **直连**后端（不经 JSON client），handler 用 `http.files` / `http.file(i)` 读字节，
   仅平级声明 `.response`。不要手写 `content-type`（运行时按 boundary 自动补）。
-- **前端模块的 import 只有三类**：`@oj-module/runtime`、宿主 importmap 提供的共享依赖、
-  自身相对路径。共享依赖不进工程 `dependencies`（宿主提供单例，模块不得打包副本）。
+- **前端模块的 import 只有三类**：`@oj-module/runtime`、共享依赖（裸说明符）、自身相对路径。
+  共享依赖分两档：**宿主 importmap 单例**（`react` / `antd` / `dayjs` …，模块不得打包副本）
+  与**模块自打包**（`echarts` 家族 / `vditor` / `@plane/editor`，宿主不提供、模块自带，
+  体积记在模块产物上）。两档都写 `devDependencies`；分档口径与体积控制见手册 §2.6。
   **拿用户/角色等信息：读走 `useUserStore` / `useAuthStore` / `useAccess`（`AccessControl` 门禁），
   写走契约 client（`ojm api` 生成模块自有 `__client`，或复用 runtime 导出的 `api/rbac` / `api/user`），
   绝不 import 框架 `#src/*`**——设计动机与红线见手册 §2.8。
@@ -208,6 +210,7 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 | `oj build` 报 `#/_platform/...` 找不到模块 | 跨模块别名没在 `manifest.yaml` 的 `deps` 里声明 | 加 `_platform: ^0.1.0`（manual §14.2） |
 | 同步一轮之后本地手建的部门消失了 | 适配器漏了 `origin` 条件（同步与回收都必须只动自己的行） | `markSeen` / `reconcileHidden` 带 `origin`；回收只在「本轮完整零跳过」时执行（manual §14.5） |
 | 组织架构里有这个人，通讯录搜不到 | 他是同步建档（`activated=0`，从没登录过本站），通讯录只出活人 | 正确行为；让他登录一次，或走组织架构读面（manual §14.6） |
+| 以为要外挂 nginx 才有 gzip/br 与长缓存 | `oj serve` 自 0.1.116 内建：br>gzip 协商 + 按文件名哈希判 `immutable`；0.1.118 起明文端口还有 h2c | 零配置即可；但**浏览器连不上 h2c**（只支持 prior knowledge、进程内无 TLS），要让浏览器走 h2 才需要前置 nginx/caddy TLS 终结。CDN 必须按 `Vary: Accept-Encoding` 分键（manual §7） |
 
 ## 手册
 

package/devkit/framework-dev.md

@@ -21,7 +21,8 @@
 > ⚠️ 那两份 guide 有**已知陈旧处**，以源码为准：
 > dev 端口实际是 **3333**（guide 写的 5173 已过时；注意与 `ojm dev` 的前端 devServer
 > **5174** 不是一回事——前者是本仓 vite，后者是业务工程 devServer）；包版本以
-> `packages/*/package.json` 为准（撰写时实际 **0.2.47**，仅供参考，以当前 package.json 为准）。
+> `packages/*/package.json` 为准（本文件随 cli 发布，**不写死包版本号**——版本每轮 lockstep
+> 都会变，写死必然漂移）。
 
 ## §2 两包结构与依赖方向
 
@@ -38,7 +39,9 @@ pnpm 改写成**精确版本**，不是 `^` 范围）。
 - **双入口别搞混**：给模块作者用的加在 `src/index.ts`；框架自己怎么启动看 `src/index.tsx`。
 - `#src/*` alias 指向 `packages/runtime/src/*`（由 `packages/runtime/package.json`
   的 `imports` 字段与 vite alias **双声明**，即「模块仅 import 三类」不变式）。
-- 业务工程**不打包共享依赖**——宿主经 importmap 提供单例。
+- 业务工程**不打包宿主共享依赖**——宿主经 importmap 提供单例。例外是 `shared-deps.ts` 里
+  标了 `bundle: true` 的重型依赖（echarts 家族 / vditor / @plane/editor）：宿主不提供，
+  模块自带，见手册 §2.6。
 
 ## §3 常用命令
 
@@ -71,8 +74,9 @@ pnpm test tests/shell                       # 宿主全量
 
 ### 4.1 四条通用红线
 
-1. **共享依赖只能有一个版本**：安装走 `catalog:`，产物走宿主（cli 内置
+1. **宿主共享依赖只能有一个版本**：安装走 `catalog:`，产物走宿主（cli 内置
    `shell-dist`）importmap 单例。私自写死 `react@18` 会导致「双 React」崩溃。
+   （`bundle: true` 的自打包档不在其列——它们本就由各模块自带。）
 2. **`packages/runtime/dist`、`packages/cli/shell-dist` 随仓库提交**
    （`.gitignore` 为它们开了例外）。**改了源码必须重建并提交产物**，
    否则本地/CI 跑的是旧产物——历史上多次出现「方法不存在」。
@@ -139,7 +143,7 @@ pnpm test tests/shell                       # 宿主全量
 **一键发布**：`node scripts/publish-packages.mjs`（lockstep 门禁 → 构建 → 守卫测试 →
 runtime → cli → registry 复核；`--dry-run` 只演练）。下面的手动步骤是它的展开参考。
 
-- **两包**同版本号（`@oj-module/runtime` + `@oj-module/cli`，当前 `0.2.47`），后续发版保持
+- **两包**同版本号（`@oj-module/runtime` + `@oj-module/cli`，两处 `package.json` 恒等），后续发版保持
   lockstep；`@plane/kit` / `@plane/editor` 不在发布集内（脚本里已注释）。
 - **必须 `pnpm publish`**——用 `npm publish` 会漏出 `workspace:*` / `catalog:` 字面量。
 - **顺序：先 `runtime` 后 `cli`**。`runtime` 未公开时，新 `cli` 的精确依赖会悬空，
@@ -169,13 +173,14 @@ runtime → cli → registry 复核；`--dry-run` 只演练）。下面的手动
   `docs/devkit/` 归置进 cli 包 `packages/cli/devkit/`，随 `@oj-module/cli` 发布
   （`package.json#files` 白名单已含 `devkit`）；
 - `packages/cli/src/init.ts` 第 4b 步：从 cli 包内置 devkit 多拷一份到
-  工程的 `.claude/skills/ojm-module-dev/`（拷 `SKILL.md` / `manual.md` /
-  `README.md`，已存在则幂等跳过）。
+  工程的 `.claude/skills/ojm-module-dev/`（连同企微两本手册与发布 walkthrough，共 6 个文件；
+  已存在则幂等跳过）。`framework-dev.md` / `menu-rules.md` / 教学文档 / SQL 构造器 PR 记录
+  只随 cli 包、不进业务工程——它们是框架贡献者或专题材料，`ojm init` 有意不分发。
 
 `packages/cli/devkit/` 是发布副本、由 prepack 生成，已加进 `.gitignore` 不入库；
 源仍是仓库 `docs/devkit/` 顶层，改文档只动那里一处。
 
-> `docs/devkit/oj-api-dev/` 是 **oj 侧 devkit 的快照**（10 个文件，与
+> `docs/devkit/oj-api-dev/` 是 **oj 侧 devkit 的快照**（12 个文件，与
 > `~/.local/share/oj/devkit/` 逐字节一致），仅供本仓 grep 后端手册，
 > **不随 cli 包发货**（`sync-devkit.mjs` 只同步顶层文件）——用户工程的
 > `oj-api-dev` skill 由 oj 二进制分发。升级本机 oj 后要同步快照：

package/devkit/manual.md

@@ -391,66 +391,113 @@ export default defineModule({
 
 ### 2.6 前端模块能 import 什么
 
-**只有三类**：
+**只有三类来源**：
 
 1. `@oj-module/runtime`（含 `/contract`、`/contract/errors` 子路径）；
-2. 宿主 **importmap 提供的共享依赖**；
+2. 共享依赖（写法上都是裸说明符 import，见下表的两个档位）；
 3. 自身相对路径。
 
-框架内部的 `#src/*` 在构建期被拦。共享依赖由宿主提供**单例**，
-模块工程**不得**打包自己的副本——只在 `devDependencies` 里对齐版本（供 `tsc` 用）。
-
-共享依赖矩阵关键项：`react`、`react-dom`、`react-router`、`@tanstack/react-query`、
-`antd`（含 `locale/*`）、`@ant-design/icons`、`@ant-design/pro-components`、
-`i18next`、`react-i18next`、`zustand`、`dayjs`、`echarts`、`echarts-for-react`、
-`motion`、`@dnd-kit/*`、`keepalive-for-react`、`simplebar-react`、`nprogress`、
-`react-countup`、`ahooks`、`ky`、`clsx`、`tailwind-merge`、`pinyin-pro`、`vditor`。
-查实际矩阵：`pnpm exec ojm info`。
-
-#### vditor（Markdown 编辑器，软共享）
-
-模块侧写法不变：`import Vditor from "vditor"` + `import "vditor/dist/index.css"`。
-两个说明符均由宿主 importmap 供包（`/assets/vditor.js`、`/assets/vditor-index-css.js`），
-模块**不得**再把 vditor 写进 `dependencies` 自打包——放 `devDependencies` 对齐版本供 `tsc` 用。
-资产惰性加载：importmap 只做映射，宿主自身不 import vditor，`/assets/vditor.js` 仅在
-模块产物真正 import 它（进编辑器页）时才被浏览器拉取，不进宿主首屏。
-
-注意：vditor 运行期还要按需加载 lute / i18n / 图标 / 主题 CSS 等资源（默认走第三方 CDN，
-宿主 CSP 通常不放行）。这部分**不随共享资产分发**，由模块自行处理（自注入或指向宿主
-可服务的同源路径）。直接 `import "vditor/dist/..."` 其它深路径会命中前缀 external 但无
-importmap 键，构建期报错——需要新深路径请联系框架方在共享表登记。
-
-### 2.7 本版本共享依赖钉版（0.2.47 快照）
-
-宿主经 importmap 提供以下单例（模块 `devDependencies` 须对齐，供 `tsc` 用）；完整矩阵以
-`pnpm exec ojm info` 为准——**别抄本节表格当真相**，本表是撰写时的快照，升级 cli 后
-以 `ojm info` 输出为准。
-
-| 包 | 钉版 |
-| --- | --- |
-| `react` / `react-dom` | 19.2.8 |
-| `react-router` | 7.18.2 |
-| `@tanstack/react-query` | 5.102.8 |
-| `antd` | 6.6.1 |
-| `@ant-design/icons` | 6.3.2 |
-| `@ant-design/pro-components` | 3.1.12-0 |
-| `i18next` / `react-i18next` | 26.4.0 / 17.0.12 |
-| `zustand` | 5.0.15 |
-| `dayjs` | 1.11.23 |
-| `echarts` / `echarts-for-react` | 6.1.0 / 3.0.6 |
-| `motion` | 12.43.0 |
-| `@dnd-kit/core` | 6.3.1 |
-| `keepalive-for-react` | 5.0.11 |
-| `simplebar-react` | 3.3.2 |
-| `nprogress` | 0.2.0 |
-| `react-countup` | 6.5.3 |
-| `ahooks` | 3.9.7 |
-| `ky` | 2.0.2 |
-| `clsx` / `tailwind-merge` | 2.1.1 / 3.6.0 |
-| `pinyin-pro` | 3.29.3 |
-| `vditor` | 4.0.0 |
-
-框架包版本：`@oj-module/runtime` / `@oj-module/cli` 为 `0.2.47`（**双包 lockstep**，
+框架内部的 `#src/*` 在构建期被拦。
+
+共享依赖按**谁出这份 JS** 分两档。两档写法一样，体积责任与失败形态完全不同——
+把它们混为一谈，是「白屏」和「产物莫名变大一倍」的最常见来源：
+
+| 档位 | 谁提供 | importmap 有键 | 典型包 |
+| --- | --- | --- | --- |
+| **宿主共享（单例）** | `shell-dist` 预构建资产 | 有 | `react` / `react-dom` / `react-router` / `antd`（含 `locale/*`）/ `@ant-design/icons` / `@ant-design/pro-components` / `i18next` / `react-i18next` / `zustand` / `dayjs` / `motion` / `@dnd-kit/*` / `keepalive-for-react` / `simplebar-react` / `nprogress` / `react-countup` / `ahooks` / `ky` / `clsx` / `tailwind-merge` / `pinyin-pro` |
+| **模块自打包** | 模块自己的产物 | **无** | `echarts` 家族、`vditor`、`@plane/editor` |
+
+- 第一档由宿主提供**单例**：模块工程**不得**打包自己的副本（多副本 = 双 store / 双 antd
+  context 树），只在 `devDependencies` 里对齐版本供 `tsc` 用。
+- 第二档宿主**不提供**：模块必须自带，体积记在模块产物上。依赖同样放 `devDependencies`
+  （构建期能解析即可），但要自己控体积——见下面两节。
+
+判定口径：`packages/cli/src/shared-deps.ts` 里带 `bundle: true` 的条目就是第二档。
+版本矩阵查 `pnpm exec ojm info`（宿主 `versions.json`，两档都在里面，故它只回答「钉哪个版本」，
+不回答「谁提供 JS」）。
+
+#### vditor（Markdown 编辑器，模块自打包）
+
+写法：`import Vditor from "vditor"` + `import "vditor/dist/index.css"`。
+
+但这两个说明符**没有 importmap 键**——宿主不预构建 `/assets/vditor.js`，构建时整份打进
+模块产物 `entry.js`（gzip ≈ 700 KiB）。由此有两条推论：
+
+- 动态导入**不能**省这笔体积：模块产物是单文件（`codeSplitting: false`），
+  `import("vditor")` 会被内联回同一个文件。要把它从首屏摘掉，只能把编辑器页拆成独立模块/方案。
+- 运行期还要按需加载 lute / i18n / 图标 / 主题 CSS（默认走第三方 CDN，宿主 CSP 通常不放行）。
+  这部分**不随产物分发**，由模块自行处理（自注入或指向宿主可服务的同源路径）；
+  直接 `import "vditor/dist/..."` 其它深路径会命中前缀 external 但无 importmap 键，构建期报错。
+
+#### echarts（图表，模块自打包 + 必须按需注册）
+
+`echarts` / `echarts/charts` / `echarts/features.js` / `echarts-for-react` 同属第二档。
+**默认写法会把整包打进去**：`import ReactECharts from "echarts-for-react"` 内部是
+`import * as echarts from "echarts"`（index 全量），全部图表类型 + 组件 + 渲染器一起进
+`entry.js`。脚手架实测：单文件 1,697,666 B 里 echarts 918 KB + zrender 221 KB，占 **87%**，
+而首页只画折线/柱状/饼图三种。
+
+按需注册写法（脚手架 `src/app/web/home/pages/components/echarts-setup.ts` 可整段照抄）：
+
+```ts
+// echarts-setup.ts —— 注册清单集中一处，新增图表类型只改这里
+import { BarChart, LineChart, PieChart } from "echarts/charts";
+import { GridComponent, LegendComponent, TooltipComponent } from "echarts/components";
+import * as echarts from "echarts/core";
+import { CanvasRenderer } from "echarts/renderers";
+
+echarts.use([
+  BarChart, LineChart, PieChart,
+  GridComponent, LegendComponent, TooltipComponent,
+  CanvasRenderer,
+]);
+export { echarts };
+```
+
+```tsx
+import ReactEChartsCore from "echarts-for-react/esm/core";
+import { echarts } from "./echarts-setup";
+
+// 组件里渲染：把按需注册过的实例传进去（不传就走整包默认实例）
+return <ReactEChartsCore echarts={echarts} option={option} opts={{ height: 320, width: "auto" }} />;
+```
+
+同一份页面实测：`entry.js` 1,697,666 → **918,319 B（−45.9%）**。
+
+⚠️ 按需注册最容易踩的坑是**静默空白**：少 `use()` 一个图表类型或组件（例如柱状图漏了
+`GridComponent`、图例漏了 `LegendComponent`），echarts 不抛错、只是画不出来。新增图时
+先补注册清单，再用真页面看一眼。
+
+### 2.7 共享依赖钉版（快照，以 `ojm info` 为准）
+
+版本矩阵的真源是宿主 `versions.json`（`pnpm exec ojm info` 直接打印）。下表是撰写时的快照，
+升级 cli 后会变——**别抄表格当真相**；`档位` 列才是长期有效的信息。
+
+| 包 | 钉版 | 档位 |
+| --- | --- | --- |
+| `react` / `react-dom` | 19.2.8 | 宿主 |
+| `react-router` | 7.18.2 | 宿主 |
+| `@tanstack/react-query` | 5.102.8 | 宿主 |
+| `antd` | 6.6.1 | 宿主 |
+| `@ant-design/icons` | 6.3.2 | 宿主 |
+| `@ant-design/pro-components` | 3.1.12-0 | 宿主 |
+| `i18next` / `react-i18next` | 26.4.0 / 17.0.12 | 宿主 |
+| `zustand` | 5.0.15 | 宿主 |
+| `dayjs` | 1.11.23 | 宿主 |
+| `echarts` / `echarts-for-react` | 6.1.0 / 3.0.6 | **自打包** |
+| `motion` | 12.43.0 | 宿主 |
+| `@dnd-kit/core` | 6.3.1 | 宿主 |
+| `keepalive-for-react` | 5.0.11 | 宿主 |
+| `simplebar-react` | 3.3.2 | 宿主 |
+| `nprogress` | 0.2.0 | 宿主 |
+| `react-countup` | 6.5.3 | 宿主 |
+| `ahooks` | 3.9.7 | 宿主 |
+| `ky` | 2.0.2 | 宿主 |
+| `clsx` / `tailwind-merge` | 2.1.1 / 3.6.0 | 宿主 |
+| `pinyin-pro` | 3.29.3 | 宿主 |
+| `vditor` | 4.0.0 | **自打包** |
+
+框架包版本：`@oj-module/runtime` / `@oj-module/cli` 为 `0.2.66`（**双包 lockstep**，
 以 `packages/*/package.json` 或 `ojm info` 为准——本表是撰写时快照）；
 `@plane/kit` / `@plane/editor` 是独立版本线（当前 `0.1.20`，随宿主 importmap 提供，
 不参与 lockstep）。`oj` 二进制最低版本门禁 `MIN_OJ_VERSION = 0.1.85`——这个版本带来
@@ -1490,6 +1537,26 @@ flowchart LR
   例如 `ojm migrate -d api/dist`、`ojm schema diff` 等价于带绝对 `-c` 的 `oj` 调用——
   不用再手敲 `-c`。**完整命令参考与「oj 原生命令 vs ojm 透传」的差异区分见 §10。**
 
+**静态层与传输（oj ≥ 0.1.116 内建，0.1.118 起支持 h2c）**：单服务部署时 `oj serve` 自己就是
+静态服务器，压缩与缓存不必靠外挂 nginx，下面四条直接决定首屏体验：
+
+- **压缩**：默认开，协商 br > gzip，可压资源恒带 `Vary: Accept-Encoding`；压缩产物落
+  `<config_dir>/compress-cache/`（派生数据，可整删重建；只读根设 `compress_cache_dir: ""`
+  走内存直压）。`server.static.brotli_quality` 默认 5（1..=11），q11 能再省约 12% 字节，
+  代价是**每个新版本资产的第一个请求要在线冷压**（实测 antd 单文件 2.2MB 约 1.4s）——
+  流量入口集中、首访敏感就别拉满。
+- **缓存按文件名判**：stem 末段 ≥8 位且数字字母兼具 → `public, max-age=31536000, immutable`；
+  其余一律 `no-cache` 恒校验（`config-production.js` 这类纯字母词不会被误钉）。**所以产物里的
+  共享资产与入口 chunk 必须内容寻址命名**，否则跨版本要么全量重下、要么全量 304。
+  本仓构建期已强制（`hashifySharedAssets` / `hashifyHostEntry`）。
+- **传输**：0.1.118 起明文端口上 h2c（HTTP/2 prior knowledge）与 HTTP/1.1 **同端口共存**，
+  零配置；但**只支持 prior knowledge，没有 `Upgrade: h2c` 路径**，且进程内无 TLS 终结——
+  **浏览器连不上 h2c**。要让浏览器走 h2，必须前置 nginx/caddy 做 TLS-ALPN，反代到源站那一跳
+  可选 h2c。WS 握手仍必须走 HTTP/1.1（无 RFC 8441）。
+- **前置缓存层**：CDN/反代**必须按 `Vary: Accept-Encoding` 分键**；确认不了就让
+  `server.static.compression: false`，压缩交给前置层一家做——两层都压等于白费 CPU 且易出
+  「br 解成乱码」。
+
 **按路由注入 HTML（`htmlTransform`，SEO / IM 链接预览）**：SPA 的服务端只有一份
 `index.html`——想让 `/issues/<id>` 这类路由带自己的 `<title>`/`og:*`（微信、Slack、飞书预览
 与不执行 JS 的爬虫只看服务端 HTML，客户端 `document.title` 无效），在 `web.config.ts` 配：

package/devkit/menu-rules.md

@@ -278,7 +278,7 @@ export default {
 
 | 位置 | 动作 | 不配的后果 |
 |---|---|---|
-| `<dist>/index.html` | importmap 映射值、`<script src>`、`<link href>` 统一加 `/oj` 前缀 | HTML 指向 `/assets/react.js`，在 `/oj` 挂载下 404 → 白屏 |
+| `<dist>/index.html` | importmap 映射值、`<script src>`、`<link href>` 统一加 `/oj` 前缀 | HTML 指向 `/assets/react.<hash>.js`，在 `/oj` 挂载下 404 → 白屏 |
 | `<dist>/index.html` | `<head>` 注入 `<script nonce>window.__OJ_BASE__="/oj/"</script>`（复用 importmap 的 nonce，否则被 CSP 拦掉） | 运行期拿不到真实部署前缀 |
 | 运行期 Router | runtime 与宿主 shell 都经 `resolveSiteBase()` 取 basename，即 `window.__OJ_BASE__` | Router 不剥 `/oj`，`/oj/wiki/...` 匹配不到 `/wiki/...`（深链刷新落 404 页） |
 
@@ -302,6 +302,9 @@ export default {
 
 实测依据（2026-10-21，站点以 `mounts: [{prefix: /oj, web: web/dist, spa: true}]` 挂起）：
 
+> 下表的资产文件名是当时的 `/assets/react.js`。当前产物改为内容寻址命名
+> （`/assets/react.<hash>.js`，10 位 base36），**前缀判断逻辑不变**，只是文件名多一段哈希。
+
 | 请求 | 结果 | 说明 |
 |---|---|---|
 | `GET /oj/wiki/space/3/doc/12` | `200 text/html` | 深链回落本身是通的，前提是该挂载显式 `spa: true` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.63",
+  "version": "0.2.66",
   "description": "React Antd 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
@@ -49,10 +49,11 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.2.63",
+    "@oj-module/runtime": "0.2.66",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "cac": "^6.7.14",
+    "es-module-lexer": "^2.3.2",
     "esbuild": "^0.28.2",
     "tailwindcss": "^4.3.0",
     "tsx": "^4.23.12",