imtoagent 0.3.21 → 0.3.23

package/README.md

@@ -1,4 +1,4 @@
-# imtoagent — IM ↔ Agent Unified Gateway
+# IMtoAgent — IM ↔ Agent Unified Gateway
 
 Connect Feishu, Telegram, personal WeChat, and WeCom to AI coding agents like Claude Code, Codex (GPT), OpenCode, and more.
 
@@ -180,6 +180,34 @@ The interactive wizard will guide you through:
 | `imtoagent status` | Check running status |
 | `imtoagent restore` | Hot reload recovery |
 | `imtoagent daemon` | Foreground daemon mode (crash auto-restart) |
+| `imtoagent update-system` | Upgrade IMtoAgent itself via npm |
+| `imtoagent update-backend [type]` | Upgrade an agent backend (claude/codex/opencode) |
+
+### Upgrading
+
+**Upgrade IMtoAgent itself:**
+
+```bash
+imtoagent update-system
+```
+
+This runs `npm update -g imtoagent` and verifies the new version.
+
+**Upgrade agent backends:**
+
+```bash
+# Auto-detect current Bot's backend and upgrade it
+imtoagent update-backend
+
+# Upgrade a specific backend
+imtoagent update-backend codex
+imtoagent update-backend claude
+imtoagent update-backend opencode
+```
+
+The command detects how each backend was installed (npm, brew, or manual) and uses the correct upgrade command automatically.
+
+### Running Modes
 
 ### Running Modes
 

package/bin/imtoagent-real

