kld-sdd 2.6.16 → 2.6.21

package/lib/init.js

@@ -30,11 +30,26 @@ const {
 const { deployCodebuddyHookPack } = require('./deploy-codebuddy-hooks');
 const workspaceLayout = require('./workspace-layout');
 const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
+const { runAccountBinding } = require('./init-account-binding');
 
-const rl = readline.createInterface({
-  input: process.stdin,
-  output: process.stdout
-});
+let rl = null;
+
+function getRl() {
+  if (!rl) {
+    rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+  }
+  return rl;
+}
+
+function closeRl() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}
 
 // 工具类型配置（路径字段从 TOOL_PROFILES 派生，避免双份漂移）
 const TOOL_CONFIGS = buildToolConfigs();
@@ -44,10 +59,30 @@ const TOOL_CONFIGS = buildToolConfigs();
  */
 function ask(question) {
   return new Promise(resolve => {
-    rl.question(question, answer => resolve(answer.trim()));
+    getRl().question(question, answer => resolve(answer.trim()));
   });
 }
 
+/**
+ * 输出详细度判定（惰性读取，便于测试在运行期注入）
+ * 触发条件：argv 含 --verbose，或 KLD_SDD_VERBOSE 为 1/true（大小写不敏感）
+ * 注意：-v 已被 --version 占用，不复用
+ */
+function isVerbose() {
+  if (process.argv.includes('--verbose')) return true;
+  const env = process.env.KLD_SDD_VERBOSE;
+  return typeof env === 'string' && /^(1|true)$/i.test(env);
+}
+
+/**
+ * verbose 模式下的明细日志；默认模式静默
+ */
+function vlog(...args) {
+  if (isVerbose()) {
+    console.log(...args);
+  }
+}
+
 /**
  * 从命令行参数读取指定编辑器
  * 支持：--tool codex、--tool=codex、--tool cursor,codex、--tool all
@@ -496,7 +531,7 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
       
       if (fs.existsSync(sourceDir)) {
         copyDirRendered(sourceDir, targetDir, config, toolKey);
-        console.log(`     ✓ ${skillDir}/`);
+        vlog(`     ✓ ${skillDir}/`);
       }
     }
   }
@@ -706,14 +741,14 @@ function copyTemplatesToProject(cwd = process.cwd()) {
   }
   
   copyDir(templatePath, targetDir);
-  
-  console.log(`✅ 标准文档模版已复制到: ${targetDir}`);
-  console.log('   包含文件:');
+
   const files = fs.readdirSync(targetDir);
+  console.log(`✅ 标准文档模版已复制到: ${targetDir}（${files.length} 个文件）`);
+  vlog('   包含文件:');
   files.forEach(file => {
-    console.log(`     - ${file}`);
+    vlog(`     - ${file}`);
   });
-  
+
   return true;
 }
 
@@ -803,13 +838,15 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   // 创建本地数据目录（事件和活跃状态存储；报告落 change 子目录，不在此创建）
   const eventsDir = path.join(dataDir, 'events');
   const stateDir = path.join(dataDir, 'state');
+  // 成功部署的模块计数（用于默认模式单行摘要）
+  let deployedModules = 0;
   if (!fs.existsSync(eventsDir)) {
     fs.mkdirSync(eventsDir, { recursive: true });
-    console.log('   ✓ 创建 skywalk-sdd/events/ 数据目录');
+    vlog('   ✓ 创建 skywalk-sdd/events/ 数据目录');
   }
   if (!fs.existsSync(stateDir)) {
     fs.mkdirSync(stateDir, { recursive: true });
-    console.log('   ✓ 创建 skywalk-sdd/state/ 活跃阶段状态目录');
+    vlog('   ✓ 创建 skywalk-sdd/state/ 活跃阶段状态目录');
   }
 
   // 部署项目内 Telemetry CLI（不依赖 npm 发布）
@@ -817,7 +854,8 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   const telemetryDst = path.join(dataDir, 'log.cjs');
   if (fs.existsSync(telemetrySrc)) {
     fs.copyFileSync(telemetrySrc, telemetryDst);
-    console.log('   ✓ 部署 skywalk-sdd/log.cjs（本地 Telemetry CLI）');
+    deployedModules += 1;
+    vlog('   ✓ 部署 skywalk-sdd/log.cjs（本地 Telemetry CLI）');
   } else {
     console.log(`   ⚠️  Telemetry CLI 源文件缺失: ${telemetrySrc}`);
   }
@@ -826,11 +864,58 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   const metricsV3Dst = path.join(dataDir, 'metrics-v3.cjs');
   if (fs.existsSync(metricsV3Src)) {
     fs.copyFileSync(metricsV3Src, metricsV3Dst);
-    console.log('   ✓ 部署 skywalk-sdd/metrics-v3.cjs（V3 指标运行时）');
+    deployedModules += 1;
+    vlog('   ✓ 部署 skywalk-sdd/metrics-v3.cjs（V3 指标运行时）');
   } else {
     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);
+    deployedModules += 1;
+    vlog('   ✓ 部署 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);
+    deployedModules += 1;
+    vlog('   ✓ 部署 skywalk-sdd/lib/shared.cjs（共用工具：parseArgs/JSON/BOM/HTTP/specRoot/KB）');
+  } else {
+    console.log('   ⚠️  lib/shared.cjs 源文件缺失，多个脚本将缺少共用工具依赖');
+  }
+
+  // kld-fixback: 部署使用统计上报模块（usage-contract/usage-reporter/user-config）
+  // 这些模块被部署后的 skywalk-sdd/log.cjs（即 index.cjs 副本）在 cmdStart 中 require，
+  // 缺失时会上报静默失效。三件套必须同时部署，路径与 npm 包内布局一致。
+  const usageModules = [
+    { src: 'usage-contract.cjs', desc: '使用统计契约（七值/Device/ApiResponse/HTTP）' },
+    { src: 'usage-reporter.cjs', desc: '使用事件上报器（3s deadline + pending 队列）' },
+    { src: 'user-config.cjs', desc: '用户级配置（~/.kld-sdd/config.json + cli_token）' },
+  ];
+  for (const mod of usageModules) {
+    const src = path.join(pkgPath, 'skywalk-sdd', 'lib', mod.src);
+    const dst = path.join(sharedLibDir, mod.src);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dst);
+      deployedModules += 1;
+      vlog(`   ✓ 部署 skywalk-sdd/lib/${mod.src}（${mod.desc}）`);
+    } else {
+      console.log(`   ⚠️  ${mod.src} 源文件缺失，使用统计上报将不可用`);
+    }
+  }
+
   const packageVersion = require(path.join(pkgPath, 'package.json')).version;
   const runtimeMetadataDst = path.join(dataDir, 'runtime-metadata.cjs');
   fs.writeFileSync(
@@ -838,13 +923,15 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
     `'use strict';\nmodule.exports = { resolveRuntimeMetadata() { return { version: '${packageVersion}', producer: 'kld-sdd@${packageVersion}' }; } };\n`,
     'utf8',
   );
-  console.log(`   ✓ 部署 kld-sdd 运行时身份（${packageVersion}）`);
+  deployedModules += 1;
+  vlog(`   ✓ 部署 kld-sdd 运行时身份（${packageVersion}）`);
 
   const reportingSrc = path.join(pkgPath, 'skywalk-sdd', 'reporting');
   const reportingDst = path.join(dataDir, 'reporting');
   if (fs.existsSync(reportingSrc)) {
     copyDir(reportingSrc, reportingDst);
-    console.log('   ✓ 部署 skywalk-sdd/reporting/（V3 单次变更报告）');
+    deployedModules += 1;
+    vlog('   ✓ 部署 skywalk-sdd/reporting/（V3 单次变更报告）');
   } else {
     throw new Error(`E_INIT_MISSING_CRITICAL: reporting/ 目录缺失: ${reportingSrc}（归档报告生成将失败）`);
   }
@@ -853,7 +940,8 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   const contextClientDst = path.join(dataDir, 'context-client.cjs');
   if (fs.existsSync(contextClientSrc)) {
     fs.copyFileSync(contextClientSrc, contextClientDst);
-    console.log('   ✓ 部署 skywalk-sdd/context-client.cjs（工程 Spec 上下文客户端）');
+    deployedModules += 1;
+    vlog('   ✓ 部署 skywalk-sdd/context-client.cjs（工程 Spec 上下文客户端）');
   } else {
     console.log(`   ⚠️  工程 Spec 上下文客户端缺失: ${contextClientSrc}`);
   }
@@ -862,7 +950,8 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   const ontologyDst = path.join(dataDir, 'ontology');
   if (fs.existsSync(ontologySrc)) {
     copyDir(ontologySrc, ontologyDst);
-    console.log('   ✓ 部署 skywalk-sdd/ontology/（本地本体语义运行时）');
+    deployedModules += 1;
+    vlog('   ✓ 部署 skywalk-sdd/ontology/（本地本体语义运行时）');
   } else {
     console.log(`   ⚠️  本体语义运行时缺失: ${ontologySrc}`);
   }
@@ -871,7 +960,8 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   const worktreeFinishDst = path.join(dataDir, 'apply-worktree-finish.cjs');
   if (fs.existsSync(worktreeFinishSrc)) {
     fs.copyFileSync(worktreeFinishSrc, worktreeFinishDst);
-    console.log('   ✓ 部署 skywalk-sdd/apply-worktree-finish.cjs（Apply 收尾脚本）');
+    deployedModules += 1;
+    vlog('   ✓ 部署 skywalk-sdd/apply-worktree-finish.cjs（Apply 收尾脚本）');
   } else {
     console.log('   ⚠️  apply-worktree-finish.cjs 源文件缺失，Apply 阶段收尾需要手动执行');
   }
@@ -880,16 +970,40 @@ function deployTelemetryDataDir(targetCwd = process.cwd()) {
   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）');
+    deployedModules += 1;
+    vlog('   ✓ 部署 skywalk-sdd/openspec-shim.cjs（openspec 包裹包路径 shim）');
   } else {
     console.log('   ⚠️  openspec-shim.cjs 源文件缺失，openspec 命令需要手动 cd 到 spec 包执行');
   }
 
-  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）时自动创建');
+  // 部署 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);
+    deployedModules += 1;
+    vlog('   ✓ 部署 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);
+    deployedModules += 1;
+    vlog('   ✓ 部署 skywalk-sdd/kb-sync-identity.cjs（KB 身份同步：重新入库前同步 version-id）');
+  } else {
+    console.log('   ⚠️  kb-sync-identity.cjs 源文件缺失，重新入库身份同步不可用');
+  }
+
+  console.log(`   ✓ 部署 skywalk-sdd/ 运行时（events/state 数据目录 + ${deployedModules} 个模块）`);
+  vlog('   ✓ 调用方式: node skywalk-sdd/log.cjs start|end|metrics|semantic-identity|semantic-reconcile|semantic-check');
+  vlog('   ✓ openspec: node skywalk-sdd/openspec-shim.cjs list（自动 cd 到 *-sdd-specs）');
+  vlog('   ✓ Spec Context: node skywalk-sdd/context-client.cjs --query="<自然语言需求>" --target-stage=spec');
+  vlog('   ✓ Apply worktree: record-base 在 §1.5；收尾 apply-worktree-finish.cjs --change=<name>');
+  vlog('   ℹ️  project-identity.json 将在首次配置 KB（opsx-kb-config）时自动创建');
   console.log('✅ Telemetry 已就绪（数据存储在 skywalk-sdd/，无需配置 MCP）');
   return true;
 }
@@ -990,7 +1104,9 @@ function deployCodeRepoHooks(codeRepoRoot, specRepoRoot, options = {}) {
   for (const script of hookScripts) {
     const src = path.join(gitHooksTemplateDir, script);
     const dst = path.join(specHooksDir, script);
-    if (fs.existsSync(src) && !fs.existsSync(dst)) {
+    // 删除 !fs.existsSync(dst) 条件：原逻辑只在目标不存在时复制，导致模板升级后 spec 仓不会拿到最新脚本。
+    // 现在始终覆盖，与 shell hook 的 marker 覆盖策略保持一致。
+    if (fs.existsSync(src)) {
       fs.copyFileSync(src, dst);
     }
   }
@@ -1053,8 +1169,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}`);
   }
@@ -1354,10 +1478,11 @@ function detectTools() {
 
 /**
  * 创建 / 更新 .gitignore
+ * @param {string} [cwd=process.cwd()]
  */
