kld-sdd 2.7.3 → 2.7.8

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

@@ -77,10 +77,10 @@ function parseIdentityBlocks(content) {
   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;
+  const entityIdRe = /^(\s*(?:-\s+\*\*)?entity-id(?:\*\*)?:\s*)([0-9a-f]{8}(?:-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?)\s*$/i;
+  const versionIdRe = /^(\s*(?:-\s+\*\*)?version-id(?:\*\*)?:\s*)([0-9a-f]{8}(?:-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?)\s*$/i;
+  const deltaStateRe = /^(\s*(?:-\s+\*\*)?delta-state(?:\*\*)?:\s*)(\w+)\s*$/i;
+  const predecessorRe = /^(\s*(?:-\s+\*\*)?predecessor-version(?:\*\*)?:\s*)([0-9a-f]{8}(?:-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?|none|无|\(none\))\s*$/i;
 
   for (let i = 0; i < lines.length; i++) {
     const entityIdMatch = lines[i].match(entityIdRe);
@@ -117,7 +117,7 @@ function parseIdentityBlocks(content) {
     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-]+)\]/);
+      const anchorMatch = line.match(/\[([A-Z]{2,5}-[A-Z0-9-]+)\]/) || line.match(/^change-id:\s*(CHG-[A-Z0-9-]+)/);
       if (anchorMatch) {
         anchor = anchorMatch[1];
         break;
@@ -154,10 +154,10 @@ function parseIdentityBlocks(content) {
  */
 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;
+  const entityIdRe = /^(\s*(?:-\s+\*\*)?entity-id(?:\*\*)?:\s*)([0-9a-f]{8}(?:-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?)\s*$/i;
+  const versionIdRe = /^(\s*(?:-\s+\*\*)?version-id(?:\*\*)?:\s*)([0-9a-f]{8}(?:-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?)\s*$/i;
+  const deltaStateRe = /^(\s*(?:-\s+\*\*)?delta-state(?:\*\*)?:\s*)(\w+)\s*$/i;
+  const predecessorRe = /^(\s*(?:-\s+\*\*)?predecessor-version(?:\*\*)?:\s*)(.+)\s*$/i;
 
   for (const update of updates) {
     // 找到对应的 entity-id 行
@@ -190,7 +190,8 @@ function updateIdentityBlocks(content, updates) {
       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}`);
+            const prefix = lines[j].includes('**') ? `${lines[j].match(/^\s*/)[0]}- **predecessor-version**: ` : 'predecessor-version: ';
+            lines.splice(j + 1, 0, `${prefix}${update.predecessorVersion}`);
             break;
           }
         }
@@ -228,7 +229,7 @@ function filterRegistryKeys(registry, filePath) {
  * @param {string} specRoot
  * @returns {{ kbState: object, projectId: string, kbParams: { apiBase, token, spaceId, kbId } }}
  */
-function initKbConfig(specRoot) {
+function initKbConfig(specRoot, args = {}) {
   // 1. 读取 kb-state.json
   const { config: kbState, warnings } = loadKbState(specRoot);
   if (warnings && warnings.length > 0) {
@@ -258,6 +259,9 @@ function initKbConfig(specRoot) {
 
   // 3. 解析 KB 参数
   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) {
     throw new Error('KB apiKey 未配置（kb-state.json 中缺少 apiKey）。');
   }
@@ -266,13 +270,12 @@ function initKbConfig(specRoot) {
   }
 
   // 4. 校验 project_id 与 spaceKey 一致性
-  const targets = kbState.targets || [];
-  if (targets.length > 0 && targets[0].spaceKey) {
-    if (projectId !== targets[0].spaceKey) {
+  if (target.spaceKey) {
+    if (projectId !== target.spaceKey) {
       throw new Error(
         `project_id 不匹配:\n` +
         `  project-identity.json: ${projectId}\n` +
-        `  kb-state.json spaceKey: ${targets[0].spaceKey}\n` +
+        `  kb-state.json spaceKey: ${target.spaceKey}\n` +
         `请运行 /opsx-kb-config 更新配置。`
       );
     }
@@ -319,33 +322,16 @@ async function resolveEntityFromKb(kbParams, entityId, timeoutMs = 30000) {
   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 };
+    const result = resp?.data || resp;
+    if (result.inheritanceAllowed !== true) {
+      return { found: false, inactive: result.matchType === 'HISTORICAL_ONLY', entityVersionId: null, raw: result };
     }
-
-    // 如果没有 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 };
+    const currentUrl = `${kbParams.apiBase}/v1/spaces/${encodeURIComponent(kbParams.spaceId)}` +
+      `/knowledge-bases/${encodeURIComponent(kbParams.kbId)}/entities/${encodeURIComponent(entityId)}/current-version`;
+    const response = await httpGetJson(currentUrl, kbParams.token, timeoutMs);
+    const current = response?.data || response;
+    if (!current?.entityVersionId || !current.contentHash) throw new Error('当前版本响应缺少版本或内容哈希');
+    return { found: true, entityVersionId: current.entityVersionId, contentHash: current.contentHash, raw: current };
   } catch (e) {
     // KB API 错误（网络/权限/服务器等）
     throw new Error(`KB resolve 失败 (entity=${entityId}): ${e.message}`);
@@ -354,427 +340,89 @@ async function resolveEntityFromKb(kbParams, entityId, timeoutMs = 30000) {
 
 // ── 主流程 ────────────────────────────────────────────
 
-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;
-
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (!args.file || !args.change) throw new Error('需要 --file、--change 和可选的 --project');
   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 changeDir = path.resolve(specRoot, 'openspec', 'changes', args.change);
+  const changesRoot = path.resolve(specRoot, 'openspec', 'changes');
+  if (!changeDir.startsWith(changesRoot + path.sep)) throw new Error('非法 change 路径');
+  const mdPath = path.resolve(changeDir, args.file);
+  if (!mdPath.startsWith(changeDir + path.sep)) throw new Error('非法文件路径');
+  const filePath = path.relative(changeDir, mdPath).split(path.sep).join('/');
+  const { acquireChangeLock, releaseChangeLock } = require('./ontology/change-lock.cjs');
+  const lock = acquireChangeLock(specRoot, args.change);
+  try {
     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());
+    const registry = readRegistry(changeDir);
+    const registryBefore = JSON.parse(JSON.stringify(registry));
+    const { parseChangeArtifacts } = require('./ontology/artifact-parser.cjs');
+    const parsed = parseChangeArtifacts(specRoot, args.change, { persistStructuralIdentities: false });
+    const blocks = parseIdentityBlocks(mdContent);
+    const anchors = args.anchors ? new Set(String(args.anchors).split(',').map(x => x.trim().toUpperCase())) : null;
+    const kbParams = args['skip-kb-verify'] ? null : initKbConfig(specRoot, args).kbParams;
+    const updates = [];
+    const report = { structuralSynced: [], businessSynced: [], skipped: [], errors: [], dryRun: Boolean(args['dry-run']), baselineVerified: Boolean(kbParams) };
+    const cleanHash = value => String(value || '').replace(/^sha256:/, '');
+    // Plan every change before writing. Network errors and stale baselines leave source files untouched.
+    for (const entity of parsed.entities.filter(e => e.source?.file === filePath)) {
+      const structural = ['Artifact', 'DocumentSection'].includes(entity.type);
+      if (!structural && args['structural-only']) continue;
+      if (!structural && anchors && !anchors.has(entity.anchor_id || entity.id)) continue;
+      const registryItem = structural ? Object.entries(registry.identities).find(([, entry]) => entry.entity_id === entity.entity_id) : null;
+      const block = structural ? null : blocks.find(b => b.entityId === entity.entity_id);
+      if (!registryItem && !block) continue;
+      const local = registryItem ? registryItem[1] : entity;
+      const remote = kbParams ? await resolveEntityFromKb(kbParams, entity.entity_id) : null;
+      if (remote?.inactive) throw new Error(`NO_CURRENT_EVIDENCE: ${entity.id} 已失效，不能自动恢复身份`);
+      let next = null;
+      if (remote?.found) {
+        const current = normalizeUuid(remote.entityVersionId);
+        const localVersion = normalizeUuid(local.version_id);
+        if (current !== localVersion) {
+          if (normalizeUuid(local.predecessor_version_id) !== current) {
+            throw new Error(`STALE_BASE_VERSION: ${entity.id} 本地=${localVersion}，当前=${current}；先比较并合并正文，禁止只改 predecessor`);
+          }
+          // This is an unpublished draft already based on current. Its identity stays stable while editing.
+        } else if (cleanHash(remote.contentHash) !== cleanHash(entity.content_hash)) {
+          next = allocateIdentity({ deltaState: entity.delta_state === 'removed' ? 'removed' : 'modified',
+            entityId: entity.entity_id, predecessorVersionId: localVersion });
         }
+      } else if (remote && !remote.found) {
+        if ((local.delta_state || 'added') !== 'added') throw new Error(`BASE_VERSION_MISSING: ${entity.id} 的前驱在目标 KB 中不存在`);
+      } else if (cleanHash(local.content_hash) !== cleanHash(entity.content_hash)) {
+        // Explicit offline mode preserves the real local base. Publication still validates it remotely.
+        next = allocateIdentity({ deltaState: 'modified', entityId: entity.entity_id, predecessorVersionId: local.version_id });
       }
-    }
-
-    // 过滤需要同步的实体
-    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 状态（不污染版本）`);
+      if (registryItem) {
+        Object.assign(registryItem[1], next || {}, { content_hash: entity.content_hash });
+      } else if (next) {
+        updates.push({ entityId: entity.entity_id, oldVersionId: block.versionId, newVersionId: next.version_id,
+          newDeltaState: next.delta_state, predecessorVersion: next.predecessor_version_id });
       }
+      if (next) report[structural ? 'structuralSynced' : 'businessSynced'].push({ anchor: entity.id, ...next });
+      else report.skipped.push(entity.id);
     }
-
-    const mdUpdates = [];
-
-    for (const block of blocksToSync) {
+    if (!args['dry-run']) {
+      const nextContent = updateIdentityBlocks(mdContent, updates);
       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}`);
+        writeTextAtomic(mdPath, nextContent);
+        writeRegistry(changeDir, registry);
+      } catch (error) {
+        writeTextAtomic(mdPath, mdContent);
+        writeRegistry(changeDir, registryBefore);
+        throw error;
       }
     }
-
-    // 跳过的实体
-    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✓ 无需同步（所有实体内容未变更）');
+    console.log(JSON.stringify(report, null, 2));
+    return report;
+  } finally {
+    releaseChangeLock(lock);
   }
 }
 
-main().catch(err => {
+if (require.main === module) main().catch(err => {
   console.error(`\n❌ ${err.message}`);
-  process.exit(1);
+  process.exitCode = 1;
 });
+module.exports = { main, parseIdentityBlocks, updateIdentityBlocks, resolveEntityFromKb };