kcode-pi 0.1.20 → 0.1.23

package/README.md

@@ -1,297 +1,102 @@
 # KCode
 
-KCode 是面向金蝶开发的 Pi 工作环境启动器。安装后会提供全局命令 `kcode`，自动携带 Pi CLI，并在当前业务项目中加载金蝶专属工具、skills、prompts、themes 和知识库。
+KCode 是面向金蝶开发的 Pi 工作环境启动器。它提供全局命令 `kcode`，自动携带 Pi CLI，并在当前业务项目中加载金蝶专属工具、skills、prompts、themes、知识库和 Harness 工作流。
 
-KCode 默认面向中文用户：README、`kcode help`、Pi 内 `/kd-*` 命令说明、工具参数说明、内置 prompts 和 Harness 阶段文档模板均使用中文。命令名和产品标识仍保持英文，例如 `/kd-start`、`kd_search`、`flagship`。
+KCode 默认面向中文用户。命令名和产品标识保持英文，例如 `/kd-start`、`/kd-product`、`kd_search`、`flagship`。
 
-KCode 不要求你单独安装全局 `pi` 命令，也不会修改用户全局 Pi 配置。它只维护当前项目的：
+## 文档导航
 
-```text
-.pi/settings.json
-```
+如果你是第一次使用，按顺序看：
+
+1. [用户指南](docs/USER_GUIDE.md)：安装、初始化、启动、模型配置、升级。
+2. [Harness 工作流](docs/HARNESS_WORKFLOW.md)：如何从需求进入 discuss -> spec -> plan -> execute -> verify -> ship。
+3. [产品画像确认](docs/PRODUCT_PROFILE.md)：如何用 `/kd-product` 确认苍穹、星瀚、星空旗舰版或企业版。
+4. [证据和门禁](docs/EVIDENCE_AND_GATES.md)：为什么需要 evidence、SDK 签名、TDD 红绿证据、风险确认。
+5. [命令参考](docs/COMMAND_REFERENCE.md)：完整 `kcode` 子命令、Pi 内 `/kd-*` 命令和内置工具参数。
+6. [更新日志](docs/CHANGELOG.md)：查看版本变化、发布验证和近期改进。
+7. [故障排查](docs/TROUBLESHOOTING.md)：模型、旧版本、Windows 路径、终端显示等常见问题。
+
+维护者文档：
+
+- [开发与发布说明](docs/DEVELOPMENT.md)
+- [发行版方案](docs/KCODE_DISTRIBUTION.md)
+- [更新日志](docs/CHANGELOG.md)
 
-## 安装
+## 快速开始
 
 环境要求：
 
 - Node.js `>=22.19.0`
 - npm
 - Windows 推荐使用 Windows Terminal
-- 不需要安装 Python。KCode 随包工具使用 Node/TypeScript 实现；只有你自己的业务项目或外部脚本明确依赖 Python 时才需要另行安装。
 
-全局安装：
+安装：
 
 ```powershell
 npm install -g kcode-pi
 ```
 
-如果企业内发布包名不是 `kcode-pi`，请替换为实际包名。全局命令仍是：
-
-```powershell
-kcode
-```
-
-## 首次使用
-
-进入你的业务项目根目录，不是 KCode 源码目录：
-
-```powershell
-cd E:\projects\your-business-project
-```
-
-初始化项目级 KCode 配置：
+进入你的实际业务项目根目录后执行：
 
 ```powershell
 kcode init
-```
-
-`init` 会登记 KCode package，并生成项目常驻上下文：
-
-```text
-.pi/kd/PROJECT_CONTEXT.md
-```
-
-如果项目结构后来变化，手动刷新：
-
-```powershell
-kcode context --refresh
-```
-
-检查环境：
-
-```powershell
-kcode doctor
 kcode doctor --deep
-```
-
-修复项目级 KCode 配置：
-
-```powershell
-kcode repair
-```
-
-查看当前 KCode 版本：
-
-```powershell
-kcode version
-```
-
-启动工作环境：
-
-```powershell
 kcode start
 ```
 
