kcode-pi 0.1.13 → 0.1.14

package/README.md

@@ -59,6 +59,13 @@ kcode context --refresh
 
 ```powershell
 kcode doctor
+kcode doctor --deep
+```
+
+修复项目级 KCode 配置：
+
+```powershell
+kcode repair
 ```
 
 查看当前 KCode 版本：
@@ -240,6 +247,17 @@ kcode context --refresh
 
 ```powershell
 kcode doctor
+kcode doctor --deep
+```
+
+`--deep` 会额外检查 Node 版本、npm 全局目录、项目 `.pi/settings.json` 中的重复/旧 KCode package 路径、项目上下文和 active run。
+
+### `kcode repair`
+
+清理当前项目 `.pi/settings.json` 中旧 Node/nvm 版本下的 KCode package 路径，只保留当前安装路径，并刷新项目上下文。
+
+```powershell
+kcode repair
 ```
 
 ### `kcode version`
@@ -522,7 +540,7 @@ npm install -g kcode-pi@latest
 
 ```powershell
 kcode init
-kcode doctor
+kcode doctor --deep
 ```
 
 ## nvm 与 Node 版本切换
@@ -646,7 +664,7 @@ type .pi\settings.json
 如果 `packages` 中有多条 `kcode-pi` 路径，运行：
 
 ```powershell
-kcode init
+kcode repair
 ```
 
 如果使用的是 `0.1.1` 或更早版本，请手工删除旧路径，或升级到最新版。

package/dist/cli/kcode.d.ts

