@oj-module/cli 0.2.17 → 0.2.20

package/src/lifecycle/__tests__/manifest-contract.test.ts

@@ -1,4 +1,4 @@
-import type { InstallContext } from "../../../templates/api/src/_platform/_lifecycle/steps/preflight";
+import type { InstallContext } from "../../../templates/src/_platform/api/_lifecycle/steps/preflight";
 
 // BDD：bundle 级 manifest.yaml 契约校验（P1-11，C2 规则构建列）。
 // 规则真源：docs/prd/solution/202610171254-lifecycle-manifest-contract.md（C2-01~33 构建列，§4.1 矩阵）；
@@ -13,8 +13,8 @@ import { describe, expect, it } from "vitest";
 import { parse } from "yaml";
 // 跨端引用（双端一致钉）：被测实现同仓分居两运行时（计划 §1「两运行时取舍」），
 // 测试直接互调，比「两套件各读同一夹具」更强——漂移即本文件红。
-import { preflight } from "../../../templates/api/src/_platform/_lifecycle/steps/preflight";
-import { checkLocalesComplete, checkTablesAgainstSchema, groupI18nKeys, parseManifest, validateContract } from "../../manifest-contract";
+import { preflight } from "../../../templates/src/_platform/api/_lifecycle/steps/preflight";
+import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, validateContract } from "../../manifest-contract";
 
 const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "fixtures");
 const readText = (p: string) => readFileSync(join(FIXTURES, p), "utf8");
@@ -214,72 +214,31 @@ describe("checkLocalesComplete（C2-25：构建期缺 key fail-fast）", () => {
 	});
 });
 
-// ── C2-43 归组父标题 i18n（solution menu grouping；纯内容入参）──
+// ── 归组父标题不再进引用面（0.2.18：`menu.main` 是模块级标题的唯一真源）──
 
