kld-sdd 2.8.0 → 2.8.2

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

@@ -1,10 +1,15 @@
+
+<!-- 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 字段或 Archive Package 规格时再读。
 
-## `.local/state.json`
+## 旧项目单文件格式示例（未启用团队共享）
 
-路径：`skills/opsx-kb-ingest/.local/state.json`（已 gitignore）。
+路径：`<spec-root>/kb-state.json`（已 gitignore，个人凭据文件；团队地址和目标以 kb.config.json 为准，必须通过 kb-config.cjs 合并读取）。
 
 ```json
 {
@@ -20,7 +25,11 @@
       "kbId": "uuid",
       "kbName": "默认知识库"
     }
-  ]
+  ],
+  "uploadTarget": {
+    "spaceId": "uuid",
+    "kbId": "uuid"
+  }
 }
 ```
 
@@ -30,6 +39,7 @@
 | `tenantKey` | 是 | 列空间用；默认 `default` |
 | `apiKey` | 是 | 控制台创建的 `sk_sdd_…`，scope 至少 `archive:ingest` |
 | `targets` | 操作前必填 | 多选；可为空仅当尚未完成选择 |
+| `uploadTarget` | 多目标上传前必填 | 默认写入位置，必须引用 `targets` 中的一项；旧单目标配置可省略 |
 | `updatedAt` | 建议 | ISO-8601 |
 
 示例（无密钥）见 [state.example.json](state.example.json)。
@@ -68,7 +78,17 @@ API Key 一般为租户范围；`apiKeySpaceId` 为空时可列出租户下多
 
 路径前缀：`/api/v1/spaces/{spaceId}/knowledge-bases/{kbId}/ingestions`
 
-### 上传 zip 包
+### 日常直接入库
+
+- `POST {base}/spec-status`：按 Change ID 核对远端快照及来源指纹。
+- `POST {base}/prepare`：获取本次涉及事实的版本基线。
+- `POST {base}/direct`：发送 `{schemaVersion:"kld-sdd-direct-ingest/v1",files:{"proposal.md":"…",…}}`。内存中生成本体、来源清单与 SHA-256，不写 ZIP。
+
+用户不手工构造上述请求，统一调用 kb-ingest.cjs。旧文件夹命令转到同一实现。
+`--require-review` 只保存候选；相同候选不会重复上传。用户明确审阅并授权发布后，运行同一命令加 `--confirm-review`；仅确认原文完全相同的远端候选，不跳过并发核对。
+服务端基线冲突整体回滚，提示先同步团队 Spec，不覆盖 current。
+
+### 兼容已有 zip 包（不是日常入库入口）
 
 ```bash
 POST {base}/ingestions
@@ -101,7 +121,7 @@ GET {base}/ingestions/{jobId}
 POST {base}/ingestions/{jobId}/retry
 ```
 
-仅 `status=failed` 的任务可重试；后端会重新解析原始上传的 zip 包。
+仅 `status=failed` 的任务可重试；后端会重新解析原始请求（直接 JSON 或旧 ZIP）。
 
 ## IngestionJobDto 响应字段
 
@@ -173,7 +193,7 @@ requirement 条目可选 `feature_id`（同 feature 文法）；配对关系随
 
 修正必须回到 kld-sdd（复用历史身份或换新锚点），重新 check → 归档 → 入库；禁止在 KB 改绑。
 
-## Archive Package 规格
+## 旧 Archive Package 规格（仅兼容已有 ZIP）
 
 ### 必需文件
 
@@ -218,7 +238,7 @@ requirement 条目可选 `feature_id`（同 feature 文法）；配对关系随
 # 仅校验
 node skywalk-sdd/kb-upload.cjs --validate-only --folder=<path> [--minimum-level=propose-spec]
 
-# 文件夹上传（自动语义管线 + 元数据生成 + 打包 + 上传）
+# 文件夹上传（读取本地文档 + 本体 JSON + 直接上传）
 node skywalk-sdd/kb-upload.cjs --folder=<path> [--minimum-level=propose-spec] [--space-id=<id>] [--kb-id=<id>]
 
 # zip 包上传
@@ -233,13 +253,19 @@ 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-id 一起显式提供 |
-| `--kb-id=<id>` | 否 | 目标 KB ID；单目标可读取配置，多目标时与 --space-id 一起显式提供 |
+| `--space-id=<id>` | 否 | 临时指定上传 Space（改投还需 `--override-upload-target`）；必须与 `--kb-id` 同时提供。默认读取 `uploadTarget` |
+| `--kb-id=<id>` | 否 | 临时指定上传 KB（改投还需 `--override-upload-target`）；必须与 `--space-id` 同时提供。默认读取 `uploadTarget` |
+
+上传目标：默认统一解析器返回的 `config.uploadTarget`；没有团队文件的旧项目对应 `kb-state.json.uploadTarget`；仅缺少该字段的旧单目标配置兼容唯一目标。字段为 null 表示未选择上传库，不能回退。
+成对参数与已保存目标不同会报 `UPLOAD_TARGET_CONFLICT`；只有用户明确临时改投并增加 `--override-upload-target` 才覆盖，且不得超出 targets。
+多个 `targets` 没有有效 `uploadTarget` 时直接停止，不能默选首项或广播。
 
 ### project_id 解析优先级
 
 1. `$SPEC_ROOT/skywalk-sdd/project-identity.json` 的 `project_id` 字段
