@oj-module/cli 0.2.20 → 0.2.23

package/src/builtin.ts

@@ -0,0 +1,93 @@
+/**
+ * 脚手架自带模块身份：`src/.ojm-builtin.json`。
+ *
+ * 名单派生自 init 白名单（`init.include.yaml` 的 `src/<name>/(api|web)` 条目）——
+ * 单一真源是白名单，本模块只是它的读取/派生面，不在别处另立名单常量（防双写漂移）。
+ *
+ * 语义边界（评审钉死）：
+ *   - 只是打包排除 / UI 折叠提示，**不是安全边界**——文件只活在源工程、永不入包，
+ *     安装侧信任链（签名 + 信任库 + TOFU，fail-closed）与它无关；
+ *   - 文件缺失 → 空名单（旧工程/框架仓没有内置概念，行为退化为现状）；
+ *   - 坏 JSON / modules 非字符串数组 → fail-fast（与「坏清单出不了包」同哲学，
+ *     缺失是故意的，坏文件是事故）；
+ *   - 用户对该文件有完全控制权：删名 = 该模块恢复参与打包/显示，删文件 = 全部退化。
+ *
+ * 消费方：`ojm build --bundle`（排除）、`ojm info`（折叠）、`ojm new`（拒名）、
+ * `ojm init`（生成/回填）。历史布局（new/flat）工程不适用（无 src/ 模块树概念），
+ * 调用方自行判布局，本模块不感知 layout。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const BUILTIN_LIST_FILE = ".ojm-builtin.json";
+
+export function builtinListPath(projectRoot: string): string {
+	return path.join(projectRoot, "src", BUILTIN_LIST_FILE);
+}
+
+/**
+ * 读取自带模块名单。
+ * 文件缺失 → 空集；坏文件 → fail-fast（报路径与错因）。
+ */
+export function readBuiltinModules(projectRoot: string): Set<string> {
+	const p = builtinListPath(projectRoot);
+	if (!fs.existsSync(p))
+		return new Set();
+	let doc: unknown;
+	try {
+		doc = JSON.parse(fs.readFileSync(p, "utf-8"));
+	}
+	catch (error) {
+		throw new Error(
+			`[ojm] ${p} 解析失败（${error instanceof Error ? error.message : String(error)}）。`
+			+ "该文件由 ojm init 生成、可手改/删除，但必须是合法 JSON"
+			+ "（{ \"modules\": [\"<模块名>\", …] }）。",
+		);
+	}
+	const modules = (doc as { modules?: unknown })?.modules;
+	if (!Array.isArray(modules) || modules.some(m => typeof m !== "string")) {
+		throw new Error(
+			`[ojm] ${p} 的 modules 必须是字符串数组，`
+			+ `实际为 ${Array.isArray(modules) ? `含非字符串项的数组（${JSON.stringify(modules)}）` : typeof modules
+			}。修复或删除该文件后重试。`,
+		);
+	}
+	return new Set(modules);
+}
+
+/**
+ * 从 init.include.yaml 的 include 集合派生自带模块名：`src/<name>/(api|web)` 条目的
+ * `<name>` 段（整目录收录 `src/<name>/api` 与逐文件收录 `src/<name>/web/...` 都命中）。
+ * 与 `pruneUnincludedApiPaths` 的派生同族，扩 web 侧覆盖 web-only 模块（login/oj-market）。
+ */
+export function deriveBuiltinModules(include: Iterable<string>): Set<string> {
+	const mods = new Set<string>();
+	for (const p of include) {
+		const m = /^src\/([^/]+)\/(?:api|web)(?:\/|$)/.exec(p)?.[1];
+		if (m)
+			mods.add(m);
+	}
+	return mods;
+}
+
+/**
+ * init 接线：生成/回填 `src/.ojm-builtin.json`（copyIfAbsent 语义）。
+ * 已存在 → 原样不动（用户手改权）；派生集为空 → 不写。
+ * @returns "created" | "skipped" | "none"
+ */
+export function writeBuiltinList(projectRoot: string, include: Iterable<string>): "created" | "skipped" | "none" {
+	const target = builtinListPath(projectRoot);
+	if (fs.existsSync(target))
+		return "skipped";
+	const modules = [...deriveBuiltinModules(include)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+	if (modules.length === 0)
+		return "none";
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	const doc = {
+		"//": "由 ojm init 生成（名单派生自模板白名单）。可手改/删除：删名 = 该模块恢复参与打包与 ojm info 显示；删整个文件 = 退化为无内置概念。",
+		modules,
+	};
+	fs.writeFileSync(target, `${JSON.stringify(doc, null, "\t")}\n`);
+	return "created";
+}

package/src/bundle.ts

@@ -1,7 +1,28 @@
-// 方案包构建（P1-11，`ojm build --bundle`）：manifest.yaml 契约校验（fail-fast 先于打包）
+// 方案包构建（P1-11，`ojm build --bundle`）：bundle 级契约校验（fail-fast 先于打包）
 // → 组装 tgz 内布局（契约 §2.9）→ 确定性打包（C2-32）+ sha256。
+// bundle 级契约文件名：解决方案优先 `solution.yaml`；旧方案回退 `manifest.yaml`。
+// 之所以用 solution.yaml 而非根目录 manifest.yaml：oj 按 `manifest.yaml` 枚举发现 api 后端模块
+// （模块级 `src/<name>/api/manifest.yaml`），根目录再放一份 bundle 契约会污染后端的「搜索枚举」，
+// 让 oj 误把 bundle 契约当 api 模块——故用独立文件名隔开两条枚举（避免后端搜索枚举与 bundle 冲突）。
+//
+// 多方案（2026-10-22，docs/plans/2026-10-22-1640-multi-solution-bundle-design.md）：
+// 一个脚手架可有多份用户方案，各自一份模块级契约。契约解析优先级矩阵：
+//   --bundle <name> → src/<name>/solution.yaml（无则 manifest.yaml 回退）；
+//                     未命中再比对工程根契约的 name === <name>；都不中 → 报错。
+//                     内置名拒绝（第一方请在框架仓模板工程打包——那里无 builtin 清单）。
+//   无参 + 工程根契约 → 只打根契约，src 契约被跳过打 hint。根 solution.yaml 场景与旧行为
+//                     逐字节一致；根 manifest.yaml 与 src 模块契约并存时旧版取 src 契约
+//                     （旧优先级 ②>③）、现取根契约——多方案矩阵定版「根压 src」（B11）。
+//   无参 + 无根契约   → 收集全部非内置模块级契约逐个打包；
+//                     零份用户契约 → 友好报错指向 `ojm new`
+//   模块级契约强校验 name === 目录名（B8；跨契约查重因 B8 不可达已不实现，见计划文档 B7 决策）。
+//   两段式：全部校验（纯读零写盘）先于全部组装——校验失败 dist/ 零增量，
+//   发布者不会把半截批次扫进 CDN 索引（build-index 全量收目录）。
+//
 // 组装映射（对齐 P1-9 staging copy 源一层定版，unpack 布局即安装器 extract 段消费面）：
-//   <project>/manifest.yaml                     → <name>-<version>/manifest.yaml（Form A）
+//   <project>/solution.yaml | manifest.yaml          → 工程根契约（旧单方案写法）
+//   <project>/src/<模块>/solution.yaml | manifest.yaml → 模块级契约（绝不进 <模块>/api/，§1.2 红线）
+//   任一处均 → <name>-<version>/manifest.yaml（Form A；tgz 内名固定为 manifest.yaml）
 //   <project>/api/dist/<name>-<version>/        → <name>-<version>/api/<name>-<version>/（oj build 产物原样，C2-31 分层核对）
 //   <project>/web/dist/modules/<name>/          → <name>-<version>/web/modules/<name>/（只入包方案自己的模块；
 //                                                 web.entry/css 存在性复核）
@@ -13,9 +34,10 @@ import path from "node:path";
 
 import { parse } from "yaml";
 import { readModuleDefinition } from "./build";
+import { readBuiltinModules } from "./builtin";
 import { createDeterministicTgz } from "./deterministic-tar";
 import { apiSrcOf, resolveLayout, webSrcOf } from "./layout";
-import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, referencedI18nKeys, validateContract } from "./manifest-contract";
+import { assertValidSolutionName, checkLocalesComplete, checkTablesAgainstSchema, NAME_RE, parseManifest, referencedI18nKeys, validateContract } from "./manifest-contract";
 import { deriveManifestRoutes, reconcileManifestRoutes } from "./manifest-routes-derive";
 
 export interface BundleBuildResult {
@@ -26,29 +48,168 @@ export interface BundleBuildResult {
 }
 
 /**
- * 从方案工程产出可安装 tgz + sha256。
- * @param projectRoot 方案工程根（manifest.yaml 所在目录）
- * @param opts 输出与选项
- * @param opts.out 输出目录，缺省 `dist/`；产物 `<name>-<version>.tgz`
+ * 方案名正则（`--bundle <name>` / `ojm new <name>` 入口校验共用，DRY）：
+ * 与契约 C2-01 同一条（小写字母开头 kebab-case，≤64）——入口先校验，
+ * 契约校验再做正式判罚；挡住 ../ 路径穿越与引号/换行注入。
+ * 校验函数本体在 manifest-contract.ts（new 入口不拖入打包模块图），此处 re-export 兼容既有引用。
  */
-export async function buildBundle(projectRoot: string, opts: { out?: string } = {}): Promise<BundleBuildResult> {
-	// 1) 读入并校验契约（构建即校验，坏清单出不了包）
-	const manifestPath = path.join(projectRoot, "manifest.yaml");
-	if (!fs.existsSync(manifestPath)) {
-		throw new Error(`[ojm] 方案包构建失败：${projectRoot} 下缺少 manifest.yaml（bundle 级契约是打包入口，写法见 devkit 手册「打包与分发」）`);
-	}
-	const parsed = parseManifest(fs.readFileSync(manifestPath, "utf8"));
-	if (!parsed.ok) {
-		throw new Error(`[ojm] 方案包构建失败：${parsed.error}`);
+export const SOLUTION_NAME_RE = NAME_RE;
+export { assertValidSolutionName } from "./manifest-contract";
+
+/** 打包目标：一份契约 = 一个方案包 */
+interface BundleTarget {
+	/** 契约文件路径（solution.yaml 或 manifest.yaml） */
+	contractPath: string
+	/** 模块级契约所在 src/<name> 目录名（工程根契约为 undefined） */
+	moduleDir?: string
+}
+
+/**
+ * 收集模块级契约（`src/<name>/` 根下，solution.yaml 优先于 manifest.yaml 回退；
+ * 绝不进 `<模块>/api/`——与 oj 的 api 枚举撞车红线，§1.2）。按目录名排序保证确定性。
+ */
+function collectModuleContracts(projectRoot: string): BundleTarget[] {
+	const srcDir = path.join(projectRoot, "src");
+	if (!fs.existsSync(srcDir))
+		return [];
+	const out: BundleTarget[] = [];
+	for (const e of fs.readdirSync(srcDir, { withFileTypes: true })) {
+		if (!e.isDirectory() || e.name.startsWith("."))
+			continue;
+		const dir = path.join(srcDir, e.name);
+		const sol = path.join(dir, "solution.yaml");
+		const man = path.join(dir, "manifest.yaml");
+		if (fs.existsSync(sol))
+			out.push({ contractPath: sol, moduleDir: e.name });
+		else if (fs.existsSync(man))
+			out.push({ contractPath: man, moduleDir: e.name });
+	}
+	out.sort((a, b) => (a.moduleDir! < b.moduleDir! ? -1 : a.moduleDir! > b.moduleDir! ? 1 : 0));
+	return out;
+}
+
+/** 读契约 name 用于优先级矩阵的快速比对（坏契约不在此处报错——planBundle 会给正式错误） */
+function peekContractName(contractPath: string): string | undefined {
+	try {
+		const parsed = parseManifest(fs.readFileSync(contractPath, "utf8"));
+		return parsed.ok ? (parsed.manifest.name as string) : undefined;
+	}
+	catch {
+		return undefined;
+	}
+}
+
+/**
+ * 契约解析复数化（优先级矩阵见文件头注释）。
+ * 内置排除只是便利机制不是安全边界：伪造/删除名单的最坏后果在打包侧，
+ * 安装侧信任链（签名 + 信任库，fail-closed）与它无关。
+ */
+function resolveContractTargets(projectRoot: string, name?: string): BundleTarget[] {
+	const builtin = readBuiltinModules(projectRoot);
+	const moduleContracts = collectModuleContracts(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;
+
+	// --bundle <name>：先按目录名选模块级契约，再比对根契约 name
+	if (name !== undefined) {
+		assertValidSolutionName(name, "--bundle <name>");
+		const hit = moduleContracts.find(c => c.moduleDir === name);
+		if (hit) {
+			if (builtin.has(name)) {
+				throw new Error(
+					`[ojm] 「${name}」是框架自带方案，不参与用户打包。`
+					+ "第一方发布请在框架仓模板工程打包（模板工程无内置名单，走全量打包路径）。",
+				);
+			}
+			return [hit];
+		}
+		if (rootContract) {
+			const rootName = peekContractName(rootContract);
+			if (rootName === undefined) {
+				throw new Error(
+					`[ojm] 方案包构建失败：工程根契约 ${path.basename(rootContract)} 存在但无法解析`
+					+ "（name 缺失或文件损坏）——请先修复它，或显式给出 src/<name>/solution.yaml。",
+				);
+			}
+			if (rootName === name) {
+				if (builtin.has(name)) {
+					console.warn(
+						`[ojm] ⚠️ 工程根契约 name「${name}」与框架自带方案同名——`
+						+ "确认你要分发的是自有方案而非自带模块的构建产物。",
+					);
+				}
+				return [{ contractPath: rootContract }];
+			}
+		}
+		throw new Error(
+			`[ojm] 方案包构建失败：未找到「${name}」的契约`
+			+ `（期望 src/${name}/solution.yaml，或工程根契约 name === "${name}"）。`,
+		);
+	}
+
+	// 无参 + 工程根契约：旧单方案行为零变化（根优先于一切模块级契约）
+	if (rootContract) {
+		if (moduleContracts.length > 0) {
+			console.log(
+				`[ojm] 工程根契约优先：跳过 src/ 下 ${moduleContracts.length} 份模块级契约`
+				+ "（用 ojm build --bundle <name> 单独打包其中一份）",
+			);
+		}
+		const rootName = peekContractName(rootContract);
+		if (rootName !== undefined && builtin.has(rootName)) {
+			console.warn(
+				`[ojm] ⚠️ 工程根契约 name「${rootName}」与框架自带方案同名——`
+				+ "确认你要分发的是自有方案而非自带模块的构建产物。",
+			);
+		}
+		return [{ contractPath: rootContract }];
+	}
+
+	// 无参 + 无根契约：全部非内置模块级契约
+	for (const c of moduleContracts.filter(c => builtin.has(c.moduleDir!)))
+		console.log(`[ojm] 跳过框架自带方案：${c.moduleDir}（不参与用户打包）`);
+	const userContracts = moduleContracts.filter(c => !builtin.has(c.moduleDir!));
+	if (userContracts.length === 0) {
+		throw new Error(
+			"[ojm] 方案包构建失败：没有可打包的用户方案（脚手架自带方案不参与打包）。"
+			+ "用 ojm new <name> 创建方案后再打包。",
+		);
 	}
+	return userContracts;
+}
+
+/** 校验段产物：一份通过全部构建期校验、待组装的方案 */
+interface BundlePlan {
+	manifest: Record<string, unknown>
+	contractPath: string
+	moduleDir?: string
+	name: string
+	version: string
+}
+
+/**
+ * 校验段（纯读、零写盘）：契约解析 → routes 派生 → 契约校验 → 文件面校验。
+ * 模块级契约强校验 name === 目录名（--bundle <name> 按目录名选契约，
+ * 产物定位/入口派生全用契约 name，两者不一致会打出名字与目录对不上的包）。
+ */
+async function planBundle(projectRoot: string, layout: ProjectLayout, target: BundleTarget): Promise<BundlePlan> {
+	const parsed = parseManifest(fs.readFileSync(target.contractPath, "utf8"));
+	if (!parsed.ok)
+		throw new Error(`[ojm] 方案包构建失败：${parsed.error}`);
 	const m = parsed.manifest;
 	const name = m.name as string;
 
+	if (target.moduleDir !== undefined && name !== target.moduleDir) {
+		throw new Error(
+			`[ojm] 方案包构建失败：${target.contractPath} 的 name「${name}」与目录名「${target.moduleDir}」不一致`
+			+ "（module-root 下契约与模块同位同名）。",
+		);
+	}
+
 	// R5：manifest.routes 由 entry.ts 路由 handle 自动派生（单一真源），覆盖手工书写。
 	// 仅当 entry.ts 声明了 category 路由才覆盖；否则保留 manifest 既有 routes（未迁移方案兼容）。
 	// entry 读不出来（如第三依赖未装）时软降级：沿用既有 routes，不阻断打包。
-	const layout = resolveLayout(projectRoot);
-	// 前端入口两侧布局都在 webSrcOf 里收口：module-root → src/<name>/web，历史 → web/src/<name>
 	const entryFile = path.join(webSrcOf(layout, name), "entry.ts");
 	if (fs.existsSync(entryFile)) {
 		try {
@@ -73,7 +234,7 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 	}
 	const version = m.version as string;
 
-	// 2) 文件面契约（§4.1 构建列专属执行点；manifest 内在规则已在 validateContract 全量通过）
+	// 文件面契约（§4.1 构建列专属执行点；manifest 内在规则已在 validateContract 全量通过）
 	const fileViolations = [
 		...checkTables(m, layout, name),
 		...checkLocales(m, layout, name),
@@ -91,15 +252,27 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 		}
 	}
 
+	return { manifest: m, contractPath: target.contractPath, moduleDir: target.moduleDir, name, version };
+}
+
+/**
+ * 组装段（写盘）：staging 单根 <name>-<version>/ → 红线自检 → 确定性 tgz + sha256。
+ * 入包内容与 §11.1 一致：只组装本方案的模块产物（api/dist/<name>-<version>/ 与
+ * web/dist/modules/<name>/），模板/宿主模块不随包。
+ */
+async function assembleBundle(projectRoot: string, layout: ProjectLayout, plan: BundlePlan, outDir: string): Promise<BundleBuildResult> {
+	const m = plan.manifest;
+	const name = plan.name;
+	const version = plan.version;
+
 	// 3) 组装 staging：<name>-<version>/ 单根
 	const staging = fs.mkdtempSync(path.join(projectRoot, ".ojm-bundle-"));
 	try {
 		const root = path.join(staging, `${name}-${version}`);
 		fs.mkdirSync(root);
-		fs.copyFileSync(manifestPath, path.join(root, "manifest.yaml"));
+		fs.copyFileSync(plan.contractPath, path.join(root, "manifest.yaml"));
 
-		// api：oj build 产物原样入包（编译编排不在此重跑——作者先 oj build，本命令只校验与组装；
-		// 编排接线随 P1-15 方案脚手架定形）
+		// api：oj build 产物原样入包（编译编排不在此重跑——作者先 oj build，本命令只校验与组装）
 		if (m.api !== undefined) {
 			const built = path.join(projectRoot, "api/dist", `${name}-${version}`);
 			if (!fs.existsSync(built)) {
@@ -141,7 +314,6 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 		assertNoForbiddenMembers(root);
 
 		// 4) 确定性打包（C2-32；symlink 等成员守卫在打包原语内，C2-30）
-		const outDir = path.resolve(projectRoot, opts.out ?? "dist");
 		const tgzPath = path.join(outDir, `${name}-${version}.tgz`);
 		const sha256 = await createDeterministicTgz(staging, tgzPath);
 		const size = fs.statSync(tgzPath).size;
@@ -154,6 +326,38 @@ export async function buildBundle(projectRoot: string, opts: { out?: string } =
 	}
 }
 
+/**
+ * 从方案工程产出可安装 tgz + sha256（多方案：返回 N 份结果，与目标契约一一对应）。
+ * 两段式：planBundle 全部先跑完（纯读、零写盘），任一失败 dist/ 零增量；
+ * 组装段失败保留已完成产物并在报错中指名失败方案。
+ */
+export async function buildBundle(projectRoot: string, opts: { out?: string, name?: string } = {}): Promise<BundleBuildResult[]> {
+	const targets = resolveContractTargets(projectRoot, opts.name);
+	const layout = resolveLayout(projectRoot);
+	// 两段式：全部校验先跑完（纯读、零写盘），任一失败 dist/ 零增量——
+	// 发布者不会把半截批次扫进 CDN 索引（build-index 全量收目录）。
+	// name+version 撞车防护由 planBundle 的 name===目录名 强校验承担：
+	// 目录名在单一 src/ 层唯一 ⇒ 契约 name 唯一（评审 B7 与 B8 组合后撞车向量不可达）。
+	const plans = await Promise.all(targets.map(t => planBundle(projectRoot, layout, t)));
+
+	const outDir = path.resolve(projectRoot, opts.out ?? "dist");
+	const results: BundleBuildResult[] = [];
+	for (const plan of plans) {
+		try {
+			results.push(await assembleBundle(projectRoot, layout, plan, outDir));
+		}
+		catch (error) {
+			const done = results.map(r => `${r.name}-${r.version}`).join(", ");
+			throw new Error(
+				`[ojm] 方案「${plan.name}」打包失败${done ? `（已完成：${done}）` : ""}：${
+					error instanceof Error ? error.message : String(error)}`,
+				{ cause: error },
+			);
+		}
+	}
+	return results;
+}
+
 /**
  * C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version 与 bundle 级逐一相等
  * （oj 启动强校验同源）。
@@ -214,8 +418,8 @@ function checkLocales(m: Record<string, unknown>, layout: ProjectLayout, name: s
 	return [...out, ...checkLocalesComplete(m, texts["zh-CN"] ?? "", texts["en-US"] ?? "")];
 }
 
-/** 私钥/凭证文件名红线（P2-4 入包自检）：*.pem / *.key / .env / id_ed25519|id_rsa */
-const FORBIDDEN_MEMBER = /\.(?:pem|key)$|^\.env$|^id_(?:ed25519|rsa)$/;
+/** 私钥/凭证文件名红线（P2-4 入包自检）：*.pem/*.key/*.p12/*.pfx、.env 系（.env/.env.*）、id_ed25519|id_rsa */
+const FORBIDDEN_MEMBER = /\.(?:pem|key|p12|pfx)$|^\.env(?:\.|$)|^id_(?:ed25519|rsa)$/;
 
 /** staging 全树扫描：modules.json 禁入（C2-31 红线）+ 私钥/凭证禁入（P2-4 红线） */
 function assertNoForbiddenMembers(root: string): void {
@@ -230,7 +434,7 @@ function assertNoForbiddenMembers(root: string): void {
 				throw new Error(`[ojm] 打包自检失败（C2-31）：modules.json 禁入方案包（该清单由安装器在目标站点 upsert，防覆盖宿主清单）——位置：${p}`);
 			}
 			if (e.isFile() && FORBIDDEN_MEMBER.test(e.name)) {
-				throw new Error(`[ojm] 打包自检失败（P2-4 入包红线）：私钥/凭证文件「${e.name}」禁入方案包（*.pem / *.key / .env / id_ed25519 / id_rsa）——签名私钥永不入包，签名经 detached .sig 侧车随包分发（包内只含产物与公钥）。位置：${p}`);
+				throw new Error(`[ojm] 打包自检失败（P2-4 入包红线）：私钥/凭证文件「${e.name}」禁入方案包（*.pem / *.key / *.p12 / *.pfx / .env 系 / id_ed25519 / id_rsa）——签名私钥永不入包，签名经 detached .sig 侧车随包分发（包内只含产物与公钥）。位置：${p}`);
 			}
 		}
 	};

package/src/contract/__tests__/market-client.integration.test.ts

@@ -63,7 +63,7 @@ function mockRequest(responder: (c: Call) => { status?: number, data?: unknown }
 
 // 让 index() 直连的 request 与生成 client 的 bindRequest 指向同一 mock，行为一致。
 // 桥接：占位方法零参签名 ↔ ScopedRequestLike 真实签名，经 any 双向打通（测试桩，无运行时差异）。
-function useMock(m: ReturnType<typeof mockRequest>) {
+function bindMock(m: ReturnType<typeof mockRequest>) {
 	bindRequest(m.req);
 	const req = m.req as unknown as Record<keyof typeof requestImpl, () => never>;
 	for (const k of Object.keys(requestImpl) as Array<keyof typeof requestImpl>)
@@ -75,12 +75,12 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	beforeEach(() => {
 		mock = mockRequest(() => ({ data: {} }));
-		useMock(mock);
+		bindMock(mock);
 	});
 
 	it("meta() → GET _platform/market/meta，返回 { apiVersion }", async () => {
 		mock = mockRequest(() => ({ data: { apiVersion: "1.2.3" } }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.meta();
 		expect(mock.calls).toEqual([{ method: "get", url: "_platform/market/meta", opts: undefined }]);
 		expect(r).toEqual({ apiVersion: "1.2.3" });
@@ -89,7 +89,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 	it("index() → GET _platform/market/index，返回 IndexRow[]", async () => {
 		const rows = [{ name: "a", latest: "1.0", installed: "1.0", enabled: true, upgradable: false }];
 		mock = mockRequest(() => ({ data: rows }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.index();
 		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/index" });
 		expect(r).toEqual(rows);
@@ -97,7 +97,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("index() 遇 503（未配置市场地址）→ [] 空态，不抛（PRD §5.3）", async () => {
 		mock = mockRequest(c => (c.url === "_platform/market/index" ? { status: 503 } : { data: {} }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.index();
 		expect(r).toEqual([]);
 		// 503 是配置态而非故障：silentError 抑制全局 toast + retry:0 不重试（原
@@ -108,7 +108,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("install(input) → POST _platform/market/install，body 含 name/version/source", async () => {
 		mock = mockRequest(() => ({ data: { task_id: "t-1" } }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.install({ name: "alpha", version: "2.0", source: "file" });
 		expect(mock.calls[0]).toMatchObject({ method: "post", url: "_platform/market/install" });
 		expect(mock.calls[0].opts?.json).toEqual({ name: "alpha", version: "2.0", source: "file" });
@@ -117,7 +117,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("install(input) 缺省 version/source → null / cdn 兜底", async () => {
 		mock = mockRequest(() => ({ data: { task_id: "t-2" } }));
-		useMock(mock);
+		bindMock(mock);
 		await httpMarketClient.install({ name: "beta" });
 		expect(mock.calls[0].opts?.json).toEqual({ name: "beta", version: null, source: "cdn" });
 	});
@@ -125,7 +125,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 	it("task(id) → GET _platform/market/task? 带 id", async () => {
 		const rec = { id: "t-1", name: "a", version: "1.0", status: "done", stage: "done", progress: 100, message: "ok", stages: [], startedAt: 1 };
 		mock = mockRequest(() => ({ data: rec }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.task("t-1");
 		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/task" });
 		expect(mock.calls[0].opts?.searchParams).toEqual({ id: "t-1" });
@@ -134,7 +134,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("enable(input) → POST _platform/market/enable，body {name,enabled}", async () => {
 		mock = mockRequest(() => ({ data: { ok: true, message: "done" } }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.enable({ name: "a", enabled: false });
 		expect(mock.calls[0]).toMatchObject({ method: "post", url: "_platform/market/enable" });
 		expect(mock.calls[0].opts?.json).toEqual({ name: "a", enabled: false });
@@ -144,7 +144,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 	it("history() → GET _platform/market/history，返回 MarketHistory[]", async () => {
 		const hist = [{ id: 1, solution: "a", version: "1.0", action: "install", status: "ok", operator: null, message: null, created_at: 1 }];
 		mock = mockRequest(() => ({ data: hist }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.history();
 		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/history" });
 		expect(r).toEqual(hist);
@@ -152,7 +152,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("uninstallImpact(name) → GET _platform/market/uninstall-impact? 带 name", async () => {
 		mock = mockRequest(() => ({ data: { name: "a", affectedRoles: 2, affectedUsers: 5 } }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.uninstallImpact("a");
 		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/uninstall-impact" });
 		expect(mock.calls[0].opts?.searchParams).toEqual({ name: "a" });
@@ -161,7 +161,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("uninstall(name) → POST _platform/market/uninstall，body {name}", async () => {
 		mock = mockRequest(() => ({ data: { ok: true, message: "removed" } }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.uninstall("a");
 		expect(mock.calls[0]).toMatchObject({ method: "post", url: "_platform/market/uninstall" });
 		expect(mock.calls[0].opts?.json).toEqual({ name: "a" });

package/src/dev.ts

@@ -294,6 +294,8 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 	// 仅 TTY 默认启用（管道/CI 下不抢 stdin）；测试可经 keymap + inputStream 强制。
 	const keymapEnabled = opts.keymap ?? (process.stdin.isTTY ?? false);
 	if (keymapEnabled) {
+		const footerText = "快捷键：r 热更新 · h 帮助 · c 清屏 · o 打开浏览器 · q 退出";
+		const footer = pinFooter(`[ojm] ${footerText}`);
 		setupDevKeymap({
 			server,
 			oj,
@@ -301,12 +303,15 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 			port: actualPort,
 			input: opts.inputStream,
 			openBrowser: opts.openBrowser,
+			clearScreen: footer ? () => footer.clear() : undefined,
 			onReload: () => {
 				void trigger();
 			},
 			onQuit: shutdown,
 		});
-		console.log("[ojm] 快捷键：r 热更新 · h 帮助 · c 清屏 · o 打开浏览器 · q 退出");
+		// 非 TTY（pinFooter 拒绝）回退一次性打印，行为与历史一致
+		if (!footer)
+			console.log(`[ojm] ${footerText}`);
 	}
 
 	return server;
@@ -335,6 +340,52 @@ export async function shutdownDev(
 	setTimeout(exit, 1500, 0).unref();
 }
 
+/**
+ * 快捷键提示常驻底栏：DECSTBM 把滚动区设为 1..rows-1，末行留给提示。
+ * 之后本进程 console.log 与 oj 透传（均经 process.stdout.write）只在滚动区内滚动，
+ * 末行由终端保持，无需逐条重绘。非 TTY / 行数不足返回 undefined（调用方回退一次性打印）。
+ */
+export interface PinnedFooter {
+	/** 清屏：ED（\x1b[2J）保留滚动区（RIS \x1bc 会复位滚动区，禁用），随后重绘提示 */
+	clear: () => void
+	/** 恢复全屏滚动区并落光标到底行（进程退出/shell 接管前调用）；幂等 */
+	stop: () => void
+}
+
+export function pinFooter(text: string, stream: NodeJS.WriteStream = process.stdout): PinnedFooter | undefined {
+	if (!stream.isTTY || (stream.rows ?? 0) < 3)
+		return undefined;
+	const write = (s: string) => {
+		stream.write(s);
+	};
+	const render = () => {
+		const rows = stream.rows || 24;
+		write(`\x1B[1;${rows - 1}r`); // 滚动区：首行 ~ 倒数第二行（DECSTBM 会把光标送回 1;1）
+		write(`\x1B[${rows};1H\x1B[2K${text}`); // 末行清行后画常驻提示
+		write(`\x1B[${rows - 1};1H`); // 光标回滚动区底行，后续输出照常滚动
+	};
+	render();
+	const onResize = () => render();
+	let stopped = false;
+	const stop = () => {
+		if (stopped)
+			return;
+		stopped = true;
+		process.removeListener("SIGWINCH", onResize);
+		process.removeListener("exit", stop);
+		write("\x1B[r\x1B[999;1H\n"); // 恢复全屏滚动区，光标夹到底行避免 shell 提示符悬空
+	};
+	process.on("SIGWINCH", onResize);
+	process.on("exit", stop);
+	return {
+		clear: () => {
+			write("\x1B[2J");
+			render();
+		},
+		stop,
+	};
+}
+
 /**
  * Vite 风格 dev 快捷键（默认仅在 TTY 启用，见 devServer 内的 keymapEnabled 判定）。
  *   r  强制重建并热更新（复用 trigger）
@@ -356,6 +407,8 @@ export interface DevKeymapDeps {
 	 */
 	input?: NodeJS.ReadableStream & { setRawMode?: (mode: boolean) => unknown }
 	openBrowser?: (url: string) => void
+	/** 清屏实现（默认 \x1Bc）；devServer 注入底栏版以保住滚动区 */
+	clearScreen?: () => void
 	onReload: () => void
 	onQuit: () => void
 	log?: (msg: string) => void
@@ -404,7 +457,10 @@ export function setupDevKeymap(deps: DevKeymapDeps): void {
 			help();
 		}
 		else if (k === "c") {
-			process.stdout.write("\x1Bc");
+			if (deps.clearScreen)
+				deps.clearScreen();
+			else
+				process.stdout.write("\x1Bc");
 		}
 		else if (k === "o") {
 			open(url);