kld-sdd 2.7.3 → 2.7.8-2

package/skywalk-sdd/kb-upload.cjs

@@ -33,19 +33,48 @@ const {
   httpGetJson,
 } = require('./lib/shared.cjs');
 
+function resolveUploadTarget(state, options = {}) {
+  if (Boolean(options.spaceId) !== Boolean(options.kbId)) throw new Error('必须同时指定 --space-id 和 --kb-id');
+  const targets = state.targets || [];
+  if (options.spaceId && options.kbId) {
+    return targets.find(t => t.spaceId === options.spaceId && t.kbId === options.kbId) || options;
+  }
+  if (targets.length !== 1) throw new Error('请明确上传目标：配置一个知识库，或同时指定 --space-id 和 --kb-id；不会自动分发到多个 KB');
+  if (!targets[0].spaceId || !targets[0].kbId) throw new Error('知识库目标缺少 spaceId/kbId');
+  return targets[0];
+}
+
+function cacheKey(changeName, context) {
+  if (!context?.api || !context?.spaceId || !context?.kbId) return null;
+  return JSON.stringify([context.api.replace(/\/+$/, ''), context.spaceId, context.kbId, changeName]);
+}
+
+function assertIngestionResult(result) {
+  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') {
+    throw new Error(`VERSION_CONFLICT: 事实包已保存为候选，当前事实未更新；请合并基线后重新发布。job=${job.jobId}`);
+  }
+  return job;
+}
+
 /**
  * 读取 kb-state.json 中指定 change 的 archive 缓存。
  * @param {string} specRoot
  * @param {string} changeName
  * @returns {object|null} { archive_id, content_hash, uploaded_at }
  */
