kld-sdd 2.6.8 → 2.6.10

package/lib/init.js

@@ -687,14 +687,13 @@ function cleanupNativeOpenspecSkills(selectedTools = Object.keys(TOOL_CONFIGS))
 }
 
 /**
- * 复制标准文档模版到项目
+ * 复制标准文档模版到项目（openspec-templates/）
  */
-function copyTemplatesToProject() {
+function copyTemplatesToProject(cwd = process.cwd()) {
   console.log('📄 正在复制标准文档模版到项目...');
   
   const pkgPath = getPackagePath();
   const templatePath = path.join(pkgPath, 'templates', 'openspec');
-  const cwd = process.cwd();
   const targetDir = path.join(cwd, 'openspec-templates');
   
   if (!fs.existsSync(templatePath)) {
@@ -702,12 +701,10 @@ function copyTemplatesToProject() {
     return false;
   }
   
-  // 创建目标目录
   if (!fs.existsSync(targetDir)) {
     fs.mkdirSync(targetDir, { recursive: true });
   }
   
-  // 复制模版文件
   copyDir(templatePath, targetDir);
   
   console.log(`✅ 标准文档模版已复制到: ${targetDir}`);
@@ -724,29 +721,24 @@ function copyTemplatesToProject() {
  * 初始化全局 overview.md 到 openspec/specs/ 目录
  * overview.md 是全局架构约束，所有 Capability 的设计都必须遵守
  */
-function initGlobalOverview() {
+function initGlobalOverview(cwd = process.cwd()) {
   console.log('🌐 正在初始化全局架构约束 (overview.md)...');
   
   const pkgPath = getPackagePath();
   const overviewSource = path.join(pkgPath, 'templates', 'openspec', 'overview.md');
-  const cwd = process.cwd();
   const targetDir = path.join(cwd, 'openspec', 'specs');
   const targetFile = path.join(targetDir, 'overview.md');
   
-  // 检查源文件是否存在
   if (!fs.existsSync(overviewSource)) {
     console.log(`⚠️  overview.md 源文件不存在: ${overviewSource}`);
     return false;
   }
   
-  // 创建目标目录
   if (!fs.existsSync(targetDir)) {
     fs.mkdirSync(targetDir, { recursive: true });
   }
   
-  // 检查目标文件是否已存在
   if (fs.existsSync(targetFile)) {
-    // 读取现有文件，检查是否需要更新
     const existingContent = fs.readFileSync(targetFile, 'utf-8');
     const newContent = fs.readFileSync(overviewSource, 'utf-8');
     
@@ -755,13 +747,11 @@ function initGlobalOverview() {
       return true;
     }
     
-    // 备份现有文件
     const backupFile = path.join(targetDir, 'overview.md.backup');
     fs.copyFileSync(targetFile, backupFile);
     console.log(`   ℹ️  已备份现有 overview.md 到 ${backupFile}`);
   }
   
-  // 复制 overview.md
   fs.copyFileSync(overviewSource, targetFile);
   
   console.log(`✅ 全局架构约束已初始化: ${targetFile}`);
@@ -857,7 +847,15 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
     console.log('   ✓ 部署 skywalk-sdd/apply-worktree-finish.cjs（Apply 收尾脚本）');
   }
 
+  const openspecShimSrc = path.join(pkgPath, 'skywalk-sdd', 'openspec-shim.cjs');
+  const openspecShimDst = path.join(dataDir, 'openspec-shim.cjs');
+  if (fs.existsSync(openspecShimSrc)) {
+    fs.copyFileSync(openspecShimSrc, openspecShimDst);
+    console.log('   ✓ 部署 skywalk-sdd/openspec-shim.cjs（openspec 包裹包路径 shim）');
+  }
+
   console.log('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics|semantic-identity|semantic-reconcile|semantic-check');
+  console.log('   ✓ openspec: node skywalk-sdd/openspec-shim.cjs list（自动 cd 到 *-sdd-specs）');
   console.log('   ✓ Spec Context: node skywalk-sdd/context-client.cjs --query="<自然语言需求>" --target-stage=spec');
   console.log('   ✓ Apply worktree: record-base 在 §1.5；收尾 apply-worktree-finish.cjs --change=<name>');
   console.log('✅ Telemetry 已就绪（数据存储在 skywalk-sdd/，无需配置 MCP）');
@@ -1065,32 +1063,98 @@ function deployDotSddYaml(cwd = process.cwd(), pkgPath = getPackagePath()) {
 }
 
 /**
- * 单仓（openspec 与代码同仓）声明 layout: mono。
+ * 单仓声明 layout: mono，并记录仓内统一包裹目录相对路径。
  * commit-msg Hook 靠它跳过「spec 工作区干净」检查并只写 Spec-Change。
  */
-function deployMonoSddYaml(cwd = process.cwd()) {
+function deployMonoSddYaml(cwd = process.cwd(), options = {}) {
   const target = path.join(cwd, '.sdd.yaml');
+  const specRel = options.specPathRelative
+    ? String(options.specPathRelative).replace(/\\/g, '/')
+    : '';
+
   if (fs.existsSync(target)) {
     const existing = fs.readFileSync(target, 'utf8');
     if (/^layout:\s*mono\s*$/m.test(existing)) {
+      if (specRel && !new RegExp(`^spec_path:\\s*${specRel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(existing)) {
+        // 已有 mono 但缺/错 spec_path：补写相对路径
+        let next = existing.replace(/\s*$/, '');
+        if (/^spec_path:\s*.+$/m.test(next)) {
+          next = next.replace(/^spec_path:\s*.+$/m, `spec_path: ${specRel}`);
+        } else {
+          next = `${next}\nspec_path: ${specRel}`;
+        }
+        fs.writeFileSync(target, `${next}\n`, 'utf8');
+        console.log(`   ✓ 已更新 .sdd.yaml spec_path → ${specRel}`);
+        return true;
+      }
       console.log('   ✓ .sdd.yaml 已声明 layout: mono，跳过');
       return true;
     }
-    console.log('⚠️  .sdd.yaml 已存在但未声明 layout: mono；单仓请手动补一行 `layout: mono`');
+    console.log('⚠️  .sdd.yaml 已存在但未声明 layout: mono；单仓请手动补 `layout: mono`');
     return false;
   }
   const lines = [
-    '# 单仓布局：openspec 文档与代码在同一个仓库',
-    '# commit-msg 只写 Spec-Change（spec 与代码同属一次 commit，无需 Spec-Revision 指针）',
+    '# 单仓布局：业务代码与 SDD 包裹包在同一个 Git 仓库',
+    '# SDD 内容统一在 spec_path 目录内（openspec / modules / sdd.config / 模版）',
+    '# commit-msg 只写 Spec-Change（同仓一次 commit，无需 Spec-Revision 指针）',
     'version: 1',
     'layout: mono',
-    '',
   ];
+  if (specRel) lines.push(`spec_path: ${specRel}`);
+  lines.push('');
   fs.writeFileSync(target, lines.join('\n'), 'utf8');
-  console.log(`✅ 已创建 .sdd.yaml（layout: mono）: ${target}`);
+  console.log(`✅ 已创建 .sdd.yaml（layout: mono${specRel ? `, spec_path: ${specRel}` : ''}）: ${target}`);
   return true;
 }
 
+/**
+ * 向统一 SDD 包裹目录写入完整内容（多仓兄弟仓 / 单仓内部子目录共用）。
+ * 不在此部署编辑器 skills——skills 只装工作目录或单仓 Git 根。
+ */
+async function populateSpecPackage(specRoot, options = {}) {
+  const root = path.resolve(specRoot);
+  const skipOpenspec = Boolean(options.skipOpenspec);
+  const asIndependentGit = Boolean(options.asIndependentGit);
+  console.log(`📦 正在填充 SDD 包裹包: ${root}`);
+
+  if (!skipOpenspec) {
+    const prev = process.cwd();
+    try {
+      process.chdir(root);
+      // 包裹包内只建 openspec 目录结构，不把编辑器配置写进文档仓
+      await runOpenspecInit([]);
+    } finally {
+      process.chdir(prev);
+    }
+  }
+
+  deployTelemetryDataDir(root);
+  if (asIndependentGit || workspaceLayout.isGitRepo(root)) {
+    deployQualityGateTemplates(root, { mode: 'full' });
+  }
+  deployModulesYaml(root);
+  deploySddConfigYaml(root);
+  copyTemplatesToProject(root);
+  initGlobalOverview(root);
+  deploySddGuideManual(root);
+  console.log(`✅ SDD 包裹包已就绪: ${path.basename(root)}`);
+  return { ok: true, path: root };
+}
+
+/**
+ * 在工作区 / Git 根写入 .sdd-spec-root，供 shell 与 skills 引用相对包裹包路径。
+ */
+function writeSddSpecRootHint(anchorDir, specPackageAbs) {
+  const anchor = path.resolve(anchorDir);
+  const specAbs = path.resolve(specPackageAbs);
+  const rel = path.relative(anchor, specAbs).replace(/\\/g, '/');
+  if (!rel || rel.startsWith('..')) return null;
+  const filePath = path.join(anchor, '.sdd-spec-root');
+  fs.writeFileSync(filePath, `${rel}\n`, 'utf8');
+  console.log(`   ✓ 已写入 .sdd-spec-root → ${rel}`);
+  return filePath;
+}
+
 /**
  * 检测当前项目已初始化的 AI 编辑器
  */
@@ -1274,32 +1338,21 @@ async function main() {
   }
 
   const workspaceRoot = process.cwd();
-  const layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
+  let layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
+  let specPackage = layout.specRepo
+    ? { name: layout.specRepo.name, abs: layout.specRepo.abs, created: false, isGit: true }
+    : null;
+
   if (layout.isWorkspace) {
     console.log('📂 检测到个人工作目录布局（子目录 Git 仓库）');
-    console.log(`   Spec: ${layout.specRepo ? layout.specRepo.name : '(未发现)'}`);
+    console.log(`   Spec: ${specPackage ? specPackage.name : '(未发现，将自动创建包裹包)'}`);
     console.log(`   代码仓: ${layout.codeRepos.map((c) => c.name).join(', ') || '(无)'}`);
-    console.log('   → skills 只部署到本工作目录；代码仓仅轻量接入 Hook/关联');
+    console.log('   → skills 只部署到本工作目录；SDD 文档统一进 *-sdd-specs 包裹包');
     console.log();
   }
 
-  // 1. openspec init：工作区模式下若有 spec 仓则在其内执行
-  if (!skipOpenspec) {
-    if (layout.isWorkspace && layout.specRepo) {
-      const prev = process.cwd();
-      try {
-        process.chdir(layout.specRepo.abs);
-        await runOpenspecInit(selectedTools);
-      } finally {
-        process.chdir(prev);
-      }
-    } else {
-      await runOpenspecInit(selectedTools);
-    }
-  }
-
   if (!skipTemplate) {
-    // 2/3. skills 与编辑器产物：永远只装在当前工作目录一次
+    // skills / 编辑器产物：永远只装在当前工作目录一次
     cleanupNativeOpenspecCommands(selectedTools);
     cleanupLegacyBundledOpsxSkills(selectedTools);
     deployOpsxSkills(selectedTools);
@@ -1307,49 +1360,93 @@ async function main() {
     deployProfileArtifacts(selectedTools, workspaceRoot, getPackagePath());
 
     if (layout.isWorkspace) {
-      // 工作目录本身保留一份 telemetry，供 skills 调用
       deployTelemetryDataDir(workspaceRoot);
 
-      if (layout.specRepo) {
-        const prev = process.cwd();
-        try {
-          process.chdir(layout.specRepo.abs);
-          deployTelemetryDataDir(layout.specRepo.abs);
-          deployQualityGateTemplates(layout.specRepo.abs, { mode: 'full' });
-          deployModulesYaml(layout.specRepo.abs);
-          deploySddConfigYaml(layout.specRepo.abs);
-          copyTemplatesToProject();
-          initGlobalOverview();
-          deploySddGuideManual(layout.specRepo.abs);
-        } finally {
-          process.chdir(prev);
-        }
+      if (!specPackage) {
+        console.log('📦 未发现 spec 仓，正在创建统一 SDD 包裹包（独立 Git）...');
+        specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: true });
+        console.log(`   ✓ ${specPackage.created ? '已创建' : '已复用'}: ${specPackage.name}`);
+      }
 
-        console.log();
-        console.log('🔗 正在为子代码仓做轻量接入（不安装 skills）...');
-        for (const repo of layout.codeRepos) {
-          attachCodeRepoLite(repo.abs, layout.specRepo.abs);
-        }
-        const wsFile = workspaceLayout.writeWorkspaceFile(workspaceRoot, layout);
-        console.log(`✅ 工作区清单: ${wsFile}`);
-      } else {
-        console.log('⚠️  未发现 spec 仓，已跳过代码仓 Hook 接入。请先准备 *-sdd-specs 子目录后执行: kld-sdd sync-repos');
+      await populateSpecPackage(specPackage.abs, {
+        skipOpenspec,
+        asIndependentGit: true,
+      });
+      writeSddSpecRootHint(workspaceRoot, specPackage.abs);
+
+      // 重新探测，刷新 layout.specRepo / codeRepos
+      layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
+      if (!layout.specRepo) {
+        layout.specRepo = { name: specPackage.name, abs: specPackage.abs };
+      }
+
+      console.log();
+      console.log('🔗 正在为子代码仓做轻量接入（不安装 skills）...');
+      for (const repo of layout.codeRepos) {
+        attachCodeRepoLite(repo.abs, specPackage.abs);
       }
+      const wsFile = workspaceLayout.writeWorkspaceFile(workspaceRoot, layout);
+      console.log(`✅ 工作区清单: ${wsFile}`);
     } else {
-      // 单仓模式（旧行为）：当前目录既是项目根
+      // 单仓：Git 根只放代码 + skills + Hook；SDD 内容进统一包裹子目录
+      const isGit = workspaceLayout.isGitRepo(workspaceRoot);
       deployTelemetryDataDir(workspaceRoot);
-      deployQualityGateTemplates(workspaceRoot, { mode: 'full' });
-      deployModulesYaml(workspaceRoot);
-      deploySddConfigYaml(workspaceRoot);
-      if (workspaceLayout.isGitRepo(workspaceRoot)) {
-        // openspec 与代码同仓：显式声明单仓，Hook 才会写 Spec-Change
-        deployMonoSddYaml(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,
+        });
+        writeSddSpecRootHint(workspaceRoot, specPackage.abs);
+
+        deployMonoSddYaml(workspaceRoot, { specPathRelative: specPackage.name });
+        // Hook 装在 Git 根；Trailer 读包裹目录里的 sdd.config / openspec
+        deployQualityGateTemplates(workspaceRoot, { mode: 'commit-msg-only' });
+        const linked = sddConfig.setSpecPath(workspaceRoot, specPackage.abs, {
+          allowNestedPackage: true,
+        });
+        if (linked.ok) {
+          console.log(`   ✓ sdd.specPath = ${linked.path}`);
+        } else {
+          console.log(`   ⚠️  未能写入 sdd.specPath: ${linked.message}`);
+        }
       } else {
+        // 非 Git 目录：仍创建包裹包，便于随后 git init
+        console.log('📦 当前目录不是 Git 仓：仍创建 SDD 包裹包（请稍后 git init）...');
+        specPackage = workspaceLayout.ensureSpecPackage(workspaceRoot, { initGit: false });
+        await populateSpecPackage(specPackage.abs, {
+          skipOpenspec,
+          asIndependentGit: false,
+        });
         deployDotSddYaml(workspaceRoot);
       }
-      copyTemplatesToProject();
-      initGlobalOverview();
-      deploySddGuideManual(workspaceRoot);
+    }
+  } 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);
+      }
     }
   }
 
@@ -1369,8 +1466,9 @@ async function main() {
     console.log('工作区部署结果:');
     console.log('  🎯 工作目录 .*/skills/opsx-*/     # skills 只装这一份');
     console.log('  📋 .sdd-workspace.yaml           # 子仓编排清单');
-    if (layout.specRepo) {
-      console.log(`  📄 ${layout.specRepo.name}/modules.yaml + openspec-templates`);
+    if (specPackage) {
+      console.log(`  📄 ${specPackage.name}/              # 统一 SDD 包裹包（独立 Git）`);
+      console.log('       modules.yaml / sdd.config.yaml / openspec / openspec-templates / skywalk-sdd');
     }
     for (const repo of layout.codeRepos) {
       console.log(`  🔗 ${repo.name}/  ← commit-msg Hook + .sdd.yaml（无 skills）`);
@@ -1380,12 +1478,13 @@ async function main() {
     console.log('  kld-sdd sync-repos');
     console.log('Trailer 仍在各代码仓 git commit 时由 Hook 写入。');
   } else {
-    console.log('已生成/覆盖:');
-    console.log('  🌐 openspec/specs/overview.md     # 全局架构约束（数据字典、接口规范）');
-    console.log('  📖 openspec/kld-sdd操作手册.html   # SDD 操作手册（HTML）');
-    console.log('  📄 openspec-templates/           # 标准文档模版（参考用）');
-    console.log('  📦 modules.yaml / .sdd.yaml      # 多仓库命名与关联配置');
-    console.log('  🎯 .*/skills/opsx-*/              # SDD skills（扁平一层）');
+    console.log('单仓部署结果:');
+    console.log('  🎯 .*/skills/opsx-*/              # SDD skills（装在 Git 根）');
+    if (specPackage) {
+      console.log(`  📄 ${specPackage.name}/              # 统一 SDD 包裹包（仓内子目录）`);
+      console.log('       modules.yaml / sdd.config.yaml / openspec / openspec-templates / skywalk-sdd');
+    }
+    console.log('  🔗 .sdd.yaml (layout: mono) + commit-msg Hook');
   }
   if (selectedTools.includes('kunlunzhima')) {
     console.log('  📎 .kunlunzhima/commands/opsx/    # KunlunZhima OPSX command bridge（11 个）');
@@ -1398,9 +1497,8 @@ async function main() {
     console.log('  🪝 .claude/hooks/                 # Claude Code SDD Hook Pack（可选增强）');
   }
   if (!layout.isWorkspace) {
-    console.log('  📊 skywalk-sdd/                  # SDD Telemetry 数据目录');
-    console.log('  🧰 skywalk-sdd/git-hooks/        # Git hooks 质量门禁模板');
-    console.log('  🧪 skywalk-sdd/ci/               # CI 兜底采集模板');
+    console.log('  📊 skywalk-sdd/                  # Hook 运行时 ontology（Git 根）');
+    console.log('  🧰 skywalk-sdd/git-hooks/        # commit-msg Trailer Hook');
   }
   console.log();
   
@@ -1420,8 +1518,10 @@ async function main() {
     
   console.log();
   console.log('后续步骤:');
-  if (layout.isWorkspace && layout.specRepo) {
-    console.log(`  0. 文档类命令请以 spec 仓为 --project（例: --project=${layout.specRepo.name}）`);
+  if (layout.isWorkspace && specPackage) {
+    console.log(`  0. 文档类命令请以包裹包为 --project（例: --project=${specPackage.name}）`);
+  } else if (specPackage) {
+    console.log(`  0. 文档类命令请以包裹包为 --project（例: --project=${specPackage.name}）`);
   }
   console.log('  1. 激活 opsx-propose skill，输入变更名称开始创建文档');
   console.log('  2. 按顺序执行 propose → spec → design → task');
@@ -1438,8 +1538,12 @@ async function main() {
   }
   console.log();
   console.log('📊 SDD Telemetry（嵌入在 skill 流程中，自动执行，无需配置）：');
-  console.log('  - 度量数据自动采集到 skywalk-sdd/events/');
-  console.log('  - 运行 node skywalk-sdd/log.cjs metrics --project=. 查看四维度指标');
+  if (specPackage) {
+    console.log(`  - 文档侧度量在 ${specPackage.name}/skywalk-sdd/events/`);
+  } else {
+    console.log('  - 度量数据自动采集到 skywalk-sdd/events/');
+  }
+  console.log('  - 运行 node skywalk-sdd/log.cjs metrics --project=<包裹包> 查看四维度指标');
   console.log();
 
   rl.close();
@@ -1458,6 +1562,8 @@ module.exports = {
   deploySddConfigYaml,
   deployDotSddYaml,
   deployMonoSddYaml,
+  populateSpecPackage,
+  writeSddSpecRootHint,
   deployQualityGateTemplates,
   deployTelemetryDataDir,
   attachCodeRepoLite,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.6.8",
+  "version": "2.6.10",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
     "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/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/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"
+    "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/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"
   },
   "keywords": [
     "kld",

package/skywalk-sdd/context-client.cjs

@@ -5,6 +5,7 @@ const fs = require('fs');
 const http = require('http');
 const https = require('https');
 const { URL } = require('url');
+const path = require('path');
 
 function parseArgs(argv) {
   const args = {};
@@ -71,10 +72,16 @@ function requestJson(url, payload, token, timeoutMs) {
             reject(new Error(`knowledge base returned invalid JSON (HTTP ${response.statusCode})`));
             return;
           }
-          if (response.statusCode >= 400 || parsed?.code !== 0) {
+          if (response.statusCode >= 400) {
             reject(new Error(parsed?.message || `knowledge base HTTP ${response.statusCode}`));
             return;
           }
+          // code 字段仅当存在且不为 0 时才视为业务错误（health/ingest 等管理 API 返回 code，
+          // 但 resolve/search 等 context API 直接返回 data，不包含 code 字段）
+          if (parsed?.code != null && parsed.code !== 0) {
+            reject(new Error(parsed?.message || `knowledge base error code ${parsed.code}`));
+            return;
+          }
           resolve(parsed.data);
         });
       },
@@ -149,8 +156,57 @@ function buildPayload(args, mode) {
 }
 
 async function retrieveContext(args = parseArgs(process.argv), env = process.env) {
-  const spaceId = args['space-id'] || env.ENGINEERING_KB_SPACE_ID || '';
-  const kbId = args['kb-id'] || env.ENGINEERING_KB_KB_ID || '';
+  // 优先从共享 state 文件读取配置（与 opsx-ontology-query / opsx-kb-ingest 共用）
+  // 搜索多个可能的 IDE skills 目录（.codebuddy / .claude / .cursor 等）
+  let stateConfig = {};
+  const stateFile = args['state-file'] || env.SDD_KB_STATE_FILE;
+  const candidatePaths = [];
+  if (stateFile) candidatePaths.push(stateFile);
+  // 从 skywalk-sdd 目录向上查找 skills/.shared/kb-state.json
+  const ideDirs = ['.codebuddy', '.claude', '.cursor', '.vscode'];
+  for (const ide of ideDirs) {
+    candidatePaths.push(path.join(__dirname, '..', ide, 'skills', '.shared', 'kb-state.json'));
+  }
+  // 也检查 skywalk-sdd 同级的 .shared
+  candidatePaths.push(path.join(__dirname, '.shared', 'kb-state.json'));
+  for (const p of candidatePaths) {
+    try {
+      if (fs.existsSync(p)) {
+        stateConfig = JSON.parse(fs.readFileSync(p, 'utf8'));
+        break;
+      }
+    } catch (_) { /* try next */ }
+  }
+
+  const apiBase = args['api-base'] || stateConfig.api || env.ENGINEERING_KB_API || 'http://localhost:8090/api';
+  const token = args.token || stateConfig.apiKey || env.ENGINEERING_KB_TOKEN || '';
+  const spaceId = args['space-id'] || env.ENGINEERING_KB_SPACE_ID ||
+    (stateConfig.targets && stateConfig.targets.length > 0 ? stateConfig.targets[0].spaceId : '');
+  const kbId = args['kb-id'] || env.ENGINEERING_KB_KB_ID ||
+    (stateConfig.targets && stateConfig.targets.length > 0 ? stateConfig.targets[0].kbId : '');
+
+  // --check-only: 只检查 KB 配置是否就绪，不发起 API 请求
+  // 用于 SDD 各阶段（propose/spec/design/task/check）统一检测 KB 可用性，消除相对路径歧义
+  if (args['check-only']) {
+    const missing = [];
+    if (!token) missing.push('apiKey');
+    if (!spaceId) missing.push('spaceId');
+    if (!kbId) missing.push('kbId');
+    if (missing.length > 0) {
+      return {
+        available: false,
+        reason: 'engineering_kb_not_configured',
+        missing,
+        hint: 'Run opsx-ontology-query Session startup to configure .shared/kb-state.json',
+      };
+    }
+    return {
+      available: true,
+      api: apiBase,
+      targets: stateConfig.targets || [],
+    };
+  }
+
   if (!spaceId || !kbId) {
     return {
       available: false,
@@ -162,8 +218,6 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
   }
 
   const mode = String(args.mode || 'match').trim().toLowerCase() === 'resolve' ? 'resolve' : 'match';
-  const apiBase = args['api-base'] || env.ENGINEERING_KB_API || 'http://localhost:8090/api';
-  const token = args.token || env.ENGINEERING_KB_TOKEN || '';
   const timeoutMs = Number(args.timeout || env.ENGINEERING_KB_TIMEOUT_MS || 30000);
   const payload = buildPayload(args, mode);
   const data = await requestJson(

package/skywalk-sdd/index.cjs

@@ -13,6 +13,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { resolveProjectArg } = require('./ontology/resolve-spec-root.cjs');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 
@@ -73,11 +74,11 @@ function nowISO() {
 }
 
 function normalizeProjectRoot(projectRoot) {
-  const rawProjectRoot = projectRoot || process.cwd();
+  const rawProjectRoot = projectRoot || '.';
   if (process.platform === 'win32' && /^[a-zA-Z]:[^\\/]/.test(String(rawProjectRoot))) {
     fail(`Windows 项目路径格式不安全: ${rawProjectRoot}。请使用 --project=.，或使用正斜杠路径如 D:/project/demo，或给路径加引号。`);
   }
-  return path.resolve(rawProjectRoot);
+  return resolveProjectArg(rawProjectRoot, process.cwd());
 }
 
 function inferAgentType(args) {