@oj-module/cli 0.2.56 → 0.2.62

package/src/bundle.ts

@@ -308,6 +308,16 @@ async function assembleBundle(projectRoot: string, layout: ProjectLayout, plan:
 			}
 			fs.mkdirSync(path.join(root, "web", "modules"), { recursive: true });
 			fs.cpSync(ownWeb, path.join(root, "web", "modules", name), { recursive: true });
+			// R1 数据源随包（计划 docs/plans/20261103-0948）：安装期角色 title 解析读
+			// <包>/web/modules/<name>/locales/<lang>.json——构建产物不含 locales（源码 JSON
+			// 被 vite 内联进 JS chunk），故从源码树复制双语；目录不存在（纯后端段缺 locales）静默跳过。
+			for (const lang of ["zh-CN", "en-US"]) {
+				const src = path.join(webSrcOf(layout, name), "locales", `${lang}.json`);
+				if (fs.existsSync(src)) {
+					fs.mkdirSync(path.join(root, "web", "modules", name, "locales"), { recursive: true });
+					fs.copyFileSync(src, path.join(root, "web", "modules", name, "locales", `${lang}.json`));
+				}
+			}
 			const web = m.web as Record<string, unknown>;
 			for (const rel of [web.entry, ...(Array.isArray(web.css) ? web.css : [])]) {
 				if (typeof rel === "string" && !fs.existsSync(path.join(root, "web", rel))) {
@@ -365,6 +375,57 @@ export async function buildBundle(projectRoot: string, opts: { out?: string, nam
 	return results;
 }
 
+/**
+ * `ojm build` 末尾的用户方案摘要（2026-11-03，计划 docs/plans/20261103-0925）：
+ * 明确回答「我的方案构建进了吗、能不能打包」。判定口径与 resolveContractTargets 同源
+ * （模块级契约 ∪ 根契约，减内置名单）——摘要里列出的就是 --bundle 将要打包的那批。
+ * 只报告不裁决：不调 resolveLayout（构建末尾不因摘要崩溃），log 可注入供测试断言。
+ */
+export function summarizeBuiltSolutions(projectRoot: string, built: readonly { name: string, version: string }[], log: (line: string) => void = console.log): void {
+	const builtin = readBuiltinModules(projectRoot);
+	const rootSolution = path.join(projectRoot, "solution.yaml");
+	const rootManifest = path.join(projectRoot, "manifest.yaml");
+	const rootContract = fs.existsSync(rootSolution) ? rootSolution : fs.existsSync(rootManifest) ? rootManifest : undefined;
+	const rootName = rootContract ? peekContractName(rootContract) : undefined;
+
+	// 用户方案候选：模块级契约（非内置）∪ 根契约 name（按名去重——「根压 src」只是打包取哪份契约，摘要里是同一个方案）
+	const names = new Set<string>();
+	for (const c of collectModuleContracts(projectRoot)) {
+		if (!builtin.has(c.moduleDir!))
+			names.add(c.moduleDir!);
+	}
+	if (rootName !== undefined && !builtin.has(rootName))
+		names.add(rootName);
+
+	const builtByName = new Map(built.map(b => [b.name, b]));
+	if (names.size === 0) {
+		log("[ojm] 用户方案 0 份（ojm new <name> 创建后即可 ojm build --bundle 打包）");
+	}
+	else {
+		const all = [...names].sort();
+		const ok = all.filter(n => builtByName.has(n));
+		const missing = all.filter(n => !builtByName.has(n));
+		const builtList = ok.map(n => `${n}@${builtByName.get(n)!.version}`).join("、") || "无";
+		if (missing.length === 0)
+			log(`[ojm] 用户方案 ${all.length} 份已构建：${builtList}（ojm build --bundle 打包）`);
+		else
+			log(`[ojm] 用户方案 ${all.length} 份中 ${ok.length} 份已构建：${builtList}；未构建：${missing.join("、")}（查 web.config.ts 登记/enabled）`);
+	}
+
+	const builtinBuilt = built.filter(b => builtin.has(b.name));
+	if (builtinBuilt.length > 0)
+		log(`[ojm] 框架自带模块 ${builtinBuilt.length} 份已构建（不参与用户打包）`);
+
+	// module-root 口径（src/ 树在即适用；flat/new 工程模块不在 src/）：非内置且无契约的模块不会被打包——提前点名，别等 --bundle 才发现
+	if (fs.existsSync(path.join(projectRoot, "src"))) {
+		for (const b of built) {
+			if (builtin.has(b.name) || names.has(b.name))
+				continue;
+			log(`[ojm] ⚠️ 模块 ${b.name}@${b.version} 缺方案契约（src/${b.name}/solution.yaml），不会被打包`);
+		}
+	}
+}
+
 /**
  * C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version 与 bundle 级逐一相等
  * （oj 启动强校验同源）。

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 得到字符串
@@ -135,7 +142,10 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 				}
 				const { buildBackend, buildModules } = await import("./build");
 				await buildBackend(projectRoot);
-				await buildModules(projectRoot, { mergeSite: true });
+				const built = await buildModules(projectRoot, { mergeSite: true });
+				// 用户方案摘要（计划 20261103-0925）：构建末尾点名「我的方案」是否进构建、能否打包
+				const { summarizeBuiltSolutions } = await import("./bundle");
+				summarizeBuiltSolutions(projectRoot, built);
 			};
 		case "new":
 			return async (name: string | undefined, extra: string[] = [], opts: { layout?: string, api?: boolean } = {}) => {

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

@@ -21,7 +21,7 @@ import { BUILTIN_LIST_FILE, writeBuiltinList } from "./builtin";
 import { resolveCertDir, resolveConfigPath } from "./layout";
 import { probeOjCaps } from "./oj-caps";
 import { mintDevCert } from "./oj-cert";
-import { isSupportedOjVersion, MIN_OJ_VERSION, resolveOjBin, vendorCommand } from "./vendor";
+import { isSupportedOjVersion, MIN_OJ_VERSION, resolveOjBin, syncOjDevkit, vendorCommand } from "./vendor";
 import { readHostVersions } from "./versions";
 
 export interface InitOptions {
@@ -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 }));
@@ -167,25 +169,16 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	//      oj 不可用/不支持 secret → 保留明文并告警（init 不因加密失败而失败）
 	await sealJwtSecret(destDir, report, opts.seal);
 
-	// 4) devkit 分发：agent skill + 全局类型
-	const devkit = path.join(binDir, "devkit");
-	if (fs.existsSync(path.join(devkit, "SKILL.md"))) {
-		const skillDir = path.join(destDir, ".claude/skills/oj-api-dev");
-		fs.mkdirSync(skillDir, { recursive: true });
-		for (const name of ["SKILL.md", "api-manual.md"])
-			copyIfAbsent(path.join(devkit, name), path.join(skillDir, name), report);
-		// v0.1.82 起 devkit 新增两份专题指南（api-manual/SKILL 均引用它们）：
-		// SQL 构造器能力矩阵/方言差异、oj test L1 测试指南。它们是**增量文档**、
-		// 不影响 ojm 运行，故「有则拷、无则记跳过」——bin/devkit 来自用户本地
-		// oj 版本（MIN_OJ_VERSION 只钉到 0.1.73），旧版 devkit 没有这两个文件，
-		// 为两份文档把整个 init 打挂不值当（用户升 oj 后重跑 init 即补上）。
-		for (const name of ["sql-builder-guide.md", "oj-test-guide.md"])
-			copyIfPresent(path.join(devkit, name), path.join(skillDir, name), report);
-		copyIfAbsent(path.join(devkit, "global.d.ts"), path.join(destDir, "global.d.ts"), report);
-	}
-	else {
+	// 4) devkit 分发：agent skill（与 vendor 同一同步出口 syncOjDevkit：bin/devkit 全量
+	//    .md **覆盖**进 .claude/skills/oj-api-dev——文档随 oj 版本同步，见计划 20261103-1020）
+	//    + 全局类型（模板已落则 copyIfAbsent 跳过，模板变体优先、用户可编辑）
+	const devkitStatus = syncOjDevkit(destDir, binDir);
+	if (devkitStatus.ok)
+		report.created.push(`.claude/skills/oj-api-dev（oj devkit 文档已同步 ${devkitStatus.files.length} 个文件）`);
+	else
 		report.skipped.push(".claude/skills/oj-api-dev（bin/devkit 缺失，跳过）");
-	}
+	if (fs.existsSync(path.join(binDir, "devkit", "global.d.ts")))
+		copyIfAbsent(path.join(binDir, "devkit", "global.d.ts"), path.join(destDir, "global.d.ts"), report);
 
 	// 4b) ojm 模块开发 skill 分发：从 cli 包内置 devkit（prepack 同步的
 	//     docs/devkit）拷到 .claude/skills/ojm-module-dev/；已存在则幂等跳过。
@@ -197,7 +190,8 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 		// 业务工程拿到模板后自助完成对接要用，不能只留本仓：
 		//   · `wecom-daikaifa.md`  企业微信代开发（服务商模板）：凭据清单 + 用户/开发/部署三视角；
 		//   · `wecom-internal-app.md` 企业内部应用（自建）：五项 corp 凭据 + 验证并接入 + 共存。
-		for (const name of ["SKILL.md", "manual.md", "README.md", "wecom-daikaifa.md", "wecom-internal-app.md"])
+		//   · `publish-walkthrough.md` 方案包发布全流程（新手照做版）：打包/签名/CDN/安装一条链。
+		for (const name of ["SKILL.md", "manual.md", "README.md", "wecom-daikaifa.md", "wecom-internal-app.md", "publish-walkthrough.md"])
 			copyIfAbsent(path.join(cliDevkit, name), path.join(ojmSkillDir, name), report);
 	}
 	else {
@@ -336,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;
@@ -398,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}（拼写错误或模板缺文件？）`);
@@ -483,21 +484,6 @@ function copyIfAbsent(src: string, dest: string, report: InitReport): void {
 	report.created.push(path.relative(process.cwd(), dest) || path.basename(dest));
 }
 
-/**
- * 同 copyIfAbsent，但**源缺失**时记一条跳过而非抛错。
- *
- * 用于从 bin/devkit 拷第三方版本化内容（两份专题指南）：devkit 随用户本地 oj
- * 版本而变，旧版没有新文件属正常版本 skew，不是安装包损坏——缺了只少份文档，
- * 不该让 init 失败。源在而目标已存在仍走 copyIfAbsent 的幂等跳过。
- */
-function copyIfPresent(src: string, dest: string, report: InitReport): void {
-	if (!fs.existsSync(src)) {
-		report.skipped.push(`${path.basename(src)}（bin/devkit 无此文件，跳过）`);
-		return;
-	}
-	copyIfAbsent(src, dest, report);
-}
-
 /**
  * 新工程 .gitignore：不存在则生成；已存在则幂等跳过（用户规则永不覆盖）。
  *
@@ -519,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/
 `;