@oj-module/cli 0.2.15 → 0.2.17

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.15",
-  "@oj-module/runtime/contract": "0.2.15",
-  "@oj-module/runtime/contract/errors": "0.2.15",
+  "@oj-module/runtime": "0.2.17",
+  "@oj-module/runtime/contract": "0.2.17",
+  "@oj-module/runtime/contract/errors": "0.2.17",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/__tests__/manifest-routes-derive.test.ts

@@ -0,0 +1,102 @@
+import type { DerivedRoute, ModuleDefinitionLike } from "../manifest-routes-derive";
+
+import { describe, expect, it } from "vitest";
+import { deriveManifestRoutes, reconcileManifestRoutes } from "../manifest-routes-derive";
+
+/**
+ * BDD：R5 manifest.routes 由 entry.ts 路由 handle 自动派生（单一真源，避免手工双写漂移）。
+ * - d-1：三类（main/admin/hidden）路由均派生，字段口径正确；
+ * - d-2：无 handle.category 的路由（框架/纯页面/动态段子页）跳过，不进 manifest；
+ * - d-3：既有 manifest routes 与派生结果漂移时，reconcile 以 entry.ts 为准并发警告（不阻断）。
+ */
+
+function def(routes: ModuleDefinitionLike["routes"]): ModuleDefinitionLike {
+	return { name: "wiki", routes };
+}
+
+describe("deriveManifestRoutes（entry.ts → manifest routes）", () => {
+	it("d-1 三类 category 均派生，字段口径正确（path/category/order/title_key）", () => {
+		const d = def([
+			{ path: "/space", handle: { category: "main", order: 200, title: "wiki:menu.space" } },
+			{ path: "/admin", handle: { category: "admin", order: 220, title: "wiki:menu.admin" } },
+			{ path: "/wiki/status", handle: { category: "hidden", order: 201, title: "wiki:menu.status" } },
+		]);
+		const out = deriveManifestRoutes(d);
+		expect(out).toEqual([
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+			{ path: "/admin", category: "admin", order: 220, title_key: "wiki:menu.admin" },
+			{ path: "/wiki/status", category: "hidden", order: 201, title_key: "wiki:menu.status" },
+		]);
+	});
+
+	it("d-2 无 category 的路由跳过：框架页/动态段子页/纯组件页不进 manifest", () => {
+		const d = def([
+			{ path: "/space", handle: { category: "main", order: 200, title: "wiki:menu.space" } },
+			// 动态段子页（空间成员页）：不进菜单，无 category → 跳过
+			{ path: ":id/members", handle: { title: "wiki:menu.members", hideInMenu: true } },
+			// 框架/纯页面路由：无 category → 跳过
+			{ path: "/dashboard", handle: { title: "framework:menu.dashboard" } },
+		]);
+		const out = deriveManifestRoutes(d);
+		expect(out).toEqual([
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+		]);
+	});
+
+	it("d-2b 缺 order 的 category 路由仍派生（order 省略，交 C2-17 契约校验报必填）", () => {
+		const d = def([
+			{ path: "/space", handle: { category: "main", title: "wiki:menu.space" } },
+		]);
+		const out = deriveManifestRoutes(d);
+		expect(out).toEqual([{ path: "/space", category: "main", title_key: "wiki:menu.space" }]);
+	});
+
+	it("d-2c routes 缺失/空 → 派生为空数组（不抛）", () => {
+		expect(deriveManifestRoutes(def(undefined))).toEqual([]);
+		expect(deriveManifestRoutes(def([]))).toEqual([]);
+	});
+});
+
+describe("reconcileManifestRoutes（entry.ts 为准 + 漂移警告）", () => {
+	it("d-3a 既有 routes 与派生一致：不警告，采用派生", () => {
+		const existing: DerivedRoute[] = [
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+		];
+		const derived: DerivedRoute[] = [
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+		];
+		const { routes, warnings } = reconcileManifestRoutes(existing, derived);
+		expect(routes).toEqual(derived);
+		expect(warnings).toEqual([]);
+	});
+
+	it("d-3b 既有 routes 与派生漂移：以派生为准并发警告（不阻断）", () => {
+		const existing: DerivedRoute[] = [
+			// 旧 manifest 手写的 order 与 category 与 entry.ts 不一致
+			{ path: "/space", category: "admin", order: 999, title_key: "wiki:menu.space" },
+		];
+		const derived: DerivedRoute[] = [
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+		];
+		const { routes, warnings } = reconcileManifestRoutes(existing, derived);
+		expect(routes).toEqual(derived); // 以 entry.ts 为准
+		expect(warnings).toHaveLength(1);
+		expect(warnings[0]).toContain("/space");
+		expect(warnings[0]).toContain("entry.ts 为准");
+	});
+
+	it("d-3c 派生为空（未迁移方案未声明 category）：保留既有 routes，不覆盖", () => {
+		const existing: DerivedRoute[] = [
+			{ path: "/space", category: "main", order: 200, title_key: "wiki:menu.space" },
+		];
+		const { routes, warnings } = reconcileManifestRoutes(existing, []);
+		expect(routes).toEqual(existing); // 沿用既有，向后兼容
+		expect(warnings).toEqual([]);
+	});
+
+	it("d-3d 既有为空且派生为空：结果为空，无警告", () => {
+		const { routes, warnings } = reconcileManifestRoutes([], []);
+		expect(routes).toEqual([]);
+		expect(warnings).toEqual([]);
+	});
+});