-`kcode start` 会先确保 `.pi/settings.json` 已登记当前安装的 KCode package，然后启动随包 Pi CLI。
-
-## 配置模型
-
-首次启动 Pi 时，如果看到：
-
-```text
-Warning: No models available.
-```
-
-说明还没有配置模型供应商。进入 `kcode start` 后输入：
+如果首次启动提示没有模型，在 KCode/Pi 中执行：
 
 ```text
 /login
-```
-
-选择供应商并登录或填写 API Key。常见选择包括：
-
-```text
-ChatGPT Plus/Pro (Codex)
-Claude Pro/Max
-GitHub Copilot
-OpenAI
-Anthropic
-DeepSeek
-Gemini
-```
-
-也可以在 PowerShell 中设置环境变量后再启动：
-
-```powershell
-$env:OPENAI_API_KEY="sk-..."
-kcode start
-```
-
-或：
-
-```powershell
-$env:ANTHROPIC_API_KEY="sk-ant-..."
-kcode start
-```
-
-登录或配置完成后，可在 Pi 中使用：
-
-```text
 /model
 ```
 
-选择模型。
-
-### 自定义模型供应商
-
-如果你的模型服务是企业网关、代理服务、Ollama、LM Studio、vLLM，或其他 OpenAI-compatible endpoint，不需要改 KCode。Pi 原生支持通过用户级配置文件添加自定义供应商：
+## 第一个需求
 
-```powershell
-notepad $env:USERPROFILE\.pi\agent\models.json
-```
-
-写入或合并：
-
-```json
-{
-  "providers": {
-    "corp-ai": {
-      "baseUrl": "https://ai.example.com/v1",
-      "api": "openai-completions",
-      "apiKey": "$CORP_AI_API_KEY",
-      "compat": {
-        "supportsDeveloperRole": false,
-        "supportsReasoningEffort": false
-      },
-      "models": [
-        {
-          "id": "corp-coder",
-          "name": "Corp Coder",
-          "reasoning": false,
-          "input": ["text"],
-          "contextWindow": 128000,
-          "maxTokens": 16384,
-          "cost": {
-            "input": 0,
-            "output": 0,
-            "cacheRead": 0,
-            "cacheWrite": 0
-          }
-        }
-      ]
-    }
-  }
-}
-```
-
-再设置 API Key 并启动：
-
-```powershell
-$env:CORP_AI_API_KEY="sk-..."
-kcode start
-```
-
-进入后使用：
+推荐显式指定产品：
 
 ```text
-/model
-```
-
-选择 `corp-ai/corp-coder`。也可以直接指定：
-
-```powershell
-kcode start --provider corp-ai --model corp-coder
-```
-
-说明：
-
-- `/login` 用于 Pi 内置供应商或扩展注册过登录流程的供应商。
-- 任意自定义 endpoint/API key 推荐写 `~\.pi\agent\models.json`。
-- `api` 常用值是 `openai-completions`，适合大多数 OpenAI-compatible 服务。
-- 如果服务支持 Anthropic Messages 或 Google Generative AI，可按 Pi 文档改为对应 API 类型。
-
-## 常用命令
-
-### `kcode init`
-
-初始化或更新当前项目的 `.pi/settings.json`。
-
-```powershell
-kcode init
+/kd-start --product cangqiong 实现采购订单保存校验
 ```
 
-它只修改当前项目，不写用户全局 Pi 配置。`kcode-pi@0.1.2` 起，`init` 会自动清理同名旧 KCode package 路径，避免 Node 版本切换后重复加载。
-
-同时会确保项目常驻上下文存在：
+也可以直接提供需求文档：
 
 ```text
-.pi/kd/PROJECT_CONTEXT.md
-```
-
-这份文件记录项目根目录、真实源码根、构建文件、模块线索和 KCode 持久约束。KCode Harness 会在每次对话继续时读取它，降低中断后丢失项目结构上下文的风险。
-
-### `kcode context`
-
-生成或刷新项目常驻上下文。
-
-```powershell
-kcode context
-kcode context --refresh
+/kd-start --product cangqiong E:\project\docs\需求说明.md
 ```
 
