kld-sdd 2.6.16 → 2.6.21

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

@@ -0,0 +1,129 @@
+# 判定标准参考
+
+## 一、问题分类
+
+首先将每个差异归类为以下四种类型之一：
+
+| 问题类型 | 说明 | 示例 |
+|---------|------|------|
+| **代码有 spec 没有（业务）** | 代码实现了业务功能但 spec 未描述 | 代码有 `/api/export` 接口但 spec 未记录 |
+| **代码有 spec 没有（技术）** | 代码实现了纯技术支撑逻辑，不涉及业务契约 | 工具方法、防御性校验、日志打印、框架样板代码、DTO 转换 |
+| **spec 有代码没有** | spec 定义了但代码未实现 | spec 定义了权限校验但代码未实现 |
+| **不一致** | 代码和 spec 都有但不匹配 | spec 定义字段 `token`，代码返回 `accessToken` |
+
+> **技术实现 vs 业务实现的区分标准**：
+>
+> 以下类别属于**纯技术实现**，不要求 spec 覆盖：
+>
+> | 类别 | 说明 | 示例 |
+> |------|------|------|
+> | 工具/基础设施代码 | 通用工具方法、辅助函数 | `DateUtils.format()`, `StringUtils.isBlank()` |
+> | 防御性代码 | 空值检查、边界保护、异常兜底 | `if (param == null) throw ...` |
+> | 日志/监控代码 | 日志打印、埋点、健康检查 | `log.info("request: {}", param)` |
+> | 框架样板代码 | 框架要求的固定结构 | Spring `@Configuration`、序列化配置 |
+> | DTO/VO 转换 | 对象拷贝、字段映射 | `BeanUtils.copyProperties()` |
+> | 配置类 | 技术配置、环境配置 | 数据库连接池、线程池配置 |
+>
+> **判断原则**：若代码行为不影响外部可观测的业务契约（接口路径、请求/响应字段、业务规则、错误码），则视为纯技术实现。
+
+## 二、置信度判定规则
+
+按以下顺序依次判定（最终置信度取最严重的结果）：
+
+**步骤 1：判断 spec 相关的问题（spec 有代码没有 / 不一致）**
+
+| 关键性 | 置信度 | 说明 |
+|--------|--------|------|
+| 关键 | **low** | 影响核心业务流程、安全、前端决策 |
+| 非关键 | **medium** | 辅助功能、非核心字段、提示性信息 |
+
+```
+示例：
+- spec 定义了核心接口 /api/orders 但代码未实现 → low（关键）
+- spec 定义了权限校验但代码未实现 → low（关键）
+- 缺少提示性错误码 → medium（非关键）
+- 前端非核心字段名与后端不一致 → medium（非关键）
+```
+
+**步骤 2：判断代码多出来的内容（代码有 spec 没有）→ 分级兜底规则**
+
+根据代码多出来的内容性质，分级处理：
+
+| 代码多出的内容 | 置信度 | 说明 |
+|--------------|--------|------|
+| **业务功能**（接口、业务逻辑、业务错误码） | **low** | 核心业务行为必须有 spec 记录 |
+| **辅助业务功能**（导出、审计、非核心扩展） | **medium** | 辅助功能建议记录但不强制 |
+| **纯技术实现**（工具方法、防御性代码、日志、框架样板、DTO 转换、配置类） | **不降级** | 技术支撑代码不要求 spec 覆盖 |
+
+此步骤用于确保业务代码实现都有对应的 spec 记录，同时避免对纯技术细节的过度管控。如果步骤 1 已判定为 low，此步骤结果也是 low，最终结果不变。如果步骤 1 是 medium，此步骤发现代码有**业务功能** spec 没有，则升级为 low。
+
+```
+示例：
+- 代码有业务接口 /api/export 但 spec 未记录 → low（业务功能）
+- 代码有权限校验逻辑但 spec 未记录 → low（业务功能）
+- 代码有错误码 400 但 spec 未记录 → low（业务功能）
+- 代码有 DateUtils.format() 工具方法但 spec 未记录 → 不降级（纯技术实现）
+- 代码有 if (param == null) throw 防御性校验但 spec 未记录 → 不降级（纯技术实现）
+- 代码有 log.info() 日志打印但 spec 未记录 → 不降级（纯技术实现）
+```
+
+**最终置信度**：取步骤 1 和步骤 2 中最严重的结果（low > medium > high）。
+
+## 三、关键性判断标准
+
+步骤 1 中需要判断差异是否"关键"，按以下标准执行（满足任一即为关键）：
+
+**关键（→ low）：**
+
+| 类别 | 说明 | 示例 |
+|------|------|------|
+| 核心业务流程 | 影响主流程的接口/逻辑 | 登录、注册、下单、支付、审批 |
+| 数据写入操作 | POST / PUT / DELETE / PATCH 操作 | 创建、编辑、删除接口 |
+| 认证与授权 | 决定用户身份和权限的逻辑 | 401→登录页、403→权限页、角色校验 |
+| 安全相关 | 防注入、防越权、敏感数据处理 | 密码加密、SQL 注入防护、数据脱敏 |
+| 前端核心决策字段 | 决定页面跳转、功能开关的字段 | token、userId、status、role |
+| 核心展示字段 | 用户可见的主要数据 | 订单金额、用户名、商品名称 |
+
+**非关键（→ medium）：**
+
+同时满足以下全部条件即为非关键：
+
+| 条件 | 说明 |
+|------|------|
+| 不影响核心业务流程 | 非主流程接口 |
+| 不影响前端核心决策 | 不决定页面跳转或功能开关 |
+| 非安全相关 | 不涉及认证、授权、数据校验 |
+| 辅助功能 | 导出、日志、审计、健康检查、监控 |
+
+**判断优先级**：当无法明确判断时，**默认视为关键**（宁可误报，不可漏报）。
+
+## 四、维度判定参考
+
+各维度的 pass/warning/fail 判定参考：
+
+| 维度 | pass | warning（→ medium） | fail（→ low） |
+|------|------|------------------|-------------------|
+| **接口契约** | 所有检查项 ✅ | 辅助接口未记录 | 接口差异；代码有**业务接口**但 spec 未记录 |
+| **业务规则** | 所有规则一致 | 非关键规则不一致 | 规则不一致；代码有**业务逻辑**但 spec 未记录 |
+| **校验规则** | 所有约束一致 | 非关键约束不一致 | 必填字段无校验；代码有**业务校验逻辑**但 spec 未记录 |
+| **错误码** | 所有错误码一致 | 非关键错误码缺失 | 错误码不一致；代码有**业务错误码**但 spec 未记录 |
+| **前后端一致性** | 所有字段匹配 | 非核心字段不匹配 | 核心字段不匹配 |
+
+> **注意**：纯技术实现（工具方法、防御性代码、日志、框架样板、DTO 转换、配置类）不影响维度判定，各维度均为 pass。
+
+## 五、示例
+
+| 场景 | 问题类型 | 关键性 | 置信度 |
+|------|---------|--------|--------|
+| 响应字段名错误（token → accessToken） | 不一致 | 关键 | **low** |
+| 缺少密码复杂度校验 | spec 有代码没有 | 关键 | **low** |
+| 代码有业务接口 /api/orders 但 spec 未记录 | 代码有 spec 没有（业务） | — | **low** |
+| 代码有权限校验逻辑但 spec 未记录 | 代码有 spec 没有（业务） | — | **low** |
+| 代码有辅助导出接口但 spec 未记录 | 代码有 spec 没有（业务） | 非关键 | **medium** |
+| spec 定义了核心接口 /api/orders 但代码未实现 | spec 有代码没有 | 关键 | **low** |
+| 缺少提示性错误码 | spec 有代码没有 | 非关键 | **medium** |
+| 前端非核心字段名与后端不一致 | 不一致 | 非关键 | **medium** |
+| 代码有 DateUtils 工具方法但 spec 未记录 | 代码有 spec 没有（技术） | — | **不降级** |
+| 代码有防御性空值校验但 spec 未记录 | 代码有 spec 没有（技术） | — | **不降级** |
+| 代码有日志打印但 spec 未记录 | 代码有 spec 没有（技术） | — | **不降级** |
+| 所有维度完美匹配 | — | — | **high** |

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

