kcode-pi 0.1.34 → 0.1.38

package/docs/CHANGELOG.md

@@ -6,6 +6,94 @@
 
 - 暂无。
 
+## 0.1.38 - 2026-06-07
+
+### 修复
+
+- 将用户要求的“足够事实后再编码”规则集中写入运行时策略，并自动生成到 `.pi/kd/PROJECT_CONTEXT.md` 的持久规则中，确保新会话继承约束。
+- 明确 API/SDK 文档不能替代 FormId、字段/实体、插件事件、SQL/KSQL 表名、字段映射、并发、日志和验收数据等业务事实。
+- `run.facts` 固化为唯一结构化事实源；已回答 questions 仅作为审计记录，读取状态时不再从历史问题答案反推门禁事实。
+- 状态读取时过滤未知 `factLabel` 和无效事实值，规范化可识别事实标签，避免自造标签或占位答案污染门禁。
+
+### 文档
+
+- 在 Harness 工作流和证据门禁文档中补充项目持久规则、业务事实门禁和外部/BOS 人工验证边界。
+
+### 验证
+
+- `npm run check`
+- `npm run smoke:harness`
+- `npm run smoke:kcode-command`
+- `npm run smoke:package`
+- `npm run smoke:official`
+- `npm run build:cli`
+- `git diff --check`
+
+## 0.1.37 - 2026-06-07
+
+### 修复
+
+- `factLabel` 限制为集中定义的事实标签或别名，禁止 LLM 自造标签写入门禁事实。
+- 数据源上下文门禁只信任结构化 facts 和 evidence，不再仅凭 PLAN 自由文本证明 FormId、字段、插件事件或读写方式。
+- 开放事实问题拒绝“可以、好的、是”等口头确认语；确认题只接受明确肯定或明确否定。
+- 重复 open 问题不会再次写入阶段文档，`/kd-answer` 会区分已回答、无效答案和问题不存在。
+
+### 验证
+
+- `npm run check`
+- `npm run smoke:harness`
+- `npm run smoke:package`
+- `npm run smoke:official`
+- `npm run build:cli`
+- `git diff --check`
+
+## 0.1.36 - 2026-06-07
+
+### 修复
+
+- `kd_question` 改为结构化事实账本：带 `factLabel` 的答案会写入 current fact，否定确认题不会成为事实。
+- 同一 `factLabel` 已有 open 问题或当前事实时禁止重复提问；事实更正必须使用 `action=revise`，旧值会标记为 superseded。
+- 移除 `kd_question` 的交互输入/自定义输入路径；当前只有一个 open blocking 问题时，用户普通短答会自动记录为答案。
+- 占位答案如“待确认、未知、按实际环境、TODO/TBD”不能解除门禁。
+- 子 agent 上下文显式注入已问已答事实和未回答问题，避免委派任务丢失关键约束。
+- Cosmic metadata 数据源证据要求 evidence index `exitCode=0` 且 JSON 内容可解析，避免失败或空证据通过门禁。
+- `kd_verify_result` 拒绝空命令、`unknown` 和占位命令，避免坏 payload 写入验证证据。
+
+### 验证
+
+- `npm run check`
+- `npm run smoke:harness`
+- `npm run smoke:package`
+- `npm run smoke:official`
+- `npm run build:cli`
+- `git diff --check`
+
+## 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 +187,7 @@
 ### 改进
 
 - 收敛运行时 prompt，只保留状态、最近阶段资料、项目上下文摘要、当前阶段任务和核心约束。
-- 精简 `kd-plan`、`kd-execute`、`kd-verify` 命令入口提示，减少和 skills、门禁规则的重复。
+- 精简 `kd-plan`、`kd-execute`、`kd-verify` 命令入口指令，减少和 skills、门禁规则的重复。
 - 移除不存在的 IDE 相关验证表述，保留 Gradle/dotnet 的真实构建验证策略。
 
 ### 验证
@@ -116,7 +204,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
 
