kld-sdd 2.6.8 → 2.6.9

package/templates/skills/kld-sdd/opsx-ontology-query/phase-4-explore.md

@@ -0,0 +1,240 @@
+# Phase 4 · 跨迭代探索（Cross-iteration Exploration）
+
+> **触发时机**：开发者手动查询 / Agent 按需加载
+> **加载方式**：任意阶段可 `Read` 本文件
+> **前置条件**：`.local/state.json` 已完成 Session 启动
+
+---
+
+## §1 版本谱系追踪（Lineage）
+
+### 场景
+
+查看某实体的完整变更历史，理解它经历了哪些变更、每次变更改了什么。
+
+### API
+
+```
+GET {base}/entities/{entityId}/lineage
+```
+
+### 示例
+
+```bash
+curl -sS -H "Authorization: Bearer $API_KEY" \
+  "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/e89287e8-0000-0000-0000-000000000000/lineage"
+```
+
+### 响应解读
+
+返回按时间排序的版本数组，每版包含：
+
+| 字段 | 含义 |
+|------|------|
+| `entityVersionId` | 该版本的 UUID |
+| `predecessorVersionId` | 前序版本 UUID（v1 为 null） |
+| `deltaState` | added / modified / removed |
+| `changeId` | 来源变更 ID |
+| `attributes` | 该版本的属性快照 |
+| `source` | 来源文件（file / line / change_id / archive_id） |
+| `createdAt` | 入库时间 |
+
+### 使用场景
+
+- **变更审计**：追溯某需求从创建到当前的完整路径
+- **回溯根因**：理解某属性何时被修改、由哪次变更引入
+- **差异对比**：对比 v1 和 v2 的 attributes 变化
+
+---
+
+## §2 语义检索（Semantic Search）
+
+### 场景
+
+用自然语言查找相关工程事实，不依赖精确锚点。
+
+### API
+
+```
+POST {base}/context/search
+```
+
+### 请求
+
+```json
+{
+  "query": "用户登录认证流程",
+  "entityTypes": [],
+  "limit": 15
+}
+```
+
+### 检索通道
+
+| 通道 | 说明 | matchType |
+|------|------|-----------|
+| 精确 | 锚点 / canonicalKey 完全匹配 | `exact` |
+| 结构 | entityType + 属性结构匹配 | `structural` |
+| 全文 | PostgreSQL FTS 关键词匹配 | `fulltext` |
+| 向量 | pgvector 语义相似 | `vector` |
+| 图谱 | AGE 关系扩展邻居 | `graph` |
+
+### 响应解读
+
+```json
+{
+  "degraded": false,
+  "degradationReasons": [],
+  "results": [
+    {
+      "matchType": "exact",
+      "entityId": "e89287e8-0000-0000-0000-000000000000",
+      "entityType": "Capability",
+      "displayName": "user-login",
+      "anchorId": "CAP-USER-LOGIN",
+      "scoreExplanation": {
+        "method": "rrf",
+        "ranks_by_channel": { "exact": 1, "fulltext": 1, "vector": 19 }
+      }
+    }
+  ]
+}
+```
+
+### 降级处理
+
+| `degraded` | `degradationReasons` | 影响 |
+|------------|----------------------|------|
+| `false` | `[]` | 全通道可用 |
+| `true` | `["vector_unavailable"]` | 向量通道缺失，精确/全文仍可用 |
+| `true` | `["age_unavailable"]` | 图谱扩展缺失 |
+
+> 降级不阻塞查询，精确/结构/全文通道始终可用。
+
+---
+
+## §3 原文溯源（Disclosure）
+
+### 场景
+
+从实体回到源文档，查看该实体在 spec.md / design.md / tasks.md 中的原文上下文。
+
+### API
+
+```
+POST {base}/context/disclosures
+```
+
+### 请求
+
+```json
+{
+  "anchorId": "STMT-USER-LOGIN-001",
+  "sourceLevel": "preview"
+}
+```
+
+### sourceLevel 选项
+
+| sourceLevel | 返回内容 | 适用场景 |
+|-------|----------|----------|
+| `preview` | 锚点附近几行 | 快速确认实体内容 |
+| `section` | 包含子节的完整章节 | 理解实体及其下属 AC/CON |
+| `document` | 整个源文档 | 全面上下文 |
+
+### 使用场景
+
+- **代码审查**：查看 STMT 的原始规格定义
+- **需求对齐**：对比 AC 场景与实际实现行为
+- **文档生成**：提取原文片段生成技术文档
+
+---
+
+## §4 知识图谱导航（Ontology View）
+
+### 场景
+
+浏览某实体的一跳关系结构，理解其在本体中的位置。
+
+### API
+
+```
+GET {base}/entities/{entityId}/ontology-view
+```
+
+### 响应结构
+
+```json
+{
+  "focus": { "entityId": "...", "canonicalKey": "CAP-USER-LOGIN", ... },
+  "attributes": [ { "key": "description", "value": "..." } ],
+  "businessStructure": {
+    "changes": [...],
+    "capabilities": [...],
+    "statements": [...],
+    "tasks": [...],
+    "designElements": [...],
+    "acceptanceCriteria": [...]
+  },
+  "relations": [
+    { "relationType": "contains", "direction": "outbound", "neighbor": {...} },
+    { "relationType": "verifiedBy", "direction": "outbound", "neighbor": {...} }
+  ],
+  "evidence": {
+    "artifacts": [...],
+    "documentSections": [...],
+    "source": { "file": "proposal.md", "line": 66 }
+  }
+}
+```
+
+### 使用场景
+
+- **影响评估**：从 Capability 出发看下游 STMT → AC → DES → TASK
+- **覆盖分析**：从 STMT 出发看 verifiedBy → AC 列表
+- **溯源链**：从任意实体出发看 sourcedFrom → DocumentSection → Artifact
+
+---
+
+## §5 多跳影响分析（Impact）
+
+### 场景
+
+评估变更的级联影响，超出直接关联。
+
+### API
+
+```
+GET {base}/entities/{entityId}/impact
+```
+
+### 示例
+
+```bash
+curl -sS -H "Authorization: Bearer $API_KEY" \
+  "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/e89287e8-0000-0000-0000-000000000000/impact"
+```
+
+### 响应解读
+
+```json
+{
+  "anchorEntityId": "e89287e8-0000-0000-0000-000000000000",
+  "maxDepth": 4,
+  "nodes": [
+    { "entityId": "...", "entityVersionId": "...", "entityType": "Capability", "displayName": "user-login", "depth": 0 },
+    { "entityId": "...", "entityVersionId": "...", "entityType": "SpecificationStatement", "displayName": "用户登录认证", "depth": 1 },
+    { "entityId": "...", "entityVersionId": "...", "entityType": "AcceptanceCriterion", "displayName": "正确凭证登录成功", "depth": 2 }
+  ],
+  "edges": [
+    { "relationType": "contains", "fromEntityId": "cap-id", "toEntityId": "stmt-id", "assertionType": "asserted" },
+    { "relationType": "verifiedBy", "fromEntityId": "stmt-id", "toEntityId": "ac-id", "assertionType": "inferred" }
+  ]
+}
+```
+
+### 使用场景
+
+- **变更前评估**：修改某 Capability 会波及哪些下游
+- **回归测试范围**：确定受影响的 AC 需要回归验证
+- **架构决策**：理解实体间的依赖深度

