@oj-module/cli 0.2.64 → 0.2.67

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

@@ -26,7 +26,7 @@ peerPlatform: '>=0.1.0' # C2-11（P2 起对宿主 API_VERSION 强制；本仓 AP
 api:
   module: demo-solution # C2-12（存在时必须 === name）
   prefix: /api/demo-solution # C2-13（默认形态显式写出）
-  tables: [note] # 与 schema.yaml 表集一致（oj 冗余校验同源）
+  tables: [demo_solution_note] # 与 schema.yaml 表集一致（oj 冗余校验同源）；表名带 C2-12c 前缀
   deps: # 键 = 模块名（C2-01 语法或 _platform）；值 = 范围算子语法
     _platform: '>=0.1.0'
   anonymous: # C2-26：首段 === 模块段；无登录语义端点

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

@@ -14,7 +14,7 @@ import { parse } from "yaml";
 // 跨端引用（双端一致钉）：被测实现同仓分居两运行时（计划 §1「两运行时取舍」），
 // 测试直接互调，比「两套件各读同一夹具」更强——漂移即本文件红。
 import { preflight } from "../../../templates/src/app/api/_platform/_lifecycle/steps/preflight";
-import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, RESERVED_NAMES, reservedNameSuggestions, validateContract } from "../../manifest-contract";
+import { checkLocalesComplete, checkSchemaTablePrefix, checkTablesAgainstSchema, parseManifest, RESERVED_NAMES, reservedNameSuggestions, validateContract } from "../../manifest-contract";
 
 const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "fixtures");
 const readText = (p: string) => readFileSync(join(FIXTURES, p), "utf8");
