kld-sdd 2.7.8-2 → 2.7.8-4

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "kld-sdd",
-  "version": "2.7.8-2",
+  "version": "2.7.8-4",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
-  "main": "index.js",
+  "main": "lib/init.js",
   "bin": {
     "kld-sdd": "bin/kld-sdd-init.js",
     "kld-sdd-init": "bin/kld-sdd-init.js"
   },
   "scripts": {
     "bench:check": "node test/benchmark-check.cjs",
-    "test": "node --test test/execution-friction.test.cjs test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/prompt-spec-path.cjs && node test/workspace-layout.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs && node test/init-report-runtime.cjs && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs skywalk-sdd/usage-reporter.test.cjs skywalk-sdd/usage-reporting.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
+    "test": "node --test test/delivery-hooks.test.cjs test/execution-friction.test.cjs test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/prompt-spec-path.cjs && node test/spec-detect.cjs && node test/workspace-layout.cjs && node test/sync-repos-spec-choice.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/deploy-strategy.cjs && node test/uninstall.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs && node test/init-report-runtime.cjs && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs test/runtime/usage-reporter.test.cjs test/runtime/usage-reporting.test.cjs test/runtime/git-identity.test.cjs test/runtime/kb-state-location.test.cjs && node test/runtime/metrics-v3.test.cjs && node test/runtime/fixback.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
   },
   "keywords": [
     "kld",

package/skywalk-sdd/index.cjs

@@ -8610,7 +8610,7 @@ SDD Telemetry CLI - 流程度量采集工具
   check-task 扫描变更目录 tasks.md 并勾选指定 task_id
   archive-docs 将 Simple/Full spec 变更真实移动到 openspec/changes/archive/，并可结束 archive 阶段生成报告
   kb-upload 知识库上传（文件夹自动打包 / zip 直传），支持随时入库
-  semantic-identity 生成或复用实体/版本 ID（8 位十六进制）；无需网络和中央 ID 服务
+  semantic-identity 生成或复用实体/版本 ID（完整 UUID，界面可显示短标识）；无需网络和中央 ID 服务
   semantic-scan 只读解析并校验当前 Change
   semantic-reconcile 全量对账文件与本地工作态本体实例
   semantic-check 全量对账并在通过时标记 pending；--include-tasks 同时返回任务状态、评审输入清单和程序耗时

package/skywalk-sdd/kb-upload.cjs

@@ -28,7 +28,8 @@ const {
   ensureDir,
   copyDirRecursive,
   resolveSpecRootFast,
-  loadKbState,
+  KB_STATE_FILENAME,
+  isKbStateHostDir,
   uploadFile,
   httpGetJson,
 } = require('./lib/shared.cjs');
@@ -61,6 +62,18 @@ function assertIngestionResult(result) {
   return job;
 }
 
+/**
+ * 解析 kb-state.json 的权威路径：`<specRoot>/kb-state.json`。
+ *
+ * 位置校验已由 `resolveSpecRoot` 在入口完成（本函数只做路径拼接）。
+ *
+ * @param {string} specRoot spec 包裹包根目录
+ * @returns {string} kb-state.json 绝对路径
+ */
+function resolveKbStatePath(specRoot) {
+  return path.join(path.resolve(specRoot), KB_STATE_FILENAME);
+}
+
 /**
  * 读取 kb-state.json 中指定 change 的 archive 缓存。
  * @param {string} specRoot
@@ -68,9 +81,7 @@ function assertIngestionResult(result) {
  * @returns {object|null} { archive_id, content_hash, uploaded_at }
  */
 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 statePath = resolveKbStatePath(specRoot);
   const state = readJsonSafe(statePath);
   if (!state || !state.archiveCache) return null;
   const key = cacheKey(changeName, context);
@@ -85,9 +96,7 @@ function readArchiveCache(specRoot, changeName, context) {
  * @param {string} 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 statePath = resolveKbStatePath(specRoot);
   const state = readJsonSafe(statePath) || {};
   if (!state.archiveCache) state.archiveCache = {};
   const key = cacheKey(changeName, context);
@@ -116,8 +125,18 @@ const DEFAULT_LEVEL = 'propose-spec';
 // ── 工具函数 ──────────────────────────────────────────
 
 function resolveSpecRoot(explicit) {
-  if (explicit) return path.resolve(explicit);
-  return resolveSpecRootFast(__dirname);
+  const root = explicit ? path.resolve(explicit) : resolveSpecRootFast(__dirname);
+  // 位置校验前移：specRoot 必须是 spec 包裹包根，后续所有 kb-state.json /
+  // project-identity.json 读取都建立在它之上。在此 fail-fast，避免流程走到
+  // 中途才因「文件不存在」报出误导性错误（真正原因是路径指错了地方）。
+  if (!isKbStateHostDir(root)) {
+    throw new Error(
+      `kb-state.json 位置校验失败：${root} 不是 spec 包裹包根目录。\n` +
+      'kb-state.json 只允许位于 spec 包裹包根（由 /opsx-kb-config 写入）。\n' +
+      '请确认 --project 指向 *-sdd-specs 包裹包，或运行 /opsx-kb-config 重新配置。'
+    );
+  }
+  return root;
 }
 
 /**
@@ -139,36 +158,28 @@ function resolveProjectId(specRoot) {
 }
 
 /**
- * 读取 KB 配置（api, apiKey, tenantKey, targets）
- * 使用 shared.cjs 的 loadKbState，支持 BOM 剥离和多路径搜索
+ * 读取 KB 配置（api, apiKey, tenantKey, targets）。
+ *
+ * 位置校验：只读 `<specRoot>/kb-state.json`（specRoot 的 spec 根身份已由
+ * resolveSpecRoot 在入口校验）。
  */
 function readKbState(specRoot) {
-  // 优先尝试 specRoot 根目录下的 kb-state.json（新路径）
-  const directPath = path.join(specRoot, 'kb-state.json');
-  // 兼容旧路径：specRoot 同级 .shared/kb-state.json
-  const legacyPath = path.join(specRoot, '..', '.shared', 'kb-state.json');
-  if (fs.existsSync(directPath)) {
-    try {
-      return readJson(directPath);
-    } catch (e) {
-      throw new Error(
-        `KB 配置解析失败 (${directPath}): ${e.message}\n` +
-        '请运行 /opsx-kb-config 重新配置知识库。'
-      );
-    }
-  }
-  // 退回到多路径搜索（从 specRoot 向上查找）
-  const { config, path: foundPath, warnings } = loadKbState(specRoot);
-  if (warnings.length > 0) {
-    for (const w of warnings) console.warn(`⚠️  ${w}`);
-  }
-  if (!config) {
+  const statePath = resolveKbStatePath(specRoot);
+  if (!fs.existsSync(statePath)) {
     throw new Error(
       'KB 配置不存在（kb-state.json 缺失）。\n' +
+      `期望位置: ${statePath}\n` +
       '请运行 /opsx-kb-config 配置知识库。'
     );
   }
-  return config;
+  try {
+    return readJson(statePath);
+  } catch (e) {
+    throw new Error(
+      `KB 配置解析失败 (${statePath}): ${e.message}\n` +
+      '请运行 /opsx-kb-config 重新配置知识库。'
+    );
+  }
 }
 
 /**
@@ -332,6 +343,7 @@ async function main() {
   try {
     // ── Zip 模式 ──
     if (args.package) {
+      if (args['validate-only']) throw new Error('--validate-only 仅支持 --folder/--change 本地语义校验；未执行归档上传');
       const zipPath = path.resolve(args.package);
       if (!fs.existsSync(zipPath)) {
         throw new Error(`zip 文件不存在: ${zipPath}`);
@@ -370,9 +382,12 @@ 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 指定归档包');
+    const changesRoot = fs.realpathSync(path.resolve(specRoot, 'openspec', 'changes'));
+    const expectedPath = path.resolve(changesRoot, changeName);
+    const expectedFolder = fs.existsSync(expectedPath) ? fs.realpathSync(expectedPath) : expectedPath;
+    const suppliedFolder = fs.existsSync(folderPath) ? fs.realpathSync(folderPath) : path.resolve(folderPath);
+    if (suppliedFolder !== expectedFolder || !expectedFolder.startsWith(changesRoot + path.sep)) {
+      throw new Error('文件夹上传仅接受当前 Spec 仓 openspec/changes/<change>；已归档内容请用 --package 指定归档包');
     }
 
     if (!fs.existsSync(folderPath)) {
@@ -389,19 +404,6 @@ async function main() {
     // 1. 校验必需文件
     validateRequiredFiles(folderPath, minimumLevel);
 
-    // 2. 解析 project_id
-    const projectId = resolveProjectId(specRoot);
-    console.log(`✓ project_id: ${projectId}`);
-
-    // 3. 读取 KB 配置 + 预检
-    const state = readKbState(specRoot);
-    if (!state.apiKey) {
-      throw new Error('KB 配置中无 apiKey，请运行 /opsx-kb-config 配置知识库。');
-    }
-    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']) {
       const runtime = require('./ontology/runtime.cjs');
@@ -417,10 +419,23 @@ async function main() {
         throw new Error(`语义校验失败:\n${errors.join('\n')}`);
       }
       console.log(`✓ 语义校验通过 (profile: ${semanticResult.profile}, revision: ${semanticResult.revision})`);
-      console.log('\n✓ 校验完成（--validate-only，未上传）');
+      console.log('\n✓ 本地语义校验完成（--validate-only，未联网；不代表权限、发布基线或入库已验证）');
       return;
     }
 
+    // 2. 解析 project_id
+    const projectId = resolveProjectId(specRoot);
+    console.log(`✓ project_id: ${projectId}`);
+
+    // 3. 读取 KB 配置 + 预检
+    const state = readKbState(specRoot);
+    if (!state.apiKey) {
+      throw new Error('KB 配置中无 apiKey，请运行 /opsx-kb-config 配置知识库。');
+    }
+    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 };
+
     // 5. 构建 Archive Package
     console.log('');
     const { zipPath, manifest, stagingDir } = buildPackageFromFolder(specRoot, changeName, {

package/skywalk-sdd/lib/shared.cjs

@@ -289,61 +289,81 @@ function resolveSpecRootFast(anchorDir = __dirname) {
 // 7. KB 配置加载
 // ═══════════════════════════════════════════════════════════════
 
-/** 已知的 IDE skills 目录名 */
-const IDE_DIRS = [
-  '.codebuddy', '.claude', '.cursor', '.vscode',
-  '.kunlunzhima', '.opencode', '.workbuddy', '.codex',
-];
+/** kb-state.json 文件名（唯一权威位置：spec 包裹包根目录） */
+const KB_STATE_FILENAME = 'kb-state.json';
+
+/** 向上搜索 kb-state.json 的最大层数（从 skywalk-sdd/lib/ 到 spec 根最多 3 层） */
+const MAX_KB_STATE_LEVELS = 6;
+
+let _isSpecPackageRoot = null;
+
+/**
+ * 惰性加载 resolve-spec-root.cjs 的 isSpecPackageRoot（避免加载期循环依赖）。
+ */
+function getIsSpecPackageRoot() {
+  if (!_isSpecPackageRoot) {
+    const mod = require(path.join(__dirname, '..', 'ontology', 'resolve-spec-root.cjs'));
+    _isSpecPackageRoot = mod.isSpecPackageRoot;
+  }
+  return _isSpecPackageRoot;
+}
+
+/**
+ * kb-state.json 位置校验：宿主目录必须是 spec 包裹包根。
+ *
+ * 判据复用 `ontology/resolve-spec-root.cjs#isSpecPackageRoot`（与全仓 spec 识别
+ * 单一真相源对齐），不在本模块另立一套结构判据。
+ *
+ * @param {string} dir 候选宿主目录
+ * @returns {boolean}
+ */
+function isKbStateHostDir(dir) {
+  try {
+    return Boolean(getIsSpecPackageRoot()(dir));
+  } catch {
+    // ontology 层不可用（理论上部署布局下不会发生）：保守判否，避免误用未知位置的配置
+    return false;
+  }
+}
 
 /**
  * 加载 KB 配置（kb-state.json）。
  *
- * 从 anchorDir 逐层向上搜索（优先新路径，兼容旧路径）：
- *   - <dir>/kb-state.json                              ← 新路径（spec 仓根目录）
- *   - <dir>/<ide>/skills/kb-state.json                  ← 新路径（IDE skills 目录）
- *   - <dir>/.shared/kb-state.json                       ← 旧路径（向后兼容）
- *   - <dir>/<ide>/skills/.shared/kb-state.json          ← 旧路径（向后兼容）
+ * **唯一权威位置**：spec 包裹包根目录 `<spec-root>/kb-state.json`
+ * —— 由 `/opsx-kb-config` 写入（见 opsx-kb-config/reference.md §kb-state.json），
+ * spec 仓根、已 gitignore。
+ *
+ * 位置校验（本函数同时承担「位置正确性」判定，而不只是「能否读到」）：
+ * 从 anchorDir 逐级向上查找同名文件，但**只接受宿主目录为 spec 包裹包根**的命中
+ * （isKbStateHostDir）。因此从 `<spec-root>/skywalk-sdd/`、`<spec-root>/skywalk-sdd/lib/`
+ * 等子目录调用都能正确命中 spec 根；而落在工作区根、代码仓根等错误位置的文件
+ * 不会被误用 —— 读到「不该读的配置」比读不到更危险。
  *
  * @param {string} [anchorDir=__dirname] — 搜索起点
- * @param {object} [env=process.env] — 环境变量（用于 fallback）
+ * @param {object} [env=process.env] — 保留参数（环境变量兜底由 resolveKbParams 处理）
  * @returns {{ config: object|null, path: string|null, warnings: string[] }}
  */
 function loadKbState(anchorDir = __dirname, env = process.env) {
+  void env;
   const warnings = [];
-  const candidatePaths = [];
-
-  const MAX_LEVELS = 6;
-  let current = path.resolve(anchorDir);
-  const fileRoot = path.parse(current).root;
-  for (let level = 0; level < MAX_LEVELS; level++) {
-    // 新路径（优先）：直接放在目录下
-    candidatePaths.push(path.join(current, 'kb-state.json'));
-    // 新路径：IDE skills 目录下
-    for (const ide of IDE_DIRS) {
-      candidatePaths.push(path.join(current, ide, 'skills', 'kb-state.json'));
-    }
-    // 旧路径（向后兼容）：.shared/ 子目录
-    candidatePaths.push(path.join(current, '.shared', 'kb-state.json'));
-    for (const ide of IDE_DIRS) {
-      candidatePaths.push(path.join(current, ide, 'skills', '.shared', 'kb-state.json'));
+  const start = path.resolve(anchorDir);
+  const fileRoot = path.parse(start).root;
+
+  let current = start;
+  for (let level = 0; level < MAX_KB_STATE_LEVELS; level += 1) {
+    const candidate = path.join(current, KB_STATE_FILENAME);
+    if (fs.existsSync(candidate) && isKbStateHostDir(current)) {
+      try {
+        const config = JSON.parse(stripBom(fs.readFileSync(candidate, 'utf8')));
+        return { config, path: candidate, warnings };
+      } catch (e) {
+        warnings.push(`kb-state.json 解析失败 (${candidate}): ${e.message}`);
+      }
     }
     if (current === fileRoot) break;
     current = path.dirname(current);
   }
 
-  for (const p of candidatePaths) {
-    try {
-      if (fs.existsSync(p)) {
-        let raw = fs.readFileSync(p, 'utf8');
-        raw = stripBom(raw);
-        const config = JSON.parse(raw);
-        return { config, path: p, warnings };
-      }
-    } catch (e) {
-      warnings.push(`kb-state.json 解析失败 (${p}): ${e.message}`);
-    }
-  }
-
   return { config: null, path: null, warnings };
 }
 
@@ -797,7 +817,8 @@ module.exports = {
   // Spec root
   resolveSpecRootFast,
   // KB state
-  IDE_DIRS,
+  KB_STATE_FILENAME,
+  isKbStateHostDir,
   loadKbState,
   resolveKbParams,
   resolveKbScopes,

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

@@ -17,6 +17,26 @@ function parseCounts(output) {
       && total === passed + failed + (skipped || 0) + (todo || 0)) {
     return { counts_known: true, passed, failed, skipped: (skipped || 0) + (todo || 0) };
   }
+  // Surefire/Failsafe print per-class counts and a Results section. Count only
+  // the latter, once per module/execution, to avoid double-counting classes.
+  const summaries = [];
+  let inResults = false;
+  for (const raw of output.replace(/\u001b\[[0-9;]*m/g, '').split(/\r?\n/)) {
+    const line = raw.replace(/^\[(?:INFO|WARNING|ERROR)\]\s*/, '').trim();
+    if (line === 'Results:') { inResults = true; continue; }
+    if (!inResults) continue;
+    const match = /^Tests run:\s*(\d+),\s*Failures:\s*(\d+),\s*Errors:\s*(\d+),\s*Skipped:\s*(\d+)\b/.exec(line);
+    if (!match) continue;
+    const [, count, failures, errors, ignored] = match.map(Number);
+    if (count < failures + errors + ignored) return { counts_known: false };
+    summaries.push({ passed: count - failures - errors - ignored, failed: failures + errors, skipped: ignored });
+    inResults = false;
+  }
+  if (summaries.length) {
+    return summaries.reduce((sum, item) => ({ counts_known: true, passed: sum.passed + item.passed,
+      failed: sum.failed + item.failed, skipped: sum.skipped + item.skipped }),
+    { counts_known: true, passed: 0, failed: 0, skipped: 0 });
+  }
   return { counts_known: false };
 }
 

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

@@ -23,6 +23,8 @@ const {
   readUserConfig,
 } = require('./user-config.cjs');
 const gitIdentity = require('./git-identity.cjs');
+// kb-state.json 的唯一读取入口（含「必须位于 spec 包裹包根」的位置校验）
+const { loadKbState } = require('./shared.cjs');
 
 const PENDING_FILE_NAME = 'pending-usage.jsonl';
 const PENDING_MAX_BYTES = 1024 * 1024; // 1 MB
@@ -93,6 +95,16 @@ function _resetGitIdentityCache() {
  * 四级解析上报地址：config.server → 项目 kb-state.json api → env KLD_SDD_SERVER → 内置默认。
  * 每级均经 normalizeServerUrl；结果永远非空（默认地址兜底）。
  *
+ * kb-state.json 的读取走 `loadKbState`（唯一 kb-state 读取入口），因此沿用
+ * 其位置校验：只有位于 spec 包裹包根的那份才被采用。位置不符时行为与
+ * 「文件不存在」一致 —— 静默落到下一级（env → 内置默认）。
+ *
+ * 这里刻意**不**把 loadKbState 的 warnings 打到 stderr：上报链路是
+ * 「永不抛错、静默兜底」的后台路径，配置告警应由 KB 技能链路（kb-config /
+ * ontology-query / kb-ingest）呈现，避免每次 log start 都刷屏。
+ * 且宁可上报到默认地址，也不能因为某处残留的陈旧 kb-state.json
+ * 把使用数据发到错误服务器。
+ *
  * @param {{homeDir?:string, projectRoot?:string, env?:object}} [options]
  * @returns {string}
  */
@@ -107,14 +119,11 @@ function resolveReportServer(options = {}) {
   }
   // 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;
-      }
+    const { config: kbState } = loadKbState(projectRoot);
+    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 读取失败时静默，继续下一级

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

@@ -4,6 +4,8 @@ const fs = require('fs');
 const path = require('path');
 const sddConfig = require('./sdd-config.cjs');
 const workspaceLayout = require('./workspace-layout.cjs');
+// spec 判据的唯一真相源（spec-detect 对本模块无依赖，不构成循环）
+const specDetect = require('./spec-detect.cjs');
 
 /**
  * 从 anchorRoot 向上遍历目录树，查找 .sdd-spec-root 配置文件。
@@ -28,6 +30,34 @@ function resolveHint(anchorRoot) {
   return null;
 }
 
+/**
+ * 从 `.sdd-workspace.yaml` 的 `spec_path` 解析 spec 根（向上逐级查找）。
+ *
+ * 委托 `spec-detect.resolveWorkspaceYamlUpward` —— 该解析在 spec-detect 中
+ * 同时用于「候选枚举的 tier 0 来源」，两处共用一份实现，避免漂移。
+ */
+function resolveWorkspaceYamlSpecPath(anchorRoot) {
+  return specDetect.resolveWorkspaceYamlUpward(anchorRoot);
+}
+
+/**
+ * 解析 spec 包裹包根目录。
+ *
+ * 优先级（权威声明 → 结构判据 → 回落）：
+ *   1. `.sdd-spec-root` 指针文件（init / 运行时写入）
+ *   2. `.sdd.yaml` layout: mono（单仓，仓内包裹包）
+ *   3. `.sdd-workspace.yaml` spec_path（多仓工作区编排）
+ *   4. 工作区探测：子仓结构判据命中的 spec 包
+ *   5. 非 Git 子目录包裹包
+ *   6. 回落为入参本身（调用方用 isSpecPackageRoot 区分「就是 spec 根」与「解析失败」）
+ *
+ * 第 3 步是**新增**的：多仓工作区根执行文档类命令时，权威链此前不读
+ * `.sdd-workspace.yaml`，只能靠第 4 步的结构判据猜；而 skills 的
+ * `opsx-consistency-check/scripts.cjs` 早已自己解析该文件 —— 两处不一致。
+ * 现由权威链直接支持，该文件成为与 `.sdd.yaml` 同级的显式声明来源。
+ *
+ * 前 3 步均**向上逐级查找**，故从工作区子目录（如某个代码仓内）调用也能命中。
+ */
 function resolveSpecProjectRoot(projectRoot = process.cwd()) {
   const root = path.resolve(projectRoot);
   const hinted = resolveHint(root);
@@ -37,6 +67,9 @@ function resolveSpecProjectRoot(projectRoot = process.cwd()) {
     return sddConfig.resolveMonoSpecRoot(root);
   }
 
+  const fromWorkspaceYaml = resolveWorkspaceYamlSpecPath(root);
+  if (fromWorkspaceYaml) return fromWorkspaceYaml;
+
   const layout = workspaceLayout.detectWorkspaceLayout(root);
   if (layout.specRepo) return layout.specRepo.abs;
 
@@ -50,7 +83,23 @@ function resolveProjectArg(projectArg = '.', cwd = process.cwd()) {
   return resolveSpecProjectRoot(path.resolve(cwd, projectArg));
 }
 
+/**
+ * 判断 dir 本身是否就是一个 SDD spec 包裹包根。
+ *
+ * 用于 `log spec-root` 的 resolved 判定：当 resolveSpecProjectRoot 因找不到
+ * 任何线索而回落为入参本身时，需区分「dir 就是 spec 根」与「解析失败」。
+ *
+ * ⚠️ 判据已收敛到 `spec-detect.cjs#isSpecPackageRoot`（全仓唯一判据入口）。
+ * 该判据比 `isSpecCandidate` 宽一档 —— 额外接受仅含 `openspec/` 的半成品
+ * （`--skip-openspec` 产物），因为本函数的语义是「能否作为 spec 根使用」
+ * 而非「是否是当前项目的 spec 仓」。
+ */
+function isSpecPackageRoot(dir) {
+  return specDetect.isSpecPackageRoot(dir);
+}
+
 module.exports = {
   resolveProjectArg,
   resolveSpecProjectRoot,
+  isSpecPackageRoot,
 };

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

@@ -3,6 +3,8 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
+// spec 判据的唯一真相源（spec-detect 对本模块的依赖是惰性，不构成循环）
+const specDetect = require('./spec-detect.cjs');
 
 const CODES = {
   MISSING: 'SDD_YAML_MISSING',
@@ -156,12 +158,18 @@ function resolveMonoSpecRoot(repoRoot) {
   return root;
 }
 
+/**
+ * 目录内容是否"像 spec 包"（任一产物标记存在）。
+ *
+ * ⚠️ 判据已收敛到 `spec-detect.cjs#hasSpecPackageContent`（全仓唯一判据入口）。
+ * 本函数保留仅为向后兼容既有调用点。
+ *
+ * 语义：仅用于用户**显式给定**路径的校验（`validateSpecPath` 的
+ * allowNestedPackage 分支）。不可用于检测 —— 单仓代码仓根可能有 modules.yaml
+ * 而无 openspec，仅凭内容无法区分。
+ */
 function looksLikeSpecPackageContent(dir) {
-  return (
-    fs.existsSync(path.join(dir, 'modules.yaml'))
-    || fs.existsSync(path.join(dir, 'sdd.config.yaml'))
-    || fs.existsSync(path.join(dir, 'openspec', 'changes'))
-  );
+  return specDetect.hasSpecPackageContent(dir);
 }
 
 function gitConfig(cwd, key) {
@@ -176,6 +184,25 @@ function gitConfig(cwd, key) {
   }
 }
 
+/**
+ * 删除 git config --local sdd.specPath（卸载用）。
+ * 配置项不存在时视为成功（幂等）。
+ */
+function unsetSpecPath(codeRepoRoot) {
+  if (!gitConfig(codeRepoRoot, 'sdd.specPath')) {
+    return { ok: true, removed: false };
+  }
+  try {
+    execFileSync('git', ['config', '--local', '--unset', 'sdd.specPath'], {
+      cwd: codeRepoRoot,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    return { ok: false, message: `无法删除 git config sdd.specPath: ${error.message}` };
+  }
+  return { ok: true, removed: true };
+}
+
 function gitRemoteUrl(cwd, remote = 'origin') {
   try {
     return execFileSync('git', ['remote', 'get-url', remote], {
@@ -374,6 +401,7 @@ module.exports = {
   resolveSpecPath,
   validateSpecPath,
   setSpecPath,
+  unsetSpecPath,
   resolveCodeRepoContext,
   gitHeadSha,
   gitWorkingTreeClean,