package/templates/skills/kld-sdd/opsx-ontology-query/phase-5-governance.md

@@ -0,0 +1,232 @@
+# Phase 5 · 治理与监控（Governance & Monitoring）
+
+> **触发时机**：治理流程 / 定期巡检 / opsx-check 深度验证
+> **加载方式**：治理角色按需 `Read` 本文件
+> **前置条件**：`.local/state.json` 已完成 Session 启动
+>
+> ✅ conformance / drift API **已实现**，但需要先通过 `POST /evidence-ingestions` 入库代码证据后才有数据。
+> 无 evidence 时返回 `{"integrationStatus":"not_integrated","reports":[]}`，Agent 遇到此状态应提示用户"需先入库 evidence"，不当作错误。
+
+---
+
+## §1 覆盖率仪表盘（Coverage Dashboard）
+
+### 场景
+
+全局监控规格覆盖完整性，按 gapType 分类统计缺失项。
+
+### API
+
+```
+GET {base}/coverage
+```
+
+> KB 级别 API，路径含 kbId。
+
+### 示例
+
+```bash
+curl -sS -H "Authorization: Bearer $API_KEY" \
+  "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/coverage"
+```
+
+### 响应解读
+
+```json
+{
+  "gaps": [
+    {
+      "entityId": "xxx-0000-0000-0000-000000000000",
+      "entityType": "SpecificationStatement",
+      "displayName": "某规格声明",
+      "gapType": "missing_acceptance_criterion"
+    }
+  ]
+}
+```
+
+### 统计维度
+
+| gapType | 实体类型 | 含义 | 建议 |
+|---------|----------|------|------|
+| `missing_acceptance_criterion` | STMT | 无验收场景 | 补充 AC |
+| `missing_specification_statement` | DES | 无规格依据 | 补充 realizes 或创建 STMT |
+| `missing_upstream_trace` | TASK | 无上游追溯 | 补充 covers/implements |
+
+### 使用场景
+
+- **定期巡检**：每周/每迭代检查全局覆盖率
+- **质量门禁**：归档前覆盖率必须达标
+- **技术债识别**：长期 missing 的实体标记为技术债
+
+> **Agent 行为指导**：遇到 `integrationStatus: "not_integrated"` 时，提示用户"需先通过 `POST /evidence-ingestions` 入库代码证据"，不当作"无数据"或错误处理。
+
+---
+
+## §2 一致性检查（Conformance）
+
+### 场景
+
+验证代码实现与规格定义的一致性，对比 KB 规格事实与实现证据。
+
+### API
+
+```
+GET {base}/conformance
+```
+
+### 示例
+
+```bash
+curl -sS -H "Authorization: Bearer $API_KEY" \
+  "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/conformance"
+```
+
+### 检查维度
+
+| 维度 | 含义 | 数据源 |
+|------|------|--------|
+| 规格断言 vs 代码实现 | STMT/AC 是否在代码中实现 | semantic facts vs implementation_evidence |
+| 规格覆盖 vs 实际行为 | AC 场景是否被测试覆盖 | AC vs test evidence |
+
+### 使用场景
+
+- **发布前验证**：确认实现与规格一致
+- **回归检测**：代码变更后检查是否仍符合规格
+- **审计报告**：生成一致性报告供评审
+
+---
+
+## §3 漂移检测（Drift）
+
+### 场景
+
+检测实现偏离规格的程度，识别"规格说 A 但代码做 B"的情况。
+
+### API
+
+```
+GET {base}/drift
+```
+
+### 示例
+
+```bash
+curl -sS -H "Authorization: Bearer $API_KEY" \
+  "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/drift"
+```
+
+### 漂移类型
+
+| 类型 | 含义 | 严重度 |
+|------|------|--------|
+| 规格未实现 | STMT/AC 无对应代码 | 高 |
+| 实现无规格 | 代码无对应 STMT/AC | 中 |
+| 行为不一致 | 代码行为与 AC 描述不符 | 高 |
+| 规格过期 | 代码已变更但规格未更新 | 中 |
+
+### 使用场景
+
+- **迭代回顾**：识别本迭代引入的漂移
+- **技术债管理**：长期漂移项纳入技术债看板
+- **重构决策**：高漂移区域优先重构
+
+> **Agent 行为指导**：同 §2，遇到 `integrationStatus: "not_integrated"` 时提示用户需先入库 evidence。
+
+---
+
+## §4 关系候选审批（Relation Candidate Review）
+
+### 场景
+
+`suggested` 关系（AI 推荐但未确认）需要人工审批后才能进入正式本体。
+
+### API
+
+```
+GET  {base}/relation-candidates
+POST {base}/relation-candidates/{candidateId}/review
+```
+
+> 审批通过/拒绝都走同一个 `/review` 端点，用 body 中的 `decision` 区分。
+
+### 示例
+
+```bash
+# 列出待审批候选（可按 status 过滤）
+curl -sS -H "Authorization: Bearer $API_KEY" \
+  "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/relation-candidates?status=pending"
+
+# 审批通过
+curl -sS -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/relation-candidates/{candidateId}/review" \
+  -d '{"decision":"accept","reason":"关系正确，确认批准"}'
+
+# 拒绝
+curl -sS -X POST -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
+  "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/relation-candidates/{candidateId}/review" \
+  -d '{"decision":"reject","reason":"证据不足"}'
+```
+
+### 候选字段
+
+| 字段 | 含义 |
+|------|------|
+| `candidateId` | 候选 UUID |
+| `relationType` | 推荐的关系类型 |
+| `fromEntityId` / `fromName` | 源实体 |
+| `toEntityId` / `toName` | 目标实体 |
+| `confidence` | 置信度（0-1） |
+| `supportEvidence` / `oppositionEvidence` | 支持/反对证据 |
+| `status` | pending / accepted / rejected |
+
+### 审批请求
+
+```json
+{ "decision": "accept | reject", "reason": "string" }
+```
+
+### 审批决策
+
+| confidence | support vs opposition | 建议 |
+|------------|----------------------|------|
+| > 0.8 | support >> opposition | accept |
+| 0.5-0.8 | 有争议 | 人工审查后决定 |
+| < 0.5 | opposition >> support | reject |
+
+### 使用场景
+
+- **日常治理**：定期审批待确认关系
+- **本体质量提升**：高置信度候选批量批准
+- **误报过滤**：低置信度候选拒绝并反馈
+
+---
+
+## §5 变更统计与趋势（Change Analytics）
+
+### 场景
+
+查看 KB 中所有变更的统计信息，分析迭代趋势。
+
+### API
+
+```
+GET {base}/changes
+GET {base}/changes/{changeId}
+```
+
+### 分析维度
+
+| 维度 | 指标 | 用途 |
+|------|------|------|
+| 变更频率 | 每迭代变更数 | 评估迭代节奏 |
+| 变更类型分布 | added / modified / removed 比例 | 评估系统成熟度 |
+| 实体增长率 | 每迭代新增实体数 | 评估规格膨胀 |
+| 覆盖率趋势 | 各 gapType 随时间变化 | 评估质量改进 |
+| 冲突频率 | VERSION_CONFLICT / EXTERNAL_REF_CONFLICT / EXTERNAL_REFERENCE_FORMAT_INVALID / SCOPE_MISMATCH / FEATURE_UNBOUND 次数 | 评估 Continuity 与编号体系流程成熟度 |
+
+### 使用场景
+
+- **迭代报告**：每迭代生成本体变更统计
+- **成熟度评估**：评估团队的 SDD 流程成熟度
+- **容量规划**：预测 KB 增长趋势

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

