KCode

KCode 是面向金蝶开发的 Pi 工作环境启动器。安装后会提供全局命令 kcode，自动携带 Pi CLI，并在当前业务项目中加载金蝶专属工具、skills、prompts、themes 和知识库。

KCode 不要求你单独安装全局 pi 命令，也不会修改用户全局 Pi 配置。它只维护当前项目的：

.pi/settings.json

安装

环境要求：

• Node.js >=22.19.0
• npm
• Windows 推荐使用 Windows Terminal
• 不需要安装 Python。KCode 随包工具使用 Node/TypeScript 实现；只有你自己的业务项目或外部脚本明确依赖 Python 时才需要另行安装。

全局安装：

npm install -g kcode-pi

如果企业内发布包名不是 kcode-pi，请替换为实际包名。全局命令仍是：

kcode

首次使用

进入你的业务项目根目录，不是 KCode 源码目录：

cd E:\projects\your-business-project

初始化项目级 KCode 配置：

kcode init

init 会登记 KCode package，并生成项目常驻上下文：

.pi/kd/PROJECT_CONTEXT.md

如果项目结构后来变化，手动刷新：

kcode context --refresh

检查环境：

kcode doctor

查看当前 KCode 版本：

kcode version

启动工作环境：

kcode start

kcode start 会先确保 .pi/settings.json 已登记当前安装的 KCode package，然后启动随包 Pi CLI。

配置模型

首次启动 Pi 时，如果看到：

Warning: No models available.

说明还没有配置模型供应商。进入 kcode start 后输入：

/login

选择供应商并登录或填写 API Key。常见选择包括：

ChatGPT Plus/Pro (Codex)
Claude Pro/Max
GitHub Copilot
OpenAI
Anthropic
DeepSeek
Gemini

也可以在 PowerShell 中设置环境变量后再启动：

$env:OPENAI_API_KEY="sk-..."
kcode start

或：

$env:ANTHROPIC_API_KEY="sk-ant-..."
kcode start

登录或配置完成后，可在 Pi 中使用：

/model

选择模型。

自定义模型供应商

如果你的模型服务是企业网关、代理服务、Ollama、LM Studio、vLLM，或其他 OpenAI-compatible endpoint，不需要改 KCode。Pi 原生支持通过用户级配置文件添加自定义供应商：

notepad $env:USERPROFILE\.pi\agent\models.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 并启动：

$env:CORP_AI_API_KEY="sk-..."
kcode start

进入后使用：

/model

选择 corp-ai/corp-coder。也可以直接指定：

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。

kcode init

它只修改当前项目，不写用户全局 Pi 配置。kcode-pi@0.1.2 起，init 会自动清理同名旧 KCode package 路径，避免 Node 版本切换后重复加载。

同时会确保项目常驻上下文存在：

.pi/kd/PROJECT_CONTEXT.md

这份文件记录项目根目录、真实源码根、构建文件、模块线索和 KCode 持久约束。KCode Harness 会在每次对话继续时读取它，降低中断后丢失项目结构上下文的风险。

kcode context

生成或刷新项目常驻上下文。

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 路径和项目配置。

kcode doctor

kcode version

显示当前 KCode package 版本、安装路径、随包 Pi CLI 版本和 Node 版本。

kcode version
kcode --version
kcode -v

kcode start

启动 KCode 工作环境。

kcode start

start 后面的参数会原样透传给 Pi CLI，例如：

kcode start --provider openai --model gpt-4o

Pi 内 KCode 命令

进入 kcode start 后，可以使用以下 KCode 命令：

/kd-start [--product product] [--version version] <goal>
/kd-product <product> [--version version]
/kd-status
/kd-runs
/kd-switch <run-id>
/kd-finish
/kd-gate
/kd-advance [phase]
/kd-artifact [phase] [content]
/kd-answer Q-001 <answer>

典型开始方式：

/kd-start --product flagship 实现采购订单插件

支持的产品画像：

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 阶段。

工作流阶段：

discuss -> spec -> plan -> execute -> verify -> ship

KCode 会把金蝶开发需求纳入 Harness 工作流。你可以直接输入自然语言需求；如果当前项目还没有 active run，KCode 会自动创建 run 并进入 discuss 阶段，而不是直接生成代码。

一个功能点对应一个 run。每个 run 都有独立阶段、计划、执行记录和证据；做另一个功能点时，不要复用上一个功能点的阶段。

/kd-start 实现采购订单保存校验
/kd-finish
/kd-start 实现采购订单列表字段展示

查看和切换当前项目里的功能点 run：

/kd-runs
/kd-switch <run-id>

如果当前 active run 处于 execute 或 verify，但你提出的是另一个需求，KCode 会要求先创建新 run 或切换 run，避免把新需求塞进旧功能点的 PLAN.md 和阶段门禁。

