kld-sdd 2.6.15 → 2.6.17

package/lib/init.js

@@ -831,6 +831,30 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
     console.log(`   ⚠️  V3 指标模块源文件缺失: ${metricsV3Src}（report/metrics 可能无法加载 metrics-v3）`);
   }
 
+  // 部署 spec-root.cjs（替代脆弱的 $(cat .sdd-spec-root)，CWD 无关）
+  const specRootSrc = path.join(pkgPath, 'skywalk-sdd', 'spec-root.cjs');
+  const specRootDst = path.join(dataDir, 'spec-root.cjs');
+  if (fs.existsSync(specRootSrc)) {
+    fs.copyFileSync(specRootSrc, specRootDst);
+    console.log('   ✓ 部署 skywalk-sdd/spec-root.cjs（CWD 无关的 spec 根路径解析器）');
+  } else {
+    console.log('   ⚠️  spec-root.cjs 源文件缺失，$(cat .sdd-spec-root) 模式可能受影响');
+  }
+
+  // 部署 lib/shared.cjs（共用工具模块：parseArgs/readJson/atomicWrite/HTTP/specRoot/KB状态）
+  const sharedLibDir = path.join(dataDir, 'lib');
+  if (!fs.existsSync(sharedLibDir)) {
+    fs.mkdirSync(sharedLibDir, { recursive: true });
+  }
+  const sharedSrc = path.join(pkgPath, 'skywalk-sdd', 'lib', 'shared.cjs');
+  const sharedDst = path.join(sharedLibDir, 'shared.cjs');
+  if (fs.existsSync(sharedSrc)) {
+    fs.copyFileSync(sharedSrc, sharedDst);
+    console.log('   ✓ 部署 skywalk-sdd/lib/shared.cjs（共用工具：parseArgs/JSON/BOM/HTTP/specRoot/KB）');
+  } else {
+    console.log('   ⚠️  lib/shared.cjs 源文件缺失，多个脚本将缺少共用工具依赖');
+  }
+
   const packageVersion = require(path.join(pkgPath, 'package.json')).version;
   const runtimeMetadataDst = path.join(dataDir, 'runtime-metadata.cjs');
   fs.writeFileSync(
@@ -885,73 +909,146 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
     console.log('   ⚠️  openspec-shim.cjs 源文件缺失，openspec 命令需要手动 cd 到 spec 包执行');
   }
 
+  // 部署 kb-upload.cjs（知识库上传脚本，支持文件夹/zip 双模式随时入库）
+  const kbUploadSrc = path.join(pkgPath, 'skywalk-sdd', 'kb-upload.cjs');
+  const kbUploadDst = path.join(dataDir, 'kb-upload.cjs');
+  if (fs.existsSync(kbUploadSrc)) {
+    fs.copyFileSync(kbUploadSrc, kbUploadDst);
+    console.log('   ✓ 部署 skywalk-sdd/kb-upload.cjs（知识库上传：文件夹/zip 双模式）');
+  } else {
+    console.log('   ⚠️  kb-upload.cjs 源文件缺失，随时入库功能不可用');
+  }
+
+  // 部署 kb-sync-identity.cjs（KB 身份同步脚本，重新入库前同步 version-id）
+  const kbSyncIdentitySrc = path.join(pkgPath, 'skywalk-sdd', 'kb-sync-identity.cjs');
+  const kbSyncIdentityDst = path.join(dataDir, 'kb-sync-identity.cjs');
+  if (fs.existsSync(kbSyncIdentitySrc)) {
+    fs.copyFileSync(kbSyncIdentitySrc, kbSyncIdentityDst);
+    console.log('   ✓ 部署 skywalk-sdd/kb-sync-identity.cjs（KB 身份同步：重新入库前同步 version-id）');
+  } else {
+    console.log('   ⚠️  kb-sync-identity.cjs 源文件缺失，重新入库身份同步不可用');
+  }
+
   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('   ℹ️  project-identity.json 将在首次配置 KB（opsx-ontology-query）时自动创建');
+  console.log('   ℹ️  project-identity.json 将在首次配置 KB（opsx-kb-config）时自动创建');
   console.log('✅ Telemetry 已就绪（数据存储在 skywalk-sdd/，无需配置 MCP）');
   return true;
 }
 
