@oj-module/cli 0.2.27 → 0.2.28

package/devkit/README.md

@@ -24,7 +24,7 @@
 | 文件 | 用途 |
 |---|---|
 | `SKILL.md` | Claude Code 等 agent 的 skill 入口：工作流、红线、新模块 checklist、陷阱速查，按章节号引用手册 |
-| `manual.md` | 模块开发手册（13 章）：工程结构（module-root 单树 + 两处产物根；含 §1.7 handler 四红线——oj 运行时实测钉出，后端必读；§1.8 `#` 别名与 TS 投影）、写模块、契约与代码生成（含 §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 透传命令）、方案包打包与分发（含 §11.1.1 引用式方案）、签名与信任；含 §13.1.1 web.route_prefix 自定义根路径 |
 | `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 项诉求的闭环记录 |

package/devkit/manual.md

@@ -822,7 +822,8 @@ export default { get };
    逐个改 import 与调用；`tsc --noEmit` 应收敛到 0 错误。
 6. **删旧文件**：删除各 `contract.ts`，以及旧流水线产物 `routes.json` /
    `openapi.yaml`（模块目录下；ojm 不再自产。`ojm api --docs` 渲染的静态文档站另放：
-   module-root → 工程根 `docs/api/`，历史布局 → `api/docs/`，保留）。
+   `<projectRoot>/src/docs/<name>/api`（与模块树同位、树外，不参与模块枚举与 handler 路由扫描，
+   杜绝 docs 被当 handler 镜像导致端点翻倍；legacy 布局同形、落在 `api/src` 扫描树外，保留）。
 7. **对账**：`ojm api --check` 应 `0 error / 0 warn`；内置端点（`auth/*`、`web/*`、
    `notification/*`）经 `.ojm-api-exempt.json` 豁免（init 已内置）。
 
@@ -1681,6 +1682,9 @@ ojm build --bundle crm           # 打包
 ```
 
 
+> 生成的 `src/<name>/solution.yaml` 不再写出 `web.route_prefix: /<name>`（与缺省重复），只在
+> `web` 段留一行注释；要自定义根路径时取消注释改值即可（见 §13.1.1）。
+
 #### `ojm preview [port]`
 
 生产形态预览（设计 §6，2026-10-19 单服务化）：
@@ -1705,8 +1709,11 @@ ojm build --bundle crm           # 打包
 - `dir`：项目目录（缺省 `cwd`；显式目录必须先存在，否则报错）。
 - `--check`：**四重对账**（只读、绝不写盘）：① 生成物同步 ② route 双向对账
   ③ `routes.js` diff ④ WS 路由鉴权（§3.6）。
-- `--docs`：聚合 OpenAPI → redoc 自包含静态文档站（离线可看），落 `<cwd>/docs/api/`
-  （历史布局 `<cwd>/api/docs/`）。
+- `--docs`：聚合 OpenAPI → redoc 自包含静态文档站（离线可看），落
+  `<projectRoot>/src/docs/<name>/api`（与模块树同位、树外——不参与模块枚举与 handler 路由扫描，
+  杜绝 docs 被当 handler 镜像导致端点翻倍 `wikiDocsDocs*`）。`name` 推导：cwd 为 `src/<name>/api`
+  时取父目录名；module-root 单模块时取该模块名；否则回退工程目录名（legacy 布局同形，
+  落在 `api/src` 扫描树外）。
 - `--exempt <path>`：指定豁免清单，覆盖默认探测顺序 `.ojm-api-exempt.json` →
   `api/.ojm-api-exempt.json` → `api/.ram-api-exempt.json`（旧名回退），§3.8。
 
@@ -1830,6 +1837,24 @@ ojm build --bundle crm        # 只打 src/crm/ 这一份；--bundle=crm 等价
 - **入包红线**：`*.pem` / `*.key` / `*.p12` / `*.pfx` / `.env` 系 / `id_ed25519` / `id_rsa`
   等私钥形态文件禁入包（与 `modules.json` 禁入同款自检，0.2.23 起扩面）——私钥入包即信任根基烧毁。
 
+#### 11.1.1 引用式方案：`api` 段省略 `tables` / `deps`
+
+方案包契约的 `api` 段有两种合法形态：
+
+- **全量形态**：给出 `tables` 与/或 `deps`（外加 `module` / `prefix` / `anonymous` 等），
+  契约按全量校验，`api.tables` 须与 `api/src/<name>/schema.yaml` 表集逐一相等（oj 冗余校验同源）。
+- **引用形态**：`api` 段只给 `module` / `prefix` 等、**省略 `tables` 与 `deps`**——表与依赖清单
+  **引用包内** oj 原生 `<module>/manifest.yaml`（七键清单，tgz 打包时已随包携带）。契约**显式承认**
+  此形态（不再仅靠字段可选性漏过），安装期 `extract` 阶段读回该原生 manifest 做占用检测与依赖装配
+  （`_platform` 除外）；两字段任一给出即按全量优先。
+
+`ojm build --bundle` 校验通过后会打印一行提示，避免把省略误读成漏配：
+
+```
+[ojm] 引用式方案：api.tables/api.deps 缺省，引用包内 api/<name>-<version>/manifest.yaml
+       （安装期复核其存在，依赖装配据其回读，非漏配）
+```
+
 ### 11.2 两种分发源
 
 | 源 | 形态 | 说明 |
@@ -2011,6 +2036,45 @@ export default defineModule({
 });
 ```
 
+#### 13.1.1 自定义模块根路径：`web.route_prefix`
+
+单根约定下，模块根路由首段默认就是模块名 `name`（即 `web.route_prefix` 缺省 `/<name>`）。
+要换根（比如让 `wiki` 模块挂在 `/kb`），在 `src/<name>/solution.yaml` 的 `web` 段声明：
+
+```yaml
+web:
+  route_prefix: /kb   # 形如 /<小写字母开头，字母数字短横线>
+```
+
+构建期 `ojm build` 会把**生效前缀段**（`kb`，去首斜杠）写进 `modules.json` 每个模块条目的
+`routePrefix` 字段；运行时模块加载器据此**只改写路由根段**（单根约定下仅首段——
+`applyRoutePrefix` 保持原 path 的前导斜杠风格：相对 `wiki`→`kb`、绝对 `/wiki`→`/kb`，
+children 不变）。因此**缺省（不声明）= name 时路径字段逐字节不变（零漂移）**，已有模块升级无感。
+
+改写后 `rewriteAdminPaths` 会自动跟随（它从顶层路径推导根），`category: "admin"` 的路由落到
+`/system/<前缀>/admin`，菜单归组一并跟随——菜单、深链、模块内跳转、tab 键、admin 提升全部落在
+同一个根。
+
+模块内路径**不要硬编码根段**，统一经 `getModuleRoutePrefix(name)` 单点消费（运行时导出，读
+`modules.json` 的 `routePrefix`，未声明回落 `name`）：
+
+```ts
+// paths.ts：把根段参数化，所有 navigate / Link / matchPath 都从它派生
+export const createWikiPaths = (root: string) => ({
+  home: `/${root}`,
+  space: `/${root}/space`,
+  admin: `/${root}/admin`,
+});
+
+// 使用时懒取（组件渲染 / 事件处理内），不要缓存到模块顶层常量——
+// 模块静态求值期模块表尚未就绪，须等 loadAll 之后才取值
+import { getModuleRoutePrefix } from "@oj-module/runtime";
+const paths = createWikiPaths(getModuleRoutePrefix("wiki"));
+```
+
+> `ojm new` 生成的骨架不再写出 `route_prefix: /<name>`（与缺省重复），只留注释，需要时取消
+> 注释改值即可（见 §10.1）。
+
 ### 13.2 category 三值语义
 
 `handle.category`：
@@ -2025,6 +2089,7 @@ export default defineModule({
 
 - 模块根菜单标题与 /system 下的管理子组标题**共用** `<模块>:menu.main` 一个 i18n key（嵌套在 `menu.main`，是模块级标题的唯一真源，缺则构建期 fail-fast）。
 - 模块内所有前端路径——`navigate` / `Link to` / `useMatch`·`matchPath` / `currentActiveMenu` / SEO 正则——统一从模块基路径助手（如 `paths.ts` 的 `wikiPath(...)` / `wikiBase`）派生，不散落 `/wiki/...` 字面量；`currentActiveMenu` 必须写绝对路径（指向真实菜单 key）。`tree/bus.ts` 的 room 名是后端 WS 契约，非前端路由，不动。
+- 模块基路径的真源是 `getModuleRoutePrefix(name)`（运行时导出，读 `modules.json` 的 `routePrefix`，缺省 `name`）——`paths.ts` 助手应以其为参数，而非写死 `/<name>`；自定义根路径见 §13.1.1。
 
 ### 13.4 开发者的该做 / 别做
 
@@ -2060,6 +2125,6 @@ export default defineModule({
 | §8 排查 | 五步排查法、症状速查表 | 任何「没生效」 |
 | §9 参考 | 可抄的工程内文件、oj-api-dev 手册指引 | 找范本 |
 | §10 CLI 子命令参考 | ojm 原生命令 vs oj 透传命令；`market` 子命令（本地模拟 CDN） | 查命令用法；`ojm <cmd> --help` 看单命令帮助 |
-| §11 方案包：打包与分发 | build --bundle、Form A/B、分发源、索引规范 | 发布方案包 |
+| §11 方案包：打包与分发 | build --bundle、Form A/B、分发源、索引规范、引用式方案（api 段省略 tables/deps，引用包内原生 manifest） | 发布方案包 |
 | §12 签名与信任 | keygen/sign/install 发布流程、信任库、TOFU、bootstrap key | 首次签名发布；管理信任 |
-| §13 方案菜单归组规则 | 单根模块约定（根路由=第一级菜单）、category 三值（普通/hidden/admin）、admin 真重写 `/system/<模块 root>/*` + 视觉归组、menu.main 统一、模块内路径助手、开发者 DO/DON'T | 写方案要让菜单按模块分组、admin 归系统设置 |
+| §13 方案菜单归组规则 | 单根模块约定（根路由=第一级菜单）、自定义根路径 `web.route_prefix`（构建写 modules.json、运行时只改根段、getModuleRoutePrefix 单点消费）、category 三值（普通/hidden/admin）、admin 真重写 `/system/<模块 root>/*` + 视觉归组、menu.main 统一、模块内路径助手、开发者 DO/DON'T | 写方案要让菜单按模块分组、admin 归系统设置 |

package/package.json

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

package/shell-dist/assets/{index-B3g19Uet.js → index-CtTVbohp.js}

@@ -1,5 +1,5 @@
 import { StyleProvider } from "@ant-design/cssinjs";
-import { AntdApp, ErrorBoundary, LayoutEffects, PageError, getRoutes, loadAll, setupI18n, useAuthStore, usePreferences, useUserStore } from "@oj-module/runtime";
+import { AntdApp, ErrorBoundary, LayoutEffects, PageError, getHostRoutes, loadAll, setupI18n, useAuthStore, usePreferences, useUserStore } from "@oj-module/runtime";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { ConfigProvider, theme } from "antd";
 import { useEffect, useState } from "react";
@@ -300,6 +300,7 @@ function Boot() {
 				await hydrateUser();
 				await loadAll(manifest);
 				if (cancelled) return;
+				const hostRoutes = getHostRoutes();
 				setRouter(createBrowserRouter([{
 					path: "/",
 					element: /* @__PURE__ */ jsxs(ErrorBoundary, {
@@ -310,11 +311,11 @@ function Boot() {
 						{
 							index: true,
 							element: /* @__PURE__ */ jsx(Navigate, {
-								to: getRoutes()[0]?.path ?? "/",
+								to: hostRoutes[0]?.path ?? "/",
 								replace: true
 							})
 						},
-						...getRoutes(),
+						...hostRoutes,
 						{
 							path: "*",
 							element: /* @__PURE__ */ jsx(CatchAll, {})

package/shell-dist/assets/runtime.js

@@ -304,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.27",
+			"version": "0.2.28",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-24 00:06:50"
+		"lastBuildTime": "2026-10-24 18:30:15"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -7203,6 +7203,42 @@ var init_resolve_layout = __esmMin((() => {
 	warnedUnknownLayouts = /* @__PURE__ */ new Set();
 }));
 //#endregion
+//#region src/router/utils/rewrite-admin-paths.ts
+/** 解析路由绝对路径（与 generate-menu-items-from-routes 同语义） */
+function resolveAbs(path, parentAbs) {
+	if (!path) return parentAbs;
+	return path.startsWith("/") ? path : `${parentAbs.replace(/\/+$/, "")}/${path}`;
+}
+function rewriteAdminPaths(routes, systemKey = SYSTEM_KEY) {
+	const hoisted = [];
+	return [...routes.map((r) => processRoute(r, "/", systemKey, hoisted, void 0)).filter((r) => r !== null), ...hoisted];
+}
+function processRoute(route, parentAbs, systemKey, hoisted, moduleRootAbs) {
+	const abs = resolveAbs(route.path, parentAbs);
+	const rootAbs = moduleRootAbs ?? abs;
+	if (route.handle?.category === "admin") {
+		const newAbs = `${systemKey}${rootAbs}${abs.slice(rootAbs.length) || ""}`;
+		hoisted.push({
+			...route,
+			path: newAbs
+		});
+		return null;
+	}
+	if (!route.children || route.children.length === 0) return { ...route };
+	const newChildren = [];
+	for (const c of route.children) {
+		const processed = processRoute(c, abs, systemKey, hoisted, rootAbs);
+		if (processed !== null) newChildren.push(processed);
+	}
+	const result = { ...route };
+	result.children = newChildren;
+	return result;
+}
+var SYSTEM_KEY;
+var init_rewrite_admin_paths = __esmMin((() => {
+	SYSTEM_KEY = "/system";
+}));
+//#endregion
 //#region src/store/header-provider.ts
 function registerHeaderProvider(moduleName, provider) {
 	if (current) {
@@ -7378,11 +7414,12 @@ function satisfiesSemver(version, range) {
 var init_semver = __esmMin((() => {}));
 //#endregion
 //#region src/module-loader/index.ts
-function createModuleContext(definition) {
+function createModuleContext(definition, routePrefix) {
 	return {
 		module: {
 			name: definition.name,
-			version: definition.version
+			version: definition.version,
+			routePrefix
 		},
 		utils: { request: createScopedRequest(definition.name, () => registeredApiPrefixes.get(definition.name)) },
 		register: {
@@ -7485,6 +7522,7 @@ async function loadAll(manifest) {
 			console.error(`[module-loader] 模块 "${entry.name}" 与宿主 runtime 版本不兼容：期望 ${peerRuntime}，实际 ${manifest.runtimeVersion}。已跳过加载。修复建议：升级宿主 runtime 或按兼容范围重新构建该模块（US-5）。`);
 			modules.set(entry.name, {
 				definition,
+				routePrefix: entry.routePrefix ?? rootSegmentOf(definition.routes) ?? entry.name,
 				status: "error",
 				error: /* @__PURE__ */ new Error(`模块 "${entry.name}" peerRuntime 不兼容：期望 ${peerRuntime}，实际 ${manifest.runtimeVersion}`)
 			});
@@ -7494,6 +7532,7 @@ async function loadAll(manifest) {
 		validEntries.push(entry);
 		modules.set(entry.name, {
 			definition,
+			routePrefix: entry.routePrefix ?? rootSegmentOf(definition.routes) ?? entry.name,
 			status: "loaded"
 		});
 	} else modules.set(entry.name, {
@@ -7503,6 +7542,7 @@ async function loadAll(manifest) {
 			version: "0.0.0",
 			routes: []
 		},
+		routePrefix: entry.routePrefix ?? entry.name,
 		status: "error",
 		error: /* @__PURE__ */ new Error("Failed to load module entry")
 	});
@@ -7514,6 +7554,7 @@ async function loadAll(manifest) {
 			console.error(`[module-loader] 模块 "${entry.name}" 依赖缺失：${missing.join(", ")} 未加载。已跳过该模块（不执行生命周期、不注册路由）。修复建议：先部署依赖模块，或在清单中移除该依赖（US-9）。`);
 			modules.set(entry.name, {
 				definition,
+				routePrefix: entry.routePrefix ?? rootSegmentOf(definition.routes) ?? entry.name,
 				status: "missing-deps",
 				error: /* @__PURE__ */ new Error(`模块 "${entry.name}" 依赖缺失：${missing.join(", ")}`)
 			});
@@ -7524,7 +7565,7 @@ async function loadAll(manifest) {
 	const sortedEntries = topologicalSort(validEntries, definitions);
 	for (const entry of sortedEntries) {
 		const definition = definitions.get(entry.name);
-		const ctx = createModuleContext(definition);
+		const ctx = createModuleContext(definition, entry.routePrefix ?? rootSegmentOf(definition.routes) ?? entry.name);
 		try {
 			if (definition.lifecycle?.beforeInit) await definition.lifecycle.beforeInit(ctx);
 			if (definition.lifecycle?.onInit) await definition.lifecycle.onInit(ctx);
@@ -7533,6 +7574,7 @@ async function loadAll(manifest) {
 			console.error(`[module-loader] Lifecycle error for "${entry.name}":`, error);
 			modules.set(entry.name, {
 				definition,
+				routePrefix: entry.routePrefix ?? rootSegmentOf(definition.routes) ?? entry.name,
 				status: "error",
 				error: error instanceof Error ? error : new Error(String(error))
 			});
@@ -7556,6 +7598,19 @@ function getModule(name) {
 	return modules.get(name);
 }
 /**
+* 模块生效 web 路由前缀段取值口（R1.3）。
+*
+* 模块内深链/跳转应经此单点消费，勿硬编码根段：
+* `createWikiPaths(getModuleRoutePrefix("wiki") ?? "wiki")`。
+*
+* 注意时序：须在 `loadAll` 之后调用——模块静态求值期 `modules` 未就绪。
+* 模块内导航应懒取（组件渲染 / 事件处理器内），不要缓存于模块顶层常量。
+* 未加载模块回落 `name`（与缺省语义一致）。
+*/
+function getModuleRoutePrefix(name) {
+	return modules.get(name)?.routePrefix ?? name;
+}
+/**
 * 给模块路由打 module 标（R1，0.2.16）：递归 children，非突变返回新对象。
 * module 来自 `definition.name`，作者无需手写——归组据此甄别方案路由、
 * 生成 `solgroup:<category>:<module>` 父键，不再依赖宿主 DB 行。
@@ -7573,6 +7628,35 @@ function tagModuleRoutes(routes, name) {
 		return tagged;
 	});
 }
+/**
+* 按生效前缀改写模块路由根（R1.2，单根约定下仅改首段/根段）。
+* 顶层路由 path 的首段替换为 prefix；children 为相对路径不变。
+* 保持原 path 的「前导斜杠」风格：相对 `wiki` → `kb`、绝对 `/wiki` → `/kb`，
+* 因此缺省 prefix = name 时路径字段逐字节不变（零漂移），仅段值一致。
+*/
+function applyRoutePrefix(routes, prefix) {
+	return routes.map((route) => {
+		const p = typeof route.path === "string" ? route.path : "";
+		const hadLeadingSlash = p.startsWith("/");
+		const firstSeg = p.replace(/^\/?/, "").split("/")[0] ?? "";
+		const afterFirst = hadLeadingSlash ? p.slice(1 + firstSeg.length) : p.slice(firstSeg.length);
+		const newPath = hadLeadingSlash ? `/${prefix}${afterFirst}` : `${prefix}${afterFirst}`;
+		return {
+			...route,
+			path: newPath
+		};
+	});
+}
+/**
+* 取模块路由根段（首段，去前导斜杠）；无路由返回 undefined。
+* 用于 `routePrefix` 缺省：单根约定下根段即模块身份，故缺省前缀 = 根段
+* （约定等于 name；fixture/异常态下 name 与根段不一致时回落根段而非 name，避免改写真实根）。
+*/
+function rootSegmentOf(routes) {
+	const p = routes[0]?.path;
+	if (typeof p !== "string" || p.length === 0) return void 0;
+	return p.replace(/^\/?/, "").split("/")[0] || void 0;
+}
 function getRoutes() {
 	const { roles, permissions = [] } = useUserStore.getState();
 	const routes = [];
@@ -7586,6 +7670,22 @@ function getRoutes() {
 	}
 	return addRouteIdByPath(routes);
 }
+/**
+* 宿主链建路由表的唯一取口：与菜单管线同源套 rewriteAdminPaths。
+*
+* 0.2.17 起方案 admin 路由被真重写为 /system/<模块根>/*（菜单项 key 已随之改写），
+* 宿主若直接用 getRoutes() 建表（cli/shell host.tsx 回归，2026-10），渲染路由表
+* 停留在 /wiki/admin/* 而菜单指向 /system/wiki/admin/* → 方案管理页菜单点击必 404。
+* getRoutes() 只该给 access store 登记、keep-alive 聚合等「无需重写」的场景用。
+*/
+function getHostRoutes() {
+	return rewriteAdminPaths(getRoutes().map((route) => {
+		const mod = route.handle?.module;
+		if (!mod) return route;
+		const prefix = modules.get(mod)?.routePrefix ?? mod;
+		return applyRoutePrefix([route], prefix)[0] ?? route;
+	}));
+}
 function getRegisteredStore(name) {
 	return registeredStores.get(name);
 }
@@ -7600,7 +7700,7 @@ function getRegisteredApiPrefix(moduleName) {
 async function unloadModule(name) {
 	const instance = modules.get(name);
 	if (instance) {
-		const ctx = createModuleContext(instance.definition);
+		const ctx = createModuleContext(instance.definition, instance.routePrefix);
 		if (instance.definition.lifecycle?.onDestroy) await instance.definition.lifecycle.onDestroy(ctx);
 	}
 	removeModuleSlots(name);
@@ -7632,6 +7732,7 @@ var init_module_loader = __esmMin((() => {
 	init_layout_registry();
 	init_add_route_id_by_path();
 	init_resolve_layout();
+	init_rewrite_admin_paths();
 	init_access();
 	init_api_provider();
 	init_auth_provider();
@@ -8702,42 +8803,6 @@ var init_resolve_login_route = __esmMin((() => {
 	isInternalLoginRoute = (r) => r?.handle?.login === true && r?.handle?.internal === true;
 }));
 //#endregion
-//#region src/router/utils/rewrite-admin-paths.ts
-/** 解析路由绝对路径（与 generate-menu-items-from-routes 同语义） */
-function resolveAbs(path, parentAbs) {
-	if (!path) return parentAbs;
-	return path.startsWith("/") ? path : `${parentAbs.replace(/\/+$/, "")}/${path}`;
-}
-function rewriteAdminPaths(routes, systemKey = SYSTEM_KEY) {
-	const hoisted = [];
-	return [...routes.map((r) => processRoute(r, "/", systemKey, hoisted, void 0)).filter((r) => r !== null), ...hoisted];
-}
-function processRoute(route, parentAbs, systemKey, hoisted, moduleRootAbs) {
-	const abs = resolveAbs(route.path, parentAbs);
-	const rootAbs = moduleRootAbs ?? abs;
-	if (route.handle?.category === "admin") {
-		const newAbs = `${systemKey}${rootAbs}${abs.slice(rootAbs.length) || ""}`;
-		hoisted.push({
-			...route,
-			path: newAbs
-		});
-		return null;
-	}
-	if (!route.children || route.children.length === 0) return { ...route };
-	const newChildren = [];
-	for (const c of route.children) {
-		const processed = processRoute(c, abs, systemKey, hoisted, rootAbs);
-		if (processed !== null) newChildren.push(processed);
-	}
-	const result = { ...route };
-	result.children = newChildren;
-	return result;
-}
-var SYSTEM_KEY;
-var init_rewrite_admin_paths = __esmMin((() => {
-	SYSTEM_KEY = "/system";
-}));
-//#endregion
 //#region src/store/access.ts
 /**
 * 切分主区/底部固定区路由（ascending 已双段排序：负 order 段整体在后）。
@@ -8877,6 +8942,29 @@ var init_auth = __esmMin((() => {
 	}), { name: getAppNamespace("access-token") }));
 }));
 //#endregion
+//#region src/utils/api-base.ts
+/** 归一为不以 `/` 结尾；绝对域（http(s)://）原样剥尾斜杠；空值回落默认 */
+function normalizeApiBase(raw) {
+	const trimmed = raw?.trim();
+	if (!trimmed) return DEFAULT_API_BASE;
+	return trimmed.replace(/\/+$/, "") || DEFAULT_API_BASE;
+}
+/**
+* 当前 API 端点 base（ky `prefix`，恒不以 `/` 结尾）。
+*
+* 每次调用都重新读取——不做模块级缓存（与 `resolveSiteBase()` 同理：
+* 测试需要在不重启模块的情况下模拟不同部署）。
+*/
+function resolveApiBase() {
+	const injected = globalThis.__OJ_API_BASE__;
+	if (typeof injected === "string") return normalizeApiBase(injected);
+	return normalizeApiBase("/api");
+}
+var DEFAULT_API_BASE;
+var init_api_base = __esmMin((() => {
+	DEFAULT_API_BASE = "/api";
+}));
+//#endregion
 //#region src/utils/request/error-response.ts
 /**
 * 处理错误响应
@@ -8950,13 +9038,24 @@ var init_global_progress = __esmMin((() => {
 }));
 //#endregion
 //#region src/utils/remember-route/index.ts
+/**
+* 回跳参数取**路由空间**路径（剥掉站点 base）。
+*
+* 消费端（login 模块 `navigate(getRedirectPath(search))`）走的是 react-router
+* navigate——basename 会被再补一次。这里若直接用 `window.location.pathname`
+* （URL 空间，含 `/oj` 前缀），子路径部署下登录后落 `/oj/oj/home`（base 双拼，
+* 2026-10 子路径部署实测回归）。goLogin 的硬跳转负责补 base，本函数只管剥。
+*/
 function rememberRoute() {
 	const { pathname, search } = window.location;
-	if (pathname.length > 1 && pathname !== "/login") return `?redirect=${pathname}${search}`;
+	const base = resolveSiteBase();
+	const routePath = base === "/" ? pathname : `/${pathname.slice(base.length)}`;
+	if (routePath.length > 1 && routePath !== "/login") return `?redirect=${routePath}${search}`;
 	return "";
 }
 var init_remember_route = __esmMin((() => {
 	init_extra_info();
+	init_site_base();
 }));
 //#endregion
 //#region src/utils/request/go-login.ts
@@ -9102,6 +9201,7 @@ var init_request = __esmMin((() => {
 	init_auth();
 	init_header_provider();
 	init_preferences$3();
+	init_api_base();
 	init_constants$3();
 	init_error_response();
 	init_global_progress();
@@ -9110,7 +9210,7 @@ var init_request = __esmMin((() => {
 	init_refresh();
 	init_whitelist();
 	defaultConfig = {
-		prefix: "/api",
+		prefix: resolveApiBase(),
 		timeout: 1e4,
 		retry: { limit: 3 },
 		hooks: {
@@ -9678,9 +9778,10 @@ function BasicContent(props) {
 //#endregion
 //#region src/components/basic-form/form-items/form-avatar-item.tsx
 init_api_provider();
+init_api_base();
 function FormAvatarItem({ value, onChange }) {
 	const uploadProvider = getUploadApiProvider();
-	const uploadAction = uploadProvider?.action ?? `/api/upload`;
+	const uploadAction = uploadProvider?.action ?? `${resolveApiBase()}/upload`;
 	const uploadHeaders = uploadProvider?.headers() ?? { authorization: "authorization-text" };
 	return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsxs("div", {
 		className: "flex items-center gap-5",
@@ -28102,4 +28203,4 @@ init_ri();
 init_menu_icons();
 init_tree();
 //#endregion
-export { AccessControl, AccessControlRoles, AntdApp, BasicButton, BasicContent, BasicTable, EmbeddedIcon, ErrorBoundary, ExternalIcon, FormAvatarItem, FormTreeItem, Iframe, LayoutCenterIcon, LayoutEffects, LayoutLeftIcon, LayoutRightIcon, MixedNavigationIcon, OutsidePageIcon, PageError, ProfileCardIcon, RiAccountCircleLine, RiContrastFill, RiFullscreenExitLine, RiFullscreenLine, RiMailCheckLine, RiMoonIcon, RiReactjsLine, RiSunIcon, RiUserSettingsLine, ServerErrorIcon, SideNavigationIcon, TopNavigationIcon, TwoColumnNavigationIcon, accessControlCodes, bindingDiff, canAssignRole, canDeleteRole, canEditRoleBindings, defineModule, fetchAddMenuItem, fetchAddRoleItem, fetchAsyncRoutes, fetchChangePassword, fetchDeleteMenuItem, fetchDeleteRoleItem, fetchLdapLogin, fetchLogin, fetchLoginMethods, fetchLogout, fetchMenuByRoleId, fetchMenuList, fetchRbacAdminResetPassword, fetchRbacContactDetail, fetchRbacContacts, fetchRbacCreateRole, fetchRbacCreateUser, fetchRbacDeleteRole, fetchRbacOplog, fetchRbacOplogPost, fetchRbacPermissionList, fetchRbacRoleList, fetchRbacSetForbidden, fetchRbacSettings, fetchRbacUpdateBindings, fetchRbacUpdateSetting, fetchRbacUpdateUserRoles, fetchRbacUserList, fetchRefreshToken, fetchRoleList, fetchRoleMenu, fetchSolutionRoutes, fetchUpdateMenuItem, fetchUpdateRoleItem, fetchUserInfo, filterTree, getAllExpandedKeys, getAppInfo, getBooleanOptions, getModule, getModules, getRedirectPath, getRegisteredApiPrefix, getRegisteredStore, getRoutes, getYesNoOptions, groupByModule, groupSettingsByModule, handleTree, loadAll, mapTree, menuIcons, notify, permissionPrefix, request, resolveSiteBase, roleLabel, setupI18n, traverseTreeValues, unloadModule, useAccess, useAuthStore, usePreferences, useSlotNodes, useSolutionRoutes, useTabKey, useTabsStore, useUserStore, withSiteBase, external_exports as z };
+export { AccessControl, AccessControlRoles, AntdApp, BasicButton, BasicContent, BasicTable, EmbeddedIcon, ErrorBoundary, ExternalIcon, FormAvatarItem, FormTreeItem, Iframe, LayoutCenterIcon, LayoutEffects, LayoutLeftIcon, LayoutRightIcon, MixedNavigationIcon, OutsidePageIcon, PageError, ProfileCardIcon, RiAccountCircleLine, RiContrastFill, RiFullscreenExitLine, RiFullscreenLine, RiMailCheckLine, RiMoonIcon, RiReactjsLine, RiSunIcon, RiUserSettingsLine, ServerErrorIcon, SideNavigationIcon, TopNavigationIcon, TwoColumnNavigationIcon, accessControlCodes, bindingDiff, canAssignRole, canDeleteRole, canEditRoleBindings, defineModule, fetchAddMenuItem, fetchAddRoleItem, fetchAsyncRoutes, fetchChangePassword, fetchDeleteMenuItem, fetchDeleteRoleItem, fetchLdapLogin, fetchLogin, fetchLoginMethods, fetchLogout, fetchMenuByRoleId, fetchMenuList, fetchRbacAdminResetPassword, fetchRbacContactDetail, fetchRbacContacts, fetchRbacCreateRole, fetchRbacCreateUser, fetchRbacDeleteRole, fetchRbacOplog, fetchRbacOplogPost, fetchRbacPermissionList, fetchRbacRoleList, fetchRbacSetForbidden, fetchRbacSettings, fetchRbacUpdateBindings, fetchRbacUpdateSetting, fetchRbacUpdateUserRoles, fetchRbacUserList, fetchRefreshToken, fetchRoleList, fetchRoleMenu, fetchSolutionRoutes, fetchUpdateMenuItem, fetchUpdateRoleItem, fetchUserInfo, filterTree, getAllExpandedKeys, getAppInfo, getBooleanOptions, getHostRoutes, getModule, getModuleRoutePrefix, getModules, getRedirectPath, getRegisteredApiPrefix, getRegisteredStore, getRoutes, getYesNoOptions, groupByModule, groupSettingsByModule, handleTree, loadAll, mapTree, menuIcons, notify, permissionPrefix, request, resolveSiteBase, roleLabel, setupI18n, traverseTreeValues, unloadModule, useAccess, useAuthStore, usePreferences, useSlotNodes, useSolutionRoutes, useTabKey, useTabsStore, useUserStore, withSiteBase, external_exports as z };

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-LoiG1HDggaNmP/FtNKL2EQ=='; 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-mh43xEkINEUP2sZNPLqVdA=='; 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="LoiG1HDggaNmP/FtNKL2EQ==">{
+		<script type="importmap" nonce="mh43xEkINEUP2sZNPLqVdA==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",
@@ -133,7 +133,7 @@
     "dayjs/locale/zh-cn": "/assets/ojm-dayjs-locale-zh-cn.js"
   }
 }</script>
-		<script type="module" crossorigin src="/assets/index-B3g19Uet.js"></script>
+		<script type="module" crossorigin src="/assets/index-CtTVbohp.js"></script>
 	</head>
 	<body>
 		<div id="root"></div>

package/shell-dist/versions.json

@@ -7,9 +7,9 @@
   "react-router": "7.18.2",
   "react-router/dom": "7.18.2",
   "@tanstack/react-query": "5.102.8",
-  "@oj-module/runtime": "0.2.27",
-  "@oj-module/runtime/contract": "0.2.27",
-  "@oj-module/runtime/contract/errors": "0.2.27",
+  "@oj-module/runtime": "0.2.28",
+  "@oj-module/runtime/contract": "0.2.28",
+  "@oj-module/runtime/contract/errors": "0.2.28",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/build.ts

@@ -1,5 +1,6 @@
 import type { Plugin as EsbuildPlugin } from "esbuild";
 import type { Plugin } from "vite";
+import type { ProjectLayout } from "./layout";
 import type { RouteDefinitionLike } from "./manifest-routes-derive";
 import { execFileSync } from "node:child_process";
 import crypto from "node:crypto";
@@ -10,9 +11,10 @@ import { pathToFileURL } from "node:url";
 import tailwindcss from "@tailwindcss/vite";
 import { build as esbuild } from "esbuild";
 import { build } from "vite";
+import { parse as parseYaml } from "yaml";
 import { ALIAS_PATHS_FILE, syncAliasPaths } from "./alias-paths";
 import { assertModuleList, loadSiteConfig, mergeModuleList, resolveModuleEntry } from "./config";
-import { resolveConfigPath, resolveLayout, scanModules, tryResolveLayout } from "./layout";
+import { moduleDir, resolveConfigPath, resolveLayout, scanModules, tryResolveLayout } from "./layout";
 import { requireModuleRootCapability } from "./oj-caps";
 import { isSharedDep, SHARED_DEPS } from "./shared-deps";
 import { normalizeSiteBase, rewriteIndexHtml } from "./site-base";
@@ -154,6 +156,9 @@ export const defineGuard = (...a) => a[a.length - 1];
 export const getModules = () => [];
 export const getModule = () => undefined;
 export const getRoutes = () => [];
+export const getHostRoutes = () => [];
+// 模块生效 web 路由前缀段取值口（R1.3：写进 modules.json 的 routePrefix，未声明回落 name）
+export const getModuleRoutePrefix = _fn;
 export const getRegisteredStore = () => undefined;
 export const getRegisteredApiPrefix = () => undefined;
 export const loadAll = async () => [];
@@ -341,6 +346,37 @@ export interface BuiltModule {
 	integrity: string
 	css: string[]
 	chunks: ChunkEntry[]
+	/**
+	 * 生效的 web 路由前缀段（契约 C2-14：`web.route_prefix` 缺省 `/<name>`）。
+	 * 运行期据其改写模块路由根（单根约定下仅根段），缺省 = name 保证零漂移。
+	 */
+	routePrefix: string
+}
+
+/**
+ * 解析模块生效的 web 路由前缀段（R1.1）。
+ * module-root：读 `src/<name>/solution.yaml` 的 `web.route_prefix`（契约 C2-14，缺省 `/<name>`）；
+ * 未配置/非法/非 module-root → 缺省 `name`，与现有路由根（顶层段即 name）逐字节一致。
+ */
+function resolveRoutePrefix(layout: ProjectLayout, name: string): string {
+	if (layout.kind !== "module-root")
+		return name;
+	const solPath = path.join(moduleDir(layout, name), "solution.yaml");
+	if (!fs.existsSync(solPath))
+		return name;
+	try {
+		const doc = parseYaml(fs.readFileSync(solPath, "utf-8")) as Record<string, unknown>;
+		const web = doc.web;
+		if (web && typeof web === "object" && !Array.isArray(web)) {
+			const rp = (web as Record<string, unknown>).route_prefix;
+			if (typeof rp === "string" && /^\/[a-z][a-z0-9-]{0,63}$/.test(rp))
+				return rp.slice(1);
+		}
+	}
+	catch {
+		// YAML 解析失败 → 缺省，不阻断构建（契约校验会在别处暴露）
+	}
+	return name;
 }
 
 const ALGORITHM = "sha384";
@@ -565,19 +601,22 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
  * dev 的 / 与 /assets/* 直接服务 shell dist，合并产物无人消费。
  *
  * siteBase 非空时（站点挂载在 `/oj` 这类子路径）改写 index.html 的站内绝对
- * URL 并注入 `window.__OJ_BASE__`（见 site-base.ts）；为空则产物与既有行为
- * 逐字节一致。
+ * URL；apiBase 非空时注入 `window.__OJ_API_BASE__`（API 挂载前缀部署期可配，
+ * 见 site-base.ts）。两者都为空则产物与既有行为逐字节一致。
  */
-function mergeShellSite(distDir: string, siteBase: string): void {
+function mergeShellSite(distDir: string, siteBase: string, apiBase: string): void {
 	const shellDist = resolveShellDist();
 	fs.rmSync(distDir, { recursive: true, force: true });
 	fs.mkdirSync(path.dirname(distDir), { recursive: true });
 	fs.cpSync(shellDist, distDir, { recursive: true });
 
 	const indexPath = path.join(distDir, "index.html");
-	if (normalizeSiteBase(siteBase) !== "/") {
-		fs.writeFileSync(indexPath, rewriteIndexHtml(fs.readFileSync(indexPath, "utf-8"), siteBase));
-		console.log(`[ojm] 站点 index.html 已按 siteBase=${normalizeSiteBase(siteBase)} 重写（子路径部署）`);
+	if (normalizeSiteBase(siteBase) !== "/" || apiBase.trim()) {
+		fs.writeFileSync(indexPath, rewriteIndexHtml(fs.readFileSync(indexPath, "utf-8"), siteBase, apiBase));
+		if (normalizeSiteBase(siteBase) !== "/")
+			console.log(`[ojm] 站点 index.html 已按 siteBase=${normalizeSiteBase(siteBase)} 重写（子路径部署）`);
+		if (apiBase.trim())
+			console.log(`[ojm] API 前缀已注入 index.html：${apiBase.trim().replace(/\/+$/, "")}（apiBase）`);
 	}
 	console.log(`[ojm] 已合并宿主站点 → ${distDir}`);
 }
@@ -607,7 +646,7 @@ export async function buildModules(
 	const baseUrl = config.baseUrl ?? "";
 
 	if (opts.mergeSite)
-		mergeShellSite(outDir, config.siteBase ?? "");
+		mergeShellSite(outDir, config.siteBase ?? "", config.apiBase ?? "");
 
 	// P4.5 / C4 / D12：构建前先过版本矩阵门禁，版本漂移直接拒绝
 	checkSharedVersions(projectRoot, resolveShellDist());
@@ -756,6 +795,7 @@ export async function buildModules(
 			integrity: sha384(path.join(moduleOutDir, "entry.js")),
 			css,
 			chunks,
+			routePrefix: resolveRoutePrefix(layout, definition.name),
 		});
 	}
 

package/src/bundle.ts

@@ -37,7 +37,7 @@ import { readModuleDefinition } from "./build";
 import { readBuiltinModules } from "./builtin";
 import { createDeterministicTgz } from "./deterministic-tar";
 import { apiSrcOf, resolveLayout, webSrcOf } from "./layout";
-import { assertValidSolutionName, checkLocalesComplete, checkTablesAgainstSchema, NAME_RE, parseManifest, referencedI18nKeys, validateContract } from "./manifest-contract";
+import { assertValidSolutionName, checkLocalesComplete, checkTablesAgainstSchema, isReferenceApiForm, NAME_RE, parseManifest, referencedI18nKeys, validateContract } from "./manifest-contract";
 import { deriveManifestRoutes, reconcileManifestRoutes } from "./manifest-routes-derive";
 
 export interface BundleBuildResult {
@@ -232,6 +232,13 @@ async function planBundle(projectRoot: string, layout: ProjectLayout, target: Bu
 	if (violations.length > 0) {
 		throw new Error(`[ojm] 方案包构建失败：manifest.yaml 契约校验未通过（${violations.length} 项违规，全量列出）：\n${violations.map(x => `- ${x}`).join("\n")}`);
 	}
+	// R2.2：引用式 solution 提示——api.tables/api.deps 缺省 = 引用包内 manifest.yaml（非漏配）
+	if (isReferenceApiForm(m.api)) {
+		console.log(
+			`[ojm] 引用式方案：api.tables/api.deps 缺省，引用包内 api/${String(m.name)}-${String(m.version)}/manifest.yaml`
+			+ "（安装期 C2-31 复核其存在，依赖装配据其回读，非漏配）",
+		);
+	}
 	const version = m.version as string;
 
 	// 文件面契约（§4.1 构建列专属执行点；manifest 内在规则已在 validateContract 全量通过）

package/src/config.ts

@@ -26,6 +26,18 @@ export interface ModulesConfig {
 	 * 绝对域），`siteBase` 是**站点自身**的部署位置；两者正交，可同时使用。
 	 */
 	siteBase?: string
+	/**
+	 * API 端点前缀（如 `"/gw"`），留空 = 构建期默认 `/api`。
+	 *
+	 * oj 的 API 挂载前缀是部署期配置（`config.yaml` 的 `mounts` api 条），
+	 * 而 runtime 是预构建产物——构建期内联的默认前缀改不了。API 挂载不在
+	 * `/api` 时**必须**配它：`ojm build` 注入 `window.__OJ_API_BASE__`，
+	 * runtime 的 ky `prefix` 运行期读它（`resolveApiBase()`），端点仍一律相对。
+	 *
+	 * 与 `siteBase` 正交：站点可挂 `/oj` 而 API 恒在 `/api`；也可只换 API
+	 * 前缀而站点在根。允许绝对域（如 `https://api.example.com`）。
+	 */
+	apiBase?: string
 	modules?: ModuleConfigEntry[]
 	/**
 	 * 站点 HTML 变换模块（可选）：相对工程根的路径（`./html-transform.ts`）

package/src/contract/run.ts

@@ -4,11 +4,11 @@ import type { OpenApiDoc } from "./openapi-ir";
 import { execFile as execFileCb } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
 import { stringify as stringifyYaml } from "yaml";
-import { apiModuleRoots, apiModulesSrc, apiSrcOf, legacyApiModuleRoots, tryResolveLayout, webSrcOf } from "../layout";
+import { apiModuleRoots, apiModulesSrc, apiSrcOf, legacyApiModuleRoots, scanModules, tryResolveLayout, webSrcOf } from "../layout";
 import { emitClient } from "./emit-client";
 import { applyStubWrites, planStubWrites } from "./emit-stub";
 import { implementedRouteKeys } from "./handler-scan";
@@ -125,7 +125,10 @@ export async function runApi(opts: { cwd: string, openapi?: string, rawPaths?: S
 
 /**
  * R5：`ojm api --docs`——聚合 openapi.json 的 paths → redoc 渲染静态站。
- * uni-dev 形态（存在 api/src）落 `api/docs/index.html`，纯前端落 `docs/api/index.html`。
+ * 文档统一落 `<projectRoot>/src/docs/<name>/api`（与模块树同位、树外——不参与模块
+ * 枚举与 handler 路由扫描，杜绝 docs 被当 handler 镜像导致端点翻倍 wikiDocsDocs*）。
+ * `name` 推导：cwd 为 `src/<name>/api` 时取父目录名；module-root 单模块时取该模块名；
+ * 否则回退工程目录名。legacy 布局同样落 `src/docs/<name>/api`（位于 api/src 扫描树外）。
  * redoc CLI 缺失时人话报错。
  */
 export async function runApiDocs(cwd: string, opts: { redocBin?: string, fetchJs?: (url: string) => Promise<string> } = {}): Promise<string> {
@@ -136,9 +139,30 @@ export async function runApiDocs(cwd: string, opts: { redocBin?: string, fetchJs
 	const doc = JSON.parse(readFileSync(openapiPath, "utf8")) as { paths?: Record<string, Record<string, unknown>> };
 	const paths = doc.paths ?? {};
 	const layout = tryResolveLayout(cwd);
-	const isUniDev = existsSync(layout ? apiModulesSrc(layout) : join(cwd, "api/src"));
 
-	const outDir = isUniDev ? join(cwd, "api/docs") : join(cwd, "docs/api");
+	// 修正B：文档统一落 <projectRoot>/src/docs/<name>/api（与模块树同位、树外——
+	// 无 manifest.yaml、顶层不被 scanModuleRoot 枚举，walkApiFiles 也不命中，
+	// 不会把 docs 当 handler 路由镜像，杜绝 wikiDocsDocs* 类端点翻倍）。
+	const projectRoot = layout?.projectRoot ?? cwd;
+	let name = basename(projectRoot);
+	if (basename(cwd) === "api") {
+		// cwd 为模块 api 目录（src/<name>/api）时取父目录名为模块名
+		const candidate = basename(dirname(cwd));
+		if (layout?.kind === "module-root") {
+			const mods = scanModules(layout).map(m => m.name);
+			if (mods.includes(candidate))
+				name = candidate;
+		}
+		else {
+			name = candidate;
+		}
+	}
+	else if (layout?.kind === "module-root") {
+		const mods = scanModules(layout).map(m => m.name);
+		if (mods.length === 1)
+			name = mods[0]!;
+	}
+	const outDir = join(projectRoot, "src", "docs", name, "api");
 	mkdirSync(outDir, { recursive: true });
 	const specPath = join(outDir, "openapi.yaml");
 	writeFileSync(specPath, stringifyYaml({ openapi: "3.1.0", info: { title: "API 文档", version: "0.0.0" }, paths }));

package/src/manifest-contract.ts

@@ -38,6 +38,19 @@ export const RESERVED_NAMES = new Set(["_platform", "system", "auth", "market",
 /** C2-02 字符集：[0-9A-Za-z.-]（禁 +——oj validate_version 拒装，附录 B-1；禁 _——契约收紧） */
 const VERSION_CHARS_RE = /^[0-9A-Z.-]+$/i;
 
+/**
+ * 引用式 api 段判定（R2.1）：`api` 段存在但 `tables` 与 `deps` 均缺省 =
+ * 引用包内 `<module>/manifest.yaml`（oj 原生七键清单，tgz 已随包携带，安装期 C2-31 复核）。
+ * 契约**显式承认**此形态（不再仅靠字段可选性「漏过」通过）：安装器据 native manifest
+ * 回读做占用检测/装配（R2.2），全量 form（两字段任一给出）优先。
+ */
+export function isReferenceApiForm(api: unknown): boolean {
+	if (!isObj(api))
+		return false;
+	const a = api as Record<string, unknown>;
+	return a.tables === undefined && a.deps === undefined;
+}
+
 /** §2.2 范围算子语法（peer 四字段/api.deps 值共用） */
 const RANGE_RE = /^(>=|<=|[><^=])?([0-9A-Z.-]+)$/i;
 
@@ -253,7 +266,7 @@ export function validateContract(m: unknown): string[] {
 		}
 	}
 
-	// ── api 段（C2-12/12a/12b/13/26）──
+	// ── api 段（C2-12/12a/12b/13/26；R2.1 引用式：tables/deps 均缺省 = 引用包内 manifest.yaml）──
 	let apiSeg = name;
 	if (m.api !== undefined) {
 		const api = m.api;

package/src/new.ts

@@ -130,7 +130,8 @@ peerRuntime: ">=0.0.0"
 archive:
   file: ${name}-0.1.0.tgz
 ${api}web:
-  route_prefix: /${name}
+  # route_prefix 缺省 = /<name>（契约 C2-14）；需自定义根路径时取消下一行注释修改
+  # route_prefix: /${name}
   entry: modules/${name}/0.1.0/entry.js
 `;
 }

package/src/site-base.ts

@@ -71,31 +71,45 @@ function rewriteImportmap(html: string, base: string): string {
 /**
  * 重写全站 index.html：
  * - importmap 映射值、`<script src>`、`<link href>` 统一加 `siteBase`；
- * - `<head>` 内注入 `window.__OJ_BASE__`（**复用 importmap 的 nonce**，
- *   CSP 是 `script-src 'self' … 'nonce-xxx'`，无 nonce 的内联脚本会被直接拦掉）。
+ * - `<head>` 内注入 `window.__OJ_BASE__` / `window.__OJ_API_BASE__`
+ *   （**复用 importmap 的 nonce**，CSP 是 `script-src 'self' … 'nonce-xxx'`，
+ *   无 nonce 的内联脚本会被直接拦掉）。
+ *
+ * 两者独立：siteBase 非根才重写 URL；apiBase 配了就注入（API 挂载前缀是
+ * 部署期事实，与站点位置正交）。都不涉及 → 逐字节原样返回（零回归）。
  */
-export function rewriteIndexHtml(html: string, siteBase: string | undefined): string {
+export function rewriteIndexHtml(html: string, siteBase: string | undefined, apiBase?: string): string {
 	const base = normalizeSiteBase(siteBase);
-	// 根路径部署：原样返回（保持与既有产物逐字节一致）
-	if (base === ROOT_BASE)
+	const api = apiBase?.trim();
+	// 根路径部署且未配 API 前缀：原样返回（保持与既有产物逐字节一致）
+	if (base === ROOT_BASE && !api)
 		return html;
 
 	const nonce = html.match(/<script type="importmap"[^>]*\snonce="([^"]*)"/)?.[1];
 	if (!nonce) {
 		throw new Error(
-			"[ojm] 站点 index.html 缺少带 nonce 的 importmap，无法注入 window.__OJ_BASE__"
+			"[ojm] 站点 index.html 缺少带 nonce 的 importmap，无法注入 window.__OJ_BASE__ / window.__OJ_API_BASE__"
 			+ "（CSP 会拦掉无 nonce 的内联脚本，子路径部署下路由 basename 会退化成 \"/\"）。"
 			+ "请确认 shell-dist 是最新构建产物（pnpm build:shell）。",
 		);
 	}
 
-	let out = rewriteImportmap(html, base);
-	// 属性值：只要以单个 "/" 开头（排除 "//host"）。importmap 是脚本正文、非属性，
-	// 上一步已处理，二者不重叠。
-	out = out.replace(/(\b(?:href|src)=")(\/[^/"][^"]*|\/")/g, (_m, attr: string, url: string) =>
-		`${attr}${withSiteBase(url, base)}`);
+	const globals: string[] = [];
+	let out = html;
+	if (base !== ROOT_BASE) {
+		out = rewriteImportmap(out, base);
+		// 属性值：只要以单个 "/" 开头（排除 "//host"）。importmap 是脚本正文、非属性，
+		// 上一步已处理，二者不重叠。
+		out = out.replace(/(\b(?:href|src)=")(\/[^/"][^"]*|\/")/g, (_m, attr: string, url: string) =>
+			`${attr}${withSiteBase(url, base)}`);
+		globals.push(`window.__OJ_BASE__=${JSON.stringify(base)};`);
+	}
+	if (api) {
+		// 归一为不以 / 结尾（ky v2 的 prefix 自剥尾斜杠，这里归一保证注入值确定）
+		globals.push(`window.__OJ_API_BASE__=${JSON.stringify(api.replace(/\/+$/, ""))};`);
+	}
 
-	const injected = `<script nonce="${nonce}">window.__OJ_BASE__=${JSON.stringify(base)};</script>`;
+	const injected = `<script nonce="${nonce}">${globals.join("")}</script>`;
 	// 注入点选在 importmap 之前：importmap 本身必须在任何 module script 之前，
 	// 而内联 classic script 是解析期同步执行，因此宿主 main 与模块 entry 读
 	// `window.__OJ_BASE__` 时它一定已经在位。

package/templates/src/_platform/api/_lifecycle/steps/deploy-web.ts

@@ -40,9 +40,16 @@ function isObj(v: unknown): v is Record<string, unknown> {
 	return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
-/** manifest api.deps 的模块依赖键（排除 _platform——平台非 web 模块依赖，P2-15② extras） */
-function apiDepsOf(m: Record<string, unknown>): string[] {
-	const deps = isObj(m.api) && isObj((m.api as Record<string, unknown>).deps) ? (m.api as Record<string, unknown>).deps as Record<string, unknown> : {};
+/**
+ * manifest api.deps 的模块依赖键（排除 _platform——平台非 web 模块依赖，P2-15② extras）。
+ * 全量 form（C2 `api.deps` 给出）优先；引用式（R2.2）回退包内 native manifest.deps
+ * （oj 原生七键清单，tgz 随包携带，extract 段已解析留存 ctx.nativeManifest）。
+ */
+function apiDepsOf(m: Record<string, unknown>, native?: unknown): string[] {
+	const c2 = isObj(m.api) && isObj((m.api as Record<string, unknown>).deps)
+		? (m.api as Record<string, unknown>).deps as Record<string, unknown>
+		: undefined;
+	const deps = c2 ?? (isObj(native) && isObj((native as Record<string, unknown>).deps) ? (native as Record<string, unknown>).deps as Record<string, unknown> : {});
 	return Object.keys(deps).filter(k => k !== "_platform").sort();
 }
 
@@ -157,7 +164,8 @@ export async function deployWeb(ctx: DeployWebContext): Promise<StageResult> {
 		// P2-15②（G7 defer-P2 承载）：完整条目 extras——version/dependencies/chunks 补齐
 		// （deployWeb 全新生成 entry，构建器条目不透传的缺口；宿主 HostModule 全字段消费面）
 		version: ctx.version,
-		...(apiDepsOf(m).length > 0 ? { dependencies: apiDepsOf(m) } : {}),
+		// R2.2：引用式 solution 的 dependencies 据包内 native manifest 回读装配
+		...(apiDepsOf(m, ctx.nativeManifest).length > 0 ? { dependencies: apiDepsOf(m, ctx.nativeManifest) } : {}),
 		chunks: [], // 单 entry 产物无懒加载 chunk（宿主 collectPreloads 消费 `?? []`，字段形状齐备）
 		...(Array.isArray(web.css) ? { css: web.css.map(c => posixPath(String(c))) } : {}),
 		...(integrity !== undefined ? { integrity } : {}),

package/templates/src/_platform/api/_lifecycle/steps/extract.ts

@@ -189,6 +189,8 @@ async function checkApiSegment(ctx: ExtractContext): Promise<{ ok: true } | { ok
 	catch (e) {
 		return { ok: false, message: `解压复核失败：api/${ctx.name}-${ctx.version}/manifest.yaml 不可解析（${String(e)}）——C2-31` };
 	}
+	// R2.2：引用式 solution 的 tables/deps 真源——保留 native manifest 供 deployWeb 回读装配。
+	ctx.nativeManifest = native;
 	return checkModuleManifest(ctx.manifest, native, ctx.name, ctx.version);
 }
 

package/templates/src/_platform/api/_lifecycle/types.ts

@@ -9,6 +9,11 @@ import type { StateStore } from "./state";
 export interface InstallContext {
 	/** 已解析的 manifest.yaml（安装器读盘解析产物） */
 	manifest: unknown
+	/**
+	 * 包内 oj 原生清单（C2-31 复核解析产物；引用式 solution 的 tables/deps 真源）。
+	 * web-only 包（无 api 段）保持 undefined；引用式方案的依赖装配据其回读（R2.2）。
+	 */
+	nativeManifest?: unknown
 	/** 安装目标身份（与 manifest.name/version 同源；manifest 字段缺失/非字符串时兜底） */
 	name: string
 	version: string

package/vendor/host-versions.json

@@ -8,9 +8,9 @@
 		"react-router": "7.18.2",
 		"react-router/dom": "7.18.2",
 		"@tanstack/react-query": "5.102.8",
-		"@oj-module/runtime": "0.2.27",
-		"@oj-module/runtime/contract": "0.2.27",
-		"@oj-module/runtime/contract/errors": "0.2.27",
+		"@oj-module/runtime": "0.2.28",
+		"@oj-module/runtime/contract": "0.2.28",
+		"@oj-module/runtime/contract/errors": "0.2.28",
 		"@plane/kit": "0.1.20",
 		"@plane/editor": "0.1.20",
 		"antd": "6.6.1",