@@ -214,19 +214,91 @@ describe("rEG-CS7 保留名扩项（红队 F5）", () => {
 describe("checkTablesAgainstSchema（C2-12a：构建 ✅ 对照 schema.yaml）", () => {
 	const SCHEMA = readText("fixture-valid/api/src/demo-solution/schema.yaml");
 
-	it("fixture-valid tables [note] 与 schema.yaml 表集一致 → 零违规", () => {
+	it("fixture-valid tables 与 schema.yaml 表集一致 → 零违规", () => {
 		expect(checkTablesAgainstSchema(structuredClone(VALID), SCHEMA)).toEqual([]);
 	});
 
 	it("tables 与 schema.yaml 表集不一致 → C2-12a 且指明差额", () => {
 		const m = structuredClone(VALID);
-		(m.api as any).tables = ["note", "ghost"];
+		(m.api as any).tables = ["demo_solution_note", "ghost"];
 		const v = checkTablesAgainstSchema(m, SCHEMA);
 		expect(v[0]).toContain("C2-12a");
 		expect(v[0]).toContain("ghost");
 	});
 });
 
+describe("checkSchemaTablePrefix（C2-12c：schema.yaml 表前缀）", () => {
+	const SCHEMA = readText("fixture-valid/api/src/demo-solution/schema.yaml");
+
+	it("fixture-valid 声明 prefix 且表名带前缀 → 零违规", () => {
+		expect(checkSchemaTablePrefix(SCHEMA)).toEqual([]);
+	});
+
+	it("允许自选短前缀（长模块名可用 crm_ 之类，不强制由模块名派生）", () => {
+		expect(checkSchemaTablePrefix("prefix: dm_\ntables:\n  dm_note: {}\n")).toEqual([]);
+	});
+
+	it("缺 prefix → C2-12c", () => {
+		const v = checkSchemaTablePrefix("tables:\n  demo_solution_note: {}\n");
+		expect(v[0]).toContain("C2-12c");
+		expect(v[0]).toContain("prefix");
+	});
+
+	it("prefix 不以 _ 结尾 → C2-12c 语法违规", () => {
+		const v = checkSchemaTablePrefix("prefix: demo_solution\ntables:\n  demo_solution_note: {}\n");
+		expect(v[0]).toContain("C2-12c");
+		expect(v[0]).toContain("_ 结尾");
+	});
+
+	it("prefix 超过 32 字符 → C2-12c（吃掉表名可用空间）", () => {
+		const long = `${"a".repeat(33)}_`;
+		const v = checkSchemaTablePrefix(`prefix: ${long}\ntables:\n  ${long}note: {}\n`);
+		expect(v[0]).toContain("C2-12c");
+		expect(v[0]).toContain("超过上限 32");
+	});
+
+	it("表名未带前缀 → C2-12c 并给出改名建议", () => {
+		const v = checkSchemaTablePrefix("prefix: demo_solution_\ntables:\n  note: {}\n");
+		expect(v[0]).toContain("C2-12c");
+		expect(v[0]).toContain("demo_solution_note");
+	});
+
+	it("表名总长边界：63 合法、64 拒绝（PostgreSQL 上限 63 字节）", () => {
+		const p = "ab_";
+		const name63 = `${p}${"c".repeat(60)}`; // 3 + 60 = 63
+		const name64 = `${p}${"c".repeat(61)}`; // 3 + 61 = 64
+		expect(name63.length).toBe(63);
+		expect(checkSchemaTablePrefix(`prefix: ${p}\ntables:\n  ${name63}: {}\n`)).toEqual([]);
+		const v = checkSchemaTablePrefix(`prefix: ${p}\ntables:\n  ${name64}: {}\n`);
+		expect(v[0]).toContain("C2-12c");
+		expect(v[0]).toContain("63 字符");
+	});
+
+	it("引用式方案（api.tables 缺省）也做前缀检查", () => {
+		const m = structuredClone(VALID);
+		delete (m.api as any).tables;
+		const v = checkTablesAgainstSchema(m, "tables:\n  note: {}\n");
+		expect(v[0]).toContain("C2-12c");
+	});
+
+	it("prefix 落在第一方保留段（oj_ / ojm_ 开头）→ C2-12c，整段禁用含派生形式", () => {
+		for (const p of ["oj_", "ojm_", "oj_crm_", "ojm_tools_"]) {
+			const v = checkSchemaTablePrefix(`prefix: ${p}\ntables:\n  ${p}note: {}\n`);
+			expect(v.some(x => x.includes("C2-12c") && x.includes("保留段"))).toBe(true);
+		}
+	});
+
+	it("自有前缀不落在保留段 → 零违规（保留段检查的对照）", () => {
+		expect(checkSchemaTablePrefix("prefix: crm_\ntables:\n  crm_note: {}\n")).toEqual([]);
+	});
+
+	it("_oj_ 因下划线开头只报语法违规，不重复报保留段", () => {
+		const v = checkSchemaTablePrefix("prefix: _oj_\ntables:\n  _oj_note: {}\n");
+		expect(v[0]).toContain("必须匹配");
+		expect(v.every(x => !x.includes("保留段"))).toBe(true);
+	});
+});
+
 describe("checkLocalesComplete（C2-25：构建期缺 key fail-fast）", () => {
 	const ZH = readText("fixture-valid/web/src/demo-solution/locales/zh-CN.json");
 	const EN = readText("fixture-valid/web/src/demo-solution/locales/en-US.json");

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

@@ -37,11 +37,11 @@ describe.skipIf(!smokeReady)("真机冒烟（需 OJM_SMOKE_URL/OJM_SMOKE_USER/OJ
 		const apiDist = join(project, "dist/api/demo-solution-0.1.0");
 		const { mkdirSync, writeFileSync } = await import("node:fs");
 		mkdirSync(join(apiDist, "ping"), { recursive: true });
-		// 迁移 SQL 随夹具 src 真源（0001__init.sql 建 note 表）；B-11 硬验收：appliedSeq > 0 可断言
+		// 迁移 SQL 随夹具 src 真源（0001__init.sql 建 demo_solution_note 表）；B-11 硬验收：appliedSeq > 0 可断言
 		cpSync(join(FIXTURE_VALID, "api/src/demo-solution/migrations"), join(apiDist, "migrations"), { recursive: true });
 		// schema.yaml 同随夹具真源（列集与迁移 SQL 一致）：oj migrate 在 apply 后跑 schema
 		// reconcile（migrate_cmd.rs migrate_one），声明缺列而实库多列 = Err——合成空列集会炸
-		writeFileSync(join(apiDist, "manifest.yaml"), "name: demo-solution\ndesc: manifest.yaml 契约全字段合法夹具\nversion: 0.1.0\ntables:\n  - note\n");
+		writeFileSync(join(apiDist, "manifest.yaml"), "name: demo-solution\ndesc: manifest.yaml 契约全字段合法夹具\nversion: 0.1.0\ntables:\n  - demo_solution_note\n");
 		cpSync(join(FIXTURE_VALID, "api/src/demo-solution/schema.yaml"), join(apiDist, "schema.yaml"));
 		writeFileSync(join(apiDist, "routes.js"), "export {};\n");
 		writeFileSync(join(apiDist, "ping/api.js"), "export async function ping() {}\n");

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

@@ -38,6 +38,8 @@ export interface MarketPublishOptions {
 	check?: boolean
 	/** 签发方 registry 身份（REG-CS3 v2 防跨仓库重放；透传 signCommand --registry-id） */
 	registryId?: string
+	/** 命令层是否紧接着重建索引（仅用于措辞：true 时不打印「索引未重建」） */
+	rebuildIndex?: boolean
 }
 
 export interface MarketPublishResult {
@@ -88,7 +90,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,

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/shared-deps.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 /**
  * 共享依赖表 —— 单一常量源（设计文档 §4.3，解决 B11 / B12）。
  *
@@ -21,15 +23,18 @@ export interface SharedDepEntry {
 	/** 硬共享：模块不得自带 */
 	hard: boolean
 	/**
-	 * 软共享但「不进宿主首屏」：宿主 shell 不预构建该资产、importmap 不列该键，
-	 * 模块若 import 它则自行打包进模块产物（设计文档 §4.3 的「软共享缺席→模块自带
-	 * 副本兜底」语义）。用于**仅模块使用、宿主与共享 chunk 永不 import**的重型依赖
-	 * （编辑器 / 图表 / Markdown / 拖拽 …），避免把它们 5~6MB 的体量无谓铺进
-	 * shell-dist 并要求公开链路多传一堆文件。宿主侧有真实 import 的共享依赖
-	 * （antd / pro-components / icons 内部依赖的 motion / react-jss / dayjs /
-	 * zustand 等）绝不能标 bundle —— 否则会被 antd 等共享 chunk 经 importmap 解析
-	 * 不到而 404。判定依据：宿主 host.tsx + runtime.js 的传递 import 图，以及
-	 * antd/pro-components/icons 的传递依赖图，都不含这些说明符。
+	 * 模块自打包：宿主 shell 不预构建该资产、importmap 不列该键，模块若 import 它
+	 * 则自行打包进模块产物（设计文档 §4.3 的「软共享缺席→模块自带副本兜底」语义）。
+	 * 用于**仅模块使用、宿主与共享 chunk 永不 import**的重型依赖（编辑器 / 图表 /
+	 * Markdown），避免把它们 5~6MB 的体量无谓铺进 shell-dist 并要求公开链路多传
+	 * 一堆文件。宿主侧有真实 import 的共享依赖（antd / pro-components / icons 内部
+	 * 依赖的 motion / react-jss / dayjs / zustand / @dnd-kit 等）绝不能标 bundle ——
+	 * 否则会被 antd 等共享 chunk 经 importmap 解析不到而 404。判定依据：宿主
+	 * host.tsx + runtime.js 的传递 import 图，以及 antd/pro-components/icons 的
+	 * 传递依赖图，都不含这些说明符。
+	 *
+	 * ⚠️ 本档位**不计入宿主版本一致性保障**：模块把副本打进产物，多副本不会报错，
+	 * 只会重复体积。体积怎么控，见 docs/devkit/manual.md §2.6。
 	 */
 	bundle?: boolean
 }
@@ -66,9 +71,10 @@ export const SHARED_DEPS: SharedDepEntry[] = [
 	 *   - 无单例语义。kit 必须唯一是因为多副本 = 两份 antd 上下文树；编辑器资产
 	 *     把 @tiptap/*、@plane/ui 等**全部内联**在自身里，跨边界穿过的只有 React
 	 *     家族（那是独立的硬共享条目），多一份编辑器副本不会拆散任何 context。
-	 *   - 不是每个模块都用编辑器。软共享的语义正是「默认由宿主提供，允许 importmap
-	 *     scopes 多版本共存兜底（C7）」——缺席时模块可自带副本而不硬失败。
-	 *     代价：多副本会重复约 5.4 MB 资产，故 scopes 只作兜底、默认仍走宿主。
+	 *   - 不是每个模块都用编辑器。软共享的语义是「允许缺席」——宿主**不预构建**
+	 *     这份资产（bundle: true，不进 shell-dist、不进 importmap），模块 import 它
+	 *     就自己打进产物。代价是每个用编辑器的模块各带一份约 5.4 MB，换来宿主
+	 *     分发体积不被没人用的重型依赖撑大。
 	 */
 	{ specifier: "@plane/editor", asset: "editor", hard: false, bundle: true },
 	// 注：@rc-component/form（antd 6 Form 底层）曾尝试单例化以修 my-profile
@@ -120,6 +126,9 @@ export const SHARED_DEPS: SharedDepEntry[] = [
 	{ specifier: "dayjs/plugin/weekday", asset: "dayjs-plugin-weekday", hard: false },
 	{ specifier: "dayjs/plugin/weekOfYear", asset: "dayjs-plugin-weekOfYear", hard: false },
 	{ specifier: "dayjs/plugin/weekYear", asset: "dayjs-plugin-weekYear", hard: false },
+	// echarts 家族：模块自打包。整包 index（`import * as echarts from "echarts"`）会让
+	// 单个模块产物从 ~180KB 涨到 1.7MB（实测 echarts 918KB + zrender 221KB 占 87%），
+	// 故脚手架改用 `echarts/core` 按需注册；接入方写法见 docs/devkit/manual.md §2.6。
 	{ specifier: "echarts", asset: "echarts", hard: false, bundle: true },
 	{ specifier: "echarts/charts", asset: "echarts-charts", hard: false, bundle: true },
 	{ specifier: "echarts/features.js", asset: "echarts-features", hard: false, bundle: true },
@@ -147,18 +156,21 @@ export const SHARED_DEPS: SharedDepEntry[] = [
 	{ specifier: "tailwind-merge", asset: "tailwind-merge", hard: false },
 	/**
 	 * Markdown 编辑器（Vditor v4，M5 回升自下游 oj-wiki）：npm 包是 webpack **UMD**
-	 * 单产物（main=dist/index.js，无 ESM 出口、仅 default 导出），走 starShim + esbuild
-	 * 的既有 CJS/UMD interop 链路打包成 ESM 资产（与 react 家族同路，无需新机制）。
+	 * 单产物（main=dist/index.js，无 ESM 出口、仅 default 导出）。bundle: true 表示
+	 * 宿主不预构建 —— CJS/UMD interop 交给模块自己的 rolldown 打包链路处理。
 	 *
-	 * 软共享：无单例语义（多副本只是重复体积，不拆 context），且不是每个模块都用。
-	 * 体积大（gzip ≈700 KiB），故**惰性生效**：importmap 只做映射，宿主 shell 自身
-	 * 不 import vditor ⇒ /assets/vditor.js 仅在模块产物真正 import 它时才被拉取，
-	 * 不进宿主首屏。
+	 * 为什么不预构建：体积大（gzip ≈700 KiB）且不是每个模块都用。宿主为它留一份
+	 * /assets/vditor.js，等于给所有站点无条件加 700 KiB 分发体积，而只有编辑器页
+	 * 才用得上。改由模块自带后，代价转给「真正 import 它的那个模块」。
+	 *
+	 * 副作用（写文档时容易说错）：模块产物是单文件（codeSplitting: false），
+	 * 所以 `import("vditor")` 会被内联回去，**动态导入并不能把它从首屏摘掉**；
+	 * 要省这笔体积只能把编辑器页拆成独立模块/方案。
 	 *
 	 * 深路径只登记 CSS 主样式（nprogress 同款样式垫片）。vditor 其余 dist 深路径
 	 * （lute / i18n / icons / 主题 CSS…）是**运行期经 cdn 选项按需拉取的资源**而非
 	 * import 说明符，由模块侧自行处理（自注入或指向宿主可服务的路径）；若模块代码
-	 * 直接 import 它们，会命中前缀 external 但无 importmap 键 → 构建期深路径报错，
+	 * 直接 import 它们，会命中前缀 external 但无共享表键 → 构建期深路径报错，
 	 * 属预期拦截（与 dayjs/plugin/* 同规则）。
 	 */
 	{ specifier: "vditor", asset: "vditor", hard: false, bundle: true },
@@ -182,6 +194,10 @@ export function generateShellEntries(): { name: string, pkg: string }[] {
 /**
  * 由共享表生成 importmap：说明符 → /assets/<asset>.js。
  * baseUrl 供宿主部署在子路径时使用。
+ *
+ * 注意：这里给出的是**逻辑名**。shell 构建落盘时会把每个资产改名成
+ * `<asset>.<hash>.js`（见 `hashedAssetFileName`），importmap 由构建脚本同步改写，
+ * 运行时拿到的仍是 `/assets/<asset>.<hash>.js`。
  */
 export function generateImportmap(baseUrl = ""): Record<string, string> {
 	const map: Record<string, string> = {};
@@ -196,3 +212,37 @@ export function generateImportmap(baseUrl = ""): Record<string, string> {
 export function isPrebuiltDep(id: string): boolean {
 	return SHARED_DEPS.some(dep => !dep.bundle && (id === dep.specifier || id.startsWith(`${dep.specifier}/`)));
 }
+
+/**
+ * 共享资产的内容哈希段：10 位 base36，且**保证**同时含数字与字母。
+ *
+ * 为什么必须保证：oj serve ≥ 0.1.116 的默认缓存策略按**文件名**判定
+ * （`serve/src/static_files.rs::default_cache_control`）——文件名 stem 按 `-` `_` `.`
+ * 切段，末段 ≥8 位且同时含数字与字母才发 `public, max-age=31536000, immutable`，
+ * 其余一律 `no-cache`。纯 base36 有十万分之一量级会全数字（vite 的 base64url 更糟：
+ * 8 位全字母约 19%），漏判就白丢一年缓存。这里按「缺哪类补哪类」定长补齐，
+ * 让每个资产 100% 命中长缓存，而不是赌概率。
+ *
+ * 9 位 base36 ≈ 46.5 bit，65 个资产量级碰撞概率可忽略。
+ */
+export function assetHash(content: string | Uint8Array): string {
+	const digest = createHash("sha256").update(content).digest();
+	const body = digest.readBigUInt64BE(0).toString(36).slice(0, 9).padStart(9, "0");
+	// 已有字母 → 补数字；全数字 → 补字母。两类必在其一，补齐另一类即可。
+	return /[a-z]/.test(body) ? `${body}0` : `${body}z`;
+}
+
+/** 内容寻址文件名：`<base>.<hash>.js`（js 与 map 同为 .js 后缀，map 保持原名不动） */
+export function hashedAssetFileName(base: string, content: string | Uint8Array): string {
+	return `${base}.${assetHash(content)}.js`;
+}
+
+/**
+ * 与 oj serve 的 `default_cache_control` 同口径：末段 ≥8 位且数字字母都有 → 可发 immutable。
+ * 构建期用它断言产物名，避免哪天哈希算法换掉后长缓存静默失效。
+ */
+export function isImmutableAssetFileName(fileName: string): boolean {
+	const stem = fileName.replace(/\.[^.]*$/, "");
+	const seg = stem.split(/[-_.]/).pop() ?? "";
+	return seg.length >= 8 && /\d/.test(seg) && /[a-z]/i.test(seg);
+}

package/src/site-base.ts

@@ -102,6 +102,10 @@ export function rewriteIndexHtml(html: string, siteBase: string | undefined, api
 		// 上一步已处理，二者不重叠。
 		out = out.replace(/(\b(?:href|src|data-ojm-entry)=")(\/[^/"][^"]*|\/")/g, (_m, attr: string, url: string) =>
 			`${attr}${withSiteBase(url, base)}`);
+		// data-ojm-preload 是**逗号分隔的 URL 列表**（构建期算好的首屏静态闭包），
+		// 上面那条单值正则匹配不到列表，漏改会让子路径部署下预取全 404（退化回瀑布，不白屏但慢）
+		out = out.replace(/(\bdata-ojm-preload=")([^"]*)"/g, (_m, attr: string, list: string) =>
+			`${attr}${list.split(",").map(url => url.startsWith("/") ? withSiteBase(url, base) : url).join(",")}"`);
 		globals.push(`window.__OJ_BASE__=${JSON.stringify(base)};`);
 	}
 	if (api) {

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） */