imtoagent 0.3.5 → 0.3.7

package/README.md

@@ -4,12 +4,50 @@ Connect Feishu, Telegram, personal WeChat, and WeCom to AI coding agents like Cl
 
 One gateway, multiple IMs, multiple agents, unified port proxy.
 
+## 🚀 Quick Start (5 Minutes)
+
+### Step 1: Install (One Command)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/imtoagent/imtoagent/main/install.sh | bash
+```
+
+This script detects your environment, installs bun if needed, installs imtoagent, and guides you through setup.
+
+### Step 2: Start
+
+```bash
+imtoagent setup
+```
+
+The interactive wizard guides you through:
+1. Select IM platform (Feishu/Telegram/WeChat/WeCom)
+2. Enter Bot credentials
+3. Choose Agent backend (Claude Code/Codex/OpenCode)
+4. Configure model providers (API keys)
+5. Generate soul files for personality injection
+
+### Step 2: Verify
+
+```bash
+imtoagent status    # check it's running
+```
+
+That's it! Send `/help` to your Bot in the IM to see available commands.
+
+---
+
+**Alternative install methods:** See [Installation Methods](#installation-methods) below for npm global install or source install.
+
+---
+
 ## Architecture
 
 ```
-飞书/Telegram/微信/企微 → IM Registry 工厂 → Bot 实例
-                                          → AgentRuntime SDK → Agent Adapter
-                                                             → 统一 Proxy (:18899) → 上游模型
+IM Platform (Feishu/Telegram/WeChat/WeCom)
+    → IM Registry Factory → Bot Instance
+        → AgentRuntime SDK → Agent Adapter
+            → Unified Proxy (:18899) → Upstream Models
 ```
 
 ### Supported IM Adapters
@@ -43,63 +81,115 @@ One gateway, multiple IMs, multiple agents, unified port proxy.
 | Codex | `npm install -g @openai/codex` |
 | OpenCode | `npm install -g opencode` |
 
-### Installation
+## Installation Methods
 
-#### Method 1: npm global install (recommended)
+### Method 1: One-Click Install (Recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/imtoagent/imtoagent/main/install.sh | bash
+```
+
+This script does everything automatically:
+- Detects your OS and environment
+- Installs bun if missing
+- Installs or upgrades imtoagent
+- Runs the setup wizard if no configuration exists
+- Starts the gateway and verifies it's running
+
+**Flags:**
+- `--non-interactive` — Skip all prompts, auto-install and auto-start
+- `--skip-bun` — Skip bun installation check
+- `--skip-start` — Don't start the gateway after install
+
+### Method 2: npm Global Install
 
 ```bash
 npm install -g imtoagent
 ```
 
-After installation, it automatically checks whether initial configuration is needed. An interactive terminal will guide you through the setup wizard.
+This is the simplest approach. After installation, the post-install script checks if you need initial configuration.
 
-#### Method 2: Source install
+### Method 3: Source Install
 
 ```bash
-git clone https://github.com/YOUR_USERNAME/imtoagent.git
+git clone https://github.com/imtoagent/imtoagent.git
 cd imtoagent
 bun install
 bun run bin/imtoagent setup
 ```
 
-### First-Time Configuration
+Use this for development or if you want to modify the source code.
+
+### Prerequisites
+
+- **Bun** runtime (≥1.0.0): `brew install oven-sh/bun/bun`
+- **macOS or Linux**
+- **At least one Agent backend** installed (see below)
+
+### Agent Backend Installation
+
+| Backend | Install Command |
+|---------|----------------|
+| Claude Code | `npm install -g @anthropic-ai/claude-agent-sdk` |
+| Codex | `npm install -g @openai/codex` |
+| OpenCode | `npm install -g opencode` |
+
+You can install backends before or after installing imtoagent.
+
+## Configuration
+
+### First-Time Setup
 
 ```bash
 imtoagent setup
 ```
 
-The interactive setup wizard guides you through:
+The interactive wizard will guide you through:
 
-1. **Configure Bot** — Select IM platform + Agent backend
+1. **Configure Bot** — Select IM platform + Agent backend combination
 2. **Configure Model Providers** — Add API credentials (DeepSeek, Dashscope, etc.)
-3. **Generate Soul Files** — Create rules.md / identity.md etc. for each Bot
+3. **Generate Soul Files** — Create personality files (rules.md, identity.md, etc.)
 4. **Write Config Files** — Auto-generate `~/.imtoagent/config.json`
 
-#### Feishu Bot Requirements
+### Platform-Specific Requirements
 
-- Feishu App ID (`cli_...`)
-- Feishu App Secret
-- Feishu app must enable: Bot, Event Subscription, Message Send/Receive permissions
+#### Feishu
+- **App ID** (`cli_...`) and **App Secret**
+- Enable in Feishu app console: Bot, Event Subscription, Message Send/Receive permissions
 
-#### Telegram Bot Requirements
-
-- Telegram Bot Token (obtain from @BotFather)
-- Optional: Proxy address (e.g., `http://127.0.0.1:7890`)
+#### Telegram
+- **Bot Token** from @BotFather
+- Optional: HTTP proxy (e.g., `http://127.0.0.1:7890`)
 
 #### Personal WeChat
