@oj-module/cli 0.2.64 → 0.2.67

package/bin/.oj-version

@@ -0,0 +1 @@
+v0.1.123

package/bin/oj

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/bin/oj
+size: 126034368 bytes
+sha256: 6774d629abecdd96a84bed71ed220ce85ae46bbbe9a818819eca87a5b5d50be6

package/devkit/README.md

@@ -1,15 +1,22 @@
 # oj-module DevKit——模块开发手册 + agent skill
 
+> **你在哪读这份文件？** 两种视图，内容同一份：
+> - **业务工程里**（`.claude/skills/ojm-module-dev/`）：文件是随 `@oj-module/cli` 分发的**副本**，
+>   直接读 `SKILL.md` / `manual.md` / 两本企微手册 / `publish-walkthrough.md` 即可闭环；
+>   下文出现的 `docs/devkit/`、`packages/cli/` 是**框架仓库路径**，只用来解释文件怎么来的，
+>   你本地没有也不影响使用。
+> - **框架仓库里**（`docs/devkit/`）：这里才是源文件，改文档只改这一处。
+
 面向用 `ojm` 开发前后端一体工程的开发者与 AI agent。本目录是**源文件**，
 发布时由 cli 的 `prepack`（`packages/cli/scripts/sync-devkit.mjs`）把其中
-**ojm 侧的 9 个文件**同步进 `packages/cli/devkit/`，随 `@oj-module/cli`
+**ojm 侧的 11 个文件**同步进 `packages/cli/devkit/`，随 `@oj-module/cli`
 发布，再由 `ojm init` 分发到工程内。
 
 整棵树覆盖前后端两侧，但仍是**两套独立分发的 skill**（同名不同物，别混）：
 
 | 侧 | 本仓位置 | 用户工程里的落点 | 分发链 |
 |---|---|---|---|
-| ojm 模块开发（前端模块、契约、前后端对接） | 本目录顶层 9 个文件 | `.claude/skills/ojm-module-dev/` | `@oj-module/cli` 包 → `ojm init` 第 4b 步 |
+| ojm 模块开发（前端模块、契约、前后端对接） | 本目录顶层 11 个文件 | `.claude/skills/ojm-module-dev/` | `@oj-module/cli` 包（全部 11 个）→ `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 的
@@ -25,13 +32,20 @@
 |---|---|
 | `SKILL.md` | Claude Code 等 agent 的 skill 入口：工作流、红线、新模块 checklist、陷阱速查，按章节号引用手册 |
 | `manual.md` | 模块开发手册（14 章）：工程结构（module-root 单树 + 两处产物根；含 §1.7 handler 四红线——oj 运行时实测钉出，后端必读；§1.8 `#` 别名与 TS 投影）、写模块、契约与代码生成（含 §3.10 旧 contract.ts 工程迁移指南）、provider 接管（覆盖框架内置功能）、布局、i18n、构建发布、排查、CLI 子命令参考（ojm 原生命令 vs oj 透传命令）、方案包打包与分发（含 §11.1.1 引用式方案）、签名与信任、§13.1.1 web.route_prefix 自定义根路径、**§14 组织架构与通讯录**（内置部门/成员底座 + 共享读面 7 端点 + `scope` 两级门禁 + 归属权四条规则 + 源适配器接点，选人与按部门算人都读它） |
