kld-sdd 2.8.1 → 2.8.3

package/skywalk-sdd/kb-upload.cjs

@@ -5,7 +5,7 @@
  * kb-upload.cjs — 知识库上传脚本
  *
  * 支持两种上传模式：
- *   1. 文件夹上传：自动跑语义管线 → 生成元数据 → 打包 zip → 上传
+ *   1. 文件夹上传：读取本地 Spec → 生成本体 JSON → 直接上传（无 ZIP、无 AI）
  *   2. Zip 上传：直接上传已有 zip 包
  *
  * 用法：
@@ -16,11 +16,13 @@
  *
  * 历史产物（缺 entity-id / version-id）：
  *   自动旁路物化 spec-ontology.json，无 semantic_key 冲突时自动确认并发布为 current；
- *   有冲突或 --require-review 时只上传候选，需人工 approve-spec-ontology 后再上传。
+ *   --require-review 仅保存候选；明确审阅后用 --confirm-review 发布同一原文。
+ *   并发基线冲突整体拒绝，不覆盖团队 current。
  *
  * project_id 解析：
  *   1. $SPEC_ROOT/skywalk-sdd/project-identity.json 的 project_id
- *   2. 都没有 → 报错：请运行 /opsx-kb-config 配置知识库
+ *   2. 缺少身份时自动创建稳定的 Spec 来源标识，不依赖上传库
+ *   3. 已有身份（含旧离线身份）原样保留，上传目标只由 uploadTarget 决定
  */
 
 const fs = require('fs');
