kcode-pi 0.1.14 → 0.1.16

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
@@ -289,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 <答案>
 ```
 
 典型开始方式：
@@ -393,8 +395,10 @@ 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 / 红绿检查`，声明红灯证据、绿灯证据和测试/检查命令。
+- Java/C# 产品代码进入 `execute` 前必须已有 `evidence/sdk-signature.md`。该证据由 `kd_sdk_signature` 成功查证当前项目真实 SDK jar/dll 后自动写入。
+- LLM 禁止凭记忆、模型知识或随包知识库猜 SDK 方法签名。`kd_search`、`kd_cosmic_api` 只能作为线索；最终签名事实必须来自 `kd_sdk_signature`、当前项目构建输出、项目源码封装或官方元数据。
 - 红绿检查不等于必须写 JUnit。金蝶项目不要为了满足门禁引入额外 jar 或测试框架。
 - 写生产源码前必须已有 `evidence/tdd-red.md`，内容可以是 API/基类/方法签名检查、元数据检查、编译检查、既有测试框架或外部接口最小验证的失败输出。
 - 进入 `execute` 后，只允许写入 `PLAN.md` 明确列出的源码文件；如果临时发现要改新文件，必须先回到 plan 更新 `PLAN.md`。
@@ -405,36 +409,37 @@ 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 或测试框架。
+- Java/C# SDK 签名证据：evidence/sdk-signature.md
 ```
 
 示例执行记录：
 
 ```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`。
@@ -449,7 +454,7 @@ ship     汇总变更、验证证据、风险和后续事项
 
 得到回答后，再继续问触发时机、库存条件、弹窗内容或插件位置。
 
-在 `kcode start` 的交互式 TUI 中，`kd_question` 会弹出 KCode Question 选择/输入对话，并在用户选择或输入后自动记录答案。非交互模式或 UI 不可用时，问题会显示在对话里，用户直接回复；Agent 读取回复后再记录答案。也可以手动执行：
+在 `kcode start` 的交互式 TUI 中，`kd_question` 会弹出 KCode 问题选择/输入对话，并在用户选择或输入后自动记录答案。非交互模式或 UI 不可用时，问题会显示在对话里，用户直接回复；Agent 读取回复后再记录答案。也可以手动执行：
 
 ```text
 /kd-answer Q-001 采购订单
@@ -489,6 +494,7 @@ kd_debug            分析金蝶日志和堆栈
 - `kd_cosmic_metadata` 使用统一路由 API 查询真实单据/表单元数据，并在当前项目 `.pi/kd/official-skills/` 下维护 JSON 缓存。
 - `kd_sdk_signature` 优先从当前业务项目的实际 SDK jar/dll 中读取类型和方法签名。Cosmic Java 依赖 `javap`，Enterprise C# 依赖 PowerShell 读取 DLL 元数据。
 - `kd_cosmic_api` 查询随包金蝶知识库，只作为 API 线索和兜底；精确方法签名优先使用 `kd_sdk_signature`、当前项目 SDK 或编译输出确认。
+- 当前项目存在 active run 时，`kd_sdk_signature` 成功后会自动写入 `.pi/kd/runs/<run-id>/evidence/sdk-signature.md`。Java/C# 产品代码缺少这份证据时，KCode 不允许进入 `execute` 或写生产源码。
 
 示例：
 

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) {