kld-sdd 2.8.1 → 2.8.3

package/README.md

@@ -6,6 +6,21 @@ KLD SDD OpenSpec 工程增强工具：一键初始化 AI 编辑器技能、语
 
 日常提交默认只保留本地关联 Hook；Apply 自动执行代码/Spec 检查、真实测试与交付验证。旧项目升级、备份回退、多仓和 CI 边界见 [Git Hook 调整说明](USABILITY.md#2026-09-10git-hook-收缩与交付验证)。
 
+## Spec 直接入库（2.8.2）
+
+日常入库直接读取选中的本地 Change 文档，通过 `/ingestions/direct` 发送本体 JSON，不生成 ZIP、不调用托盘模型，也不要求先完成归档。旧 `kb-upload.cjs --folder` 使用同一实现；`--package` 仅兼容已有归档包。Archive 的离线 ZIP 产物仍保留。
+
+```bash
+node skywalk-sdd/kb-ingest.cjs --project=<spec-root> --list
+node skywalk-sdd/kb-ingest.cjs --project=<spec-root> --change=<change目录名>
+```
+
+`lib/kb-config.cjs` 统一合并 `kb.config.json`（共享地址、读取范围、唯一上传库）和 `kb-state.json`（个人 Key、个人补充读取范围）。旧项目仅有个人文件仍兼容；团队地址改变后需重新登录。入库回执在 `skywalk-sdd/state/ingestions.json`，个人文件与回执自动忽略 Git。
+
+每次核对远端内容，相同内容跳过，更新生成新快照，旧版本保留；并发基线变化整体拒绝，先同步团队 Spec。历史产物缺 UUID 自动旁路适配，不改写业务 Markdown。无业务事实、候选待审核、服务端索引异常分别说明，不冒充发布成功。需人工候选审核时用 `--require-review`；审阅同一原文并明确授权后用 `--confirm-review` 发布。
+
+正式服务需先部署直接入库与基线接口。服务尚未升级时明确失败，本地 SDD 开发可继续；不会改投其他知识库或静默降级到 ZIP。
+
 ## 工具更新与卸载
 
 **更新不需要先卸载。** 在原工作目录重新运行安装器，覆盖运行脚本、Skills 和只读模板；Spec 文档、KB 绑定、项目身份、历史数据、用户配置和自定义 Hook 保留。先确认目标编辑器及 Spec 目录，完成后检查实际部署版本。下载失败不启动安装；执行中断后可以重跑补齐，不承诺整个项目的事务回滚。

package/lib/init.js

@@ -890,7 +890,7 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   if (!fs.existsSync(sharedLibDir)) {
     fs.mkdirSync(sharedLibDir, { recursive: true });
   }
-  for (const name of ['test-execution.cjs', 'check-review.cjs']) {
+  for (const name of ['test-execution.cjs', 'check-review.cjs', 'kb-config.cjs']) {
     const src = path.join(pkgPath, 'skywalk-sdd', 'lib', name);
     if (!fs.existsSync(src)) throw new Error(`E_INIT_MISSING_CRITICAL: lib/${name} 源文件缺失`);
     fs.copyFileSync(src, path.join(sharedLibDir, name));
@@ -978,6 +978,8 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
     deployedModules += 1;
   }
 
+  if (deployRuntimeModule(path.join(pkgPath, 'skywalk-sdd/kb-ingest.cjs'), path.join(dataDir, 'kb-ingest.cjs'), 'Spec 文档直接入库', '缺少直接入库运行文件')) deployedModules += 1;
+
   // 部署 kb-upload.cjs（知识库上传脚本，支持文件夹/zip 双模式随时入库）
   const kbUploadSrc = path.join(pkgPath, 'skywalk-sdd', 'kb-upload.cjs');
   const kbUploadDst = path.join(dataDir, 'kb-upload.cjs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.8.1",
+  "version": "2.8.3",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "lib/init.js",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "bench:check": "node test/benchmark-check.cjs",
-    "test": "node --test test/delivery-hooks.test.cjs test/execution-friction.test.cjs test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/prompt-spec-path.cjs && node test/spec-detect.cjs && node test/workspace-layout.cjs && node test/sync-repos-spec-choice.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/spec-ontology-compatibility.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/deploy-strategy.cjs && node test/uninstall.cjs && node --test test/maintenance.test.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs && node test/init-report-runtime.cjs && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs test/runtime/usage-reporter.test.cjs test/runtime/usage-reporting.test.cjs test/runtime/git-identity.test.cjs test/runtime/kb-state-location.test.cjs && node test/runtime/metrics-v3.test.cjs && node test/runtime/fixback.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
+    "test": "node --test test/kb-direct.test.cjs && node --test test/delivery-hooks.test.cjs test/execution-friction.test.cjs test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/prompt-spec-path.cjs && node test/spec-detect.cjs && node test/workspace-layout.cjs && node test/sync-repos-spec-choice.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/spec-ontology-compatibility.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/deploy-strategy.cjs && node test/uninstall.cjs && node --test test/maintenance.test.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs && node test/init-report-runtime.cjs && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs test/runtime/usage-reporter.test.cjs test/runtime/usage-reporting.test.cjs test/runtime/git-identity.test.cjs test/runtime/kb-state-location.test.cjs && node test/runtime/metrics-v3.test.cjs && node test/runtime/fixback.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
   },
   "keywords": [
     "kld",
@@ -45,7 +45,8 @@
     "skywalk-sdd/kb-upload.cjs",
     "skywalk-sdd/kb-sync-identity.cjs",
     "README.md",
-    "USABILITY.md"
+    "USABILITY.md",
+    "skywalk-sdd/kb-ingest.cjs"
   ],
   "sddMaintenance": {
     "toolOnly": 1

package/skywalk-sdd/context-client.cjs

@@ -119,7 +119,8 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
   if (args.offline) return unavailableContext('engineering_kb_offline', '本次使用本地上下文，未验证远程基线');
   // 优先从共享 state 文件读取配置（与 opsx-ontology-query / opsx-kb-ingest 共用）
   let stateConfig = {};
-  const stateFile = args['state-file'] || env.SDD_KB_STATE_FILE;
+  const stateFile = args['state-file'];
+  if (!stateFile && env.SDD_KB_STATE_FILE) console.error('⚠️ SDD_KB_STATE_FILE 已忽略；默认读取当前 Spec 根目录的 kb-state.json，需要临时读取其他配置时请显式传 --state-file');
 
   if (stateFile) {
     // 显式指定路径，直接读取
@@ -127,7 +128,9 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
       if (fs.existsSync(stateFile)) {
         let raw = fs.readFileSync(stateFile, 'utf8');
         raw = stripBom(raw);
-        stateConfig = JSON.parse(raw);
+        stateConfig = /^(kb-state|kb.config)\.json$/.test(path.basename(stateFile))
+          ? require('./lib/kb-config.cjs').readProjectConfig(path.dirname(path.resolve(stateFile))).config
+          : JSON.parse(raw);
       }
     } catch (e) {
       console.error(`⚠️  kb-state.json 解析失败 (${stateFile}): ${e.message}`);

package/skywalk-sdd/kb-ingest.cjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+'use strict';
+// Local documents -> structured JSON -> transactional KB ingestion. No ZIP and no model required.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const configStore = require('./lib/kb-config.cjs');
+const { parseChangeArtifacts } = require('./ontology/artifact-parser.cjs');
+const { normalizeFacts } = require('./ontology/normalizer.cjs');
+const { buildSpecOntology, validateSpecOntology, deterministicUuid } = require('./ontology/spec-ontology.cjs');
+const { readKbState, resolveUploadTarget, prepareUploadConfig, assertIngestionResult } = require('./kb-upload.cjs');
+const sha = text => crypto.createHash('sha256').update(text).digest('hex');
+const jsonText = value => JSON.stringify(value, null, 2) + '\n';
+function documents(dir) {
+  const result = {};
+  const visit = (current, prefix = '') => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) throw new Error('Spec 中存在符号链接，请移到实际目录再入库');
+      if (entry.name.startsWith('.') || ['reports', 'logs', 'ontology'].includes(entry.name)) continue;
+      const relative = prefix + entry.name;
+      if (entry.isDirectory()) visit(path.join(current, entry.name), relative + '/');
+      else if (/^(proposal|spec|design|tasks?)\.md$/i.test(entry.name)) {
+        if (fs.statSync(path.join(current, entry.name)).size > 4 * 1024 * 1024) throw new Error('单份 Spec 文档过大，请拆分后入库');
+        result[relative] = fs.readFileSync(path.join(current, entry.name), 'utf8');
+      }
+    }
+  };
+  visit(dir);
+  return result;
+}
+function sourceFingerprint(files) {
+  return 'sha256:' + sha(Object.keys(files).sort().map(name => name + '\0' + sha(files[name].replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n'))).join('\n'));
+}
+function locate(root, key) {
+  if (typeof key !== 'string' || !/^(?:archive\/)?[^/\\.][^/\\]*$/.test(key) || key.includes('..')) throw new Error('无效的 Change 目录');
+  const base = path.resolve(root, 'openspec/changes'), dir = path.resolve(base, key);
+  if (!fs.realpathSync(dir).startsWith(fs.realpathSync(base) + path.sep) || fs.lstatSync(dir).isSymbolicLink()) throw new Error('Change 必须位于当前 Spec 目录中');
+  return dir;
+}
+function localChange(root, key) {
+  const dir = locate(root, key), files = documents(dir);
+  if (!Object.keys(files).some(f => /(^|\/)proposal\.md$/i.test(f)) || !Object.keys(files).some(f => /(^|\/)spec\.md$/i.test(f))) throw new Error('请先完成 proposal.md 和 spec.md，再入库');
+  // OpenSpec archive adds a calendar prefix; it must not create a second Change identity.
+  const name = key.startsWith('archive/') ? path.basename(key).replace(/^\d{4}-\d{2}-\d{2}-/, '') : path.basename(key);
+  const facts = normalizeFacts(parseChangeArtifacts(root, name, { changeDir: dir, persistStructuralIdentities: false }));
+  const changeId = String(facts.change_id || `CHG-LEGACY-${sha(name).slice(0, 12)}`).toUpperCase();
+  const legacyChangeId = !facts.change_id && name !== path.basename(key) ? `CHG-LEGACY-${sha(path.basename(key)).slice(0, 12)}`.toUpperCase() : null;
+  const updatedAt = new Date(Math.max(...Object.keys(files).map(f => fs.statSync(path.join(dir, f)).mtimeMs))).toISOString();
+  return { key, dir, files, facts, changeId, legacyChangeId, sourceFingerprint: sourceFingerprint(files), updatedAt };
+}
+function connection(root, initialize = false, uploadOptions = {}) {
+  const loaded = configStore.readProjectConfig(root);
+  const state = readKbState(root), target = resolveUploadTarget(state, uploadOptions);
+  if (!state.apiKey) throw new Error('请先登录 Spec 知识库并保存连接');
+  const api = configStore.endpoint(state.api), base = `${api}/v1/spaces/${encodeURIComponent(target.spaceId)}/knowledge-bases/${encodeURIComponent(target.kbId)}/ingestions`;
+  const projectId = initialize ? prepareUploadConfig(root, uploadOptions).projectId : null;
+  return { state, target, base, api, projectId, revision: loaded.revision };
+}
+async function request(c, suffix, data, options = {}) {
+  let result;
+  if (!options.fetcher && typeof fetch !== 'function') {
+    try { result = await require('./lib/shared.cjs').requestJson(c.base + suffix, data, c.state.apiKey, 120000); }
+    catch (error) { if (/Not Found|404/.test(error.message)) throw new Error('知识库服务尚未升级到直接入库接口，请先部署新版服务'); throw error; }
+  } else {
+    const response = await (options.fetcher || fetch)(c.base + suffix, { method: 'POST', redirect: 'error', headers: { Authorization: `Bearer ${c.state.apiKey}`, 'Content-Type': 'application/json' }, body: JSON.stringify(data), signal: options.signal || (typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(120000) : undefined) });
+    if (response.status === 404) throw new Error('知识库服务尚未升级到直接入库接口，请先部署新版服务');
+    if (!response.ok) throw new Error(`知识库请求失败（HTTP ${response.status}），请检查连接或权限`);
+    result = await response.json();
+  }
+  if (result.code != null && result.code !== 0) throw new Error(result.message || '知识库拒绝请求');
+  return result.data || result;
+}
+function receiptKey(c, changeId) { return JSON.stringify([c.api, c.target.spaceId, c.target.kbId, changeId]); }
+function classify(local, remote, receipt) {
+  if (!remote?.snapshotId) return { status: 'new', label: '未入库', selected: true };
+  if (remote.status === 'needs_review') return { status: 'review', label: '已保存待审核，尚未供后续需求使用', selected: false };
+  if (remote.sourceFingerprint === local.sourceFingerprint && ['failed', 'degraded'].includes(remote.projectionStatus)) return { status: 'saved', label: '内容已保存，服务端检索索引未完成；请联系知识库管理员处理', selected: false };
+  if (remote.sourceFingerprint === local.sourceFingerprint) return { status: 'uploaded', label: remote.status === 'needs_review' ? '已保存，待审核' : '已入库', selected: false };
+  if (receipt?.snapshotId === remote.snapshotId) return { status: 'updated', label: '有更新', selected: true };
+  return { status: 'conflict', label: '请先同步团队 Spec', selected: false };
+}
+async function listChanges(root, options = {}) {
+  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;
+    if (entry.name === 'archive') {
+      for (const child of fs.readdirSync(path.join(base, 'archive'), { withFileTypes: true })) if (child.isDirectory() && !child.name.startsWith('.')) keys.push('archive/' + child.name);
+    } else keys.push(entry.name);
+  }
+  const local = keys.map(key => { try { return localChange(root, key); } catch (error) { return { key, error: error.message }; } });
+  const remote = new Map();
+  const ids = [...new Set(local.filter(x => !x.error).flatMap(x => [x.changeId, x.legacyChangeId].filter(Boolean)))];
+  for (let i = 0; i < ids.length; i += 200) {
+    const result = await request(c, '/spec-status', { changeIds: ids.slice(i, i + 200) }, options);
+    for (const item of result.items || []) remote.set(item.changeId, item);
+    if (ids.slice(i, i + 200).some(id => !remote.has(id))) throw new Error('知识库未完整返回入库状态，请稍后刷新；本次未上传');
+  }
+  const receipts = configStore.readReceipts(root).receipts || {};
+  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); }
+    if (current?.snapshotId && current.sourceFingerprint === item.sourceFingerprint && current.status !== 'needs_review') configStore.writeReceipt(root, receiptKey(c, item.changeId), { snapshotId: current.snapshotId, sourceFingerprint: item.sourceFingerprint, jobId: current.jobId, uploadedAt: new Date().toISOString() });
+    return { key: item.key, changeId: item.changeId, sourceFingerprint: item.sourceFingerprint, updatedAt: item.updatedAt, snapshotId: current?.snapshotId || null, ...classify(item, current, receipts[receiptKey(c, item.changeId)]) };
+  }).sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || '')) };
+}
+function extractOntology(local, projectId, requireReview = false) {
+  const facts = { ...local.facts, change_id: local.changeId };
+  const reviewStatus = requireReview ? 'pending' : 'confirmed';
+  let ontology = buildSpecOntology(facts, { projectId, reviewStatus });
+  if (!validateSpecOntology(ontology).valid) ontology = buildSpecOntology(facts, { projectId, compatibilityMode: 'LEGACY_MATERIALIZED', reviewStatus });
+  return ontology;
+}
+function directPayload(local, projectId, baseline, options = {}) {
+  // Reuse the existing ontology extractor, including legacy identity repair. It reads only this Change.
+  const ontology = extractOntology(local, projectId, options.requireReview);
+  if (!ontology.entities.length) throw new Error('尚未识别到业务对象、规则或场景，请补充结构化 Spec 后再入库');
+  for (const entity of ontology.entities) {
+    entity.entity_version_id = deterministicUuid(`${projectId}\n${entity.semantic_key}\n${entity.content_hash}`);
+    const source = entity.source, lines = (local.files[source.file] || '').replace(/\r\n?/g, '\n').split('\n');
+    const start = Math.max(0, Number(source.line || 1) - 1);
+    let end = start + 1;
+    while (end < lines.length && !/^#{1,6}\s/.test(lines[end])) end++;
+    source.quote = lines.slice(start, end).join('\n').trim();
+    const body = lines.slice(start + 1, end).join('\n').trim();
+    if (!entity.attributes.description && !entity.attributes.summary && body) entity.summary = body;
+  }
+  for (const mapping of ontology.identity_map) mapping.entity_version_id = ontology.entities.find(e => e.semantic_key === mapping.semantic_key).entity_version_id;
+  const archiveId = `urn:kld:sdd:archive:${sha(projectId + '\n' + local.changeId + '\n' + local.sourceFingerprint + '\n' + (baseline.change?.snapshotId || 'initial') + '\n' + ontology.review_status)}`;
+  ontology.archive_id = archiveId;
+  delete ontology.ontology_hash; ontology.ontology_hash = 'sha256:' + sha(JSON.stringify(ontology));
+  const validation = validateSpecOntology(ontology);
+  if (!validation.valid) throw new Error(validation.errors.join('; '));
+  const files = { ...local.files, 'spec-ontology.json': jsonText(ontology), 'conversion-report.json': jsonText({ schema_version: 'kld-sdd-conversion-report/v1', producer: require('./runtime-metadata.cjs').resolveRuntimeMetadata().producer, target_file: 'spec-ontology.json', target_schema: 'kld-sdd-spec-ontology/v1', status: options.requireReview ? 'materialized_pending_review' : 'materialized_reviewed', entity_count: ontology.entities.length, relation_count: ontology.relations.length }) };
+  const expected = Object.fromEntries(ontology.entities.map(e => [e.semantic_key, baseline.facts?.[e.semantic_key]?.revisionId || null]));
+  files['archive-manifest.json'] = jsonText({ schema_version: 'kld-sdd-archive-manifest/v2', producer: require('./runtime-metadata.cjs').resolveRuntimeMetadata().producer, project_id: projectId, archive_id: archiveId, change_id: local.changeId, content_hash: 'sha256:' + sha(files['spec-ontology.json']), spec_ontology_path: 'spec-ontology.json', conversion_report_path: 'conversion-report.json', created_at: new Date().toISOString(), source_fingerprint: local.sourceFingerprint, expected_snapshot_id: baseline.change?.snapshotId || null, expected_fact_revisions: expected, files: Object.entries(files).map(([name, content]) => ({ path: name, content_hash: 'sha256:' + sha(content) })) });
+  return { schemaVersion: 'kld-sdd-direct-ingest/v1', files };
+}
+async function uploadChanges(root, selections, options = {}) {
+  if (options.requireReview && options.confirmReview) throw new Error('待审核和确认发布不能同时选择');
+  const c = connection(root, true, options), results = [];
+  if (options.configRevision && options.configRevision !== c.revision) throw new Error('知识库配置已变化，请重新读取入库列表');
+  const wanted = [...new Map(selections.map(s => [s.key, s])).values()];
+  for (const selected of wanted) {
+    try {
+      const local = localChange(root, selected.key);
+      if (selected.sourceFingerprint && local.sourceFingerprint !== selected.sourceFingerprint) throw new Error('文档已修改，请刷新入库列表');
+      const ontology = extractOntology(local, c.projectId);
+      if (selected.changeId === local.legacyChangeId) local.changeId = local.legacyChangeId;
+      let baseline = await request(c, '/prepare', { changeId: local.changeId, semanticKeys: ontology.entities.map(e => e.semantic_key), entityIds: [] }, options);
+      if (!baseline.change?.snapshotId && local.legacyChangeId && local.legacyChangeId !== local.changeId) {
+        const legacy = await request(c, '/prepare', { changeId: local.legacyChangeId, semanticKeys: ontology.entities.map(e => e.semantic_key), entityIds: [] }, options);
+        if (legacy.change?.snapshotId) { local.changeId = local.legacyChangeId; baseline = legacy; }
+      }
+      const remote = baseline.change;
+      const confirming = options.confirmReview && remote?.status === 'needs_review' && remote.sourceFingerprint === local.sourceFingerprint;
+      if (remote?.snapshotId && remote.sourceFingerprint === local.sourceFingerprint && !confirming) {
+        if (remote.status === 'needs_review') throw new Error('REVIEW_REQUIRED: 相同内容已保存待审核，请先在知识库确认，未重复上传');
+        configStore.writeReceipt(root, receiptKey(c, local.changeId), { snapshotId: remote.snapshotId, sourceFingerprint: local.sourceFingerprint, jobId: remote.jobId, uploadedAt: new Date().toISOString() });
+        const state = classify(local, remote, null);
+        results.push({ key: selected.key, status: state.status, message: state.status === 'uploaded' ? '相同内容已入库，跳过上传' : state.label }); continue;
+      }
+      const receipts = configStore.readReceipts(root).receipts || {}, receipt = receipts[receiptKey(c, local.changeId)];
+      const expectedSnapshot = confirming ? remote.snapshotId : Object.hasOwn(selected, 'snapshotId') ? selected.snapshotId : receipt?.snapshotId || null;
+      if ((remote?.snapshotId || null) !== (expectedSnapshot || null)) throw new Error('团队已有新版本，请同步 Spec 后重试');
+      if (remote?.snapshotId && !receipt && !confirming) throw new Error('此内容在团队已有版本，请先同步 Spec 并核对');
+      const payload = directPayload(local, c.projectId, baseline, options);
+      const result = await request(c, '/direct', payload, options);
+      const job = assertIngestionResult(result, { allowNeedsReview: options.requireReview });
+      if (job.report?.publication_status === 'needs_review') {
+        results.push({ key: selected.key, status: 'review', message: '已保存待审核，尚未供后续需求使用', jobId: job.jobId }); continue;
+      }
+      configStore.writeReceipt(root, receiptKey(c, local.changeId), { snapshotId: job.report?.snapshot_id, sourceFingerprint: local.sourceFingerprint, archiveId: job.archiveId, jobId: job.jobId, uploadedAt: new Date().toISOString() });
+      const state = classify(local, { snapshotId: job.report?.snapshot_id, sourceFingerprint: local.sourceFingerprint, projectionStatus: job.projectionStatus }, null);
+      results.push({ key: selected.key, status: state.status, message: state.label, jobId: job.jobId });
+    } catch (error) { results.push({ key: selected.key, status: 'failed', message: error.message }); }
+    options.onProgress?.(results[results.length - 1]);
+  }
+  return { items: results };
+}
+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 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;
+}
+if (require.main === module) main().catch(error => { console.error(error.message); process.exitCode = 1; });
+module.exports = { documents, sourceFingerprint, locate, localChange, connection, classify, listChanges, directPayload, uploadChanges, main };

