kcode-pi 0.1.31 → 0.1.35

package/README.md

@@ -6,12 +6,12 @@ KCode 默认面向中文用户。命令名和产品标识保持英文，例如 `
 
 ## 文档导航
 
-如果你是第一次使用，按顺序看：
+首次使用按顺序阅读：
 
 1. [用户指南](docs/USER_GUIDE.md)：安装、初始化、启动、模型配置、升级。
 2. [Harness 工作流](docs/HARNESS_WORKFLOW.md)：如何从需求进入 discuss -> spec -> plan -> execute -> verify -> ship。
 3. [产品画像确认](docs/PRODUCT_PROFILE.md)：如何用 `/kd-product` 确认苍穹、星瀚、星空旗舰版或企业版。
-4. [证据和门禁](docs/EVIDENCE_AND_GATES.md)：为什么需要 evidence、SDK 签名、TDD 红绿证据、风险确认。
+4. [证据和门禁](docs/EVIDENCE_AND_GATES.md)：evidence、SDK 签名、TDD 红绿证据和风险确认规则。
 5. [命令参考](docs/COMMAND_REFERENCE.md)：完整 `kcode` 子命令、Pi 内 `/kd-*` 命令和内置工具参数。
 6. [更新日志](docs/CHANGELOG.md)：查看版本变化、发布验证和近期改进。
 7. [故障排查](docs/TROUBLESHOOTING.md)：模型、旧版本、Windows 路径、终端显示等常见问题。
@@ -28,7 +28,7 @@ KCode 默认面向中文用户。命令名和产品标识保持英文，例如 `
 
 - Node.js `>=22.19.0`
 - npm
-- Windows 推荐使用 Windows Terminal
+- Windows 环境使用 Windows Terminal
 
 安装：
 
@@ -44,7 +44,7 @@ kcode doctor --deep
 kcode start
 ```
 
-如果首次启动提示没有模型，在 KCode/Pi 中执行：
+首次启动出现无模型信息时，在 KCode/Pi 中执行：
 
 ```text
 /login
@@ -53,19 +53,19 @@ kcode start
 
 ## 第一个需求
 
-推荐显式指定产品：
+使用显式产品参数：
 
 ```text
 /kd-start --product cangqiong 实现采购订单保存校验
 ```
 
-也可以直接提供需求文档：
+支持直接提供需求文档：
 
 ```text
 /kd-start --product cangqiong E:\project\docs\需求说明.md
 ```
 
-如果已经创建了 run，但标题栏显示产品未确认：
+已创建 run 且标题栏显示产品未确认时：
 
 ```text
 /kd-product cangqiong --version V6.0
@@ -82,7 +82,7 @@ flagship    星空旗舰版 / 基于苍穹/Cosmic
 enterprise  金蝶企业版 / C#
 ```
 
-进入 `ship` 前还需要确认风险：
+进入 `ship` 前必须确认风险：
 
 ```text
 /kd-risk low 已完成本地构建和元数据检查，无残余交付风险
@@ -156,7 +156,7 @@ KCode 只维护当前业务项目内的配置和工作流状态：
 .pi/kd/runs/<run-id>/evidence/index.json
 ```
 
-KCode 不要求你单独安装全局 `pi` 命令，也不会修改用户全局 Pi 配置。
+KCode 无需单独安装全局 `pi` 命令，也不会修改用户全局 Pi 配置。
 
 ## 升级
 
@@ -165,7 +165,7 @@ npm install -g kcode-pi@latest
 kcode version
 ```
 
-升级后建议在业务项目根目录重新执行：
+升级后在业务项目根目录重新执行：
 
 ```powershell
 kcode init

package/dist/cli/kcode.js

