kld-sdd 2.6.7 → 2.6.9

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

@@ -27,6 +27,15 @@ allowed-tools:
 > **完成本阶段后，绝对禁止自动继续执行 task 等后续阶段。**
 > 阶段边界自检见 `./checklist.md`「阶段边界⛔」。
 
+> **KB 上下文**：设计时可参考历史设计决策。
+> 1. 检查 proposal.md frontmatter `kb-status`：若 `degraded(by-user-choice)` → 跳过 KB，仅用本地上下文。
+> 2. 否则运行 KB 就绪检查：
+> ```bash
+> node skywalk-sdd/context-client.cjs --check-only
+> ```
+> - `"available": true` → 若需查历史设计参考，先 `Read` `opsx-ontology-query/phase-2-during.md` §1
+> - `"available": false` → **KB 不可用不阻塞 design 流程**，仅跳过历史设计参考查询
+
 > **⚠️ 渐进式上下文加载原则**
 >
 > - 本技能针对**单一 Capability** 执行设计（Simple 模式例外，见下方 S1 说明）

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

@@ -1,4 +1,4 @@
----
+---
 name: opsx-explore
 description: "浏览变更技能 - 查看所有变更状态和 SDD 文档完整性概览"
 argument-hint: "[change-name]"
@@ -10,8 +10,6 @@ metadata:
 allowed-tools:
   - Bash
   - Read
-  - Write
-  - Edit
 ---
 
 你是一个 SDD（Specification-Driven Development）变更浏览专家。激活本技能后，你将展示项目中所有变更的状态概览，并引导用户执行下一步操作。
@@ -40,8 +38,15 @@ allowed-tools:
 
 ## 启动流程
 
-### 1. 获取所有变更列表
+### 1. 获取所有变更列表（按模块中文分组）
 
+优先使用命名协议分组：
+```bash
+node skywalk-sdd/ontology/cli.cjs list-changes --project=.
+# 需要结构化数据时加 --json
+```
+
+也可辅助：
 ```bash
 openspec list
 ```
@@ -52,25 +57,40 @@ openspec list
 ### 2. 检查每个变更的 SDD 文档完整性
 
 对每个变更，检查以下文件是否存在：
-- `openspec/changes/<name>/proposal.md`（P）
-- `openspec/changes/<name>/specs/<capability>/spec.md`（S）
-- `openspec/changes/<name>/specs/<capability>/design.md`（D）
-- `openspec/changes/<name>/specs/<capability>/tasks.md`（T）
+- `openspec/changes/<change-key>/proposal.md`（P）
+- `openspec/changes/<change-key>/specs/<capability>/spec.md`（S）
+- `openspec/changes/<change-key>/specs/<capability>/design.md`（D）
+- `openspec/changes/<change-key>/specs/<capability>/tasks.md`（T）
 
 同时获取每个变更状态：
 ```bash
-openspec status --change "<name>" --json
+openspec status --change "<change-key>" --json
 ```
 
-### 3. 展示变更概览表
+### 3. 展示按模块分组的变更概览
+
+展示格式（title 来自 proposal frontmatter，目录定位使用 change-key）：
+
+```text
+📦 财务核算 (fi)
+  ● 会计凭证头创建
+    fi-260727-account-doc-head-create
+    P✅ S✅ D✅ T❌ | 建议: /opsx-task fi-260727-account-doc-head-create
+
+📦 跨模块 (cross)
+  ● 凭证与库存联动
+    cross-260727-fi-mm-voucher-stock-link
+    affected: fi, mm
+
+📦 未分类
+  ● legacy-add-user-auth
+    legacy-add-user-auth
+```
 
-> "📋 **项目变更概览**（P=提案 S=规格 D=设计 T=任务）：
->
-> | 变更名称 | P | S | D | T | openspec状态 | 建议下一步 |
-> |---------|---|---|---|---|------------|---------|
-> | add-user-auth | ✅ | ✅ | ✅ | ❌ | PENDING | `/opsx-task add-user-auth` |
-> | payment-refund | ✅ | ❌ | ❌ | ❌ | PENDING | `/opsx-spec payment-refund` |
-> | points-exchange | ✅ | ✅ | ✅ | ✅ | IMPLEMENTING | `/opsx-check points-exchange` |"
+规则：
+- 分组依据 `module`；中文组名来自 `modules.yaml`
+- 缺少 change-key/title/module 的存量 change 归入「未分类」
+- `module=cross` 时额外展示 `affected-modules`
 
 ### 4. 【交互引导】选择操作
 

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

@@ -13,20 +13,14 @@ description: >-
 
 > 控制台知识库页另有浮动 Ontology Agent（会话登录 + SSE）；本 Skill 仍走 API Key，二者分开。
 