@@ -1,6 +1,6 @@
 # 本体查询 · 参考
 
-需要鉴权细节、state 字段或响应字段时再读。
+需要鉴权细节、state 字段、API curl 示例或响应字段时再读。
 
 ## `.local/state.json`
 
@@ -68,6 +68,12 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 
 `POST {base}/context/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}'
+```
+
 ```json
 { "query": "string", "entityTypes": [], "limit": 15 }
 ```
@@ -75,14 +81,30 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 | 字段 | 含义 |
 |------|------|
 | `degraded` / `degradationReasons` | 向量/AGE/rerank 等降级 |
+| `advisory` | true=结果为建议性，非权威；Agent 应在输出中标注 |
 | `results[].matchType` | exact / structural / fulltext / vector / graph … |
 | `results[].entityId` / `entityVersionId` | 溯源 |
+| `results[].snippet` | 命中片段预览 |
+| `results[].source` | 溯源信息（file/line/anchor_id/change_id/archive_id） |
+| `results[].reviewStatus` | 审核状态 |
+| `results[].score` | 归一化分数 |
 | `results[].scoreExplanation` | RRF channel ranks 等 |
 
 ## entities/resolve（Continuity / 外部需求号）
 
 `POST {base}/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"
+  }'
+```
+
 ```json
 {
   "externalSystem": "requirement-mgmt",
@@ -97,16 +119,60 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 | 结果 | 含义 |
 |------|------|
 | `resolution=LINK_EXISTING` + `inheritanceAllowed=true` | ≥1 可继承绑定；`candidates` 仅存活实体；`removedBindingCount` 为失效绑定数 |
+| `resolution=SAME_ITERATION` | entityId/previousVersionId 精确命中，已对齐同一实体 |
+| `resolution=CREATE_NEW` | 无匹配，全新需求 |
+| `resolution=RELATED_ONLY` | canonicalKey/名称匹配但无确定性身份，仅候选 |
 | `matchType=HISTORICAL_ONLY` | 有绑定但全部无 current / removed；`inheritanceAllowed=false`，不得当迭代继承 |
 | `NEEDS_CONFIRM` / `SIMILAR_REQUIREMENT` | 名称/结构相似，仅候选 |
 | `NEW_REQUIREMENT` | 无命中 |
 
-**禁止**用本地 `archive/` 目录当跨迭代继承源。
+> **补充响应字段**：
+> - `reviewRequired`：true=需人工确认
+> - `supportEvidence` / `oppositionEvidence`：支持/反对决议的证据列表，Agent 可向用户展示
+> - `clarificationQuestions`：AI 生成的澄清问题，Agent 可用 `ask_user` 呈现给用户
+
+**KB 可用时禁止**用本地 `archive/` 目录当跨迭代继承源，entity-id 必须来自 KB resolve by canonicalKey。KB degraded 时 archive 可作为降级手段（标注 `source: archive(degraded)`）。
+
+## 按功能号圈能力（FEAT query）
+
+在 propose 前，用 feature 编号查询该功能下已有能力清单，辅助勾选本次 CAP 范围。
+
+`POST {base}/entities/resolve`（与 Continuity 同一接口，`externalObjectType:"feature"`）
+
+```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"
+  }'
+```
+
+响应中 `candidates` 列出该 FEAT 下存活 / 失效能力清单；`removedBindingCount` 为已失效绑定数。
+
+> 此查询只作范围参考，不改变 Continuity 判定优先级。
 
 ## context/match-requirement
 
 `POST {base}/context/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`。
+
 ```json
 {
   "query": "string",
@@ -129,6 +195,13 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 | `NEEDS_CONFIRM` | 需人确认 |
 | `NEW_REQUIREMENT` | 无可信复用 |
 
+> **补充响应字段**：
+> - `advisory`：true=结果为建议性
+> - `reviewRequired`：true=需人工确认
+> - `specGenerationContext`：复用统计（`reusableStatements`/`reusableAcceptanceCriteria`/`reusableConstraints`/`reusableDesignElements`/`unresolvedQuestions`），Agent 可据此判断复用率
+> - `warnings`：注意事项（如"相似度只能产生候选，不能自动 sameAs"）
+> - `clarificationQuestions`：AI 生成的澄清问题，Agent 可用 `ask_user` 呈现给用户
+
 ## 对象读
 
 | 方法 | 路径 |
@@ -141,6 +214,8 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 
 `impact` / `ontology-view` 走 PG 关系；与 `context/search` 不同链路。
 
+`impact` 响应字段：`anchorEntityId`（锚点实体 ID）、`maxDepth`（最大影响深度≤4）、`nodes`（含 entityId/entityVersionId/entityType/displayName/depth）、`edges`（含 relationType/fromEntityId/toEntityId/assertionType）。
+
 ## disclosures
 
 `POST {base}/context/disclosures`
@@ -150,8 +225,21 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
   "anchorId": "STMT-…",
   "entityId": null,
   "entityVersionId": null,
-  "level": "preview"
+  "sourceLevel": "preview"
 }
 ```
 
-`level`：`preview` | `section` | `document`。
+`sourceLevel`：`preview` | `section` | `document`。
+
+> 注：请求字段名为 `sourceLevel`（不是 `level`）。响应中对应字段为 `disclosureLevel`。
+> 请求还支持可选的 `relationDepth`、`direction`、`relationTypes`、`entityTypes`、`relatedLimit`。
+
+## 实现备注
+
+> 控制台 Agent 架构 / Skills 激活机制 / 记忆策略。对查询操作无直接影响，仅供维护者参考。
+
+- 控制台知识库页另有浮动 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，除非以后要跨会话个人偏好记忆。