@@ -303,12 +303,27 @@ kd_plan_status
 记录、回答或列出结构化问题：
 
 ```text
-kd_question action=ask question="采购入库单 Form ID 是否为 pur_receivebill？" choices=["是","不是"]
+kd_question action=ask factLabel="目标 FormId/单据或表单标识" question="目标 FormId、单据或表单标识是什么？"
+kd_question action=ask factLabel="目标 FormId/单据或表单标识" proposedFactValue="pur_receivebill" question="采购入库单 Form ID 是否为 pur_receivebill？" choices=["是","不是"]
 kd_question action=answer id=Q-001 answer=是
+kd_question action=revise factLabel="目标 FormId/单据或表单标识" answer="SAL_SaleOrder" reason="用户更正先前答案"
 kd_question action=list
 ```
 
-一次只能登记一个当前最阻塞的问题，最多 3 个简短选项。
+一次只能登记一个当前最阻塞的问题，最多 3 个简短选项。`action=ask` 只登记 open 问题，不弹出输入框、不在工具调用内继续追问。
+
+结构化事实参数：
+
+```text
+factLabel          可选，该答案要补齐的门禁事实标签
+proposedFactValue  可选，确认题候选事实值；用户回答 是/yes 时写入 factLabel
+```
+
+门禁只消费当前结构化事实。没有 `factLabel` 的问答只作为上下文记录，不直接解除数据源、字段、接口等事实缺口。
+
+`factLabel` 必须使用 KCode 集中定义的实现契约、数据源上下文或第三方对接事实标签，允许使用这些标签的别名并自动规范为正式标签。同一 `factLabel` 已有 open 问题时禁止重复提问；已有当前事实时禁止再次提问，必须使用 `action=revise` 显式修订。`待确认`、`未知`、`按实际环境`、`TODO/TBD`、单独“是/否”和“可以/好的”等口头确认不会解除开放事实问题。带 `proposedFactValue` 的确认题只接受明确肯定或明确否定。
+
+当前只有一个 open blocking 问题时，用户下一条普通短答会自动记录为该问题答案；命令、疑问句和明显的新任务不会自动记录。
 
 ### kd_subagent
 
@@ -367,7 +382,7 @@ product   可选，flagship/xinghan/cangqiong/enterprise
 edition   旧参数，等同 product
 ```
 
-随包表结构主要覆盖旗舰版和企业版；Cosmic 家族字段和数据库信息优先用 `kd_cosmic_metadata`。
+随包表结构主要覆盖旗舰版和企业版；Cosmic 家族字段和数据库信息默认用 `kd_cosmic_metadata`。
 
 ### kd_check
 
@@ -450,7 +465,7 @@ mode     必填，search/search-method/detail
 query    必填，类名、方法名或完整限定类名
 config   可选，ok-cosmic.json 路径
 method   可选，detail 模式下过滤方法
-compact  可选，请求紧凑详情输出
+compact  可选，紧凑详情输出
 dryRun   可选，只展示命令
 ```
 
@@ -532,7 +547,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)。
 
@@ -38,6 +38,13 @@ KCode Harness 的门禁用于避免跳阶段、猜 SDK、伪造验证结果或
 
 `execute` 阶段只能写 `PLAN.md` 明确列出的源码文件。
 
+业务事实门禁：
+
+- 通用实现契约必须覆盖触发入口、源对象、目标对象、数据变化或字段映射、业务规则、失败处理和验收样例。
+- 数据源上下文必须覆盖目标 FormId/单据或表单标识、插件类型和触发事件、字段/实体/分录标识、数据读取写入方式；SQL/KSQL 场景还必须覆盖表名和数据库字段名。
+- 第三方对接必须覆盖接口文档、对接方向、触发时机、接口地址、认证配置、字段映射、并发/幂等、超时重试限流、错误补偿、日志脱敏和请求/响应样例。
+- API 文档、SDK 知识库和 PLAN 自由文本不能替代结构化 facts 或 evidence。
+
 ## SDK 签名证据
 
 涉及 Java/C# 产品代码时，进入 `execute` 前必须已有：
@@ -46,7 +53,7 @@ KCode Harness 的门禁用于避免跳阶段、猜 SDK、伪造验证结果或
 evidence/sdk-signature.md
 ```
 
-推荐工具：
+使用工具：
 
 ```text
 kd_sdk_signature product=cangqiong query=QueryServiceHelper method=loadSingle
