kcode-pi 0.1.20 → 0.1.23

package/docs/EVIDENCE_AND_GATES.md

@@ -0,0 +1,168 @@
+# 证据和门禁
+
+KCode Harness 的门禁用于避免跳阶段、猜 SDK、伪造验证结果或在错误产品技术栈上写代码。
+
+## 查看门禁
+
+```text
+/kd-gate
+/kd-status
+```
+
+门禁不通过时，先按原因补齐产品、文档、问题答案、计划、证据或风险说明。
+
+## 产品确认
+
+当需求涉及具体金蝶产品实现、构建、元数据或 SDK 查证时，需要确认产品画像：
+
+```text
+/kd-product cangqiong --version V6.0
+```
+
+如果只是整理需求文档或处理产品无关的工程事项，可以先完成需求梳理，并在计划中写明不涉及产品实现。后续实际要改金蝶产品代码、构建、元数据或 SDK 时，再按范围确认产品。
+
+详见 [产品画像确认](PRODUCT_PROFILE.md)。
+
+## 计划门禁
+
+进入 `execute` 前，`PLAN.md` 必须包含：
+
+- 已检查的项目结构。
+- 目标源码根 / 路径。
+- 允许修改的文件。
+- 必需的金蝶查证项。
+- `## 执行步骤`，并用 `- [ ] STEP-001：...` 格式拆分步骤。
+- `## TDD / 红绿检查`。
+- `## 验证命令`。
+- 回滚 / 影响控制。
+
+`execute` 阶段只能写 `PLAN.md` 明确列出的源码文件。
+
+## SDK 签名证据
+
+涉及 Java/C# 产品代码时，进入 `execute` 前必须已有：
+
+```text
+evidence/sdk-signature.md
+```
+
+推荐工具：
+
+```text
+kd_sdk_signature product=cangqiong query=QueryServiceHelper method=loadSingle
+kd_sdk_signature product=flagship query=SaveServiceHelper method=save
+kd_sdk_signature product=enterprise query=DynamicObject method=GetDynamicObject
+```
+
+只有这些来源可以作为签名事实：
+
+- `kd_sdk_signature` 从当前项目真实 jar/dll 读取的结果。
+- 当前项目构建输出。
+- 项目源码封装。
+- 官方元数据。
+
+`kd_search`、`kd_cosmic_api` 和随包知识只能作为线索。
+
+## TDD 红绿证据
+
+写生产源码前必须有红灯证据：
+
+```text
+evidence/tdd-red.md
+```
+
+进入 `verify` 前必须有绿灯证据：
+
+```text
+evidence/tdd-green.md
+```
+
+绿灯证据必须包含真实成功输出和：
+
+```text
+Exit: 0
+```
+
+或：
+
+```text
+退出码：0
+```
+
+不能写：
+
+- “需在开发环境验证”
+- “待验证”
+- “未执行”
+- “应该可以”
+- “Kingdee IDE 中编译”
+
+如果命令无法运行，记录真实阻塞原因和残余风险，不能把它当绿灯。
+
+## evidence/index.json
+
+所有 evidence 文件必须登记在：
+
+```text
+evidence/index.json
+```
+
+KCode 内置工具和统一 evidence 写入路径会自动维护索引。不要手工塞文件绕过门禁。
+
+常见 evidence：
+
+```text
+evidence/sdk-signature.md
+evidence/cosmic-config.txt
+evidence/cosmic-metadata.json
+evidence/cosmic-api.txt
+evidence/ksql-lint.txt
+evidence/tdd-red.md
+evidence/tdd-green.md
+evidence/step-001.md
+```
+
+## Cosmic 官方能力证据
+
+苍穹、星瀚和星空旗舰版通常需要：
+
+```text
+kd_cosmic_config product=cangqiong
+kd_cosmic_metadata product=cangqiong form=<formId或单据名>
+kd_cosmic_api product=cangqiong mode=search query=<关键词>
+```
+
+这些工具成功执行后会自动写入 run 目录下的 evidence 文件。
+
+## KSQL / SQL 证据
+
+交付 KSQL/SQL 数据修复内容时，ship 前通常需要：
+
+```text
+evidence/cosmic-metadata.json
+evidence/ksql-lint.txt
+```
+
+运行：
+
+```text
+kd_ksql_lint product=cangqiong path=<sql文件路径>
+```
+
+## 风险确认
+
+进入 `ship` 前必须确认风险等级和原因：
+
+```text
+/kd-risk low 已完成本地构建和元数据检查，无残余交付风险
+```
+
+等级：
+
+```text
+low
+medium
+high
+```
+
+风险原因应来自 `VERIFY.md` 和 `SHIP.md` 的真实验证结果，不要为了过门禁随手写 `low`。