-建议在以下情况刷新：
-
-- 初次接入已有业务项目。
-- 新增、移动或删除模块。
-- 从分支切换到不同项目结构。
-- Agent 写代码前发现 `PROJECT_CONTEXT.md` 与当前项目不一致。
-
-项目上下文是按业务项目隔离的：
-
-- 在 `E:\projects\a` 运行 `kcode context`，只会写 `E:\projects\a\.pi\kd\PROJECT_CONTEXT.md`。
-- 切换到 `E:\projects\b` 后，需要在 `b` 项目下运行 `kcode init` 或 `kcode context`，不会自动携带 `a` 项目的上下文。
-- 切回 `a` 项目后，只要 `.pi/kd/` 没有删除，原来的 `PROJECT_CONTEXT.md`、`active-run.json` 和历史 runs 都还在。
-- 如果项目被复制、移动路径或重建工作区，建议重新运行 `kcode context --refresh`，让绝对路径和源码根重新匹配当前目录。
+如果已经创建了 run，但标题栏显示产品未确认：
 
-### `kcode doctor`
-
-检查 Node、随包 Pi CLI、KCode package 路径和项目配置。
-
-```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
+```text
+/kd-product cangqiong --version V6.0
+/kd-gate
+/kd-status
 ```
 
-### `kcode version`
-
-显示当前 KCode package 版本、安装路径、随包 Pi CLI 版本和 Node 版本。
+支持的产品画像：
 
-```powershell
-kcode version
-kcode --version
-kcode -v
+```text
+cangqiong   金蝶苍穹 / Cosmic Java
+xinghan     金蝶星瀚 / 基于苍穹/Cosmic
+flagship    星空旗舰版 / 基于苍穹/Cosmic
+enterprise  金蝶企业版 / C#
 ```
 
-### `kcode start`
-
-启动 KCode 工作环境。
+进入 `ship` 前还需要确认风险：
 
-```powershell
-kcode start
+```text
+/kd-risk low 已完成本地构建和元数据检查，无残余交付风险
+/kd-gate
 ```
 
-`start` 后面的参数会原样透传给 Pi CLI，例如：
-
-```powershell
-kcode start --provider openai --model gpt-4o
-```
+完整解释见 [产品画像确认](docs/PRODUCT_PROFILE.md) 和 [证据和门禁](docs/EVIDENCE_AND_GATES.md)。
 
 ## Pi 内 KCode 命令
 
-进入 `kcode start` 后，可以使用以下 KCode 命令：
+进入 `kcode start` 后常用：
 
 ```text
-/kd-start [--product 产品] [--version 版本] <需求>
+/kd-start [--product 产品] [--version 版本] <需求或需求文档>
 /kd-product <产品> [--version 版本]
 /kd-risk <low|medium|high> <原因>
 /kd-status
@@ -305,77 +110,37 @@ kcode start --provider openai --model gpt-4o
 /kd-answer Q-001 <答案>
 ```
 
-典型开始方式：
-
-```text
-/kd-start --product flagship 实现采购订单插件
-```
-
-`/kd-start` 会创建新的功能点 run，并立即触发 Agent 进入 `discuss` 阶段。如果未识别出产品画像，例如显示 `(unknown/unknown)`，下一步应先确认产品、版本和技术栈，而不是直接写代码。
-
-进入 `ship` 前必须确认风险等级：
-
-```text
-/kd-risk low 已完成本地构建和元数据检查，无残余交付风险
-```
-
-`/kd-artifact` 默认只创建缺失阶段文档。若阶段文档已存在，带内容调用不会直接覆盖；确认要整体替换时必须追加 `--replace`。
-
-暂停后接续：
-
-```text
-/kd-resume
-/kd-resume 继续确认采购入库单即时库存检查插件
-```
-
-重新 `kcode start` 时，如果当前项目存在未完成 active run，KCode 会提示当前功能点和阶段。`/kd-resume` 会读取项目常驻上下文、active run 状态和已落盘的阶段文档，再把完整工作流上下文交给 Agent 继续。
-
-支持的产品画像：
-
-```text
-cosmic     -> Cosmic 平台底座
-cangqiong  -> Cosmic / Java
-xinghan    -> Cosmic / Java
-flagship   -> Cosmic / Java
-enterprise -> Enterprise / C#
-```
-
-企业版补充：
-
-- 默认企业版插件按 `Enterprise / C#` 处理。
-- 只有明确提出 `Python插件`、`IronPython`，或带企业版/BOS 语境的 `Python脚本` 时，KCode 才切换到 `Enterprise / Python(IronPython)`。
-- Python 插件同样必须走 Harness 工作流，`.py` 写入也必须等到 `execute` 阶段。
-
-工作流阶段：
-
-```text
-discuss -> spec -> plan -> execute -> verify -> ship
-```
+完整说明见 [命令参考](docs/COMMAND_REFERENCE.md)。
 
