@oj-module/cli 0.2.64 → 0.2.67

package/src/__tests__/templates-schema-columns.test.ts

@@ -88,12 +88,25 @@ describe("templates 后端 schema.yaml 列白名单", () => {
 		expect(violations).toEqual([]);
 	});
 
-	it("s-2 回归锚点：0017 三方言迁移齐备，users.employee_no 已声明为 text", () => {
+	it("s-2 回归锚点：_platform 基线为 0001、增量 0002（发布历史）三方言齐备，且基线里确有 users.employee_no", () => {
 		const migDir = join(srcRoot, "app", "api", "_platform", "migrations");
-		for (const file of ["0017__users_employee_no.sql", "0017__users_employee_no.mysql.sql", "0017__users_employee_no.pg.sql"])
+		for (const file of [
+			"0001__baseline.sql",
+			"0001__baseline.mysql.sql",
+			"0001__baseline.pg.sql",
+			"0002__market_release.sql",
+			"0002__market_release.mysql.sql",
+			"0002__market_release.pg.sql",
+		])
 			expect(existsSync(join(migDir, file)), `缺迁移 ${file}`).toBe(true);
 
+		// 0001 是压平后的结构基线，已应用过的库不会重跑——新增结构只能追加新序号，
+		// 不得回改基线（否则老库拿不到）。序号必须从 0001 起连续、无空洞。
+		const seqs = [...new Set(readdirSync(migDir).map(f => f.slice(0, 4)))].sort();
+		expect(seqs).toEqual(["0001", "0002"]);
+
 		const schema = parse(readFileSync(join(srcRoot, "app", "api", "_platform", "schema.yaml"), "utf-8")) as SchemaDoc;
 		expect(schema.tables?.users?.columns?.employee_no).toMatchObject({ type: "text" });
+		expect(readFileSync(join(migDir, "0001__baseline.sql"), "utf-8")).toContain("employee_no");
 	});
 });

package/src/__tests__/templates-tenant-scope.test.ts

@@ -115,7 +115,7 @@ describe("templates 租户定性（A 租户表 / B 共享表）", () => {
 		expect(unknown).toEqual([]);
 	});
 