package/docs/HARNESS_WORKFLOW.md

@@ -0,0 +1,149 @@
+# Harness 工作流
+
+KCode Harness 把金蝶开发工作拆成固定阶段：
+
+```text
+discuss -> spec -> plan -> execute -> verify -> ship
+```
+
+run 可以是一条明确需求，也可以是一组同一目标下的需求。
+
+## 创建 run
+
+推荐显式指定产品：
+
+```text
+/kd-start --product cangqiong 实现采购订单保存校验
+```
+
+也可以直接提供需求文档来源，例如本地文件、目录或在线文档链接：
+
+```text
+/kd-start E:\project\docs\需求说明.md
+/kd-start https://example.com/requirements
+```
+
+在线文档如果需要登录或权限，KCode 会提示你提供可访问链接、导出文件路径或关键内容。
+
+如果你直接输入自然语言需求，KCode 会自动创建 run，并进入 `discuss` 阶段分析需求来源和范围。
+
+查看当前状态：
+
+```text
+/kd-status
+/kd-gate
+```
+
+如果产品未知，先看 [产品画像确认](PRODUCT_PROFILE.md)。
+
+## 阶段说明
+
+```text
+discuss  梳理需求、产品版本、目标对象、边界和开放问题
+spec     明确验收标准、数据对象、异常、性能和风险
+plan     检查当前项目结构，记录真实目标路径、待改文件、查证项和验证命令
+execute  只实现 PLAN.md 中批准的内容
+verify   运行检查、构建或领域验证并记录证据
+ship     汇总变更、验证证据、风险和后续事项
+```
+
+推进阶段：
+
+```text
+/kd-advance
+/kd-advance spec
+/kd-advance plan
+/kd-advance execute
+/kd-advance verify
+/kd-advance ship
+```
+
+门禁不通过时，不要绕过。先按 `/kd-gate` 给出的原因补齐产品、文档、计划、证据或风险说明。
+
+## 阶段文档
+
+每个 run 会落地到：
+
+```text
+.pi/kd/runs/<run-id>/
+```
+
+主要文件：
+
+```text
+RUN.json
+CONTEXT.md
+SPEC.md
+PLAN.md
+EXECUTION.md
+VERIFY.md
+SHIP.md
+evidence/
+evidence/index.json
+```
+
+创建缺失阶段文档：
+
+```text
+/kd-artifact plan
+```
+
+`/kd-artifact` 默认不会覆盖已有阶段文档。确认要整体替换时必须显式使用：
+
+```text
+/kd-artifact plan <完整内容> --replace
+```
+
+## 待确认问题
+
+需要确认产品、目标单据、插件位置、高风险 SQL 或方案选择时，KCode 会记录待确认问题。未回答的阻断问题会阻止阶段推进。
+
+手动回答：
+
+```text
+/kd-answer Q-001 采购订单
+```
+
+原则：
+
+- 一次只问一个当前最阻塞的问题。
+- 不要把 FormId、字段、触发时机、弹窗内容打包成问题清单。
+- 得到答案后再继续问下一个必要问题。
+
+## 多个需求
+
+查看历史 run：
+
+```text
+/kd-runs
+```
+
+切换 run：
+
+```text
+/kd-switch <run-id>
+```
+
+完成当前 run：
+
+```text
+/kd-finish
+```
+
+同一目标下的一组需求可以放在同一个 run 中处理。无关目标建议创建新 run：
+
+```text
+/kd-start --product cangqiong E:\project\docs\本轮采购订单改造.docx
+```
+
+## 写代码规则
+
+KCode 会阻止过早写入 Java/XML/SQL/C# 等产品代码：
+
+- 未进入 `execute` 阶段不能写产品代码。
+- `execute` 只能写 `PLAN.md` 中批准的真实源码文件。
+- 临时发现要改新文件，先回到 `plan` 更新计划。
+- 不允许凭空写 demo、sample、scaffold。
+- 必须先理解当前业务项目已有目录、模块、包名、基类和本地封装。
+
+证据和门禁细节见 [证据和门禁](EVIDENCE_AND_GATES.md)。

package/docs/KCODE_DISTRIBUTION.md

@@ -2,7 +2,7 @@
 
 ## 目标
 
-KCode 不 fork Pi，也不替换 Pi 生态。KCode 提供一个企业入口，自动携带 Pi CLI，并把 KCodeV2 和经过审查的 Pi packages 以项目级配置方式组合起来。
+KCode 不 fork Pi，也不替换 Pi 生态。KCode 提供一个面向金蝶开发的入口，自动携带 Pi CLI，并把 KCode package 和经过审查的 Pi packages 以项目级配置方式组合起来。
 
 核心目标：
 
