kcode-pi 0.1.4 → 0.1.6

package/README.md

@@ -15,6 +15,7 @@ KCode 不要求你单独安装全局 `pi` 命令，也不会修改用户全局 P
 - Node.js `>=22.19.0`
 - npm
 - Windows 推荐使用 Windows Terminal
+- 不需要安装 Python。KCode 随包工具使用 Node/TypeScript 实现；只有你自己的业务项目或外部脚本明确依赖 Python 时才需要另行安装。
 
 全局安装：
 
@@ -60,6 +61,12 @@ kcode context --refresh
 kcode doctor
 ```
 
+查看当前 KCode 版本：
+
+```powershell
+kcode version
+```
+
 启动工作环境：
 
 ```powershell
@@ -235,6 +242,16 @@ kcode context --refresh
 kcode doctor
 ```
 
+### `kcode version`
+
+显示当前 KCode package 版本、安装路径、随包 Pi CLI 版本和 Node 版本。
+
+```powershell
+kcode version
+kcode --version
+kcode -v
+```
+
 ### `kcode start`
 
 启动 KCode 工作环境。
@@ -394,11 +411,19 @@ kd_build            按产品画像执行或 dry-run 构建
 kd_debug            分析金蝶日志和堆栈
 ```
 
+这些工具不依赖本机 Python：
+
+- `kd_ksql_lint` 是内置 Node 静态检查器。
+- `kd_cosmic_config` 使用 Node 读取并校验 `ok-cosmic.json`。
+- `kd_cosmic_metadata` 使用 `ok-cosmic.json` 中的统一路由 API，并在当前项目 `.pi/kd/official-skills/` 下维护 JSON 缓存。
+- `kd_cosmic_api` 查询随包金蝶知识库；需要精确方法签名时，仍要结合当前项目 SDK、编译输出或红绿证据确认。
+
 ## 升级
 
 查看当前安装版本：
 
 ```powershell
+kcode version
 npm ls -g kcode-pi --depth=0
 ```
 