@@ -54,7 +61,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 +103,7 @@ Exit: 0
 - “未执行”
 - “应该可以”
 
-如果命令无法运行，记录真实阻塞原因和残余风险，不能把它当绿灯。
+命令无法运行时，记录真实阻塞原因和残余风险。禁止把未运行命令当作绿灯。
 
 ## evidence/index.json
 
@@ -123,7 +130,7 @@ evidence/step-001.md
 
 ## Cosmic 官方能力证据
 
-苍穹、星瀚和星空旗舰版通常需要：
+苍穹、星瀚和星空旗舰版通常要求：
 
 ```text
 kd_cosmic_config product=cangqiong
@@ -135,7 +142,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 会记录待确认问题。未回答的阻断问题会阻止阶段推进。
 
 手动回答：
 
@@ -107,6 +107,11 @@ evidence/index.json
 原则：
 
 - 一次只问一个当前最阻塞的问题。
+- 问题登记后保持 open；用户回答后必须用 `/kd-answer` 或 `kd_question action=answer` 记录。
+- 需要解除门禁事实缺口的问题必须带结构化 `factLabel`；确认题必须用 `proposedFactValue` 表示候选事实值。
+- 同一 `factLabel` 已有 open 问题或当前事实时禁止重复提问；用户更正事实时使用 `kd_question action=revise`，旧事实会标记为 superseded。
+- 当前只有一个 open blocking 问题时，用户下一条普通短答会自动记录；占位答案不会解除门禁。
+- 数据源 FormId、字段/实体、插件事件和读写方式必须来自结构化 facts 或 evidence；PLAN 自由文本不能单独证明这些事实。
 - 得到答案后再继续问下一个必要问题。
 
 ## 多个需求
@@ -129,7 +134,7 @@ evidence/index.json
 /kd-finish
 ```
 
-同一目标下的一组需求可以放在同一个 run 中处理。无关目标建议创建新 run：
+同一目标下的一组需求允许放在同一个 run 中处理。无关目标创建新 run：
 
 ```text
 /kd-start --product cangqiong E:\project\docs\本轮采购订单改造.docx
@@ -141,8 +146,23 @@ KCode 会阻止过早写入 Java/XML/SQL/C# 等产品代码：
 
 - 未进入 `execute` 阶段不能写产品代码。
 - `execute` 只能写 `PLAN.md` 中批准的真实源码文件。
-- 临时发现要改新文件，先回到 `plan` 更新计划。
-- 必须先理解当前业务项目已有目录、模块、包名、基类和本地封装。
+- 临时发现要改新文件，回到 `plan` 更新计划。
+- 必须理解当前业务项目已有目录、模块、包名、基类和本地封装后再编码。
+- API 文档、SDK 文档和知识库只能作为技术用法证据，不能替代 FormId、字段/实体、插件事件、SQL/KSQL 表名、数据库字段名、字段映射、并发/幂等、日志脱敏和验收数据等业务事实。
+- 信息不足时登记一个最阻塞的结构化问题；禁止生成模板代码或占位实现。
+- 内部插件、自动下推、第三方对接、字段改写和数据同步统一按实现契约、数据源上下文和对接上下文补齐事实，不为单个业务场景写死提示词。
+
+## 项目持久规则
+
+`kcode init` 和 `kcode context --refresh` 会生成 `.pi/kd/PROJECT_CONTEXT.md`。新会话必须先读取该文件，再计划或编辑代码。
+
+持久规则由 `src/harness/prompt-policy.ts` 集中管理，并自动写入项目上下文。规则要求：
+
+- `run.facts` 是唯一结构化事实源，已回答 questions 只作为审计记录。
+- `factLabel` 必须使用集中定义的事实标签或别名。
+- PLAN 自由文本不能单独证明 FormId、字段、插件事件或读写方式。
+- 外部系统操作、BOS 注册、人工功能测试和生产验证必须由用户提供可核验证据。
+- 不做旧状态迁移兼容或旧问题答案推断；坏状态只过滤，缺失事实重新提问确认。
 
 证据和门禁细节见 [证据和门禁](EVIDENCE_AND_GATES.md)。
 
@@ -152,7 +172,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/...`。
 
 刷新项目上下文：