package/skywalk-sdd/kb-sync-identity.cjs

@@ -44,7 +44,6 @@ const {
   readJson,
   writeTextAtomic,
   resolveSpecRootFast,
-  loadKbState,
   resolveKbParams,
   httpGetJson,
   requestJson,
@@ -230,36 +229,11 @@ function filterRegistryKeys(registry, filePath) {
  * @returns {{ kbState: object, projectId: string, kbParams: { apiBase, token, spaceId, kbId } }}
  */
 function initKbConfig(specRoot, args = {}) {
-  // 1. 读取 kb-state.json
-  const { config: kbState, warnings } = loadKbState(specRoot);
-  if (warnings && warnings.length > 0) {
-    for (const w of warnings) console.warn(`  ⚠️  ${w}`);
-  }
-  if (!kbState) {
-    throw new Error(
-      'KB 配置不存在（kb-state.json 缺失）。\n' +
-      '请运行 /opsx-kb-config 配置知识库后再使用本脚本，\n' +
-      '或使用 --skip-kb-verify 跳过 KB 验证（不推荐）。'
-    );
-  }
-
-  // 2. 读取 project-identity.json
-  const identityPath = path.join(specRoot, 'skywalk-sdd', 'project-identity.json');
-  let projectId = null;
-  if (fs.existsSync(identityPath)) {
-    const identity = readJson(identityPath);
-    projectId = identity.project_id || null;
-  }
-  if (!projectId) {
-    throw new Error(
-      '无法确定 project_id。project-identity.json 不存在或无 project_id 字段。\n' +
-      '请运行 /opsx-kb-config 配置知识库。'
-    );
-  }
-
-  // 3. 解析 KB 参数
+  const { state: kbState, target, projectId } = require('./kb-upload.cjs').prepareUploadConfig(specRoot, {
+    spaceId: args['space-id'], kbId: args['kb-id'], overrideUploadTarget: Boolean(args['override-upload-target']),
+    readOnlyIdentity: Boolean(args['dry-run']),
+  });
   const kbParams = resolveKbParams(kbState);
-  const target = require('./kb-upload.cjs').resolveUploadTarget(kbState, { spaceId: args['space-id'], kbId: args['kb-id'] });
   kbParams.spaceId = target.spaceId; kbParams.kbId = target.kbId;
   kbParams.apiBase = kbParams.apiBase.replace(/\/+$/, '');
   if (!kbParams.token) {
@@ -269,18 +243,6 @@ function initKbConfig(specRoot, args = {}) {
     throw new Error('KB 上传目标未配置（请检查 kb-state.json 的 targets 与 uploadTarget）。');
   }
 
-  // 4. 校验 project_id 与 spaceKey 一致性
-  if (target.spaceKey) {
-    if (projectId !== target.spaceKey) {
-      throw new Error(
-        `project_id 不匹配:\n` +
-        `  project-identity.json: ${projectId}\n` +
-        `  kb-state.json spaceKey: ${target.spaceKey}\n` +
-        `请运行 /opsx-kb-config 更新配置。`
-      );
-    }
-  }
-
   return { kbState, projectId, kbParams };
 }