@@ -71,8 +71,8 @@ export function doctor(cwd, args = []) {
     lines.push(`Pi CLI：${formatPiCliStatus(piCli, pi)}`);
     lines.push(`KCode version：${packageName}@${packageVersion}`);
     lines.push(`KCode package：${packageRoot}`);
-    lines.push(`项目配置：${existsSync(settingsPath) ? settingsPath : "未创建，请先运行 kcode init"}`);
-    lines.push(`项目上下文：${existsSync(projectContextPath) ? projectContextPath : "未创建，请运行 kcode context"}`);
+    lines.push(`项目配置：${existsSync(settingsPath) ? settingsPath : "未创建，运行 kcode init"}`);
+    lines.push(`项目上下文：${existsSync(projectContextPath) ? projectContextPath : "未创建，运行 kcode context"}`);
     if (existsSync(settingsPath)) {
         const settingsResult = readSettingsSafe(settingsPath);
         if (!settingsResult.ok) {
@@ -166,7 +166,7 @@ export function start(cwd, piArgs) {
     if (!piCli) {
         return {
             exitCode: 1,
-            output: `${init.output}\n未找到随包 Pi CLI 或全局 pi 命令。请重新安装 kcode-pi 后再运行 kcode start。`,
+            output: `${init.output}\n未找到随包 Pi CLI 或全局 pi 命令。重新安装 kcode-pi 后再运行 kcode start。`,
         };
     }
     const pi = spawnSync(piCli.command, piCli.args, { cwd, stdio: "inherit", shell: false });

package/dist/context/project-context.js

@@ -57,9 +57,9 @@ export function generateProjectContext(cwd) {
         "",
         "- 本文件是 KCode 的项目记忆，计划或编辑代码前必须读取。",
         "- 业务需求不得生成 demo/sample/scaffold 代码。",
-        "- 不要假设模块结构。必须基于下方真实路径，并在编辑前确认目标文件。",
-        "- 调用文件工具时优先使用项目相对路径。在 Windows 中，不要把路径改写为 /mnt/<drive>/... 或 /<drive>/...；只有确需绝对路径时才使用 Windows 路径。",
-        "- 如果本文件过期，计划前先运行 `kcode context --refresh` 重新生成。",
+        "- 禁止假设模块结构。必须基于下方真实路径，并在编辑前确认目标文件。",
+        "- 调用文件工具时默认使用项目相对路径。在 Windows 中禁止把路径改写为 /mnt/<drive>/... 或 /<drive>/...；绝对路径只允许使用 Windows 路径。",
+        "- 本文件过期时，计划前运行 `kcode context --refresh` 重新生成。",
         "- 只有 Harness 进入 `execute` 且 PLAN.md 写明真实目标路径后，才能写产品代码。",
         "",
         "## 项目结构摘要",

package/docs/CHANGELOG.md

@@ -6,6 +6,32 @@
 
 - 暂无。
 
+## 0.1.35 - 2026-06-07
+
+### 新增
+
+- 新增集中式工程指令策略，统一管理实现契约、数据源上下文、第三方对接上下文、提示风格和阶段约束。
+- 新增数据源与实现就绪门禁，产品代码写入前必须具备触发入口、源对象、目标对象、字段映射、业务规则、失败处理和验收样例。
+- 新增第三方对接上下文门禁，要求接口文档、对接方向、认证配置、字段映射、并发幂等、重试限流、错误补偿、日志脱敏和验收样例齐全后再编码。
+
+### 改进
+
+- 将 Harness、extensions、CLI、工具说明、静态检查结果和文档中的用户/LLM 可见文本改为正式工程指令，减少口语化表达。
+- 强化企业版 C#、企业版 Python、苍穹、星瀚和星空旗舰版的数据源证据要求。
+- 企业版 Python 插件明确为用户侧 BOS 注册和功能测试证据，LLM 不能替代外部系统操作，只能要求用户提供可核验证据并记录来源。
+- 子 agent、自动修复循环、项目上下文、SDK 签名和 KSQL/SQL lint 的输出改为“必须/禁止/执行/记录”式约束。
+
+### 验证
+
+- `npm run check`
+- `npm run smoke:harness`
+- `npm run smoke:package`
+- `npm run smoke:checker`
+- `npm run smoke:build-debug`
+- `npm run smoke:official`
+- `npm run build:cli`
+- `git diff --check`
+
 ## 0.1.30 - 2026-06-07
 
 ### 新增
@@ -99,7 +125,7 @@
 ### 改进
 
 - 收敛运行时 prompt，只保留状态、最近阶段资料、项目上下文摘要、当前阶段任务和核心约束。
-- 精简 `kd-plan`、`kd-execute`、`kd-verify` 命令入口提示，减少和 skills、门禁规则的重复。
+- 精简 `kd-plan`、`kd-execute`、`kd-verify` 命令入口指令，减少和 skills、门禁规则的重复。
 - 移除不存在的 IDE 相关验证表述，保留 Gradle/dotnet 的真实构建验证策略。
 
 ### 验证
@@ -116,7 +142,7 @@
 
 - 将包版本更新到 `0.1.23`，并同步 `package-lock.json` 顶层版本信息。
 - 改进文档示例、用户文档和 README 使用说明。
-- 优化 Harness 门禁、证据跟踪、恢复流程和风险确认提示。
+- 优化 Harness 门禁、证据跟踪、恢复流程和风险确认指令。
 - 使用 Gradle 和 dotnet 作为对应产品画像的构建验证入口。
 - 本地化 KCode prompts，并要求关键 SDK 结论提供签名证据。
 

package/docs/COMMAND_REFERENCE.md

@@ -1,6 +1,6 @@
 # 命令参考
 
-本文集中说明 KCode 的终端命令、Pi 内命令和内置工具参数。首次使用请先看 [用户指南](USER_GUIDE.md)，工作流顺序请看 [Harness 工作流](HARNESS_WORKFLOW.md)。
+本文集中说明 KCode 的终端命令、Pi 内命令和内置工具参数。首次使用阅读 [用户指南](USER_GUIDE.md)，工作流顺序见 [Harness 工作流](HARNESS_WORKFLOW.md)。
 
 ## 终端命令
 
@@ -77,7 +77,7 @@ kcode doctor --deep
 kcode repair
 ```
 
-升级后或 `doctor --deep` 提示旧路径时使用。
+升级后或 `doctor --deep` 报告旧路径时使用。
 
 ### kcode start
 
@@ -87,7 +87,7 @@ kcode repair
 kcode start
 ```
 
-`start` 会先自动执行项目级初始化，再启动随包 Pi CLI。后续参数会原样传给 Pi CLI：
+`start` 会自动执行项目级初始化，再启动随包 Pi CLI。后续参数会原样传给 Pi CLI：
 
 ```powershell
 kcode start --provider openai --model gpt-4o
@@ -99,13 +99,13 @@ kcode start --provider openai --model gpt-4o
 
 ### /kd-start
 
-创建一个新的 Kingdee Harness run。输入可以是一条需求，也可以是需求文档来源：
+创建一个新的 Kingdee Harness run。输入允许是一条需求，或需求文档来源：
 
 ```text
 /kd-start [--product 产品] [--version 版本] <需求或需求组>
 ```
 
-推荐显式带产品：
+使用显式产品参数：
 
 ```text
 /kd-start --product cangqiong --version V6.0 实现采购订单保存校验
@@ -263,7 +263,7 @@ discuss -> spec -> plan -> execute -> verify -> ship
 /kd-review [审查重点]
 ```
 
-用于检查状态机漏洞、门禁绕过、证据缺口、提示词分散和测试缺口。子 agent 不修改文件，主 agent 负责采纳结论和后续修复。
+用于检查状态机漏洞、门禁绕过、证据缺口、工程指令分散和测试缺口。子 agent 不修改文件，主 agent 负责采纳结论和后续修复。
 
 ### /kd-delegate
 
@@ -288,7 +288,7 @@ verify    只读分析验证命令和失败证据，实际验证由主 agent 执
 
 ## 内置工具
 
-这些工具多数情况下会由 KCode 自动使用；当需要明确证据或排障时，也可以按下面参数手动调用。
+这些工具多数情况下由 KCode 自动使用；明确证据或排障时，支持按下面参数手动调用。
 
 ### kd_plan_status
 
@@ -367,7 +367,7 @@ product   可选，flagship/xinghan/cangqiong/enterprise
 edition   旧参数，等同 product
 ```
 
-随包表结构主要覆盖旗舰版和企业版；Cosmic 家族字段和数据库信息优先用 `kd_cosmic_metadata`。
+随包表结构主要覆盖旗舰版和企业版；Cosmic 家族字段和数据库信息默认用 `kd_cosmic_metadata`。
 
 ### kd_check
 
@@ -450,7 +450,7 @@ mode     必填，search/search-method/detail
 query    必填，类名、方法名或完整限定类名
 config   可选，ok-cosmic.json 路径
 method   可选，detail 模式下过滤方法
-compact  可选，请求紧凑详情输出
+compact  可选，紧凑详情输出
 dryRun   可选，只展示命令
 ```
 
@@ -532,7 +532,7 @@ kd_debug text="<日志或堆栈>" product=enterprise
 ```text
 text     可选，与 path 二选一
 path     可选，与 text 二选一
-product  可选，产品提示
+product  可选，产品上下文
 ```
 
 ## 常用组合

package/docs/DEVELOPMENT.md

@@ -1,6 +1,6 @@
 # KCode 开发与发布说明
 
-本文档面向 KCode 维护者。用户安装和使用说明请看根目录 `README.md`。
+本文档面向 KCode 维护者。用户安装和使用说明见根目录 `README.md`。
 
 ## 源码开发
 
@@ -117,7 +117,7 @@ npm run release:check
 npm publish
 ```
 
-如果使用 scoped 包并发布到公网 npm：
+使用 scoped 包并发布到公网 npm 时：
 
 ```powershell
 npm publish --access public
@@ -152,7 +152,7 @@ docs/KCODE_DISTRIBUTION.md
 - 是否写全局配置或访问敏感路径。
 - 是否与 KCode harness、权限策略、上下文策略冲突。
 
-通过审查后优先使用项目级推荐安装，写入 `.pi/settings.json`。只有离线交付或强依赖时，才考虑 `dependencies` + `bundledDependencies` 内置。
+通过审查后默认使用项目级安装，写入 `.pi/settings.json`。只有离线交付或强依赖时，才允许考虑 `dependencies` + `bundledDependencies` 内置。
 
 ## 当前维护事项
 

package/docs/EVIDENCE_AND_GATES.md

@@ -9,17 +9,17 @@ KCode Harness 的门禁用于避免跳阶段、猜 SDK、伪造验证结果或
 /kd-status
 ```
 
-门禁不通过时，先按原因补齐产品、文档、问题答案、计划、证据或风险说明。
+门禁不通过时，按原因补齐产品、文档、问题答案、计划、证据或风险说明。
 
 ## 产品确认
 
-当需求涉及具体金蝶产品实现、构建、元数据或 SDK 查证时，需要确认产品画像：
+当需求涉及具体金蝶产品实现、构建、元数据或 SDK 查证时，必须确认产品画像：
 
 ```text
 /kd-product cangqiong --version V6.0
 ```
 
-如果只是整理需求文档或处理产品无关的工程事项，可以先完成需求梳理，并在计划中写明不涉及产品实现。后续实际要改金蝶产品代码、构建、元数据或 SDK 时，再按范围确认产品。
+仅整理需求文档或处理产品无关工程事项时，完成需求梳理，并在计划中写明不涉及产品实现。后续实际修改金蝶产品代码、构建、元数据或 SDK 时，按范围确认产品。
 
 详见 [产品画像确认](PRODUCT_PROFILE.md)。
 
@@ -46,7 +46,7 @@ KCode Harness 的门禁用于避免跳阶段、猜 SDK、伪造验证结果或
 evidence/sdk-signature.md
 ```
 
-推荐工具：
+使用工具：
 
 ```text
 kd_sdk_signature product=cangqiong query=QueryServiceHelper method=loadSingle
@@ -54,7 +54,7 @@ kd_sdk_signature product=flagship query=SaveServiceHelper method=save
 kd_sdk_signature product=enterprise query=DynamicObject method=GetDynamicObject
 ```
 
-只有这些来源可以作为签名事实：
+只有以下来源允许作为签名事实：
 
 - `kd_sdk_signature` 从当前项目真实 jar/dll 读取的结果。
 - 当前项目构建输出。
@@ -96,7 +96,7 @@ Exit: 0
 - “未执行”
 - “应该可以”
 
-如果命令无法运行，记录真实阻塞原因和残余风险，不能把它当绿灯。
+命令无法运行时，记录真实阻塞原因和残余风险。禁止把未运行命令当作绿灯。
 
 ## evidence/index.json
 
@@ -123,7 +123,7 @@ evidence/step-001.md
 
 ## Cosmic 官方能力证据
 
-苍穹、星瀚和星空旗舰版通常需要：
+苍穹、星瀚和星空旗舰版通常要求：
 
 ```text
 kd_cosmic_config product=cangqiong
@@ -135,7 +135,7 @@ kd_cosmic_api product=cangqiong mode=search query=<关键词>
 
 ## KSQL / SQL 证据
 
-交付 KSQL/SQL 数据修复内容时，ship 前通常需要：
+交付 KSQL/SQL 数据修复内容时，ship 前通常要求：
 
 ```text
 evidence/cosmic-metadata.json

package/docs/HARNESS_WORKFLOW.md

@@ -6,26 +6,26 @@ KCode Harness 把金蝶开发工作拆成固定阶段：
 discuss -> spec -> plan -> execute -> verify -> ship
 ```
 
-run 可以是一条明确需求，也可以是一组同一目标下的需求。
+run 允许包含一条明确需求，或同一目标下的一组需求。
 
 ## 创建 run
 
-推荐显式指定产品：
+使用显式产品参数：
 
 ```text
 /kd-start --product cangqiong 实现采购订单保存校验
 ```
 
-也可以直接提供需求文档来源，例如本地文件、目录或在线文档链接：
+支持直接提供需求文档来源，例如本地文件、目录或在线文档链接：
 
 ```text
 /kd-start E:\project\docs\需求说明.md
 /kd-start https://example.com/requirements
 ```
 
-在线文档如果需要登录或权限，KCode 会提示你提供可访问链接、导出文件路径或关键内容。
+在线文档要求登录或权限时，KCode 会要求提供可访问链接、导出文件路径或关键内容。
 
-如果你直接输入自然语言需求，KCode 会自动创建 run，并进入 `discuss` 阶段分析需求来源和范围。
+直接输入自然语言需求时，KCode 会自动创建 run，并进入 `discuss` 阶段分析需求来源和范围。
 
 查看当前状态：
 
@@ -34,7 +34,7 @@ run 可以是一条明确需求，也可以是一组同一目标下的需求。
 /kd-gate
 ```
 
-如果产品未知，先看 [产品画像确认](PRODUCT_PROFILE.md)。
+产品未知时，查看 [产品画像确认](PRODUCT_PROFILE.md)。
 
 ## 阶段说明
 
@@ -58,7 +58,7 @@ ship     汇总变更、验证证据、风险和后续事项
 /kd-advance ship
 ```
 
-门禁不通过时，先按 `/kd-gate` 给出的原因补齐产品、文档、计划、证据或风险说明。
+门禁不通过时，按 `/kd-gate` 给出的原因补齐产品、文档、计划、证据或风险说明。
 
 ## 阶段文档
 
@@ -96,7 +96,7 @@ evidence/index.json
 
 ## 待确认问题
 
-需要确认产品、目标单据、插件位置、高风险 SQL 或方案选择时，KCode 会记录待确认问题。未回答的阻断问题会阻止阶段推进。
+产品、目标单据、插件位置、高风险 SQL 或方案选择要求确认时，KCode 会记录待确认问题。未回答的阻断问题会阻止阶段推进。
 
 手动回答：
 
@@ -129,7 +129,7 @@ evidence/index.json
 /kd-finish
 ```
 
-同一目标下的一组需求可以放在同一个 run 中处理。无关目标建议创建新 run：
+同一目标下的一组需求允许放在同一个 run 中处理。无关目标创建新 run：
 
 ```text
 /kd-start --product cangqiong E:\project\docs\本轮采购订单改造.docx
@@ -141,8 +141,8 @@ KCode 会阻止过早写入 Java/XML/SQL/C# 等产品代码：
 
 - 未进入 `execute` 阶段不能写产品代码。
 - `execute` 只能写 `PLAN.md` 中批准的真实源码文件。
-- 临时发现要改新文件，先回到 `plan` 更新计划。
-- 必须先理解当前业务项目已有目录、模块、包名、基类和本地封装。
+- 临时发现要改新文件，回到 `plan` 更新计划。
+- 必须理解当前业务项目已有目录、模块、包名、基类和本地封装后再编码。
 
 证据和门禁细节见 [证据和门禁](EVIDENCE_AND_GATES.md)。
 
@@ -152,7 +152,7 @@ KCode 支持把局部任务委派给隔离子 agent，用来降低长上下文
 
 触发方式有两种：
 
-- 自动：主 agent 在大量调研、独立交叉审查、长上下文复盘或可并行拆分时，可以主动调用 `kd_subagent`。
+- 自动：主 agent 在大量调研、独立交叉审查、长上下文复盘或可并行拆分时，允许主动调用 `kd_subagent`。
 - 显式：用户用 `/kd-review` 或 `/kd-delegate` 指定委派任务。
 
 常用入口：

package/docs/KCODE_DISTRIBUTION.md

@@ -10,16 +10,16 @@ KCode 不 fork Pi，也不替换 Pi 生态。KCode 提供一个面向金蝶开
 - 不修改用户全局 Pi 配置。
 - 不强制安装未审查的第三方 package。
 - 支持项目内复现同一套金蝶开发环境。
-- 不要求用户额外安装全局 `pi` 命令。
+- 无需用户额外安装全局 `pi` 命令。
 
-## 推荐结构
+## 分发结构
 
 ```text
 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`。
+`kcode` 启动器只管理当前项目的 `.pi/settings.json`，不写 `~/.pi` 或其他用户全局目录。启动时默认调用随包 `@earendil-works/pi-coding-agent` 的 `dist/cli.js`，仅在随包 CLI 缺失时回退全局 `pi`。
 
 ## 项目级配置
 
@@ -39,7 +39,7 @@ kcode        全局命令，负责项目初始化、环境检查和启动随包
 }
 ```
 
-后续如需接入第三方 Pi package，先进入 allowlist，再固定版本写入项目配置：
+后续接入第三方 Pi package 时，进入 allowlist 后再固定版本写入项目配置：
 
 ```json
 {
@@ -64,10 +64,10 @@ kcode        全局命令，负责项目初始化、环境检查和启动随包
 
 通过审查后有两种接入方式：
 
-1. 项目级推荐安装：写入 `.pi/settings.json`。
+1. 项目级安装：写入 `.pi/settings.json`。
 2. 离线内置：写入 `dependencies` 和 `bundledDependencies`，并在 `package.json -> pi` 中显式引用其资源。
 
-优先使用项目级推荐安装。只有离线交付或强依赖时，才考虑离线内置。
+默认使用项目级安装。只有离线交付或强依赖时，才允许考虑离线内置。
 
 ## 命令设计
 
@@ -88,4 +88,4 @@ kcode start     初始化后启动 KCode 工作环境
 
 ## 当前限制
 
-当前仓库已可作为 npm 包发布，并提供全局 `kcode` 命令。真实交互式 Pi runtime smoke 需要在具备可用模型/API 配置的环境中执行。
+当前仓库已可作为 npm 包发布，并提供全局 `kcode` 命令。真实交互式 Pi runtime smoke 必须在具备可用模型/API 配置的环境中执行。

package/docs/PRODUCT_PROFILE.md

@@ -1,6 +1,6 @@
 # 产品画像确认
 
-产品画像决定 KCode 使用哪套产品知识、SDK/元数据来源、构建策略、目录约束和门禁规则。标题栏里如果出现 `产品：未确认`，必须先确认产品。
+产品画像决定 KCode 使用哪套产品知识、SDK/元数据来源、构建策略、目录约束和门禁规则。标题栏出现 `产品：未确认` 时，必须确认产品。
 
 ## 支持的产品
 
@@ -17,13 +17,13 @@ enterprise  金蝶企业版 / C#
 
 ## 创建 run 时确认产品
 
-推荐：
+使用显式产品参数：
 
 ```text
 /kd-start --product cangqiong --version V6.0 实现采购订单保存校验
 ```
 
-也可以省略版本：
+允许省略版本：
 
 ```text
 /kd-start --product flagship 实现采购订单插件
@@ -31,7 +31,7 @@ enterprise  金蝶企业版 / C#
 
 ## 已有 run 补产品
 
-如果 run 已经创建，但标题栏显示：
+run 已经创建且标题栏显示以下内容时：
 
 ```text
 产品：未确认
@@ -45,7 +45,7 @@ enterprise  金蝶企业版 / C#
 /kd-status
 ```
 
-如果不确定具体产品，但明确属于金蝶苍穹相关技术栈，优先确认业务实际使用的是苍穹、星瀚还是星空旗舰版，不要把 `cosmic` 当成产品名。
+具体产品不确定但明确属于金蝶苍穹相关技术栈时，确认业务实际使用的是苍穹、星瀚还是星空旗舰版。禁止把 `cosmic` 当成产品名。
 
 ## 如何选择
 
@@ -57,7 +57,7 @@ enterprise  金蝶企业版 / C#
 选择 `xinghan`：
 
 - 明确是金蝶星瀚。
-- 基于苍穹/Cosmic 平台，优先按平台 Java 插件处理。
+- 基于苍穹/Cosmic 平台，默认按平台 Java 插件处理。
 - 接口或元数据存在星瀚差异时，以星瀚产品和当前项目证据为准。
 
 选择 `flagship`：
@@ -65,7 +65,7 @@ enterprise  金蝶企业版 / C#
 - 明确是星空旗舰版。
 - 基于苍穹/Cosmic 平台，Java 插件规则适用。
 - 接口或目录存在旗舰版差异时，以旗舰版产品和当前项目证据为准。
-- 如果项目存在 `code/` 目录，生产代码应跟随 `code/` 下真实结构。
+- 项目存在 `code/` 目录时，生产代码应跟随 `code/` 下真实结构。
 
 选择 `enterprise`：
 
@@ -87,14 +87,14 @@ KCode 会阻止 unknown run 离开 `discuss`。
 
 ### Header 和 `/kd-status` 不一致怎么办？
 
-先刷新门禁：
+刷新门禁：
 
 ```text
 /kd-gate
 /kd-status
 ```
 
-如果刚升级过 KCode，重新启动：
+刚升级过 KCode 时，重新启动：
 
 ```powershell
 kcode start

package/docs/TROUBLESHOOTING.md

@@ -15,7 +15,7 @@ Warning: No models available.
 /model
 ```
 
-或先设置供应商 API Key：
+或设置供应商 API Key：
 
 ```powershell
 $env:OPENAI_API_KEY="sk-..."
@@ -37,7 +37,7 @@ kcode start
 /kd-gate
 ```
 
-如果不知道选哪个，看 [产品画像确认](PRODUCT_PROFILE.md)。
+产品无法判断时，查看 [产品画像确认](PRODUCT_PROFILE.md)。
 
 ## ship 阶段门禁阻塞
 
@@ -72,13 +72,13 @@ kcode version
 type .pi\settings.json
 ```
 
-如果 `packages` 中有多条 `kcode-pi` 路径：
+`packages` 中存在多条 `kcode-pi` 路径时：
 
 ```powershell
 kcode repair
 ```
 
-如果使用 nvm，Windows 上每个 Node 版本都有独立全局 npm 安装目录。切换 Node 后重新安装并初始化：
+使用 nvm 时，Windows 上每个 Node 版本都有独立全局 npm 安装目录。切换 Node 后重新安装并初始化：
 
 ```powershell
 npm install -g kcode-pi@latest
@@ -87,7 +87,7 @@ kcode init
 
 ## npm install 没有更新
 
-先确认 registry 上的版本：
+确认 registry 上的版本：
 
 ```powershell
 npm view kcode-pi version
@@ -102,7 +102,7 @@ npm install -g kcode-pi@latest
 kcode version
 ```
 
-如果提示 `EEXIST: file already exists ... kcode.cmd`，确认旧 shim：
+出现 `EEXIST: file already exists ... kcode.cmd` 时，确认旧 shim：
 
 ```powershell
 npm root -g
@@ -124,9 +124,9 @@ ENOENT: no such file or directory, access 'D:\mnt\d\projects\xxx\src\main\java\F
 
 正确做法：
 
-- 优先使用项目相对路径。
+- 默认使用项目相对路径。
 - 必须用绝对路径时，使用 `D:\projects\xxx\...`。
-- 不要使用 `/mnt/d/...` 或 `/d/...`。
+- 禁止使用 `/mnt/d/...` 或 `/d/...`。
 
 刷新项目上下文：