-| `publish-walkthrough.md` | 方案包发布全流程（**新手照做版**）：构建打包 → keygen 签名 → `market publish` 落 CDN → build-index → verify/trial 验证 → install + TOFU，含多人各自独立发包纪律与失败速查（手册 §11/§12 的过程版） |
+| `publish-walkthrough.md` | 方案包发布全流程（**新手照做版**）：构建打包 → **拿发布身份（「发布管理」申请凭证 → `ojm keygen --credential`；无站点才用离线 `--id`）** → 签名 → `market publish` 落 CDN → build-index → verify/trial 验证 → install + TOFU，含多人各自独立发包纪律与失败速查（手册 §11/§12 的过程版） |
 | `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 项诉求的闭环记录 |
 | `menu-rules.md` | 方案菜单归组规则专题：单根模块约定、自定义根路径 `web.route_prefix`、`category` 三值语义、admin 重写与视觉归组（手册 §13 的展开版） |
 | `wecom-daikaifa.md` | 企业微信代开发集成：**凭据清单**（8 项 `vars`，按 Tier A/B/C 分层的来源与必填时序 + 可信域名/可信 IP 备案）、首次开通顺序（含 `suite_ticket` 依赖与引导期死锁的破法）、**用户 / 开发 / 部署三角色手册**、错误文案速查、与自建应用共存的语义变化 |
 | `wecom-internal-app.md` | 企业微信**企业内部应用（自建应用）**集成：5 项 `wecom_corp_*` 凭据 + 2 项复用、回调只填「通讯录同步」一处、「验证并接入」四步自检、可见范围与可信 IP/域名、单企业私有化的边界（自建应用收不到成员变更事件）、共存配置、故障速查 |
+| `wecom-multi-corp-links.md` | **平台运维 / 服务商运营**：一套部署服务 N 家企业的**专属登录链接运维清单**（方案一，运维零代码改动）——前置检查、逐企业接入 6 步、链接格式与参数、员工四入口、逐企业验收打勾、故障速查、日常运维；含企微工作台内早跳透传 `corp`/`agent` 的修复说明 |
+
+> 上表 10 项 + 本文件 `README.md` = 顶层 11 个文件，全部随 cli 包发货。
+> `ojm init` 第 4b 步**只分发其中 6 个**给业务工程：`SKILL.md` / `manual.md` / `README.md` /
+> `wecom-daikaifa.md` / `wecom-internal-app.md` / `publish-walkthrough.md`。
+> 其余 5 个（`framework-dev.md`、`menu-rules.md`、`module-dev-and-cdn-playground.md`、
+> `sql-builder-missing-capabilities-pr.md`、`wecom-multi-corp-links.md`）是框架贡献者或专题材料，只在 cli 包内可取。
 
 后端 handler 本身的写法（`json` 信封、`db` 查询、`manifest.yaml`、`oj test`）、
 站点挂载（`mounts`）、密钥信封（`secrets`）、vars、cors、schema 校验、broker/tasks/oidc/ws 等
@@ -115,6 +129,6 @@ flowchart LR
   框架贡献者要把本仓快照同步到新版：从 `~/.local/share/oj/devkit/` 整目录覆盖
   `docs/devkit/oj-api-dev/`（oj v0.1.116 起 12 个文件，保持逐字节一致以便对账）。
 
-> 本目录顶层 9 个文件是**自包含**的：业务工程拿到即可读懂，不需要工程仓库里的
+> 本目录顶层 11 个文件是**自包含**的：业务工程拿到即可读懂，不需要工程仓库里的
 > 其它文档。`oj-api-dev/` 子目录是 oj 侧快照，同样自包含（其自身 README 即索引），
 > 但不随 cli 包发货、仅本仓参考。维护者视角的内容来源整理在 `framework-dev.md`（仅本仓）。

package/devkit/SKILL.md

@@ -19,7 +19,8 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
    接管通知/上传/菜单 → §4；换布局或加插槽 → §5；排查 → §8；
    **组织架构 / 通讯录（选人、按部门算收件人、接 LDAP 等新来源）→ §14**；
    **接通企业微信（代开发 / 企业内部应用 / 两套共存）→ `wecom-daikaifa.md` + `wecom-internal-app.md`**；
-   **把方案包发出去（打包/签名/CDN/安装一条链，新手照敲）→ `publish-walkthrough.md`**。
+   **把方案包发出去（打包/签名/CDN/安装一条链，新手照敲）→ `publish-walkthrough.md`**
+   （发布身份走站点凭证见其 §2.1）。
 2. **建目录**：一个目录 = 一个模块——前端一侧 `src/<模块名>/web/`（`entry.ts` 必备，
    `pages/`、`locales/` 按需），后端一侧 `src/<模块名>/api/`（目录镜像路由的 `api.ts`，
    动词挂 `.schema`）。两侧可只存在一侧。
@@ -70,8 +71,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。
@@ -138,6 +141,30 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
   同步/事件增量与回调解密是**两条独立纪律**：回调必须回 `success`，而事件处理失败**也照样回 `success`**
   （重推补不回已判死的失败，兜底是下一轮全量同步）。
 
+## 发布身份（keygen 从哪来）
+
+签名前的第一件事是拿到一对 Ed25519 密钥。**两条路，二选一**：
+
+| 路径 | 命令 | 何时用 |
+|---|---|---|
+| 站点凭证（推荐） | `ojm keygen --credential <token>` | 站点有「方案市场 → 发布管理」页；key_id 由站点按产品名+账号下发（信任仍需首装核对） |
+| 离线自建（旁路） | `ojm keygen --id <publisher>.<key-name>` | 只在站点没有「发布管理」页（纯自建/离线 CDN）或 CI 临时密钥时用 |
+
+站点有「方案市场 → 发布管理」页时**不要自建 key_id**：站点侧没有这条身份记录，产品归属与申请人无从追溯，
+能不能装只能靠超管为陌生指纹手工放行。
+
+- 凭证是**一次性兑换令牌**：站点「方案市场 → 发布管理 → 申请发布凭证」填产品名 → 明文只显示一次 →
+  本机 `ojm keygen --credential <token>`（或 `OJM_PUBLISH_CREDENTIAL=<token> ojm keygen`，
+  免得令牌进 shell 历史）。兑换成功即作废，失败（已用/过期/撤销/网络不通）**不落任何密钥文件**。
+- 站点地址优先级：`--site-url` > `OJM_SITE_URL` > `http://127.0.0.1:9778`；兑换端点匿名可达，
+  **不需要 `--user/--pass`**。`--credential` 与 `--id` 互斥（同时给 exit 2）。
+- 下发的 key_id 形如 `<产品名>.<编码后用户名>`（例：`demo-solution.wecom-everpan`），CLI 不做推导；
+  它同时是 `~/.ojm/keys/<key_id>/` 的目录名——**不要拿它拼路径或改名**，否则签名侧找不到私钥。
+  凭证只解决「身份命名与归属」，**不预置信任**：公钥在本地生成，站点兑换时拿不到，首装照样
+  `needs_trust`，仍要核对指纹。
+- 两条路的私钥纪律完全一致：只活在 `~/.ojm/keys/<id>/`、不入仓不入包、一次发布固定一把。
+  签名/发布/安装全流程见 `publish-walkthrough.md`（§2 凭证、§2.1 离线旁路、§3 签名起）。
+
 ## 新模块 checklist
 
 - [ ] `src/<模块>/web/entry.ts` 默认导出 `defineModule({ name, version, routes, i18n?, lifecycle? })`