-	it("t-4 27 张表的 A/B 分组与方案 v3 §5.2 一致（新增表须先定性）", () => {
+	it("t-4 29 张表的 A/B 分组与方案 v3 §5.2 一致（新增表须先定性）", () => {
 		const { tables } = loadSchemaTables();
 		const shared = [...tables].filter(([, d]) => d.tenant === false).map(([n]) => n).sort();
 		// Phase 0 落地 21 张（11 A + 10 B）；Phase 1 加企微三表，全部 B 组（D9：查它们时必然还没有租户上下文）
@@ -125,10 +125,14 @@ describe("templates 租户定性（A 租户表 / B 共享表）", () => {
 		// （D7 不接受 corpId 参数），故不进 shared_allow——跨租户读元数据那条另走显式 tenant_id 的裸 SQL。
 		// 改这张表清单 = 改租户隔离边界，必须同步 config.yaml 的 tenant.shared_allow（t-2/t-3 会把关）。
 		// 2026-11-02 demo 模块下线（ecc7b35e）删掉 demo/api/schema.yaml 的 todos 表，28 → 27。
-		expect(tables.size).toBe(27);
+		// 2026-11 发布凭证加 publish_credential：共享表（CLI 兑换无租户语义，归属走 owner_tenant），27 → 28。
+		// 2026-11 发布历史加 market_release：共享表（发布物落在站点级 CDN，历史按站点归口），28 → 29。
+		expect(tables.size).toBe(29);
 		expect(shared).toEqual([
 			"_oj_migrations",
 			"market_history",
+			"market_release",
+			"publish_credential",
 			"reg_source_seq",
 			"sys_login_throttle",
 			"sys_permission",

package/src/bundle.ts

@@ -456,14 +456,19 @@ function checkModuleManifest(built: string, name: string, version: string, _summ
 	return out;
 }
 
-/** api.tables ↔ schema.yaml 表集对照（C2-12a 构建列；schema 缺失/声明不一致均 fail-fast） */
+/**
+ * api.tables ↔ schema.yaml 表集对照（C2-12a）+ 表前缀（C2-12c）。
+ * 引用式方案（tables 缺省）只要 schema.yaml 存在也做前缀检查——表名冲突与打包形态无关。
+ */
 function checkTables(m: Record<string, unknown>, layout: ProjectLayout, name: string): string[] {
 	const api = m.api as Record<string, unknown> | undefined;
-	if (api === undefined || api.tables === undefined)
+	if (api === undefined)
 		return [];
 	const schemaPath = path.join(apiSrcOf(layout, name), "schema.yaml");
 	if (!fs.existsSync(schemaPath)) {
-		return [`【C2-12a】api.tables 已声明但缺少 ${path.relative(layout.projectRoot, schemaPath)}，无法对照表集（oj 冗余校验同源）`];
+		return api.tables === undefined
+			? []
+			: [`【C2-12a】api.tables 已声明但缺少 ${path.relative(layout.projectRoot, schemaPath)}，无法对照表集（oj 冗余校验同源）`];
 	}
 	return checkTablesAgainstSchema(m, fs.readFileSync(schemaPath, "utf8"));
 }

package/src/cli.ts

@@ -223,9 +223,21 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 				await mergeManifests(out ?? "", inputs);
 			};
 		case "keygen":
-			return async (opts: { id?: string, out?: string, yes?: boolean } = {}) => {
-				const { keygenCommand } = await import("./keygen");
-				keygenCommand({ id: opts.id, out: opts.out, yes: opts.yes });
+			return async (opts: { id?: string, out?: string, yes?: boolean, credential?: string, siteUrl?: string } = {}) => {
+				const { exchangePublishCredential, keygenCommand } = await import("./keygen");
+				// 令牌解析：--credential > OJM_PUBLISH_CREDENTIAL；都没有则走原离线路径（逐字节不变）
+				const credential = (opts.credential ?? process.env.OJM_PUBLISH_CREDENTIAL ?? "").trim();
+				if (credential === "") {
+					keygenCommand({ id: opts.id, out: opts.out, yes: opts.yes });
+					return;
+				}
+				// 身份只来自凭证：--id 是另一条（离线）路径的入口，同时给必然有一方被静默忽略
+				if (opts.id !== undefined)
+					throw new UsageError("[ojm] --credential 与 --id 不能同时使用：凭证已绑定发布身份（要自定义身份请走离线 ojm keygen --id）");
+				const identity = await exchangePublishCredential(credential, { siteUrl: opts.siteUrl });
+				const who = identity.display_name === null ? identity.username : `${identity.display_name}（${identity.username}）`;
+				console.log(`[ojm] 凭证已兑换：产品 ${identity.product} / 申请人 ${who}`);
+				keygenCommand({ id: identity.key_id, out: opts.out, yes: opts.yes });
 			};
 		case "sign":
 			return async (file: string | undefined, opts: { id?: string, key?: string, check?: boolean, registryId?: string } = {}) => {
@@ -283,9 +295,9 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 					exit(EXIT_FAILURE);
 			};
 		case "install":
-			return async (target: string | undefined, opts: SiteOpts & { locale?: string, name?: string, version?: string, registry?: string } = {}) => {
+			return async (target: string | undefined, opts: SiteOpts & { locale?: string, name?: string, version?: string, registry?: string, force?: boolean } = {}) => {
 				const { installCommand } = await import("./install");
-				await installCommand(target ?? "", { siteUrl: opts.siteUrl, user: opts.user, pass: opts.pass, locale: opts.locale, name: opts.name, version: opts.version, registry: opts.registry });
+				await installCommand(target ?? "", { siteUrl: opts.siteUrl, user: opts.user, pass: opts.pass, locale: opts.locale, name: opts.name, version: opts.version, registry: opts.registry, force: opts.force });
 			};
 		case "list":
 			return async (opts: SiteOpts & { all?: boolean, json?: boolean } = {}) => {

package/src/dev.ts

@@ -230,12 +230,6 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 		proxyWsUpgrade(ojTarget)(req, socket, head);
 	});
 
-	// 退出回收：server 关闭 → SSE 通道 + oj 子进程一并回收
-	server.on("close", () => {
-		hub.close();
-		void oj?.stop();
-	});
-
 	// 终端 Ctrl+C / `kill`（SIGINT / SIGTERM）终止 dev 进程时，后端 oj 必须随之消亡：
 	// 起一个统一优雅停机，先停 oj 再退出；并打印后端终止信息。
 	// 终端 Ctrl-C 是进程组信号：外层 bin 转发一份 + 组送达一份，内层会收到
@@ -249,13 +243,24 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 		shuttingDown = true;
 		void shutdownDev(server, oj, hub);
 	};
-	process.on("SIGINT", shutdown);
-	process.on("SIGTERM", shutdown);
-
 	// 兜底：dev 进程以任何非优雅路径退出（未走 SIGINT/SIGTERM，如未捕获异常）时，
 	// 同步强杀 oj，确保它不孤儿化继续占端口（shutdownDev 已停则 kill 为 no-op）。
-	process.once("exit", () => {
+	const killOjOnExit = () => {
 		oj?.kill?.();
+	};
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+	process.once("exit", killOjOnExit);
+
+	// 退出回收：server 关闭 → SSE 通道 + oj 子进程一并回收，并摘除本实例注册的
+	// 进程级信号/exit handler。devServer 可在同一进程被多次调用（编程式 / 测试），
+	// 不摘除会累积闭包、触发 MaxListenersExceededWarning（与 preview 的 stop 同款）。
+	server.on("close", () => {
+		hub.close();
+		void oj?.stop();
+		process.removeListener("SIGINT", shutdown);
+		process.removeListener("SIGTERM", shutdown);
+		process.removeListener("exit", killOjOnExit);
 	});
 
 	// 端口被占用时自动顺延，避免 `EADDRINUSE` 直接让 `pnpm dev` 以非零码退出

package/src/esm-exports.ts

@@ -14,14 +14,19 @@
  * 本模块只做「扫描产物文本、回答谁导出/导入了什么」，不含修复逻辑，
  * 供 shell 构建（门禁，失败即中断）与 tests/ 共用，避免两套正则漂移。
  *
- * 解析口径：只认**行首**的 `import` / `export`。esbuild 与 vite 在
- * `minify: false` 下顶层语句一律顶格输出，依赖内部的代码有缩进，
- * 借此把「字符串字面量里恰好写了 import」这类误报压到最低。
+ * 解析口径：`es-module-lexer` 真词法扫描，而非行首正则。
+ * 早先的实现假设「esbuild/vite 在 `minify: false` 下顶层语句一律顶格」，一旦
+ * 共享资产开启压缩（`minifyWhitespace` 会把 `export{a as b}` / `}from"react"`
+ * 挤成一行且行内任意位置），行首锚定的正则全部失配 → 门禁集体误报「零具名导出」
+ * 和「裸说明符未登记」。词法扫描只依赖语法、与压缩/换行无关，故换掉。
+ * 顺带消灭了「字符串字面量里恰好写了 import/from」的误报（原先靠行首锚定压制）。
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { ImportType, initSync, parse as lexModule } from "es-module-lexer";
+
 /** 一个 ESM 文件的导出面 */
 export interface EsmExports {
 	/** 静态具名导出（不含 `default`、不含 `export *` 透传的部分） */
@@ -56,22 +61,6 @@ export interface EsmImport {
 	needsDefault: boolean
 }
 
-/**
- * `export { a, b as c }`（本地导出块）与 `export { a, b as c } from "x"`（再导出）
- * 的公共部分：取出**对外暴露**的名字（`b as c` 取 `c`）。
- */
-function exportedNamesFromClause(clause: string): string[] {
-	return clause
-		.split(",")
-		.map(part => part.trim())
-		.filter(Boolean)
-		.map((part) => {
-			const as = part.split(/\s+as\s+/);
-			return (as[as.length - 1] ?? part).trim();
-		})
-		.filter(name => name !== "default");
-}
-
 /**
  * `import { a, b as c }` 中被**请求**的名字。
  *
@@ -88,51 +77,75 @@ function importedNamesFromClause(clause: string): string[] {
 		.filter(name => name !== "default");
 }
 
+/** wasm 实例化只需一次；按需初始化，避免「只是 import 一下」的消费方付启动开销 */
+let lexReady = false;
+function lex(source: string): ReturnType<typeof lexModule> {
+	if (!lexReady) {
+		initSync();
+		lexReady = true;
+	}
+	return lexModule(source);
+}
+
+/** 语句文本；`ss`/`se` 是 lexer 给出的整条语句区间（含分号） */
+function statementAt(source: string, ss: number, se: number): string {
+	return source.slice(ss, se);
+}
+
+/**
+ * 从一条 `import … from "x"` / `export … from "x"` 语句里分出关键字与子句。
+ *
+ * 语句边界已由 lexer 确定，这里只处理语句内部的切片，因此不再需要行首锚定，
+ * 压缩后（`import{a as b}from"react"`）同样成立。
+ */
+function clauseOf(statement: string): { keyword: "import" | "export", clause: string } | undefined {
+	const head = /^\s*(import|export)\b/.exec(statement);
+	if (!head)
+		return undefined;
+	const rest = statement.slice(head[0].length);
+	// `from` 后必须紧跟说明符字符串，才不会误取子句里的同名标识符
+	const fromIdx = rest.search(/\bfrom\s*["']/);
+	if (fromIdx < 0)
+		return undefined;
+	return { keyword: head[1] as "import" | "export", clause: rest.slice(0, fromIdx) };
+}
+
 /** 解析产物的静态导出面 */
 export function parseEsmExports(source: string): EsmExports {
+	const [imports, exports] = lex(source);
 	const names = new Set<string>();
+	let hasDefault = false;
 
-	// 收集全部 export 子句（本地导出块 + 再导出），具名与 default 两种判定共用
-	const clauses: string[] = [];
-	for (const m of source.matchAll(/^export\s*\{([^}]*)\}(?:\s*from\s*["'][^"']+["'])?\s*(?:;\s*)?$/gm)) {
-		clauses.push(m[1] ?? "");
-	}
-
-	for (const clause of clauses) {
-		for (const name of exportedNamesFromClause(clause))
-			names.add(name);
+	for (const exp of exports) {
+		if (exp.n === "default")
+			hasDefault = true;
+		else
+			names.add(exp.n);
 	}
 
-	// 声明式导出：export const/let/var/function/class/async function
-	for (const m of source.matchAll(/^export\s+(?:declare\s+)?(?:async\s+)?(?:const|let|var|function\*?|class)\s+([A-Za-z_$][\w$]*)/gm)) {
-		names.add(m[1]!);
-	}
+	// `export * from "x"` 不产生具名导出（静态不可展开），lexer 也不把它列进 exports，
+	// 只能从「语句以 export 开头、星号之后不带 as」反推。
+	// `export * as ns from "x"` 是有名字的导出（ns），导出面仍可静态确定，不算在内。
+	const hasStarReexport = imports.some((imp) => {
+		if (imp.t !== ImportType.Static || imp.ss < 0)
+			return false;
+		return /^export\s*\*(?!\s*as\b)/.test(statementAt(source, imp.ss, imp.se));
+	});
 
-	// default 有两副面孔：声明式 `export default …`，或子句里的 `x as default`
-	// （esbuild 产出的正是后者，形如 `rad_shim_xxx_default as default`）
-	const hasDefaultClause = clauses.some(clause => clause
-		.split(",")
-		.map(part => part.trim())
-		.some(part => /\bas\s+default$/.test(part)));
-
-	return {
-		names,
-		hasDefault: /^export\s+default\b/m.test(source) || hasDefaultClause,
-		hasStarReexport: /^export\s*\*/m.test(source),
-	};
+	return { names, hasDefault, hasStarReexport };
 }
 
 /**
  * 解析产物消费了哪些说明符的哪些具名导出。
  *
- * 覆盖三种形态（均为 esbuild / vite 非压缩产物的常见写法）：
- *   `import { a, b as c } from "x"`、`import { a } from "x"`（多行）、
- *   `export { a } from "x"`（再导出同样是消费）。
+ * 覆盖：`import { a, b as c } from "x"`、`import X, { a } from "x"`、
+ * `export { a } from "x"`（再导出同样是消费）。
  *
  * 不覆盖：`import * as ns from "x"`、动态 `import("x")` 后取属性——
  * 这些都拿不到具名绑定，无从校验。
  */
 export function parseEsmImports(source: string): EsmImport[] {
+	const [imports] = lex(source);
 	const found = new Map<string, { names: Set<string>, needsDefault: boolean }>();
 
 	const slot = (specifier: string) => {
@@ -144,25 +157,30 @@ export function parseEsmImports(source: string): EsmImport[] {
 		return entry;
 	};
 
-	// 具名导入（允许跨行）；用 [^;]*? 兜住语句边界，避免跨越到下一条语句
-	for (const m of source.matchAll(/^import\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/gm)) {
-		const entry = slot(m[2]!);
-		for (const name of importedNamesFromClause(m[1] ?? ""))
-			entry.names.add(name);
-	}
+	for (const imp of imports) {
+		// 动态 import / import.meta 不带静态具名绑定
+		if (imp.t !== ImportType.Static || imp.ss < 0 || !imp.n)
+			continue;
+		const parsed = clauseOf(statementAt(source, imp.ss, imp.se));
+		if (!parsed)
+			continue;
 
-	// 具名再导出
-	for (const m of source.matchAll(/^export\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/gm)) {
-		const entry = slot(m[2]!);
-		for (const name of importedNamesFromClause(m[1] ?? ""))
-			entry.names.add(name);
-	}
+		const entry = slot(imp.n);
+		const brace = /\{([^}]*)\}/.exec(parsed.clause);
+		if (brace) {
+			for (const name of importedNamesFromClause(brace[1] ?? ""))
+				entry.names.add(name);
+		}
 
-	// default 导入：`import X from "x"`（X 非 { 、非 *）
-	// 不能假定它一定可用——只有 default 的包若 shim 没兜住，浏览器同样是
-	// "does not provide an export named 'default'"
-	for (const m of source.matchAll(/^import\s+([A-Za-z_$][\w$]*)\s+from\s*["']([^"']+)["']/gm)) {
-		slot(m[2]!).needsDefault = true;
+		// default 导入：子句去掉 `{…}` 后仍剩标识符（`X` / `X,`）。
+		// `* as ns` 是命名空间导入，不消费 default。
+		// 不能假定它一定可用——只有 default 的包若 shim 没兜住，浏览器同样是
+		// "does not provide an export named 'default'"。
+		if (parsed.keyword === "import") {
+			const head = parsed.clause.replace(/\{[^}]*\}/g, "").trim();
+			if (head && !head.startsWith("*"))
+				entry.needsDefault = true;
+		}
 	}
 
 	return [...found].map(([specifier, entry]) => ({
@@ -233,24 +251,88 @@ export function collectDynamicRequires(distDir: string): DynamicRequireHit[] {
 }
 
 /**
- * 产物引用的全部裸说明符（三种形态：具名/副作用 import、`import("x")`、再导出）。
+ * 产物引用的全部裸说明符（静态/副作用 import、`import("x")`、再导出）。
  *
  * 浏览器只能解析 importmap 里登记过的裸说明符，漏一个就是
  * `Failed to resolve module specifier` 白屏。
  */
 export function parseBareSpecifiers(source: string): string[] {
+	const [imports] = lex(source);
 	const found = new Set<string>();
-	// 行首锚定，规避字符串字面量里的假阳性（P3.5 教训）
-	const pattern = /^import\s*\(\s*["']([^"']+)["']\s*\)|^(?:import|export)\s[^;]*?from\s*["']([^"']+)["']|^import\s+["']([^"']+)["']/gm;
-	for (const m of source.matchAll(pattern)) {
-		const spec = m[1] ?? m[2] ?? m[3];
-		if (!spec || spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("data:") || spec.startsWith("http"))
+	// lexer 已给出每条语句的说明符原文；非字符串字面量（`import(x)`）为 undefined，跳过
+	for (const imp of imports) {
+		const spec = imp.n;
+		if (!spec)
+			continue;
+		if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("data:") || spec.startsWith("http"))
 			continue;
 		found.add(spec);
 	}
 	return [...found];
 }
 
+/**
+ * 产物的**静态**依赖说明符：`import … from "x"`、副作用 `import "x"`、再导出。
+ *
+ * 与 {@link parseBareSpecifiers} 的差别有两点，都是为了算「首屏静态闭包」：
+ *   - **排除动态 `import("x")`**：那是懒加载，不在首屏关键路径上，预取它会白拉；
+ *   - **保留相对/绝对路径**：闭包要顺着 `/assets/x.hash.js` 继续走，不能只看裸名。
+ *
+ * 静态图的切分口径与浏览器一致（缓存模块记录前先取完整静态图），所以这里能算出
+ * 「浏览器一定会请求的最小集合」。
+ */
+export function parseStaticSpecifiers(source: string): string[] {
+	const [imports] = lex(source);
+	const found = new Set<string>();
+	for (const imp of imports) {
+		// d === -1 才是静态导入；`import("x")` 的 d 是 `(` 的偏移
+		if (imp.d !== -1 || !imp.n)
+			continue;
+		found.add(imp.n);
+	}
+	return [...found];
+}
+
+/**
+ * 首屏静态依赖闭包：从入口出发，顺着**静态** import 一直走到没得走。
+ *
+ * 这就是浏览器一定会请求的集合（ESM 语义：先取完整静态图再执行），所以可以放心
+ * 全量预取；动态 `import()` 不在其中。裸说明符经 importmap 解析，相对路径按当前
+ * 文件所在目录拼。
+ *
+ * `readAsset` 返回 undefined 表示读不到（跨源 CDN 资产、或缺失文件）：该 URL 仍算
+ * 闭包成员（预取它对浏览器有效），但不再往下展开。
+ *
+ * 与构建脚本共用同一份实现，是为了让测试能重算一遍对撞产物——两套实现必然漂移。
+ */
+export function collectStaticClosure(
+	entryUrl: string,
+	importmap: Record<string, string>,
+	readAsset: (url: string) => string | undefined,
+): string[] {
+	const seen = new Set<string>();
+	const queue = [entryUrl];
+	while (queue.length) {
+		const url = queue.shift()!;
+		if (seen.has(url))
+			continue;
+		seen.add(url);
+		const source = readAsset(url);
+		if (source === undefined)
+			continue;
+		for (const spec of parseStaticSpecifiers(source)) {
+			const target = spec.startsWith("/")
+				? spec
+				: spec.startsWith(".")
+					? resolve("/", url.slice(0, url.lastIndexOf("/") + 1), spec)
+					: importmap[spec];
+			if (target)
+				queue.push(target);
+		}
+	}
+	return [...seen];
+}
+
 /** 一处「资产引用了 importmap 未登记的裸说明符」 */
 export interface UnresolvedSpecifier {
 	file: string

package/src/install.ts

@@ -254,6 +254,11 @@ export interface InstallOptions {
 	locale?: string
 	/** REG-R9②：从指定 registry 源安装（白名单在服务端；旧站点 API < 0.2.0 不支持 → exit 1） */
 	registry?: string
+	/**
+	 * 强制重装配（oj 0.1.123+ reloadConfig(force)）：旁路「unchanged=已是最新装配」幂等短路，
+	 * 强制宿主重做一次装配。运维显式重装配用；缺省 false。
+	 */
+	force?: boolean
 	/** 测试注入；缺省 globalThis.fetch */
 	fetchFn?: typeof fetch
 	/** 测试注入；缺省真睡 */
@@ -269,6 +274,8 @@ export async function installCommand(target: string, opts: InstallOptions = {}):
 	const fetchFn = opts.fetchFn ?? globalThis.fetch;
 	const { base, user, pass } = resolveSite(opts);
 	const token = await login(fetchFn, base, user, pass);
+	// force 透传（oj 0.1.123+ reloadConfig(force) 逃逸舱）：仅运维显式重装配时用；常规安装走锁 diff
+	const forceQ = opts.force === true ? "?force=1" : "";
 
 	let response: { task_id: string };
 	if (opts.registry !== undefined) {
@@ -282,13 +289,13 @@ export async function installCommand(target: string, opts: InstallOptions = {}):
 		if (!isSiteApiAtLeast(meta.apiVersion, "0.2.0"))
 			throw new Error(`[ojm] 目标站点平台 API 版本过低（需 ≥ 0.2.0 才支持 --registry 源安装，实为 ${meta.apiVersion ?? "未知"}）——请升级目标站点的 oj-module，或改用 CDN/file 源`);
 		const registryOrigin = originOf(src.url) ?? src.url;
-		response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", "/api/_platform/market/install", {
+		response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", `/api/_platform/market/install${forceQ}`, {
 			name: slug,
 			version: opts.version ?? version,
 			source: "registry",
 			registry: registryOrigin,
 		});
-		console.log(`[ojm] 已从 registry 源提交安装任务（源 ${registryOrigin}，物理名 ${slug}）`);
+		console.log(`[ojm] 已从 registry 源提交安装任务（源 ${registryOrigin}，物理名 ${slug}${opts.force === true ? "，强制重装配" : ""}）`);
 	}
 	else {
 		const parsed = parseTarget(target);
@@ -314,7 +321,7 @@ export async function installCommand(target: string, opts: InstallOptions = {}):
 			else {
 				console.log(`[ojm] 未发现签名侧车（${path.basename(sigPath)}）——宿主验签硬 fail-closed，未签名包将被拒（sig_missing）；签名方法见 devkit「签名与信任」`);
 			}
-			const res = await fetchFn(`${base}/api/_platform/market/install`, {
+			const res = await fetchFn(`${base}/api/_platform/market/install${forceQ}`, {
 				method: "POST",
 				headers: { authorization: `Bearer ${token}`, ...tenantHeaders() },
 				body: form,
@@ -324,7 +331,7 @@ export async function installCommand(target: string, opts: InstallOptions = {}):
 		else {
 			if (opts.name !== undefined && opts.name !== parsed.name)
 				throw new Error(`[ojm] --name「${opts.name}」与目标「${parsed.name}」不一致——请二选一`);
-			response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", "/api/_platform/market/install", {
+			response = await callApi<{ task_id: string }>(fetchFn, base, token, "POST", `/api/_platform/market/install${forceQ}`, {
 				name: parsed.name,
 				version: opts.version ?? parsed.version,
 				source: "cdn",

package/src/keygen.ts

@@ -10,6 +10,7 @@ import path from "node:path";
 import process from "node:process";
 import { generateKeyPair } from "./lifecycle/keygen";
 import { fingerprintOfPublicKey } from "./lifecycle/sign";
+import { DEFAULT_SITE_URL, tenantHeaders, unwrapEnvelope } from "./site";
 
 export interface KeygenOptions {
 	/** 发布方 key_id（C2-37：<publisher>.<id> 全小写，禁裸通用名） */
@@ -67,3 +68,56 @@ export function keygenCommand(opts: KeygenOptions = {}): KeygenResult {
 	console.log(`[ojm] 下一步：ojm sign <pkg>.tgz --id ${keyId}（或 --key ${privateKeyPath} --id ${keyId}）`);
 	return { keyId, publicKeyHex: kp.publicKeyHex, fingerprint, dir, privateKeyPath, publicKeyPath };
 }
+
+/** 兑换结果：服务端下发身份（CLI 零推导——编码规则只在 templates 侧一份） */
+export interface ExchangedIdentity {
+	key_id: string
+	product: string
+	username: string
+	display_name: string | null
+}
+
+export interface ExchangeOptions {
+	/** 站点地址；flag > OJM_SITE_URL > DEFAULT_SITE_URL */
+	siteUrl?: string
+	/** 测试注入 */
+	fetchFn?: typeof fetch
+}
+
+/**
+ * 用一次性发布凭证换身份（匿名端点，不需要账号密码）。
+ *
+ * 只做「取回服务端算好的 key_id」——不做任何编码推导（规则漂移比多一次网络请求贵得多），
+ * 但**必须**校验拿回的 key_id 形状：它马上会被拼进 `~/.ojm/keys/<key_id>`，
+ * 一个被中间人改成 `../../x` 的响应就是任意路径写入。失败一律不落盘（调用方先兑换后生成）。
+ */
+export async function exchangePublishCredential(token: string, opts: ExchangeOptions = {}): Promise<ExchangedIdentity> {
+	const t = token.trim();
+	// 形状先挡：不是 64 位 hex 的输入连请求都不必发（与页面生成规则一致）
+	if (!/^[0-9a-f]{64}$/i.test(t))
+		throw new Error("[ojm] 发布凭证格式不对（应为 64 位十六进制）：请在站点「发布管理」页复制完整凭证");
+
+	const base = (opts.siteUrl ?? process.env.OJM_SITE_URL ?? DEFAULT_SITE_URL).replace(/\/+$/, "");
+	const fetchFn = opts.fetchFn ?? fetch;
+	let res: Response;
+	try {
+		res = await fetchFn(`${base}/api/publish/credential/exchange`, {
+			method: "POST",
+			headers: { "content-type": "application/json", ...tenantHeaders() },
+			body: JSON.stringify({ token: t }),
+		});
+	}
+	catch (e) {
+		throw new Error(`[ojm] 无法连接站点 ${base}：${e instanceof Error ? e.message : String(e)}——请确认站点地址（--site-url / OJM_SITE_URL）与网络`);
+	}
+	const data = await unwrapEnvelope(res) as Partial<ExchangedIdentity> | null;
+	const keyId = String(data?.key_id ?? "");
+	if (!isValidKeyId(keyId))
+		throw new Error(`[ojm] 站点返回的 key_id 非法（C2-37）：「${keyId}」——已中止，未写入任何密钥（请核对站点版本）`);
+	return {
+		key_id: keyId,
+		product: String(data?.product ?? ""),
+		username: String(data?.username ?? ""),
+		display_name: data?.display_name == null ? null : String(data.display_name),
+	};
+}

package/src/lifecycle/__tests__/bundle.test.ts

@@ -53,8 +53,8 @@ function makePrebuiltArtifacts(): void {
 	const apiDist = join(project, "dist/api/demo-solution-0.1.0");
 	mkdirSync(join(apiDist, "ping"), { recursive: true });
 	mkdirSync(join(apiDist, "migrations"), { recursive: true });
-	writeFileSync(join(apiDist, "manifest.yaml"), "name: demo-solution\ndesc: manifest.yaml 契约全字段合法夹具\nversion: 0.1.0\ntables:\n  - note\n");
-	writeFileSync(join(apiDist, "schema.yaml"), "tables:\n  note: {}\n");
+	writeFileSync(join(apiDist, "manifest.yaml"), "name: demo-solution\ndesc: manifest.yaml 契约全字段合法夹具\nversion: 0.1.0\ntables:\n  - demo_solution_note\n");
+	writeFileSync(join(apiDist, "schema.yaml"), "prefix: demo_solution_\ntables:\n  demo_solution_note: {}\n");
 	writeFileSync(join(apiDist, "routes.js"), "export {};\n");
 	writeFileSync(join(apiDist, "ping/api.js"), "export async function ping() {}\n");
 	// 站点构建产物（dist/web/modules/<name>/<version>/entry.js + css，对应 web.entry/css 声明）
@@ -317,11 +317,29 @@ describe("buildBundle · 校验先于打包（fail-fast）", () => {
 
 	it("c2-12a：api.tables 与 schema.yaml 表集不一致 → 构建期拒绝", async () => {
 		const m = readManifest();
-		m.api.tables = ["note", "ghost"];
+		m.api.tables = ["demo_solution_note", "ghost"];
 		writeManifest(m);
 		await expect(pack()).rejects.toThrow(/C2-12a/);
 	});
 
+	it("c2-12c：schema.yaml 缺 prefix / 表名未带方案前缀 → 构建期拒绝", async () => {
+		const schemaPath = join(project, "api/src/demo-solution/schema.yaml");
+		writeFileSync(schemaPath, "tables:\n  demo_solution_note: {}\n");
+		await expect(pack()).rejects.toThrow(/C2-12c.*prefix/);
+
+		writeFileSync(schemaPath, "prefix: demo_solution_\ntables:\n  note: {}\n");
+		await expect(pack()).rejects.toThrow(/C2-12c.*demo_solution_note/);
+	});
+
+	it("c2-12c：prefix 落在第一方保留段 → 构建期拒绝", async () => {
+		const m = readManifest();
+		m.api.tables = ["oj_note"];
+		writeManifest(m);
+		const schemaPath = join(project, "api/src/demo-solution/schema.yaml");
+		writeFileSync(schemaPath, "prefix: oj_\ntables:\n  oj_note: {}\n");
+		await expect(pack()).rejects.toThrow(/C2-12c.*保留段/);
+	});
+
 	it("c2-25：locales 缺引用 key → 构建期 fail-fast", async () => {
 		const m = readManifest();
 		m.roles[0].title_key = "demo-solution:role.absent";

package/src/lifecycle/__tests__/fixtures/fixture-valid/api/src/demo-solution/manifest.yaml

@@ -6,4 +6,4 @@ name: demo-solution
 desc: manifest.yaml 契约全字段合法夹具
 version: 0.1.0
 tables:
-  - note
+  - demo_solution_note

package/src/lifecycle/__tests__/fixtures/fixture-valid/api/src/demo-solution/migrations/0001__init.sql

@@ -1,5 +1,5 @@
--- 0001__init：建 note 表（与 schema.yaml 列集一致；oj migrate 按 seq 升序执行）
-CREATE TABLE IF NOT EXISTS note (
+-- 0001__init：建 demo_solution_note 表（与 schema.yaml 列集一致；oj migrate 按 seq 升序执行）
+CREATE TABLE IF NOT EXISTS demo_solution_note (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   title TEXT NOT NULL,
   create_time INTEGER NOT NULL

package/src/lifecycle/__tests__/fixtures/fixture-valid/api/src/demo-solution/schema.yaml

@@ -1,7 +1,10 @@
 # 声明式表结构（形态对齐 apps/playground-oj/api/src/demo/schema.yaml）。
-# 契约 C2-12：bundle manifest 的 api.tables 必须与本表 keys 一致（oj 冗余校验 fail-fast）。
+# C2-12c：prefix 必须 = 模块名 kebab→snake 再补尾部 `_`（demo-solution → demo_solution_），
+# 且每张表名以它开头——表名全库共享，前缀把归属编码进名字，避免方案之间撞表。
+prefix: demo_solution_
+# 契约 C2-12a：bundle manifest 的 api.tables 必须与本表 keys 一致（oj 冗余校验 fail-fast）。
 tables:
-  note:
+  demo_solution_note:
     pk: id
     columns:
       id: {type: integer, autoincrement: true}