kld-sdd 2.7.8-5 → 2.7.8-7

package/skywalk-sdd/kb-upload.cjs

@@ -12,6 +12,11 @@
  *   node skywalk-sdd/kb-upload.cjs --folder=<path> [--minimum-level=propose-spec] [--validate-only]
  *   node skywalk-sdd/kb-upload.cjs --package=<zip-path>
  *   node skywalk-sdd/kb-upload.cjs --folder=<path> --project=<spec-root> --change=<name>
+ *   node skywalk-sdd/kb-upload.cjs --folder=<path> --require-review
+ *
+ * 历史产物（缺 entity-id / version-id）：
+ *   自动旁路物化 spec-ontology.json，无 semantic_key 冲突时自动确认并发布为 current；
+ *   有冲突或 --require-review 时只上传候选，需人工 approve-spec-ontology 后再上传。
  *
  * project_id 解析：
  *   1. $SPEC_ROOT/skywalk-sdd/project-identity.json 的 project_id
@@ -50,15 +55,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,9 +248,65 @@ function preCheckProjectId(projectId, state, selectedTarget) {
  *   5. materializeArchivePackage（生成 manifest + canonical-facts + conversion-report + zip）
  *   6. 返回 zip 路径
  */
-function buildPackageFromFolder(specRoot, changeName, options) {
+/**
+ * 历史产物的 Spec 本体解析：
+ *   - 已审核且与当前 Markdown 一致 → 直接复用
+ *   - 否则重新物化。重复锚点、非法 UUID、身份冲突由物化自动改写为稳定身份并确认发布
+ *   - 只有显式 requireReview，或正文没有结构化事实时，才保留候选
+ * 全程不改写 Markdown，只读写 <change>/ontology/spec-ontology.json 与 legacy-mapping.json。
+ */
+function resolveLegacySpecOntology(specRoot, changeName, changeDir, facts, options = {}) {
+  const {
+    buildSpecOntology,
+    materializeChangeSpecOntology,
+    approveSpecOntologyFile,
+    specOntologyContentSignature,
+  } = require('./ontology/spec-ontology.cjs');
+  const { ensureProjectIdentity } = require('./ontology/archive-package.cjs');
+  const identity = ensureProjectIdentity(specRoot);
+  const ontologyPath = path.join(changeDir, 'ontology', 'spec-ontology.json');
+
+  const fresh = buildSpecOntology(facts, {
+    projectId: identity.project_id,
+    compatibilityMode: 'LEGACY_MATERIALIZED',
+    reviewStatus: 'pending',
+  });
+  const freshSignature = specOntologyContentSignature(fresh);
+  const existing = readJsonSafe(ontologyPath);
+  const existingApproved = existing
+    && existing.compatibility_mode === 'LEGACY_MATERIALIZED'
+    && existing.review_status === 'confirmed'
+    && existing.publication_eligible === true
+    && existing.project_id === identity.project_id;
+  if (existingApproved && specOntologyContentSignature(existing) === freshSignature) {
+    return { approved: existing, status: 'reused', path: ontologyPath, collisions: [] };
+  }
+
+  const materialized = materializeChangeSpecOntology(specRoot, changeName, {
+    changeDir,
+    projectId: identity.project_id,
+    compatibilityMode: 'LEGACY_MATERIALIZED',
+    reviewStatus: 'pending',
+  });
+  if (!materialized.validation.valid) {
+    throw new Error(`历史 Spec 本体物化失败: ${materialized.validation.errors.join('; ')}`);
+  }
+  const repairs = (materialized.payload.warnings || [])
+    .filter((warning) => warning.startsWith('LEGACY_DUPLICATE_ANCHOR:') || warning.startsWith('LEGACY_IDENTITY_REPAIRED:'));
+  if (options.requireReview) {
+    return { approved: null, status: 'pending_review', path: ontologyPath, collisions: repairs };
+  }
+  if (materialized.payload.entities.length === 0) {
+    return { approved: null, status: 'needs_review', path: ontologyPath, collisions: repairs };
+  }
+  const approved = approveSpecOntologyFile(materialized.output_path, { allowCollisions: true });
+  return { approved: approved.payload, status: 'auto_approved', path: ontologyPath, collisions: repairs };
+}
+
+function buildPackageFromFolder(specRoot, changeName, options = {}) {
   const runtime = require('./ontology/runtime.cjs');
   const archivePackage = require('./ontology/archive-package.cjs');
+  const { classifyLegacyDiagnostics } = require('./ontology/spec-ontology.cjs');
 
   // 1. 语义管线
   console.log('→ 运行语义管线 (semantic-reconcile)...');
@@ -250,13 +314,20 @@ function buildPackageFromFolder(specRoot, changeName, options) {
     profile: 'auto',
     markPending: true,
   });
+  const legacy = classifyLegacyDiagnostics(semanticResult.diagnostics);
+  const legacyIdentityOnly = legacy.legacyCompatible;
   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')}`);
+    if (!legacyIdentityOnly) {
+      const errors = legacy.blocking.map(d => `${d.code}: ${d.message}`);
+      throw new Error(`语义校验失败:\n${errors.join('\n')}`);
+    }
+    console.warn('⚠️  检测到历史产物缺少身份标识，将生成旁路映射与本体包，不改写 Markdown。');
+    for (const item of legacy.tolerated) {
+      console.warn(`   ↳ 兼容放行 ${item.code}: ${item.message}`);
+    }
+  } 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 +340,63 @@ 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;
+    let legacyStatus = null;
+    if (legacyIdentityOnly) {
+      const resolved = resolveLegacySpecOntology(specRoot, changeName, changeDir, semanticResult.state, {
+        requireReview: Boolean(options.requireReview),
+      });
+      legacyStatus = resolved.status;
+      const messages = {
+        reused: '✓ 已发现审核通过且与当前 Markdown 一致的历史 Spec 本体，直接发布',
+        auto_approved: '✓ 历史 Spec 本体已自动物化并确认，身份和重复锚点已在旁路改写，将发布为 current 事实',
+        needs_review: '⚠️  历史正文没有可发布的结构化事实，仅保留为证据候选',
+        pending_review: 'ℹ️  按 --require-review 要求，历史 Spec 本体保留为待审核候选',
+      };
+      console.log(messages[resolved.status]);
+      result = archivePackage.materializeCompatibilityPackage({
+        projectRoot: specRoot,
+        archiveDir: stagingDir,
+        changeName,
+        facts: semanticResult.state,
+        specOntology: resolved.approved,
+        toleratedDiagnostics: legacy.tolerated,
+        packagePath: zipPath,
+        reason: options.reason || '历史 Spec 兼容入库',
+        method: 'kb-upload-legacy-folder',
+      });
+      console.log(resolved.approved
+        ? '✓ 已生成审核通过的 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',
+      legacyStatus,
+      toleratedDiagnostics: legacyIdentityOnly ? legacy.tolerated : [],
+    };
   } catch (err) {
     // 出错时清理 staging
     fs.rmSync(stagingDir, { recursive: true, force: true });
@@ -313,7 +419,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}`);
@@ -330,6 +436,7 @@ async function main() {
     console.error('  node skywalk-sdd/kb-upload.cjs --folder=<path> [--minimum-level=propose-spec] [--validate-only]');
     console.error('  node skywalk-sdd/kb-upload.cjs --package=<zip-path>');
     console.error('  node skywalk-sdd/kb-upload.cjs --folder=<path> --project=<spec-root> --change=<name>');
+    console.error('  node skywalk-sdd/kb-upload.cjs --folder=<path> --require-review   # 历史产物只上传候选，不自动确认本体');
     process.exit(1);
   }
 
@@ -413,12 +520,17 @@ async function main() {
         markPending: true,
       });
       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 { classifyLegacyDiagnostics } = require('./ontology/spec-ontology.cjs');
+        const legacy = classifyLegacyDiagnostics(semanticResult.diagnostics);
+        if (!legacy.legacyCompatible) {
+          const errors = legacy.blocking.map(d => `${d.code}: ${d.message}`);
+          throw new Error(`语义校验失败:\n${errors.join('\n')}`);
+        }
+        console.log('⚠️  历史产物缺少身份标识，正式上传时将走 LEGACY_MATERIALIZED 旁路物化，不改写 Markdown');
+        for (const item of legacy.tolerated) console.log(`   ↳ 兼容放行 ${item.code}: ${item.message}`);
+      } else {
+        console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
       }
-      console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
       console.log('\n✓ 本地语义校验完成（--validate-only，未联网；不代表权限、发布基线或入库已验证）');
       return;
     }
@@ -438,8 +550,9 @@ async function main() {
 
     // 5. 构建 Archive Package
     console.log('');
-    const { zipPath, manifest, stagingDir } = buildPackageFromFolder(specRoot, changeName, {
+    const { zipPath, manifest, stagingDir, requiresReview, legacyStatus } = buildPackageFromFolder(specRoot, changeName, {
       reason: args.reason,
+      requireReview: Boolean(args['require-review']),
     });
 
     try {
@@ -492,6 +605,7 @@ async function main() {
       const result = await uploadZip(zipPath, state, {
         spaceId: target.spaceId,
         kbId: target.kbId,
+        allowNeedsReview: requiresReview,
       });
 
       console.log('\n── 上传结果 ──');
@@ -504,8 +618,21 @@ 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')}`);
+        if (legacyStatus === 'needs_review') {
+          console.log('  → 正文没有足够的结构化事实，只能作为证据保留');
+        } else {
+          console.log('  → 运行 approve-spec-ontology 后再次上传即可发布；不带 --require-review 上传则自动确认');
+        }
+      } else {
+        // Published commit has been verified; a receipt does not imply projection completion.
+        updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
+      }
 
       // === 投影状态提示 ===
       // 上传成功后，KB 后端异步执行 vector embedding + AGE graph 投影。

