kld-sdd 2.6.4 → 2.6.6

package/lib/skills-bundle.js

@@ -19,6 +19,9 @@ const OPSX_SKILL_DIRS = [
   'opsx-explore',
   'opsx-knowledge',
   'opsx-rules',
+  // Engineering KB 依赖技能（随 init 部署；propose/spec/archive 硬依赖）
+  'opsx-ontology-query',
+  'opsx-kb-ingest',
 ];
 
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -97,6 +100,8 @@ const KUNLUN_SLASH_COMMANDS = [
   'test',
   'archive',
   'explore',
+  'ontology-query',
+  'kb-ingest',
 ];
 
 function transformKunlunSlashCommands(content) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.6.4",
+  "version": "2.6.6",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {

package/templates/skills/kld-sdd/opsx-apply/SKILL.md

@@ -211,6 +211,7 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 > 合理化预防表见 opsx-tdd-core/SKILL.md §7
 > REFACTOR 检查点见 opsx-tdd-rules/rules/refactor-checklist.md
 > 异常路径覆盖门禁见 opsx-tdd-rules/rules/exception-path-coverage.md
+> TDD 节奏校验（执行后校验）见 `./checklist.md` §5e.1
 
 **【S2.1 RED 测试质量标准】**（test-strategy=tdd 时强制）：
 
@@ -282,6 +283,7 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 - **⛔ 编译检查门禁**：每完成一个任务后必须运行编译检查，编译失败禁止标记已完成。
 - **⛔ 测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry。${HOOK_GATE_DESCRIPTION}
 - **⛔ 必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式同步。
+- **⛔ apply 结束前 checkbox 全量同步校验**：`stage_end` 前对比 telemetry `task_update` 记录数与 tasks.md `[x]` 数量，不一致则补齐（见 `./checklist.md` §5f.1）。
 - **⛔ task_update 后必须验证 checkbox 已更新**：执行 `check-task` 确认 tasks.md 对应行已变更；未更新则手动修改。
 - **⛔ TDD RED→GREEN 严格串行**：不适用同层并行派发；RED-N 确认失败后必须执行中断声明再进入 GREEN-N；GREEN 完成后必须通过 Scope 门禁再进入下一个 RED。
 - **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目用 `vcs_mode=no-git` 继续执行。
@@ -298,7 +300,7 @@ g. **继续下一个层级** — 重新检查 DAG，找出依赖已满足的下
 
 ## 渐进披露
 
-- Read `checklist.md` 仅在执行 apply 需要校验门禁/自检时 — 含 §1.2 Check 门禁检查点、§5d/§5e 编译/测试门禁自检、§6.0 单元测试真实执行自检、§6.1 worktree 收尾前置条件、Guardrails ⛔ 强制项勾选表。
+- Read `checklist.md` 仅在执行 apply 需要校验门禁/自检时 — 含 §1.2 Check 门禁检查点、§5d/§5e 编译/测试门禁自检、§5e.1 TDD 节奏校验、§5f.1 checkbox 全量同步校验、§6.0 单元测试真实执行自检、§6.1 worktree 收尾前置条件、Guardrails ⛔ 强制项勾选表。
 - Read `reference.md` 仅在需要参考详细模板时 — 含 📊 Telemetry 命令模板（start/end/task_update/ai_adoption_review/worktree_finish）、§1.5 worktree 全套策略（Step 0.1-3 + record-base + 多 cap 合并顺序）、§5c 子代理派发、§5.1 AI 产出快照、§6.0 单元测试、§6.1 worktree 收尾脚本。
 - `implementer-prompt.md` 为子代理派发提示模板（§5c 派发时组合 tasks/design/overview 上下文使用）。
 - `worktree-setup.md` 为 worktree 快速参考（§1.5 策略的精简版，与 reference.md §1.5 完整版并存：reference=完整策略，worktree-setup=快速参考）。

package/templates/skills/kld-sdd/opsx-apply/checklist.md

@@ -47,6 +47,11 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 > 不在此内联复制，以 opsx-tdd-core/checklist.md §A 为唯一真相源。
 > 额外补充：REFACTOR 任务还需执行 `opsx-tdd-rules/rules/refactor-checklist.md`（7 项重构检查点）。
 
+⛔ **TDD 节奏校验**（RED→GREEN 严格串行的执行后校验）：
+- [ ] 连续的 RED-N `task_update` 与 GREEN-N `task_update` 之间有可验证的执行间隔（建议 >60 秒），若时间戳差距过小视为批量执行信号
+- [ ] 每对 RED→GREEN 之间已执行 🔴 中断声明（`🔴 RED-N 确认失败，原因：XXX。现在进入 GREEN-N`）
+- [ ] 若同层有多个 RED→GREEN 对，确认是逐对完成而非一次性编写多个 RED 再一次性实现多个 GREEN
+
 ### §5e.2 RED 测试质量门禁（仅 test-strategy=tdd 时，RED 任务完成后强制检查）
 
 ⛔ 核心原则（引用 opsx-tdd-quality/SKILL.md §2）：Mock 边界，不 Mock 行为
@@ -79,6 +84,15 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] 记录任务级 Telemetry（`task_update`，`--task-id=<TASK-ID>` 必填，否则 E4 指标无法计算）；TDD 测试骨架任务须在 `--details-json` 带 `"task_kind":"test-skeleton"`（P3，避免红灯误判拉低 E4）
 - [ ] ⛔ **task_update 后必须验证 checkbox 已更新**：执行 `node skywalk-sdd/index.cjs check-task --project=. --change=<变更名称> --task-id=<TASK-ID>` 确认 tasks.md 中对应行已从 `- [ ]` 变为 `- [x]`；若未更新，手动修改 tasks.md 并报告
 
+### §5f.1 apply 结束前 checkbox 全量同步校验
+
+> ⛔ 在 `stage_end` telemetry 记录前必须执行此校验，防止任务状态滞后到 archive 阶段。
+
+- [ ] 对比 telemetry `task_update` 记录的已完成任务数与 tasks.md 中 `[x]` 数量，不一致则补齐
+- [ ] tasks.md 中所有 `- [ ]` / `- [x]` 与 `**状态**: [ ]` / `[x]` 两种格式已同步
+- [ ] 手动验证清单（如有）已勾选
+- [ ] 文档更新项（如有）已完成或显式标注推迟
+
 ---
 
 ## §6.0 单元测试真实执行自检（`test-strategy` 非 `none`）
@@ -114,8 +128,10 @@ description: opsx-apply 的阶段强制检查点与自检清单。仅在执行 a
 - [ ] ⛔ **测试执行门禁**：根据 `test-strategy` 决定（tdd=强制, impl-first=强制补跑, none=跳过）；须真实执行并留 telemetry，`sdd-apply-test-gate` 校验非占位数据
 - [ ] ⛔ **RED 测试质量门禁**：见 §5e.2（引用 opsx-tdd-quality + opsx-tdd-anti-patterns，不在此内联复制）
 - [ ] ⛔ **必须实时更新任务状态**：每完成一个任务立即改 tasks.md，两种格式（`- [ ]`→`- [x]` 与 `**状态**: [ ]`→`[x]`）同步
+- [ ] ⛔ **apply 结束前 checkbox 全量同步校验**：见 §5f.1，`stage_end` 前对比 telemetry `task_update` 记录数与 tasks.md `[x]` 数量
 - [ ] ⛔ **task_update 后必须验证 checkbox 已更新**：执行 `check-task` 确认 tasks.md 对应行已变更；未更新则手动修改
 - [ ] ⛔ **TDD RED→GREEN 严格串行**：不适用同层并行派发；RED-N 确认失败后必须执行中断声明再进入 GREEN-N；GREEN 完成后必须通过 Scope 门禁再进入下一个 RED