package/src/__tests__/usage.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { getCommandHelp, resolveHelpRequest } from "../usage";
+
+describe("getCommandHelp", () => {
+	it("返回命令级帮助（init）", () => {
+		const t = getCommandHelp("init");
+		expect(t).toBeDefined();
+		expect(t).toContain("ojm init");
+	});
+
+	it("子命令优先：market setup 命中专属条目", () => {
+		expect(getCommandHelp("market", "setup")).toContain("ojm market setup");
+	});
+
+	it("子命令无专属条目时回退到命令级（market 无 sub）", () => {
+		const t = getCommandHelp("market");
+		expect(t).toContain("ojm market");
+	});
+
+	it("trust 子命令（add/revoke/confirm/ls）各自有专属条目", () => {
+		for (const sub of ["ls", "add", "revoke", "confirm"]) {
+			const t = getCommandHelp("trust", sub);
+			expect(t, `trust ${sub}`).toBeDefined();
+			expect(t).toContain(`ojm trust ${sub}`);
+		}
+	});
+
+	it("未知命令返回 undefined", () => {
+		expect(getCommandHelp("nope")).toBeUndefined();
+	});
+});
+
+describe("resolveHelpRequest", () => {
+	it("ojm --help → 顶层（无 cmd）", () => {
+		expect(resolveHelpRequest(["--help"])).toEqual({ cmd: undefined, sub: undefined });
+	});
+
+	it("ojm -h → 顶层（无 cmd）", () => {
+		expect(resolveHelpRequest(["-h"])).toEqual({ cmd: undefined, sub: undefined });
+	});
+
+	it("ojm init --help → cmd=init", () => {
+		expect(resolveHelpRequest(["init", "--help"])).toEqual({ cmd: "init", sub: undefined });
+	});
+
+	it("ojm trust add --help → cmd=trust sub=add", () => {
+		expect(resolveHelpRequest(["trust", "add", "--help"])).toEqual({ cmd: "trust", sub: "add" });
+	});
+
+	it("ojm market setup --help → cmd=market sub=setup", () => {
+		expect(resolveHelpRequest(["market", "setup", "--help"])).toEqual({ cmd: "market", sub: "setup" });
+	});
+
+	it("ojm help init → cmd=init", () => {
+		expect(resolveHelpRequest(["help", "init"])).toEqual({ cmd: "init", sub: undefined });
+	});
+
+	it("ojm help trust add → cmd=trust sub=add", () => {
+		expect(resolveHelpRequest(["help", "trust", "add"])).toEqual({ cmd: "trust", sub: "add" });
+	});
+
+	it("ojm help → 顶层（无 cmd）", () => {
+		expect(resolveHelpRequest(["help"])).toEqual({ cmd: undefined, sub: undefined });
+	});
+
+	it("非帮助调用返回 null（ojm build）", () => {
+		expect(resolveHelpRequest(["build", "--bundle"])).toBeNull();
+	});
+});

