kld-sdd 2.6.21 → 2.7.8

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

@@ -1,6 +1,10 @@
-// kld-T04 — 使用事件 reporter（kld-fixback RED#2/#4/#9 重构版）
-// 职责：单一 3s deadline；pending JSONL 原子追加；100 条上限；1MB 淘汰；
-//       HTTP 状态分类（confirmed/retry/unauthorized/drop）；401 原子清除 token；
+// kld-T04 — 使用事件 reporter（git 身份缓存化韧性版）
+// 职责：git 身份取自 ~/.kld-sdd/git-identity.json 持久缓存（git 仅由 git-identity.cjs
+//       后台刷新读取，慢 git 环境前台零调用）；无身份当前事件入 pending 队列不跳过，
+//       身份就绪后 flush 时注入身份补报；
+//       server 四级解析（config > kb-state.api > KLD_SDD_SERVER > 内置默认）；
+//       单一 3s deadline；pending JSONL 原子追加；100 条上限；1MB 淘汰；
+//       HTTP 状态分类（confirmed/retry/drop，401 归入 drop 不清任何本地状态）；
 //       并发安全（appendFileSync O_APPEND + 事件 id 差集提交）；不改原业务退出码。
 'use strict';
 
@@ -13,11 +17,12 @@ const {
   classifyUsageSubmitResponse,
   postJson,
   mapCommandToUsageSkill,
+  DEFAULT_SERVER_URL,
 } = require('./usage-contract.cjs');
 const {
   readUserConfig,
-  clearUserToken,
 } = require('./user-config.cjs');
+const gitIdentity = require('./git-identity.cjs');
 
 const PENDING_FILE_NAME = 'pending-usage.jsonl';
 const PENDING_MAX_BYTES = 1024 * 1024; // 1 MB
@@ -26,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
@@ -34,6 +60,74 @@ function pendingPathFor(homeDir) {
   return path.join(home, '.kld-sdd', PENDING_FILE_NAME);
 }
 
+// git 身份进程内缓存：仅缓存成功读取；失败不缓存，下次重试
+let gitIdentityCache = null;
+
+/**
+ * 读取本机 git 身份。
+ * - 来源：~/.kld-sdd/git-identity.json 持久缓存（git-identity.cjs 维护，
+ *   git 仅由 detached 后台刷新进程读取——慢 git 环境（7-34s 启动）前台零调用）
+ * - 进程内缓存：首次成功后复用；失败不缓存
+ * - 无缓存 / 缓存缺字段 / tombstone → 返回 null（调用方将当前事件入队待补报，
+ *   并已由 ensureIdentity 触发一次后台刷新）
+ *
+ * @param {string} [homeDir] — 测试注入 home；缺省走 KLD_SDD_HOME/os.homedir
+ * @returns {{userName:string, email:string}|null}
+ */
+function readGitIdentity(homeDir) {
+  if (gitIdentityCache) return gitIdentityCache;
+  const identity = gitIdentity.ensureIdentity({ homeDir });
+  if (!identity) return null;
+  gitIdentityCache = identity;
+  return gitIdentityCache;
+}
+
+/**
+ * 测试专用：重置进程内 git 身份缓存。
+ */
+function _resetGitIdentityCache() {
+  gitIdentityCache = null;
+}
+
+/**
+ * 四级解析上报地址：config.server → 项目 kb-state.json api → env KLD_SDD_SERVER → 内置默认。
+ * 每级均经 normalizeServerUrl；结果永远非空（默认地址兜底）。
+ *
+ * @param {{homeDir?:string, projectRoot?:string, env?:object}} [options]
+ * @returns {string}
+ */
+function resolveReportServer(options = {}) {
+  const env = options.env || process.env;
+  const projectRoot = options.projectRoot || process.cwd();
+  // 1. 用户级 config.server
+  const config = readUserConfig(options.homeDir);
+  if (config && typeof config.server === 'string') {
+    const normalized = normalizeServerUrl(config.server);
+    if (normalized) return normalized;
+  }
+  // 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 stripped = kbState.api.trim().replace(/\/api(\/v\d+)?\/?$/i, '');
+        const normalized = normalizeServerUrl(stripped);
+        if (normalized) return normalized;
+      }
+    }
+  } catch {
+    // kb-state 读取失败时静默，继续下一级
+  }
+  // 3. env KLD_SDD_SERVER
+  if (env && typeof env.KLD_SDD_SERVER === 'string') {
+    const normalized = normalizeServerUrl(env.KLD_SDD_SERVER);
+    if (normalized) return normalized;
+  }
+  // 4. 内置默认地址兜底
+  return normalizeServerUrl(DEFAULT_SERVER_URL);
+}
+
 /**
  * 生成事件唯一 id（基于时间戳 + pid + 随机字节）。
  * 用于 flush 提交时按 id 差集删除已确认行，避免 read-modify-write 覆盖并发 append。
@@ -174,21 +268,113 @@ function appendPending(event, filePath) {
 }
 
 /**
- * 提交单条事件；返回分类。
- * @returns {Promise<'confirmed'|'unauthorized'|'retry'|'drop'>}
+ * 提交单条事件；发送前注入 git 身份；返回分类。
+ * @returns {Promise<'confirmed'|'retry'|'drop'>}
  */