-2. 都没有 → 报错：`请运行 /opsx-kb-config 配置知识库`
+2. 文件不存在且已选上传目标包含服务端 `spaceKey` → 首次上传自动创建，不能从读取目标顺序推断
+3. 旧离线归档的 `UNCONFIGURED` 临时身份且无 kb_space_id → 自动绑定已选上传库并保留原临时 ID；不改写历史归档
+4. 已有文件损坏、已绑定项目归属不符，或缺少 spaceKey → 停止并提示具体配置问题；不覆盖团队身份
 
 ### 上传等级校验
 
@@ -249,3 +275,5 @@ node skywalk-sdd/kb-upload.cjs --package=<zip-path> [--space-id=<id>] [--kb-id=<
 | `design` | + design.md |
 | `task` | + tasks.md |
 | `full` | 全部 4 个 + ontology 状态完整 |
+
+`--check-config`：只核对实际读取的配置与上传目标，输出不含密钥；不修改文件。

package/templates/skills/kld-sdd/opsx-kb-ingest/state.example.json

@@ -0,0 +1,18 @@
+{
+  "api": "http://10.29.213.80:8080/api",
+  "tenantKey": "default",
+  "apiKey": "",
+  "targets": [
+    {
+      "spaceId": "space-uuid",
+      "spaceKey": "project-key",
+      "spaceName": "项目空间",
+      "kbId": "knowledge-base-uuid",
+      "kbName": "Spec 知识库"
+    }
+  ],
+  "uploadTarget": {
+    "spaceId": "space-uuid",
+    "kbId": "knowledge-base-uuid"
+  }
+}

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

@@ -30,7 +30,7 @@ allowed-tools:
 
 ## 执行流程
 
-1. 确定 Spec 仓根目录和 change。
+1. 确定 Spec 仓根目录和 change。配置只读 `<spec-root>/kb-state.json`，通过 `kb-upload.cjs --project=<spec-root> --check-config` 核对上传位置；不创建 Skill 私有 state，也不把查询 targets 首项当上传库。已有配置直接复用，项目身份缺失且上传目标含 spaceKey 时由上传器首次创建。
 2. 执行兼容物化：
 
 ```bash

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

@@ -19,6 +19,11 @@ allowed-tools:
   - Edit
 ---
 
+<!-- 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 仅供已有归档包兼容。
+
+
 > **执行方式**：先读 [交互与执行契约](../opsx-propose/interaction-policy.md)；同一会话已读则复用。用户已授权连续处理时按范围推进，不重复索要阶段口令；只请求单阶段时完成即停。
 
 # 本体知识库 · 查询
@@ -31,23 +36,22 @@ allowed-tools:
 ## ⚠️ 数据边界（必读）
 
 ```
-SDD 流程：Propose → Spec → Design → Task → Check → Apply → Archive → kb-ingest
-                                                          ↑
-                                                   此刻之前，当前变更不在 KB 中
+本地 Spec → 用户选择入库 → 服务端发布为 current → 后续需求可召回
+归档可以在前或在后；未发布的本地改动不自动进入 KB。
 ```
 
 - Propose → Check 阶段查 KB = 查**历史上下文**（上一次入库的状态）
 - 当前变更的 added/modified 实体在 KB 中**不存在**或**只有旧版本**
 - 当前变更内部一致性 → **本地文件 + semantic-check**，不查 KB
-- 只有 Archive → kb-ingest 后，当前变更才进入 KB（Phase 3 验证）
+- 只有显式入库并发布为 current 后，本地版本才进入 KB；候选待审核不算发布。
 
 ## Session 启动（同一连续任务复用）
 
-> **📡 共享状态**：本技能与 `opsx-kb-ingest`、`kb-upload` **共用同一份 KB 配置**（`kb-state.json`，位于 spec 仓根目录）。KB 配置（API Key + Space/KB 选择 + project-identity.json）由 `opsx-kb-config` 统一负责。
+> **📡 共享状态**：本技能与 `opsx-kb-ingest`、`kb-upload` **共用同一个有效配置解析器**（Spec 根目录的团队 `kb.config.json` + 个人 `kb-state.json`）。KB 配置（API Key + Space/KB 选择 + project-identity.json）由 `opsx-kb-config` 统一负责。
 
 ```
 Task Progress:
-- [ ] 1. 读 kb-state.json（spec 仓根目录）
+- [ ] 1. 调用 readProjectConfig(specRoot).config（不要直接读个人文件）
 - [ ] 2. 无 apiKey 或无 targets → 记录未配置，本地工作继续；用户明确要配置时才进入 /opsx-kb-config
 - [ ] 3. 有唯一或已明确选择的目标 → 按意图查询；多个目标未明确时先澄清本次查询范围，不默认选第一个
 - [ ] 4. 按模板输出；无命中不编造
@@ -115,7 +119,7 @@ scenario:    ^[A-Z0-9_-]+:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
 - 无 `apiKey` 不得猜密钥、不得改走 login。
 - 无 `targets` 不得臆造 spaceId/kbId。
 - 无命中 → 写明「无当前依据」，禁止编造条款。
-- 完整 apiKey 只写共享 state 文件（`kb-state.json`，spec 仓根目录）；聊天里最多显示前缀（如 `sk_sdd_****`）。
+- 完整 apiKey 只写个人 state 文件（`kb-state.json`，spec 仓根目录）；聊天里最多显示前缀（如 `sk_sdd_****`）。
 - **共享状态**：state 文件与 `opsx-kb-ingest` 共用。配置一次，两个 skill 都生效。
 
 ## 用户口令

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

@@ -2,7 +2,7 @@
 
 > **触发时机**：opsx-propose 创建变更前 / opsx-spec 生成规格前
 > **加载方式**：SDD skill 在对应阶段 `Read` 本文件
-> **前置条件**：`.local/state.json` 已完成 Session 启动（apiKey + targets 就绪）
+> **前置条件**：`<spec-root>/kb-state.json` 已完成 Session 启动（apiKey + targets 就绪）
 >
 > ⚠️ **数据边界**：当前变更尚未入库，KB 中只有历史变更数据。
 > 本阶段 KB 查询的目的：**用历史上下文辅助当前变更的决策**（身份决议、影响预评、历史 AC 查询、Spec 复用）。

package/templates/skills/kld-sdd/opsx-ontology-query/phase-2-during.md

@@ -2,7 +2,7 @@
 
 > **触发时机**：opsx-design / opsx-task / opsx-check 阶段
 > **加载方式**：SDD skill 在对应阶段 `Read` 本文件
-> **前置条件**：`.local/state.json` 已完成 Session 启动
+> **前置条件**：`<spec-root>/kb-state.json` 已完成 Session 启动
 >
 > ⚠️ **数据边界**：当前变更尚未入库（Archive → kb-ingest 之前），KB 中只有历史变更数据。
 > 本阶段所有 KB 查询都是查**历史上下文**，用于辅助决策，不能用于验证当前变更的内部一致性。

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

@@ -2,7 +2,7 @@
 
 > **触发时机**：开发者手动查询 / Agent 按需加载
 > **加载方式**：任意阶段可 `Read` 本文件
-> **前置条件**：`.local/state.json` 已完成 Session 启动
+> **前置条件**：`<spec-root>/kb-state.json` 已完成 Session 启动
 
 ---
 

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

@@ -2,7 +2,7 @@
 
 > **触发时机**：治理流程 / 定期巡检 / opsx-check 深度验证
 > **加载方式**：治理角色按需 `Read` 本文件
-> **前置条件**：`.local/state.json` 已完成 Session 启动
+> **前置条件**：`<spec-root>/kb-state.json` 已完成 Session 启动
 >
 > ✅ conformance / drift API **已实现**，但需要先通过 `POST /evidence-ingestions` 入库代码证据后才有数据。
 > 无 evidence 时返回 `{"integrationStatus":"not_integrated","reports":[]}`，Agent 遇到此状态应提示用户"需先入库 evidence"，不当作错误。

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

@@ -1,10 +1,15 @@
+
+<!-- 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 curl 示例或响应字段时再读。
 
-## `.local/state.json`
+## 旧项目单文件格式示例（未启用团队共享）
 
-路径：`skills/opsx-ontology-query/.local/state.json`（已 gitignore）。
+路径：`<spec-root>/kb-state.json`（已 gitignore），与托盘、配置和入库 Skill 共用；不读取 Skill 私有 state。`targets` 可多选用于读取；`uploadTarget` 仅用于写入，查询不得修改它。
 
 ```json
 {
@@ -42,7 +47,7 @@ Authorization: Bearer sk_sdd_…
 
 - **不要** `POST /auth/login`。
 - Key 在控制台「API 密钥」创建；创建时勾选 **读取上下文 / context:read**（查询够用）。
-- 401/403：清掉 state 里的 `apiKey`，请用户重贴；勿循环重试。
+- 401/403：停止本次操作并提示检查密钥或权限；保留 apiKey、targets 和 uploadTarget，不自动清空配置，不循环重试。
 
 探活与校验：