imtoagent 0.3.6 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imtoagent",
-  "version": "0.3.6",
+  "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"
 }