kld-sdd 2.7.8 → 2.8.0

package/lib/uninstall.js

@@ -0,0 +1,453 @@
+/** 只卸载可识别的 SDD 工具；文档、配置、数据和仓库关联始终保留。 */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { isManagedBridgeFile } = require('./command-bridge');
+const { PROVIDERS, stripManagedHooks } = require('./settings-merge');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const maintenance = require('./maintenance');
+const packageRoot = path.resolve(__dirname, '..');
+const { getToolProfile, listToolProfileIds, buildToolConfigs } = require('./tool-profiles');
+const sddConfig = require('../skywalk-sdd/ontology/sdd-config.cjs');
+const workspaceLayout = require('./workspace-layout');
+// spec 候选枚举的唯一入口（含 tier 分级与排序）
+const specDetect = require('../skywalk-sdd/ontology/spec-detect.cjs');
+
+/** 卸载模式 */
+const MODE = Object.freeze({
+  /** 只删工具内容，保留用户配置与运行时数据 */
+  TOOLS_ONLY: 'tools-only',
+});
+
+/** 操作类型（用于计划与摘要） */
+const OP = Object.freeze({
+  DELETE_FILE: 'delete-file',
+  STRIP_HOOKS: 'strip-hooks',
+  KEEP: 'keep',
+});
+
+/** .gitignore 中 SDD 块的起始标记 */
+const GITIGNORE_MARKER = 'KLD SDD';
+
+function createPlan(root = null) {
+  return { ops: [], warnings: [], root: root ? path.resolve(root) : null };
+}
+
+function addOp(plan, op, target, reason) {
+  plan.ops.push({ op, target, reason });
+}
+
+function warn(plan, message) {
+  plan.warnings.push(message);
+}
+
+/** 列出目录下所有文件（递归），目录不存在返回空 */
+function listFilesRecursive(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    const p = path.join(dir, name);
+    let st;
+    try {
+      st = fs.lstatSync(p);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      out.push(...listFilesRecursive(p));
+    } else {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/** 按随包工具文件清单逐文件清理，未知文件和用户添加的文件不删。 */
+function planOwnedFiles(plan, source, target, reason) {
+  for (const rel of maintenance.filesUnder(source)) {
+    // Skill 的本地检索配置可能包含连接信息，不作为工具脚本清理。
+    if (path.basename(rel) === 'config.json') continue;
+    if (maintenance.regularFileWithin(target, rel)) addOp(plan, OP.DELETE_FILE, path.join(target, rel), reason);
+  }
+}
+
+function planProfileArtifacts(plan, toolKey, cwd) {
+  const profile = getToolProfile(toolKey);
+  const config = buildToolConfigs()[toolKey];
+  if (!config) return;
+  if (profile.skillsDir) {
+    planOwnedFiles(plan, path.join(packageRoot, 'templates/skills/kld-sdd'), path.join(cwd, profile.skillsDir), `${config.name} SDD skill 文件`);
+  }
+  if (profile.requiresCommandBridge && profile.opsxCommandsDir) {
+    const root = path.join(cwd, profile.opsxCommandsDir);
+    for (const rel of maintenance.filesUnder(root)) {
+      if (!rel.endsWith('.md') || !maintenance.regularFileWithin(cwd, path.relative(cwd, path.join(root, rel)))) continue;
+      const file = path.join(root, rel);
+      if (isManagedBridgeFile(fs.readFileSync(file, 'utf8'))) addOp(plan, OP.DELETE_FILE, file, 'SDD command bridge');
+    }
+  }
+  if (profile.hookProvider && profile.hookProvider !== 'none') {
+    planOwnedFiles(plan, path.join(packageRoot, 'templates/hooks', profile.hookProvider, 'hooks'), path.join(cwd, profile.configDir, 'hooks'), `${config.name} SDD hook`);
+    const relative = path.join(profile.configDir, 'settings.json');
+    if (maintenance.regularFileWithin(cwd, relative)) addOp(plan, OP.STRIP_HOOKS, path.join(cwd, relative), '仅摘除 SDD 受管 hook');
+  }
+  // rules 由用户或 Agent 编写，不因名称带 sdd/opsx 就删除。
+}
+
+function planSpecPackage(plan, specRoot) {
+  if (!specRoot || !fs.existsSync(specRoot)) return;
+  for (const file of maintenance.runtimeToolFiles(path.join(specRoot, 'skywalk-sdd'))) {
+    addOp(plan, OP.DELETE_FILE, file, 'SDD 运行工具');
+  }
+  planOwnedFiles(plan, path.join(packageRoot, 'templates/openspec'), path.join(specRoot, 'openspec-templates'), 'SDD 只读模板');
+  for (const name of ['openspec', 'modules.yaml', 'sdd.config.yaml', 'kb-state.json', 'skywalk-sdd/events', 'skywalk-sdd/state', 'skywalk-sdd/project-identity.json', 'skywalk-sdd/git-hooks/hooks.config']) {
+    const target = path.join(specRoot, name);
+    if (fs.existsSync(target)) addOp(plan, OP.KEEP, target, '项目文档、配置或历史数据');
+  }
+  // 即使没有文档，也不删除 Spec 仓根目录及 .git。
+  addOp(plan, OP.KEEP, specRoot, 'Spec 仓库目录');
+}
+
+function planCodeRepo(plan, repoRoot) {
+  if (!repoRoot || !fs.existsSync(repoRoot)) return;
+  for (const name of ['.sdd.yaml', '.sdd-spec-root', '.sdd-workspace.yaml', '.gitignore']) {
+    const target = path.join(repoRoot, name);
+    if (fs.existsSync(target)) addOp(plan, OP.KEEP, target, '保留关联配置与隐私数据忽略规则');
+  }
+  // 与安装器一样尊重 Hook 管理器、worktree 和自定义 Hook。
+  if (!workspaceLayout.isGitRepo(repoRoot) || sddConfig.gitConfig(repoRoot, 'core.hooksPath')) return;
+  const known = require('./managed-hook-hashes.json');
+  for (const name of ['commit-msg', 'pre-commit', 'pre-push']) {
+    let target;
+    try {
+      const value = execFileSync('git', ['rev-parse', '--git-path', `hooks/${name}`], { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+      target = path.resolve(repoRoot, value);
+    } catch { continue; }
+    if (!target.startsWith(path.resolve(repoRoot) + path.sep)) {
+      addOp(plan, OP.KEEP, target, '其他 worktree 共用的 Git Hook；请从主仓库管理');
+      continue;
+    }
+    const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+    if (!stat || !stat.isFile() || !fs.lstatSync(path.dirname(target)).isDirectory()) continue;
+    const hash = content => crypto.createHash('sha256').update(content).digest('hex');
+    const current = hash(fs.readFileSync(target));
+    const template = hash(fs.readFileSync(path.join(packageRoot, 'templates/git-hooks', name)));
+    if (current === template || (known[name] || []).includes(current)) addOp(plan, OP.DELETE_FILE, target, '完整匹配已发布的 SDD Hook');
+    else addOp(plan, OP.KEEP, target, '自定义或未知 Hook，请自行审阅其中的 SDD 调用');
+  }
+}
+
+/**
+ * 生成卸载计划（纯计算，不落盘）
+ *
+ * @param {object} options
+ * @param {string} options.cwd 工作目录（代码仓 / 工作区根）
+ * @param {string[]} [options.tools] 要卸载的编辑器，缺省=全部
+ * @param {string} [options.mode] MODE.TOOLS_ONLY（唯一支持的方式）
+ * @param {string} [options.specRoot] 已确认的 spec 包裹包目录（CLI 交互层选定后传入）；
+ *   缺省时仅按权威来源（.sdd-spec-root → git config）保守定位
+ * @returns {{ok: boolean, plan: object, specRoot: string|null, message?: string}}
+ */
+function buildUninstallPlan(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  if (options.mode && options.mode !== MODE.TOOLS_ONLY) throw new Error('仅支持工具卸载；不允许删除 Spec 文档、配置和历史数据');
+  const mode = MODE.TOOLS_ONLY;
+  const tools = Array.isArray(options.tools) && options.tools.length
+    ? options.tools
+    : listToolProfileIds();
+
+  const plan = createPlan(cwd);
+  plan.tools = tools;
+
+  // 编辑器专属产物：工作区根 / 当前目录
+  for (const toolKey of tools) {
+    planProfileArtifacts(plan, toolKey, cwd);
+  }
+
+  // spec 仓：优先用调用方（CLI 交互层）已确认的目录；
+  // 未指定时才自行定位 —— 此时仅取「权威来源」，不做全目录扫描。
+  // 定位职责已上移到 bin 层（listSpecCandidates + 用户单选 + 确认），
+  // 见 listSpecCandidatesForUninstall。本函数只接收结果，不猜。
+  const specRoot = options.specRoot
+    ? path.resolve(options.specRoot)
+    : resolveSpecRootForUninstall(cwd);
+  if (specRoot) {
+    plan.specRoot = path.resolve(specRoot);
+    const relative = path.relative(cwd, specRoot);
+    const sharedExternal = relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative);
+    if (sharedExternal) {
+      addOp(plan, OP.KEEP, specRoot, '工作目录外的共享 Spec，仅卸载当前代码仓工具');
+      warn(plan, '共享 Spec 位于当前目录之外，运行工具与文档均保留；如需卸载共享工具，请从所属工作区操作');
+    } else {
+      planSpecPackage(plan, specRoot);
+      planCodeRepo(plan, specRoot);
+    }
+    // spec 仓自身的 .git/hooks（init 装的 commit-msg / pre-commit / pre-push）
+    // 是工具产物，须摘除 —— 与代码仓共用同一套受管标记判据，
+    // 非受管 hook 与 .git 其余内容一律保留。
+  } else {
+    warn(plan, '未定位到 spec 包裹包：spec 侧产物（skywalk-sdd/、openspec/ 等）未纳入计划');
+  }
+
+  // 代码仓 / 工作区根
+  planCodeRepo(plan, cwd, { mode });
+
+  // 工作区模式：子代码仓也要摘 hook。
+  //
+  // 排除所有 spec 候选目录：detectWorkspaceLayout 只挑一个作为 specRepo，
+  // 其余候选（如用户复制的 `erp-sdd-specs copy`）会被误归入 codeRepos，
+  // 进而被 planCodeRepo 摘掉 .git/hooks/ —— 那不是代码仓，是 spec 仓库/备份。
+  const layout = workspaceLayout.detectWorkspaceLayout(cwd);
+  if (layout.isWorkspace) {
+    const specDirs = new Set(
+      listSpecCandidatesForUninstall(cwd).map((c) => path.resolve(c.abs)),
+    );
+    if (specRoot) specDirs.add(path.resolve(specRoot));
+    for (const repo of layout.codeRepos) {
+      if (specDirs.has(path.resolve(repo.abs))) continue;
+      if (!specRoot || maintenance.associationConflict(repo.abs, specRoot)) {
+        warn(plan, `保留代码仓 ${repo.name}：未确认属于所选 Spec`);
+        continue;
+      }
+      const linked = sddConfig.gitConfig(repo.abs, 'sdd.specPath');
+      const yaml = sddConfig.loadSddYaml(repo.abs);
+      if (!linked && !yaml.ok) continue;
+      planCodeRepo(plan, repo.abs);
+    }
+  }
+
+  // 不沿中间符号链接删除文件；同一个文件仅处理一次。
+  const seen = new Set();
+  plan.ops = plan.ops.filter(item => {
+    const key = item.op + ':' + item.target;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    if (item.op === OP.KEEP) return true;
+    const root = specRoot && item.target.startsWith(path.resolve(specRoot) + path.sep) ? path.resolve(specRoot) : cwd;
+    // Git worktree 的 hooks 位于 common git dir，已单独校验完整内容。
+    if (item.reason !== '完整匹配已发布的 SDD Hook' && !maintenance.regularFileWithin(root, path.relative(root, item.target))) return false;
+    item.digest = crypto.createHash('sha256').update(fs.readFileSync(item.target)).digest('hex');
+    return true;
+  });
+  return { ok: true, plan, specRoot: specRoot || null, mode };
+}
+
+/**
+ * 枚举待卸载的 spec 包裹包候选（供 CLI 交互层让用户单选）。
+ *
+ * 返回全部候选并标注来源，由用户裁决；`erp-sdd-specs copy` 这类用户备份
+ * 会作为 'scan' 候选被列出，而不是被静默删除。
+ *
+ * 委托 `spec-detect.detectSpecCandidatesWithGit` —— 与 init 侧共用唯一入口。
+ *
+ * @param {string} cwd 工作目录
+ * @returns {Array<{abs: string, name: string, source: string, tier: number, evidence: string[]}>}
+ */
+function listSpecCandidatesForUninstall(cwd) {
+  return specDetect.detectSpecCandidatesWithGit(cwd || process.cwd());
+}
+
+/**
+ * 保守定位 spec 包裹包：仅取**权威来源**（.sdd-spec-root → git config）。
+ *
+ * 不复用 `findNestedSpecPackage` 的扫描来源 —— 判据命中不等于「当前项目的
+ * spec 仓」（用户备份同样命中）。需要扫描裁决时，由 CLI 层走
+ * `listSpecCandidatesForUninstall` + 用户单选。
+ *
+ * 实现上复用 `listSpecCandidatesForUninstall` 并筛出权威来源，而不是另写一遍
+ * hint / git config 的读取逻辑 —— 历史上这里是第二份实现，导致「卸载比 init
+ * 少认来源」（如 init 认 `.sdd.yaml mono`，卸载不认）的漂移。
+ * 候选已按 tier → 来源优先级排序，故 hint 天然优先于 git。
+ *
+ * @param {string} cwd 工作目录
+ * @returns {string|null} 权威来源指向的 spec 根；无权威来源时 null
+ */
+function resolveSpecRootForUninstall(cwd) {
+  const authoritative = listSpecCandidatesForUninstall(cwd)
+    .find((c) => c.source === 'hint' || c.source === 'git');
+  return authoritative ? path.resolve(authoritative.abs) : null;
+}
+
+/** 从 .gitignore 摘除 SDD 块（保留其余行） */
+function stripGitignoreBlock(filePath) {
+  const original = fs.readFileSync(filePath, 'utf8');
+  const lines = original.split(/\r?\n/);
+  const kept = [];
+  let skipping = false;
+  let removed = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // SDD 块由注释标题开头，遇到下一个非 SDD 注释标题或空行段落结束
+    if (/^#\s*KLD SDD/.test(trimmed)) {
+      skipping = true;
+      removed += 1;
+      continue;
+    }
+    if (skipping) {
+      // 块内：注释、空行、SDD 相关忽略行
+      if (trimmed === '' || trimmed.startsWith('#')) {
+        if (trimmed.startsWith('#') && !/SDD|Telemetry|Apply|KB 绑定/.test(trimmed)) {
+          // 遇到无关注释 → 块结束
+          skipping = false;
+          kept.push(line);
+          continue;
+        }
+        removed += 1;
+        continue;
+      }
+      if (/^(\.?[\w.*/-]*)(sdd|skywalk|worktrees|kb-state)/i.test(trimmed)
+        || /sdd/i.test(trimmed) || /skywalk/i.test(trimmed)
+        || /^\.worktrees\//.test(trimmed) || /personal-\*$/.test(trimmed)) {
+        removed += 1;
+        continue;
+      }
+      skipping = false;
+      kept.push(line);
+      continue;
+    }
+    kept.push(line);
+  }
+
+  const next = kept.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '') + '\n';
+  return { changed: removed > 0 && next !== original, next, removed };
+}
+
+/** 从 settings.json 摘除受管 hook */
+function stripSettingsHooks(filePath, provider) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+  } catch {
+    return { ok: false, error: '不是合法 JSON，已跳过（请手工处理）' };
+  }
+  const stripped = stripManagedHooks(settings, provider);
+  const next = JSON.stringify(stripped, null, 2) + '\n';
+  if (next === raw) return { ok: true, changed: false };
+  fs.writeFileSync(filePath, next, 'utf8');
+  return { ok: true, changed: true };
+}
+
+/** 判断目录是否为空 */
+function isEmptyDir(dir) {
+  try {
+    return fs.existsSync(dir) && fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** provider 判定：从 settings.json 路径反推 */
+function providerFromSettingsPath(settingsPath) {
+  return /\.claude[\\/]/.test(settingsPath) ? PROVIDERS.CLAUDE : PROVIDERS.CODEBUDDY;
+}
+
+/** 执行前重新校验白名单和文件快照，拒绝旧全量计划以及预览后的变更。 */
+function applyUninstallPlan(plan, options = {}) {
+  const log = typeof options.log === 'function' ? options.log : console.log;
+  const errors = [];
+  if (!plan || !plan.root || !Array.isArray(plan.ops)) return { ok: false, applied: 0, skipped: 0, errors: ['卸载计划无效，请重新预览'] };
+  const fresh = buildUninstallPlan({ cwd: plan.root, specRoot: plan.specRoot, tools: plan.tools }).plan;
+  const allowed = new Map(fresh.ops.filter(item => item.op !== OP.KEEP).map(item => [item.op + ':' + item.target, item]));
+  for (const item of plan.ops) {
+    if (item.op === OP.KEEP) continue;
+    const current = allowed.get(item.op + ':' + item.target);
+    if (!current || !item.digest || current.digest !== item.digest) errors.push(`${item.target}: 范围或内容已变化，请重新预览`);
+  }
+  if (errors.length) return { ok: false, applied: 0, skipped: 0, errors };
+  let applied = 0;
+  let skipped = 0;
+  for (const item of plan.ops) {
+    if (item.op === OP.KEEP) { skipped++; continue; }
+    try {
+      // 执行时再检查一次，不接受被替换为链接的文件。
+      const stat = fs.lstatSync(item.target);
+      if (!stat.isFile() || crypto.createHash('sha256').update(fs.readFileSync(item.target)).digest('hex') !== item.digest) throw new Error('文件已变化，请重新预览');
+      if (options.dryRun) { log(`   将处理 ${item.target}`); applied++; continue; }
+      if (item.op === OP.DELETE_FILE) { fs.unlinkSync(item.target); applied++; }
+      else if (item.op === OP.STRIP_HOOKS) {
+        const result = stripSettingsHooks(item.target, providerFromSettingsPath(item.target));
+        if (!result.ok) throw new Error(result.error);
+        if (result.changed) applied++; else skipped++;
+      }
+    } catch (error) { errors.push(`${item.target}: ${error.message}`); }
+  }
+  // 只收起因工具文件删除而变空的目录；根目录、Spec、数据目录保持原样。
+  if (!options.dryRun) {
+    const roots = [plan.root, plan.specRoot].filter(Boolean).map(p => path.resolve(p));
+    const kept = plan.ops.filter(i => i.op === OP.KEEP).map(i => path.resolve(i.target));
+    for (const item of plan.ops.filter(i => i.op === OP.DELETE_FILE && !i.target.includes(`${path.sep}.git${path.sep}`))) {
+      let dir = path.dirname(item.target);
+      while (roots.some(root => dir.startsWith(root + path.sep)) && !roots.includes(dir)) {
+        if (kept.some(p => p === dir || p.startsWith(dir + path.sep))) break;
+        if (!isEmptyDir(dir)) break;
+        fs.rmdirSync(dir);
+        dir = path.dirname(dir);
+      }
+    }
+  }
+  return { ok: errors.length === 0, applied, skipped, errors };
+}
+
+/** 卸载方式的中文标签（供 CLI 层复用，避免文案漂移） */
+function modeLabel() {
+  return '卸载工具（保留 Spec 文档、配置与历史数据）';
+}
+
+/**
+ * 卸载执行（纯业务，无交互）
+ *
+ * CLI 参数解析与全部交互（方式选择 / 预览 / 确认）都在 bin/ 层完成；
+ * 本函数只接收已解析的选项对象，不读取 process.argv，也不询问用户。
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]    工作目录（代码仓 / 工作区根），缺省 process.cwd()
+ * @param {string[]} [opts.tools] 要卸载的编辑器 id 列表，缺省=全部
+ * @param {string} [opts.mode]   MODE.TOOLS_ONLY（唯一支持的方式）
+ * @param {boolean} [opts.dryRun] 只打印计划，不落盘
+ * @param {object} [opts.plan]   复用调用方已算好的计划（避免重复计算）
+ * @param {boolean} [opts.showWarnings] 是否打印 plan.warnings，缺省 true
+ * @returns {{ok: boolean, applied: number, skipped: number, errors: string[]}}
+ */
+function main(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  if (opts.mode && opts.mode !== MODE.TOOLS_ONLY) throw new Error('仅支持工具卸载');
+  const mode = MODE.TOOLS_ONLY;
+
+  const plan = opts.plan || buildUninstallPlan({ cwd, tools: opts.tools, mode }).plan;
+  const result = applyUninstallPlan(plan, { dryRun: Boolean(opts.dryRun) });
+
+  // 交互路径下 CLI 层已用 printPlanPreview 打过同一份 warnings，
+  // 由调用方传 showWarnings:false 避免重复刷屏；非交互路径缺省照常打印。
+  if (opts.showWarnings !== false && plan.warnings.length) {
+    console.log('');
+    for (const w of plan.warnings) console.log(`⚠️  ${w}`);
+  }
+
+  console.log('');
+  console.log(`${result.ok ? '✅ 完成' : '❌ 未完整卸载'}：处理 ${result.applied} 项，保留 ${result.skipped} 项`);
+  if (result.errors.length) {
+    console.log(`⚠️  ${result.errors.length} 项失败：`);
+    for (const e of result.errors) console.log(`   - ${e}`);
+  }
+  if (opts.dryRun) {
+    console.log('');
+    console.log('ℹ️  这是预演结果，未修改任何文件。去掉 --dry-run 执行实际卸载。');
+  }
+  return result;
+}
+
+module.exports = {
+  MODE,
+  OP,
+  modeLabel,
+  main,
+  buildUninstallPlan,
+  applyUninstallPlan,
+  stripGitignoreBlock,
+  listSpecCandidatesForUninstall,
+};

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "kld-sdd",
-  "version": "2.7.8",
+  "version": "2.8.0",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 一键部署 SDD skills",
-  "main": "index.js",
+  "main": "lib/init.js",
   "bin": {
     "kld-sdd": "bin/kld-sdd-init.js",
     "kld-sdd-init": "bin/kld-sdd-init.js"
   },
   "scripts": {
     "bench:check": "node test/benchmark-check.cjs",
-    "test": "node --test test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/prompt-spec-path.cjs && node test/workspace-layout.cjs && node test/ontology-release-blockers.cjs && node test/ontology-semantic-core.cjs && node test/ontology-identity-versioning.cjs && node test/ontology-identity-continuity.cjs && node test/ontology-state-transaction.cjs && node test/ontology-process-concurrency.cjs && node test/ontology-observer-convergence.cjs && node test/ontology-working-runtime.cjs && node test/ontology-stage-materialization.cjs && node test/ontology-template-contract.cjs && node test/ontology-cli-archive.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs && node test/init-report-runtime.cjs && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs skywalk-sdd/usage-reporter.test.cjs skywalk-sdd/usage-reporting.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
+    "test": "node --test test/delivery-hooks.test.cjs test/execution-friction.test.cjs test/kb-fact-lifecycle.test.cjs test/workflow-usability.test.cjs test/check-efficiency.test.cjs && node test/external-key.cjs && node test/change-key.cjs && node test/modules-and-sdd-config.cjs && node test/active-changes.cjs && node test/hook-layouts.cjs && node test/spec-package-init.cjs && node test/prompt-spec-path.cjs && node test/spec-detect.cjs && node test/workspace-layout.cjs && node test/sync-repos-spec-choice.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/spec-ontology-compatibility.cjs && node test/archive-package-producer.cjs && node --test test/evidence-integrity-oracle.cjs test/evidence-integrity-wiring.cjs test/change-report-correctness.cjs test/report-metrics-correctness.cjs test/change-report-model-ui.cjs && node test/validate-skills-bundle.cjs && node test/tool-profiles.cjs && node test/deploy-strategy.cjs && node test/uninstall.cjs && node --test test/maintenance.test.cjs && node test/settings-merge.cjs && node test/command-bridge.cjs && node test/codebuddy-hooks.cjs && node test/skill-content-contract.cjs && node test/init-agent-profiles.cjs && node test/init-report-runtime.cjs && node test/init-output-verbosity.cjs && node --test test/usage-contract.test.cjs test/user-config.test.cjs test/usage-runtime-removal.test.cjs test/runtime/usage-reporter.test.cjs test/runtime/usage-reporting.test.cjs test/runtime/git-identity.test.cjs test/runtime/kb-state-location.test.cjs && node test/runtime/metrics-v3.test.cjs && node test/runtime/fixback.test.cjs && node test/progress-package-artifact.test.cjs && node --test test/progress-package-install.e2e.cjs && node test/consistency-check-core.cjs"
   },
   "keywords": [
     "kld",
@@ -46,5 +46,8 @@
     "skywalk-sdd/kb-sync-identity.cjs",
     "README.md",
     "USABILITY.md"
-  ]
+  ],
+  "sddMaintenance": {
+    "toolOnly": 1
+  }
 }

