kld-sdd 2.7.8-5 → 2.7.8-6

package/bin/kld-sdd-init.js

@@ -20,7 +20,8 @@
 const path = require('path');
 const { listToolProfileIds, buildToolConfigs } = require('../lib/tool-profiles');
 const { MODE, OP, modeLabel } = require('../lib/uninstall');
-const { specSourceLabel } = require('../skywalk-sdd/ontology/spec-detect.cjs');
+const specDetect = require('../skywalk-sdd/ontology/spec-detect.cjs');
+const { specSourceLabel } = specDetect;
 // spec 候选单选交互（唯一实现，与 lib/init.js 共用）
 const { selectSpecRoot: selectSpecChoice } = require('../lib/spec-choice');
 
@@ -125,6 +126,9 @@ function parseInitArgs(argv = cliArgs(), env = process.env) {
     verbose: isVerbose(argv, env),
     skipOpenspec: argv.includes('--skip-openspec'),
     skipTemplate: argv.includes('--skip-template'),
+    repairGit: argv[0] === 'repair-git' || argv.includes('--repair-git'),
+    applyRepair: argv.includes('--apply'),
+    json: argv.includes('--json'),
     tools,
     // 显式给了 --tool 即自动化场景：lib 据此抑制 spec 路径的交互询问
     hasToolArg: tools !== null,
@@ -357,6 +361,7 @@ KLD SDD 项目初始化工具
   kld-sdd-init [选项]
   npx kld-sdd [选项]
   kld-sdd sync-repos           # 工作目录下发现新增代码仓并轻量接入（多 spec 候选时单选）
+  kld-sdd repair-git           # 检查并清理旧 Spec 仓的工具跟踪噪声（默认只预览）
   kld-sdd uninstall [选项]     # 卸载 SDD 产物（渐进式：预览工具范围 → 确认）
   kld-sdd uninstall --help     # 查看工具卸载与保留范围
 
@@ -366,6 +371,9 @@ KLD SDD 项目初始化工具
   --verbose        输出每个安装文件/目录的明细日志（默认仅摘要，亦可用 KLD_SDD_VERBOSE=1）
   --skip-openspec  跳过 openspec init 步骤
   --skip-template  跳过复制内置模版
+  --repair-git     检查 Spec 仓中被 Git 跟踪的安装器工具（默认只预览）
+  --apply          与 --repair-git 同用：保留本地文件，仅从 Git 索引移除工具
+  --json           --repair-git 输出机器可读 JSON，供托盘健康检查使用
   --tool <name>     指定编辑器，可用值: cursor, claude, codebuddy, qoder, opencode, kunlunzhima, workbuddy, codex, all
   --spec-path <dir> 指定 spec 包裹包目录（必须是当前目录的子目录）。
                     不指定时（交互终端）：自动检测已有 spec 目录（目录名 *-sdd-specs，
@@ -385,6 +393,8 @@ KLD SDD 项目初始化工具
   kld-sdd-init --skip-openspec # 跳过 openspec，直接部署 skills
   kld-sdd-init --tool codex    # 仅部署 Codex 配置
   kld-sdd-init --spec-path erp-sdd-specs  # 指定 spec 目录（当前目录的子目录）
+  kld-sdd repair-git --spec-path=.          # 预览旧仓工具跟踪问题
+  kld-sdd repair-git --apply --spec-path=.  # 一次迁出工具，文件仍留在磁盘
   kld-sdd sync-repos           # 新代码仓加入后同步接入
 `);
 }
@@ -393,6 +403,72 @@ KLD SDD 项目初始化工具
 // 子命令路由：解析参数后调用 lib/ 业务实现
 // ═══════════════════════════════════════════════════════════════
 
+function resolveRepairSpecRoot(parsed, cwd = process.cwd()) {
+  const root = path.resolve(cwd);
+  if (parsed.specPath) {
+    const explicit = path.resolve(root, parsed.specPath);
+    if (!specDetect.isSpecPackageRoot(explicit)) {
+      throw new Error(`指定目录不是有效的 Spec 包裹包: ${explicit}`);
+    }
+    return explicit;
+  }
+  if (specDetect.isSpecPackageRoot(root)) return root;
+  const candidates = specDetect.detectSpecCandidatesWithGit(root);
+  if (candidates.length === 1) return candidates[0].abs;
+  if (candidates.length === 0) throw new Error('未发现 Spec 包裹包，请用 --spec-path=<dir> 指定');
+  throw new Error(`发现 ${candidates.length} 个 Spec 包裹包，请用 --spec-path=<dir> 指定，不自动猜测`);
+}
+
+function runGitRepair(parsed) {
+  const init = require('../lib/init');
+  const maintenance = require('../lib/maintenance');
+  const specRoot = resolveRepairSpecRoot(parsed);
+  const plan = maintenance.trackedManagedSpecTools(specRoot);
+  if (!plan.ok) throw new Error(plan.error);
+
+  if (!parsed.applyRepair) {
+    const payload = {
+      mode: 'preview',
+      specRoot,
+      trackedToolCount: plan.files.length,
+      trackedTools: plan.files.map((file) => file.relative),
+      businessFilesAffected: 0,
+    };
+    if (parsed.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+    console.log(`🧹 Spec Git 清洁度检查: ${path.basename(specRoot)}`);
+    console.log(`   被 Git 跟踪的可再生成工具: ${plan.files.length} 个`);
+    for (const file of plan.files.slice(0, 8)) console.log(`   - ${file.relative}`);
+    if (plan.files.length > 8) console.log(`   … 其余 ${plan.files.length - 8} 个`);
+    console.log('   业务 Spec、配置、项目身份与 Hook 参数: 不处理');
+    if (plan.files.length) console.log('   执行 --repair-git --apply 可一次迁出工具；不会删除磁盘文件。');
+    return;
+  }
+
+  const existingBefore = plan.files.filter((file) => require('fs').existsSync(path.join(specRoot, file.relative)));
+  init.updateGitignore(specRoot, { specPackage: true });
+  const result = maintenance.untrackManagedSpecTools(specRoot);
+  if (!result.ok) throw new Error(result.error);
+  const payload = {
+    mode: 'applied',
+    specRoot,
+    untrackedToolCount: result.files.length,
+    filesRemainOnDisk: existingBefore.every((file) => require('fs').existsSync(path.join(specRoot, file.relative))),
+    retainedLocalToolCount: existingBefore.length,
+    alreadyMissingToolCount: result.files.length - existingBefore.length,
+    businessFilesAffected: 0,
+  };
+  if (parsed.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(`✅ 已将 ${result.files.length} 个安装器工具移出 Git 跟踪，现存的 ${existingBefore.length} 个本地文件全部保留`);
+  if (payload.alreadyMissingToolCount) console.log(`   ℹ️ 其中 ${payload.alreadyMissingToolCount} 个文件在修复前已从磁盘删除`);
+  console.log('   请审阅一次 git status 并提交迁移；以后升级不再污染业务改动列表。');
+}
+
 async function runInit() {
   let parsed;
   try {
@@ -412,6 +488,15 @@ async function runInit() {
     return;
   }
 
+  if (parsed.repairGit) {
+    try {
+      runGitRepair(parsed);
+    } catch (error) {
+      fail(`Git 清洁度修复失败: ${error.message}`);
+    }
+    return;
+  }
+
   const init = require('../lib/init');
   init.setVerbose(parsed.verbose);
 

package/lib/init.js

@@ -1282,6 +1282,9 @@ async function populateSpecPackage(specRoot, options = {}) {
   copyTemplatesToProject(root);
   initGlobalOverview(root);
   deploySddGuideManual(root);
+  // Spec 包可能是独立 Git 仓或单仓内的子目录；忽略规则必须落在它自身，
+  // 不能只写工作区根，否则升级会把整套可再生成运行时显示为业务改动。
+  updateGitignore(root, { specPackage: true });
   console.log(`✅ SDD 包裹包已就绪: ${path.basename(root)}`);
   return { ok: true, path: root };
 }
@@ -1376,7 +1379,7 @@ function removeOuterSkywalk(anchorDir) {
  * 创建 / 更新 .gitignore
  * @param {string} [cwd=process.cwd()]
  */
-function updateGitignore(cwd = process.cwd()) {
+function updateGitignore(cwd = process.cwd(), options = {}) {
   const root = path.resolve(cwd);
   const gitignorePath = path.join(root, '.gitignore');
   const requiredLines = [
@@ -1395,6 +1398,10 @@ function updateGitignore(cwd = process.cwd()) {
     '**/skywalk-sdd/state/',
     '.worktrees/'
   ];
+  const specPackageLines = options.specPackage ? maintenance.specPackageIgnoreLines() : [];
+  if (options.specPackage) {
+    requiredLines.push(...specPackageLines);
+  }
 
   const sddConfig = `
 # KLD SDD AI 编辑器个人配置（请勿提交）
@@ -1418,6 +1425,10 @@ skywalk-sdd/state/
 
 # SDD Apply 隔离 worktree（本地临时目录）
 .worktrees/
+${options.specPackage ? `
+# KLD SDD 安装器工具（可由 init/升级重新生成，不属于业务 Spec）
+${specPackageLines.join('\n')}
+` : ''}
 `;
 
   const result = deployFile(null, gitignorePath, {
@@ -1868,4 +1879,5 @@ module.exports = {
   promptSpecPath,
   listSpecCandidatesForInit,
   deployCodeRepoHooks,
+  updateGitignore,
 };

package/lib/maintenance.js

@@ -3,11 +3,124 @@
 // 安装、升级、卸载共用的边界；业务文档和关联配置不属于可清理的工具文件。
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 const sdd = require('../skywalk-sdd/ontology/sdd-config.cjs');
 const layout = require('./workspace-layout');
 const detect = require('../skywalk-sdd/ontology/spec-detect.cjs');
 const pkg = path.resolve(__dirname, '..');
 
+function posix(relative) {
+  return String(relative || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+const MANAGED_ROOT_TOOLS = new Set([
+  'apply-worktree-finish.cjs',
+  'context-client.cjs',
+  'kb-sync-identity.cjs',
+  'kb-upload.cjs',
+  'log.cjs',
+  'metrics-v3.cjs',
+  'openspec-shim.cjs',
+  'runtime-metadata.cjs',
+  'spec-root.cjs',
+]);
+
+const MANAGED_HOOK_TOOLS = new Set([
+  'commit-msg-runner.cjs',
+  'commit-msg-sdd-trailer.cjs',
+  'consistency-check-core.cjs',
+  'delivery-check.cjs',
+  'delivery-snapshot.cjs',
+  'pre-commit-consistency-check.cjs',
+  'pre-commit-sdd-check.cjs',
+  'pre-push-consistency-check.cjs',
+  'pre-push-sdd-check.cjs',
+]);
+
+function specPackageIgnoreLines() {
+  return [
+    ...[...MANAGED_ROOT_TOOLS].sort().map((name) => `/skywalk-sdd/${name}`),
+    '/skywalk-sdd/lib/',
+    '/skywalk-sdd/ontology/',
+    '/skywalk-sdd/reporting/',
+    '/skywalk-sdd/ci/github-actions-sdd.yml',
+    '/skywalk-sdd/ci/gitlab-ci-sdd.yml',
+    ...[...MANAGED_HOOK_TOOLS].sort().map((name) => `/skywalk-sdd/git-hooks/${name}`),
+    '/openspec-templates/',
+    '/openspec/kld-sdd操作手册.html',
+    '/_tmp_*',
+    '/*-start.log',
+  ];
+}
+
+/**
+ * 只识别能够由 kld-sdd 安装器重新生成的文件。
+ * 业务 Spec、项目身份、Hook 参数、KB 配置和历史数据都不属于工具文件。
+ */
+function isManagedSpecToolPath(relative) {
+  const rel = posix(relative);
+  if (rel === 'openspec/kld-sdd操作手册.html' || rel.startsWith('openspec-templates/')) return true;
+  if (rel.startsWith('skywalk-sdd/') && MANAGED_ROOT_TOOLS.has(rel.slice('skywalk-sdd/'.length))) return true;
+  if (/^skywalk-sdd\/(?:lib|ontology|reporting)\//.test(rel)) return true;
+  if (/^skywalk-sdd\/ci\/(?:github-actions-sdd|gitlab-ci-sdd)\.yml$/.test(rel)) return true;
+  const hookPrefix = 'skywalk-sdd/git-hooks/';
+  return rel.startsWith(hookPrefix) && MANAGED_HOOK_TOOLS.has(rel.slice(hookPrefix.length));
+}
+
+function git(cwd, args) {
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      error: String(result.stderr || result.stdout || 'git 命令失败').trim(),
+      output: '',
+    };
+  }
+  return { ok: true, output: String(result.stdout || '') };
+}
+
+/** 列出当前 Spec 包中仍被 Git 跟踪的安装器工具文件。 */
+function trackedManagedSpecTools(specRoot) {
+  const requestedRoot = path.resolve(specRoot);
+  const root = fs.existsSync(requestedRoot) ? fs.realpathSync(requestedRoot) : requestedRoot;
+  const top = git(root, ['rev-parse', '--show-toplevel']);
+  if (!top.ok) return { ok: false, specRoot: root, files: [], error: '当前 Spec 目录不在 Git 仓库中' };
+  const gitRoot = path.resolve(top.output.trim());
+  const rootRelative = posix(path.relative(gitRoot, root));
+  if (rootRelative.startsWith('../') || path.isAbsolute(rootRelative)) {
+    return { ok: false, specRoot: root, gitRoot, files: [], error: 'Spec 目录不属于检测到的 Git 仓库' };
+  }
+  const pathspec = rootRelative ? `${rootRelative}/` : '.';
+  const listed = git(gitRoot, ['ls-files', '-z', '--', pathspec]);
+  if (!listed.ok) return { ok: false, specRoot: root, gitRoot, files: [], error: listed.error };
+  const prefix = rootRelative ? `${rootRelative}/` : '';
+  const files = listed.output.split('\0').filter(Boolean).map(posix).flatMap((gitPath) => {
+    if (prefix && !gitPath.startsWith(prefix)) return [];
+    const relative = prefix ? gitPath.slice(prefix.length) : gitPath;
+    return isManagedSpecToolPath(relative) ? [{ gitPath, relative }] : [];
+  });
+  return { ok: true, specRoot: root, gitRoot, files };
+}
+
+/**
+ * 将安装器工具从 Git 索引移除，文件仍留在磁盘供本地运行。
+ * 调用方必须先把对应规则写入 Spec 根 .gitignore。
+ */
+function untrackManagedSpecTools(specRoot) {
+  const plan = trackedManagedSpecTools(specRoot);
+  if (!plan.ok || plan.files.length === 0) return plan;
+  for (let offset = 0; offset < plan.files.length; offset += 100) {
+    const batch = plan.files.slice(offset, offset + 100).map((file) => file.gitPath);
+    const removed = git(plan.gitRoot, ['update-index', '--force-remove', '--', ...batch]);
+    if (!removed.ok) return { ...plan, ok: false, error: removed.error };
+  }
+  return { ...plan, untracked: plan.files.length };
+}
+
 function filesUnder(root, prefix = '') {
   if (!fs.existsSync(root) || !fs.lstatSync(root).isDirectory()) return [];
   return fs.readdirSync(root).flatMap(name => {
@@ -93,4 +206,16 @@ function maintenanceConflicts(root, spec, repos) {
   return failures;
 }
 
-module.exports = { filesUnder, regularFileWithin, runtimeToolFiles, samePath, associationConflict, workspaceCodeRepos, maintenanceConflicts };
+module.exports = {
+  filesUnder,
+  regularFileWithin,
+  runtimeToolFiles,
+  specPackageIgnoreLines,
+  isManagedSpecToolPath,
+  trackedManagedSpecTools,
+  untrackManagedSpecTools,
+  samePath,
+  associationConflict,
+  workspaceCodeRepos,
+  maintenanceConflicts,
+};

package/lib/skills-bundle.js

@@ -40,6 +40,7 @@ const OPSX_SKILL_DIRS = [
   // Engineering KB 依赖技能（随 init 部署；propose/spec/archive 硬依赖）
   'opsx-kb-config',
   'opsx-ontology-query',
+  'opsx-ontology-ingest',
   'opsx-kb-ingest',
   // Spec 一致性校验技能
   'opsx-consistency-check',
@@ -122,6 +123,7 @@ const KUNLUN_SLASH_COMMANDS = [
   'archive',
   'explore',
   'ontology-query',
+  'ontology-ingest',
   'kb-ingest',
   'kb-config',
   'consistency-check',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.7.8-5",
+  "version": "2.7.8-6",
   "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/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/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",

package/skywalk-sdd/context-client.cjs

@@ -37,6 +37,9 @@ function buildEndpoint(apiBase, spaceId, kbId, mode) {
   if (mode === 'resolve') {
     return `${base}/v1/spaces/${space}/knowledge-bases/${kb}/entities/resolve`;
   }
+  if (mode === 'spec-generation') {
+    return `${base}/v1/spaces/${space}/knowledge-bases/${kb}/context/spec-generation`;
+  }
   return `${base}/v1/spaces/${space}/knowledge-bases/${kb}/context/match-requirement`;
 }
 
@@ -61,7 +64,14 @@ function compactContext(data, includeCandidates, mode = 'match') {
     warnings: data.warnings,
     clarificationQuestions: data.clarificationQuestions,
     specGenerationContext: data.specGenerationContext,
+    matchedCapabilities: data.matchedCapabilities,
+    matchedScenarios: data.matchedScenarios,
+    businessObjects: data.businessObjects,
+    rules: data.rules,
+    specPatterns: data.specPatterns,
+    compatibilityMode: data.compatibilityMode,
     supportEvidence: data.supportEvidence,
+    candidateEvidence: data.candidateEvidence,
     oppositionEvidence: data.oppositionEvidence,
   };
   // Continuity resolve 必须透出 candidates；match 默认隐藏内部候选除非 --include-candidates
@@ -171,19 +181,40 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
     return { ...unavailableContext('engineering_kb_not_configured', 'KB 尚未配置，本地工作可以继续'), configured: false };
   }
 
-  const mode = String(args.mode || 'match').trim().toLowerCase() === 'resolve' ? 'resolve' : 'match';
+  const requestedMode = String(args.mode || 'match').trim().toLowerCase();
+  const mode = requestedMode === 'resolve'
+    ? 'resolve'
+    : (['spec-generation', 'spec_generation', 'generation'].includes(requestedMode)
+      ? 'spec-generation' : 'match');
   const timeoutMs = contextTimeout(args, env, 5000);
   const payload = buildPayload(args, mode);
-  const data = await requestJson(
-    buildEndpoint(apiBase, spaceId, kbId, mode),
-    payload,
-    token,
-    timeoutMs,
-  );
+  let responseMode = mode;
+  let data;
+  try {
+    data = await requestJson(
+      buildEndpoint(apiBase, spaceId, kbId, mode),
+      payload,
+      token,
+      timeoutMs,
+    );
+  } catch (error) {
+    const endpointUnavailable = /Not Found|HTTP 404/i.test(error.message);
+    if (mode !== 'spec-generation' || !endpointUnavailable) throw error;
+    data = await requestJson(
+      buildEndpoint(apiBase, spaceId, kbId, 'match'),
+      payload,
+      token,
+      timeoutMs,
+    );
+    responseMode = 'match';
+  }
   return {
     available: true,
     mode,
+    responseMode,
+    remoteContextVerified: true,
     ...compactContext(data, Boolean(args['include-candidates']), mode),
+    compatibilityMode: responseMode === mode ? (data.compatibilityMode || 'NATIVE') : 'LEGACY_V2',
   };
 }
 

package/skywalk-sdd/kb-upload.cjs

@@ -50,15 +50,18 @@ function cacheKey(changeName, context) {
   return JSON.stringify([context.api.replace(/\/+$/, ''), context.spaceId, context.kbId, changeName]);
 }
 
-function assertIngestionResult(result) {
+function assertIngestionResult(result, options = {}) {
   if (result?.code != null && result.code !== 0) throw new Error(result.message || 'KB API 拒绝入库');
   const job = result?.data || result;
   if (!job || !['projecting', 'succeeded'].includes(job.status) || job.relationStatus !== 'committed') {
     throw new Error(`INGEST_NOT_COMMITTED: ${job?.errorCode || job?.status || 'unknown'} ${job?.errorMessage || ''} job=${job?.jobId || 'unknown'}`);
   }
-  if (Number(job.report?.version_conflicts || 0) > 0 || job.report?.publication_status === 'needs_review') {
+  if (Number(job.report?.version_conflicts || 0) > 0) {
     throw new Error(`VERSION_CONFLICT: 事实包已保存为候选，当前事实未更新；请合并基线后重新发布。job=${job.jobId}`);
   }
+  if (job.report?.publication_status === 'needs_review' && !options.allowNeedsReview) {
+    throw new Error(`REVIEW_REQUIRED: 事实包已保存为候选，当前事实未更新；请审核本体后重新发布。job=${job.jobId}`);
+  }
   return job;
 }
 
@@ -240,7 +243,7 @@ function preCheckProjectId(projectId, state, selectedTarget) {
  *   5. materializeArchivePackage（生成 manifest + canonical-facts + conversion-report + zip）
  *   6. 返回 zip 路径
  */
-function buildPackageFromFolder(specRoot, changeName, options) {
+function buildPackageFromFolder(specRoot, changeName, options = {}) {
   const runtime = require('./ontology/runtime.cjs');
   const archivePackage = require('./ontology/archive-package.cjs');
 
@@ -250,13 +253,18 @@ function buildPackageFromFolder(specRoot, changeName, options) {
     profile: 'auto',
     markPending: true,
   });
+  const blockingDiagnostics = semanticResult.diagnostics.filter(d => d.severity === 'error');
+  const legacyIdentityOnly = blockingDiagnostics.length > 0
+    && blockingDiagnostics.every(d => d.code === 'SEM_UUID_MISSING');
   if (!semanticResult.valid) {
-    const errors = semanticResult.diagnostics
-      .filter(d => d.severity === 'error')
-      .map(d => `${d.code}: ${d.message}`);
-    throw new Error(`语义校验失败:\n${errors.join('\n')}`);
+    const errors = blockingDiagnostics.map(d => `${d.code}: ${d.message}`);
+    if (!legacyIdentityOnly) {
+      throw new Error(`语义校验失败:\n${errors.join('\n')}`);
+    }
+    console.warn('⚠️  检测到历史产物缺少身份标识，将生成旁路映射和待审核本体包，不改写 Markdown。');
+  } else {
+    console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
   }
-  console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
 
   // 2. 创建临时 staging 目录
   const stagingDir = path.join(
@@ -269,28 +277,55 @@ function buildPackageFromFolder(specRoot, changeName, options) {
     const changeDir = path.join(specRoot, 'openspec', 'changes', changeName);
     copyDirRecursive(changeDir, stagingDir);
 
-    // 4. 创建 archive snapshot（生成 archive-ontology.json）
-    runtime.createArchiveSnapshot(specRoot, changeName, stagingDir, semanticResult.state);
-    console.log('✓ 已生成 archive-ontology.json');
-
-    // 5. 生成 manifest + canonical-facts + conversion-report + zip
-    const projectIdentity = archivePackage.ensureProjectIdentity(specRoot);
-    const result = archivePackage.materializeArchivePackage({
-      projectRoot: specRoot,
-      archiveDir: stagingDir,
-      archivePath: stagingDir,
-      changeName: changeName,
-      packagePath: zipPath,
-      reason: options.reason || '随时入库（文件夹上传）',
-      method: 'kb-upload-folder',
-    });
+    let result;
+    if (legacyIdentityOnly) {
+      const approvedPath = path.join(changeDir, 'ontology', 'spec-ontology.json');
+      const approvedOntology = readJsonSafe(approvedPath);
+      const useApproved = approvedOntology?.review_status === 'confirmed'
+        && approvedOntology?.publication_eligible === true;
+      if (useApproved) {
+        console.log('✓ 已发现审核通过的历史 Spec 本体，将校验内容一致性后发布');
+      }
+      result = archivePackage.materializeCompatibilityPackage({
+        projectRoot: specRoot,
+        archiveDir: stagingDir,
+        changeName,
+        facts: semanticResult.state,
+        specOntology: useApproved ? approvedOntology : null,
+        packagePath: zipPath,
+        reason: options.reason || '历史 Spec 兼容入库',
+        method: 'kb-upload-legacy-folder',
+      });
+      console.log(useApproved
+        ? '✓ 已生成审核通过的 LEGACY_MATERIALIZED 发布包'
+        : '✓ 已生成 LEGACY_MATERIALIZED 本体候选包');
+    } else {
+      // 严格产物继续生成 confirmed snapshot 和双协议事实包。
+      runtime.createArchiveSnapshot(specRoot, changeName, stagingDir, semanticResult.state);
+      console.log('✓ 已生成 archive-ontology.json');
+      archivePackage.ensureProjectIdentity(specRoot);
+      result = archivePackage.materializeArchivePackage({
+        projectRoot: specRoot,
+        archiveDir: stagingDir,
+        archivePath: stagingDir,
+        changeName: changeName,
+        packagePath: zipPath,
+        reason: options.reason || '随时入库（文件夹上传）',
+        method: 'kb-upload-folder',
+      });
+    }
 
     console.log(`✓ Archive Package 已生成`);
     console.log(`  archive_id: ${result.manifest.archive_id}`);
     console.log(`  project_id: ${result.manifest.project_id}`);
     console.log(`  files: ${result.manifest.files.length}`);
 
-    return { zipPath, manifest: result.manifest, stagingDir };
+    return {
+      zipPath,
+      manifest: result.manifest,
+      stagingDir,
+      requiresReview: result.conversion_report?.status === 'materialized_pending_review',
+    };
   } catch (err) {
     // 出错时清理 staging
     fs.rmSync(stagingDir, { recursive: true, force: true });
@@ -313,7 +348,7 @@ async function uploadZip(zipPath, state, options) {
 
   try {
     const result = await uploadFile(uploadUrl, zipPath, state.apiKey);
-    assertIngestionResult(result);
+    assertIngestionResult(result, options);
     return result;
   } catch (err) {
     throw new Error(`上传失败: ${err.message}`);
@@ -438,7 +473,7 @@ async function main() {
 
     // 5. 构建 Archive Package
     console.log('');
-    const { zipPath, manifest, stagingDir } = buildPackageFromFolder(specRoot, changeName, {
+    const { zipPath, manifest, stagingDir, requiresReview } = buildPackageFromFolder(specRoot, changeName, {
       reason: args.reason,
     });
 
@@ -492,6 +527,7 @@ async function main() {
       const result = await uploadZip(zipPath, state, {
         spaceId: target.spaceId,
         kbId: target.kbId,
+        allowNeedsReview: requiresReview,
       });
 
       console.log('\n── 上传结果 ──');
@@ -504,8 +540,17 @@ async function main() {
       console.log(`  change_id:  ${manifest.change_id}`);
       console.log(`  files:      ${manifest.files.length}`);
 
-      // Canonical commit has been verified; a receipt does not imply projection completion.
-      updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
+      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')}`);
+        console.log('  → 运行 approve-spec-ontology 后再次上传即可发布');
+      } else {
+        // Published commit has been verified; a receipt does not imply projection completion.
+        updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
+      }
 
       // === 投影状态提示 ===
       // 上传成功后，KB 后端异步执行 vector embedding + AGE graph 投影。