-KCode 会把金蝶开发需求纳入 Harness 工作流。你可以直接输入自然语言需求；如果当前项目还没有 active run，KCode 会自动创建 run 并进入 `discuss` 阶段，而不是直接生成代码。
-
-一个功能点对应一个 run。每个 run 都有独立阶段、计划、执行记录和证据；做另一个功能点时，不要复用上一个功能点的阶段。
-
-```text
-/kd-start 实现采购订单保存校验
-/kd-finish
-/kd-start 实现采购订单列表字段展示
-```
+## 内置金蝶工具
 
-查看和切换当前项目里的功能点 run：
+KCode 会向 Pi 注册：
 
 ```text
-/kd-runs
-/kd-switch <run-id>
+kd_plan_status      查看当前 Harness run、阶段、产物和门禁
+kd_question         记录/回答/查看阻断问题
+kd_search           搜索随包金蝶知识库
+kd_table            查询随包表结构
+kd_check            检查金蝶 Java/C#/Python 插件代码
+kd_cosmic_config    运行 Cosmic 官方能力配置预检
+kd_cosmic_metadata  查询 Cosmic 表单/单据元数据
+kd_cosmic_api       查询随包 Cosmic API 知识线索
+kd_sdk_signature    从当前项目实际 SDK jar/dll 中读取类和方法签名
+kd_ksql_lint        运行 KSQL/SQL lint
+kd_build            按产品画像执行或 dry-run 构建
+kd_debug            分析金蝶日志和堆栈
 ```
 
-如果当前 active run 处于 `execute` 或 `verify`，但你提出的是另一个需求，KCode 会要求先创建新 run 或切换 run，避免把新需求塞进旧功能点的 `PLAN.md` 和阶段门禁。
+工具细节和使用顺序见 [Harness 工作流](docs/HARNESS_WORKFLOW.md)。
+完整参数见 [命令参考](docs/COMMAND_REFERENCE.md)。
 
-每次进入 Harness 时，KCode 会附带 `.pi/kd/PROJECT_CONTEXT.md`。这份上下文不会替代计划阶段的实际文件检查，但会让 Agent 在暂停、恢复、重新打开终端后仍知道当前项目的源码根、模块线索和禁止猜路径规则。
+## 运行状态文件
 
-每个需求 run 的设计和执行文档会落到本地：
+KCode 只维护当前业务项目内的配置和工作流状态：
 
 ```text
+.pi/settings.json
+.pi/kd/PROJECT_CONTEXT.md
 .pi/kd/active-run.json
 .pi/kd/runs/<run-id>/RUN.json
 .pi/kd/runs/<run-id>/CONTEXT.md
@@ -388,237 +153,15 @@ KCode 会把金蝶开发需求纳入 Harness 工作流。你可以直接输入
 .pi/kd/runs/<run-id>/evidence/index.json
 ```
 
