kld-sdd 2.6.16 → 2.6.21

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

@@ -0,0 +1,780 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * kb-sync-identity.cjs — KB 身份同步脚本
+ *
+ * 当 markdown 文件（spec.md / proposal.md 等）内容被修改后重新入库时，
+ * 需要更新被修改实体的身份元数据（version-id + delta-state + predecessor-version），
+ * 否则 KB 会拒绝（VERSION_IDENTITY_CONFLICT：同 version-id 但 content_hash 不同）。
+ *
+ * 本脚本自动完成以下工作：
+ *   Phase 0: 初始化与预检
+ *     - 读取 KB 配置（kb-state.json + project-identity.json）
+ *     - KB API 健康检查
+ *     - KB resolve 验证实体当前 version-id（predecessor 来源）
+ *   Phase 1: 结构实体同步（Artifact / DocumentSection）
+ *     - 对比 content_hash 变化，为变更实体生成新 version-id
+ *   Phase 2: 业务实体同步（STMT / AC / CON / CAP）
+ *     - 为指定实体生成新 version-id 并更新 markdown 身份块
+ *   Phase 3: 汇总报告
+ *
+ * 用法：
+ *   # 同步 spec.md 中所有结构实体 + 内容有变化的业务实体
+ *   # （自动检测 content_hash 变化，只同步真正变化的实体，不污染未变实体）
+ *   node skywalk-sdd/kb-sync-identity.cjs --file=spec.md --change=us-260801-user-crud --project=.
+ *
+ *   # 仅同步指定锚点的业务实体（精准模式，用户明确指定变更实体）
+ *   node skywalk-sdd/kb-sync-identity.cjs --file=spec.md --change=us-260801-user-crud --anchors=AC-USER-CRUD-006
+ *
+ *   # 仅同步结构实体（Artifact / DocumentSection），不修改业务实体
+ *   node skywalk-sdd/kb-sync-identity.cjs --file=spec.md --change=us-260801-user-crud --structural-only
+ *
+ *   # 干跑模式（只输出报告，不修改文件）
+ *   node skywalk-sdd/kb-sync-identity.cjs --file=spec.md --change=us-260801-user-crud --dry-run
+ *
+ *   # 跳过 KB 验证（KB 不可用时强制本地同步，风险：predecessor 可能不匹配 KB）
+ *   node skywalk-sdd/kb-sync-identity.cjs --file=spec.md --change=us-260801-user-crud --skip-kb-verify
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  parseArgs,
+  readJson,
+  writeTextAtomic,
+  resolveSpecRootFast,
+  loadKbState,
+  resolveKbParams,
+  httpGetJson,
+  requestJson,
+} = require('./lib/shared.cjs');
+
+const { allocateIdentity, normalizeUuid } = require('./ontology/id.cjs');
+const { readRegistry, writeRegistry } = require('./ontology/structural-identity.cjs');
+
+// ── 工具函数 ──────────────────────────────────────────
+
+function resolveSpecRoot(explicit) {
+  if (explicit) return path.resolve(explicit);
+  return resolveSpecRootFast(__dirname);
+}
+
+/**
+ * 解析 markdown 中的身份块。
+ *
+ * 身份块格式：
+ *   - **entity-id**: <8-hex>
+ *   - **version-id**: <8-hex>
+ *   - **delta-state**: added|modified|unchanged|removed
+ *   - **predecessor-version**: <8-hex>  (可选，modified/removed 时存在)
+ *
+ * @param {string} content — markdown 文件内容
+ * @returns {Array<{start: number, end: number, entityId: string, versionId: string, deltaState: string, predecessorVersion: string|null, anchor: string|null}>}
+ */
+function parseIdentityBlocks(content) {
+  const lines = content.split('\n');
+  const blocks = [];
+
+  // 匹配身份属性行
+  const entityIdRe = /^(-\s+\*\*entity-id\*\*:\s*)([0-9a-f]{8})\s*$/i;
+  const versionIdRe = /^(-\s+\*\*version-id\*\*:\s*)([0-9a-f]{8})\s*$/i;
+  const deltaStateRe = /^(-\s+\*\*delta-state\*\*:\s*)(\w+)\s*$/i;
+  const predecessorRe = /^(-\s+\*\*predecessor-version\*\*:\s*)([0-9a-f]{8}|none|\(none\))\s*$/i;
+
+  for (let i = 0; i < lines.length; i++) {
+    const entityIdMatch = lines[i].match(entityIdRe);
+    if (!entityIdMatch) continue;
+
+    // 向后扫描最多 6 行找完属性块
+    let versionId = null;
+    let deltaState = null;
+    let predecessorVersion = null;
+    let blockEnd = i;
+
+    for (let j = i; j < Math.min(i + 8, lines.length); j++) {
+      const vm = lines[j].match(versionIdRe);
+      if (vm) { versionId = vm[2]; blockEnd = j; }
+
+      const dm = lines[j].match(deltaStateRe);
+      if (dm) { deltaState = dm[2]; blockEnd = j; }
+
+      const pm = lines[j].match(predecessorRe);
+      if (pm) {
+        predecessorVersion = (pm[2].toLowerCase() === 'none' || pm[2] === '(none)') ? null : pm[2];
+        blockEnd = j;
+      }
+
+      // 遇到空行或下一个 entity-id 行，结束扫描
+      if (j > i && entityIdRe.test(lines[j])) break;
+      if (j > i && lines[j].trim() === '' && versionId && deltaState) break;
+    }
+
+    if (!versionId || !deltaState) continue;
+
+    // 向前查找锚点（最近的标题行或列表项中的 [XXX-YYY-ZZZ] 标识）
+    let anchor = null;
+    for (let k = i - 1; k >= Math.max(0, i - 10); k--) {
+      const line = lines[k];
+      // 匹配 [CAP-XXX] / [STMT-XXX] / [AC-XXX] / [CON-XXX] 等
+      const anchorMatch = line.match(/\[([A-Z]{2,5}-[A-Z0-9-]+)\]/);
+      if (anchorMatch) {
+        anchor = anchorMatch[1];
+        break;
+      }
+      // 匹配标题行
+      if (/^#{1,6}\s+/.test(line)) {
+        const titleMatch = line.match(/\[([A-Z]{2,5}-[A-Z0-9-]+)\]/);
+        if (titleMatch) { anchor = titleMatch[1]; break; }
+        // 标题行但没有锚点标识，仍可作为上下文
+        if (!anchor) { anchor = line.replace(/^#{1,6}\s+/, '').trim(); }
+        break;
+      }
+    }
+
+    blocks.push({
+      lineStart: i,
+      lineEnd: blockEnd,
+      entityId: entityIdMatch[2],
+      versionId,
+      deltaState,
+      predecessorVersion,
+      anchor,
+    });
+  }
+
+  return blocks;
+}
+
+/**
+ * 更新 markdown 中的身份块。
+ * @param {string} content — 原始 markdown 内容
+ * @param {Array} updates — 要更新的身份块列表
+ * @returns {string} 更新后的内容
+ */
+function updateIdentityBlocks(content, updates) {
+  const lines = content.split('\n');
+  const entityIdRe = /^(-\s+\*\*entity-id\*\*:\s*)([0-9a-f]{8})\s*$/i;
+  const versionIdRe = /^(-\s+\*\*version-id\*\*:\s*)([0-9a-f]{8})\s*$/i;
+  const deltaStateRe = /^(-\s+\*\*delta-state\*\*:\s*)(\w+)\s*$/i;
+  const predecessorRe = /^(-\s+\*\*predecessor-version\*\*:\s*)(.+)\s*$/i;
+
+  for (const update of updates) {
+    // 找到对应的 entity-id 行
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(entityIdRe);
+      if (!m || m[2].toLowerCase() !== update.entityId.toLowerCase()) continue;
+
+      // 扫描后续行更新属性
+      let hasPredecessorLine = false;
+      for (let j = i; j < Math.min(i + 8, lines.length); j++) {
+        const vm = lines[j].match(versionIdRe);
+        if (vm && vm[2].toLowerCase() === update.oldVersionId.toLowerCase()) {
+          lines[j] = `${vm[1]}${update.newVersionId}`;
+        }
+
+        const dm = lines[j].match(deltaStateRe);
+        if (dm && update.newDeltaState) {
+          lines[j] = `${dm[1]}${update.newDeltaState}`;
+        }
+
+        // 更新或添加 predecessor-version
+        const pm = lines[j].match(predecessorRe);
+        if (pm && update.predecessorVersion) {
+          lines[j] = `${pm[1]}${update.predecessorVersion}`;
+          hasPredecessorLine = true;
+        }
+      }
+
+      // 如果原文件没有 predecessor-version 行，在 delta-state 行后插入
+      if (!hasPredecessorLine && update.predecessorVersion) {
+        for (let j = i; j < Math.min(i + 8, lines.length); j++) {
+          if (deltaStateRe.test(lines[j])) {
+            lines.splice(j + 1, 0, `  - **predecessor-version**: ${update.predecessorVersion}`);
+            break;
+          }
+        }
+      }
+      break;
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * 从 registry 中过滤出指定文件相关的结构实体 key。
+ *
+ * key 格式：
+ *   Artifact:       artifact:CHG-xxx:spec.md        → 以 :filePath 结尾
+ *   DocumentSection: section:CHG-xxx:spec.md#AC-xxx  → 含 :filePath#
+ */
+function filterRegistryKeys(registry, filePath) {
+  const result = [];
+  for (const [key, entry] of Object.entries(registry.identities)) {
+    // Artifact key 以 :filePath 结尾（无尾随冒号或井号）
+    // DocumentSection key 含 :filePath#
+    if (key.endsWith(`:${filePath}`) || key.includes(`:${filePath}#`)) {
+      result.push({ key, entry });
+    }
+  }
+  return result;
+}
+
+// ── Phase 0: KB 初始化与预检 ──────────────────────────
+
+/**
+ * 读取 KB 配置（kb-state.json + project-identity.json）。
+ * @param {string} specRoot
+ * @returns {{ kbState: object, projectId: string, kbParams: { apiBase, token, spaceId, kbId } }}
+ */
+function initKbConfig(specRoot) {
+  // 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 kbParams = resolveKbParams(kbState);
+  if (!kbParams.token) {
+    throw new Error('KB apiKey 未配置（kb-state.json 中缺少 apiKey）。');
+  }
+  if (!kbParams.spaceId || !kbParams.kbId) {
+    throw new Error('KB targets 未配置（kb-state.json 中缺少 targets[0].spaceId/kbId）。');
+  }
+
+  // 4. 校验 project_id 与 spaceKey 一致性
+  const targets = kbState.targets || [];
+  if (targets.length > 0 && targets[0].spaceKey) {
+    if (projectId !== targets[0].spaceKey) {
+      throw new Error(
+        `project_id 不匹配:\n` +
+        `  project-identity.json: ${projectId}\n` +
+        `  kb-state.json spaceKey: ${targets[0].spaceKey}\n` +
+        `请运行 /opsx-kb-config 更新配置。`
+      );
+    }
+  }
+
+  return { kbState, projectId, kbParams };
+}
+
+/**
+ * KB API 健康检查。
+ * @param {string} apiBase
+ * @returns {Promise<boolean>}
+ */
+async function checkKbHealth(apiBase) {
+  const healthUrl = apiBase.replace(/\/api\/?$/, '') + '/health';
+  try {
+    await httpGetJson(healthUrl, '', 10000);
+    return true;
+  } catch (e) {
+    // 尝试备用路径
+    try {
+      await httpGetJson(apiBase.replace(/\/$/, '') + '/health', '', 10000);
+      return true;
+    } catch (e2) {
+      return false;
+    }
+  }
+}
+
+/**
+ * 调用 KB resolve API 查询实体的当前 version-id。
+ *
+ * @param {object} kbParams — { apiBase, token, spaceId, kbId }
+ * @param {string} entityId — 实体 ID（8-hex）
+ * @param {number} timeoutMs
+ * @returns {Promise<{ found: boolean, entityVersionId: string|null, raw: object }>}
+ */
+async function resolveEntityFromKb(kbParams, entityId, timeoutMs = 30000) {
+  const endpoint = `${kbParams.apiBase}/v1/spaces/${encodeURIComponent(kbParams.spaceId)}` +
+    `/knowledge-bases/${encodeURIComponent(kbParams.kbId)}/entities/resolve`;
+
+  const payload = { entityId: normalizeUuid(entityId) };
+
+  try {
+    const resp = await requestJson(endpoint, payload, kbParams.token, timeoutMs);
+
+    // 尝试从响应中提取当前 version-id
+    // 响应结构可能因 KB 版本而异，尝试多种路径
+    const candidates = resp?.candidates || resp?.data?.candidates || [];
+    if (candidates.length > 0) {
+      const candidate = candidates[0];
+      const versionId = candidate.entityVersionId
+        || candidate.version_id
+        || candidate.versionId
+        || candidate.entity_version_id
+        || null;
+      return { found: true, entityVersionId: versionId, raw: resp };
+    }
+
+    // 如果没有 candidates 但有 resolution，尝试从 resolution 提取
+    const resolution = resp?.resolution || resp?.data?.resolution;
+    if (resolution) {
+      const versionId = resolution.entityVersionId
+        || resolution.version_id
+        || resolution.versionId
+        || null;
+      if (versionId) {
+        return { found: true, entityVersionId: versionId, raw: resp };
+      }
+    }
+
+    // 实体在 KB 中不存在（首次上传场景）
+    return { found: false, entityVersionId: null, raw: resp };
+  } catch (e) {
+    // KB API 错误（网络/权限/服务器等）
+    throw new Error(`KB resolve 失败 (entity=${entityId}): ${e.message}`);
+  }
+}
+
+// ── 主流程 ────────────────────────────────────────────
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.file || !args.change) {
+    console.error('用法:');
+    console.error('  node skywalk-sdd/kb-sync-identity.cjs --file=<spec.md> --change=<change-key> [--project=.]');
+    console.error('  [--anchors=AC-USER-CRUD-006,AC-USER-CRUD-007] [--structural-only] [--dry-run]');
+    console.error('  [--skip-kb-verify]');
+    process.exit(1);
+  }
+
+  const dryRun = Boolean(args['dry-run']);
+  const structuralOnly = Boolean(args['structural-only']);
+  const skipKbVerify = Boolean(args['skip-kb-verify']);
+  const anchorList = args.anchors
+    ? String(args.anchors).split(',').map(s => s.trim().toUpperCase()).filter(Boolean)
+    : null;
+
+  const specRoot = resolveSpecRoot(args.project);
+  const changeName = args.change;
+  const filePath = args.file;
+
+  const changeDir = path.join(specRoot, 'openspec', 'changes', changeName);
+  if (!fs.existsSync(changeDir)) {
+    console.error(`❌ 变更目录不存在: ${changeDir}`);
+    process.exit(1);
+  }
+
+  const mdPath = path.join(changeDir, filePath);
+  if (!fs.existsSync(mdPath)) {
+    console.error(`❌ 文件不存在: ${mdPath}`);
+    process.exit(1);
+  }
+
+  console.log(`模式: KB 身份同步`);
+  console.log(`  文件: ${filePath}`);
+  console.log(`  变更: ${changeName}`);
+  console.log(`  Spec Root: ${specRoot}`);
+  console.log(`  干跑: ${dryRun ? '是' : '否'}`);
+  console.log(`  KB 验证: ${skipKbVerify ? '跳过' : '启用'}`);
+  console.log('');
+
+  const report = {
+    structuralSynced: [],
+    structuralSkipped: [],
+    businessSynced: [],
+    businessSkipped: [],
+    errors: [],
+    warnings: [],
+  };
+
+  // ═════════════════════════════════════════════════════
+  // Phase 0: 初始化与预检
+  // ═════════════════════════════════════════════════════
+
+  console.log('── Phase 0: 初始化与预检 ──');
+
+  let kbParams = null;
+  let kbHealthOk = false;
+
+  if (skipKbVerify) {
+    console.log('  ⚠️ 已跳过 KB 验证（--skip-kb-verify）');
+    console.log('  ⚠️ 风险：本地 version-id 可能与 KB 不一致，导致上传被拒绝');
+    report.warnings.push('skip-kb-verify: 本地 version-id 未经 KB 验证');
+  } else {
+    // 0a. 读取 KB 配置
+    console.log('  → 读取 KB 配置...');
+    try {
+      const kbConfig = initKbConfig(specRoot);
+      kbParams = kbConfig.kbParams;
+      console.log(`  ✓ KB 配置: api=${kbParams.apiBase}, space=${kbParams.spaceId}, kb=${kbParams.kbId}`);
+      console.log(`  ✓ project_id: ${kbConfig.projectId}`);
+    } catch (e) {
+      console.error(`  ❌ KB 配置错误: ${e.message}`);
+      process.exit(1);
+    }
+
+    // 0b. KB API 健康检查
+    console.log('  → KB API 健康检查...');
+    kbHealthOk = await checkKbHealth(kbParams.apiBase);
+    if (!kbHealthOk) {
+      console.warn('  ⚠️ KB API 不可达，降级为本地模式（不查询 KB）');
+      console.warn('  ⚠️ 风险：predecessor-version 将使用本地 version-id，可能与 KB 不一致');
+      report.warnings.push('kb-unreachable: KB API 不可达，predecessor 使用本地 version-id');
+    } else {
+      console.log('  ✓ KB API 可达');
+    }
+  }
+
+  const kbVerifyEnabled = !skipKbVerify && kbHealthOk && kbParams;
+  console.log('');
+
+  // ═════════════════════════════════════════════════════
+  // Part 1: 结构实体同步（Artifact / DocumentSection）
+  // ═════════════════════════════════════════════════════
+
+  console.log('── 结构实体同步 ──');
+
+  // 1. 读取旧 registry（上传前的 version_id）
+  const oldRegistry = readRegistry(changeDir);
+  const oldEntries = filterRegistryKeys(oldRegistry, filePath);
+
+  console.log(`  扫描到 ${oldEntries.length} 个结构实体（Artifact + DocumentSection）`);
+
+  if (oldEntries.length === 0) {
+    console.log('  ⚠️ 未找到结构实体记录，跳过结构实体同步');
+    console.log('  （可能是首次上传，无需同步）');
+  } else {
+    // 2. 运行 scanChange 更新 content_hash（但不改 version_id）
+    //    ⚠️ dry-run 模式下需要保存旧 registry 快照，扫描后恢复，避免污染后续正式执行
+    const oldRegistrySnapshot = dryRun
+      ? JSON.parse(JSON.stringify(oldRegistry))
+      : null;
+
+    console.log('  → 运行语义扫描（更新 content_hash）...');
+    const runtime = require('./ontology/runtime.cjs');
+    const scanResult = runtime.scanChange(specRoot, changeName, {
+      profile: 'auto',
+      markPending: true,
+    });
+    console.log(`  ✓ 语义扫描完成 (valid=${scanResult.valid})`);
+
+    // 3. 读取新 registry（content_hash 已更新，version_id 未变）
+    const newRegistry = readRegistry(changeDir);
+    const newEntries = filterRegistryKeys(newRegistry, filePath);
+
+    // dry-run 恢复：将 registry 恢复为扫描前的状态，确保正式执行时能正确检测变化
+    if (dryRun) {
+      writeRegistry(changeDir, oldRegistrySnapshot);
+      console.log('  ✓ dry-run: 已恢复 ontology-identities.json 到扫描前状态');
+    }
+
+    // 4. 比较 content_hash，为变更实体生成新 version_id
+    for (const { key, entry } of newEntries) {
+      const oldEntry = oldRegistry.identities[key];
+      if (!oldEntry) {
+        // 新增实体，跳过（首次分配由 reconcile 处理）
+        report.structuralSkipped.push({ key, reason: 'new_entity' });
+        continue;
+      }
+
+      if (entry.content_hash === oldEntry.content_hash) {
+        // content_hash 未变，跳过
+        report.structuralSkipped.push({ key, reason: 'unchanged' });
+        continue;
+      }
+
+      // content_hash 变了 → 需要新 version_id
+      try {
+        // 确定正确的 predecessor version-id
+        let predecessorVersionId = entry.version_id;
+        let predecessorSource = 'local';
+
+        if (kbVerifyEnabled) {
+          // 查询 KB 获取当前 version-id
+          const kbResult = await resolveEntityFromKb(kbParams, entry.entity_id);
+          if (kbResult.found && kbResult.entityVersionId) {
+            const kbVersionId = normalizeUuid(kbResult.entityVersionId);
+            if (kbVersionId !== entry.version_id.toLowerCase()) {
+              console.log(`  ⚠️ KB version-id 不一致: local=${entry.version_id}, kb=${kbVersionId}`);
+              console.log(`    → 使用 KB version-id 作为 predecessor`);
+              predecessorVersionId = kbVersionId;
+              predecessorSource = 'kb';
+              report.warnings.push(
+                `${key}: local version ${entry.version_id} != KB version ${kbVersionId}, using KB as predecessor`
+              );
+            }
+          } else if (!kbResult.found) {
+            console.log(`  ⚠️ 实体在 KB 中不存在: ${entry.entity_id} (${key})`);
+            console.log(`    → 可能是首次上传，跳过同步`);
+            report.structuralSkipped.push({ key, reason: 'not_in_kb' });
+            continue;
+          }
+        }
+
+        const newIdentity = allocateIdentity({
+          deltaState: 'modified',
+          entityId: entry.entity_id,
+          predecessorVersionId,
+        });
+
+        if (!dryRun) {
+          entry.version_id = newIdentity.version_id;
+        }
+
+        report.structuralSynced.push({
+          key,
+          type: entry.type,
+          entityId: entry.entity_id,
+          oldVersionId: oldEntry.version_id,
+          newVersionId: newIdentity.version_id,
+          predecessorSource,
+          contentHashChanged: true,
+        });
+
+        console.log(`  ✓ 同步: ${key}`);
+        console.log(`    ${entry.type} entity=${entry.entity_id}`);
+        console.log(`    version: ${oldEntry.version_id} → ${newIdentity.version_id}`);
+        console.log(`    predecessor: ${predecessorVersionId} (来源: ${predecessorSource})`);
+      } catch (e) {
+        report.errors.push({ key, error: e.message });
+        console.error(`  ❌ 同步失败: ${key}: ${e.message}`);
+      }
+    }
+
+    // 5. 写入更新后的 registry
+    if (!dryRun && report.structuralSynced.length > 0) {
+      writeRegistry(changeDir, newRegistry);
+      console.log(`  ✓ 已更新 ontology-identities.json (${report.structuralSynced.length} 个实体)`);
+    }
+
+    // 6. 检测残留实体（registry 中有但 markdown 中已删除的实体）
+    const newKeys = new Set(newEntries.map(e => e.key));
+    const staleKeys = oldEntries.filter(e => !newKeys.has(e.key));
+    if (staleKeys.length > 0) {
+      console.log(`\n  ⚠️ 检测到 ${staleKeys.length} 个残留结构实体（已在 ${filePath} 中删除但 registry 仍有记录）:`);
+      for (const { key, entry } of staleKeys) {
+        console.log(`    - ${key} (entity=${entry.entity_id}, version=${entry.version_id})`);
+        report.warnings.push(`stale_entity: ${key} — 已从 markdown 删除但 registry 仍有记录`);
+      }
+      console.log('  → 这些实体不会影响本次上传（canonical-facts 仅包含当前 markdown 中的实体）');
+      console.log('  → 但建议在 KB 中标记为 removed 或清理 registry 以避免未来锚点复用冲突');
+    }
+  }
+
+  console.log(`  结构实体: ${report.structuralSynced.length} 同步, ${report.structuralSkipped.length} 跳过`);
+
+  // ═════════════════════════════════════════════════════
+  // Part 2: 业务实体同步（STMT / AC / CON / CAP）
+  // ═════════════════════════════════════════════════════
+
+  if (!structuralOnly) {
+    console.log('\n── 业务实体同步 ──');
+
+    const mdContent = fs.readFileSync(mdPath, 'utf8');
+    const identityBlocks = parseIdentityBlocks(mdContent);
+
+    console.log(`  扫描到 ${identityBlocks.length} 个身份块`);
+
+    // ── 从 Part 1 结果中提取 content_hash 变化的 DocumentSection 锚点 ──
+    // key 格式: section:CHG-xxx:spec.md#AC-USER-CRUD-001
+    const changedSectionAnchors = new Set();
+    for (const synced of report.structuralSynced) {
+      if (synced.type === 'DocumentSection' && synced.key) {
+        const hashIndex = synced.key.lastIndexOf('#');
+        if (hashIndex >= 0) {
+          changedSectionAnchors.add(synced.key.substring(hashIndex + 1).toUpperCase());
+        }
+      }
+    }
+
+    // 过滤需要同步的实体
+    let blocksToSync = [];
+
+    if (anchorList) {
+      // 精准模式：只同步指定锚点（用户明确指定，信任用户判断）
+      blocksToSync = identityBlocks.filter(b =>
+        b.anchor && anchorList.some(a => b.anchor.toUpperCase().includes(a)),
+      );
+      console.log(`  精准模式: 匹配 ${blocksToSync.length}/${identityBlocks.length} 个实体（anchors: ${anchorList.join(', ')}）`);
+
+      // 内容变化检测提示（仅信息性，不阻断）
+      const anchorSet = new Set(anchorList);
+      const matchedWithoutChange = blocksToSync.filter(b =>
+        b.deltaState === 'added' && b.anchor && !changedSectionAnchors.has(b.anchor.toUpperCase()),
+      );
+      if (matchedWithoutChange.length > 0) {
+        console.log(`  ℹ️ 其中 ${matchedWithoutChange.length} 个实体在 Part 1 中未检测到 content_hash 变化`);
+        console.log(`    （可能是身份元数据变更或用户强制指定，仍将同步）`);
+      }
+    } else {
+      // 默认/全量模式：基于 Part 1 的 content_hash 变化结果驱动筛选
+      // 只同步 delta-state=added 且对应 DocumentSection content_hash 变化的实体
+      blocksToSync = identityBlocks.filter(b => {
+        if (b.deltaState !== 'added') return false;
+        if (!b.anchor) return false;
+        return changedSectionAnchors.has(b.anchor.toUpperCase());
+      });
+
+      console.log(`  内容驱动模式: ${blocksToSync.length}/${identityBlocks.length} 个实体需要同步`);
+      console.log(`    (DocumentSection content_hash 变化: ${changedSectionAnchors.size} 个)`);
+
+      if (blocksToSync.length === 0 && changedSectionAnchors.size === 0) {
+        console.log('  ✓ 无内容变化，跳过业务实体同步');
+      }
+
+      // 输出未同步的 added 实体（信息性）
+      const unchangedAdded = identityBlocks.filter(b =>
+        b.deltaState === 'added' && b.anchor && !changedSectionAnchors.has(b.anchor.toUpperCase()),
+      );
+      if (unchangedAdded.length > 0) {
+        console.log(`  ℹ️ ${unchangedAdded.length} 个 added 实体内容未变化，保持 added 状态（不污染版本）`);
+      }
+    }
+
+    const mdUpdates = [];
+
+    for (const block of blocksToSync) {
+      try {
+        // 确定正确的 predecessor version-id
+        let predecessorVersionId = block.versionId;
+        let predecessorSource = 'local';
+
+        if (kbVerifyEnabled) {
+          // 查询 KB 获取当前 version-id
+          const kbResult = await resolveEntityFromKb(kbParams, block.entityId);
+          if (kbResult.found && kbResult.entityVersionId) {
+            const kbVersionId = normalizeUuid(kbResult.entityVersionId);
+            if (kbVersionId !== block.versionId.toLowerCase()) {
+              console.log(`  ⚠️ KB version-id 不一致: ${block.anchor || block.entityId}`);
+              console.log(`    local=${block.versionId}, kb=${kbVersionId}`);
+              console.log(`    → 使用 KB version-id 作为 predecessor`);
+              predecessorVersionId = kbVersionId;
+              predecessorSource = 'kb';
+              report.warnings.push(
+                `${block.anchor}: local version ${block.versionId} != KB version ${kbVersionId}, using KB as predecessor`
+              );
+            }
+          } else if (!kbResult.found) {
+            console.log(`  ⚠️ 实体在 KB 中不存在: ${block.anchor || block.entityId} (entity=${block.entityId})`);
+            console.log(`    → 可能是首次上传，仍生成新 version-id（delta-state=added → modified）`);
+            report.warnings.push(
+              `${block.anchor}: entity not found in KB, treating as first-time upload`
+            );
+          }
+        }
+
+        // 生成新 version-id（modified, predecessor=KB验证的 version-id）
+        const newIdentity = allocateIdentity({
+          deltaState: 'modified',
+          entityId: block.entityId,
+          predecessorVersionId,
+        });
+
+        mdUpdates.push({
+          entityId: block.entityId,
+          oldVersionId: block.versionId,
+          newVersionId: newIdentity.version_id,
+          newDeltaState: 'modified',
+          predecessorVersion: predecessorVersionId,
+          anchor: block.anchor,
+        });
+
+        report.businessSynced.push({
+          anchor: block.anchor,
+          entityId: block.entityId,
+          oldVersionId: block.versionId,
+          newVersionId: newIdentity.version_id,
+          predecessorSource,
+        });
+
+        console.log(`  ✓ 同步: ${block.anchor || block.entityId}`);
+        console.log(`    version: ${block.versionId} → ${newIdentity.version_id}`);
+        console.log(`    predecessor: ${predecessorVersionId} (来源: ${predecessorSource})`);
+      } catch (e) {
+        report.errors.push({ anchor: block.anchor, error: e.message });
+        console.error(`  ❌ 同步失败: ${block.anchor || block.entityId}: ${e.message}`);
+      }
+    }
+
+    // 跳过的实体
+    for (const block of identityBlocks) {
+      if (blocksToSync.includes(block)) continue;
+      let reason;
+      if (block.deltaState !== 'added') {
+        reason = `delta-state=${block.deltaState}`;
+      } else if (anchorList) {
+        reason = 'not matched by anchors';
+      } else {
+        reason = 'content unchanged (no DocumentSection hash change)';
+      }
+      report.businessSkipped.push({
+        anchor: block.anchor,
+        reason,
+      });
+    }
+
+    // 更新 markdown 文件
+    if (!dryRun && mdUpdates.length > 0) {
+      const newContent = updateIdentityBlocks(mdContent, mdUpdates);
+      writeTextAtomic(mdPath, newContent);
+      console.log(`  ✓ 已更新 ${filePath} (${mdUpdates.length} 个身份块)`);
+    }
+
+    console.log(`  业务实体: ${report.businessSynced.length} 同步, ${report.businessSkipped.length} 跳过`);
+  }
+
+  // ═════════════════════════════════════════════════════
+  // Part 3: 汇总报告
+  // ═════════════════════════════════════════════════════
+
+  console.log('\n── 同步报告 ──');
+  console.log(`  结构实体: ${report.structuralSynced.length} 同步, ${report.structuralSkipped.length} 跳过`);
+  console.log(`  业务实体: ${report.businessSynced.length} 同步, ${report.businessSkipped.length} 跳过`);
+
+  if (report.warnings.length > 0) {
+    console.log(`  ⚠️ 警告: ${report.warnings.length}`);
+    for (const w of report.warnings) {
+      console.log(`    - ${w}`);
+    }
+  }
+
+  if (report.errors.length > 0) {
+    console.log(`  ❌ 错误: ${report.errors.length}`);
+    for (const e of report.errors) {
+      console.log(`    - ${e.key || e.anchor}: ${e.error}`);
+    }
+  }
+
+  if (dryRun) {
+    console.log('\n⚠️ 干跑模式（--dry-run）：未修改任何文件');
+  } else if (report.structuralSynced.length > 0 || report.businessSynced.length > 0) {
+    console.log('\n✓ 同步完成');
+    console.log('  下一步: 运行 kb-upload.cjs --folder 上传到 KB');
+    console.log('  → node skywalk-sdd/kb-upload.cjs --folder=<变更目录> --project=.');
+  } else {
+    console.log('\n✓ 无需同步（所有实体内容未变更）');
+  }
+}
+
+main().catch(err => {
+  console.error(`\n❌ ${err.message}`);
+  process.exit(1);
+});