# KCode

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

KCode 默认面向中文用户。Pi 会话提供统一入口 `/kd`；产品标识保持英文，例如 `cangqiong`、`enterprise`、`flagship`。

## 文档导航

首次使用按顺序阅读：

1. [用户指南](docs/USER_GUIDE.md)：安装、初始化、启动、模型配置、升级。
2. [Harness 工作流](docs/HARNESS_WORKFLOW.md)：如何按 quick、normal 模式推进需求。
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. [数据库 MCP](docs/DATABASE_MCP.md)：通过成熟 MCP server 查询 PostgreSQL、SQL Server 和 Oracle 元数据。
7. [更新日志](docs/CHANGELOG.md)：查看版本变化、发布验证和近期改进。
8. [故障排查](docs/TROUBLESHOOTING.md)：模型、旧版本、Windows 路径、终端显示等常见问题。

维护者文档：

- [开发与发布说明](docs/DEVELOPMENT.md)
- [发行版方案](docs/KCODE_DISTRIBUTION.md)
- [更新日志](docs/CHANGELOG.md)

## 快速开始

环境要求：

- Node.js `>=22.19.0`
- npm
- Windows 环境使用 Windows Terminal

安装：

```powershell
npm install -g kcode-pi
```

进入你的实际业务项目根目录后执行：

```powershell
kcode
```

首次启动出现无模型信息时，在 KCode/Pi 中执行：

```text
/login
/model
```

## 第一个需求

直接输入需求即可开始：

```text
/kd 实现采购订单保存校验
/kd cangqiong 实现采购订单保存校验
/kd normal enterprise 第三方 WMS 对接
```

支持直接提供需求文档：

```text
/kd cangqiong E:\project\docs\需求说明.md
```

产品未确认时：

```text
/kd product cangqiong --version V6.0
/kd check
/kd status
```

支持的产品画像：

```text
cangqiong   金蝶苍穹 / Cosmic Java
xinghan     金蝶星瀚 / 基于苍穹/Cosmic
flagship    星空旗舰版 / 基于苍穹/Cosmic
enterprise  金蝶企业版 / C#
```

normal 模式进入 `ship` 前必须确认风险：

```text
/kd risk low 已完成本地构建和元数据检查，无残余交付风险
/kd check
```

完整解释见 [产品画像确认](docs/PRODUCT_PROFILE.md) 和 [证据和门禁](docs/EVIDENCE_AND_GATES.md)。

Harness 模式：

```text
quick     discuss -> plan -> execute -> verify
normal    discuss -> spec -> plan -> execute -> verify -> ship
```

`quick` 保留工作区安全、PLAN 批准文件、编码规范检查和验证记录，优先快速实现并进入 UAT 修复闭环；`normal` 启用完整业务事实、SDK 签名、元数据、TDD 和交付证据硬门禁。
第三方对接、SQL/KSQL、数据修复、外部验证、生产发布和高风险改动会强制使用 `normal`。

## Pi 内 KCode 命令

进入 `kcode start` 后常用：

```text
/kd
/kd <需求或需求文档>
/kd status
/kd answer Q-001 <答案>
/kd check
/kd done
```

`/kd` 继续当前需求；`/kd <文本>` 始终创建新需求。
`/kd check` 会刷新检查；检查通过时直接继续当前需求。
已有需求只需补产品或流程强度时，可以直接输入 `/kd cangqiong`、`/kd enterprise`、`/kd normal`。
当前只有一个待回答问题时，`/kd <答案>` 会记录为该问题答案。

配置、审计和交付相关操作统一走 `/kd` 子命令：

```text
/kd product <产品> [--version 版本]
/kd mode <quick|normal>
/kd risk <low|medium|high> <原因>
/kd list
/kd use <需求id>
/kd doc [阶段] [内容] [--replace]
/kd verify <exitCode> <command>
/kd log
/kd handoff
```

完整说明见 [命令参考](docs/COMMAND_REFERENCE.md)。

## 内置金蝶工具

KCode 会向 Pi 注册：

```text
kd_plan_status      查看当前需求、阶段、产物和检查状态
kd_ask_user         阻塞式询问用户并登记结构化问题
kd_answer_user      记录问题答案、修订事实、查看问题和标签
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            分析金蝶日志和堆栈
kd_subagent         将调研、文档、代码、验证或交叉审查委派给隔离子 agent
```

工具细节和使用顺序见 [Harness 工作流](docs/HARNESS_WORKFLOW.md)。
完整参数见 [命令参考](docs/COMMAND_REFERENCE.md)。

## 运行状态文件

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
.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/
.pi/kd/runs/<run-id>/evidence/index.json
```

`quick` 不生成 `SPEC.md` 和 `SHIP.md`；`normal` 使用完整文件集合。

KCode 无需单独安装全局 `pi` 命令，也不会修改用户全局 Pi 配置。

## 数据库 MCP

需要让 LLM 查询 PostgreSQL、SQL Server 或 Oracle 元数据时，先在业务项目根目录执行：

```powershell
kcode db
```

该命令只写入 `.mcp.json` 中的 MCP server 配置，凭证必须通过环境变量提供。进入 `kcode start` 后使用 `mcp` 代理工具搜索和调用数据库 MCP。详细规则见 [数据库 MCP](docs/DATABASE_MCP.md)。

## 升级

```powershell
npm install -g kcode-pi@latest
kcode -v
```

升级后在业务项目根目录重新执行 `kcode` 即可自动刷新项目配置。

更多升级和异常处理见 [故障排查](docs/TROUBLESHOOTING.md)。