imtoagent 0.2.5 → 0.3.1

package/index.ts

@@ -51,18 +51,12 @@ registerIM('telegram', {
   },
 });
 
-// 注册企业微信
+// 注册企业微信（扫码绑定，无需预填凭证）
 registerIM('wecom', {
   create(cfg: BotConfig) {
     return new WeComIMModule({
-      corpId: cfg.appId,
-      corpSecret: cfg.appSecret,
-      agentId: (cfg as any).agentId,
-      token: (cfg as any).token,
-      encodingAESKey: (cfg as any).encodingAESKey,
-      receiveId: (cfg as any).receiveId,
-      webhookPort: (cfg as any).webhookPort,
-      webhookPath: (cfg as any).webhookPath,
+      botId: (cfg as any).botId,
+      secret: (cfg as any).secret,
     });
   },
 });
@@ -82,7 +76,7 @@ import { getProxyUsage, resetProxyUsage, initCodexProxyConfig } from './modules/
 import { initOpenCodeConfig } from './modules/agent/opencode';
 import { checkRateLimit, setRateLimitConfig } from './modules/rate-limiter';
 import { setCurrentBot } from './modules/bot-context';
-import { getDataDir, getSessionsDir, getSoulDir, getRestoreMarkerPath } from './modules/utils/paths';
+import { getDataDir, getSessionsDir, getSoulDir, getBotKey, getRestoreMarkerPath } from './modules/utils/paths';
 
 // ===== SDK 核心 =====
 import { AgentRuntime, FileSessionManager, DefaultErrorHandler, DefaultStatsTracker } from './modules/core';
