# 命令参考

本文集中说明 KCode 的终端命令、Pi 内命令和内置工具参数。首次使用阅读 [用户指南](USER_GUIDE.md)，工作流顺序见 [Harness 工作流](HARNESS_WORKFLOW.md)。

## 终端命令

终端命令在业务项目根目录执行。

### kcode

启动 KCode/Pi 工作环境。自动完成项目初始化、环境检查，然后启动 Pi：

```powershell
kcode
```

不需要任何子命令。进入项目目录后直接执行即可。

### kcode -v

显示 KCode、Pi CLI 和 Node 版本：

```powershell
kcode -v
kcode --version
```

## Pi 内命令

以下命令在 `kcode start` 进入 Pi 后输入。

### /kd

统一入口，覆盖需求创建、推进、状态查看、答案记录和交付检查：

```text
/kd
/kd <需求或需求文档>
/kd next [补充说明]
/kd status
/kd answer Q-001 <答案>
/kd check
/kd done
```

使用显式产品或模式：

```text
/kd cangqiong 实现采购订单保存校验
/kd quick 更新 README 文档说明
/kd normal enterprise 第三方 WMS 对接
```

使用需求文档：

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

也可以使用显式参数，适合脚本或需要指定版本时：

```text
/kd --product cangqiong --version V6.0 --mode normal 第三方 WMS 对接
```

支持产品：

```text
cangqiong
xinghan
flagship
enterprise
```

模式：

```text
quick     discuss -> plan -> execute -> verify，用于文档、只读分析和低风险小改
normal    discuss -> spec -> plan -> execute -> verify -> ship，用于常规产品实现、第三方对接、SQL/KSQL、数据修复、外部验证、生产发布和高风险改动
```

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

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

### 常用快捷命令

这些是日常执行入口：

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

### /kd 子命令

配置、审计和交付相关操作统一放在 `/kd` 后面，保持命令面稳定：

```text
/kd product <flagship|xinghan|cangqiong|enterprise> [--version 版本]
/kd mode <quick|normal>
/kd risk <low|medium|high> <原因>
/kd phase [discuss|spec|plan|execute|verify|ship]
/kd doc [阶段] [内容] [--replace]
/kd verify <exitCode> <command>
/kd goal <目标命令>
/kd list
/kd use <需求id>
/kd log [数量]
/kd handoff [说明]
```

`/kd check` 会重新检查当前阶段能不能继续；检查通过时直接继续当前需求，阻塞时按输出补齐产品、阶段文档、问题答案、证据或风险说明。

`/kd status` 默认只输出当前阶段、检查结果和下一步；需要需求 ID、模式、运行目录等诊断信息时使用 `/kd status --detail`。

`/kd handoff` 用于交给新会话、子 agent 复盘或人工检查当前唯一下一动作。

`/kd log` 用于排查用户已回答但 LLM 重问、工具失败后注意力漂移、工作区外路径被反复尝试等问题。

### /kd-review

启动只读交叉自查子 agent：

```text
/kd-review [审查重点]
```

用于检查状态机漏洞、门禁绕过、证据缺口、工程指令分散和测试缺口。子 agent 不修改文件，主 agent 负责采纳结论和后续修复。

### /kd-delegate

把局部任务委派给隔离子 agent：

```text
/kd-delegate <research|doc|code|review|verify> <任务> [--dry-run]
```

角色：

```text
research  只读调研，输出压缩结论和证据位置
doc       写指定文档或阶段产物
code      只在 execute 阶段修改 PLAN.md 批准文件
review    只读交叉自查，输出 findings 和是否阻止发布
verify    只读分析验证命令和失败证据，实际验证由主 agent 执行并用 /kd goal 记录
```

`--dry-run` 只预览上下文包，不启动子进程。
复杂任务也可能由主 agent 自动调用 `kd_subagent` 委派；自动委派不会改变 Harness 阶段。

### /kd goal

设定验证目标命令，自动执行验证、修复、再验证循环直到通过或超限：

```text
/kd goal npm test
/kd goal kd_ksql_lint scripts/fix.sql
```

`/kd goal` 完全取代手动 `kd_verify_result` 流程。用户只需设定目标命令，系统自动：
- 运行验证命令并记录 evidence
- 验证失败时自动修复
- 修复后重新运行验证命令
- 修复达到上限后要求用户决策