@@ -208,6 +235,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） |
 
 ## 手册
 
@@ -226,3 +254,7 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 五项 `wecom_corp_*` 从哪取、回调为什么只填「通讯录同步」一处、「验证并接入」的四步自检、
 可见范围 / 可信 IP / 可信域名的处置、单企业私有化的边界（自建应用收不到成员变更事件）、
 以及和代开发共存时的配置与页面差异。**接自建应用时先读它**。
+
+另有 `publish-walkthrough.md`（同目录）：从「代码写完」到「装进站点」的一条命令链——
+构建/打包 → 拿发布身份（凭证或离线）→ 签名 → 落 CDN → 重建索引 → verify/trial → install/TOFU，
+每步带期望输出与通过判据。**第一次发包照着它敲**。

package/devkit/framework-dev.md

@@ -15,13 +15,19 @@
 | 框架开发完整指南（契约层/运行时/宿主/工具链四章） | `docs/prd/framework-development-guide.md` |
 | 端到端可重复验证流程 | `docs/prd/framework-verification-playbook.md` |
 | 某特性的设计与评审记录 | `docs/prd/<日期>-<特性>-design.md` |
-| 各阶段实战记录（骨架→注入→认证→CRUD→release） | `apps/playground-oj/docs/phase*.md` |
+| 各阶段实战记录（骨架→注入→认证→CRUD→发布） | `docs/prd/framework-verification-playbook.md` 附录 A 基线表（playground 已下线） |
 | 后端 handler 写法 | `docs/devkit/oj-api-dev/api-manual.md`（`oj-api-dev` skill 的本仓快照；用户工程侧在 `.claude/skills/oj-api-dev/`，随 oj 二进制分发） |
 
