kld-sdd 2.6.16 → 2.6.17

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,164 @@
+---
+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 |
+| 查看当前配置 | 展示已配置的 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`。
+
+### 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：{前缀}****（已配置 / 未配置）
+- 目标 Space/KB：
+  1. {spaceName}（spaceKey: {spaceKey}）→ {kbName}
+  2. ...
+- project-identity.json：{已存在 / 不存在}（project_id: {值}）
+```
+
+## 用户口令
+
+| 用户说 | Agent 做 |
+|--------|----------|
+| 配置知识库 / 首次使用 | 走完 Step 1→2→3→4 |
+| 换密钥 / 重置 API Key | 清 apiKey，重走 Step 2 |
+| 换空间 / 换知识库 / 重新选择 | 清 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,116 @@
+# 本体知识库配置 · 参考
+
+需要鉴权细节、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_…",
+  "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` |
+| `targets` | 操作前必填 | 多选；可为空仅当尚未完成选择 |
+| `updatedAt` | 建议 | ISO-8601 |
+
+## `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**（查询和入库都需要）。
+- 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`。

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

@@ -9,59 +9,28 @@ description: >-
 
 # 本体知识库 · 入库
 
-只负责**入库**（zip 上传）。鉴权只用 **API Key**（`Authorization: Bearer sk_sdd_…`），**禁止**走手机号登录。
+只负责**入库**（zip 上传 + 文件夹上传）。鉴权只用 **API Key**（`Authorization: Bearer sk_sdd_…`），**禁止**走手机号登录。
 
 > 控制台知识库页另有浮动 Ontology Agent（会话登录 + SSE）；本 Skill 仍走 API Key，二者分开。
 
-> **📡 共享状态**：本技能与 `opsx-ontology-query` **共用同一份 KB 配置**（`../.shared/kb-state.json`）。任一 skill 配置后，另一个自动可用，无需重复输入 API Key。
+> **📡 共享状态**：本技能与 `opsx-ontology-query`、`kb-upload` **共用同一份 KB 配置**（`kb-state.json`，位于 spec 仓根目录）。KB 配置（API Key + Space/KB 选择 + project-identity.json）由 `opsx-kb-config` 统一负责。
+
+> **🖥️ 跨平台执行规则**（Windows 用户必读）:
+> - 入库涉及 HTTP 请求和 JSON 文件读写，**禁止**在 PowerShell 中使用 `curl` → 用 `Invoke-RestMethod` 或 Node.js 脚本（`kb-upload.cjs` 已封装）
+> - **禁止**用 PowerShell `Get-Content` / `Out-File` 读写 JSON（默认写 BOM 导致 JSON.parse 失败）→ 用 write_to_file 工具或 Node.js `fs` 模块
+> - **禁止** `| cat` 管道 → 直接执行命令
 
 ## Session 启动（每次用本 Skill 必做）
 
 ```
 Task Progress:
-- [ ] 1. 读 ../.shared/kb-state.json（没有则当空）
-- [ ] 2. 无 apiKey → 向用户索取并写入共享 state（勿把完整 key 打进聊天摘要）
-- [ ] 3. 无 targets 或用户要重置 → 拉空间/KB 列表，让用户多选后写入
-- [ ] 4. 按意图执行入库操作（上传 / 查状态 / 列表 / 重试）
-- [ ] 5. 按模板输出结果
+- [ ] 1. 读 kb-state.json（spec 仓根目录）
+- [ ] 2. 无 apiKey 或无 targets → 提示用户运行 /opsx-kb-config 配置知识库
+- [ ] 3. 有配置 → 按意图执行入库操作（上传 / 查状态 / 列表 / 重试）
+- [ ] 4. 按模板输出结果
 ```
 
-### 1–2. API Key
-
-若 `state.apiKey` 为空或无效（401/403）：
-
-1. 请用户提供 API Key（控制台「API 密钥」创建，至少含 `archive:ingest`。建议同时勾选 `context:read`，使 `opsx-ontology-query` 也能复用此 Key）。
-2. 可选：请用户确认 `api`（默认 `http://localhost:8090/api`）与 `tenantKey`（默认 `default`）。
-3. 写入共享 `../.shared/kb-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 执行上传。
-
-### 3.5 兜底：确保 project-identity.json 存在（上传前必做）
-
-> 正常情况下 `project-identity.json` 已在 `opsx-ontology-query` 首次配置 KB 时创建。
-> 本步是兜底：如果用户跳过了 ontology-query（如选择 archive 降级路径），直接来做入库，需要确保文件存在且 `project_id` 正确。
-
-1. 读取 spec 包裹包路径：
-   ```bash
-   SPEC_ROOT=$(node "$(cat .sdd-spec-root)/skywalk-sdd/ontology/cli.cjs" spec-root)
-   ```
-2. 检查 `$SPEC_ROOT/skywalk-sdd/project-identity.json`：
-   - **不存在** → 从 `targets[0].spaceKey` 创建（格式同 `opsx-ontology-query` Step 3.5）
-   - **已存在但 `project_id !== targets[0].spaceKey`** → 提示用户：`⚠️ project_id 与 Space spaceKey 不一致，入库将报 PROJECT_SPACE_MISMATCH。是否更新？`
-   - **已存在且一致** → 跳过
+> **KB 配置**（API Key、Space/KB 选择、project-identity.json）由 `opsx-kb-config` 统一负责。如用户需要配置或更换 KB，请引导运行 `/opsx-kb-config`。
 
 ### 4. 入库操作
 
@@ -122,11 +91,195 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JO
 - 包内无重复 `(external key, entity_id)` 绑定对
 - `project_id` / `spaceKey` 既有规则保留
 - **编号格式**：三条正则（见 reference）+ 场景 SLUG≤40 / 键总长≤120；先归一化再匹配
-- **场景作用域**：scenario 键的 REQ 前缀必须出现在同包 requirement 绑定集合
+- **场景作用域**：scenario 键的需求编号前缀必须出现在同包 requirement 绑定集合
 - **功能配对**：同实体每条 feature 绑定必须能与某 requirement 条目的 `feature_id` 精确配对；反向同理
 
 详细字段说明 → [reference.md](reference.md)。
 
+### 4.5 文件夹上传（支持随时入库）
+
+支持直接传入 SDD 变更目录，自动完成语义校验、元数据生成、打包上传。**不要求 SDD 流程全部走完**，任意阶段均可入库。
+
+**用法**：
+
+```bash
+# 仅校验（不上传）
+node skywalk-sdd/kb-upload.cjs --validate-only --folder=<变更目录路径> [--minimum-level=propose-spec]
+
+# 文件夹上传（自动跑语义管线 + 生成元数据 + 打包 zip + 上传）
+node skywalk-sdd/kb-upload.cjs --folder=<变更目录路径> [--minimum-level=propose-spec]
+
+# zip 包上传（兼容现有方式）
+node skywalk-sdd/kb-upload.cjs --package=<zip 路径>
+```
+
+#### 上传等级（`--minimum-level`）
+
+| 等级 | 最低要求 | 入库内容 | 适用场景 |
+|------|---------|----------|---------|
+| `propose-spec`（默认） | proposal.md + spec.md | Change、Capability、STMT、AC、Constraint | 需求定义阶段入库 |
+| `design` | + design.md | + DesignElement | 补充技术方案 |
+| `task` | + tasks.md | + Task、TaskDependency | 补充任务拆解 |
+| `full` | 全部 4 个 | 全部实体 | 完整归档 |
+
+#### 前置校验规则
+
+- 校验必需文件存在（按 `--minimum-level` 决定）
+- 校验 `project-identity.json` 存在且 `project_id === spaceKey`（本地预检，避免上传后报 `PROJECT_SPACE_MISMATCH`）
+- 若 `project-identity.json` 不存在 → 提示运行 `/opsx-kb-config` 配置知识库
+
+#### 重新入库前：KB 身份同步（重要）
+
+当 Change 的 proposal.md / spec.md / design.md / tasks.md **内容被修改后重新上传**（KB 中已存在同 entity-id 的实体），需要更新被修改实体的身份元数据（delta-state + version-id + predecessor-version），否则 KB 会拒绝（`VERSION_IDENTITY_CONFLICT`：同 version-id 但 content_hash 不同）。
+
+> **KB 入库原理**：对每个实体执行 `INSERT … ON CONFLICT (entity_version_id) DO NOTHING`。若 version-id 已存在且 entity-id + content_hash 一致 → 幂等跳过 ✅；若 content_hash 不同 → `VERSION_IDENTITY_CONFLICT` ❌。因此，**未修改的实体不需要动**——它们 version-id + content_hash 都没变 → KB 自动幂等跳过。
+
+> **语义校验**：`kb-upload.cjs --folder` 在上传前运行 `reconcileChange()` 语义校验。当本地无 confirmed archive（单变更场景）时，语义校验跳过基于历史的 lineage 检查，`modified` 实体只需提供合法的 `predecessor-version`（来自 KB resolve）即可通过。
+
+**判断是否为重新入库**（满足任一即为重新入库）：
+
+- spec.md / proposal.md 身份块中已有 `entity-id` + `version-id`（说明之前已分配过身份）
+- 上次 `kb-upload.cjs --folder` 返回 `succeeded`（KB 中已有该实体）
+- 上传返回 `VERSION_IDENTITY_CONFLICT`（错误消息含 anchorId / name / versionId）
+
+**重新入库步骤**（只针对**被修改的实体**）：
+
+> **⚠️ 文档实体也需要同步**：修改 .md 文件内容时，需同步**两类**实体：
+> 1. **结构实体**（Artifact / DocumentSection）— 存储在 `ontology/ontology-identities.json` 中，由 reconcile 管理
+> 2. **业务实体**（STMT / AC / CON / CAP）— 身份块写在 markdown 中
+>
+> 常见错误：只同步了业务实体（AC/STMT），遗漏了结构实体（文档 Artifact）→ KB 报 `VERSION_IDENTITY_CONFLICT`。
+
+**方式 A：自动同步（推荐）**
+
+```bash
+# 自动扫描 content_hash 变化，同步所有变更的结构实体 + 内容有变化的业务实体
+# （内容驱动模式：只同步 content_hash 真正变化的实体，不污染未变实体）
+node skywalk-sdd/kb-sync-identity.cjs \
+  --file=spec.md \
+  --change=<change-key> \
+  --project=.
+
+# 或精准指定变更的业务实体锚点（用户明确知道改了哪些 AC/STMT/CON）
+node skywalk-sdd/kb-sync-identity.cjs \
+  --file=spec.md \
+  --change=<change-key> \
+  --project=. \
+  --anchors=AC-USER-CRUD-006
+
+# 干跑模式（只看报告不修改文件）
+node skywalk-sdd/kb-sync-identity.cjs \
+  --file=spec.md \
+  --change=<change-key> \
+  --project=. \
+  --dry-run
+
+# 跳过 KB 验证（KB 不可用时强制本地同步，风险：predecessor 可能不匹配 KB）
+node skywalk-sdd/kb-sync-identity.cjs \
+  --file=spec.md \
+  --change=<change-key> \
+  --project=. \
+  --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）。
+
+> 没有 `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=<变更目录路径>
+```
+
+> ⛔ **禁止**跳过步骤 1-3 直接 `kb-upload.cjs --folder`：被修改的实体 version-id 未变 + content_hash 变了 → KB 报 `VERSION_IDENTITY_CONFLICT`（错误消息含 anchorId / name / versionId，据此定位是哪个实体）。
+
+**其他影响入库的因素**：
+
+| 因素 | 说明 | 是否需 Agent 处理 |
+|------|------|-------------------|
+| `archive_id` | `kb-upload.cjs` 每次自动生成新的 | ❌ 自动处理 |
+| `project_id` | 必须匹配 Space 的 `spaceKey`，前置校验已拦截 | ❌ 已校验 |
+| `external-ref` 冲突 | 同 external-key 已绑不同 entity-id → `EXTERNAL_REF_CONFLICT` | ✅ 见下文错误处理 |
+| `ARCHIVE_IMMUTABILITY_VIOLATION` | 同一 archive_id 上传不同 content_hash | ❌ 不会发生（每次新 archive_id） |
+| 多个实体同时修改 | 每个被修改的实体都需步骤 2 | ✅ 对每个分别处理 |
+
+#### 文件夹上传 vs Zip 上传
+
+| 维度 | 文件夹上传 | Zip 上传 |
+|------|-----------|---------|
+| 输入 | 原始变更目录 | 已打包 zip |
+| 语义管线 | 自动执行（semantic-scan → reconcile → check） | 无需（zip 已含元数据） |
+| 元数据生成 | 自动生成（archive-manifest + canonical-facts + conversion-report） | 无需（zip 已含） |
+| 适用场景 | 任意 SDD 阶段入库 | 已有 zip 补传 / 归档后上传 |
+
+> 文件夹上传最终也会打包成 zip 走同一上传接口，KB 后端解析逻辑不变。
+
 ### 5. 输出模板
 
 ```markdown
@@ -149,11 +302,23 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JO
 
 成功时展示 `report.externalRefsWritten`。冲突**不**出现在成功模板。
 
+若 `errorCode=VERSION_IDENTITY_CONFLICT`（version-id 与 KB 已锁定版本冲突）：
+
+1. 错误消息中包含 `anchorId`、`name`、`entityId`、`versionId`，据此**定位是哪个实体**被修改后未更新身份。
+2. 按「重新入库前：KB 身份同步」步骤操作：对该实体查询 KB → 生成新 version-id → 更新 delta-state=modified + predecessor-version → 重新上传。
+3. **只需处理该实体**，其余未修改实体不用动（KB 自动幂等跳过）。
+
+若语义校验阶段报 `SEM_VERSION_LINEAGE_MISSING`（`modified` 实体无法定位前序版本）：
+
+1. 说明本地存在 confirmed archive（如通过 SDD archive 流程归档的其他变更），但 markdown 中 `predecessor-version` 与 archive 中的 version-id 不匹配。
+2. 检查 `predecessor-version` 是否来自 KB resolve 返回的 `entityVersionId`（而非手写）。
+3. 按「重新入库前：KB 身份同步」步骤 2a 重新查询 KB，确认 `entityVersionId`，然后重新生成 version-id 并更新身份块。
+
 若 `errorCode=EXTERNAL_REF_CONFLICT`（整包已回滚）：
 
 1. 展示 `report.details`（externalRef / anchor / existingEntityId / incomingEntityId）。
 2. 向用户给出两个修正选项：
-   - **复用历史身份**：回到 kld-sdd，复用 KB 中原有 entity_id / current version，重新 check → 归档 → 入库
+   - **复用历史身份**：按「重新入库前：KB 身份同步」步骤——查询 KB 获取已有 entity-id 和 version-id，更新 delta-state=modified + predecessor-version，重新上传
    - **改为新锚点**：回到 kld-sdd，分配新锚点与新 entity_id，重新 check → 归档 → 入库
 3. **禁止**在 KB 内现场改绑或解绑。
 
@@ -161,8 +326,8 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JO
 
 | errorCode | 指引 |
 |-----------|------|
-| `EXTERNAL_REFERENCE_FORMAT_INVALID` | 编号不合规 → **回需求管理系统换发**；不得手改编号硬闯 |
-| `EXTERNAL_REFERENCE_SCOPE_MISMATCH` | 场景键 REQ 前缀不在申报集合 → 回 kld-sdd spec 修正 external-ref |
+| `EXTERNAL_REFERENCE_FORMAT_INVALID` | 编号含非白名单字符 → **检查外部编号来源**；不得手改编号硬闯 |
+| `EXTERNAL_REFERENCE_SCOPE_MISMATCH` | 场景键需求编号前缀不在申报集合 → 回 kld-sdd spec 修正 external-ref |
 | `EXTERNAL_REFERENCE_FEATURE_UNBOUND` | feature↔requirement.`feature_id` 配对断裂 → 回 propose/archive 修正线缆字段 |
 
 **禁止**手改包内编号绕过门禁。
@@ -173,18 +338,17 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JO
 - 无 `targets` 不得臆造 spaceId/kbId。
 - 上传前确认 zip 包路径存在且为有效 zip 文件。
 - 入库失败时展示 `errorCode` 和 `errorMessage`，不编造原因。
-- 完整 apiKey 只写共享 state 文件（`../.shared/kb-state.json`）；聊天里最多显示前缀（如 `sk_sdd_****`）。
+- 完整 apiKey 只写共享 state 文件（`kb-state.json`，spec 仓根目录）；聊天里最多显示前缀（如 `sk_sdd_****`）。
 - 401/403 时清掉 `apiKey`，请用户重贴；勿循环重试。
-- **共享状态**：state 文件与 `opsx-ontology-query` 共用。如用户此前已通过查询 skill 配置过 KB，本 skill 启动时直接读取已有配置，无需重复询问。
+- **共享状态**：state 文件与 `opsx-ontology-query`、`kb-upload`、`opsx-kb-config` 共用。KB 配置由 `opsx-kb-config` 统一负责。
 
 ## 用户口令
 
 | 用户说 | Agent 做 |
 |--------|----------|
-| （首次使用） | 要 key → 选 KB（多选）→ 写共享 state → 再操作。此后 `opsx-ontology-query` 也自动可用 |
-| 换密钥 / 重置 API Key | 清 apiKey，重走第 2 步 |
-| 重新选择 / 重置空间或知识库 | 清 targets，重走第 3 步 |
-| 上传 / 入库 | 用当前共享 targets 中选中的 KB 上传 zip |
+| 配置 / 换密钥 / 换 KB | 引导运行 `/opsx-kb-config`（本技能不处理配置） |
+| 上传 zip / 入库 | 用当前共享 targets 中选中的 KB 上传 zip |
+| 文件夹上传 / 随时入库 | 运行 `kb-upload.cjs --folder=<path>`，自动打包上传 |
 | 查状态 / 看任务 | 用 jobId 查询任务状态 |
 | 列任务 / 看历史 | 列出最近入库任务 |
 | 重试 | 对失败的 jobId 执行重试 |
@@ -192,6 +356,7 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JO
 ## 心智模型（简述）
 
 - 入库是同步操作：上传后后端立即解析 zip、校验、写入数据库，返回最终 job 状态。
+- 投影是异步操作：入库成功后，后端异步执行 vector embedding + AGE graph 投影（通常 5-30 秒）。正常 SDD 流程中，阶段间由用户手动触发，间隔远大于投影时间，无需特殊处理。
 - 幂等机制：同一 `archive_id` + `content_hash` 重复上传会命中幂等，不重复写入。
 - `archive_id` 不可变：同一 `archive_id` 上传不同 `content_hash` 会被拒绝（`ARCHIVE_IMMUTABILITY_VIOLATION`）。
 - `project_id` 必须匹配：zip 包 manifest 中的 `project_id` 必须等于目标 Space 的 `spaceKey`。