+- [ ] ⛔ **TDD 节奏校验**：见 §5e.1，连续 RED-N/GREEN-N 的 `task_update` 时间戳须有可验证间距
 - [ ] **Git 只读策略**：禁止为了度量自动初始化 Git、创建分支或提交 commit；非 Git 项目用 `vcs_mode=no-git` 继续执行
 - [ ] ⛔ **Step 0.1 隔离校验必做**：建 worktree / 建议分支名前必须完成 proposal + 跨 cap spec 依赖校验并输出报告；未通过不得按 full 并行策略拆 `kld-sdd/<change>/<cap>`
 - [ ] **Worktree 为加速手段，非必选项**：校验通过且解耦方可多 worktree；有依赖或共享修改面则串行

package/templates/skills/kld-sdd/opsx-archive/SKILL.md

@@ -3,10 +3,11 @@ name: opsx-archive
 description: "归档变更技能 - 将已结束的 SDD 变更真实移入 archive，并生成最终中文度量报告"
 argument-hint: "[change-name]"
 license: MIT
-compatibility: Requires skywalk-sdd/log.cjs.
+compatibility: Requires skywalk-sdd/log.cjs; depends on opsx-kb-ingest for KB upload.
 metadata:
   author: sdd-team
   version: "3.2"
+  depends-on: opsx-kb-ingest
 allowed-tools:
   - Bash
   - Read
@@ -16,6 +17,8 @@ allowed-tools:
 
 你是一个 SDD（Specification-Driven Development）变更归档专家。激活本技能后，你要安全地结束变更生命周期：真实归档文档、同步正式 specs、记录 archive telemetry，并生成最终中文度量报告。
 
+> **硬依赖（收尾入库）**：zip 生成后的上传依赖同级已部署的 **`opsx-kb-ingest`**。进入 §5.5 前必须先 `Read` 该技能的 `SKILL.md` 并完成其 Session 启动。缺失则提示用户重新 `kld-sdd-init`，**不要**自造另一套入库协议。
+
 > **跨平台执行规则**
 > - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
@@ -117,7 +120,9 @@ node skywalk-sdd/log.cjs archive-docs --project=. --change=<变更名称> --reas
 
 ### 5.5 收尾入库（opsx-kb-ingest）
 
-归档 zip 生成后，提示用户用知识库技能 **`opsx-kb-ingest`** 上传；成功则写 `ingest-receipt.json`。若返回 `EXTERNAL_REF_CONFLICT`，引导回 spec/check 修正后重入，**禁止**在 KB 内现场改绑。
+1. 确认 `${AGENT_SKILL_DIR}/opsx-kb-ingest/SKILL.md` 存在并 Read；按该技能完成 API Key / targets。
+2. 归档 zip 生成后，**加载并执行** **`opsx-kb-ingest`** 上传（勿只口头提示而不走技能流程）；成功则写 `ingest-receipt.json`。
+3. 若返回 `EXTERNAL_REF_CONFLICT`，引导回 spec/check 修正后重入，**禁止**在 KB 内现场改绑。
 
 > 注意：`archive-docs` 成功执行后已经在内部写入 `stage_end`，因此**不要在成功的归档后再单独运行 `node skywalk-sdd/log.cjs end --command=archive ...`**。仅在第 5 步归档命令失败时，才需要运行下方的失败分支 `end`。
 

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

@@ -97,6 +97,10 @@ openspec list
 - [ ] spec.md 的需求项在 design.md 中 100% 被覆盖
 - [ ] design.md 的设计点在 tasks.md 中 100% 被拆解
 - [ ] 跨文档引用路径正确
+- [ ] ⛔ **CON 覆盖一致性**：spec.md 中每个 CON 在 tasks.md 中有对应验证任务或显式声明间接覆盖；tasks.md 声明"100% 覆盖 CON"时必须可追溯
+- [ ] ⛔ **安全/审计要求覆盖一致性**：spec.md §5.x 中的安全与审计要求在 tasks.md 中有对应任务或显式声明推迟
+- [ ] ⛔ **AC 变体覆盖一致性**：spec.md 中含"或"条件的 AC 场景，其 RED 任务验收标准须列出所有变体的测试方法（规则见 `opsx-tdd-rules/rules/multi-validation-split.md` §AC 内"或"条件变体覆盖）
+- [ ] ⛔ **tasks.md §4.x 验证方式表内部一致性**：§4.x 验证方式表中的测试注解/配置与任务实现步骤中的声明一致
 
 #### 4.3 算法正确性检查
 

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

@@ -36,6 +36,13 @@ description: "opsx-check 阶段日志自检清单 — 仅在 check 自检时读
 - [ ] 完整性、一致性、算法正确性、可执行性、TDD合规性（仅test-strategy=tdd时）五维均已输出
 - [ ] 报告问题对应修复建议（spec/design/task）
 
+## D2. 一致性补充检查（SKILL.md §4.2 扩展）
+
+- [ ] **CON 覆盖**：spec.md 中每个 CON 在 tasks.md 中有对应验证任务或显式声明间接覆盖
+- [ ] **安全/审计要求覆盖**：spec.md §5.x 中的安全与审计要求在 tasks.md 中有对应任务或显式声明推迟
+- [ ] **AC 变体覆盖**：spec.md 中含"或"条件的 AC 场景，其 RED 任务验收标准列出所有变体的测试方法（引用 `opsx-tdd-rules/rules/multi-validation-split.md`）
+- [ ] **§4.x 验证方式表内部一致性**：tasks.md §4.x 验证方式表中的测试注解/配置与任务实现步骤中的声明一致
+
 ## E. TDD 合规性检查（仅 test-strategy=tdd 时）
 
 ⛔ 执行 `opsx-tdd-core/checklist.md` §B（11 项）逐项检查。

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