+> **路径口径**：上表除 `CLAUDE.md` 与 `docs/devkit/oj-api-dev/` 外，都是**框架仓库内**的路径，
+> 不随 `@oj-module/cli` 发货。本文件只对「能进框架仓库的人」有用——如果你是在 cli 包或
+> 业务工程里读到这里，说明没有仓库上下文，那些链接按设计不可达，**不是坏链**：业务开发
+> 请回 `SKILL.md` + `manual.md`。
+
 > ⚠️ 那两份 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 +44,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 +79,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 +148,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 +178,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 后要同步快照：
@@ -187,9 +197,10 @@ runtime → cli → registry 复核；`--dry-run` 只演练）。下面的手动
 
 ## 附：本 devkit 内容来源（维护者看）
 
-`docs/devkit/` 是**自包含**的交付文档（顶层 6 个文件，含
-`sql-builder-missing-capabilities-pr.md` 这份构造器能力缺口 PR 参考），业务工程拿到即可读懂，不依赖工程仓库里的其它文档。
-另有 `oj-api-dev/` 子目录是 oj 侧 devkit 的快照（10 文件，仅本仓参考、不发货），
+`docs/devkit/` 是**自包含**的交付文档（顶层 11 个文件，全部随 cli 包发货，其中 6 个随
+`ojm init` 进业务工程；含 `sql-builder-missing-capabilities-pr.md` 这份构造器能力缺口 PR 参考），
+业务工程拿到即可读懂，不依赖工程仓库里的其它文档。
+另有 `oj-api-dev/` 子目录是 oj 侧 devkit 的快照（oj v0.1.116 起 12 文件，仅本仓参考、不发货），
 结构说明见 `README.md`。
 下面的来源仅用于维护时追溯与同步，不参与交付：
 

package/devkit/manual.md

@@ -35,7 +35,6 @@
 ├── env.d.ts               # ImportMeta.env 类型补丁
 ├── types/oj-modules.d.ts  # `declare module "#*"` 别名兜底（非模块文件的 ambient 声明）
 ├── .ojm-api-exempt.json
-├── seed.mysql.sql / seed.pg.sql
 ├── vitest.config.ts       # 后端 BDD（include tests/**/*.spec.ts）
 ├── tests/                 # 后端 BDD 测试（node:sqlite 内存库 + 真实迁移建表）
 ├── src/
@@ -60,7 +59,9 @@
 │   │       ├── auth/      #   仅 __client（无页面）
 │   │       ├── _platform/ #   仅 __client（oj-market 引用）
 │   │       └── web/       #   仅 __client
-│   ├── oj-market/web/     # 解决方案市场（独立模块，删目录即下线）
+│   ├── oj-market/web/     # 解决方案市场（独立模块，删目录即下线；单根 /oj-market 挂三个子页）
+│   │   ├── entry.ts       #   routes 聚合：/oj-market 根（方案清单 index）+ 发布管理/发布历史子路由
+│   │   └── publish/       #   发布管理 + 发布历史（/oj-market/publish、/oj-market/history：routes + pages + locales + __client）
 ├── dist/api/              # 后端产物（release 根：<name>-<ver>/ + manifests.yaml + versions.json）—构建后才有
 ├── dist/web/              # 站点产物（shell + modules/ + modules.json）—构建后才有
 ├── bin/                   # oj 二进制 + plugins/ + devkit/（不入库）