目标命令必须返回标准退出码（0 = 通过，非 0 = 失败）。

## 内置工具

这些工具多数情况下由 KCode 自动使用；明确证据或排障时，支持按下面参数手动调用。

### kd_plan_status

查看当前需求、阶段、文档和检查结果：

```text
kd_plan_status
```

### kd_ask_user

阻塞式询问用户并登记结构化问题：

```text
kd_ask_user questions=[{"header":"目标 FormId","factLabel":"目标 FormId/单据或表单标识","question":"目标 FormId、单据或表单标识是什么？","contextSummary":"已读取相关文件，等待确认 FormId 后继续字段映射校验。","sourceRefs":["src/Plugin.cs:120"]}]
kd_ask_user questions=[{"header":"数据源上下文","factLabel":"目标 FormId/单据或表单标识","question":"目标 FormId、单据或表单标识是什么？","contextSummary":"已读取计划和字段映射，等待补齐数据源上下文。"},{"header":"字段实体","factLabel":"字段/实体/分录标识","question":"涉及哪些字段、实体或分录标识？","contextSummary":"已读取计划和字段映射，等待补齐数据源上下文。"}]
```

`questions` 可包含同一事实组内多个独立问题。已有 open blocking question 或已确认的同一 `factLabel` 时会拒绝重复提问。阻塞问题必须提供 `contextSummary`；读取过文件或证据时必须提供 `sourceRefs`。

问题参数：

```text
header             必填，极短标题
question           必填，完整问题
options            可选，[{label, description}]
custom             可选，是否允许自定义输入，默认 true
multiple           可选，多选问题；当前 UI 要求用户用逗号输入多项
factLabel          可选，该答案要补齐的门禁事实标签
proposedFactValue  可选，确认题候选事实值；用户回答 是/yes 时写入 factLabel
contextSummary     阻塞问题必填，提问前上下文摘要
sourceRefs         可选，上下文来源文件、证据或命令
```

`custom=true` 时工具会自动提供自定义输入路径，`options` 中不要添加“其他/自行输入”。门禁只消费当前结构化事实。没有 `factLabel` 的问答只作为上下文记录，不直接解除数据源、字段、接口等事实缺口。

### kd_answer_user

记录用户答案、修订事实或查看问题：

```text
kd_answer_user action=answer id=Q-001 answer=SAL_SaleOrder
kd_answer_user action=revise factLabel="目标 FormId/单据或表单标识" answer="SAL_SaleOrder" reason="用户更正先前答案"
kd_answer_user action=list
kd_answer_user action=labels
```

`factLabel` 必须使用 KCode 集中定义的实现契约、数据源上下文或第三方对接事实标签，允许使用别名并自动规范为正式标签。已有当前事实时禁止再次提问，必须用 `action=revise` 显式修订。`待确认`、`未知`、`按实际环境`、`TODO/TBD`、单独“是/否”和“可以/好的”等口头确认不会解除开放事实问题。带 `proposedFactValue` 的确认题只接受明确肯定或明确否定。

当前只有一个 open blocking 问题时，用户下一条普通短答会自动记录为该问题答案；命令、疑问句和明显的新任务不会自动记录。

存在同一事实组的多个 open blocking 问题时，可以用结构化文本一次回答：

```text
Q-001: SAL_SaleOrder
Q-002: FBillNo, FQty, FEntity
```

KCode 会先按问题编号写入答案和结构化 facts，再把刷新后的 run state 注入下一轮 prompt。

### kd_subagent

将局部任务委派给隔离 Pi 子进程：

```text
kd_subagent role=review task="审查当前 run 的门禁和证据缺口"
kd_subagent role=research task="查找采购订单保存插件相关代码" dryRun=true
kd_subagent tasks=[{"role":"research","task":"查找模型层"},{"role":"review","task":"审查状态机"}]
kd_subagent chain=[{"role":"research","task":"找相关代码"},{"role":"review","task":"基于上一输出审查风险"}]
```

参数：