@@ -47,8 +47,8 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
+> - `openspec` 命令：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
+> - Telemetry / ontology：`node <spec-package>/skywalk-sdd/log.cjs …`（直接在包裹包内执行）；`--project=.` 指当前 spec 包裹包。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

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

@@ -17,8 +17,8 @@ allowed-tools:
 
 > **🖥️ 跨平台执行规则**
 > - **SDD 文档根** = `*-sdd-specs` 包裹包（含 `openspec/`、`modules.yaml`），不是 Git 根或工作区根。
-> - `openspec` 命令：优先 `node "$(cat .sdd-spec-root)/skywalk-sdd/openspec-shim.cjs" list`（自动 cd 到包裹包），或先 `cd` 到包裹包再执行。
-> - Telemetry / ontology：`node "$(cat .sdd-spec-root)/skywalk-sdd/log.cjs" …`（Git 根无 skywalk-sdd/）；`spec-root` 可用 `node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root`。
+> - `openspec` 命令：`cd <spec-package> && openspec …`（先 cd 到包裹包即可）。路径不确定时用 `node <spec-package>/skywalk-sdd/spec-root.cjs` 验证。
+> - Telemetry / ontology：`node <spec-package>/skywalk-sdd/log.cjs …`（直接在包裹包内执行）；`--project=.` 指当前 spec 包裹包。
 > - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
 > - ${SHELL_GUIDANCE}
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。

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

