kld-sdd 2.6.7 → 2.6.9

package/bin/kld-sdd-init.js

@@ -3,17 +3,53 @@
 /**
  * KLD SDD 项目初始化工具
  * 一键配置团队标准化开发环境，内置 openSpec 模版
- * 
+ *
  * 子命令:
- *   (无参数)  运行项目初始化
- *   log       SDD Telemetry CLI（记录阶段事件、查询指标）
+ *   (无参数)     运行项目初始化
+ *   log          SDD Telemetry CLI（记录阶段事件、查询指标）
+ *   link-spec    将代码仓关联到本地 spec clone（git config sdd.specPath）
+ *   sync-repos   工作目录下发现新增代码仓并轻量接入（不装 skills）
  */
 
+const path = require('path');
 const args = process.argv.slice(2);
 
 if (args[0] === 'log') {
   // Telemetry CLI 模式
   require('../skywalk-sdd/index.js').main();
+} else if (args[0] === 'link-spec') {
+  const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
+  const pathArg = args.find((item) => item.startsWith('--path='));
+  const projectArg = args.find((item) => item.startsWith('--project='));
+  const positional = args.slice(1).find((item) => !item.startsWith('--'));
+  const specPath = pathArg ? pathArg.slice('--path='.length) : positional;
+  const projectRoot = path.resolve(projectArg ? projectArg.slice('--project='.length) : '.');
+  if (!specPath) {
+    console.error('用法: kld-sdd link-spec --path=<spec-clone> [--project=.]');
+    process.exit(1);
+  }
+  const result = sddConfig.setSpecPath(projectRoot, specPath);
+  if (!result.ok) {
+    console.error(`❌ ${result.message}`);
+    process.exit(1);
+  }
+  console.log(`✅ 已设置 git config --local sdd.specPath = ${result.path}`);
+} else if (args[0] === 'sync-repos') {
+  const { syncWorkspaceRepos } = require('../lib/init');
+  const projectArg = args.find((item) => item.startsWith('--project='));
+  const workspaceRoot = path.resolve(projectArg ? projectArg.slice('--project='.length) : '.');
+  const all = args.includes('--all');
+  const result = syncWorkspaceRepos(workspaceRoot, { onlyNew: !all });
+  if (!result.ok && result.attached.length === 0 && (!result.layout || !result.layout.specRepo)) {
+    process.exit(1);
+  }
+  if (result.failed && result.failed.length) {
+    for (const item of result.failed) {
+      console.error(`❌ ${item.repo}: ${item.message}`);
+    }
+    process.exit(1);
+  }
+  console.log(`✅ sync-repos 完成，接入 ${result.attached.length} 个代码仓`);
 } else {
   // 正常初始化模式
   const { main } = require('../lib/init');

package/lib/init.js

@@ -28,6 +28,8 @@ const {
   BRIDGE_MARKER,
 } = require('./command-bridge');
 const { deployCodebuddyHookPack } = require('./deploy-codebuddy-hooks');
+const workspaceLayout = require('./workspace-layout');
+const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
 
 const rl = readline.createInterface({
   input: process.stdin,
@@ -797,11 +799,11 @@ function deploySddGuideManual(cwd = process.cwd(), pkgPath = getPackagePath()) {
  * 部署 SDD Telemetry 数据目录
  * 创建本地数据目录用于存储事件和活跃状态（最终报告落 openspec/changes/<change>/reports/，不再写 skywalk-sdd/reports/）
  */
-function deployTelemetryDataDir() {
+function deployTelemetryDataDir(targetCwd = process.cwd()) {
   console.log('📊 正在初始化 SDD Telemetry 数据目录...');
 
   const pkgPath = getPackagePath();
-  const cwd = process.cwd();
+  const cwd = path.resolve(targetCwd);
   const dataDir = path.join(cwd, 'skywalk-sdd');
 
   if (!fs.existsSync(dataDir)) {
@@ -901,16 +903,22 @@ function installGitHookShim(cwd, hookName, scriptPath) {
 /**
  * 部署 Git hooks / CI 兜底模板
  * 这些脚本只做质量门禁和 CI 补充记录，不替代 OPSX 主采集链路。
+ *
+ * @param {string} [targetCwd]
+ * @param {{ mode?: 'full'|'commit-msg-only' }} [options]
+ *   full: spec 仓（pre-commit/pre-push/commit-msg + CI）
+ *   commit-msg-only: 代码仓（只装 Trailer Hook，不装 skills、不装文档门禁）
  */
-function deployQualityGateTemplates() {
+function deployQualityGateTemplates(targetCwd = process.cwd(), options = {}) {
   const pkgPath = getPackagePath();
-  const cwd = process.cwd();
+  const cwd = path.resolve(targetCwd);
+  const mode = options.mode || 'full';
   // U4: 非 Git 项目跳过 Git hooks / CI 兜底模板（按需部署，不污染非 Git 项目根）
   if (!fs.existsSync(path.join(cwd, '.git'))) {
     console.log('🧰 非 Git 项目，跳过 Git hooks / CI 兜底模板部署');
     return false;
   }
-  console.log('🧰 正在部署 SDD Git hooks / CI 兜底模板...');
+  console.log(`🧰 正在部署 SDD Git hooks（${mode}）: ${cwd}`);
   const dataDir = path.join(cwd, 'skywalk-sdd');
   const gitHooksTemplateDir = path.join(pkgPath, 'templates', 'git-hooks');
   const ciTemplateDir = path.join(pkgPath, 'templates', 'ci');
@@ -924,17 +932,162 @@ function deployQualityGateTemplates() {
     console.log(`   ⚠️  Git hooks 模板缺失: ${gitHooksTemplateDir}`);
   }
 
-  if (fs.existsSync(ciTemplateDir)) {
+  if (mode === 'full' && fs.existsSync(ciTemplateDir)) {
     copyDir(ciTemplateDir, targetCiDir);
     console.log('   ✓ 部署 skywalk-sdd/ci/');
+  }
+
+  if (mode === 'full') {
+    installGitHookShim(cwd, 'pre-commit', 'skywalk-sdd/git-hooks/pre-commit-sdd-check.cjs');
+    installGitHookShim(cwd, 'pre-push', 'skywalk-sdd/git-hooks/pre-push-sdd-check.cjs');
+  }
+  installGitHookShim(cwd, 'commit-msg', 'skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs');
+
+  console.log('✅ Git hooks 已就绪');
+  return true;
+}
+
+/**
+ * 代码仓轻量接入：只部署 Hook 运行所需 ontology + commit-msg，不部署 skills。
+ */
+function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
+  const cwd = path.resolve(codeRepoRoot);
+  const specRoot = path.resolve(specRepoRoot);
+  const pkgPath = options.pkgPath || getPackagePath();
+  const label = path.basename(cwd);
+
+  if (!workspaceLayout.isGitRepo(cwd)) {
+    return { ok: false, repo: label, message: '不是 Git 仓库' };
+  }
+  if (!workspaceLayout.isGitRepo(specRoot)) {
+    return { ok: false, repo: label, message: `spec 路径不是 Git 仓库: ${specRoot}` };
+  }
+
+  console.log(`🔗 轻量接入代码仓（无 skills）: ${label}`);
+
+  // Hook 依赖 ontology + git-hooks；不部署完整 telemetry/skills
+  const dataDir = path.join(cwd, 'skywalk-sdd');
+  const ontologySrc = path.join(pkgPath, 'skywalk-sdd', 'ontology');
+  const ontologyDst = path.join(dataDir, 'ontology');
+  if (fs.existsSync(ontologySrc)) {
+    copyDir(ontologySrc, ontologyDst);
+  }
+  deployQualityGateTemplates(cwd, { mode: 'commit-msg-only' });
+
+  const remote = sddConfig.gitRemoteUrl(specRoot) || 'git@gitlab.example.com:biz/xxx-sdd-specs.git';
+  const sddYamlPath = path.join(cwd, '.sdd.yaml');
+  if (!fs.existsSync(sddYamlPath)) {
+    fs.writeFileSync(
+      sddYamlPath,
+      [
+        '# 代码仓库关联团队 spec Git 仓库（个人绝对路径勿写入本文件）',
+        'version: 1',
+        `spec_repository: ${remote}`,
+        '',
+      ].join('\n'),
+      'utf8',
+    );
+    console.log(`   ✓ 写入 .sdd.yaml → ${remote}`);
   } else {
-    console.log(`   ⚠️  CI 模板缺失: ${ciTemplateDir}`);
+    console.log('   ✓ .sdd.yaml 已存在，跳过覆盖');
+  }
+
+  const linked = sddConfig.setSpecPath(cwd, specRoot);
+  if (!linked.ok) {
+    return { ok: false, repo: label, message: linked.message };
   }
+  console.log(`   ✓ sdd.specPath = ${linked.path}`);
 
-  installGitHookShim(cwd, 'pre-commit', 'skywalk-sdd/git-hooks/pre-commit-sdd-check.cjs');
-  installGitHookShim(cwd, 'pre-push', 'skywalk-sdd/git-hooks/pre-push-sdd-check.cjs');
+  return { ok: true, repo: label, path: cwd, specPath: linked.path };
+}
 
-  console.log('✅ Git hooks / CI 兜底模板已就绪');
+/**
+ * 部署 modules.yaml 到 spec 仓库根目录（若不存在）
+ */
+function deployModulesYaml(cwd = process.cwd(), pkgPath = getPackagePath()) {
+  console.log('📦 正在检查 modules.yaml...');
+  const source = path.join(pkgPath, 'templates', 'modules.yaml');
+  const target = path.join(cwd, 'modules.yaml');
+  if (!fs.existsSync(source)) {
+    console.log(`⚠️  modules.yaml 模板缺失: ${source}`);
+    return false;
+  }
+  if (fs.existsSync(target)) {
+    console.log('   ✓ modules.yaml 已存在，跳过');
+    return true;
+  }
+  fs.copyFileSync(source, target);
+  console.log(`✅ 已创建 modules.yaml: ${target}`);
+  return true;
+}
+
+/**
+ * 部署 sdd.config.yaml（活动变更登记表）到 spec 仓库根目录（若不存在）
+ * propose 隐式写入、archive 隐式移除；代码仓 AI 与 commit-msg Hook 读取
+ */
+function deploySddConfigYaml(cwd = process.cwd(), pkgPath = getPackagePath()) {
+  console.log('📦 正在检查 sdd.config.yaml...');
+  const source = path.join(pkgPath, 'templates', 'sdd.config.yaml');
+  const target = path.join(cwd, 'sdd.config.yaml');
+  if (!fs.existsSync(source)) {
+    console.log(`⚠️  sdd.config.yaml 模板缺失: ${source}`);
+    return false;
+  }
+  if (fs.existsSync(target)) {
+    console.log('   ✓ sdd.config.yaml 已存在，跳过');
+    return true;
+  }
+  fs.copyFileSync(source, target);
+  console.log(`✅ 已创建 sdd.config.yaml: ${target}`);
+  return true;
+}
+
+/**
+ * 部署 .sdd.yaml 示例到代码仓库（若不存在且不像 spec 仓）
+ * spec 仓特征：存在 openspec/changes 或 modules.yaml
+ */
+function deployDotSddYaml(cwd = process.cwd(), pkgPath = getPackagePath()) {
+  const hasSpecLayout =
+    fs.existsSync(path.join(cwd, 'openspec', 'changes')) ||
+    fs.existsSync(path.join(cwd, 'modules.yaml'));
+  if (hasSpecLayout) {
+    return false;
+  }
+  const source = path.join(pkgPath, 'templates', 'dot-sdd.yaml');
+  const target = path.join(cwd, '.sdd.yaml');
+  if (!fs.existsSync(source) || fs.existsSync(target)) {
+    return false;
+  }
+  console.log('🔗 检测到代码仓库布局，部署 .sdd.yaml 示例...');
+  fs.copyFileSync(source, target);
+  console.log(`✅ 已创建 .sdd.yaml（请修改 spec_repository）: ${target}`);
+  return true;
+}
+
+/**
+ * 单仓（openspec 与代码同仓）声明 layout: mono。
+ * commit-msg Hook 靠它跳过「spec 工作区干净」检查并只写 Spec-Change。
+ */
+function deployMonoSddYaml(cwd = process.cwd()) {
+  const target = path.join(cwd, '.sdd.yaml');
+  if (fs.existsSync(target)) {
+    const existing = fs.readFileSync(target, 'utf8');
+    if (/^layout:\s*mono\s*$/m.test(existing)) {
+      console.log('   ✓ .sdd.yaml 已声明 layout: mono，跳过');
+      return true;
+    }
+    console.log('⚠️  .sdd.yaml 已存在但未声明 layout: mono；单仓请手动补一行 `layout: mono`');
+    return false;
+  }
+  const lines = [
+    '# 单仓布局：openspec 文档与代码在同一个仓库',
+    '# commit-msg 只写 Spec-Change（spec 与代码同属一次 commit，无需 Spec-Revision 指针）',
+    'version: 1',
+    'layout: mono',
+    '',
+  ];
+  fs.writeFileSync(target, lines.join('\n'), 'utf8');
+  console.log(`✅ 已创建 .sdd.yaml（layout: mono）: ${target}`);
   return true;
 }
 
@@ -1017,6 +1170,7 @@ KLD SDD 项目初始化工具
 用法:
   kld-sdd-init [选项]
   npx kld-sdd [选项]
+  kld-sdd sync-repos           # 工作目录下发现新增代码仓并轻量接入
 
 选项:
   -h, --help       显示帮助信息
@@ -1025,13 +1179,61 @@ KLD SDD 项目初始化工具
   --skip-template  跳过复制内置模版
   --tool <name>     指定编辑器，可用值: cursor, claude, codebuddy, qoder, opencode, kunlunzhima, workbuddy, codex, all
 
+工作区模式（在个人工作目录执行）:
+  - skills / 编辑器配置只部署一次到当前工作目录
+  - 自动发现子目录 Git 仓库
+  - spec 仓：modules.yaml / openspec 模板 / 文档门禁
+  - 代码仓：仅 commit-msg Hook + .sdd.yaml + link-spec（不装 skills）
+  - Trailer 数据仍在代码 commit 时由 Hook 写入
+
 示例:
   kld-sdd-init                 # 完整初始化流程
   kld-sdd-init --skip-openspec # 跳过 openspec，直接部署 skills
   kld-sdd-init --tool codex    # 仅部署 Codex 配置
+  kld-sdd sync-repos           # 新代码仓加入后同步接入
 `);
 }
 
+/**
+ * 工作区：为已发现的代码仓做轻量接入，并刷新 .sdd-workspace.yaml
+ */
+function syncWorkspaceRepos(workspaceRoot = process.cwd(), options = {}) {
+  const root = path.resolve(workspaceRoot);
+  const { layout, newcomers, saved } = workspaceLayout.findNewCodeRepos(root);
+  const onlyNew = options.onlyNew !== false;
+
+  if (!layout.specRepo) {
+    console.log('❌ 未发现 spec 仓库（需子目录含 modules.yaml / openspec/changes / *-sdd-specs）');
+    return { ok: false, attached: [], layout };
+  }
+
+  console.log(`📂 工作目录: ${root}`);
+  console.log(`📄 Spec 仓: ${layout.specRepo.name}`);
+  console.log(`🔎 已发现代码仓: ${layout.codeRepos.map((c) => c.name).join(', ') || '(无)'}`);
+
+  const targets = onlyNew && saved.ok
+    ? newcomers
+    : layout.codeRepos;
+
+  if (onlyNew && saved.ok) {
+    console.log(`🆕 待接入新仓: ${newcomers.map((c) => c.name).join(', ') || '(无)'}`);
+  }
+
+  const attached = [];
+  const failed = [];
+  for (const repo of targets) {
+    const result = attachCodeRepoLite(repo.abs, layout.specRepo.abs);
+    if (result.ok) attached.push(result);
+    else failed.push(result);
+  }
+
+  // 刷新清单（包含本次发现的全部代码仓）
+  const filePath = workspaceLayout.writeWorkspaceFile(root, layout);
+  console.log(`✅ 已更新 ${path.basename(filePath)}`);
+
+  return { ok: failed.length === 0, attached, failed, layout, filePath };
+}
+
 /**
  * 主函数
  */
@@ -1071,44 +1273,87 @@ async function main() {
     process.exit(1);
   }
 
-  // 1. 运行 openspec init（传入用户选择的工具）
+  const workspaceRoot = process.cwd();
+  const layout = workspaceLayout.detectWorkspaceLayout(workspaceRoot);
+  if (layout.isWorkspace) {
+    console.log('📂 检测到个人工作目录布局（子目录 Git 仓库）');
+    console.log(`   Spec: ${layout.specRepo ? layout.specRepo.name : '(未发现)'}`);
+    console.log(`   代码仓: ${layout.codeRepos.map((c) => c.name).join(', ') || '(无)'}`);
+    console.log('   → skills 只部署到本工作目录；代码仓仅轻量接入 Hook/关联');
+    console.log();
+  }
+
+  // 1. openspec init：工作区模式下若有 spec 仓则在其内执行
   if (!skipOpenspec) {
-    await runOpenspecInit(selectedTools);
+    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. 清理原生 openspec 命令（删除 opsx-*.md，避免命名混淆）
+    // 2/3. skills 与编辑器产物：永远只装在当前工作目录一次
     cleanupNativeOpenspecCommands(selectedTools);
-
-    // 3. 清理旧版嵌套 skills/kld-sdd/ bundle（Claude Code 无法识别二层目录）
     cleanupLegacyBundledOpsxSkills(selectedTools);
-
-    // 3.1 部署 SDD opsx skills（扁平到 .claude/skills/opsx-*/）
     deployOpsxSkills(selectedTools);
-    
-    // 3.2 清理原生 openspec-* skills（防止残留）
     cleanupNativeOpenspecSkills(selectedTools);
+    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);
+        }
 
-    // 3.3 部署 Agent 专属产物（Kunlun bridge / CodeBuddy hooks / Claude hooks）
-    deployProfileArtifacts(selectedTools, process.cwd(), getPackagePath());
-
-    // 5. 部署 SDD Telemetry 数据目录
-    deployTelemetryDataDir();
-
-    // 5.1 部署 Git hooks / CI 兜底模板
-    deployQualityGateTemplates();
-
-    // 6. 复制标准文档模版到项目（供参考）
-    copyTemplatesToProject();
-    
-    // 7. 初始化全局架构约束 (overview.md)
-    initGlobalOverview();
-
-    // 7.1 部署 SDD 操作手册（HTML）
-    deploySddGuideManual();
+        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');
+      }
+    } else {
+      // 单仓模式（旧行为）：当前目录既是项目根
+      deployTelemetryDataDir(workspaceRoot);
+      deployQualityGateTemplates(workspaceRoot, { mode: 'full' });
+      deployModulesYaml(workspaceRoot);
+      deploySddConfigYaml(workspaceRoot);
+      if (workspaceLayout.isGitRepo(workspaceRoot)) {
+        // openspec 与代码同仓：显式声明单仓，Hook 才会写 Spec-Change
+        deployMonoSddYaml(workspaceRoot);
+      } else {
+        deployDotSddYaml(workspaceRoot);
+      }
+      copyTemplatesToProject();
+      initGlobalOverview();
+      deploySddGuideManual(workspaceRoot);
+    }
   }
 
-  // 7. 更新 .gitignore
+  // 7. 更新工作目录 .gitignore
   updateGitignore();
 
   const selectedNames = selectedTools.map(t => TOOL_CONFIGS[t].name).join(', ');
@@ -1120,11 +1365,28 @@ async function main() {
   console.log();
   console.log(`已为以下编辑器生成配置: ${selectedNames}`);
   console.log();
-  console.log('已生成/覆盖:');
-  console.log('  🌐 openspec/specs/overview.md     # 全局架构约束（数据字典、接口规范）');
-  console.log('  📖 openspec/kld-sdd操作手册.html   # SDD 操作手册（HTML）');
-  console.log('  📄 openspec-templates/           # 标准文档模版（参考用）');
-  console.log('  🎯 .*/skills/opsx-*/              # SDD skills（扁平一层）');
+  if (layout.isWorkspace) {
+    console.log('工作区部署结果:');
+    console.log('  🎯 工作目录 .*/skills/opsx-*/     # skills 只装这一份');
+    console.log('  📋 .sdd-workspace.yaml           # 子仓编排清单');
+    if (layout.specRepo) {
+      console.log(`  📄 ${layout.specRepo.name}/modules.yaml + openspec-templates`);
+    }
+    for (const repo of layout.codeRepos) {
+      console.log(`  🔗 ${repo.name}/  ← commit-msg Hook + .sdd.yaml（无 skills）`);
+    }
+    console.log();
+    console.log('新代码仓加入后执行:');
+    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（扁平一层）');
+  }
   if (selectedTools.includes('kunlunzhima')) {
     console.log('  📎 .kunlunzhima/commands/opsx/    # KunlunZhima OPSX command bridge（11 个）');
     console.log('  ℹ️  KunlunZhima 通过 commands/skills 入口使用 SDD，未启用自动 Hook');
@@ -1135,9 +1397,11 @@ async function main() {
   if (selectedTools.includes('claude')) {
     console.log('  🪝 .claude/hooks/                 # Claude Code SDD Hook Pack（可选增强）');
   }
-  console.log('  📊 skywalk-sdd/                  # SDD Telemetry 数据目录');
-  console.log('  🧰 skywalk-sdd/git-hooks/        # Git hooks 质量门禁模板');
-  console.log('  🧪 skywalk-sdd/ci/               # CI 兜底采集模板');
+  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();
   
   // 统一的 skill 格式说明
@@ -1156,6 +1420,9 @@ async function main() {
     
   console.log();
   console.log('后续步骤:');
+  if (layout.isWorkspace && layout.specRepo) {
+    console.log(`  0. 文档类命令请以 spec 仓为 --project（例: --project=${layout.specRepo.name}）`);
+  }
   console.log('  1. 激活 opsx-propose skill，输入变更名称开始创建文档');
   console.log('  2. 按顺序执行 propose → spec → design → task');
   console.log('  3. 激活 opsx-check 验证文档质量');
@@ -1187,6 +1454,14 @@ module.exports = {
   deployOpsxSkills,
   deployProfileArtifacts,
   deploySddGuideManual,
+  deployModulesYaml,
+  deploySddConfigYaml,
+  deployDotSddYaml,
+  deployMonoSddYaml,
+  deployQualityGateTemplates,
+  deployTelemetryDataDir,
+  attachCodeRepoLite,
+  syncWorkspaceRepos,
   copyDirRendered,
   parseSelectedTools,
   TOOL_CONFIGS,

package/lib/workspace-layout.js

@@ -0,0 +1,2 @@
+'use strict';
+module.exports = require('../skywalk-sdd/ontology/workspace-layout.cjs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.6.7",
+  "version": "2.6.9",
   "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/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/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(