package/skywalk-sdd/ontology/archive-package.cjs

@@ -4,6 +4,13 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { generateUuidV7 } = require('./id.cjs');
+const {
+  SPEC_ONTOLOGY_SCHEMA_VERSION,
+  SPEC_ONTOLOGY_PATH,
+  buildSpecOntology,
+  validateSpecOntology,
+  specOntologyContentSignature,
+} = require('./spec-ontology.cjs');
 const { resolveRuntimeMetadata } = require('../runtime-metadata.cjs');
 const {
   readJson,
@@ -581,6 +588,18 @@ function materializeArchivePackage(options = {}) {
   );
   const canonicalPath = path.join(archiveDir, CANONICAL_FACTS_PATH);
   const canonicalBytes = writeJsonAtomic(canonicalPath, canonicalFacts);
+  const specOntology = buildSpecOntology(snapshot, {
+    projectId: projectIdentity.project_id,
+    archiveId,
+    compatibilityMode: 'ADAPTED_V2',
+    reviewStatus: 'confirmed',
+  });
+  const specOntologyValidation = validateSpecOntology(specOntology);
+  if (!specOntologyValidation.valid) {
+    throw new Error(`Spec 本体事实包校验失败: ${specOntologyValidation.errors.join('; ')}`);
+  }
+  const specOntologyPath = path.join(archiveDir, SPEC_ONTOLOGY_PATH);
+  writeJsonAtomic(specOntologyPath, specOntology);
 
   const conversionReport = {
     schema_version: CONVERSION_REPORT_SCHEMA_VERSION,
@@ -589,6 +608,9 @@ function materializeArchivePackage(options = {}) {
     source_schema: String(snapshot.schema_version || 'unknown'),
     target_file: CANONICAL_FACTS_PATH,
     target_schema: CANONICAL_FACTS_SCHEMA_VERSION,
+    spec_ontology_file: SPEC_ONTOLOGY_PATH,
+    spec_ontology_schema: SPEC_ONTOLOGY_SCHEMA_VERSION,
+    compatibility_mode: specOntology.compatibility_mode,
     status: 'converted',
     entity_count: canonicalFacts.entities.length,
     relation_count: canonicalFacts.relations.length,
@@ -618,6 +640,9 @@ function materializeArchivePackage(options = {}) {
     change_id: changeId,
     content_hash: `sha256:${sha256(canonicalBytes)}`,
     canonical_facts_path: CANONICAL_FACTS_PATH,
+    spec_ontology_path: SPEC_ONTOLOGY_PATH,
+    spec_ontology_schema: SPEC_ONTOLOGY_SCHEMA_VERSION,
+    compatibility_mode: specOntology.compatibility_mode,
     conversion_report_path: CONVERSION_REPORT_PATH,
     created_at: createdAt,
     files,
@@ -647,6 +672,121 @@ function materializeArchivePackage(options = {}) {
     conversion_report: conversionReport,
     manifest_path: existingManifestPath,
     canonical_facts_path: canonicalPath,
+    spec_ontology_path: specOntologyPath,
+    conversion_report_path: path.join(archiveDir, CONVERSION_REPORT_PATH),
+    package_path: packagePath,
+  };
+}
+
+function materializeCompatibilityPackage(options = {}) {
+  const projectRoot = path.resolve(options.projectRoot || process.cwd());
+  const archiveDir = path.resolve(requiredText(options.archiveDir, 'archiveDir', 'Compatibility Package'));
+  const facts = options.facts;
+  if (!facts || !Array.isArray(facts.entities)) {
+    throw new Error('Compatibility Package 缺少已解析 facts');
+  }
+  const projectIdentity = ensureProjectIdentity(projectRoot);
+  const changeName = requiredText(options.changeName || facts.change, 'changeName', 'Compatibility Package');
+  const changeId = String(facts.change_id || `CHG-LEGACY-${sha256(changeName).slice(0, 12)}`).toUpperCase();
+  const publicationVariant = options.specOntology?.review_status === 'confirmed' ? 'reviewed' : 'candidate';
+  const archiveId = `urn:kld:sdd:archive:${sha256(
+    `${projectIdentity.project_id}\n${changeId}\n${facts.facts_hash || sha256(JSON.stringify(facts))}\n${publicationVariant}`,
+  )}`;
+  let specOntology;
+  if (options.specOntology) {
+    specOntology = JSON.parse(JSON.stringify(options.specOntology));
+    if (specOntology.project_id !== projectIdentity.project_id) {
+      throw new Error('已审核 Spec 本体的 project_id 与当前项目不一致，请重新物化并审核');
+    }
+    if (specOntology.compatibility_mode !== 'LEGACY_MATERIALIZED') {
+      throw new Error('兼容包只接受 LEGACY_MATERIALIZED 本体');
+    }
+    if (specOntology.review_status !== 'confirmed' || specOntology.publication_eligible !== true) {
+      throw new Error('历史 Spec 本体尚未审核，不能发布为 current 事实');
+    }
+    const currentOntology = buildSpecOntology({ ...facts, change_id: changeId }, {
+      projectId: projectIdentity.project_id,
+      compatibilityMode: 'LEGACY_MATERIALIZED',
+      reviewStatus: 'pending',
+    });
+    if (specOntologyContentSignature(specOntology) !== specOntologyContentSignature(currentOntology)) {
+      throw new Error('已审核 Spec 本体与当前 Markdown 内容不一致，请重新物化并审核');
+    }
+    specOntology.archive_id = archiveId;
+    specOntology.change = changeName;
+    specOntology.change_id = changeId;
+    delete specOntology.ontology_hash;
+    specOntology.ontology_hash = `sha256:${sha256(JSON.stringify(specOntology))}`;
+  } else {
+    specOntology = buildSpecOntology({ ...facts, change_id: changeId }, {
+      projectId: projectIdentity.project_id,
+      archiveId,
+      compatibilityMode: 'LEGACY_MATERIALIZED',
+      reviewStatus: 'pending',
+    });
+  }
+  const validation = validateSpecOntology(specOntology);
+  if (!validation.valid) {
+    throw new Error(`历史 Spec 本体物化失败: ${validation.errors.join('; ')}`);
+  }
+  const toleratedDiagnostics = (options.toleratedDiagnostics || [])
+    .map((item) => `LEGACY_DIAGNOSTIC_TOLERATED: ${item.code}: ${item.message}`);
+  const specOntologyPath = path.join(archiveDir, SPEC_ONTOLOGY_PATH);
+  const specOntologyBytes = writeJsonAtomic(specOntologyPath, specOntology);
+  const conversionReport = {
+    schema_version: CONVERSION_REPORT_SCHEMA_VERSION,
+    producer: PRODUCER,
+    source_file: 'legacy-markdown',
+    source_schema: String(facts.schema_version || 'legacy-markdown'),
+    target_file: SPEC_ONTOLOGY_PATH,
+    target_schema: SPEC_ONTOLOGY_SCHEMA_VERSION,
+    compatibility_mode: 'LEGACY_MATERIALIZED',
+    status: specOntology.publication_eligible ? 'materialized_reviewed' : 'materialized_pending_review',
+    entity_count: specOntology.entities.length,
+    relation_count: specOntology.relations.length,
+    warnings: [...new Set([...(specOntology.warnings || []), ...toleratedDiagnostics])],
+  };
+  writeJsonAtomic(path.join(archiveDir, CONVERSION_REPORT_PATH), conversionReport);
+
+  const createdAt = options.archivedAt || new Date().toISOString();
+  const filePaths = collectPackageFilePaths(archiveDir);
+  const files = filePaths.map((relativePath) => ({
+    path: relativePath,
+    content_hash: `sha256:${sha256(fs.readFileSync(path.join(archiveDir, relativePath)))}`,
+  }));
+  const manifest = {
+    schema_version: MANIFEST_SCHEMA_VERSION,
+    producer: PRODUCER,
+    project_id: projectIdentity.project_id,
+    archive_id: archiveId,
+    change_id: changeId,
+    content_hash: `sha256:${sha256(specOntologyBytes)}`,
+    canonical_facts_path: null,
+    spec_ontology_path: SPEC_ONTOLOGY_PATH,
+    spec_ontology_schema: SPEC_ONTOLOGY_SCHEMA_VERSION,
+    compatibility_mode: 'LEGACY_MATERIALIZED',
+    conversion_report_path: CONVERSION_REPORT_PATH,
+    created_at: createdAt,
+    files,
+    change: changeName,
+    archived_at: createdAt,
+    reason: options.reason || '历史 Spec 本体兼容入库',
+    method: options.method || 'legacy-spec-ontology-materialization',
+    source_path: options.sourcePath || '',
+    archive_path: toPosix(path.relative(projectRoot, archiveDir)),
+    copied_specs: [],
+    evidence_events_path: null,
+  };
+  const manifestPath = path.join(archiveDir, MANIFEST_PATH);
+  writeJsonAtomic(manifestPath, manifest);
+  const packagePath = path.resolve(options.packagePath || `${archiveDir}.zip`);
+  writeArchiveZip(archiveDir, packagePath, manifest);
+  return {
+    manifest,
+    conversion_report: conversionReport,
+    validation,
+    manifest_path: manifestPath,
+    spec_ontology_path: specOntologyPath,
     conversion_report_path: path.join(archiveDir, CONVERSION_REPORT_PATH),
     package_path: packagePath,
   };
@@ -707,5 +847,6 @@ module.exports = {
   readStoredZipEntries,
   verifyArchivePackage,
   materializeArchivePackage,
+  materializeCompatibilityPackage,
   finalizeArchivePackageAfterReports,
 };

package/skywalk-sdd/ontology/artifact-parser.cjs

@@ -6,7 +6,7 @@ const path = require('path');
 const { DIAGNOSTIC_CODES, entityTypeForId } = require('./schema.cjs');
 const { ensureStructuralIdentities } = require('./structural-identity.cjs');
 
-const ENTITY_ID_PATTERN = /\b(?:CHG|CAP|STMT|AC|CON|DES|TASK|ART|SEC|SNAP)-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/gi;
+const ENTITY_ID_PATTERN = /\b(?:CHG|OBJ|CAP|STMT|AC|CON|DES|TASK|ART|SEC|SNAP)-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/gi;
 const IDENTITY_META_PATTERN = /^\s*-\s+\*\*(entity-id|version-id|predecessor-version|delta-state|external-ref)\*\*\s*[：:]\s*(.*?)\s*$/i;
 
 function toPosix(value) {
@@ -444,7 +444,7 @@ function parseSpec(target, file, lines, frontmatter) {
       });
       continue;
     }
-    const inheritedRelationMatch = line.match(/^\s*-\s+\*\*relation\*\*\s*[：:]\s*`?((?:CHG|CAP|STMT|AC|CON|DES|TASK)-[A-Z0-9-]+)\s+(contains|acceptedBy|constrainedBy|realizes|implements|covers|dependsOn)\s+((?:CHG|CAP|STMT|AC|CON|DES|TASK)-[A-Z0-9-]+)`?\s*$/i);
+    const inheritedRelationMatch = line.match(/^\s*-\s+\*\*relation\*\*\s*[：:]\s*`?((?:CHG|OBJ|CAP|STMT|AC|CON|DES|TASK)-[A-Z0-9-]+)\s+(contains|usesObject|acceptedBy|constrainedBy|realizes|implements|covers|dependsOn)\s+((?:CHG|OBJ|CAP|STMT|AC|CON|DES|TASK)-[A-Z0-9-]+)`?\s*$/i);
     if (inheritedRelationMatch) {
       let source = '';
       for (let offset = index + 1; offset < Math.min(lines.length, index + 6); offset += 1) {
@@ -461,7 +461,28 @@ function parseSpec(target, file, lines, frontmatter) {
       });
       continue;
     }
-    let match = line.match(/^\s*####\s+需求项[：:]\s*[【\[]?(STMT-[A-Z0-9-]+)[】\]]?\s*(.*?)\s*$/i);
+    let match = line.match(/^\s*####\s+业务对象[：:]\s*[【\[]?(OBJ-[A-Z0-9-]+)[】\]]?\s*(.*?)\s*$/i);
+    if (match) {
+      const objectId = match[1].toUpperCase();
+      const endIndex = sectionEnd(lines, index, 4);
+      addEntity(
+        target,
+        'BusinessObject',
+        objectId,
+        match[2],
+        file,
+        index + 1,
+        { capability_id: capabilityId || undefined },
+        parseIdentityBlock(lines, index + 1, endIndex),
+        lines.slice(index, endIndex).join('\n'),
+      );
+      if (capabilityId) {
+        addRelation(target, 'usesObject', capabilityId, objectId, file, index + 1, 'asserted');
+      }
+      continue;
+    }
+
+    match = line.match(/^\s*####\s+需求项[：:]\s*[【\[]?(STMT-[A-Z0-9-]+)[】\]]?\s*(.*?)\s*$/i);
     if (match) {
       currentStatement = match[1].toUpperCase();
       currentConstraint = '';

package/skywalk-sdd/ontology/cli.cjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 const {
   scanChange,
@@ -18,6 +19,11 @@ const listChanges = require('./list-changes.cjs');
 const sddConfig = require('./sdd-config.cjs');
 const activeChanges = require('./active-changes.cjs');
 const { resolveProjectArg } = require('./resolve-spec-root.cjs');
+const {
+  materializeChangeSpecOntology,
+  validateSpecOntology,
+  approveSpecOntologyFile,
+} = require('./spec-ontology.cjs');
 
 function parseArgs(argv) {
   const result = { _: [] };
@@ -77,6 +83,9 @@ function showHelp() {
   node skywalk-sdd/ontology/cli.cjs status    --project=. --change=<name>
   node skywalk-sdd/ontology/cli.cjs observe   --project=. --change=<name> [--interval=1500]
   node skywalk-sdd/ontology/cli.cjs snapshot  --project=. --change=<name> --archive=<path>
+  node skywalk-sdd/ontology/cli.cjs materialize-ontology --project=. --change=<name> [--output=<path>]
+  node skywalk-sdd/ontology/cli.cjs validate-spec-ontology --file=<spec-ontology.json>
+  node skywalk-sdd/ontology/cli.cjs approve-spec-ontology --file=<spec-ontology.json>
 
 observe 只负责采集和同步；check/archive 前仍必须执行 reconcile。`);
 }
@@ -254,11 +263,55 @@ function main(argv = process.argv.slice(2)) {
     if (!result.ok) process.exitCode = 1;
     return;
   }
+  if (command === 'validate-spec-ontology') {
+    const filePath = path.resolve(args.file || args._[1] || 'spec-ontology.json');
+    const payload = JSON.parse(fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, ''));
+    const result = validateSpecOntology(payload);
+    console.log(JSON.stringify({ file: filePath, ...result }, null, 2));
+    if (!result.valid) process.exitCode = 1;
+    return;
+  }
+  if (command === 'approve-spec-ontology') {
+    const filePath = path.resolve(args.file || args._[1] || 'spec-ontology.json');
+    const result = approveSpecOntologyFile(filePath, {
+      allowCollisions: args['allow-collisions'] === true,
+    });
+    console.log(JSON.stringify({
+      file: result.file,
+      compatibility_mode: result.payload.compatibility_mode,
+      review_status: result.payload.review_status,
+      publication_eligible: result.payload.publication_eligible,
+      validation: result.validation,
+      warnings: result.payload.warnings,
+    }, null, 2));
+    if (!result.validation.valid) process.exitCode = 1;
+    return;
+  }
   const projectRoot = resolveCliProject(args);
   const changeName = args.change;
   if (!changeName) throw new Error('缺少 --change 参数');
   const profile = args.profile || 'auto';
 
+  if (command === 'materialize-ontology' || command === 'materialize') {
+    const result = materializeChangeSpecOntology(projectRoot, changeName, {
+      outputPath: args.output,
+      mappingPath: args.mapping,
+      reviewStatus: args['review-status'],
+    });
+    console.log(JSON.stringify({
+      change: changeName,
+      compatibility_mode: result.payload.compatibility_mode,
+      review_status: result.payload.review_status,
+      publication_eligible: result.payload.publication_eligible,
+      output_path: result.output_path,
+      mapping_path: result.mapping_path,
+      validation: result.validation,
+      warnings: result.payload.warnings,
+    }, null, 2));
+    if (!result.validation.valid) process.exitCode = 1;
+    return;
+  }
+
   if (command === 'scan') {
     const result = scanChange(projectRoot, changeName, { profile });
     console.log(JSON.stringify(summary({ ...result, changed: false, paths: undefined }), null, 2));

package/skywalk-sdd/ontology/id.cjs

@@ -42,7 +42,7 @@ function nextEntityId(prefix, scope, existingIds = []) {
 
 function isValidEntityId(entityId, expectedType = '') {
   const value = String(entityId || '').trim().toUpperCase();
-  if (!/^(?:CHG|CAP|STMT|AC|CON|DES|TASK|ART|SEC|SNAP)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/.test(value)) {
+  if (!/^(?:CHG|OBJ|CAP|STMT|AC|CON|DES|TASK|ART|SEC|SNAP)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/.test(value)) {
     return false;
   }
   if (expectedType && entityTypeForId(value) !== expectedType) {

package/skywalk-sdd/ontology/schema.cjs

@@ -4,6 +4,7 @@ const SCHEMA_VERSION = 'kld-sdd-ontology/v2';
 
 const ENTITY_TYPES = Object.freeze([
   'Change',
+  'BusinessObject',
   'Capability',
   'SpecificationStatement',
   'AcceptanceCriterion',
@@ -17,6 +18,7 @@ const ENTITY_TYPES = Object.freeze([
 
 const ID_PREFIX_TYPES = Object.freeze({
   CHG: 'Change',
+  OBJ: 'BusinessObject',
   CAP: 'Capability',
   STMT: 'SpecificationStatement',
   AC: 'AcceptanceCriterion',
@@ -37,6 +39,10 @@ const RELATION_TYPES = Object.freeze({
       Object.freeze(['Capability', 'SpecificationStatement']),
     ]),
   }),
+  usesObject: Object.freeze({
+    domain: Object.freeze(['Capability']),
+    range: Object.freeze(['BusinessObject']),
+  }),
   acceptedBy: Object.freeze({
     domain: Object.freeze(['SpecificationStatement']),
     range: Object.freeze(['AcceptanceCriterion']),