-function installGitHookShim(cwd, hookName, scriptPath, options = {}) {
+/**
+ * 安装 SDD shell hook（多脚本调用型 hook，如 pre-commit / pre-push / commit-msg）。
+ * 直接部署完整的 shell 脚本到 .git/hooks/，脚本内部远程引用 spec 仓的 .cjs 脚本。
+ *
+ * shell hook 运行时通过 git config sdd.specPath / .sdd-spec-root / 向上搜索
+ * 定位 spec 仓的 skywalk-sdd/git-hooks/ 目录，兼容单仓/多仓/mono 布局。
+ *
+ * @param {string} cwd - Git 仓库根目录
+ * @param {string} hookName - hook 名称（如 'pre-commit'、'pre-push'）
+ * @param {string} pkgPath - kld-sdd 包路径（用于读取模板）
+ */
+function installSddShellHook(cwd, hookName, pkgPath = getPackagePath()) {
   const hooksDir = path.join(cwd, '.git', 'hooks');
   if (!fs.existsSync(hooksDir)) {
     return;
   }
 
+  const templatePath = path.join(pkgPath, 'templates', 'git-hooks', hookName);
+  if (!fs.existsSync(templatePath)) {
+    console.log(`   ⚠️  Hook 模板不存在: ${templatePath}`);
+    return;
+  }
+
   const hookPath = path.join(hooksDir, hookName);
   const marker = 'KLD SDD quality gate';
-  // Git 把 commit-msg 文件路径放在 $1；--project 等额外参数必须跟在 "$@" 后面，
-  // 否则 trailer 脚本会把 --project=… 误当成 message 文件（argv[2]）。
-  const extraArgs = options.extraArgs || '';
-  // Windows 反斜杠路径在 #!/bin/sh（Git for Windows MSYS2）中不被 [ -f ] 和 node 识别，
-  // 统一转为正斜杠，确保 hook shim 跨平台可执行。
-  const shScriptPath = scriptPath.replace(/\\/g, '/');
-  const shExtraArgs = extraArgs.replace(/\\/g, '/');
-  const nodeLine = shExtraArgs
-    ? `  node "${shScriptPath}" "$@" ${shExtraArgs}`
-    : `  node "${shScriptPath}" "$@"`;
-  const shim = [
-    '#!/bin/sh',
-    `# ${marker}`,
-    `if [ -f "${shScriptPath}" ]; then`,
-    nodeLine,
-    'else',
-    `  echo "[kld-sdd] Hook 脚本不存在: ${shScriptPath}" >&2`,
-    '  exit 1',
-    'fi',
-    '',
-  ].join('\n');
+  const content = fs.readFileSync(templatePath, 'utf8');
 
   if (fs.existsSync(hookPath)) {
     const existing = fs.readFileSync(hookPath, 'utf8');
     if (existing.includes(marker)) {
-      // 已是 SDD shim：若指向路径变化（如改为引用 spec 仓），允许覆盖升级
-      if (existing.includes(shScriptPath) && (!shExtraArgs || existing.includes(shExtraArgs.trim()))) {
-        console.log(`   ✓ .git/hooks/${hookName} 已包含 SDD 质量门禁`);
-        return;
-      }
-      fs.writeFileSync(hookPath, shim, 'utf8');
+      // 已是 SDD hook：允许覆盖升级
+      fs.writeFileSync(hookPath, content, 'utf8');
       try {
         fs.chmodSync(hookPath, 0o755);
       } catch {
         // ignore
       }
-      console.log(`   ✓ 更新 .git/hooks/${hookName} SDD 质量门禁`);
+      console.log(`   ✓ 更新 .git/hooks/${hookName} SDD 质量门禁（多脚本）`);
       return;
     }
-    console.log(`   ℹ️  .git/hooks/${hookName} 已存在，已保留不覆盖；可手动调用 ${scriptPath}`);
+    console.log(`   ℹ️  .git/hooks/${hookName} 已存在且非 SDD 受管 hook，已保留不覆盖`);
     return;
   }
 
-  fs.writeFileSync(hookPath, shim, 'utf8');
+  fs.writeFileSync(hookPath, content, 'utf8');
   try {
     fs.chmodSync(hookPath, 0o755);
   } catch {
-    // Windows 上 chmod 可能没有实际效果，不影响 Git Bash 执行文本 hook。
+    // Windows 上 chmod 可能没有实际效果
   }
-  console.log(`   ✓ 安装 .git/hooks/${hookName} SDD 质量门禁`);
+  console.log(`   ✓ 安装 .git/hooks/${hookName} SDD 质量门禁（多脚本）`);
+}
+
+/**
+ * 部署代码仓全部 Git hooks（commit-msg + pre-commit + pre-push）。
+ *
+ * 统一入口，封装三种 hook 的部署逻辑。代码仓**不落 skywalk-sdd/**，
+ * 只在 .git/hooks/ 安装 shell hook 模板，远程引用 spec 仓的 .cjs 脚本：
+ *
+ * - **spec 仓**：确保 skywalk-sdd/git-hooks/ 下有全部 .cjs 脚本
+ *   （commit-msg-sdd-trailer + pre-commit-* + pre-push-* + ontology）。
+ * - **代码仓 .git/hooks/**：仅安装 3 个 shell hook 模板，运行时通过
+ *   git config sdd.specPath / .sdd-spec-root / 向上搜索定位 spec 仓的脚本。
+ *
+ * @param {string} codeRepoRoot - 代码仓根目录
+ * @param {string} specRepoRoot - spec 包裹包根目录
+ * @param {object} options - { pkgPath }
+ * @returns {{ ok: boolean, message?: string }}
+ */
+function deployCodeRepoHooks(codeRepoRoot, specRepoRoot, options = {}) {
+  const cwd = path.resolve(codeRepoRoot);
+  const specRoot = path.resolve(specRepoRoot);
+  const pkgPath = options.pkgPath || getPackagePath();
+
+  if (!workspaceLayout.isGitRepo(cwd)) {
+    return { ok: false, message: '不是 Git 仓库' };
+  }
+
+  // ── 1. 确保 spec 仓有全部 hook 脚本 + ontology ──
+  // commit-msg .cjs + ontology（ensureSpecCommitMsgScript 已处理）
+  ensureSpecCommitMsgScript(specRoot, pkgPath);
+  // pre-commit / pre-push .cjs 脚本
+  const specHooksDir = path.join(specRoot, 'skywalk-sdd', 'git-hooks');
+  const gitHooksTemplateDir = path.join(pkgPath, 'templates', 'git-hooks');
+  if (!fs.existsSync(specHooksDir)) {
+    fs.mkdirSync(specHooksDir, { recursive: true });
+  }
+  const hookScripts = [
+    'pre-commit-sdd-check.cjs',
+    'pre-commit-consistency-check.cjs',
+    'pre-push-sdd-check.cjs',
+    'pre-push-consistency-check.cjs',
+  ];
+  for (const script of hookScripts) {
+    const src = path.join(gitHooksTemplateDir, script);
+    const dst = path.join(specHooksDir, script);
+    // 删除 !fs.existsSync(dst) 条件：原逻辑只在目标不存在时复制，导致模板升级后 spec 仓不会拿到最新脚本。
+    // 现在始终覆盖，与 shell hook 的 marker 覆盖策略保持一致。
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dst);
+    }
+  }
+  console.log(`   ✓ 确保 spec 仓 skywalk-sdd/git-hooks/ 脚本齐全`);
+
+  // ── 2. 安装三个 shell hooks 到代码仓 .git/hooks/ ──
+  // 模板 hook 运行时自动定位 spec 仓的 .cjs 脚本
+  installSddShellHook(cwd, 'commit-msg', pkgPath);
+  installSddShellHook(cwd, 'pre-commit', pkgPath);
+  installSddShellHook(cwd, 'pre-push', pkgPath);
+
+  return { ok: true };
 }
 
 /**
@@ -976,22 +1073,6 @@ function ensureSpecCommitMsgScript(specRepoRoot, pkgPath = getPackagePath()) {
   return { ok: true, scriptPath, deployed: true };
 }
 
-/**
- * 代码仓 commit-msg：只写 .git/hooks，脚本与 ontology 一律用 spec 仓那一份。
- */
-function installCodeRepoCommitMsgHook(codeRepoRoot, specRepoRoot, options = {}) {
-  const cwd = path.resolve(codeRepoRoot);
-  const ensured = ensureSpecCommitMsgScript(specRepoRoot, options.pkgPath || getPackagePath());
-  if (!ensured.ok) {
-    console.log(`   ⚠️  ${ensured.message}`);
-    return false;
-  }
-  installGitHookShim(cwd, 'commit-msg', ensured.scriptPath, {
-    extraArgs: `"--project=${cwd}"`,
-  });
-  return true;
-}
-
 /**
  * 部署 Git hooks / CI 兜底模板
  * 这些脚本只做质量门禁和 CI 补充记录，不替代 OPSX 主采集链路。
@@ -999,7 +1080,7 @@ function installCodeRepoCommitMsgHook(codeRepoRoot, specRepoRoot, options = {})
  * @param {string} [targetCwd]
  * @param {{ mode?: 'full'|'commit-msg-only' }} [options]
  *   full: spec 包裹包（pre-commit/pre-push/commit-msg + CI）
- *   commit-msg-only: 单仓 Git 根（本仓落 skywalk-sdd/git-hooks；多仓代码仓请用 installCodeRepoCommitMsgHook）
+ *   commit-msg-only: 仅安装 commit-msg hook（跳过 pre-commit/pre-push）
  */
 function deployQualityGateTemplates(targetCwd = process.cwd(), options = {}) {
   const pkgPath = getPackagePath();
@@ -1018,8 +1099,16 @@ function deployQualityGateTemplates(targetCwd = process.cwd(), options = {}) {
   const targetCiDir = path.join(dataDir, 'ci');
 
   if (fs.existsSync(gitHooksTemplateDir)) {
-    copyDir(gitHooksTemplateDir, targetGitHooksDir);
-    console.log('   ✓ 部署 skywalk-sdd/git-hooks/');
+    // 只复制 .cjs 脚本到 skywalk-sdd/git-hooks/，shell hook 模板（commit-msg/pre-commit/pre-push）不落此目录
+    if (!fs.existsSync(targetGitHooksDir)) {
+      fs.mkdirSync(targetGitHooksDir, { recursive: true });
+    }
+    for (const file of fs.readdirSync(gitHooksTemplateDir)) {
+      if (file.endsWith('.cjs')) {
+        fs.copyFileSync(path.join(gitHooksTemplateDir, file), path.join(targetGitHooksDir, file));
+      }
+    }
+    console.log('   ✓ 部署 skywalk-sdd/git-hooks/（.cjs 脚本）');
   } else {
     console.log(`   ⚠️  Git hooks 模板缺失: ${gitHooksTemplateDir}`);
   }
@@ -1030,18 +1119,18 @@ function deployQualityGateTemplates(targetCwd = process.cwd(), options = {}) {
   }
 
   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');
+    installSddShellHook(cwd, 'pre-commit', pkgPath);
+    installSddShellHook(cwd, 'pre-push', pkgPath);
   }
-  installGitHookShim(cwd, 'commit-msg', 'skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs');
+  installSddShellHook(cwd, 'commit-msg', pkgPath);
 
   console.log('✅ Git hooks 已就绪');
   return true;
 }
 
 /**
- * 代码仓轻量接入：只写 .sdd.yaml + sdd.specPath + .git/hooks/commit-msg。
- * 不在代码仓落 skywalk-sdd/——Hook 脚本与 ontology 引用 spec 包裹包那一份。
+ * 代码仓轻量接入：写 .sdd.yaml + sdd.specPath + .git/hooks/（commit-msg + pre-commit + pre-push）。
+ * 代码仓不落 skywalk-sdd/，shell hook 远程引用 spec 仓 skywalk-sdd/git-hooks/ 下的 .cjs 脚本。
  */
 function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
   const cwd = path.resolve(codeRepoRoot);