@@ -0,0 +1,185 @@
+---
+name: opsx-kb-config
+description: >-
+  Configures Engineering KB access (API Key + Space/KB selection + project-identity).
+  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:
+  author: sdd-team
+  version: "1.0"
+  source: "kb-sdd/skills/opsx-kb-config"
+allowed-tools:
+  - Bash
+  - Read
+  - 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. **已存在且一致** → 跳过，不输出
+
+> state.json 字段 schema、鉴权细节、列表接口 → [reference.md](reference.md)。
+
+## 更换知识库
+
+当用户说「换知识库 / 换 Space / 重新选择」时：
+
+1. **保留 apiKey**（不需要重新输入密钥）
+2. 清空 `state.targets`
+3. 重走 Step 3（选择空间与知识库）
+4. 重走 Step 4（更新 project-identity.json）
+
+> ⚠️ 更换 Space 后，`project_id` 会随之变化。之前上传到旧 Space 的归档包不受影响，但新上传将写入新 Space。
+
+## 查看当前配置
+
+读取 `kb-state.json` 并展示：
+
+```markdown
+### 当前 KB 配置
+- API 地址：{api}
+- 租户：{tenantKey}
+- API Key：{前缀}****（已配置 / 未配置）
+- 项目绑定：{projectName 或 未绑定}
+- 目标 Space/KB：
+  1. {spaceName}（spaceKey: {spaceKey}）→ {kbName}
+  2. ...
+- project-identity.json：{已存在 / 不存在}（project_id: {值}）
+```
+
+## 用户口令
+
+| 用户说 | 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 |
+
+## 硬规则
+
+- 无 `apiKey` 不得猜密钥、不得改走 login。
+- 无 `targets` 不得臆造 spaceId/kbId。
+- 完整 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