package/skywalk-sdd/context-client.cjs

@@ -37,6 +37,9 @@ function buildEndpoint(apiBase, spaceId, kbId, mode) {
   if (mode === 'resolve') {
     return `${base}/v1/spaces/${space}/knowledge-bases/${kb}/entities/resolve`;
   }
+  if (mode === 'spec-generation') {
+    return `${base}/v1/spaces/${space}/knowledge-bases/${kb}/context/spec-generation`;
+  }
   return `${base}/v1/spaces/${space}/knowledge-bases/${kb}/context/match-requirement`;
 }
 
@@ -61,7 +64,14 @@ function compactContext(data, includeCandidates, mode = 'match') {
     warnings: data.warnings,
     clarificationQuestions: data.clarificationQuestions,
     specGenerationContext: data.specGenerationContext,
+    matchedCapabilities: data.matchedCapabilities,
+    matchedScenarios: data.matchedScenarios,
+    businessObjects: data.businessObjects,
+    rules: data.rules,
+    specPatterns: data.specPatterns,
+    compatibilityMode: data.compatibilityMode,
     supportEvidence: data.supportEvidence,
+    candidateEvidence: data.candidateEvidence,
     oppositionEvidence: data.oppositionEvidence,
   };
   // Continuity resolve 必须透出 candidates；match 默认隐藏内部候选除非 --include-candidates
