kld-sdd 2.7.3 → 2.7.8-2

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

@@ -5,8 +5,8 @@ description: >-
   Shared prerequisite for opsx-ontology-query, opsx-kb-ingest, and kb-upload.
   Run once, all KB skills become available. Also supports changing KB spaces.
 license: MIT
-compatibility: Requires Engineering KB API (API Key with context:read + archive:ingest).
 metadata:
+  compatibility: Requires Engineering KB API (API Key with context:read + archive:ingest).
   author: sdd-team
   version: "1.0"
   source: "kb-sdd/skills/opsx-kb-config"
@@ -16,170 +16,45 @@ allowed-tools:
   - Write
   - Edit
 ---
-
 # 本体知识库 · 配置
 
-只负责**配置**。一次配置，查询（opsx-ontology-query）、入库（opsx-kb-ingest）、文件夹上传（kb-upload）全部可用。
-
-> **📡 共享状态**：配置写入 `kb-state.json`（位于 spec 仓根目录），所有 KB 技能共用。任一技能配置后，其他技能自动可用，无需重复输入。
-
-> **🖥️ 跨平台执行规则**（Windows 用户必读）:
-> - KB 配置涉及 HTTP 请求和 JSON 文件读写，**禁止**在 PowerShell 中使用 `curl`（被别名为 Invoke-WebRequest）→ 用 `Invoke-RestMethod` 或 Node.js 脚本
-> - **禁止**用 PowerShell `Get-Content` / `Out-File` 读写 JSON（默认写 BOM 导致 JSON.parse 失败）→ 用 write_to_file 工具或 Node.js `fs` 模块
-> - **禁止** `| cat` 管道（PowerShell 将 cat 解释为 Get-Content 不接受管道输入）→ 直接执行命令
-> - **禁止**用 `node -e "..."` 内联脚本（PowerShell 对 `||`/`{}`/`()` 有特殊解析，导致 JS 语法被破坏）→ 用 `write_to_file` 创建临时 `.cjs` 脚本执行后删除
-> - **⚠️ PowerShell CLIXML**：直接执行 `node xxx.cjs` 时 stdout 可能被包装为 CLIXML `<Objs>` 格式导致 JSON 解析失败。`lib/shared.cjs` 已内置 `stripCliXml()` 剥离函数；临时脚本中可用 `require('./lib/shared.cjs').stripCliXml(output)` 处理
-> - **推荐**用 `write_to_file` 创建临时 `.cjs` 脚本执行所有 Node.js 逻辑，执行完后 `delete_file` 清理
-
-## 能做什么
-
-| 场景 | 说明 |
-|------|------|
-| 首次配置 | 输入 API Key → 绑定监控项目（可留空）→ 选择 Space/KB → 创建 project-identity.json |
-| 更换 API Key | 清空 apiKey，重新输入；随后需重新校验监控项目绑定 |
-| 更换知识库 | 清空 targets，重新选择 Space/KB |
-| 绑定/更换监控项目 | 写入或清除 `projectName`（Step 2.5） |
-| 查看当前配置 | 展示已配置的 Space/KB 列表与项目绑定 |
-| 校验配置 | 探活 API + 校验 project_id 与 spaceKey 一致 |
-
-## 配置步骤
-
-### 1. 读取共享状态
-
-```bash
-# 读取 spec 包裹包路径
-SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
-
-# 读取共享 KB 配置（用 write_to_file 创建临时脚本，勿用 node -e）
-# 临时脚本内容：
-#   const fs = require('fs');
-#   try { console.log(fs.readFileSync(process.argv[1], 'utf8')); }
-#   catch { console.log('{}'); }
-# 执行：node _tmp-read-state.cjs "$SPEC_ROOT/kb-state.json"
-# 或直接用 read_file 工具读取该文件
-```
-
-### 2. API Key
-
-若 `state.apiKey` 为空或用户要求换密钥：
-
-1. 请用户提供 API Key（控制台「API 密钥」创建，scope 建议同时勾选 `context:read` + `archive:ingest`，使查询与入库都能复用）。
-2. 可选：请用户确认 `api`（默认 `http://10.29.213.80:8080/api`）与 `tenantKey`（默认 `default`）。
-3. 写入 `kb-state.json`（spec 仓根目录，已 gitignore）。
-4. 用 `GET $API/health` 探活；再用 `GET $API/v1/spaces?tenantKey=…` + Bearer 校验 key。
-
-**安全规则**：
-- 完整 apiKey 只写共享 state 文件；聊天里最多显示前缀（如 `sk_sdd_****`）。
-- 401/403 → 清掉 apiKey 请用户重贴，勿循环重试。
-- **不要** `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` 为空，或用户要求重新选择：
-
-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 }, …]`。
-
-> **API 返回字段说明**（临时脚本中注意字段名）：
-> - Space 列表返回 `spaceId`（camelCase），不是 `id`。临时脚本中使用 `s.spaceId || s.id` 兼容。
-> - Space 列表返回 `spaceKey`（项目标识，非 UUID），用于 `project-identity.json` 的 `project_id`。
-> - KB 列表返回 `kbId`（camelCase），不是 `id`。
-
-### 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`。
-
-选择 Space 完成后（Step 3 写入 `targets` 后），执行以下逻辑：
-
-1. 读取 spec 包裹包路径：
-   ```bash
-   SPEC_ROOT=$(node <spec-package>/skywalk-sdd/spec-root.cjs)
-   ```
-2. 检查 `$SPEC_ROOT/skywalk-sdd/project-identity.json` 是否已存在
-3. **不存在** → 创建（取 `targets[0].spaceKey` 作为 `project_id`）：
-   ```json
-   {
-     "schema_version": "kld-sdd-project-identity/v1",
-     "project_id": "<targets[0].spaceKey>",
-     "created_at": "<ISO timestamp>",
-     "kb_space_id": "<targets[0].spaceId>",
-     "kb_space_name": "<targets[0].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. **已存在且一致** → 跳过，不输出
+配置 spec 仓根目录的 `kb-state.json`，供查询、身份核对和入库共用。首次使用补齐缺失项；已有有效配置直接复用。用户已经指定的 API、租户、Space/KB 不再重复询问。
 
-> state.json 字段 schema、鉴权细节、列表接口 → [reference.md](reference.md)。
+## 连接与目标
 
-## 更换知识库
+1. 用已安装的 `skywalk-sdd/spec-root.cjs` 定位 spec 根目录，读取现有 state，保留无关字段。
+2. 缺少连接信息时，补齐团队 API 地址（含 `/api`）、tenantKey、API Key。完整密钥只在本地安全填写，不回显到聊天、命令历史或截图。查询需要 `context:read`，上传需要 `archive:ingest`。
+3. 访问 `/health` 探活，再带 Bearer 调用 `/v1/spaces?tenantKey=…` 和目标空间的 `/knowledge-bases` 验证访问权。健康检查成功不等于目标授权成功。
+4. API 的 `spaceId/spaceKey/name` 映射为 `spaceId/spaceKey/spaceName`；KB 的 **`knowledgeBaseId/name` 映射为 `kbId/kbName`**。不凭名称猜 ID。
+5. `targets` 可保存多个连接目标。单个目标可直接使用；多个目标时，按用户本次指定的 Space/KB 选择，查询、同步和上传同时传 `--space-id`、`--kb-id`。缺少明确选择时询问本次目标，**不默选首项，不自动广播**。跨目标查询逐个执行并保留来源。
+6. 保存配置后，对本次目标运行 `context-client.cjs --check-only`，说明可达性、权限与检索通道状态。断连仍允许本地编写、测试和归档，远程基线核对与正式发布保持未完成。
 
-当用户说「换知识库 / 换 Space / 重新选择」时：
+可用目标只有一个且信息完整时，不添加确认步骤。多目标选择可沿用本轮用户已明确的选择；不用额外持久化一套“默认目标”状态。
 
-1. **保留 apiKey**（不需要重新输入密钥）
-2. 清空 `state.targets`
-3. 重走 Step 3（选择空间与知识库）
-4. 重走 Step 4（更新 project-identity.json）
+## 团队项目身份
 
-> ⚠️ 更换 Space 后，`project_id` 会随之变化。之前上传到旧 Space 的归档包不受影响，但新上传将写入新 Space。
+`skywalk-sdd/project-identity.json` 随 spec 仓提交 Git，`project_id` 必须等于**该 spec 仓所属项目** Space 的 `spaceKey`。
 
-## 查看当前配置
+- 文件不存在：为用户已选定的业务项目创建身份。多个查询目标属于不同 Space 时，先明确哪个项目拥有此 spec 仓；不能用目标列表顺序推断。
+- 文件存在且项目一致：保留。
+- 文件存在但选择了不同项目：可以作为只读查询目标，**不能因为切换查询连接就改写团队身份**。已有事实/历史包迁移到其他 Space/KB 属于另一个明确任务，不能仅改 project_id、manifest 或 targets 冒充迁移完成。
+- 一个 Space 下的多个 KB 也分别选择。既有实体身份不能靠原包复制到另一 KB；跨库复用需确认事实归属并按正常流程建立目标身份。
 
-读取 `kb-state.json` 并展示：
+创建字段与 API 映射见 [reference.md](reference.md)。机器身份保留完整 UUID；人阅读使用锚点与业务名称，不能截短远程返回的实体或版本 ID。
 
-```markdown
-### 当前 KB 配置
-- API 地址：{api}
-- 租户：{tenantKey}
-- API Key：{前缀}****（已配置 / 未配置）
-- 项目绑定：{projectName 或 未绑定}
-- 目标 Space/KB：
-  1. {spaceName}（spaceKey: {spaceKey}）→ {kbName}
-  2. ...
-- project-identity.json：{已存在 / 不存在}（project_id: {值}）
-```
+## 更换配置与失败处理
 
-## 用户口令
+- 换密钥：只替换密钥并验证当前目标权限，保留 targets 与团队身份。
+- 换 Space/KB：更新用户指定的连接目标，再核对查询权或入库项目一致性；不清空所有已有连接或自动改写身份。
+- 401：停止本次远程操作，提示验证密钥；403：说明 scope/目标访问权不足。两者均不自动清除可能仍对其他目标有效的密钥，不循环重试。
+- 网络不可用：保留配置，报告原因；可选查询失败不阻止本地流程。不能把不可用报告成“没有事实”或“已完成入库”。
+- 当前七种 Skill 使用统计按本机 Git 身份上报，独立于 Spec 入库。本配置流程无需填写监控项目或访问旧 `/sdd-runs/dimensions`。历史 `projectName` 字段可保留兼容，不作为当前使用统计或业务归属依据。
 
-| 用户说 | 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 |
+查看配置时展示 API、租户、目标 Space/KB、团队项目身份和授权/就绪结果；密钥仅显示“已配置”或脱敏前缀。
 
-## 硬规则
+## 文件与跨平台执行
 
-- 无 `apiKey` 不得猜密钥、不得改走 login。
-- 无 `targets` 不得臆造 spaceId/kbId。
-- 完整 apiKey 只写共享 state 文件（`kb-state.json`，spec 仓根目录）；聊天里最多显示前缀。
-- 401/403 时清掉 `apiKey`，请用户重贴；勿循环重试。
-- **共享状态**：state 文件与 `opsx-ontology-query`、`opsx-kb-ingest`、`kb-upload` 共用。配置一次，全部生效。
+- `kb-state.json` 不提交 Git，校验 `.gitignore`；项目身份文件提交 Git。
+- 通过客户端文件工具或 Node.js 写 UTF-8 JSON，无 BOM，并原子替换；勿用 PowerShell 默认编码直接覆盖。
+- PowerShell 的 `curl` 可能是别名，HTTP 用 `Invoke-RestMethod` 或 Node.js；复杂 Node 逻辑写临时 `.cjs` 文件，避免 shell 内联转义。
+- 不调用 `/auth/login` 换取另一身份，不猜密钥或目标 ID。

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`。

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