+- QR code automatically appears on first `imtoagent start`
+- Scan with WeChat on your phone to complete binding
 
-- QR code automatically pops up on first run of `imtoagent start`
-- Scan with your phone's WeChat to complete binding
+#### WeCom (Enterprise WeChat)
+- Webhook callback URL configuration
+- REST API credentials
 
-### Start the Gateway
+## Running the Gateway
 
-```bash
-imtoagent start     # Start in background
-imtoagent status    # Check running status
-imtoagent stop      # Stop the gateway
-```
+### Basic Commands
+
+| Command | Description |
+|---------|-------------|
+| `imtoagent start` | Start gateway in background |
+| `imtoagent stop` | Stop the gateway |
+| `imtoagent status` | Check running status |
+| `imtoagent restore` | Hot reload recovery |
+| `imtoagent daemon` | Foreground daemon mode (crash auto-restart) |
+
+### Running Modes
 
-### Auto-Start on Boot (macOS launchd)
+- **`start`** — Background mode, terminal returns immediately
+- **`run`** — Foreground mode, real-time logs, Ctrl+C to stop
+- **`daemon`** — Foreground with auto-restart on crash
+
+### Auto-Start on Boot
+
+#### macOS (launchd)
 
 ```bash
 # Create launchd configuration
@@ -134,36 +224,54 @@ cat > ~/Library/LaunchAgents/com.imtoagent.plist << 'EOF'
 </plist>
 EOF
 
-# Load
+# Load the service
 launchctl load ~/Library/LaunchAgents/com.imtoagent.plist
 ```
 
-### Common Commands
+#### Linux (systemd)
 
-| Command | Description |
-|------|------|
-| `imtoagent setup` | Interactive setup wizard |
-| `imtoagent start` | Start gateway in background |
-| `imtoagent stop` | Stop the gateway |
-| `imtoagent status` | Check running status |
-| `imtoagent restore` | Hot reload recovery |
-| `imtoagent daemon` | Foreground daemon mode (suitable for launchd/systemd) |
+Create `/etc/systemd/system/imtoagent.service`:
 
-### Built-In Gateway Commands
+```ini
+[Unit]
+Description=IMtoAgent Gateway
+After=network.target
 
-Send to the Bot in IM chat:
+[Service]
+Type=simple
+User=youruser
+WorkingDirectory=/home/youruser/.imtoagent
+ExecStart=/usr/bin/bun run /usr/lib/node_modules/imtoagent/index.ts daemon
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+systemctl daemon-reload
+systemctl enable imtoagent
+systemctl start imtoagent
+```
+
+## Using the Gateway
+
+### Built-In Commands
+
+Send these to your Bot in the IM chat:
 
 | Command | Description |
-|------|------|
-| `/help` | Help information |
+|---------|-------------|
+| `/help` | Show available commands |
 | `/status` | Gateway status |
 | `/stats` | Usage statistics |
-| `/model` | Switch model |
-| `/providers` | View providers |
-| `/memory` | View memory |
+| `/model` | Switch AI model |
+| `/providers` | View model providers |
+| `/memory` | View memory status |
 | `/soul` | Soul management |
-| `/reload` | Reload |
-| `/clear` | Clear session |
+| `/reload` | Reload configuration |
+| `/clear` | Clear conversation session |
 | `/mode` | Switch mode (permission/auto/plan) |
 | `/dir` | Switch working directory |
 
@@ -206,27 +314,66 @@ imtoagent/
 
 ## Data Directory
 