@@ -281,6 +275,7 @@ type CommandHandler = (ctx: CommandCtx) => Promise<string> | string;
 // BotConfig
 // ================================================================
 interface BotConfig {
+  id?: string;
   name: string;
   appId: string;
   appSecret: string;
@@ -292,6 +287,7 @@ interface BotConfig {
 // Bot 类 — SDK 完整接入版
 // ================================================================
 class Bot {
+  id: string;
   name: string;
   backend: 'claude' | 'codex' | 'opencode';
   appId: string;
@@ -313,6 +309,7 @@ class Bot {
   adapter: AgentAdapter;
 
   constructor(cfg: BotConfig, globalConfig: any) {
+    this.id = cfg.id || cfg.name; // 后向兼容：无 id 时用 name
     this.name = cfg.name;
     this.backend = cfg.backend;
     this.appId = cfg.appId;
@@ -353,7 +350,7 @@ class Bot {
     this.im = imFactory.create(cfg);
 
     // ===== SDK 集成 =====
-    this.sessionManager = new CustomSessionManager(this.name, this.sessions);
+    this.sessionManager = new CustomSessionManager(this.id, this.sessions);
 
     const adapterCtx = {
       imModule: this.im,
@@ -388,7 +385,7 @@ class Bot {
   }
 
   // ===== 灵魂管理 =====
-  _soulDir() { return getSoulDir(this.name); }
+  _soulDir() { return getSoulDir(this.id); }
 
   _initSoul() {
     const dir = this._soulDir();
@@ -438,7 +435,7 @@ class Bot {
   }
 
   // ===== Bot 配置 =====
-  _botConfigPath() { return path.join(getSessionsDir(), this.name, '_bot.json'); }
+  _botConfigPath() { return path.join(getSessionsDir(), this.id, '_bot.json'); }
 
   _loadBotConfig() {
     try {
@@ -698,7 +695,7 @@ class Bot {
       const cmdResp = await this.tryHandleCommand(chatId, text, session);
       if (cmdResp !== null) {
         await this.reply(chatId, cmdResp);
-        this.sessionManager.persist(this.name, session);
+        this.sessionManager.persist(this.id, session);
         return;
       }
 
@@ -719,7 +716,7 @@ class Bot {
         sendProgress: async (t: string) => this.sendProgress(chatId, t),
         sendBlocks: async (blocks) => this.sendFormattedReplyDirect(chatId, blocks),
         imCaps: this.im.getCapabilities(),
-      }, this.adapter, this.name);
+      }, this.adapter, this.id);
 
       // Agent 自主重启信号检测
       if (result?.restart) {
@@ -1017,7 +1014,7 @@ async function main() {
   // 避免 --resume 恢复重启前残留的 Claude CLI 子进程 session
   for (const bot of bots) {
     if (bot.backend !== 'claude') continue;
-    const botDir = path.join(getSessionsDir(), bot.name);
+    const botDir = path.join(getSessionsDir(), bot.id);
     try {
       if (fs.existsSync(botDir)) {
         for (const file of fs.readdirSync(botDir)) {
@@ -1052,7 +1049,7 @@ async function main() {
           const summary = `🔄 IMtoAgent 已重启\n原因: ${reason}\n耗时: ${(uptime / 1000).toFixed(1)}s`;
           let sent = 0;
           for (const bot of bots) {
-            const snap = data.bots?.[bot.name];
+            const snap = data.bots?.[bot.id];
             if (!snap?.chats?.length) continue;
             for (const { chatId } of snap.chats) {
               try { await bot.reply(chatId, summary); sent++; break; }
@@ -1087,7 +1084,7 @@ async function main() {
     console.log('[Shutdown] 持久化所有 session...');
     for (const bot of bots) {
       for (const [chatId, session] of bot.sessions.entries()) {
-        try { bot.sessionManager.persist(bot.name, session); } catch {}
+        try { bot.sessionManager.persist(bot.id, session); } catch {}
       }
     }
     const DRAIN_TIMEOUT = 10_000;

package/modules/cli/setup.ts

@@ -1,219 +1,428 @@
 // ================================================================
-// setup.ts — 交互式配置向导
+// setup.ts — 交互式配置向导（v2）
 // ================================================================
-// 零依赖，使用 Bun 原生 prompt()
-// 通过 `imtoagent setup` 调用
+// 交互方式：
+//   ↑↓ 或 空格 — 切换选项
+//   回车 — 确认选择
+//   ESC — 返回上一步
+//
+// 支持的 IM 平台：飞书 / Telegram / 企业微信 / 个人微信
 // ================================================================
 
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import * as readline from 'readline';
-import { getDataDir, getPkgDir, getTemplatePath, getTemplateSoulPath, getSoulDir } from '../utils/paths';
-import { checkAllBackends, formatBackendStatus, checkBackend } from '../utils/backend-check';
+import { getDataDir, getPkgDir, getTemplatePath, getSoulDir, getBotKey } from '../utils/paths';
+import { randomUUID } from 'crypto';
+import { checkAllBackends, formatBackendStatus } from '../utils/backend-check';
+
+// ================================================================
+// 键盘输入（raw mode）
+// ================================================================
+
+const KEY = {
+  UP: '\x1b[A',
+  DOWN: '\x1b[B',
+  ENTER: '\r',
+  SPACE: ' ',
+  ESC: '\x1b',
+  BACKSPACE: '\x7f',
+};
+
+/** 读取单个按键 */
+function readKey(): Promise<string> {
+  return new Promise((resolve) => {
+    const onData = (data: Buffer) => {
+      process.stdin.removeListener('data', onData);
+      const s = data.toString();
+      if (s === '\x03') process.exit(130); // Ctrl+C
+      resolve(s);
+    };
+    process.stdin.once('data', onData);
+  });
+}
+
+// ================================================================
+// 菜单选择（↑↓/空格 切换，回车确认）
+// ================================================================
+
+async function selectMenu(title: string, options: string[]): Promise<number> {
+  let idx = 0;
+  const linesAbove = options.length + 2;
+
+  function render() {
+    // 清除之前的输出
+    process.stdout.write('\x1B[0G'); // 回到行首
+    options.forEach((opt, i) => {
+      const prefix = i === idx ? '▸ ' : '  ';
+      process.stdout.write(`\x1B[0G${prefix}${opt}\x1B[0K\n`);
+    });
+  }
+
+  // 显示标题
+  console.log(title);
+  render();
+
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+
+  try {
+    while (true) {
+      const key = await readKey();
+
+      if (key === KEY.UP || key === KEY.DOWN || key === KEY.SPACE) {
+        // 移动光标
+        idx = (idx + (key === KEY.UP ? -1 : 1) + options.length) % options.length;
+        // 重绘所有选项
+        process.stdout.write(`\x1B[${options.length}A`); // 上移 N 行
+        render();
+      } else if (key === KEY.ENTER) {
+        break;
+      } else if (key === KEY.ESC) {
+        return -1; // ESC = 返回上一步
+      }
+    }
+  } finally {
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+  }
+
+  console.log(`\x1B[0G▸ ${options[idx]} ✓\n`);
+  return idx;
+}
+
+// ================================================================
+// 文本输入（回车确认，ESC 返回 -1）
+// ================================================================
+
+async function promptText(label: string, defaultValue = ''): Promise<string> {
+  const buf: string[] = [];
+  const defaultHint = defaultValue ? ` [${defaultValue}]` : '';
+
+  process.stdout.write(`${label}${defaultHint}: `);
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+
+  try {
+    while (true) {
+      const key = await readKey();
+
+      if (key === KEY.ENTER) {
+        break;
+      } else if (key === KEY.ESC) {
+        process.stdout.write('\x1B[0K\n');
+        return -1 as unknown as string; // 特殊返回值表示 ESC
+      } else if (key === KEY.BACKSPACE) {
+        if (buf.length > 0) {
+          buf.pop();
+          process.stdout.write('\x1B[1D \x1B[1D'); // 退格删除
+        }
+      } else if (key === KEY.UP || key === KEY.DOWN) {
+        // 忽略方向键
+      } else if (key.length === 1 && key !== KEY.SPACE) {
+        // 普通字符（空格单独处理）
+        buf.push(key);
+        process.stdout.write(key);
+      } else if (key === KEY.SPACE) {
+        buf.push(' ');
+        process.stdout.write(' ');
+      }
+    }
+  } finally {
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+  }
+
+  process.stdout.write('\n');
+  const result = buf.join('').trim();
+  return result || defaultValue;
+}
+
+// ================================================================
+// 确认（Y/N，回车确认，ESC 返回 -1）
+// ================================================================
+
+async function confirm(label: string, defaultYes = true): Promise<boolean | -1> {
+  const hint = defaultYes ? '[Y/n]' : '[y/N]';
+  process.stdout.write(`${label} ${hint}: `);
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+
+  try {
+    while (true) {
+      const key = await readKey();
+      if (key === KEY.ENTER) {
+        process.stdout.write('\n');
+        return defaultYes;
+      } else if (key === KEY.ESC) {
+        process.stdout.write('\x1B[0K\n');
+        return -1;
+      } else if (key.toLowerCase() === 'y') {
+        process.stdout.write('Y\n');
+        return true;
+      } else if (key.toLowerCase() === 'n') {
+        process.stdout.write('N\n');
+        return false;
+      }
+    }
+  } finally {
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+  }
+}
+
+// ================================================================
+// IM 平台配置定义
+// ================================================================
+
+const IM_PLATFORMS = [
+  { value: 'feishu', label: '飞书', desc: 'WebSocket 长连接' },
+  { value: 'telegram', label: 'Telegram', desc: '长轮询' },
+  { value: 'wecom', label: '企业微信', desc: '扫码绑定 + WebSocket' },
+  { value: 'wechat', label: '个人微信', desc: 'iLink + QR 扫码' },
+];
+
+/** 每种 IM 需要的凭证字段 */
+const IM_FIELDS: Record<string, { key: string; label: string; required: boolean }[]> = {
+  feishu: [
+    { key: 'appId', label: '飞书 App ID (cli_...)', required: true },
+    { key: 'appSecret', label: '飞书 App Secret', required: true },
+  ],
+  telegram: [
+    { key: 'appId', label: 'Bot Token', required: true },
+    { key: 'proxy', label: '代理地址（留空不使用）', required: false },
+  ],
+  wecom: [
+    // 企业微信使用扫码绑定，无需预填凭证，启动时自动触发 QR 扫码
+  ],
+  wechat: [
+    // 微信通过 iLink + QR 扫码认证，无需预填凭证
+    { key: 'botId', label: 'iLink Bot ID（留空使用 QR 扫码）', required: false },
+    { key: 'botToken', label: 'iLink Bot Token（留空使用 QR 扫码）', required: false },
+  ],
+};
 
 // ================================================================
 // 主流程
 // ================================================================
+
 export async function runSetupWizard(): Promise<void> {
   const dataDir = getDataDir();
   const configPath = path.join(dataDir, 'config.json');
-  const providersPath = path.join(dataDir, 'providers.json');
-  const opencodePath = path.join(dataDir, 'opencode.json');
 
   console.log('\n╔══════════════════════════════════════════════╗');
   console.log('║   🚀  imtoagent 配置向导                     ║');
-  console.log('╚══════════════════════════════════════════════╝\n');
-  console.log(`数据目录: ${dataDir}\n`);
+  console.log('╚══════════════════════════════════════════════╝');
+  console.log(`\n数据目录: ${dataDir}`);
+  console.log(`操作提示: ↑↓/空格 切换  |  回车确认  |  ESC 返回\n`);
 
   // ===== Step 1: 检测已有配置 =====
   let existingConfig: any = null;
+  let mergeMode = false;
+
   if (fs.existsSync(configPath)) {
-    console.log('📋 检测到已有配置。');
-    console.log('   [1] 覆盖现有配置');
-    console.log('   [2] 合并（保留现有 bot，添加新的）');
-    console.log('   [3] 退出');
-
-    const choice = await prompt('请选择 (1/2/3): ');
-    if (choice === '3' || choice.toLowerCase() === 'exit') {
-      console.log('👋 已取消');
-      process.exit(0);
-    }
+    console.log('📋 检测到已有配置\n');
+    const idx = await selectMenu('选择操作', ['覆盖现有配置', '合并（保留现有 Bot）', '退出']);
+    if (idx === -1) return; // ESC
+    if (idx === 2) { console.log('👋 已取消'); process.exit(0); }
+    if (idx === 1) mergeMode = true;
 
     try {
       existingConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
     } catch {
       console.log('⚠️  现有配置文件解析失败，将重新生成');
       existingConfig = null;
+      mergeMode = false;
     }
   }
 
-  // ===== Step 1.5: 检测后端安装状态 =====
-  console.log('📌 检测后端 Agent...\n');
+  // ===== Step 2: 检测后端 =====
+  console.log('\n📌 检测后端 Agent...\n');
   const backendStatus = checkAllBackends();
   console.log(formatBackendStatus(backendStatus));
 
   const installedBackends = backendStatus.filter(b => b.installed);
   if (installedBackends.length === 0) {
     console.log('\n⚠️  未检测到任何后端 Agent。');
-    console.log('你需要先安装至少一个后端 Agent 才能使用 imtoagent。');
-    console.log('\n推荐安装:');
+    console.log('推荐安装:');
     console.log('  npm install -g @anthropic-ai/claude-agent-sdk   # Claude Code');
     console.log('  npm install -g @openai/codex                    # Codex');
     console.log('  npm install -g opencode                         # OpenCode');
-    const proceed = await promptChoice('暂不配置 Bot，先退出?', ['Y', 'N']);
-    if (proceed === 'Y') {
-      console.log('\n👋 安装后端后请重新运行 "imtoagent setup"');
-      process.exit(0);
-    }
-    console.log('\n⚠️  你可以继续配置 Bot，但启动网关后发消息会报错，直到后端安装完成。\n');
+    const r = await confirm('是否继续配置？（启动后发消息会报错，直到后端安装）', false);
+    if (r === false || r === -1) { console.log('\n👋 安装后端后请重新运行 "imtoagent setup"'); process.exit(0); }
+    console.log('\n⚠️  已跳过，你可以稍后安装后端。\n');
   } else {
-    console.log(`\n✅ 已安装 ${installedBackends.length} 个后端: ${installedBackends.map(b => b.label).join(', ')}\n`);
+    console.log(`\n✅ 已安装: ${installedBackends.map(b => b.label).join(', ')}\n`);
   }
 
-  // ===== Step 2: 配置 Bot =====
-  console.log('📌 Step 2: 配置 Bot\n');
-
-  const bots: any[] = existingConfig?.bots && (await promptChoice('保留现有 Bot?', ['Y', 'N'])) !== 'N'
-    ? [...existingConfig.bots]
-    : [];
-
-  let addMore = true;
-  while (addMore) {
-    console.log(`\n--- 添加新 Bot (已有 ${bots.length} 个) ---`);
-
-    const name = await prompt('Bot 名称 (如 ClaudeBot): ');
-    if (!name) { addMore = false; continue; }
-
-    const imType = await promptChoice('IM 平台', ['feishu', 'telegram']);
-
-    // 后端选项：优先推荐已安装的，未安装的标 ⚠️
-    const backendOptions = backendStatus.map(b => {
-      const label = b.installed ? `${b.label} (v${b.version})` : `${b.label} ⚠️ 未安装`;
-      return { value: b.type, label };
-    });
-    const backendLabels = backendOptions.map(o => o.label);
-    const backendChoice = await promptChoice('后端', backendLabels);
-    const backend = backendOptions.find(o => o.label === backendChoice)?.value || 'claude';
-    const isBackendInstalled = backendStatus.find(b => b.type === backend)?.installed;
-
+  // ===== Step 3: 配置 Bot =====
+  console.log('📌 Step 3: 配置 Bot\n');
+
+  const bots: any[] = (mergeMode && existingConfig?.bots) ? [...existingConfig.bots] : [];
+
+  let addingBots = true;
+  while (addingBots) {
+    console.log(`\n--- 添加新 Bot (已有 ${bots.length} 个) ---\n`);
+
+    // 3a: 选择 IM 平台
+    const imLabels = IM_PLATFORMS.map(p => `${p.label}  ${p.desc}`);
+    const imIdx = await selectMenu('选择 IM 平台', imLabels);
+    if (imIdx === -1) { if (bots.length === 0) return; break; } // ESC
+    const imType = IM_PLATFORMS[imIdx].value;
+
+    // 3b: 自动生成 Bot 名称，可自定义
+    const defaultName = IM_PLATFORMS[imIdx].label + 'Bot';
+    const nameInput = await promptText('Bot 名称', defaultName);
+    if ((nameInput as any) === -1) { if (bots.length === 0) return; break; } // ESC
+    const botName = nameInput || defaultName; // 留空用默认
+
+    // 3c: 选择后端
+    const backendLabels = backendStatus.map(b =>
+      b.installed ? `${b.label} (v${b.version})` : `${b.label} ⚠️ 未安装`
+    );
+    const backendIdx = await selectMenu('选择后端', backendLabels);
+    if (backendIdx === -1) continue; // ESC 返回重新选 IM
+    const backend = backendStatus[backendIdx].type;
+    const isBackendInstalled = backendStatus[backendIdx].installed;
+
+    // 后端未安装 → 提示自动安装
     if (!isBackendInstalled) {
-      const installCmd = backendStatus.find(b => b.type === backend)?.installHint || '';
-      console.log(`\n⚠️  ${backend} 未安装。`);
-      console.log(`   安装提示: ${installCmd}\n`);
-
-      const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-      });
-
-      const answer = await new Promise<string>((resolve) => {
-        rl.question(`🔧 是否现在自动安装？[Y/n]: `, resolve);
-      });
-      rl.close();
-
-      if (answer.trim().toLowerCase() !== 'n') {
+      const installCmd = backendStatus[backendIdx].installHint || '';
+      console.log(`\n⚠️  ${backend} 未安装`);
+      console.log(`   ${installCmd}\n`);
+      const r = await confirm('是否现在自动安装?');
+      if (r === true) {
         const { installBackend } = await import('../utils/backend-check');
         const ok = await installBackend(backend as 'claude' | 'codex' | 'opencode');
-        if (!ok) {
-          console.log(`\n⚠️  安装失败，你可以稍后手动运行: ${installCmd}`);
-          const rl2 = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout,
-          });
-          const retry = await new Promise<string>((resolve) => {
-            rl2.question('是否仍然选择此 Bot？[y/N]: ', resolve);
-          });
-          rl2.close();
-          if (retry.trim().toLowerCase() !== 'y') {
-            addMore = (await promptChoice('继续添加其他 Bot?', ['Y', 'N'])) !== 'Y';
-            continue;
-          }
+        if (ok) {
+          console.log(`✅ ${backend} 已安装\n`);
         } else {
-          console.log(`✅ ${backend} 已安装，继续配置。\n`);
+          console.log(`⚠️  安装失败，可稍后手动运行: ${installCmd}\n`);
+          const r2 = await confirm('仍要继续配置此 Bot?');
+          if (r2 === false) continue;
         }
+      } else if (r === -1) {
+        continue; // ESC 返回
       } else {
-        console.log(`跳过安装。你可以稍后手动运行: ${installCmd}\n`);
-        const confirm = await promptChoice('仍要继续配置此 Bot？', ['Y', 'N']);
-        if (confirm !== 'Y') {
-          addMore = (await promptChoice('继续添加其他 Bot?', ['Y', 'N'])) !== 'Y';
-          continue;
-        }
+        console.log('跳过安装\n');
       }
     }
 
-    let appId = '', appSecret = '', proxy = '', cwd = '';
+    // 3d: 根据 IM 类型收集凭证
+    console.log(`\n--- ${IM_PLATFORMS.find(p => p.value === imType)?.label} 凭证 ---`);
+    const fields = IM_FIELDS[imType] || [];
+    const credentials: Record<string, string> = {};
 
-    if (imType === 'feishu') {
-      appId = await prompt('飞书 App ID (cli_...): ');
-      appSecret = await prompt('飞书 App Secret: ');
-    } else {
-      appId = await prompt('Telegram Bot Token: ');
-      proxy = await prompt('代理地址 (留空不使用代理): ') || '';
+    for (const field of fields) {
+      const val = await promptText(field.label + (field.required ? '' : '（可选）'));
+      if ((val as any) === -1) { credentials._escaped = 'true'; break; } // ESC
+      credentials[field.key] = val;
     }
+    if (credentials._escaped) continue; // ESC 返回重新选后端
+
+    // 3e: 工作目录
+    const cwd = await promptText('工作目录', os.homedir());
+    if ((cwd as any) === -1) continue;
 
-    cwd = await prompt('工作目录 (如 /Users/keyi/Desktop，留空用默认): ') || os.homedir();
+    // 生成唯一 ID（UUID，用于目录隔离，改名不影响）
+    const botId = randomUUID();
 
+    // 构建 Bot 配置（不同 IM 需要的字段不同）
     const bot: any = {
-      name,
-      appId,
-      appSecret,
+      id: botId,
+      name: botName,
       backend,
-      im: imType === 'feishu' ? undefined : 'telegram',
-      cwd,
+      cwd: cwd || os.homedir(),
     };
-    if (proxy) bot.proxy = proxy;
+
+    // 飞书需要 appId + appSecret
+    if (imType === 'feishu') {
+      bot.appId = credentials.appId || '';
+      bot.appSecret = credentials.appSecret || '';
+    }
+    // Telegram 需要 appId（Bot Token），可选 proxy
+    else if (imType === 'telegram') {
+      bot.appId = credentials.appId || '';
+      if (credentials.proxy) bot.proxy = credentials.proxy;
+    }
+    // 企业微信：扫码绑定，无需预填凭证（可选 botId/secret）
+    else if (imType === 'wecom') {
+      bot.im = 'wecom';
+      if (credentials.botId) bot.botId = credentials.botId;
+      if (credentials.secret) bot.secret = credentials.secret;
+    }
+    // 个人微信：可选 botId/botToken，留空则 QR 扫码
+    else if (imType === 'wechat') {
+      bot.im = 'wechat';
+      if (credentials.botId) bot.botId = credentials.botId;
+      if (credentials.botToken) bot.botToken = credentials.botToken;
+      if (credentials.ilinkUserId) bot.ilinkUserId = credentials.ilinkUserId;
+    }
+    // 默认：非飞书平台加 im 字段
+    else {
+      bot.im = imType;
+    }
 
     // 检查重名
-    const existing = bots.findIndex(b => b.name === name);
-    if (existing >= 0) {
-      bots[existing] = bot;
+    const existingIdx = bots.findIndex(b => b.name === botName);
+    if (existingIdx >= 0) {
+      bots[existingIdx] = bot;
       console.log(`✅ 已替换: ${name}`);
     } else {
       bots.push(bot);
       console.log(`✅ 已添加: ${name}`);
     }
 
-    addMore = (await promptChoice('继续添加 Bot?', ['Y', 'N'])) === 'Y';
+    // 是否继续添加
+    const r = await confirm('继续添加其他 Bot?', true);
+    if (r === -1) addingBots = false; // ESC = 不添加了，进入下一步
+    else addingBots = (r === true);
   }
 
   if (bots.length === 0) {
     console.log('\n⚠️  未配置任何 Bot。');
-    if ((await promptChoice('至少配置一个 Bot 吗?', ['Y', 'N'])) === 'Y') {
-      return runSetupWizard(); // 重新开始
-    }
+    const r = await confirm('至少配置一个 Bot 吗?');
+    if (r === true) return runSetupWizard();
+    console.log('\n⚠️  至少需要一个 Bot，配置已取消');
+    return;
   }
 
-  // ===== Step 3: 配置模型供应商 =====
-  console.log('\n📌 Step 3: 配置模型供应商\n');
+  // ===== Step 4: 配置模型供应商 =====
+  console.log('\n📌 Step 4: 配置模型供应商\n');
 
   const providers: Record<string, any> = {};
-  let existingProviders = existingConfig?.providers || {};
-  const keepProviders = Object.keys(existingProviders).length > 0
-    && (await promptChoice('保留现有供应商?', ['Y', 'N'])) !== 'N';
-
-  if (keepProviders) {
-    Object.assign(providers, existingProviders);
+  if (mergeMode && existingConfig?.providers) {
+    Object.assign(providers, existingConfig.providers);
+    console.log(`✅ 已保留 ${Object.keys(providers).length} 个现有供应商\n`);
   }
 
-  let addProvider = true;
-  while (addProvider) {
-    console.log('\n--- 添加新供应商 ---');
-    const provName = await prompt('供应商名称 (如 deepseek, dashscope): ');
-    if (!provName) { addProvider = false; continue; }
+  let addingProviders = true;
+  while (addingProviders) {
+    console.log('--- 添加新供应商 ---\n');
+    const provName = await promptText('供应商名称 (如 deepseek, dashscope)');
+    if ((provName as any) === -1) { addingProviders = false; continue; }
+    if (!provName) { addingProviders = false; continue; }
 
     if (providers[provName]) {
-      console.log(`⚠️  供应商 "${provName}" 已存在，将覆盖`);
+      console.log(`⚠️  供应商 "${provName}" 已存在，将覆盖\n`);
     }
 
-    const baseUrl = await prompt('Base URL (如 https://api.deepseek.com/v1): ');
-    const apiKey = await prompt('API Key: ');
-    const modelsStr = await prompt('模型列表 (逗号分隔，如 deepseek-v4-pro,deepseek-v4-flash): ');
-    const models = modelsStr.split(',').map(s => s.trim()).filter(Boolean);
-    const format = await promptChoice('API 格式', ['openai', 'anthropic']);
+    const baseUrl = await promptText('Base URL (如 https://api.deepseek.com/v1)');
+    if ((baseUrl as any) === -1) continue;
+    const apiKey = await promptText('API Key');
+    if ((apiKey as any) === -1) continue;
+    const modelsStr = await promptText('模型列表 (逗号分隔，如 deepseek-v4-pro,deepseek-v4-flash)');
+    if ((modelsStr as any) === -1) continue;
+    const models = (modelsStr || '').split(',').map(s => s.trim()).filter(Boolean);
+
+    const formatIdx = await selectMenu('API 格式', ['openai', 'anthropic']);
+    if (formatIdx === -1) continue;
+    const format = ['openai', 'anthropic'][formatIdx];
+
+    const priceInput = await promptText('价格 (入/出 每百万 Token，如 0.55,2.19，留空跳过)');
+    if ((priceInput as any) === -1) continue;
 
     const pricing: any = {};
-    const priceInput = await prompt('价格 (入/出 每百万 Token，如 0.55,2.19，留空跳过): ');
     if (priceInput) {
       const parts = priceInput.split(',').map(s => parseFloat(s.trim()));
       if (parts.length === 2 && !isNaN(parts[0]) && !isNaN(parts[1])) {
@@ -224,13 +433,21 @@ export async function runSetupWizard(): Promise<void> {
     }
 
     providers[provName] = { baseUrl, apiKey, models, format, ...(Object.keys(pricing).length ? { pricing } : {}) };
-    console.log(`✅ 已添加: ${provName}`);
+    console.log(`✅ 已添加: ${provName}\n`);
+
+    const r = await confirm('继续添加供应商?', false);
+    if (r === -1) addingProviders = false;
+    else addingProviders = (r === true);
+  }
 
-    addProvider = (await promptChoice('继续添加供应商?', ['Y', 'N'])) === 'Y';
+  if (Object.keys(providers).length === 0) {
+    console.log('\n⚠️  未配置任何供应商。');
+    const r = await confirm('至少配置一个供应商吗?');
+    if (r === true) { addingProviders = true; }
   }
 
-  // ===== Step 4: 选择默认模型 =====
-  console.log('\n📌 Step 4: 选择默认模型\n');
+  // ===== Step 5: 选择默认模型 =====
+  console.log('\n📌 Step 5: 选择默认模型\n');
 
   const allModels: string[] = [];
   for (const [provName, prov] of Object.entries(providers)) {
@@ -242,22 +459,26 @@ export async function runSetupWizard(): Promise<void> {
   let defaultModel = '';
   if (allModels.length > 0) {
     const existingDefault = existingConfig?.defaultModel || allModels[0];
-    const defaultChoice = await prompt(`默认模型 [${existingDefault}]: `);
-    defaultModel = defaultChoice || existingDefault;
+    const val = await promptText('默认模型', existingDefault);
+    defaultModel = (val as any) === -1 ? existingDefault : (val || existingDefault);
   } else {
-    defaultModel = await prompt('默认模型 (供应商/模型名): ') || 'deepseek/deepseek-v4-pro';
+    defaultModel = await promptText('默认模型 (供应商/模型名)') || 'deepseek/deepseek-v4-pro';
+    if ((defaultModel as any) === -1) defaultModel = 'deepseek/deepseek-v4-pro';
   }
 
-  // ===== Step 5: 生成灵魂文件 =====
-  console.log('\n📌 Step 5: 生成灵魂文件\n');
+  // ===== Step 6: 生成灵魂文件 =====
+  console.log('\n📌 Step 6: 生成灵魂文件\n');
 
   for (const bot of bots) {
-    const botSoulDir = getSoulDir(bot.name);
+    const botSoulDir = getSoulDir(getBotKey(bot));
     const templateSoulDir = path.join(getPkgDir(), 'templates', 'soul.template');
 
-    if (fs.existsSync(botSoulDir) && (await promptChoice(`已存在 ${bot.name} 的灵魂文件，重新生成?`, ['Y', 'N'])) !== 'Y') {
-      console.log(`⏭  跳过: ${bot.name}`);
-      continue;
+    if (fs.existsSync(botSoulDir)) {
+      const r = await confirm(`已存在 ${bot.name} 的灵魂文件，重新生成?`, false);
+      if (r === -1 || r === false) {
+        console.log(`⏭  跳过: ${bot.name}`);
+        continue;
+      }
     }
 
     fs.mkdirSync(botSoulDir, { recursive: true });
@@ -267,29 +488,24 @@ export async function runSetupWizard(): Promise<void> {
       const tmplPath = path.join(templateSoulDir, sf);
       const destPath = path.join(botSoulDir, sf);
 
-      if (fs.existsSync(destPath) && !fs.existsSync(tmplPath)) {
-        continue; // 已有且无模板，保留
-      }
+      if (fs.existsSync(destPath) && !fs.existsSync(tmplPath)) continue;
 
       if (fs.existsSync(tmplPath)) {
         let content = fs.readFileSync(tmplPath, 'utf-8');
-        // 替换模板变量
         content = content.replace(/\{\{backend\}\}/g, bot.backend);
         content = content.replace(/\{\{cwd\}\}/g, bot.cwd || os.homedir());
         content = content.replace(/\{\{botName\}\}/g, bot.name);
         fs.writeFileSync(destPath, content);
       }
     }
-    console.log(`✅ ${bot.name}: 灵魂文件已生成 → ${botSoulDir}`);
+    console.log(`✅ ${bot.name}: 灵魂文件 → ${botSoulDir}`);
   }
 
-  // ===== Step 6: 写入配置文件 =====
-  console.log('\n📌 Step 6: 写入配置文件\n');
+  // ===== Step 7: 写入配置文件 =====
+  console.log('\n📌 Step 7: 写入配置文件\n');
 
-  // 确保数据目录存在
   fs.mkdirSync(dataDir, { recursive: true });
 
-  // config.json
   const config: any = {
     system: existingConfig?.system || {
       defaultProjectDir: os.homedir(),
@@ -327,46 +543,38 @@ export async function runSetupWizard(): Promise<void> {
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
   console.log(`✅ ${configPath}`);
 
-  // providers.json
-  const providersFile: any = {
-    providers,
-    defaultModel,
-    modelAliases: config.modelAliases,
-  };
+  const providersFile: any = { providers, defaultModel, modelAliases: config.modelAliases };
+  const providersPath = path.join(dataDir, 'providers.json');
   fs.writeFileSync(providersPath, JSON.stringify(providersFile, null, 2) + '\n');
   console.log(`✅ ${providersPath}`);
 
-  // opencode.json（从模板复制）
+  const opencodePath = path.join(dataDir, 'opencode.json');
   const opencodeTemplate = getTemplatePath('opencode.template.json');
   if (fs.existsSync(opencodeTemplate)) {
-    const opencodeContent = fs.readFileSync(opencodeTemplate, 'utf-8');
-    fs.writeFileSync(opencodePath, opencodeContent);
+    fs.writeFileSync(opencodePath, fs.readFileSync(opencodeTemplate, 'utf-8'));
     console.log(`✅ ${opencodePath}`);
   }
 
-  // 创建必要的子目录
   fs.mkdirSync(path.join(dataDir, 'sessions'), { recursive: true });
   fs.mkdirSync(path.join(dataDir, 'logs'), { recursive: true });
   console.log('✅ 子目录已创建 (sessions/, logs/)');
 
-  // ===== Step 7: 完成 =====
+  // ===== 完成 =====
   console.log('\n╔══════════════════════════════════════════════╗');
   console.log('║   ✅ 配置完成！                              ║');
   console.log('╚══════════════════════════════════════════════╝\n');
   console.log(`Bot: ${bots.map(b => b.name).join(', ')}`);
   console.log(`默认模型: ${defaultModel}`);
-  console.log(`供应商: ${Object.keys(providers).join(', ')}`);
+  console.log(`供应商: ${Object.keys(providers).join(', ') || '无'}`);
   console.log(`\n下一步:`);
   console.log(`  imtoagent start    启动网关`);
-  console.log(`  imtoagent status   查看状态`);
-  console.log();
+  console.log(`  imtoagent status   查看状态\n`);
 }
 
 // ================================================================
 // 工具函数
 // ================================================================
 
-/** 构建默认模型别名 */
 function buildDefaultAliases(defaultModel: string): Record<string, string> {
   return {
     default: defaultModel,
@@ -377,48 +585,3 @@ function buildDefaultAliases(defaultModel: string): Record<string, string> {
     opencode: defaultModel,
   };
 }
-
-/** 交互式 prompt（Bun 原生） */
-async function prompt(question: string): Promise<string> {
-  // Bun 环境使用原生 prompt
-  if (typeof Bun !== 'undefined' && typeof Bun.stdin !== 'undefined') {
-    // 尝试使用 readline
-    const readline = await import('readline');
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-
-    return new Promise(resolve => {
-      rl.question(question, answer => {
-        rl.close();
-        resolve(answer.trim());
-      });
-    });
-  }
-
-  // fallback
-  console.error('⚠️  无法读取用户输入，请检查运行环境');
-  return '';
-}
-
-/** 选项选择（Y/N 或自定义选项） */
-async function promptChoice(question: string, options: string[]): Promise<string> {
-  const optStr = options.join('/');
-  const answer = await prompt(`${question} [${optStr}]: `);
-  const upper = answer.toUpperCase();
-
-  // 精确匹配（全大写比较，返回原始值）
-  const exact = options.find(o => o.toUpperCase() === upper);
-  if (exact) return exact;
-
-  // 简写匹配（首字母）
-  if (upper.length === 1) {
-    const short = options.find(o => o[0].toUpperCase() === upper);
-    if (short) return short;
-  }
-
-  // 默认返回第一个
-  if (!answer && options.length > 0) return options[0];
-  return upper || options[0];
-}

package/modules/core/config.ts

@@ -96,7 +96,7 @@ export class FileConfigManager implements ConfigManager {
     // 加载各 bot 的模型配置
     if (this.rawConfig?.bots) {
       for (const bot of this.rawConfig.bots) {
-        this._loadBotConfig(bot.name);
+        this._loadBotConfig(botKey);
       }
     }
   }
@@ -118,36 +118,36 @@ export class FileConfigManager implements ConfigManager {
   }
 
   /** 加载 Bot 级别配置 */
-  private _loadBotConfig(botName: string): void {
+  private _loadBotConfig(botKey: string): void {
     const sessionsDir = getSessionsDir();
-    const configPath = path.join(sessionsDir, `${botName}_config.json`);
+    const configPath = path.join(sessionsDir, `${botKey}_config.json`);
 
     try {
       if (fs.existsSync(configPath)) {
         const raw = fs.readFileSync(configPath, 'utf-8');
-        this.botConfigs.set(botName, JSON.parse(raw));
+        this.botConfigs.set(botKey, JSON.parse(raw));
       } else {
-        this.botConfigs.set(botName, {});
+        this.botConfigs.set(botKey, {});
       }
     } catch (e: any) {
-      console.error(`[Config] 加载 bot ${botName} 配置失败: ${e.message}`);
-      this.botConfigs.set(botName, {});
+      console.error(`[Config] 加载 bot ${botKey} 配置失败: ${e.message}`);
+      this.botConfigs.set(botKey, {});
     }
   }
 
   /** 保存 Bot 级别配置 */
-  private _saveBotConfig(botName: string, config: BotLevelConfig): void {
+  private _saveBotConfig(botKey: string, config: BotLevelConfig): void {
     const sessionsDir = getSessionsDir();
-    const configPath = path.join(sessionsDir, `${botName}_config.json`);
+    const configPath = path.join(sessionsDir, `${botKey}_config.json`);
 
     try {
       if (!fs.existsSync(sessionsDir)) {
         fs.mkdirSync(sessionsDir, { recursive: true });
       }
-      this.botConfigs.set(botName, config);
+      this.botConfigs.set(botKey, config);
       fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
     } catch (e: any) {
-      console.error(`[Config] 保存 bot ${botName} 配置失败: ${e.message}`);
+      console.error(`[Config] 保存 bot ${botKey} 配置失败: ${e.message}`);
     }
   }
 
@@ -249,10 +249,10 @@ export class FileConfigManager implements ConfigManager {
   }
 
   /** 保存 Bot 活跃模型 */
-  saveActiveModel(botName: string, modelSpec: string): void {
-    const botLevel = this.botConfigs.get(botName) || {};
+  saveActiveModel(botKey: string, modelSpec: string): void {
+    const botLevel = this.botConfigs.get(botKey) || {};
     botLevel.activeModel = modelSpec;
-    this._saveBotConfig(botName, botLevel);
+    this._saveBotConfig(botKey, botLevel);
 
     // 同时更新全局配置
     if (this.rawConfig) {
@@ -267,9 +267,9 @@ export class FileConfigManager implements ConfigManager {
   }
 
   /** 保存 Bot 模型别名 */
-  saveModelAliases(botName: string, aliases: Record<string, string>): void {
-    const botLevel = this.botConfigs.get(botName) || {};
+  saveModelAliases(botKey: string, aliases: Record<string, string>): void {
+    const botLevel = this.botConfigs.get(botKey) || {};
     botLevel.modelAliases = aliases;
-    this._saveBotConfig(botName, botLevel);
+    this._saveBotConfig(botKey, botLevel);
   }
 }

package/modules/core/session.ts

@@ -85,24 +85,24 @@ export class FileSessionManager implements SessionManager {
   private cache = new Map<string, Map<string, Session>>();
 
   /** 获取 Session 文件路径 */
-  private sessionPath(botName: string, chatId: string): string {
+  private sessionPath(botKey: string, chatId: string): string {
     const sessionsBase = getSessionsDir();
-    const botDir = path.join(sessionsBase, botName);
+    const botDir = path.join(sessionsBase, botKey);
     return path.join(botDir, `${chatId}.memory.json`);
   }
 
   /** 确保目录存在 */
-  private ensureDir(botName: string): void {
+  private ensureDir(botKey: string): void {
     const sessionsBase = getSessionsDir();
-    const botDir = path.join(sessionsBase, botName);
+    const botDir = path.join(sessionsBase, botKey);
     if (!fs.existsSync(botDir)) {
       fs.mkdirSync(botDir, { recursive: true });
     }
   }
 
-  async getOrCreate(botName: string, chatId: string, userId: string): Promise<Session> {
+  async getOrCreate(botKey: string, chatId: string, userId: string): Promise<Session> {
     // 先查缓存
-    const botCache = this.cache.get(botName);
+    const botCache = this.cache.get(botKey);
     if (botCache) {
       const cached = botCache.get(chatId);
       if (cached) {
@@ -112,8 +112,8 @@ export class FileSessionManager implements SessionManager {
     }
 
     // 从文件加载
-    const filePath = this.sessionPath(botName, chatId);
-    this.ensureDir(botName);
+    const filePath = this.sessionPath(botKey, chatId);
+    this.ensureDir(botKey);
 
     let session: Session;
 
@@ -147,10 +147,10 @@ export class FileSessionManager implements SessionManager {
     }
 
     // 缓存
-    if (!this.cache.has(botName)) {
-      this.cache.set(botName, new Map());
+    if (!this.cache.has(botKey)) {
+      this.cache.set(botKey, new Map());
     }
-    this.cache.get(botName)!.set(chatId, session);
+    this.cache.get(botKey)!.set(chatId, session);
 
     return session;
   }
@@ -170,8 +170,8 @@ export class FileSessionManager implements SessionManager {
     };
   }
 
-  persist(botName: string, session: Session): void {
-    this.ensureDir(botName);
+  persist(botKey: string, session: Session): void {
+    this.ensureDir(botKey);
 
     // 写入时保持旧格式兼容：将 metadata 中的旧 ID 也写入顶层
     const output: Record<string, any> = {
@@ -203,7 +203,7 @@ export class FileSessionManager implements SessionManager {
     // metadata 完整保存
     output.metadata = session.metadata;
 
-    const filePath = this.sessionPath(botName, session.chatId);
+    const filePath = this.sessionPath(botKey, session.chatId);
     try {
       fs.writeFileSync(filePath, JSON.stringify(output, null, 2));
     } catch (e: any) {
@@ -211,15 +211,15 @@ export class FileSessionManager implements SessionManager {
     }
   }
 
-  delete(botName: string, chatId: string): void {
+  delete(botKey: string, chatId: string): void {
     // 清除缓存
-    const botCache = this.cache.get(botName);
+    const botCache = this.cache.get(botKey);
     if (botCache) {
       botCache.delete(chatId);
     }
 
     // 删除文件
-    const filePath = this.sessionPath(botName, chatId);
+    const filePath = this.sessionPath(botKey, chatId);
     try {
       if (fs.existsSync(filePath)) {
         fs.unlinkSync(filePath);
@@ -229,8 +229,8 @@ export class FileSessionManager implements SessionManager {
     }
   }
 
-  cleanupIdle(botName: string, timeoutMs: number): void {
-    const botCache = this.cache.get(botName);
+  cleanupIdle(botKey: string, timeoutMs: number): void {
+    const botCache = this.cache.get(botKey);
     if (!botCache) return;
 
     const now = Date.now();
@@ -248,8 +248,8 @@ export class FileSessionManager implements SessionManager {
     }
   }
 
-  listActive(botName: string): Session[] {
-    const botCache = this.cache.get(botName);
+  listActive(botKey: string): Session[] {
+    const botCache = this.cache.get(botKey);
     if (!botCache) return [];
     return Array.from(botCache.values());
   }

package/modules/core/types.ts

@@ -170,15 +170,15 @@ export interface MessageContext {
 /** Session 管理器 */
 export interface SessionManager {
   /** 获取或创建 Session */
-  getOrCreate(botName: string, chatId: string, userId: string): Promise<Session>;
+  getOrCreate(botKey: string, chatId: string, userId: string): Promise<Session>;
   /** 持久化 Session */
-  persist(botName: string, session: Session): void;
+  persist(botKey: string, session: Session): void;
   /** 删除 Session */
-  delete(botName: string, chatId: string): void;
+  delete(botKey: string, chatId: string): void;
   /** 清理空闲 Session */
-  cleanupIdle(botName: string, timeoutMs: number): void;
+  cleanupIdle(botKey: string, timeoutMs: number): void;
   /** 列出所有活跃 Session */
-  listActive(botName: string): Session[];
+  listActive(botKey: string): Session[];
 }
 
 /** 错误处理器 */
@@ -233,6 +233,8 @@ export interface ErrorContext {
 // ================================================================
 
 export interface BotConfig {
+  /** 唯一标识（UUID，用于目录/文件隔离，改名不影响） */
+  id?: string;
   name: string;
   backend: string; // 'claude' | 'codex' | 'opencode'
   appId: string;

package/modules/prompt-builder.ts

@@ -37,8 +37,8 @@ export const DEFAULT_TERMINAL_CAPS: IMCapabilities = {
 // 从 ~/Desktop/imtoagent/soul/{botName}/ 按顺序加载
 // 加载顺序：rules → identity → profile → workspace → skills
 // ================================================================
-export function loadSoul(botName: string): string {
-  const soulDir = getSoulDir(botName);
+export function loadSoul(botKey: string): string {
+  const soulDir = getSoulDir(botKey);
   const soulOrder = ['rules.md', 'identity.md', 'profile.md', 'workspace.md', 'skills.md'];
   const parts: string[] = [];
   try {
@@ -64,7 +64,7 @@ export interface PromptBuilderContext {
   /** 当 imModule 不可用时，手动指定的能力 */
   caps?: IMCapabilities | null;
   /** Bot 名称，用于加载 Soul */
-  botName: string;
+  botKey: string;
   /** Agent 特有的额外系统提示（如工具使用指南、工作目录约束等） */
   agentInstructions?: string;
 }

package/modules/types.ts

@@ -134,6 +134,8 @@ export interface IMModule {
 // ================================================================
 
 export interface BotConfig {
+  /** 唯一标识（UUID，用于目录隔离，改名不影响） */
+  id?: string;
   name: string;
   backend: 'claude' | 'codex' | 'opencode';
   appId: string;

package/modules/utils/backend-check.ts

@@ -3,6 +3,8 @@
 // ================================================================
 
 import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
 
 export interface BackendInfo {
   type: 'claude' | 'codex' | 'opencode';
@@ -18,20 +20,64 @@ const BACKEND_DEFS: Omit<BackendInfo, 'installed' | 'version'>[] = [
   { type: 'opencode', label: 'OpenCode',   installHint: 'npm install -g opencode' },
 ];
 
-function checkOne(b: Omit<BackendInfo, 'installed' | 'version'>): BackendInfo {
+// ================================================================
+// 获取 npm 全局 bin 目录
+// 解决 PATH 未包含 npm global bin 时的检测失败问题
+// ================================================================
+
+let _cachedNpmBin: string | null | undefined = undefined;
+
+function getNpmGlobalBin(): string | null {
+  if (_cachedNpmBin !== undefined) return _cachedNpmBin;
   try {
-    let version: string | null = null;
-    if (b.type === 'claude') {
-      version = execSync('claude --version', { encoding: 'utf-8', timeout: 5000 }).trim();
-    } else if (b.type === 'codex') {
-      version = execSync('codex --version', { encoding: 'utf-8', timeout: 5000 }).trim();
-    } else {
-      version = execSync('opencode version', { encoding: 'utf-8', timeout: 5000 }).trim();
+    const prefix = execSync('npm get prefix', { encoding: 'utf-8', timeout: 5000 }).trim();
+    if (!prefix) {
+      _cachedNpmBin = null;
+      return null;
     }
+    const binDir = path.join(prefix, 'bin');
+    if (fs.existsSync(binDir)) {
+      _cachedNpmBin = binDir;
+      return binDir;
+    }
+    _cachedNpmBin = null;
+    return null;
+  } catch {
+    _cachedNpmBin = null;
+    return null;
+  }
+}
+
+function checkOne(b: Omit<BackendInfo, 'installed' | 'version'>): BackendInfo {
+  const versionCmd: Record<string, string> = {
+    claude: 'claude --version',
+    codex: 'codex --version',
+    opencode: 'opencode version',
+  };
+
+  // 先尝试 PATH 中的命令
+  try {
+    const version = execSync(versionCmd[b.type], { encoding: 'utf-8', timeout: 5000 }).trim();
     return { ...b, installed: true, version };
   } catch {
-    return { ...b, installed: false, version: null };
+    // PATH 中找不到，继续尝试 npm global bin
+  }
+
+  // fallback：直接从 npm global bin 目录运行
+  const npmBin = getNpmGlobalBin();
+  if (npmBin) {
+    const binPath = path.join(npmBin, b.type);
+    try {
+      if (fs.existsSync(binPath)) {
+        const version = execSync(`"${binPath}" --version`, { encoding: 'utf-8', timeout: 5000 }).trim();
+        return { ...b, installed: true, version };
+      }
+    } catch {
+      // bin 存在但执行失败，视为未安装
+    }
   }
+
+  return { ...b, installed: false, version: null };
 }
 
 export function checkAllBackends(): BackendInfo[] {
@@ -59,7 +105,8 @@ export function formatBackendStatus(backends: BackendInfo[]): string {
 
 /**
  * 自动安装缺失的后端 CLI
- * 使用 Bun.spawn 流式输出 npm install -g 的进度
+ * 使用 bash -lc 加载用户 shell 环境，确保 npm 在 PATH 中
+ * 流式输出安装进度，支持 Ctrl+C 中断
  */
 export async function installBackend(
   type: 'claude' | 'codex' | 'opencode',
@@ -74,10 +121,16 @@ export async function installBackend(
   console.log(`   命令: ${b.installHint}\n`);
 
   try {
-    const child = Bun.spawn(b.installHint.split(' '), {
+    // 获取 npm 全局 bin 目录，用于安装后验证（复用 getNpmGlobalBin 缓存）
+    const npmBinDir = getNpmGlobalBin();
+
+    // 用 zsh -ic 加载用户 shell 环境（匹配 macOS 默认 shell）
+    // 传入当前 PATH 环境变量，确保 npm 可执行文件可访问
+    const child = Bun.spawn(['zsh', '-ic', b.installHint], {
       stdout: 'pipe',
       stderr: 'pipe',
-      stdin: 'inherit',
+      stdin: 'ignore',
+      env: { ...process.env },
     });
 
     const decoder = new TextDecoder();
@@ -102,16 +155,35 @@ export async function installBackend(
 
     if (exitCode !== 0) {
       console.error(`\n❌ ${b.label} 安装失败 (退出码: ${exitCode})`);
+      console.error(`   可手动运行: ${b.installHint}`);
       return false;
     }
 
-    // 安装完成后验证
+    // 安装完成后验证 — 优先用 npm bin 目录直接检查
+    if (npmBinDir) {
+      const binPath = path.join(npmBinDir, b.type);
+      try {
+        if (fs.existsSync(binPath)) {
+          const version = execSync(`"${binPath}" --version`, { encoding: 'utf-8', timeout: 5000 }).trim();
+          console.log(`\n✅ ${b.label} 安装成功! 版本: ${version}`);
+          return true;
+        }
+      } catch {}
+    }
+
+    // fallback: 通过 PATH 查找
     const info = checkOne(b);
     if (info.installed) {
       console.log(`\n✅ ${b.label} 安装成功! 版本: ${info.version}`);
       return true;
     } else {
-      console.error(`\n❌ ${b.label} 安装后仍未检测到，请手动运行: ${b.installHint}`);
+      console.error(`\n❌ ${b.label} 安装后仍未检测到`);
+      if (npmBinDir) {
+        console.error(`   npm 全局 bin 目录: ${npmBinDir}`);
+        console.error(`   建议将该目录添加到 PATH，或手动运行: ${b.installHint}`);
+      } else {
+        console.error(`   请手动运行: ${b.installHint}`);
+      }
       return false;
     }
   } catch (e: any) {

package/modules/utils/paths.ts

@@ -191,8 +191,13 @@ export function getLogsDir(): string {
   return path.join(getDataDir(), 'logs');
 }
 
-export function getSoulDir(botName: string): string {
-  return path.join(getDataDir(), 'soul', botName);
+/** 解析 Bot 唯一 key：优先用 id（UUID），后向兼容用 name */
+export function getBotKey(bot: { id?: string; name: string }): string {
+  return bot.id || bot.name;
+}
+
+export function getSoulDir(botKey: string): string {
+  return path.join(getDataDir(), 'soul', botKey);
 }
 
 export function getRestoreMarkerPath(): string {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "imtoagent",
-  "version": "0.2.5",
-  "description": "IM \u2194 Agent \u7edf\u4e00\u7f51\u5173 \u2014 \u98de\u4e66/Telegram/\u5fae\u4fe1/\u4f01\u4e1a\u5fae\u4fe1\u5bf9\u63a5 Claude Code/Codex/OpenCode",
+  "version": "0.3.1",
+  "description": "IM ↔ Agent 统一网关 — 飞书/Telegram/微信/企业微信对接 Claude Code/Codex/OpenCode",
   "type": "module",
   "bin": {
     "imtoagent": "./bin/imtoagent.cjs"
@@ -53,4 +53,4 @@
     "url": "https://github.com/YOUR_USERNAME/imtoagent/issues"
   },
   "homepage": "https://github.com/YOUR_USERNAME/imtoagent#readme"
-}
+}