kld-sdd 2.6.16 → 2.6.21

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

@@ -0,0 +1,157 @@
+// kld-T02 — ~/.kld-sdd/config.json 用户级配置管理
+// 职责：读取、规范化、原子写、0600/Windows ACL、401 token 清除、敏感信息脱敏。
+// 与 kb-sdd 跨仓契约对齐：cli_token 仅存于此，不进入 Archive/Knowledge 请求。
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const USER_CONFIG_VERSION = 1;
+const CONFIG_DIR_NAME = '.kld-sdd';
+const CONFIG_FILE_NAME = 'config.json';
+
+/**
+ * 返回用户配置目录路径。
+ * @param {string} [homeDir] — 注入的 home 目录（测试用）；缺省取 env.KLD_SDD_HOME 或 os.homedir()
+ */
+function getConfigDir(homeDir) {
+  const envHome = typeof process !== 'undefined' && process && process.env
+    ? process.env.KLD_SDD_HOME
+    : undefined;
+  const home = (typeof homeDir === 'string' && homeDir)
+    || (typeof envHome === 'string' && envHome)
+    || os.homedir();
+  return path.join(home, CONFIG_DIR_NAME);
+}
+
+/**
+ * 返回用户配置文件完整路径。
+ */
+function getConfigPath(homeDir) {
+  return path.join(getConfigDir(homeDir), CONFIG_FILE_NAME);
+}
+
+/**
+ * 读取用户配置。
+ * - 文件不存在 / 损坏 JSON / 非对象 → 返回 null（不抛）
+ * - 返回新引用；调用方修改不影响后续读取
+ *
+ * @param {string} [homeDir]
+ * @returns {object|null}
+ */
+function readUserConfig(homeDir) {
+  const file = getConfigPath(homeDir);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  // 深拷贝隔离
+  try {
+    return JSON.parse(JSON.stringify(parsed));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * POSIX 平台设置 0600/0700；Windows 平台尝试通过 icacls 收紧 ACL（best-effort）。
+ * @param {string} target — 文件或目录路径
+ * @param {'file'|'dir'} kind
+ */
+function hardenPermissions(target, kind) {
+  if (process.platform === 'win32') {
+    // Windows：依赖 Node 默认 ACL 通常已限当前用户，无需显式 icacls；
+    // 实际收紧在更高层以同步子进程完成，避免引入异步依赖。
+    return;
+  }
+  try {
+    fs.chmodSync(target, kind === 'dir' ? 0o700 : 0o600);
+  } catch {
+    // best-effort：无法 chmod 时静默（例如某些 FS 不支持）
+  }
+}
+
+/**
+ * 原子写入用户配置：先 temp 后 rename，目录与文件均设置权限。
+ * @param {object} config — 必须含 version 字段
+ * @param {string} [homeDir]
+ * @throws {Error} config 非法 / 缺 version
+ */
+function writeUserConfig(config, homeDir) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('user config must be an object');
+  }
+  if (typeof config.version !== 'number') {
+    throw new Error('user config requires numeric version');
+  }
+  const dir = getConfigDir(homeDir);
+  const file = getConfigPath(homeDir);
+  fs.mkdirSync(dir, { recursive: true });
+  hardenPermissions(dir, 'dir');
+
+  const tmp = path.join(dir, `.${CONFIG_FILE_NAME}.${process.pid}.${Date.now()}.tmp`);
+  const payload = JSON.stringify(config, null, 2);
+  fs.writeFileSync(tmp, payload, { encoding: 'utf8', mode: 0o600 });
+  hardenPermissions(tmp, 'file');
+  try {
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+  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

@@ -4,7 +4,8 @@ const REPORT_SCHEMA_VERSION = 'sdd-efficiency-report/v4';
 const METRICS_CONTRACT_VERSION = '4.0';
 const SCHEME_VERSION = 'V3.0';
 /** Writable change types (scheme 5.3). Legacy document/other read as unknown. */
-const CHANGE_TYPES = ['config', 'transaction', 'report', 'composite'];
+const BUSINESS_CHANGE_TYPES = ['config', 'transaction', 'report', 'composite'];
+const CHANGE_TYPES = [...BUSINESS_CHANGE_TYPES, 'unknown'];
 const LEGACY_CHANGE_TYPES = ['document', 'other'];
 const MINIMUM_METRICS = ['e1', 'q3', 'p4', 'p_r', 'p_h'];
 
@@ -55,7 +56,7 @@ const AGENT_OVERRIDE_REASONS = new Set([
   'unspecified',
 ]);
 
-const SCENARIO_HEADING_RE = /^#####\s+(场景|Scenario)\s*[：:]/gm;
+const SCENARIO_HEADING_RE = /^#####\s+(?:场景|Scenario)\s*[：:]\s*(.+?)\s*$/gim;
 
 function createInvalidArgError(code, message) {
   const err = new Error(message);
@@ -74,6 +75,26 @@ function round(n, digits = 4) {
   return Math.round(n * factor) / factor;
 }
 
+function computeTelemetryHealthScore(input = {}) {
+  const weightedIssueValue = Number(input.weighted_issue_value);
+  const stageEventCount = Number(input.stage_event_count);
+  const safeWeightedIssueValue = Number.isFinite(weightedIssueValue) && weightedIssueValue >= 0
+    ? weightedIssueValue
+    : 0;
+  const safeStageEventCount = Number.isFinite(stageEventCount) && stageEventCount >= 0
+    ? stageEventCount
+    : 0;
+  const denominator = Math.max(safeStageEventCount, 1);
+  const ratio = Math.max(0, round(1 - safeWeightedIssueValue / denominator, 2));
+  return {
+    weighted_issue_value: safeWeightedIssueValue,
+    stage_event_count: safeStageEventCount,
+    denominator,
+    ratio,
+    score: round(ratio * 100, 2),
+  };
+}
+
 function percentile(sortedOrUnsortedValues, p) {
   if (!Array.isArray(sortedOrUnsortedValues)) {
     throw createInvalidArgError('invalid-arg', 'percentile expects an array');
@@ -137,10 +158,44 @@ function summarizeDistribution(values) {
 }
 
 function countScenariosInMarkdown(text) {
-  if (typeof text !== 'string' || !text) return 0;
+  return extractScenariosInMarkdown(text).length;
+}
+
+function maskMarkdownFencedCode(text) {
+  const lines = text.split('\n');
+  let fence = null;
+  return lines.map((line) => {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (!fence && marker) {
+      fence = {
+        character: marker[1][0],
+        length: marker[1].length,
+      };
+      return ' '.repeat(line.length);
+    }
+    if (!fence) return line;
+
+    const closing = line.match(/^ {0,3}(`{3,}|~{3,})[ \t]*$/);
+    const isClosing = closing
+      && closing[1][0] === fence.character
+      && closing[1].length >= fence.length;
+    if (isClosing) fence = null;
+    return ' '.repeat(line.length);
+  }).join('\n');
+}
+
+function extractScenariosInMarkdown(text) {
+  if (typeof text !== 'string' || !text) return [];
   const normalized = text.replace(/\r\n/g, '\n');
-  const matches = normalized.match(SCENARIO_HEADING_RE);
-  return matches ? matches.length : 0;
+  const searchable = maskMarkdownFencedCode(normalized);
+  const scenarios = [];
+  for (const match of searchable.matchAll(SCENARIO_HEADING_RE)) {
+    scenarios.push({
+      title: String(match[1] || '').trim(),
+      line: searchable.slice(0, match.index).split('\n').length,
+    });
+  }
+  return scenarios;
 }
 
 function validateChangeType(value) {
@@ -185,11 +240,33 @@ function resolveReviewerIndependence(meta = {}) {
   return 'unknown';
 }
 
+const REVIEW_IDENTITY_PLACEHOLDERS = new Set([
+  'unknown',
+  'none',
+  'null',
+  'n/a',
+  'na',
+  '未记录',
+  '未知',
+]);
+
+function isMeaningfulReviewIdentity(value) {
+  const normalized = String(value || '').trim();
+  if (!normalized) return false;
+  if (REVIEW_IDENTITY_PLACEHOLDERS.has(normalized.toLowerCase())) return false;
+  if (/^<[^>]+>$/.test(normalized) || /^\[[^\]]+\]$/.test(normalized)) return false;
+  return true;
+}
+
 function resolveScoreStatus(reviewerIndependence, meta = {}) {
   if (reviewerIndependence !== 'independent-review') return 'provisional';
+  if (meta.review_execution_mode !== 'subagent') return 'provisional';
+  if (!isMeaningfulReviewIdentity(meta.reviewer_agent_id)) return 'provisional';
   const reviewSession = meta.review_session_id || meta.reviewer_session_id || null;
   const authorSession = meta.author_session_id || null;
-  if (reviewSession && authorSession && reviewSession !== authorSession) {
+  if (isMeaningfulReviewIdentity(reviewSession)
+    && isMeaningfulReviewIdentity(authorSession)
+    && reviewSession !== authorSession) {
     return 'verified';
   }
   return 'provisional';
@@ -210,7 +287,7 @@ function computeSpecQualityScore(checkResults, meta = {}) {
   }
 
   const total = Number.isFinite(checkResults.total) ? checkResults.total : null;
-  const errors = Number.isFinite(checkResults.errors) ? checkResults.errors : 0;
+  const errors = Number.isFinite(checkResults.errors) ? checkResults.errors : null;
   const warnings = Number.isFinite(checkResults.warnings) ? checkResults.warnings : 0;
   const suggestions = Number.isFinite(checkResults.suggestions) ? checkResults.suggestions : 0;
 
@@ -227,6 +304,24 @@ function computeSpecQualityScore(checkResults, meta = {}) {
       suggestions,
     };
   }
+  if (!Number.isInteger(total)
+      || !Number.isInteger(errors)
+      || errors < 0
+      || errors > total) {
+    const reviewerIndependence = resolveReviewerIndependence(meta);
+    return {
+      q3_spec_quality_score: null,
+      category_scores: {},
+      reviewer_independence: reviewerIndependence,
+      score_status: resolveScoreStatus(reviewerIndependence, meta),
+      availability: false,
+      availability_reason: 'invalid-counts',
+      warnings,
+      suggestions,
+      total: Number.isInteger(total) ? total : null,
+      errors: Number.isInteger(errors) ? errors : null,
+    };
+  }
 
   const categoryScores = {};
   const categories = checkResults.categories && typeof checkResults.categories === 'object'
@@ -380,6 +475,33 @@ function computeV3ChangeMetrics(context = {}) {
       q3_score_status: q3Result.score_status,
       q3_availability: q3Result.availability,
       q3_availability_reason: q3Result.availability_reason,
+      q3_total: q3Result.total ?? null,
+      q3_errors: q3Result.errors ?? null,
+      q3_warnings: q3Result.warnings ?? 0,
+      q3_suggestions: q3Result.suggestions ?? 0,
+      q3_review: {
+        reviewer_independence: q3Result.reviewer_independence,
+        review_execution_mode: q3Result.review_execution_mode
+          || context.check_meta?.review_execution_mode
+          || null,
+        reviewer_agent_id: q3Result.reviewer_agent_id
+          || context.check_meta?.reviewer_agent_id
+          || null,
+        review_session_id: q3Result.review_session_id
+          || q3Result.reviewer_session_id
+          || context.check_meta?.review_session_id
+          || context.check_meta?.reviewer_session_id
+          || null,
+        author_session_id: q3Result.author_session_id
+          || context.check_meta?.author_session_id
+          || null,
+        fallback_reason_code: q3Result.fallback_reason_code
+          || context.check_meta?.fallback_reason_code
+          || null,
+        fallback_reason: q3Result.fallback_reason
+          || context.check_meta?.fallback_reason
+          || null,
+      },
       q1_spec_conformance: buildPendingUpstreamMetric(context.q1_spec_conformance, context.q1_source),
       q4_tdd_coverage: buildPendingUpstreamMetric(context.q4_tdd_coverage, context.q4_source),
     },
@@ -456,8 +578,12 @@ function aggregateV3Metrics(changeMetrics, options = {}) {
   const distribution = {};
 
   for (const key of metricKeys) {
-    byChangeType[key] = aggregateByChangeType(changeMetrics, key, options);
+    byChangeType[key] = aggregateByChangeType(changeMetrics, key, {
+      ...options,
+      includeUnknown: false,
+    });
     const allValues = changeMetrics
+      .filter(m => validateChangeType(m.change_type) !== 'unknown')
       .map(m => pickMetricValue(m, key))
       .filter(v => Number.isFinite(v));
     distribution[key] = summarizeDistribution(allValues);
@@ -1210,12 +1336,15 @@ module.exports = {
   REPORT_SCHEMA_VERSION,
   METRICS_CONTRACT_VERSION,
   SCHEME_VERSION,
+  BUSINESS_CHANGE_TYPES,
   CHANGE_TYPES,
   LEGACY_CHANGE_TYPES,
   ALERT_THRESHOLDS,
   MINIMUM_METRICS,
   clamp,
   round,
+  computeTelemetryHealthScore,
+  resolveScoreStatus,
   percentile,
   summarizeDistribution,
   detectIqrOutliers,
@@ -1238,4 +1367,5 @@ module.exports = {
   formatArtifactSize,
   createInvalidArgError,
   countScenariosInMarkdown,
+  extractScenariosInMarkdown,
 };

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

@@ -5,6 +5,14 @@ const fs = require('fs');
 const path = require('path');
 const { generateUuidV7 } = require('./id.cjs');
 const { resolveRuntimeMetadata } = require('../runtime-metadata.cjs');
+const {
+  readJson,
+  writeJsonAtomic,
+  writeTextAtomic,
+  toPosix,
+  sha256,
+  ensureDir,
+} = require('../lib/shared.cjs');
 
 const RUNTIME_METADATA = resolveRuntimeMetadata();
 const PRODUCER_VERSION = RUNTIME_METADATA.version;
@@ -19,30 +27,7 @@ const CANONICAL_FACTS_PATH = 'canonical-facts.json';
 const CONVERSION_REPORT_PATH = 'conversion-report.json';
 const PACKAGE_SUFFIXES = new Set(['.md', '.html', '.json', '.jsonl', '.yaml', '.yml']);
 
-function sha256(content) {
-  return crypto.createHash('sha256').update(content).digest('hex');
-}
-
-function readJson(filePath) {
-  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-}
-
-function atomicWrite(filePath, content) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
-  fs.writeFileSync(tempPath, content);
-  fs.renameSync(tempPath, filePath);
-}
-
-function writeJson(filePath, value) {
-  const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
-  atomicWrite(filePath, bytes);
-  return bytes;
-}
-
-function toPosix(value) {
-  return String(value || '').replace(/\\/g, '/');
-}
+// readJson, atomicWrite, writeJson, toPosix, sha256 已迁移至 lib/shared.cjs
 
 function safePackagePath(value) {
   const input = toPosix(value).trim();
@@ -65,18 +50,18 @@ function ensureProjectIdentity(projectRoot) {
     }
     return existing;
   }
-  // 兜底：project-identity.json 未通过 opsx-ontology-query 配置 KB 时创建
+  // 兜底：project-identity.json 未通过 opsx-kb-config 配置 KB 时创建
   // 此时 project_id 为随机值，KB 入库时会因 project_id !== spaceKey 而失败
-  console.warn('⚠️  project-identity.json 不存在 — 未通过 opsx-ontology-query 配置 KB。');
+  console.warn('⚠️  project-identity.json 不存在 — 未通过 opsx-kb-config 配置 KB。');
   console.warn('⚠️  将生成临时 project_id，KB 入库时需确保与 Space spaceKey 一致。');
-  console.warn('⚠️  建议在首次使用 opsx-ontology-query 配置 KB 时自动创建正确的 project-identity.json。');
+  console.warn('⚠️  建议运行 /opsx-kb-config 配置 KB 后更新 project_id 为 Space spaceKey。');
   const identity = {
     schema_version: PROJECT_IDENTITY_SCHEMA_VERSION,
     project_id: `urn:kld:sdd:project:${generateUuidV7()}`,
     created_at: new Date().toISOString(),
-    _warning: 'UNCONFIGURED — 请通过 opsx-ontology-query 配置 KB 后更新 project_id 为 Space spaceKey',
+    _warning: 'UNCONFIGURED — 请运行 /opsx-kb-config 配置 KB 后更新 project_id 为 Space spaceKey',
   };
-  writeJson(identityPath, identity);
+  writeJsonAtomic(identityPath, identity);
   return identity;
 }
 
@@ -188,7 +173,7 @@ function assertExternalKeyFinalGate(entities) {
         const parts = parseScenario(ref.external_id);
         if (!parts || !packageRequirementIds.has(parts.requirementId)) {
           throw new Error(
-            `${CODES.SCOPE_MISMATCH}: 场景键 REQ 前缀不在同包 requirement 绑定集合中: ${ref.external_id} @ ${entity.anchor_id}`,
+            `${CODES.SCOPE_MISMATCH}: 场景键需求编号前缀不在同包 requirement 绑定集合中: ${ref.external_id} @ ${entity.anchor_id}`,
           );
         }
       }
@@ -499,7 +484,7 @@ function writeArchiveZip(archiveDir, packagePath, manifest) {
   end.writeUInt32LE(centralDirectory.length, 12);
   end.writeUInt32LE(offset, 16);
   end.writeUInt16LE(0, 20);
-  atomicWrite(packagePath, Buffer.concat([...localParts, centralDirectory, end]));
+  writeTextAtomic(packagePath, Buffer.concat([...localParts, centralDirectory, end]));
   return packagePath;
 }
 
@@ -595,7 +580,7 @@ function materializeArchivePackage(options = {}) {
     archiveId,
   );
   const canonicalPath = path.join(archiveDir, CANONICAL_FACTS_PATH);
-  const canonicalBytes = writeJson(canonicalPath, canonicalFacts);
+  const canonicalBytes = writeJsonAtomic(canonicalPath, canonicalFacts);
 
   const conversionReport = {
     schema_version: CONVERSION_REPORT_SCHEMA_VERSION,
@@ -609,7 +594,7 @@ function materializeArchivePackage(options = {}) {
     relation_count: canonicalFacts.relations.length,
     warnings,
   };
-  writeJson(path.join(archiveDir, CONVERSION_REPORT_PATH), conversionReport);
+  writeJsonAtomic(path.join(archiveDir, CONVERSION_REPORT_PATH), conversionReport);
 
   const existingManifestPath = path.join(archiveDir, MANIFEST_PATH);
   const existingManifest = fs.existsSync(existingManifestPath)
@@ -649,7 +634,7 @@ function materializeArchivePackage(options = {}) {
       ? (existingManifest.evidence_events_path || null)
       : options.evidenceEventsPath,
   };
-  writeJson(existingManifestPath, manifest);
+  writeJsonAtomic(existingManifestPath, manifest);
 
   const packagePath = options.packagePath === false
     ? ''

package/skywalk-sdd/ontology/change-lock.cjs

@@ -4,6 +4,7 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { safeChangeName } = require('./artifact-parser.cjs');
+const { readJsonSafe } = require('../lib/shared.cjs');
 
 const DEFAULT_STALE_MS = 5 * 60 * 1000;
 
@@ -27,13 +28,8 @@ function isProcessAlive(pid) {
   }
 }
 
-function readLock(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch (error) {
-    return null;
-  }
-}
+// readLock 改用 shared.cjs 的 readJsonSafe（带 BOM 剥离）
+const readLock = readJsonSafe;
 
 function isStaleLock(lock, staleMs) {
   if (!lock || !lock.created_at) return true;

package/skywalk-sdd/ontology/external-key.cjs

@@ -4,20 +4,26 @@
  * External key grammar for requirement / feature / scenario.
  * Authority: kb-sdd docs/superpowers/specs/2026-07-24-external-numbering-kb-sdd-design.md §2.
  * Regex and normalization MUST stay byte-for-byte aligned with kb-sdd ExternalKeyFormat.java.
+ *
+ * 格式放宽（2026-08-04）：requirement / feature 不再强制 REQ-/FEAT- 前缀，
+ * 允许外部系统（客户 ERP、Jira 等）的自有编号格式。
+ * 白名单：大写字母 + 数字 + 连字符(-) + 下划线(_)，1~50 字符。
+ * 示例：KLERP-001, KLERP001, 1010000, KLERP_001, REQ-FI-2024-001
  */
 
 const REGEX = {
-  requirement: /^REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}$/,
-  feature: /^FEAT-[A-Z][A-Z0-9]{1,7}-[0-9]{3,6}$/,
-  scenario: /^REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$/,
+  requirement: /^[A-Z0-9_-]+$/,
+  feature: /^[A-Z0-9_-]+$/,
+  scenario: /^[A-Z0-9_-]+:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$/,
 };
 
 const SCENARIO_PARTS =
-  /^(REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}):SCN-([a-z0-9]+(?:-[a-z0-9]+)*)-([0-9]{3})$/;
+  /^([A-Z0-9_-]+):SCN-([a-z0-9]+(?:-[a-z0-9]+)*)-([0-9]{3})$/;
 
 const SLUG_MAX_LEN = 40;
 const SCENARIO_KEY_MAX_LEN = 120;
 const SCN_SEQ_MAX = 999;
+const EXTERNAL_ID_MAX_LEN = 50;
 
 const CODES = {
   FORMAT_INVALID: 'EXTERNAL_KEY_FORMAT_INVALID',
@@ -76,6 +82,13 @@ function validate(id, objectType) {
       message: `编号格式不合规 (${type}): ${id} → ${normalized}`,
     };
   }
+  if ((type === 'requirement' || type === 'feature') && normalized.length > EXTERNAL_ID_MAX_LEN) {
+    return {
+      ok: false,
+      code: CODES.FORMAT_INVALID,
+      message: `编号超过 ${EXTERNAL_ID_MAX_LEN} 字符: ${normalized}`,
+    };
+  }
   if (type === 'scenario') {
     const parts = parseScenario(normalized);
     if (!parts) {
@@ -150,6 +163,7 @@ module.exports = {
   SLUG_MAX_LEN,
   SCENARIO_KEY_MAX_LEN,
   SCN_SEQ_MAX,
+  EXTERNAL_ID_MAX_LEN,
   normalize,
   validate,
   parseScenario,

package/skywalk-sdd/ontology/id.cjs

@@ -59,19 +59,39 @@ function generateUuidV7() {
   return generateIdentityId();
 }
 
+/**
+ * Normalize a UUID value to the internal 8-hex short format.
+ *
+ * KB backend (PostgreSQL) serializes UUID columns as full 36-char format
+ * (e.g. "3518f551-0000-0000-0000-000000000000").  The SDD toolchain uses
+ * an 8-hex short format internally (e.g. "3518f551").  This function
+ * accepts both and returns the short form.
+ */
+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}$/);
+  if (fullUuidMatch) {
+    return fullUuidMatch[1];
+  }
+  return v;
+}
+
 function isValidUuid(value) {
-  return new RegExp(`^[0-9a-f]{${ID_HEX_LENGTH}}$`).test(String(value || '').trim().toLowerCase());
+  const v = String(value || '').trim().toLowerCase();
+  // Accept 8-hex short format (internal) OR 36-char full UUID (from KB API)
+  return /^[0-9a-f]{8}$/.test(v)
+    || /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(v);
 }
 
 const isValidUuidV7 = isValidUuid;
 
 function allocateIdentity(options = {}) {
   const deltaState = String(options.deltaState || options['delta-state'] || 'added').trim().toLowerCase();
-  const entityId = String(options.entityId || options['entity-id'] || '').trim().toLowerCase();
-  const versionId = String(options.versionId || options['version-id'] || '').trim().toLowerCase();
-  const predecessorVersionId = String(
+  const entityId = normalizeUuid(options.entityId || options['entity-id'] || '');
+  const versionId = normalizeUuid(options.versionId || options['version-id'] || '');
+  const predecessorVersionId = normalizeUuid(
     options.predecessorVersionId || options['predecessor-version'] || '',
-  ).trim().toLowerCase();
+  );
 
   if (!['added', 'modified', 'unchanged', 'removed'].includes(deltaState)) {
     throw new Error(`不支持的 delta-state: ${deltaState}`);
@@ -119,5 +139,6 @@ module.exports = {
   generateUuidV7,
   isValidUuid,
   isValidUuidV7,
+  normalizeUuid,
   allocateIdentity,
 };

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

@@ -9,6 +9,7 @@ const {
   ONTOLOGY_STATE_FILES,
   resolveOntologyStateFile,
 } = require('./ontology-paths.cjs');
+const { readJsonSafe } = require('../lib/shared.cjs');
 
 function catalogDiagnostic(code, message, context = {}) {
   return {
@@ -22,13 +23,8 @@ function catalogDiagnostic(code, message, context = {}) {
   };
 }
 
-function readJson(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
+// readJson 已迁移至 lib/shared.cjs（readJsonSafe 版本，返回 null 而非抛出）
+const readJson = readJsonSafe;
 
 function identityRoots(projectRoot) {
   const root = path.resolve(projectRoot || process.cwd());

package/skywalk-sdd/ontology/resolve-spec-root.cjs

@@ -5,13 +5,27 @@ const path = require('path');
 const sddConfig = require('./sdd-config.cjs');
 const workspaceLayout = require('./workspace-layout.cjs');
 
+/**
+ * 从 anchorRoot 向上遍历目录树，查找 .sdd-spec-root 配置文件。
+ * 修复：当 shim 从子目录（如 sdd-sdd-specs/）运行时，cwd 不是 workspace 根目录，
+ * 需要向上查找到 .sdd-spec-root 所在的祖先目录。
+ */
 function resolveHint(anchorRoot) {
-  const hintPath = path.join(anchorRoot, '.sdd-spec-root');
-  if (!fs.existsSync(hintPath)) return null;
-  const hint = fs.readFileSync(hintPath, 'utf8').trim();
-  if (!hint) return null;
-  const resolved = path.resolve(anchorRoot, hint);
-  return fs.existsSync(resolved) ? resolved : null;
+  let current = path.resolve(anchorRoot);
+  const root = path.parse(current).root;
+  for (;;) {
+    const hintPath = path.join(current, '.sdd-spec-root');
+    if (fs.existsSync(hintPath)) {
+      const hint = fs.readFileSync(hintPath, 'utf8').trim();
+      if (hint) {
+        const resolved = path.resolve(current, hint);
+        if (fs.existsSync(resolved)) return resolved;
+      }
+    }
+    if (current === root) break;
+    current = path.dirname(current);
+  }
+  return null;
 }
 
 function resolveSpecProjectRoot(projectRoot = process.cwd()) {