-本地状态文件（含密钥，勿提交）：
-
-```text
-skills/opsx-kb-ingest/.local/state.json
-```
-
-字段说明 → [reference.md](reference.md)。
+> **📡 共享状态**：本技能与 `opsx-ontology-query` **共用同一份 KB 配置**（`../.shared/kb-state.json`）。任一 skill 配置后，另一个自动可用，无需重复输入 API Key。
 
 ## Session 启动（每次用本 Skill 必做）
 
 ```
 Task Progress:
-- [ ] 1. 读 .local/state.json（没有则当空）
-- [ ] 2. 无 apiKey → 向用户索取并写入 state（勿把完整 key 打进聊天摘要）
+- [ ] 1. 读 ../.shared/kb-state.json（没有则当空）
+- [ ] 2. 无 apiKey → 向用户索取并写入共享 state（勿把完整 key 打进聊天摘要）
 - [ ] 3. 无 targets 或用户要重置 → 拉空间/KB 列表，让用户多选后写入
 - [ ] 4. 按意图执行入库操作（上传 / 查状态 / 列表 / 重试）
 - [ ] 5. 按模板输出结果
@@ -36,9 +30,9 @@ Task Progress:
 
 若 `state.apiKey` 为空或无效（401/403）：
 
-1. 请用户提供 API Key（控制台「API 密钥」创建，至少含 `archive:ingest`）。
+1. 请用户提供 API Key（控制台「API 密钥」创建，至少含 `archive:ingest`。建议同时勾选 `context:read`，使 `opsx-ontology-query` 也能复用此 Key）。
 2. 可选：请用户确认 `api`（默认 `http://localhost:8090/api`）与 `tenantKey`（默认 `default`）。
-3. 写入 `.local/state.json`（创建目录若不存在）。
+3. 写入共享 `../.shared/kb-state.json`（创建目录若不存在）。
 4. 用 `GET $API/health` 探活；再用 `GET $API/v1/spaces?tenantKey=…` + Bearer 校验 key。
 
 用户说「换密钥 / 重置 API Key」→ 清空 `apiKey`（可保留 targets），回到本步。
@@ -165,17 +159,18 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JO
 - 无 `targets` 不得臆造 spaceId/kbId。
 - 上传前确认 zip 包路径存在且为有效 zip 文件。
 - 入库失败时展示 `errorCode` 和 `errorMessage`，不编造原因。
-- 完整 apiKey 只写 state 文件；聊天里最多显示前缀（如 `sk_sdd_****`）。
+- 完整 apiKey 只写共享 state 文件（`../.shared/kb-state.json`）；聊天里最多显示前缀（如 `sk_sdd_****`）。
 - 401/403 时清掉 `apiKey`，请用户重贴；勿循环重试。
+- **共享状态**：state 文件与 `opsx-ontology-query` 共用。如用户此前已通过查询 skill 配置过 KB，本 skill 启动时直接读取已有配置，无需重复询问。
 
 ## 用户口令
 
 | 用户说 | Agent 做 |
 |--------|----------|
-| （首次使用） | 要 key → 选 KB（多选）→ 再操作 |
+| （首次使用） | 要 key → 选 KB（多选）→ 写共享 state → 再操作。此后 `opsx-ontology-query` 也自动可用 |
 | 换密钥 / 重置 API Key | 清 apiKey，重走第 2 步 |
 | 重新选择 / 重置空间或知识库 | 清 targets，重走第 3 步 |
-| 上传 / 入库 | 用当前 targets 中选中的 KB 上传 zip |
+| 上传 / 入库 | 用当前共享 targets 中选中的 KB 上传 zip |
 | 查状态 / 看任务 | 用 jobId 查询任务状态 |
 | 列任务 / 看历史 | 列出最近入库任务 |
 | 重试 | 对失败的 jobId 执行重试 |

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

@@ -5,126 +5,85 @@ description: >-
   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: "2.0"
+  source: "kb-sdd/skills/opsx-ontology-query"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # 本体知识库 · 查询
 
 只负责**查**。鉴权只用 **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**，除非以后要跨会话个人偏好记忆。
-
-本地状态文件（含密钥，勿提交）：
+> **部署说明**：随 `kld-sdd-init` 安装。`opsx-propose` / `opsx-spec` 等流程技能**硬依赖**本技能，缺失时不得用本地 archive 兜底。
+> 控制台 Agent 架构 / Skills 激活机制 / 记忆策略等实现细节 → [reference.md](reference.md)「实现备注」。
+
+## ⚠️ 数据边界（必读）
 