@@ -198,11 +199,25 @@ src/<模块>/api/<路径...>/api.ts   →   /api/<模块>/<路径...>
 | 文件 | 何时生效 |
 |---|---|
 | `migrations/*.sql` | 启动（dev `migrate_on_start: auto`）；release 默认 `verify`，账本落后则**拒绝启动** |
-| `seed.sql` | **每次启动都重放**（sqlite 默认库）——必须幂等，用 `INSERT OR IGNORE` |
+| `seed.sql` / `seed.<方言>.sql` | **每次启动都重放**——方言件（`.sqlite` / `.mysql` / `.pg`）存在即胜出、`seed.sql` 兜底、绝不双跑（oj ≥ 0.1.121）；必须幂等 |
 | `schema.yaml` | 声明；加可空列 / 加表 reconcile 能收敛，但**改类型与改名必须走 migrations** |
 
 > `seed.sql` 按 `;` 朴素切分，**注释里不许出现分号字面量**，否则语法错。
 
+> **方言 seed 放好即生效（oj ≥ 0.1.121，已是 `ojm` 最低版本门禁）**：方言件按模块存放
+> （`src/app/api/<模块>/seed.mysql.sql` / `seed.pg.sql`，与基础件同表同条数），启动时按当前库
+> 方言自动选——方言件胜出、`seed.sql` 兜底、**绝不双跑**；成功日志打 `file=` / `dialect=`，
+> 模块只有别的方言件或文件名拼错（如 `seed.postgres.sql`）会 warn，`oj check` 的 seed 检查会报错。
+> 更早的 oj 只认字面 `seed.sql`（会把 sqlite 写法原样下发 mysql/pg → 1064），已低于门禁，
+> `ojm vendor` / `ojm info` 会直接拒绝。工程根**不再**有方言 seed 副本（历史上那份只含部分
+> 设置、且 mysql 侧裸写 `key`，已删除）。
+
+> **框架自带 `_platform` 模块的迁移已压平为单条基线**（`0001__baseline.sql` 及
+> `.mysql.sql` / `.pg.sql` 两个方言版）：新工程按基线一次建表，不再有 0002…0018 的增量链。
+> 老开发库的迁移账本里记着旧序号，**基线不会被重放**——若库结构落后（例如缺新列），
+> 直接删 `api/db.sqlite` 重启即可（dev 自动重跑迁移 + seed），本项目**不提供兼容 shim**。
+> 基线必须三方言同步：只写 sqlite 版会让同一模块在 mysql/pg 部署上建表失败。
+
 ### 1.7 handler 四红线（oj 运行时实测钉出，2026-10-16 RBAC 阶段）
 
 以下四条都是真机冒烟（`ojm init` + `ojm dev`/`build`）实测钉出的 oj 运行时行为，
@@ -391,66 +406,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 +1552,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` 配：
@@ -1852,9 +1934,9 @@ module-root 下数据源是「扫描 + `web.config.ts` 登记」并集（未登
 一个脚手架可放多份用户方案（`ojm new` 逐个生成，各自一份 `src/<name>/solution.yaml`），
 `ojm build --bundle` 无参时全部打包、逐个校验独立出包；框架自带方案自动排除（名单见
 `src/.ojm-builtin.json`，`ojm info` 默认折叠自带模块）。
-**从开发到发布的完整过程视角（新手照做版，含签名/私钥纪律与多人各自发包纪律）见本目录**
-[`publish-walkthrough.md`](./publish-walkthrough.md)；仓内深度过程视角另见
-[`docs/guides/solution-dev-build-publish.md`](../guides/solution-dev-build-publish.md)（不随 cli 包发货）。
+**从开发到发布的完整过程视角（新手照做版，含签名/私钥纪律与多人各自发包纪律）见本目录
+[`publish-walkthrough.md`](./publish-walkthrough.md)**——那份文件同样随包分发、自包含，
+发布链路只读它 + 本章即可闭环。
 
 ### 11.1 打包：`ojm build --bundle`
 
@@ -2008,16 +2090,26 @@ flowchart LR
 ### 12.1 发布流程（作者侧，三步）
 
 ```bash
