kld-sdd 2.7.8 → 2.8.0

package/templates/skills/kld-sdd/opsx-check/review-template.json

@@ -0,0 +1,22 @@
+{
+  "reviewer": {
+    "reviewer": "<实际评审者>",
+    "review_execution_mode": "subagent",
+    "reviewer_agent_id": "<真实子代理ID>",
+    "parent_session_id": "<主会话ID>",
+    "review_session_id": "<评审会话ID>",
+    "author_session_id": "<作者会话ID>",
+    "reviewer_independence": "independent-review",
+    "fallback_reason_code": null,
+    "fallback_reason": null
+  },
+  "items": [
+    {
+      "id": "<唯一检查项ID>",
+      "category": "consistency",
+      "status": "passed",
+      "evidence": "<实际文件:行号或锚点及检查依据>"
+    }
+  ],
+  "warning_dispositions": []
+}

package/templates/skills/kld-sdd/opsx-check/reviewer.md

@@ -7,7 +7,8 @@
 
 - 自己读取完整的相关业务文档正文一次；批量读取相互独立的文件，同一文件同一版本复用，输出截断时补读缺失部分。
 - Simple 支持根目录 `spec.md/design.md/tasks.md`；Full 使用 `specs/<capability>/`。兼容 `propose.md/task.md`。
-- 程序已核验的 UUID、谱系、引用和 DAG 结果直接引用；模型负责语义覆盖、业务矛盾、可行性和测试质量，不能把“结构合法”当作“设计正确”。
+- 程序已核验结构。身份、UUID、谱系和归档诊断由主 Agent 自行处理，不写入给用户的评审结论。
+- 模型负责产物质量：语义覆盖、design 是否覆盖 spec、tasks 是否拆解 design、业务矛盾、可行性和测试质量。不能把“结构合法”当作“设计正确”，也不能用工具诊断代替这些缺口。
 - 代码只读 design/tasks 实际引用的锚点及其必要依赖；不做全仓 diff、不运行测试。用户提供的上下文文件必须读取。
 - 仅指定 Capability 时，补读 proposal 和明确的跨能力依赖；报告覆盖边界，不能宣称全 Change 已独立评审。全 Change 的程序语义门禁仍执行。
 - 不适用的算法、TDD 或实施后检查写 `N/A` 和理由，不能计成通过；仅在 test-strategy=tdd 时加载下面 TDD 资料。
@@ -15,10 +16,10 @@
 
 #### 4.1 完整性检查
 
-- [ ] proposal.md 存在且包含完整章节
+- [ ] proposal.md 存在，实际业务意图、能力、范围与约束完整；不要求无关空章节
 - [ ] 每个 Capability 都有 spec.md
 - [ ] Full 模式每个 spec.md 都有对应 design.md，每个 design.md 都有对应 tasks.md；Simple 未生成这些文档不误报缺失
-- [ ] 所有文档符合模板结构
+- [ ] 所有文档保留解析需要的 frontmatter、身份、锚点与关系，内容规模匹配实际变更
 
 #### 4.2 一致性检查
 
@@ -91,10 +92,30 @@
 - Check 阶段只读，不自动勾选；报告中必须说明这是“任务可能已执行但文档未同步”或“任务真实未完成”的待确认项。
 
 
+## 长文档分批读取
+
+- 单个文件超过 1500 行时必须分段读取（先读前 1500 行，再按需续读缺失部分），避免一次读取撑爆上下文导致输出截断。
+- spec.md / design.md / tasks.md 分多次独立读取，不要把所有文档合并进一次读取；同一文件同一版本只读一次，复用结果。
+
 ## 返回给主 Agent
 
-一次返回五维结论和 [result-template.json](result-template.json) 中的 `check_results`（替换全部占位值），以及检查范围、逐项证据路径/锚点、未执行项及原因、阻断问题、warning 明细和修复建议。算法问题归到四类统计中的 `consistency`，五维文字报告仍单列算法；不得重复计数。
+**⛔ 返回格式硬约束**：最终回复必须包含且仅包含一个 json 代码块，结构与 [review-template.json](review-template.json) 对齐（`reviewer` 身份块由主 Agent 补齐，评审者不写）；JSON 之前的解释文字不得超过 3 行：
+
+```json
+{
+  "items": [
+    { "id": "<唯一ID>", "category": "consistency", "status": "error", "evidence": "spec.md §3.2 要求…但 design.md 未覆盖（文件+章节定位）" }
+  ],
+  "warning_dispositions": []
+}
+```
+
+- `category` ∈ completeness / consistency / executability / tdd_compliance；`status` ∈ passed / error / warning / suggestion / na。
+- 每项必须含 `evidence`（文件+章节定位），na 项写不适用理由；§4.4b 的 DAG 语义警告归入 `warning_dispositions`，不混入 items。
+- 不满足此结构视为 `SUBAGENT_RESULT_INVALID`，主 Agent 会要求补齐一次缺项。
+
+内容要求：items 覆盖全部实际执行的检查；检查范围与必要问题说明写在 JSON 前的 ≤3 行解释文字或对应 item 的 evidence 中，不另起段落；身份块由主 Agent 根据真实工具结果补齐，评审者不写。算法归入 consistency，不重复计数；不手算总数，不复述所有通过项，不复制文档全文。
 
-顶层 `total` 必须是大于 0 的整数；四类 categories.total 合计等于 total，四类未通过数合计等于 errors。N/A 项 total=0。不要为使计数好看填“全部通过”。任务状态直接复用程序输出，reviewer 身份使用真实工具返回 ID；无法确认作者身份不能标为 independent-review。
+至少有一个实际适用项。未执行项使用 na 并写原因，不能为计数填“全部通过”。任务状态由工具读取，不能伪造 reviewer 或独立性。主 Agent 无需为统计不匹配重新委派评审。
 
-评审期间若发现文件变化，返回受影响路径，不能用旧版本结果覆盖新文档。只读检查不修文档、不改代码。
+评审期间若发现文件变化，返回受影响路径。只读检查不修文档、不改代码。