每次进入 Harness 时，KCode 会附带 .pi/kd/PROJECT_CONTEXT.md。这份上下文不会替代计划阶段的实际文件检查，但会让 Agent 在暂停、恢复、重新打开终端后仍知道当前项目的源码根、模块线索和禁止猜路径规则。

每个需求 run 的设计和执行文档会落到本地：

.pi/kd/active-run.json
.pi/kd/runs/<run-id>/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、项目常驻上下文和已生成的阶段文档，再继续当前功能点的当前阶段。已完成或暂停的功能点仍保留在 .pi/kd/runs/<run-id>/，可用 /kd-runs 查看，用 /kd-switch <run-id> 切回。

阶段含义：

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，或在不了解项目结构时新建猜测目录。

示例计划步骤：

## Execution Steps

- [ ] STEP-001: 检查现有插件基类、包名和目标字段。
- [ ] STEP-002: 运行 API/元数据/编译等红灯检查并记录证据。
- [ ] STEP-003: 修改 `code/scm/plugin/src/main/java/.../PurchaseOrderPlugin.java`。
- [ ] STEP-004: 运行同一类绿灯检查并记录证据。
- [ ] STEP-005: 记录变更文件和验证证据。

示例红绿检查：

## TDD / Red-Green Checks

- 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.

示例执行记录：

## 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。

结构化问题也会进入门禁。Agent 需要确认产品、目标单据、插件位置、高风险 SQL 或方案选择时，会使用 kd_question 记录问题；未回答的阻断问题会阻止进入下一阶段。

kd_question 一次只允许问一个当前最阻塞的问题，不能把多个问题打包成编号清单。比如应先问：

采购入库单 Form ID 是否为 pur_receivebill？

得到回答后，再继续问触发时机、库存条件、弹窗内容或插件位置。

在 kcode start 的交互式 TUI 中，kd_question 会弹出 KCode Question 选择/输入对话，并在用户选择或输入后自动记录答案。非交互模式或 UI 不可用时，问题会显示在对话里，用户直接回复；Agent 读取回复后再记录答案。也可以手动执行：

/kd-answer Q-001 采购订单

运行状态保存在当前业务项目：

.pi/kd/active-run.json
.pi/kd/runs/<run-id>/
.pi/kd/runs/<run-id>/RUN.json

内置金蝶工具

KCode 会向 Pi 注册这些金蝶工具：

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 构建
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 或编译输出确认。

示例：

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：

{
  "graph": {
    "dbPath": "D:\\path\\to\\ok-cosmic-docs.db"
  },
  "route": {
    "apiUrl": "https://your-runtime-route.example.com/api",
    "timeoutSeconds": 10
  }
}

升级

查看当前安装版本：

kcode version
npm ls -g kcode-pi --depth=0

查看 npm 最新版本：

npm view kcode-pi version

升级到最新版本：

npm install -g kcode-pi@latest

升级后建议在业务项目根目录重新执行：

kcode init
kcode doctor

nvm 与 Node 版本切换

如果使用 nvm，Windows 上每个 Node 版本都有独立的全局 npm 安装目录，例如：

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 后，在业务项目根目录重新执行：

kcode init

kcode-pi@0.1.2 起会自动清理 .pi/settings.json 中同名旧路径，只保留当前 Node 版本下的安装路径。

如果旧版本已经出现工具冲突：

Tool "kd_search" conflicts with ...\nvm\v22.19.0\node_modules\kcode-pi\extensions\kingdee-tools.ts

打开当前业务项目的配置：

notepad .pi\settings.json

删除旧 Node 版本下的 kcode-pi 路径，只保留当前 nvm current 对应的那一条，然后运行：

kcode start

常见问题

找不到模型

现象：

Warning: No models available.

处理：

/login
/model

或先设置供应商 API Key，再运行 kcode start。

终端输入逐字换行或选择列表有残影

这通常是 Pi TUI 与当前终端/Node/TTY 环境的兼容问题。优先使用：

• Windows Terminal
• Node.js 22.19.0 或更新的 Node 22 LTS
• 宽度正常的终端窗口

检查终端尺寸：

node -e "console.log({isTTY:process.stdout.isTTY, columns:process.stdout.columns, rows:process.stdout.rows, term:process.env.TERM})"

如果 columns 很小或异常，重新打开 Windows Terminal，或尝试：

$env:TERM="xterm-256color"
$env:COLORTERM="truecolor"
kcode start

也可以在 Pi 全局设置中启用兼容项：

notepad $env:USERPROFILE\.pi\agent\settings.json

写入或合并：

{
  "terminal": {
    "clearOnShrink": true
  },
  "showHardwareCursor": true
}

Windows 下出现 /mnt/d/... 找不到文件

现象：

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

先检查当前项目配置：

type .pi\settings.json

如果 packages 中有多条 kcode-pi 路径，运行：

kcode init

如果使用的是 0.1.1 或更早版本，请手工删除旧路径，或升级到最新版。

更多文档

维护者和开发文档放在：

docs/DEVELOPMENT.md
docs/KCODE_DISTRIBUTION.md