-```text
-skills/opsx-ontology-query/.local/state.json
+```
+SDD 流程：Propose → Spec → Design → Task → Check → Apply → Archive → kb-ingest
+                                                          ↑
+                                                   此刻之前，当前变更不在 KB 中
 ```
 
-字段说明 → [reference.md](reference.md)。
+- Propose → Check 阶段查 KB = 查**历史上下文**（上一次入库的状态）
+- 当前变更的 added/modified 实体在 KB 中**不存在**或**只有旧版本**
+- 当前变更内部一致性 → **本地文件 + semantic-check**，不查 KB
+- 只有 Archive → kb-ingest 后，当前变更才进入 KB（Phase 3 验证）
 
 ## Session 启动（每次用本 Skill 必做）
 
+> **📡 共享状态**：本技能与 `opsx-kb-ingest` **共用同一份 KB 配置**（`../.shared/kb-state.json`）。任一 skill 配置后，另一个自动可用，无需重复输入 API Key。
+
 ```
 Task Progress:
-- [ ] 1. 读 .local/state.json（没有则当空）
-- [ ] 2. 无 apiKey → 向用户索取并写入 state（勿把完整 key 打进聊天摘要）
+- [ ] 1. 读 ../.shared/kb-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），回到本步。
+**API Key**：控制台「API 密钥」创建，scope ≥ `context:read`。401/403 → 清掉 apiKey 请用户重贴，勿循环重试。
 
-### 3. 选择空间与知识库（支持多选）
+**选择空间/KB**：`GET $API/v1/spaces?tenantKey=…` → 对每个 space `GET …/knowledge-bases` → 展示清单**允许多选** → 写入共享 `../.shared/kb-state.json` 的 `targets`。
 
-若 `state.targets` 为空，或用户说「重新选择 / 重置空间 / 重置知识库」：
+> state.json 字段 schema、鉴权细节、列表接口 → [reference.md](reference.md)。
 
-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}`  
+路径前缀：`/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`） |
+| Continuity / 按外部需求号定位身份 | `POST …/entities/resolve` |
+| Spec 复用 / 转换 | `POST …/context/match-requirement` |
 | 对象详情 | `GET …/entities/{id}/current-version` |
 | 一跳结构 | `GET …/entities/{id}/ontology-view` |
 | 多跳影响 | `GET …/entities/{id}/impact` |
-| 原文 | `POST …/context/disclosures`（见 reference） |
-
-**机器意图（SDD 流程 Agent）**
+| 版本谱系 | `GET …/entities/{id}/lineage` |
+| 原文 | `POST …/context/disclosures` |
 
-- Continuity（只要身份、不要 reuseBundles）→ 优先 `POST …/entities/resolve`
-- Spec 复用 → `POST …/context/match-requirement`，带 external 与/或 `entityId`
-- **禁止**扫描消费方本地 `archive/` 目录当跨迭代继承源；历史有效规格以 KB current 为准
+> 各 API 的完整 curl 示例、请求/响应字段、matchType 含义、降级处理 → [reference.md](reference.md)。
 
-**search**
+**机器意图（SDD 流程 Agent）**：
 
-```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"
-  }'
-```
+- Continuity（只要身份）→ 优先 `entities/resolve`
+- Spec 复用 → `context/match-requirement`，带 external 与/或 `entityId`
+- **KB 可用时禁止**扫描消费方本地 `archive/` 目录当跨迭代继承源；entity-id 必须来自 KB resolve by canonicalKey。KB degraded 时 archive 可作为降级手段（标注 `source: archive(degraded)`），历史有效规格以 KB current 为准
 
 命中时关注：`resolution=LINK_EXISTING` 且 `inheritanceAllowed=true`（可继承 n）；`removedBindingCount`（已失效绑定 m）；`matchType=HISTORICAL_ONLY` 表示仅有失效绑定，不可继承。
 
-**按功能号圈能力（propose 前）**
-
-```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":"feature",
-    "externalId":"FEAT-FI-012",
-    "entityType":"Capability"
-  }'
-```
-
-展示该功能下存活 / 失效能力清单，辅助勾选本次 CAP 范围；此查询只作范围参考，不改变 Continuity 判定优先级。
-
 ### 编号文法速查（权威在 KB 仓设计 §2）
 
 ```text
@@ -135,24 +94,9 @@ scenario:    ^REQ-…:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
 
 归一化：trim；REQ/FEAT 段大写；SCN slug 小写。编号五律摘要：REQ/FEAT 仅需求系统铸号；SCN 由 kld-sdd/opsx-spec 铸号；编号≠身份；归属权威在需求系统；历史绑定 append-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`。
+> 按功能号圈能力（FEAT query）、match-requirement / resolve 完整 curl 示例与响应字段解读 → [reference.md](reference.md)。
 
-### 5. 输出模板
+## 输出模板
 
 ```markdown
 ### 本体查询结论
