@oj-module/cli 0.2.66 → 0.2.68

package/src/manifest-contract.ts

@@ -297,8 +297,8 @@ export function validateContract(m: unknown): string[] {
 			}
 			if (api.tables !== undefined) {
 				const t = api.tables;
-				if (!Array.isArray(t) || !t.every(x => typeof x === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(x))) {
-					v0.push(v("C2-12a", "api.tables 每项必须匹配 ^[a-z][a-z0-9_]{0,63}$ 的字符串（与 api/src/<name>/schema.yaml 表集逐一相等另行对照）"));
+				if (!Array.isArray(t) || !t.every(x => typeof x === "string" && /^[a-z][a-z0-9_]{0,62}$/.test(x))) {
+					v0.push(v("C2-12a", "api.tables 每项必须匹配 ^[a-z][a-z0-9_]{0,62}$ 的字符串（≤63 字符：PostgreSQL 标识符上限 63 字节、MySQL 64 字符，取最严值；与 api/src/<name>/schema.yaml 表集逐一相等另行对照）"));
 				}
 			}
 			if (api.deps !== undefined) {
@@ -682,30 +682,113 @@ export function checkLocalesComplete(m: unknown, zhText: string, enText: string)
 	return out;
 }
 
+/** C2-12c prefix 语法：小写字母开头，仅小写字母/数字/下划线，且以 `_` 结尾 */
+const TABLE_PREFIX_RE = /^[a-z][a-z0-9_]*_$/;
+
+/**
+ * 第一方保留的表前缀段：oj 引擎 / ojm CLI 的命名空间。
+ *
+ * 框架表（_platform / auth / home / notification 下的 users / sys_* / wecom_* 等）保持裸名，
+ * 是保留的框架命名空间；方案表名一律带作者自选前缀，与框架表名天然不重叠。把 `oj_` / `ojm_`
+ * 整段留给第一方，防止方案先占用、日后框架想用时反被占（S002 归属图以表名为全局主键）。
+ * 按「段」保留（startsWith），不只禁精确值——整个命名空间都归第一方。
+ * 注：下划线开头的 `_oj_`（oj 内建账本 `_oj_migrations`）本就不满足 TABLE_PREFIX_RE，无需列举。
+ */
+const RESERVED_TABLE_PREFIX_SEGMENTS = ["oj_", "ojm_"];
+
+/**
+ * 跨库可移植的表名上限：PostgreSQL 标识符上限 63 **字节**（NAMEDATALEN-1），
+ * MySQL 是 64 字符、SQLite 无实际限制——取最严的 63。表名字符集限定 ASCII，
+ * 字符数 = 字节数，因此 63 字符在三种库上都安全。
+ */
+const MAX_TABLE_NAME_LEN = 63;
+
+/** 前缀上限：给表名留 ≥31 字符（63 - 32），避免前缀把表名的可用空间吃光 */
+const MAX_PREFIX_LEN = 32;
+
+/**
+ * C2-12c `schema.yaml` 的 `prefix` 与逐表前缀校验。
+ *
+ * 表名在**全库共享**（oj 归属图以表名为主键），前缀把模块归属编码进名字，
+ * 让两个独立发布的方案不会因为都叫 `note` 而在安装期 S002 拒启。
+ * 前缀由作者选择（短、可读、尽量全局唯一），不强制由模块名派生——长模块名
+ * 可以用 `crm_` 之类短前缀，避免表名被模块名拖到数据库上限之外。
+ *
+ * 入参为 schema.yaml 文本（fs 在调用方）。YAML 解析失败返回 []——那是 C2-12a
+ * 的判罚面，同一事故不重复报两遍。
+ */
+export function checkSchemaTablePrefix(schemaYamlText: string): string[] {
+	let doc: unknown;
+	try {
+		doc = parse(schemaYamlText);
+	}
+	catch {
+		return [];
+	}
+	if (!isObj(doc) || !isObj(doc.tables))
+		return []; // 缺 tables / 非映射由 C2-12a 报
+
+	const keys = Object.keys(doc.tables);
+	const out: string[] = [];
+	const prefix = doc.prefix;
+
+	if (prefix === undefined) {
+		out.push(v("C2-12c", "schema.yaml 缺 prefix：必须声明表前缀（如 prefix: crm_；小写字母开头、以 _ 结尾、≤32 字符，建议与方案名相关且全局唯一）；表名在全库共享，前缀把归属编码进名字，避免方案之间撞表"));
+	}
+	else if (typeof prefix !== "string" || !TABLE_PREFIX_RE.test(prefix)) {
+		out.push(v("C2-12c", `schema.yaml 的 prefix「${String(prefix)}」必须匹配 ^[a-z][a-z0-9_]*_$（小写字母开头、仅小写字母/数字/下划线、以 _ 结尾）`));
+	}
+	if (typeof prefix === "string" && prefix.length > MAX_PREFIX_LEN) {
+		out.push(v("C2-12c", `schema.yaml 的 prefix「${prefix}」长 ${prefix.length} 字符，超过上限 ${MAX_PREFIX_LEN}——表名总长须 ≤${MAX_TABLE_NAME_LEN}，前缀过长会吃掉表名可用空间；请改用更短的方案前缀（如 crm_）`));
+	}
+	if (typeof prefix === "string" && TABLE_PREFIX_RE.test(prefix)) {
+		const seg = RESERVED_TABLE_PREFIX_SEGMENTS.find(s => prefix.startsWith(s));
+		if (seg !== undefined) {
+			out.push(v("C2-12c", `schema.yaml 的 prefix「${prefix}」落在第一方保留段「${seg}*」——oj 引擎 / ojm CLI 的表命名空间由框架独占，方案不得占用，请改用自有前缀（如 crm_、acme_）`));
+		}
+	}
+
+	if (typeof prefix === "string" && prefix !== "") {
+		const offenders = keys.filter(k => !k.startsWith(prefix));
+		if (offenders.length > 0) {
+			out.push(v("C2-12c", `表名必须以本方案前缀「${prefix}」开头：${offenders.map(k => `「${k}」→「${prefix}${k}」`).join("、")}`));
+		}
+	}
+	// 表名语法/总长（引用式方案没有 api.tables 语法列兜底，这里一并查）
+	const malformed = keys.filter(k => !/^[a-z][a-z0-9_]{0,62}$/.test(k));
+	if (malformed.length > 0) {
+		out.push(v("C2-12c", `schema.yaml 表名必须匹配 ^[a-z][a-z0-9_]{0,62}$（小写字母开头，仅小写字母/数字/下划线，≤${MAX_TABLE_NAME_LEN} 字符——PostgreSQL 上限 63 字节、MySQL 64 字符，取最严值）：${malformed.join("、")}`));
+	}
+	return out;
+}
+
 /**
- * C2-12a api.tables 与 `api/src/<name>/schema.yaml` 表集逐一相等（oj 冗余校验同源，不一致 fail-fast）。
+ * C2-12a api.tables 与 `api/src/<name>/schema.yaml` 表集逐一相等（oj 冗余校验同源，不一致 fail-fast）；
+ * 同时执行 C2-12c 表前缀校验——引用式方案（api.tables 缺省）只要 schema.yaml 存在也必须带前缀。
  * 入参为 schema.yaml 文本（fs 在调用方）。
  */
 export function checkTablesAgainstSchema(m: unknown, schemaYamlText: string): string[] {
+	const prefixViolations = checkSchemaTablePrefix(schemaYamlText);
+
 	if (!isObj(m) || !isObj(m.api) || m.api.tables === undefined)
-		return [];
+		return prefixViolations;
 	const declared = m.api.tables;
 	if (!Array.isArray(declared))
-		return []; // 语法违规归 validateContract（C2-12a 语法列），此处只对照表集
+		return prefixViolations; // 语法违规归 validateContract（C2-12a 语法列），此处只对照表集
 	let schemaTables: unknown;
 	try {
 		const doc = parse(schemaYamlText);
 		schemaTables = isObj(doc) ? doc.tables : undefined;
 	}
 	catch {
-		return [v("C2-12a", "schema.yaml 不是合法 YAML，无法对照 api.tables 表集")];
+		return [...prefixViolations, v("C2-12a", "schema.yaml 不是合法 YAML，无法对照 api.tables 表集")];
 	}
 	if (!isObj(schemaTables)) {
-		return [v("C2-12a", "schema.yaml 缺 tables 映射，无法对照 api.tables 表集（oj 冗余校验同源）")];
+		return [...prefixViolations, v("C2-12a", "schema.yaml 缺 tables 映射，无法对照 api.tables 表集（oj 冗余校验同源）")];
 	}
 	const schemaKeys = new Set(Object.keys(schemaTables));
 	const declaredKeys = new Set(declared.filter(x => typeof x === "string"));
-	const out: string[] = [];
+	const out: string[] = [...prefixViolations];
 	const missingInSchema = [...declaredKeys].filter(k => !schemaKeys.has(k));
 	const undeclaredInManifest = [...schemaKeys].filter(k => !declaredKeys.has(k));
 	if (missingInSchema.length > 0) {

package/src/market/bootstrap.ts

@@ -69,6 +69,14 @@ export interface IsolatedSite {
 	cleanup: () => Promise<void>
 	/** 销毁清单（--keep 时给人看这里到底有什么） */
 	teardownReport: () => string[]
+	/**
+	 * 重启隔离站点 oj serve（停当前进程，按同一派生 config 重新起站）。
+	 * 用途：无守护形态安装会落 partial（vars/auth 等冻结段热改属 restart_pending，需进程
+	 * 重启才激活）。walkthrough 在每次安装后置重启，模拟真实「部署 → 重启」时序，让模块真正
+	 * 上线（路由/匿名端点注册），使后续深检/升级/重装断言落到活跃态而非空洞的 partial。
+	 * token 仍有效（jwt_secret 落在 config 文件，重启不变）；DB 在同根，会话延续。
+	 */
+	restart: () => Promise<void>
 }
 
 export interface BootstrapOptions {
@@ -178,8 +186,13 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 	// 隔离站点直接预置被测方案的探活路径——与 scripts/verify-solution-smoke/bootstrap-host.mjs 同手法，
 	// 让 trial 验的是安装机制本身，而不是重启时序。
 	const healthPath = `/${parseFixtureSpec(opts.fixture).name}/ping`;
-	if (!cfg.includes(`- ${healthPath}`))
-		cfg = cfg.replace(/^(\s*)- \/system\/login-methods$/m, `$1- /system/login-methods\n$1- ${healthPath}`);
+	// 锚点行可能带行内注释与缩进（模板 config.yaml 的 /system/login-methods 即如此），
+	// 故用 lookahead 容忍尾注释；命中第一个 anonymous_paths 列表项（auth 守卫读取的那个，
+	// 与安装器 appendAnonymousPaths 同目标）即可——旧写法用 `$` 硬锚尾，注释使其失配导致预置
+	// 静默失效，安装器随后自己补匿名路径 → auth 进 restart_pending → 无守护形态判 partial。
+	const loginAnchor = /^(\s*)- \/system\/login-methods(?=\s*(?:#.*)?$)/m;
+	if (loginAnchor.test(cfg) && !cfg.includes(`- ${healthPath}`))
+		cfg = cfg.replace(loginAnchor, `$1- /system/login-methods\n$1- ${healthPath}`);
 	// fs 段：模板自 0.2.13 起已自带（安装器落盘面）；旧模板没有时才补，避免重复键
 	if (!/^fs:/m.test(cfg))
 		cfg = `${cfg.trimEnd()}\nfs:\n  root: .\n  readonly: false\n`;
@@ -237,6 +250,16 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 	process.on("SIGINT", onSignal);
 	process.on("SIGTERM", onSignal);
 
+	// 重启：停当前进程后按同一派生 config 重新起站（激活冻结段）；cleanup 持有的是本作用域的
+	// `oj` 变量引用，故重启后 cleanup 停的是新进程（闭包捕获变量，非值）。
+	const restart = async () => {
+		log("[ojm] 隔离站点重启 oj serve（激活冻结段 auth/vars）…");
+		await oj.stop();
+		oj = starter(configPath, "/api", resolveLayout(root).apiDist);
+		await oj.ready;
+		log(`[ojm] 隔离站点重启就绪：http://127.0.0.1:${port}（根 ${root}）`);
+	};
+
 	return {
 		root,
 		port,
@@ -249,6 +272,7 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 		admin: { user: SEED_ADMIN_USER, pass: SEED_ADMIN_PASS },
 		cleanup,
 		teardownReport: () => teardownReport(root, port),
+		restart,
 	};
 }
 

package/src/market/command.ts

@@ -109,6 +109,7 @@ export async function marketCommand(sub: string, argv: string[]): Promise<void>
 				key: flags.key,
 				check: flags.check,
 				registryId: flags.registryId,
+				rebuildIndex: flags.rebuildIndex === true,
 			});
 			if (flags.rebuildIndex === true)
 				await buildIndex({ id: flags.id, key: flags.key, check: flags.check });

package/src/market/publish.ts

@@ -17,6 +17,7 @@ import process from "node:process";
 
 import { buildBundle } from "../bundle";
 import { createDeterministicTgz } from "../deterministic-tar";
+import { assertDefaultModulesUntouched } from "../scaffold-guard";
 import { signCommand } from "../sign";
 import { resolveCdnLayout } from "./cdn-layout";
 import { buildFixturePackage, parseFixtureSpec } from "./fixture";
@@ -38,6 +39,8 @@ export interface MarketPublishOptions {
 	check?: boolean
 	/** 签发方 registry 身份（REG-CS3 v2 防跨仓库重放；透传 signCommand --registry-id） */
 	registryId?: string
+	/** 命令层是否紧接着重建索引（仅用于措辞：true 时不打印「索引未重建」） */
+	rebuildIndex?: boolean
 }
 
 export interface MarketPublishResult {
@@ -88,7 +91,9 @@ export async function publishPackage(opts: MarketPublishOptions = {}): Promise<M
 		const size = fs.statSync(tgzPath).size;
 		console.log(`[ojm] 包已落 CDN → ${path.relative(projectRoot, tgzPath)}（${size} 字节）`);
 		console.log(`[ojm] 发布方 ${signed.keyId}；指纹 ${signed.fingerprint}`);
-		console.log("[ojm] 索引未重建：多人场景请由维护者跑 ojm market build-index");
+		// 带了 --rebuild-index 时由命令层紧接着重建索引，这里不能再报「未重建」（否则前后两句自相矛盾）
+		if (opts.rebuildIndex !== true)
+			console.log("[ojm] 索引未重建：多人场景请由维护者跑 ojm market build-index");
 
 		return {
 			name,
@@ -122,6 +127,8 @@ async function buildFixture(args: { fixture?: string, staging: string, cdnDir: s
 
 /** `--real`：走既有 ojm build --bundle，产物搬到 CDN 目录（一次只发一份：多方案工程请显式指定） */
 async function buildRealPackage(solutionRoot: string, staging: string, cdnDir: string): Promise<{ name: string, version: string, tgzPath: string, sha256: string, preExisted: boolean }> {
+	// 与 ojm build 同一道完整性门禁：发布链路同样不许携带被改过的默认模块
+	assertDefaultModulesUntouched(solutionRoot);
 	const builtList = await buildBundle(solutionRoot, { out: staging });
 	if (builtList.length !== 1) {
 		throw new Error(

package/src/market/walkthrough.ts

@@ -70,6 +70,17 @@ export interface WalkthroughResult {
 	port: number
 }
 
+/**
+ * 安装成功终态：oj 0.1.122 起，无守护形态安装会落 partial（vars/auth 等冻结段热改属
+ * restart_pending，需进程重启才完全生效）——这是正确终态（P0 §3.6 / 验收 15），不是失败。
+ * 真正的失败 partial（锁后异常 + 补偿回滚）不会带 restartRequired，故以它区分二者。
+ * 本 walkthrough 在每次安装后置重启（IsolatedSite.restart），模拟真实「部署 → 重启」时序，
+ * 让模块真正上线。
+ */
+function installSucceeded(task: TaskRecord): boolean {
+	return task.status === "done" || (task.status === "partial" && task.restartRequired === true);
+}
+
 /**
  * neg-* 专用版本：与主链路（0.1.0/0.2.0）完全隔离，收尾整包摘除。
  * 必须低于主链路 latest（0.2.0），否则发布后它会成为 latest，摘除时 REG-CS2 单调性守卫
@@ -96,8 +107,8 @@ const OPS: Op[] = [
 		title: "安装（11 段）",
 		run: async (ctx) => {
 			const task = await install(ctx, ctx.version);
-			const done = task.status === "done";
-			return { ok: done, detail: done ? `${task.stages.length} 段全 ok` : `status=${task.status} stage=${task.stage ?? "?"}：${task.message}` };
+			const ok = installSucceeded(task);
+			return { ok, detail: ok ? `${task.stages.length} 段全 ok（终态 ${task.status}${task.restartRequired ? " + restartRequired" : ""}，已重启激活）` : `status=${task.status} stage=${task.stage ?? "?"}：${task.message}` };
 		},
 	},
 	{
@@ -106,7 +117,7 @@ const OPS: Op[] = [
 		run: async (ctx) => {
 			await ensureInstalled(ctx);
 			const task = await install(ctx, ctx.version);
-			const ok = task.status === "done";
+			const ok = installSucceeded(task);
 			return { ok, detail: ok ? "重装成功（未报方案名占用）" : `status=${task.status}：${task.message}` };
 		},
 	},
@@ -159,7 +170,7 @@ const OPS: Op[] = [
 			await ensureInstalled(ctx); // 前置：0.1.0 在列（账本 head=1）
 			await publishVersion(ctx, "0.2.0");
 			const task = await install(ctx, "0.2.0");
-			if (task.status !== "done")
+			if (!installSucceeded(task))
 				return { ok: false, detail: `升级安装未 done：status=${task.status} stage=${task.stage ?? "?"}：${task.message}` };
 			const card = await indexCard(ctx);
 			const distDir = resolveLayout(ctx.site.root).apiDist;
@@ -189,7 +200,7 @@ const OPS: Op[] = [
 			if (card?.installed !== "0.2.0") {
 				await publishVersion(ctx, "0.2.0");
 				const pre = await install(ctx, "0.2.0");
-				if (pre.status !== "done")
+				if (!installSucceeded(pre))
 					return { ok: false, detail: `前置安装 0.2.0 未 done：status=${pre.status}：${pre.message}` };
 				card = await indexCard(ctx);
 			}
@@ -320,7 +331,7 @@ const OPS: Op[] = [
 					return { ok: false, detail: `未停 needs_trust：status=${first.status}：${first.message}` };
 				await callApi(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/trust", { task_id: first.id });
 				const second = await installOnce(ctx, NEG_VERSION, NEG_NAME);
-				if (second.status !== "done")
+				if (!installSucceeded(second))
 					return { ok: false, detail: `确认后重装未 done：status=${second.status}：${second.message}` };
 				// 收尾（F3）：显式 revoke 陌生 key，快照 diff 断言无残留——不靠 uninstall 兜底（它本就不摘信任）
 				const del = await callApi<{ revoked?: boolean }>(fetch, ctx.base, ctx.token, "DELETE", `/api/_platform/market/trust/key?key_id=${encodeURIComponent("stranger.publisher")}`);
@@ -417,13 +428,18 @@ export async function walkthrough(opts: WalkthroughOptions = {}): Promise<Walkth
 	}
 }
 
-/** 安装 + 轮询；needs_trust 时自动确认（隔离站点，无外部信任可言） */
+/**
+ * 安装 + 轮询；needs_trust 时自动确认（隔离站点，无外部信任可言）。
+ * 成功（done 或 restartRequired 的 partial）后置重启，激活冻结段，模拟真实部署时序。
+ */
 async function install(ctx: Ctx, version: string): Promise<TaskRecord> {
 	let task = await installOnce(ctx, version);
 	if (task.status === "needs_trust") {
 		await callApi(fetch, ctx.base, ctx.token, "POST", "/api/_platform/market/trust", { task_id: task.id });
 		task = await installOnce(ctx, version);
 	}
+	if (installSucceeded(task))
+		await ctx.site.restart();
 	return task;
 }
 
@@ -462,7 +478,7 @@ async function ensureInstalled(ctx: Ctx): Promise<void> {
 	if (card?.installed === ctx.version)
 		return;
 	const task = await install(ctx, ctx.version);
-	if (task.status !== "done")
+	if (!installSucceeded(task))
 		throw new Error(`前置安装失败：status=${task.status}：${task.message}`);
 }
 

package/src/new.ts

@@ -140,6 +140,8 @@ function solutionYaml(name: string, withApi: boolean | undefined): string {
 			"api:",
 			`  module: ${name}`,
 			`  prefix: /api/${name}`,
+			// ping 匿名可达必须在契约声明（fixture.ts 同形状）；漏声明安装预检 anonymous_residual 拒装
+			`  anonymous: ["${name}/ping"]`,
 			"",
 		].join("\n")
 		: "";

package/src/scaffold-guard.ts

@@ -0,0 +1,227 @@
+/**
+ * 脚手架完整性门禁——内置模块自治契约。
+ *
+ * 契约（下游反馈 2026-11-06）：`src/app` 内置模块与 `src/oj-market` 属上游自治，
+ * 下游不得本地修改；`ojm build` 前逐文件与**当前 cli 包内 templates** 比对
+ * （上游模板即基线，不另立可被下游手改的哈希 lock）。CLI 升级后工程里的旧版
+ * 默认模块与新模板必不一致 → fail-fast，必须先 `ojm init --yes` 同步再构建
+ * （「必须先同步上游」策略，用户已确认）。
+ *
+ * 语义边界：
+ *   - 保护集 = init.include.yaml 白名单中保护根前缀条目展开的模板文件清单；
+ *     demo-only 文件本就不在白名单，不参与比较，无误报；
+ *   - 三类漂移均拦：modified（内容不一致，CRLF 归一防 autocrlf 误报）、
+ *     missing（白名单文件缺失）、extra（保护根内模板没有的文件）；
+ *   - 门禁开关 = `src/.ojm-builtin.json` 存在（新脚手架 init 必写；缺失 =
+ *     旧工程/框架仓，退化现状不拦——与 builtin.ts 同哲学）；
+ *   - **不是安全边界**：删开关文件即退回旧行为；错误信息如实告知处置路径；
+ *   - 仅约束打包链路（ojm build / build --bundle / market publish --real）；
+ *     dev 不拦，允许本地试验。
+ *
+ * 消费方：`cli.ts` build action（分支前，失败零产物）、`market/publish.ts`、
+ * `init.ts`（--yes 恢复复用保护根/白名单/清理面）。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import yaml from "yaml";
+import { builtinListPath } from "./builtin";
+
+/** 上游自治的保护根（相对工程根，正斜杠）。init --yes 恢复范围与此严格一致。 */
+export const PROTECTED_ROOTS = ["src/app", "src/oj-market"] as const;
+
+/** rel 是否落在保护根内（接受平台分隔符输入，归一后比较） */
+export function isProtectedRel(rel: string): boolean {
+	const p = rel.split(path.sep).join("/");
+	return PROTECTED_ROOTS.some(root => p === root || p.startsWith(`${root}/`));
+}
+
+/** cli 包根（src 运行态与 dist 发布态各上跳一层即包根） */
+export function cliRoot(): string {
+	return path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export function templatesRoot(): string {
+	return path.join(cliRoot(), "templates");
+}
+
+/**
+ * 读取模板根 `init.include.yaml` 的 `include` 白名单，归一为相对模板根的路径集合。
+ * 清单随模板一起发布，缺失即安装包损坏——直接 fail-fast，不留「静默少拷」的
+ * 退化路径。条目指向不存在的路径同样 fail-fast：拼错一个目录名不会当场报错，
+ * 只会在用户工程里留下难以追溯的缺文件（旧 exclude 清单没有这类校验面）。
+ */
+export function readInitInclude(templatesDir: string): Set<string> {
+	const yamlPath = path.join(templatesDir, "init.include.yaml");
+	if (!fs.existsSync(yamlPath))
+		throw new Error(`模板缺少 init.include.yaml：${yamlPath}（安装包损坏？）`);
+	const doc = yaml.parse(fs.readFileSync(yamlPath, "utf-8")) as { include?: string[] } | null;
+	const out = new Set<string>();
+	for (const raw of doc?.include ?? []) {
+		// 跨平台：include 清单用正斜杠书写，但 path.normalize 在 Windows 会把
+		// 正斜杠折成反斜杠，导致与 srcRel（path.relative 在 Windows 同样出反斜杠）
+		// 的对比永远落空、整棵 src 子树被 skip。这里只把反斜杠归正、剥 ./ 前缀，
+		// 不引入平台分隔符（修复：Windows 下 init 不拷贝 src 树）。
+		const p = raw.replace(/\\/g, "/").replace(/^(\.\/)+/, "");
+		out.add(p);
+		if (!fs.existsSync(path.join(templatesDir, p)))
+			throw new Error(`init.include.yaml 收录了不存在的路径：${p}（拼写错误或模板缺文件？）`);
+	}
+	return out;
+}
+
+export interface ScaffoldDrift {
+	modified: string[]
+	missing: string[]
+	extra: string[]
+}
+
+/** 门禁开关：工程声明了内置模块概念（`src/.ojm-builtin.json` 存在） */
+export function guardEnabled(projectRoot: string): boolean {
+	return fs.existsSync(builtinListPath(projectRoot));
+}
+
+/** 白名单中保护根条目展开成模板文件相对路径清单（正斜杠、去重、排序） */
+export function protectedTemplateFiles(templatesDir: string, include: Set<string>): string[] {
+	const files = new Set<string>();
+	const walk = (abs: string): void => {
+		for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+			const p = path.join(abs, entry.name);
+			if (entry.isDirectory())
+				walk(p);
+			else
+				files.add(path.relative(templatesDir, p).split(path.sep).join("/"));
+		}
+	};
+	for (const rel of include) {
+		if (!isProtectedRel(rel))
+			continue;
+		const abs = path.join(templatesDir, rel);
+		if (fs.statSync(abs).isDirectory())
+			walk(abs);
+		else
+			files.add(rel);
+	}
+	return [...files].sort();
+}
+
+const normalizeText = (s: string): string => s.replaceAll("\r\n", "\n");
+
+function walkProjectFiles(projectRoot: string, root: string, visit: (rel: string, abs: string) => void): void {
+	const absRoot = path.join(projectRoot, root);
+	if (!fs.existsSync(absRoot))
+		return;
+	const walk = (abs: string): void => {
+		for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+			const p = path.join(abs, entry.name);
+			if (entry.isDirectory())
+				walk(p);
+			else
+				visit(path.relative(projectRoot, p).split(path.sep).join("/"), p);
+		}
+	};
+	walk(absRoot);
+}
+
+/**
+ * 收集工程默认模块相对当前 cli 模板的漂移。
+ * 门禁未启用（无 `.ojm-builtin.json`）→ null；已启用 → 三类清单（可为空）。
+ */
+export function collectDefaultModuleDrift(projectRoot: string): ScaffoldDrift | null {
+	if (!guardEnabled(projectRoot))
+		return null;
+	const templatesDir = templatesRoot();
+	const expected = protectedTemplateFiles(templatesDir, readInitInclude(templatesDir));
+	const expectedSet = new Set(expected);
+	const drift: ScaffoldDrift = { modified: [], missing: [], extra: [] };
+	for (const rel of expected) {
+		const projectFile = path.join(projectRoot, rel);
+		if (!fs.existsSync(projectFile)) {
+			drift.missing.push(rel);
+			continue;
+		}
+		if (normalizeText(fs.readFileSync(projectFile, "utf-8")) !== normalizeText(fs.readFileSync(path.join(templatesDir, rel), "utf-8")))
+			drift.modified.push(rel);
+	}
+	for (const root of PROTECTED_ROOTS) {
+		walkProjectFiles(projectRoot, root, (rel) => {
+			if (!expectedSet.has(rel))
+				drift.extra.push(rel);
+		});
+	}
+	drift.extra.sort();
+	return drift;
+}
+
+/**
+ * 门禁入口：有漂移即抛（错误信息点名文件 + 上游自治说明 + `ojm init --yes` 处置）。
+ * 调用方保证在任何产物写入之前调用（失败零产物）。
+ */
+export function assertDefaultModulesUntouched(projectRoot: string): void {
+	const drift = collectDefaultModuleDrift(projectRoot);
+	if (!drift)
+		return;
+	const sections: string[] = [];
+	const section = (label: string, items: string[]): void => {
+		if (items.length > 0)
+			sections.push(`${label}（${items.length} 个文件）：\n${items.map(f => `  - ${f}`).join("\n")}`);
+	};
+	section("内容被修改", drift.modified);
+	section("缺失", drift.missing);
+	section("多出（模板没有）", drift.extra);
+	if (sections.length === 0)
+		return;
+	throw new Error([
+		"[ojm] 框架默认模块与上游模板不一致，已拒绝构建（未写入任何产物）。",
+		"",
+		...sections,
+		"",
+		"框架默认模块（src/app 内置模块、src/oj-market）由上游自治：本地修改会在下次同步时丢失，",
+		"功能需求请向上游仓库提交 issue，不要在下游直接改这些目录。",
+		"处置：",
+		"  - 确认放弃本地修改并恢复上游版本：ojm init --yes",
+		"    （仅覆盖/清理 src/app 与 src/oj-market，会丢弃其中的本地改动，执行前请备份；",
+		"     下游自定义模块与工程配置不受影响）。",
+	].join("\n"));
+}
+
+/**
+ * `ojm init --yes` 恢复的清理面：删除保护根内模板没有的文件（含遗留空目录）。
+ * 返回删除清单（正斜杠相对路径），供 init report 展示。
+ */
+export function removeExtraProtectedFiles(projectRoot: string): string[] {
+	const templatesDir = templatesRoot();
+	const expected = new Set(protectedTemplateFiles(templatesDir, readInitInclude(templatesDir)));
+	const removed: string[] = [];
+	for (const root of PROTECTED_ROOTS) {
+		walkProjectFiles(projectRoot, root, (rel, abs) => {
+			if (!expected.has(rel)) {
+				fs.rmSync(abs);
+				removed.push(rel);
+			}
+		});
+		const absRoot = path.join(projectRoot, root);
+		if (fs.existsSync(absRoot))
+			pruneEmptyDirs(absRoot);
+	}
+	return removed.sort();
+}
+
+/** 递归删除空目录（自底向上）；根自身保留，返回其是否为空 */
+function pruneEmptyDirs(dir: string): boolean {
+	let empty = true;
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const p = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (pruneEmptyDirs(p))
+				fs.rmdirSync(p);
+			else
+				empty = false;
+		}
+		else {
+			empty = false;
+		}
+	}
+	return empty;
+}

package/src/site.ts

@@ -43,6 +43,8 @@ export interface TaskRecord {
 	appliedSeq?: number
 	startedAt: number
 	finishedAt?: number
+	/** 无守护形态部分生效：冻结段（auth/vars）热改属 restart_pending，需宿主重启才完全生效 */
+	restartRequired?: boolean
 }
 
 /** 模板 serve 缺省端口（templates/config.yaml server.port: 9778；host 显式钉 127.0.0.1） */

package/src/usage.ts

@@ -77,11 +77,11 @@ export const HELP_GROUPS: HelpGroup[] = [
 				zh: "前后端一体化工程脚手架（幂等补缺）",
 				en: "Full-stack project scaffolding (idempotent, fills gaps only)",
 				options: [
-					{ raw: "--yes", zh: "非交互：缺省回答一律 yes", en: "Non-interactive: default all answers to yes" },
+					{ raw: "--yes", zh: "非交互：跳过非空确认，并把框架自带模块（src/app、src/oj-market）恢复为当前版本（丢弃其中的本地修改）", en: "Non-interactive: skip the non-empty check and restore built-in modules (src/app, src/oj-market) to upstream (local edits there are discarded)" },
 				],
 				detail: {
-					zh: "ojm init [dir] [--yes]\n  前后端一体化工程脚手架（幂等补缺：重跑只补缺失文件，永不覆盖已有文件）",
-					en: "ojm init [dir] [--yes]\n  Full-stack project scaffolding (idempotent: re-runs only fill missing files, never overwrite existing ones)",
+					zh: "ojm init [dir] [--yes]\n  前后端一体化工程脚手架（重跑只补缺失文件；已有文件永不覆盖）\n  --yes 恢复模式：覆盖 src/app 与 src/oj-market 为当前 CLI 携带的上游版本，\n  并删除这些目录内多出的文件（会丢弃其中的本地修改，先备份；\n  下游自定义模块与工程配置不受影响）。CLI 升级后构建前需先跑一次。",
+					en: "ojm init [dir] [--yes]\n  Full-stack project scaffolding (re-runs only fill missing files; existing files are never overwritten)\n  --yes restore mode: overwrites src/app & src/oj-market with the upstream version\n  carried by this CLI and removes extra files there (local edits in those two\n  directories are discarded — back up first; your own modules and project config\n  are untouched). Run once after a CLI upgrade before building.",
 				},
 			},
 			{
@@ -135,8 +135,8 @@ export const HELP_GROUPS: HelpGroup[] = [
 					{ raw: "--out <dir>", zh: "--bundle 输出目录（缺省 dist/）", en: "Output directory for --bundle (default dist/)" },
 				],
 				detail: {
-					zh: "ojm build [--bundle [name]] [--out <dir>]\n  构建后端（oj build）与模块产物（含全站合并）\n  --bundle 产出 dist/<name>-<version>.tgz + sha256（市场安装器的上游产物）",
-					en: "ojm build [--bundle [name]] [--out <dir>]\n  Builds the backend (oj build) and module artifacts (including the site-wide merge)\n  --bundle produces dist/<name>-<version>.tgz + sha256 (upstream artifact for the marketplace installer)",
+					zh: "ojm build [--bundle [name]] [--out <dir>]\n  构建后端（oj build）与模块产物（含全站合并）\n  --bundle 产出 dist/<name>-<version>.tgz + sha256（市场安装器的上游产物）\n  构建前校验框架自带模块（src/app、src/oj-market）未被本地修改——\n  与上游模板不一致即拒绝构建（内置模块自治契约，见 src/README.md）",
+					en: "ojm build [--bundle [name]] [--out <dir>]\n  Builds the backend (oj build) and module artifacts (including the site-wide merge)\n  --bundle produces dist/<name>-<version>.tgz + sha256 (upstream artifact for the marketplace installer)\n  Before building, verifies the built-in modules (src/app, src/oj-market) are unmodified —\n  any drift from the upstream templates rejects the build (built-in module autonomy, see src/README.md)",
 				},
 			},
 			{
@@ -245,11 +245,13 @@ export const HELP_GROUPS: HelpGroup[] = [
 					{ raw: "--name <name>", zh: "覆盖文件名推导的方案名", en: "Override the solution name derived from the file name" },
 					{ raw: "--version <version>", zh: "覆盖文件名推导的版本", en: "Override the version derived from the file name" },
 					{ raw: "--registry <url>", zh: "从指定 registry 源安装（白名单在服务端；旧站点 API < 0.2.0 不支持）", en: "Install from the specified registry source (allowlist is server-side; sites with API < 0.2.0 are unsupported)" },
+					{ raw: "--force", zh: "强制重装配（oj 0.1.123+ reloadConfig(force)）：旁路 unchanged 幂等短路，强制宿主重做一次装配", en: "Force re-assembly (oj 0.1.123+ reloadConfig(force)): bypass the unchanged idempotent short-circuit and force a re-assembly" },
 					{ raw: "--locale <locale>", zh: "终态文案语言 zh-CN|en-US", en: "Language of the final status message zh-CN|en-US" },
+					{ raw: "--force", zh: "强制重装配（绕过「unchanged=已是最新装配」幂等短路，要求宿主重跑一次 reload；oj ≥ v0.1.123）", en: "Force a reload even if unchanged (bypass the idempotent short-circuit; requires oj ≥ v0.1.123)" },
 				],
 				detail: {
-					zh: "ojm install <file.tgz | name[@version] | @<scope>/<name>[@version]> [--site-url <u>] [--user <u>] [--pass <p>] [--name <n>] [--version <v>] [--registry <r>] [--locale <zh-CN|en-US>]\n  本地 tgz 走 file 上传（<name>-<version>.tgz 文件名推导身份，可 --name/--version 覆盖）；name[@version] 走 CDN 市场源；@<scope>/<name>[@version] --registry <url> 走外部 registry 源（目录键由 CLI 归一为物理名 slug，白名单在服务端）\n  登录 → 提交 → 轮询任务至终态并打印结果（失败附原因 + 指引）\n  站点寻址：--site-url/--user/--pass，或环境变量 OJM_SITE_URL / OJM_USER / OJM_PASS",
-					en: "ojm install <file.tgz | name[@version] | @<scope>/<name>[@version]> [--site-url <u>] [--user <u>] [--pass <p>] [--name <n>] [--version <v>] [--registry <r>] [--locale <zh-CN|en-US>]\n  Local tgz goes through file upload (identity derived from the <name>-<version>.tgz file name, overridable via --name/--version); name[@version] goes through the CDN marketplace; @<scope>/<name>[@version] --registry <url> goes through an external registry source (the directory key is normalized to the physical slug by the CLI; allowlist is server-side)\n  Login → submit → poll the task to a terminal state and print the result (failures include the reason + guidance)\n  Site addressing: --site-url/--user/--pass, or env vars OJM_SITE_URL / OJM_USER / OJM_PASS",
+					zh: "ojm install <file.tgz | name[@version] | @<scope>/<name>[@version]> [--site-url <u>] [--user <u>] [--pass <p>] [--name <n>] [--version <v>] [--registry <r>] [--force] [--locale <zh-CN|en-US>]\n  本地 tgz 走 file 上传（<name>-<version>.tgz 文件名推导身份，可 --name/--version 覆盖）；name[@version] 走 CDN 市场源；@<scope>/<name>[@version] --registry <url> 走外部 registry 源（目录键由 CLI 归一为物理名 slug，白名单在服务端）\n  登录 → 提交 → 轮询任务至终态并打印结果（失败附原因 + 指引）\n  --force：强制重装配（oj 0.1.123+），旁路「已是最新装配」幂等短路\n  站点寻址：--site-url/--user/--pass，或环境变量 OJM_SITE_URL / OJM_USER / OJM_PASS",
+					en: "ojm install <file.tgz | name[@version] | @<scope>/<name>[@version]> [--site-url <u>] [--user <u>] [--pass <p>] [--name <n>] [--version <v>] [--registry <r>] [--force] [--locale <zh-CN|en-US>]\n  Local tgz goes through file upload (identity derived from the <name>-<version>.tgz file name, overridable via --name/--version); name[@version] goes through the CDN marketplace; @<scope>/<name>[@version] --registry <url> goes through an external registry source (the directory key is normalized to the physical slug by the CLI; allowlist is server-side)\n  Login → submit → poll the task to a terminal state and print the result (failures include the reason + guidance)\n  --force: force re-assembly (oj 0.1.123+), bypassing the \"already latest assembly\" idempotent short-circuit\n  Site addressing: --site-url/--user/--pass, or env vars OJM_SITE_URL / OJM_USER / OJM_PASS",
 				},
 			},
 			{
@@ -364,12 +366,14 @@ export const HELP_GROUPS: HelpGroup[] = [
 				en: "Generate an Ed25519 signing key pair",
 				options: [
 					{ raw: "--id <id>", zh: "发布方 key id（形如 publisher.key）", en: "Publisher key id (e.g. publisher.key)" },
+					{ raw: "--credential <token>", zh: "在线兑换发布凭证（也读 OJM_PUBLISH_CREDENTIAL；与 --id 互斥）", en: "Redeem a publishing credential online (also reads OJM_PUBLISH_CREDENTIAL; mutually exclusive with --id)" },
+					{ raw: "--site-url <url>", zh: "兑换站点（缺省 OJM_SITE_URL / http://127.0.0.1:9778）", en: "Site for redemption (defaults to OJM_SITE_URL / http://127.0.0.1:9778)" },
 					{ raw: "--out <dir>", zh: "输出目录（缺省 ~/.ojm/keys/<id>/；指到工程树内须 --yes）", en: "Output directory (default ~/.ojm/keys/<id>/; pointing inside the project tree requires --yes)" },
 					{ raw: "--yes", zh: "确认私钥落盘到工程树内（私钥入仓即泄露）", en: "Acknowledge writing the private key inside the project tree (a private key in the repo is leaked)" },
 				],
 				detail: {
-					zh: "ojm keygen --id <publisher.id> [--out <dir>] [--yes]\n  私钥默认 ~/.ojm/keys/<id>/ 永不出目录；打印公钥 hex 供 ojm trust add / 模板回填",
-					en: "ojm keygen --id <publisher.id> [--out <dir>] [--yes]\n  The private key stays under ~/.ojm/keys/<id>/ by default; prints the public key hex for ojm trust add / template backfill",
+					zh: "ojm keygen --id <publisher.id> [--out <dir>] [--yes]\n  私钥默认 ~/.ojm/keys/<id>/ 永不出目录；打印公钥 hex 供 ojm trust add / 模板回填\n\nojm keygen --credential <token> [--site-url <url>] [--out <dir>] [--yes]\n  凭证兑换：key_id 由站点按「产品名.用户名」算好下发，CLI 不推导；凭证一次性，兑换即作废\n  失败（过期/已用/已撤销/网络）不落任何密钥文件；兑换成功再走与离线版完全相同的落盘流程",
+					en: "ojm keygen --id <publisher.id> [--out <dir>] [--yes]\n  The private key stays under ~/.ojm/keys/<id>/ by default; prints the public key hex for ojm trust add / template backfill\n\nojm keygen --credential <token> [--site-url <url>] [--out <dir>] [--yes]\n  Credential redemption: key_id is derived server-side as <product>.<username>, the CLI never re-derives it; the credential is single-use\n  Any failure (expired/used/revoked/network) writes no key files; on success the same keygen flow as the offline path runs",
 				},
 			},
 			{