@@ -514,6 +539,23 @@ notepad $env:USERPROFILE\.pi\agent\settings.json
 }
 ```
 
+### Windows 下出现 `/mnt/d/...` 找不到文件
+
+现象：
+
+```text
+read /mnt/d/projects/xxx/src/main/java/Foo.java
+ENOENT: no such file or directory, access 'D:\mnt\d\projects\xxx\src\main\java\Foo.java'
+```
+
+原因是当前运行环境是 Windows，但 LLM 或工具把 Windows 路径误写成了 WSL/MSYS 风格路径。正确做法：
+
+- 优先使用项目相对路径，例如 `code/fi/module/src/main/java/.../Foo.java`。
+- 如果必须使用绝对路径，在 Windows 下使用 `D:\projects\xxx\...`，不要使用 `/mnt/d/...` 或 `/d/...`。
+- 发现项目结构变化后运行 `kcode context --refresh`，让项目常驻上下文重新记录真实源码根。
+
+KCode Harness 会拦截常见 `/mnt/<drive>/...` 和 `/<drive>/...` 文件工具调用，并提示改用 Windows 路径或项目相对路径。
+
 ### 仍然加载旧版本 KCode
 
 先检查当前项目配置：

package/dist/cli/kcode.d.ts

@@ -12,5 +12,6 @@ export declare function runKcodeCli(args: string[], cwd?: string): KcodeCliResul
 export declare function initProject(cwd: string): KcodeCliResult;
 export declare function context(cwd: string, args: string[]): KcodeCliResult;
 export declare function doctor(cwd: string): KcodeCliResult;
+export declare function version(): KcodeCliResult;
 export declare function start(cwd: string, piArgs: string[]): KcodeCliResult;
 export declare function resolvePiCliCommand(piArgs?: string[]): PiCliCommand | undefined;

package/dist/cli/kcode.js

@@ -6,7 +6,9 @@ import { createRequire } from "node:module";
 import { ensureProjectContext, writeProjectContext } from "../context/project-context.js";
 const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 const require = createRequire(import.meta.url);
-const packageName = readPackageName(packageRoot) ?? "kcode-pi";
+const packageMetadata = readPackageMetadata(packageRoot);
+const packageName = packageMetadata.name ?? "kcode-pi";
+const packageVersion = packageMetadata.version ?? "unknown";
 export function runKcodeCli(args, cwd = process.cwd()) {
     const command = args[0] ?? "help";
     switch (command) {
@@ -16,6 +18,10 @@ export function runKcodeCli(args, cwd = process.cwd()) {
             return context(cwd, args.slice(1));
         case "doctor":
             return doctor(cwd);
+        case "version":
+        case "--version":
+        case "-v":
+            return version();
         case "start":
             return start(cwd, args.slice(1));
         case "help":
@@ -57,6 +63,7 @@ export function doctor(cwd) {
     const settingsPath = projectSettingsPath(cwd);
     lines.push(`Node：${node.status === 0 ? node.stdout.trim() : "未找到"}`);
     lines.push(`Pi CLI：${formatPiCliStatus(piCli, pi)}`);
+    lines.push(`KCode version：${packageName}@${packageVersion}`);
     lines.push(`KCode package：${packageRoot}`);
     lines.push(`项目配置：${existsSync(settingsPath) ? settingsPath : "未创建，请先运行 kcode init"}`);
     lines.push(`项目上下文：${existsSync(join(cwd, ".pi", "kd", "PROJECT_CONTEXT.md")) ? join(cwd, ".pi", "kd", "PROJECT_CONTEXT.md") : "未创建，请运行 kcode context"}`);
@@ -70,6 +77,19 @@ export function doctor(cwd) {
         output: lines.join("\n"),
     };
 }
+export function version() {
+    const piCli = resolvePiCliCommand(["--version"]);
+    const pi = piCli ? spawnSync(piCli.command, piCli.args, { encoding: "utf8" }) : undefined;
+    return {
+        exitCode: 0,
+        output: [
+            `${packageName}@${packageVersion}`,
+            `KCode package：${packageRoot}`,
+            `Pi CLI：${formatPiCliStatus(piCli, pi)}`,
+            `Node：${process.version}`,
+        ].join("\n"),
+    };
+}
 export function start(cwd, piArgs) {
     const init = initProject(cwd);
     const piCli = resolvePiCliCommand(piArgs);
@@ -127,12 +147,14 @@ function isSameKcodePackage(candidate, currentPackage) {
     return candidateName === packageName;
 }
 function readPackageName(packagePath) {
+    return readPackageMetadata(packagePath).name;
+}
+function readPackageMetadata(packagePath) {
     try {
-        const packageJson = JSON.parse(readFileSync(join(packagePath, "package.json"), "utf8"));
-        return packageJson.name;
+        return JSON.parse(readFileSync(join(packagePath, "package.json"), "utf8"));
     }
     catch {
-        return undefined;
+        return {};
     }
 }
 function packageNameFromPath(path) {
@@ -182,6 +204,7 @@ function helpText() {
         "  kcode init      初始化当前项目的 .pi/settings.json",
         "  kcode context   生成或刷新 .pi/kd/PROJECT_CONTEXT.md",
         "  kcode doctor    检查 Node、随包 Pi CLI、KCode package 和项目级配置",
+        "  kcode version   显示 KCode、随包 Pi CLI 和 Node 版本",
         "  kcode start     初始化项目配置后启动 KCode 工作环境",
     ].join("\n");
 }

package/dist/context/project-context.js

@@ -58,6 +58,7 @@ export function generateProjectContext(cwd) {
         "- This file is project memory for KCode. Read it before planning or editing code.",
         "- Do not create demo/sample/scaffold code for business requirements.",
         "- Do not assume module layout. Follow the actual paths below and verify target files before editing.",
+        "- Use project-relative paths when calling file tools. On Windows, do not rewrite paths to /mnt/<drive>/... or /<drive>/...; use Windows paths only when an absolute path is necessary.",
         "- If this file is stale, regenerate with `kcode context --refresh` before planning.",
         "- Write product code only after the Harness reaches `execute` and PLAN.md names the real target path.",
         "",

package/docs/DEVELOPMENT.md

@@ -43,7 +43,7 @@ npm run smoke:kcode-cli
 - 金蝶知识库搜索。
 - `kd_check` 静态规则。
 - Harness 阶段和门禁。
-- 官方脚本适配器。
+- 官方能力 Node 适配器。
 - 构建/调试诊断。
 - package manifest、skills、vendor 文件完整性。
 - `kcode` 项目级入口逻辑。

package/extensions/kingdee-harness.ts

@@ -15,6 +15,7 @@ import { readArtifact } from "../src/harness/artifacts.ts";
 import { flagshipWriteBlockReason, isSourceLikePath, planWriteBlockReason } from "../src/harness/path-policy.ts";
 import { tddProductionWriteBlockReason } from "../src/harness/tdd-policy.ts";
 import { readProjectContext } from "../src/context/project-context.ts";
+import { windowsPathHint } from "../src/platform/path.ts";
 
 const KINGDEE_INTENT_PATTERN =
 	/金蝶|苍穹|星瀚|星空|旗舰|企业版|单据|表单|列表|插件|操作插件|校验器|反写|转换|工作流|基础资料|动态对象|DynamicObject|BOS|Cosmic|IronPython|Python\s*插件|py\s*插件|kd_|KSQL/i;
@@ -104,6 +105,7 @@ function workflowPromptForRun(cwd: string, run: NonNullable<ReturnType<typeof re
 		"",
 		phaseGuidance[run.phase],
 		"必须先理解当前业务项目已有目录、模块、包名、基类和本地封装，再决定文件位置和实现方式。",
+		"路径规则：在 Windows 工作区内，优先使用项目相对路径；如需绝对路径必须使用 `D:\\...` 这类 Windows 路径，禁止把路径改写成 `/mnt/d/...`、`/d/...` 等 WSL/MSYS 风格路径。",
 		"execute 阶段只能写 PLAN.md 明确列出的源码文件；如果目标文件不在计划内，必须先回到 plan 更新 PLAN.md。",
 		"写生产源码前必须先有红灯证据 evidence/tdd-red.md；红绿证据可以是 API/基类/方法签名、元数据、编译、既有测试框架或外部接口最小验证，不要为了测试引入额外 jar。",
 	].join("\n");
@@ -179,9 +181,17 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("tool_call", (event, ctx) => {
+		const input = event.input as Record<string, unknown>;
+		const path = typeof input.path === "string" ? input.path : undefined;
+		const hint = path ? windowsPathHint(path) : undefined;
+		if (hint && ["read", "write", "edit"].includes(event.toolName)) {
+			const reason = `当前是 Windows 工作区，不能使用 WSL/MSYS 路径 ${path}。请改用项目相对路径，或使用 Windows 路径 ${hint}。`;
+			if (ctx.hasUI) ctx.ui.notify(reason, "warning");
+			return { block: true, reason };
+		}
+
 		if (event.toolName !== "write" && event.toolName !== "edit") return undefined;
 
-		const path = typeof event.input.path === "string" ? event.input.path : undefined;
 		const reason = codeWriteBlockReason(ctx.cwd, path) ?? flagshipWriteBlockReason(readActiveRun(ctx.cwd), path, ctx.cwd);
 		if (!reason) return undefined;
 

package/extensions/kingdee-tools.ts

@@ -17,9 +17,10 @@ import {
 	type OfficialEvidenceFile,
 	isCosmicFamily,
 	ksqlLintCommand,
-	runCommand,
+	runOfficialCommand,
 	writeOfficialEvidence,
 } from "../src/official/kingdee-skills.ts";
+import { resolveWorkspacePath } from "../src/platform/path.ts";
 
 const extensionDir = dirname(fileURLToPath(import.meta.url));
 const knowledgePath = join(extensionDir, "..", "knowledge");
@@ -83,7 +84,7 @@ async function runOrDryRun(
 		};
 	}
 
-	const result = await runCommand(command);
+	const result = await runOfficialCommand(command);
 	const evidencePath = evidenceFile ? writeOfficialEvidence(ctx.cwd, evidenceFile, result) : undefined;
 	return {
 		content: [{ type: "text" as const, text: formatCommandResult(result) }],
@@ -194,7 +195,7 @@ const kdCheckTool = defineTool({
 		let source = "inline";
 
 		if (!code && params.path) {
-			const filePath = join(ctx.cwd, params.path);
+			const filePath = resolveWorkspacePath(ctx.cwd, params.path);
 			code = readFileSync(filePath, "utf8");
 			source = params.path;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Kingdee-specific package and harness for Pi Coding Agent",
   "type": "module",
   "private": false,

package/src/cli/kcode.ts

@@ -17,7 +17,9 @@ interface PiSettings {
 
 const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 const require = createRequire(import.meta.url);
-const packageName = readPackageName(packageRoot) ?? "kcode-pi";
+const packageMetadata = readPackageMetadata(packageRoot);
+const packageName = packageMetadata.name ?? "kcode-pi";
+const packageVersion = packageMetadata.version ?? "unknown";
 
 export interface PiCliCommand {
 	command: string;
@@ -36,6 +38,10 @@ export function runKcodeCli(args: string[], cwd = process.cwd()): KcodeCliResult
 			return context(cwd, args.slice(1));
 		case "doctor":
 			return doctor(cwd);
+		case "version":
+		case "--version":
+		case "-v":
+			return version();
 		case "start":
 			return start(cwd, args.slice(1));
 		case "help":
@@ -84,6 +90,7 @@ export function doctor(cwd: string): KcodeCliResult {
 
 	lines.push(`Node：${node.status === 0 ? node.stdout.trim() : "未找到"}`);
 	lines.push(`Pi CLI：${formatPiCliStatus(piCli, pi)}`);
+	lines.push(`KCode version：${packageName}@${packageVersion}`);
 	lines.push(`KCode package：${packageRoot}`);
 	lines.push(`项目配置：${existsSync(settingsPath) ? settingsPath : "未创建，请先运行 kcode init"}`);
 	lines.push(`项目上下文：${existsSync(join(cwd, ".pi", "kd", "PROJECT_CONTEXT.md")) ? join(cwd, ".pi", "kd", "PROJECT_CONTEXT.md") : "未创建，请运行 kcode context"}`);
@@ -100,6 +107,20 @@ export function doctor(cwd: string): KcodeCliResult {
 	};
 }
 
+export function version(): KcodeCliResult {
+	const piCli = resolvePiCliCommand(["--version"]);
+	const pi = piCli ? spawnSync(piCli.command, piCli.args, { encoding: "utf8" }) : undefined;
+	return {
+		exitCode: 0,
+		output: [
+			`${packageName}@${packageVersion}`,
+			`KCode package：${packageRoot}`,
+			`Pi CLI：${formatPiCliStatus(piCli, pi)}`,
+			`Node：${process.version}`,
+		].join("\n"),
+	};
+}
+
 export function start(cwd: string, piArgs: string[]): KcodeCliResult {
 	const init = initProject(cwd);
 	const piCli = resolvePiCliCommand(piArgs);
@@ -168,11 +189,14 @@ function isSameKcodePackage(candidate: string, currentPackage: string): boolean
 }
 
 function readPackageName(packagePath: string): string | undefined {
+	return readPackageMetadata(packagePath).name;
+}
+
+function readPackageMetadata(packagePath: string): { name?: string; version?: string } {
 	try {
-		const packageJson = JSON.parse(readFileSync(join(packagePath, "package.json"), "utf8")) as { name?: string };
-		return packageJson.name;
+		return JSON.parse(readFileSync(join(packagePath, "package.json"), "utf8")) as { name?: string; version?: string };
 	} catch {
-		return undefined;
+		return {};
 	}
 }
 
@@ -229,6 +253,7 @@ function helpText(): string {
 		"  kcode init      初始化当前项目的 .pi/settings.json",
 		"  kcode context   生成或刷新 .pi/kd/PROJECT_CONTEXT.md",
 		"  kcode doctor    检查 Node、随包 Pi CLI、KCode package 和项目级配置",
+		"  kcode version   显示 KCode、随包 Pi CLI 和 Node 版本",
 		"  kcode start     初始化项目配置后启动 KCode 工作环境",
 	].join("\n");
 }

package/src/context/project-context.ts

@@ -70,6 +70,7 @@ export function generateProjectContext(cwd: string): string {
 		"- This file is project memory for KCode. Read it before planning or editing code.",
 		"- Do not create demo/sample/scaffold code for business requirements.",
 		"- Do not assume module layout. Follow the actual paths below and verify target files before editing.",
+		"- Use project-relative paths when calling file tools. On Windows, do not rewrite paths to /mnt/<drive>/... or /<drive>/...; use Windows paths only when an absolute path is necessary.",
 		"- If this file is stale, regenerate with `kcode context --refresh` before planning.",
 		"- Write product code only after the Harness reaches `execute` and PLAN.md names the real target path.",
 		"",

package/src/official/kingdee-skills.ts

@@ -1,11 +1,14 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 import type { ProductProfile } from "../product/profile.ts";
 import { readActiveRun } from "../harness/state.ts";
 import { runArtifactPath } from "../harness/paths.ts";
+import { searchKnowledge } from "../knowledge/search.ts";
+import { formatSearchResults } from "../knowledge/format.ts";
+import { resolveWorkspacePath } from "../platform/path.ts";
 
 const execFileAsync = promisify(execFile);
 
@@ -25,6 +28,11 @@ export interface CommandResult {
 	stderr: string;
 }
 
+export interface OfficialCommand {
+	display: string;
+	run: () => Promise<CommandResult>;
+}
+
 export type OfficialEvidenceFile = "cosmic-config.txt" | "cosmic-metadata.json" | "cosmic-api.txt" | "ksql-lint.txt";
 
 const SKILL_DIRS: Record<OfficialSkillKey, string> = {
@@ -63,25 +71,6 @@ export async function ensureOfficialSkillRoot(_cwd: string, skill: OfficialSkill
 	throw new Error(`Official skill directory not found for ${skill}. Checked: ${officialSkillsSourceRoots().join(", ")}`);
 }
 
-export function resolveWorkspacePath(cwd: string, path: string): string {
-	return isAbsolute(path) ? path : resolve(cwd, path);
-}
-
-export function pythonExecutable(): string {
-	return process.env.KCODE_PYTHON ?? (process.platform === "win32" ? "python" : "python3");
-}
-
-export function buildPythonCommand(cwd: string, scriptPath: string, args: string[]): CommandSpec {
-	const executable = pythonExecutable();
-	const fullArgs = [scriptPath, ...args];
-	return {
-		executable,
-		args: fullArgs,
-		cwd,
-		display: formatCommand(executable, fullArgs),
-	};
-}
-
 export async function runCommand(command: CommandSpec, timeoutMs = 120_000): Promise<CommandResult> {
 	try {
 		const result = await execFileAsync(command.executable, command.args, {
@@ -113,11 +102,15 @@ export async function runCommand(command: CommandSpec, timeoutMs = 120_000): Pro
 	}
 }
 
-export async function cosmicConfigCommand(cwd: string, config?: string): Promise<CommandSpec> {
-	const root = await ensureOfficialSkillRoot(cwd, "ok-cosmic");
-	const script = join(root, "scripts", "cosmic-config-check.py");
-	const args = config ? ["--config", resolveWorkspacePath(cwd, config)] : [];
-	return buildPythonCommand(cwd, script, args);
+export async function runOfficialCommand(command: OfficialCommand): Promise<CommandResult> {
+	return command.run();
+}
+
+export async function cosmicConfigCommand(cwd: string, config?: string): Promise<OfficialCommand> {
+	await ensureOfficialSkillRoot(cwd, "ok-cosmic");
+	const configPath = resolveConfigPath(cwd, config);
+	const display = formatCommand("kcode-node:cosmic-config", config ? ["--config", configPath] : []);
+	return officialCommand(display, () => runCosmicConfig(cwd, configPath));
 }
 
 export async function cosmicMetadataCommand(
@@ -131,16 +124,16 @@ export async function cosmicMetadataCommand(
 		op?: boolean;
 		showDetail?: boolean;
 	},
-): Promise<CommandSpec> {
-	const root = await ensureOfficialSkillRoot(cwd, "ok-cosmic");
-	const script = join(root, "scripts", "cosmic-form-metadata.py");
+): Promise<OfficialCommand> {
+	await ensureOfficialSkillRoot(cwd, "ok-cosmic");
 	const args = withConfig(["get", params.form], cwd, params.config);
 	if (params.sql) args.push("--sql");
 	if (params.op) args.push("--op");
 	if (params.showDetail) args.push("--show-detail");
 	if (params.fuzzy) args.push("--fuzzy", ...splitTerms(params.fuzzy));
 	if (params.typeFilter) args.push("--type", params.typeFilter);
-	return buildPythonCommand(cwd, script, args);
+	const configPath = resolveConfigPath(cwd, params.config);
+	return officialCommand(formatCommand("kcode-node:cosmic-metadata", args), () => runCosmicMetadata(cwd, configPath, params));
 }
 
 export async function cosmicApiCommand(
@@ -152,19 +145,18 @@ export async function cosmicApiCommand(
 		method?: string;
 		compact?: boolean;
 	},
-): Promise<CommandSpec> {
-	const root = await ensureOfficialSkillRoot(cwd, "ok-cosmic");
-	const script = join(root, "scripts", "cosmic-api-knowledge.py");
+): Promise<OfficialCommand> {
+	await ensureOfficialSkillRoot(cwd, "ok-cosmic");
 	const args = withConfig([params.mode, params.query], cwd, params.config);
 	if (params.method) args.push("--method", params.method);
 	if (params.compact) args.push("--compact");
-	return buildPythonCommand(cwd, script, args);
+	return officialCommand(formatCommand("kcode-node:cosmic-api", args), () => runCosmicApi(cwd, params));
 }
 
-export async function ksqlLintCommand(cwd: string, path: string): Promise<CommandSpec> {
-	const root = await ensureOfficialSkillRoot(cwd, "ok-ksql");
-	const script = join(root, "scripts", "ksql_lint.py");
-	return buildPythonCommand(cwd, script, [resolveWorkspacePath(cwd, path)]);
+export async function ksqlLintCommand(cwd: string, path: string): Promise<OfficialCommand> {
+	await ensureOfficialSkillRoot(cwd, "ok-ksql");
+	const resolvedPath = resolveWorkspacePath(cwd, path);
+	return officialCommand(formatCommand("kcode-node:ksql-lint", [resolvedPath]), () => runKsqlLint(resolvedPath));
 }
 
 export function formatCommandResult(result: CommandResult): string {
@@ -208,6 +200,525 @@ function formatJsonEvidence(evidenceFile: OfficialEvidenceFile, result: CommandR
 	)}\n`;
 }
 