@@ -15,8 +15,8 @@ KCode 不 fork Pi，也不替换 Pi 生态。KCode 提供一个企业入口，
 ## 推荐结构
 
 ```text
-kcode-pi     当前仓库，作为 Pi package 提供金蝶工具、skills、prompts、themes。
-kcode cli    启动器，负责项目初始化、环境检查和启动随包 Pi CLI。
+kcode-pi     npm 包，作为 Pi package 提供金蝶工具、skills、prompts、themes。
+kcode        全局命令，负责项目初始化、环境检查和启动随包 Pi CLI。
 ```
 
 `kcode` 启动器只管理当前项目的 `.pi/settings.json`，不写 `~/.pi` 或其他用户全局目录。启动时优先调用随包 `@earendil-works/pi-coding-agent` 的 `dist/cli.js`，仅在随包 CLI 缺失时回退全局 `pi`。
@@ -29,12 +29,12 @@ kcode cli    启动器，负责项目初始化、环境检查和启动随包 Pi
 .pi/settings.json
 ```
 
-默认只写入当前 KCodeV2 package：
+默认只写入当前安装的 KCode package 路径：
 
 ```json
 {
   "packages": [
-    "E:\\projects\\kingdee\\KCodeV2"
+    "<当前 kcode-pi 安装路径>"
   ]
 }
 ```
@@ -44,7 +44,7 @@ kcode cli    启动器，负责项目初始化、环境检查和启动随包 Pi
 ```json
 {
   "packages": [
-    "E:\\projects\\kingdee\\KCodeV2",
+    "<当前 kcode-pi 安装路径>",
     "npm:pi-subagents@1.2.3"
   ]
 }
@@ -57,7 +57,7 @@ kcode cli    启动器，负责项目初始化、环境检查和启动随包 Pi
 允许接入前必须检查：
 
 - package 来源和维护状态。
-- license 是否允许企业内部分发。
+- license 是否允许随包分发和商业使用。
 - 是否注册 extensions、hooks、commands、tools。
 - 是否写全局配置或访问敏感路径。
 - 是否与 KCode harness、权限策略、上下文策略冲突。
@@ -83,7 +83,7 @@ kcode start     初始化后启动 KCode 工作环境
 - 不改用户全局 Pi 配置。
 - 不覆盖用户已安装 package。
 - 不自动安装未在 allowlist 中的 package。
-- 不把第三方 package 静默 bundle 进 KCodeV2。
+- 不把第三方 package 静默 bundle 进 KCode。
 - 所有新增 package 固定版本，变更必须记录。
 
 ## 当前限制

package/docs/PRODUCT_PROFILE.md

