imtoagent 0.3.22 → 0.3.23

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();
@@ -98,6 +98,7 @@ imtoagent — IM ↔ Agent Unified Gateway
 
 Usage:
   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
@@ -115,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);
 }
 
 // ================================================================

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/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.22",
+  "version": "0.3.23",
   "description": "IM ↔ Agent 统一网关 — 飞书/Telegram/微信/企业微信对接 Claude Code/Codex/OpenCode",
   "type": "module",
   "bin": {