kcode-pi 0.1.1 → 0.1.4

package/README.md

@@ -1,191 +1,257 @@
-# KCodeV2
+# KCode
 
-KCodeV2 是面向金蝶开发的 Pi package 和企业启动器原型。
+KCode 是面向金蝶开发的 Pi 工作环境启动器。安装后会提供全局命令 `kcode`，自动携带 Pi CLI，并在当前业务项目中加载金蝶专属工具、skills、prompts、themes 和知识库。
 
-它不 fork Pi，也不替换 Pi 生态。当前仓库主要提供：
-
-- 金蝶专属 tools、skills、prompts、themes。
-- 金蝶 Harness Engineering 工作流。
-- 官方金蝶 skills 的 vendor 资源和 Pi 适配器。
-- `kcode` 企业入口，用项目级 `.pi/settings.json` 加载 KCode package，并通过随包 Pi CLI 启动工作环境。
-
-## 当前定位
-
-当前仓库是：
+KCode 不要求你单独安装全局 `pi` 命令，也不会修改用户全局 Pi 配置。它只维护当前项目的：
 
 ```text
-kcode-pi
+.pi/settings.json
 ```
 
-也就是金蝶 Pi package，同时包含 `kcode-cli` 的仓库内原型。
-
-仓库内的 `npm run kcode -- ...` 是启动器原型，用于验证 `kcode-cli` 的设计。企业入口由两部分组成：
+## 安装
 
-```text
-kcode-pi   金蝶 Pi package，本仓库
-kcode-cli  企业启动器，自动携带 Pi CLI，并启动 KCode 工作环境
-```
-
-## 环境要求
+环境要求：
 
 - Node.js `>=22.19.0`
 - npm
-- Pi CLI 由 KCode 运行依赖自动携带
+- Windows 推荐使用 Windows Terminal
 
-当前机器如果没有全局 `pi` 命令，`kcode start` 会优先使用随包的 Pi CLI。
+全局安装：
+
+```powershell
+npm install -g kcode-pi
+```
 
-检查 KCode 能否找到 Pi CLI：
+如果企业内发布包名不是 `kcode-pi`，请替换为实际包名。全局命令仍是：
 
 ```powershell
-npm run kcode -- doctor
+kcode
 ```
 
-## 快速开始
+## 首次使用
 
-发布到 npm 后，开发者可以直接全局安装：
+进入你的业务项目根目录，不是 KCode 源码目录：
 
 ```powershell
-npm install -g kcode-pi
+cd E:\projects\your-business-project
 ```
 
-安装后会得到全局 `kcode` 命令。进入业务项目根目录，初始化 KCode 工作环境：
+初始化项目级 KCode 配置：
 
 ```powershell
 kcode init
 ```
 
-检查 Node、随包 Pi CLI 和项目级配置：
+`init` 会登记 KCode package，并生成项目常驻上下文：
+
+```text
+.pi/kd/PROJECT_CONTEXT.md
+```
+
+如果项目结构后来变化，手动刷新：
+
+```powershell
+kcode context --refresh
+```
+
+检查环境：
 
 ```powershell
 kcode doctor
 ```
 
-启动 KCode 工作环境：
+启动工作环境：
 
 ```powershell
 kcode start
 ```
 
-如果发布时改用 `kcode-cli` 或 `@kingdee/kcode-cli` 包名，把安装命令中的 `kcode-pi` 替换为实际包名即可；全局命令仍是 `kcode`。
+`kcode start` 会先确保 `.pi/settings.json` 已登记当前安装的 KCode package，然后启动随包 Pi CLI。
+
+## 配置模型
+
+首次启动 Pi 时，如果看到：
+
+```text
+Warning: No models available.
+```
+
+说明还没有配置模型供应商。进入 `kcode start` 后输入：
+
+```text
+/login
+```
+
+选择供应商并登录或填写 API Key。常见选择包括：
 
-## 源码开发
+```text
+ChatGPT Plus/Pro (Codex)
+Claude Pro/Max
+GitHub Copilot
+OpenAI
+Anthropic
+DeepSeek
+Gemini
+```
 
