kcode-pi 0.1.13 → 0.1.15

package/README.md

@@ -2,6 +2,8 @@
 
 KCode 是面向金蝶开发的 Pi 工作环境启动器。安装后会提供全局命令 `kcode`，自动携带 Pi CLI，并在当前业务项目中加载金蝶专属工具、skills、prompts、themes 和知识库。
 
+KCode 默认面向中文用户：README、`kcode help`、Pi 内 `/kd-*` 命令说明、工具参数说明、内置 prompts 和 Harness 阶段文档模板均使用中文。命令名和产品标识仍保持英文，例如 `/kd-start`、`kd_search`、`flagship`。
+
 KCode 不要求你单独安装全局 `pi` 命令，也不会修改用户全局 Pi 配置。它只维护当前项目的：
 
 ```text
@@ -59,6 +61,13 @@ kcode context --refresh
 
 ```powershell
 kcode doctor
+kcode doctor --deep
+```
+
+修复项目级 KCode 配置：
+
+```powershell
+kcode repair
 ```
 
 查看当前 KCode 版本：
@@ -240,6 +249,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`
@@ -271,17 +291,17 @@ kcode start --provider openai --model gpt-4o
 进入 `kcode start` 后，可以使用以下 KCode 命令：
 
 ```text
-/kd-start [--product product] [--version version] <goal>
-/kd-product <product> [--version version]
+/kd-start [--product 产品] [--version 版本] <需求>
+/kd-product <产品> [--version 版本]
 /kd-status
 /kd-runs
 /kd-switch <run-id>
 /kd-resume [补充说明]
 /kd-finish
 /kd-gate
-/kd-advance [phase]
-/kd-artifact [phase] [content]
-/kd-answer Q-001 <answer>
+/kd-advance [阶段]
+/kd-artifact [阶段] [内容]
+/kd-answer Q-001 <答案>
 ```
 
 典型开始方式：
@@ -375,8 +395,8 @@ ship     汇总变更、验证证据、风险和后续事项
 
 - 未进入 `execute` 阶段时，KCode 会阻止写入 Java/XML/SQL 等产品代码。
 - 进入 `execute` 前必须已有 `PLAN.md` 和必要证据。
-- `PLAN.md` 必须包含 `## Execution Steps`，并用 `- [ ] STEP-001: ...` 格式拆分可跟踪步骤。
-- `PLAN.md` 必须包含 `## TDD / Red-Green Checks`，声明红灯证据、绿灯证据和测试/检查命令。
+- `PLAN.md` 必须包含 `## 执行步骤`，并用 `- [ ] STEP-001：...` 格式拆分可跟踪步骤。
+- `PLAN.md` 必须包含 `## TDD / 红绿检查`，声明红灯证据、绿灯证据和测试/检查命令。
 - 红绿检查不等于必须写 JUnit。金蝶项目不要为了满足门禁引入额外 jar 或测试框架。
 - 写生产源码前必须已有 `evidence/tdd-red.md`，内容可以是 API/基类/方法签名检查、元数据检查、编译检查、既有测试框架或外部接口最小验证的失败输出。
 - 进入 `execute` 后，只允许写入 `PLAN.md` 明确列出的源码文件；如果临时发现要改新文件，必须先回到 plan 更新 `PLAN.md`。
@@ -387,36 +407,36 @@ ship     汇总变更、验证证据、风险和后续事项
 示例计划步骤：
 
 ```markdown
-## Execution Steps
+## 执行步骤
 
-- [ ] STEP-001: 检查现有插件基类、包名和目标字段。
-- [ ] STEP-002: 运行 API/元数据/编译等红灯检查并记录证据。
-- [ ] STEP-003: 修改 `code/scm/plugin/src/main/java/.../PurchaseOrderPlugin.java`。
-- [ ] STEP-004: 运行同一类绿灯检查并记录证据。
-- [ ] STEP-005: 记录变更文件和验证证据。
+- [ ] STEP-001：检查现有插件基类、包名和目标字段。
+- [ ] STEP-002：运行 API/元数据/编译等红灯检查并记录证据。
+- [ ] STEP-003：修改 `code/scm/plugin/src/main/java/.../PurchaseOrderPlugin.java`。
+- [ ] STEP-004：运行同一类绿灯检查并记录证据。
+- [ ] STEP-005：记录变更文件和验证证据。
 ```
 
 示例红绿检查：
 
 ```markdown
-## TDD / Red-Green Checks
+## TDD / 红绿检查
 
-- Red evidence: evidence/tdd-red.md
-- Green evidence: evidence/tdd-green.md
-- Red/green command or tool: kd_sdk_signature / kd_cosmic_metadata / kd_check / build
-- Do not add third-party test jars or frameworks only for this gate.
+- 红灯证据：evidence/tdd-red.md
+- 绿灯证据：evidence/tdd-green.md
+- 红绿检查命令或工具：kd_sdk_signature / kd_cosmic_metadata / kd_check / build
+- 不要为了满足门禁引入第三方测试 jar 或测试框架。
 ```
 
 示例执行记录：
 
 ```markdown
-## Step Results
+## 步骤结果
 
-- [x] STEP-001: completed. Evidence: evidence/step-001.md
-- [x] STEP-002: completed. Evidence: evidence/step-002.md
-- [x] STEP-003: completed. Evidence: evidence/step-003.md
-- [x] STEP-004: completed. Evidence: evidence/tdd-green.md
-- [x] STEP-005: completed. Evidence: evidence/step-005.md
+- [x] STEP-001：已完成。证据：evidence/step-001.md
+- [x] STEP-002：已完成。证据：evidence/step-002.md
+- [x] STEP-003：已完成。证据：evidence/step-003.md
+- [x] STEP-004：已完成。证据：evidence/tdd-green.md
+- [x] STEP-005：已完成。证据：evidence/step-005.md
 ```
 
 如果 LLM 跳过步骤、没有记录 evidence，或只是口头声明完成，KCode 不允许进入 `verify`。
