kld-sdd 2.7.3 → 2.7.8

package/lib/init.js

@@ -112,6 +112,139 @@ function parseSelectedTools(args) {
   return selected;
 }
 
+/**
+ * 从命令行参数读取自定义 spec 目录
+ * 支持：--spec-path erp-sdd-specs、--spec-path=./specs、--spec-path=/abs/path/specs
+ * 返回相对/绝对路径字符串，未指定时返回 null。
+ */
+function parseSpecPathArg(args) {
+  const index = args.findIndex(
+    (arg) => arg === '--spec-path' || arg.startsWith('--spec-path='),
+  );
+  if (index === -1) return null;
+
+  const rawValue = args[index] === '--spec-path'
+    ? args[index + 1]
+    : args[index].slice('--spec-path='.length);
+
+  if (!rawValue || rawValue.startsWith('--')) {
+    throw new Error('缺少 --spec-path 参数值，请指定 spec 仓库目录（相对或绝对路径）');
+  }
+  return rawValue.trim();
+}
+
+/**
+ * 将 --spec-path 解析为 { name, abs }。
+ * - 绝对路径：直接使用
+ * - 相对路径：相对 workspaceRoot 解析
+ * 仅取末段目录名作为包裹包名，abs 落在 workspaceRoot 下（保持包裹包在工作区/仓内的定位）。
+ */
+function resolveSpecPathOption(specPathArg, workspaceRoot) {
+  if (!specPathArg) return null;
+  const root = path.resolve(workspaceRoot);
+  const abs = path.resolve(root, specPathArg);
+  const rel = path.relative(root, abs);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(
+      `--spec-path 必须落在当前目录内（相对包裹包定位）：${specPathArg}\n` +
+      `  当前目录: ${root}\n  解析结果: ${abs}`,
+    );
+  }
+  const relPosix = rel.replace(/\\/g, '/');
+  // name 用相对路径（支持嵌套），供 ensureSpecPackage 与 .sdd.yaml spec_path 使用
+  return { name: relPosix, abs, rel: relPosix, display: path.basename(abs) };
+}
+
+/**
+ * 交互提示前的 spec 目录兜底检测：
+ * detectWorkspaceLayout 的 specRepo 只覆盖「子目录是 Git 仓」的场景，
+ * 这里补充两种常见形态，避免已有 spec 产物被漏检：
+ * 1. .sdd-spec-root 指针文件（历史初始化产物）
+ * 2. 非 Git 子目录的 spec 产物（findNestedSpecPackage 不要求子目录是 Git 仓）
+ */
+function detectSpecCandidateForPrompt(workspaceRoot) {
+  try {
+    const hintPath = path.join(workspaceRoot, '.sdd-spec-root');
+    if (fs.existsSync(hintPath)) {
+      const rel = String(fs.readFileSync(hintPath, 'utf8') || '')
+        .trim()
+        .split(/\r?\n/)[0]
+        .trim();
+      if (rel) {
+        const abs = path.resolve(workspaceRoot, rel);
+        if (fs.existsSync(abs) && workspaceLayout.looksLikeSpecRepo(abs)) {
+          return { name: path.basename(abs), abs };
+        }
+      }
+    }
+  } catch { /* 指针读取异常时继续兜底 */ }
+
+  const nested = workspaceLayout.findNestedSpecPackage(workspaceRoot);
+  return nested ? { name: nested.name, abs: nested.abs } : null;
+}
+
+/**
+ * 交互式确定 spec 包裹包目录（--spec-path 未显式指定时）：
+ * 1. 自动检测到已有 spec 产物（modules.yaml / openspec/changes / *-sdd-specs）→ 提醒用户确认是否使用
+ * 2. 未检测到 → 要求用户输入相对路径指定（回车则用默认推导名 <当前目录名>-sdd-specs）
+ *
+ * 非交互环境（CI / 管道 / --tool 自动化）不询问，保持原自动推导行为。
+ *
+ * @param {object} [options] - 测试注入：{ askFn, interactive }
+ * @returns {{ name: string, abs: string, rel: string, display: string } | null}
+ *          null 表示未选择自定义目录，走默认推导逻辑
+ */
+async function promptSpecPath(workspaceRoot, detectedSpec, options = {}) {
+  const askUser = options.askFn || ask;
+  let interactive = options.interactive;
+  if (typeof interactive !== 'boolean') {
+    // 非交互环境：无 TTY 或显式给了 --tool（自动化场景），不询问
+    const isTTY = process.stdin && process.stdin.isTTY;
+    const hasToolArg = process.argv.slice(2).some((arg) => arg === '--tool' || arg.startsWith('--tool='));
+    interactive = Boolean(isTTY) && !hasToolArg;
+  }
+  if (!interactive) return null;
+
+  if (detectedSpec) {
+    console.log(`\n🔍 检测到已有 spec 目录（命名约定或完整结构标记）: ${detectedSpec.name}`);
+    console.log(`   位置: ${detectedSpec.abs}`);
+    while (true) {
+      const answer = await askUser(`是否使用该 spec 仓库？(Y=使用 / n=重新指定路径，默认 Y): `);
+      const normalized = (answer || '').trim().toLowerCase();
+      if (!normalized || normalized === 'y' || normalized === 'yes') {
+        const relPosix = path.relative(workspaceRoot, detectedSpec.abs).replace(/\\/g, '/') || detectedSpec.name;
+        return { name: relPosix, abs: detectedSpec.abs, rel: relPosix, display: detectedSpec.name };
+      }
+      if (normalized === 'n' || normalized === 'no') break;
+      console.log(`❌ 无效输入 "${answer}"，请输入 Y 或 n`);
+    }
+  } else {
+    console.log('\n🔍 未检测到已有 spec 目录（目录名 *-sdd-specs，或 modules.yaml + sdd.config.yaml + openspec/changes + openspec/specs/overview.md 齐全）');
+  }
+
+  // 未确认使用检测目录（或未检测到）：要求输入相对路径
+  const defaultName = workspaceLayout.deriveSpecPackageName(workspaceRoot);
+  while (true) {
+    const input = await askUser(`请输入 spec 目录的相对路径（直接回车使用默认 ${defaultName}）: `);
+    const trimmed = (input || '').trim();
+    if (!trimmed) {
+      // 回车 = 使用默认推导名。
+      // 若用户刚用 n 拒绝了检测到的目录，必须显式返回默认目录：
+      // 返回 null 会让主流程走自动探测，重新命中刚被拒绝的目录。
+      if (detectedSpec) {
+        return resolveSpecPathOption(defaultName, workspaceRoot);
+      }
+      return null; // 未检测到场景：走主流程默认创建
+    }
+    try {
+      return resolveSpecPathOption(trimmed, workspaceRoot);
+    } catch (error) {
+      console.log(`❌ ${error.message}`);
+      // 循环重新输入
+    }
+  }
+}
+
 /**
  * 让用户选择编辑器
  * 无效输入时重新询问，不允许默认
@@ -918,6 +1051,17 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
     }
   }
 
+  // 部署 scale-thresholds.json（Simple/Full 模式判定阈值，opsx-propose §6.8 自动规模判定依赖）
+  const thresholdsSrc = path.join(pkgPath, 'lib', 'scale-thresholds.json');
+  const thresholdsDst = path.join(sharedLibDir, 'scale-thresholds.json');
+  if (fs.existsSync(thresholdsSrc)) {
+    fs.copyFileSync(thresholdsSrc, thresholdsDst);
+    deployedModules += 1;
+    vlog('   ✓ 部署 skywalk-sdd/lib/scale-thresholds.json（Simple/Full 判定阈值）');
+  } else {
+    console.log('   ⚠️  scale-thresholds.json 源文件缺失，propose 自动规模判定将使用内置默认值');
+  }
+
   const packageVersion = require(path.join(pkgPath, 'package.json')).version;
   const runtimeMetadataDst = path.join(dataDir, 'runtime-metadata.cjs');
   fs.writeFileSync(
@@ -1043,7 +1187,8 @@ function installSddShellHook(cwd, hookName, pkgPath = getPackagePath()) {
       // 已是 SDD hook：允许覆盖升级
       fs.writeFileSync(hookPath, content, 'utf8');
       try {
-        fs.chmodSync(hookPath, 0o755);
+        // 0o700：仅属主可执行（git 以属主身份执行 hook），避免 S2612 对组/其他用户放权的告警
+        fs.chmodSync(hookPath, 0o700);
       } catch {
         // ignore
       }
@@ -1563,6 +1708,11 @@ KLD SDD 项目初始化工具
   --skip-openspec  跳过 openspec init 步骤
   --skip-template  跳过复制内置模版
   --tool <name>     指定编辑器，可用值: cursor, claude, codebuddy, qoder, opencode, kunlunzhima, workbuddy, codex, all
+  --spec-path <dir> 指定 spec 包裹包目录（必须是当前目录的子目录）。
+                    不指定时（交互终端）：自动检测已有 spec 目录（目录名 *-sdd-specs，
+                    或 modules.yaml + sdd.config.yaml + openspec/changes + openspec/specs/overview.md 齐全），
+                    检测到则询问是否使用；未检测到则要求输入相对路径（回车用默认 <当前目录名>-sdd-specs）。
+                    例: 在 erp-klny-all 下 --spec-path erp-sdd-specs
 
 工作区模式（在个人工作目录执行）:
   - skills / 编辑器配置只部署一次到当前工作目录
@@ -1575,6 +1725,7 @@ KLD SDD 项目初始化工具
   kld-sdd-init                 # 完整初始化流程
   kld-sdd-init --skip-openspec # 跳过 openspec，直接部署 skills
   kld-sdd-init --tool codex    # 仅部署 Codex 配置
+  kld-sdd-init --spec-path erp-sdd-specs  # 指定 spec 目录（当前目录的子目录）
   kld-sdd sync-repos           # 新代码仓加入后同步接入
 `);
 }
@@ -1642,6 +1793,17 @@ async function main() {
   const skipOpenspec = args.includes('--skip-openspec');
   const skipTemplate = args.includes('--skip-template');
 
+  // 自定义 spec 目录（--spec-path）：未指定时交互询问（自动检测确认 / 输入相对路径）
+  let customSpec = null;
+  try {
+    const specPathArg = parseSpecPathArg(args);
+    if (specPathArg) customSpec = resolveSpecPathOption(specPathArg, process.cwd());
+  } catch (error) {
+    console.error(`❌ ${error.message}`);
+    closeRl();
+    process.exit(1);
+  }
+
   console.log('╔════════════════════════════════════════╗');
   console.log('║     KLD SDD 项目初始化工具             ║');
   console.log('║     内置 openSpec 标准模版             ║');
@@ -1664,10 +1826,47 @@ async function main() {
     ? { name: layout.specRepo.name, abs: layout.specRepo.abs, created: false, isGit: true }
     : null;
 
+  // 统一在此确定 spec 包裹包目录，后续所有分支直接复用 specPackage，不再各自 ensureSpecPackage。
+  // - 显式 --spec-path：以指定目录为准（复用或创建），优先于同级自动探测
+  // - 未显式指定：交互环境先自动检测已有 spec 产物，检测到则询问确认，未检测到则要求输入相对路径
+  //   （非交互环境 / 用户回车跳过：保持原默认推导行为）
+  // - 否则未探测到 spec 仓：创建默认包裹包（--skip-template + --skip-openspec 时不创建）
+  // initGit：多仓工作区的包裹包是独立 Git 仓；单仓/非 Git 则共用外层 Git。
+  const specInitGit = layout.isWorkspace;
+  if (customSpec) {
+    specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, {
+      initGit: specInitGit,
+      name: customSpec.name,
+    });
+    console.log(`📌 使用自定义 spec 目录: ${customSpec.rel}`);
+    console.log();
+  } else {
+    // 交互提示前兜底检测：Git 仓探测（layout.specRepo）漏掉的非 Git spec 产物
+    const promptCandidate = layout.specRepo
+      ? { name: layout.specRepo.name, abs: layout.specRepo.abs }
+      : detectSpecCandidateForPrompt(workspaceRoot);
+    const interactiveSpec = await promptSpecPath(workspaceRoot, promptCandidate);
+    if (interactiveSpec) {
+      customSpec = interactiveSpec;
+      specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, {
+        initGit: specInitGit,
+        name: customSpec.name,
+      });
+      console.log(`📌 使用 spec 目录: ${customSpec.rel}`);
+      console.log();
+    } else if (!specPackage && !(skipTemplate && skipOpenspec)) {
+      specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: specInitGit });
+    }
+  }
+
   if (layout.isWorkspace) {
+    // 显示层同步过滤：用户交互选择的 spec 目录可能原被分类为代码仓
+    const displayCodeRepos = specPackage
+      ? layout.codeRepos.filter((c) => path.resolve(c.abs) !== path.resolve(specPackage.abs))
+      : layout.codeRepos;
     console.log('📂 检测到个人工作目录布局（子目录 Git 仓库）');
     console.log(`   Spec: ${specPackage ? specPackage.name : '(未发现，将自动创建包裹包)'}`);
-    console.log(`   代码仓: ${layout.codeRepos.map((c) => c.name).join(', ') || '(无)'}`);
+    console.log(`   代码仓: ${displayCodeRepos.map((c) => c.name).join(', ') || '(无)'}`);
     console.log('   → skills 只部署到本工作目录；SDD 文档统一进 *-sdd-specs 包裹包');
     console.log();
   }
@@ -1681,12 +1880,6 @@ async function main() {
     deployProfileArtifacts(selectedTools, workspaceRoot, getPackagePath());
 
     if (layout.isWorkspace) {
-      if (!specPackage) {
-        console.log('📦 未发现 spec 仓，正在创建统一 SDD 包裹包（独立 Git）...');
-        specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: true });
-        console.log(`   ✓ ${specPackage.created ? '已创建' : '已复用'}: ${specPackage.name}`);
-      }
-
       await populateSpecPackage(specPackage.abs, {
         skipOpenspec,
         asIndependentGit: true,
@@ -1694,10 +1887,17 @@ async function main() {
       writeSddSpecRootHint(workspaceRoot, specPackage.abs);
       removeOuterSkywalk(workspaceRoot);
 
-      // 重新探测，刷新 layout.specRepo / codeRepos
+      // 重新探测，刷新 layout.specRepo / codeRepos。
+      // 用户交互中可能指定了与自动探测不同的 spec 目录（旧目录仍在盘上），
+      // 此时以用户选择为准，避免重探测把旧目录选为 specRepo、把新目录误分类为代码仓。
       layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
-      if (!layout.specRepo) {
-        layout.specRepo = { name: specPackage.name, abs: specPackage.abs };
+      if (specPackage) {
+        if (!layout.specRepo || path.resolve(layout.specRepo.abs) !== path.resolve(specPackage.abs)) {
+          layout.specRepo = { name: specPackage.name, abs: specPackage.abs };
+        }
+        layout.codeRepos = layout.codeRepos.filter(
+          (c) => path.resolve(c.abs) !== path.resolve(specPackage.abs),
+        );
       }
 
       console.log();
@@ -1712,10 +1912,6 @@ async function main() {
       const isGit = workspaceLayout.isGitRepo(workspaceRoot);
 
       if (isGit) {
-        console.log('📦 单仓模式：创建/复用仓内统一 SDD 包裹目录...');
-        specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: false });
-        console.log(`   ✓ ${specPackage.created ? '已创建' : '已复用'}: ${specPackage.name}`);
-
         await populateSpecPackage(specPackage.abs, {
           skipOpenspec,
           asIndependentGit: false,
@@ -1737,8 +1933,7 @@ async function main() {
         }
       } else {
         // 非 Git 目录：仍创建包裹包，便于随后 git init
-        console.log('📦 当前目录不是 Git 仓：仍创建 SDD 包裹包（请稍后 git init）...');
-        specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: false });
+        console.log('📦 当前目录不是 Git 仓：包裹包已就绪（请稍后 git init）...');
         await populateSpecPackage(specPackage.abs, {
           skipOpenspec,
           asIndependentGit: false,
@@ -1750,26 +1945,13 @@ async function main() {
     }
   } else if (!skipOpenspec) {
     // 仅 openspec、跳过模版时：仍尊重包裹包，避免在工作区根平铺
-    if (layout.isWorkspace) {
-      if (!specPackage) {
-        specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: true });
-      }
-      const prev = process.cwd();
-      try {
-        process.chdir(specPackage.abs);
-        await runOpenspecInit([]);
-      } finally {
-        process.chdir(prev);
-      }
-    } else {
-      specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: false });
-      const prev = process.cwd();
-      try {
-        process.chdir(specPackage.abs);
-        await runOpenspecInit([]);
-      } finally {
-        process.chdir(prev);
-      }
+    // specPackage 已在顶部统一 ensureSpecPackage 创建/复用
+    const prev = process.cwd();
+    try {
+      process.chdir(specPackage.abs);
+      await runOpenspecInit([]);
+    } finally {
+      process.chdir(prev);
     }
   }
 
@@ -1912,6 +2094,8 @@ module.exports = {
   syncWorkspaceRepos,
   copyDirRendered,
   parseSelectedTools,
+  promptSpecPath,
+  detectSpecCandidateForPrompt,
   installSddShellHook,
   deployCodeRepoHooks,
   TOOL_CONFIGS,

package/lib/scale-thresholds.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://kld-sdd.dev/schemas/scale-thresholds/v1",
+  "description": "SDD Simple 模式自动规模判定阈值。临界时优先选 Full（保守策略）。",
+  "version": "1.0.0",
+  "simple": {
+    "max_files": 5,
+    "max_lines": 200,
+    "max_modules": 1,
+    "allow_new_table": false,
+    "allow_new_api": false
+  },
+  "fallback": {
+    "max_files": 5,
+    "max_lines": 200,
+    "max_modules": 1,
+    "allow_new_table": false,
+    "allow_new_api": false
+  }
+}

package/lib/skills-bundle.js

@@ -132,7 +132,8 @@ function transformKunlunSlashCommands(content) {
 
   let result = content;
   for (const cmd of KUNLUN_SLASH_COMMANDS) {
-    result = result.replace(new RegExp(`/opsx-${cmd}(?![a-z-])`, 'g'), `/opsx:${cmd}`);
+    // Command syntax changes for Kunlun; skill directory paths remain portable.
+    result = result.replace(new RegExp(`/opsx-${cmd}(?![a-z-/])`, 'g'), `/opsx:${cmd}`);
   }
   return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.7.3",
+  "version": "2.7.8",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,8 @@
     "kld-sdd-init": "bin/kld-sdd-init.js"
   },
   "scripts": {
-    "test": "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/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"
+    "bench:check": "node test/benchmark-check.cjs",
+    "test": "node --test 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"
   },
   "keywords": [
     "kld",
@@ -43,6 +44,7 @@
     "skywalk-sdd/lib/",
     "skywalk-sdd/kb-upload.cjs",
     "skywalk-sdd/kb-sync-identity.cjs",
-    "README.md"
+    "README.md",
+    "USABILITY.md"
   ]
 }

package/skywalk-sdd/context-client.cjs

@@ -12,6 +12,7 @@ const {
   loadKbState,
   resolveKbParams,
   stripBom,
+  httpGetJson,
 } = require('./lib/shared.cjs');
 
 // Re-export requestJson for external callers (API compatibility)
@@ -105,6 +106,7 @@ function buildPayload(args, mode) {
 }
 
 async function retrieveContext(args = parseArgs(process.argv), env = process.env) {
+  if (args.offline) return unavailableContext('engineering_kb_offline', '本次使用本地上下文，未验证远程基线');
   // 优先从共享 state 文件读取配置（与 opsx-ontology-query / opsx-kb-ingest 共用）
   let stateConfig = {};
   const stateFile = args['state-file'] || env.SDD_KB_STATE_FILE;
@@ -131,12 +133,17 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
 
   const { apiBase: kbApiBase, token: kbToken, spaceId: kbSpaceId, kbId: kbKbId, targets: kbTargets } = resolveKbParams(stateConfig, env);
 
+  if (Boolean(args['space-id']) !== Boolean(args['kb-id'])) throw new Error('请同时指定 --space-id 和 --kb-id');
+  const explicitSpace = args['space-id'] || env.ENGINEERING_KB_SPACE_ID;
+  const explicitKb = args['kb-id'] || env.ENGINEERING_KB_KB_ID;
+  if (Boolean(explicitSpace) !== Boolean(explicitKb)) throw new Error('请同时配置目标 spaceId 和 kbId');
+  if (kbTargets.length > 1 && !explicitSpace) throw new Error('配置了多个 KB，请用 --space-id 和 --kb-id 明确本次查询目标');
   const apiBase = args['api-base'] || kbApiBase;
   const token = args.token || kbToken;
-  const spaceId = args['space-id'] || kbSpaceId;
-  const kbId = args['kb-id'] || kbKbId;
+  const spaceId = explicitSpace || kbSpaceId;
+  const kbId = explicitKb || kbKbId;
 
-  // --check-only: 只检查 KB 配置是否就绪，不发起 API 请求
+  // --check-only performs an authenticated check against the selected KB.
   // 用于 SDD 各阶段（propose/spec/design/task/check）统一检测 KB 可用性，消除相对路径歧义
   if (args['check-only']) {
     const missing = [];
@@ -145,31 +152,27 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
     if (!kbId) missing.push('kbId');
     if (missing.length > 0) {
       return {
-        available: false,
-        reason: 'engineering_kb_not_configured',
+        ...unavailableContext('engineering_kb_not_configured', 'KB 尚未配置，本地工作可以继续'),
+        configured: false,
         missing,
-        hint: 'Run /opsx-kb-config to configure kb-state.json (in spec root)',
       };
     }
-    return {
-      available: true,
-      api: apiBase,
-      targets: kbTargets,
-    };
+    const endpoint = `${String(apiBase).replace(/\/+$/, '')}/v1/spaces/${encodeURIComponent(spaceId)}`
+      + `/knowledge-bases/${encodeURIComponent(kbId)}/context/readiness`;
+    const response = await httpGetJson(endpoint, token, contextTimeout(args, env, 3000));
+    if (response?.code != null && response.code !== 0) throw new Error(response.message || 'KB readiness failed');
+    const readiness = response?.data || response;
+    if (readiness?.available !== true || readiness?.authorized !== true) throw new Error('KB 未返回有效的权限与就绪状态');
+    return { ...readiness, configured: true, api: apiBase, spaceId, kbId };
+
   }
 
-  if (!spaceId || !kbId) {
-    return {
-      available: false,
-      advisory: true,
-      degraded: true,
-      reason: 'engineering_kb_not_configured',
-      hint: 'set ENGINEERING_KB_SPACE_ID and ENGINEERING_KB_KB_ID; do not fall back to local archive/',
-    };
+  if (!spaceId || !kbId || !token) {
+    return { ...unavailableContext('engineering_kb_not_configured', 'KB 尚未配置，本地工作可以继续'), configured: false };
   }
 
   const mode = String(args.mode || 'match').trim().toLowerCase() === 'resolve' ? 'resolve' : 'match';
-  const timeoutMs = Number(args.timeout || env.ENGINEERING_KB_TIMEOUT_MS || 30000);
+  const timeoutMs = contextTimeout(args, env, 5000);
   const payload = buildPayload(args, mode);
   const data = await requestJson(
     buildEndpoint(apiBase, spaceId, kbId, mode),
@@ -184,21 +187,38 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
   };
 }
 
+function contextTimeout(args, env, fallback) {
+  const timeout = Number(args.timeout || env.ENGINEERING_KB_TIMEOUT_MS || fallback);
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new Error('timeout 必须是大于 0 的毫秒数');
+  return timeout;
+}
+
+function unavailableContext(reason, message) {
+  return {
+    available: false,
+    advisory: true,
+    degraded: true,
+    localWorkAllowed: true,
+    baselineVerified: false,
+    inheritanceAllowed: false,
+    reason,
+    message,
+    hint: '继续本地编写、检查和测试；保留已有身份与真实基线。发布前重新在线校验，不把历史参考当作 KB current。',
+  };
+}
+
 async function main() {
   const args = parseArgs(process.argv);
+  let result;
   try {
-    console.log(JSON.stringify(await retrieveContext(args), null, 2));
+    result = await retrieveContext(args);
   } catch (error) {
-    console.log(JSON.stringify({
-      available: false,
-      advisory: true,
-      degraded: true,
-      reason: 'engineering_kb_unavailable',
-      message: error.message,
-      hint: 'KB unavailable: continue degraded; never scan local archive/ for inheritance UUIDs',
-    }, null, 2));
-    if (args.strict) process.exitCode = 1;
+    const reason = /\b(401|403|Unauthorized|Forbidden)\b/.test(error.message)
+      ? 'engineering_kb_access_denied' : 'engineering_kb_unavailable';
+    result = unavailableContext(reason, error.message);
   }
+  console.log(JSON.stringify(result, null, 2));
+  if (args.strict && result.available !== true) process.exitCode = 1;
 }
 
 if (require.main === module) {