-需要修改 KCodeV2 本身时，再 clone 仓库并安装依赖：
+也可以在 PowerShell 中设置环境变量后再启动：
 
 ```powershell
-git clone <KCodeV2仓库地址>
-cd KCodeV2
-npm install
+$env:OPENAI_API_KEY="sk-..."
+kcode start
 ```
 
-源码仓库内可以用 npm script 调试同一个入口：
+或：
 
 ```powershell
-npm run kcode -- doctor
-npm run kcode -- init
-npm run kcode -- start
+$env:ANTHROPIC_API_KEY="sk-ant-..."
+kcode start
 ```
 
-## 安装依赖
+登录或配置完成后，可在 Pi 中使用：
+
+```text
+/model
+```
+
+选择模型。
+
+### 自定义模型供应商
 
-在仓库根目录执行：
+如果你的模型服务是企业网关、代理服务、Ollama、LM Studio、vLLM，或其他 OpenAI-compatible endpoint，不需要改 KCode。Pi 原生支持通过用户级配置文件添加自定义供应商：
 
 ```powershell
-npm install
+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
-npm run check
-npm run build:cli
-npm run smoke:knowledge
-npm run smoke:checker
-npm run smoke:harness
-npm run smoke:official
-npm run smoke:build-debug
-npm run smoke:package
-npm run smoke:kcode-cli
+$env:CORP_AI_API_KEY="sk-..."
+kcode start
 ```
 
-这些 smoke 分别验证：
-
-- TypeScript 类型检查。
-- 金蝶知识库搜索。
-- `kd_check` 静态规则。
-- Harness 阶段和门禁。
-- 官方脚本适配器。
-- 构建/调试诊断。
-- package manifest、skills、vendor 文件完整性。
-- `kcode` 项目级入口逻辑。
+进入后使用：
 
-## KCode 企业入口原型
+```text
+/model
+```
 
-当前仓库提供 `kcode` 命令。发布后可直接运行全局命令；源码调试时使用 `npm run kcode -- ...`。它不会写用户全局 Pi 配置，只管理当前项目的 `.pi/settings.json`：
+选择 `corp-ai/corp-coder`。也可以直接指定：
 
 ```powershell
-kcode init
-kcode doctor
-kcode start
+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 配置：
+初始化或更新当前项目的 `.pi/settings.json`。
 
 ```powershell
 kcode init
 ```
 
-它只写当前项目：
+它只修改当前项目，不写用户全局 Pi 配置。`kcode-pi@0.1.2` 起，`init` 会自动清理同名旧 KCode package 路径，避免 Node 版本切换后重复加载。
+
+同时会确保项目常驻上下文存在：
 
 ```text
-.pi/settings.json
+.pi/kd/PROJECT_CONTEXT.md
 ```
 
-不会修改用户全局 Pi 配置。
+这份文件记录项目根目录、真实源码根、构建文件、模块线索和 KCode 持久约束。KCode Harness 会在每次对话继续时读取它，降低中断后丢失项目结构上下文的风险。
 
-生成内容会把当前 KCodeV2 package 加入项目级 packages，例如：
+### `kcode context`
 
-```json
-{
-  "packages": [
-    "E:\\projects\\kingdee\\KCodeV2"
-  ]
-}
+生成或刷新项目常驻上下文。
+
+```powershell
+kcode context
+kcode context --refresh
 ```
 
