kld-sdd 2.8.1 → 2.8.2

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

@@ -16,202 +16,42 @@ allowed-tools:
   - Write
   - Edit
 ---
-# 本体知识库 · 配置
 
-只负责**配置**。一次配置，查询（opsx-ontology-query）、入库（opsx-kb-ingest）、文件夹上传（kb-upload）全部可用。
+> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；遵守用户授权范围，用户只请求单阶段时完成即停，不重复请求阶段口令。
 
-> **📡 共享状态**：配置写入 `kb-state.json`（**唯一权威位置 = spec 包裹包根目录**），所有 KB 技能共用。任一技能配置后，其他技能自动可用，无需重复输入。
+# 配置 Spec 知识库
 
-> **🖥️ 跨平台执行规则**（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` 清理
+<!-- KB_CONFIG_CONTRACT: team-personal-direct-v1 -->
 
-## 能做什么
+优先复用托盘已保存的配置。只有缺少连接、权限或用户明确要求更改时才询问配置。
 
-| 场景 | 说明 |
-|------|------|
-| 首次配置 | 输入 API Key → 选择 Space/KB → 创建 project-identity.json |
-| 更换 API Key | 清空 apiKey，重新输入并验证当前目标权限 |
-| 更换知识库 | 清空 targets，重新选择 Space/KB |
-| 指定上传知识库 | 从已选知识库中指定唯一的 Spec 写入位置；查询范围仍可多选 |
-| 查看当前配置 | 展示已配置的 Space/KB 列表与团队项目身份 |
-| 校验配置 | 探活 API + 校验 project_id 与 spaceKey 一致 |
+## 读取
 
-## 配置步骤
+确定实际关联的 Spec 根目录，通过 `skywalk-sdd/lib/kb-config.cjs` 的 `readProjectConfig(specRoot)` 读取。返回 `config` 是有效配置、`personal` 是个人原文、`team` 是团队原文、`revision` 用于并发保存。不得绕过它直接读取个人文件覆盖团队设置。不要在聊天里回显 config.apiKey。
 
-### 1. 读取共享状态
+- `kb.config.json`：仅 schemaVersion、api、targets、uploadTarget，随 Git 共享。
+- `kb-state.json`：个人 Key、个人补充读取库和原有个人字段，不提交 Git。
+- 旧项目只有 kb-state.json 时继续可用，选择团队共享后再迁移。
+- `targets` 可多选用于读取；`uploadTarget` 只指定一个上传知识库，必须在读取范围内。`uploadTarget` 只决定写入位置，不缩小查询可用的 `targets`。
+- 团队服务地址改变会使原个人 Key 失效；请重新登录获取适用于新地址的 Key。
 
-```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 工具读取该文件
-```
+## 保存
 
-#### 1.1 位置校验（写入前必做）
-
-`kb-state.json` 的**唯一权威位置是 spec 包裹包根目录**（`$SPEC_ROOT/kb-state.json`）。
-本步骤在**任何写入之前**执行，防止把配置写到错误位置 —— 一旦写偏，
-后续所有 KB 技能都读不到。
-
-校验两件事，任一不通过则**停止写入**并提示用户：
-
-1. **`SPEC_ROOT` 必须是 spec 包裹包根**。用统一判据（与 `lib/shared.cjs#isKbStateHostDir`
-   同源，即 `ontology/resolve-spec-root.cjs#isSpecPackageRoot`）：
-   目录名匹配 `*-sdd-specs`，或四结构齐全
-   （`modules.yaml` + `sdd.config.yaml` + `openspec/changes` + `openspec/specs/overview.md`），
-   或至少含 `openspec/`。
-   ```bash
-   # 临时脚本：const shared = require('<SPEC_ROOT>/skywalk-sdd/lib/shared.cjs');
-   #           console.log(shared.isKbStateHostDir(process.argv[1]));
-   node _tmp-check-host.cjs "$SPEC_ROOT"
-   ```
-   输出 `false` → 报错：`SPEC_ROOT 不是 spec 包裹包根，禁止写入 kb-state.json`，
-   并让用户确认 `--project` / `.sdd-spec-root` 是否指向 `*-sdd-specs`。
-
-2. **写入路径必须由 `$SPEC_ROOT` 直接拼接**：`"$SPEC_ROOT/kb-state.json"`。
-   禁止使用 `../`、`.shared/`、`<ide>/skills/` 等相对偏移构造路径。
-
-> 读取侧由 `lib/shared.cjs#loadKbState` 执行同样的位置校验：只接受宿主目录为
-> spec 包裹包根的命中。因此若本步校验通过而后续仍报「KB 未配置」，
-> 优先检查是否写到了非 `$SPEC_ROOT` 的位置。
-
-### 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：说明 scope/目标访问权不足。两者均**不**自动清空可能对其他目标仍有效的密钥，不循环重试。
-- **不要** `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 }, …]`。
-5. `targets` 只有一个时，自动把它写入 `uploadTarget: { spaceId, kbId }`；有多个时，
-   让用户从已选列表中指定一个“Spec 上传知识库”，再写入 `uploadTarget`。
-   `uploadTarget` 只决定写入位置，不缩小查询可用的 `targets`。
-
-> 更新 `targets` 时必须同时校验 `uploadTarget`：它仍在列表中则保留；已被取消选择则清空并
-> 立即让用户重新指定，禁止默选新的首项。旧版单目标配置没有 `uploadTarget` 时继续兼容，
-> 入库器会使用唯一目标；旧版多目标配置必须补选后才能上传。
-
-> **API 返回字段说明**（临时脚本中注意字段名）：
-> - Space 列表返回 `spaceId`（camelCase），不是 `id`。临时脚本中使用 `s.spaceId || s.id` 兼容。
-> - Space 列表返回 `spaceKey`（项目标识，非 UUID），用于 `project-identity.json` 的 `project_id`。
-> - KB 列表返回 **`knowledgeBaseId` + `name`**，不是 `kbId`/`kbName`；需映射后写入 state。详见 [reference.md](reference.md#响应字段映射重要)。
-
-### 4. 写入项目身份文件（首次配置 Space 后必做）
-
-> `project-identity.json` 是 spec 仓 Git 中的**团队共享**文件，记录 `project_id`（= **该 spec 仓所属项目** 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. **不存在** → 用 AskUserQuestion 询问「**哪个 Space 拥有此 spec 仓**」。
-   **不得用 `targets` 列表顺序推断** —— 多个查询目标可能属于不同 Space，
-   拥有此 spec 仓的项目未必是第一个。用户指认后创建：
-   ```json
-   {
-     "schema_version": "kld-sdd-project-identity/v1",
-     "project_id": "<用户指认 Space 的 spaceKey>",
-     "created_at": "<ISO timestamp>",
-     "kb_space_id": "<该 Space spaceId>",
-     "kb_space_name": "<该 Space spaceName>"
-   }
-   ```
-   输出：`✓ 已创建 skywalk-sdd/project-identity.json（project_id: <spaceKey>），请提交到 spec 仓 Git 以便团队共享`
-4. **已存在且与用户本次指认的 Space 一致** → 保留，不输出
-5. **已存在但用户本次指认了不同 Space** → 该 Space 仅作为**只读查询目标**，
-   **不改写 `project_id`**。切换查询连接不是改写团队身份的理由；
-   若用户确实要把已有事实/历史包迁移到其他 Space/KB，属于另一个明确任务 ——
-   不能仅改 project_id、manifest 或 targets 冒充迁移完成
-
-### 5. 校验配置（保存后执行）
-
-1. `targets` 可保存多个查询目标；查询时按用户本次意图逐个选择并保留来源。
-   上传和入库身份同步默认读取 `uploadTarget`，无需每次重新询问或拼接 `--space-id`、`--kb-id`。
-   用户明确要求临时改投其他目标时，才用成对参数覆盖。任何场景都不默选首项、不自动广播。
-2. 对本次目标运行 `context-client.cjs --check-only`，说明可达性、权限与检索通道状态。
-   断连仍允许本地编写、测试和归档，远程基线核对与正式发布保持未完成。
-
-可用目标只有一个且信息完整时，不添加确认步骤。多目标查询可沿用本轮用户已明确的选择；
-上传目标必须持久化为 `uploadTarget`，供 Skill 和 `kb-upload.cjs` 在后续会话中直接读取。
-
-## 团队项目身份
-
-`skywalk-sdd/project-identity.json` 随 spec 仓提交 Git，`project_id` 必须等于**该 spec 仓所属项目** Space 的 `spaceKey`。
-
-- 文件不存在：为用户已选定的业务项目创建身份。多个查询目标属于不同 Space 时，先明确哪个项目拥有此 spec 仓；不能用目标列表顺序推断。
-- 文件存在且项目一致：保留。
-- 文件存在但选择了不同项目：可以作为只读查询目标，**不能因为切换查询连接就改写团队身份**。已有事实/历史包迁移到其他 Space/KB 属于另一个明确任务，不能仅改 project_id、manifest 或 targets 冒充迁移完成。
-- 一个 Space 下的多个 KB 也分别选择。既有实体身份不能靠原包复制到另一 KB；跨库复用需确认事实归属并按正常流程建立目标身份。
-
-创建字段与 API 映射见 [reference.md](reference.md)。机器身份保留完整 UUID；人阅读使用锚点与业务名称，不能截短远程返回的实体或版本 ID。
-
-## 更换配置与失败处理
-
-- 换密钥：只替换密钥并验证当前目标权限，保留 targets 与团队身份。
-- 换 Space/KB：更新用户指定的连接目标，再核对查询权或入库项目一致性；不清空所有已有连接或自动改写身份。
-- 401：停止本次远程操作，提示验证密钥；403：说明 scope/目标访问权不足。两者均不自动清除可能仍对其他目标有效的密钥，不循环重试。
-- 网络不可用：保留配置，报告原因；可选查询失败不阻止本地流程。不能把不可用报告成“没有事实”或“已完成入库”。
-- 当前七种 Skill 使用统计按本机 Git 身份上报，独立于 Spec 入库。本配置流程无需填写监控项目或访问旧 `/sdd-runs/dimensions`。历史 `projectName` 字段可保留兼容，不作为当前使用统计或业务归属依据。
-
-## 查看当前配置
-
-读取 `kb-state.json` 与 `project-identity.json` 并展示：
-
-```markdown
-### 当前 KB 配置
-- API 地址：{api}
-- 租户：{tenantKey}
-- API Key：{前缀}****（已配置 / 未配置）
-- 目标 Space/KB：
-  1. {spaceName}（spaceKey: {spaceKey}）→ {kbName}
-  2. ...
-- Spec 上传知识库：{spaceName} → {kbName / 未指定}
-- project-identity.json：{已存在 / 不存在}（project_id: {值}）
-- 授权/就绪：{context-client.cjs --check-only 结果}
-```
+调用 `saveProjectConfig(specRoot, effectiveConfig, {revision, team})`。保留已有有效字段，只合并用户明确提供的改动。只有用户明确选择共享地址和知识库选择时 team=true；否则 team=false。团队文件存在时，个人保存不能修改团队地址和上传库。
+
+所有密钥只落个人文件，公共文件只写白名单字段。解析器自动加入个人文件和本地入库记录的 Git 忽略规则。项目身份绑定由上传预检负责，已有身份不允许静默改绑。
 
-密钥仅显示“已配置”或脱敏前缀。
+没有 API Key 时推荐用户在托盘登录知识库，按名称多选读取库、单选上传库，连接并保存。不能让用户手工寻找 Space/KB UUID，除非其明确要求手动配置。
 
-## 文件与跨平台执行
+## 验证
+
+```bash
+node <spec-root>/skywalk-sdd/kb-upload.cjs --project=<spec-root> --check-config
+node <spec-root>/skywalk-sdd/context-client.cjs --check-only
+```
 
-- **位置唯一**：`kb-state.json` 只写 `<spec-root>/kb-state.json`（Step 1.1 校验通过后）。
-  禁止写 `.shared/`、`<ide>/skills/` 或任何非 spec 根位置。
-- `kb-state.json` 不提交 Git，校验 `.gitignore`；项目身份文件提交 Git。
-- 通过客户端文件工具或 Node.js 写 UTF-8 JSON，无 BOM，并原子替换；勿用 PowerShell 默认编码直接覆盖。
-- PowerShell 的 `curl` 可能是别名，HTTP 用 `Invoke-RestMethod` 或 Node.js；复杂 Node 逻辑写临时 `.cjs` 文件，避免 shell 内联转义。
+配置检查不上传文档。连接失败要说明未验证远端能力，本地 SDD 仍可使用。不得把服务异常当作配置成功。
 
-## 硬规则
+详细 API 结构见 [reference.md](reference.md)。其原始文件示例仅适用于没有团队配置的旧项目；有团队配置必须使用上述解析器保存。
 
-- 无 `apiKey` 不得猜密钥、不得改走 login；不调用 `/auth/login` 换取另一身份。
-- 无 `targets` 不得臆造 spaceId/kbId；不猜目标 ID。
-- 多个 `targets` 且无有效 `uploadTarget` 时不得上传，也不得使用 `targets[0]` 代替用户选择。
-- 完整 apiKey 只写共享 state 文件（`kb-state.json`，spec 仓根目录）；聊天里最多显示前缀。
-- **共享状态**：state 文件与 `opsx-ontology-query`、`opsx-kb-ingest`、`kb-upload` 共用。配置一次，全部生效。
+禁止直接使用 `targets[0]` 选择上传库，必须采用保存的 uploadTarget。

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

@@ -1,8 +1,13 @@
+
+<!-- KB_CONFIG_CONTRACT: team-personal-direct-v1 -->
+> **配置统一入口（优先于下文历史 API 示例）**：调用 `skywalk-sdd/lib/kb-config.cjs` 的 `readProjectConfig(specRoot)` 获取有效配置。`kb.config.json` 是可提交 Git 的团队地址、读取范围和上传位置；`kb-state.json` 只保存个人 Key 和个人补充读取范围，必须忽略 Git。团队配置存在时不能直接读取/改写个人文件来覆盖团队选择。保存通过 `saveProjectConfig(root, config, {team:true/false, revision})`，仅明确修改团队公共选项时传 team:true。禁止回显 Key。
+> 日常上传直接运行 `node <spec-root>/skywalk-sdd/kb-ingest.cjs --project=<spec-root> --change=<change目录名>`；列出状态用 `--list`。脚本读取本地 Markdown，生成本体 JSON 并直接上传，不生成 ZIP、不依赖 AI、不要求先归档。不重复传 Space/KB 参数，不直接发裸上传 HTTP。旧 ZIP 仅供已有归档包兼容。
+
 # 本体知识库配置 · 参考
 
 需要鉴权细节、state 字段或 API 示例时再读。
 
-## `kb-state.json`
+## 旧项目单文件格式示例（未启用团队共享）
 
 路径：`<spec-root>/kb-state.json`（已 gitignore）。
 
@@ -98,7 +103,7 @@ GET $API/v1/spaces?tenantKey=$TENANT_KEY
 GET $API/v1/spaces/{spaceId}/knowledge-bases
 ```
 
-API Key 的可见范围以实际授权结果为准，可被限制到特定 Space；不能因为配置多个 targets 就认为已获得各目标权限。查询目标按本次意图明确选择；上传默认读取 `uploadTarget`，只有临时覆盖时才同时传 `--space-id` 与 `--kb-id`。
+API Key 的可见范围以实际授权结果为准，可被限制到特定 Space；不能因为配置多个 targets 就认为已获得各目标权限。查询目标按本次意图明确选择；上传默认读取 `uploadTarget`，只有用户明确临时改投时才同时传 `--space-id`、`--kb-id` 与 `--override-upload-target`。
 
 ### 响应字段映射（重要）
 

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

@@ -1,312 +1,62 @@
 ---
 name: opsx-kb-ingest
 description: >-
-  Uploads knowledge archive packages (zip) to the Engineering KB via API Key
-  (archive:ingest scope). Prompts for API key and multi-selects spaces/KBs into
-  local skill state. Supports upload, job status query, job list, and retry.
-  Use when ingesting new or updated knowledge archives into the ontology KB.
+  Uploads selected local Spec Change documents directly as JSON to the Spec ontology KB.
+  Uses shared team settings and a local API Key, detects unchanged and updated content,
+  and prevents overwriting a newer team version. Existing ZIP archives remain compatible.
 ---
 
-> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；同一会话已读则复用。用户已授权连续处理时按范围推进，不重复索要阶段口令；只请求单阶段时完成即停。
+> **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；遵守用户授权范围，用户只请求单阶段时完成即停，不重复请求阶段口令。
 
-# 本体知识库 · 入库
+# Spec 知识库入库
 
-只负责**入库**（zip 上传 + 文件夹上传）。鉴权只用 **API Key**（`Authorization: Bearer sk_sdd_…`），**禁止**走手机号登录。
+<!-- KB_CONFIG_CONTRACT: canonical-upload-v2 -->
+<!-- KB_CONFIG_CONTRACT: team-personal-direct-v1 -->
 
-> 控制台知识库页另有浮动 Ontology Agent（会话登录 + SSE）；本 Skill 仍走 API Key，二者分开。
+把用户选定的本地 Spec Change 直接上传到知识库，让后续需求能够复用业务对象、场景和规则。普通入库不需要 AI 分析、ZIP 打包或先完成归档。
 
-> **📡 共享状态**：本技能与 `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` 管道 → 直接执行命令
+1. 找到当前项目实际关联的 Spec 根目录；多仓共用同一个 Spec 时只在这个根目录操作。
+2. 用户没有指定 Change 时，运行 `node <spec-root>/skywalk-sdd/kb-ingest.cjs --project=<spec-root> --list`，展示未入库和有更新的内容，让用户选择。不要上传整个仓库。
+3. 上传前运行 `node <spec-root>/skywalk-sdd/kb-upload.cjs --project=<spec-root> --check-config`。输出不包含 Key；配置缺失时才运行 `opsx-kb-config`。
 
-## Session 启动（每次用本 Skill 必做）
+## 配置契约
 
-```
-Task Progress:
-- [ ] 1. 读 kb-state.json（spec 仓根目录）
-- [ ] 2. 无 apiKey 或无 targets → 提示用户运行 /opsx-kb-config 配置知识库
-- [ ] 3. 解析上传目标：优先 `uploadTarget`；旧单目标配置兼容；多目标但未指定则停止并提示配置
-- [ ] 4. 有配置 → 按意图执行入库操作（上传 / 查状态 / 列表 / 重试）
-- [ ] 5. 按模板输出结果
-```
-
-> **KB 配置**（API Key、Space/KB 选择、project-identity.json）由 `opsx-kb-config` 统一负责。如用户需要配置或更换 KB，请引导运行 `/opsx-kb-config`。
-
-### 上传目标解析（必须遵守）
-
-1. 用户本次明确同时提供 `--space-id` 与 `--kb-id` 时，作为临时覆盖目标。
-2. 否则读取 `kb-state.json.uploadTarget`，并确认它仍对应 `targets` 中的一项。
-3. 历史配置只有一个 `targets` 且没有 `uploadTarget` 时，兼容使用该唯一目标。
-4. 多个 `targets` 但没有有效 `uploadTarget` 时停止上传，提示在 SDD 助手中选择“Spec 上传知识库”。
+通过 `skywalk-sdd/lib/kb-config.cjs` 的 `readProjectConfig(specRoot)` 读取有效配置，不能绕过公共解析器只读个人文件。
 
-禁止直接使用 `targets[0]`，禁止把 Spec 自动广播到多个知识库。调用 `kb-upload.cjs` 时默认不再重复拼接目标参数；脚本会按同一规则读取共享配置。
+- `kb.config.json`：团队共享地址、读取知识库 `targets`、唯一上传位置 `uploadTarget`。可提交 Git，不允许包含 Key。
+- `kb-state.json`：个人 API Key 和额外读取范围；不提交 Git。旧项目只存在这个文件时继续兼容。
+- 上传默认采用团队上传位置；无团队文件时采用 `kb-state.json.uploadTarget`。旧单目标且未声明 uploadTarget 时可兼容唯一目标；显式 null 必须停止，不能回退。
+- 禁止直接使用 `targets[0]`，不能把内容广播到所有读取库。正常上传不要重复拼接 Space/KB 参数。调用 `kb-upload.cjs` 时默认不再重复拼接目标参数。
+- 团队地址变化后必须重新登录；不能把旧 Key 发给新地址。
 
-### 4. 入库操作
-
-路径前缀：`/api/v1/spaces/{spaceId}/knowledge-bases/{kbId}/ingestions`
-所有请求：`-H "Authorization: Bearer $API_KEY"`
-
-| 意图 | 调用 |
-|------|------|
-| 上传 zip 包入库 | `POST …/ingestions`（multipart，字段名 `package`） |
-| 列出入库任务 | `GET …/ingestions` |
-| 查看任务状态 | `GET …/ingestions/{jobId}` |
-| 重试失败任务 | `POST …/ingestions/{jobId}/retry` |
-
-**上传入库**
+## 执行上传
 
 ```bash
-curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions" \
-  -H "Authorization: Bearer $API_KEY" \
-  -F "package=@/path/to/your-archive.zip;type=application/zip"
+node <spec-root>/skywalk-sdd/kb-ingest.cjs --project=<spec-root> --change=<change目录名>
+# 已归档的本地文档同样可以直接读取
+node <spec-root>/skywalk-sdd/kb-ingest.cjs --project=<spec-root> --change=archive/<归档目录名>
 ```
 
-**查看任务状态**
-
-```bash
-curl -sS -X GET "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JOB_ID" \
-  -H "Authorization: Bearer $API_KEY"
-```
-
-**列出入库任务**
-
-```bash
-curl -sS -X GET "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions" \
-  -H "Authorization: Bearer $API_KEY"
-```
-
-**重试失败任务**
-
-```bash
-curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JOB_ID/retry" \
-  -H "Authorization: Bearer $API_KEY"
-```
-
-### Archive Package 要求
-
-上传的 zip 包必须满足以下条件（否则入库会失败）：
-
-- 当前产物包含：`archive-manifest.json`、`canonical-facts.json`、`spec-ontology.json`、`conversion-report.json`
-- 历史兼容包可不带 `canonical-facts.json`，但必须带 `spec-ontology.json`，且 `compatibility_mode=LEGACY_MATERIALIZED`。重复锚点、非法 UUID、身份冲突、依赖成环、归档版本不一致由上传自动消解；无结构化事实时才是 `pending`。不要让用户处理这些历史诊断。
-- `canonical-facts.json` 支持 `kld-sdd-canonical-facts/v1` 与 **`v2`**（v2 可选实体级 `external_refs`）
-- 所有文件需通过 SHA-256 校验（manifest 中记录每个文件的 `content_hash`）
-- 允许的文件类型：`.md`、`.json`、`.jsonl`、`.yaml`、`.yml`
-- 大小限制：包 ≤ 50MB，条目 ≤ 2000 个，单文件 ≤ 10MB，解压后 ≤ 200MB
-- `archive-manifest.json` 中的 `project_id` 必须与目标 Space 的 `spaceKey` 一致
-
-**v2 本地预检（skill 侧，上传前）**
-
-- `external_refs[]` 每项含 `system` / `object_type` / `external_id`
-- object_type 与实体类型匹配：`requirement`/`feature`→Capability；`scenario`→SpecificationStatement|AcceptanceCriterion
-- 包内无重复 `(external key, entity_id)` 绑定对
-- `project_id` / `spaceKey` 既有规则保留
-- **编号格式**：三条正则（见 reference）+ 场景 SLUG≤40 / 键总长≤120；先归一化再匹配
-- **场景作用域**：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
-```
-
-脚本先读取当前正文和身份登记，再查询目标 KB 的当前版本与内容哈希，完成全部检查后才写文件：
-
-- 正文未变保留版本；正文改变且基线匹配时生成新版本；未发布草稿继续沿用自身版本。
-- 本地基线落后时报 `STALE_BASE_VERSION`，先比较、合并正文，不自动把最新 version-id 填成 predecessor。
-- `--anchors` 仅筛选业务锚点，不绕过内容哈希和基线检查；结构实体也参与核对。
-- 默认在线同步失败只终止这次同步，本地编写/检查/测试仍可继续。`--skip-kb-verify` 仅为显式本地维护模式，报告 `baselineVerified:false`，不能证明可发布。
-- `--dry-run` 不改 Markdown 和身份登记；`--validate-only` 可能刷新工作态，不能当作无写入预览。
-- 身份由工具维护，不让用户手工填写 UUID；脚本不可用时先保留正文和待同步事项，修复工具后再同步，不手动篡改版本链。
-- 已发布内容修改后，先同步所有受影响文件，再上传。禁止删除 ontology/artifacts 或重建身份以绕过冲突。
-- 完整 UUID 保留原值，旧短 ID 继续兼容；不得截断真实 UUID。
-
-上传回执需分别检查事实保存、`publication_status` 和索引状态。HTTP 200 不是成功证明；多 KB 时默认使用配置中的 `uploadTarget`，不自动广播。
-
-**其他影响入库的因素**：
-
-| 因素 | 说明 | 是否需 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 已含元数据） |
-| 元数据生成 | 自动生成（manifest + canonical v2 + Spec ontology v1 + report） | 无需（zip 已含） |
-| 适用场景 | 任意 SDD 阶段入库 | 已有 zip 补传 / 归档后上传 |
-
-> 文件夹上传最终也会打包成 zip 走同一上传接口，KB 后端解析逻辑不变。
-
-### 5. 输出模板
-
-```markdown
-### 入库结果
-- 目标 KB：{spaceName}/{kbName}
-- 操作：{上传 | 查状态 | 列表 | 重试}
-- 状态：{succeeded | failed | running | idempotent}
-- Job ID：{jobId}
-
-### 详情
-- archiveId：{archiveId}
-- contentHash：{contentHash}
-- stage：{stage}
-- relationStatus：{relationStatus}
-- projectionStatus：{projectionStatus}
-- 外部引用写入数：{externalRefsWritten 或 0}
-- 幂等命中：{是 / 否}
-- 错误信息：{errorCode — errorMessage 或 无}
-```
-
-成功时展示 `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. 向用户给出两个修正选项：
-   - **复用历史身份**：按「重新入库前：KB 身份同步」步骤——查询 KB 获取已有 entity-id 和 version-id，更新 delta-state=modified + predecessor-version，重新上传
-   - **改为新锚点**：回到 kld-sdd，分配新锚点与新 entity_id，重新 check → 归档 → 入库
-3. **禁止**在 KB 内现场改绑或解绑。
-
-若编号门禁失败：
-
-| errorCode | 指引 |
-|-----------|------|
-| `EXTERNAL_REFERENCE_FORMAT_INVALID` | 编号含非白名单字符 → **检查外部编号来源**；不得手改编号硬闯 |
-| `EXTERNAL_REFERENCE_SCOPE_MISMATCH` | 场景键需求编号前缀不在申报集合 → 回 kld-sdd spec 修正 external-ref |
-| `EXTERNAL_REFERENCE_FEATURE_UNBOUND` | feature↔requirement.`feature_id` 配对断裂 → 回 propose/archive 修正线缆字段 |
+脚本只读取指定 Change 的 proposal.md、spec.md、design.md、tasks.md，使用已有解析器生成本体 JSON，并通过 `/ingestions/direct` 上传。不会改写业务 Markdown，也不会运行全仓 check。
 
-**禁止**手改包内编号绕过门禁。
+- 相同内容已发布：远端确认后跳过，不创建重复任务。
+- 本地内容更新：本地回执与团队版本相符时发布新版本；原版本保留。
+- 团队已更新：停止覆盖，提示先同步团队 Spec。不得伪造当前版本或跳过冲突。
+- 历史产物没有 UUID：自动生成稳定旁路身份；不要求手工补全旧文档。
+- 没有可识别的业务对象、场景或规则：提示补充 Spec，不能把空内容当作本体发布成功。
+- 相同内容已保存为候选：不重复上传，提示在知识库完成审核。
+- 服务没有直接入库接口：提示部署新版服务，不偷偷改投其他目标。
 
-**硬规则**
+普通文件夹入口 `kb-upload.cjs --folder=<path> --project=<spec-root>` 也采用直接 JSON 传输。`--validate-only` 仍是独立的完整本地语义校验，不代表远端发布成功。
 
-- 无 `apiKey` 不得猜密钥、不得改走 login。
-- 无 `targets` 不得臆造 spaceId/kbId。
-- 上传前确认 zip 包路径存在且为有效 zip 文件。
-- 入库失败时展示 `errorCode` 和 `errorMessage`，不编造原因。
-- 完整 apiKey 只写共享 state 文件（`kb-state.json`，spec 仓根目录）；聊天里最多显示前缀（如 `sk_sdd_****`）。
-- 401/403 时清掉 `apiKey`，请用户重贴；勿循环重试。
-- **共享状态**：state 文件与 `opsx-ontology-query`、`kb-upload`、`opsx-kb-config` 共用。KB 配置由 `opsx-kb-config` 统一负责。
+## 旧 ZIP 和任务兼容
 
-## 用户口令
+已有归档 ZIP 可使用 `node <spec-root>/skywalk-sdd/kb-upload.cjs --project=<spec-root> --package=<zip路径>`，沿用原来的 multipart 接口。不要为日常入库重新生成 ZIP。
 
-| 用户说 | Agent 做 |
-|--------|----------|
-| 配置 / 换密钥 / 换 KB | 引导运行 `/opsx-kb-config`（本技能不处理配置） |
-| 上传 zip / 入库 | 用当前共享 targets 中选中的 KB 上传 zip |
-| 文件夹上传 / 随时入库 | 运行 `kb-upload.cjs --folder=<path>`，自动打包上传 |
-| 查状态 / 看任务 | 用 jobId 查询任务状态 |
-| 列任务 / 看历史 | 列出最近入库任务 |
-| 重试 | 对失败的 jobId 执行重试 |
+任务查询、失败重试、SHA-256 校验和旧协议字段见 [reference.md](reference.md)。Windows 用 Node 脚本，不用 curl / PowerShell 的默认编码读写 JSON。
 
-## 心智模型（简述）
+## 返回结果
 
-- 入库是同步操作：上传后后端立即解析 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`。
-- 细节与 state schema → [reference.md](reference.md)。
+只汇报实际 Change、上传库、任务编号及服务端状态。区分已发布、待审核和检索准备失败；不能把候选保存或本地检查通过当作入库成功。不要回显 API Key。入库回执在 `skywalk-sdd/state/ingestions.json`，只保存在本地。