-describe("c2-43 归组父标题 i18n（solution menu grouping）", () => {
+describe("main/admin 路由不再要求归组父标题", () => {
 	const baseManifest = (): any => ({
 		name: "demo-solution",
 		version: "0.1.0",
 		routes: [
 			{ path: "/demo-solution", category: "main", order: 200, title_key: "demo-solution:menu.main" },
+			{ path: "/demo-solution/users", category: "admin", order: 210, title_key: "demo-solution:menu.users" },
 		],
 	});
-	const ZH_FULL = JSON.stringify({ menu: { main: "主", group: "分组" } });
-	const EN_FULL = JSON.stringify({ menu: { main: "Main", group: "Group" } });
 
-	it("groupI18nKeys：声明 main/admin 路由才产一条 <name>:menu.group", () => {
-		expect(groupI18nKeys(baseManifest())).toEqual(["demo-solution:menu.group"]);
+	it("声明 main/admin 路由、locale 只有 menu.main → 零违规", () => {
+		const zh = JSON.stringify({ menu: { main: "主", users: "用户" } });
+		const en = JSON.stringify({ menu: { main: "Main", users: "Users" } });
+		expect(checkLocalesComplete(baseManifest(), zh, en)).toEqual([]);
 	});
 
-	it("groupI18nKeys：多条 main 路由去重只产一条（C5）", () => {
-		const m = baseManifest();
-		m.routes = [
-			{ path: "/a", category: "main", order: 200, title_key: "demo-solution:menu.a" },
-			{ path: "/b", category: "main", order: 210, title_key: "demo-solution:menu.b" },
-		];
-		expect(groupI18nKeys(m)).toEqual(["demo-solution:menu.group"]);
-	});
-
-	it("groupI18nKeys：仅 hidden 路由不产 group key（C3）", () => {
-		const m = baseManifest();
-		m.routes = [{ path: "/x", category: "hidden", order: 210, title_key: "demo-solution:menu.x" }];
-		expect(groupI18nKeys(m)).toEqual([]);
-	});
-
-	it("c1 正例：menu.group 双语齐备 → 零违规", () => {
-		expect(checkLocalesComplete(baseManifest(), ZH_FULL, EN_FULL)).toEqual([]);
-	});
-
-	it("c2 反例：zh-CN 缺 menu.group → C2-43（非 C2-25，去重生效）", () => {
-		const zh = JSON.stringify({ menu: { main: "主" } });
-		const v = checkLocalesComplete(baseManifest(), zh, EN_FULL);
-		const hit = v.find(x => x.includes("C2-43"));
-		expect(hit, `期望 C2-43，实际：\n${v.join("\n")}`).toBeTruthy();
-		expect(hit).not.toContain("C2-25");
-		expect(hit).toContain("menu.group");
-	});
-
-	it("c4 反例：en-US 缺 menu.group → C2-43 指明 en-US", () => {
-		const en = JSON.stringify({ menu: { main: "Main" } });
-		const v = checkLocalesComplete(baseManifest(), ZH_FULL, en);
-		const hit = v.find(x => x.includes("C2-43"));
-		expect(hit).toBeTruthy();
-		expect(hit).toContain("en-US");
-	});
-
-	it("去重：多条 main 路由只产一条 group key，缺失时按语言各报一次（非按路由重复）", () => {
-		const m = baseManifest();
-		m.routes = [
-			{ path: "/a", category: "main", order: 200, title_key: "demo-solution:menu.a" },
-			{ path: "/b", category: "main", order: 210, title_key: "demo-solution:menu.b" },
-		];
-		const v = checkLocalesComplete(m, JSON.stringify({ menu: { main: "主" } }), JSON.stringify({ menu: { main: "Main" } }));
-		const c243 = v.filter(x => x.includes("C2-43"));
-		// 关键：2 条路由只产 1 个 group key → 缺失时按语言各报 1 次 = 2 条 C2-43，
-		// 而非 2 路由 × 2 语言 = 4 条（去重生效的判据是「< 路由数 × 语言数」）
-		expect(c243.length).toBe(2);
-		expect(c243.some(x => x.includes("zh-CN 缺少归组父标题 key「demo-solution:menu.group」"))).toBe(true);
-		expect(c243.some(x => x.includes("en-US 缺少归组父标题 key「demo-solution:menu.group」"))).toBe(true);
+	it("根标题 menu.main 仍受 C2-25 约束：缺则报 C2-25", () => {
+		const zh = JSON.stringify({ menu: { users: "用户" } });
+		const en = JSON.stringify({ menu: { main: "Main", users: "Users" } });
+		const v = checkLocalesComplete(baseManifest(), zh, en);
+		expect(v).toHaveLength(1);
+		expect(v[0]).toContain("C2-25");
+		expect(v[0]).toContain("demo-solution:menu.main");
 	});
 });
 

package/src/manifest-contract.ts

@@ -1,5 +1,5 @@
 // bundle 级 manifest.yaml 契约校验（P1-11，`ojm build --bundle` 构建期执行点）。
-// 规则真源：docs/prd/solution/202610171254-lifecycle-manifest-contract.md §2/§4（C2-01~33 构建列；C2-34~42 为归档签名与信任，见 sign.ts；本文件新增 C2-43）；
+// 规则真源：docs/prd/solution/202610171254-lifecycle-manifest-contract.md §2/§4（C2-01~33 构建列；C2-34~42 为归档签名与信任，见 sign.ts）；
 // 期望真源：src/lifecycle/__tests__/fixtures/（fixture-valid 零违规 / fixture-invalid 七码齐报）。
 // 双端一致：本实现与 isolate 侧 preflight（templates/api/.../steps/preflight.ts）共享同一组夹具，
 // 正则与规则**逐字一致**（§4.1 矩阵构建列 vs 安装列的执行点差异见各规则注释）——
@@ -581,15 +581,6 @@ export function validateContract(m: unknown): string[] {
 	return v0;
 }
 
-/** C2-43 引用面：声明 main/admin 路由的方案须提供归组父标题 `<name>:menu.group`（单 bundle 单 name，去重只产一条） */
-export function groupI18nKeys(m: BundleManifest): string[] {
-	if (!isObj(m) || typeof m.name !== "string")
-		return [];
-	const routes = Array.isArray(m.routes) ? m.routes : [];
-	const hasGroupable = routes.some(r => isObj(r) && (r.category === "main" || r.category === "admin"));
-	return hasGroupable ? [`${m.name}:menu.group`] : [];
-}
-
 /** 收集 manifest 引用的全部 i18n key（C2-25 locales 齐备检查的引用面；bundle.ts 以此判定 locales 文件是否必查） */
 export function referencedI18nKeys(m: BundleManifest): string[] {
 	const keys: string[] = [];
@@ -620,10 +611,6 @@ export function referencedI18nKeys(m: BundleManifest): string[] {
 			}
 		}
 	}
-	// C2-43：归组父标题纳入引用面，交由 checkLocalesComplete 双语齐备（改报 C2-43）
-	for (const k of groupI18nKeys(m)) {
-		keys.push(k);
-	}
 	return keys;
 }
 
@@ -646,12 +633,9 @@ export function checkLocalesComplete(m: unknown, zhText: string, enText: string)
 	if (!isObj(m))
 		return [v("C2-25", "manifest 不是键值对象，无法核对 locales 引用")];
 	const locales: [string, Record<string, unknown> | null][] = [["zh-CN", parseJson(zhText)], ["en-US", parseJson(enText)]];
-	// group key 识别（C2-43）：归组父标题缺失须归因 C2-43 而非笼统 C2-25，避免重复报错
-	const groupKeys = new Set(groupI18nKeys(m));
 	const out: string[] = [];
 	for (const key of referencedI18nKeys(m)) {
 		const nsKey = key.includes(":") ? key.slice(key.indexOf(":") + 1) : key;
-		const isGroup = groupKeys.has(key);
 		for (const [lang, tree] of locales) {
 			if (tree === null) {
 				out.push(v("C2-25", `${lang} locale 不是合法 JSON 对象，无法核对引用 key`));
@@ -659,14 +643,7 @@ export function checkLocalesComplete(m: unknown, zhText: string, enText: string)
 			}
 			const val = lookupKey(tree, nsKey);
 			if (typeof val !== "string" || val === "") {
-				out.push(
-					v(
-						isGroup ? "C2-43" : "C2-25",
-						isGroup
-							? `${lang} 缺少归组父标题 key「${key}」（须为嵌套 menu.group，C2-43；声明 main/admin 路由即须提供）`
-							: `${lang} 缺少 manifest 引用的 key「${key}」（双语齐备，D4；构建期 fail-fast）`,
-					),
-				);
+				out.push(v("C2-25", `${lang} 缺少 manifest 引用的 key「${key}」（双语齐备，D4；构建期 fail-fast）`));
 			}
 		}
 	}

package/src/market/__tests__/bootstrap.test.ts

@@ -28,8 +28,16 @@ function fakeStarter() {
 function newSourceProject(): string {
 	const root = mkdtempSync(join(tmpdir(), "ojm-bootstrap-src-"));
 	mkdirSync(join(root, "bin", "plugins"), { recursive: true });
-	writeFileSync(join(root, "bin", "oj"), "#!/bin/sh\necho fake-oj\n", { mode: 0o755 });
-	writeFileSync(join(root, "bin", ".oj-version"), "v0.1.84\n");
+	// 假 oj 必须过 §7 双探：`-V` 报版本、`build --help` 含 --module-root，否则 buildBackend 在闸门处 fail-fast
+	writeFileSync(
+		join(root, "bin", "oj"),
+		"#!/bin/sh\n"
+		+ "if [ \"$1\" = \"-V\" ]; then echo oj 0.1.85; exit 0; fi\n"
+		+ "if [ \"$1\" = \"build\" ]; then echo \"      --module-root <MODULE_ROOT>  源码树根\"; exit 0; fi\n"
+		+ "echo fake-oj\n",
+		{ mode: 0o755 },
+	);
+	writeFileSync(join(root, "bin", ".oj-version"), "v0.1.85\n");
 	writeFileSync(join(root, "bin", "plugins", "auth.wasm"), "plugin", "utf-8");
 	mkdirSync(join(root, "api", "src", "_platform"), { recursive: true });
 	writeFileSync(join(root, "api", "src", "_platform", "seed.sql"), "-- seed\n", "utf-8");
@@ -60,7 +68,7 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 
 		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
 
-		expect(existsSync(join(site.root, "api", "src", "_platform", "seed.sql"))).toBe(true);
+		expect(existsSync(join(site.root, "src", "_platform", "api", "seed.sql"))).toBe(true);
 		expect(existsSync(join(site.root, "bin", "oj"))).toBe(true);
 		expect(existsSync(join(site.root, "bin", "plugins", "auth.wasm"))).toBe(true);
 		expect(site.root).not.toBe(src);
@@ -75,8 +83,8 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 
 		expect(site.port).toBeGreaterThan(1024);
 		expect(site.port).not.toBe(9778);
-		expect(started[0]?.configPath).toBe(join(site.root, "api", "config.yaml"));
-		const cfg = readFileSync(join(site.root, "api", "config.yaml"), "utf-8");
+		expect(started[0]?.configPath).toBe(join(site.root, "config.yaml"));
+		const cfg = readFileSync(join(site.root, "config.yaml"), "utf-8");
 		expect(cfg).toContain(`port: ${site.port}`);
 		await site.cleanup();
 	});
@@ -87,7 +95,7 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 
 		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
 
-		const cfg = readFileSync(join(site.root, "api", "config.yaml"), "utf-8");
+		const cfg = readFileSync(join(site.root, "config.yaml"), "utf-8");
 		expect(cfg).not.toContain("__JWT_SECRET__");
 		await site.cleanup();
 	});
@@ -113,7 +121,8 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 
 		expect(site.publisher.privateKeyPem).toContain("PRIVATE KEY");
 		const pemFiles = listFiles(site.root).filter(f => f.endsWith(".pem"));
-		const outside = pemFiles.filter(f => !f.includes("api/config"));
+		// listFiles 返回相对隔离根的路径；站点自身证书三件套在 config/ 下，其余任何 PEM 都是泄漏
+		const outside = pemFiles.filter(f => !f.startsWith("config/"));
 		expect(outside).toEqual([]);
 		await site.cleanup();
 	});