+建议在以下情况刷新：
+
+- 初次接入已有业务项目。
+- 新增、移动或删除模块。
+- 从分支切换到不同项目结构。
+- 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`，让绝对路径和源码根重新匹配当前目录。
+
 ### `kcode doctor`
 
-检查当前环境：
+检查 Node、随包 Pi CLI、KCode package 路径和项目配置。
 
 ```powershell
 kcode doctor
 ```
 
-它会检查：
-
-- Node 版本。
-- 是否能找到随包 Pi CLI。
-- KCode package 路径。
-- 当前项目 `.pi/settings.json` 是否存在。
-- KCode package 是否已写入项目级配置。
-
 ### `kcode start`
 
-初始化项目配置后启动 KCode 工作环境：
+启动 KCode 工作环境。
 
 ```powershell
 kcode start
 ```
 
-`kcode start` 会先写入项目级 `.pi/settings.json`，再优先通过随包 `@earendil-works/pi-coding-agent` 的 CLI 启动 Pi；只有随包 CLI 不存在时才回退全局 `pi`。传给 `start` 的后续参数会原样透传给 Pi CLI。
+`start` 后面的参数会原样透传给 Pi CLI，例如：
 
-## Pi 内使用方式
+```powershell
+kcode start --provider openai --model gpt-4o
+```
 
-安装到 Pi 后，KCodeV2 提供以下命令：
+## Pi 内 KCode 命令
+
+进入 `kcode start` 后，可以使用以下 KCode 命令：
 
 ```text
 /kd-start [--product product] [--version version] <goal>
@@ -196,22 +262,124 @@ kcode start
 /kd-artifact [phase] [content]
 ```
 
+典型开始方式：
+
+```text
+/kd-start --product flagship 实现采购订单插件
+```
+
+支持的产品画像：
+
+```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
 ```
 
-运行状态保存在：
+KCode 会把金蝶开发需求纳入 Harness 工作流。你可以直接输入自然语言需求；如果当前项目还没有 active run，KCode 会自动创建 run 并进入 `discuss` 阶段，而不是直接生成代码。
+
+每次进入 Harness 时，KCode 会附带 `.pi/kd/PROJECT_CONTEXT.md`。这份上下文不会替代计划阶段的实际文件检查，但会让 Agent 在暂停、恢复、重新打开终端后仍知道当前项目的源码根、模块线索和禁止猜路径规则。
+
+每个需求 run 的设计和执行文档会落到本地：
+
+```text
+.pi/kd/active-run.json
+.pi/kd/runs/<run-id>/CONTEXT.md
+.pi/kd/runs/<run-id>/SPEC.md
+.pi/kd/runs/<run-id>/PLAN.md
+.pi/kd/runs/<run-id>/EXECUTION.md
+.pi/kd/runs/<run-id>/VERIFY.md
+.pi/kd/runs/<run-id>/SHIP.md
+.pi/kd/runs/<run-id>/evidence/
+```
+
+下次重新 `kcode start` 时，KCode 会读取当前项目的 active run、项目常驻上下文和已生成的阶段文档，再继续当前阶段。
+
+阶段含义：
+
+```text
+discuss  梳理需求、产品版本、插件类型、目标单据/表单、生命周期和开放问题
+spec     明确验收标准、数据对象、字段、异常、性能和风险
+plan     检查当前项目结构，记录真实目标源码路径、待改文件、查证项和验证命令
+execute  只实现 PLAN.md 中批准的内容
+verify   运行检查、构建或领域验证并记录证据
+ship     汇总变更、验证证据、风险和后续事项
+```
+
+代码写入受门禁控制：
+
+- 未进入 `execute` 阶段时，KCode 会阻止写入 Java/XML/SQL 等产品代码。
+- 进入 `execute` 前必须已有 `PLAN.md` 和必要证据。
+- `PLAN.md` 必须包含 `## Execution Steps`，并用 `- [ ] STEP-001: ...` 格式拆分可跟踪步骤。
+- `PLAN.md` 必须包含 `## TDD / Red-Green Checks`，声明红灯证据、绿灯证据和测试/检查命令。
+- 红绿检查不等于必须写 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`。
+- 旗舰版项目必须先检查当前项目结构。若存在 `code/`，跟随 `code/` 下的实际组织；若不存在，必须在 `PLAN.md` 记录实际源码根或目标文件。
+- 不允许凭空写 demo、sample、scaffold，或在不了解项目结构时新建猜测目录。
+
+示例计划步骤：
+
+```markdown
+## Execution Steps
+
+- [ ] STEP-001: 检查现有插件基类、包名和目标字段。
+- [ ] STEP-002: 运行 API/元数据/编译等红灯检查并记录证据。
+- [ ] STEP-003: 修改 `code/scm/plugin/src/main/java/.../PurchaseOrderPlugin.java`。
+- [ ] STEP-004: 运行同一类绿灯检查并记录证据。
+- [ ] STEP-005: 记录变更文件和验证证据。
+```
+
+示例红绿检查：
+
+```markdown
+## TDD / Red-Green Checks
+
+- Red evidence: evidence/tdd-red.md
+- Green evidence: evidence/tdd-green.md
+- Red/green command or tool: kd_cosmic_api detail / kd_cosmic_metadata / kd_check / build
+- Do not add third-party test jars or frameworks only for this gate.
+```
+
+示例执行记录：
+
+```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
+```
+
+如果 LLM 跳过步骤、没有记录 evidence，或只是口头声明完成，KCode 不允许进入 `verify`。
+
+运行状态保存在当前业务项目：
 
 ```text
 .pi/kd/active-run.json
 .pi/kd/runs/<run-id>/
 ```
 
-## 金蝶工具
+## 内置金蝶工具
 
-当前注册的主要工具：
+KCode 会向 Pi 注册这些金蝶工具：
 
 ```text
 kd_plan_status      查看当前 Harness run、阶段、产物和门禁