+function officialCommand(display: string, run: () => Promise<Omit<CommandResult, "command">>): OfficialCommand {
+	return {
+		display,
+		run: async () => {
+			try {
+				const result = await run();
+				return { command: display, ...result };
+			} catch (error) {
+				return {
+					command: display,
+					exitCode: 1,
+					stdout: "",
+					stderr: error instanceof Error ? error.message : String(error),
+				};
+			}
+		},
+	};
+}
+
+function resolveConfigPath(cwd: string, config?: string): string {
+	return config ? resolveWorkspacePath(cwd, config) : resolve(cwd, "ok-cosmic.json");
+}
+
+function readJsonObject(path: string): Record<string, unknown> {
+	const data = JSON.parse(readFileSync(path, "utf8")) as unknown;
+	if (!data || typeof data !== "object" || Array.isArray(data)) {
+		throw new Error(`配置文件格式错误: ${path} 必须包含 JSON Object`);
+	}
+	return data as Record<string, unknown>;
+}
+
+async function runCosmicConfig(_cwd: string, configPath: string): Promise<Omit<CommandResult, "command">> {
+	const issues: Array<{ level: "OK" | "WARNING" | "ERROR"; key: string; message: string }> = [];
+	issues.push({ level: "OK", key: "runtime.node", message: `Node ${process.version}` });
+
+	let config: Record<string, unknown> | undefined;
+	try {
+		if (!existsSync(configPath)) throw new Error(`找不到配置文件: ${configPath}`);
+		config = readJsonObject(configPath);
+		issues.push({ level: "OK", key: "__file__", message: `已找到配置文件: ${configPath}` });
+	} catch (error) {
+		issues.push({ level: "ERROR", key: "__file__", message: error instanceof Error ? error.message : String(error) });
+	}
+
+	if (config) issues.push(...validateCosmicConfig(config, dirname(configPath)));
+	const errors = issues.filter((issue) => issue.level === "ERROR").length;
+	const warnings = issues.filter((issue) => issue.level === "WARNING").length;
+	const lines = issues.map((issue) => `[${issue.level}] ${issue.key}: ${issue.message}`);
+	lines.push(`[SUMMARY] errors=${errors} warnings=${warnings}`);
+	return { exitCode: errors ? 1 : 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
+}
+
+function validateCosmicConfig(config: Record<string, unknown>, baseDir: string): Array<{ level: "OK" | "WARNING" | "ERROR"; key: string; message: string }> {
+	const issues: Array<{ level: "OK" | "WARNING" | "ERROR"; key: string; message: string }> = [];
+	const graph = objectValue(config.graph);
+	if (!graph) {
+		issues.push({ level: "ERROR", key: "graph", message: "缺少 `graph` 配置对象。" });
+	} else {
+		const dbPath = stringValue(graph.dbPath);
+		if (!dbPath) {
+			issues.push({ level: "ERROR", key: "graph.dbPath", message: "缺少必填项 `graph.dbPath`。" });
+		} else {
+			const resolved = resolveWorkspacePath(baseDir, dbPath);
+			issues.push({
+				level: existsSync(resolved) ? "OK" : "WARNING",
+				key: "graph.dbPath",
+				message: existsSync(resolved) ? `知识库路径: ${resolved}` : `graph.dbPath 指向的文件不存在: ${resolved}`,
+			});
+		}
+	}
+
+	const route = objectValue(config.route);
+	const routeUrl = stringValue(route?.apiUrl) || process.env.COSMIC_ROUTE_API || process.env.COSMIC_RUNTIME_ROUTE_API || "";
+	if (!route && !routeUrl) {
+		issues.push({ level: "WARNING", key: "route", message: "缺少 `route` 配置节，统一路由在线查询不可用。" });
+	} else if (!routeUrl) {
+		issues.push({ level: "WARNING", key: "route.apiUrl", message: "`route.apiUrl` 为空，统一路由在线查询不可用。" });
+	} else {
+		issues.push({ level: "OK", key: "route.apiUrl", message: "统一路由 API 已配置。" });
+	}
+
+	const extensionRepos = config.extensionRepos;
+	if (extensionRepos !== undefined) {
+		if (!Array.isArray(extensionRepos)) {
+			issues.push({ level: "ERROR", key: "extensionRepos", message: "`extensionRepos` 必须是字符串数组。" });
+		} else {
+			extensionRepos.forEach((raw, index) => {
+				const value = typeof raw === "string" ? raw.trim() : "";
+				const key = `extensionRepos[${index}]`;
+				if (!value) {
+					issues.push({ level: "ERROR", key, message: `${key} 必须是非空字符串路径。` });
+					return;
+				}
+				const resolved = resolveWorkspacePath(baseDir, value);
+				issues.push({
+					level: existsSync(resolved) ? "OK" : "WARNING",
+					key,
+					message: existsSync(resolved) ? `扩展代码库: ${resolved}` : `扩展代码库路径不存在或不是目录: ${resolved}`,
+				});
+			});
+		}
+	}
+
+	return issues;
+}
+
+async function runCosmicMetadata(
+	cwd: string,
+	configPath: string,
+	params: { form: string; fuzzy?: string; typeFilter?: string; sql?: boolean; op?: boolean; showDetail?: boolean },
+): Promise<Omit<CommandResult, "command">> {
+	const config = readJsonObject(configPath);
+	const cache = readMetadataCache(cwd);
+	const targets = params.form.split(/[,，]/).map((item) => item.trim()).filter(Boolean);
+	if (targets.length === 0) return { exitCode: 1, stdout: "", stderr: "必须提供 formId 或中文单据名。" };
+
+	const outputs: string[] = [];
+	for (const target of targets) {
+		const cached = findCachedMetadata(cache, target);
+		const payload = cached ?? (await fetchMetadata(config, target));
+		const formId = stringValue(objectValue(payload.form)?.formId) || stringValue(payload.formId) || target;
+		cache[formId] = { payload, updatedAt: Date.now() };
+		outputs.push(formatMetadata(target, payload, params, cached ? "cache" : "route"));
+	}
+	writeMetadataCache(cwd, cache);
+	return { exitCode: 0, stdout: `${outputs.join("\n\n---\n\n")}\n`, stderr: "" };
+}
+
+async function fetchMetadata(config: Record<string, unknown>, target: string): Promise<Record<string, unknown>> {
+	const route = objectValue(config.route);
+	const routeUrl = routeUrlFromConfig(route);
+	if (!routeUrl) {
+		throw new Error("未配置表单元数据查询 API。请在 ok-cosmic.json 的 route.apiUrl 中配置统一路由，或设置 COSMIC_ROUTE_API。");
+	}
+
+	const hasCjk = /[\u3400-\u9fff]/.test(target);
+	const response = await postRoute(routeUrl, route, {
+		data: {
+			type: "meta",
+			reqData: {
+				entityId: hasCjk ? "" : target,
+				formId: hasCjk ? "" : target,
+				billName: hasCjk ? target : "",
+				full: true,
+			},
+		},
+	});
+	if (response.status === false) throw new Error(`接口请求失败: ${stringValue(response.message) || "未知错误"}`);
+	const data = response.status === true && response.data !== undefined ? unwrapRoutePayload(response.data) : unwrapRoutePayload(response);
+	if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error("元数据接口返回格式不是 JSON Object。");
+	return data as Record<string, unknown>;
+}
+
+async function postRoute(url: string, route: Record<string, unknown> | undefined, body: unknown): Promise<Record<string, unknown>> {
+	const headers: Record<string, string> = { "Content-Type": "application/json" };
+	const token = stringValue(route?.apiToken) || stringValue(route?.token) || process.env.COSMIC_ROUTE_TOKEN || "";
+	if (token) headers.Authorization = `Bearer ${token}`;
+	const timeoutSeconds = Number(route?.timeoutSeconds ?? process.env.COSMIC_ROUTE_TIMEOUT ?? 10);
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), Math.max(1, timeoutSeconds) * 1000);
+	try {
+		const response = await fetch(url, { method: "POST", headers, body: JSON.stringify(body), signal: controller.signal });
+		const text = await response.text();
+		if (!response.ok) throw new Error(`HTTP ${response.status}: ${text.slice(0, 500)}`);
+		const parsed = JSON.parse(text) as unknown;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("远程接口返回的根对象不是 JSON Object。");
+		return parsed as Record<string, unknown>;
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+
+function routeUrlFromConfig(route: Record<string, unknown> | undefined): string {
+	let url = stringValue(route?.apiUrl) || process.env.COSMIC_ROUTE_API || process.env.COSMIC_RUNTIME_ROUTE_API || "";
+	const sign = stringValue(route?.openApiSign) || stringValue(route?.openapiSign) || process.env.COSMIC_ROUTE_OPEN_API_SIGN || process.env.COSMIC_OPEN_API_SIGN || "";
+	if (url && sign && !/[?&]openApiSign=/.test(url)) url += `${url.includes("?") ? "&" : "?"}openApiSign=${encodeURIComponent(sign)}`;
+	return url;
+}
+
+function unwrapRoutePayload(value: unknown): unknown {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+	const obj = value as Record<string, unknown>;
+	if (obj.form || obj.formFields || obj.entityFields || obj.code === "MULTI_MATCH" || obj.code === "BILL_NOT_FOUND") return obj;
+	for (const key of ["data", "result", "respData", "response"]) {
+		const nested = unwrapRoutePayload(obj[key]);
+		if (nested && typeof nested === "object" && !Array.isArray(nested)) return nested;
+	}
+	return obj;
+}
+
+type MetadataCache = Record<string, { payload: Record<string, unknown>; updatedAt: number }>;
+
+function metadataCachePath(cwd: string): string {
+	return join(officialSkillsCacheRoot(cwd), "cosmic-form-metadata-cache.json");
+}
+
+function readMetadataCache(cwd: string): MetadataCache {
+	const path = metadataCachePath(cwd);
+	if (!existsSync(path)) return {};
+	try {
+		return JSON.parse(readFileSync(path, "utf8")) as MetadataCache;
+	} catch {
+		return {};
+	}
+}
+
+function writeMetadataCache(cwd: string, cache: MetadataCache): void {
+	const path = metadataCachePath(cwd);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+}
+
+function findCachedMetadata(cache: MetadataCache, target: string): Record<string, unknown> | undefined {
+	const direct = cache[target]?.payload;
+	if (direct) return direct;
+	for (const entry of Object.values(cache)) {
+		const form = objectValue(entry.payload.form);
+		const names = [form?.formId, form?.id, form?.formName, form?.name, form?.title].map(stringValue);
+		if (names.includes(target)) return entry.payload;
+	}
+	return undefined;
+}
+
+function formatMetadata(
+	target: string,
+	payload: Record<string, unknown>,
+	params: { fuzzy?: string; typeFilter?: string; sql?: boolean; op?: boolean; showDetail?: boolean },
+	source: "cache" | "route",
+): string {
+	const form = objectValue(payload.form) ?? {};
+	const fields = [...arrayObjects(payload.formFields), ...arrayObjects(payload.entityFields)];
+	const operations = arrayObjects(payload.operateMetas).length ? arrayObjects(payload.operateMetas) : arrayObjects(payload.buttons);
+	const formName = stringValue(form.formName) || stringValue(form.name) || stringValue(form.title) || target;
+	const formId = stringValue(form.formId) || stringValue(form.id) || stringValue(form.key) || target;
+	const dbName = stringValue(form.dbName) || "-";
+	const dbTable = stringValue(form.dbTableName) || stringValue(form.dbTableKey) || "-";
+
+	if (params.op) {
+		const ops = filterObjects(operations, params.fuzzy);
+		return [`## [Op] 操作查询: ${formName} (${formId})`, "", "| 名称 | 标识 | 类型 |", "| :--- | :--- | :--- |", ...ops.map((op) => `| ${stringValue(op.name) || stringValue(op.opName) || "-"} | \`${stringValue(op.key) || stringValue(op.opKey) || "-"}\` | ${stringValue(op.type) || stringValue(op.opType) || "-"} |`)].join("\n");
+	}
+
+	const filtered = filterObjects(fields, params.fuzzy).filter((field) => {
+		if (!params.typeFilter) return true;
+		return matchesText(stringValue(field.type), params.typeFilter);
+	});
+	const selected = filtered.length ? filtered : fields.slice(0, 120);
+	const lines = [
+		`## [Meta] ${formName} (${formId})`,
+		`**来源**: ${source === "cache" ? "KCode 本地 JSON 缓存" : "统一路由 API"}`,
+		`**表**: dbName=\`${dbName}\`, dbTable=\`${dbTable}\``,
+		"",
+	];
+	if (params.sql) {
+		lines.push("| 名称 | 标识 | 类型 | 表名 | 数据库字段 |");
+		lines.push("| :--- | :--- | :--- | :--- | :--- |");
+		for (const field of selected) {
+			lines.push(`| ${stringValue(field.name) || "-"} | \`${stringValue(field.key) || "-"}\` | ${stringValue(field.type) || "-"} | \`${fieldTable(field, form)}\` | \`${stringValue(field.dbKey) || "-"}\` |`);
+		}
+		return lines.join("\n");
+	}
+
+	lines.push("| 名称 | 标识 | 类型 | 附加信息 |");
+	lines.push("| :--- | :--- | :--- | :--- |");
+	for (const field of selected) {
+		const detail = params.showDetail ? fieldDetail(field) : stringValue(field.dbKey) || stringValue(field.refType) || "-";
+		lines.push(`| ${stringValue(field.name) || "-"} | \`${stringValue(field.key) || "-"}\` | ${stringValue(field.type) || "-"} | ${detail} |`);
+	}
+	return lines.join("\n");
+}
+
+function runCosmicApi(cwd: string, params: { mode: "search" | "search-method" | "detail"; query: string; method?: string; compact?: boolean }): Promise<Omit<CommandResult, "command">> {
+	const knowledgePath = join(packageRoot, "knowledge");
+	const query = params.mode === "detail" && params.method ? `${params.query} ${params.method}` : params.query;
+	const results = searchKnowledge(query, { scopes: ["cosmic", "cangqiong", "xinghan", "flagship"], topK: params.compact ? 5 : 10, minScore: 1 }, knowledgePath);
+	const header = [
+		`KCode Node Cosmic API query (${params.mode})`,
+		"说明: 当前 npm 包不再调用 Python/SQLite 脚本；这里查询随包金蝶知识库。需要精确方法签名时，请优先结合项目 SDK/编译输出做红绿验证。",
+		"",
+	].join("\n");
+	const stdout = `${header}${formatSearchResults(query, results, knowledgePath)}\n`;
+	return Promise.resolve({ exitCode: results.length ? 0 : 1, stdout, stderr: results.length ? "" : "未在随包知识库找到匹配 API 线索。" });
+}
+
+function runKsqlLint(path: string): Promise<Omit<CommandResult, "command">> {
+	if (!existsSync(path)) return Promise.resolve({ exitCode: 2, stdout: "", stderr: `${path}:1: ERROR: 文件不存在。\n` });
+	const rawSql = readFileSync(path, "utf8");
+	const findings = [...lintTimestamps(path, rawSql), ...iterStatements(stripCommentsAndLiterals(rawSql)).flatMap(lintStatement)].sort((a, b) => a.line - b.line || a.severity.localeCompare(b.severity));
+	const lines = findings.map((finding) => `${path}:${finding.line}: ${finding.severity}: ${finding.message}`);
+	const errorCount = findings.filter((finding) => finding.severity === "ERROR").length;
+	const warnCount = findings.filter((finding) => finding.severity === "WARN").length;
+	lines.push(`SUMMARY: ${errorCount} error(s), ${warnCount} warning(s)`);
+	return Promise.resolve({ exitCode: errorCount ? 1 : 0, stdout: `${lines.join("\n")}\n`, stderr: "" });
+}
+
+interface KsqlFinding {
+	severity: "ERROR" | "WARN";
+	line: number;
+	message: string;
+}
+
+interface KsqlStatement {
+	text: string;
+	line: number;
+}
+
+function stripCommentsAndLiterals(sql: string): string {
+	let out = "";
+	let i = 0;
+	let state: "normal" | "line" | "block" | "single" | "double" | "dollar" = "normal";
+	let dollarTag = "";
+	while (i < sql.length) {
+		const ch = sql[i];
+		const next = sql[i + 1] ?? "";
+		if (state === "normal") {
+			if (ch === "-" && next === "-") {
+				out += "  ";
+				i += 2;
+				state = "line";
+				continue;
+			}
+			if (ch === "/" && next === "*") {
+				out += "  ";
+				i += 2;
+				state = "block";
+				continue;
+			}
+			if (ch === "'") {
+				out += " ";
+				i++;
+				state = "single";
+				continue;
+			}
+			if (ch === '"') {
+				out += " ";
+				i++;
+				state = "double";
+				continue;
+			}
+			if (ch === "$") {
+				const match = sql.slice(i).match(/^\$[A-Za-z_][A-Za-z0-9_]*\$|^\$\$/);
+				if (match) {
+					dollarTag = match[0];
+					out += " ".repeat(dollarTag.length);
+					i += dollarTag.length;
+					state = "dollar";
+					continue;
+				}
+			}
+			out += ch;
+			i++;
+			continue;
+		}
+		if (state === "line") {
+			out += ch === "\n" ? "\n" : " ";
+			i++;
+			if (ch === "\n") state = "normal";
+			continue;
+		}
+		if (state === "block") {
+			if (ch === "*" && next === "/") {
+				out += "  ";
+				i += 2;
+				state = "normal";
+			} else {
+				out += ch === "\n" ? "\n" : " ";
+				i++;
+			}
+			continue;
+		}
+		if (state === "single" || state === "double") {
+			const quote = state === "single" ? "'" : '"';
+			if (ch === quote && next === quote) {
+				out += "  ";
+				i += 2;
+			} else {
+				out += ch === "\n" ? "\n" : " ";
+				i++;
+				if (ch === quote) state = "normal";
+			}
+			continue;
+		}
+		if (sql.startsWith(dollarTag, i)) {
+			out += " ".repeat(dollarTag.length);
+			i += dollarTag.length;
+			state = "normal";
+			dollarTag = "";
+		} else {
+			out += ch === "\n" ? "\n" : " ";
+			i++;
+		}
+	}
+	return out;
+}
+
+function iterStatements(maskedSql: string): KsqlStatement[] {
+	const statements: KsqlStatement[] = [];
+	let start = 0;
+	let startLine = 1;
+	let line = 1;
+	for (let i = 0; i < maskedSql.length; i++) {
+		const ch = maskedSql[i];
+		if (ch === ";") {
+			const text = maskedSql.slice(start, i + 1);
+			if (text.trim()) statements.push({ text, line: startLine });
+			start = i + 1;
+			startLine = line;
+		}
+		if (ch === "\n") {
+			line++;
+			if (!maskedSql.slice(start, i).trim()) startLine = line;
+		}
+	}
+	const tail = maskedSql.slice(start);
+	if (tail.trim()) statements.push({ text: tail, line: startLine });
+	return statements;
+}
+
+function lintStatement(stmt: KsqlStatement): KsqlFinding[] {
+	const findings: KsqlFinding[] = [];
+	const compact = stmt.text.split(/\s+/).filter(Boolean).join(" ");
+	const first = compact.match(/^\s*(\w+)/)?.[1]?.toUpperCase() ?? "";
+	if ((first === "UPDATE" || first === "DELETE") && !hasToken(stmt.text, "WHERE")) {
+		findings.push({ severity: "ERROR", line: stmt.line, message: `${first} 语句缺少 WHERE，禁止生成无范围更新/删除。` });
+	}
+	const selectStarMatches = [...stmt.text.matchAll(/\bSELECT\s+\*/gi)];
+	if (selectStarMatches.length) {
+		const isBackup = /\bSELECT\s+\*\s+INTO\s+bak_[a-zA-Z0-9_]+_\d{12}\s+FROM\b/i.test(stmt.text);
+		if (isBackup && hasToken(stmt.text, "WHERE")) {
+			findings.push({ severity: "ERROR", line: stmt.line, message: "备份语句必须整表备份，SELECT * INTO bak_... 不允许带 WHERE。" });
+		} else if (!isBackup) {
+			for (const match of selectStarMatches) {
+				findings.push({ severity: "ERROR", line: lineOfOffset(stmt.text, stmt.line, match.index ?? 0), message: "查询/验证语句禁止 SELECT *；只有整表备份 SELECT * INTO bak_... 例外。" });
+			}
+		}
+	}
+	if (/\bSELECT\s+\*\s+INTO\b/i.test(stmt.text) && !/\bSELECT\s+\*\s+INTO\s+bak_[a-zA-Z0-9_]+_\d{12}\s+FROM\b/i.test(stmt.text)) {
+		findings.push({ severity: "ERROR", line: stmt.line, message: "备份表名必须形如 bak_<原表或业务缩写>_<yyyyMMddHHmm>。" });
+	}
+	for (const match of stmt.text.matchAll(/\bEXISTS\b/gi)) {
+		findings.push({ severity: "WARN", line: lineOfOffset(stmt.text, stmt.line, match.index ?? 0), message: "SQL 可读性偏好：成员关系/半连接默认使用 IN，只有 IN 改变语义时才保留 EXISTS 并说明原因。" });
+	}
+	if (/\bUPDATE\b.+\bJOIN\b/i.test(compact)) {
+		findings.push({ severity: "WARN", line: stmt.line, message: "PostgreSQL 多表更新优先使用 UPDATE ... FROM ... WHERE ...，不要使用 MySQL 风格 UPDATE ... JOIN。" });
+	}
+	if (/=\s*NULL\b|\bNULL\s*=/i.test(stmt.text)) {
+		findings.push({ severity: "ERROR", line: stmt.line, message: "NULL 判断必须使用 IS NULL / IS NOT NULL，不能使用 = NULL。" });
+	}
+	if (/<>|!=/.test(stmt.text) && hasToken(stmt.text, "NULL")) {
+		findings.push({ severity: "WARN", line: stmt.line, message: "涉及 NULL 的不等比较需确认语义；PostgreSQL 可优先使用 IS DISTINCT FROM。" });
+	}
+	return findings;
+}
+
+function lintTimestamps(path: string, rawSql: string): KsqlFinding[] {
+	const findings: KsqlFinding[] = [];
+	const backupTimestamps = new Set([...rawSql.matchAll(/\bbak_[a-zA-Z0-9_]+_(\d{12})\b/gi)].map((match) => match[1]));
+	const filenameTs = path.match(/ksql_[^/\\]*_(\d{12})\.txt$/i)?.[1];
+	const headerTimestamps = new Set([...rawSql.matchAll(/备份表时间戳[：:]\s*(\d{12})/g)].map((match) => match[1]));
+	if (backupTimestamps.size > 1) findings.push({ severity: "ERROR", line: 1, message: "同一 SQL 文件中出现多个备份表时间戳；桌面文件、备份表和文件头时间戳必须一致。" });
+	if (filenameTs && backupTimestamps.size && !backupTimestamps.has(filenameTs)) {
+		findings.push({ severity: "ERROR", line: 1, message: `文件名时间戳 ${filenameTs} 与备份表时间戳 ${[...backupTimestamps].sort().join(", ")} 不一致。` });
+	}
+	if (headerTimestamps.size > 1) findings.push({ severity: "ERROR", line: 1, message: "文件头出现多个不同的备份表时间戳。" });
+	if (headerTimestamps.size && backupTimestamps.size && [...headerTimestamps].some((ts) => !backupTimestamps.has(ts))) {
+		findings.push({ severity: "ERROR", line: 1, message: `文件头时间戳 ${[...headerTimestamps].sort().join(", ")} 与备份表时间戳 ${[...backupTimestamps].sort().join(", ")} 不一致。` });
+	}
+	return findings;
+}
+
+function hasToken(text: string, token: string): boolean {
+	return new RegExp(`\\b${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(text);
+}
+
+function lineOfOffset(text: string, baseLine: number, offset: number): number {
+	return baseLine + (text.slice(0, offset).match(/\n/g)?.length ?? 0);
+}
+
+function arrayObjects(value: unknown): Record<string, unknown>[] {
+	return Array.isArray(value) ? value.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object" && !Array.isArray(item)) : [];
+}
+
+function objectValue(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+function stringValue(value: unknown): string {
+	return typeof value === "string" ? value.trim() : value === undefined || value === null ? "" : String(value).trim();
+}
+
+function filterObjects(values: Record<string, unknown>[], fuzzy?: string): Record<string, unknown>[] {
+	const terms = fuzzy ? splitTerms(fuzzy) : [];
+	if (!terms.length) return values;
+	return values.filter((value) => terms.some((term) => matchesText(Object.values(value).map(stringValue).join("|"), term)));
+}
+
+function matchesText(text: string, term: string): boolean {
+	try {
+		return new RegExp(term, "i").test(text);
+	} catch {
+		return text.toLowerCase().includes(term.toLowerCase());
+	}
+}
+
+function fieldTable(field: Record<string, unknown>, form: Record<string, unknown>): string {
+	return stringValue(field.dbTableName) || stringValue(field.dbTableKey) || stringValue(form.dbTableName) || stringValue(form.dbTableKey) || "-";
+}
+
+function fieldDetail(field: Record<string, unknown>): string {
+	const parts = [];
+	const extMap = objectValue(field.extMap);
+	if (extMap) parts.push(`枚举: ${Object.entries(extMap).map(([key, value]) => `${key}:${stringValue(value)}`).join(", ")}`);
+	const refType = stringValue(field.refType);
+	if (refType) parts.push(`refType: ${refType}`);
+	const dbKey = stringValue(field.dbKey);
+	if (dbKey) parts.push(`dbKey: ${dbKey}`);
+	return parts.join("；") || "-";
+}
+
 function withConfig(args: string[], cwd: string, config?: string): string[] {
 	if (!config) return args;
 	return ["--config", resolveWorkspacePath(cwd, config), ...args];

package/src/platform/path.ts

@@ -0,0 +1,38 @@
+import { isAbsolute, resolve } from "node:path";
+
+const WINDOWS_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
+
+export function resolveWorkspacePath(cwd: string, inputPath: string): string {
+	const normalized = normalizeExternalPath(inputPath);
+	return isAbsolute(normalized) || WINDOWS_DRIVE_RE.test(normalized) ? resolve(normalized) : resolve(cwd, normalized);
+}
+
+export function normalizeExternalPath(inputPath: string): string {
+	let value = inputPath.trim();
+	if (value.startsWith("file://")) {
+		try {
+			value = new URL(value).pathname;
+		} catch {
+			// Keep original value when it is not a valid file URL.
+		}
+	}
+
+	if (process.platform === "win32") {
+		const wsl = value.match(/^\/mnt\/([a-zA-Z])\/(.*)$/);
+		if (wsl) return `${wsl[1].toUpperCase()}:\\${wsl[2].replace(/\//g, "\\")}`;
+
+		const msys = value.match(/^\/([a-zA-Z])\/(.*)$/);
+		if (msys) return `${msys[1].toUpperCase()}:\\${msys[2].replace(/\//g, "\\")}`;
+	}
+
+	return value;
+}
+
+export function hasUnixDrivePath(inputPath: string): boolean {
+	return /^\/mnt\/[a-zA-Z]\//.test(inputPath.trim()) || /^\/[a-zA-Z]\//.test(inputPath.trim());
+}
+
+export function windowsPathHint(inputPath: string): string | undefined {
+	if (process.platform !== "win32" || !hasUnixDrivePath(inputPath)) return undefined;
+	return normalizeExternalPath(inputPath);
+}

package/src/tools/build-debug.ts

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { extname, join } from "node:path";
 import type { ProductProfile } from "../product/profile.ts";
-import { type CommandSpec, formatCommandResult, resolveWorkspacePath, runCommand } from "../official/kingdee-skills.ts";
+import { type CommandSpec, formatCommandResult, runCommand } from "../official/kingdee-skills.ts";
+import { resolveWorkspacePath } from "../platform/path.ts";
 
 export interface BuildPlan {
 	profile: string;