@@ -7,6 +7,8 @@ description: >-
   Use when ingesting new or updated knowledge archives into the ontology KB.
 ---
 
+> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；同一会话已读则复用。用户已授权连续处理时按范围推进，不重复索要阶段口令；只请求单阶段时完成即停。
+
 # 本体知识库 · 入库
 
 只负责**入库**（zip 上传 + 文件夹上传）。鉴权只用 **API Key**（`Authorization: Bearer sk_sdd_…`），**禁止**走手机号登录。
@@ -182,82 +184,18 @@ node skywalk-sdd/kb-sync-identity.cjs \
   --skip-kb-verify
 ```
 
-脚本自动完成：
-- **Phase 0**: 读取 KB 配置（kb-state.json + project-identity.json）→ KB API 健康检查 → KB resolve 验证实体当前 version-id
-- **结构实体同步**: 扫描 `ontology-identities.json` 中结构实体（Artifact + DocumentSection）的 content_hash 变化，为变更实体生成新 version-id（predecessor=KB验证的 version-id）
-- **业务实体同步**: 基于结构实体同步的 DocumentSection 变化结果，只为 content_hash 真正变化的业务实体生成新 version-id 并更新 markdown 身份块。未变化的 `added` 实体保持原样，不会被无端 version-bump
-- **同步报告**: 输出哪些实体被同步、哪些跳过、predecessor 来源（local/KB）
-
-> **✅ 内容驱动安全保证**：默认模式下，脚本通过 Part 1 的 DocumentSection content_hash 比较结果驱动 Part 2 的业务实体筛选。只有 `delta-state=added` **且** 对应 DocumentSection content_hash 真正变化的实体才会被转为 `modified`。未变化的 `added` 实体保持原样，不会造成版本污染。
->
-> **⚠️ 精准模式** (`--anchors`): 当用户明确知道改了哪些实体时使用。脚本信任用户指定，即使 Part 1 未检测到 content_hash 变化也会同步（适用于身份元数据变更等非内容性修改场景）。
-
-> **Phase 0 说明**：脚本默认会查询 KB 获取实体的当前 version-id 作为 predecessor。如果本地 version-id 与 KB 不一致（如 git 恢复后），脚本会自动使用 KB 的 version-id 作为 predecessor 并输出警告。如果 KB 不可达，脚本会降级为本地模式（使用本地 version-id）并输出警告。使用 `--skip-kb-verify` 可强制跳过所有 KB 操作。
-
-> ⛔ **禁止**跳过同步直接 `kb-upload.cjs --folder`：被修改的实体 version-id 未变 + content_hash 变了 → KB 报 `VERSION_IDENTITY_CONFLICT`。
->
-> ⛔ **禁止**删除整个 `ontology/` + `artifacts/` 缓存来绕过冲突：会导致所有实体被重新计算 hash 和 version-id，造成不必要的版本扩散。应使用 `kb-sync-identity.cjs` 精准同步。
-
-**方式 B：手动同步（脚本不可用时 fallback）**
-
-1. **识别被修改的实体**——Agent 知道自己改了哪些内容。例如：修改了 AC-USER-CRUD-007 的默认分页大小，则只需处理该实体。若修改了 spec.md 的多处内容，列出所有受影响的实体 anchor（如 STMT-xxx、AC-xxx、CON-xxx）。
-
-> ⚠️ **不要忘记结构实体**：修改了 .md 文件后，该文件的 Artifact 实体（文档级）也需要同步。结构实体存储在 `ontology/ontology-identities.json` 中，需更新其 `version_id` 字段。
-
-2. **对每个被修改的实体，查 KB → 生成新 version-id → 更新身份块**
-
-2a. 查询 KB 获取该实体的当前 version-id：
-
-```bash
-# 示例：查询 AC-USER-CRUD-007（external-id 为场景键）
-node "$(cat .sdd-spec-root)/skywalk-sdd/context-client.cjs" \
-  --mode=resolve \
-  --external-system=requirement-mgmt \
-  --external-object-type=scenario \
-  --external-id="REQ-US-2026-001:SCN-user-crud-007" \
-  --space-id="$ENGINEERING_KB_SPACE_ID" \
-  --kb-id="$ENGINEERING_KB_KB_ID"
-```
-
-KB 返回 `candidates[]`，每项含 `entityId` 和 `entityVersionId`（完整 UUID，`id.cjs` 自动归一化为 8-hex）。
+脚本先读取当前正文和身份登记，再查询目标 KB 的当前版本与内容哈希，完成全部检查后才写文件：
 
-> 没有 `external-ref` 的实体（如 STMT、CON）可用 `--entity-id=<spec.md中的entity-id>` + `--entity-type=<SpecificationStatement|Constraint>` 查询。
-
-2b. 生成新 version-id：
-
-```bash
-# AC-USER-CRUD-007，KB 返回 entityId=e248ba63, entityVersionId=be5581d9
-node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" semantic-identity \
-  --delta-state=modified \
-  --entity-id=e248ba63 \
-  --predecessor-version=be5581d9
-# → 输出新的 version_id（如 3f8a1c2b）
-```
-
-2c. 更新 spec.md / proposal.md 中该实体的身份块：
-
-```markdown
-##### 场景：[AC-USER-CRUD-007] 默认分页查询
-- **entity-id**: e248ba63          ← 不变（复用 KB 的 entityId）
-- **version-id**: 3f8a1c2b         ← 改为步骤 2b 生成的新 version-id
-- **delta-state**: modified         ← 从 added 改为 modified
-- **predecessor-version**: be5581d9  ← 新增：KB 返回的 entityVersionId
-- **external-ref**: requirement-mgmt:scenario:REQ-US-2026-001:SCN-user-crud-007
-```
-
-3. **未修改的实体保持原样不动**——它们 version-id + content_hash 都没变 → KB 自动幂等跳过。不需要改为 `unchanged` 或 `modified`。
-
-4. **先校验再上传**：
-
-```bash
-# 先校验（含语义校验，确认 modified 实体身份块正确）
-node skywalk-sdd/kb-upload.cjs --validate-only --folder=<变更目录路径>
-
-# 校验通过后上传
-node skywalk-sdd/kb-upload.cjs --folder=<变更目录路径>
-```
+- 正文未变保留版本；正文改变且基线匹配时生成新版本；未发布草稿继续沿用自身版本。
+- 本地基线落后时报 `STALE_BASE_VERSION`，先比较、合并正文，不自动把最新 version-id 填成 predecessor。
+- `--anchors` 仅筛选业务锚点，不绕过内容哈希和基线检查；结构实体也参与核对。
+- 默认在线同步失败只终止这次同步，本地编写/检查/测试仍可继续。`--skip-kb-verify` 仅为显式本地维护模式，报告 `baselineVerified:false`，不能证明可发布。
+- `--dry-run` 不改 Markdown 和身份登记；`--validate-only` 可能刷新工作态，不能当作无写入预览。
+- 身份由工具维护，不让用户手工填写 UUID；脚本不可用时先保留正文和待同步事项，修复工具后再同步，不手动篡改版本链。
+- 已发布内容修改后，先同步所有受影响文件，再上传。禁止删除 ontology/artifacts 或重建身份以绕过冲突。
+- 完整 UUID 保留原值，旧短 ID 继续兼容；不得截断真实 UUID。
 
-> ⛔ **禁止**跳过步骤 1-3 直接 `kb-upload.cjs --folder`：被修改的实体 version-id 未变 + content_hash 变了 → KB 报 `VERSION_IDENTITY_CONFLICT`（错误消息含 anchorId / name / versionId，据此定位是哪个实体）。
+上传回执需分别检查事实保存、`publication_status` 和索引状态。HTTP 200 不是成功证明；多 KB 时明确本次 `--space-id` 与 `--kb-id`，不自动广播。
 
 **其他影响入库的因素**：
 

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

@@ -233,8 +233,8 @@ node skywalk-sdd/kb-upload.cjs --package=<zip-path> [--space-id=<id>] [--kb-id=<
 | `--package=<zip>` | 与 `--folder` 二选一 | 已打包的 zip 路径 |
 | `--minimum-level` | 否 | 上传最低等级：`propose-spec`（默认）/ `design` / `task` / `full` |
 | `--validate-only` | 否 | 仅校验不上传 |
-| `--space-id=<id>` | 否 | 目标 Space ID（从 kb-state.json targets[0] 读取） |
-| `--kb-id=<id>` | 否 | 目标 KB ID（从 kb-state.json targets[0] 读取） |
+| `--space-id=<id>` | 否 | 目标 Space ID；单目标可读取配置，多目标时与 --kb-id 一起显式提供 |
+| `--kb-id=<id>` | 否 | 目标 KB ID；单目标可读取配置，多目标时与 --space-id 一起显式提供 |
 
 ### project_id 解析优先级
 

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

@@ -19,6 +19,8 @@ allowed-tools:
   - Edit
 ---
 
+> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；同一会话已读则复用。用户已授权连续处理时按范围推进，不重复索要阶段口令；只请求单阶段时完成即停。
+
 # 本体知识库 · 查询
 
 只负责**查**。鉴权只用 **API Key**（`Authorization: Bearer sk_sdd_…`），**禁止**走手机号登录。
@@ -39,15 +41,15 @@ SDD 流程：Propose → Spec → Design → Task → Check → Apply → Archiv
 - 当前变更内部一致性 → **本地文件 + semantic-check**，不查 KB
 - 只有 Archive → kb-ingest 后，当前变更才进入 KB（Phase 3 验证）
 
-## Session 启动（每次用本 Skill 必做）
+## Session 启动（同一连续任务复用）
 
 > **📡 共享状态**：本技能与 `opsx-kb-ingest`、`kb-upload` **共用同一份 KB 配置**（`kb-state.json`，位于 spec 仓根目录）。KB 配置（API Key + Space/KB 选择 + project-identity.json）由 `opsx-kb-config` 统一负责。
 
 ```
 Task Progress:
 - [ ] 1. 读 kb-state.json（spec 仓根目录）