@@ -1055,7 +1144,7 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
     return { ok: false, repo: label, message: `spec 路径不是 Git 仓库: ${specRoot}` };
   }
 
-  console.log(`🔗 轻量接入代码仓（无 skywalk-sdd/、无 skills）: ${label}`);
+  console.log(`🔗 轻量接入代码仓（commit-msg + pre-commit + pre-push）: ${label}`);
 
   const remote = sddConfig.gitRemoteUrl(specRoot) || 'git@gitlab.example.com:biz/xxx-sdd-specs.git';
   const sddYamlPath = path.join(cwd, '.sdd.yaml');
@@ -1081,8 +1170,8 @@ function attachCodeRepoLite(codeRepoRoot, specRepoRoot, options = {}) {
   }
   console.log(`   ✓ sdd.specPath = ${linked.path}`);
 
-  installCodeRepoCommitMsgHook(cwd, specRoot, options);
-  console.log('   ✓ commit-msg → spec 仓 skywalk-sdd/git-hooks/（代码仓不落 skywalk-sdd/）');
+  // 部署代码仓全部 Git hooks（commit-msg + pre-commit + pre-push）
+  deployCodeRepoHooks(cwd, specRoot, options);
 
   return { ok: true, repo: label, path: cwd, specPath: linked.path };
 }