@@ -11,7 +11,8 @@ export interface PiCliCommand {
 export declare function runKcodeCli(args: string[], cwd?: string): KcodeCliResult;
 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 doctor(cwd: string, args?: string[]): KcodeCliResult;
+export declare function repair(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

@@ -17,7 +17,9 @@ export function runKcodeCli(args, cwd = process.cwd()) {
         case "context":
             return context(cwd, args.slice(1));
         case "doctor":
-            return doctor(cwd);
+            return doctor(cwd, args.slice(1));
+        case "repair":
+            return repair(cwd);
         case "version":
         case "--version":
         case "-v":
@@ -55,28 +57,96 @@ export function context(cwd, args) {
         output: [`项目上下文已${refresh ? "刷新" : "就绪"}：${projectContext.path}`, "", projectContext.content].join("\n"),
     };
 }
-export function doctor(cwd) {
+export function doctor(cwd, args = []) {
+    const deep = args.includes("--deep");
     const lines = [];
     const node = spawnSync("node", ["--version"], { encoding: "utf8" });
     const piCli = resolvePiCliCommand(["--version"]);
     const pi = piCli ? spawnSync(piCli.command, piCli.args, { encoding: "utf8" }) : undefined;
     const settingsPath = projectSettingsPath(cwd);
+    const projectContextPath = join(cwd, ".pi", "kd", "PROJECT_CONTEXT.md");
+    let errors = 0;
+    let warnings = 0;
     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"}`);
+    lines.push(`项目上下文：${existsSync(projectContextPath) ? projectContextPath : "未创建，请运行 kcode context"}`);
     if (existsSync(settingsPath)) {
-        const settings = readSettings(settingsPath);
-        const hasKcode = (settings.packages ?? []).includes(normalizePath(packageRoot));
-        lines.push(`KCode package 已登记：${hasKcode ? "是" : "否"}`);
+        const settingsResult = readSettingsSafe(settingsPath);
+        if (!settingsResult.ok) {
+            errors++;
+            lines.push(`[ERROR] 项目配置无法解析：${settingsResult.error}`);
+        }
+        else {
+            const packages = settingsResult.settings.packages ?? [];
+            const hasKcode = packages.includes(normalizePath(packageRoot));
+            lines.push(`KCode package 已登记：${hasKcode ? "是" : "否"}`);
+            if (!hasKcode)
+                warnings++;
+            if (deep) {
+                const kcodePackages = packages.filter((pkg) => isSameKcodePackage(pkg, normalizePath(packageRoot)));
+                const stalePackages = kcodePackages.filter((pkg) => normalizePath(pkg) !== normalizePath(packageRoot));
+                lines.push(`KCode package 条目数：${kcodePackages.length}`);
+                if (stalePackages.length > 0) {
+                    warnings++;
+                    lines.push(`[WARN] 发现旧 KCode package 路径：${stalePackages.join(" | ")}`);
+                    lines.push("       运行 kcode repair 可清理旧路径并刷新项目上下文。");
+                }
+            }
+        }
     }
+    else {
+        warnings++;
+    }
+    if (deep) {
+        if (!isSupportedNodeVersion(process.version)) {
+            errors++;
+            lines.push(`[ERROR] 当前 Node ${process.version} 不满足要求：>=22.19.0`);
+        }
+        if (!existsSync(projectContextPath)) {
+            warnings++;
+            lines.push("[WARN] 项目上下文不存在，运行 kcode context --refresh 或 kcode repair。");
+        }
+        const npmPrefix = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8" });
+        const npmRoot = spawnSync("npm", ["root", "-g"], { encoding: "utf8" });
+        lines.push(`npm prefix -g：${npmPrefix.status === 0 ? npmPrefix.stdout.trim() : "不可用"}`);
+        lines.push(`npm root -g：${npmRoot.status === 0 ? npmRoot.stdout.trim() : "不可用"}`);
+        lines.push(`active run：${existsSync(join(cwd, ".pi", "kd", "active-run.json")) ? "存在" : "无"}`);
+    }
+    if (deep)
+        lines.push(`诊断汇总：errors=${errors} warnings=${warnings}`);
     return {
-        exitCode: pi?.status === 0 ? 0 : 1,
+        exitCode: pi?.status === 0 && errors === 0 ? 0 : 1,
         output: lines.join("\n"),
     };
 }
+export function repair(cwd) {
+    const settingsPath = projectSettingsPath(cwd);
+    const settingsResult = readSettingsSafe(settingsPath);
+    if (!settingsResult.ok) {
+        return {
+            exitCode: 1,
+            output: `项目配置无法解析，未自动覆盖：${settingsPath}\n原因：${settingsResult.error}`,
+        };
+    }
+    const currentPackage = normalizePath(packageRoot);
+    const packages = (settingsResult.settings.packages ?? []).filter((pkg) => !isSameKcodePackage(pkg, currentPackage));
+    packages.unshift(currentPackage);
+    settingsResult.settings.packages = packages;
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(settingsResult.settings, null, 2)}\n`, "utf8");
+    const projectContext = writeProjectContext(cwd);
+    return {
+        exitCode: 0,
+        output: [
+            `已修复项目级 Pi 配置：${settingsPath}`,
+            `已保留当前 KCode package：${currentPackage}`,
+            `已刷新项目上下文：${projectContext.path}`,
+        ].join("\n"),
+    };
+}
 export function version() {
     const piCli = resolvePiCliCommand(["--version"]);
     const pi = piCli ? spawnSync(piCli.command, piCli.args, { encoding: "utf8" }) : undefined;
@@ -136,6 +206,14 @@ function readSettings(path) {
         return {};
     return JSON.parse(readFileSync(path, "utf8"));
 }
+function readSettingsSafe(path) {
+    try {
+        return { ok: true, settings: readSettings(path) };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
 function normalizePath(path) {
     return resolve(path);
 }
@@ -184,6 +262,24 @@ function formatPiCliStatus(piCli, result) {
     const source = piCli.source === "bundled" ? "随包" : "全局";
     return `${version}（${source}：${piCli.displayPath}）`;
 }
+function isSupportedNodeVersion(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+    if (!match)
+        return false;
+    const [, majorText, minorText, patchText] = match;
+    const major = Number(majorText);
+    const minor = Number(minorText);
+    const patch = Number(patchText);
+    if (major > 22)
+        return true;
+    if (major < 22)
+        return false;
+    if (minor > 19)
+        return true;
+    if (minor < 19)
+        return false;
+    return patch >= 0;
+}
 function piCliPackageVersion(piCli) {
     if (piCli.source !== "bundled")
         return undefined;
@@ -204,6 +300,7 @@ function helpText() {
         "  kcode init      初始化当前项目的 .pi/settings.json",
         "  kcode context   生成或刷新 .pi/kd/PROJECT_CONTEXT.md",
         "  kcode doctor    检查 Node、随包 Pi CLI、KCode package 和项目级配置",
+        "  kcode repair    清理旧 KCode package 路径并刷新项目上下文",
         "  kcode version   显示 KCode、随包 Pi CLI 和 Node 版本",
         "  kcode start     初始化项目配置后启动 KCode 工作环境",
     ].join("\n");

package/docs/DEVELOPMENT.md

@@ -35,6 +35,7 @@ npm run smoke:build-debug
 npm run smoke:sdk-signature
 npm run smoke:package
 npm run smoke:kcode-cli
+npm run release:check
 ```
 
 这些 smoke 分别验证：
@@ -107,11 +108,7 @@ npm run build:cli
 发布检查：
 
 ```powershell
-npm run check
-npm run build:cli
-npm run smoke:package
-npm run smoke:kcode-cli
-npm pack --dry-run
+npm run release:check
 ```
 
 发布：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kcode-pi",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Kingdee-specific package and harness for Pi Coding Agent",
   "type": "module",
   "private": false,
@@ -64,6 +64,7 @@
     "smoke:sdk-signature": "tsx scripts/smoke-sdk-signature.ts",
     "smoke:package": "tsx scripts/smoke-package.ts",
     "smoke:kcode-cli": "tsx scripts/smoke-kcode-cli.ts",
+    "release:check": "tsx scripts/release-check.ts",
     "kcode": "tsx scripts/kcode.ts",
     "prepack": "npm run build:cli && npm run smoke:package"
   },

package/src/cli/kcode.ts

@@ -37,7 +37,9 @@ export function runKcodeCli(args: string[], cwd = process.cwd()): KcodeCliResult
 		case "context":
 			return context(cwd, args.slice(1));
 		case "doctor":
-			return doctor(cwd);
+			return doctor(cwd, args.slice(1));
+		case "repair":
+			return repair(cwd);
 		case "version":
 		case "--version":
 		case "-v":
@@ -81,32 +83,101 @@ export function context(cwd: string, args: string[]): KcodeCliResult {
 	};
 }
 
-export function doctor(cwd: string): KcodeCliResult {
+export function doctor(cwd: string, args: string[] = []): KcodeCliResult {
+	const deep = args.includes("--deep");
 	const lines: string[] = [];
 	const node = spawnSync("node", ["--version"], { encoding: "utf8" });
 	const piCli = resolvePiCliCommand(["--version"]);
 	const pi = piCli ? spawnSync(piCli.command, piCli.args, { encoding: "utf8" }) : undefined;
 	const settingsPath = projectSettingsPath(cwd);
+	const projectContextPath = join(cwd, ".pi", "kd", "PROJECT_CONTEXT.md");
+	let errors = 0;
+	let warnings = 0;
 
 	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"}`);
+	lines.push(`项目上下文：${existsSync(projectContextPath) ? projectContextPath : "未创建，请运行 kcode context"}`);
 
 	if (existsSync(settingsPath)) {
-		const settings = readSettings(settingsPath);
-		const hasKcode = (settings.packages ?? []).includes(normalizePath(packageRoot));
-		lines.push(`KCode package 已登记：${hasKcode ? "是" : "否"}`);
+		const settingsResult = readSettingsSafe(settingsPath);
+		if (!settingsResult.ok) {
+			errors++;
+			lines.push(`[ERROR] 项目配置无法解析：${settingsResult.error}`);
+		} else {
+			const packages = settingsResult.settings.packages ?? [];
+			const hasKcode = packages.includes(normalizePath(packageRoot));
+			lines.push(`KCode package 已登记：${hasKcode ? "是" : "否"}`);
+			if (!hasKcode) warnings++;
+			if (deep) {
+				const kcodePackages = packages.filter((pkg) => isSameKcodePackage(pkg, normalizePath(packageRoot)));
+				const stalePackages = kcodePackages.filter((pkg) => normalizePath(pkg) !== normalizePath(packageRoot));
+				lines.push(`KCode package 条目数：${kcodePackages.length}`);
+				if (stalePackages.length > 0) {
+					warnings++;
+					lines.push(`[WARN] 发现旧 KCode package 路径：${stalePackages.join(" | ")}`);
+					lines.push("       运行 kcode repair 可清理旧路径并刷新项目上下文。");
+				}
+			}
+		}
+	} else {
+		warnings++;
 	}
 
+	if (deep) {
+		if (!isSupportedNodeVersion(process.version)) {
+			errors++;
+			lines.push(`[ERROR] 当前 Node ${process.version} 不满足要求：>=22.19.0`);
+		}
+		if (!existsSync(projectContextPath)) {
+			warnings++;
+			lines.push("[WARN] 项目上下文不存在，运行 kcode context --refresh 或 kcode repair。");
+		}
+		const npmPrefix = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8" });
+		const npmRoot = spawnSync("npm", ["root", "-g"], { encoding: "utf8" });
+		lines.push(`npm prefix -g：${npmPrefix.status === 0 ? npmPrefix.stdout.trim() : "不可用"}`);
+		lines.push(`npm root -g：${npmRoot.status === 0 ? npmRoot.stdout.trim() : "不可用"}`);
+		lines.push(`active run：${existsSync(join(cwd, ".pi", "kd", "active-run.json")) ? "存在" : "无"}`);
+	}
+
+	if (deep) lines.push(`诊断汇总：errors=${errors} warnings=${warnings}`);
+
 	return {
-		exitCode: pi?.status === 0 ? 0 : 1,
+		exitCode: pi?.status === 0 && errors === 0 ? 0 : 1,
 		output: lines.join("\n"),
 	};
 }
 
+export function repair(cwd: string): KcodeCliResult {
+	const settingsPath = projectSettingsPath(cwd);
+	const settingsResult = readSettingsSafe(settingsPath);
+	if (!settingsResult.ok) {
+		return {
+			exitCode: 1,
+			output: `项目配置无法解析，未自动覆盖：${settingsPath}\n原因：${settingsResult.error}`,
+		};
+	}
+
+	const currentPackage = normalizePath(packageRoot);
+	const packages = (settingsResult.settings.packages ?? []).filter((pkg) => !isSameKcodePackage(pkg, currentPackage));
+	packages.unshift(currentPackage);
+	settingsResult.settings.packages = packages;
+	mkdirSync(dirname(settingsPath), { recursive: true });
+	writeFileSync(settingsPath, `${JSON.stringify(settingsResult.settings, null, 2)}\n`, "utf8");
+	const projectContext = writeProjectContext(cwd);
+
+	return {
+		exitCode: 0,
+		output: [
+			`已修复项目级 Pi 配置：${settingsPath}`,
+			`已保留当前 KCode package：${currentPackage}`,
+			`已刷新项目上下文：${projectContext.path}`,
+		].join("\n"),
+	};
+}
+
 export function version(): KcodeCliResult {
 	const piCli = resolvePiCliCommand(["--version"]);
 	const pi = piCli ? spawnSync(piCli.command, piCli.args, { encoding: "utf8" }) : undefined;
@@ -176,6 +247,14 @@ function readSettings(path: string): PiSettings {
 	return JSON.parse(readFileSync(path, "utf8")) as PiSettings;
 }
 
+function readSettingsSafe(path: string): { ok: true; settings: PiSettings } | { ok: false; error: string } {
+	try {
+		return { ok: true, settings: readSettings(path) };
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
 function normalizePath(path: string): string {
 	return resolve(path);
 }
@@ -233,6 +312,20 @@ function formatPiCliStatus(
 	return `${version}（${source}：${piCli.displayPath}）`;
 }
 
+function isSupportedNodeVersion(version: string): boolean {
+	const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+	if (!match) return false;
+	const [, majorText, minorText, patchText] = match;
+	const major = Number(majorText);
+	const minor = Number(minorText);
+	const patch = Number(patchText);
+	if (major > 22) return true;
+	if (major < 22) return false;
+	if (minor > 19) return true;
+	if (minor < 19) return false;
+	return patch >= 0;
+}
+
 function piCliPackageVersion(piCli: PiCliCommand): string | undefined {
 	if (piCli.source !== "bundled") return undefined;
 
@@ -253,6 +346,7 @@ function helpText(): string {
 		"  kcode init      初始化当前项目的 .pi/settings.json",
 		"  kcode context   生成或刷新 .pi/kd/PROJECT_CONTEXT.md",
 		"  kcode doctor    检查 Node、随包 Pi CLI、KCode package 和项目级配置",
+		"  kcode repair    清理旧 KCode package 路径并刷新项目上下文",
 		"  kcode version   显示 KCode、随包 Pi CLI 和 Node 版本",
 		"  kcode start     初始化项目配置后启动 KCode 工作环境",
 	].join("\n");