-- [ ] 2. 无 apiKey 或无 targets → 提示用户运行 /opsx-kb-config 配置知识库
-- [ ] 3. 有配置 → 按意图查询（可对多个 KB 逐个查询）
+- [ ] 2. 无 apiKey 或无 targets → 记录未配置，本地工作继续；用户明确要配置时才进入 /opsx-kb-config
+- [ ] 3. 有唯一或已明确选择的目标 → 按意图查询；多个目标未明确时先澄清本次查询范围，不默认选第一个
 - [ ] 4. 按模板输出；无命中不编造
 ```
 
@@ -75,7 +77,7 @@ Task Progress:
 
 - 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 为准
+- **KB 可用时禁止**扫描消费方本地 `archive/` 目录当跨迭代继承源；entity-id 必须来自 KB resolve by canonicalKey。KB degraded 时 archive 仅作背景参考，不自动继承身份；保留已有草稿基线，发布前再在线核对
 
 命中时关注：`resolution=LINK_EXISTING` 且 `inheritanceAllowed=true`（可继承 n）；`removedBindingCount`（已失效绑定 m）；`matchType=HISTORICAL_ONLY` 表示仅有失效绑定，不可继承。
 
@@ -103,7 +105,7 @@ scenario:    ^[A-Z0-9_-]+:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
 
 ### 命中
 1. **{displayName}**（{entityType}）@ {kbName}
-   - id / version / matchType / externalRefs（归一化形态）…
+   - 业务锚点 / 来源 / 匹配依据；完整身份保留在机器响应中
    - 若外部键命中：可继承 n / 已失效绑定 m
 ```
 