@@ -226,133 +394,147 @@ kd_build            按产品画像执行或 dry-run 构建
 kd_debug            分析金蝶日志和堆栈
 ```
 
-## 产品画像
+## 升级
 
-KCodeV2 会区分金蝶产品和技术栈：
+查看当前安装版本：
 
-```text
-cosmic     -> Cosmic 平台底座
-cangqiong  -> Cosmic / Java
-xinghan    -> Cosmic / Java
-flagship   -> Cosmic / Java
-enterprise -> Enterprise / C#
+```powershell
+npm ls -g kcode-pi --depth=0
 ```
 
-未知产品不能离开 `discuss` 阶段。不要把 Cosmic Java API 和 Enterprise C# API 混用。
+查看 npm 最新版本：
 
-## 官方 skills 资源
+```powershell
+npm view kcode-pi version
+```
 
-官方金蝶 skills 以 vendor 形式保存在：
+升级到最新版本：
 
-```text
-vendor/kingdee-skills
+```powershell
+npm install -g kcode-pi@latest
+```
+
+升级后建议在业务项目根目录重新执行：
+
+```powershell
+kcode init
+kcode doctor
 ```
 
-包含：
+## nvm 与 Node 版本切换
+
+如果使用 nvm，Windows 上每个 Node 版本都有独立的全局 npm 安装目录，例如：
 
 ```text
-ok-cosmic
-ok-ksql
-kingdee-cosmic-reviewer
-cosmic-unittest
+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
 ```
 
-运行时默认使用包内 vendor 目录。本地开发可通过环境变量覆盖：
+切换 Node 版本并重新全局安装 KCode 后，在业务项目根目录重新执行：
 
 ```powershell
-$env:KCODE_KINGDEE_SKILLS_ROOT="E:\projects\kingdee\skills"
+kcode init
 ```
 
-## 官方证据与门禁
+`kcode-pi@0.1.2` 起会自动清理 `.pi/settings.json` 中同名旧路径，只保留当前 Node 版本下的安装路径。
 
-官方工具在存在 active run 时会写入证据：
+如果旧版本已经出现工具冲突：
 
 ```text