-下次重新 `kcode start` 时，KCode 会提示当前项目的 active run。执行 `/kd-resume` 后，KCode 会读取项目常驻上下文、active run 状态和已生成的阶段文档，再继续当前功能点的当前阶段。已完成或暂停的功能点仍保留在 `.pi/kd/runs/<run-id>/`，可用 `/kd-runs` 查看，用 `/kd-switch <run-id>` 切回。
-
-阶段含义：
-
-```text
-discuss  梳理需求、产品版本、插件类型、目标单据/表单、生命周期和开放问题
-spec     明确验收标准、数据对象、字段、异常、性能和风险
-plan     检查当前项目结构，记录真实目标源码路径、待改文件、查证项和验证命令
-execute  只实现 PLAN.md 中批准的内容
-verify   运行检查、构建或领域验证并记录证据
-ship     汇总变更、验证证据、风险和后续事项
-```
-
-代码写入受门禁控制：
-
-- 未进入 `execute` 阶段时，KCode 会阻止写入 Java/XML/SQL 等产品代码。
-- 进入 `execute` 前必须已有 `PLAN.md` 和必要证据。
-- `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`。
-- 进入 `verify` 前，`EXECUTION.md` 必须逐个完成 `PLAN.md` 中的所有 `STEP-###`，并为每个步骤记录真实存在的 `evidence/...` 文件；同时必须已有 `evidence/tdd-red.md` 和 `evidence/tdd-green.md`。
-- evidence 文件必须登记在 `evidence/index.json` 中。KCode 内置工具和 evidence 写入路径会自动维护索引；不要手工塞文件绕过门禁。
-- `evidence/tdd-green.md` 必须包含真实成功输出和 `Exit: 0` 或 `退出码：0`；不能写“需在开发环境验证”“待验证”“未执行”等不确定结论。
-- 如果门禁提示 evidence 内容无效，不要反复改文案或补关键词；必须重新运行 `PLAN.md` 中声明的真实验证命令，并记录命令、Exit、STDOUT/STDERR 或工具输出。
-- Java / 苍穹 / 星空旗舰版的语法和编译验证优先使用当前项目 Gradle 命令，例如 `.\gradlew.bat build`、`./gradlew build` 或 `.\gradlew.bat :模块:build`。
-- C# / 企业版的语法和编译验证使用 `dotnet build`、`dotnet build <.sln>` 或 `dotnet build <.csproj>`。
-- 不要写“Kingdee IDE 中编译”作为验证方式；如果构建命令无法运行，记录真实阻塞原因和残余风险，不能把它当作绿灯证据。
-- 旗舰版项目必须先检查当前项目结构。若存在 `code/`，跟随 `code/` 下的实际组织；若不存在，必须在 `PLAN.md` 记录实际源码根或目标文件。
-- 不允许凭空写 demo、sample、scaffold，或在不了解项目结构时新建猜测目录。
-
-### SDK 签名门禁怎么用
-
-当需求涉及 Java/C# 插件代码时，KCode 会强制要求先查证当前项目真实 SDK 的类、方法、构造器、枚举或属性签名。这个门禁是为了避免 LLM 根据记忆编出不存在的方法。
-
-推荐操作顺序：
-
-```text
-1. discuss/spec 阶段确认需求、产品、插件类型和目标单据。
-2. plan 阶段检查当前项目源码结构、构建文件和 SDK 依赖位置。
-3. 用 kd_sdk_signature 查证要调用的 SDK 类型和方法。
-4. 确认生成 .pi/kd/runs/<run-id>/evidence/sdk-signature.md。
-5. 记录 evidence/tdd-red.md。
-6. 进入 execute 后再写 PLAN.md 中列出的生产源码。
-7. 写完后记录 evidence/tdd-green.md，再进入 verify。
-```
-
-示例：
-
-```text
-kd_sdk_signature product=flagship query=SaveServiceHelper method=save
-kd_sdk_signature product=flagship query=OperationServiceHelper method=executeOperate
-kd_sdk_signature product=enterprise query=DynamicObject method=GetDynamicObject
-```
-
-如果 `kd_sdk_signature` 找不到结果，不要让 Agent 直接写代码。先检查：
-
-- 当前是否在业务项目根目录启动 `kcode start`。
-- 项目是否能看到 SDK jar/dll，例如 `lib/`、`libs/`、`bin/`、`WebSite/bin/` 或构建缓存。
-- `PLAN.md` 是否记录了真实源码根和 SDK 依赖位置。
-- 是否可以通过当前项目已有封装类、编译输出或官方元数据反查签名。
-
-只有 `kd_sdk_signature`、当前项目构建输出、项目源码封装或官方元数据能作为签名事实。`kd_search`、`kd_cosmic_api` 和 README 里的示例只用于找线索。
-
-示例计划步骤：
-
-```markdown
-## 执行步骤
-
-- [ ] STEP-001：检查现有插件基类、包名和目标字段。
-- [ ] STEP-002：运行 API/元数据/编译等红灯检查并记录证据。
-- [ ] STEP-003：修改 `code/scm/plugin/src/main/java/.../PurchaseOrderPlugin.java`。
-- [ ] STEP-004：运行同一类绿灯检查并记录证据。
-- [ ] STEP-005：记录变更文件和验证证据。
-```
-
-示例红绿检查：
-
-```markdown
-## TDD / 红绿检查
-
-- 红灯证据：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
-## 步骤结果
-
-- [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`。
-
-结构化问题也会进入门禁。Agent 需要确认产品、目标单据、插件位置、高风险 SQL 或方案选择时，会使用 `kd_question` 记录问题；未回答的阻断问题会阻止进入下一阶段。
-
-`kd_question` 一次只允许问一个当前最阻塞的问题，不能把多个问题打包成编号清单。比如应先问：
-
-```text
-采购入库单 Form ID 是否为 pur_receivebill？
-```
-
-得到回答后，再继续问触发时机、库存条件、弹窗内容或插件位置。
-
-在 `kcode start` 的交互式 TUI 中，`kd_question` 会弹出 KCode 问题选择/输入对话，并在用户选择或输入后自动记录答案。非交互模式或 UI 不可用时，问题会显示在对话里，用户直接回复；Agent 读取回复后再记录答案。也可以手动执行：
-
-```text
-/kd-answer Q-001 采购订单
-```
-
-运行状态保存在当前业务项目：
-
-```text
-.pi/kd/active-run.json
-.pi/kd/runs/<run-id>/
-.pi/kd/runs/<run-id>/RUN.json
-```
-
-## 内置金蝶工具
-
-KCode 会向 Pi 注册这些金蝶工具：
-
-```text
-kd_plan_status      查看当前 Harness run、阶段、产物和门禁
-kd_question         记录/回答/查看阻断问题，未回答时阻止阶段推进
-kd_search           搜索内置金蝶 SDK 知识和代码模式
-kd_table            查询内置金蝶表结构
-kd_check            检查金蝶 Java/C# 插件代码
-kd_cosmic_config    运行官方 ok-cosmic 配置预检
-kd_cosmic_metadata  查询官方 Cosmic 表单/单据元数据
-kd_cosmic_api       查询随包 Cosmic API 知识线索
-kd_sdk_signature    从当前项目实际 SDK jar/dll 中读取类和方法签名
-kd_ksql_lint        运行官方 ok-ksql SQL/KSQL lint
-kd_build            按产品画像执行或 dry-run 构建；Java 使用 Gradle，C# 使用 dotnet build
-kd_debug            分析金蝶日志和堆栈
-```
-
-这些工具不依赖本机 Python：
-
-- `kd_ksql_lint` 是内置 Node 静态检查器。
-- `kd_cosmic_config` 使用 Node 校验 Cosmic 官方能力配置；项目没有 `ok-cosmic.json` 时会自动使用 KCode 随包默认配置。
-- `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` 或写生产源码。
-
-示例：
-
-```text
-kd_sdk_signature product=flagship query=QueryServiceHelper method=loadSingle path=lib
-kd_sdk_signature product=enterprise query=DynamicObject method=GetDynamicObject path=bin
-```
-
-`method` 只是在已匹配的类/类型里过滤方法或属性；如果不知道类名，先用 `query` 搜类型关键词，再结合项目源码和构建文件缩小范围。
-
-`ok-cosmic.json` 是可选的 KCode 官方能力覆盖配置，不是苍穹工程模板里的 `cosmic.json`。业务项目里的 `cosmic.json` 通常只包含开发者标识、工程标识、MC 资源地址等运行环境信息，不能替代 `ok-cosmic.json`。
-
-只有需要指定企业统一路由 API 或覆盖知识库路径时，才需要在业务项目根目录创建 `ok-cosmic.json`：
-
-```json
-{
-  "graph": {
-    "dbPath": "D:\\path\\to\\ok-cosmic-docs.db"
-  },
-  "route": {
-    "apiUrl": "https://your-runtime-route.example.com/api",
-    "timeoutSeconds": 10
-  }
-}
-```
+KCode 不要求你单独安装全局 `pi` 命令，也不会修改用户全局 Pi 配置。
 
 ## 升级
 