-All runtime data is stored centrally in `~/.imtoagent/`:
+All runtime data is stored in `~/.imtoagent/`:
 
 ```
 ~/.imtoagent/
 ├── config.json          # Main config (Bot + providers + system)
-├── providers.json       # Model provider config
-├── opencode.json        # OpenCode config
-├── sessions/            # Session persistence
+├── providers.json       # Model provider configurations
+├── opencode.json        # OpenCode-specific config
+├── sessions/            # Conversation persistence
 ├── logs/                # Runtime logs
-└── soul/                # Soul files (one directory per Bot)
+└── soul/                # Bot personality files
     ├── ClaudeBot/
     ├── CodexBot/
-    └── ...
+    └── ...              # One directory per Bot
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Gateway won't start**
+- Check `imtoagent status` for details
+- Verify config with `cat ~/.imtoagent/config.json`
+- Check logs: `cat ~/.imtoagent/logs/*.log`
+
+**Setup wizard stuck**
+- Ensure terminal supports interactive input
+- Try running in a standard terminal (not IDE integrated)
+
+**Bot not responding in IM**
+- Verify credentials in config.json
+- Check IM platform permissions (Feishu events, Telegram webhook, etc.)
+- Ensure the gateway is running: `imtoagent status`
+
+**Port 18899 already in use**
+- Another service is using the proxy port
+- Kill the existing process or change port in config
+
+### Getting Help
+
+- Check logs: `~/.imtoagent/logs/`
+- Run `imtoagent status` for runtime information
+- Open an issue on GitHub with logs attached
 ```
 
 ## Development
 
 ```bash
+# Clone and setup development environment
+git clone https://github.com/imtoagent/imtoagent.git
+cd imtoagent
 bun install
-bun run index.ts          # Run directly
-bun run bin/imtoagent setup  # Run setup wizard
+
+# Run directly
+bun run index.ts
+
+# Run setup wizard
+bun run bin/imtoagent setup
+
+# Run CLI from source
+bun run bin/imtoagent status
 ```
 
 ## License

package/bin/imtoagent-real

@@ -5,14 +5,16 @@
 // Available after npm install -g imtoagent:
 //   imtoagent setup    — interactive setup wizard
 //   imtoagent start    — start gateway in background
+//   imtoagent run      — start gateway in foreground
 //   imtoagent stop     — stop gateway
 //   imtoagent status   — check running status
 //   imtoagent restore  — hot reload
-//   imtoagent daemon   — foreground daemon (auto-restart + logs)
+//   imtoagent daemon   — foreground daemon (auto-restart, for launchd/systemd)
 // ================================================================
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { spawn, execSync } from 'child_process';
 import { getDataDir } from '../modules/utils/paths';
 
 const PID_FILE = '/tmp/imtoagent.pid';
@@ -29,6 +31,9 @@ switch (command) {
   case 'start':
     await cmdStart();
     break;
+  case 'run':
+    await cmdRun();
+    break;
   case 'stop':
     await cmdStop();
     break;
@@ -42,14 +47,12 @@ switch (command) {
     await cmdDaemon();
     break;
   case undefined: {
-    // No command → auto-enter setup if not configured, show help otherwise
     const dataDir = getDataDir();
     const configPath = path.join(dataDir, 'config.json');
     let needsSetup = !fs.existsSync(configPath);
     if (!needsSetup) {
       try {
         const raw = fs.readFileSync(configPath, 'utf-8');
-        // If config still has YOUR_ placeholders, setup is incomplete
         needsSetup = /YOUR_[A-Z_]+/.test(raw);
       } catch { needsSetup = true; }
     }
@@ -81,11 +84,12 @@ imtoagent — IM ↔ Agent Unified Gateway
 
 Usage:
   imtoagent setup     Interactive setup wizard
-  imtoagent start     Start gateway in background
+  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 (auto-restart + logs, for launchd/systemd)
+  imtoagent daemon    Foreground daemon with auto-restart (for launchd/systemd)
 
 Data directory: ${getDataDir()}
 `);
@@ -100,7 +104,22 @@ async function cmdSetup() {
 }
 
 // ================================================================
-// start — launch in background
+// Shared: build gateway launch args
+// ================================================================
+function getGatewayArgs() {
+  const pkgDir = path.resolve(import.meta.dirname, '..');
+  const indexFile = path.join(pkgDir, 'index.ts');
+  return { execPath: process.execPath, args: ['run', indexFile] };
+}
+
+function ensureLogDir(dataDir: string) {
+  const logsDir = path.join(dataDir, 'logs');
+  if (!fs.existsSync(logsDir)) fs.mkdirSync(logsDir, { recursive: true });
+  return path.join(logsDir, 'imtoagent.log');
+}
+
+// ================================================================
+// start — background mode (spawn detached, log to file, return immediately)
 // ================================================================
 async function cmdStart() {
   // Check if already running
@@ -112,12 +131,10 @@ async function cmdStart() {
       console.error(`   Run "imtoagent stop" to stop first`);
       process.exit(1);
     } catch {
-      // Stale PID file, clean up
       fs.unlinkSync(PID_FILE);
     }
   }
 
-  // Check if config exists
   const dataDir = getDataDir();
   const configPath = path.join(dataDir, 'config.json');
   if (!fs.existsSync(configPath)) {
@@ -125,7 +142,7 @@ async function cmdStart() {
     process.exit(1);
   }
 
-  // Check if configured backends are installed
+  // Backend check (non-blocking)
   try {
     const { checkBackend } = await import('../modules/utils/backend-check');
     const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
@@ -140,25 +157,89 @@ async function cmdStart() {
     }
     if (missingBackends.length > 0) {
       console.error(`\n⚠️  The following backends are configured but not installed, messages will fail after gateway starts:`);
-      for (const b of missingBackends) {
-        console.error(`   ❌ ${b}`);
-      }
+      for (const b of missingBackends) console.error(`   ❌ ${b}`);
       console.error(`\nPlease install the missing backends, or run "imtoagent setup" to reconfigure.\n`);
-      // Don't force exit, let user start gateway and install backends later
     }
   } catch {
     // Check failure doesn't block startup
   }
 
-  console.log('🚀 Starting imtoagent gateway...');
+  const logFile = ensureLogDir(dataDir);
+
+  console.log('🚀 Starting imtoagent gateway (background)...');
   console.log(`   Data directory: ${dataDir}`);
-  console.log(`   Config file: ${configPath}`);
+  console.log(`   Log file: ${logFile}`);
 
-  // Launch in background using Bun.spawn
-  const pkgDir = path.resolve(import.meta.dirname, '..');
-  const indexFile = path.join(pkgDir, 'index.ts');
+  const { execPath, args } = getGatewayArgs();
+  const cmdLine = `"${execPath}" run "${path.resolve(import.meta.dirname, '..', 'index.ts')}"`;
+
+  // Use a shell to launch the gateway in background — avoids event-loop blockers
+  const shellCmd = `IMTOAGENT_HOME="${dataDir}" ${cmdLine} >> "${logFile}" 2>&1 &
+PID=$!
+echo $PID`;
 
-  const child = Bun.spawn([process.execPath, 'run', indexFile], {
+  const { execSync } = await import('child_process');
+  const pidStr = execSync(shellCmd, {
+    cwd: dataDir,
+    env: { ...process.env, IMTOAGENT_HOME: dataDir },
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+  const gatewayPid = parseInt(pidStr.split('\n').pop()!);
+
+  fs.writeFileSync(PID_FILE, String(gatewayPid));
+  console.log(`✅ Gateway started (PID=${gatewayPid})`);
+
+  // Wait for startup verification
+  await new Promise(r => setTimeout(r, 3000));
+  try {
+    process.kill(gatewayPid, 0);
+    console.log('✅ Gateway is running');
+  } catch {
+    console.error('❌ Gateway failed to start, check logs:');
+    if (fs.existsSync(logFile)) {
+      console.log(fs.readFileSync(logFile, 'utf-8').slice(-2000));
+    }
+    fs.unlinkSync(PID_FILE);
+    process.exit(1);
+  }
+
+  // Explicitly exit — Bun may keep event loop alive due to inherited stdio
+  process.exit(0);
+}
+
+// ================================================================
+// run — foreground mode (real-time logs, Ctrl+C to stop)
+// ================================================================
+async function cmdRun() {
+  const dataDir = getDataDir();
+  const configPath = path.join(dataDir, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    console.error('❌ No config file found. Please run "imtoagent setup" first');
+    process.exit(1);
+  }
+
+  const logFile = ensureLogDir(dataDir);
+
+  // Warn if already running in background
+  if (fs.existsSync(PID_FILE)) {
+    const pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim());
+    try {
+      process.kill(pid, 0);
+      console.log(`⚠️  Gateway is already running in background (PID=${pid})`);
+      console.log(`   Run "imtoagent stop" first, or this may conflict.\n`);
+    } catch {
+      fs.unlinkSync(PID_FILE);
+    }
+  }
+
+  const { execPath, args } = getGatewayArgs();
+
+  console.log('🚀 Starting imtoagent gateway (foreground mode)...');
+  console.log('   Press Ctrl+C to stop');
+  console.log('');
+
+  const child = Bun.spawn([execPath, ...args], {
     cwd: dataDir,
     env: { ...process.env, IMTOAGENT_HOME: dataDir },
     stdout: 'pipe',
@@ -166,16 +247,10 @@ async function cmdStart() {
   });
 
   fs.writeFileSync(PID_FILE, String(child.pid));
-  console.log(`✅ Gateway started (PID=${child.pid})`);
 
-  // Redirect background logs to logs/
-  const logsDir = path.join(dataDir, 'logs');
-  if (!fs.existsSync(logsDir)) fs.mkdirSync(logsDir, { recursive: true });
-  const logFile = path.join(logsDir, 'imtoagent.log');
+  const logStream = fs.createWriteStream(logFile, { flags: 'a' });
 
-  // Start log collection
-  (async () => {
-    const logStream = fs.createWriteStream(logFile, { flags: 'a' });
+  const pumpOut = (async () => {
     for await (const chunk of child.stdout as any) {
       const line = new TextDecoder().decode(chunk);
       process.stdout.write(line);
@@ -183,8 +258,7 @@ async function cmdStart() {
     }
   })().catch(() => {});
 
-  (async () => {
-    const logStream = fs.createWriteStream(logFile, { flags: 'a' });
+  const pumpErr = (async () => {
     for await (const chunk of child.stderr as any) {
       const line = new TextDecoder().decode(chunk);
       process.stderr.write(line);
@@ -192,18 +266,24 @@ async function cmdStart() {
     }
   })().catch(() => {});
 
-  // Wait for startup verification (check PID survives 5s)
-  await new Promise(r => setTimeout(r, 3000));
-  try {
-    process.kill(child.pid, 0);
-    console.log('✅ Gateway is running');
-  } catch {
-    console.error('❌ Gateway failed to start, check logs:');
-    if (fs.existsSync(logFile)) {
-      console.log(fs.readFileSync(logFile, 'utf-8').slice(-2000));
-    }
-    fs.unlinkSync(PID_FILE);
-    process.exit(1);
+  // Ctrl+C → SIGTERM to child
+  const cleanup = () => {
+    console.log('\n🛑 Stopping gateway...');
+    try { process.kill(child.pid, 'SIGTERM'); } catch {}
+  };
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  const exitCode = await child.exited;
+  await Promise.allSettled([pumpOut, pumpErr]);
+  logStream.end();
+
+  try { fs.unlinkSync(PID_FILE); } catch {}
+
+  if (exitCode === 0) {
+    console.log('✅ Gateway exited cleanly');
+  } else {
+    console.log(`⚠️  Gateway exited with code ${exitCode}`);
   }
 }
 
@@ -222,7 +302,6 @@ async function cmdStop() {
     console.log(`⏹  Stopping gateway (PID=${pid})...`);
     process.kill(pid, 'SIGTERM');
 
-    // Wait for process to exit
     for (let i = 0; i < 20; i++) {
       try {
         process.kill(pid, 0);
@@ -232,7 +311,6 @@ async function cmdStop() {
       }
     }
 
-    // Check if still running
     try {
       process.kill(pid, 0);
       console.log('⚠️  Process not responding, force killing...');
@@ -256,7 +334,6 @@ async function cmdStatus() {
   console.log(`\n📊 imtoagent Status`);
   console.log(`   Data directory: ${dataDir}`);
 
-  // Process status
   if (fs.existsSync(PID_FILE)) {
     const pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim());
     try {
@@ -269,7 +346,6 @@ async function cmdStatus() {
     console.log(`   Process: ⏸  Not running`);
   }
 
-  // Config file
   const configPath = path.join(dataDir, 'config.json');
   if (fs.existsSync(configPath)) {
     try {
@@ -286,7 +362,6 @@ async function cmdStatus() {
     console.log(`   Config: ❌ Not found (run "imtoagent setup")`);
   }
 
-  // Log file
   const logFile = path.join(dataDir, 'logs', 'imtoagent.log');
   if (fs.existsSync(logFile)) {
     const stats = fs.statSync(logFile);
@@ -320,13 +395,7 @@ async function cmdRestore() {
 }
 
 // ================================================================
-// daemon — foreground daemon mode (auto-restart + logs + graceful shutdown)
-// ================================================================
-// Design:
-//   - Runs in foreground, managed by launchd / systemd etc.
-//   - Auto-restarts on crash (exponential backoff, max 30s)
-//   - Graceful shutdown on SIGTERM/SIGINT, no restart
-//   - Logs written to ~/.imtoagent/logs/imtoagent.log
+// daemon — foreground daemon with auto-restart (for launchd/systemd)
 // ================================================================
 async function cmdDaemon(): Promise<void> {
   const dataDir = getDataDir();
@@ -337,21 +406,15 @@ async function cmdDaemon(): Promise<void> {
     process.exit(1);
   }
 
-  const logsDir = path.join(dataDir, 'logs');
-  if (!fs.existsSync(logsDir)) fs.mkdirSync(logsDir, { recursive: true });
-  const logFile = path.join(logsDir, 'imtoagent.log');
-
-  const pkgDir = path.resolve(import.meta.dirname, '..');
-  const indexFile = path.join(pkgDir, 'index.ts');
+  const logFile = ensureLogDir(dataDir);
+  const { execPath, args } = getGatewayArgs();
 
   console.log(`🛡  imtoagent Daemon Mode`);
   console.log(`   Data directory: ${dataDir}`);
   console.log(`   Log file: ${logFile}`);
   console.log(`   Press Ctrl+C to stop\n`);
 
-  // Graceful shutdown flag
   let shuttingDown = false;
-
   const shutdown = () => {
     if (shuttingDown) return;
     shuttingDown = true;
@@ -362,15 +425,13 @@ async function cmdDaemon(): Promise<void> {
   process.on('SIGINT', shutdown);
 
   let retryDelay = 0;
-  const MAX_RETRY_DELAY = 30_000; // 30s cap
+  const MAX_RETRY_DELAY = 30_000;
 
   while (!shuttingDown) {
-    // No delay on first run, exponential backoff after
     if (retryDelay > 0) {
       console.log(`   Waiting ${retryDelay / 1000}s before restart...`);
       await new Promise<void>(resolve => {
         const timer = setTimeout(resolve, retryDelay);
-        // Exit immediately if shutdown signal received during wait
         const check = setInterval(() => {
           if (shuttingDown) {
             clearTimeout(timer);
@@ -382,56 +443,39 @@ async function cmdDaemon(): Promise<void> {
       if (shuttingDown) break;
     }
 
-    const logStream = fs.createWriteStream(logFile, { flags: 'a' });
+    // Open log fd for child stdout/stderr
+    const logFd = fs.openSync(logFile, 'a');
 
-    const child = Bun.spawn([process.execPath, 'run', indexFile], {
+    const child = spawn(execPath, args, {
       cwd: dataDir,
       env: { ...process.env, IMTOAGENT_HOME: dataDir },
-      stdout: 'pipe',
-      stderr: 'pipe',
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
     });
 
     const childPid = child.pid;
     fs.writeFileSync(PID_FILE, String(childPid));
     console.log(`[${new Date().toISOString()}] 🚀 Starting gateway (PID=${childPid})`);
 
-    // Log collection
-    const pumpStdout = (async () => {
-      for await (const chunk of child.stdout as any) {
-        const line = new TextDecoder().decode(chunk);
-        process.stdout.write(line);
-        logStream.write(line);
-      }
-    })().catch(() => {});
-
-    const pumpStderr = (async () => {
-      for await (const chunk of child.stderr as any) {
-        const line = new TextDecoder().decode(chunk);
-        process.stderr.write(line);
-        logStream.write(line);
-      }
-    })().catch(() => {});
-
-    // Wait for child process to exit
-    const exitCode = await child.exited;
-    await Promise.allSettled([pumpStdout, pumpStderr]);
-    logStream.end();
+    let childExitCode: number | null = null;
+    await new Promise<void>(resolve => {
+      child.on('exit', (code) => { childExitCode = code; resolve(); });
+      child.on('error', () => resolve());
+    });
 
+    fs.closeSync(logFd);
     try { fs.unlinkSync(PID_FILE); } catch {}
 
     if (shuttingDown) break;
 
-    // Determine if restart needed
-    if (exitCode === 0) {
+    if (childExitCode === 0) {
       console.log(`[${new Date().toISOString()}] ⏹  Gateway exited cleanly (code=0), not restarting`);
       break;
     }
 
-    // Crash → exponential backoff restart
     retryDelay = retryDelay === 0 ? 3_000 : Math.min(retryDelay * 2, MAX_RETRY_DELAY);
-    console.log(`[${new Date().toISOString()}] ⚠️  Gateway crashed (code=${exitCode}), restarting in ${retryDelay / 1000}s`);
+    console.log(`[${new Date().toISOString()}] ⚠️  Gateway crashed (code=${childExitCode}), restarting in ${retryDelay / 1000}s`);
   }
 
   console.log('👋 Daemon stopped');
 }
-

package/bin/imtoagent.cjs

@@ -3,7 +3,7 @@
 "use strict";
 var path = require("path");
 var fs = require("fs");
-var spawnSync = require("child_process").spawnSync;
+var spawn = require("child_process").spawn;
 
 var candidates = [
   process.env.BUN_BIN,
@@ -12,7 +12,7 @@ var candidates = [
   "/opt/homebrew/bin/bun",
 ];
 try {
-  var r = spawnSync("which", ["bun"]);
+  var r = require("child_process").spawnSync("which", ["bun"]);
   if (r.status === 0) candidates.unshift(r.stdout.toString().trim());
 } catch (e) {}
 
@@ -32,8 +32,16 @@ if (!bunPath) {
 
 var pkgDir = path.resolve(__dirname, "..");
 var real = path.join(pkgDir, "bin", "imtoagent-real");
-var result = spawnSync(bunPath, [real].concat(process.argv.slice(2)), {
+var child = spawn(bunPath, [real].concat(process.argv.slice(2)), {
   stdio: "inherit",
   env: Object.assign({}, process.env),
 });
-process.exit(result.status || 0);
+
+child.on("exit", function (code) {
+  process.exit(code || 0);
+});
+
+child.on("error", function (err) {
+  console.error("❌ Failed to start imtoagent:", err.message);
+  process.exit(1);
+});

package/install.sh

@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+#
+# imtoagent — One-Click Install Script
+# Usage: curl -fsSL https://raw.githubusercontent.com/imtoagent/imtoagent/main/scripts/install.sh | bash
+#
+# This script detects the environment, installs dependencies, installs/upgrades
+# imtoagent, and optionally runs the interactive setup wizard.
+#
+# Flags:
+#   --non-interactive    Skip interactive setup (for CI/automated installs)
+#   --skip-bun           Skip bun installation check
+#   --skip-start         Don't start the gateway after install
+
+set -euo pipefail
+
+# ============================================================
+# Colors & Helpers
+# ============================================================
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+info()  { echo -e "${BLUE}ℹ  ${NC}$1"; }
+ok()    { echo -e "${GREEN}✅ ${NC}$1"; }
+warn()  { echo -e "${YELLOW}⚠️  ${NC}$1"; }
+error() { echo -e "${RED}❌ ${NC}$1"; }
+step()  { echo -e "\n${BOLD}${CYAN}▸ $1${NC}"; }
+done_ok() { echo -e "  ${GREEN}✓${NC} $1"; }
+
+# ============================================================
+# Parse flags
+# ============================================================
+NON_INTERACTIVE=false
+SKIP_BUN=false
+SKIP_START=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --non-interactive) NON_INTERACTIVE=true ;;
+    --skip-bun)        SKIP_BUN=true ;;
+    --skip-start)      SKIP_START=true ;;
+  esac
+done
+
+# ============================================================
+# Banner
+# ============================================================
+echo ""
+echo -e "${BOLD}  ┌──────────────────────────────────────────┐${NC}"
+echo -e "${BOLD}  │  ${CYAN}imtoagent${NC} — IM ↔ Agent Unified Gateway${BOLD}   │${NC}"
+echo -e "${BOLD}  └──────────────────────────────────────────┘${NC}"
+echo ""
+
+# ============================================================
+# 1. OS Detection
+# ============================================================
+step "1. Detecting environment"
+
+OS=""
+ARCH=""
+
+case "$(uname -s)" in
+  Darwin*)  OS="macos" ;;
+  Linux*)   OS="linux" ;;
+  *)        error "Unsupported OS: $(uname -s)"; exit 1 ;;
+esac
+
+case "$(uname -m)" in
+  arm64|aarch64) ARCH="aarch64" ;;
+  x86_64|amd64)  ARCH="x64" ;;
+  *)             ARCH="unknown" ;;
+esac
+
+done_ok "OS: $OS ($(uname -m))"
+
+# ============================================================
+# 2. Bun Detection & Installation
+# ============================================================
+if [ "$SKIP_BUN" = true ]; then
+  info "Skipping bun check (--skip-bun)"
+else
+  step "2. Checking bun"
+
+  BUN_BIN=""
+
+  # Check environment variable first
+  if [ -n "${BUN_BIN:-}" ] && [ -x "$BUN_BIN" ]; then
+    BUN_BIN="$BUN_BIN"
+  # Check common paths
+  elif [ -x "$HOME/.bun/bin/bun" ]; then
+    BUN_BIN="$HOME/.bun/bin/bun"
+  elif [ -x "/opt/homebrew/bin/bun" ]; then
+    BUN_BIN="/opt/homebrew/bin/bun"
+  elif [ -x "/usr/local/bin/bun" ]; then
+    BUN_BIN="/usr/local/bin/bun"
+  elif command -v bun &>/dev/null; then
+    BUN_BIN="$(command -v bun)"
+  fi
+
+  if [ -n "$BUN_BIN" ]; then
+    BUN_VER=$("$BUN_BIN" --version 2>/dev/null || echo "unknown")
+    done_ok "bun found: $BUN_BIN (v${BUN_VER})"
+  else
+    warn "bun not found — installing..."
+    echo ""
+
+    if [ "$OS" = "macos" ] || [ "$OS" = "linux" ]; then
+      echo "  Downloading and installing bun..."
+      curl -fsSL https://bun.sh/install | bash 2>&1 | tail -5
+
+      # Add bun to PATH for this session
+      if [ -f "$HOME/.bun/bin/bun" ]; then
+        BUN_BIN="$HOME/.bun/bin/bun"
+        export PATH="$HOME/.bun/bin:$PATH"
+      elif command -v bun &>/dev/null; then
+        BUN_BIN="$(command -v bun)"
+      fi
+
+      if [ -n "$BUN_BIN" ] && [ -x "$BUN_BIN" ]; then
+        BUN_VER=$("$BUN_BIN" --version 2>/dev/null || echo "unknown")
+        done_ok "bun installed: v${BUN_VER}"
+      else
+        error "bun installation failed. Please install manually:"
+        echo "   curl -fsSL https://bun.sh/install | bash"
+        echo "   Then re-run this script."
+        exit 1
+      fi
+    else
+      error "Unsupported platform for automatic bun install."
+      echo "   Install bun manually: https://bun.sh"
+      exit 1
+    fi
+  fi
+fi
+
+# ============================================================
+# 3. Node.js Check (npm requires node)
+# ============================================================
+step "3. Checking node/npm"
+
+if command -v node &>/dev/null; then
+  NODE_VER=$(node --version)
+  done_ok "node: ${NODE_VER}"
+else
+  warn "node not found — npm install will fail"
+  echo ""
+  echo "  You need Node.js installed. Options:"
+  echo "   macOS: brew install node"
+  echo "   Linux: apt install nodejs npm  (or use nvm)"
+  echo ""
+  echo "  Or install via nvm:"
+  echo "   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash"
+  echo "   source ~/.bashrc  # or ~/.zshrc"
+  echo "   nvm install 20"
+  echo ""
+  if [ "$NON_INTERACTIVE" = true ]; then
+    error "Cannot continue in non-interactive mode without node."
+    exit 1
+  fi
+  read -rp "  Continue anyway? [y/N] " CONTINUE
+  case "$CONTINUE" in
+    [yY]*) info "Continuing..." ;;
+    *)     error "Aborted."; exit 1 ;;
+  esac
+fi
+
+if command -v npm &>/dev/null; then
+  NPM_VER=$(npm --version)
+  done_ok "npm: v${NPM_VER}"
+else
+  error "npm not found — required for installation"
+  exit 1
+fi
+
+# ============================================================
+# 4. Install / Upgrade imtoagent
+# ============================================================
+step "4. Installing imtoagent"
+
+# Check if already installed
+EXISTING_VER=""
+if command -v imtoagent &>/dev/null; then
+  EXISTING_VER=$(imtoagent --version 2>/dev/null || echo "unknown")
+  warn "Already installed: v${EXISTING_VER}"
+  echo ""
+  if [ "$NON_INTERACTIVE" = true ]; then
+    info "Non-interactive mode — upgrading"
+  else
+    read -rp "  Upgrade to latest? [Y/n] " UPGRADE
+    case "$UPGRADE" in
+      [nN]*) info "Skipping upgrade."; exit 0 ;;
+    esac
+  fi
+fi
+
+echo "  Running: npm install -g imtoagent"
+echo ""
+npm install -g imtoagent 2>&1 | tail -10
+
+INSTALLED_VER=$(imtoagent --version 2>/dev/null || echo "unknown")
+done_ok "imtoagent v${INSTALLED_VER} installed globally"
+
+# ============================================================
+# 5. Configuration Check & Setup
+# ============================================================
+step "5. Checking configuration"
+
+CONFIG_DIR="$HOME/.imtoagent"
+CONFIG_FILE="$CONFIG_DIR/config.json"
+
+NEED_SETUP=true
+
+if [ -f "$CONFIG_FILE" ]; then
+  done_ok "Config found: $CONFIG_FILE"
+
+  # Quick check if config has any bots (grep for botType field)
+  if grep -q '"botType"' "$CONFIG_FILE" 2>/dev/null; then
+    BOT_COUNT=$(grep -c '"botType"' "$CONFIG_FILE" 2>/dev/null || echo "0")
+    done_ok "$BOT_COUNT bot(s) configured — skipping setup wizard"
+    NEED_SETUP=false
+  else
+    warn "No bots configured in config"
+  fi
+else
+  warn "No configuration found"
+fi
+
+if [ "$NEED_SETUP" = true ]; then
+  if [ "$NON_INTERACTIVE" = true ]; then
+    info "Non-interactive mode — skipping setup wizard"
+    echo ""
+    echo "  Run 'imtoagent setup' manually to configure."
+  else
+    echo ""
+    echo "  Starting interactive setup wizard..."
+    echo "  You'll need:"
+    echo "   • IM platform credentials (Feishu App ID/Secret, Telegram Token, etc.)"
+    echo "   • Agent backend (Claude Code / Codex / OpenCode)"
+    echo "   • Model provider API keys"
+    echo ""
+    read -rp "  Start setup now? [Y/n] " START_SETUP
+    case "$START_SETUP" in
+      [nN]*)
+        info "Skipping setup. Run 'imtoagent setup' later to configure."
+        ;;
+      *)
+        echo ""
+        imtoagent setup
+        ;;
+    esac
+  fi
+fi
+
+# ============================================================
+# 6. Start Gateway (optional)
+# ============================================================
+if [ "$SKIP_START" = true ]; then
+  info "Skipping gateway start (--skip-start)"
+else
+  step "6. Starting gateway"
+
+  # Check if already running
+  if imtoagent status 2>/dev/null | grep -q "running"; then
+    warn "Gateway already running"
+    imtoagent status 2>/dev/null || true
+  else
+    if [ "$NON_INTERACTIVE" = true ]; then
+      info "Non-interactive mode — starting gateway in background"
+      imtoagent start
+      sleep 3
+      imtoagent status 2>/dev/null || true
+    else
+      read -rp "  Start gateway now? [Y/n] " START_GATEWAY
+      case "$START_GATEWAY" in
+        [nN]*)
+          info "Not starting. Run 'imtoagent start' when ready."
+          ;;
+        *)
+          imtoagent start
+          sleep 3
+          imtoagent status 2>/dev/null || true
+          ;;
+      esac
+    fi
+  fi
+fi
+
+# ============================================================
+# Summary
+# ============================================================
+echo ""
+echo -e "${BOLD}  ──────────────────────────────────────────${NC}"
+echo -e "${GREEN}${BOLD}  Installation Complete!${NC}"
+echo -e "${BOLD}  ──────────────────────────────────────────${NC}"
+echo ""
+echo "  Version:  v${INSTALLED_VER}"
+echo "  Config:   ${CONFIG_FILE}"
+echo "  Logs:     ${CONFIG_DIR}/logs/"
+echo ""
+echo "  Quick commands:"
+echo "    imtoagent status    # Check gateway status"
+echo "    imtoagent stop      # Stop the gateway"
+echo "    imtoagent setup     # Configure bots"
+echo "    imtoagent restore   # Hot reload"
+echo ""
+echo "  Send ${BOLD}/help${NC} to your Bot in IM to see available commands."
+echo ""
+echo "  Docs: https://github.com/imtoagent/imtoagent"
+echo ""

package/modules/agent/codex-adapter.ts

@@ -88,7 +88,7 @@ async function spawnCodexResume(cwd: string, threadId: string, prompt: string):
   try {
     [stdout, stderr] = await Promise.all([
       new Response(child.stdout).text().catch((e: any) => { throw new Error(`stdout read failed: ${e?.message || e}`); }),
-      new Response(child.stderr).text().catch((e: any) => { throw new Error(`stderr read failed: ${e?.message || e}`; }),
+      new Response(child.stderr).text().catch((e: any) => { throw new Error(`stderr read failed: ${e?.message || e}`); }),
     ]);
   } catch (ioErr: any) {
     try { child.kill('SIGKILL'); } catch {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imtoagent",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "IM ↔ Agent 统一网关 — 飞书/Telegram/微信/企业微信对接 Claude Code/Codex/OpenCode",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "templates/",
     "scripts/",
     "README.md",
+    "install.sh",
     "bin/imtoagent.ts",
     "bin/imtoagent.cjs",
     "bin/imtoagent-real"
@@ -32,7 +33,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/YOUR_USERNAME/imtoagent.git"
+    "url": "https://github.com/imtoagent/imtoagent.git",
+    "directory": ""
   },
   "keywords": [
     "im",
@@ -50,7 +52,7 @@
   "author": "Keyi",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/YOUR_USERNAME/imtoagent/issues"
+    "url": "https://github.com/imtoagent/imtoagent/issues"
   },
-  "homepage": "https://github.com/YOUR_USERNAME/imtoagent#readme"
+  "homepage": "https://github.com/imtoagent/imtoagent#readme"
 }