-# ① 一次性：生成 Ed25519 密钥对（私钥 ~/.ojm/keys/<id>/ 永不出目录——--out 指进工程树须 --yes）
-ojm keygen --id <publisher>.<key-name>
+# ① 一次性：拿发布身份。站点有「方案市场 → 发布管理」页时，用页面签发的一次性凭证兑换（key_id 由站点算好下发，
+#    CLI 不推导；兑换即作废；失败不落任何密钥文件；与 --id 互斥，同时给 exit 2）：
+ojm keygen --credential <token> [--site-url <站点>]
+OJM_PUBLISH_CREDENTIAL=<token> ojm keygen
+
+# ①' 旁路：只在没有「发布管理」页（纯自建/离线 CDN）或 CI 临时密钥时自建 key_id——
+#    站点侧没有这条身份记录，产品归属与申请人无从追溯，只能靠超管为陌生指纹手工放行：
+ojm keygen --id <publisher>.<key-name>   # 私钥 ~/.ojm/keys/<id>/ 永不出目录；--out 指进工程树须 --yes
 
-# ② 每次发布：签名（产物 = 同目录 <tgz>.sig；--check 离线自检，不必靠装失败发现签错）
-ojm sign dist/<name>-<version>.tgz --id <publisher>.<key-name> --check
+# ② 每次发布：签名（--id 填上一步拿到的 key_id；产物 = 同目录 <tgz>.sig；--check 离线自检）
+ojm sign dist/<name>-<version>.tgz --id <key_id> --check
 
 # ③ 安装/分发：.sig 自动探测随包上传
 ojm install dist/<name>-<version>.tgz --site-url <站点> --user superadmin --pass …
 ```
 
+凭证通道的站点地址：`--site-url` > `OJM_SITE_URL` > `http://127.0.0.1:9778`；兑换端点匿名可达，
+不需要 `--user/--pass`。key_id 形如 `<产品名>.<编码后用户名>`（例：`demo-solution.wecom-everpan`），
+由站点按申请时的产品名与账号算好。
+
 宿主验签六码（失败文案双语，`--locale` 切换）：`sig_missing`（缺签）/ `sig_alg`（算法
 不受接受）/ `sig_key`（key_id 命名空间违约）/ `tampered`（验签不过）/ `unknown_key`
 （信任库无此 key → **needs_trust 第五终态**）/ `sig_format`（.sig 结构违约）。
@@ -2026,8 +2118,9 @@ ojm install dist/<name>-<version>.tgz --site-url <站点> --user superadmin --pa
 
 **TOFU = Trust On First Use（首次使用即信任）**：陌生发布方的第一个包，安装器无法判断
 该不该信，于是把公钥指纹摆出来让人核对——核对通过才入库，之后同一 key_id 直接放行。
-信任的建立因此有两条路：**第一方**走模板内置公钥免核对（§12.3），**第三方**走本节的
-人工核对。
+信任的建立因此有两条路：**模板内置的 oj-market 方案**用内置公钥免核对（§12.3），其余来源
+（含你自己 keygen 的身份、站点凭证下发的身份）一律走本节的人工核对——凭证只定 key_id 归属，
+站点在兑换时拿不到你的公钥，无法代为建立信任。
 
 - 信任库 = `.solutions/trusted-keys.yaml`（key_id → 公钥 + added_at；首次绑定不可改，
   轮换 = 新增 key_id）。

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` |