-查看当前安装版本：
-
-```powershell
-kcode version
-npm ls -g kcode-pi --depth=0
-```
-
-查看 npm 最新版本：
-
-```powershell
-npm view kcode-pi version
-```
-
-升级到最新版本：
-
 ```powershell
 npm install -g kcode-pi@latest
-```
-
-如果 `npm install -g` 没有更新到新版本，或提示 `EEXIST: file already exists ... kcode.cmd`，通常是全局命令 shim 或旧包目录没有被 npm 清干净。按下面顺序处理：
-
-```powershell
-npm uninstall -g kcode-pi
-npm install -g kcode-pi@latest
 kcode version
 ```
 
-如果仍提示 `kcode.cmd` 已存在，先确认它属于旧的 `kcode-pi` 全局安装：
-
-```powershell
-npm root -g
-where kcode
-```
-
-删除 `where kcode` 指向的旧 `kcode.cmd`、`kcode.ps1` 后再重装：
-
-```powershell
-npm install -g kcode-pi@latest
-```
-
-如果 npm 仍使用缓存或企业镜像没有同步新版本，先确认 registry 上真实可安装版本：
-
-```powershell
-npm view kcode-pi version
-npm view kcode-pi versions --json
-```
-
 升级后建议在业务项目根目录重新执行：
 
 ```powershell
@@ -626,137 +169,4 @@ kcode init
 kcode doctor --deep
 ```
 