@@ -0,0 +1,127 @@
+# 本体知识库配置 · 参考
+
+需要鉴权细节、state 字段或 API 示例时再读。
+
+## `kb-state.json`
+
+路径：`<spec-root>/kb-state.json`（已 gitignore）。
+
+```json
+{
+  "api": "http://10.29.213.80:8080/api",
+  "tenantKey": "default",
+  "apiKey": "sk_sdd_…",
+  "projectName": "支付网关重构",
+  "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` + `archive:ingest` |
+| `projectName` | 否 | 监控项目绑定名；`null`/缺失/空白 = 未绑定，上传批次不携带 `project_name` |
+| `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` 时生效）。
+
+## `project-identity.json`
+
+路径：`<spec-root>/skywalk-sdd/project-identity.json`（**提交到 Git，团队共享**）。
+
+```json
+{
+  "schema_version": "kld-sdd-project-identity/v1",
+  "project_id": "<KB Space 的 spaceKey>",
+  "created_at": "<ISO timestamp>",
+  "kb_space_id": "<Space UUID>",
+  "kb_space_name": "<Space 名称>"
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `schema_version` | 是 | 固定 `kld-sdd-project-identity/v1` |
+| `project_id` | 是 | = 目标 Space 的 `spaceKey`，KB 入库时校验一致性 |
+| `created_at` | 是 | ISO-8601 |
+| `kb_space_id` | 建议 | Space UUID |
+| `kb_space_name` | 建议 | Space 名称 |
+
+## 鉴权
+
+```http
+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`，请用户重贴；勿循环重试。
+
+探活与校验（PowerShell 用 `Invoke-RestMethod`，**禁止** `curl`）：
+
+```powershell
+# 探活
+Invoke-RestMethod -Uri "$API/health"
+
+# 校验 API Key + 列空间
+$headers = @{ Authorization = "Bearer $API_KEY" }
+Invoke-RestMethod -Uri "$API/v1/spaces?tenantKey=$TENANT_KEY" -Headers $headers
+```
+
+## 列表接口（选择用）
+
+```bash
+# 空间
+GET $API/v1/spaces?tenantKey=$TENANT_KEY
+
+# 某空间下 KB
+GET $API/v1/spaces/{spaceId}/knowledge-bases
+```
+
+API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多空间，便于多选。
+
+### 响应字段映射（重要）
+
+KB API 返回的 JSON 字段名（Java record 序列化）与 `kb-state.json` 的字段名**不完全一致**，必须做映射：
+
+#### Space 列表 → `kb-state.json targets[]`
+
+| API 响应字段 (`ProjectSpaceDto`) | `kb-state.json` 字段 | 映射 |
+|------|------|------|
+| `spaceId` | `spaceId` | 直接使用 |
+| `spaceKey` | `spaceKey` | 直接使用 |
+| `name` | `spaceName` | **需映射** `name → spaceName` |
+
+#### KB 列表 → `kb-state.json targets[]`
+
+| API 响应字段 (`KnowledgeBaseDto`) | `kb-state.json` 字段 | 映射 |
+|------|------|------|
+| `knowledgeBaseId` | `kbId` | **需映射** `knowledgeBaseId → kbId` |
+| `name` | `kbName` | **需映射** `name → kbName` |
+
+#### Resolve 响应 → `semantic-identity` 参数
+
+| API 响应字段 (`ResolveCandidate`) | `semantic-identity` 参数 | 注意 |
+|------|------|------|
+| `entityId` | `--entity-id` | KB 返回完整 UUID（36字符），`semantic-identity` 的 `id.cjs` 会自动归一化为 8-hex 短格式 |
+| `entityVersionId` | `--previous-version-id` | 同上，自动归一化 |
+
+> ⚠️ **常见错误**：直接用 `k.kbId` / `k.kbName` 读取 KB API 响应 → 返回空值。正确写法：`k.knowledgeBaseId` / `k.name`，然后映射到 `kb-state.json` 的 `kbId` / `kbName`。