@@ -0,0 +1,108 @@
+# 产品画像确认
+
+产品画像决定 KCode 使用哪套产品知识、SDK/元数据来源、构建策略、目录约束和门禁规则。标题栏里如果出现 `产品：未确认`，必须先确认产品。
+
+## 支持的产品
+
+```text
+cangqiong   金蝶苍穹 / Cosmic Java
+xinghan     金蝶星瀚 / 基于苍穹/Cosmic
+flagship    星空旗舰版 / 基于苍穹/Cosmic
+enterprise  金蝶企业版 / C#
+```
+
+`Cosmic` 在 KCode 中就是苍穹平台语境，不作为独立产品画像。用户输入 `cosmic` 或 `云苍穹` 时，KCode 会按 `cangqiong` 归一处理。星瀚和星空旗舰版都基于苍穹/Cosmic 平台，但具体接口、目录和元数据可能存在产品差异，最终以当前产品、项目 SDK、元数据和构建证据为准。
+
+企业版默认按 C# 处理。只有明确提出 `Python插件`、`IronPython`，或带企业版/BOS 语境的 `Python脚本` 时，KCode 才切换到企业版 Python/IronPython 模式。
+
+## 创建 run 时确认产品
+
+推荐：
+
+```text
+/kd-start --product cangqiong --version V6.0 实现采购订单保存校验
+```
+
+也可以省略版本：
+
+```text
+/kd-start --product flagship 实现采购订单插件
+```
+
+## 已有 run 补产品
+
+如果 run 已经创建，但标题栏显示：
+
+```text
+产品：未确认
+```
+
+执行：
+
+```text
+/kd-product cangqiong --version V6.0
+/kd-gate
+/kd-status
+```
+
+如果不确定具体产品，但明确属于金蝶苍穹相关技术栈，优先确认业务实际使用的是苍穹、星瀚还是星空旗舰版，不要把 `cosmic` 当成产品名。
+
+## 如何选择
+
+选择 `cangqiong`：
+
+- 明确是金蝶苍穹。
+- Java 插件、Cosmic 表单/单据/元数据。
+
+选择 `xinghan`：
+
+- 明确是金蝶星瀚。
+- 基于苍穹/Cosmic 平台，优先按平台 Java 插件处理。
+- 接口或元数据存在星瀚差异时，以星瀚产品和当前项目证据为准。
+
+选择 `flagship`：
+
+- 明确是星空旗舰版。
+- 基于苍穹/Cosmic 平台，Java 插件规则适用。
+- 接口或目录存在旗舰版差异时，以旗舰版产品和当前项目证据为准。
+- 如果项目存在 `code/` 目录，生产代码应跟随 `code/` 下真实结构。
+
+选择 `enterprise`：
+
+- 明确是金蝶企业版 / BOS C#。
+- Java/Cosmic API 不适用。
+
+## 常见问题
+
+### 为什么不能保持 unknown？
+
+因为 unknown 会导致：
+
+- 无法选择对应产品的知识范围、SDK/元数据查证来源和门禁规则。
+- 无法确定构建策略、目录约束和证据要求，例如苍穹/星瀚/旗舰版的 Java 插件、企业版 C# 插件、企业版 Python/IronPython 脚本或 KSQL/SQL 数据脚本各自的验证方式。
+- 构建命令无法可靠选择。
+- SDK 签名和证据门禁会失去产品约束。
+
+KCode 会阻止 unknown run 离开 `discuss`。
+
+### Header 和 `/kd-status` 不一致怎么办？
+
+先刷新门禁：
+
+```text
+/kd-gate
+/kd-status
+```
+
+如果刚升级过 KCode，重新启动：
+
+```powershell
+kcode start
+```
+
+仍异常时运行：
+
+```powershell
+kcode doctor --deep
+kcode repair
+```

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,135 @@
+# 故障排查
+
+## 找不到模型
+
+现象：
+
+```text
+Warning: No models available.
+```
+
+处理：
+
+```text
+/login
+/model
+```
+
+或先设置供应商 API Key：
+
+```powershell
+$env:OPENAI_API_KEY="sk-..."
+kcode start
+```
+
+## 产品一直是未确认
+
+查看状态：
+
+```text
+/kd-status
+```
+
+确认产品：
+
+```text
+/kd-product cangqiong --version V6.0
+/kd-gate
+```
+
+如果不知道选哪个，看 [产品画像确认](PRODUCT_PROFILE.md)。
+
+## ship 阶段门禁阻塞
+
+常见原因：
+
+- 产品画像未确认。
+- 风险等级或风险原因未知。
+- 缺少 `SHIP.md` 必需章节。
+- 缺少 evidence 文件。
+- evidence 文件未登记到 `evidence/index.json`。
+- KSQL/SQL 交付缺少元数据或 lint 证据。
+
+常用命令：
+
+```text
+/kd-status
+/kd-gate
+/kd-risk low 已完成验证，无残余交付风险
+```
+
+## 仍然加载旧版本 KCode
+
+检查当前版本：
+
+```powershell
+kcode version
+```
+
+检查项目配置：
+
+```powershell
+type .pi\settings.json
+```
+
+如果 `packages` 中有多条 `kcode-pi` 路径：
+
+```powershell
+kcode repair
+```
+
+如果使用 nvm，Windows 上每个 Node 版本都有独立全局 npm 安装目录。切换 Node 后重新安装并初始化：
+
+```powershell
+npm install -g kcode-pi@latest
+kcode init
+```
+
+## npm install 没有更新
+
+先确认 registry 上的版本：
+
+```powershell
+npm view kcode-pi version
+npm view kcode-pi versions --json
+```
+
+必要时重装：
+
+```powershell
+npm uninstall -g kcode-pi
+npm install -g kcode-pi@latest
+kcode version
+```
+
+如果提示 `EEXIST: file already exists ... kcode.cmd`，确认旧 shim：
+
+```powershell
+npm root -g
+where kcode
+```
+
+删除旧 `kcode.cmd`、`kcode.ps1` 后重装。
+
+## 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，但路径被写成了 WSL/MSYS 风格。
+
+正确做法：
+
+- 优先使用项目相对路径。
+- 必须用绝对路径时，使用 `D:\projects\xxx\...`。
+- 不要使用 `/mnt/d/...` 或 `/d/...`。
+
+刷新项目上下文：
+
+```powershell
+kcode context --refresh
+```