-.pi/kd/runs/<run-id>/evidence/cosmic-config.txt
-.pi/kd/runs/<run-id>/evidence/cosmic-metadata.json
-.pi/kd/runs/<run-id>/evidence/cosmic-api.txt
-.pi/kd/runs/<run-id>/evidence/ksql-lint.txt
+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` 对应的那一条，然后运行：
 
-- Cosmic 体系进入 `execute` 前必须有配置证据。
-- `PLAN.md` 声明字段/元数据验证时，进入 `execute` 前必须有 metadata 证据。
-- `PLAN.md` 声明 API/方法签名验证时，进入 `execute` 前必须有 API 证据。
-- KSQL/数据修复交付进入 `ship` 前必须有 metadata 和 lint 证据。
+```powershell
+kcode start
+```
 
-## Skills
+## 常见问题
 
-Pi-native skills 位于：
+### 找不到模型
+
+现象：
 
 ```text
-skills/
+Warning: No models available.
 ```
 
-核心金蝶 skills：
+处理：
 
 ```text
-kd-cosmic-dev
-kd-cosmic-review
-kd-cosmic-unittest
-kd-ksql
-kd-gen
-kd-check
-kd-plan
-kd-execute
-kd-verify
-kd-ship
+/login
+/model
 ```
 
-新增和维护文档、注释时，默认使用中文。
-
-## 打包策略
+或先设置供应商 API Key，再运行 `kcode start`。
 
-当前不内置第三方 Pi packages。
+### 终端输入逐字换行或选择列表有残影
 
-推荐策略：
+这通常是 Pi TUI 与当前终端/Node/TTY 环境的兼容问题。优先使用：
 
-- 不 fork Pi。
-- 不改用户全局 Pi 配置。
-- 第三方 Pi package 先进入 allowlist，再写入项目级 `.pi/settings.json`。
-- 只有离线交付或强依赖时，才考虑 `dependencies` + `bundledDependencies` 内置。
+- Windows Terminal
+- Node.js `22.19.0` 或更新的 Node 22 LTS
+- 宽度正常的终端窗口
 
-详细方案见：
+检查终端尺寸：
 
-```text
-docs/KCODE_DISTRIBUTION.md
+```powershell
+node -e "console.log({isTTY:process.stdout.isTTY, columns:process.stdout.columns, rows:process.stdout.rows, term:process.env.TERM})"
 ```
 
-## 发布 npm 包
+如果 `columns` 很小或异常，重新打开 Windows Terminal，或尝试：
 
-发布前确认 `package.json` 中的包名、版本和 npm registry。当前包名是 `kcode-pi`，也可以发布前改成企业内约定的 `kcode-cli` 或 `@kingdee/kcode-cli`。
+```powershell
+$env:TERM="xterm-256color"
+$env:COLORTERM="truecolor"
+kcode start
+```
 
-发布检查：
+也可以在 Pi 全局设置中启用兼容项：
 
 ```powershell
-npm run check
-npm run build:cli
-npm run smoke:package
-npm pack --dry-run
+notepad $env:USERPROFILE\.pi\agent\settings.json
 ```
 
-发布：
+写入或合并：
+
+```json
+{
+  "terminal": {
+    "clearOnShrink": true
+  },
+  "showHardwareCursor": true
+}
+```
+
+### 仍然加载旧版本 KCode
+
+先检查当前项目配置：
 
 ```powershell
-npm publish
+type .pi\settings.json
 ```
 
-`prepack` 会自动执行 `build:cli` 和 `smoke:package`，确保发布包里有全局 `kcode` 入口和随包 Pi CLI 运行依赖。
+如果 `packages` 中有多条 `kcode-pi` 路径，运行：
 
-## 当前限制
+```powershell
+kcode init
+```
 
-- 当前仓库可以直接发布为 npm 包，但包名仍是 `kcode-pi`；如果企业侧要叫 `kcode-cli`，发布前需要调整 `package.json.name`。
-- 更深层的 reviewer 语义规则、HTML 审查报告、自动 SQL 产物生成仍在后续计划中。
+如果使用的是 `0.1.1` 或更早版本，请手工删除旧路径，或升级到最新版。
 
-## 状态文档
+## 更多文档
 
-集成进度见：
+维护者和开发文档放在：
 
 ```text
-OFFICIAL_SKILLS_STATUS.md
+docs/DEVELOPMENT.md
+docs/KCODE_DISTRIBUTION.md
 ```