@@ -144,8 +153,7 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 describe("given 源工程没装 oj 二进制 When 自举", () => {
 	it("then 人话报错指向 ojm vendor，且不留半成品临时根", async () => {
 		const root = mkdtempSync(join(tmpdir(), "ojm-bootstrap-nooj-"));
-		mkdirSync(join(root, "api"), { recursive: true });
-		writeFileSync(join(root, "api", "config.yaml"), "server:\n  port: 9778\n", "utf-8");
+		writeFileSync(join(root, "config.yaml"), "server:\n  port: 9778\n", "utf-8");
 		const { starter } = fakeStarter();
 
 		await expect(bootstrapIsolatedSite({ projectRoot: root, starter }))

package/src/market/bootstrap.ts

@@ -18,7 +18,7 @@
 import type { OjProcess } from "../oj";
 import { Buffer } from "node:buffer";
 import { createHash, createPrivateKey, randomBytes } from "node:crypto";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import net from "node:net";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -26,6 +26,7 @@ import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { buildBackend } from "../build";
+import { resolveLayout } from "../layout";
 import { exportRawPublicKeyHex, fingerprintOfPublicKey } from "../lifecycle/sign";
 import { startOj } from "../oj";
 import { mintDevCert } from "../oj-cert";
@@ -49,7 +50,7 @@ export interface IsolatedPublisher {
 }
 
 export interface IsolatedSite {
-	/** 临时根（含 api/ bin/ cdn/） */
+	/** 临时根（含 config.yaml / src/ / api/dist/ / bin/ / cdn/） */
 	root: string
 	port: number
 	baseUrl: string
@@ -94,19 +95,26 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 	}
 
 	const root = mkdtempSync(path.join(tmpdir(), "ojm-trial-"));
-	const apiDir = path.join(root, "api");
-	const configPath = path.join(apiDir, "config.yaml");
+	// 新布局（`src/<name>/{api,web}`）：config.yaml 在隔离根，源码树根为 <root>/src，
+	// 构建产物仍是扁平根 <root>/api/dist（与真实工程同形）。
+	const srcDir = path.join(root, "src");
+	const configPath = path.join(root, "config.yaml");
 	const cdnDir = path.join(root, "cdn");
-	const dbPath = path.join(apiDir, "db.sqlite");
+	const dbPath = path.join(root, "db.sqlite");
 
-	// 1) api 树 + config（模板由 cli 包内置，init 同源；与 cli→templates 依赖红线不冲突——那是运行期文件而非 import）
+	// 1) 后端源码树 + config（模板由 cli 包内置，init 同源；与 cli→templates 依赖红线不冲突——那是运行期文件而非 import）
 	const cliRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
-	const templateApi = path.join(cliRoot, "templates", "api");
-	if (!existsSync(path.join(templateApi, "config.yaml"))) {
-		throw new Error(`[ojm] cli 内置模板缺失：${templateApi}（@oj-module/cli 安装不完整？）`);
+	const templateDir = path.join(cliRoot, "templates");
+	if (!existsSync(path.join(templateDir, "config.yaml"))) {
+		throw new Error(`[ojm] cli 内置模板缺失：${templateDir}（@oj-module/cli 安装不完整？）`);
 	}
-	cpSync(path.join(templateApi, "src"), path.join(apiDir, "src"), { recursive: true });
-	writeFileSync(configPath, readFileSync(path.join(templateApi, "config.yaml"), "utf-8"), "utf-8");
+	// 只拷后端侧（`src/<name>/api`）：隔离站点不构建前端，web 源码拷过去只是噪音
+	for (const entry of readdirSync(path.join(templateDir, "src"), { withFileTypes: true })) {
+		const apiSide = path.join(templateDir, "src", entry.name, "api");
+		if (entry.isDirectory() && existsSync(apiSide))
+			cpSync(apiSide, path.join(srcDir, entry.name, "api"), { recursive: true });
+	}
+	writeFileSync(configPath, readFileSync(path.join(templateDir, "config.yaml"), "utf-8"), "utf-8");
 
 	// 2) oj 二进制与插件（startOj 按 <root>/bin/oj 解析；plugins 让 auth 插件可用）
 	mkdirSync(path.join(root, "bin"), { recursive: true });
@@ -134,10 +142,13 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 	const siteDir = path.join(root, "site");
 	mkdirSync(siteDir, { recursive: true });
 	writeFileSync(path.join(siteDir, "index.html"), "<!doctype html><html><body>ojm trial site</body></html>\n", "utf-8");
-	cfg = cfg.replace("web: ../cdn", `web: ${cdnDir}\n  - prefix: /\n    web: ${siteDir}\n    spa: true`);
+	cfg = cfg.replace("web: ./cdn", `web: ${cdnDir}\n  - prefix: /\n    web: ${siteDir}\n    spa: true`);
 	// 安装目标恒为 release 部署：装好的模块落在 api/dist，dev 形态（--api-path src）发现不了。
 	// 故隔离站点以 dist 起站，platform.root 同步改写（oj 校验 root 必须是生效的 api 挂载目录）。
-	cfg = cfg.replace("  root: src", "  root: dist");
+	// root 相对 **config 所在目录** 解析——config 在隔离根，产物在 <root>/api/dist，故不能写死
+	// `dist`（那是 config 还在 api/ 时的旧口径），按布局取值。
+	const apiDistRel = path.relative(root, resolveLayout(root).apiDist).split(path.sep).join("/");
+	cfg = cfg.replace("  root: src", `  root: ${apiDistRel}`);
 	// auth 守卫在装配期读 anonymous_paths，安装器注册的新匿名端点要重启才生效（首次安装 smoke 会 401）。
 	// 隔离站点直接预置被测方案的探活路径——与 scripts/verify-solution-smoke/bootstrap-host.mjs 同手法，
 	// 让 trial 验的是安装机制本身，而不是重启时序。
@@ -149,8 +160,8 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 		cfg = `${cfg.trimEnd()}\nfs:\n  root: .\n  readonly: false\n`;
 	writeFileSync(configPath, cfg, "utf-8");
 
-	// 4) 站点开发证书（oj serve 无绕过开关；mintDevCert 落 api/config 三件套）
-	await mintDevCert(path.join(apiDir, "config"));
+	// 4) 站点开发证书（oj serve 无绕过开关；mintDevCert 落 config.yaml 同级的 config/ 三件套）
+	await mintDevCert(path.join(root, "config"));
 
 	// 5) 一次性发布方身份：seed 派生，私钥只在内存
 	const keyId = "trial.publisher";
@@ -168,7 +179,7 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 	const starter = opts.starter ?? ((cfgPath: string, base: string, apiSrc: string) => startOj(cfgPath, base, apiSrc));
 	let oj: OjProcess;
 	try {
-		oj = starter(configPath, "/api", path.join(apiDir, "dist"));
+		oj = starter(configPath, "/api", path.join(root, "api", "dist"));
 		await oj.ready;
 	}
 	catch (error) {
@@ -245,7 +256,9 @@ function freePort(): Promise<number> {
 function teardownReport(root: string, port: number): string[] {
 	const lines = [
 		`隔离根：${root}`,
-		"  api/    站点树（src + config.yaml + config/ 证书 + db.sqlite）",
+		"  config.yaml + config/ 证书 + db.sqlite   站点配置面",
+		"  src/    后端模块源码树（src/<name>/api，拷自 cli 内置模板）",
+		"  api/dist/  构建产物（安装目标）",
 		"  bin/    oj 二进制与插件（拷贝自源工程）",
 		"  cdn/    隔离 CDN（fixture 包 + 两份索引 + 签名）",
 		`监听端口：127.0.0.1:${port}（进程已停）`,

package/src/oj-caps.ts

@@ -0,0 +1,133 @@
+/**
+ * oj 二进制**能力**探针（设计 202610220010 §7「双探」）。
+ *
+ * 为什么不能只看版本号：`bin/oj` 允许手改/手替（vendor.ts:143 的逃生门），
+ * `bin/.oj-version` 标记会漂移；且 vendor.ts:102-110 已实证「`oj -V` 正常但
+ * JsRuntime 能力缺失」真实存在。版本号是声明，能跑通才是事实。
+ *
+ * 为什么单独探 `--module-root`：module-root 布局（`src/<name>/{api,web}`）依赖
+ * oj 的模块根可配置。能力缺失时必须 fail-fast 并给处置命令——回落旧布局会让
+ * 「源码搬了、构建产物还是旧的」这种半坏状态长期存在，比直接失败难排查得多。
+ *
+ * 缓存：`bin/.oj-caps`，以二进制的 size+mtime 为指纹。指纹变了就重探，
+ * 所以手替 `bin/oj` 不会吃到旧缓存。
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveOjBin } from "./vendor";
+
+export interface OjCaps {
+	/** `oj build --help` 是否接受 `--module-root <DIR>`（源码树根，与 `-d` 互斥） */
+	moduleRoot: boolean
+}
+
+/** 探针执行器（测试注入）：执行 oj 子命令并返回合并输出 */
+export type OjProbeRun = (ojBin: string, args: string[]) => string;
+
+const defaultRun: OjProbeRun = (ojBin, args) =>
+	execFileSync(ojBin, args, { encoding: "utf-8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"] });
+
+export const CAPS_FILE = ".oj-caps";
+
+/** 二进制指纹：size + mtime 足以识别「换了文件」，比哈希便宜且无 IO 放大 */
+function fingerprint(ojBin: string): string {
+	const st = fs.statSync(ojBin);
+	return `${st.size}:${Math.floor(st.mtimeMs)}`;
+}
+
+function capsPath(binDir: string): string {
+	return path.join(binDir, CAPS_FILE);
+}
+
+/** 缓存文件形状：指纹 + 能力位 */
+interface CapsCache {
+	fingerprint?: string
+	caps?: Partial<OjCaps>
+}
+
+/** 读缓存；指纹不匹配或结构不对 → null（重探） */
+export function readCapsCache(ojBin: string): OjCaps | null {
+	try {
+		const raw = JSON.parse(fs.readFileSync(capsPath(path.dirname(ojBin)), "utf-8")) as CapsCache | null;
+		if (!raw || raw.fingerprint !== fingerprint(ojBin) || typeof raw.caps?.moduleRoot !== "boolean")
+			return null;
+		return { moduleRoot: raw.caps.moduleRoot };
+	}
+	catch {
+		return null;
+	}
+}
+
+/** 写缓存（失败不影响主流程：缓存只是加速，不是正确性来源） */
+export function writeCapsCache(ojBin: string, caps: OjCaps): void {
+	try {
+		fs.writeFileSync(
+			capsPath(path.dirname(ojBin)),
+			`${JSON.stringify({ fingerprint: fingerprint(ojBin), caps }, null, 2)}\n`,
+			"utf-8",
+		);
+	}
+	catch {
+		// 只读目录 / 权限不足：忽略
+	}
+}
+
+/** 现场探测：解析 `oj build --help` 的旗标列表（不缓存） */
+export function probeOjCaps(ojBin: string, run: OjProbeRun = defaultRun): OjCaps {
+	let help = "";
+	try {
+		help = run(ojBin, ["build", "--help"]);
+	}
+	catch (error) {
+		throw new Error(
+			`[ojm] 无法执行 ${ojBin} build --help：${(error as Error).message}\n`
+			+ "处置：`ojm vendor` 重装 oj 二进制。",
+		);
+	}
+	// 只认长旗标整词：`--module-root <DIR>`；避免帮助文本里的说明文字误命中
+	return { moduleRoot: /--module-root\b/.test(help) };
+}
+
+/**
+ * module-root 布局的能力闸门：缺失即抛，文案给处置命令。
+ * 有缓存走缓存（热路径每次 build/dev 都会经过这里）。
+ */
+export function requireModuleRootCapability(
+	projectRoot: string,
+	run: OjProbeRun = defaultRun,
+): OjCaps {
+	const ojBin = resolveOjBin(projectRoot);
+	if (!fs.existsSync(ojBin)) {
+		throw new Error(
+			`[ojm] 缺少 ${ojBin}：module-root 布局需要 oj 提供 --module-root。\n`
+			+ "处置：`ojm vendor` 安装 oj 二进制。",
+		);
+	}
+
+	const caps = readCapsCache(ojBin) ?? (() => {
+		const probed = probeOjCaps(ojBin, run);
+		writeCapsCache(ojBin, probed);
+		return probed;
+	})();
+
+	if (caps.moduleRoot)
+		return caps;
+
+	const version = (() => {
+		try {
+			return run(ojBin, ["-V"]).trim() || "(未知)";
+		}
+		catch {
+			return "(不可探测)";
+		}
+	})();
+	throw new Error(
+		`[ojm] 当前 oj 不支持 --module-root（版本 ${version}），无法构建 src/<name>/{api,web} 布局。\n`
+		+ "原因：module-root 布局要求 oj build / serve 的模块根可配置；本版 oj 只认 `-d` 首层子目录为模块。\n"
+		+ "处置：升级 oj 后重试——`ojm vendor <tag>`（需 >= 支持 --module-root 的版本），"
+		+ "或把工程改回 web/src/<name> 布局。\n"
+		+ `缓存：${capsPath(path.dirname(ojBin))}（换二进制后指纹变化会自动重探）。`,
+	);
+}

package/src/oj.ts

@@ -40,17 +40,40 @@ export interface StartOjPoll {
 	timeoutMs?: number
 }
 
+/**
+ * 工程根：从 config 所在目录向上找最近的含 `bin/` 的目录（ojm 的 vendor 布局）。
+ *
+ * 两种布局：
+ *   <root>/api/config.yaml → <root>/bin/oj     （历史布局，命中第二层）
+ *   <root>/config.yaml     → <root>/bin/oj     （module-root，命中第一层）
+ * 找不到 `bin/` 时退回旧的「往上两级」，保持既有报错行为（缺 bin/oj 的文案不变）。
+ */
+function resolveProjectRoot(configPath: string): string {
+	const configDir = path.dirname(configPath);
+	for (const dir of [configDir, path.dirname(configDir)]) {
+		if (fs.existsSync(path.join(dir, "bin")))
+			return dir;
+	}
+	return path.dirname(configDir);
+}
+
 export function startOj(
 	configPath: string,
 	base: string,
-	apiSrcPath: string,
+	apiSource: string | string[],
 	poll: StartOjPoll = {},
 	extraArgs: string[] = [],
 ): OjProcess {
 	const port = readOjPort(configPath);
-	// 约定：config 在 <project>/api/config.yaml，vendor 二进制在 <project>/bin/oj
-	const projectRoot = path.dirname(path.dirname(configPath));
+	// 约定：vendor 二进制在 <project>/bin/oj。工程根不能按「config 往上两级」算：
+	// module-root 布局的 config 在仓库根（<project>/config.yaml），往上两级会越过工程，
+	// 落到父目录找 bin/oj。改为「向上找最近的含 bin/ 的目录」，两种布局都成立。
+	const projectRoot = resolveProjectRoot(configPath);
 	const binPath = resolveOjBin(projectRoot);
+	// 后端源码参数二选一（oj v0.1.85：`--api-path` 与 `--module-root` 互斥，同时给会被
+	// clap 拒掉）：历史布局传目录 → `--api-path <dir>`；module-root 布局传**已拼好的
+	// 旗标数组** → `["--module-root", "<project>/src"]`。
+	const apiArgs = Array.isArray(apiSource) ? apiSource : ["--api-path", apiSource];
 	const healthUrl = `http://127.0.0.1:${port}${base}/health`;
 
 	// 插件目录发现显式化：oj 的 resolve_plugins_dir 依赖 current_exe() 启发式，而
@@ -69,7 +92,7 @@ export function startOj(
 	let stderrTail = "";
 	// --console-log：oj 新版终端默认静默（console_log 缺省 false，只落 logs/），
 	// ojm dev/preview 的 [oj] 透传管道必须显式打开终端输出才能看到日志（手册 §10）。
-	const child = spawn(binPath, ["serve", "-c", configPath, "-b", base, "--api-path", apiSrcPath, "--console-log", ...extraArgs], {
+	const child = spawn(binPath, ["serve", "-c", configPath, "-b", base, ...apiArgs, "--console-log", ...extraArgs], {
 		stdio: ["ignore", "pipe", "pipe"],
 		...(env ? { env } : {}),
 	});

package/src/preview-config.ts

@@ -44,7 +44,7 @@ export interface DerivePreviewConfigOptions {
 	apiRoot?: string
 	/** 显式端口时覆盖 server.port；缺省沿用原 config（oj 代码默认 9778） */
 	port?: number
-	/** 原 config 文本（测试注入）；缺省读 api/config.yaml */
+	/** 原 config 文本（测试注入）；缺省读 config.yaml */
 	configText?: string
 }
 

package/src/preview.ts

@@ -59,7 +59,8 @@ export async function runPreview(projectRoot: string, opts: PreviewOptions = {})
 	const siteDir = opts.siteDir ?? layout.distDir;
 	const ojBin = resolveOjBin(projectRoot);
 	const configPath = resolveConfigPath(projectRoot);
-	const apiDist = path.join(projectRoot, "api", "dist");
+	// release 根恒为扁平 api/dist（module-root 只改源码布局，不改产物形状——设计 C-3/C-7）
+	const apiDist = layout.apiDist;
 
 	// fail-fast 四查：缺一即提示对应补救（init 幂等补缺 / ojm build 产物）
 	if (!existsSync(ojBin))

package/src/site.ts

@@ -6,7 +6,7 @@
 
 import process from "node:process";
 
-/** 任务记录（线形状镜像；真源 templates/api/src/_platform/_lifecycle/types.ts:65，客户端不 import 模板内部） */
+/** 任务记录（线形状镜像；真源 templates/src/_platform/api/_lifecycle/types.ts:65，客户端不 import 模板内部） */
 export interface TaskRecord {
 	/**
 	 * 记录 schema 版本（P2-10 线形状镜像）：缺省（undefined）=旧记录=v1 语义照常渲染；
@@ -30,7 +30,7 @@ export interface TaskRecord {
 	finishedAt?: number
 }
 
-/** 模板 serve 缺省端口（templates/api/config.yaml server.port: 9778；host 显式钉 127.0.0.1） */
+/** 模板 serve 缺省端口（templates/config.yaml server.port: 9778；host 显式钉 127.0.0.1） */
 export const DEFAULT_SITE_URL = "http://127.0.0.1:9778";
 
 /** 本 CLI 已知的任务记录 schema 版本（P2-10；与服务端 tasks.ts TASK_SCHEMA_VERSION 手工同步，更高版本触发降级提示） */

package/src/usage.ts

@@ -27,7 +27,7 @@ export function usageText(): string {
   ojm api [dir] [--check] [--docs] [--exempt <path>]
         契约代码生成（client / routes / openapi / stub）
         --check   四重对账（生成物同步 / route 双向 / routes.js / WS 路由鉴权）
-        --exempt <path>  指定豁免清单，覆盖默认 api/.ojm-api-exempt.json
+        --exempt <path>  指定豁免清单，覆盖默认 .ojm-api-exempt.json（工程根；历史布局在 api/ 下）
         --docs    出自包含文档站（单文件离线可看）
   ojm info
         输出版本矩阵与模块清单（报障用，US-7）
@@ -68,7 +68,7 @@ export function usageText(): string {
         --check 离线自检两份索引签名
   ojm market setup [--url <站点地址>] [--user <u> --pass <p>] [--new-pass <p>]
         把系统设置 framework.market_cdn_url 指向本地模拟 CDN（工程根 cdn/，由
-        api/config.yaml 的 /cdn 挂载直出）。首跑若账号处于首次改密期（seed admin
+        config.yaml 的 /cdn 挂载直出）。首跑若账号处于首次改密期（seed admin
         must_change=1），会自动改密换全权 token 后再写入。
   ojm market publish [--fixture <name>@<version>] [--real <方案工程>] [--id <key>] [--key <pem>] [--rebuild-index] [--check]
         把方案包落进 cdn/：合成 fixture（或 --real 走 ojm build --bundle）→ 确定性 tgz
@@ -86,7 +86,7 @@ export function usageText(): string {
         在一次性隔离站点（随机端口 + 一次性 DB/密钥/凭据/信任库/CDN）里跑完整安装，
         跑完即毁；--keep 保留现场供排查。用于确认「这个包到底能不能装」，不污染你的工程。
   ojm test|exec|openapi|migrate|schema [args...]
-        透传给 oj 同名子命令（自动补 -c <project>/api/config.yaml；其余参数原样转发）
+        透传给 oj 同名子命令（自动补 -c <project>/config.yaml；其余参数原样转发）
         例：ojm test --anonymous / ojm migrate --db report / ojm openapi --check
 `;
 }
@@ -104,7 +104,7 @@ const COMMAND_HELP: Record<string, string> = {
   开发模式快捷键（仅 TTY 终端，类 Vite）：
     r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开
     q  退出（后端 oj 一并终止）
-  port 缺省 5174（oj 后端端口以 api/config.yaml 的 server.port 为准）`,
+  port 缺省 5174（oj 后端端口以 config.yaml 的 server.port 为准）`,
 	"build": `ojm build [--bundle] [--out <dir>]
   构建后端（oj build）与模块产物（含全站合并）
   --bundle   方案包构建：manifest.yaml 契约校验（fail-fast）→ 确定性 tgz
@@ -117,7 +117,7 @@ const COMMAND_HELP: Record<string, string> = {
 	"api": `ojm api [dir] [--check] [--docs] [--exempt <path>]
   契约代码生成（client / routes / openapi / stub）
   --check   四重对账（生成物同步 / route 双向 / routes.js / WS 路由鉴权）
-  --exempt <path>  指定豁免清单，覆盖默认 api/.ojm-api-exempt.json
+  --exempt <path>  指定豁免清单，覆盖默认 .ojm-api-exempt.json（工程根；历史布局在 api/ 下）
   --docs    出自包含文档站（单文件离线可看）
   dir 缺省当前目录；显式目录须先存在`,
 	"info": `ojm info
@@ -168,7 +168,7 @@ const COMMAND_HELP: Record<string, string> = {
   本地模拟 CDN 与市场链路子命令：setup / publish / build-index / verify / trial
   详见各子命令帮助：ojm market setup --help 等`,
 	"market setup": `ojm market setup [--url <站点地址>] [--user <u> --pass <p>] [--new-pass <p>]
-  把系统设置 framework.market_cdn_url 指向本地模拟 CDN（工程根 cdn/，由 api/config.yaml 的 /cdn 挂载直出）。首跑若账号处于首次改密期（seed admin must_change=1），会自动改密换全权 token 后再写入`,
+  把系统设置 framework.market_cdn_url 指向本地模拟 CDN（工程根 cdn/，由 config.yaml 的 /cdn 挂载直出）。首跑若账号处于首次改密期（seed admin must_change=1），会自动改密换全权 token 后再写入`,
 	"market publish": `ojm market publish [--fixture <name>@<version>] [--real <方案工程>] [--id <key>] [--key <pem>] [--rebuild-index] [--check]
   把方案包落进 cdn/：合成 fixture（或 --real 走 ojm build --bundle）→ 确定性 tgz → 包级 detached 签名 <name>-<version>.tgz.sig
   不碰索引（索引由 build-index 扫描重建，多人发布才不会互相覆盖）`,

package/src/vendor.ts

@@ -35,8 +35,12 @@ export const NPM_PKG = "@oj-bin/oj";
  * （见 CHANGELOG 0.1.20 / docs/guides/api-codegen-openapi.md）。**0.2.13 抬到 0.1.81**：
  * 模板侧 `solution-perms.ts` 权限级联清理用 `startswith` 操作键（v0.1.81 补齐，
  * 构造器迁移收尾），oj < 0.1.81 时卸载方案报 `unknown variant startswith` fail-closed。
+ * **本版抬到 0.1.85**：`src/<name>/{web,api}` 布局依赖 `--module-root <DIR>`（源码树根，
+ * 与 `-d`/`--api-path` 互斥）；旧版收到该旗标即报错。0.1.85 同时落地了
+ * `manifest.name` 与目录名脱钩、`#/m/x` 按 name 解析（见
+ * docs/prd/202610220010-layout-module-root-design.md §5）。
  */
-export const MIN_OJ_VERSION = "0.1.81";
+export const MIN_OJ_VERSION = "0.1.85";
 
 /** 按段数值比较（字符串比较会把 0.1.9 判成大于 0.1.69）；非数字段按 0 处理 */
 export function isSupportedOjVersion(version: string): boolean {