package/templates/skills/kld-sdd/opsx-ontology-query/phase-1-prechange.md

@@ -68,7 +68,7 @@ POST {base}/entities/resolve
 ### 集成点
 
 - opsx-propose §6.5：写入 proposal frontmatter `continuity` 字段
-- 禁止扫本地 `archive/` 抄 UUID（KB 可用时）；KB degraded 时 archive 作为降级手段，标注 `source: archive(degraded)`
+- 本地 archive 仅作背景参考，不能据此宣称已验证 KB current；离线保留已有草稿身份和真实前驱，发布前在线解析，不从相似标题自动继承 ID。
 
 > **Agent 行为指导**：响应中的 `clarificationQuestions` 是 AI 生成的澄清问题，Agent 应直接用 `ask_user` 呈现给用户，不要自行回答。
 > `supportEvidence` / `oppositionEvidence` 可作为决策依据向用户展示。
@@ -235,7 +235,7 @@ POST {base}/context/match-requirement
 ### 集成点
 
 - opsx-spec §3：Continuity=iteration 时必须带 `entityId` + external
-- 禁止从本地 `archive/` 抄 UUID 当跨迭代继承源（KB 可用时）；KB degraded 时 archive 作为降级手段，标注 `source: archive(degraded)`
+- 本地 archive 仅作背景参考，不能据此宣称已验证 KB current；离线保留已有草稿身份和真实前驱，发布前在线解析，不从相似标题自动继承 ID。
 
 > **Agent 行为指导**：消费 `specGenerationContext` 判断复用率——`reusableStatements` > 50% 走迭代修改，< 20% 走全新建。
 > `warnings` 和 `clarificationQuestions` 应呈现给用户，不要忽略。

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

@@ -131,7 +131,7 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/resol
 > - `supportEvidence` / `oppositionEvidence`：支持/反对决议的证据列表，Agent 可向用户展示
 > - `clarificationQuestions`：AI 生成的澄清问题，Agent 可用 `ask_user` 呈现给用户
 
-**KB 可用时禁止**用本地 `archive/` 目录当跨迭代继承源，entity-id 必须来自 KB resolve by canonicalKey。KB degraded 时 archive 可作为降级手段（标注 `source: archive(degraded)`）。
+- 本地 archive 仅作背景参考，不能据此宣称已验证 KB current；离线保留已有草稿身份和真实前驱，发布前在线解析，不从相似标题自动继承 ID。
 
 ## 按功能号圈能力（FEAT query）