-function readArchiveCache(specRoot, changeName) {
+function readArchiveCache(specRoot, changeName, context) {
   const directPath = path.join(specRoot, 'kb-state.json');
   const legacyPath = path.join(specRoot, '..', '.shared', 'kb-state.json');
   const statePath = fs.existsSync(directPath) ? directPath : legacyPath;
   const state = readJsonSafe(statePath);
   if (!state || !state.archiveCache) return null;
-  return state.archiveCache[changeName] || null;
+  const key = cacheKey(changeName, context);
+  return key ? state.archiveCache[key] || null : null;
 }
 
 /**
@@ -55,16 +84,19 @@ function readArchiveCache(specRoot, changeName) {
  * @param {string} archiveId
  * @param {string} contentHash
  */
-function updateKbStateCache(specRoot, changeName, archiveId, contentHash) {
+function updateKbStateCache(specRoot, changeName, archiveId, contentHash, context) {
   const directPath = path.join(specRoot, 'kb-state.json');
   const legacyPath = path.join(specRoot, '..', '.shared', 'kb-state.json');
   const statePath = fs.existsSync(directPath) ? directPath : legacyPath;
   const state = readJsonSafe(statePath) || {};
   if (!state.archiveCache) state.archiveCache = {};
-  state.archiveCache[changeName] = {
+  const key = cacheKey(changeName, context);
+  if (!key) throw new Error('缓存必须包含 API、Space 和 KB');
+  state.archiveCache[key] = {
     archive_id: archiveId,
     content_hash: contentHash,
     uploaded_at: new Date().toISOString(),
+    target: context,
   };
   writeJsonAtomic(statePath, state);
   console.log(`✓ 已更新本地缓存: ${changeName} → ${archiveId.slice(0, 24)}...`);
@@ -144,7 +176,11 @@ function readKbState(specRoot) {
  */
 function validateRequiredFiles(folderPath, minimumLevel) {
   const required = MINIMUM_LEVELS[minimumLevel] || MINIMUM_LEVELS[DEFAULT_LEVEL];
-  const missing = required.filter(f => !fs.existsSync(path.join(folderPath, f)));
+  const specsDir = path.join(folderPath, 'specs');
+  const capabilityDirs = fs.existsSync(specsDir) ? fs.readdirSync(specsDir, { withFileTypes: true })
+    .filter(e => e.isDirectory()).map(e => path.join(specsDir, e.name)) : [];
+  const missing = required.filter(f => !fs.existsSync(path.join(folderPath, f))
+    && !(f !== 'proposal.md' && capabilityDirs.length > 0 && capabilityDirs.every(d => fs.existsSync(path.join(d, f)))));
   if (missing.length > 0) {
     throw new Error(
       `[${minimumLevel}] 缺少必需文件: ${missing.join(', ')}\n` +
@@ -162,11 +198,11 @@ function validateRequiredFiles(folderPath, minimumLevel) {
 /**
  * 本地预检 project_id === spaceKey
  */
-function preCheckProjectId(projectId, state) {
+function preCheckProjectId(projectId, state, selectedTarget) {
   if (!state.targets || !state.targets[0]) {
     throw new Error('KB 配置中无 targets，请运行 /opsx-kb-config 配置知识库。');
   }
-  const spaceKey = state.targets[0].spaceKey;
+  const spaceKey = (selectedTarget || resolveUploadTarget(state)).spaceKey;
   if (!spaceKey) {
     console.warn('⚠️  kb-state.json targets[0].spaceKey 为空，跳过本地预检');
     return;
@@ -255,15 +291,9 @@ function buildPackageFromFolder(specRoot, changeName, options) {
  * 上传 zip 到 KB（使用 Node.js HTTP，替代 curl）
  */
 async function uploadZip(zipPath, state, options) {
-  const target = options.spaceId && options.kbId
-    ? { spaceId: options.spaceId, kbId: options.kbId }
-    : state.targets[0];
+  const target = resolveUploadTarget(state, options);
 
-  if (!target || !target.spaceId || !target.kbId) {
-    throw new Error('未指定目标 Space/KB，请运行 /opsx-kb-config 配置知识库。');
-  }
-
-  const apiUrl = state.api || 'http://localhost:8090/api';
+  const apiUrl = (state.api || 'http://localhost:8090/api').replace(/\/+$/, '');
   const uploadUrl = `${apiUrl}/v1/spaces/${target.spaceId}/knowledge-bases/${target.kbId}/ingestions`;
 
   console.log(`→ 上传到 KB: ${target.spaceName || target.spaceId}/${target.kbName || target.kbId}`);
@@ -272,6 +302,7 @@ async function uploadZip(zipPath, state, options) {
 
   try {
     const result = await uploadFile(uploadUrl, zipPath, state.apiKey);
+    assertIngestionResult(result);
     return result;
   } catch (err) {
     throw new Error(`上传失败: ${err.message}`);
@@ -339,6 +370,11 @@ async function main() {
       changeName = path.basename(folderPath);
     }
 
+    const expectedFolder = path.resolve(specRoot, 'openspec', 'changes', changeName);
+    if (path.resolve(folderPath) !== expectedFolder || !expectedFolder.startsWith(path.resolve(specRoot, 'openspec', 'changes') + path.sep)) {
+      throw new Error('文件夹上传仅接受当前 Spec 仓 openspec/changes/<change>；已归档内容请用 --zip 指定归档包');
+    }
+
     if (!fs.existsSync(folderPath)) {
       throw new Error(`变更目录不存在: ${folderPath}`);
     }
@@ -362,7 +398,9 @@ async function main() {
     if (!state.apiKey) {
       throw new Error('KB 配置中无 apiKey，请运行 /opsx-kb-config 配置知识库。');
     }
-    preCheckProjectId(projectId, state);
+    const target = resolveUploadTarget(state, { spaceId: args['space-id'], kbId: args['kb-id'] });
+    preCheckProjectId(projectId, state, target);
+    const cacheContext = { api: state.api || 'http://localhost:8090/api', spaceId: target.spaceId, kbId: target.kbId };
 
     // 4. 仅校验模式（含语义校验）
     if (args['validate-only']) {
@@ -390,26 +428,8 @@ async function main() {
     });
 
     try {
-      // === Step 5.1: 本地缓存快速检查 ===
-      const cache = readArchiveCache(specRoot, changeName);
-      if (cache && cache.archive_id === manifest.archive_id) {
-        console.log('\n✓ 内容无变更（archive_id 与上次成功上传一致），跳过上传');
-        console.log(`  cached archive_id: ${cache.archive_id}`);
-        console.log(`  uploaded_at: ${cache.uploaded_at}`);
-        console.log('\n✓ 完成（本地缓存命中）');
-        return;
-      }
-
-      // 解析上传目标
-      const target = (args['space-id'] && args['kb-id'])
-        ? { spaceId: args['space-id'], kbId: args['kb-id'] }
-        : state.targets[0];
-
-      if (!target || !target.spaceId || !target.kbId) {
-        throw new Error('未指定目标 Space/KB，请运行 /opsx-kb-config 配置知识库。');
-      }
-
-      const apiUrl = state.api || 'http://localhost:8090/api';
+      // Local receipts are informational only. Always verify the selected destination remotely.
+      const apiUrl = (state.api || 'http://localhost:8090/api').replace(/\/+$/, '');
 
       // === Step 5.5: KB 预检（网络级幂等确认）===
       const archiveId = manifest.archive_id;
@@ -424,11 +444,13 @@ async function main() {
       try {
         const checkResult = await httpGetJson(checkUrl, state.apiKey);
 
-        if (checkResult && checkResult.data && checkResult.data.idempotent) {
+        if (checkResult?.data?.idempotent && checkResult.data.publicationStatus === 'published') {
           console.log('\n✓ KB 中已存在相同 archive（幂等命中），跳过上传');
           console.log(`  snapshot_id: ${checkResult.data.snapshotId}`);
-          updateKbStateCache(specRoot, changeName, archiveId, contentHash);
-          console.log('\n✓ 完成（KB 预检命中）');
+          updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
+          console.log(`  publication: ${checkResult.data.publicationStatus}; projection: ${checkResult.data.projectionStatus}`);
+          if (['failed', 'degraded'].includes(checkResult.data.projectionStatus)) console.log('⚠️ 检索准备尚未完成，请在知识库概览重试该任务的投影');
+          console.log('\n✓ 归档已存在（检索状态以上述回执为准）');
           return;
         }
 
@@ -467,8 +489,8 @@ async function main() {
       console.log(`  change_id:  ${manifest.change_id}`);
       console.log(`  files:      ${manifest.files.length}`);
 
-      // === 上传成功后更新本地缓存 ===
-      updateKbStateCache(specRoot, changeName, archiveId, contentHash);
+      // Canonical commit has been verified; a receipt does not imply projection completion.
+      updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
 
       // === 投影状态提示 ===
       // 上传成功后，KB 后端异步执行 vector embedding + AGE graph 投影。
@@ -479,9 +501,9 @@ async function main() {
       if (projStatus === 'complete') {
         console.log('\n✓ 投影已完成，向量/图检索可用');
       } else if (projStatus === 'degraded') {
-        console.log('\n⚠️  投影完成但有降级（部分通道不可用，FTS 仍可用）');
+        console.log('\n⚠️  投影完成但有降级（部分通道不可用，召回结果会标记降级）');
       } else if (projStatus === 'disabled') {
-        console.log('\nℹ️  投影已禁用（FTS-only 模式）');
+        console.log('\nℹ️  投影已禁用（仅可使用当前已就绪的检索通道）');
       } else if (projStatus && projStatus !== 'complete') {
         console.log(`\nℹ️  投影进行中 (${projStatus})，向量/图检索暂不可用`);
         console.log('  → 正常 SDD 流程中阶段间间隔通常足够投影完成');
@@ -502,4 +524,5 @@ async function main() {
   }
 }
 
-main();
+if (require.main === module) main();
+module.exports = { resolveUploadTarget, readArchiveCache, updateKbStateCache, assertIngestionResult, uploadZip, buildPackageFromFolder, validateRequiredFiles };

package/skywalk-sdd/lib/check-review.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+const CATEGORIES = ['completeness', 'consistency', 'executability', 'tdd_compliance'];
+
+function assembleReview(review, taskCompletion, options = {}) {
+  if (!review || !Array.isArray(review.items) || !review.items.length) throw new Error('CHECK_ITEMS_REQUIRED: 提供实际评审项，不能提交空模板');
+  const categories = Object.fromEntries(CATEGORIES.map(key => [key, { passed: 0, total: 0 }]));
+  const warnings = [], suggestions = [], ids = new Set();
+  for (const item of review.items) {
+    if (!item.id || ids.has(item.id)) throw new Error('CHECK_ITEM_ID_INVALID: 检查项必须有唯一 ID');
+    ids.add(item.id);
+    if (!CATEGORIES.includes(item.category) || !['passed', 'error', 'warning', 'suggestion', 'na'].includes(item.status)) throw new Error('CHECK_ITEM_STATUS_INVALID');
+    if (typeof item.evidence !== 'string' || !item.evidence.trim()) throw new Error(`CHECK_ITEM_EVIDENCE_REQUIRED: ${item.id} 缺少来源证据或不适用原因`);
+    if (item.status === 'na') continue;
+    categories[item.category].total++;
+    if (item.status !== 'error') categories[item.category].passed++;
+    if (item.status === 'warning') warnings.push({ category: item.category, warning: item.id, description: item.description || item.evidence, target: item.evidence });
+    if (item.status === 'suggestion') suggestions.push(item);
+  }
+  const total = Object.values(categories).reduce((n, c) => n + c.total, 0);
+  const passed = Object.values(categories).reduce((n, c) => n + c.passed, 0);
+  if (!total) throw new Error('CHECK_ITEMS_REQUIRED: 至少有一个实际适用的评审项');
+  if (taskCompletion.has_incomplete) warnings.push({ category: 'task_completion', warning: 'TASKS_INCOMPLETE', description: `${taskCompletion.incomplete} 个任务尚未完成`, target: 'tasks.md' });
+  const result = total !== passed ? 'failure' : (warnings.length ? 'partial' : 'success');
+  return {
+    result,
+    details: { check_results: {
+      ...review.reviewer,
+      total, errors: total - passed, warnings: warnings.length, suggestions: suggestions.length,
+      categories, warning_items: warnings, warning_dispositions: review.warning_dispositions || [],
+      // This field means items satisfied before implementation, not defect fixes.
+      fixed_before_apply: options.beforeApply ? passed : Math.min(total, options.previousBeforeApply || 0),
+      consistency_score: null,
+      task_completion: { ...taskCompletion, checked_for_archive_readiness: !options.beforeApply },
+      review_items: review.items,
+      review_revision: options.revision,
+    } },
+  };
+}
+
+module.exports = { assembleReview };

package/skywalk-sdd/lib/test-execution.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+function parseCounts(output) {
+  // Prefer runner totals: counting TAP parent suites as tests double-counts nested tests.
+  const value = name => {
+    const matches = [...output.matchAll(new RegExp(`^(?:#|ℹ)\\s+${name}\\s+(\\d+)\\s*$`, 'gm'))];
+    return matches.length ? Number(matches[matches.length - 1][1]) : null;
+  };
+  const total = value('tests'), passed = value('pass'), failed = value('fail');
+  const skipped = value('skipped'), todo = value('todo');
+  if ([total, passed, failed].every(Number.isInteger)
+      && total === passed + failed + (skipped || 0) + (todo || 0)) {
+    return { counts_known: true, passed, failed, skipped: (skipped || 0) + (todo || 0) };
+  }
+  return { counts_known: false };
+}
+
+function classifyFailure(output, exitCode, error, signal) {
+  if (error?.code === 'ETIMEDOUT') return 'timeout';
+  if (error || signal) return 'infrastructure';
+  if (exitCode === 0) return 'none';
+  // A missing executable/module/test path is not evidence of a failing business assertion.
+  if (/MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND|Cannot find module|Could not find|ENOENT|SyntaxError|ERR_TEST_FAILURE.*cancelled/i.test(output)) return 'infrastructure';
+  if (/ERR_ASSERTION|AssertionError|AssertionFailedError|org\.opentest4j\.AssertionFailedError/.test(output)) return 'assertion';
+  return 'infrastructure';
+}
+
+function captureTest(args, projectRoot, change) {
+  let command;
+  try { command = JSON.parse(args['command-json'] || 'null'); } catch { /* validated below */ }
+  if (!Array.isArray(command) || !command.length || command.some(x => typeof x !== 'string' || x.includes('\0')) || !command[0]) {
+    throw new Error('TEST_COMMAND_REQUIRED: --command-json 必须是非空命令参数数组，不通过 shell 执行');
+  }
+  const phase = args['tdd-phase'] || 'regression';
+  if (!['red', 'green', 'refactor', 'regression', 'not-applicable'].includes(phase)) throw new Error('TEST_PHASE_INVALID');
+  const taskIds = [...new Set(String(args['task-ids'] || args['task-id'] || '').split(',').map(x => x.trim()).filter(Boolean))];
+  if (!taskIds.length) throw new Error('TEST_TASKS_REQUIRED: 明确指定 --task-ids，工具不猜测测试覆盖的任务');
+  const timeout = Number(args['timeout-ms'] || 120000);
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > 3600000) throw new Error('TEST_TIMEOUT_INVALID');
+  const cwd = path.resolve(args.cwd || projectRoot);
+  if (!fs.statSync(cwd).isDirectory()) throw new Error('TEST_CWD_INVALID');
+  const runId = args['run-id'] || crypto.randomUUID();
+  const key = crypto.createHash('sha256').update(`${change}:${runId}`).digest('hex');
+  const dir = path.join(projectRoot, 'skywalk-sdd', 'state', 'test-runs', key);
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  // A run ID identifies one execution. Never re-execute a command under an old receipt.
+  try { fs.mkdirSync(dir); } catch (error) {
+    if (error.code === 'EEXIST') throw new Error('TEST_RUN_EXISTS: 此 run-id 已执行；使用保存的 details.json 重试记录，重新执行须使用新 run-id');
+    throw error;
+  }
+  const startedAt = new Date().toISOString();
+  const started = process.hrtime.bigint();
+  const childEnv = { ...process.env };
+  // The wrapper can itself run inside node:test; its child is a fresh test runner.
+  delete childEnv.NODE_TEST_CONTEXT;
+  const child = spawnSync(command[0], command.slice(1), {
+    cwd, env: childEnv, shell: false, encoding: 'utf8', timeout, maxBuffer: 16 * 1024 * 1024,
+  });
+  const duration = Math.round(Number(process.hrtime.bigint() - started) / 1e6);
+  const stdout = child.stdout || '', stderr = child.stderr || '';
+  const output = stdout + '\n' + stderr;
+  const exitCode = Number.isInteger(child.status) ? child.status : (child.error?.code === 'ETIMEDOUT' ? 124 : 1);
+  const failureType = classifyFailure(output, exitCode, child.error, child.signal);
+  const counts = parseCounts(output);
+  const files = {};
+  for (const [name, content] of Object.entries({ 'stdout.log': stdout, 'stderr.log': stderr })) {
+    fs.writeFileSync(path.join(dir, name), content, { mode: 0o600 });
+    files[name] = crypto.createHash('sha256').update(content).digest('hex');
+  }
+  const execution = {
+    origin: 'command-execution', argv: command, cwd, started_at: startedAt,
+    finished_at: new Date().toISOString(), signal: child.signal || null,
+    error: child.error ? { code: child.error.code, message: child.error.message } : null,
+    output_files: Object.entries(files).map(([name, sha256]) => ({ path: path.join(dir, name), sha256 })),
+    task_association: 'explicit-caller-declaration',
+    receipt_path: path.join(dir, 'execution.json'),
+  };
+  const testResults = {
+    run_id: runId, verified_task_ids: taskIds, tdd_phase: phase,
+    command: JSON.stringify(command), result: exitCode === 0 ? 'success' : 'failure',
+    exit_code: exitCode, duration_ms: duration, ...counts, failure_type: failureType,
+    expected_failure: phase === 'red' && args['expected-failure'] === true,
+    execution,
+  };
+  const receipt = path.join(dir, 'details.json');
+  fs.writeFileSync(execution.receipt_path, JSON.stringify(testResults, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+  fs.writeFileSync(receipt, JSON.stringify({ test_results: testResults }, null, 2) + '\n', { mode: 0o600 });
+  return { testResults, runId, receipt };
+}
+
+function verifyCapture(input, projectRoot) {
+  const base = fs.realpathSync(path.join(projectRoot, 'skywalk-sdd/state/test-runs')) + path.sep;
+  const receiptPath = fs.realpathSync(input.execution.receipt_path);
+  if (input.execution.origin !== 'command-execution' || !receiptPath.startsWith(base)) throw new Error('TEST_CAPTURE_INVALID: 执行回执不在当前项目');
+  const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
+  for (const key of Object.keys(receipt)) {
+    if (JSON.stringify(receipt[key]) !== JSON.stringify(input[key])) throw new Error(`TEST_CAPTURE_MISMATCH: ${key} 与真实执行回执不一致`);
+  }
+  for (const output of receipt.execution.output_files) {
+    const file = fs.realpathSync(output.path);
+    if (!file.startsWith(base) || crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== output.sha256) throw new Error('TEST_CAPTURE_HASH_MISMATCH: 原始测试输出已变化');
+  }
+}
+
+module.exports = { captureTest, parseCounts, classifyFailure, verifyCapture };

package/skywalk-sdd/lib/usage-contract.cjs

@@ -112,7 +112,7 @@ function classifyUsageSubmitResponse(statusCode) {
  *   data: 若为 ApiResponse 信封且 code=0，则为解包后的 data；否则为 undefined
  *   error: 仅在 statusCode=null 时携带 Error；否则为 null
  */
-function postJson(url, payload, options = {}) {
+function postJson(url, payload = {}, options = {}) {
   return new Promise((resolve, reject) => {
     let target;
     try {
@@ -132,7 +132,8 @@ function postJson(url, payload, options = {}) {
 
     let body;
     try {
-      body = JSON.stringify(payload === undefined ? {} : payload);
+      // payload 缺省为 {}（默认参数），null 仍按 "null" 序列化，与原三元行为一致
+      body = JSON.stringify(payload);
     } catch (err) {
       reject(new Error(`payload serialization error: ${err.message}`));
       return;

package/skywalk-sdd/lib/usage-reporter.cjs

@@ -31,6 +31,27 @@ const SHARED_DEADLINE_MS = 3000;
 // 单行事件 JSON 的安全上限（小于 4KB 以保证 appendFileSync 在 POSIX/Windows 都原子）
 const SINGLE_EVENT_MAX_BYTES = 4096;
 
+// drop 警告每进程最多一次的模块级标记
+let dropWarned = false;
+
+/**
+ * drop（含 401）时输出一次 stderr 警告；每进程最多一次，简短带 [kld-sdd] 前缀。
+ */
+function warnUsageDropOnce() {
+  if (dropWarned) return;
+  dropWarned = true;
+  try {
+    process.stderr.write('[kld-sdd] usage 事件上报被拒绝，本次事件已丢弃\n');
+  } catch { /* stderr 不可用时静默 */ }
+}
+
+/**
+ * 测试专用：重置 drop 警告的每进程一次标记。
+ */
+function _resetDropWarned() {
+  dropWarned = false;
+}
+
 function pendingPathFor(homeDir) {
   const envHome = typeof process !== 'undefined' && process && process.env
     ? process.env.KLD_SDD_HOME
@@ -84,13 +105,14 @@ function resolveReportServer(options = {}) {
     const normalized = normalizeServerUrl(config.server);
     if (normalized) return normalized;
   }
-  // 2. 项目级 kb-state.json 的 api
+  // 2. 项目级 kb-state.json 的 api（kb-state.api 是唯一带 /api 契约的来源，先剥离尾部 /api 再标准化）
   try {
     const kbStatePath = path.join(projectRoot, 'kb-state.json');
     if (fs.existsSync(kbStatePath)) {
       const kbState = JSON.parse(fs.readFileSync(kbStatePath, 'utf8'));
       if (kbState && typeof kbState.api === 'string') {
-        const normalized = normalizeServerUrl(kbState.api);
+        const stripped = kbState.api.trim().replace(/\/api(\/v\d+)?\/?$/i, '');
+        const normalized = normalizeServerUrl(stripped);
         if (normalized) return normalized;
       }
     }
@@ -300,6 +322,7 @@ async function flushPendingQueue(server, identity, pendingFile, deadlineStart) {
     }
     if (classification === 'drop') {
       // drop 丢弃该条（含 401），不 retained、不 break，继续下一条
+      warnUsageDropOnce();
       if (ev.id) droppedIds.add(ev.id);
       continue;
     }
@@ -421,6 +444,7 @@ async function reportUsageOnce(options = {}) {
           currentOutcome = 'confirmed';
         } else if (classification === 'drop') {
           // 当前事件 drop（含 401）直接丢弃不入队，不清任何本地状态
+          warnUsageDropOnce();
           currentOutcome = 'dropped';
         } else {
           currentOutcome = 'enqueued';
@@ -453,6 +477,7 @@ module.exports = {
   readGitIdentity,
   resolveReportServer,
   _resetGitIdentityCache,
+  _resetDropWarned,
   PENDING_FILE_NAME,
   PENDING_MAX_BYTES,
   FLUSH_MAX_COUNT,

package/skywalk-sdd/metrics-v3.cjs

@@ -1036,7 +1036,7 @@ function buildSchemeCompliance(input = {}) {
   const semanticParity = input.semantic_parity_status || input.semantic_parity || null;
   const multiFormatStatus = semanticParity === 'pass'
     ? 'implemented'
-    : (['md', 'html', 'json'].every(format => formats.includes(format)) ? 'provisional' : 'provisional');
+    : 'provisional';
   const alertLoopReady = Boolean(
     input.alert_loop
     && input.alert_loop.root_cause
@@ -1050,7 +1050,7 @@ function buildSchemeCompliance(input = {}) {
     || null;
   const reproducibleStatus = eventContractHealth === 'healthy' && Number(input.event_count) > 0
     ? 'implemented'
-    : (Number(input.event_count) > 0 ? 'provisional' : 'provisional');
+    : 'provisional';
   const statusLabel = status => ({
     implemented: '已实现',
     provisional: '部分可用',

package/skywalk-sdd/ontology/active-changes.cjs

@@ -42,7 +42,8 @@ function stripQuotes(value) {
 }
 
 function needsQuotes(value) {
-  return /^[\s]|[:#]|[\s]$/.test(value);
+  // 非捕获分组显式锚定各分支优先级：以空白开头、含 : 或 #、以空白结尾
+  return /(?:^[\s])|(?:[:#])|(?:[\s]$)/.test(value);
 }
 
 function quoteIfNeeded(value) {

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

@@ -571,7 +571,7 @@ function materializeArchivePackage(options = {}) {
   const projectIdentity = ensureProjectIdentity(projectRoot);
   const changeId = requiredText(snapshot.change_id, 'change_id', ONTOLOGY_PATH);
   const archiveId = `urn:kld:sdd:archive:${sha256(
-    `${projectIdentity.project_id}\n${changeId}\n${snapshot.facts_hash}`,
+    `${projectIdentity.project_id}\n${changeId}\n${snapshot.facts_hash}\n${snapshot.source_revision || snapshot.facts_hash}`,
   )}`;
   const { canonicalFacts, warnings } = buildCanonicalFacts(
     archiveDir,

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

@@ -246,7 +246,8 @@ function parseStructuredFrontmatter(lines) {
     const nested = line.match(/^\s{2,}([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
 
     if (topKey && !/^\s/.test(line)) {
-      currentRef = flushRequirementRef(requirementRefs, currentRef);
+      flushRequirementRef(requirementRefs, currentRef);
+      currentRef = null;
       section = topKey[1].toLowerCase();
       const value = unwrapScalar(stripInlineYamlComment(topKey[2]));
       flat[section] = value;
@@ -263,7 +264,7 @@ function parseStructuredFrontmatter(lines) {
     }
 
     if (section === 'requirement-refs' && listItem) {
-      currentRef = flushRequirementRef(requirementRefs, currentRef) || {};
+      flushRequirementRef(requirementRefs, currentRef);
       currentRef = { [listItem[1].toLowerCase()]: unwrapScalar(stripInlineYamlComment(listItem[2])) };
       continue;
     }
@@ -668,7 +669,8 @@ function addStructuralEntities(target, files, options = {}) {
         name: descriptor.file.relativePath,
         entity_id: identity.entity_id,
         version_id: identity.version_id,
-        delta_state: 'added',
+        delta_state: identity.delta_state || 'added',
+        predecessor_version_id: identity.predecessor_version_id || undefined,
         content_hash: descriptor.content_hash,
         attributes: { artifact_type: artifactType(descriptor.file.relativePath), path: descriptor.file.relativePath },
         source: sourceFor(descriptor.file, 1, identity.anchor_id),
@@ -684,7 +686,8 @@ function addStructuralEntities(target, files, options = {}) {
         name: `${owner.source.file}#${owner.id}`,
         entity_id: identity.entity_id,
         version_id: identity.version_id,
-        delta_state: 'added',
+        delta_state: identity.delta_state || 'added',
+        predecessor_version_id: identity.predecessor_version_id || undefined,
         content_hash: descriptor.content_hash,
         attributes: { artifact_path: owner.source.file, entity_anchor: owner.id },
         source: { ...owner.source, anchor_id: identity.anchor_id },

package/skywalk-sdd/ontology/id.cjs

@@ -3,7 +3,7 @@
 const crypto = require('crypto');
 const { ID_PREFIX_TYPES, entityTypeForId } = require('./schema.cjs');
 
-const ID_BYTE_LENGTH = 4;
+const ID_BYTE_LENGTH = 16;
 const ID_HEX_LENGTH = ID_BYTE_LENGTH * 2;
 
 function normalizeSlug(value) {
@@ -52,15 +52,16 @@ function isValidEntityId(entityId, expectedType = '') {
 }
 
 function generateIdentityId() {
-  return crypto.randomBytes(ID_BYTE_LENGTH).toString('hex');
+  return crypto.randomUUID();
 }
 
 function generateUuidV7() {
+  // Compatibility name retained for existing callers; new identities are standard UUIDs.
   return generateIdentityId();
 }
 
 /**
- * Normalize a UUID value to the internal 8-hex short format.
+ * Preserve full UUIDs; collapse only the legacy zero-padded 8-hex representation.
  *
  * KB backend (PostgreSQL) serializes UUID columns as full 36-char format
  * (e.g. "3518f551-0000-0000-0000-000000000000").  The SDD toolchain uses
@@ -69,7 +70,7 @@ function generateUuidV7() {
  */
 function normalizeUuid(value) {
   const v = String(value || '').trim().toLowerCase();
-  const fullUuidMatch = v.match(/^([0-9a-f]{8})-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  const fullUuidMatch = v.match(/^([0-9a-f]{8})-0000-0000-0000-000000000000$/);
   if (fullUuidMatch) {
     return fullUuidMatch[1];
   }

package/skywalk-sdd/ontology/identity-index.cjs

@@ -168,11 +168,11 @@ function buildCatalogDiagnostics(records) {
   const byPredecessor = groupBy(records, 'predecessor_version_id');
 
   for (const [entityId, items] of byEntityId.entries()) {
-    const signatures = new Set(items.map((item) => `${item.anchor_id}|${item.type}`));
+    const signatures = new Set(items.map((item) => item.type));
     if (signatures.size > 1) {
       diagnostics.push(catalogDiagnostic(
         DIAGNOSTIC_CODES.ENTITY_IDENTITY_CONFLICT,
-        `历史集合中同一 entity-id 对应多个锚点或类型: ${entityId}`,
+        `历史集合中同一 entity-id 对应多个类型: ${entityId}`,
         { entity_id: items[0].anchor_id, file: items[0].source && items[0].source.file },
       ));
     }
@@ -206,7 +206,8 @@ function buildCatalogDiagnostics(records) {
       diagnostics.push(catalogDiagnostic(
         DIAGNOSTIC_CODES.VERSION_LINEAGE_CONFLICT,
         `历史集合中同一 predecessor 存在多个后继: ${predecessorId}`,
-        { entity_id: items[0].anchor_id, file: items[0].source && items[0].source.file },
+        { severity: items.every(item => item.scope === "active") ? "warning" : "error",
+          entity_id: items[0].anchor_id, file: items[0].source && items[0].source.file },
       ));
     }
   }
@@ -235,7 +236,11 @@ function buildIdentityCatalog(projectRoot, options = {}) {
 
   for (const candidate of identityRoots(root)) {
     if (excluded && path.resolve(candidate.changeDir) === excluded) continue;
-    const facts = normalizeFacts(parseChangeArtifacts(root, candidate.change, {
+    const snapshot = candidate.scope === 'archive'
+      ? readJson(path.join(candidate.changeDir, 'archive-ontology.json')) : null;
+    // The archive directory gains a date prefix, but facts were frozen with the logical change name.
+    const logicalChange = snapshot && snapshot.change ? snapshot.change : candidate.change;
+    const facts = normalizeFacts(parseChangeArtifacts(root, logicalChange, {
       changeDir: candidate.changeDir,
       persistStructuralIdentities: false,
     }));

package/skywalk-sdd/ontology/list-changes.cjs

@@ -15,7 +15,7 @@ function listActiveChanges(projectRoot) {
       const full = path.join(changesDir, name);
       return fs.statSync(full).isDirectory();
     })
-    .sort();
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
 function describeChange(projectRoot, changeName, registry) {