package/src/build.ts

@@ -1,5 +1,6 @@
 import type { Plugin as EsbuildPlugin } from "esbuild";
 import type { Plugin } from "vite";
+import type { RouteDefinitionLike } from "./manifest-routes-derive";
 import { execFileSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -12,6 +13,7 @@ import { build } from "vite";
 import { loadModulesConfig, resolveModuleEntry } from "./config";
 import { resolveConfigPath, resolveLayout } from "./layout";
 import { isSharedDep, SHARED_DEPS } from "./shared-deps";
+import { normalizeSiteBase, rewriteIndexHtml } from "./site-base";
 import { resolveOjBin } from "./vendor";
 import { checkSharedVersions, resolveShellDist } from "./versions";
 
@@ -138,6 +140,9 @@ export const mapTree = _fn;
 export const getAllExpandedKeys = _fn;
 export const getAppInfo = _fn;
 export const getRedirectPath = _fn;
+// 站点部署 base（子路径部署）：stub 只需占位，元数据读取期不拼 URL
+export const resolveSiteBase = _fn;
+export const withSiteBase = _fn;
 export const getYesNoOptions = _fn;
 export const getBooleanOptions = _fn;
 // 模块契约
@@ -387,6 +392,9 @@ export async function readModuleDefinition(entryFile: string, projectRoot: strin
 			version: string
 			peerRuntime?: string
 			config?: { dependencies?: string[] }
+			// R5：entry.ts 声明的路由树（含 handle.category/order/title），
+			// buildBundle 据此派生 manifest.routes（单一真源，避免手工双写漂移）
+			routes?: RouteDefinitionLike[]
 		};
 	}
 	finally {
@@ -528,12 +536,22 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
  * 再由模块构建写入 modules.json 与 modules/。清场防旧哈希资产无限累积
  * （shell 每次重构建生成新哈希文件名）；devServer 热重建路径不合并——
  * dev 的 / 与 /assets/* 直接服务 shell dist，合并产物无人消费。
+ *
+ * siteBase 非空时（站点挂载在 `/oj` 这类子路径）改写 index.html 的站内绝对
+ * URL 并注入 `window.__OJ_BASE__`（见 site-base.ts）；为空则产物与既有行为
+ * 逐字节一致。
  */
-function mergeShellSite(distDir: string): void {
+function mergeShellSite(distDir: string, siteBase: 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)} 重写（子路径部署）`);
+	}
 	console.log(`[ojm] 已合并宿主站点 → ${distDir}`);
 }
 
@@ -557,7 +575,7 @@ export async function buildModules(
 	const baseUrl = config.baseUrl ?? "";
 
 	if (opts.mergeSite)
-		mergeShellSite(outDir);
+		mergeShellSite(outDir, config.siteBase ?? "");
 
 	// P4.5 / C4 / D12：构建前先过版本矩阵门禁，版本漂移直接拒绝
 	checkSharedVersions(projectRoot, resolveShellDist());

package/src/bundle.ts

@@ -10,8 +10,11 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { parse } from "yaml";
+import { readModuleDefinition } from "./build";
 import { createDeterministicTgz } from "./deterministic-tar";
+import { resolveLayout } from "./layout";
 import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, referencedI18nKeys, validateContract } from "./manifest-contract";
+import { deriveManifestRoutes, reconcileManifestRoutes } from "./manifest-routes-derive";
 
 export interface BundleBuildResult {
 	tgz: string
@@ -37,11 +40,34 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 		throw new Error(`[ojm] 方案包构建失败：${parsed.error}`);
 	}
 	const m = parsed.manifest;
+	const name = m.name as string;
+
+	// R5：manifest.routes 由 entry.ts 路由 handle 自动派生（单一真源），覆盖手工书写。
+	// 仅当 entry.ts 声明了 category 路由才覆盖；否则保留 manifest 既有 routes（未迁移方案兼容）。
+	// entry 读不出来（如第三依赖未装）时软降级：沿用既有 routes，不阻断打包。
+	const layout = resolveLayout(projectRoot);
+	const entryFile = path.join(layout.modulesSrc, name, "entry.ts");
+	if (fs.existsSync(entryFile)) {
+		try {
+			const def = await readModuleDefinition(entryFile, projectRoot);
+			const derived = deriveManifestRoutes(def);
+			const { routes, warnings } = reconcileManifestRoutes(
+				Array.isArray(m.routes) ? m.routes : [],
+				derived,
+			);
+			for (const w of warnings)
+				console.warn(w);
+			m.routes = routes;
+		}
+		catch (e) {
+			console.warn(`[ojm] ⚠️ 无法从 entry.ts 派生 routes（${e instanceof Error ? e.message : String(e)}），沿用 manifest.yaml 既有 routes`);
+		}
+	}
+
 	const violations = validateContract(m);
 	if (violations.length > 0) {
 		throw new Error(`[ojm] 方案包构建失败：manifest.yaml 契约校验未通过（${violations.length} 项违规，全量列出）：\n${violations.map(x => `- ${x}`).join("\n")}`);
 	}
-	const name = m.name as string;
 	const version = m.version as string;
 
 	// 2) 文件面契约（§4.1 构建列专属执行点；manifest 内在规则已在 validateContract 全量通过）

package/src/config.ts

@@ -12,6 +12,19 @@ export interface ModuleConfigEntry {
 export interface ModulesConfig {
 	/** 产物 URL 前缀，留空表示同源相对路径 */
 	baseUrl?: string
+	/**
+	 * 站点部署子路径（如 `"/oj"`），留空 = 挂在域名根。
+	 *
+	 * 站点被 oj 挂到 `mounts: [{ prefix: /oj, web: dist, spa: true }]` 这类非根
+	 * 前缀时**必须**配它：`ojm build` 会把全站 index.html 的站内绝对 URL
+	 * （importmap / `<script src>` / `<link href>`）改写为 `/oj/...`，并注入
+	 * `window.__OJ_BASE__` 供路由 basename 与模块资源解析取用。
+	 * 不配则浏览器去域名根取 `/assets/*` → 404 白屏，深链刷新也匹配不到路由。
+	 *
+	 * 与 `baseUrl` 的区别：`baseUrl` 是**模块产物**的 URL 前缀（可指向 CDN
+	 * 绝对域），`siteBase` 是**站点自身**的部署位置；两者正交，可同时使用。
+	 */
+	siteBase?: string
 	modules: ModuleConfigEntry[]
 	/**
 	 * 站点 HTML 变换模块（可选）：相对工程根的路径（`./html-transform.ts`）
@@ -24,8 +37,9 @@ export interface ModulesConfig {
 	htmlTransform?: string
 }
 
-const DEFAULT_CONFIG: Required<Pick<ModulesConfig, "baseUrl">> = {
+const DEFAULT_CONFIG: Required<Pick<ModulesConfig, "baseUrl" | "siteBase">> = {
 	baseUrl: "",
+	siteBase: "",
 };
 
 /**
@@ -34,7 +48,7 @@ const DEFAULT_CONFIG: Required<Pick<ModulesConfig, "baseUrl">> = {
  * 用 tsx 真实 import，而不是正则解析——这样配置文件里可以写注释、
  * 用变量、做条件判断，且类型错误会直接暴露（B10 的正则方案做不到）。
  */
-export async function loadModulesConfig(projectRoot: string): Promise<ModulesConfig & { baseUrl: string }> {
+export async function loadModulesConfig(projectRoot: string): Promise<ModulesConfig & { baseUrl: string, siteBase: string }> {
 	const configPath = path.join(projectRoot, "web.config.ts");
 
 	let mod: { default?: ModulesConfig };

package/src/index.ts

@@ -8,7 +8,7 @@ import { devServer } from "./dev";
 import { mergeManifests, printInfo } from "./info";
 import { initProject } from "./init";
 import { runPreview } from "./preview";
-import { usageText } from "./usage";
+import { getCommandHelp, resolveHelpRequest, usageText } from "./usage";
 import { vendorCommand } from "./vendor";
 import { readCliVersion } from "./versions";
 
@@ -25,6 +25,23 @@ function usage(): never {
 async function main() {
 	const projectRoot = process.cwd();
 
+	// 帮助请求：`ojm <cmd> --help` / `ojm help <cmd>` / 顶层 `ojm --help`
+	// 必须在 switch 之前拦截，否则会真正执行子命令（如 `ojm market setup --help` 会去建 CDN）。
+	const helpReq = resolveHelpRequest();
+	if (helpReq !== null) {
+		if (!helpReq.cmd) {
+			console.log(usageText());
+			return;
+		}
+		const text = getCommandHelp(helpReq.cmd, helpReq.sub);
+		if (text) {
+			console.log(text);
+			return;
+		}
+		console.error(`[ojm] 未知命令：${helpReq.cmd}${helpReq.sub ? ` ${helpReq.sub}` : ""}`);
+		process.exit(1);
+	}
+
 	// 顶层 --version / -V：打印 cli 包版本（与 `ojm info` 的 cli 版本同源）
 	if (command === "--version" || command === "-V") {
 		console.log(readCliVersion());

package/src/manifest-routes-derive.ts

@@ -0,0 +1,130 @@
+// R5：manifest.yaml `routes` 由 entry.ts 路由 handle 自动派生（单一真源）。
+//
+// 背景：0.2.15 时期 manifest.routes 由作者手工书写，且 runtime 分组还依赖
+// `sys_solution_route` 表行（dev 下该表空 → 不分组，见上游 wiki parity 方案 R1–R6）。
+// 0.2.16 起：category/order/title 的真源是 entry.ts 路由 handle，manifest.routes
+// 改为 build 期从 handle 派生，杜绝「entry.ts 改了 handle 但 manifest.yaml 没同步」的漂移。
+//
+// 派生口径（仅取顶层一级菜单路由；children 是动态段/子页，不进 manifest routes）：
+//   - handle.category ∈ {main,admin,hidden} 才纳入（无 category 的路由不进菜单，跳过）
+//   - path      ← route.path
+//   - category  ← handle.category
+//   - order     ← handle.order（缺省不写，交 C2-17 契约校验报「必填整数」）
+//   - title_key ← handle.title（main/admin 必填且须匹配 <name>:menu.*，契约校验）
+//
+// 兼容：entry.ts 未声明任何 category 路由时（迁移前的旧方案），调用方保留 manifest
+// 既有 routes，不强制覆盖——避免未迁移方案构建即坏。
+
+/** entry.ts 路由树节点（派生只读字段，宽松结构，避免 import runtime 类型形成环） */
+export interface RouteDefinitionLike {
+	path?: string
+	handle?: {
+		category?: "main" | "admin" | "hidden"
+		order?: number
+		title?: string
+		[key: string]: unknown
+	}
+	children?: RouteDefinitionLike[]
+	[key: string]: unknown
+}
+
+/** 派生出的 manifest route 契约项（字段口径见 C2-17） */
+export interface DerivedRoute {
+	path: string
+	category: "main" | "admin" | "hidden"
+	order?: number
+	title_key?: string
+}
+
+/** 模块定义（只需 name + routes 子集，宽松结构） */
+export interface ModuleDefinitionLike {
+	name: string
+	routes?: RouteDefinitionLike[]
+	[key: string]: unknown
+}
+
+/**
+ * 从 entry.ts 模块定义派生 manifest routes（仅顶层一级菜单路由）。
+ * 不抛异常：handle 缺字段时照常产出，交由 C2-17 契约校验报出具体违规项。
+ */
+export function deriveManifestRoutes(definition: ModuleDefinitionLike): DerivedRoute[] {
+	const routes = Array.isArray(definition.routes) ? definition.routes : [];
+	const out: DerivedRoute[] = [];
+	for (const r of routes) {
+		if (r === null || typeof r !== "object")
+			continue;
+		const handle = (typeof r.handle === "object" && r.handle !== null) ? r.handle : undefined;
+		const category = handle?.category;
+		if (category !== "main" && category !== "admin" && category !== "hidden")
+			continue;
+		if (typeof r.path !== "string" || r.path.length === 0)
+			continue;
+		const route: DerivedRoute = { path: r.path, category };
+		if (typeof handle?.order === "number")
+			route.order = handle.order;
+		if (typeof handle?.title === "string")
+			route.title_key = handle.title;
+		out.push(route);
+	}
+	return out;
+}
+
+/**
+ * 归并既有 manifest routes 与 entry.ts 派生 routes，返回最终采用项 + 警告。
+ *
+ * 规则（单一真源 = entry.ts）：
+ *   - derived 为空（entry.ts 未声明任何 category 路由）→ 沿用 existing，不覆盖（向后兼容）
+ *   - derived 非空 → 以 derived 为准；若 existing 非空且与 derived 在某 path 上漂移
+ *     （category/order/title_key 任一不一致）→ 追加警告（不阻断，R5 选择项「自动生成」而非「双写+校验」）
+ */
+export function reconcileManifestRoutes(
+	existing: unknown[],
+	derived: DerivedRoute[],
+): { routes: DerivedRoute[], warnings: string[] } {
+	const warnings: string[] = [];
+	if (derived.length === 0) {
+		// 未迁移方案：保留 manifest 既有 routes，等作者后续在 entry.ts 登记 category
+		return { routes: normalizeExisting(existing), warnings };
+	}
+	const existingByPath = new Map<string, DerivedRoute>();
+	for (const r of normalizeExisting(existing)) {
+		existingByPath.set(r.path, r);
+	}
+	const drift: DerivedRoute[] = [];
+	for (const d of derived) {
+		const e = existingByPath.get(d.path);
+		if (e === undefined)
+			continue;
+		if (e.category !== d.category || e.order !== d.order || e.title_key !== d.title_key) {
+			drift.push(d);
+		}
+	}
+	if (existing.length > 0 && drift.length > 0) {
+		warnings.push(
+			`[ojm] manifest.yaml 既有 routes 与 entry.ts 派生结果不一致，已采用 entry.ts 为准（R5 单一真源，避免手工双写漂移）：\n${
+				drift.map(d => `- ${d.path}（派生 category=${d.category} order=${d.order ?? "?"} title_key=${d.title_key ?? "?"})`).join("\n")}`,
+		);
+	}
+	return { routes: derived, warnings };
+}
+
+function normalizeExisting(existing: unknown[]): DerivedRoute[] {
+	const out: DerivedRoute[] = [];
+	for (const r of existing) {
+		if (r === null || typeof r !== "object")
+			continue;
+		const o = r as Record<string, unknown>;
+		if (typeof o.path !== "string")
+			continue;
+		const cat = o.category;
+		if (cat !== "main" && cat !== "admin" && cat !== "hidden")
+			continue;
+		const route: DerivedRoute = { path: o.path, category: cat };
+		if (typeof o.order === "number")
+			route.order = o.order;
+		if (typeof o.title_key === "string")
+			route.title_key = o.title_key;
+		out.push(route);
+	}
+	return out;
+}

package/src/preview-config.ts

@@ -30,6 +30,12 @@ export const PREVIEW_CONFIG_NAME = ".ojm-preview.yaml";
 export interface DerivePreviewConfigOptions {
 	/** 全站产物目录（layout.distDir），写入 web 挂载的绝对路径 */
 	siteDir: string
+	/**
+	 * web 挂载前缀（默认 `"/"`）。配了 `siteBase` 的工程，产物里 URL 全是
+	 * `/oj/...`，preview 必须把站点挂在同一前缀上才能验证子路径部署
+	 * （否则资源全 404，预览白屏）。
+	 */
+	prefix?: string
 	/**
 	 * release 形态的后端模块根（api/dist）。给了且原 config 声明了 platform.modules 时，
 	 * 把 `platform.root` 一并改写到该目录——特权模块的受控根必须与 `--api-path` 同源，
@@ -78,9 +84,9 @@ function isMountEntry(m: unknown): m is Record<string, unknown> {
 	return m !== null && typeof m === "object" && !Array.isArray(m);
 }
 
-/** 找 prefix === "/" 的 web 挂载条目下标；没有返回 -1 */
-function findRootWebMount(mounts: unknown[]): number {
-	return mounts.findIndex(m => isMountEntry(m) && m.prefix === "/" && "web" in m);
+/** 找指定 prefix 的 web 挂载条目下标；没有返回 -1 */
+function findWebMount(mounts: unknown[], prefix: string): number {
+	return mounts.findIndex(m => isMountEntry(m) && m.prefix === prefix && "web" in m);
 }
 
 /**
@@ -116,13 +122,14 @@ export function derivePreviewConfigText(configText: string, opts: DerivePreviewC
 	const doc = parseConfigDoc(configText, configPath);
 
 	const mounts = [...readMounts(doc, configPath)];
-	const idx = findRootWebMount(mounts);
+	const prefix = opts.prefix ?? "/";
+	const idx = findWebMount(mounts, prefix);
 	if (idx >= 0) {
 		// 保留用户自定义键（headers 等），只接管指向与回落
 		mounts[idx] = { ...(mounts[idx] as Record<string, unknown>), web: opts.siteDir, spa: true };
 	}
 	else {
-		mounts.push({ prefix: "/", web: opts.siteDir, spa: true });
+		mounts.push({ prefix, web: opts.siteDir, spa: true });
 	}
 	doc.mounts = mounts;
 

package/src/preview.ts

@@ -17,6 +17,7 @@
  * 一律传绝对路径：oj 命令行相对 CWD、config 内相对 config 目录，混用即歧义。
  */
 
+import type { ModulesConfig } from "./config";
 import type { OjProcess } from "./oj";
 import type { PreviewConfigFiles } from "./preview-config";
 import { execFileSync } from "node:child_process";
@@ -28,6 +29,7 @@ import { resolveConfigPath, resolveLayout } from "./layout";
 import { startOj } from "./oj";
 import { readOjApiPrefix } from "./oj-config";
 import { hasRootApiMount, parseMounts, writePreviewConfig } from "./preview-config";
+import { normalizeSiteBase } from "./site-base";
 import { resolveOjBin } from "./vendor";
 
 export interface PreviewOptions {
@@ -40,7 +42,7 @@ export interface PreviewOptions {
 	/** 注入桩 oj 进程；默认 startOj */
 	ojStarter?: (configPath: string, base: string, apiPath: string, extraArgs: string[]) => OjProcess
 	/** 注入桩派生 config 落盘（测试）；默认 writePreviewConfig */
-	configWriter?: (projectRoot: string, opts: { siteDir: string, port?: number, apiRoot?: string }) => PreviewConfigFiles
+	configWriter?: (projectRoot: string, opts: { siteDir: string, prefix?: string, port?: number, apiRoot?: string }) => PreviewConfigFiles
 }
 
 export interface PreviewHandle {
@@ -71,7 +73,11 @@ export async function runPreview(projectRoot: string, opts: PreviewOptions = {})
 
 	// DR-5：htmlTransform 存在性检测（只读 web.config.ts 的字段，不 import 变换模块——
 	// 单服务下 oj 直出 HTML，钩子不生效；执行用户代码只会白付副作用）
-	await warnHtmlTransformUnsupported(projectRoot);
+	const moduleConfig = await warnHtmlTransformUnsupported(projectRoot);
+
+	// 站点部署前缀：web.config.ts 的 siteBase（"{siteBase}" → 挂载 prefix "/oj"）。
+	// 产物里的 URL 已按 siteBase 重写，preview 必须挂在同一前缀上，否则白屏。
+	const sitePrefix = mountPrefixOf(moduleConfig?.siteBase);
 
 	const execOj = opts.execOj ?? ((args: string[]) => execFileSync(ojBin, args, { stdio: "inherit" }));
 
@@ -81,12 +87,13 @@ export async function runPreview(projectRoot: string, opts: PreviewOptions = {})
 
 	// 派生 config 在 migrate 成功后落盘：失败即退路径零残留
 	const base = readOjApiPrefix(configPath);
-	const writer = opts.configWriter ?? ((root: string, o: { siteDir: string, port?: number, apiRoot?: string }) => writePreviewConfig(root, o));
+	const writer = opts.configWriter ?? ((root: string, o: { siteDir: string, prefix?: string, port?: number, apiRoot?: string }) => writePreviewConfig(root, o));
 	// apiRoot 交给派生器：release 下 platform.root 必须指向 api/dist（与 --api-path 同源）
-	const preview = writer(projectRoot, { siteDir, port: opts.port, apiRoot: apiDist });
+	const preview = writer(projectRoot, { siteDir, prefix: sitePrefix, port: opts.port, apiRoot: apiDist });
 
-	// / api 挂载与注入的 / web 挂载配对时 oj 不开 SPA 回落（oj 语义，见 devkit 手册 §13）
-	if (hasRootApiMount(parseMounts(readFileSync(configPath, "utf-8"), configPath)))
+	// / api 挂载与注入的 web 挂载配对时 oj 不开 SPA 回落（oj 语义，见 devkit 手册 §13）。
+	// 仅在站点挂根时成立：web 挂到 /oj 时两者不配对，深链回落正常。
+	if (sitePrefix === "/" && hasRootApiMount(parseMounts(readFileSync(configPath, "utf-8"), configPath)))
 		console.warn("[ojm] config 的 api 挂载位于 /：与 web 挂载配对时 oj 不做 SPA 深链回落（已知限制），深链接刷新将 404。");
 
 	const starter = opts.ojStarter ?? ((cfg: string, b: string, apiPath: string, extraArgs: string[]) =>
@@ -111,7 +118,7 @@ export async function runPreview(projectRoot: string, opts: PreviewOptions = {})
 		throw error;
 	}
 	console.log(`[ojm] oj 已就绪（release/js，单服务：${base} API + 静态 SPA 同进程）：http://127.0.0.1:${oj.port}`);
-	console.log(`\n[ojm] preview 已启动：http://localhost:${oj.port}`);
+	console.log(`\n[ojm] preview 已启动：http://localhost:${oj.port}${sitePrefix === "/" ? "" : sitePrefix}`);
 	console.log(`[ojm] 静态由 oj web 挂载直出（spa 深链回落）；派生 config ${path.basename(preview.configPath)} 为本进程临时产物，退出自动清理`);
 
 	// 退出回收：派生 config 必须随 oj 一起消亡（test/integration 断言其不存在）
@@ -150,10 +157,11 @@ export async function runPreview(projectRoot: string, opts: PreviewOptions = {})
 }
 
 /**
- * web.config.ts 配了 htmlTransform → WARN。加载失败（缺文件/坏配置）静默
- * 跳过：能走到 preview 的工程必然过 ojm build，config 问题会在那里先炸。
+ * web.config.ts 配了 htmlTransform → WARN；返回已加载的配置（preview 还要读
+ * siteBase 决定挂载前缀）。加载失败（缺文件/坏配置）静默跳过：能走到 preview
+ * 的工程必然过 ojm build，config 问题会在那里先炸。
  */
-async function warnHtmlTransformUnsupported(projectRoot: string): Promise<void> {
+async function warnHtmlTransformUnsupported(projectRoot: string): Promise<ModulesConfig | undefined> {
 	try {
 		const config = await loadModulesConfig(projectRoot);
 		if (config.htmlTransform) {
@@ -163,8 +171,21 @@ async function warnHtmlTransformUnsupported(projectRoot: string): Promise<void>
 				+ "见 bin/devkit/api-manual.md「静态站点与 per-route meta」。",
 			);
 		}
+		return config;
 	}
 	catch {
 		// config 加载失败：不阻塞 preview（build 已先行校验过）
+		return undefined;
 	}
 }
+
+/**
+ * `siteBase`（`"/oj"` / `"/oj/"` / 空）→ oj 挂载 prefix（`"/oj"` / `"/"`）。
+ *
+ * 两者只差尾斜杠：`siteBase` 是 URL 拼接口径（恒带尾斜杠），oj 的 mount
+ * prefix 是路径口径（不带尾斜杠，见模板 config 的 `/api`）。
+ */
+function mountPrefixOf(siteBase: string | undefined): string {
+	const normalized = normalizeSiteBase(siteBase);
+	return normalized === "/" ? "/" : normalized.slice(0, -1);
+}