@@ -171,19 +181,40 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
     return { ...unavailableContext('engineering_kb_not_configured', 'KB 尚未配置，本地工作可以继续'), configured: false };
   }
 
-  const mode = String(args.mode || 'match').trim().toLowerCase() === 'resolve' ? 'resolve' : 'match';
+  const requestedMode = String(args.mode || 'match').trim().toLowerCase();
+  const mode = requestedMode === 'resolve'
+    ? 'resolve'
+    : (['spec-generation', 'spec_generation', 'generation'].includes(requestedMode)
+      ? 'spec-generation' : 'match');
   const timeoutMs = contextTimeout(args, env, 5000);
   const payload = buildPayload(args, mode);
-  const data = await requestJson(
-    buildEndpoint(apiBase, spaceId, kbId, mode),
-    payload,
-    token,
-    timeoutMs,
-  );
+  let responseMode = mode;
+  let data;
+  try {
+    data = await requestJson(
+      buildEndpoint(apiBase, spaceId, kbId, mode),
+      payload,
+      token,
+      timeoutMs,
+    );
+  } catch (error) {
+    const endpointUnavailable = /Not Found|HTTP 404/i.test(error.message);
+    if (mode !== 'spec-generation' || !endpointUnavailable) throw error;
+    data = await requestJson(
+      buildEndpoint(apiBase, spaceId, kbId, 'match'),
+      payload,
+      token,
+      timeoutMs,
+    );
+    responseMode = 'match';
+  }
   return {
     available: true,
     mode,
+    responseMode,
+    remoteContextVerified: true,
     ...compactContext(data, Boolean(args['include-candidates']), mode),
+    compatibilityMode: responseMode === mode ? (data.compatibilityMode || 'NATIVE') : 'LEGACY_V2',
   };
 }