@@ -160,6 +104,7 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/context/match-
 - 意图：{复用 | 事实检索 | 影响}
 - 可信度：{高 | 中（降级） | 无命中}
 - 降级：{reasons 或 无}
+- 建议性：{是（advisory=true） | 否}
 
 ### 命中
 1. **{displayName}**（{entityType}）@ {kbName}
@@ -167,25 +112,54 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/context/match-
    - 若外部键命中：可继承 n / 已失效绑定 m
 ```
 
-**硬规则**
+## 硬规则
 
 - 无 `apiKey` 不得猜密钥、不得改走 login。
 - 无 `targets` 不得臆造 spaceId/kbId。
 - 无命中 → 写明「无当前依据」，禁止编造条款。
-- 完整 apiKey 只写 state 文件；聊天里最多显示前缀（如 `sk_sdd_****`）。
+- 完整 apiKey 只写共享 state 文件（`../.shared/kb-state.json`）；聊天里最多显示前缀（如 `sk_sdd_****`）。
+- **共享状态**：state 文件与 `opsx-kb-ingest` 共用。配置一次，两个 skill 都生效。
 
 ## 用户口令
 
 | 用户说 | Agent 做 |
 |--------|----------|
-| （首次使用） | 要 key → 选 KB（多选）→ 再查 |
-| 换密钥 / 重置 API Key | 清 apiKey，重走第 2 步 |
-| 重新选择 / 重置空间或知识库 | 清 targets，重走第 3 步 |
-| 查 / Spec 复用 / 影响… | 用当前 targets 查询 |
+| （首次使用） | 要 key → 选 KB（多选）→ 写共享 state → 再查。此后 `opsx-kb-ingest` 也自动可用 |
+| 换密钥 / 重置 API Key | 清 apiKey，重走 Session 第 2 步 |
+| 重新选择 / 重置空间或知识库 | 清 targets，重走 Session 第 3 步 |
+| 查 / Spec 复用 / 影响… | 用当前共享 targets 查询 |
 
-## 心智模型（简述）
+## 心智模型
 
 - 本体真相在 PG（entity + relation）；控制台地图/对象用 SQL 遍历。
 - **外部需求号是确定性身份**；自然语言只产生 REFERENCE 候选，不能自动 sameAs。
-- `context/search` 才是语义检索主通道（+ 可选 AGE 扩邻）；跨迭代 Continuity 走 `entities/resolve`。
-- 细节与 state schema → [reference.md](reference.md)。
+- `context/search` 是语义检索主通道（+ 可选 AGE 扩邻）；跨迭代 Continuity 走 `entities/resolve`。
+
+## 渐进披露（阶段 Playbook）
+
+> **何时读哪个文件**——SDD 各阶段 skill 在对应步骤 `Read` 以下文件，获取场景化的 API 调用示例和决策逻辑。
+
+| 文件 | 何时 Read | 场景 |
+|------|----------|------|
+| [reference.md](reference.md) | 需要 API 字段细节 / state schema / 鉴权细节 | 完整 API 参考 |
+| [phase-1-prechange.md](phase-1-prechange.md) | opsx-propose §6.5 / opsx-spec §3 | 连续性检查、影响预评、历史 AC、Spec 复用、约束冲突 |
+| [phase-2-during.md](phase-2-during.md) | opsx-design / opsx-task / opsx-check | 历史设计参考、历史任务参考、历史覆盖率基线、入库前预检 |
+| [phase-3-postchange.md](phase-3-postchange.md) | opsx-archive 入库后 | 版本生效验证、AC 保留、关系完整性、谱系验证、冲突检测 |
+| [phase-4-explore.md](phase-4-explore.md) | 跨迭代探索 / 开发者手动 | 谱系追踪、语义检索、原文溯源、图谱导航、多跳影响 |
+| [phase-5-governance.md](phase-5-governance.md) | 治理流程 / 定期巡检 | 覆盖率仪表盘、一致性检查、漂移检测、候选审批、变更统计 |
+
+**快速定位**：
+
+```
+propose 前查影响范围？           → phase-1-prechange.md §2
+看某 STMT 有哪些历史 AC？        → phase-1-prechange.md §3
+复用历史 Spec？                  → phase-1-prechange.md §4
+查历史设计作参考？               → phase-2-during.md §1
+查历史覆盖率基线？               → phase-2-during.md §3
+入库前预检 predecessor？         → phase-2-during.md §5
+入库后验证版本生效？              → phase-3-postchange.md §1
+查实体完整变更历史？              → phase-4-explore.md §1
+用自然语言搜工程事实？            → phase-4-explore.md §2
+看全局覆盖率仪表盘？             → phase-5-governance.md §1
+当前变更内部一致性验证？          → 不查 KB，走本地文件 + semantic-check
+```