-function updateGitignore() {
-  const cwd = process.cwd();
-  const gitignorePath = path.join(cwd, '.gitignore');
+function updateGitignore(cwd = process.cwd()) {
+  const root = path.resolve(cwd);
+  const gitignorePath = path.join(root, '.gitignore');
   const requiredLines = [
     '.cursor/commands/personal-*',
     '.claude/commands/personal-*',
@@ -1366,6 +1491,10 @@ function updateGitignore() {
     '.kunlunzhima/commands/personal-*',
     '.workbuddy/commands/personal-*',
     '.agents/commands/personal-*',
+    'kb-state.json',
+    '**/kb-state.json',
+    'skywalk-sdd/kb-state.json',
+    '**/skywalk-sdd/kb-state.json',
     'skywalk-sdd/events/',
     'skywalk-sdd/state/',
     '**/skywalk-sdd/events/',
@@ -1383,6 +1512,12 @@ function updateGitignore() {
 .workbuddy/commands/personal-*
 .agents/commands/personal-*
 
+# KB 绑定状态（含 API Key，勿提交）
+kb-state.json
+**/kb-state.json
+skywalk-sdd/kb-state.json
+**/skywalk-sdd/kb-state.json
+
 # SDD Telemetry 数据（实体在 *-sdd-specs/skywalk-sdd/；工作区可能是 symlink）
 skywalk-sdd/events/
 skywalk-sdd/state/
@@ -1411,6 +1546,20 @@ skywalk-sdd/state/
   }
 }
 
+/**
+ * B1 汇总块绑定文案：已绑定显示用户，未绑定引导 auth login；不出现“使用统计”字样
+ */
+function formatBindingSummaryLine(bindingResult) {
+  if (
+    bindingResult
+    && (bindingResult.status === 'bound' || bindingResult.status === 'kept')
+    && bindingResult.userName
+  ) {
+    return `  ✓ 平台账号已绑定：${bindingResult.userName}`;
+  }
+  return '  6. 绑定平台账号：npx kld-sdd auth login';
+}
+
 /**
  * 显示帮助信息
  */
@@ -1426,6 +1575,7 @@ KLD SDD 项目初始化工具
 选项:
   -h, --help       显示帮助信息
   -v, --version    显示版本号
+  --verbose        输出每个安装文件/目录的明细日志（默认仅摘要，亦可用 KLD_SDD_VERBOSE=1）
   --skip-openspec  跳过 openspec init 步骤
   --skip-template  跳过复制内置模版
   --tool <name>     指定编辑器，可用值: cursor, claude, codebuddy, qoder, opencode, kunlunzhima, workbuddy, codex, all
@@ -1494,14 +1644,14 @@ async function main() {
   // 解析参数
   if (args.includes('-h') || args.includes('--help')) {
     showHelp();
-    rl.close();
+    closeRl();
     return;
   }
   
   if (args.includes('-v') || args.includes('--version')) {
     const pkg = require('../package.json');
     console.log(pkg.version);
-    rl.close();
+    closeRl();
     return;
   }
   
@@ -1520,7 +1670,7 @@ async function main() {
     selectedTools = parseSelectedTools(args) || await selectEditor();
   } catch (error) {
     console.error(`❌ ${error.message}`);
-    rl.close();
+    closeRl();
     process.exit(1);
   }
 
@@ -1640,7 +1790,7 @@ async function main() {
   }
 
   // 7. 更新工作目录 .gitignore
-  updateGitignore();
+  updateGitignore(workspaceRoot);
 
   // 8. 收尾：无论前面是否走过 symlink/旧副本路径，强制清掉工作区/Git 根多余 skywalk-sdd/
   if (specPackage && fs.existsSync(specPackage.abs)) {
@@ -1648,6 +1798,23 @@ async function main() {
   }
   removeOuterSkywalk(workspaceRoot);
 
+  // 9. B1 账号绑定向导（部署完成后、最终汇总前；--skip-auth/非 TTY 自动跳过；失败不阻塞 init）
+  const bindingController = new AbortController();
+  const onBindingSigint = () => bindingController.abort();
+  process.on('SIGINT', onBindingSigint);
+  let bindingResult = null;
+  try {
+    bindingResult = await runAccountBinding({
+      ask,
+      skipAuth: args.includes('--skip-auth'),
+      signal: bindingController.signal,
+    });
+  } catch (error) {
+    console.log(`⚠️  账号绑定向导异常（${error && error.message ? error.message : error}），已跳过`);
+  } finally {
+    process.removeListener('SIGINT', onBindingSigint);
+  }
+
   const selectedNames = selectedTools.map(t => TOOL_CONFIGS[t].name).join(', ');
 
   console.log();
@@ -1685,7 +1852,7 @@ async function main() {
     console.log('  📌 .sdd-spec-root → 包裹包；无根目录 skywalk-sdd/');
   }
   if (selectedTools.includes('kunlunzhima')) {
-    console.log('  📎 .kunlunzhima/commands/opsx/    # KunlunZhima OPSX command bridge（12 个）');
+    console.log('  📎 .kunlunzhima/commands/opsx/    # KunlunZhima OPSX command bridge（13 个）');
     console.log('  ℹ️  KunlunZhima 通过 commands/skills 入口使用 SDD，未启用自动 Hook');
   }
   if (selectedTools.includes('codebuddy')) {
@@ -1696,20 +1863,23 @@ async function main() {
   }
   console.log();
   
-  // 统一的 skill 格式说明
-  console.log('可用 skills（opsx-* 系列，14 个 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）');
+  // 统一的 skill 格式说明（默认单行指引，完整列表走 --verbose）
+  console.log('可用 skills：opsx-* 系列 15 个 SDD skills（--verbose 查看完整列表，或见 openspec/kld-sdd操作手册.html）');
+  vlog('  opsx-propose           - 创建业务意图文档（Why）');
+  vlog('  opsx-spec              - 创建技术契约文档（What）');
+  vlog('  opsx-design            - 创建技术实现方案（How）');
+  vlog('  opsx-task              - 拆解AI编码任务（Do）');
+  vlog('  opsx-check             - 质量门禁检查（Verify）');
+  vlog('  opsx-apply             - 申请变更实施（Apply）');
+  vlog('  opsx-test              - 执行单元测试（Test）');
+  vlog('  opsx-archive           - 归档变更（Archive）');
+  vlog('  opsx-explore           - 浏览变更状态（Explore）');
+  vlog('  opsx-knowledge         - 业务知识库检索（辅助）');
+  vlog('  opsx-rules             - 生成/更新 Agent 规则（辅助）');
+  vlog('  opsx-consistency-check - Spec 一致性校验（代码 vs spec）');
+  vlog('  opsx-kb-config         - 知识库配置（API Key + Space/KB 选择）');
+  vlog('  opsx-ontology-query    - 本体知识库查询');
+  vlog('  opsx-kb-ingest         - 知识库入库（zip / 文件夹上传）');
     
   console.log();
   console.log('后续步骤:');
@@ -1722,14 +1892,18 @@ 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 配置知识库）');
+  // B1: 汇总块绑定文案（不出现“使用统计”字样）
+  console.log(formatBindingSummaryLine(bindingResult));
   if (selectedTools.includes('codebuddy')) {
-    console.log('  5. CodeBuddy 用户：SDD Hook Pack 已随初始化自动部署，门禁自动生效，无需手动配置');
+    console.log('  - CodeBuddy 用户：SDD Hook Pack 已随初始化自动部署，门禁自动生效，无需手动配置');
   }
   if (selectedTools.includes('kunlunzhima')) {
-    console.log('  5. KunlunZhima 用户：在 Craft 模式使用 /opsx:propose 等 OPSX 命令（.kunlunzhima/commands/opsx/）');
+    console.log('  - KunlunZhima 用户：在 Craft 模式使用 /opsx:propose 等 OPSX 命令（.kunlunzhima/commands/opsx/）');
   }
   if (selectedTools.includes('opencode')) {
-    console.log('  5. OpenCode 用户：用 /opsx-propose 或 /skills 启动 SDD（.opencode/skills/opsx-*/，skill 即斜杠命令）');
+    console.log('  - OpenCode 用户：用 /opsx-propose 或 /skills 启动 SDD（.opencode/skills/opsx-*/，skill 即斜杠命令）');
   }
   console.log();
   console.log('📊 SDD Telemetry（嵌入在 skill 流程中，自动执行，无需配置）：');
@@ -1741,16 +1915,24 @@ async function main() {
   console.log('  - 运行 node skywalk-sdd/log.cjs metrics --project=<包裹包> 查看四维度指标');
   console.log();
 
-  rl.close();
+  closeRl();
 }
 
+// kld-T06: Progress Runtime 已删除，用户级 workspace 注册函数一并移除。
+// 用户级 Device Flow 绑定由 lib/device-auth.js + skywalk-sdd/lib/user-config.cjs 负责，
+// 通过 `kld-sdd auth login` 显式触发。
+
 module.exports = {
   main,
   detectTools,
   getTemplatePath,
   getPackagePath,
   selectEditor,
+  isVerbose,
+  vlog,
+  formatBindingSummaryLine,
   deployOpsxSkills,
+  copyTemplatesToProject,
   deployProfileArtifacts,
   deploySddGuideManual,
   deployModulesYaml,
@@ -1762,6 +1944,7 @@ module.exports = {
   removeOuterSkywalk,
   deployQualityGateTemplates,
   deployTelemetryDataDir,
+  updateGitignore,
   attachCodeRepoLite,
   syncWorkspaceRepos,
   copyDirRendered,

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,6 +36,7 @@ const OPSX_SKILL_DIRS = [
   'opsx-knowledge',
   'opsx-rules',
   // Engineering KB 依赖技能（随 init 部署；propose/spec/archive 硬依赖）
+  'opsx-kb-config',
   'opsx-ontology-query',
   'opsx-kb-ingest',
   // Spec 一致性校验技能
@@ -104,6 +121,7 @@ const KUNLUN_SLASH_COMMANDS = [
   'explore',
   'ontology-query',
   'kb-ingest',
+  'kb-config',
   'consistency-check',
 ];
 
@@ -128,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 的多代理能力启动恰好一个独立评审子代理，并传入所需文件而不是作者对话；不得让评审子代理再次委派。',
     },
   },
 });