package/templates/skills/kld-sdd/opsx-consistency-check/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: opsx-consistency-check
-description: "Spec 双向一致性校验 - 验证代码实现与 spec 文档的双向一致性"
-argument-hint: "[change-name] [file...]"
+description: "根据实际代码和 Spec 检查接口、业务规则与错误处理，按输入指纹复用检查回执"
+argument-hint: "[change-name]"
 license: MIT
 metadata:
   author: sdd-team
-  version: "3.0"
+  version: "4.0"
 allowed-tools:
   - Bash
   - Read
@@ -13,141 +13,63 @@ allowed-tools:
   - Edit
 ---
 
-> **路径约定**：`<skill-dir>` = 本文件所在目录；`<spec-root>` = spec 仓根目录（含 `skywalk-sdd/git-hooks/`）。辅助脚本：`<skill-dir>/scripts/scripts.cjs`；hook 同款采集器：`<spec-root>/skywalk-sdd/git-hooks/consistency-check-core.cjs`。
+检查实现是否满足本次业务约定，留下可复核的证据。`opsx-check` 检查文档及其关系；本技能检查代码与 Spec，两者不能互相替代。日常 Git 提交不要求用户手动运行本技能；Apply 在实施收尾时自动调用。
 
-你是 SDD 一致性校验专家。任务只有一件事：**对比 diff 变更代码与 spec 的接口契约是否一致**（API 路径、HTTP 方法、请求参数、响应字段、错误码），生成 git hook 可消费的报告。除此之外的一切（业务规则深挖、关联文件扫描、多维度深度校验）都不做。
+## 1. 确定输入并尝试复用
 
-## 硬约束（违反会导致 hook 死循环或误拦，不可协商）
-
-1. **采集必须用 hook 同款命令**（步骤 1），禁止手工拼 git diff——两边采集不一致会导致报告盖不住 diff → hook 拦截 → 重新生成仍被拦的死循环
-2. **coveredFiles 必须与实际校验的变更文件完全一致**：path 为工作区相对路径，size/sha256 直接复用采集器输出（LF 归一化已内置），禁止估算、禁止用平台命令重算
-3. **confidence 只能 `high`/`medium`/`low`**（其他值被 hook 判非法拦截）；**generatedAt 必须本机本地时间** `YYYY-MM-DD HH:mm:ss`（禁止 UTC，hook 按本地时区做过期判断）
-4. **md + json 成对写入** `openspec/changes/<change-name>/`，单边存在会被判报告不完整并拦截
-5. **只读变更文件本身**，不扩展读 DTO/Model/配置/SQL 等关联文件；缺证据标"待人工核查"，不中断补读
-6. **无业务代码变更 → 不生成报告**，输出一句提示即结束（hook 对无业务代码提交直接放行）
-7. 生成前必须先删旧报告（步骤 2c 已内置），全量重新校验，不读旧报告做增量复用
-8. **多仓布局下 `repositories` 必填**：工作区根存在 `.sdd-workspace.yaml` 时，JSON 报告必须含 `repositories` 数组，`path` 为该 change 覆盖的代码仓名（与 `.sdd-workspace.yaml` 的 `code_repos` 条目一致）。单仓布局可省略或留空数组。hook 用此字段剥离 coveredFiles 路径前缀以对齐 diff 路径，缺失会导致路径不匹配 → 误判"无交集" → 报告形同虚设
-
-## 执行流程（4 步）
-
-### 1. 采集变更文件（脚本，秒级）
-
-> **禁止环境预探测**：不要 Test-Path 探测 git 仓、不要列目录确认脚本存在——采集器自动处理单仓/多仓布局（多仓读 `.sdd-workspace.yaml` 的 code_repos 逐仓 diff），命令失败自会报错。首轮回复直接并行发起：① 采集命令 ② `list-changes`（两者无依赖）。
+从当前实施上下文取得明确的 Change 和代码仓。多个活动 Change 不等于本次都要检查；不要按分支名猜测。多仓逐个实际涉及的代码仓运行，使用同一个 Spec 根和 Change；回执按仓库身份分别存储，互不覆盖。
 
 ```bash
-node <spec-root>/skywalk-sdd/git-hooks/consistency-check-core.cjs --collect --business-only --hash --project=<工作区根或代码仓根>
-node <skill-dir>/scripts/scripts.cjs list-changes
+node "<spec-root>/skywalk-sdd/git-hooks/delivery-check.cjs" prepare --project="<代码仓>" --change=<change> --base=<实施前提交SHA>
 ```
 