```text
role            必填，research/doc/code/review/verify
task            必填，具体委派任务
tasks           可选，并行任务数组，只允许 research/review/verify，和 role/task/chain 三选一
chain           可选，链式任务数组，和 role/task/tasks 三选一
dryRun          可选，只预览上下文包
maxOutputChars  可选，限制返回给主 agent 的输出长度
```

主 Harness 仍负责阶段推进、证据和门禁；子 agent 返回结果后由主 agent 决策下一步。

### kd_search

搜索随包金蝶知识库：

```text
kd_search query=QueryServiceHelper product=cangqiong limit=5
```

参数：

```text
query     必填，关键词、API、类名、表名或生命周期术语
product   可选，flagship/xinghan/cangqiong/enterprise
limit     可选，默认 5，最大 10
```

### kd_table

查询随包表结构：

```text
kd_table table=T_PUR_POORDER product=flagship
```

参数：

```text
table     必填，表名
product   可选，flagship/xinghan/cangqiong/enterprise
```

随包表结构主要覆盖旗舰版和企业版；Cosmic 家族字段和数据库信息默认用 `kd_cosmic_metadata`。

### kd_check

检查金蝶 Java/C#/Python 插件代码：

```text
kd_check path=src/main/java/com/example/MyPlugin.java product=cangqiong
kd_check code="<源码片段>" language=java
```

参数：

```text
code      可选，与 path 二选一
path      可选，与 code 二选一
product   可选，用于推导语言和产品规则
language  可选，java/csharp/python
```

### kd_anchor_read

读取文本文件并输出 `line#hash|content` 锚点，用于精确编辑和防止陈旧上下文覆盖。写入或编辑 source-like 生产源码前必须先读取锚点：

```text
kd_anchor_read path=src/Integration/MesApiClient.cs
kd_anchor_read path=src/Integration/MesApiClient.cs maxChars=40000
```

参数：

```text
path      必填，文本文件路径
maxChars  可选，最大输出字符数，默认 20000
```

使用规则：

- 精确修改普通文本文件前优先使用 `kd_anchor_read`；修改 source-like 生产源码前必须使用。
- 锚点快照会写入 run state；后续 source-like `write`/`edit` 事务会校验锚点是否存在、文件是否在读取后变化。
- 锚点校验失败时必须重新读取目标文件，禁止凭旧上下文继续编辑。
- Source Anchors 只证明文件内容未变，不证明 FormId、字段、接口映射等业务事实。

### kd_cosmic_config

运行 Cosmic 家族官方能力配置预检：

```text
kd_cosmic_config product=cangqiong
kd_cosmic_config product=flagship config=ok-cosmic.json dryRun=true
```

参数：

```text
product  必填，cangqiong/xinghan/flagship
config   可选，ok-cosmic.json 路径
dryRun   可选，只展示命令
```

有 active run 时，成功结果会写入 `evidence/cosmic-config.txt`。

### kd_cosmic_metadata

查询 Cosmic 表单、单据、字段、枚举、操作和 SQL 表信息：

```text
kd_cosmic_metadata product=cangqiong form=sal_order
kd_cosmic_metadata product=cangqiong form=sal_order fuzzy="数量 金额" showDetail=true
kd_cosmic_metadata product=flagship form=采购订单 sql=true op=true
```

参数：

```text
product     必填，cangqiong/xinghan/flagship
form        必填，Form ID、单据 ID 或中文单据名；多个目标可用逗号分隔
config      可选，ok-cosmic.json 路径
fuzzy       可选，字段关键词
typeFilter  可选，字段类型正则，例如 combo|check
sql         可选，包含数据库表和字段信息
op          可选，显示操作
showDetail  可选，显示详细元数据
dryRun      可选，只展示命令
```

有 active run 时，成功结果会写入 `evidence/cosmic-metadata.json`。

### kd_metadata_parse

解析企业版 SQL Server/Oracle 元数据 XML，或苍穹/星瀚/旗舰版 PostgreSQL `t_meta_entitydesign.fdata` MCP 查询 JSON，并写入数据源证据：

```text
kd_metadata_parse path=meta/poorder.xml form=PUR_PurchaseOrder name=采购订单
kd_metadata_parse path=meta/poorder-mcp.json
kd_metadata_parse path=meta/poorder.xml dryRun=true
```

参数：