-async function submitOne(server, token, event, timeoutMs) {
-  // 提交时剔除内部 id（不上传给服务端）
-  const outgoing = Object.assign({}, event);
+async function submitOne(server, identity, event, timeoutMs) {
+  // 提交时剔除内部 id（不上传给服务端），统一注入当前 git 身份
+  // （兼容 pending 队列里无身份字段的遗留事件）
+  const outgoing = Object.assign({}, event, {
+    userName: identity.userName,
+    email: identity.email,
+  });
   delete outgoing.id;
   const result = await postJson(
     `${server}/api/v1/usage-events`,
     outgoing,
-    { token, timeoutMs },
+    { timeoutMs },
   );
   return classifyUsageSubmitResponse(result.statusCode);
 }
 
+/**
+ * 共享冲刷执行体：读 pending → 逐条提交 → 按 id 差集原子提交队列变化。
+ * reportUsageOnce（冲刷后发当前事件）与 flushPendingUsage（只冲刷）共用。
+ *
+ * @returns {Promise<{submitted:number, confirmedIds:Set, droppedIds:Set}>}
+ */
+async function flushPendingQueue(server, identity, pendingFile, deadlineStart) {
+  const deadline = deadlineStart || (Date.now() + SHARED_DEADLINE_MS);
+  const confirmedIds = new Set();   // 已成功的事件 id
+  const droppedIds = new Set();     // 4xx 永久失败的事件 id
+  let submitted = 0;
+
+  const { events: pendingEvents } = readPending(pendingFile);
+  let flushed = 0;
+  for (let i = 0; i < pendingEvents.length; i++) {
+    const ev = pendingEvents[i];
+    const remaining = deadline - Date.now();
+    if (flushed >= FLUSH_MAX_COUNT || remaining <= 0) break;
+
+    const timeoutMs = Math.max(50, remaining);
+    let classification;
+    try {
+      classification = await submitOne(server, identity, ev, timeoutMs);
+    } catch {
+      classification = 'retry';
+    }
+
+    if (classification === 'confirmed') {
+      flushed += 1;
+      submitted += 1;
+      if (ev.id) confirmedIds.add(ev.id);
+      continue;
+    }
+    if (classification === 'drop') {
+      // drop 丢弃该条（含 401），不 retained、不 break，继续下一条
+      warnUsageDropOnce();
+      if (ev.id) droppedIds.add(ev.id);
+      continue;
+    }
+    // retry：网络/5xx/429/timeout，本次及后续保留
+    break;
+  }
+
+  // 原子提交队列变化（按 id 差集删除已确认 + 已丢弃）
+  // 关键：rewrite 前必须重新读文件，把并发 append 的新行合并进来
+  if (confirmedIds.size > 0 || droppedIds.size > 0) {
+    const { events: latestEvents } = readPending(pendingFile);
+    const retained = latestEvents.filter((e) => {
+      if (e.id && confirmedIds.has(e.id)) return false;
+      if (e.id && droppedIds.has(e.id)) return false;
+      return true;
+    });
+    writePendingAtomic(pendingFile, retained);
+  }
+
+  return { submitted, confirmedIds, droppedIds };
+}
+
+/**
+ * 只冲刷 pending 队列，不产生新事件（cmdEnd / git 身份就绪后的补报入口）。
+ * 无身份返回 skipped 零请求；任何失败均不抛。
+ *
+ * @param {object} [options]
+ * @param {string} [options.homeDir] — 测试注入
+ * @param {string} [options.projectRoot] — kb-state.json 查找目录，缺省 process.cwd()
+ * @returns {Promise<{submitted:number,enqueued:boolean,skipped:boolean}>}
+ */
+async function flushPendingUsage(options = {}) {
+  const result = { submitted: 0, enqueued: false, skipped: false };
+  try {
+    const identity = readGitIdentity(options.homeDir);
+    if (!identity) {
+      result.skipped = true;
+      return result;
+    }
+    const pendingFile = pendingPathFor(options.homeDir);
+    const { events: pendingEvents } = readPending(pendingFile);
+    if (pendingEvents.length === 0) return result;
+    const server = resolveReportServer({ homeDir: options.homeDir, projectRoot: options.projectRoot });
+    const flushed = await flushPendingQueue(server, identity, pendingFile);
+    result.submitted = flushed.submitted;
+    return result;
+  } catch {
+    // 兜底：永不抛到调用方
+    return result;
+  }
+}
+
 /**
  * 上报一次使用事件（主入口）。任何失败均不抛。
  *
@@ -196,119 +382,69 @@ async function submitOne(server, token, event, timeoutMs) {
  * @param {string} options.skill — 七值之一；非七值立即返回
  * @param {string} [options.startedAt] — ISO8601；缺省取当前
  * @param {string} [options.homeDir] — 测试注入
- * @param {Function} [options.onNotify] — 401 等用户提示
- * @returns {Promise<{submitted:number,enqueued:boolean,tokenCleared:boolean,skipped:boolean}>}
+ * @param {string} [options.projectRoot] — kb-state.json 查找目录，缺省 process.cwd()
+ * @returns {Promise<{submitted:number,enqueued:boolean,skipped:boolean}>}
  */
 async function reportUsageOnce(options = {}) {
-  const result = { submitted: 0, enqueued: false, tokenCleared: false, skipped: false };
+  const result = { submitted: 0, enqueued: false, skipped: false };
   const skill = mapCommandToUsageSkill(options.skill);
   if (!skill) {
     result.skipped = true;
     return result;
   }
-  const onNotify = typeof options.onNotify === 'function' ? options.onNotify : () => {};
+
+  const startedAt = typeof options.startedAt === 'string' && options.startedAt
+    ? options.startedAt
+    : new Date().toISOString();
+  const currentEvent = { skill, startedAt, id: generateEventId() };
+  const pendingFile = pendingPathFor(options.homeDir);
 
   try {
-    const config = readUserConfig(options.homeDir);
-    if (!config || typeof config.token !== 'string' || !config.token) {
-      result.skipped = true;
-      return result;
-    }
-    const server = normalizeServerUrl(config.server || '');
-    if (!server) {
-      result.skipped = true;
+    // 无 git 身份：当前事件入队（无身份字段，与遗留事件同构），本次冲刷整体跳过、
+    // 队列原有内容保留；身份就绪后由后续 flush 注入身份补报（慢 git 环境不静默丢失）。
+    const identity = readGitIdentity(options.homeDir);
+    if (!identity) {
+      try {
+        appendPending(currentEvent, pendingFile);
+        result.enqueued = true;
+      } catch { /* append 失败静默，不改退出码 */ }
       return result;
     }
-    const token = config.token;
-
-    const startedAt = typeof options.startedAt === 'string' && options.startedAt
-      ? options.startedAt
-      : new Date().toISOString();
-    const currentEvent = { skill, startedAt, id: generateEventId() };
+    const server = resolveReportServer({ homeDir: options.homeDir, projectRoot: options.projectRoot });
 
-    const pendingFile = pendingPathFor(options.homeDir);
-    const deadline = Date.now() + SHARED_DEADLINE_MS;
     const MAX_TIMEOUT_SKEW_MS = 500; // 调度容差
+    // 共享 3s deadline：冲刷与当前事件共用同一预算
+    const deadline = Date.now() + SHARED_DEADLINE_MS;
 
-    // 1. 先冲刷 pending（最多 100 条）
-    const { events: pendingEvents } = readPending(pendingFile);
-    const confirmedIds = new Set();   // 已成功的事件 id
-    const droppedIds = new Set();     // 4xx 永久失败的事件 id
-    const failedEarly = { hit: false, kind: null }; // 提前终止标记（unauthorized/retry）
-
-    let flushed = 0;
-    for (let i = 0; i < pendingEvents.length; i++) {
-      const ev = pendingEvents[i];
-      const remaining = deadline - Date.now();
-      if (flushed >= FLUSH_MAX_COUNT || remaining <= 0) break;
-
-      const timeoutMs = Math.max(50, remaining);
-      let classification;
-      try {
-        classification = await submitOne(server, token, ev, timeoutMs);
-      } catch {
-        classification = 'retry';
-      }
-
-      if (classification === 'confirmed') {
-        flushed += 1;
-        result.submitted += 1;
-        if (ev.id) confirmedIds.add(ev.id);
-        continue;
-      }
-      if (classification === 'unauthorized') {
-        // 401：原子清除 token；本次及后续不再请求
-        try {
-          if (clearUserToken(options.homeDir)) {
-            result.tokenCleared = true;
-            onNotify('检测到平台凭证已失效，请运行 `kld-sdd auth login` 重新绑定。');
-          }
-        } catch { /* ignore */ }
-        failedEarly.hit = true;
-        failedEarly.kind = 'unauthorized';
-        break;
-      }
-      if (classification === 'drop') {
-        // kld-fixback YELLOW#4: drop 丢弃该条，不 retained、不 break，继续下一条
-        if (ev.id) droppedIds.add(ev.id);
-        continue;
-      }
-      // retry：网络/5xx/429/timeout，本次及后续保留
-      failedEarly.hit = true;
-      failedEarly.kind = 'retry';
-      break;
-    }
+    // 1. 先冲刷 pending（最多 100 条；retry 提前终止时剩余保留）
+    const flushOutcome = await flushPendingQueue(server, identity, pendingFile, deadline);
+    result.submitted += flushOutcome.submitted;
+    // 冲刷提前失败判定：零提交、零 drop，且队列仍有残留（retry 语义）
+    const failedEarly = flushOutcome.submitted === 0
+      && flushOutcome.confirmedIds.size === 0
+      && flushOutcome.droppedIds.size === 0
+      && readPending(pendingFile).events.length > 0;
 
     // 2. 发当前事件（若仍有预算且未提前失败）
-    // kld-fixback-review#2 RED: flush 提前失败时当前事件必须入队（与 design
-    // 『网络/超时/429/5xx 将事件追加或保留在 pending 队列』一致），不得静默丢弃。
+    // flush 提前失败时当前事件必须入队，不得静默丢弃。
     let currentOutcome = 'pending'; // 'confirmed' | 'enqueued' | 'dropped' | 'pending'
-    if (failedEarly.hit) {
+    if (failedEarly) {
       currentOutcome = 'enqueued';
     } else {
       const remaining = deadline - Date.now();
       if (remaining > MAX_TIMEOUT_SKEW_MS) {
         let classification;
         try {
-          classification = await submitOne(server, token, currentEvent, remaining);
+          classification = await submitOne(server, identity, currentEvent, remaining);
         } catch {
           classification = 'retry';
         }
         if (classification === 'confirmed') {
           result.submitted += 1;
           currentOutcome = 'confirmed';
-        } else if (classification === 'unauthorized') {
-          try {
-            if (clearUserToken(options.homeDir)) {
-              result.tokenCleared = true;
-              onNotify('检测到平台凭证已失效，请运行 `kld-sdd auth login` 重新绑定。');
-            }
-          } catch { /* ignore */ }
-          currentOutcome = 'enqueued';
-          failedEarly.hit = true;
-          failedEarly.kind = 'unauthorized';
         } else if (classification === 'drop') {
-          // kld-fixback YELLOW#4: 当前事件 drop 直接丢弃不入队
+          // 当前事件 drop（含 401）直接丢弃不入队，不清任何本地状态
+          warnUsageDropOnce();
           currentOutcome = 'dropped';
         } else {
           currentOutcome = 'enqueued';
@@ -318,18 +454,8 @@ async function reportUsageOnce(options = {}) {
       }
     }
 
-    // 3. 原子提交队列变化（按 id 差集删除已确认 + 已丢弃；append 当前事件若需要）
-    // 关键：rewrite 前必须重新读文件，把并发 append 的新行合并进来
+    // 3. append 当前事件（若需要）
     try {
-      if (confirmedIds.size > 0 || droppedIds.size > 0) {
-        const { events: latestEvents } = readPending(pendingFile);
-        const retained = latestEvents.filter((e) => {
-          if (e.id && confirmedIds.has(e.id)) return false;
-          if (e.id && droppedIds.has(e.id)) return false;
-          return true;
-        });
-        writePendingAtomic(pendingFile, retained);
-      }
       if (currentOutcome === 'enqueued') {
         appendPending(currentEvent, pendingFile);
         result.enqueued = true;
@@ -345,8 +471,13 @@ async function reportUsageOnce(options = {}) {
 
 module.exports = {
   reportUsageOnce,
+  flushPendingUsage,
   appendPending,
   readPending,
+  readGitIdentity,
+  resolveReportServer,
+  _resetGitIdentityCache,
+  _resetDropWarned,
   PENDING_FILE_NAME,
   PENDING_MAX_BYTES,
   FLUSH_MAX_COUNT,

package/skywalk-sdd/lib/user-config.cjs

@@ -1,13 +1,14 @@
 // kld-T02 — ~/.kld-sdd/config.json 用户级配置管理
-// 职责：读取、规范化、原子写、0600/Windows ACL、401 token 清除、敏感信息脱敏。
-// 与 kb-sdd 跨仓契约对齐：cli_token 仅存于此，不进入 Archive/Knowledge 请求。
+// 职责：读取、规范化、原子写、0600/Windows ACL。
+// schema v2 = {version, server}；使用统计按 git 身份上报，不再保存任何 token。
+// 旧版含 token/userName/boundAt 的 config 读取时 sanitize 为 {version, server}，回写即淘汰。
 'use strict';
 
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-const USER_CONFIG_VERSION = 1;
+const USER_CONFIG_VERSION = 2;
 const CONFIG_DIR_NAME = '.kld-sdd';
 const CONFIG_FILE_NAME = 'config.json';
 
@@ -32,9 +33,23 @@ function getConfigPath(homeDir) {
   return path.join(getConfigDir(homeDir), CONFIG_FILE_NAME);
 }
 
+/**
+ * 将任意已解析对象规范化为 v2 config：只保留 {version, server}。
+ * @param {object} parsed
+ * @returns {{version: number, server?: string}}
+ */
+function sanitizeConfig(parsed) {
+  const config = { version: USER_CONFIG_VERSION };
+  if (typeof parsed.server === 'string') {
+    config.server = parsed.server;
+  }
+  return config;
+}
+
 /**
  * 读取用户配置。
  * - 文件不存在 / 损坏 JSON / 非对象 → 返回 null（不抛）
+ * - 旧版多余字段（token/userName/boundAt 等）读取即忽略，不回传
  * - 返回新引用；调用方修改不影响后续读取
  *
  * @param {string} [homeDir]
@@ -55,12 +70,7 @@ function readUserConfig(homeDir) {
     return null;
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
-  // 深拷贝隔离
-  try {
-    return JSON.parse(JSON.stringify(parsed));
-  } catch {
-    return null;
-  }
+  return sanitizeConfig(parsed);
 }
 
 /**
@@ -83,6 +93,7 @@ function hardenPermissions(target, kind) {
 
 /**
  * 原子写入用户配置：先 temp 后 rename，目录与文件均设置权限。
+ * 只持久化 {version, server}，多余字段写入即淘汰。
  * @param {object} config — 必须含 version 字段
  * @param {string} [homeDir]
  * @throws {Error} config 非法 / 缺 version
@@ -100,7 +111,7 @@ function writeUserConfig(config, homeDir) {
   hardenPermissions(dir, 'dir');
 
   const tmp = path.join(dir, `.${CONFIG_FILE_NAME}.${process.pid}.${Date.now()}.tmp`);
-  const payload = JSON.stringify(config, null, 2);
+  const payload = JSON.stringify(sanitizeConfig(config), null, 2);
   fs.writeFileSync(tmp, payload, { encoding: 'utf8', mode: 0o600 });
   hardenPermissions(tmp, 'file');
   try {
@@ -112,46 +123,10 @@ function writeUserConfig(config, homeDir) {
   hardenPermissions(file, 'file');
 }
 
-/**
- * 原子清除 token 字段，保留其他所有字段。
- * - 文件不存在 / 损坏 / 已无 token → 幂等返回 false
- * - 成功清除返回 true
- *
- * @param {string} [homeDir]
- * @returns {boolean}
- */
-function clearUserToken(homeDir) {
-  const file = getConfigPath(homeDir);
-  if (!fs.existsSync(file)) return false;
-  const current = readUserConfig(homeDir);
-  if (!current) return false;
-  if (!Object.prototype.hasOwnProperty.call(current, 'token')) return false;
-  delete current.token;
-  writeUserConfig(current, homeDir);
-  return true;
-}
-
-/**
- * 敏感信息脱敏：任何非空字符串 token 一律返回 '***'。
- * - 空字符串保持空字符串
- * - 非字符串原样返回
- * - 永不抛出
- *
- * @param {*} value
- * @returns {*}
- */
-function redactToken(value) {
-  if (typeof value !== 'string') return value;
-  if (value.length === 0) return '';
-  return '***';
-}
-
 module.exports = {
   USER_CONFIG_VERSION,
   getConfigDir,
   getConfigPath,
   readUserConfig,
   writeUserConfig,
-  clearUserToken,
-  redactToken,
 };

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

@@ -200,7 +200,7 @@ function identityFromValues(values = {}) {
 }
 
 function flushRequirementRef(requirementRefs, currentRef) {
-  if (!currentRef) return null;
+  if (!currentRef) return;
   const { normalize, validate } = require('./external-key.cjs');
   const system = currentRef.system;
   const objectType = currentRef['object-type'] || currentRef.object_type;
@@ -224,7 +224,6 @@ function flushRequirementRef(requirementRefs, currentRef) {
     }
     requirementRefs.push(entry);
   }
-  return null;
 }
 
 function parseStructuredFrontmatter(lines) {
@@ -247,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;
@@ -264,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;
     }
@@ -669,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),
@@ -685,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 },