devassist-agent 1.0.0

package/src/cli/commands/ai.js

@@ -0,0 +1,944 @@
+/**
+ * devassist ai - AI 配置与多引擎管理
+ *
+ *   devassist ai --status                                查看当前 AI 配置状态
+ *   devassist ai --setup --provider qwen --key <key>     配置主引擎
+ *   devassist ai --add-engine --provider hunyuan --key <key>  添加引擎
+ *   devassist ai --setup-secondary --provider hunyuan --key <key>  （别名）添加引擎
+ *   devassist ai --remove-engine <provider|index>        移除引擎
+ *   devassist ai --list-engines                          列出所有引擎
+ *   devassist ai --test                                  测试主引擎连通性
+ *   devassist ai --test-all                              测试所有引擎连通性
+ *   devassist ai --analyze                               单引擎 AI 分析
+ *   devassist ai --compare                               多引擎对比分析（所有引擎并行）
+ *
+ * 支持的 provider: qwen（通义千问）/ openai / claude / hunyuan（腾讯混元）
+ *
+ * ai-config.json 格式（向后兼容）：
+ * {
+ *   "provider": "qwen",           // 主引擎（引擎 0）
+ *   "apiKey": "...",
+ *   "model": "qwen-plus",
+ *   "enabled": true,
+ *   "engines": [                  // 额外引擎（引擎 1, 2, ...）
+ *     { "provider": "hunyuan", "apiKey": "...", "model": "hy3-preview", "enabled": true },
+ *     { "provider": "openai", "apiKey": "...", "model": "gpt-4o-mini", "enabled": true }
+ *   ],
+ *   "secondary": { ... }          // 旧格式副引擎，自动合并到 engines[]
+ * }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const ai = require('../../ai/adapter');
+const qwen = require('../../ai/providers/qwen');
+const openai = require('../../ai/providers/openai');
+const claude = require('../../ai/providers/claude');
+const hunyuan = require('../../ai/providers/hunyuan');
+
+ai.registerProvider('qwen', qwen);
+ai.registerProvider('openai', openai);
+ai.registerProvider('claude', claude);
+ai.registerProvider('hunyuan', hunyuan);
+
+const PROVIDER_INFO = {
+  qwen:    { name: '通义千问', envVar: 'DASHSCOPE_API_KEY',   defaultModel: 'qwen-plus',     baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1' },
+  openai:  { name: 'OpenAI',  envVar: 'OPENAI_API_KEY',       defaultModel: 'gpt-4o-mini',   baseUrl: 'https://api.openai.com/v1' },
+  claude:  { name: 'Claude',  envVar: 'ANTHROPIC_API_KEY',    defaultModel: 'claude-sonnet-4-20250514', baseUrl: 'https://api.anthropic.com' },
+  hunyuan: { name: '腾讯混元', envVar: 'HUNYUAN_API_KEY',      defaultModel: 'hy3-preview',     baseUrl: 'https://tokenhub.tencentmaas.com/v1' },
+};
+
+const ENV_MAP = { qwen: 'DASHSCOPE_API_KEY', openai: 'OPENAI_API_KEY', claude: 'ANTHROPIC_API_KEY', hunyuan: 'HUNYUAN_API_KEY' };
+
+module.exports = async function aiCmd(projectRoot, args, ui) {
+  const { printHeader, c } = ui;
+
+  const showStatus      = args.includes('--status');
+  const doSetup         = args.includes('--setup');
+  const doSetupSecondary = args.includes('--setup-secondary');
+  const doAddEngine     = args.includes('--add-engine');
+  const doRemoveEngine  = args.includes('--remove-engine');
+  const doListEngines   = args.includes('--list-engines');
+  const doTest          = args.includes('--test');
+  const doTestAll       = args.includes('--test-all');
+  const doAnalyze       = args.includes('--analyze');
+  const doCompare       = args.includes('--compare');
+  const doWatchList     = args.includes('--watch-list');
+
+  // Default: show help
+  if (!showStatus && !doSetup && !doSetupSecondary && !doAddEngine && !doRemoveEngine &&
+      !doListEngines && !doTest && !doTestAll && !doAnalyze && !doCompare && !doWatchList) {
+    printHelp(c);
+    return;
+  }
+
+  if (showStatus)      { showAIStatus(projectRoot, c); return; }
+  if (doSetup)         { await setupAI(projectRoot, args, c, 'primary'); return; }
+  if (doSetupSecondary){ await setupAI(projectRoot, args, c, 'add'); return; }
+  if (doAddEngine)     { await setupAI(projectRoot, args, c, 'add'); return; }
+  if (doRemoveEngine)  { removeEngine(projectRoot, args, c); return; }
+  if (doListEngines)   { listEngines(projectRoot, c); return; }
+  if (doTest)          { await testAI(projectRoot, c, false); return; }
+  if (doTestAll)       { await testAI(projectRoot, c, true); return; }
+  if (doAnalyze)       { await analyzeFindings(projectRoot, c); return; }
+  if (doCompare)       { await compareFindings(projectRoot, c); return; }
+  if (doWatchList)     { manageWatchList(projectRoot, args, c); return; }
+};
+
+// ─── Help ────────────────────────────────────────────
+
+function printHelp(c) {
+  console.log(`\n  ${c.bold('devassist ai')} — AI 配置与多引擎管理\n`);
+  console.log(`  ${c.gray('用法：')}\n`);
+  console.log(`    devassist ai --status                                       查看当前配置`);
+  console.log(`    devassist ai --setup --provider qwen --key <密钥>            配置主引擎`);
+  console.log(`    devassist ai --add-engine --provider hunyuan --key <密钥>    添加引擎`);
+  console.log(`    devassist ai --setup-secondary --provider <p> --key <k>      （别名）添加引擎`);
+  console.log(`    devassist ai --remove-engine <provider|序号>                 移除引擎`);
+  console.log(`    devassist ai --list-engines                                  列出所有引擎`);
+  console.log(`    devassist ai --test                                          测试主引擎连通性`);
+  console.log(`    devassist ai --test-all                                      测试所有引擎`);
+  console.log(`    devassist ai --analyze                                       单引擎 AI 分析`);
+  console.log(`    devassist ai --compare                                       多引擎对比分析`);
+  console.log(`    devassist ai --watch-list                                     查看待观察列表`);
+  console.log(`    devassist ai --watch-list --resolve <序号>                    标记待观察项为已修复`);
+  console.log(`    devassist ai --watch-list --dismiss <序号>                    标记待观察项为无问题\n`);
+  console.log(`  ${c.gray('多引擎对比模式：')}`);
+  console.log(`    配置 2~N 个引擎后运行 --compare，所有引擎并行分析同一批发现`);
+  console.log(`    生成对比报告，按一致性自动分组\n`);
+  console.log(`  ${c.gray('支持的 provider：')}`);
+  console.log(`    qwen     通义千问（阿里云 DashScope）`);
+  console.log(`    hunyuan  腾讯混元`);
+  console.log(`    openai   OpenAI GPT`);
+  console.log(`    claude   Anthropic Claude\n`);
+  console.log(`  ${c.gray('也可通过环境变量配置：')}`);
+  console.log(`    DASHSCOPE_API_KEY     通义千问`);
+  console.log(`    HUNYUAN_API_KEY       腾讯混元`);
+  console.log(`    OPENAI_API_KEY        OpenAI`);
+  console.log(`    ANTHROPIC_API_KEY     Claude\n`);
+}
+
+// ─── Config Loading (N-engine aware) ─────────────────
+
+/**
+ * Load AI config and resolve all engine configs into a flat array.
+ * Returns: { ...rawConfig, engines: [{ provider, apiKey, model, baseUrl, enabled, name }] }
+ *
+ * Resolution order:
+ *   1. Primary engine from top-level fields (provider/apiKey/model)
+ *   2. Legacy `secondary` field (if present)
+ *   3. `engines` array (if present)
+ *   4. Env vars for API keys
+ *   5. Deduplicate by provider+model
+ */
+function loadAIConfig(projectRoot) {
+  const configPath = path.join(projectRoot, '.devassist', 'ai-config.json');
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    const rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+
+    // Build engines array
+    const engines = [];
+
+    // Engine 0: primary (top-level fields)
+    if (rawConfig.provider) {
+      const info = PROVIDER_INFO[rawConfig.provider];
+      let apiKey = rawConfig.apiKey;
+      if (!apiKey && info && process.env[info.envVar]) {
+        apiKey = process.env[info.envVar];
+      }
+      engines.push({
+        provider: rawConfig.provider,
+        apiKey,
+        model: rawConfig.model || info?.defaultModel,
+        baseUrl: rawConfig.baseUrl || info?.baseUrl,
+        enabled: rawConfig.enabled !== false,
+        name: info?.name || rawConfig.provider,
+      });
+    }
+
+    // Legacy secondary engine
+    if (rawConfig.secondary && rawConfig.secondary.provider) {
+      const sInfo = PROVIDER_INFO[rawConfig.secondary.provider];
+      let sApiKey = rawConfig.secondary.apiKey;
+      if (!sApiKey && sInfo && process.env[sInfo.envVar]) {
+        sApiKey = process.env[sInfo.envVar];
+      }
+      engines.push({
+        provider: rawConfig.secondary.provider,
+        apiKey: sApiKey,
+        model: rawConfig.secondary.model || sInfo?.defaultModel,
+        baseUrl: rawConfig.secondary.baseUrl || sInfo?.baseUrl,
+        enabled: rawConfig.secondary.enabled !== false,
+        name: sInfo?.name || rawConfig.secondary.provider,
+      });
+    }
+
+    // New engines array
+    if (Array.isArray(rawConfig.engines)) {
+      for (const eng of rawConfig.engines) {
+        if (!eng || !eng.provider) continue;
+        const eInfo = PROVIDER_INFO[eng.provider];
+        let eApiKey = eng.apiKey;
+        if (!eApiKey && eInfo && process.env[eInfo.envVar]) {
+          eApiKey = process.env[eInfo.envVar];
+        }
+        engines.push({
+          provider: eng.provider,
+          apiKey: eApiKey,
+          model: eng.model || eInfo?.defaultModel,
+          baseUrl: eng.baseUrl || eInfo?.baseUrl,
+          enabled: eng.enabled !== false,
+          name: eng.name || eInfo?.name || eng.provider,
+        });
+      }
+    }
+
+    // Deduplicate by provider+model
+    const seen = new Set();
+    const uniqueEngines = engines.filter(e => {
+      const key = `${e.provider}:${e.model || ''}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+
+    return {
+      ...rawConfig,
+      engines: uniqueEngines,
+    };
+  } catch (_) { return null; }
+}
+
+// ─── Status ──────────────────────────────────────────
+
+function showAIStatus(projectRoot, c) {
+  const config = loadAIConfig(projectRoot);
+
+  console.log(`\n  ${c.bold('AI 配置状态')}\n`);
+
+  if (!config || config.engines.length === 0) {
+    console.log(`  ${c.yellow('尚未配置。')} 运行 ${c.bold('devassist ai --setup --provider <name> --key <key>')} 来配置。\n`);
+    return;
+  }
+
+  const enabledEngines = config.engines.filter(e => e.enabled && e.apiKey);
+
+  config.engines.forEach((eng, i) => {
+    const info = PROVIDER_INFO[eng.provider];
+    const label = i === 0 ? '主引擎' : `引擎 ${i}`;
+    const status = eng.enabled ? (eng.apiKey ? c.green('就绪') : c.yellow('缺少 Key')) : c.gray('已禁用');
+    const envKey = info ? process.env[info.envVar] : null;
+
+    console.log(`  ${c.bold(label)}`);
+    console.log(`    Provider:   ${c.bold(eng.provider)}${info ? ' (' + info.name + ')' : ''}`);
+    console.log(`    状态:       ${status}`);
+    console.log(`    API Key:    ${eng.apiKey ? c.green('已设置') : c.yellow('未设置')}`);
+    if (envKey && !eng.apiKey) console.log(`    环境变量:   ${c.green('已设置（' + info.envVar + '）')}`);
+    console.log(`    模型:       ${eng.model || info?.defaultModel || c.gray('默认')}`);
+    if (i < config.engines.length - 1) console.log('');
+  });
+
+  if (enabledEngines.length >= 2) {
+    console.log(`\n  ${c.green(`${enabledEngines.length} 个引擎已就绪！`)} 可运行 ${c.bold('devassist ai --compare')} 进行多引擎对比分析。\n`);
+  } else if (enabledEngines.length === 1) {
+    console.log(`\n  ${c.gray('仅 1 个引擎就绪。添加更多引擎启用对比模式：')}`);
+    console.log(`    ${c.bold('devassist ai --add-engine --provider hunyuan --key <key>')}\n`);
+  }
+
+  console.log(`  配置文件:   ${path.join(projectRoot, '.devassist', 'ai-config.json')}\n`);
+}
+
+// ─── Setup / Add / Remove Engine ─────────────────────
+
+async function setupAI(projectRoot, args, c, mode) {
+  // mode: 'primary' = replace main engine, 'add' = append to engines[]
+  const provider = getArg(args, '--provider');
+  const key = getArg(args, '--key');
+  const model = getArg(args, '--model');
+  const baseUrl = getArg(args, '--base-url');
+
+  if (!provider) {
+    console.log(`\n  ${c.red('错误：')} 请指定 --provider\n`);
+    console.log(`  可选值：qwen / hunyuan / openai / claude\n`);
+    console.log(`  示例：devassist ai --${mode === 'primary' ? 'setup' : 'add-engine'} --provider qwen --key sk-xxxx\n`);
+    return;
+  }
+
+  const info = PROVIDER_INFO[provider];
+  if (!info) {
+    console.log(`\n  ${c.red('错误：')} 不支持的 provider "${provider}"\n`);
+    console.log(`  可选值：qwen / hunyuan / openai / claude\n`);
+    return;
+  }
+
+  let apiKey = key || process.env[info.envVar] || '';
+  if (!apiKey) {
+    console.log(`\n  ${c.red('错误：')} 未提供 API Key\n`);
+    console.log(`  请通过 --key 参数提供，或设置环境变量 ${info.envVar}\n`);
+    return;
+  }
+
+  const newEngine = {
+    provider,
+    apiKey,
+    model: model || info.defaultModel,
+    baseUrl: baseUrl || info.baseUrl,
+    enabled: true,
+  };
+
+  const configDir = path.join(projectRoot, '.devassist');
+  if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true });
+  const configPath = path.join(configDir, 'ai-config.json');
+
+  // Load existing config
+  let existingConfig = {};
+  if (fs.existsSync(configPath)) {
+    try { existingConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch (_) {}
+  }
+
+  if (mode === 'primary') {
+    // Replace primary engine fields, preserve engines[]
+    existingConfig.provider = newEngine.provider;
+    existingConfig.apiKey = newEngine.apiKey;
+    existingConfig.model = newEngine.model;
+    existingConfig.baseUrl = newEngine.baseUrl;
+    existingConfig.enabled = newEngine.enabled;
+    // Preserve engines[] and legacy secondary
+  } else {
+    // Add to engines[] array
+    if (!Array.isArray(existingConfig.engines)) existingConfig.engines = [];
+
+    // Check for duplicate provider+model
+    const dup = existingConfig.engines.find(e => e.provider === provider && (e.model || PROVIDER_INFO[e.provider]?.defaultModel) === newEngine.model);
+    if (dup) {
+      // Update existing
+      Object.assign(dup, newEngine);
+      console.log(`\n  ${c.yellow('已更新现有引擎配置。')}\n`);
+    } else {
+      existingConfig.engines.push(newEngine);
+    }
+  }
+
+  fs.writeFileSync(configPath, JSON.stringify(existingConfig, null, 2), 'utf-8');
+
+  const label = mode === 'primary' ? '主引擎' : '引擎';
+  console.log(`\n  ${c.green(`${label}配置已保存！`)}\n`);
+  console.log(`  Provider:  ${provider} (${info.name})`);
+  console.log(`  模型:      ${newEngine.model}`);
+  console.log(`  API Key:   ${c.gray('****' + apiKey.slice(-4))}`);
+  console.log(`  状态:      ${c.green('已启用')}\n`);
+
+  // Show current engine count
+  const fullConfig = loadAIConfig(projectRoot);
+  const count = fullConfig ? fullConfig.engines.length : 1;
+
+  if (count >= 2) {
+    console.log(`  ${c.green(`当前共 ${count} 个引擎已就绪。`)}`);
+    console.log(`    ${c.bold('devassist ai --compare')}          多引擎对比分析`);
+    console.log(`    ${c.bold('devassist ai --list-engines')}     查看所有引擎\n`);
+  } else {
+    console.log(`  ${c.gray('提示：添加更多引擎可启用对比模式：')}`);
+    console.log(`    ${c.bold('devassist ai --add-engine --provider hunyuan --key <key>')}\n`);
+    console.log(`  ${c.gray('现在可以运行：')}`);
+    console.log(`    ${c.bold('devassist ai --test')}             测试 AI 连通性`);
+    console.log(`    ${c.bold('devassist check --ai')}            对代码检查结果做 AI 深度分析\n`);
+  }
+}
+
+function removeEngine(projectRoot, args, c) {
+  // Find the target: either a provider name or a numeric index
+  const target = args[args.indexOf('--remove-engine') + 1];
+
+  if (!target) {
+    console.log(`\n  ${c.red('错误：')} 请指定要移除的引擎（provider 名称或序号）\n`);
+    console.log(`  示例：devassist ai --remove-engine hunyuan`);
+    console.log(`        devassist ai --remove-engine 2\n`);
+    return;
+  }
+
+  const configPath = path.join(projectRoot, '.devassist', 'ai-config.json');
+  if (!fs.existsSync(configPath)) {
+    console.log(`\n  ${c.yellow('尚未配置 AI。')}\n`);
+    return;
+  }
+
+  let config;
+  try { config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch (_) {
+    console.log(`\n  ${c.red('配置文件无法读取。')}\n`);
+    return;
+  }
+
+  const fullConfig = loadAIConfig(projectRoot);
+  if (!fullConfig || fullConfig.engines.length === 0) {
+    console.log(`\n  ${c.yellow('无引擎可移除。')}\n`);
+    return;
+  }
+
+  // Try numeric index first
+  const idx = parseInt(target, 10);
+  if (!isNaN(idx) && idx >= 0 && idx < fullConfig.engines.length) {
+    const removed = fullConfig.engines[idx];
+    removeFromConfig(config, removed, idx);
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    console.log(`\n  ${c.green('已移除引擎 ' + idx + '：')} ${removed.provider} (${removed.name})\n`);
+    return;
+  }
+
+  // Try provider name
+  const matchIdx = fullConfig.engines.findIndex(e => e.provider === target);
+  if (matchIdx >= 0) {
+    const removed = fullConfig.engines[matchIdx];
+    removeFromConfig(config, removed, matchIdx);
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    console.log(`\n  ${c.green('已移除引擎：')} ${removed.provider} (${removed.name})\n`);
+    return;
+  }
+
+  console.log(`\n  ${c.red('未找到匹配的引擎：')} ${target}\n`);
+  listEngines(projectRoot, c);
+}
+
+function removeFromConfig(config, removed, index) {
+  // If it's the primary engine (index 0), clear top-level fields
+  if (index === 0) {
+    delete config.provider;
+    delete config.apiKey;
+    delete config.model;
+    delete config.baseUrl;
+    delete config.enabled;
+    // Promote first engine from engines[] to primary if available
+    if (Array.isArray(config.engines) && config.engines.length > 0) {
+      const promoted = config.engines.shift();
+      config.provider = promoted.provider;
+      config.apiKey = promoted.apiKey;
+      config.model = promoted.model;
+      config.baseUrl = promoted.baseUrl;
+      config.enabled = promoted.enabled;
+    }
+  } else if (index === 1 && config.secondary) {
+    // Legacy secondary
+    delete config.secondary;
+  } else {
+    // Remove from engines[]
+    if (Array.isArray(config.engines)) {
+      // Adjust index: subtract primary (1) and legacy secondary (1 if exists)
+      let adjIdx = index - 1;
+      if (config.secondary) adjIdx -= 1;
+      if (adjIdx >= 0 && adjIdx < config.engines.length) {
+        config.engines.splice(adjIdx, 1);
+      }
+    }
+  }
+}
+
+function listEngines(projectRoot, c) {
+  const config = loadAIConfig(projectRoot);
+
+  console.log(`\n  ${c.bold('已配置的 AI 引擎')}\n`);
+
+  if (!config || config.engines.length === 0) {
+    console.log(`  ${c.yellow('尚未配置任何引擎。')}\n`);
+    return;
+  }
+
+  config.engines.forEach((eng, i) => {
+    const info = PROVIDER_INFO[eng.provider];
+    const label = i === 0 ? '主引擎' : `引擎 ${i}`;
+    const status = eng.enabled && eng.apiKey ? c.green('就绪') : c.yellow('未就绪');
+
+    console.log(`  ${c.bold(`[${i}]`)} ${label}`);
+    console.log(`      Provider:  ${eng.provider} (${info?.name || eng.name || '?'})`);
+    console.log(`      模型:      ${eng.model || info?.defaultModel || '默认'}`);
+    console.log(`      状态:      ${status}`);
+    if (i < config.engines.length - 1) console.log('');
+  });
+
+  console.log(`\n  ${c.gray('共 ' + config.engines.length + ' 个引擎')}\n`);
+}
+
+// ─── Test ────────────────────────────────────────────
+
+async function testAI(projectRoot, c, testAll) {
+  const config = loadAIConfig(projectRoot);
+
+  if (!config || config.engines.length === 0) {
+    console.log(`\n  ${c.yellow('AI 尚未配置。')}\n`);
+    console.log(`  运行 ${c.bold('devassist ai --setup --provider qwen --key <key>')} 来配置。\n`);
+    return;
+  }
+
+  const enginesToTest = testAll ? config.engines : [config.engines[0]];
+
+  console.log(`\n  ${c.bold(testAll ? '所有引擎连通性测试' : '主引擎连通性测试')}\n`);
+
+  let allPassed = true;
+
+  for (let i = 0; i < enginesToTest.length; i++) {
+    const eng = enginesToTest[i];
+    const info = PROVIDER_INFO[eng.provider];
+    const label = testAll ? `引擎 [${i}] ` : '';
+
+    console.log(`  ${c.bold(label + eng.provider)} (${info?.name || '?'})`);
+    console.log(`  模型: ${eng.model || info?.defaultModel || '默认'}`);
+    console.log(`  ${c.gray('正在发送测试请求...')}`);
+
+    const testConfig = { provider: eng.provider, apiKey: eng.apiKey, model: eng.model, baseUrl: eng.baseUrl };
+    const testQuestion = '请用一句话回答：1+1等于几？';
+
+    try {
+      const result = await ai.ask(testConfig, testQuestion, {});
+      if (result.error || result.unavailable) {
+        console.log(`  ${c.red('失败：')} ${result.content}\n`);
+        allPassed = false;
+      } else {
+        console.log(`  ${c.green('成功！')} ${c.gray('回复：')} ${result.content.trim()}`);
+        if (result.model) console.log(`  ${c.gray('模型：')} ${result.model}\n`);
+        else console.log('');
+      }
+    } catch (err) {
+      console.log(`  ${c.red('失败：')} ${err.message}\n`);
+      allPassed = false;
+    }
+  }
+
+  if (testAll) {
+    if (allPassed) {
+      console.log(`  ${c.green('所有引擎测试通过！')}\n`);
+    } else {
+      console.log(`  ${c.yellow('部分引擎测试失败，请检查配置。')}\n`);
+    }
+  }
+
+  if (allPassed) {
+    console.log(`  ${c.gray('AI 已就绪。现在可以运行：')}`);
+    console.log(`    ${c.bold('devassist check --ai')}         对代码做 AI 深度分析`);
+    if (config.engines.length >= 2) {
+      console.log(`    ${c.bold('devassist ai --compare')}       多引擎对比分析\n`);
+    } else {
+      console.log(`    ${c.bold('devassist ai --analyze')}       分析最近一次检查结果\n`);
+    }
+  }
+}
+
+// ─── Single-Engine Analyze ───────────────────────────
+
+async function analyzeFindings(projectRoot, c) {
+  const config = loadAIConfig(projectRoot);
+
+  if (!config || config.engines.length === 0) {
+    console.log(`\n  ${c.yellow('AI 尚未配置。')}\n`);
+    console.log(`  运行 ${c.bold('devassist ai --setup --provider qwen --key <key>')} 来配置。\n`);
+    return;
+  }
+
+  const primaryEngine = config.engines[0];
+
+  // Load latest report findings
+  const reportDir = path.join(projectRoot, '.devassist', 'reports');
+  const latestJson = path.join(reportDir, 'latest.json');
+
+  let findings = [];
+  if (fs.existsSync(latestJson)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(latestJson, 'utf-8'));
+      findings = data.findings || [];
+    } catch (_) {}
+  }
+
+  if (findings.length === 0) {
+    console.log(`\n  ${c.yellow('没有可分析的发现。')}\n`);
+    console.log(`  请先运行 ${c.bold('devassist check')} 生成检查结果。\n`);
+    return;
+  }
+
+  const suspectFindings = findings.filter(f => f.severity === 'block' || f.severity === 'warn');
+
+  if (suspectFindings.length === 0) {
+    console.log(`\n  ${c.green('无需 AI 分析。')} 所有发现均为 info 级别。\n`);
+    return;
+  }
+
+  console.log(`\n  ${c.bold('AI 深度分析')}\n`);
+  console.log(`  发现数量:  ${suspectFindings.length} 个（warn/block 级别）`);
+  console.log(`  Provider:  ${primaryEngine.provider}`);
+  console.log(`  ${c.gray('正在分析...')}\n`);
+
+  const { ConventionStore } = require('../../modules/dev-time/convention-store');
+  const conventionStore = new ConventionStore(projectRoot);
+  const aiContext = {
+    conventions: conventionStore.getRelevant({}),
+    projectInfo: { root: projectRoot },
+  };
+
+  try {
+    const enrichedFindings = await ai.analyze(primaryEngine, suspectFindings, aiContext);
+
+    console.log(`  ${c.green('分析完成！')}\n`);
+
+    for (const f of enrichedFindings) {
+      const sev = f.severity === 'block' ? c.red('[阻断]') : c.yellow('[警告]');
+      console.log(`  ${sev} ${f.message}`);
+      console.log(`         ${c.gray(f.file)}${f.line ? ':' + f.line : ''}`);
+
+      if (f.aiAnalysis && !f.aiAnalysisUnavailable) {
+        const a = f.aiAnalysis;
+        console.log(`         ${c.cyan('── AI 根因分析 ──')}`);
+        if (a.rootCause) console.log(`         根因: ${a.rootCause}`);
+        if (a.isFalsePositive !== undefined) console.log(`         误报: ${a.isFalsePositive ? '是' : '否'}`);
+        if (a.fix) console.log(`         修复: ${a.fix}`);
+        if (a.codeExample) console.log(`         ${c.gray('示例:')} ${a.codeExample}`);
+        if (a.confidence !== undefined) console.log(`         置信度: ${(a.confidence * 100).toFixed(0)}%`);
+      } else if (f.aiAnalysisUnavailable) {
+        console.log(`         ${c.gray('(AI 分析不可用)')}`);
+        if (f.aiError) console.log(`         ${c.gray('错误: ' + f.aiError)}`);
+      }
+      console.log();
+    }
+
+    // Save AI analysis results
+    const analysisPath = path.join(projectRoot, '.devassist', 'reports', 'ai-analysis.json');
+    if (!fs.existsSync(reportDir)) fs.mkdirSync(reportDir, { recursive: true });
+    fs.writeFileSync(analysisPath, JSON.stringify({
+      analyzedAt: new Date().toISOString(),
+      provider: primaryEngine.provider,
+      model: primaryEngine.model,
+      findings: enrichedFindings,
+    }, null, 2), 'utf-8');
+
+    console.log(`  ${c.gray('分析结果已保存到 .devassist/reports/ai-analysis.json')}\n`);
+  } catch (err) {
+    console.log(`  ${c.red('分析失败：')} ${err.message}\n`);
+  }
+}
+
+// ─── Multi-Engine Compare ────────────────────────────
+
+async function compareFindings(projectRoot, c) {
+  const config = loadAIConfig(projectRoot);
+
+  if (!config || config.engines.length === 0) {
+    console.log(`\n  ${c.yellow('尚未配置任何 AI 引擎。')}\n`);
+    console.log(`  运行 ${c.bold('devassist ai --setup --provider qwen --key <key>')} 来配置主引擎。\n`);
+    return;
+  }
+
+  const readyEngines = config.engines.filter(e => e.enabled && e.apiKey);
+
+  if (readyEngines.length < 2) {
+    console.log(`\n  ${c.yellow('对比分析至少需要 2 个引擎就绪。')}\n`);
+    console.log(`  当前就绪引擎数：${readyEngines.length}`);
+    console.log(`  运行 ${c.bold('devassist ai --add-engine --provider hunyuan --key <key>')} 添加更多引擎。\n`);
+    return;
+  }
+
+  // Load latest report findings
+  const reportDir = path.join(projectRoot, '.devassist', 'reports');
+  const latestJson = path.join(reportDir, 'latest.json');
+
+  let findings = [];
+  if (fs.existsSync(latestJson)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(latestJson, 'utf-8'));
+      findings = data.findings || [];
+    } catch (_) {}
+  }
+
+  if (findings.length === 0) {
+    console.log(`\n  ${c.yellow('没有可分析的发现。')}\n`);
+    console.log(`  请先运行 ${c.bold('devassist check')} 生成检查结果。\n`);
+    return;
+  }
+
+  const suspectFindings = findings.filter(f => f.severity === 'block' || f.severity === 'warn');
+
+  if (suspectFindings.length === 0) {
+    console.log(`\n  ${c.green('无需 AI 分析。')} 所有发现均为 info 级别。\n`);
+    return;
+  }
+
+  console.log(`\n  ${c.bold(`${readyEngines.length} 引擎对比分析`)}\n`);
+  console.log(`  发现数量:    ${suspectFindings.length} 个（warn/block 级别）`);
+  readyEngines.forEach((eng, i) => {
+    console.log(`  引擎 [${i}]:     ${eng.provider} (${eng.name}) → ${eng.model}`);
+  });
+  console.log(`  ${c.gray(`正在并行分析（${readyEngines.length} 个引擎同时运行）...`)}\n`);
+
+  // Load conventions as context
+  const { ConventionStore } = require('../../modules/dev-time/convention-store');
+  const conventionStore = new ConventionStore(projectRoot);
+  const aiContext = {
+    conventions: conventionStore.getRelevant({}),
+    projectInfo: { root: projectRoot },
+  };
+
+  try {
+    const mergedFindings = await ai.multiAnalyze(readyEngines, suspectFindings, aiContext);
+
+    // Compute agreement stats
+    const stats = computeAgreementStats(mergedFindings, readyEngines.length);
+
+    console.log(`  ${c.green('多引擎分析完成！')}\n`);
+    console.log(`  ${c.bold('一致性统计：')}`);
+    console.log(`    全引擎一致:        ${stats.allAgree} 个`);
+    console.log(`    部分一致:          ${stats.partialAgree} 个`);
+    console.log(`    全引擎不一致:      ${stats.allDisagree} 个`);
+    console.log(`    误报判断一致率:    ${stats.agreementRate}\n`);
+
+    // Print comparison
+    for (const f of mergedFindings) {
+      const sev = f.severity === 'block' ? c.red('[阻断]') : c.yellow('[警告]');
+      console.log(`  ${sev} ${f.message}`);
+      console.log(`         ${c.gray(f.file)}${f.line ? ':' + f.line : ''}`);
+
+      if (f.aiAnalyses) {
+        for (const ea of f.aiAnalyses) {
+          const tag = `[${ea.engineName}]`;
+          if (ea.available && ea.analysis) {
+            const a = ea.analysis;
+            console.log(`         ${c.cyan(`── ${tag} ──`)}`);
+            if (a.rootCause) console.log(`         根因: ${a.rootCause}`);
+            if (a.isFalsePositive !== undefined) console.log(`         误报: ${a.isFalsePositive ? '是' : '否'}`);
+            if (a.fix) console.log(`         修复: ${a.fix}`);
+            if (a.confidence !== undefined) console.log(`         置信度: ${(a.confidence * 100).toFixed(0)}%`);
+          } else {
+            console.log(`         ${c.gray(`── ${tag} 不可用 ──`)}`);
+            if (ea.error) console.log(`         ${c.gray('错误: ' + ea.error)}`);
+          }
+        }
+      }
+
+      // Agreement indicator
+      if (f.aiAnalyses) {
+        const available = f.aiAnalyses.filter(ea => ea.available && ea.analysis);
+        if (available.length >= 2) {
+          const fpValues = available.map(ea => ea.analysis.isFalsePositive);
+          const allSame = fpValues.every(v => v === fpValues[0]);
+          console.log(`         ${allSame ? c.green('✓ 全引擎判断一致 → 建议修复') : c.yellow('⏳ 引擎判断不一致 → 已标记待观察，暂不修复')}`);
+        }
+      }
+
+      console.log();
+    }
+
+    // Auto-add disagreement findings to watch list
+    const watchList = require('../shared/watch-list');
+    const deferredCount = watchList.addDeferredFindings(projectRoot, mergedFindings,
+      '待观察：引擎判断不一致，等运行时验证');
+
+    // Save comparison results
+    const comparisonPath = path.join(projectRoot, '.devassist', 'reports', 'ai-comparison.json');
+    if (!fs.existsSync(reportDir)) fs.mkdirSync(reportDir, { recursive: true });
+    fs.writeFileSync(comparisonPath, JSON.stringify({
+      analyzedAt: new Date().toISOString(),
+      engines: readyEngines.map(e => ({ provider: e.provider, model: e.model, name: e.name })),
+      stats,
+      findings: mergedFindings,
+    }, null, 2), 'utf-8');
+
+    // Generate comparison HTML report
+    const { generateComparisonHTML } = require('./comparison-report');
+    const html = generateComparisonHTML({
+      projectRoot: path.basename(projectRoot),
+      timestamp: new Date().toISOString(),
+      engines: readyEngines.map(e => ({ provider: e.provider, model: e.model, name: e.name })),
+      stats,
+      findings: mergedFindings,
+    });
+
+    const htmlPath = path.join(reportDir, 'ai-comparison.html');
+    fs.writeFileSync(htmlPath, html, 'utf-8');
+
+    console.log(`  ${c.gray('分析结果已保存：')}`);
+    console.log(`    JSON:  .devassist/reports/ai-comparison.json`);
+    console.log(`    HTML:  .devassist/reports/ai-comparison.html`);
+
+    if (deferredCount > 0) {
+      console.log(`\n  ${c.yellow(`⏳ ${deferredCount} 个判断不一致的发现已标记为待观察`)}`);
+      console.log(`  ${c.gray('    → 暂不修复，等实际运行验证后再处理')}`);
+      console.log(`  ${c.gray('    → 查看待观察列表：devassist ai --watch-list')}`);
+    }
+
+    console.log(`\n  ${c.gray('修复策略：')}`);
+    console.log(`  ${c.gray('  ✓ 全引擎一致 → 优先修复')}`);
+    console.log(`  ${c.gray('  ⏳ 全引擎不一致 → 待观察，不修复')}\n`);
+  } catch (err) {
+    console.log(`  ${c.red('分析失败：')} ${err.message}\n`);
+  }
+}
+
+/**
+ * Compute agreement statistics for N engines.
+ */
+function computeAgreementStats(findings, engineCount) {
+  let allAgree = 0;       // All engines agree on isFalsePositive
+  let partialAgree = 0;   // Some engines agree, some disagree
+  let allDisagree = 0;    // All engines returned but no two agree
+  let partialAvailable = 0; // Not all engines returned
+  let falsePositiveAgreement = 0;
+  let totalCompared = 0;
+
+  for (const f of findings) {
+    if (!f.aiAnalyses) continue;
+    const available = f.aiAnalyses.filter(ea => ea.available && ea.analysis);
+    if (available.length < 2) {
+      partialAvailable++;
+      continue;
+    }
+
+    totalCompared++;
+    const fpValues = available.map(ea => ea.analysis.isFalsePositive);
+    const allSame = fpValues.every(v => v === fpValues[0]);
+
+    if (available.length === engineCount) {
+      if (allSame) {
+        allAgree++;
+        falsePositiveAgreement++;
+      } else {
+        // Check if majority agree
+        const trueCount = fpValues.filter(v => v === true).length;
+        const falseCount = fpValues.filter(v => v === false).length;
+        if (Math.max(trueCount, falseCount) >= 2) {
+          partialAgree++;
+        } else {
+          allDisagree++;
+        }
+      }
+    } else {
+      partialAvailable++;
+      if (allSame) falsePositiveAgreement++;
+    }
+  }
+
+  const agreementRate = totalCompared > 0
+    ? `${((falsePositiveAgreement / totalCompared) * 100).toFixed(0)}%（${falsePositiveAgreement}/${totalCompared}）`
+    : '—';
+
+  return { allAgree, partialAgree, allDisagree, partialAvailable, falsePositiveAgreement, totalCompared, agreementRate };
+}
+
+// ─── Watch List Management ───────────────────────────
+
+function manageWatchList(projectRoot, args, c) {
+  const watchList = require('../shared/watch-list');
+
+  const doResolve  = args.includes('--resolve');
+  const doDismiss  = args.includes('--dismiss');
+  const doNote     = args.includes('--note');
+  const doRemove   = args.includes('--remove');
+  const doStats    = args.includes('--stats');
+
+  // --resolve <index> — mark as fixed (runtime confirmed issue)
+  if (doResolve) {
+    const target = getArg(args, '--resolve');
+    const runtimeNotes = getArg(args, '--runtime-note');
+    const item = watchList.resolveItem(projectRoot, target, 'fixed', runtimeNotes);
+    if (item) {
+      console.log(`\n  ${c.green('✓ 已标记为已修复：')} ${item.finding.file}:${item.finding.line}\n`);
+    } else {
+      console.log(`\n  ${c.red('未找到对应的待观察项。')}\n`);
+    }
+    return;
+  }
+
+  // --dismiss <index> — mark as no-issue (runtime confirmed no problem)
+  if (doDismiss) {
+    const target = getArg(args, '--dismiss');
+    const runtimeNotes = getArg(args, '--runtime-note');
+    const item = watchList.dismissItem(projectRoot, target, runtimeNotes);
+    if (item) {
+      console.log(`\n  ${c.green('✓ 已标记为无问题：')} ${item.finding.file}:${item.finding.line}\n`);
+    } else {
+      console.log(`\n  ${c.red('未找到对应的待观察项。')}\n`);
+    }
+    return;
+  }
+
+  // --note <index> --text "备注内容"
+  if (doNote) {
+    const target = getArg(args, '--note');
+    const note = getArg(args, '--text') || '无备注';
+    const item = watchList.updateNote(projectRoot, target, note);
+    if (item) {
+      console.log(`\n  ${c.green('✓ 备注已更新：')} ${item.finding.file}:${item.finding.line}`);
+      console.log(`  ${c.gray('备注：' + item.note)}\n`);
+    } else {
+      console.log(`\n  ${c.red('未找到对应的待观察项。')}\n`);
+    }
+    return;
+  }
+
+  // --remove <index>
+  if (doRemove) {
+    const target = getArg(args, '--remove');
+    const removed = watchList.removeItem(projectRoot, target);
+    if (removed) {
+      console.log(`\n  ${c.green('✓ 已移除：')} ${removed.finding.file}:${removed.finding.line}\n`);
+    } else {
+      console.log(`\n  ${c.red('未找到对应的待观察项。')}\n`);
+    }
+    return;
+  }
+
+  // --stats only
+  if (doStats) {
+    const stats = watchList.getStats(projectRoot);
+    console.log(`\n  ${c.bold('待观察列表统计')}\n`);
+    console.log(`    总计:     ${stats.total}`);
+    console.log(`    待观察:   ${c.yellow(stats.pending)}`);
+    console.log(`    已修复:   ${c.green(stats.resolved)}`);
+    console.log(`    已排除:   ${c.gray(stats.dismissed)}\n`);
+    return;
+  }
+
+  // Default: list all pending items
+  const stats = watchList.getStats(projectRoot);
+  const pending = watchList.getPending(projectRoot);
+
+  console.log(`\n  ${c.bold('⏳ 待观察列表')}\n`);
+
+  if (pending.length === 0) {
+    console.log(`  ${c.green('没有待观察的发现。')}\n`);
+    if (stats.total > 0) {
+      console.log(`  ${c.gray(`（历史记录：${stats.resolved} 已修复，${stats.dismissed} 已排除）`)}\n`);
+    }
+    return;
+  }
+
+  console.log(`  共 ${c.yellow(pending.length + ' 个')} 待观察的发现（暂不修复，等运行时验证）\n`);
+
+  pending.forEach((item, i) => {
+    const sev = item.finding.severity === 'block' ? c.red('[阻断]') : c.yellow('[警告]');
+    console.log(`  ${c.bold(`[${i}]`)} ${sev} ${item.finding.message}`);
+    console.log(`      位置:    ${c.gray(item.finding.file + ':' + item.finding.line)} | ${item.finding.ruleId}`);
+    console.log(`      备注:    ${c.gray(item.note)}`);
+    console.log(`      标记于:  ${c.gray(new Date(item.deferredAt).toLocaleString('zh-CN'))}`);
+
+    // Show engine disagreement summary
+    if (item.aiAnalyses && item.aiAnalyses.length >= 2) {
+      const fpYes = item.aiAnalyses.filter(a => a.isFalsePositive === true).map(a => a.engineName);
+      const fpNo = item.aiAnalyses.filter(a => a.isFalsePositive === false).map(a => a.engineName);
+      console.log(`      分歧:    ${c.gray(fpNo.join('/') + ' 认为真问题 vs ' + fpYes.join('/') + ' 认为误报')}`);
+    }
+    console.log();
+  });
+
+  console.log(`  ${c.gray('操作：')}`);
+  console.log(`    ${c.bold('devassist ai --watch-list --resolve <序号>')}            标记为已修复`);
+  console.log(`    ${c.bold('devassist ai --watch-list --dismiss <序号>')}            标记为无问题`);
+  console.log(`    ${c.bold('devassist ai --watch-list --note <序号> --text "备注"')}  更新备注`);
+  console.log(`    ${c.bold('devassist ai --watch-list --remove <序号>')}              从列表移除\n`);
+}
+
+// ─── Utils ───────────────────────────────────────────
+
+function getArg(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx >= 0 && args[idx + 1]) return args[idx + 1];
+  return null;
+}
+
+module.exports.loadAIConfig = loadAIConfig;
+module.exports.PROVIDER_INFO = PROVIDER_INFO;
+module.exports.ENV_MAP = ENV_MAP;
+module.exports.computeAgreementStats = computeAgreementStats;