@@ -37,16 +39,27 @@ const {
   isKbStateHostDir,
   uploadFile,
   httpGetJson,
+  resolveKbParams,
 } = require('./lib/shared.cjs');
 
 function resolveUploadTarget(state, options = {}) {
   if (Boolean(options.spaceId) !== Boolean(options.kbId)) throw new Error('必须同时指定 --space-id 和 --kb-id');
   const targets = Array.isArray(state?.targets) ? state.targets : [];
+  const configured = state?.uploadTarget;
   if (options.spaceId && options.kbId) {
-    return targets.find(t => t.spaceId === options.spaceId && t.kbId === options.kbId) || options;
+    const differs = Object.prototype.hasOwnProperty.call(state || {}, 'uploadTarget')
+      && (!configured || configured.spaceId !== options.spaceId || configured.kbId !== options.kbId);
+    if (differs && !options.overrideUploadTarget) {
+      throw new Error('UPLOAD_TARGET_CONFLICT: 命令中的上传库与助手保存的上传位置不同；请更新旧 Skill，默认不传目标参数。确需临时改投时，显式增加 --override-upload-target');
+    }
+    const selected = targets.find(t => t.spaceId === options.spaceId && t.kbId === options.kbId);
+    if (options.overrideUploadTarget && !selected) throw new Error('临时上传目标必须在 kb-state.json 的 targets 中');
+    return selected || { spaceId: options.spaceId, kbId: options.kbId };
   }
 
-  const configured = state?.uploadTarget;
+  if (Object.prototype.hasOwnProperty.call(state || {}, 'uploadTarget') && configured == null) {
+    throw new Error('尚未选择 Spec 上传知识库（uploadTarget 已清空）；请在助手中选择上传位置，不能用读取库代替');
+  }
   if (configured != null) {
     if (!configured.spaceId || !configured.kbId) {
       throw new Error('kb-state.json 的 uploadTarget 不完整，请在 SDD 助手中重新选择 Spec 上传知识库');
@@ -106,9 +119,9 @@ function resolveKbStatePath(specRoot) {
 function readArchiveCache(specRoot, changeName, context) {
   const statePath = resolveKbStatePath(specRoot);
   const state = readJsonSafe(statePath);
-  if (!state || !state.archiveCache) return null;
+  const local = require('./lib/kb-config.cjs').readReceipts(specRoot);
   const key = cacheKey(changeName, context);
-  return key ? state.archiveCache[key] || null : null;
+  return key ? local.receipts?.[key] || local.legacyArchiveCache?.[key] || state?.archiveCache?.[key] || null : null;
 }
 
 /**
@@ -119,18 +132,14 @@ function readArchiveCache(specRoot, changeName, context) {
  * @param {string} contentHash
  */
 function updateKbStateCache(specRoot, changeName, archiveId, contentHash, context) {
-  const statePath = resolveKbStatePath(specRoot);
-  const state = readJsonSafe(statePath) || {};
-  if (!state.archiveCache) state.archiveCache = {};
   const key = cacheKey(changeName, context);
   if (!key) throw new Error('缓存必须包含 API、Space 和 KB');
-  state.archiveCache[key] = {
+  require('./lib/kb-config.cjs').writeReceipt(specRoot, key, {
     archive_id: archiveId,
     content_hash: contentHash,
     uploaded_at: new Date().toISOString(),
     target: context,
-  };
-  writeJsonAtomic(statePath, state);
+  });
   console.log(`✓ 已更新本地缓存: ${changeName} → ${archiveId.slice(0, 24)}...`);
 }
 
@@ -164,19 +173,29 @@ function resolveSpecRoot(explicit) {
 
 /**
  * 解析 project_id
- * 优先级：project-identity.json → 报错
+ * 保留 Spec 来源标识；切换知识库不会改变实体及版本命名空间。
  */
-function resolveProjectId(specRoot) {
+function resolveProjectId(specRoot, target) {
   const identityPath = path.join(specRoot, 'skywalk-sdd', 'project-identity.json');
+  if (!fs.existsSync(identityPath) && target) {
+    ensureDir(path.dirname(identityPath));
+    try {
+      fs.writeFileSync(identityPath, JSON.stringify({
+        schema_version: 'kld-sdd-project-identity/v1',
+        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);
-    if (identity.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 配置知识库。'
+    '请检查该文件；上传目标在知识库配置中单独选择。'
   );
 }
 
@@ -186,9 +205,9 @@ function resolveProjectId(specRoot) {
  * 位置校验：只读 `<specRoot>/kb-state.json`（specRoot 的 spec 根身份已由
  * resolveSpecRoot 在入口校验）。
  */
-function readKbState(specRoot) {
+function readKbState(specRoot, env = process.env) {
   const statePath = resolveKbStatePath(specRoot);
-  if (!fs.existsSync(statePath)) {
+  if (!fs.existsSync(statePath) && !fs.existsSync(path.join(specRoot, 'kb.config.json'))) {
     throw new Error(
       'KB 配置不存在（kb-state.json 缺失）。\n' +
       `期望位置: ${statePath}\n` +
@@ -196,7 +215,14 @@ function readKbState(specRoot) {
     );
   }
   try {
-    return readJson(statePath);
+    const loaded = require('./lib/kb-config.cjs').readProjectConfig(specRoot);
+    const state = loaded.config;
+    if (!state || typeof state !== 'object' || Array.isArray(state)) throw new Error('配置内容必须是 JSON 对象');
+    if (env.SDD_KB_STATE_FILE && path.resolve(env.SDD_KB_STATE_FILE) !== statePath) {
+      console.warn('⚠️ SDD_KB_STATE_FILE 已忽略；上传统一读取所选 Spec 根目录的 kb-state.json');
+    }
+    const params = resolveKbParams(state, env);
+    return { ...state, api: params.apiBase, apiKey: params.token };
   } catch (e) {
     throw new Error(
       `KB 配置解析失败 (${statePath}): ${e.message}\n` +
@@ -205,6 +231,16 @@ function readKbState(specRoot) {
   }
 }
 
+// Upload and identity synchronization share this entry; neither may reinterpret read targets.
+function prepareUploadConfig(specRoot, options = {}) {
+  const state = readKbState(specRoot);
+  if (!state.apiKey) throw new Error('KB 配置中无 apiKey，请在助手中登录知识库或运行 /opsx-kb-config');
+  const target = resolveUploadTarget(state, options);
+  const projectId = resolveProjectId(specRoot, options.readOnlyIdentity ? undefined : target);
+  preCheckProjectId(projectId, state, target);
+  return { state, target, projectId };
+}
+
 /**
  * 校验文件夹必需文件
  */
@@ -230,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('请选择有效的上传知识库');
 }
 
 /**
@@ -446,7 +471,23 @@ async function uploadZip(zipPath, state, options) {
 async function main() {
   const args = parseArgs(process.argv.slice(2));
 
-  if (!args.folder && !args.package) {
+  if (args['check-config']) {
+    try {
+      const specRoot = resolveSpecRoot(args.project);
+      const state = readKbState(specRoot);
+      if (!state.apiKey) throw new Error('尚未配置知识库 API Key');
+      const target = resolveUploadTarget(state);
+      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，已保留原文件，请先修复');
+      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, identityWillBeBound: false }, null, 2));
+    } catch (error) { console.error(error.message); process.exitCode = 1; }
+    return;
+  }
+  if (!args.folder && !args.package && !args.change) {
     console.error('用法:');
     console.error('  node skywalk-sdd/kb-upload.cjs --folder=<path> [--minimum-level=propose-spec] [--validate-only]');
     console.error('  node skywalk-sdd/kb-upload.cjs --package=<zip-path>');
@@ -483,6 +524,7 @@ async function main() {
       const result = await uploadZip(zipPath, state, {
         spaceId: args['space-id'],
         kbId: args['kb-id'],
+        overrideUploadTarget: Boolean(args['override-upload-target']),
       });
 
       console.log('\n── 上传结果 ──');
@@ -550,130 +592,11 @@ async function main() {
       return;
     }
 
-    // 2. 解析 project_id
-    const projectId = resolveProjectId(specRoot);
-    console.log(`✓ project_id: ${projectId}`);
-
-    // 3. 读取 KB 配置 + 预检
-    const state = readKbState(specRoot);
-    if (!state.apiKey) {
-      throw new Error('KB 配置中无 apiKey，请运行 /opsx-kb-config 配置知识库。');
-    }
-    const target = resolveUploadTarget(state, { spaceId: args['space-id'], kbId: args['kb-id'] });
-    preCheckProjectId(projectId, state, target);
-    const cacheContext = { api: state.api || 'http://localhost:8090/api', spaceId: target.spaceId, kbId: target.kbId };
-
-    // 5. 构建 Archive Package
-    console.log('');
-    const { zipPath, manifest, stagingDir, requiresReview, legacyStatus } = buildPackageFromFolder(specRoot, changeName, {
-      reason: args.reason,
-      requireReview: Boolean(args['require-review']),
-    });
-
-    try {
-      // Local receipts are informational only. Always verify the selected destination remotely.
-      const apiUrl = (state.api || 'http://localhost:8090/api').replace(/\/+$/, '');
-
-      // === Step 5.5: KB 预检（网络级幂等确认）===
-      const archiveId = manifest.archive_id;
-      const contentHash = manifest.content_hash;
-      console.log(`→ Pre-check: archive_id=${archiveId}`);
-      console.log(`  content_hash=${contentHash}`);
-
-      const checkUrl = `${apiUrl}/v1/spaces/${target.spaceId}/knowledge-bases/${target.kbId}/ingestions/check`
-        + `?archiveId=${encodeURIComponent(archiveId)}`
-        + `&contentHash=${encodeURIComponent(contentHash)}`;
-
-      try {
-        const checkResult = await httpGetJson(checkUrl, state.apiKey);
-
-        if (checkResult?.data?.idempotent && checkResult.data.publicationStatus === 'published') {
-          console.log('\n✓ KB 中已存在相同 archive（幂等命中），跳过上传');
-          console.log(`  snapshot_id: ${checkResult.data.snapshotId}`);
-          updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
-          console.log(`  publication: ${checkResult.data.publicationStatus}; projection: ${checkResult.data.projectionStatus}`);
-          if (['failed', 'degraded'].includes(checkResult.data.projectionStatus)) console.log('⚠️ 检索准备尚未完成，请在知识库概览重试该任务的投影');
-          console.log('\n✓ 归档已存在（检索状态以上述回执为准）');
-          return;
-        }
-
-        if (checkResult && checkResult.data && checkResult.data.exists && !checkResult.data.idempotent) {
-          throw new Error(
-            `ARCHIVE_IMMUTABILITY_VIOLATION: archive_id 已存在但 content_hash 不同\n` +
-            `  archive_id: ${archiveId}\n` +
-            `  如果内容确实变更，请确认实体身份块已正确更新`
-          );
-        }
-
-        console.log('✓ Pre-check 通过（KB 中无此 archive，继续上传）');
-      } catch (checkErr) {
-        // 降级：KB 后端未部署 /check 接口（404）→ 继续上传
-        if (checkErr.message && checkErr.message.includes('HTTP 404')) {
-          console.log('⚠️  KB 后端未部署 /check 接口，降级为直接上传');
-        } else {
-          throw checkErr;
-        }
-      }
-
-      // 6. 上传
-      console.log('');
-      const result = await uploadZip(zipPath, state, {
-        spaceId: target.spaceId,
-        kbId: target.kbId,
-        allowNeedsReview: requiresReview,
-      });
-
-      console.log('\n── 上传结果 ──');
-      console.log(JSON.stringify(result, null, 2));
-
-      // 7. 输出 manifest 摘要
-      console.log('\n── Archive Package 摘要 ──');
-      console.log(`  archive_id: ${manifest.archive_id}`);
-      console.log(`  project_id: ${manifest.project_id}`);
-      console.log(`  change_id:  ${manifest.change_id}`);
-      console.log(`  files:      ${manifest.files.length}`);
-
-      const publicationStatus = result?.data?.report?.publication_status
-        || result?.report?.publication_status
-        || '';
-      if (publicationStatus === 'needs_review') {
-        console.log('\n⚠️  历史 Spec 已安全保存为候选，尚未进入 current 召回');
-        console.log(`  → 审核 ${path.join(folderPath, 'ontology', 'spec-ontology.json')}`);
-        if (legacyStatus === 'needs_review') {
-          console.log('  → 正文没有足够的结构化事实，只能作为证据保留');
-        } else {
-          console.log('  → 运行 approve-spec-ontology 后再次上传即可发布；不带 --require-review 上传则自动确认');
-        }
-      } else {
-        // Published commit has been verified; a receipt does not imply projection completion.
-        updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
-      }
-
-      // === 投影状态提示 ===
-      // 上传成功后，KB 后端异步执行 vector embedding + AGE graph 投影。
-      // 正常 SDD 流程中，Spec→Design 等阶段间有用户手动触发的时间间隔，投影通常在此期间完成。
-      const projStatus = result?.data?.projectionStatus || result?.projectionStatus || '';
-      const jobStatus = result?.data?.status || result?.status || '';
-
-      if (projStatus === 'complete') {
-        console.log('\n✓ 投影已完成，向量/图检索可用');
-      } else if (projStatus === 'degraded') {
-        console.log('\n⚠️  投影完成但有降级（部分通道不可用，召回结果会标记降级）');
-      } else if (projStatus === 'disabled') {
-        console.log('\nℹ️  投影已禁用（仅可使用当前已就绪的检索通道）');
-      } else if (projStatus && projStatus !== 'complete') {
-        console.log(`\nℹ️  投影进行中 (${projStatus})，向量/图检索暂不可用`);
-        console.log('  → 正常 SDD 流程中阶段间间隔通常足够投影完成');
-        console.log('  → 如后续查询 degraded，可用 `context-client.cjs --check-only` 确认 KB 可用性');
-      } else if (jobStatus === 'succeeded') {
-        console.log('\n✓ 入库成功');
-      }
+    // Direct JSON transport reads the existing documents; ZIP remains for --package compatibility.
 
-    } finally {
-      // 清理临时目录
-      fs.rmSync(stagingDir, { recursive: true, force: true });
-      console.log('\n✓ 临时文件已清理');
-    }
+    const result = await require('./kb-ingest.cjs').uploadChanges(specRoot, [{ key: changeName }], { spaceId: args['space-id'], kbId: args['kb-id'], overrideUploadTarget: Boolean(args['override-upload-target']), requireReview: Boolean(args['require-review']), confirmReview: Boolean(args['confirm-review']) });
+    console.log(JSON.stringify(result, null, 2));
+    if (result.items.some(item => item.status === 'failed')) { for (const item of result.items.filter(i => i.status === 'failed')) console.error(item.message); process.exitCode = 1; }
 
   } catch (err) {
     console.error(`\n❌ ${err.message}`);
@@ -681,5 +604,6 @@ async function main() {
   }
 }
 
+module.exports = { resolveUploadTarget, prepareUploadConfig, readKbState, readArchiveCache, updateKbStateCache, assertIngestionResult, uploadZip, buildPackageFromFolder, validateRequiredFiles };
+
 if (require.main === module) main();
-module.exports = { resolveUploadTarget, readArchiveCache, updateKbStateCache, assertIngestionResult, uploadZip, buildPackageFromFolder, validateRequiredFiles };

package/skywalk-sdd/lib/kb-config.cjs

@@ -0,0 +1,107 @@
+'use strict';
+// One resolver for tray, Skills, retrieval, uploads and reporting. Never export a
+// personal file wholesale as team configuration.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const PUBLIC_KEYS = ['api', 'targets', 'uploadTarget'];
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+function endpoint(value) {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('知识库服务地址无效');
+  return url.toString().replace(/\/$/, '').replace(/\/api$/, '') + '/api';
+}
+function objectFile(file) {
+  if (!fs.existsSync(file)) return null;
+  if (fs.lstatSync(file).isSymbolicLink()) throw new Error('配置文件不能是符号链接');
+  const value = JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('配置必须是 JSON 对象');
+  return value;
+}
+function paths(root) {
+  return { team: path.join(root, 'kb.config.json'), personal: path.join(root, 'kb-state.json'), state: path.join(root, 'skywalk-sdd/state/ingestions.json') };
+}
+function unionTargets(a, b) {
+  const result = [];
+  for (const t of [...(a || []), ...(b || [])]) {
+    if (!t || typeof t.spaceId !== 'string' || typeof t.kbId !== 'string' || !t.spaceId || !t.kbId) throw new Error('知识库目标必须包含空间和知识库');
+    if (!result.some(x => x.spaceId === t.spaceId && x.kbId === t.kbId)) result.push(t);
+  }
+  return result;
+}
+function readProjectConfig(root) {
+  const files = paths(root), personal = objectFile(files.personal) || {}, team = objectFile(files.team);
+  const revision = hash([files.team, files.personal].map(f => fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : '').join('\0'));
+  let config = { ...personal }, warnings = [];
+  if (team) {
+    if (team.schemaVersion !== 1) throw new Error('团队知识库配置版本不兼容，请升级 kld-sdd');
+    if (Object.keys(team).some(k => !['schemaVersion', ...PUBLIC_KEYS].includes(k))) throw new Error('团队知识库配置包含非公共字段，请移到个人配置');
+    if (!Array.isArray(team.targets) || !Object.hasOwn(team, 'uploadTarget')) throw new Error('团队配置缺少读取范围或上传位置');
+    config = { ...personal, api: endpoint(team.api), targets: unionTargets(team.targets, personal.personalReadTargets), uploadTarget: team.uploadTarget };
+  }
+  const credentialApi = personal.credentialForApi || personal.api;
+  if (personal.apiKey && config.api && ((!credentialApi && team) || (credentialApi && credentialApi !== config.api && endpoint(credentialApi) !== endpoint(config.api)))) {
+    config.apiKey = ''; config.credentialMismatch = true;
+    warnings.push('知识库服务地址已变化，请重新登录；原 Key 已保留在本机');
+  }
+  // A changed shared server must not inherit a process-wide credential either.
+  if (team && !config.apiKey) config.credentialMismatch = true;
+  return { config, personal, team, files, revision, warnings, path: fs.existsSync(files.personal) || team ? files.personal : null };
+}
+function atomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) throw new Error('配置文件不能是符号链接');
+  const temp = file + '.' + crypto.randomBytes(8).toString('hex') + '.tmp';
+  try { fs.writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600, flag: 'wx' }); fs.renameSync(temp, file); }
+  finally { fs.rmSync(temp, { force: true }); }
+}
+function saveProjectConfig(root, config, options = {}) {
+  return require('../ontology/change-lock.cjs').withChangeLock(root, 'kb-config', {}, () => {
+  const before = readProjectConfig(root);
+  if (options.revision != null && options.revision !== before.revision) throw new Error('配置已被其他程序修改，请重新读取');
+  const api = endpoint(config.api);
+  protectPersonal(root);
+  const apiKey = config.credentialMismatch && !config.apiKey ? before.personal.apiKey : config.apiKey;
+  const sameKey = apiKey && apiKey === before.personal.apiKey;
+  const credentialApi = sameKey && !options.credentialVerified ? (before.personal.credentialForApi || before.personal.api || api) : api;
+  let personal = { ...before.personal, ...config, ...(apiKey !== undefined ? { apiKey } : {}), api, credentialForApi: credentialApi };
+  if (options.team === true || before.team) {
+    const targets = unionTargets(config.targets, []);
+    const selected = config.uploadTarget || null;
+    if (selected && !targets.some(t => t.spaceId === selected.spaceId && t.kbId === selected.kbId)) throw new Error('上传位置必须在所选知识库中');
+    if (options.team === true) {
+      const team = { schemaVersion: 1, api, targets: targets.map(t => Object.fromEntries(['spaceId', 'kbId', 'spaceKey', 'spaceName', 'kbName'].filter(k => typeof t[k] === 'string').map(k => [k, t[k]]))), uploadTarget: selected && { spaceId: selected.spaceId, kbId: selected.kbId } };
+      atomic(before.files.team, team);
+    } else {
+      if (api !== endpoint(before.team.api) || JSON.stringify(selected) !== JSON.stringify(before.team.uploadTarget)) throw new Error('修改团队地址或上传位置，请选择「团队共享」保存');
+    }
+    const defaults = options.team === true ? targets : before.team.targets;
+    personal.personalReadTargets = targets.filter(t => !defaults.some(x => x.spaceId === t.spaceId && x.kbId === t.kbId));
+    delete personal.targets; delete personal.uploadTarget;
+  }
+  delete personal.credentialMismatch;
+  if (personal.archiveCache) {
+    const state = objectFile(before.files.state) || { schemaVersion: 1, receipts: {} };
+    state.legacyArchiveCache = { ...personal.archiveCache, ...state.legacyArchiveCache };
+    atomic(before.files.state, state); delete personal.archiveCache;
+  }
+  protectPersonal(root);
+  atomic(before.files.personal, personal);
+  return readProjectConfig(root);
+  });
+}
+function readReceipts(root) { return objectFile(paths(root).state) || { schemaVersion: 1, receipts: {} }; }
+function writeReceipt(root, key, value) {
+  return require('../ontology/change-lock.cjs').withChangeLock(root, 'kb-config', {}, () => {
+  const state = readReceipts(root); state.receipts ||= {}; state.receipts[key] = value;
+  protectPersonal(root); atomic(paths(root).state, state); return value;
+  });
+}
+function protectPersonal(root) {
+  const file = path.join(root, '.gitignore');
+  if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) throw new Error('.gitignore 不能是符号链接');
+  const old = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const missing = ['/kb-state.json', '/skywalk-sdd/state/'].filter(rule => !old.split(/\r?\n/).includes(rule));
+  if (missing.length) fs.writeFileSync(file, old + (old.endsWith('\n') || !old ? '' : '\n') + missing.join('\n') + '\n');
+}
+module.exports = { endpoint, paths, readProjectConfig, saveProjectConfig, readReceipts, writeReceipt, atomic, unionTargets };

package/skywalk-sdd/lib/shared.cjs

@@ -352,12 +352,13 @@ function loadKbState(anchorDir = __dirname, env = process.env) {
   let current = start;
   for (let level = 0; level < MAX_KB_STATE_LEVELS; level += 1) {
     const candidate = path.join(current, KB_STATE_FILENAME);
-    if (fs.existsSync(candidate) && isKbStateHostDir(current)) {
+    if ((fs.existsSync(candidate) || fs.existsSync(path.join(current, 'kb.config.json'))) && isKbStateHostDir(current)) {
       try {
-        const config = JSON.parse(stripBom(fs.readFileSync(candidate, 'utf8')));
-        return { config, path: candidate, warnings };
+        return require('./kb-config.cjs').readProjectConfig(current);
       } catch (e) {
         warnings.push(`kb-state.json 解析失败 (${candidate}): ${e.message}`);
+        // A broken configuration belongs to this Spec. Never borrow another project's credentials.
+        return { config: null, path: candidate, warnings };
       }
     }
     if (current === fileRoot) break;
@@ -391,7 +392,7 @@ function normalizeProjectName(value) {
  */
 function resolveKbParams(stateConfig = {}, env = process.env) {
   const apiBase = stateConfig.api || env.ENGINEERING_KB_API || 'http://localhost:8090/api';
-  const token = stateConfig.apiKey || env.ENGINEERING_KB_TOKEN || '';
+  const token = stateConfig.credentialMismatch ? '' : stateConfig.apiKey || env.ENGINEERING_KB_TOKEN || '';
   const spaceId = stateConfig.targets && stateConfig.targets.length > 0
     ? stateConfig.targets[0].spaceId : '';
   const kbId = stateConfig.targets && stateConfig.targets.length > 0
@@ -523,7 +524,8 @@ function setKbProjectName(specRoot, projectName, options = {}) {
     error.code = 'E_PROJECT_NAME_INVALID';
     throw error;
   }
-  const next = { ...kbState, projectName: normalized };
+  const personal = require('./kb-config.cjs').readProjectConfig(root).personal;
+  const next = { ...personal, projectName: normalized };
   writeJsonAtomic(statePath, next);
   return { ok: true, path: statePath, projectName: next.projectName };
 }

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;