@@ -1555,8 +1644,9 @@ async function main() {
         removeOuterSkywalk(workspaceRoot);
 
         deployMonoSddYaml(workspaceRoot, { specPathRelative: specPackage.name });
-        // Hook 装在 Git 根，脚本在包裹包内（Git 根不落 skywalk-sdd/）
-        installCodeRepoCommitMsgHook(workspaceRoot, specPackage.abs);
+        // 部署代码仓全部 Git hooks（commit-msg + pre-commit + pre-push）
+        // 单仓 mono：hook 通过 .sdd-spec-root 定位包裹包的 skywalk-sdd/git-hooks/
+        deployCodeRepoHooks(workspaceRoot, specPackage.abs);
         const linked = sddConfig.setSpecPath(workspaceRoot, specPackage.abs, {
           allowNestedPackage: true,
         });
@@ -1649,7 +1739,7 @@ async function main() {
     console.log('  📌 .sdd-spec-root → 包裹包；无根目录 skywalk-sdd/');
   }
   if (selectedTools.includes('kunlunzhima')) {
-    console.log('  📎 .kunlunzhima/commands/opsx/    # KunlunZhima OPSX command bridge（11 个）');
+    console.log('  📎 .kunlunzhima/commands/opsx/    # KunlunZhima OPSX command bridge（13 个）');
     console.log('  ℹ️  KunlunZhima 通过 commands/skills 入口使用 SDD，未启用自动 Hook');
   }
   if (selectedTools.includes('codebuddy')) {
@@ -1661,18 +1751,22 @@ async function main() {
   console.log();
   
   // 统一的 skill 格式说明
-  console.log('可用 skills（opsx-* 系列，11 个 SDD skills）:');
-  console.log('  opsx-propose   - 创建业务意图文档（Why）');
-  console.log('  opsx-spec      - 创建技术契约文档（What）');
-  console.log('  opsx-design    - 创建技术实现方案（How）');
-  console.log('  opsx-task      - 拆解AI编码任务（Do）');
-  console.log('  opsx-check     - 质量门禁检查（Verify）');
-  console.log('  opsx-apply     - 申请变更实施（Apply）');
-  console.log('  opsx-test      - 执行单元测试（Test）');
-  console.log('  opsx-archive   - 归档变更（Archive）');
-  console.log('  opsx-explore   - 浏览变更状态（Explore）');
-  console.log('  opsx-knowledge - 业务知识库检索（辅助）');
-  console.log('  opsx-rules     - 生成/更新 Agent 规则（辅助）');
+  console.log('可用 skills（opsx-* 系列，15 个 SDD skills）:');
+  console.log('  opsx-propose           - 创建业务意图文档（Why）');
+  console.log('  opsx-spec              - 创建技术契约文档（What）');
+  console.log('  opsx-design            - 创建技术实现方案（How）');
+  console.log('  opsx-task              - 拆解AI编码任务（Do）');
+  console.log('  opsx-check             - 质量门禁检查（Verify）');
+  console.log('  opsx-apply             - 申请变更实施（Apply）');
+  console.log('  opsx-test              - 执行单元测试（Test）');
+  console.log('  opsx-archive           - 归档变更（Archive）');
+  console.log('  opsx-explore           - 浏览变更状态（Explore）');
+  console.log('  opsx-knowledge         - 业务知识库检索（辅助）');
+  console.log('  opsx-rules             - 生成/更新 Agent 规则（辅助）');
+  console.log('  opsx-consistency-check - Spec 一致性校验（代码 vs spec）');
+  console.log('  opsx-kb-config         - 知识库配置（API Key + Space/KB 选择）');
+  console.log('  opsx-ontology-query    - 本体知识库查询');
+  console.log('  opsx-kb-ingest         - 知识库入库（zip / 文件夹上传）');
     
   console.log();
   console.log('后续步骤:');
@@ -1685,6 +1779,8 @@ async function main() {
   console.log('  2. 按顺序执行 propose → spec → design → task');
   console.log('  3. 激活 opsx-check 验证文档质量');
   console.log('  4. 激活 opsx-apply 申请实施，opsx-archive 归档完成');
+  console.log('  5. 随时入库：node skywalk-sdd/kb-upload.cjs --folder=<变更目录> --minimum-level=propose-spec');
+  console.log('     （需先运行 /opsx-kb-config 配置知识库）');
   if (selectedTools.includes('codebuddy')) {
     console.log('  5. CodeBuddy 用户：SDD Hook Pack 已随初始化自动部署，门禁自动生效，无需手动配置');
   }
@@ -1729,5 +1825,7 @@ module.exports = {
   syncWorkspaceRepos,
   copyDirRendered,
   parseSelectedTools,
+  installSddShellHook,
+  deployCodeRepoHooks,
   TOOL_CONFIGS,
 };

package/lib/skills-bundle.js

@@ -7,6 +7,22 @@ const path = require('path');
 
 const SKILLS_BUNDLE_NAME = 'kld-sdd';
 
+/**
+ * PowerShell 禁忌 — 追加到 SHELL_GUIDANCE 后，自动注入所有 SKILL.md。
+ * 根因：PowerShell 的 cat/curl/Get-Content 行为与 bash 不同，导致管道断裂、
+ * HTTP 请求失败、JSON 文件 BOM 污染引发静默降级（sdd-output 错误 #1/#3/#4/#5）。
+ */
+const POWERSHELL_TABOOS = [
+  '',
+  '> - **PowerShell 禁忌**（Windows 用户必读）:',
+  '>   - 禁止 `| cat`（PowerShell 将 cat 解释为 Get-Content，不接受管道输入）→ 直接执行命令',
+  '>   - 禁止 `node -e "..."` 内联脚本（PowerShell 对 `||`/`{}`/`()` 有特殊解析，导致 JS 语法被破坏）→ 用 `write_to_file` 创建临时 `.cjs` 脚本执行后删除',
+  '>   - 禁止 cmd.exe 语法（如 `for /L %i in (1,1,N) do ...`）→ PowerShell 不支持，改用逐个 `execute_command` 调用或 PowerShell `foreach`',
+  '>   - 警告 CLIXML：PowerShell 捕获 `node`/`npx` 子进程输出时可能包装为 `#< CLIXML <Objs...>` 格式 → 检测到 CLIXML 时以文件系统实际产物为准，忽略 stdout',
+  '>   - 禁止 `curl`（PowerShell 将 curl 别名为 Invoke-WebRequest）→ HTTP 请求走 `context-client.cjs` / `kb-upload.cjs`，或用 `Invoke-RestMethod`',
+  '>   - 禁止 `Get-Content` / `Out-File` 读写 JSON（PowerShell 默认写 BOM 导致 JSON.parse 失败）→ 用 write_to_file 工具或 Node.js `fs` 模块',
+].join('\n');
+
 const OPSX_SKILL_DIRS = [
   'opsx-propose',
   'opsx-spec',
@@ -20,8 +36,11 @@ const OPSX_SKILL_DIRS = [
   'opsx-knowledge',
   'opsx-rules',
   // Engineering KB 依赖技能（随 init 部署；propose/spec/archive 硬依赖）
+  'opsx-kb-config',
   'opsx-ontology-query',
   'opsx-kb-ingest',
+  // Spec 一致性校验技能
+  'opsx-consistency-check',
 ];
 
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -102,6 +121,8 @@ const KUNLUN_SLASH_COMMANDS = [
   'explore',
   'ontology-query',
   'kb-ingest',
+  'kb-config',
+  'consistency-check',
 ];
 
 function transformKunlunSlashCommands(content) {
@@ -125,7 +146,8 @@ function replaceProfileTokens(content, profile) {
   return content
     .replace(/\$\{SKILL_RUNTIME_DIR\}/g, vars.SKILL_RUNTIME_DIR || profile.skillsDir || '')
     .replace(/\$\{HOOK_GATE_DESCRIPTION\}/g, vars.HOOK_GATE_DESCRIPTION || '')
-    .replace(/\$\{SHELL_GUIDANCE\}/g, vars.SHELL_GUIDANCE || '')
+    .replace(/\$\{SHELL_GUIDANCE\}/g, (vars.SHELL_GUIDANCE || '') + POWERSHELL_TABOOS)
+    .replace(/\$\{CHECK_REVIEW_DELEGATION_GUIDANCE\}/g, vars.CHECK_REVIEW_DELEGATION_GUIDANCE || '')
     .replace(/\$\{AGENT_SKILL_DIR\}/g, profile.skillsDir || '');
 }
 

package/lib/tool-profiles.js

@@ -24,6 +24,7 @@ const TOOL_PROFILES = Object.freeze({
       SKILL_RUNTIME_DIR: '.cursor/skills',
       HOOK_GATE_DESCRIPTION: '本项目未为此 Agent 部署自动 Hook 门禁；请遵循 Skill 自检与 CI/Git 证据门禁。',
       SHELL_GUIDANCE: '在 Windows 上优先使用 PowerShell；如需 Bash 请使用 Git Bash。',
+      CHECK_REVIEW_DELEGATION_GUIDANCE: '使用 Cursor 当前可用的独立 Agent/子代理能力启动一个全新评审上下文；若能力不可用，按本 Skill 的受控回退规则由主 Agent 检查。',
     },
   },
   claude: {
@@ -44,6 +45,7 @@ const TOOL_PROFILES = Object.freeze({
       SKILL_RUNTIME_DIR: '.claude/skills',
       HOOK_GATE_DESCRIPTION: 'Claude Code 已部署 SDD Hook Pack（.claude/hooks + settings.json），自动门禁与遥测增强已启用。',
       SHELL_GUIDANCE: '在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径；如必须使用绝对路径，请写成正斜杠路径或加引号。',
+      CHECK_REVIEW_DELEGATION_GUIDANCE: '使用 Claude Code 的 Agent 能力启动一个全新、无作者上下文的评审子代理；不得让评审子代理再次委派。',
     },
   },
   codebuddy: {
@@ -64,6 +66,7 @@ const TOOL_PROFILES = Object.freeze({
       SKILL_RUNTIME_DIR: '.codebuddy/skills',
       HOOK_GATE_DESCRIPTION: 'CodeBuddy CLI 已部署 SDD Hook Pack（.codebuddy/hooks + settings.json），初始化后自动生效。',
       SHELL_GUIDANCE: 'CodeBuddy Hooks 在 Windows 上通过 Git Bash 执行；命令使用 node "$CODEBUDDY_PROJECT_DIR/..." 引用项目路径。',
+      CHECK_REVIEW_DELEGATION_GUIDANCE: '使用 CodeBuddy 当前可用的独立 Agent 能力启动一个评审子代理；若启动失败，记录标准回退原因后由主 Agent 检查。',
     },
   },
   qoder: {
@@ -84,6 +87,7 @@ const TOOL_PROFILES = Object.freeze({
       SKILL_RUNTIME_DIR: '.qoder/skills',
       HOOK_GATE_DESCRIPTION: '本项目未为此 Agent 部署自动 Hook 门禁；请遵循 Skill 自检与 CI/Git 证据门禁。',
       SHELL_GUIDANCE: '在 Windows 上优先使用 PowerShell；如需 Bash 请使用 Git Bash。',
+      CHECK_REVIEW_DELEGATION_GUIDANCE: '使用 Qoder 当前可用的独立 Agent/子代理能力启动一个全新评审上下文；能力不可用时才允许主 Agent 回退。',
     },
   },
   opencode: {
@@ -107,6 +111,7 @@ const TOOL_PROFILES = Object.freeze({
       SKILL_RUNTIME_DIR: '.opencode/skills',
       HOOK_GATE_DESCRIPTION: '本项目未为此 Agent 部署自动 Hook 门禁；请遵循 Skill 自检与 CI/Git 证据门禁。',
       SHELL_GUIDANCE: '在 Windows 上优先使用 PowerShell；OpenCode 可通过环境变量 OPENCODE_GIT_BASH_PATH 指定 Git Bash；如需 Bash 请使用 Git Bash。',
+      CHECK_REVIEW_DELEGATION_GUIDANCE: '使用 OpenCode 当前可用的独立 Agent 能力启动一个无作者上下文的评审子代理；不得递归委派。',
     },
   },
   kunlunzhima: {
@@ -127,6 +132,7 @@ const TOOL_PROFILES = Object.freeze({
       SKILL_RUNTIME_DIR: '.kunlunzhima/skills',
       HOOK_GATE_DESCRIPTION: 'KunlunZhima IDE 不支持自动 Hook 门禁；请通过 Skill 自检、commands 入口与 CI/Git 证据门禁保障质量。',
       SHELL_GUIDANCE: 'KunlunZhima IDE 通过 commands/skills 入口使用 SDD；相对引用以 Skill 目录解析。',
+      CHECK_REVIEW_DELEGATION_GUIDANCE: '使用 KunlunZhima 当前可用的独立智能体能力启动一个全新评审上下文；若不支持，记录标准回退原因后由主智能体检查。',
     },
   },
   workbuddy: {
@@ -147,6 +153,7 @@ const TOOL_PROFILES = Object.freeze({
       SKILL_RUNTIME_DIR: '.workbuddy/skills',
       HOOK_GATE_DESCRIPTION: '本项目未为此 Agent 部署自动 Hook 门禁；请遵循 Skill 自检与 CI/Git 证据门禁。',
       SHELL_GUIDANCE: '在 Windows 上优先使用 PowerShell；如需 Bash 请使用 Git Bash。',
+      CHECK_REVIEW_DELEGATION_GUIDANCE: '使用 WorkBuddy 当前可用的独立 Agent/子代理能力启动一个全新评审上下文；能力不可用时才允许主 Agent 回退。',
     },
   },
   codex: {
@@ -167,6 +174,7 @@ const TOOL_PROFILES = Object.freeze({
       SKILL_RUNTIME_DIR: '.agents/skills',
       HOOK_GATE_DESCRIPTION: '本项目未为此 Agent 部署自动 Hook 门禁；请遵循 Skill 自检与 CI/Git 证据门禁。',
       SHELL_GUIDANCE: '在 Windows 上优先使用 PowerShell；如需 Bash 请使用 Git Bash。',
+      CHECK_REVIEW_DELEGATION_GUIDANCE: '使用 Codex 的多代理能力启动恰好一个独立评审子代理，并传入所需文件而不是作者对话；不得让评审子代理再次委派。',
     },
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.6.15",
+  "version": "2.6.17",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
   "main": "index.js",
   "bin": {
@@ -36,8 +36,13 @@
     "skywalk-sdd/runtime-metadata.cjs",
     "skywalk-sdd/reporting/",
     "skywalk-sdd/context-client.cjs",
+    "skywalk-sdd/openspec-shim.cjs",
     "skywalk-sdd/ontology/",
     "skywalk-sdd/apply-worktree-finish.cjs",
+    "skywalk-sdd/spec-root.cjs",
+    "skywalk-sdd/lib/",
+    "skywalk-sdd/kb-upload.cjs",
+    "skywalk-sdd/kb-sync-identity.cjs",
     "README.md"
   ]
 }

package/skywalk-sdd/apply-worktree-finish.cjs

@@ -11,32 +11,11 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const { parseArgs } = require('./lib/shared.cjs');
 
 const TEMP_DIR_NAMES = ['node_modules', 'dist', '.turbo', '.next', 'coverage', 'build'];
 
-function parseArgs(argv) {
-  const args = {};
-  for (let i = 2; i < argv.length; i++) {
-    const token = argv[i];
-    if (token === '--') continue;
-    if (token.startsWith('--')) {
-      const eq = token.indexOf('=');
-      if (eq !== -1) {
-        args[token.slice(2, eq)] = token.slice(eq + 1);
-      } else {
-        const key = token.slice(2);
-        const next = argv[i + 1];
-        if (next && !next.startsWith('--')) {
-          args[key] = next;
-          i++;
-        } else {
-          args[key] = true;
-        }
-      }
-    }
-  }
-  return args;
-}
+// parseArgs 已迁移至 lib/shared.cjs
 
 function git(cwd, gitArgs, opts = {}) {
   return execFileSync('git', gitArgs, {