@@ -26,7 +26,7 @@ const command = process.argv[2];
 
 switch (command) {
   case 'setup':
-    await cmdSetup();
+    await cmdSetup(process.argv[3]);
     break;
   case 'start':
     await cmdStart();
@@ -46,6 +46,14 @@ switch (command) {
   case 'daemon':
     await cmdDaemon();
     break;
+  case 'update-system':
+    await cmdUpdateSystem();
+    break;
+  case 'update-backend': {
+    const backendType = process.argv[3] as 'claude' | 'codex' | 'opencode' | undefined;
+    await cmdUpdateBackend(backendType);
+    break;
+  }
   case undefined: {
     const dataDir = getDataDir();
     const configPath = path.join(dataDir, 'config.json');
@@ -89,13 +97,17 @@ function printHelp() {
 imtoagent — IM ↔ Agent Unified Gateway
 
 Usage:
-  imtoagent setup     Interactive setup wizard
-  imtoagent start     Start gateway in background (returns immediately)
-  imtoagent run       Start gateway in foreground (Ctrl+C to stop)
-  imtoagent stop      Stop gateway
-  imtoagent status    Check running status
-  imtoagent restore   Hot reload
-  imtoagent daemon    Foreground daemon with auto-restart (for launchd/systemd)
+  imtoagent setup               Interactive setup wizard
+  imtoagent setup --quick       Quick mode (sandbox workspace, skip workspace step)
+  imtoagent start               Start gateway in background (returns immediately)
+  imtoagent run                 Start gateway in foreground (Ctrl+C to stop)
+  imtoagent stop                Stop gateway
+  imtoagent status              Check running status
+  imtoagent restore             Hot reload
+  imtoagent daemon              Foreground daemon with auto-restart (for launchd/systemd)
+  imtoagent update-system       Upgrade imtoagent itself
+  imtoagent update-backend      Upgrade current Bot's backend
+  imtoagent update-backend TYPE Upgrade specific backend (codex|claude|opencode)
 
 Data directory: ${getDataDir()}
 `);
@@ -104,9 +116,10 @@ Data directory: ${getDataDir()}
 // ================================================================
 // setup — interactive wizard
 // ================================================================
-async function cmdSetup() {
+async function cmdSetup(mode) {
+  const quick = mode === '--quick' || mode === '-q';
   const { runSetupWizard } = await import('../modules/cli/setup');
-  await runSetupWizard();
+  await runSetupWizard(quick ? { quick: true } : undefined);
 }
 
 // ================================================================
@@ -485,3 +498,121 @@ async function cmdDaemon(): Promise<void> {
 
   console.log('👋 Daemon stopped');
 }
+
+// ================================================================
+// update-system — upgrade imtoagent itself
+// ================================================================
+async function cmdUpdateSystem(): Promise<void> {
+  const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+  const currentVer = pkg.version;
+  console.log('\n📦 Upgrading imtoagent...');
+  console.log(`   Current version: ${currentVer}\n`);
+
+  console.log('   Running: npm update -g imtoagent\n');
+
+  try {
+    const child = Bun.spawn(['zsh', '-ic', 'npm update -g imtoagent'], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      stdin: 'ignore',
+      env: { ...process.env },
+    });
+
+    const decoder = new TextDecoder();
+
+    const stdoutReader = child.stdout.getReader();
+    while (true) {
+      const { done, value } = await stdoutReader.read();
+      if (done) break;
+      process.stdout.write(decoder.decode(value, { stream: true }));
+    }
+
+    const stderrReader = child.stderr.getReader();
+    while (true) {
+      const { done, value } = await stderrReader.read();
+      if (done) break;
+      process.stderr.write(decoder.decode(value, { stream: true }));
+    }
+
+    const exitCode = await child.exited;
+    if (exitCode !== 0) {
+      console.error(`\n❌ imtoagent upgrade failed (exit code: ${exitCode})`);
+      process.exit(1);
+    }
+
+    // Read new version
+    let newVer = 'unknown';
+    try {
+      const newPkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+      newVer = newPkg.version;
+    } catch {
+      // Can't read new version (possibly process swapped), check via CLI
+      try {
+        newVer = execSync('imtoagent --version', { encoding: 'utf-8', timeout: 5000 }).trim();
+      } catch {}
+    }
+
+    console.log(`\n✅ imtoagent upgraded: ${currentVer} → ${newVer}`);
+    console.log(`   Restart gateway with: imtoagent stop && imtoagent start`);
+  } catch (e: any) {
+    console.error(`\n❌ Error upgrading imtoagent: ${e.message || e}`);
+    process.exit(1);
+  }
+}
+
+// ================================================================
+// update-backend — upgrade a backend agent
+// ================================================================
+async function cmdUpdateBackend(backendType?: 'claude' | 'codex' | 'opencode'): Promise<void> {
+  const dataDir = getDataDir();
+  const configPath = path.join(dataDir, 'config.json');
+
+  // Determine which backend to upgrade
+  let targetType: 'claude' | 'codex' | 'opencode';
+
+  if (backendType) {
+    if (!['claude', 'codex', 'opencode'].includes(backendType)) {
+      console.error(`❌ Unknown backend: ${backendType}`);
+      console.error(`   Valid: claude, codex, opencode`);
+      process.exit(1);
+    }
+    targetType = backendType;
+  } else {
+    // Auto-detect from config (use first bot's backend)
+    if (!fs.existsSync(configPath)) {
+      console.error('❌ No config found. Run "imtoagent setup" first.');
+      process.exit(1);
+    }
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const bots = cfg.bots || [];
+    if (bots.length === 0) {
+      console.error('❌ No bots configured.');
+      process.exit(1);
+    }
+    targetType = bots[0].backend;
+    if (!targetType) {
+      console.error('❌ First bot has no backend configured.');
+      process.exit(1);
+    }
+    console.log(`   Auto-detected backend: ${targetType} (from bot: ${bots[0].name})\n`);
+  }
+
+  // Show current status
+  const { checkBackend } = await import('../modules/utils/backend-check');
+  const info = checkBackend(targetType);
+  console.log(`   ${info.label}: ${info.version || 'not installed'} (${info.installSource})`);
+
+  if (!info.installed) {
+    console.error(`\n❌ ${info.label} not installed.`);
+    console.error(`   Install: imtoagent setup`);
+    process.exit(1);
+  }
+
+  // Run upgrade
+  const { upgradeBackend } = await import('../modules/utils/backend-check');
+  const result = await upgradeBackend(targetType);
+
+  if (!result.success) {
+    process.exit(1);
+  }
+}

package/index.ts

@@ -19,6 +19,8 @@ import {
 import { parseToBlocks } from './modules/capabilities';
 import { resolveCapabilities } from './modules/prompt-builder';
 import { getDataDir } from './modules/utils/paths';
+import { WorkspaceManager, createWorkspaceManager } from './modules/utils/workspace-manager';
+import { migrateWorkspaces } from './modules/utils/migrate-workspaces';
 import { FeishuIMModule } from './modules/im/feishu';
 import { TelegramAdapter } from './modules/im/telegram';
 import { WeComIMModule } from './modules/im/wecom';
@@ -109,15 +111,17 @@ interface ChatSession extends Session {
 // ================================================================
 class CustomSessionManager {
   sessions: Map<string, ChatSession>;
-  botName: string;
+  botKey: string;
+  sessionsDir: string;
 
-  constructor(botName: string, sessions: Map<string, ChatSession>) {
-    this.botName = botName;
+  constructor(botKey: string, workspacePath: string, sessions: Map<string, ChatSession>) {
+    this.botKey = botKey;
     this.sessions = sessions;
+    this.sessionsDir = path.join(workspacePath, 'sessions');
   }
 
   private _sessionPath(chatId: string): string {
-    return path.join(getSessionsDir(), this.botName, `${chatId}.memory.json`);
+    return path.join(this.sessionsDir, `${chatId}.memory.json`);
   }
 
   async getOrCreate(chatId: string, userId: string): Promise<ChatSession> {
@@ -128,6 +132,10 @@ class CustomSessionManager {
     }
 
     // 从文件加载（兼容旧格式）
+    // 确保 sessions 目录存在
+    if (!fs.existsSync(this.sessionsDir)) {
+      fs.mkdirSync(this.sessionsDir, { recursive: true });
+    }
     const fp = this._sessionPath(chatId);
     let session: ChatSession;
 
@@ -300,6 +308,7 @@ class Bot {
   client: Lark.Client;
   im: IMModule;
   config: any;
+  workspaceManager: WorkspaceManager;
 
   // SDK
   runtime: AgentRuntime;
@@ -310,7 +319,7 @@ class Bot {
   /** 正在执行的任务的取消信号（chatId → AbortController） */
   activeControllers: Map<string, AbortController> = new Map();
 
-  constructor(cfg: BotConfig, globalConfig: any) {
+  constructor(cfg: BotConfig, globalConfig: any, workspaceManager: WorkspaceManager) {
     this.id = cfg.id || cfg.name; // 后向兼容：无 id 时用 name
     this.name = cfg.name;
     this.backend = cfg.backend;
@@ -318,6 +327,11 @@ class Bot {
     this.appSecret = cfg.appSecret;
     this.defaultCwd = cfg.cwd || globalConfig.system?.defaultProjectDir || path.join(os.homedir(), 'Projects');
     this.config = globalConfig;
+    this.workspaceManager = workspaceManager;
+
+    // 确保工作空间目录存在
+    const botKey = this.id;
+    this.workspaceManager.ensureWorkspace(botKey);
 
     // Bot 级模型配置
     const botCfg = this._loadBotConfig();
@@ -352,7 +366,8 @@ class Bot {
     this.im = imFactory.create(cfg);
 
     // ===== SDK 集成 =====
-    this.sessionManager = new CustomSessionManager(this.id, this.sessions);
+    const workspacePath = this.workspaceManager.getWorkspacePath(this.id);
+    this.sessionManager = new CustomSessionManager(this.id, workspacePath, this.sessions);
 
     const adapterCtx = {
       imModule: this.im,
@@ -387,7 +402,9 @@ class Bot {
   }
 
   // ===== 灵魂管理 =====
-  _soulDir() { return getSoulDir(this.id); }
+  _soulDir() {
+    return this.workspaceManager.getSoulPath(this.id);
+  }
 
   _initSoul() {
     const dir = this._soulDir();
@@ -614,9 +631,19 @@ class Bot {
 
     cmd('/dir', ({ args, session }) => {
       const dir = args.trim();
-      if (!dir) return `📁 ${session?.cwd || this.defaultCwd}`;
-      if (session) session.cwd = dir;
-      return `📁 Switched: ${dir}`;
+      const currentCwd = session?.cwd || this.defaultCwd;
+      if (!dir) {
+        const mode = this.workspaceManager.getMode();
+        return `📁 ${currentCwd}\n🏷 Workspace mode: ${mode}`;
+      }
+
+      const resolved = this.workspaceManager.resolveAndValidatePath(this.id, dir, currentCwd);
+      if (resolved === null) {
+        return `❌ Path not allowed: ${dir}\n💡 In sandbox mode, you can only access paths within your workspace`;
+      }
+
+      if (session) session.cwd = resolved;
+      return `📁 Switched: ${resolved}`;
     });
 
     cmd('/mode', ({ args, session }) => {
@@ -950,6 +977,16 @@ async function main() {
     return;
   }
 
+  // ===== Workspace Migration =====
+  // 老用户升级：自动迁移旧 sessions/ + soul/ 到新的 workspace 结构
+  const migrationResult = migrateWorkspaces();
+  if (migrationResult.botsMigrated.length > 0) {
+    console.log(`   🔄 Workspace migration: ${migrationResult.botsMigrated.length} bot(s) migrated`);
+  }
+
+  // 创建 WorkspaceManager（所有 Bot 共享）
+  const workspaceManager = createWorkspaceManager(config);
+
   const bots: Bot[] = [];
   for (const c of botCfgs) {
     const appId = c.appId || c.feishu?.appId || '';
@@ -958,7 +995,7 @@ async function main() {
 
     // wechat 不需要 appId/appSecret，首次启动会触发 QR 扫码绑定
     if (imType === 'wechat') {
-      bots.push(new Bot({ ...c, appId: appId || 'wechat-bot', appSecret }, config));
+      bots.push(new Bot({ ...c, appId: appId || 'wechat-bot', appSecret }, config, workspaceManager));
       continue;
     }
 
@@ -968,7 +1005,7 @@ async function main() {
       console.log(`[Config] ⚠️  Bot "${c.name}" has placeholder credentials, skipping`);
       continue;
     }
-    bots.push(new Bot({ ...c, appId, appSecret }, config));
+    bots.push(new Bot({ ...c, appId, appSecret }, config, workspaceManager));
   }
 
   if (bots.length === 0) {
@@ -976,6 +1013,7 @@ async function main() {
     return;
   }
 
+  console.log(`   Workspace: ${workspaceManager.getConfigSummary()}`);
   _allBots = bots;
   console.log(`\n🚀 CC Routing v4 — Multi-Bot Architecture (Full SDK Integration)`);
   console.log(`   Anthropic: http://localhost:${proxyPort}`);

package/modules/cli/setup.ts

@@ -12,7 +12,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { getDataDir, getPkgDir, getTemplatePath, getSoulDir, getBotKey } from '../utils/paths';
+import { getDataDir, getPkgDir, getTemplatePath, getSoulDir } from '../utils/paths';
 import { randomUUID } from 'crypto';
 import { checkAllBackends, formatBackendStatus } from '../utils/backend-check';
 
@@ -290,7 +290,11 @@ const IM_FIELDS: Record<string, { key: string; label: string; required: boolean
 // Main flow
 // ================================================================
 
-export async function runSetupWizard(): Promise<void> {
+export interface SetupOptions {
+  quick?: boolean;
+}
+
+export async function runSetupWizard(options?: SetupOptions): Promise<void> {
   // Guard: refuse to run in non-TTY environment
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     console.error('');
@@ -311,6 +315,11 @@ export async function runSetupWizard(): Promise<void> {
   console.log(`\nData directory: ${dataDir}`);
   console.log(`Controls: ↑↓/Space navigate  |  Enter confirm  |  ESC go back\n`);
 
+  const isQuick = options?.quick || false;
+  if (isQuick) {
+    console.log('⚡ Quick mode: workspace defaults to sandbox, skip workspace step\n');
+  }
+
   // ===== Step 1: Detect existing configuration =====
   let existingConfig: any = null;
   let mergeMode = false;
@@ -458,15 +467,20 @@ export async function runSetupWizard(): Promise<void> {
       bot.im = imType;
     }
 
-    // Check for duplicate name
-    const existingIdx = bots.findIndex(b => b.name === botName);
-    if (existingIdx >= 0) {
-      bots[existingIdx] = bot;
-      console.log(`✅ Replaced: ${botName}`);
-    } else {
-      bots.push(bot);
-      console.log(`✅ Added: ${botName}`);
+    // Check for duplicate name — auto-rename with counter
+    let finalName = botName;
+    let counter = 1;
+    while (bots.find(b => b.name === finalName)) {
+      finalName = `${botName} (${counter})`;
+      counter++;
     }
+    bot.name = finalName;
+
+    if (finalName !== botName) {
+      console.log(`⚠️  "${botName}" already exists, renamed to "${finalName}"`);
+    }
+    bots.push(bot);
+    console.log(`✅ Added: ${finalName}`);
 
     // Whether to continue adding
     const r = await confirm('Add another Bot?', true);
@@ -482,8 +496,43 @@ export async function runSetupWizard(): Promise<void> {
     return;
   }
 
-  // ===== Step 4: Configure model providers =====
-  console.log('\n📌 Step 4: Configure model providers\n');
+  // ===== Step 4: Configure workspace =====
+  let workspaceMode: 'sandbox' | 'global' = 'sandbox';
+  let workspaceGlobalPath: string | null = null;
+
+  if (!isQuick) {
+    console.log('\n📌 Step 4: Configure workspace\n');
+    console.log('Each Bot gets its own isolated file workspace:');
+    console.log('  sandbox  — isolated per Bot, no cross-Bot file access (recommended)');
+    console.log('  global   — shared root directory, multiple Bots collaborate on same codebase');
+    console.log('');
+
+    const wsLabels = ['Sandbox mode (isolated per Bot)', 'Global mode (shared root path)'];
+    const wsIdx = await selectMenu('Select workspace mode', wsLabels);
+    if (wsIdx === -1) { console.log('\n👋 Cancelled'); process.exit(0); }
+    workspaceMode = wsIdx === 1 ? 'global' : 'sandbox';
+
+    if (workspaceMode === 'global') {
+      const defaultGlobal = os.homedir() + '/imtoagent-workspace';
+      const gpInput = await promptText('Global workspace root path', defaultGlobal);
+      if ((gpInput as any) === -1) { console.log('\n👋 Cancelled'); process.exit(0); }
+      workspaceGlobalPath = (gpInput || defaultGlobal).trim();
+    }
+
+    const home = process.env.HOME || process.env.USERPROFILE?.replace(/\\/g, '/') || '';
+    console.log('');
+    console.log('Workspace layout:');
+    if (workspaceMode === 'sandbox') {
+      console.log(`  ${home}/.imtoagent/workspaces/<UUID>/  (each Bot gets a unique directory)`);
+    } else {
+      console.log(`  ${workspaceGlobalPath}/  (all Bots share this root)`);
+      console.log(`  soul files in ${workspaceGlobalPath}/.imtoagent/soul/<botId>/`);
+    }
+    console.log('');
+  }
+
+  // ===== Step 5: Configure model providers =====
+  console.log('\n📌 Step 5: Configure model providers\n');
 
   const providers: Record<string, any> = {};
   if (mergeMode && existingConfig?.providers) {
@@ -600,8 +649,8 @@ export async function runSetupWizard(): Promise<void> {
   step4Loop = false; // Has providers or user explicitly skipped
 }
 
-  // ===== Step 5: Select default model =====
-  console.log('\n📌 Step 5: Select default model\n');
+  // ===== Step 6: Select default model =====
+  console.log('\n📌 Step 6: Select default model\n');
 
   const allModels: string[] = [];
   for (const [provName, prov] of Object.entries(providers)) {
@@ -620,11 +669,23 @@ export async function runSetupWizard(): Promise<void> {
     if ((defaultModel as any) === -1) defaultModel = 'deepseek/deepseek-v4-pro';
   }
 
-  // ===== Step 6: Generate soul files =====
-  console.log('\n📌 Step 6: Generate soul files\n');
+  // ===== Step 7: Generate soul files =====
+  console.log('\n📌 Step 7: Generate soul files\n');
+
+  // Compute workspace soul dirs based on configured workspace mode
+  const home = process.env.HOME || process.env.USERPROFILE?.replace(/\\/g, '/') || '';
 
   for (const bot of bots) {
-    const botSoulDir = getSoulDir(getBotKey(bot));
+    let botSoulDir: string;
+
+    if (workspaceMode === 'sandbox') {
+      // Sandbox: soul in workspaces/<UUID>/soul/
+      botSoulDir = path.join(home, '.imtoagent', 'workspaces', bot.id, 'soul');
+    } else {
+      // Global: soul in <globalPath>/.imtoagent/soul/<botId>/
+      botSoulDir = path.join(workspaceGlobalPath || path.join(home, 'imtoagent-workspace'), '.imtoagent', 'soul', bot.id);
+    }
+
     const templateSoulDir = path.join(getPkgDir(), 'templates', 'soul.template');
 
     if (fs.existsSync(botSoulDir)) {
@@ -654,9 +715,7 @@ export async function runSetupWizard(): Promise<void> {
     }
     console.log(`✅ ${bot.name}: soul files → ${botSoulDir}`);
   }
-
-  // ===== Step 7: Write configuration files =====
-  console.log('\n📌 Step 7: Write configuration files\n');
+  console.log('\n📌 Step 8: Write configuration files\n');
 
   fs.mkdirSync(dataDir, { recursive: true });
 
@@ -666,6 +725,11 @@ export async function runSetupWizard(): Promise<void> {
       idleTimeoutMinutes: 30,
       maxReplyLength: 140000,
     },
+    workspace: {
+      mode: workspaceMode,
+      globalPath: workspaceGlobalPath,
+      botOverrides: {},
+    },
     providers,
     defaultModel,
     modelAliases: existingConfig?.modelAliases || buildDefaultAliases(defaultModel),
@@ -717,9 +781,10 @@ export async function runSetupWizard(): Promise<void> {
   console.log('\n╔══════════════════════════════════════════════╗');
   console.log('║   ✅ Configuration complete!                 ║');
   console.log('╚══════════════════════════════════════════════╝\n');
-  console.log(`Bot: ${bots.map(b => b.name).join(', ')}`);
+  console.log(`Bots: ${bots.map(b => b.name).join(', ')}`);
   console.log(`Default model: ${defaultModel}`);
   console.log(`Providers: ${Object.keys(providers).join(', ') || 'None'}`);
+  console.log(`Workspace: ${workspaceMode === 'sandbox' ? 'sandbox (isolated)' : `global (${workspaceGlobalPath})`}`);
   console.log(`\nNext steps:`);
   console.log(`  imtoagent start    Start the gateway`);
   console.log(`  imtoagent status   Check status\n`);

package/modules/utils/backend-check.ts

@@ -7,20 +7,70 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 
+export type InstallSource = 'npm' | 'brew' | 'manual' | 'unknown';
+
 export interface BackendInfo {
   type: 'claude' | 'codex' | 'opencode';
   label: string;
   installed: boolean;
   version: string | null;
   installHint: string;
+  installSource: InstallSource;
+  binaryPath: string | null;
+  upgradeCommand: string | null;
 }
 
-const BACKEND_DEFS: Omit<BackendInfo, 'installed' | 'version'>[] = [
+const BACKEND_DEFS: Omit<BackendInfo, 'installed' | 'version' | 'installSource' | 'binaryPath' | 'upgradeCommand'>[] = [
   { type: 'claude', label: 'Claude Code', installHint: 'npm install -g @anthropic-ai/claude-agent-sdk' },
   { type: 'codex',  label: 'Codex',       installHint: 'npm install -g @openai/codex' },
   { type: 'opencode', label: 'OpenCode',   installHint: 'curl -fsSL https://opencode.ai/install | bash' },
 ];
 
+// ================================================================
+// 安装来源检测
+// ================================================================
+
+/**
+ * 根据二进制路径判断安装来源
+ */
+export function detectInstallSource(binaryPath: string, type: string): InstallSource {
+  if (binaryPath.includes('/opt/homebrew/') || binaryPath.includes('/usr/local/Cellar/')) {
+    return 'brew';
+  }
+  if (binaryPath.includes('node_modules/')) {
+    return 'npm';
+  }
+  if (type === 'opencode' && binaryPath.includes('.opencode/')) {
+    return 'manual';
+  }
+  return 'unknown';
+}
+
+/**
+ * 根据安装来源和后端类型生成升级命令
+ */
+export function getUpgradeCommand(source: InstallSource, type: string): string | null {
+  switch (source) {
+    case 'brew':
+      const brewPkg: Record<string, string> = { claude: undefined, codex: 'codex', opencode: undefined };
+      if (brewPkg[type]) return `brew upgrade ${brewPkg[type]}`;
+      return null; // claude/opencode not on brew
+    case 'npm':
+      const npmPkg: Record<string, string> = {
+        claude: '@anthropic-ai/claude-agent-sdk',
+        codex: '@openai/codex',
+        opencode: 'opencode',
+      };
+      if (npmPkg[type]) return `npm update -g ${npmPkg[type]}`;
+      return null;
+    case 'manual':
+      if (type === 'opencode') return 'curl -fsSL https://opencode.ai/install | bash';
+      return null;
+    case 'unknown':
+      return null;
+  }
+}
+
 // ================================================================
 // 获取 npm 全局 bin 目录
 // 解决 PATH 未包含 npm global bin 时的检测失败问题
@@ -49,47 +99,75 @@ export function getNpmGlobalBin(): string | null {
   }
 }
 
-function checkOne(b: Omit<BackendInfo, 'installed' | 'version'>): BackendInfo {
+/**
+ * 定位后端可执行文件（按优先级）
+ * 返回 { path, version } 或 null
+ */
+function findBackendBinary(type: string): { binaryPath: string; version: string } | null {
   const versionCmd: Record<string, string> = {
     claude: 'claude --version',
     codex: 'codex --version',
     opencode: 'opencode version',
   };
 
-  // 先尝试 PATH 中的命令
+  // 1) PATH 中的命令（最常见）
   try {
-    const version = execSync(versionCmd[b.type], { encoding: 'utf-8', timeout: 5000 }).trim();
-    return { ...b, installed: true, version };
-  } catch {
-    // PATH 中找不到，继续尝试 fallback
-  }
+    const version = execSync(versionCmd[type], { encoding: 'utf-8', timeout: 5000 }).trim();
+    // 解析真实路径（处理 symlink）
+    const binName = type;
+    const realPath = execSync(`command -v ${binName}`, { encoding: 'utf-8', timeout: 3000 }).trim();
+    return { binaryPath: realPath, version };
+  } catch {}
 
-  // fallback 1: npm global bin
+  // 2) npm global bin
   const npmBin = getNpmGlobalBin();
   if (npmBin) {
-    const binPath = path.join(npmBin, b.type);
+    const binPath = path.join(npmBin, type);
     try {
       if (fs.existsSync(binPath)) {
         const version = execSync(`"${binPath}" --version`, { encoding: 'utf-8', timeout: 5000 }).trim();
-        return { ...b, installed: true, version };
+        return { binaryPath: binPath, version };
       }
-    } catch {
-      // bin 存在但执行失败，视为未安装
-    }
+    } catch {}
   }
 
-  // fallback 2: OpenCode custom install path
-  if (b.type === 'opencode') {
+  // 3) OpenCode custom install path
+  if (type === 'opencode') {
     const opencodePath = path.join(os.homedir(), '.opencode', 'bin', 'opencode');
     try {
       if (fs.existsSync(opencodePath)) {
         const version = execSync(`"${opencodePath}" version`, { encoding: 'utf-8', timeout: 5000 }).trim();
-        return { ...b, installed: true, version };
+        return { binaryPath: opencodePath, version };
       }
     } catch {}
   }
 
-  return { ...b, installed: false, version: null };
+  return null;
+}
+
+function checkOne(b: Omit<BackendInfo, 'installed' | 'version' | 'installSource' | 'binaryPath' | 'upgradeCommand'>): BackendInfo {
+  const found = findBackendBinary(b.type);
+  if (found) {
+    const installSource = detectInstallSource(found.binaryPath, b.type);
+    const upgradeCommand = getUpgradeCommand(installSource, b.type);
+    return {
+      ...b,
+      installed: true,
+      version: found.version,
+      installSource,
+      binaryPath: found.binaryPath,
+      upgradeCommand,
+    };
+  }
+
+  return {
+    ...b,
+    installed: false,
+    version: null,
+    installSource: 'unknown',
+    binaryPath: null,
+    upgradeCommand: null,
+  };
 }
 
 export function checkAllBackends(): BackendInfo[] {
@@ -106,8 +184,9 @@ export function formatBackendStatus(backends: BackendInfo[]): string {
   return backends.map(b => {
     const icon = b.installed ? '✅' : '❌';
     const ver = b.version ? ` v${b.version}` : '';
+    const source = b.installed && b.installSource !== 'unknown' ? ` (${b.installSource})` : '';
     const hint = b.installed ? '' : ` → ${b.installHint}`;
-    return `  ${icon} ${b.label}${ver}${hint}`;
+    return `  ${icon} ${b.label}${ver}${source}${hint}`;
   }).join('\n');
 }
 
@@ -143,6 +222,90 @@ function ensurePathInConfig(configPath: string, binDir: string): void {
   } catch {}
 }
 
+// ================================================================
+// 升级后端 CLI
+// ================================================================
+
+/**
+ * 升级已安装的后端到最新版
+ * 根据检测到的 installSource 自动选择正确的升级命令
+ */
+export async function upgradeBackend(
+  type: 'claude' | 'codex' | 'opencode',
+): Promise<{ success: boolean; oldVer: string; newVer: string }> {
+  const b = BACKEND_DEFS.find((x) => x.type === type);
+  if (!b) {
+    return { success: false, oldVer: '', newVer: '' };
+  }
+
+  const currentInfo = checkOne(b);
+  if (!currentInfo.installed) {
+    console.error(`❌ ${b.label} not installed. Use installBackend() instead.`);
+    return { success: false, oldVer: '', newVer: '' };
+  }
+
+  const upgradeCmd = currentInfo.upgradeCommand;
+  if (!upgradeCmd) {
+    console.error(`❌ Cannot determine upgrade method for ${b.label} (source: ${currentInfo.installSource})`);
+    console.error(`   Please upgrade manually.`);
+    return { success: false, oldVer: currentInfo.version || '', newVer: '' };
+  }
+
+  const oldVer = currentInfo.version || '';
+  console.log(`\n📦 Upgrading ${b.label}...`);
+  console.log(`   Current: ${oldVer}`);
+  console.log(`   Source: ${currentInfo.installSource}`);
+  console.log(`   Command: ${upgradeCmd}\n`);
+
+  try {
+    const child = Bun.spawn(['zsh', '-ic', upgradeCmd], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      stdin: 'ignore',
+      env: { ...process.env },
+    });
+
+    const decoder = new TextDecoder();
+
+    const stdoutReader = child.stdout.getReader();
+    while (true) {
+      const { done, value } = await stdoutReader.read();
+      if (done) break;
+      process.stdout.write(decoder.decode(value, { stream: true }));
+    }
+
+    const stderrReader = child.stderr.getReader();
+    while (true) {
+      const { done, value } = await stderrReader.read();
+      if (done) break;
+      process.stderr.write(decoder.decode(value, { stream: true }));
+    }
+
+    const exitCode = await child.exited;
+    if (exitCode !== 0) {
+      console.error(`\n❌ ${b.label} upgrade failed (exit code: ${exitCode})`);
+      return { success: false, oldVer, newVer: '' };
+    }
+
+    // 验证新版本
+    const newInfo = checkOne(b);
+    const newVer = newInfo.version || '';
+    if (newInfo.installed && newVer !== oldVer) {
+      console.log(`\n✅ ${b.label} upgraded: ${oldVer} → ${newVer}`);
+      return { success: true, oldVer, newVer };
+    } else if (newVer === oldVer) {
+      console.log(`\n✅ ${b.label} is already at latest version (${newVer})`);
+      return { success: true, oldVer, newVer };
+    } else {
+      console.log(`\n✅ ${b.label} upgrade completed (new version: ${newVer})`);
+      return { success: true, oldVer, newVer };
+    }
+  } catch (e: any) {
+    console.error(`\n❌ Error upgrading ${b.label}: ${e.message || e}`);
+    return { success: false, oldVer, newVer: '' };
+  }
+}
+
 // ================================================================
 // 自动安装后端 CLI
 // ================================================================

package/modules/utils/migrate-workspaces.ts

@@ -0,0 +1,230 @@
+// ================================================================
+// Workspace Migration — 老用户平滑迁移
+// ================================================================
+// 职责：
+//   1. 检测旧目录结构（sessions/ + soul/）
+//   2. 迁移到新 workspace 结构
+//   3. 保留旧目录作为 .backup（不删除，安全优先）
+//   4. 标记迁移完成，避免重复执行
+// ================================================================
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { getDataDir } from './paths';
+
+const MIGRATION_MARKER = '.workspace-migrated';
+
+interface MigrationResult {
+  migrated: boolean;
+  botsMigrated: string[];
+  errors: string[];
+}
+
+// ================================================================
+// 公共入口
+// ================================================================
+
+/**
+ * 检测并执行 workspace 迁移。
+ *
+ * 启动时调用一次。如果已经迁移过，直接返回。
+ * 返回迁移结果摘要，可用于日志输出。
+ */
+export function migrateWorkspaces(): MigrationResult {
+  const dataDir = getDataDir();
+  const markerPath = path.join(dataDir, MIGRATION_MARKER);
+
+  // 已经迁移过，跳过
+  if (fs.existsSync(markerPath)) {
+    return { migrated: false, botsMigrated: [], errors: [] };
+  }
+
+  const result: MigrationResult = { migrated: true, botsMigrated: [], errors: [] };
+
+  // 加载 bot-ids.json（UUID 映射）
+  const botIds = loadBotIds(dataDir);
+
+  // 旧目录
+  const oldSessionsDir = path.join(dataDir, 'sessions');
+  const oldSoulDir = path.join(dataDir, 'soul');
+
+  // 发现需要迁移的 Bot（从旧 sessions 目录扫描）
+  const botKeys = discoverBotKeys(oldSessionsDir, oldSoulDir);
+  if (botKeys.length === 0) {
+    // 没有旧数据，直接标记
+    markMigrated(markerPath);
+    return result;
+  }
+
+  console.error(`[Migration] Found ${botKeys.length} bot(s) to migrate: ${botKeys.join(', ')}`);
+
+  for (const botKey of botKeys) {
+    try {
+      const botUuid = ensureBotUuid(botKey, botIds, dataDir);
+      migrateBotData(botKey, botUuid, dataDir, oldSessionsDir, oldSoulDir);
+      result.botsMigrated.push(botKey);
+    } catch (e: any) {
+      const msg = `[${botKey}] ${e.message}`;
+      result.errors.push(msg);
+      console.error(`[Migration] ERROR: ${msg}`);
+    }
+  }
+
+  // 迁移完成后创建标记
+  markMigrated(markerPath);
+
+  // 打印摘要
+  if (result.botsMigrated.length > 0) {
+    console.error(`[Migration] ✅ ${result.botsMigrated.length} bot(s) migrated successfully`);
+  }
+  if (result.errors.length > 0) {
+    console.error(`[Migration] ⚠️ ${result.errors.length} error(s): ${result.errors.join('; ')}`);
+  }
+
+  return result;
+}
+
+// ================================================================
+// 内部函数
+// ================================================================
+
+/** 加载 bot-ids.json */
+function loadBotIds(dataDir: string): Record<string, string> {
+  const botIdsFile = path.join(dataDir, 'bot-ids.json');
+  try {
+    if (fs.existsSync(botIdsFile)) {
+      return JSON.parse(fs.readFileSync(botIdsFile, 'utf8'));
+    }
+  } catch {
+    // 文件损坏，重新开始
+  }
+  return {};
+}
+
+/** 确保 Bot 有 UUID */
+function ensureBotUuid(
+  botKey: string,
+  botIds: Record<string, string>,
+  dataDir: string,
+): string {
+  if (botIds[botKey]) return botIds[botKey];
+
+  const uuid = crypto.randomUUID();
+  botIds[botKey] = uuid;
+
+  try {
+    fs.writeFileSync(path.join(dataDir, 'bot-ids.json'), JSON.stringify(botIds, null, 2));
+  } catch {
+    // 写入失败不影响迁移流程
+  }
+
+  return uuid;
+}
+
+/** 发现需要迁移的 Bot keys */
+function discoverBotKeys(sessionsDir: string, soulDir: string): string[] {
+  const botKeys = new Set<string>();
+
+  // 从 sessions 目录扫描
+  if (fs.existsSync(sessionsDir)) {
+    try {
+      for (const entry of fs.readdirSync(sessionsDir)) {
+        if (entry.startsWith('.')) continue; // 跳过 .restore 等隐藏文件
+        const entryPath = path.join(sessionsDir, entry);
+        if (fs.statSync(entryPath).isDirectory()) {
+          botKeys.add(entry);
+        }
+      }
+    } catch {
+      // 忽略读取失败
+    }
+  }
+
+  // 从 soul 目录扫描（补充）
+  if (fs.existsSync(soulDir)) {
+    try {
+      for (const entry of fs.readdirSync(soulDir)) {
+        if (entry.startsWith('.')) continue;
+        const entryPath = path.join(soulDir, entry);
+        if (fs.statSync(entryPath).isDirectory()) {
+          botKeys.add(entry);
+        }
+      }
+    } catch {
+      // 忽略读取失败
+    }
+  }
+
+  return Array.from(botKeys);
+}
+
+/** 迁移单个 Bot 的数据 */
+function migrateBotData(
+  botKey: string,
+  botUuid: string,
+  dataDir: string,
+  oldSessionsDir: string,
+  oldSoulDir: string,
+): void {
+  const workspacesDir = path.join(dataDir, 'workspaces');
+  const newWorkspacePath = path.join(workspacesDir, botUuid);
+  const newSessionsPath = path.join(newWorkspacePath, 'sessions');
+  const newSoulPath = path.join(newWorkspacePath, 'soul');
+
+  console.error(`[Migration] Migrating [${botKey}] → workspace/${botUuid}/`);
+
+  // 确保新目录存在
+  fs.mkdirSync(newSessionsPath, { recursive: true });
+  fs.mkdirSync(newSoulPath, { recursive: true });
+
+  // 1. 迁移 session 文件
+  const oldBotSessionsDir = path.join(oldSessionsDir, botKey);
+  if (fs.existsSync(oldBotSessionsDir)) {
+    const sessionFiles = fs.readdirSync(oldBotSessionsDir).filter((f) => f.endsWith('.memory.json'));
+    for (const file of sessionFiles) {
+      const src = path.join(oldBotSessionsDir, file);
+      const dst = path.join(newSessionsPath, file);
+      if (!fs.existsSync(dst)) {
+        fs.copyFileSync(src, dst);
+        console.error(`[Migration]   session: ${file}`);
+      }
+    }
+  }
+
+  // 2. 迁移 soul 文件
+  const oldBotSoulDir = path.join(oldSoulDir, botKey);
+  if (fs.existsSync(oldBotSoulDir)) {
+    const soulFiles = fs.readdirSync(oldBotSoulDir);
+    for (const file of soulFiles) {
+      const src = path.join(oldBotSoulDir, file);
+      const dst = path.join(newSoulPath, file);
+      if (!fs.existsSync(dst) && fs.statSync(src).isFile()) {
+        fs.copyFileSync(src, dst);
+        console.error(`[Migration]   soul: ${file}`);
+      }
+    }
+  }
+
+  // 3. 迁移 .restore 文件到数据目录根（全局 marker）
+  const oldRestore = path.join(oldSessionsDir, '.restore');
+  if (fs.existsSync(oldRestore)) {
+    const newRestore = path.join(dataDir, '.restore');
+    if (!fs.existsSync(newRestore)) {
+      fs.copyFileSync(oldRestore, newRestore);
+    }
+  }
+}
+
+/** 标记迁移已完成 */
+function markMigrated(markerPath: string): void {
+  const marker = {
+    version: 1,
+    migratedAt: new Date().toISOString(),
+    note: 'Workspace migration completed. Old sessions/ and soul/ directories preserved as backup.',
+  };
+  try {
+    fs.writeFileSync(markerPath, JSON.stringify(marker, null, 2));
+  } catch {
+    console.error('[Migration] Failed to write migration marker');
+  }
+}

package/modules/utils/paths.ts

@@ -201,7 +201,7 @@ export function getSoulDir(botKey: string): string {
 }
 
 export function getRestoreMarkerPath(): string {
-  return path.join(getSessionsDir(), '.restore');
+  return path.join(getDataDir(), '.restore');
 }
 
 export function getTemplatePath(relativePath: string): string {

package/modules/utils/workspace-manager.ts

@@ -0,0 +1,209 @@
+// ================================================================
+// WorkspaceManager — 工作空间管理
+// ================================================================
+// 职责：
+//   1. 根据模式（sandbox/global）解析每个 Bot 的工作空间路径
+//   2. 确保工作空间目录存在（含 soul/ 子目录）
+//   3. 路径边界检查（沙盒模式下防止路径穿越）
+// ================================================================
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { getDataDir } from './paths';
+
+// ================================================================
+// 类型定义
+// ================================================================
+
+export type WorkspaceMode = 'sandbox' | 'global';
+
+export interface WorkspaceConfig {
+  mode: WorkspaceMode;
+  globalPath: string | null;
+  botOverrides: Record<string, string>;
+}
+
+/**
+ * 从 config.json 中提取 workspace 配置。
+ * 老用户无 workspace 配置时，默认 sandbox 模式。
+ */
+export function parseWorkspaceConfig(raw: any): WorkspaceConfig {
+  const ws = raw?.workspace || {};
+  const mode: WorkspaceMode = ws.mode === 'global' ? 'global' : 'sandbox';
+  const globalPath: string | null = ws.globalPath || null;
+  const botOverrides: Record<string, string> = {};
+
+  if (ws.botOverrides && typeof ws.botOverrides === 'object') {
+    for (const [k, v] of Object.entries(ws.botOverrides)) {
+      if (typeof v === 'string') botOverrides[k] = v;
+    }
+  }
+
+  return { mode, globalPath, botOverrides };
+}
+
+// ================================================================
+// WorkspaceManager
+// ================================================================
+
+export class WorkspaceManager {
+  private config: WorkspaceConfig;
+  private workspacesDir: string;
+
+  constructor(config: WorkspaceConfig) {
+    this.config = config;
+    this.workspacesDir = path.join(getDataDir(), 'workspaces');
+  }
+
+  /**
+   * 解析 Bot 的工作空间路径。
+   *
+   * 规则：
+   *   - 沙盒模式：~/.imtoagent/workspaces/<UUID>/（UUID 保证唯一，可被 botOverrides 覆盖）
+   *   - 全局模式：直接使用 <globalPath>/（所有 Bot 共享同一入口）
+   */
+  getWorkspacePath(botKey: string): string {
+    // 优先级：botOverrides > 模式默认路径
+    const override = this.config.botOverrides[botKey];
+    if (override) return path.resolve(override);
+
+    // 全局模式：所有 Bot 共享 globalPath，不加 botKey
+    if (this.config.mode === 'global' && this.config.globalPath) {
+      return path.resolve(this.config.globalPath);
+    }
+
+    // 沙盒模式：每个 Bot 独立目录（UUID 保证唯一性，无需日期后缀）
+    const botId = this._getBotId(botKey);
+    return path.resolve(this.workspacesDir, botId);
+  }
+
+  /**
+   * 生成或获取 Bot 的 UUID。
+   * 首次调用时创建 UUID 并持久化到数据目录。
+   */
+  private _getBotId(botKey: string): string {
+    const botIdsFile = path.join(getDataDir(), 'bot-ids.json');
+    let botIds: Record<string, string> = {};
+
+    try {
+      if (fs.existsSync(botIdsFile)) {
+        botIds = JSON.parse(fs.readFileSync(botIdsFile, 'utf8'));
+      }
+    } catch {
+      // 文件损坏或不可读，重新开始
+    }
+
+    if (!botIds[botKey]) {
+      // 生成 UUID v4
+      botIds[botKey] = crypto.randomUUID();
+      try {
+        fs.writeFileSync(botIdsFile, JSON.stringify(botIds, null, 2));
+      } catch (e) {
+        console.error(`[Workspace] Failed to persist bot ID for ${botKey}: ${e}`);
+      }
+    }
+
+    return botIds[botKey];
+  }
+
+  /**
+   * 确保工作空间目录存在，并初始化 soul/ 子目录。
+   *
+   * 沙盒模式：创建 <workspace>/soul/
+   * 全局模式：创建 <globalPath>/.imtoagent/soul/<botId>/（按 Bot 隔离）
+   */
+  ensureWorkspace(botKey: string): void {
+    const wsPath = this.getWorkspacePath(botKey);
+    const soulPath = this.getSoulPath(botKey);
+
+    try {
+      if (!fs.existsSync(wsPath)) {
+        fs.mkdirSync(wsPath, { recursive: true });
+      }
+      if (!fs.existsSync(soulPath)) {
+        fs.mkdirSync(soulPath, { recursive: true });
+      }
+    } catch (e: any) {
+      console.error(`[Workspace] Failed to ensure workspace for ${botKey}: ${e.message}`);
+      throw e;
+    }
+  }
+
+  /**
+   * 获取 soul 目录路径。
+   * 沙盒模式：<workspacePath>/soul/
+   * 全局模式：<globalPath>/.imtoagent/soul/<botId>/
+   */
+  getSoulPath(botKey: string): string {
+    if (this.config.mode === 'global' && this.config.globalPath) {
+      return path.resolve(this.config.globalPath, '.imtoagent', 'soul', botKey);
+    }
+    // 沙盒模式
+    return path.join(this.getWorkspacePath(botKey), 'soul');
+  }
+
+  /**
+   * 检查路径是否允许该 Bot 访问。
+   *
+   * 沙盒模式：路径必须在 Bot 的工作空间范围内（或子目录）。
+   * 全局模式：不做限制，允许访问任意路径（信任用户配置的全局目录）。
+   *
+   * 返回 true 表示允许，false 表示拒绝。
+   */
+  isPathAllowed(botKey: string, targetPath: string): boolean {
+    // 全局模式：不做边界限制
+    if (this.config.mode === 'global') {
+      return true;
+    }
+
+    // 沙盒模式：路径必须在工作空间内
+    const resolved = path.resolve(targetPath);
+    const wsPath = this.getWorkspacePath(botKey);
+    const resolvedWs = path.resolve(wsPath);
+
+    if (resolved === resolvedWs || resolved.startsWith(resolvedWs + path.sep)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * 获取工作空间模式。
+   */
+  getMode(): WorkspaceMode {
+    return this.config.mode;
+  }
+
+  /**
+   * 规范化路径（解析 '..'、'.' 等），用于 /dir 命令。
+   * 如果规范化后的路径超出边界，返回 null。
+   */
+  resolveAndValidatePath(botKey: string, inputPath: string, currentCwd: string): string | null {
+    // 先相对于当前 cwd 解析
+    const resolved = path.resolve(currentCwd, inputPath);
+    if (this.isPathAllowed(botKey, resolved)) {
+      return resolved;
+    }
+    return null;
+  }
+
+  /**
+   * 获取工作空间配置摘要（用于状态展示）。
+   */
+  getConfigSummary(): string {
+    if (this.config.mode === 'sandbox') {
+      return `sandbox (default: ${this.workspacesDir}/<UUID>/)`;
+    }
+    return `global (${path.resolve(this.config.globalPath || '.')})`;
+  }
+}
+
+// ================================================================
+// 便捷函数：从原始配置创建 WorkspaceManager
+// ================================================================
+
+export function createWorkspaceManager(rawConfig: any): WorkspaceManager {
+  const config = parseWorkspaceConfig(rawConfig);
+  return new WorkspaceManager(config);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imtoagent",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "IM ↔ Agent 统一网关 — 飞书/Telegram/微信/企业微信对接 Claude Code/Codex/OpenCode",
   "type": "module",
   "bin": {