kld-sdd 2.8.2 → 2.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.8.2",
+  "version": "2.8.3",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "lib/init.js",
   "bin": {

package/skywalk-sdd/kb-ingest.cjs

@@ -80,7 +80,7 @@ function classify(local, remote, receipt) {
   return { status: 'conflict', label: '请先同步团队 Spec', selected: false };
 }
 async function listChanges(root, options = {}) {
-  const c = connection(root), base = path.join(root, 'openspec/changes');
+  const c = connection(root, false, options), base = path.join(root, 'openspec/changes');
   const keys = [];
   for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
     if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
@@ -97,7 +97,7 @@ async function listChanges(root, options = {}) {
     if (ids.slice(i, i + 200).some(id => !remote.has(id))) throw new Error('知识库未完整返回入库状态，请稍后刷新；本次未上传');
   }
   const receipts = configStore.readReceipts(root).receipts || {};
-  return { configRevision: c.revision, destination: c.target.kbName || c.target.kbId, items: local.map(item => {
+  return { configRevision: c.revision, uploadTarget: { spaceId: c.target.spaceId, kbId: c.target.kbId }, destination: [c.target.spaceName, c.target.kbName || c.target.kbId].filter(Boolean).join(' / '), items: local.map(item => {
     if (item.error) return { key: item.key, status: 'invalid', label: item.error, selected: false };
     let current = remote.get(item.changeId);
     if (!current?.snapshotId && item.legacyChangeId && remote.get(item.legacyChangeId)?.snapshotId) { item.changeId = item.legacyChangeId; current = remote.get(item.changeId); }
@@ -183,7 +183,8 @@ async function main() {
   const { parseArgs, resolveSpecRootFast } = require('./lib/shared.cjs');
   const args = parseArgs(process.argv.slice(2)), root = args.project ? path.resolve(args.project) : resolveSpecRootFast(__dirname);
   const selections = args.selection ? JSON.parse(fs.readFileSync(args.selection, 'utf8')).items : [{ key: args.change }];
-  const result = args.list ? await listChanges(root) : await uploadChanges(root, selections, { configRevision: args.revision, requireReview: Boolean(args['require-review']), confirmReview: Boolean(args['confirm-review']) });
+  const options = { spaceId: args['space-id'], kbId: args['kb-id'], overrideUploadTarget: Boolean(args['override-upload-target']), configRevision: args.revision, requireReview: Boolean(args['require-review']), confirmReview: Boolean(args['confirm-review']) };
+  const result = args.list ? await listChanges(root, options) : await uploadChanges(root, selections, options);
   console.log('SDD_INGEST_RESULT:' + JSON.stringify(result));
   if (result.items.some(x => x.status === 'failed')) process.exitCode = 1;
 }

package/skywalk-sdd/kb-upload.cjs

@@ -21,8 +21,8 @@
  *
  * project_id 解析：
  *   1. $SPEC_ROOT/skywalk-sdd/project-identity.json 的 project_id
- *   2. 未配置的首次身份 → 使用已选上传库的 spaceKey 建立归属
- *   3. 缺少空间元数据或已有绑定不符 → 停止并提示修正配置
+ *   2. 缺少身份时自动创建稳定的 Spec 来源标识，不依赖上传库
+ *   3. 已有身份（含旧离线身份）原样保留，上传目标只由 uploadTarget 决定
  */
 
 const fs = require('fs');
@@ -173,41 +173,29 @@ function resolveSpecRoot(explicit) {
 
 /**
  * 解析 project_id
- * 保留团队绑定；仅缺失或明确 UNCONFIGURED 的身份可从已选上传目标首次建立。
+ * 保留 Spec 来源标识；切换知识库不会改变实体及版本命名空间。
  */
 function resolveProjectId(specRoot, target) {
   const identityPath = path.join(specRoot, 'skywalk-sdd', 'project-identity.json');
-  if (!fs.existsSync(identityPath) && typeof target?.spaceKey === 'string' && target.spaceKey.trim()) {
+  if (!fs.existsSync(identityPath) && target) {
     ensureDir(path.dirname(identityPath));
     try {
       fs.writeFileSync(identityPath, JSON.stringify({
         schema_version: 'kld-sdd-project-identity/v1',
-        project_id: target.spaceKey.trim(),
-        kb_space_id: target.spaceId,
-        kb_space_name: target.spaceName || '',
+        project_id: 'urn:kld:sdd:project:' + require('crypto').randomBytes(16).toString('hex'),
         created_at: new Date().toISOString(),
       }, null, 2) + '\n', { flag: 'wx' });
     } catch (error) { if (error.code !== 'EEXIST') throw error; }
   }
   if (fs.existsSync(identityPath)) {
     const identity = readJson(identityPath);
-    const provisional = !identity?.kb_space_id && typeof identity?._warning === 'string'
-      && identity._warning.startsWith('UNCONFIGURED') && /^urn:kld:sdd:project:/.test(identity.project_id || '');
-    if (provisional && typeof target?.spaceKey === 'string' && target.spaceKey.trim()) {
-      const next = { ...identity, previous_unconfigured_project_id: identity.project_id,
-        project_id: target.spaceKey.trim(), kb_space_id: target.spaceId, kb_space_name: target.spaceName || '',
-        configured_at: new Date().toISOString() };
-      delete next._warning;
-      writeJsonAtomic(identityPath, next);
-      return next.project_id;
-    }
     if (typeof identity?.project_id === 'string' && identity.project_id.trim()) {
       return identity.project_id;
     }
   }
   throw new Error(
     '无法确定 project_id。project-identity.json 不存在或无 project_id 字段。\n' +
-    '请运行 /opsx-kb-config 配置知识库。'
+    '请检查该文件；上传目标在知识库配置中单独选择。'
   );
 }
 
@@ -278,26 +266,15 @@ function validateRequiredFiles(folderPath, minimumLevel) {
 }
 
 /**
- * 本地预检 project_id === spaceKey
+ * 兼容旧调用：只检查来源标识和有效目标，不限制来源与目标空间一致。
  */
 function preCheckProjectId(projectId, state, selectedTarget) {
   if (!state.targets || !state.targets[0]) {
     throw new Error('KB 配置中无 targets，请运行 /opsx-kb-config 配置知识库。');
   }
-  const spaceKey = (selectedTarget || resolveUploadTarget(state)).spaceKey;
-  if (!spaceKey) {
-    console.warn('⚠️  kb-state.json 的上传目标缺少 spaceKey，跳过本地预检');
-    return;
-  }
-  if (projectId !== spaceKey) {
-    throw new Error(
-      `PROJECT_SPACE_MISMATCH 预检失败：\n` +
-      `  project_id (project-identity.json): ${projectId}\n` +
-      `  spaceKey    (kb-state.json):        ${spaceKey}\n` +
-      `请运行 /opsx-kb-config 更新配置。`
-    );
-  }
-  console.log(`✓ project_id 预检通过: ${projectId} === ${spaceKey}`);
+  if (typeof projectId !== 'string' || !projectId.trim()) throw new Error('Spec 来源标识为空，请修复 project-identity.json');
+  const target = selectedTarget || resolveUploadTarget(state);
+  if (!target.spaceId || !target.kbId) throw new Error('请选择有效的上传知识库');
 }
 
 /**
@@ -503,13 +480,10 @@ async function main() {
       const identityPath = path.join(specRoot, 'skywalk-sdd/project-identity.json');
       const identity = fs.existsSync(identityPath) ? readJson(identityPath) : null;
       if (fs.existsSync(identityPath) && (!identity || typeof identity.project_id !== 'string' || !identity.project_id.trim())) throw new Error('项目身份文件缺少 project_id，已保留原文件，请先修复');
-      const provisional = identity && !identity.kb_space_id && typeof identity._warning === 'string'
-        && identity._warning.startsWith('UNCONFIGURED') && /^urn:kld:sdd:project:/.test(identity.project_id || '');
-      if (identity?.project_id && !provisional) preCheckProjectId(identity.project_id, state, target);
-      else if (!target.spaceKey) throw new Error('上传目标缺少项目标识 spaceKey；请在助手重新登录获取知识库列表，或运行 /opsx-kb-config 补齐');
+      if (identity?.project_id) preCheckProjectId(identity.project_id, state, target);
       console.log(JSON.stringify({ configFile: resolveKbStatePath(specRoot), api: state.api,
         uploadTarget: { spaceId: target.spaceId, kbId: target.kbId, spaceKey: target.spaceKey, spaceName: target.spaceName, kbName: target.kbName }, projectId: identity?.project_id || null,
-        identityWillBeCreated: !identity && Boolean(target.spaceKey), identityWillBeBound: Boolean(provisional) }, null, 2));
+        identityWillBeCreated: !identity, identityWillBeBound: false }, null, 2));
     } catch (error) { console.error(error.message); process.exitCode = 1; }
     return;
   }

package/skywalk-sdd/ontology/archive-package.cjs

@@ -57,16 +57,11 @@ function ensureProjectIdentity(projectRoot) {
     }
     return existing;
   }
-  // 兜底：project-identity.json 未通过 opsx-kb-config 配置 KB 时创建
-  // 此时 project_id 为随机值，KB 入库时会因 project_id !== spaceKey 而失败
-  console.warn('⚠️  project-identity.json 不存在 — 未通过 opsx-kb-config 配置 KB。');
-  console.warn('⚠️  将生成临时 project_id，KB 入库时需确保与 Space spaceKey 一致。');
-  console.warn('⚠️  建议运行 /opsx-kb-config 配置 KB 后更新 project_id 为 Space spaceKey。');
+  // Stable source identity is independent of where the package is uploaded.
   const identity = {
     schema_version: PROJECT_IDENTITY_SCHEMA_VERSION,
     project_id: `urn:kld:sdd:project:${generateUuidV7()}`,
     created_at: new Date().toISOString(),
-    _warning: 'UNCONFIGURED — 请运行 /opsx-kb-config 配置 KB 后更新 project_id 为 Space spaceKey',
   };
   writeJsonAtomic(identityPath, identity);
   return identity;

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

@@ -39,7 +39,7 @@ allowed-tools:
 
 调用 `saveProjectConfig(specRoot, effectiveConfig, {revision, team})`。保留已有有效字段，只合并用户明确提供的改动。只有用户明确选择共享地址和知识库选择时 team=true；否则 team=false。团队文件存在时，个人保存不能修改团队地址和上传库。
 
-所有密钥只落个人文件，公共文件只写白名单字段。解析器自动加入个人文件和本地入库记录的 Git 忽略规则。项目身份绑定由上传预检负责，已有身份不允许静默改绑。
+所有密钥只落个人文件，公共文件只写白名单字段。解析器自动加入个人文件和本地入库记录的 Git 忽略规则。Spec 来源标识自动生成并长期保留，不绑定上传库。同一 Spec 可分别入库到不同知识库，状态按目标知识库核对；不要求用户填写 project_id。
 
 没有 API Key 时推荐用户在托盘登录知识库，按名称多选读取库、单选上传库，连接并保存。不能让用户手工寻找 Space/KB UUID，除非其明确要求手动配置。
 

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

@@ -42,7 +42,7 @@
 | `projectName` | 否 | 历史兼容字段；当前配置流程不要求填写，不作为七种 Skill 使用统计或业务归属依据 |
 | `scopes` | 建议 | API Client scope 列表 |
 | `targets` | 操作前必填 | 多选；可为空仅当尚未完成选择 |
-| `uploadTarget` | 多目标上传前必填 | Spec 的唯一写入位置，必须引用 `targets` 中的一项；不影响多目标查询 |
+| `uploadTarget` | 多目标上传前必填 | 默认上传位置（可切换），必须引用 `targets` 中的一项；不影响多目标查询 |
 | `updatedAt` | 建议 | ISO-8601 |
 
 ## 监控与入库分别验证
@@ -56,20 +56,18 @@
 ```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 名称>"
+  "project_id": "<自动生成的稳定 Spec 来源标识>",
+  "created_at": "<ISO timestamp>"
 }
 ```
 
 | 字段 | 必填 | 说明 |
 |------|------|------|
 | `schema_version` | 是 | 固定 `kld-sdd-project-identity/v1` |
-| `project_id` | 是 | = 目标 Space 的 `spaceKey`，KB 入库时校验一致性 |
+| `project_id` | 是 | 产物来源标识，自动生成；已有值保持不变，与上传位置无关 |
 | `created_at` | 是 | ISO-8601 |
-| `kb_space_id` | 建议 | Space UUID |
-| `kb_space_name` | 建议 | Space 名称 |
+| `kb_space_id` | 建议 | 历史配置元数据，保留但不限制上传目标 |
+| `kb_space_name` | 建议 | 历史配置元数据，保留但不限制上传目标 |
 
 ## 鉴权
 

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

@@ -25,9 +25,9 @@ description: >-
 
 通过 `skywalk-sdd/lib/kb-config.cjs` 的 `readProjectConfig(specRoot)` 读取有效配置，不能绕过公共解析器只读个人文件。
 
-- `kb.config.json`：团队共享地址、读取知识库 `targets`、唯一上传位置 `uploadTarget`。可提交 Git，不允许包含 Key。
+- `kb.config.json`：团队共享地址、读取知识库 `targets`、默认上传位置 `uploadTarget`。可提交 Git，不允许包含 Key。
 - `kb-state.json`：个人 API Key 和额外读取范围；不提交 Git。旧项目只存在这个文件时继续兼容。
-- 上传默认采用团队上传位置；无团队文件时采用 `kb-state.json.uploadTarget`。旧单目标且未声明 uploadTarget 时可兼容唯一目标；显式 null 必须停止，不能回退。
+- 同一 Spec 可分别上传到多个知识库，入库状态按目标知识库核对；切换知识库不得改写 Spec 的 project_id。上传默认采用团队上传位置；无团队文件时采用 `kb-state.json.uploadTarget`。旧单目标且未声明 uploadTarget 时可兼容唯一目标；显式 null 必须停止，不能回退。
 - 禁止直接使用 `targets[0]`，不能把内容广播到所有读取库。正常上传不要重复拼接 Space/KB 参数。调用 `kb-upload.cjs` 时默认不再重复拼接目标参数。
 - 团队地址变化后必须重新登录；不能把旧 Key 发给新地址。
 

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

@@ -152,7 +152,7 @@ POST {base}/ingestions/{jobId}/retry
 | errorCode | 含义 |
 |-----------|------|
 | `INGEST_FAILED` | 通用入库失败 |
-| `PROJECT_SPACE_MISMATCH` | manifest 中 project_id 与目标 Space spaceKey 不一致 |
+| 旧服务返回 `PROJECT_SPACE_MISMATCH` | 服务仍限制来源项目与上传空间一致；部署新版知识库服务，不修改产物标识绕过 |
 | `ARCHIVE_IMMUTABILITY_VIOLATION` | 同一 archive_id 已存在不同 content_hash |
 | `VERSION_IDENTITY_CONFLICT` | version-id 已存在但 content_hash 或 entity_id 不同；错误消息含 anchorId / name / versionId 帮助定位。该 Change 之前已入库，需对被修改的实体按「重新入库前：KB 身份同步」步骤更新 delta-state=modified + predecessor-version 后重新上传 |
 | `SEM_VERSION_LINEAGE_MISSING` | 语义校验阶段：modified/removed 实体的 predecessor-version 在本地 archive 中找不到对应版本。检查 predecessor-version 是否来自 KB resolve 返回的 entityVersionId |
@@ -221,7 +221,7 @@ requirement 条目可选 `feature_id`（同 feature 文法）；配对关系随
 ```json
 {
   "archive_id": "2026-07-18-user-center",
-  "project_id": "<必须与目标 Space spaceKey 一致>",
+  "project_id": "<产物稳定的来源标识，与上传库无关>",
   "content_hash": "sha256:<canonical-facts.json 的哈希>",
   "files": [
     { "path": "canonical-facts.json", "content_hash": "sha256:…" },
@@ -263,9 +263,11 @@ node skywalk-sdd/kb-upload.cjs --package=<zip-path> [--space-id=<id>] [--kb-id=<
 ### project_id 解析优先级
 
 1. `$SPEC_ROOT/skywalk-sdd/project-identity.json` 的 `project_id` 字段
-2. 文件不存在且已选上传目标包含服务端 `spaceKey` → 首次上传自动创建，不能从读取目标顺序推断
-3. 旧离线归档的 `UNCONFIGURED` 临时身份且无 kb_space_id → 自动绑定已选上传库并保留原临时 ID；不改写历史归档
-4. 已有文件损坏、已绑定项目归属不符，或缺少 spaceKey → 停止并提示具体配置问题；不覆盖团队身份
+2. 文件不存在 → 首次上传自动创建稳定来源标识，不要求 spaceKey，不从上传库生成来源身份
+3. 旧离线 `UNCONFIGURED` 标识、旧 spaceKey 标识以及历史归档均原样保留；切换上传库不重建身份
+4. 已有来源文件损坏或缺少 project_id → 停止并提示修复，不覆盖原文件。来源标识无需与任何 Space key 相同。
+
+同一 Spec 可以上传到多个知识库。每次只上传用户明确选择的目标，按规范化服务地址 + spaceId + kbId + Change ID 核对远端快照和来源 SHA-256；A 库已上传不影响 B 库首次上传。临时改投不改写团队默认值；库内并发基线保护仍然有效。
 
 ### 上传等级校验