@oj-module/cli 0.2.20 → 0.2.25

package/src/cli.ts

@@ -0,0 +1,265 @@
+import type { CAC } from "cac";
+import type { HelpEntry, Lang } from "./usage";
+/**
+ * `ojm` 的 cac 接线：命令注册 + action 薄分发（解析 → 既有 handler）。
+ * 帮助文本（双语注册表）在 usage.ts；handler 真逻辑在各业务模块，本模块不掺业务。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import cac from "cac";
+import { findCommand, groupHelpText, HELP_GROUPS, resolveLang, topHelpSections, usageText } from "./usage";
+
+export interface CliDeps { exit?: (code: number) => never }
+
+/** `ojm help [cmd [sub]]` → `<cmd> [sub] --help`：词形归一，交给 cac 的 help 机制。 */
+export function rewriteHelpArgv(argv: string[]): string[] {
+	if (argv[0] !== "help")
+		return argv;
+	if (argv.length === 1)
+		return ["--help"];
+	return [...argv.slice(1), "--help"];
+}
+
+/**
+ * 未知命令兜底结果（index.ts 打印 + 退出用）。
+ * help 形态（ojm nope --help / ojm help nope）：报「未知命令」exit 1——打帮助退 0 会掩盖拼写错误。
+ */
+export function unknownCommandResult(cmd: string, lang: Lang, helpRequested: boolean): { text: string, code: number } {
+	if (helpRequested) {
+		return {
+			text: lang === "zh-CN"
+				? `[ojm] 未知命令：${cmd}（ojm --help 查看全部命令）`
+				: `[ojm] Unknown command: ${cmd} (run ojm --help for the full command list)`,
+			code: 1,
+		};
+	}
+	return { text: usageText(lang), code: 1 };
+}
+
+/** cac 的内置报错是英文裸消息（Unknown option）——按语言重写成人话，带修复指引。 */
+export function localizeCacError(error: unknown, lang: Lang): unknown {
+	if (!(error instanceof Error))
+		return error;
+	const m = /^Unknown option `([^`]+)`/.exec(error.message);
+	if (!m)
+		return error;
+	return new Error(lang === "zh-CN"
+		? `[ojm] 未知选项：${m[1]}（ojm <cmd> --help 查看可用选项）`
+		: `[ojm] Unknown option: ${m[1]} (run ojm <cmd> --help for available options)`);
+}
+
+/** 与旧 index.ts 顶层 catch 同源：message 已是人话，堆栈仅 OJM_DEBUG=1（兼容旧名 RAM_DEBUG）。 */
+export function reportCliError(error: unknown, exit: (code: number) => never): void {
+	const isDebug = !!(process.env.OJM_DEBUG ?? process.env.RAM_DEBUG);
+	const body = error instanceof Error ? (isDebug ? error.stack ?? error.message : error.message) : String(error);
+	console.error(/^\[ojm/.test(body) ? body : `[ojm] ${body}`);
+	exit(1);
+}
+
+interface SiteOpts { url?: string, user?: string, pass?: string }
+
+function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code: number) => never): (...args: any[]) => Promise<void> {
+	switch (def.key) {
+		case "init":
+			return async (dir?: string, opts: { yes?: boolean } = {}) => {
+				const { initProject } = await import("./init");
+				await initProject(dir ? path.resolve(dir) : projectRoot, { yes: !!opts.yes });
+			};
+		case "dev":
+			return async (port?: string) => {
+				const { devServer } = await import("./dev");
+				const portArg = Number(port);
+				await devServer(projectRoot, { port: Number.isFinite(portArg) && portArg > 0 ? portArg : 5174 });
+			};
+		case "build":
+			return async (opts: { bundle?: unknown, out?: string } = {}) => {
+				// mri 可选值：裸 --bundle 得到 ""，--bundle name / --bundle=name 得到字符串
+				const bundle = opts.bundle !== undefined;
+				const bundleName = typeof opts.bundle === "string" && opts.bundle !== "" ? opts.bundle : undefined;
+				if (bundle) {
+					const { buildBundle } = await import("./bundle");
+					const results = await buildBundle(projectRoot, { out: opts.out, name: bundleName });
+					if (results.length > 1)
+						console.log(`[ojm] 共打包 ${results.length} 份方案包（逐包签名：ojm sign dist/<name>-<version>.tgz --id <publisher>.<key> --check）`);
+					return;
+				}
+				const { buildBackend, buildModules } = await import("./build");
+				await buildBackend(projectRoot);
+				await buildModules(projectRoot, { mergeSite: true });
+			};
+		case "new":
+			return async (name: string | undefined, extra: string[] = [], opts: { layout?: string, api?: boolean } = {}) => {
+				if (!name) {
+					console.error("[ojm] 用法：ojm new <name> [--layout container|none] [--api]（非交互环境必须显式给 name）");
+					exit(1);
+					return;
+				}
+				// 统一审查 F8：多余位置参数显式拒绝，不能静默丢弃（ojm new crm erp 只建 crm 是事故）
+				if (extra.length > 0)
+					throw new Error(`[ojm] ojm new 只接受一个方案名（多余参数：${extra.join(" ")}）`);
+				if (opts.layout !== undefined && opts.layout !== "container" && opts.layout !== "none")
+					throw new Error(`[ojm] --layout 只接受 container | none（实际：${opts.layout}）`);
+				const { createSolution } = await import("./new");
+				const created = createSolution(projectRoot, name, { layout: opts.layout as "container" | "none" | undefined, api: !!opts.api });
+				console.log(`[ojm] 已生成方案骨架：${path.relative(process.cwd(), created.dir)}`);
+				for (const f of created.files)
+					console.log(`[ojm]   + ${f}`);
+				console.log(`[ojm] 下一步：pnpm dev 看效果 → ojm build && ojm build --bundle ${name} 打包`);
+			};
+		case "preview":
+			return async (port?: string) => {
+				const { runPreview } = await import("./preview");
+				const portArg = Number(port);
+				await runPreview(projectRoot, { port: Number.isInteger(portArg) && portArg > 0 ? portArg : undefined });
+			};
+		case "api":
+			return async (dir?: string, opts: { check?: boolean, docs?: boolean, exempt?: string } = {}) => {
+				// S5：显式目录必须先存在——否则静默在错的目录下生成/对账
+				if (dir && !fs.existsSync(path.resolve(dir)))
+					throw new Error(`[ojm-api] 项目目录不存在：${dir}`);
+				const apiRoot = dir ? path.resolve(dir) : projectRoot;
+				if (opts.docs) {
+					const { runApiDocs } = await import("./contract/run");
+					const out = await runApiDocs(apiRoot);
+					console.log(`[ojm-api] 文档站已生成：${path.relative(projectRoot, out)}（浏览器直接打开即可）`);
+					return;
+				}
+				if (opts.check) {
+					const { checkApi } = await import("./contract/check");
+					// --exempt <path>：相对路径按项目根解析；缺省按布局找 .ojm-api-exempt.json（工程根 → api/）
+					const { violations, hints } = await checkApi({ cwd: apiRoot, exempt: opts.exempt ? path.resolve(projectRoot, opts.exempt) : undefined });
+					for (const v of violations)
+						console[v.level === "error" ? "error" : "warn"](`${v.level === "error" ? "✗" : "⚠"} ${v.message}`);
+					for (const h of hints)
+						console.log(h);
+					if (violations.length === 0)
+						console.log("[ojm-api] --check 通过：生成物同步、route 双向对账、routes.js 均无 drift。");
+					const errors = violations.filter(v => v.level === "error").length;
+					console.log(`[ojm-api] --check 结果：${errors} error / ${violations.length - errors} warn`);
+					if (errors > 0)
+						exit(1);
+					return;
+				}
+				const { runApi } = await import("./contract/run");
+				const result = await runApi({ cwd: apiRoot });
+				console.log(`[ojm-api] 契约 ${result.contracts} 份；写入 ${result.written.length} 个文件，跳过（未变）${result.skipped.length} 个；stub 新建 ${result.stubs.created} / 更新 ${result.stubs.updated} / 跳过 ${result.stubs.skipped}`);
+				for (const p of result.written)
+					console.log(`  + ${path.relative(apiRoot, p)}`);
+			};
+		case "info":
+			return async (opts: { all?: boolean } = {}) => {
+				const { printInfo } = await import("./info");
+				await printInfo(projectRoot, undefined, { all: !!opts.all });
+			};
+		case "vendor":
+			return async (tag?: string, opts: { force?: boolean } = {}) => {
+				if (tag !== undefined && !/^v?\d+\.\d+\.\d+(?:-[\w.]+)?$/.test(tag))
+					throw new Error(`[ojm] 非法版本号：${tag}（形如 v0.1.11 或 0.1.11）`);
+				const { vendorCommand } = await import("./vendor");
+				await vendorCommand(projectRoot, { force: !!opts.force, tag: tag === undefined ? undefined : (tag.startsWith("v") ? tag : `v${tag}`) });
+			};
+		case "merge":
+			return async (out?: string, inputs: string[] = []) => {
+				const { mergeManifests } = await import("./info");
+				await mergeManifests(out ?? "", inputs);
+			};
+		case "keygen":
+			return async (opts: { id?: string, out?: string, yes?: boolean } = {}) => {
+				const { keygenCommand } = await import("./keygen");
+				keygenCommand({ id: opts.id, out: opts.out, yes: opts.yes });
+			};
+		case "sign":
+			return async (file: string | undefined, opts: { id?: string, key?: string, check?: boolean } = {}) => {
+				const { signCommand } = await import("./sign");
+				signCommand(file ?? "", { id: opts.id, key: opts.key, check: opts.check });
+			};
+		case "publish":
+			return async (dir: string | undefined, opts: { id?: string, key?: string, check?: boolean } = {}) => {
+				const { publishCommand } = await import("./publish");
+				publishCommand(dir ?? "", { id: opts.id, key: opts.key, check: opts.check });
+			};
+		case "install":
+			return async (target: string | undefined, opts: SiteOpts & { locale?: string, name?: string, version?: string } = {}) => {
+				const { installCommand } = await import("./install");
+				await installCommand(target ?? "", { url: opts.url, user: opts.user, pass: opts.pass, locale: opts.locale, name: opts.name, version: opts.version });
+			};
+		case "enable":
+		case "disable":
+			return async (name: string | undefined, opts: SiteOpts = {}) => {
+				const { setEnabledCommand } = await import("./enable");
+				await setEnabledCommand(name ?? "", def.key === "enable", { url: opts.url, user: opts.user, pass: opts.pass });
+			};
+		case "uninstall":
+			return async (name: string | undefined, opts: SiteOpts = {}) => {
+				const { uninstallCommand } = await import("./uninstall");
+				await uninstallCommand(name ?? "", { url: opts.url, user: opts.user, pass: opts.pass });
+			};
+		case "trust":
+			return async (sub: string | undefined, keyId: string | undefined, pub: string | undefined, opts: SiteOpts & { task?: string } = {}) => {
+				const { trustCommand } = await import("./trust");
+				await trustCommand(sub ?? "", [keyId, pub].filter((v): v is string => v !== undefined), { url: opts.url, user: opts.user, pass: opts.pass, task: opts.task });
+			};
+		case "market":
+			return async (sub: string | undefined) => {
+				if (!sub) {
+					// bare `ojm market`：打印该组帮助（子命令索引），同旧 marketUsage 语义
+					console.log(groupHelpText("market-cdn", lang));
+					return;
+				}
+				// market 子命令自带解析器（trial/walkthrough 等 flag 各异）：raw 转发 process.argv
+				const { marketCommand } = await import("./market/command");
+				await marketCommand(sub, process.argv.slice(4));
+			};
+		case "oj":
+			return async () => {
+				// 透传：参数原样转发（process.argv 未被 help 词形改写污染——真实调用才走到这里）
+				const { runOjSubcommand } = await import("./oj-cmd");
+				runOjSubcommand(projectRoot, def.name, process.argv.slice(3));
+			};
+		default:
+			throw new Error(`[ojm] 未接线的命令键：${def.key}`);
+	}
+}
+
+export function buildCli(projectRoot: string, lang: Lang = resolveLang(), deps: CliDeps = {}): CAC {
+	const exit = deps.exit ?? ((code: number) => process.exit(code) as never);
+	const cli = cac("ojm");
+	for (const group of HELP_GROUPS) {
+		for (const def of group.commands) {
+			const cmd = cli.command(def.name, lang === "zh-CN" ? def.zh : def.en);
+			for (const o of def.options ?? [])
+				cmd.option(o.raw, lang === "zh-CN" ? o.zh : o.en);
+			if (def.allowUnknownOptions)
+				cmd.allowUnknownOptions();
+			const action = makeAction(def, projectRoot, lang, exit);
+			cmd.action((...args: unknown[]) => {
+				Promise.resolve(action(...args)).catch((error: unknown) => reportCliError(error, exit));
+			});
+		}
+	}
+
+	// help 回调：顶层 = 分组 sections；单命令 = 本地化小节标题 + 详解/子命令详解注入
+	const SECTION_TITLES: Record<string, { zh: string, en: string }> = {
+		Usage: { zh: "用法", en: "Usage" },
+		Options: { zh: "选项", en: "Options" },
+		Examples: { zh: "示例", en: "Examples" },
+	};
+	cli.help((sections) => {
+		const matched = cli.matchedCommand;
+		if (!matched)
+			return topHelpSections(lang);
+		const def = findCommand(matched.rawName);
+		const out = sections.map((s) => {
+			const t = s.title && SECTION_TITLES[s.title];
+			return t ? { ...s, title: lang === "zh-CN" ? t.zh : t.en } : s;
+		});
+		if (def?.detail)
+			out.push({ title: lang === "zh-CN" ? "详细说明" : "Details", body: lang === "zh-CN" ? def.detail.zh : def.detail.en });
+		const sub = cli.args[0];
+		if (def?.subs && sub && def.subs[sub])
+			out.push({ title: `${sub}:`, body: lang === "zh-CN" ? def.subs[sub].zh : def.subs[sub].en });
+		return out;
+	});
+	return cli;
+}

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/contract/check.ts

@@ -18,7 +18,7 @@ import { findOpenapiJson, groupIrByModule } from "./run";
  * ① 生成物同步：内存重生成 vs 磁盘逐字节 diff（含 stub 待更新）
  * ② route 双向对账：AST 扫 oj api.ts（default 导出方法名 + 语句起始 `.route = "..."` 赋值）
  *    vs 契约路由表：未实现 warn / 未登记 error / 参数段不一致 error
- * ③ routes.js diff：release 路由表（oj build 产物，api/dist 下各模块的 routes.js）vs openapi.json
+ * ③ routes.js diff：release 路由表（oj build 产物，dist/api 下各模块的 routes.js）vs openapi.json
  *   契约路由表；无 dist 给提示不判违规
  *
  * 原则：check 永不修文件——修复动作永远由人执行（重跑 ojm api / 补 handler / oj build）。
@@ -360,8 +360,8 @@ export async function checkApi(opts: { cwd: string, exempt?: string }): Promise<
 	// ④ WS 路由鉴权对账（oj 0.1.30 起握手过鉴权守卫）
 	violations.push(...checkWsAnonymous(roots, resolveConfigPath(opts.cwd)));
 
-	// ③ routes.js diff
-	const distDir = join(opts.cwd, "api/dist");
+	// ③ routes.js diff（release 路由表读 layout.apiDist；无布局工程回退同一约定 dist/api）
+	const distDir = tryResolveLayout(opts.cwd)?.apiDist ?? join(opts.cwd, "dist", "api");
 	const distRows: { method: string, pattern: string }[] = [];
 	if (existsSync(distDir)) {
 		for (const entry of readdirSync(distDir, { withFileTypes: true })) {
@@ -373,7 +373,7 @@ export async function checkApi(opts: { cwd: string, exempt?: string }): Promise<
 		}
 	}
 	if (distRows.length === 0) {
-		hints.push("[ojm-api] 未发现 api/dist/**/routes.js——release 路由表对账跳过；发布前请先 oj build 再跑 ojm api --check。");
+		hints.push(`[ojm-api] 未发现 ${relative(opts.cwd, distDir)}/**/routes.js——release 路由表对账跳过；发布前请先 oj build 再跑 ojm api --check。`);
 	}
 	else {
 		// 尾斜杠规范化：契约侧 fullPath 对「模块根路径」带尾斜杠（stripBase 的

package/src/dev.ts

@@ -35,6 +35,7 @@ import { loadProjectMocks, mockStatusCode } from "./dev-mock";
 import { createReloadHub, proxyApi, proxyWsUpgrade, sseScript } from "./dev-proxy";
 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";
@@ -123,6 +124,16 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 
 	const hub = createReloadHub();
 
+	// /cdn 反代（feature：market_cdn_url 可为相对路径 = 本站点自供）：config 有 /cdn 挂载
+	// 才反代到 oj；无挂载（旧模板/手改工程）或纯前端形态 → 回落静态，行为不变
+	let cdnPrefix: string | null = null;
+	try {
+		cdnPrefix = resolveCdnLayout(projectRoot).prefix;
+	}
+	catch {
+		cdnPrefix = null;
+	}
+
 	// 3) 静态半边（dev：模块产物优先，shell dist 兜底；no-store；注入刷新通道）
 	// hostRoots 钉死 shell dist：ojm build 的合并残留不得反向遮蔽宿主（F11）
 	// transform 来自 web.config.ts（可选）：按路由改写 title/OG，先于 reload 注入
@@ -175,6 +186,12 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 			return;
 		}
 
+		// 相对基址 CDN（/cdn）：站点自供挂载直发 oj（不剥前缀），否则静态层会回落成 index.html
+		if (cdnPrefix !== null && ojTarget !== undefined && (urlPath === cdnPrefix || urlPath.startsWith(`${cdnPrefix}/`))) {
+			void proxyApi(ojTarget)(req, res);
+			return;
+		}
+
 		serveStatic(req, res);
 	});
 
@@ -294,6 +311,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 +320,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 +357,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 +424,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 +474,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);