@oj-module/cli 0.2.57 → 0.2.62

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.57",
+  "version": "0.2.62",
   "description": "React Antd 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
@@ -49,7 +49,7 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.2.57",
+    "@oj-module/runtime": "0.2.62",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "cac": "^6.7.14",

package/shell-dist/assets/{index-CImwskAz.js → index-BKtXxIXz.js}

@@ -1,6 +1,6 @@
 import { StyleProvider } from "@ant-design/cssinjs";
 import { AntdApp, ErrorBoundary, LayoutEffects, PageError, getHostRoutes, getRoutes, loadAll, resolveApiBase, setupI18n, useAccessStore, useAuthStore, usePreferences, useUserStore } from "@oj-module/runtime";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MutationCache, QueryCache, QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { ConfigProvider, theme } from "antd";
 import { useEffect, useState } from "react";
 import { createRoot } from "react-dom/client";
@@ -195,7 +195,37 @@ ${offenders.join("\n")}\n修复建议：该来源不在宿主内置白名单中
 }
 //#endregion
 //#region shell/src/host.tsx
-var queryClient = new QueryClient();
+/**
+* 全局失败收敛（框架层唯一构造点）。
+*
+* 宿主是唯一构造 QueryClient 的地方：模块页面的 useQuery/useQueryClient 上下文
+* 都来自此处，`ojm build` 对 shell-dist 全量合并，工程侧没有注入 defaults 的缝隙。
+* 原先裸 `new QueryClient()` 走 TanStack 默认 `retry: 3`，导致「必然失败也白等 3 次
+* 重试 + 请求层逐次弹 toast 刷屏」。
+*
+* 这里两处收敛：
+* - `retry: 1`：保留一次瞬时抖动重试，去掉默认 3 次的无效等待（mutations 默认不重试）；
+* - `QueryCache/MutationCache` onError：请求层 {@link handleErrorResponse} 已对
+*   HTTP 错误体弹 toast，此处只兜底「请求层未触达」的失败（网络中断 / 解析异常 /
+*   非响应错误），避免与其重复弹窗。
+*/
+function isHttpError(error) {
+	const maybe = error;
+	return Boolean(maybe?.response && typeof maybe.response.status === "number");
+}
+function surfaceQueryError(error) {
+	if (isHttpError(error)) return;
+	const message = error instanceof Error && /fetch|network|timeout/i.test(error.message) ? "网络异常，请检查网络连接后重试" : error instanceof Error ? error.message : "请求失败";
+	window.$message?.error(message);
+}
+var queryClient = new QueryClient({
+	defaultOptions: {
+		queries: { retry: 1 },
+		mutations: { retry: 0 }
+	},
+	queryCache: new QueryCache({ onError: surfaceQueryError }),
+	mutationCache: new MutationCache({ onError: surfaceQueryError })
+});
 var DEMO_USER = {
 	id: "1",
 	avatar: "https://avatars.githubusercontent.com/u/47056890",

package/shell-dist/assets/runtime.js

@@ -304,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.57",
+			"version": "0.2.62",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-11-03 11:30:53"
+		"lastBuildTime": "2026-11-04 08:31:17"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -7160,7 +7160,7 @@ var init_parent_layout = __esmMin((() => {}));
 */
 function resolveLayoutComponent(handle) {
 	const name = handle?.layout;
-	if (!name) return Outlet;
+	if (!name || name === "none") return Outlet;
 	const registered = getRegisteredLayout(name);
 	if (registered) return registered;
 	if (layoutRegistry[name]) return layoutRegistry[name];

package/shell-dist/index.html

@@ -5,8 +5,8 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-p8IkoQDMiluaMnE2ANd5og=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
-		<script type="importmap" nonce="p8IkoQDMiluaMnE2ANd5og==">{
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-SJbJrNlpPRxj8pl6EctCJA=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<script type="importmap" nonce="SJbJrNlpPRxj8pl6EctCJA==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",
@@ -130,7 +130,7 @@
 			.boot-skeleton:after{content:"";width:18px;height:18px;margin-left:8px;border:2px solid #d9d9d9;border-top-color:#1677ff;border-radius:50%;animation:bs-spin .8s linear infinite}
 			@keyframes bs-spin{to{transform:rotate(360deg)}}
 		</style>
-		<script nonce="p8IkoQDMiluaMnE2ANd5og==" data-ojm-entry="/assets/index-CImwskAz.js">(function(){try{var ua=(navigator.userAgent||"").toLowerCase(),p=location.pathname;while(p.length>1&&p.charAt(p.length-1)==="/")p=p.slice(0,-1);if(ua.indexOf("wxwork")>=0&&p.slice(-6)==="/login"&&!new URLSearchParams(location.search).get("wecom_ticket")){var a=(typeof window.__OJ_API_BASE__==="string"&&window.__OJ_API_BASE__.trim())||"/api";while(a.length>1&&a.charAt(a.length-1)==="/")a=a.slice(0,-1);location.replace(a+"/auth/wecom/login");return}}catch(e){}var s=document.createElement("script");s.type="module";s.src=document.currentScript.getAttribute("data-ojm-entry");document.head.appendChild(s);})();</script>
+		<script nonce="SJbJrNlpPRxj8pl6EctCJA==" data-ojm-entry="/assets/index-BKtXxIXz.js">(function(){try{var ua=(navigator.userAgent||"").toLowerCase(),p=location.pathname;while(p.length>1&&p.charAt(p.length-1)==="/")p=p.slice(0,-1);if(ua.indexOf("wxwork")>=0&&p.slice(-6)==="/login"&&!new URLSearchParams(location.search).get("wecom_ticket")){var a=(typeof window.__OJ_API_BASE__==="string"&&window.__OJ_API_BASE__.trim())||"/api";while(a.length>1&&a.charAt(a.length-1)==="/")a=a.slice(0,-1);location.replace(a+"/auth/wecom/login");return}}catch(e){}var s=document.createElement("script");s.type="module";s.src=document.currentScript.getAttribute("data-ojm-entry");document.head.appendChild(s);})();</script>
 	</head>
 	<body>
 		<div id="root"><div class="boot-skeleton">加载中…</div></div>

package/shell-dist/versions.json

@@ -7,9 +7,9 @@
   "react-router": "7.18.2",
   "react-router/dom": "7.18.2",
   "@tanstack/react-query": "5.102.8",
-  "@oj-module/runtime": "0.2.57",
-  "@oj-module/runtime/contract": "0.2.57",
-  "@oj-module/runtime/contract/errors": "0.2.57",
+  "@oj-module/runtime": "0.2.62",
+  "@oj-module/runtime/contract": "0.2.62",
+  "@oj-module/runtime/contract/errors": "0.2.62",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/__tests__/port-check.test.ts

@@ -0,0 +1,40 @@
+import net from "node:net";
+import { afterAll, describe, expect, it } from "vitest";
+import { isPortOccupied } from "../port-check";
+
+describe("isPortOccupied", () => {
+	it("端口有监听者时返回 true", async () => {
+		const server = net.createServer();
+		await new Promise<void>(resolve => server.listen(0, "127.0.0.1", () => resolve()));
+		const port = (server.address() as net.AddressInfo).port;
+		expect(await isPortOccupied(port)).toBe(true);
+		await new Promise<void>(resolve => server.close(() => resolve()));
+	});
+
+	it("端口空闲时返回 false", async () => {
+		// 探测一批非临时端口区间的端口：localhost 上这些端口几乎不可能被占用，
+		// 命中一个即证明「空闲端口返回 false」。避开 macOS 临时端口区间（49152+，
+		// 连接会被静默丢弃而非返回 ECONNREFUSED，导致保守判为占用）。
+		let foundFree = false;
+		for (const p of [23000, 23001, 23002, 23003, 23004]) {
+			if (!(await isPortOccupied(p))) {
+				foundFree = true;
+				break;
+			}
+		}
+		expect(foundFree).toBe(true);
+	});
+
+	it("默认 host 为 127.0.0.1", async () => {
+		const server = net.createServer();
+		await new Promise<void>(resolve => server.listen(0, "127.0.0.1", () => resolve()));
+		const port = (server.address() as net.AddressInfo).port;
+		expect(await isPortOccupied(port, "127.0.0.1")).toBe(true);
+		await new Promise<void>(resolve => server.close(() => resolve()));
+	});
+});
+
+// 防止未关闭句柄拖慢套件退出
+afterAll(() => {
+	// 无持久资源；占位以明确意图
+});

package/src/__tests__/vendor.test.ts

@@ -0,0 +1,39 @@
+import { execFileSync } from "node:child_process";
+import { describe, expect, it, vi } from "vitest";
+import { defaultRun, npmExecSpec } from "../vendor";
+
+vi.mock("node:child_process", () => ({
+	execFileSync: vi.fn(() => ""),
+}));
+
+const mockedExec = vi.mocked(execFileSync);
+
+describe("npmExecSpec / defaultRun（Windows npm.cmd 兼容）", () => {
+	it("非 Windows：直接以 npm 执行，不经 shell", () => {
+		expect(npmExecSpec("linux", ["view", "x", "version"])).toEqual({
+			cmd: "npm",
+			execArgs: ["view", "x", "version"],
+		});
+		expect(npmExecSpec("darwin", ["install", "y"])).toEqual({
+			cmd: "npm",
+			execArgs: ["install", "y"],
+		});
+	});
+
+	it("windows：以 cmd.exe /c npm.cmd 包裹（修复 spawnSync npm.cmd EINVAL）", () => {
+		expect(npmExecSpec("win32", ["install", "@oj-bin/oj@0.1.86"])).toEqual({
+			cmd: "cmd.exe",
+			execArgs: ["/c", "npm.cmd", "install", "@oj-bin/oj@0.1.86"],
+		});
+	});
+
+	it("defaultRun 按当前平台选择执行方式", () => {
+		defaultRun(["view", "x", "version"], "/tmp/x");
+		const platform = process.platform;
+		const expectedCmd = platform === "win32" ? "cmd.exe" : "npm";
+		const expectedArgs = platform === "win32"
+			? ["/c", "npm.cmd", "view", "x", "version"]
+			: ["view", "x", "version"];
+		expect(mockedExec).toHaveBeenCalledWith(expectedCmd, expectedArgs, expect.objectContaining({ cwd: "/tmp/x" }));
+	});
+});

package/src/build/module-def.ts

@@ -297,7 +297,20 @@ function makeBareImportStubPlugin(namesBySpec: Map<string, string[]>): EsbuildPl
 	return {
 		name: "ojm-bare-import-stub",
 		setup(b) {
-			b.onResolve({ filter: /^[^./#]/ }, args => ({ path: args.path, namespace: "ojm-bare-stub" }));
+			b.onResolve({ filter: /^[^./#]/ }, (args) => {
+				// 排除入口自身与绝对路径：entryPoints 在 Windows 上以盘符绝对路径（d:/...）
+				// 传入，会命中上面的裸说明符过滤被桩化成「可 thenable 的代理」——
+				// 整个入口模块变成 new Proxy(function(){},{get:()=>value,apply:()=>value})，
+				// mod.default 因而是一个 thenable，async readModuleDefinition 执行 return
+				// 时被当 thenable 接管、其 .then 永远不回调 resolve → Promise 永 pending →
+				// 事件循环排空 → Node 以退出码 0 静默退出（pnpm dev 起不来）。
+				// macOS/Linux 绝对路径以 / 开头已被过滤排除，故这是 Windows-only bug。
+				if (args.kind === "entry-point")
+					return null;
+				if (/^[a-z]:/i.test(args.path))
+					return null;
+				return { path: args.path, namespace: "ojm-bare-stub" };
+			});
 			b.onLoad({ filter: /.*/, namespace: "ojm-bare-stub" }, (args) => {
 				const names = namesBySpec.get(args.path) ?? [];
 				return {
@@ -348,6 +361,10 @@ export async function readModuleDefinition(entryFile: string, projectRoot: strin
 			// 会让非 entry.ts 文件名（如测试夹具）的产物对不上后续 import 路径
 			entryNames: "entry",
 			bundle: true,
+			// ESM 输出 + import() 加载：入口经下方 onResolve 修正后不会被裸导入桩误伤为
+			// thenable 代理，Windows/macOS 行为一致（此前 Windows 卡死的根因是入口被桩化成
+			// 代理导致 async return 被 thenable 接管而永不 settle）。元数据读取只需取
+			// `.default`，无需 CJS 语义。
 			format: "esm",
 			platform: "node",
 			packages: "external",
@@ -360,6 +377,8 @@ export async function readModuleDefinition(entryFile: string, projectRoot: strin
 			logLevel: "silent",
 		});
 		const bundled = path.join(outDir, "entry.js");
+		// 加载桩化产物（ESM）：入口不会被裸导入桩误伤为 thenable 代理（见 onResolve 修正），
+		// 故 mod.default 是真实定义，import() 正常 settle。
 		const mod = await import(pathToFileURL(bundled).href);
 		const definition = mod.default;
 		if (!definition?.name || !definition?.version) {

package/src/cli.ts

@@ -121,6 +121,13 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 				const portArg = Number(port);
 				await devServer(projectRoot, { port: Number.isFinite(portArg) && portArg > 0 ? portArg : 5174 });
 			};
+		case "rekey":
+			return async () => {
+				const { rekeyCommand } = await import("./rekey");
+				const result = rekeyCommand(projectRoot);
+				console.log(`[ojm] 已重新生成开发态本机密钥与 dev jwt_secret：${path.relative(projectRoot, result.localPath) || result.localPath}`);
+				console.log("[ojm] 仅影响 gitignored 的 config.local.yaml 与 config/secrets-*.pem；tracked config.yaml 未改动。下次 ojm dev 会用新密钥自动重合并重起。");
+			};
 		case "build":
 			return async (opts: { bundle?: unknown, out?: string } = {}) => {
 				// mri 可选值：裸 --bundle 得到 ""，--bundle name / --bundle=name 得到字符串

package/src/contract/emit-stub.ts

@@ -2,7 +2,7 @@ import type { OjSchemaDiag } from "./emit-oj-schema";
 import type { IrEndpoint } from "./ir";
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, posix, sep } from "node:path";
 import { emitOjSchemaLine } from "./emit-oj-schema";
 import { splitRoute, wirePrefixOf } from "./ir";
 import { jsonSchemaToSample } from "./json-schema-sample";
@@ -147,8 +147,12 @@ export async function planStubWrites(ir: IrEndpoint[], opts: PlanStubOptions): P
 
 	const writes: StubWrite[] = [];
 	for (const [, { module, dir, endpoints }] of [...groups.entries()].sort()) {
-		const apiRoot = opts.apiRootOf ? opts.apiRootOf(module) : join(opts.apiSrcDir, module);
-		const filePath = join(apiRoot, dir, "api.ts");
+		// filePath 统一 POSIX 分隔符：契约/manifest/指纹键都按 `/` 比对，Windows 上
+		// path.join 会产出 `\`，导致落盘路径失配（stub 找不到、快照漂移）。
+		// fs 侧 Windows 同样接受 `/`，无需回转分隔符。
+		const apiRootRaw = opts.apiRootOf ? opts.apiRootOf(module) : posix.join(opts.apiSrcDir, module);
+		const apiRoot = apiRootRaw.split(sep).join("/");
+		const filePath = posix.join(apiRoot, dir, "api.ts");
 		// 模板天然 lint-clean（F6）→ 直接哈希发射内容；注入缝仅供测试/特殊工程对齐
 		const body = await fix(emitStubBody(endpoints, opts.diag), filePath);
 		const fingerprint = `// ojm-api:stub ${endpoints.map(e => e.name).sort().join(",")} sha256:${hashContent(body)}\n`;

package/src/dev-secrets.ts

@@ -0,0 +1,315 @@
+/**
+ * 开发态本地密钥/凭据自动供给（方案 A'，计划 docs/plans/20261103-1700）。
+ *
+ * 问题：tracked `config.yaml` 是共享模板，但其引用的机器本地密钥
+ * （`config/secrets-*.pem` 密封对 + 全部 `ENC[...]` 解密链）不随 git 分发——多名开发者
+ * clone 后解不开 → `oj serve` 起不来，且失败信息被吞。
+ *
+ * 设计（经架构师 + 工程师评审修正）：
+ *   - dev 密钥与 tracked prod ENC **解耦**：tracked 里的 `ENC[...]` 仅作 prod 资产，dev 完全忽略。
+ *   - 本机密钥 + dev `jwt_secret` 只活在 gitignored 的 `config.local.yaml`，由本模块自动供给。
+ *   - `mergeConfigForDev` 把 tracked + local 深合并成 `.ojm-tmp-config.yaml`（gitignored，与
+ *     config.yaml 同目录）交给 `oj serve -c`，**绝不写回 tracked**。
+ *   - **非 jwt 的 `ENC[...]` 红线**：若 tracked 出现其他解不开的 `ENC[...]`（如 `wecom_enc_key`，
+ *     落库加密键），触发清晰报错要求提供真实私钥，**不**自动用 dev 随机密钥重封（防破坏已加密数据）。
+ *   - 模板 drift：合并产物每次 `ojm dev` 现合现用，tracked 非密改动自动生效；本机密钥持久于
+ *     `config.local.yaml` 重合并时始终套用，模板怎么改都不丢。
+ */
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { parse, stringify } from "yaml";
+import { resolveCertDir } from "./layout";
+import { resolveOjBin } from "./vendor";
+
+/** `config.local.yaml` 落点（与 config.yaml 同目录，gitignored、可手编辑） */
+export function resolveLocalConfigPath(configPath: string): string {
+	return path.join(path.dirname(configPath), "config.local.yaml");
+}
+
+/** 合并产物落点（与 config.yaml 同目录，`.ojm-tmp-*` 已被模板 .gitignore 忽略） */
+export function resolveMergedConfigPath(configPath: string): string {
+	return path.join(path.dirname(configPath), ".ojm-tmp-config.yaml");
+}
+
+/**
+ * 写回护栏（A-4）：合并产物绝不允许写回 tracked config、且必须位于 gitignore 内。
+ * 否则哪天密钥被误写回跟踪文件就泄密了。
+ */
+export function assertOutputNotTracked(trackedConfigPath: string, mergedConfigPath: string): void {
+	if (path.resolve(mergedConfigPath) === path.resolve(trackedConfigPath)) {
+		throw new Error(
+			`[ojm] 内部错误：合并产物路径与 tracked config 相同（${mergedConfigPath}），拒绝写回以免覆盖共享配置。`,
+		);
+	}
+	// `.ojm-tmp-` 前缀已被模板 .gitignore 覆盖（无斜杠 → 任意层级匹配），双重保险
+	if (!path.basename(mergedConfigPath).startsWith(".ojm-tmp-")) {
+		throw new Error(
+			`[ojm] 内部错误：合并产物 ${mergedConfigPath} 未被 .gitignore 的 .ojm-tmp-* 覆盖，拒绝写入以免密钥泄漏。`,
+		);
+	}
+}
+
+/** 用本机私钥试解 `ENC[...]`；能解开返回 true（即使不使用明文也只在内存里） */
+function canOpenWith(enc: string, keyPath: string, projectRoot: string): boolean {
+	const ojBin = resolveOjBin(projectRoot);
+	if (!fs.existsSync(ojBin) || !fs.existsSync(keyPath))
+		return false;
+	try {
+		execFileSync(ojBin, ["secret", "open", "-k", keyPath, enc], { stdio: "pipe" });
+		return true;
+	}
+	catch {
+		return false;
+	}
+}
+
+/**
+ * 本机密钥对是否可用：公私钥文件都在，且 seal→open 往返自洽（公钥能封、私钥能解）。
+ * 用于自愈（E-3 + A' 自动 rekey）：若上次的密钥文件残缺/被改坏（如半截 pem），
+ * 直接删了重 keygen，而不是拿着坏文件去 seal 失败。返回 false 时调用方应删除后重生成。
+ */
+function keyPairUsable(keysDir: string, projectRoot: string): boolean {
+	const privateKey = path.join(keysDir, "secrets-private.pem");
+	const publicKey = path.join(keysDir, "secrets-public.pem");
+	const ojBin = resolveOjBin(projectRoot);
+	if (!fs.existsSync(ojBin) || !fs.existsSync(privateKey) || !fs.existsSync(publicKey))
+		return false;
+	try {
+		const probe = execFileSync(ojBin, ["secret", "seal", "-k", publicKey], {
+			input: "__ojm_probe__",
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (!probe.startsWith("ENC["))
+			return false;
+		execFileSync(ojBin, ["secret", "open", "-k", privateKey, probe], { stdio: "pipe" });
+		return true;
+	}
+	catch {
+		return false;
+	}
+}
+
+/** 递归扫出配置树里所有 `ENC[...]` 字符串值，返回其 JSON pointer 路径集合 */
+function findEncValues(node: unknown, pointer = "", out: Map<string, string> = new Map()): Map<string, string> {
+	if (typeof node === "string") {
+		if (/^ENC\[/.test(node))
+			out.set(pointer, node);
+	}
+	else if (Array.isArray(node)) {
+		node.forEach((item, i) => findEncValues(item, `${pointer}/${i}`, out));
+	}
+	else if (node && typeof node === "object") {
+		for (const [k, v] of Object.entries(node))
+			findEncValues(v, pointer ? `${pointer}/${k}` : `/${k}`, out);
+	}
+	return out;
+}
+
+export interface DevSecretsDeps {
+	/** 注入 oj 二进制路径（测试） */
+	ojBin?: string
+	/** 注入随机 jwt_secret 生成器（测试可固定） */
+	randomHex?: (bytes: number) => string
+	/** 注入日志（测试） */
+	log?: (msg: string) => void
+}
+
+/**
+ * 供给本机开发密钥与 dev `jwt_secret`（A-1）：
+ *   - `config/secrets-{private,public}.pem` 缺失 → `oj secret keygen`（幂等：存在即跳过）。
+ *   - `config.local.yaml` 的 `auth.jwt_secret` 缺失/解不开 → 生成随机 32 字节 hex →
+ *     `oj secret seal` 成 `ENC[...]`，连同 `secrets:` 段写入 `config.local.yaml`。
+ * 不写 tracked config。返回最终 local config 对象。
+ */
+export function provisionDevSecrets(
+	projectRoot: string,
+	configPath: string,
+	deps: DevSecretsDeps = {},
+): Record<string, unknown> {
+	const log = deps.log ?? ((msg: string) => console.log(msg));
+	const ojBin = deps.ojBin ?? resolveOjBin(projectRoot);
+	const randomHex = deps.randomHex ?? ((bytes: number) => crypto.randomBytes(bytes).toString("hex"));
+	const keysDir = resolveCertDir(projectRoot);
+	const privateKey = path.join(keysDir, "secrets-private.pem");
+	const publicKey = path.join(keysDir, "secrets-public.pem");
+
+	// 1) 密封密钥对（幂等：存在且可用即跳过，避免每次 dev 重启换新密钥致已签发会话失效，E-3）。
+	//    若文件存在但残缺/被改坏（seal→open 往返不过）→ 视为不可用，删了重 keygen（A' 自动 rekey）。
+	let provisionedKey = false;
+	const keyUsable = fs.existsSync(privateKey) && fs.existsSync(publicKey) && keyPairUsable(keysDir, projectRoot);
+	if (!keyUsable) {
+		if (!fs.existsSync(ojBin))
+			throw new Error(`[ojm] 未找到 oj 二进制（${ojBin}），无法生成开发密钥。请先运行 ojm vendor。`);
+		for (const f of [privateKey, publicKey]) {
+			if (fs.existsSync(f))
+				fs.rmSync(f);
+		}
+		fs.mkdirSync(keysDir, { recursive: true });
+		execFileSync(ojBin, ["secret", "keygen", "--out-dir", keysDir], { stdio: "pipe" });
+		provisionedKey = true;
+	}
+
+	// 2) 读/建 config.local.yaml
+	const localPath = resolveLocalConfigPath(configPath);
+	let local: Record<string, unknown> = {};
+	if (fs.existsSync(localPath)) {
+		try {
+			local = (parse(fs.readFileSync(localPath, "utf-8")) as Record<string, unknown>) ?? {};
+		}
+		catch {
+			local = {};
+		}
+	}
+	const auth = (local.auth as Record<string, unknown> | undefined) ?? {};
+	const existingJwt = typeof auth.jwt_secret === "string" ? auth.jwt_secret : "";
+
+	// 3) dev jwt_secret：缺失或本机密钥解不开 → 重新生成并 seal（仅 jwt，可随意轮换）
+	const jwtOk = existingJwt.startsWith("ENC[") && canOpenWith(existingJwt, privateKey, projectRoot);
+	let jwtSecretEnc = existingJwt;
+	if (!jwtOk) {
+		if (!fs.existsSync(ojBin))
+			throw new Error(`[ojm] 未找到 oj 二进制（${ojBin}），无法密封 jwt_secret。请先运行 ojm vendor。`);
+		const plain = randomHex(32);
+		const sealed = execFileSync(ojBin, ["secret", "seal", "-k", publicKey], {
+			input: plain,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (!sealed.startsWith("ENC["))
+			throw new Error("[ojm] oj secret seal 未返回 ENC[...]，开发密钥供给失败。");
+		jwtSecretEnc = sealed;
+	}
+
+	// 4) 写回 config.local.yaml（仅 dev 覆盖 + dev 密钥；不碰 tracked）
+	const nextLocal: Record<string, unknown> = { ...local };
+	nextLocal.auth = { ...auth, jwt_secret: jwtSecretEnc };
+	nextLocal.secrets = {
+		private_key_path: "./config/secrets-private.pem",
+		public_key_path: "./config/secrets-public.pem",
+	};
+	fs.writeFileSync(localPath, stringify(nextLocal));
+
+	if (provisionedKey)
+		log("[ojm] 已生成本机开发密钥：config/secrets-{private,public}.pem");
+	if (!jwtOk)
+		log("[ojm] 已生成本机开发 jwt_secret（密封于 config.local.yaml，git 不跟踪）。");
+
+	return nextLocal;
+}
+
+/**
+ * 红线（A-2）：tracked 里出现**非 jwt** 的 `ENC[...]` 且本机密钥解不开 → 清晰报错，
+ * 要求提供真实私钥；绝不自动用 dev 随机密钥重封（会破坏已加密落库数据）。
+ */
+export function checkNoUnopenableSharedEnc(
+	projectRoot: string,
+	configPath: string,
+	_deps: DevSecretsDeps = {},
+): void {
+	const keysDir = resolveCertDir(projectRoot);
+	const privateKey = path.join(keysDir, "secrets-private.pem");
+	if (!fs.existsSync(configPath) || !fs.existsSync(privateKey))
+		return; // 无 tracked 或无本机密钥时不查（密钥缺失由 provision/red-line 别处兜底）
+	let doc: unknown;
+	try {
+		doc = parse(fs.readFileSync(configPath, "utf-8"));
+	}
+	catch {
+		return;
+	}
+	const encValues = findEncValues(doc);
+	for (const [pointer, enc] of encValues) {
+		if (pointer === "/auth/jwt_secret")
+			continue; // jwt 由 dev 自行供给，忽略 tracked 的 prod ENC
+		if (!canOpenWith(enc, privateKey, projectRoot)) {
+			throw new Error(
+				`[ojm] 配置中 ${pointer} 是 ENC[...] 密文，但本机没有能解开的私钥（config/secrets-private.pem）。\n`
+				+ "        该密文通常由团队用真实密钥密封（如落库加密键 wecom_enc_key），dev 不会用随机密钥重封——否则会破坏已加密数据。\n"
+				+ "        请向团队获取对应私钥放到 config/secrets-private.pem，或在 config.local.yaml 里覆盖该字段为可解密的明文/ENC 后重试。",
+			);
+		}
+	}
+}
+
+/** 纯函数深合并（local 覆盖 tracked；数组整体替换，不 concat） */
+export function deepMerge(tracked: Record<string, unknown>, local: Record<string, unknown>): Record<string, unknown> {
+	const out: Record<string, unknown> = Array.isArray(tracked) ? [...(tracked as unknown[])] as unknown as Record<string, unknown> : { ...tracked };
+	for (const [k, v] of Object.entries(local)) {
+		const base = (out as Record<string, unknown>)[k];
+		if (
+			v && typeof v === "object" && !Array.isArray(v)
+			&& base && typeof base === "object" && !Array.isArray(base)
+		) {
+			(out as Record<string, unknown>)[k] = deepMerge(base as Record<string, unknown>, v as Record<string, unknown>);
+		}
+		else {
+			(out as Record<string, unknown>)[k] = v;
+		}
+	}
+	return out;
+}
+
+export interface MergeDeps extends DevSecretsDeps {
+	/** 注入供给逻辑（测试可替换为无 oj 的桩） */
+	provision?: (projectRoot: string, configPath: string, d: DevSecretsDeps) => Record<string, unknown>
+	/** 注入红线检查（测试可替换为 no-op） */
+	redLine?: (projectRoot: string, configPath: string, d: DevSecretsDeps) => void
+	/** 注入合并落点（测试可改） */
+	mergedPath?: (configPath: string) => string
+}
+
+/**
+ * dev 配置就绪 + 合并：供给本机密钥、红线校验、深合并 tracked + local → `.ojm-tmp-config.yaml`。
+ * 返回合并产物路径，供 `oj serve -c` 使用。幂等（密钥/secret 存在即跳过）。
+ */
+export function mergeConfigForDev(
+	projectRoot: string,
+	configPath: string,
+	deps: MergeDeps = {},
+): string {
+	const provision = deps.provision ?? provisionDevSecrets;
+	const redLine = deps.redLine ?? checkNoUnopenableSharedEnc;
+	const mergedPath = deps.mergedPath ?? ((cp: string) => resolveMergedConfigPath(cp));
+
+	// 必须先 provision 再 red-line：首次 clone 本机密钥尚不存在，provision 会先生成
+	// 本地密钥对；之后 red-line 才能拿本机私钥去校验 tracked 里的非 jwt ENC[...]，
+	// 否则红线会在「无密钥可校验」时直接 early-return，把打不开的共享密文漏过去
+	// （正是方案 A' 要解决的「启动失败被吞」根因之一）。
+	provision(projectRoot, configPath, deps);
+	redLine(projectRoot, configPath, deps);
+
+	let trackedDoc: Record<string, unknown> = {};
+	if (fs.existsSync(configPath)) {
+		try {
+			trackedDoc = (parse(fs.readFileSync(configPath, "utf-8")) as Record<string, unknown>) ?? {};
+		}
+		catch (error) {
+			throw new Error(`[ojm] ${configPath} 解析失败（不是合法 YAML）：${(error as Error).message}`);
+		}
+	}
+	// provision 已把本机密钥/jwt 写入 config.local.yaml；此处读回参与合并
+	const localDoc = readLocal(projectRoot, configPath);
+	const merged = deepMerge(trackedDoc, localDoc);
+
+	const outPath = mergedPath(configPath);
+	assertOutputNotTracked(configPath, outPath);
+	fs.writeFileSync(outPath, stringify(merged));
+	return outPath;
+}
+
+/** 读 config.local.yaml（不存在/解析失败 → 空对象） */
+function readLocal(projectRoot: string, configPath: string): Record<string, unknown> {
+	const localPath = resolveLocalConfigPath(configPath);
+	if (!fs.existsSync(localPath))
+		return {};
+	try {
+		return (parse(fs.readFileSync(localPath, "utf-8")) as Record<string, unknown>) ?? {};
+	}
+	catch {
+		return {};
+	}
+}

package/src/dev.ts

@@ -33,13 +33,15 @@ import { buildModules } from "./build";
 import { loadContractMocks, resolveMock } from "./contract/mock";
 import { loadProjectMocks, mockStatusCode } from "./dev-mock";
 import { createReloadHub, proxyApi, proxyWsUpgrade, sseScript } from "./dev-proxy";
+import { mergeConfigForDev } from "./dev-secrets";
 import { loadHtmlTransform } from "./html-transform";
 import { resolveConfigPath, resolveLayout } from "./layout";
 import { resolveCdnLayout } from "./market/cdn-layout";
 import { startOj } from "./oj";
 import { requireModuleRootCapability } from "./oj-caps";
 import { ensureDevCert } from "./oj-cert";
-import { readOjApiPrefix } from "./oj-config";
+import { readOjApiPrefix, readOjPort, readOjServerField } from "./oj-config";
+import { isPortOccupied } from "./port-check";
 import { createStaticHandler, decodeReqPath, listenOnFreePort } from "./static-handler";
 import { resolveShellDist } from "./versions";
 
@@ -107,10 +109,31 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 			? ["--module-root", layout.moduleRoot]
 			: resolve(projectRoot, "api/src");
 		apiBase = readOjApiPrefix(configPath);
-		await ensureDevCert(configPath);
+		// 后端端口预检：被占用（通常上次 ojm dev 未正常退出、遗留 oj 孤儿进程仍在跑）
+		// 直接禁止启动并给清晰指引，避免 oj 健康检查超时后才以晦涩信息失败。
+		const backendPort = readOjPort(configPath);
+		const backendHost = readOjServerField(configPath, "host") || "127.0.0.1";
+		if (await isPortOccupied(backendPort, backendHost)) {
+			throw new Error(
+				`[ojm] 后端 API 端口 ${backendPort} 已被占用，已禁止启动 ojm dev。\n`
+				+ "        原因通常是：上一次 ojm dev 未正常退出，遗留的 oj 进程仍在占用该端口。\n"
+				+ "        （oj 后端默认端口 9778；若 config.yaml 的 server.port 改过则为对应值。）\n\n"
+				+ "        请先结束占用该端口的进程，再重新运行 ojm dev：\n"
+				+ `          macOS / Linux： lsof -ti tcp:${backendPort} | xargs kill -9\n`
+				+ `          Windows：        netstat -ano | findstr :${backendPort}  找到 PID 后  taskkill /PID <PID> /F\n\n`
+				+ "        已停止启动，未留下新的 oj 孤儿进程。",
+			);
+		}
+		// 开发态本地密钥/凭据自动供给（方案 A'）：供给本机 secrets 密钥 + dev jwt_secret，
+		// 深合并 tracked config.yaml 与 gitignored config.local.yaml → .ojm-tmp-config.yaml。
+		// tracked 里的 ENC[...] 仅作 prod 资产，dev 完全忽略；非 jwt 的 ENC 解不开则清晰报错
+		// （红线，防用 dev 随机密钥重封破坏已加密数据）。合并产物与 config.yaml 同目录，oj
+		// 相对路径解析不变。
+		const effectiveConfigPath = mergeConfigForDev(projectRoot, configPath);
+		await ensureDevCert(effectiveConfigPath);
 		const fallbackStarter = (cfg: string, b: string, apiSrc: string | string[]) => startOj(cfg, b, apiSrc);
 		const starter: NonNullable<DevOptions["ojStarter"]> = opts.ojStarter ?? fallbackStarter;
-		oj = starter(configPath, apiBase, apiSource);
+		oj = starter(effectiveConfigPath, apiBase, apiSource);
 		try {
 			await oj.ready; // 失败人话报错（stderr 尾部），fail-fast
 		}

package/src/init.ts

@@ -154,8 +154,10 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	// 3) oj 二进制：从最新 release 联网下载（sha256 校验 → tar 解包 → chmod），
 	//    无内置兜底；bin/oj 已在则幂等跳过，缺 .oj-version 标记视为未装
 	const binDir = path.join(destDir, "bin");
-	if (fs.existsSync(path.join(binDir, "oj"))) {
-		report.skipped.push("bin/oj");
+	// Windows 上二进制名是 oj.exe，不能硬编码 `oj`（预置 bin/oj.exe 会被误判为未装而触发联网下载）。
+	const ojBin = resolveOjBin(destDir);
+	if (fs.existsSync(ojBin)) {
+		report.skipped.push(`bin/${path.basename(ojBin)}`);
 	}
 	else {
 		const installer = opts.ojInstaller ?? ((dir: string) => vendorCommand(path.dirname(dir), { force: false }));
@@ -328,7 +330,10 @@ function copyTemplates(
 	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
 		const src = path.join(srcDir, entry.name);
 		const dest = path.join(destDir, entry.name);
-		const srcRel = path.relative(rootDir, src);
+		// 跨平台：path.relative 在 Windows 返回反斜杠，而 include 集合与
+		// hasIncludedDescendant 的前缀对比都用正斜杠，必须归一后再比，
+		// 否则嵌套目录（src/app/api/<mod> 等）被误判为「未收录」整棵 skip。
+		const srcRel = path.relative(rootDir, src).split(path.sep).join("/");
 		const listed = include.has(srcRel);
 		if (!underIncluded && !listed && !hasIncludedDescendant(include, srcRel))
 			continue;
@@ -390,7 +395,11 @@ function readInitInclude(templatesDir: string): Set<string> {
 	const doc = yaml.parse(fs.readFileSync(yamlPath, "utf-8")) as { include?: string[] } | null;
 	const out = new Set<string>();
 	for (const raw of doc?.include ?? []) {
-		const p = path.normalize(raw).replace(/^(\.\/)+/, "");
+		// 跨平台：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}（拼写错误或模板缺文件？）`);
@@ -496,6 +505,8 @@ logs/
 # 现场签发的开发证书与凭据私钥（ojm dev 缺证时自动签发，见 oj-cert.ts）；私钥绝不入仓
 config/*.pem
 config/cert.jws
+# 开发态本地覆盖层（方案 A'）：dev 自动供给的本机密钥 + dev jwt_secret；git 不跟踪
+config.local.yaml
 # 构建产物（ojm build：站点 dist/web + 后端 release dist/api）
 dist/
 `;

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

@@ -15,6 +15,21 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { parse, stringify } from "yaml";
 import { buildBundle } from "../../bundle";
 
+// GNU tar 把 Windows 盘符绝对路径里的 `C:` 当「远程主机:路径」（Cannot connect to C: resolve failed），
+// 需 --force-local；但 Windows 自带 bsdtar 不支持该选项（报 Option --force-local is not supported），
+// 且 bsdtar 本就不做远程解析。按实际解析到的 tar 版本决定：仅 win32 + GNU tar 才加。POSIX 恒不加。
+const TAR_LOCAL: string[] = (() => {
+	if (process.platform !== "win32")
+		return [];
+	try {
+		const version = execFileSync("tar", ["--version"], { encoding: "utf-8", shell: true });
+		return /GNU tar/i.test(version) ? ["--force-local"] : [];
+	}
+	catch {
+		return [];
+	}
+})();
+
 const FIXTURE_VALID = join(dirname(fileURLToPath(import.meta.url)), "fixtures/fixture-valid");
 
 let project: string;
@@ -326,8 +341,10 @@ function writeManifest(m: unknown): void {
 }
 
 function tarList(tgz: string): string[] {
-	return execFileSync("tar", ["-tvzf", tgz], { encoding: "utf8" })
+	return execFileSync("tar", [...TAR_LOCAL, "-tvzf", tgz], { encoding: "utf8", shell: true })
 		// 铁律②（P1-6）：tar 输出恒带尾随换行，trim 后再 split
+		// bsdtar on Windows emits CRLF; strip \r before splitting.
+		.replace(/\r/g, "")
 		.trim()
 		.split("\n")
 		.map(line => line.split(" ").pop()!);

package/src/lifecycle/__tests__/deterministic-tar.test.ts

@@ -10,6 +10,21 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { createDeterministicTgz } from "../../deterministic-tar";
 
+// GNU tar 把 Windows 盘符绝对路径里的 `C:` 当「远程主机:路径」（Cannot connect to C: resolve failed），
+// 需 --force-local；但 Windows 自带 bsdtar 不支持该选项（报 Option --force-local is not supported），
+// 且 bsdtar 本就不做远程解析。按实际解析到的 tar 版本决定：仅 win32 + GNU tar 才加。POSIX 恒不加。
+const TAR_LOCAL: string[] = (() => {
+	if (process.platform !== "win32")
+		return [];
+	try {
+		const version = execFileSync("tar", ["--version"], { encoding: "utf-8", shell: true });
+		return /GNU tar/i.test(version) ? ["--force-local"] : [];
+	}
+	catch {
+		return [];
+	}
+})();
+
 let dir: string;
 let outDir: string;
 
@@ -97,7 +112,7 @@ describe("createDeterministicTgz · 产物可被系统 tar 消费（extract 段
 		const { names } = await packAndList("a.tgz");
 		const extractDir = join(outDir, "unpacked");
 		mkdirSync(extractDir);
-		execFileSync("tar", ["-xzf", join(outDir, "a.tgz"), "-C", extractDir]);
+		execFileSync("tar", [...TAR_LOCAL, "-xzf", join(outDir, "a.tgz"), "-C", extractDir], { shell: true });
 		const root = join(extractDir, names[0]!.slice(0, -1));
 		expect(readFileSync(join(root, "b-dir/zh.txt"), "utf8")).toBe("中文内容\n");
 		expect(existsSync(join(root, "b-dir/empty-dir"))).toBe(true);
@@ -130,8 +145,10 @@ describe("createDeterministicTgz · 打包自检（C2-30 构建列）", () => {
 // ── 助手 ──
 
 function tarList(tgz: string): string[] {
-	return execFileSync("tar", ["-tvzf", tgz], { encoding: "utf8" })
+	return execFileSync("tar", [...TAR_LOCAL, "-tvzf", tgz], { encoding: "utf8", shell: true })
 		// 铁律②（P1-6）：tar 输出恒带尾随换行，trim 后再 split
+		// bsdtar on Windows emits CRLF; strip \r before splitting.
+		.replace(/\r/g, "")
 		.trim()
 		.split("\n");
 }

package/src/market/bootstrap.ts

@@ -118,9 +118,12 @@ export async function bootstrapIsolatedSite(opts: BootstrapOptions = {}): Promis
 	}
 	writeFileSync(configPath, readFileSync(path.join(templateDir, "config.yaml"), "utf-8"), "utf-8");
 
-	// 2) oj 二进制与插件（startOj 按 <root>/bin/oj 解析；plugins 让 auth 插件可用）
+	// 2) oj 二进制与插件（startOj 按 <root>/bin/oj[.exe] 解析；plugins 让 auth 插件可用）。
+	// 跨平台：ojBin 在 Windows 为 bin/oj.exe、Linux/macOS 为 bin/oj——拷贝目标文件名必须
+	// 与源一致（path.basename），否则 Windows 下落盘成无扩展名的 `oj`，后续 resolveOjBin
+	// 按 bin/oj.exe 解析会找不到、后端构建检查也报「缺少 bin/oj.exe」（trial/walkthrough 隔离站点挂死）。
 	mkdirSync(path.join(root, "bin"), { recursive: true });
-	cpSync(ojBin, path.join(root, "bin", "oj"), { recursive: true });
+	cpSync(ojBin, path.join(root, "bin", path.basename(ojBin)), { recursive: true });
 	const versionMarker = path.join(projectRoot, "bin", ".oj-version");
 	if (existsSync(versionMarker)) {
 		cpSync(versionMarker, path.join(root, "bin", ".oj-version"));

package/src/new.ts

@@ -26,6 +26,26 @@ import { readBuiltinModules } from "./builtin";
 import { tryResolveLayout } from "./layout";
 import { assertValidSolutionName, RESERVED_NAMES } from "./manifest-contract";
 
+/**
+ * 内建聚合模块 app 的 web 路由根（src/app/web 下各 routes.ts 的顶层 path）：
+ * 这些路径由框架内置页面独占。ojm new 生成的默认路由为 /name，
+ * 若 name 命中其中之一，会与内置页面撞 route id，导致运行时白屏。
+ * 这里在脚手架阶段即拒绝，避免生成即炸。
+ *
+ * 与 readBuiltinModules（内建模块名）互补：内建模块名只覆盖 home /
+ * personal-center / system，而 login / change-password / notification-center 是
+ * app 聚合内的路由根，并非独立内建模块名，故单列此表。
+ * app 路由根增删时此处须同步。
+ */
+const BUILTIN_ROUTE_ROOTS = new Set([
+	"home",
+	"login",
+	"change-password",
+	"notification-center",
+	"personal-center",
+	"system",
+]);
+
 export interface NewSolutionOptions {
 	/** 示例路由布局（默认 container；none = 无外壳裸页面） */
 	layout?: "container" | "none"
@@ -76,6 +96,13 @@ export function createSolution(projectRoot: string, name: string, opts: NewSolut
 			+ "想改造自带模块：`ojm new <新名>` 生成骨架后把代码复制过去（自带身份按目录名判定，复制即脱离）。",
 		);
 	}
+	if (BUILTIN_ROUTE_ROOTS.has(name)) {
+		throw new Error(
+			`[ojm] 「${name}」与框架内置页面路由根（${[...BUILTIN_ROUTE_ROOTS].join("/")}）撞车——`
+			+ `ojm new 生成的默认路由 /${name} 会与内置 ${name} 页面冲突（route id 碰撞白屏）。`
+			+ "请换一个不与内置页面撞名的方案名。",
+		);
+	}
 	const dir = path.join(projectRoot, "src", name);
 	if (fs.existsSync(dir))
 		throw new Error(`[ojm] src/${name}/ 已存在。换个名字，或删掉该目录后重试。`);

package/src/oj.ts

@@ -9,7 +9,10 @@
  * 由 `ojm vendor` 的最低版本门禁挡住（见 src/vendor.ts 的 MIN_OJ_VERSION）。
  *
  * 健康判据：GET {base}/health 状态码 <400（oj 内置匿名健康端点；2xx/3xx 均视为就绪）。
- * 秒退：ready 拒绝，错误信息带 stderr 尾部（证书缺失等常见错因可直接读出）。
+ * 秒退：ready 拒绝，错误信息优先带 stderr 尾部（证书缺失等常见错因可直接读出）；
+ * 若 oj 把 FATAL 落盘到 logs/ 而未进 stderr（手册说 `--console-log` 会镜像到终端，但
+ * 部分环境仍可能只落盘），再读 `<configDir>/logs/server-*.log` 最新文件兜底，绝不输出
+ * 无意义的 "(无输出)"（方案 A' 失败提示不吞，评审 E-1）。
  */
 
 import type { Buffer } from "node:buffer";
@@ -21,6 +24,43 @@ import process from "node:process";
 import { readOjPluginsDir, readOjPort } from "./oj-config";
 import { resolveOjBin } from "./vendor";
 
+/**
+ * logs/ 兜底（评审 E-1）：oj 启动期 FATAL 有时只落盘不进 stderr。
+ * 给定 oj 的日志目录（通常 `<configDir>/logs`），挑最新的 `server-*.log`，
+ * 抽出 ERROR/FATAL/panic 等关键行（没有则取末 30 行），供失败信息兜底展示。
+ * 找不到日志目录 / 文件即返回空串（调用方维持 "(无输出)"）。
+ */
+function readLatestLogError(logsDir: string): string {
+	if (!logsDir || !fs.existsSync(logsDir))
+		return "";
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(logsDir, { withFileTypes: true });
+	}
+	catch {
+		return "";
+	}
+	const logs = entries
+		.filter(e => e.isFile() && /^server-.*\.log$/.test(e.name))
+		.map((e) => {
+			try {
+				return { name: e.name, mtime: fs.statSync(path.join(logsDir, e.name)).mtimeMs };
+			}
+			catch {
+				return null;
+			}
+		})
+		.filter((x): x is { name: string, mtime: number } => x !== null)
+		.sort((a, b) => b.mtime - a.mtime);
+	if (logs.length === 0)
+		return "";
+	const text = fs.readFileSync(path.join(logsDir, logs[0].name), "utf-8");
+	const lines = text.split(/\r?\n/);
+	const keyLines = lines.filter(l => /error|fatal|panic|denied|invalid|unable|cannot|fail|exception|refused/i.test(l));
+	const picked = keyLines.length > 0 ? keyLines.slice(-30) : lines.slice(-30);
+	return picked.join("\n").trim();
+}
+
 export interface OjProcess {
 	port: number
 	/** 健康就绪（或失败拒绝：秒退带 stderr 尾部 / 超时） */
@@ -63,8 +103,12 @@ export function startOj(
 	apiSource: string | string[],
 	poll: StartOjPoll = {},
 	extraArgs: string[] = [],
+	logsDir?: string,
 ): OjProcess {
 	const port = readOjPort(configPath);
+	// logs/ 兜底目录（评审 E-1）：oj FATAL 有时只落盘不进 stderr。缺省按 config 同级
+	// 的 logs/（与 oj 默认 logs_dir 一致）；调用方可显式覆盖（preview 派生 config 等）。
+	const resolvedLogsDir = logsDir ?? path.join(path.dirname(configPath), "logs");
 	// 约定：vendor 二进制在 <project>/bin/oj。工程根不能按「config 往上两级」算：
 	// module-root 布局的 config 在仓库根（<project>/config.yaml），往上两级会越过工程，
 	// 落到父目录找 bin/oj。改为「向上找最近的含 bin/ 的目录」，两种布局都成立。
@@ -84,10 +128,27 @@ export function startOj(
 	// 注入条件：用户未在 toml 显式声明 plugins_dir（env 优先级更高，注入会覆盖），
 	// 且 bin/plugins 确实存在（缺失时保持 oj 原行为，不生次生错误）。
 	const pluginsDir = path.join(projectRoot, "bin", "plugins");
-	const env: NodeJS.ProcessEnv | undefined
-		= !readOjPluginsDir(configPath) && fs.existsSync(pluginsDir)
-			? { ...process.env, OJ_PLUGINS_DIR: pluginsDir }
-			: undefined;
+	// win32：oj 是原生 Windows 二进制，从 Git Bash / MSYS 终端启动时继承 MSYS 风格 PATH
+	// （如 `/c/WINDOWS/system32`），Windows CreateProcess 无法按该形式解析可执行文件 → 内部
+	// `tar` 等系统工具 "command not found in PATH"（市场安装解包即挂）。追加原生 Windows 系统
+	// 目录（tar.exe 所在）；cmd/PowerShell 用户 PATH 本就含这些，无副作用。
+	// win32: Git Bash/MSYS 把 PATH 写成 /usr/bin 这类 Unix 风格条目，oj 内部按 Windows 规则检索命令
+	// 时无法据此定位 tar.exe（系统 tar 在 C:\Windows\System32），市场安装解包会报 tar not found in PATH。
+	// 剔除无盘符的 Unix 风格条目、仅保留 Windows 绝对路径，并兜底补上系统目录与 Git bin。
+	// cmd/PowerShell 用户 PATH 本就全是 Windows 形态，过滤无副作用。
+	const env: NodeJS.ProcessEnv | undefined = (() => {
+		let base: NodeJS.ProcessEnv = process.env;
+		if (process.platform === "win32") {
+			const cur = process.env.PATH ?? process.env.Path ?? "";
+			const winEntries = cur.split(";").filter(e => /^[A-Z]:[\\/]/i.test(e.trim()));
+			const sysDirs = ["C:\\Windows\\System32", "C:\\Windows", "C:\\Program Files\\Git\\usr\\bin"];
+			const missing = sysDirs.filter(d => !winEntries.some(e => e.toLowerCase().startsWith(d.toLowerCase())));
+			base = { ...process.env, PATH: [...winEntries, ...missing].join(";") };
+		}
+		return !readOjPluginsDir(configPath) && fs.existsSync(pluginsDir)
+			? { ...base, OJ_PLUGINS_DIR: pluginsDir }
+			: base;
+	})();
 
 	let stderrTail = "";
 	// --console-log：oj 新版终端默认静默（console_log 缺省 false，只落 logs/），
@@ -109,6 +170,13 @@ export function startOj(
 
 	let settled = false;
 	let pollTimer: NodeJS.Timeout | undefined;
+	// oj 端口被占用时 stderr 通常会带这些签名（Rust 绑定失败 / 系统错误码）；命中即
+	// 补一条「先杀占用进程」的可操作提示，避免只甩晦涩的 oj 原生报错。
+	const portInUseHint = (text: string): string => {
+		if (/Address already in use|EADDRINUSE|os error 98|os error 10048|地址已被使用|端口已被占用/i.test(text))
+			return "\n可能原因：后端端口被占用（通常是上次 ojm dev 未正常退出留下的 oj 孤儿进程）。请先结束占用进程再重试。";
+		return "";
+	};
 	const ready = new Promise<void>((resolve, reject) => {
 		const intervalMs = poll.intervalMs ?? 500;
 		const timeoutMs = poll.timeoutMs ?? 10_000;
@@ -129,9 +197,12 @@ export function startOj(
 		}, intervalMs);
 		pollTimer.unref();
 		child.once("exit", (code) => {
+			const hint = portInUseHint(stderrTail);
+			// A' 失败提示不吞：stderr 空时读 logs/ 最新 server-*.log 兜底（评审 E-1）
+			const tail = stderrTail.trim() || readLatestLogError(resolvedLogsDir);
 			finish(new Error(
-				`[ojm] oj 进程异常退出（code ${code}）。\n`
-				+ `stderr 尾部：\n${stderrTail.trim() || "（无输出）"}`,
+				`[ojm] oj 进程异常退出（code ${code}）。${hint}\n`
+				+ `stderr 尾部：\n${tail || "（无输出）"}`,
 			));
 		});
 		// spawn 本身失败（如 ENOENT）只发 error 不发 exit，必须单独兜住
@@ -141,9 +212,11 @@ export function startOj(
 			finish(new Error(`[ojm] 无法启动 oj（${binPath}）：${err.message}${hint}`));
 		});
 		const timeout = setTimeout(() => {
+			const hint = portInUseHint(stderrTail);
+			const tail = stderrTail.trim() || readLatestLogError(resolvedLogsDir);
 			finish(new Error(
-				`[ojm] oj 健康检查超时（${Math.round(timeoutMs / 1000)}s）：${healthUrl} 一直不可达。\n`
-				+ `stderr 尾部：\n${stderrTail.trim() || "（无输出）"}`,
+				`[ojm] oj 健康检查超时（${Math.round(timeoutMs / 1000)}s）：${healthUrl} 一直不可达。${hint}\n`
+				+ `stderr 尾部：\n${tail || "（无输出）"}`,
 			));
 		}, timeoutMs);
 		timeout.unref();

package/src/port-check.ts

@@ -0,0 +1,38 @@
+import net from "node:net";
+
+/**
+ * 探测某端口是否已被占用（即有进程在监听）。
+ *
+ * 用于 `ojm dev` 启动前的后端端口预检：若 oj 的目标端口已被（通常是上次未正常
+ * 退出、遗留的）oj 孤儿进程占据，提前给出清晰提示并禁止启动，避免 oj 健康检查
+ * 超时后才以晦涩信息失败。
+ *
+ * 探测方式：本进程尝试在该端口上 `listen`——
+ *   - `EADDRINUSE` → 端口已被占用，返回 true；
+ *   - 绑定成功 → 端口空闲，立即释放并返回 false；
+ *   - 其它错误（如权限）→ 无法确认占用，保守返回 false（宁可放行，不让带病禁止）。
+ *
+ * 不用「TCP connect 探活」：某些环境下连向空闲端口的连接会被静默丢弃（既不 RST 也
+ * 不 SYN-ACK），导致探测挂起并以「保守判占用」告终，从而误杀每一次 ojm dev 启动。
+ * bind 探测同步返回，绝不挂起。
+ */
+export function isPortOccupied(port: number, host = "127.0.0.1"): Promise<boolean> {
+	return new Promise((resolve) => {
+		const probe = net.createServer();
+		let settled = false;
+		const done = (occupied: boolean) => {
+			if (settled)
+				return;
+			settled = true;
+			resolve(occupied);
+		};
+		probe.once("error", (err: NodeJS.ErrnoException) => {
+			// EADDRINUSE = 端口确被占用；其余（EACCES 等）无法确认，保守放行
+			done(err.code === "EADDRINUSE");
+		});
+		probe.listen(port, host, () => {
+			// 能绑定说明空闲：立即释放后返回 false
+			probe.close(() => done(false));
+		});
+	});
+}

package/src/rekey.ts

@@ -0,0 +1,51 @@
+import type { DevSecretsDeps } from "./dev-secrets";
+/**
+ * `ojm rekey` —— 重新生成开发态本机密钥并重封 dev jwt_secret（方案 A' 第 8 点）。
+ *
+ * 只动 gitignored 的 `config/secrets-*.pem` 与 `config.local.yaml` 里的 dev 覆盖，
+ * **绝不**触碰 tracked `config.yaml`（prod 路径零改动，A-3 不变量）。
+ *
+ * 典型场景：
+ *   - 本机 dev 密钥对被人误删/改坏，`ojm dev` 因 jws/ENC 解不开起不来 → `ojm rekey` 重生。
+ *   - 想让本机 jwt_secret 轮换（dev 可随意轮换，无外部密文依赖）。
+ * 之后 `ojm dev` 会用新密钥自动重合并重起；无需手改任何 tracked 文件。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { provisionDevSecrets, resolveLocalConfigPath } from "./dev-secrets";
+import { resolveCertDir, resolveConfigPath } from "./layout";
+
+export interface RekeyResult {
+	/** 重生后的 `config.local.yaml` 路径 */
+	localPath: string
+	/** 是否真正重新生成了密钥对（已存在且可用则 rekey 只重封 jwt，不重生成） */
+	regeneratedKey: boolean
+}
+
+export interface RekeyDeps extends DevSecretsDeps {}
+
+/**
+ * 重新供给开发态本机密钥：删除旧 `secrets-*.pem` → `provisionDevSecrets` 因缺失而重生成，
+ * 并跟着重封 jwt_secret 写入 `config.local.yaml`。返回落点信息。
+ */
+export function rekeyCommand(projectRoot: string, deps: RekeyDeps = {}): RekeyResult {
+	const configPath = resolveConfigPath(projectRoot);
+	if (!fs.existsSync(configPath))
+		throw new Error(`[ojm] 未找到 config.yaml（${configPath}），无法 rekey。请确认当前目录是 ojm 工程。`);
+
+	const keysDir = resolveCertDir(projectRoot);
+	const privateKey = path.join(keysDir, "secrets-private.pem");
+	const publicKey = path.join(keysDir, "secrets-public.pem");
+	const hadKey = fs.existsSync(privateKey) || fs.existsSync(publicKey);
+	// 强制重生：先删旧的，provisionDevSecrets 见缺失即 keygen（A' 自动 rekey 的同一入口）
+	for (const f of [privateKey, publicKey]) {
+		if (fs.existsSync(f))
+			fs.rmSync(f);
+	}
+
+	provisionDevSecrets(projectRoot, configPath, deps);
+	return {
+		localPath: resolveLocalConfigPath(configPath),
+		regeneratedKey: hadKey,
+	};
+}

package/src/static-handler.ts

@@ -15,7 +15,7 @@
 
 import type http from "node:http";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { extname, normalize, resolve } from "node:path";
+import { extname, normalize, resolve, sep } from "node:path";
 
 const MIME: Record<string, string> = {
 	".html": "text/html; charset=utf-8",
@@ -185,7 +185,12 @@ export function createStaticHandler(opts: StaticHandlerOptions): (req: http.Inco
 			res.end("400 Bad Request: malformed URL encoding");
 			return;
 		}
-		const rel = normalize(urlPath).replace(/^(\.\.[/\\])+/, "");
+		// URL 路径是「类 Unix 斜杠语义」，不能用 path.normalize 的 OS 方言：
+		// 在 Windows 上 path.normalize("/assets/x.js") 会变成 "\\assets\\x.js"，
+		// 既让下方 /__ojm_reload.js 等精确匹配全部落空（404），又让 resolveFile
+		// 把前导反斜杠当成「盘符根」解析到 C:\\assets\\...（错位 404）。统一转回
+		// 正斜杠——POSIX 上 path.sep 即 "/" 此换行为 no-op，跨平台安全。
+		const rel = normalize(urlPath).split(sep).join("/").replace(/^(\.\.[/\\])+/, "");
 
 		if (opts.reload) {
 			if (rel === "/__ojm_reload") {

package/src/usage.ts

@@ -111,8 +111,18 @@ export const HELP_GROUPS: HelpGroup[] = [
 				zh: "启动开发服务器（/api 反代 oj + 模块重建 + SSE 刷新）",
 				en: "Start dev server (/api proxy to oj + module rebuild + SSE refresh)",
 				detail: {
-					zh: "ojm dev [port]\n  开发模式快捷键（仅 TTY 终端，类 Vite）：\n    r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开\n    q  退出（后端 oj 一并终止）\n  port 缺省 5174（oj 后端端口以 config.yaml 的 server.port 为准）",
-					en: "ojm dev [port]\n  Dev-mode shortcuts (TTY only, Vite-like):\n    r  force rebuild + hot reload    h  show help    c  clear screen    o  open browser\n    q  quit (terminates the oj backend as well)\n  port defaults to 5174 (the oj backend port comes from config.yaml server.port)",
+					zh: "ojm dev [port]\n  开发模式快捷键（仅 TTY 终端，类 Vite）：\n    r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开\n    q  退出（后端 oj 一并终止）\n  port 缺省 5174（oj 后端端口以 config.yaml 的 server.port 为准）\n  首次 clone 无本机密钥时自动供给 dev 密钥 + 随机 jwt_secret（方案 A'），并合并 config.local.yaml 后启动",
+					en: "ojm dev [port]\n  Dev-mode shortcuts (TTY only, Vite-like):\n    r  force rebuild + hot reload    h  show help    c  clear screen    o  open browser\n    q  quit (terminates the oj backend as well)\n  port defaults to 5174 (the oj backend port comes from config.yaml server.port)\n  On first clone without local keys, dev auto-provisions a dev keypair + random jwt_secret (plan A') and starts after merging config.local.yaml",
+				},
+			},
+			{
+				key: "rekey",
+				name: "rekey",
+				zh: "重生开发态本机密钥并重封 dev jwt_secret（不动 tracked config）",
+				en: "Regenerate the dev-local keypair and re-seal the dev jwt_secret (tracked config untouched)",
+				detail: {
+					zh: "ojm rekey\n  删除 config/secrets-*.pem → 重新 keygen → 重封 dev jwt_secret 写入 config.local.yaml\n  仅影响 gitignored 的本地文件，tracked config.yaml 零改动（方案 A' 第 8 点）\n  用于本机 dev 密钥对误删/损坏、或想轮换 dev jwt_secret；之后 ojm dev 自动用新密钥重合并重起",
+					en: "ojm rekey\n  Deletes config/secrets-*.pem → keygen again → re-seal the dev jwt_secret into config.local.yaml\n  Only affects gitignored local files; the tracked config.yaml is untouched (plan A' point 8)\n  Use when the local dev keypair was deleted/corrupted, or to rotate the dev jwt_secret; ojm dev then re-merges and restarts with the new key",
 				},
 			},
 			{

package/src/vendor.ts

@@ -103,6 +103,20 @@ export function syncOjDevkit(projectRoot: string, binDir: string, log: (msg: str
 	return { ok: true, files };
 }
 
+/**
+ * bin/ 下实际存在的 oj 文件名：Windows 原生二进制是 oj.exe，但也兼容无扩展名的
+ * `oj`（手动放置 / 脚本桩）。仅 win32 做回落，POSIX 恒为 `oj` 不受影响。
+ */
+function ojBinIn(binDir: string, platform: NodeJS.Platform = process.platform): string {
+	const primary = path.join(binDir, ojBinName(platform));
+	if (platform === "win32" && !fs.existsSync(primary)) {
+		const bare = path.join(binDir, "oj");
+		if (fs.existsSync(bare))
+			return bare;
+	}
+	return primary;
+}
+
 /**
  * 工程内 oj 二进制路径的**唯一口径**（<projectRoot>/bin/oj）。
  *
@@ -111,12 +125,12 @@ export function syncOjDevkit(projectRoot: string, binDir: string, log: (msg: str
  * 整套同版本，路径算错会拿到半新半旧的组合。统一到这里。
  */
 export function resolveOjBin(projectRoot: string): string {
-	return path.join(projectRoot, "bin", ojBinName());
+	return ojBinIn(path.join(projectRoot, "bin"));
 }
 
 /** 本地版本只认 .oj-version 标记；bin/oj 缺失或标记缺失都视为未安装（N6，格式 vX.Y.Z） */
 export function readLocalVersion(binDir: string, platform: NodeJS.Platform = process.platform): string | null {
-	if (!fs.existsSync(path.join(binDir, ojBinName(platform))))
+	if (!fs.existsSync(ojBinIn(binDir, platform)))
 		return null;
 	const marker = path.join(binDir, ".oj-version");
 	if (!fs.existsSync(marker))
@@ -180,10 +194,23 @@ function reportProbeFailure(log: (msg: string) => void, detail: string): void {
 /** npm 执行器（测试注入）；返回 stdout */
 export type NpmRun = (args: string[], cwd: string) => string;
 
-const NPM_CMD = process.platform === "win32" ? "npm.cmd" : "npm";
+/**
+ * npm 执行规格：按平台决定 execFileSync 的命令行。
+ *
+ * Windows 上 npm 实为 `npm.cmd` 批处理文件——`CreateProcess` 无法直接执行 `.cmd`
+ * （否则 `spawnSync npm.cmd EINVAL`，连 `npm view` 这步都过不去），必须由 `cmd.exe /c`
+ * 包裹运行。其余平台直接以 `npm` 执行即可。
+ */
+export function npmExecSpec(platform: string, args: string[]): { cmd: string, execArgs: string[] } {
+	if (platform === "win32")
+		return { cmd: "cmd.exe", execArgs: ["/c", "npm.cmd", ...args] };
+	return { cmd: "npm", execArgs: args };
+}
 
-const defaultRun: NpmRun = (args, cwd) =>
-	execFileSync(NPM_CMD, args, { cwd, encoding: "utf-8", maxBuffer: 16 * 1024 * 1024 });
+export const defaultRun: NpmRun = (args, cwd) => {
+	const { cmd, execArgs } = npmExecSpec(process.platform, args);
+	return execFileSync(cmd, execArgs, { cwd, encoding: "utf-8", maxBuffer: 16 * 1024 * 1024 });
+};
 
 export interface VendorDeps {
 	run?: NpmRun

package/vendor/host-versions.json

@@ -8,9 +8,9 @@
 		"react-router": "7.18.2",
 		"react-router/dom": "7.18.2",
 		"@tanstack/react-query": "5.102.8",
-		"@oj-module/runtime": "0.2.57",
-		"@oj-module/runtime/contract": "0.2.57",
-		"@oj-module/runtime/contract/errors": "0.2.57",
+		"@oj-module/runtime": "0.2.62",
+		"@oj-module/runtime/contract": "0.2.62",
+		"@oj-module/runtime/contract/errors": "0.2.62",
 		"@plane/kit": "0.1.20",
 		"@plane/editor": "0.1.20",
 		"antd": "6.6.1",