@@ -0,0 +1,190 @@
+---
+name: opsx-kb-ingest
+description: >-
+  Uploads knowledge archive packages (zip) to the Engineering KB via API Key
+  (archive:ingest scope). Prompts for API key and multi-selects spaces/KBs into
+  local skill state. Supports upload, job status query, job list, and retry.
+  Use when ingesting new or updated knowledge archives into the ontology KB.
+argument-hint: "[path-to-archive.zip]"
+license: MIT
+compatibility: Requires Engineering KB API (API Key with archive:ingest).
+metadata:
+  author: sdd-team
+  version: "1.0"
+  source: "kb-sdd/skills/opsx-kb-ingest"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+# 本体知识库 · 入库
+
+> **部署说明**：本技能随 `kld-sdd-init` 安装到项目 skills 目录。权威源在工程知识库仓 `skills/opsx-kb-ingest`；`opsx-archive` **硬依赖**本技能完成收尾入库。
+
+只负责**入库**（zip 上传）。鉴权只用 **API Key**（`Authorization: Bearer sk_sdd_…`），**禁止**走手机号登录。
+
+> 控制台知识库页另有浮动 Ontology Agent（会话登录 + SSE）；本 Skill 仍走 API Key，二者分开。
+
+本地状态文件（含密钥，勿提交）：
+
+```text
+skills/opsx-kb-ingest/.local/state.json
+```
+
+字段说明 → [reference.md](reference.md)。
+
+## Session 启动（每次用本 Skill 必做）
+
+```
+Task Progress:
+- [ ] 1. 读 .local/state.json（没有则当空）
+- [ ] 2. 无 apiKey → 向用户索取并写入 state（勿把完整 key 打进聊天摘要）
+- [ ] 3. 无 targets 或用户要重置 → 拉空间/KB 列表，让用户多选后写入
+- [ ] 4. 按意图执行入库操作（上传 / 查状态 / 列表 / 重试）
+- [ ] 5. 按模板输出结果
+```
+
+### 1–2. API Key
+
+若 `state.apiKey` 为空或无效（401/403）：
+
+1. 请用户提供 API Key（控制台「API 密钥」创建，至少含 `archive:ingest`）。
+2. 可选：请用户确认 `api`（默认 `http://localhost:8090/api`）与 `tenantKey`（默认 `default`）。
+3. 写入 `.local/state.json`（创建目录若不存在）。
+4. 用 `GET $API/health` 探活；再用 `GET $API/v1/spaces?tenantKey=…` + Bearer 校验 key。
+
+用户说「换密钥 / 重置 API Key」→ 清空 `apiKey`（可保留 targets），回到本步。
+
+### 3. 选择空间与知识库（支持多选）
+
+若 `state.targets` 为空，或用户说「重新选择 / 重置空间 / 重置知识库」：
+
+1. `GET $API/v1/spaces?tenantKey=$TENANT_KEY`
+2. 对每个相关 space：`GET $API/v1/spaces/{spaceId}/knowledge-bases`
+3. 向用户展示「空间名 / spaceId → KB 名 / kbId」清单，**允许多选**。
+4. 写入 `targets: [{ spaceId, spaceName, spaceKey, kbId, kbName }, …]`。
+5. 仅清空 targets、保留 apiKey 即完成「重置空间和知识库」。
+
+入库时：用户指定目标 KB（从 `targets` 中选择），仅对选中的 KB 执行上传。
+
+### 4. 入库操作
+
+路径前缀：`/api/v1/spaces/{spaceId}/knowledge-bases/{kbId}/ingestions`
+所有请求：`-H "Authorization: Bearer $API_KEY"`
+
+| 意图 | 调用 |
+|------|------|
+| 上传 zip 包入库 | `POST …/ingestions`（multipart，字段名 `package`） |
+| 列出入库任务 | `GET …/ingestions` |
+| 查看任务状态 | `GET …/ingestions/{jobId}` |
+| 重试失败任务 | `POST …/ingestions/{jobId}/retry` |
+
+**上传入库**
+
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions" \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "package=@/path/to/your-archive.zip;type=application/zip"
+```
+
+**查看任务状态**
+
+```bash
+curl -sS -X GET "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JOB_ID" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+**列出入库任务**
+
+```bash
+curl -sS -X GET "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+**重试失败任务**
+
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JOB_ID/retry" \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+### Archive Package 要求
+
+上传的 zip 包必须满足以下条件（否则入库会失败）：
+
+- 包含三个必需 JSON 文件：`archive-manifest.json`、`canonical-facts.json`、`conversion-report.json`
+- `canonical-facts.json` 支持 `kld-sdd-canonical-facts/v1` 与 **`v2`**（v2 可选实体级 `external_refs`）
+- 所有文件需通过 SHA-256 校验（manifest 中记录每个文件的 `content_hash`）
+- 允许的文件类型：`.md`、`.json`、`.jsonl`、`.yaml`、`.yml`
+- 大小限制：包 ≤ 50MB，条目 ≤ 2000 个，单文件 ≤ 10MB，解压后 ≤ 200MB
+- `archive-manifest.json` 中的 `project_id` 必须与目标 Space 的 `spaceKey` 一致
+
+**v2 本地预检（skill 侧，上传前）**
+
+- `external_refs[]` 每项含 `system` / `object_type` / `external_id`
+- object_type 与实体类型匹配：`requirement`/`feature`→Capability；`scenario`→SpecificationStatement|AcceptanceCriterion
+- 包内无重复 `(external key, entity_id)` 绑定对
+- `project_id` / `spaceKey` 既有规则保留
+
+详细字段说明 → [reference.md](reference.md)。
+
+### 5. 输出模板
+
+```markdown
+### 入库结果
+- 目标 KB：{spaceName}/{kbName}
+- 操作：{上传 | 查状态 | 列表 | 重试}
+- 状态：{succeeded | failed | running | idempotent}
+- Job ID：{jobId}
+
+### 详情
+- archiveId：{archiveId}
+- contentHash：{contentHash}
+- stage：{stage}
+- relationStatus：{relationStatus}
+- projectionStatus：{projectionStatus}
+- 外部引用写入数：{externalRefsWritten 或 0}
+- 幂等命中：{是 / 否}
+- 错误信息：{errorCode — errorMessage 或 无}
+```
+
+成功时展示 `report.externalRefsWritten`。冲突**不**出现在成功模板。
+
+若 `errorCode=EXTERNAL_REF_CONFLICT`（整包已回滚）：
+
+1. 展示 `report.details`（externalRef / anchor / existingEntityId / incomingEntityId）。
+2. 向用户给出两个修正选项：
+   - **复用历史身份**：回到 kld-sdd，复用 KB 中原有 entity_id / current version，重新 check → 归档 → 入库
+   - **改为新锚点**：回到 kld-sdd，分配新锚点与新 entity_id，重新 check → 归档 → 入库
+3. **禁止**在 KB 内现场改绑或解绑。
+
+**硬规则**
+
+- 无 `apiKey` 不得猜密钥、不得改走 login。
+- 无 `targets` 不得臆造 spaceId/kbId。
+- 上传前确认 zip 包路径存在且为有效 zip 文件。
+- 入库失败时展示 `errorCode` 和 `errorMessage`，不编造原因。
+- 完整 apiKey 只写 state 文件；聊天里最多显示前缀（如 `sk_sdd_****`）。
+- 401/403 时清掉 `apiKey`，请用户重贴；勿循环重试。
+
+## 用户口令
+
+| 用户说 | Agent 做 |
+|--------|----------|
+| （首次使用） | 要 key → 选 KB（多选）→ 再操作 |
+| 换密钥 / 重置 API Key | 清 apiKey，重走第 2 步 |
+| 重新选择 / 重置空间或知识库 | 清 targets，重走第 3 步 |
+| 上传 / 入库 | 用当前 targets 中选中的 KB 上传 zip |
+| 查状态 / 看任务 | 用 jobId 查询任务状态 |
+| 列任务 / 看历史 | 列出最近入库任务 |
+| 重试 | 对失败的 jobId 执行重试 |
+
+## 心智模型（简述）
+
+- 入库是同步操作：上传后后端立即解析 zip、校验、写入数据库，返回最终 job 状态。
+- 幂等机制：同一 `archive_id` + `content_hash` 重复上传会命中幂等，不重复写入。
+- `archive_id` 不可变：同一 `archive_id` 上传不同 `content_hash` 会被拒绝（`ARCHIVE_IMMUTABILITY_VIOLATION`）。
+- `project_id` 必须匹配：zip 包 manifest 中的 `project_id` 必须等于目标 Space 的 `spaceKey`。
+- 细节与 state schema → [reference.md](reference.md)。

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

@@ -0,0 +1,196 @@
+# 本体入库 · 参考
+
+需要鉴权细节、state 字段或 Archive Package 规格时再读。
+
+## `.local/state.json`
+
+路径：`skills/opsx-kb-ingest/.local/state.json`（已 gitignore）。
+
+```json
+{
+  "api": "http://localhost:8090/api",
+  "tenantKey": "default",
+  "apiKey": "sk_sdd_…",
+  "updatedAt": "2026-07-19T12:00:00Z",
+  "targets": [
+    {
+      "spaceId": "uuid",
+      "spaceKey": "demo",
+      "spaceName": "演示空间",
+      "kbId": "uuid",
+      "kbName": "默认知识库"
+    }
+  ]
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `api` | 是 | API 根，含 `/api` |
+| `tenantKey` | 是 | 列空间用；默认 `default` |
+| `apiKey` | 是 | 控制台创建的 `sk_sdd_…`，scope 至少 `archive:ingest` |
+| `targets` | 操作前必填 | 多选；可为空仅当尚未完成选择 |
+| `updatedAt` | 建议 | ISO-8601 |
+
+示例（无密钥）见 [state.example.json](state.example.json)。
+
+## 鉴权
+
+```http
+Authorization: Bearer sk_sdd_…
+```
+
+- **不要** `POST /auth/login`。
+- Key 在控制台「API 密钥」创建；创建时勾选 **入库 / archive:ingest**（写入需要）。
+- 401/403：清掉 state 里的 `apiKey`，请用户重贴；勿循环重试。
+
+探活与校验：
+
+```bash
+curl -sf "$API/health"
+curl -sS -H "Authorization: Bearer $API_KEY" \
+  "$API/v1/spaces?tenantKey=$TENANT_KEY"
+```
+
+## 列表接口（选择用）
+
+```bash
+# 空间
+GET $API/v1/spaces?tenantKey=$TENANT_KEY
+
+# 某空间下 KB
+GET $API/v1/spaces/{spaceId}/knowledge-bases
+```
+
+API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多空间，便于多选。
+
+## 入库接口
+
+路径前缀：`/api/v1/spaces/{spaceId}/knowledge-bases/{kbId}/ingestions`
+
+### 上传 zip 包
+
+```bash
+POST {base}/ingestions
+Content-Type: multipart/form-data
+```
+
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions" \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "package=@/path/to/archive.zip;type=application/zip"
+```
+
+### 列出入库任务
+
+```bash
+GET {base}/ingestions
+```
+
+返回最近 100 条入库任务，按 `created_at DESC` 排序。
+
+### 查看任务状态
+
+```bash
+GET {base}/ingestions/{jobId}
+```
+
+### 重试失败任务
+
+```bash
+POST {base}/ingestions/{jobId}/retry
+```
+
+仅 `status=failed` 的任务可重试；后端会重新解析原始上传的 zip 包。
+
+## IngestionJobDto 响应字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `jobId` | UUID | 任务 ID |
+| `spaceId` | UUID | 空间 ID |
+| `archiveId` | String | 归档 ID（来自 manifest） |
+| `contentHash` | String | 内容哈希 `sha256:…` |
+| `packageName` | String | 上传的文件名 |
+| `packageHash` | String | 包哈希 `sha256:…` |
+| `status` | String | `running` / `succeeded` / `failed` |
+| `stage` | String | `validating` / `canonical-store` / `committed` / `failed` |
+| `idempotentHit` | boolean | 是否命中幂等（同 archive_id + content_hash） |
+| `relationStatus` | String | `pending` / `committed` / `rolled_back` / `not_required` |
+| `projectionStatus` | String | `pending` / `not_started` / … |
+| `errorCode` | String | 失败错误码（见下表） |
+| `errorMessage` | String | 失败错误描述 |
+| `report` | JsonNode | 入库报告（成功含 `externalRefsWritten`；冲突失败含 `details`） |
+| `attempts` | int | 尝试次数 |
+| `createdBy` | String | 创建者标识 |
+| `createdAt` | Instant | 创建时间 |
+| `updatedAt` | Instant | 更新时间 |
+| `finishedAt` | Instant | 完成时间 |
+
+## 常见错误码
+
+| errorCode | 含义 |
+|-----------|------|
+| `INGEST_FAILED` | 通用入库失败 |
+| `PROJECT_SPACE_MISMATCH` | manifest 中 project_id 与目标 Space spaceKey 不一致 |
+| `ARCHIVE_IMMUTABILITY_VIOLATION` | 同一 archive_id 已存在不同 content_hash |
+| `MANIFEST_MISSING` | 缺少必需的 manifest 文件 |
+| `INVALID_FILE_TYPE` | 包含不允许的文件类型 |
+| `SIZE_LIMIT_EXCEEDED` | 超过包/文件/条目大小限制 |
+| `HASH_MISMATCH` | 文件 SHA-256 校验不通过 |
+| `EXTERNAL_REF_CONFLICT` | 同外部键+同锚点已绑不同 entity_id；整包回滚；见 `report.details` |
+| `EXTERNAL_REFERENCE_TYPE_MISMATCH` | 包内 object_type 与实体类型不匹配 |
+| `EXTERNAL_REFERENCE_DUPLICATE_IN_PACKAGE` | 包内重复 `(external key, entity_id)` |
+| `FACTS_SCHEMA_UNSUPPORTED` | canonical-facts schema 非 v1/v2 |
+
+### `EXTERNAL_REF_CONFLICT` 的 report.details
+
+```json
+{
+  "externalRef": { "system": "requirement-mgmt", "objectType": "requirement", "externalId": "REQ-…" },
+  "anchor": "CAP-ORDER-CANCEL",
+  "existingEntityId": "<uuid>",
+  "existingCurrentVersionId": "<uuid>",
+  "incomingEntityId": "<uuid>",
+  "remediation": ["reuse-existing-identity", "assign-new-anchor"]
+}
+```
+
+修正必须回到 kld-sdd（复用历史身份或换新锚点），重新 check → 归档 → 入库；禁止在 KB 改绑。
+
+## Archive Package 规格
+
+### 必需文件
+
+| 文件 | 说明 |
+|------|------|
+| `archive-manifest.json` | 归档清单，含 archive_id、project_id、content_hash、files 列表 |
+| `canonical-facts.json` | 规范化事实：`kld-sdd-canonical-facts/v1` 或 **`v2`**（v2 可选实体级 `external_refs`） |
+| `conversion-report.json` | 转换报告（`target_schema` 可为 v1 或 v2） |
+
+### 文件类型白名单
+
+`.md`、`.json`、`.jsonl`、`.yaml`、`.yml`
+
+### 大小限制
+
+| 限制项 | 默认值 |
+|--------|--------|
+| 包大小 | 50 MB |
+| 条目数 | 2000 |
+| 单文件大小 | 10 MB |
+| 解压后总大小 | 200 MB |
+
+### manifest 关键字段
+
+```json
+{
+  "archive_id": "2026-07-18-user-center",
+  "project_id": "<必须与目标 Space spaceKey 一致>",
+  "content_hash": "sha256:<canonical-facts.json 的哈希>",
+  "files": [
+    { "path": "canonical-facts.json", "content_hash": "sha256:…" },
+    { "path": "conversion-report.json", "content_hash": "sha256:…" }
+  ]
+}
+```

package/templates/skills/kld-sdd/opsx-kb-ingest/state.example.json

@@ -0,0 +1,7 @@
+{
+  "api": "http://localhost:8090/api",
+  "tenantKey": "default",
+  "apiKey": "",
+  "updatedAt": "",
+  "targets": []
+}

package/templates/skills/kld-sdd/opsx-ontology-query/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: opsx-ontology-query
+description: >-
+  Queries the Engineering KB ontology via API Key (context search, match-requirement,
+  entity/impact/ontology-view). Prompts for API key and multi-selects spaces/KBs into
+  local skill state. Use when looking up Spec/design facts, Spec reuse, impact, or
+  citation-backed answers from the ontology KB.
+argument-hint: "[query or continuity intent]"
+license: MIT
+compatibility: Requires Engineering KB API (API Key with context:read).
+metadata:
+  author: sdd-team
+  version: "1.0"
+  source: "kb-sdd/skills/opsx-ontology-query"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+# 本体知识库 · 查询
+
+> **部署说明**：本技能随 `kld-sdd-init` 安装到项目 skills 目录。权威源在工程知识库仓 `skills/opsx-ontology-query`；`opsx-propose` / `opsx-spec` 等流程技能**硬依赖**本技能，缺失时不得用本地 archive 兜底。
+
+只负责**查**。鉴权只用 **API Key**（`Authorization: Bearer sk_sdd_…`），**禁止**走手机号登录。
+
+> 控制台知识库页另有浮动 Ontology Agent（会话登录 + SSE）；本 Skill 仍走 API Key，二者分开。
+>
+> **Agent 角色（V1）**：控制台 Agent 是 **单一 ReActAgent + 角色人格切换**（架构师 / 业务分析师 / 数据分析师），
+> 不是三个独立 JVM agent。共享工具集，仅 sysPrompt 与工具偏好不同——Studio 仍单 run、延迟更低，后续需要再拆。
+> 交互硬规则：自然语言优先，不向用户索要 UUID；多实体时用 `ask_user` Generative UI 卡片（`type=choice`，options.label=名称）。
+>
+> **Skills 激活**：控制台 Agent 通过 AgentScope `FileSystemSkillRepository`（`skillsRoot`，见
+> `classpath:agent/agent.yml`）挂载本目录；运行时用内置工具 `load_skill_through_path`
+> （skillId=`opsx-ontology-query`，path=`SKILL.md` / `reference.md`）按需加载，不把全文塞进 system prompt。
+>
+> **记忆**：会话短期用 AgentScope `InMemoryAgentStateStore`；本体事实仍走 KB（pgvector/SQL）。
+> **不需要 mem0**，除非以后要跨会话个人偏好记忆。
+
+本地状态文件（含密钥，勿提交）：
+
+```text
+skills/opsx-ontology-query/.local/state.json
+```
+
+字段说明 → [reference.md](reference.md)。
+
+## Session 启动（每次用本 Skill 必做）
+
+```
+Task Progress:
+- [ ] 1. 读 .local/state.json（没有则当空）
+- [ ] 2. 无 apiKey → 向用户索取并写入 state（勿把完整 key 打进聊天摘要）
+- [ ] 3. 无 targets 或用户要重置 → 拉空间/KB 列表，让用户多选后写入
+- [ ] 4. 按意图查询（可对多个 KB 逐个查询）
+- [ ] 5. 按模板输出；无命中不编造
+```
+
+### 1–2. API Key
+
+若 `state.apiKey` 为空或无效（401/403）：
+
+1. 请用户提供 API Key（控制台「API 密钥」创建，至少含 `context:read`）。
+2. 可选：请用户确认 `api`（默认 `http://localhost:8090/api`）与 `tenantKey`（默认 `default`）。
+3. 写入 `.local/state.json`（创建目录若不存在）。
+4. 用 `GET $API/health` 探活；再用 `GET $API/v1/spaces?tenantKey=…` + Bearer 校验 key。
+
+用户说「换密钥 / 重置 API Key」→ 清空 `apiKey`（可保留 targets），回到本步。
+
+### 3. 选择空间与知识库（支持多选）
+
+若 `state.targets` 为空，或用户说「重新选择 / 重置空间 / 重置知识库」：
+
+1. `GET $API/v1/spaces?tenantKey=$TENANT_KEY`
+2. 对每个相关 space：`GET $API/v1/spaces/{spaceId}/knowledge-bases`
+3. 向用户展示「空间名 / spaceId → KB 名 / kbId」清单，**允许多选**。
+4. 写入 `targets: [{ spaceId, spaceName, spaceKey, kbId, kbName }, …]`。
+5. 仅清空 targets、保留 apiKey 即完成「重置空间和知识库」。
+
+查询时：对 `targets` **逐个**调用同一查询，结果按 KB 分组展示。用户若指定「只用某某 KB」，则仅查对应子集。
+
+### 4. 查询
+
+路径前缀：`/api/v1/spaces/{spaceId}/knowledge-bases/{kbId}`  
+所有请求：`-H "Authorization: Bearer $API_KEY"`
+
+| 意图 | 调用 |
+|------|------|
+| 开放问题 / 相似事实 | `POST …/context/search` |
+| Continuity / 按外部需求号定位身份 | `POST …/entities/resolve`（带 `externalSystem` / `externalObjectType` / `externalId`；可选 `entityType`） |
+| Spec 复用 / 转换 | `POST …/context/match-requirement`（可带外部三元组与/或 `entityId`） |
+| 对象详情 | `GET …/entities/{id}/current-version` |
+| 一跳结构 | `GET …/entities/{id}/ontology-view` |
+| 多跳影响 | `GET …/entities/{id}/impact` |
+| 原文 | `POST …/context/disclosures`（见 reference） |
+
+**机器意图（SDD 流程 Agent）**
+
+- Continuity（只要身份、不要 reuseBundles）→ 优先 `POST …/entities/resolve`
+- Spec 复用 → `POST …/context/match-requirement`，带 external 与/或 `entityId`
+- **禁止**扫描消费方本地 `archive/` 目录当跨迭代继承源；历史有效规格以 KB current 为准
+
+**search**
+
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/context/search" \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{"query":"用户登录与会话","entityTypes":[],"limit":15}'
+```
+
+**entities/resolve（外部需求号）**
+
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/resolve" \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{
+    "externalSystem":"requirement-mgmt",
+    "externalObjectType":"requirement",
+    "externalId":"REQ-FI-2024-001",
+    "entityType":"Capability"
+  }'
+```
+
+命中时关注：`resolution=LINK_EXISTING` 且 `inheritanceAllowed=true`（可继承 n）；`removedBindingCount`（已失效绑定 m）；`matchType=HISTORICAL_ONLY` 表示仅有失效绑定，不可继承。
+
+**match-requirement**
+
+```bash
+curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/context/match-requirement" \
+  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  -d '{
+    "query":"用户登录与会话",
+    "targetStage":"spec",
+    "entityId":"<capability-entity-uuid>",
+    "externalSystem":"requirement-mgmt",
+    "externalObjectType":"requirement",
+    "externalId":"REQ-FI-2024-001"
+  }'
+```
+
+检索通道：精确/结构 + 全文 + 向量（就绪时）→ RRF →（可选）图谱扩展。看 `degraded` / `degradationReasons`。
+
+### 5. 输出模板
+
+```markdown
+### 本体查询结论
+- 目标 KB：{spaceName}/{kbName}（可多行）
+- 意图：{复用 | 事实检索 | 影响}
+- 可信度：{高 | 中（降级） | 无命中}
+- 降级：{reasons 或 无}
+
+### 命中
+1. **{displayName}**（{entityType}）@ {kbName}
+   - id / version / matchType / externalRefs …
+   - 若外部键命中：可继承 n / 已失效绑定 m
+```
+
+**硬规则**
+
+- 无 `apiKey` 不得猜密钥、不得改走 login。
+- 无 `targets` 不得臆造 spaceId/kbId。
+- 无命中 → 写明「无当前依据」，禁止编造条款。
+- 完整 apiKey 只写 state 文件；聊天里最多显示前缀（如 `sk_sdd_****`）。
+
+## 用户口令
+
+| 用户说 | Agent 做 |
+|--------|----------|
+| （首次使用） | 要 key → 选 KB（多选）→ 再查 |
+| 换密钥 / 重置 API Key | 清 apiKey，重走第 2 步 |
+| 重新选择 / 重置空间或知识库 | 清 targets，重走第 3 步 |
+| 查 / Spec 复用 / 影响… | 用当前 targets 查询 |
+
+## 心智模型（简述）
+
+- 本体真相在 PG（entity + relation）；控制台地图/对象用 SQL 遍历。
+- **外部需求号是确定性身份**；自然语言只产生 REFERENCE 候选，不能自动 sameAs。
+- `context/search` 才是语义检索主通道（+ 可选 AGE 扩邻）；跨迭代 Continuity 走 `entities/resolve`。
+- 细节与 state schema → [reference.md](reference.md)。

package/templates/skills/kld-sdd/opsx-ontology-query/reference.md

@@ -0,0 +1,157 @@
+# 本体查询 · 参考
+
+需要鉴权细节、state 字段或响应字段时再读。
+
+## `.local/state.json`
+
+路径：`skills/opsx-ontology-query/.local/state.json`（已 gitignore）。
+
+```json
+{
+  "api": "http://localhost:8090/api",
+  "tenantKey": "default",
+  "apiKey": "sk_sdd_…",
+  "updatedAt": "2026-07-19T12:00:00Z",
+  "targets": [
+    {
+      "spaceId": "uuid",
+      "spaceKey": "demo",
+      "spaceName": "演示空间",
+      "kbId": "uuid",
+      "kbName": "默认知识库"
+    }
+  ]
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `api` | 是 | API 根，含 `/api` |
+| `tenantKey` | 是 | 列空间用；默认 `default` |
+| `apiKey` | 是 | 控制台创建的 `sk_sdd_…`，scope 至少 `context:read` |
+| `targets` | 查询前必填 | 多选；可为空仅当尚未完成选择 |
+| `updatedAt` | 建议 | ISO-8601 |
+
+示例（无密钥）见 [state.example.json](state.example.json)。
+
+## 鉴权
+
+```http
+Authorization: Bearer sk_sdd_…
+```
+
+- **不要** `POST /auth/login`。
+- Key 在控制台「API 密钥」创建；创建时勾选 **读取上下文 / context:read**（查询够用）。
+- 401/403：清掉 state 里的 `apiKey`，请用户重贴；勿循环重试。
+
+探活与校验：
+
+```bash
+curl -sf "$API/health"
+curl -sS -H "Authorization: Bearer $API_KEY" \
+  "$API/v1/spaces?tenantKey=$TENANT_KEY"
+```
+
+## 列表接口（选择用）
+
+```bash
+# 空间
+GET $API/v1/spaces?tenantKey=$TENANT_KEY
+
+# 某空间下 KB
+GET $API/v1/spaces/{spaceId}/knowledge-bases
+```
+
+API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多空间，便于多选。
+
+## context/search
+
+`POST {base}/context/search`
+
+```json
+{ "query": "string", "entityTypes": [], "limit": 15 }
+```
+
+| 字段 | 含义 |
+|------|------|
+| `degraded` / `degradationReasons` | 向量/AGE/rerank 等降级 |
+| `results[].matchType` | exact / structural / fulltext / vector / graph … |
+| `results[].entityId` / `entityVersionId` | 溯源 |
+| `results[].scoreExplanation` | RRF channel ranks 等 |
+
+## entities/resolve（Continuity / 外部需求号）
+
+`POST {base}/entities/resolve`
+
+```json
+{
+  "externalSystem": "requirement-mgmt",
+  "externalObjectType": "requirement",
+  "externalId": "REQ-FI-2024-001",
+  "entityType": "Capability"
+}
+```
+
+也可传 `entityId` / `previousVersionId` / `canonicalKey` / `query`。
+
+| 结果 | 含义 |
+|------|------|
+| `resolution=LINK_EXISTING` + `inheritanceAllowed=true` | ≥1 可继承绑定；`candidates` 仅存活实体；`removedBindingCount` 为失效绑定数 |
+| `matchType=HISTORICAL_ONLY` | 有绑定但全部无 current / removed；`inheritanceAllowed=false`，不得当迭代继承 |
+| `NEEDS_CONFIRM` / `SIMILAR_REQUIREMENT` | 名称/结构相似，仅候选 |
+| `NEW_REQUIREMENT` | 无命中 |
+
+**禁止**用本地 `archive/` 目录当跨迭代继承源。
+
+## context/match-requirement
+
+`POST {base}/context/match-requirement`
+
+```json
+{
+  "query": "string",
+  "targetStage": "spec",
+  "limit": 20,
+  "entityId": "<uuid>",
+  "externalSystem": "requirement-mgmt",
+  "externalObjectType": "requirement",
+  "externalId": "REQ-…"
+}
+```
+
+`entityId` / `previousVersionId` / 外部三元组齐全时走 resolve；仅当可继承（非 `HISTORICAL_ONLY`）时组装 `reuseMode=INHERIT` bundles。实体与 statement/AC 上可带 `externalRefs`。
+
+| matchType | 含义 |
+|-----------|------|
+| `SAME_ITERATION` | 已对齐同一实体 |
+| `HISTORICAL_ONLY` | 外部键仅有失效绑定，不可继承 |
+| `SIMILAR_REQUIREMENT` | 可作复用候选 |
+| `NEEDS_CONFIRM` | 需人确认 |
+| `NEW_REQUIREMENT` | 无可信复用 |
+
+## 对象读
+
+| 方法 | 路径 |
+|------|------|
+| GET | `/entities?type=&q=&page=&size=` |
+| GET | `/entities/{id}/current-version` |
+| GET | `/entities/{id}/lineage` |
+| GET | `/entities/{id}/ontology-view` |
+| GET | `/entities/{id}/impact` |
+
+`impact` / `ontology-view` 走 PG 关系；与 `context/search` 不同链路。
+
+## disclosures
+
+`POST {base}/context/disclosures`
+
+```json
+{
+  "anchorId": "STMT-…",
+  "entityId": null,
+  "entityVersionId": null,
+  "level": "preview"
+}
+```
+
+`level`：`preview` | `section` | `document`。

package/templates/skills/kld-sdd/opsx-ontology-query/state.example.json

@@ -0,0 +1,7 @@
+{
+  "api": "http://localhost:8090/api",
+  "tenantKey": "default",
+  "apiKey": "",
+  "updatedAt": "",
+  "targets": []
+}

package/templates/skills/kld-sdd/opsx-propose/SKILL.md

@@ -3,10 +3,11 @@ name: opsx-propose
 description: "业务意图文档技能 - 引导创建 proposal.md，定义变更的 Why 和上下文总览"
 argument-hint: "[change-name] [上下文文件...]"
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires openspec CLI; depends on opsx-ontology-query.
 metadata:
   author: sdd-team
   version: "3.0"
+  depends-on: opsx-ontology-query
 allowed-tools:
   - Bash
   - Read
@@ -16,6 +17,8 @@ allowed-tools:
 
 你是一个 SDD（Specification-Driven Development）业务意图文档专家。激活本技能后，你将引导用户创建符合质量红线标准的 **proposal.md** 文档。
 
+> **硬依赖**：本技能 Continuity 步骤依赖同级已部署的 **`opsx-ontology-query`**。启动 Continuity 前必须先 `Read` 该技能的 `SKILL.md`，并按其中流程准备 `.local/state.json`（API Key + targets）。若项目 skills 目录中不存在 `opsx-ontology-query/`，停止 Continuity，提示用户重新执行 `kld-sdd-init`；**禁止**用本地 `archive/` 冒充查询。
+
 > **⚠️ 阶段边界约束**
 >
 > 当前处于 **Propose（规划）阶段**：
@@ -164,7 +167,8 @@ openspec instructions proposal --change "<name>" --json
 在创建变更目录之后、写 proposal 能力列表之前（或紧接 CAP 编号分配前）：
 
 1. 提取 / 询问外部需求号 `REQ-*`（没有则问一次）。
-2. 调用知识库 **`opsx-ontology-query`**（或薄封装）：
+2. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md`（或当前编辑器等价 skills 路径）存在并 Read；按该技能完成 API Key / 空间与 KB 选择（写入其 `.local/state.json`）。未安装则停止本步。
+3. 调用知识库 **`opsx-ontology-query`**（权威）；可用薄封装，但契约以该技能为准：
 ```bash
 node skywalk-sdd/context-client.cjs --mode=resolve \
   --external-system=requirement-mgmt \
@@ -174,11 +178,11 @@ node skywalk-sdd/context-client.cjs --mode=resolve \
   --space-id="$ENGINEERING_KB_SPACE_ID" \
   --kb-id="$ENGINEERING_KB_KB_ID"
 ```
-3. 按 KB 结果确认 Continuity：`iteration` / `similar-reference` / `new`；勾选本次涉及的 CAP。
-4. 写入 proposal frontmatter：`requirement-refs` + `continuity`（字段来自 KB：`kb-space-id` / `kb-id` / `base-capabilities[].entity-id` / `current-version-id`）。**禁止**写本地 archive 文件夹名作为 `base-archive`。
-5. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C；决议写入 `openspec/changes/<name>/continuity-resolution.json` 的 `capabilities[]`。
-6. KB 不可用 → `degraded` 继续，**禁止**扫本地 `archive/` 抄 UUID。预期：恢复后同锚点入库可能触发 `EXTERNAL_REF_CONFLICT`。
-7. **不得**在本阶段生成 STMT/AC/场景或裁决场景身份。
+4. 按 KB 结果确认 Continuity：`iteration` / `similar-reference` / `new`；勾选本次涉及的 CAP。
+5. 写入 proposal frontmatter：`requirement-refs` + `continuity`（字段来自 KB：`kb-space-id` / `kb-id` / `base-capabilities[].entity-id` / `current-version-id`）。**禁止**写本地 archive 文件夹名作为 `base-archive`。
+6. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C；决议写入 `openspec/changes/<name>/continuity-resolution.json` 的 `capabilities[]`。
+7. KB 不可用 → `degraded` 继续，**禁止**扫本地 `archive/` 抄 UUID。预期：恢复后同锚点入库可能触发 `EXTERNAL_REF_CONFLICT`。
+8. **不得**在本阶段生成 STMT/AC/场景或裁决场景身份。
 
 ### 7. 【交互引导】文档拆分模式选择
 

package/templates/skills/kld-sdd/opsx-spec/SKILL.md

@@ -3,10 +3,11 @@ name: opsx-spec
 description: "技术契约文档技能 - 为每个能力创建 spec.md，定义业务场景与技术规范"
 argument-hint: "[change-name] [上下文文件...]"
 license: MIT
-compatibility: Requires openspec CLI.
+compatibility: Requires openspec CLI; depends on opsx-ontology-query.
 metadata:
   author: sdd-team
   version: "3.0"
+  depends-on: opsx-ontology-query
 allowed-tools:
   - Bash
   - Read
@@ -16,6 +17,8 @@ allowed-tools:
 
 你是一个 SDD（Specification-Driven Development）技术契约专家。激活本技能后，你将引导用户为每个 Capability 创建 **spec.md** 文档。
 
+> **硬依赖**：场景身份 / Spec 复用依赖同级已部署的 **`opsx-ontology-query`**。进入知识库上下文步骤前必须先 `Read` 该技能的 `SKILL.md` 并完成其 Session 启动（API Key + targets）。缺失则停止复用查询，提示重新 `kld-sdd-init`；**禁止**从本地 `archive/` 抄 UUID。
+
 > **⚠️ 阶段边界约束**
 >
 > 当前处于 **Spec（契约）阶段**：
@@ -109,7 +112,8 @@ openspec list
 
 **【默认尝试】工程 Spec 知识库上下文（场景身份主战场）**：
 
-读取 proposal Continuity。对**当前 Capability** 各调一次（「全部」= 循环 N 次，不是一次大查询）：
+1. **先加载依赖技能**：确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read；按该技能完成 API Key / targets（`.local/state.json`）。未安装则停止本步。
+2. 读取 proposal Continuity。对**当前 Capability** 各调一次（「全部」= 循环 N 次，不是一次大查询）——优先走 **`opsx-ontology-query`** 的 `match-requirement`；薄封装仅作参数拼装：
 
 ```bash
 node skywalk-sdd/context-client.cjs \
@@ -123,7 +127,7 @@ node skywalk-sdd/context-client.cjs \
   --kb-id="$ENGINEERING_KB_KB_ID"
 ```
 
-- 配置项：`ENGINEERING_KB_API`、`ENGINEERING_KB_SPACE_ID`、`ENGINEERING_KB_KB_ID`、可选 `ENGINEERING_KB_TOKEN`。查询权威技能是知识库 **`opsx-ontology-query`**；本脚本只是薄封装。
+- 配置项：`ENGINEERING_KB_API`、`ENGINEERING_KB_SPACE_ID`、`ENGINEERING_KB_KB_ID`、可选 `ENGINEERING_KB_TOKEN`。查询权威技能是 **`opsx-ontology-query`**；本脚本只是薄封装。
 - Continuity=`iteration` 时**必须**带 `--entity-id` + external。
 - **禁止**从本地 `archive/` 抄 UUID 当跨迭代继承源；跨迭代只认 KB current。
 - 若返回 `available=false` / `degraded=true`，记录降级并继续，不得扫本地 archive 兜底。

package/templates/skills/kld-sdd/opsx-task/SKILL.md

@@ -189,7 +189,14 @@ Simple 模式或单文件能力域下，**不要拆成多个同文件任务**。
 
 ### 8. 质量红线自检
 
-> 逐项确认，完整 7 项自检清单 + TDD 合规性自检（结构符合模板 / 拓扑图已绘制 / 依赖字段已填写 / 无循环依赖 / 颗粒度 ≤5 分钟 / 100% 覆盖 design / 每任务有验收标准）见 `./checklist.md`「§8 质量红线自检 + §8.1 TDD 合规性自检」。如有任意一项未满足，重新生成对应章节，直至全部通过。
+> 逐项确认，完整 7 项自检清单 + TDD 合规性自检（结构符合模板 / 拓扑图已绘制 / 依赖字段已填写 / 无循环依赖 / 颗粒度 ≤5 分钟 / 100% 覆盖 design / 每任务有验收标准）见 `./checklist.md`「§8 质量红线自检 + §8.1 TDD 合规性自检」。
+>
+> 额外强制项（见 `./checklist.md` §8）：
+> - ⛔ **CON 覆盖**：spec.md 中每个 CON 必须有对应验证任务或显式声明间接覆盖
+> - ⛔ **安全/审计要求覆盖**：spec.md §5.x 中的安全与审计要求必须有对应任务或显式声明推迟
+> - ⛔ **§4.x 验证方式表内部一致性**：§4.x 验证方式表中的测试注解/配置必须与任务实现步骤中的声明一致
+>
+> 如有任意一项未满足，重新生成对应章节，直至全部通过。
 
 ### 9. 确认任务并输出
 

package/templates/skills/kld-sdd/opsx-task/checklist.md

@@ -29,6 +29,9 @@ description: opsx-task 的阶段强制检查点与自检清单。仅在执行 ta
 - [ ] 每个任务颗粒度 ≤ 5 分钟
 - [ ] 100% 覆盖 design.md 定义
 - [ ] 每个任务都有验收标准
+- [ ] ⛔ **约束（CON）覆盖**：spec.md 中每个 CON 必须有对应验证任务，或在任务中显式声明"通过现有 AC 间接覆盖"并说明理由；tasks.md 质量红线声明"100% 覆盖 CON"时必须可追溯
+- [ ] ⛔ **安全/审计要求覆盖**：spec.md §5.x 中的安全与审计要求（日志记录、脱敏、告警等）必须有对应任务，或显式声明推迟到后续迭代并在任务中标注
+- [ ] ⛔ **§4.x 验证方式表内部一致性**：§4.x 验证方式表中的测试注解/配置必须与任务实现步骤中的声明一致，不得出现"§4.1 声明 @WebMvcTest 但实现步骤允许 @SpringBootTest"的矛盾
 
 **如有任意一项未满足，重新生成对应章节，直至全部通过。**
 

package/templates/skills/kld-sdd/opsx-tdd-anti-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opsx-tdd-anti-patterns
-description: "测试反模式防护层 — 15 种反模式检测（RED 阶段 3 种 + GREEN 后 12 种），每种带门禁函数和修复方案。当编写或审查测试代码时引用本技能。"
+description: "测试反模式防护层 — 16 种反模式检测（RED 阶段 3 种 + GREEN 后 13 种），每种带门禁函数和修复方案。当编写或审查测试代码时引用本技能。"
 ---
 
 # opsx-tdd-anti-patterns — 反模式防护层
@@ -32,7 +32,7 @@ description: "测试反模式防护层 — 15 种反模式检测（RED 阶段 3
 | 2 | **Mock 预定结论而非准备条件** | `when(bookMapper.countByPublisher(1L)).thenReturn(3)` 后只测 `if (count > 0) throw` — trivial 逻辑 | "我的测试是在验证完整行为链路，还是只验证一个 if 分支？" | Mock 边界依赖（Mapper）是合理的，但测试断言应验证完整行为链路（如 verify 不会执行 delete） |
 | 3 | **Given 不是真实输入** | mock 出"这个输入会导致什么结果"，而非传入真实数据让被测代码自行处理 | "我的 Given 是真实数据还是 mock 出的预定结论？" | 传入真实数据（如 `"invalid"` 字符串、`null`、空对象），让被测代码自行决定结果 |
 
-## §4 GREEN 后反模式（12 种）
+## §4 GREEN 后反模式（13 种）
 
 | # | 反模式 | 问题表现 | 修复方案 |
 |---|--------|---------|---------|
@@ -48,6 +48,7 @@ description: "测试反模式防护层 — 15 种反模式检测（RED 阶段 3
 | 13 | **魔法值** | 测试中使用未解释的字面值（如 `assertEquals(42, result)` 无注释说明 42 的含义） | 使用命名常量或注释解释字面值含义 |
 | 14 | **断言不足** | 只断言了部分结果，遗漏了关键属性（如只 assertNotNull 但不 assertEquals 具体值） | 每个测试至少有一个具体值断言（assertEquals），而非仅 assertNotNull |
 | 15 | **缺少负面测试** | 只测试正常路径，不测试错误条件 | 每个方法至少有一个异常路径测试（见 `opsx-tdd-rules/rules/exception-path-coverage.md`） |
+| 16 | **AC 变体覆盖不足** | AC 场景描述含"或"条件（如"缺少 A 或 B 或为空"），但测试只覆盖部分变体 | AC 中每个"或"条件变体必须有对应测试方法（规则见 `opsx-tdd-rules/rules/multi-validation-split.md` §AC 内"或"条件变体覆盖） |
 
 ## §5 门禁函数
 
@@ -82,3 +83,5 @@ AFTER GREEN（GREEN 完成后、标记通过前）：
 - 测试中只有 `assertNotNull` 无具体值断言
 - 测试中存在未解释的魔法数字/字符串
 - 正常路径有测试但异常路径无测试
+- AC 场景描述含"或"条件但测试只覆盖部分变体
+- 连续 RED/GREEN 的 task_update 时间戳差距过小（批量执行信号，违反 TDD 严格串行）

package/templates/skills/kld-sdd/opsx-tdd-anti-patterns/reference.md

@@ -195,6 +195,35 @@ assertEquals("user-001", result.getUserId());
 
 **修复**：每个方法至少有一个异常路径测试。规则见 `opsx-tdd-rules/rules/exception-path-coverage.md`。
 
+## 反模式 16：AC 变体覆盖不足
+
+**问题**：AC 场景描述含"或"条件（如"缺少 A 或 B 或为空"），但测试只覆盖部分变体，其余变体无测试守护。
+
+**反例**：
+```java
+// AC-004: 请求体缺少 username 或 password 字段，或字段值为空字符串
+// 仅测试 1/6 变体
+@Test
+void login_withMissingParams_returns1001() {
+    mockMvc.perform(post("/login")
+            .content("{\"username\":\"\",\"password\":\"admin123\"}"))
+            .andExpect(jsonPath("$.code").value(1001));
+}
+```
+
+**正例**：
+```java
+// 每个变体都有测试方法（或参数化测试）
+@Test void login_withEmptyUsername_returns1001() { ... }
+@Test void login_withEmptyPassword_returns1001() { ... }
+@Test void login_withMissingUsernameField_returns1001() { ... }
+@Test void login_withMissingPasswordField_returns1001() { ... }
+@Test void login_withBothEmpty_returns1001() { ... }
+@Test void login_withBothMissing_returns1001() { ... }
+```
+
+**修复**：AC 中每个"或"条件变体必须有对应测试方法。规则见 `opsx-tdd-rules/rules/multi-validation-split.md` §AC 内"或"条件变体覆盖。
+
 ## TDD 如何防止这些反模式
 
 1. 先写测试 → 迫使你思考实际在测试什么

package/templates/skills/kld-sdd/opsx-tdd-core/checklist.md

@@ -40,6 +40,9 @@ description: "opsx-tdd-core 自检清单 — TDD 执行合规自检、合规性
 - [ ] 每个 RED 任务包含测试方法名（`{method}_{state}_{outcome}` 格式）
 - [ ] 每个 GREEN 任务包含 YAGNI 围栏声明（"不提前实现 [后续 RED 行为]"）
 - [ ] 每个 REFACTOR 任务列出至少 2 个具体重构点
+- [ ] ⛔ **CON 覆盖**：spec.md 中每个 CON 在 tasks.md 中有对应验证任务或显式声明间接覆盖
+- [ ] ⛔ **安全/审计要求覆盖**：spec.md §5.x 中的安全与审计要求在 tasks.md 中有对应任务或显式声明推迟
+- [ ] ⛔ **AC 变体覆盖**：spec.md 中含"或"条件的 AC 场景，其 RED 任务验收标准列出所有变体的测试方法（引用 `opsx-tdd-rules/rules/multi-validation-split.md`）
 
 ## §C 完成验证清单（8 项）
 
@@ -53,5 +56,6 @@ description: "opsx-tdd-core 自检清单 — TDD 执行合规自检、合规性
 - [ ] 输出纯净（无错误/警告）
 - [ ] 测试使用真实代码（仅在不可避免时使用 mock）
 - [ ] 边界情况和错误已覆盖
+- [ ] ⛔ **AC "或"条件变体全覆盖**：AC 场景描述含"或"条件时，每个变体都有对应测试方法（引用 `opsx-tdd-rules/rules/multi-validation-split.md`）
 
 > Can't check all boxes? You skipped TDD. Start over.

package/templates/skills/kld-sdd/opsx-tdd-rules/SKILL.md

@@ -24,6 +24,6 @@ description: "TDD 规则库 — DAG 生成规则、Controller 策略、任务类
 | `rules/green-yagni-fence.md` | GREEN 任务 YAGNI 围栏自动注入规则 | HIGH | opsx-task |
 | `rules/green-scope-declaration.md` | GREEN 任务 Scope 声明步骤（断言清单→流程标记→仅实现属于的步骤） | HIGH | opsx-apply |
 | `rules/des-step-annotation.md` | DES 元素步骤级标注规则（TDD 模式下标注 [GREEN-N] 归属） | MEDIUM | opsx-design |
-| `rules/multi-validation-split.md` | 多校验条件拆分规则（每个校验条件须有独立 AC 场景） | MEDIUM | opsx-spec |
+| `rules/multi-validation-split.md` | 多校验条件拆分规则（每个校验条件须有独立 AC 场景；AC 内"或"条件变体须全覆盖） | MEDIUM | opsx-spec, opsx-task, opsx-check |
 | `rules/exception-path-coverage.md` | 异常路径测试覆盖门禁（每个 orElseThrow/边界检查须有对应 RED 测试） | HIGH | opsx-task, opsx-apply, opsx-check |
 | `rules/refactor-checklist.md` | REFACTOR 阶段检查点（public API 不变、行为保持、重构质量评估） | HIGH | opsx-apply, opsx-tdd-core |

package/templates/skills/kld-sdd/opsx-tdd-rules/rules/multi-validation-split.md

@@ -1,7 +1,7 @@
 # 多校验拆分规则
 
 > 影响等级：MEDIUM
-> 引用方：opsx-spec（spec.md 生成）、opsx-spec/checklist.md（自检）
+> 引用方：opsx-spec（spec.md 生成）、opsx-spec/checklist.md（自检）、opsx-task（RED 任务拆解）、opsx-check（一致性检查）
 
 ## 问题
 
@@ -34,3 +34,37 @@ AC-03: 可借数量不足（available_count = 0）
 ```
 
 > 目的：每个校验条件有独立场景 → 独立 RED 测试 → 独立 GREEN 实现，避免 AI 在一个 GREEN 中实现所有校验。
+
+## AC 内"或"条件变体覆盖
+
+> 引用方：opsx-spec（spec.md 生成）、opsx-task（RED 任务拆解）、opsx-check（一致性检查）
+
+### 问题
+
+单个 AC 场景描述中包含"或"条件时（如"缺少 username **或** password 字段，或字段值为空字符串"），AI 在拆解 RED 任务时倾向于只取一个变体编写测试，导致其余变体无测试守护。
+
+### 规则
+
+当单个 AC 场景描述包含"或"条件时，必须检查：
+
+1. 每个"或"条件变体是否有对应的测试方法
+2. 若多个变体共享一个 RED 任务，RED 验收标准中必须列出所有变体的测试方法名
+3. 变体可合并到一个 RED 任务的多个 `@Test` 方法中，但不得遗漏任何变体
+
+### 反例（禁止）
+
+```
+AC-004: 请求体缺少 username 或 password 字段，或字段值为空字符串
+RED-4: login_withMissingParams_returns1001
+  → 仅测试 username="" 一种变体，password="" / 缺少字段 / 双空 / 双缺共 5 种变体未覆盖
+```
+
+### 正例（要求）
+
+```
+AC-004: 请求体缺少 username 或 password 字段，或字段值为空字符串
+RED-4: login_withMissingParams_returns1001（含 6 个 @Test 方法或参数化测试）
+  → username="" / password="" / 缺少 username / 缺少 password / 双空 / 双缺 均有测试
+```
+
+> 目的：spec 中"或"条件描述的每个变体都有测试守护，防止参数校验逻辑回归。