-## nvm 与 Node 版本切换
-
-如果使用 nvm，Windows 上每个 Node 版本都有独立的全局 npm 安装目录，例如：
-
-```text
-C:\Users\Administrator\AppData\Local\nvm\v24.16.0\node_modules\kcode-pi
-C:\Users\Administrator\AppData\Local\nvm\v22.19.0\node_modules\kcode-pi
-```
-
-切换 Node 版本并重新全局安装 KCode 后，在业务项目根目录重新执行：
-
-```powershell
-kcode init
-```
-
-`kcode-pi@0.1.2` 起会自动清理 `.pi/settings.json` 中同名旧路径，只保留当前 Node 版本下的安装路径。
-
-如果旧版本已经出现工具冲突：
-
-```text
-Tool "kd_search" conflicts with ...\nvm\v22.19.0\node_modules\kcode-pi\extensions\kingdee-tools.ts
-```
-
-打开当前业务项目的配置：
-
-```powershell
-notepad .pi\settings.json
-```
-
-删除旧 Node 版本下的 `kcode-pi` 路径，只保留当前 `nvm current` 对应的那一条，然后运行：
-
-```powershell
-kcode start
-```
-
-## 常见问题
-
-### 找不到模型
-
-现象：
-
-```text
-Warning: No models available.
-```
-
-处理：
-
-```text
-/login
-/model
-```
-
-或先设置供应商 API Key，再运行 `kcode start`。
-
-### 终端输入逐字换行或选择列表有残影
-
-这通常是 Pi TUI 与当前终端/Node/TTY 环境的兼容问题。优先使用：
-
-- Windows Terminal
-- Node.js `22.19.0` 或更新的 Node 22 LTS
-- 宽度正常的终端窗口
-
-检查终端尺寸：
-
-```powershell
-node -e "console.log({isTTY:process.stdout.isTTY, columns:process.stdout.columns, rows:process.stdout.rows, term:process.env.TERM})"
-```
-
-如果 `columns` 很小或异常，重新打开 Windows Terminal，或尝试：
-
-```powershell
-$env:TERM="xterm-256color"
-$env:COLORTERM="truecolor"
-kcode start
-```
-
-也可以在 Pi 全局设置中启用兼容项：
-
-```powershell
-notepad $env:USERPROFILE\.pi\agent\settings.json
-```
-
-写入或合并：
-
-```json
-{
-  "terminal": {
-    "clearOnShrink": true
-  },
-  "showHardwareCursor": true
-}
-```
-
-### 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
-
-先检查当前项目配置：
-
-```powershell
-type .pi\settings.json
-```
-
-如果 `packages` 中有多条 `kcode-pi` 路径，运行：
-
-```powershell
-kcode repair
-```
-
-如果使用的是 `0.1.1` 或更早版本，请手工删除旧路径，或升级到最新版。
-
-## 更多文档
-
-维护者和开发文档放在：
-
-```text
-docs/DEVELOPMENT.md
-docs/KCODE_DISTRIBUTION.md
-```
+更多升级和异常处理见 [故障排查](docs/TROUBLESHOOTING.md)。