-输出 `businessFiles`（对象数组，含 path/size/sha256，机械筛选已内置）+ `deletedFiles`。命令失败（退出码非 0）= git diff 采集失败，如实报错终止，禁止降级为"无变更"。
-
-- **无业务文件** → 提示"无代码变更，跳过校验"并结束
-- **有业务文件但无活跃 change** → 报错终止，提示先执行 opsx-propose
-- **多 change 且未指定 change-name** → 按 spec 覆盖范围把文件归属到各 change，每个 change 独立出报告；同一文件被多个 change 归属时只在首个 change 完整校验、其余复用结论（coveredFiles 仍完整包含）。**单 change 或已指定 change-name** → 全部文件归入，跳过归属逻辑
-- **用户指定了具体文件** → 交给 `consistency-check-core.cjs --filter` 机械筛选，哈希用 `prepare-report --files-from=<列表文件>` 补算
-
-### 2. 读上下文（a/b/c 同一回复并行发起，禁止分批等待）
-
-a. **定位并读 spec**：`node <skill-dir>/scripts/scripts.cjs find-specs <change-name>` 拿文件列表，**禁止全量读**（近百个 spec 全读既慢又撑爆上下文）。API 路径由 AI 从已读 Controller 原生提取（任何语言的路由写法都直接认识，禁止用正则 grep 代码提取），再用**字面量片段**（如 `/api/user`；禁止含 `|`、`"`、`\`、`()` 的正则——Windows cmd 会拆解管道符与引号导致 0 命中）grep spec 目录：
-
-   ```bash
-   node <skill-dir>/scripts/scripts.cjs grep-code "/api/user" <openspec-dir> --glob=spec.md -i
-   ```
-
-   **grep 省略条件（省一轮往返）**：`find-specs` 命中的变更级 spec 文件总数 ≤ 5 个时，跳过 grep 直接读这些文件（变更级 spec 本来就是该 change 的契约文档，命中概率极高）；命中 > 5 个或需在全局 spec 中定位时才 grep。只读命中文件；命中 0 → 回退读变更级 spec（`changes/<name>/specs/`），仍不读全局 spec 全集。
-
-b. **读代码（按契约角色分层，同一回复并行发起）**：首轮把全部变更文件按契约角色分三层，**全文 Read 与 grep 混排在同一回复一次发齐**（不产生额外往返；禁止的是"grep 定位后再补读"的两段式，不是 grep 本身）：
-   - **契约核心（全文 Read）**：Controller、DTO/VO/QueryDTO、全局异常处理器（`*Controller`、`*DTO`、`*VO`、`*ExceptionHandler` 等，按语言现场识别）——接口契约的直接载体，必须逐字段比对
-   - **契约相关（grep 取证，不读全文）**：Service/ServiceImpl、Repository——只 grep 方法签名 + 响应构造 + 错误码，模式按语言现场定（Java `return`/`Map.of`、Python `return {`/`jsonify`、Go `c.JSON`）
-   - **无契约面（grep 确认后跳过）**：Application 启动类、`*Config`/`*Properties`、`*Util`、`BusinessException`、`*Mapper` 接口等——grep 端点声明（路由注解/路径常量）+ 业务错误码字面量，**零命中 → 结论"无契约面"，不进入步骤 3 逐字段比对**；有命中 → 升级按上一条 grep 取证处理
-   - **前端**（.ts/.tsx/.vue/.js）：只 grep API 调用路径 + HTTP 方法，与 spec 路径比对
-   - **coveredFiles 不受分层影响**：全部变更文件照常列入报告（硬约束 2），分层只决定"读多深"，不决定"盖不盖"
-   - **例外**：契约核心文件单文件 ≥ 800 行时，先 grep 定位端点区域，再分段读相关区间
+`--base` 优先使用 Apply 的实施前基线；首次新仓无 HEAD 时可省略，由工具选择空树。后续命令复用 prepare 保存的基线。默认读取工作区；显式检查暂存内容时加 `--scope=index`，不能把工作区内容当作暂存内容。
 
-c. **prepare-report**：`node <skill-dir>/scripts/scripts.cjs prepare-report openspec/changes/<change-name>` —— 清理旧报告 + 输出本地时间戳（`timestamp` 直接作为 generatedAt；该命令绝不读 stdin，不会挂起）。
+输出包括 `requiredFiles`、`inputs`、`inputFingerprint`、`preparedFile`、`reviewFile`、`reuseReview`。快照同时绑定代码、Spec、仓库身份与规则版本。指纹相同且覆盖完整时，直接复用，不删除旧报告、不重新调用模型。旧版没有输入指纹的报告需升级生成一次。
 
-> **报告落点（固定，无需确认）**：报告必须写在 **spec 根**下的 `openspec/changes/<change-name>/`（hook 的 `findReportJson` 只在 `<spec-root>/openspec/changes/<name>/` 找报告，写到别处 = 报告缺失 = 拦截）。`prepare-report` 已自动按 spec 根解析相对路径，输出 JSON 的 **`changeDir` 字段就是解析后的实际目录**——写报告直接用它拼接文件名，禁止自行按 cwd 推导路径，也无需读脚本源码确认。coveredFiles.path 由采集器原样输出（多仓布局带仓前缀如 `user-info-mgmt/src/...`）。hook 在代码仓根运行、diff 路径无前缀，靠 `repositories[].path` 剥离 coveredFiles 前缀才能对齐——故多仓布局下 `repositories` 必填（见硬约束 8）。
+当前版本保守地对本仓跟踪文件及非忽略的未跟踪文件取指纹（排除生成目录、SDD 运行时），并包含本 Change 与全局规格；它不是跨仓依赖的自动发现器。检查需要其他仓的依赖时，应在该仓单独验证，并在交付摘要列出其提交。
 
-> **子代理分派规则（按活跃 change 数机械判定，禁止裁量）**：
-> - **多 change（≥2 个）→ 必须并行**：每个 change 一个子代理，同一回复全部分派（上限 2 个，两 change 恰好一批）。**禁止**主线程逐 change 串行校验，**禁止**以"宿主并发能力不确定"为由跳过——派发在最坏情况（宿主排队串行）下也只是无收益，结果照常回收，无损害；实测多 change 串行是步骤 3 最大耗时来源（两仓各 5 分钟级推理串行叠加），并行后总耗时取单 change 最大值
-> - **单 change → 按文件量分组**（仅适用于恰好 1 个活跃 change 的场景，不得套用到多 change 的单个 change 上）：≤ 15 个文件主线程直接校验（无需子代理）；> 15 个按 8-10 个/组分派子代理，逐组执行
-> - **禁止**：主线程自己串行逐文件校验（36 文件 = 36 轮往返，是最大耗时来源）；一次回复分派超过 2 个子代理（并发过高导致宿主排队 + 结果交错，实际更慢）
-> - **派发提示必须自带分层读取规则**：子代理不读 SKILL.md，只知派发提示里写的内容——分派时必须把步骤 2b 的三层策略（契约核心全文读 / Service·Repository grep 取证 / 无契约面 grep 确认后跳过）原文写入提示。漏写则子代理退回全量读全文（实测发生：子代理全文读 ServiceImpl/Mapper/Config，上下文膨胀拖慢推理与汇总生成）
-> - 每个子代理完成"读 spec 命中集 + 按契约角色分层读本组代码 + 步骤 3 校验"，返回差异清单 + 计数，主线程汇总生成报告；公共文件只在首个归属 change 的子代理中完整校验，其余复用
+## 2. 定向取证
 
-### 3. 校验（AI 推理，唯一核心工作）
+`reuseReview=false` 时，读取 `requiredFiles` 对应的业务实现和相关 Spec。可以比较旧回执与新 `inputs` 确定变化位置，但不能把失效的旧结论直接认作本轮通过。
 
-对每个变更文件，对照 spec 回答一个问题：**接口契约是否一致？**
+- 接口：路径、方法、请求与响应字段、错误码逐项对照。
+- 业务规则：本次验收行为、边界条件、状态变化是否实现。
+- 校验规则：必要的参数校验、拒绝条件是否与约定相符。
+- 错误处理：失败路径是否满足调用方约定。
 
-**检查项（双向）**：
-- **spec → code**：spec 定义的路径/方法/参数/响应字段/错误码，代码是否实现且一致
-- **code → spec**：代码中的端点、响应字段 key、业务错误码是否已在 spec 记录（**仅枚举业务契约面**；工具方法、日志、防御性代码、DTO 转换等纯技术实现不枚举、不降级）
+先读变更文件与对应规格，再按实际引用补读 DTO、配置、SQL 或调用方。一次批量读取独立文件；不为凑检查项全量扫描全文，也不禁止必要的依赖阅读。删除文件同样需要核对受影响的契约。
 
-**要求**：
-- 响应结构**逐字段**对比，字段名精确匹配（`token` ≠ `accessToken`）；`Map.of()`/字典/结构体构造必须提取所有 key 逐一比对
-- 每条差异定位到 `文件:行号 + spec 章节`，不贴代码原文片段
-- 找不到证据的标 ❌/⚠️，不假设一致
+每个结论记录 `代码路径:行号 / Spec路径:章节`。缺依据使用 `not_checked`；有实际冲突使用 `fail`；无该维度使用 `na` 并给出理由。不用 high confidence 代替事实，不把未检查维度固定写成 pass。
 
-**置信度判定**：
-- **high**：无差异，或仅技术实现未记录
-- **medium**：辅助性差异（非关键端点/字段缺失或不一致）
-- **low**：关键契约不一致、spec 有关键功能代码没有、代码有业务功能 spec 没有
+## 3. 保存真实检查结果
 
-### 4. 生成报告（纯模板填充，零推理）
-
-结论确定后直接写文件，**禁止**重新核对证据或推演差异。md + json 在**同一回复并行写入**（多 change 的全部报告同批写）。**禁止任何计时打点**（步骤起止时长、执行统计、额外的 `now` 调用）——报告 `generatedAt` 已由步骤 2c 的 prepare-report 输出，流程内不需要其他时间戳；执行时长统计只在用户显式要求时做，默认不做。
-
-**JSON**（`consistency-report-result.json`，hook 唯一消费源，schema 固定）：
+把检查结果写到 `preparedFile` 同目录的 `review-input.json`，避免临时结果进入代码快照。`inputFingerprint` 原样复制，`reviewedFiles` 只列实际检查过的文件，至少覆盖本次 `requiredFiles`。
 
 ```json
 {
-  "changeName": "<change-name>",
-  "confidence": "high | medium | low",
-  "generatedAt": "<YYYY-MM-DD HH:mm:ss 本地时间>",
-  "repositories": [
-    { "path": "<代码仓名>" }
-  ],
-  "coveredFiles": [
-    { "path": "<工作区相对路径>", "size": 2341, "sha256": "<64位十六进制>" }
-  ],
+  "inputFingerprint": "<prepare 输出>",
+  "reviewedFiles": ["src/order.js"],
   "dimensions": {
-    "interfaceContract": { "status": "pass | warning | fail", "issues": 0 },
-    "businessRules": { "status": "pass", "issues": 0 },
-    "validationRules": { "status": "pass", "issues": 0 },
-    "errorCodes": { "status": "pass | warning | fail", "issues": 0 }
+    "interfaceContract": {"status": "pass", "evidence": ["src/order.js:12 / spec.md §接口"]},
+    "businessRules": {"status": "pass", "evidence": ["src/order.js:28 / spec.md §金额边界"]},
+    "validationRules": {"status": "not_checked", "evidence": []},
+    "errorCodes": {"status": "na", "reason": "纯计算函数，本次无错误码协议"}
   },
-  "summary": {
-    "totalChecks": 0, "passed": 0, "failed": 0, "warnings": 0,
-    "undocumentedBusiness": 0, "undocumentedTechnical": 0, "specMissing": 0, "inconsistent": 0
-  }
+  "issues": []
 }
 ```
 
-`businessRules`/`validationRules` 固定 `pass:0`（简化校验不做深度检查）；`summary` 按差异清单逐条归类（一条差异只计一次），`failed + warnings` 与各维度 `issues` 合计一致。
-
-**MD**（`consistency-report.md`，极简，禁止凑数空章节）：
-
-```markdown
-# Spec 一致性校验报告
-
-**变更**：<change-name>　**生成时间**：<YYYY-MM-DD HH:mm:ss>
-**校验范围**：<N 个文件>　**置信度**：<high/medium/low>
+只有无业务代码变化且四个维度都有理由判为 `na` 的文档或非实施变更，才可在回执中追加 `tests: {"status":"na","reason":"具体不适用理由"}`；工具显示测试不适用，不能说测试已通过。
 
-## 结果
+该例包含未检查项，不能通过交付验证。依据实际取证补完，不能只改状态。
 
-<全部通过时只写一行：接口契约与错误码全部一致，无差异。>
-
-<有差异时列下表：>
-
-| # | 类型 | 风险 | 位置 | 描述 | 建议 |
-|---|------|------|------|------|------|
-| 1 | 不一致 | P0 | File.java:42 / spec §2.1 | <差异描述> | <改代码或改 spec> |
+```bash
+node "<spec-root>/skywalk-sdd/git-hooks/delivery-check.cjs" record-review --project="<代码仓>" --change=<change> --input="<review-input.json>"
 ```
 
-类型四选一：`代码有 spec 没有（业务）` / `代码有 spec 没有（技术）` / `spec 有代码没有` / `不一致`。
-
----
+工具重算指纹，输入变化时拒绝旧结论。失败或未检查的结果仍会保存并返回非零退出码，便于修复后复核；成功回执写到输出 `reviewFile`，由脚本管理哈希，不手填。回执是 Agent 的可追溯检查记录，不是对业务正确性的数学证明。
 
-## 渐进披露
+## 4. 返回实施收尾
 
-- Read `references/reference.md` 仅在遇到置信度摘要未覆盖的边界案例时（如技术实现与业务实现难以区分、关键性拿不准）— **禁止预防性读取**（主文档摘要已覆盖 90% 场景）；含问题分类、置信度判定规则、关键性判断标准、维度判定参考、示例
+报告发现的问题、检查范围与未检查部分。由 Apply 在同一轮继续执行真实测试及 `delivery-check verify`；本技能通过只表示检查回执有效，不表示测试、知识库入库或正式交付已经完成。

package/templates/skills/kld-sdd/opsx-consistency-check/scripts/scripts.cjs

@@ -45,6 +45,11 @@ const crypto = require('crypto');
 
 /**
  * 解析 spec 仓根目录（含 openspec/ 的目录）。
+ *
+ * ⚠️ 本函数是**独立实现**，不 require 权威链（`skywalk-sdd/ontology/`）——
+ * 本脚本部署在编辑器 skills 目录，运行于代码仓 cwd，spec 仓的运行时实体
+ * 可能尚未就绪，跨仓 require 会让技能强依赖运行时。
+ *
  * 解析顺序（与权威实现 resolve-spec-root.cjs 的 resolveSpecProjectRoot 对齐）：
  * 1. --spec-root= 命令行参数（显式指定，验证 openspec/ 存在）
  * 2. .sdd-spec-root 标记文件（cwd 及祖先目录向上遍历，读内容 resolve）
@@ -53,6 +58,15 @@ const crypto = require('crypto');
  * 5. cwd 或祖先目录存在 .sdd-workspace.yaml → 读 spec_path 解析（多仓场景）
  * 6. 向上逐级父目录找 openspec/（兜底）
  * 找不到返回 null（调用方报错退出，不静默）。
+ *
+ * 与权威链的已知差异（均为有意保留）：
+ * - 多一个第 1 步「显式 --spec-root= 参数」——技能允许用户强制指定。
+ * - 第 4 步「cwd 有 openspec/」的位置比权威链靠前：本脚本常直接以 spec 根
+ *   为 cwd 运行，就近命中更符合预期。
+ *
+ * ⚠️ 修改本函数时必须同步检查 `skywalk-sdd/ontology/resolve-spec-root.cjs`
+ * 与 `spec-detect.cjs`，避免再次出现「技能认某个来源、权威链不认」的漂移
+ *（`.sdd-workspace.yaml` 曾长期只有本脚本读，权威链不读，已补齐）。
  */
 function resolveSpecRoot() {
   // 1. 显式参数
@@ -439,21 +453,8 @@ function prepareReport(changeDir) {
     const specRoot = resolveSpecRoot();
     if (specRoot) dir = path.resolve(specRoot, changeDir);
   }
-  // 1. 清理旧报告（失败不静默：残留旧报告会导致后续 Write 要求先 Read）
-  const reportFiles = ['consistency-report.md', 'consistency-report-result.json'];
+  // Keep previous evidence for comparison/reuse. Explicit clean-reports remains available.
   const cleaned = [];
-  for (const f of reportFiles) {
-    const fp = path.join(dir, f);
-    try {
-      if (fs.existsSync(fp)) {
-        fs.unlinkSync(fp);
-        cleaned.push(fp.replace(/\\/g, '/'));
-      }
-    } catch (e) {
-      console.error('ERROR: failed to delete ' + fp + ': ' + e.message);
-      process.exit(1);
-    }
-  }
   // 2. 批量哈希（可选）：仅当显式提供 --files-from=/--files= 时执行，绝不读 stdin（防交互式终端挂起）。
   //    无输入源 = "只清理 + 取时间戳"合法模式（哈希已由 --collect --hash 提供时无需重复传入），hashes 输出空数组
   const hashes = [];

package/templates/skills/kld-sdd/opsx-kb-config/SKILL.md

@@ -16,12 +16,11 @@ allowed-tools:
   - Write
   - Edit
 ---
-
 # 本体知识库 · 配置
 
 只负责**配置**。一次配置，查询（opsx-ontology-query）、入库（opsx-kb-ingest）、文件夹上传（kb-upload）全部可用。
 
-> **📡 共享状态**：配置写入 `kb-state.json`（位于 spec 仓根目录），所有 KB 技能共用。任一技能配置后，其他技能自动可用，无需重复输入。
+> **📡 共享状态**：配置写入 `kb-state.json`（**唯一权威位置 = spec 包裹包根目录**），所有 KB 技能共用。任一技能配置后，其他技能自动可用，无需重复输入。
 
 > **🖥️ 跨平台执行规则**（Windows 用户必读）:
 > - KB 配置涉及 HTTP 请求和 JSON 文件读写，**禁止**在 PowerShell 中使用 `curl`（被别名为 Invoke-WebRequest）→ 用 `Invoke-RestMethod` 或 Node.js 脚本
@@ -35,11 +34,10 @@ allowed-tools:
 
 | 场景 | 说明 |
 |------|------|
-| 首次配置 | 输入 API Key → 绑定监控项目（可留空）→ 选择 Space/KB → 创建 project-identity.json |
-| 更换 API Key | 清空 apiKey，重新输入；随后需重新校验监控项目绑定 |
+| 首次配置 | 输入 API Key → 选择 Space/KB → 创建 project-identity.json |
+| 更换 API Key | 清空 apiKey，重新输入并验证当前目标权限 |
 | 更换知识库 | 清空 targets，重新选择 Space/KB |
-| 绑定/更换监控项目 | 写入或清除 `projectName`（Step 2.5） |
-| 查看当前配置 | 展示已配置的 Space/KB 列表与项目绑定 |
+| 查看当前配置 | 展示已配置的 Space/KB 列表与团队项目身份 |
 | 校验配置 | 探活 API + 校验 project_id 与 spaceKey 一致 |
 
 ## 配置步骤
@@ -59,6 +57,34 @@ SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
 # 或直接用 read_file 工具读取该文件
 ```
 
+#### 1.1 位置校验（写入前必做）
+
+`kb-state.json` 的**唯一权威位置是 spec 包裹包根目录**（`$SPEC_ROOT/kb-state.json`）。
+本步骤在**任何写入之前**执行，防止把配置写到错误位置 —— 一旦写偏，
+后续所有 KB 技能都读不到。
+
+校验两件事，任一不通过则**停止写入**并提示用户：
+
+1. **`SPEC_ROOT` 必须是 spec 包裹包根**。用统一判据（与 `lib/shared.cjs#isKbStateHostDir`
+   同源，即 `ontology/resolve-spec-root.cjs#isSpecPackageRoot`）：
+   目录名匹配 `*-sdd-specs`，或四结构齐全
+   （`modules.yaml` + `sdd.config.yaml` + `openspec/changes` + `openspec/specs/overview.md`），
+   或至少含 `openspec/`。
+   ```bash
+   # 临时脚本：const shared = require('<SPEC_ROOT>/skywalk-sdd/lib/shared.cjs');
+   #           console.log(shared.isKbStateHostDir(process.argv[1]));
+   node _tmp-check-host.cjs "$SPEC_ROOT"
+   ```
+   输出 `false` → 报错：`SPEC_ROOT 不是 spec 包裹包根，禁止写入 kb-state.json`，
+   并让用户确认 `--project` / `.sdd-spec-root` 是否指向 `*-sdd-specs`。
+
+2. **写入路径必须由 `$SPEC_ROOT` 直接拼接**：`"$SPEC_ROOT/kb-state.json"`。
+   禁止使用 `../`、`.shared/`、`<ide>/skills/` 等相对偏移构造路径。
+
+> 读取侧由 `lib/shared.cjs#loadKbState` 执行同样的位置校验：只接受宿主目录为
+> spec 包裹包根的命中。因此若本步校验通过而后续仍报「KB 未配置」，
+> 优先检查是否写到了非 `$SPEC_ROOT` 的位置。
+
 ### 2. API Key
 
 若 `state.apiKey` 为空或用户要求换密钥：
@@ -70,27 +96,9 @@ SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
 
 **安全规则**：
 - 完整 apiKey 只写共享 state 文件；聊天里最多显示前缀（如 `sk_sdd_****`）。
-- 401/403 → 清掉 apiKey 请用户重贴，勿循环重试。
+- 401：停止本次远程操作，提示验证密钥；403：说明 scope/目标访问权不足。两者均**不**自动清空可能对其他目标仍有效的密钥，不循环重试。
 - **不要** `POST /auth/login`。
 
-### 2.5. 监控项目绑定（`projectName`，可留空）
-
-实时监控按"用户 / 项目"维度展示 Run：上传事件时服务端会根据 API 密钥解析上传用户，并按此处绑定的项目名称写入投影（服务端校验该用户必须是项目成员，否则项目留空、不阻断上传）。
-
-1. 询问用户项目名称；**留空** → 写 `projectName: null`（不绑定），跳到 Step 3。
-2. 非空 → 用共享库做成员预校验（Bearer = 当前 apiKey）：
-   ```js
-   // 临时 .cjs 脚本（遵循本文件头部跨平台规则）：
-   const shared = require('<SPEC_ROOT>/skywalk-sdd/lib/shared.cjs');
-   const r = await shared.verifyProjectMembershipViaServer(SPEC_ROOT, '<项目名称>');
-   ```
-   - `member === true` → `shared.setKbProjectName(SPEC_ROOT, '<项目名称>')` 写入，提示绑定生效。
-   - `member === false` → 提示"绑定不会生效，上传记录的项目将留空"，让用户选择**重填**或**留空**（`setKbProjectName(SPEC_ROOT, null)`）；不要直接保存非成员名称。
-   - `ok === false`（`reason: 'endpoint_unavailable'`，服务端未上线该端点或不可达）→ 软警告"平台暂不支持项目成员校验，绑定将在上传时由服务端裁决"，允许用户选择保存或留空。
-3. 换密钥后原 `projectName` 可能对新密钥用户失效 → 换密钥流程完成后重走本步校验。
-
-> 写入位置：`kb-state.json` 的 `projectName` 键（与 api/apiKey 同文件，已 gitignore）。同步代理每次上报批次时重读该配置，改绑/解绑后新事件即按新配置上报，无需重启或迁移。
-
 ### 3. 选择空间与知识库（支持多选）
 
 若 `state.targets` 为空，或用户要求重新选择：
@@ -103,11 +111,11 @@ SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
 > **API 返回字段说明**（临时脚本中注意字段名）：
 > - Space 列表返回 `spaceId`（camelCase），不是 `id`。临时脚本中使用 `s.spaceId || s.id` 兼容。
 > - Space 列表返回 `spaceKey`（项目标识，非 UUID），用于 `project-identity.json` 的 `project_id`。
-> - KB 列表返回 `kbId`（camelCase），不是 `id`。
+> - KB 列表返回 **`knowledgeBaseId` + `name`**，不是 `kbId`/`kbName`；需映射后写入 state。详见 [reference.md](reference.md#响应字段映射重要)。
 
 ### 4. 写入项目身份文件（首次配置 Space 后必做）
 
-> `project-identity.json` 是 spec 仓 Git 中的**团队共享**文件，记录 `project_id`（= KB Space 的 `spaceKey`）。Archive 阶段 `archive-docs` 读取此文件生成 `archive-manifest.json`，kb-ingest / kb-upload 上传时 KB 校验 `project_id === spaceKey`。
+> `project-identity.json` 是 spec 仓 Git 中的**团队共享**文件，记录 `project_id`（= **该 spec 仓所属项目** Space 的 `spaceKey`）。Archive 阶段 `archive-docs` 读取此文件生成 `archive-manifest.json`，kb-ingest / kb-upload 上传时 KB 校验 `project_id === spaceKey`。
 
 选择 Space 完成后（Step 3 写入 `targets` 后），执行以下逻辑：
 
@@ -116,70 +124,83 @@ SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
    SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
    ```
 2. 检查 `$SPEC_ROOT/skywalk-sdd/project-identity.json` 是否已存在
-3. **不存在** → 创建（取 `targets[0].spaceKey` 作为 `project_id`）：
+3. **不存在** → 用 AskUserQuestion 询问「**哪个 Space 拥有此 spec 仓**」。
+   **不得用 `targets` 列表顺序推断** —— 多个查询目标可能属于不同 Space，
+   拥有此 spec 仓的项目未必是第一个。用户指认后创建：
    ```json
    {
      "schema_version": "kld-sdd-project-identity/v1",
-     "project_id": "<targets[0].spaceKey>",
+     "project_id": "<用户指认 Space 的 spaceKey>",
      "created_at": "<ISO timestamp>",
-     "kb_space_id": "<targets[0].spaceId>",
-     "kb_space_name": "<targets[0].spaceName>"
+     "kb_space_id": "<该 Space spaceId>",
+     "kb_space_name": "<该 Space spaceName>"
    }
    ```
    输出：`✓ 已创建 skywalk-sdd/project-identity.json（project_id: <spaceKey>），请提交到 spec 仓 Git 以便团队共享`
-4. **已存在但 `project_id` 与 `targets[0].spaceKey` 不一致** → 用 AskUserQuestion 询问：
-   > "project-identity.json 中的 project_id 与当前选择的 KB Space spaceKey 不一致：
-   > - 文件中：`<existing project_id>`
-   > - 当前 Space：`<spaceKey>`
-   > 是否更新？"
-   - 用户确认 → 更新 `project_id` + `kb_space_id` + `kb_space_name`
-   - 用户拒绝 → 保留原值（可能入库时报 `PROJECT_SPACE_MISMATCH`）
-5. **已存在且一致** → 跳过，不输出
+4. **已存在且与用户本次指认的 Space 一致** → 保留，不输出
+5. **已存在但用户本次指认了不同 Space** → 该 Space 仅作为**只读查询目标**，
+   **不改写 `project_id`**。切换查询连接不是改写团队身份的理由；
+   若用户确实要把已有事实/历史包迁移到其他 Space/KB，属于另一个明确任务 ——
+   不能仅改 project_id、manifest 或 targets 冒充迁移完成
+
+### 5. 校验配置（保存后执行）
 
-> state.json 字段 schema、鉴权细节、列表接口 → [reference.md](reference.md)。
+1. `targets` 可保存多个连接目标。单个目标可直接使用；多个目标时，按用户本次指定的
+   Space/KB 选择，查询、同步和上传同时传 `--space-id`、`--kb-id`。缺少明确选择时询问本次
+   目标，**不默选首项，不自动广播**。跨目标查询逐个执行并保留来源。
+2. 对本次目标运行 `context-client.cjs --check-only`，说明可达性、权限与检索通道状态。
+   断连仍允许本地编写、测试和归档，远程基线核对与正式发布保持未完成。
 
-## 更换知识库
+可用目标只有一个且信息完整时，不添加确认步骤。多目标选择可沿用本轮用户已明确的选择；不用额外持久化一套“默认目标”状态。
 
-当用户说「换知识库 / 换 Space / 重新选择」时：
+## 团队项目身份
 
-1. **保留 apiKey**（不需要重新输入密钥）
-2. 清空 `state.targets`
-3. 重走 Step 3（选择空间与知识库）
-4. 重走 Step 4（更新 project-identity.json）
+`skywalk-sdd/project-identity.json` 随 spec 仓提交 Git，`project_id` 必须等于**该 spec 仓所属项目** Space 的 `spaceKey`。
 
-> ⚠️ 更换 Space 后，`project_id` 会随之变化。之前上传到旧 Space 的归档包不受影响，但新上传将写入新 Space。
+- 文件不存在：为用户已选定的业务项目创建身份。多个查询目标属于不同 Space 时，先明确哪个项目拥有此 spec 仓；不能用目标列表顺序推断。
+- 文件存在且项目一致：保留。
+- 文件存在但选择了不同项目：可以作为只读查询目标，**不能因为切换查询连接就改写团队身份**。已有事实/历史包迁移到其他 Space/KB 属于另一个明确任务，不能仅改 project_id、manifest 或 targets 冒充迁移完成。
+- 一个 Space 下的多个 KB 也分别选择。既有实体身份不能靠原包复制到另一 KB；跨库复用需确认事实归属并按正常流程建立目标身份。
+
+创建字段与 API 映射见 [reference.md](reference.md)。机器身份保留完整 UUID；人阅读使用锚点与业务名称，不能截短远程返回的实体或版本 ID。
+
+## 更换配置与失败处理
+
+- 换密钥：只替换密钥并验证当前目标权限，保留 targets 与团队身份。
+- 换 Space/KB：更新用户指定的连接目标，再核对查询权或入库项目一致性；不清空所有已有连接或自动改写身份。
+- 401：停止本次远程操作，提示验证密钥；403：说明 scope/目标访问权不足。两者均不自动清除可能仍对其他目标有效的密钥，不循环重试。
+- 网络不可用：保留配置，报告原因；可选查询失败不阻止本地流程。不能把不可用报告成“没有事实”或“已完成入库”。
+- 当前七种 Skill 使用统计按本机 Git 身份上报，独立于 Spec 入库。本配置流程无需填写监控项目或访问旧 `/sdd-runs/dimensions`。历史 `projectName` 字段可保留兼容，不作为当前使用统计或业务归属依据。
 
 ## 查看当前配置
 
-读取 `kb-state.json` 并展示：
+读取 `kb-state.json` 与 `project-identity.json` 并展示：
 
 ```markdown
 ### 当前 KB 配置
 - API 地址：{api}
 - 租户：{tenantKey}
 - API Key：{前缀}****（已配置 / 未配置）
-- 项目绑定：{projectName 或 未绑定}
 - 目标 Space/KB：
   1. {spaceName}（spaceKey: {spaceKey}）→ {kbName}
   2. ...
 - project-identity.json：{已存在 / 不存在}（project_id: {值}）
+- 授权/就绪：{context-client.cjs --check-only 结果}
 ```
 
-## 用户口令
+密钥仅显示“已配置”或脱敏前缀。
+
+## 文件与跨平台执行
 
-| 用户说 | Agent 做 |
-|--------|----------|
-| 配置知识库 / 首次使用 | 走完 Step 1→2→2.5→3→4 |
-| 换密钥 / 重置 API Key | 清 apiKey，重走 Step 2，再重走 Step 2.5 校验项目绑定 |
-| 换项目 / 重新绑定项目 / 解绑项目 | 重走 Step 2.5（保留 apiKey 与 targets） |
-| 换空间 / 换知识库 / 重新选择 | 清 targets，重走 Step 3→4 |
-| 看配置 / 当前配置 | 读取 kb-state.json + project-identity.json 并展示 |
-| 校验配置 | 探活 + 校验 project_id === spaceKey |
+- **位置唯一**：`kb-state.json` 只写 `<spec-root>/kb-state.json`（Step 1.1 校验通过后）。
+  禁止写 `.shared/`、`<ide>/skills/` 或任何非 spec 根位置。
+- `kb-state.json` 不提交 Git，校验 `.gitignore`；项目身份文件提交 Git。
+- 通过客户端文件工具或 Node.js 写 UTF-8 JSON，无 BOM，并原子替换；勿用 PowerShell 默认编码直接覆盖。
+- PowerShell 的 `curl` 可能是别名，HTTP 用 `Invoke-RestMethod` 或 Node.js；复杂 Node 逻辑写临时 `.cjs` 文件，避免 shell 内联转义。
 
 ## 硬规则
 
-- 无 `apiKey` 不得猜密钥、不得改走 login。
-- 无 `targets` 不得臆造 spaceId/kbId。
+- 无 `apiKey` 不得猜密钥、不得改走 login；不调用 `/auth/login` 换取另一身份。
+- 无 `targets` 不得臆造 spaceId/kbId；不猜目标 ID。
 - 完整 apiKey 只写共享 state 文件（`kb-state.json`，spec 仓根目录）；聊天里最多显示前缀。
-- 401/403 时清掉 `apiKey`，请用户重贴；勿循环重试。
 - **共享状态**：state 文件与 `opsx-ontology-query`、`opsx-kb-ingest`、`kb-upload` 共用。配置一次，全部生效。

package/templates/skills/kld-sdd/opsx-kb-config/reference.md

@@ -11,7 +11,7 @@
   "api": "http://10.29.213.80:8080/api",
   "tenantKey": "default",
   "apiKey": "sk_sdd_…",
-  "projectName": "支付网关重构",
+  "projectName": null,
   "updatedAt": "2026-07-19T12:00:00Z",
   "targets": [
     {
@@ -30,17 +30,14 @@
 | `api` | 是 | API 根，含 `/api` |
 | `tenantKey` | 是 | 列空间用；默认 `default` |
 | `apiKey` | 是 | 控制台创建的 `sk_sdd_…`，scope 建议 `context:read` + `archive:ingest` |
-| `projectName` | 否 | 监控项目绑定名；`null`/缺失/空白 = 未绑定，上传批次不携带 `project_name` |
+| `projectName` | 否 | 历史兼容字段；当前配置流程不要求填写，不作为七种 Skill 使用统计或业务归属依据 |
 | `scopes` | 建议 | API Client scope 列表 |
 | `targets` | 操作前必填 | 多选；可为空仅当尚未完成选择 |
 | `updatedAt` | 建议 | ISO-8601 |
 
-## 监控项目绑定与上传
+## 监控与入库分别验证
 
-- 配置期预校验：`GET {api}/v1/sdd-runs/dimensions`（Bearer），返回当前密钥用户可见的 `projects[]`；条目名称匹配即视为成员。端点 404/不可达表示服务端尚未上线该能力 → 软警告后可保存，服务端在上传时做权威裁决（非成员项目置空、不阻断）。
-- 客户端辅助函数：`verifyProjectMembershipViaServer(specRoot, projectName)`（预校验，软返回）、`setKbProjectName(specRoot, projectName|null)`（原子写入/清除），均在 `skywalk-sdd/lib/shared.cjs`。
-- 上传行为：同步代理每次组 batch 时重读 `kb-state.json`；`projectName` 非空 → batch 请求体顶层附带可选 `project_name` 字段（`sdd-progress-batch-v1.schema.json`，1-128 字符）；未配置 → 请求体与历史版本完全一致。
-- 环境变量兜底：`ENGINEERING_KB_PROJECT_NAME`（kb-state 无 `projectName` 时生效）。
+当前使用统计由独立 usage reporter 发送本机 Git 用户信息与 Skill 使用事件。Spec 的上传结果由 archive job、当前版本与检索投影验证。`projectName` 的历史辅助函数仍可兼容旧集成，但当前配置流程不再调用旧进度批次或项目成员端点，也不声称填写该字段就会绑定现行使用统计。
 
 ## `project-identity.json`
 
@@ -73,7 +70,7 @@ Authorization: Bearer sk_sdd_…
 - **不要** `POST /auth/login`。
 - Key 在控制台「API 密钥」创建；创建时建议勾选 **读取上下文 / context:read** + **入库 / archive:ingest**（查询与入库都需要）。
 - 如需查看 API Client 当前 scopes，可调用 `GET {api}/v1/spaces/{spaceId}/api-clients/me`，响应字段：`data.name`、`data.scopes`（string[]）。
-- 401/403：清掉 state 里的 `apiKey`，请用户重贴；勿循环重试。
+- 401：提示验证密钥；403：核对 scope 和目标空间访问权。保留原配置，不自动清空可能对其他目标有效的密钥，不循环重试。
 
 探活与校验（PowerShell 用 `Invoke-RestMethod`，**禁止** `curl`）：
 
@@ -96,7 +93,7 @@ GET $API/v1/spaces?tenantKey=$TENANT_KEY
 GET $API/v1/spaces/{spaceId}/knowledge-bases
 ```
 
-API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多空间，便于多选。
+API Key 的可见范围以实际授权结果为准，可被限制到特定 Space；不能因为配置多个 targets 就认为已获得各目标权限。多个目标必须显式选择，完整目标通过 `--space-id` 与 `--kb-id` 一起传入。
 
 ### 响应字段映射（重要）
 
@@ -121,7 +118,7 @@ KB API 返回的 JSON 字段名（Java record 序列化）与 `kb-state.json`
 
 | API 响应字段 (`ResolveCandidate`) | `semantic-identity` 参数 | 注意 |
 |------|------|------|
-| `entityId` | `--entity-id` | KB 返回完整 UUID（36字符），`semantic-identity` 的 `id.cjs` 会自动归一化为 8-hex 短格式 |
-| `entityVersionId` | `--previous-version-id` | 同上，自动归一化 |
+| `entityId` | `--entity-id` | 保留 KB 返回的完整 UUID（通常带连字符共 36 字符）；不得截短 |
+| `entityVersionId` | `--previous-version-id` | 保留实际当前版本的完整 UUID；只有正文实际基于该版本时才作为前驱 |
 
 > ⚠️ **常见错误**：直接用 `k.kbId` / `k.kbName` 读取 KB API 响应 → 返回空值。正确写法：`k.knowledgeBaseId` / `k.name`，然后映射到 `kb-state.json` 的 `kbId` / `kbName`。