```text
path          必填，FKERNELXML/fdata XML 文件或 MCP 查询结果 JSON 文件
fid           可选，T_META_OBJECTTYPE.FID 或 t_meta_entitydesign.fid
form          可选，FormId、单据标识或表单标识
name          可选，表单/单据名称
subsystem     可选，子系统名称
baseObjectId  可选，FBASEOBJECTID
dryRun        可选，只输出解析结果，不写 evidence
```

成功时输出实体/分录、字段、表名和数据库字段名；有 active run 且非 `dryRun` 时写入 `evidence/data-source.md`。企业版/BOS/苍穹/星瀚/旗舰版本地元数据涉及 FormId、字段、实体或 SQL/KSQL 时，必须先用该工具或等价 evidence 完成解析，不能只看原始 FKERNELXML、fdata 或示例 SQL。

使用约束：插件层、模型层和 DynamicObject 读写使用字段标识/实体标识；SQL、KSQL、报表、存储过程和直接查库使用数据库表名/数据库字段名。需求没有明确访问层时，Agent 必须先确认数据访问方式。

### kd_cosmic_api

查询随包 Cosmic API 知识线索：

```text
kd_cosmic_api product=cangqiong mode=search query=QueryServiceHelper
kd_cosmic_api product=cangqiong mode=search-method query=loadSingle
kd_cosmic_api product=cangqiong mode=detail query=kd.bos.servicehelper.QueryServiceHelper method=loadSingle compact=true
```

参数：

```text
product  必填，cangqiong/xinghan/flagship
mode     必填，search/search-method/detail
query    必填，类名、方法名或完整限定类名
config   可选，ok-cosmic.json 路径
method   可选，detail 模式下过滤方法
compact  可选，紧凑详情输出
dryRun   可选，只展示命令
```

`kd_cosmic_api` 只能作为线索；最终 SDK 签名事实以 `kd_sdk_signature`、项目构建输出或官方元数据为准。

### kd_sdk_signature

从当前业务项目真实 SDK jar/dll 检查类型和方法签名：

```text
kd_sdk_signature product=cangqiong query=QueryServiceHelper method=loadSingle
kd_sdk_signature product=enterprise query=DynamicObject method=GetDynamicObject
kd_sdk_signature language=java className=kd.bos.servicehelper.QueryServiceHelper method=loadSingle
```

参数：

```text
product    可选，用于推导 Java/C#
language   可选，java/csharp
query      可选，类或类型关键词
className  可选，完整限定类型名
method     可选，在匹配类型内过滤方法或属性
path       可选，SDK lib/bin 目录或依赖根路径
limit      可选，最大检查数量
```

有 active run 且查询成功时，会写入 `evidence/sdk-signature.md`。

### kd_ksql_lint

检查 KSQL/SQL 文件：

```text
kd_ksql_lint product=cangqiong path=scripts/fix.sql
kd_ksql_lint product=flagship path=scripts/fix.sql dryRun=true
```

参数：

```text
product  必填，cangqiong/xinghan/flagship
path     必填，SQL/KSQL 文件路径
dryRun   可选，只展示命令
```

有 active run 时，成功结果会写入 `evidence/ksql-lint.txt`。

### kd_build

按产品画像运行或预览构建命令：

```text
kd_build product=cangqiong
kd_build product=cangqiong target=:module:build
kd_build product=enterprise target=Project.sln
kd_build product=flagship dryRun=true
```

参数：

```text
product  必填，cangqiong/xinghan/flagship/enterprise
target   可选，Java Gradle task 或 C# .sln/.csproj 路径
dryRun   可选，只展示命令
```

### kd_debug

分析金蝶构建、运行日志或堆栈：

```text
kd_debug path=logs/error.log product=cangqiong
kd_debug text="<日志或堆栈>" product=enterprise
```

参数：

```text
text     可选，与 path 二选一
path     可选，与 text 二选一
product  可选，产品上下文
```

## 常用组合

新需求：

```text
/kd cangqiong 实现采购订单保存校验
/kd status
/kd check
```

已有需求补产品：

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

进入 execute 前补签名证据：

```text
kd_sdk_signature product=cangqiong query=QueryServiceHelper method=loadSingle
/kd check
```

normal 模式 ship 前补风险：

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