@@ -431,7 +451,7 @@ ship     汇总变更、验证证据、风险和后续事项
 
 得到回答后，再继续问触发时机、库存条件、弹窗内容或插件位置。
 
-在 `kcode start` 的交互式 TUI 中，`kd_question` 会弹出 KCode Question 选择/输入对话，并在用户选择或输入后自动记录答案。非交互模式或 UI 不可用时，问题会显示在对话里，用户直接回复；Agent 读取回复后再记录答案。也可以手动执行：
+在 `kcode start` 的交互式 TUI 中，`kd_question` 会弹出 KCode 问题选择/输入对话，并在用户选择或输入后自动记录答案。非交互模式或 UI 不可用时，问题会显示在对话里，用户直接回复；Agent 读取回复后再记录答案。也可以手动执行：
 
 ```text
 /kd-answer Q-001 采购订单
@@ -522,7 +542,7 @@ npm install -g kcode-pi@latest
 
 ```powershell
 kcode init
-kcode doctor
+kcode doctor --deep
 ```
 
 ## nvm 与 Node 版本切换
@@ -646,7 +666,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/dist/context/project-context.js

@@ -47,33 +47,33 @@ export function generateProjectContext(cwd) {
     const buildFiles = scan.files.filter((file) => BUILD_FILE_NAMES.has(basename(file).toLowerCase()) || isSolutionOrProject(file));
     const sourceSamples = scan.files.filter((file) => SOURCE_EXTENSIONS.has(extname(file).toLowerCase())).slice(0, MAX_SOURCE_SAMPLES);
     return [
-        "# KCode Project Context",
+        "# KCode 项目上下文",
         "",
-        `- Project root: ${cwd}`,
-        `- Project name: ${basename(cwd)}`,
-        `- Generated at: ${new Date().toISOString()}`,
+        `- 项目根目录：${cwd}`,
+        `- 项目名称：${basename(cwd)}`,
+        `- 生成时间：${new Date().toISOString()}`,
         "",
-        "## Persistent Rules",
+        "## 持久规则",
         "",
-        "- 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.",
+        "- 本文件是 KCode 的项目记忆，计划或编辑代码前必须读取。",
+        "- 业务需求不得生成 demo/sample/scaffold 代码。",
+        "- 不要假设模块结构。必须基于下方真实路径，并在编辑前确认目标文件。",
+        "- 调用文件工具时优先使用项目相对路径。在 Windows 中，不要把路径改写为 /mnt/<drive>/... 或 /<drive>/...；只有确需绝对路径时才使用 Windows 路径。",
+        "- 如果本文件过期，计划前先运行 `kcode context --refresh` 重新生成。",
+        "- 只有 Harness 进入 `execute` 且 PLAN.md 写明真实目标路径后，才能写产品代码。",
         "",
-        "## Layout Summary",
+        "## 项目结构摘要",
         "",
-        `- Has code directory: ${codeDir ? "yes" : "no"}`,
-        `- Likely source roots: ${formatList(likelyRoots)}`,
-        `- Build files: ${formatList(buildFiles)}`,
-        `- Detected modules: ${formatList(modules)}`,
+        `- 是否存在 code 目录：${codeDir ? "是" : "否"}`,
+        `- 可能的源码根：${formatList(likelyRoots)}`,
+        `- 构建文件：${formatList(buildFiles)}`,
+        `- 识别到的模块：${formatList(modules)}`,
         "",
-        "## Source Samples",
+        "## 源码样例",
         "",
         formatBlockList(sourceSamples),
         "",
-        "## Top-Level Directories",
+        "## 顶层目录",
         "",
         formatBlockList(scan.directories.filter((dir) => !dir.includes("/") && !dir.includes("\\")).sort()),
         "",
@@ -181,11 +181,11 @@ function isSolutionOrProject(file) {
     return [".sln", ".csproj"].includes(extname(file).toLowerCase());
 }
 function formatList(values) {
-    return values.length > 0 ? values.join(", ") : "none detected";
+    return values.length > 0 ? values.join(", ") : "未识别";
 }
 function formatBlockList(values) {
     if (values.length === 0)
-        return "- none detected";
+        return "- 未识别";
     return values.map((value) => `- ${value}`).join("\n");
 }
 function normalize(path) {

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
 ```
 
 发布：