imtoagent 0.2.0

package/README.md

@@ -0,0 +1,234 @@
+# imtoagent — IM ↔ Agent 统一网关
+
+将飞书、Telegram、个人微信、企业微信对接到 Claude Code、Codex (GPT)、OpenCode 等 AI 编程 Agent。
+
+一个网关，多个 IM，多种 Agent，统一端口代理。
+
+## 架构
+
+```
+飞书/Telegram/微信/企微 → IM Registry 工厂 → Bot 实例
+                                          → AgentRuntime SDK → Agent Adapter
+                                                             → 统一 Proxy (:18899) → 上游模型
+```
+
+### 已支持的 IM 适配器
+
+| IM | 连接方式 | 能力 |
+|----|----------|------|
+| **飞书** | WebSocket 长连接 + 自动重连 | 文本、代码块、卡片、文件、图片、语音、按钮 |
+| **Telegram** | 长轮询 + HTTP 代理 | 文本、文件、图片、语音 |
+| **个人微信** | iLink HTTP long-poll + QR 扫码 | 文本、图片、文件、语音（AES-128-ECB 加密） |
+| **企业微信** | HTTP Webhook 回调 + REST API | 文本、文件、图片 |
+
+### 已支持的 Agent 后端
+
+| 后端 | 对接方式 |
+|------|----------|
+| **Claude Code** | Claude Agent SDK spawn 子进程 |
+| **Codex** | app-server v2 (stdio JSON-RPC) |
+| **OpenCode** | HTTP API client |
+
+## 快速开始
+
+### 前置条件
+
+- **Bun** 运行时（≥1.0.0）：`brew install oven-sh/bun/bun`
+- **macOS / Linux**
+- **至少一个 Agent 后端**（见下表，安装 imtoagent 前或后安装均可）
+
+| 后端 | 安装命令 |
+|------|----------|
+| Claude Code | `npm install -g @anthropic-ai/claude-agent-sdk` |
+| Codex | `npm install -g @openai/codex` |
+| OpenCode | `npm install -g opencode` |
+
+### 安装
+
+#### 方式一：npm 全局安装（推荐）
+
+```bash
+npm install -g imtoagent
+```
+
+安装完成后自动检测是否需要初始配置，交互式终端会自动引导进入配置向导。
+
+#### 方式二：源码安装
+
+```bash
+git clone https://github.com/YOUR_USERNAME/imtoagent.git
+cd imtoagent
+bun install
+bun run bin/imtoagent setup
+```
+
+### 首次配置
+
+```bash
+imtoagent setup
+```
+
+交互式配置向导引导你完成：
+
+1. **配置 Bot** — 选择 IM 平台 + Agent 后端
+2. **配置模型供应商** — 添加 API 凭证（DeepSeek、Dashscope 等）
+3. **生成灵魂文件** — 为每个 Bot 创建 rules.md / identity.md 等
+4. **写入配置文件** — 自动生成 `~/.imtoagent/config.json`
+
+#### 飞书 Bot 需要
+
+- 飞书 App ID（`cli_...`）
+- 飞书 App Secret
+- 飞书应用需开启：机器人、事件订阅、消息收发权限
+
+#### Telegram Bot 需要
+
+- Telegram Bot Token（从 @BotFather 获取）
+- 可选：代理地址（如 `http://127.0.0.1:7890`）
+
+#### 个人微信
+
+- 首次运行 `imtoagent start` 后自动弹出 QR 码
+- 用手机微信扫码完成绑定
+
+### 启动网关
+
+```bash
+imtoagent start     # 后台启动
+imtoagent status    # 查看运行状态
+imtoagent stop      # 停止网关
+```
+
+### 开机自启（macOS launchd）
+
+```bash
+# 创建 launchd 配置
+cat > ~/Library/LaunchAgents/com.imtoagent.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.imtoagent</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/opt/homebrew/bin/bun</string>
+        <string>run</string>
+        <string>/usr/local/lib/node_modules/imtoagent/index.ts</string>
+        <string>daemon</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>/Users/$USER/.imtoagent</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>/Users/$USER/.imtoagent/logs/launchd.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/$USER/.imtoagent/logs/launchd.err.log</string>
+</dict>
+</plist>
+EOF
+
+# 加载
+launchctl load ~/Library/LaunchAgents/com.imtoagent.plist
+```
+
+### 常用命令
+
+| 命令 | 说明 |
+|------|------|
+| `imtoagent setup` | 交互式配置向导 |
+| `imtoagent start` | 后台启动网关 |
+| `imtoagent stop` | 停止网关 |
+| `imtoagent status` | 查看运行状态 |
+| `imtoagent restore` | 热重载恢复 |
+| `imtoagent daemon` | 前台守护模式（适合 launchd/systemd 托管） |
+
+### 网关内建命令
+
+在 IM 聊天中发送给 Bot：
+
+| 命令 | 说明 |
+|------|------|
+| `/help` | 帮助信息 |
+| `/status` | 网关状态 |
+| `/stats` | 使用统计 |
+| `/model` | 切换模型 |
+| `/providers` | 查看供应商 |
+| `/memory` | 查看记忆 |
+| `/soul` | 灵魂管理 |
+| `/reload` | 重新加载 |
+| `/clear` | 清除会话 |
+| `/mode` | 切换模式（权限/auto/plan） |
+| `/dir` | 切换工作目录 |
+
+## 项目结构
+
+```
+imtoagent/
+├── index.ts                    # 入口 — IM Registry + Bot 构造 + Proxy 启动
+├── bin/imtoagent               # CLI 命令入口
+├── modules/
+│   ├── core/                   # SDK Core
+│   │   ├── AgentRuntime.ts     # 消息处理中枢
+│   │   ├── AgentAdapter.ts     # Agent 后端统一抽象
+│   │   ├── SessionManager.ts   # 会话持久化
+│   │   └── types.ts            # 类型定义
+│   ├── im/                     # IM 适配器
+│   │   ├── feishu.ts           # 飞书
+│   │   ├── telegram.ts         # Telegram
+│   │   ├── wechat.ts           # 个人微信
+│   │   └── wecom.ts            # 企业微信
+│   ├── agent/                  # Agent 后端
+│   │   ├── claude-adapter.ts   # Claude Code
+│   │   ├── codex-adapter.ts    # Codex
+│   │   └── opencode-adapter.ts # OpenCode
+│   ├── proxy/                  # 统一代理
+│   │   └── anthropic-proxy.ts  # :18899 Anthropic 格式代理
+│   ├── cli/                    # CLI
+│   │   └── setup.ts            # 交互式配置向导
+│   └── utils/
+│       └── paths.ts            # 路径解析 + 自动初始化
+├── scripts/
+│   └── postinstall.ts          # npm 安装后引导
+├── templates/                  # 配置模板
+│   ├── config.template.json
+│   ├── providers.template.json
+│   ├── opencode.template.json
+│   └── soul.template/
+└── README.md
+```
+
+## 数据目录
+
+所有运行时数据统一存储在 `~/.imtoagent/`：
+
+```
+~/.imtoagent/
+├── config.json          # 主配置（Bot + 供应商 + 系统）
+├── providers.json       # 模型供应商配置
+├── opencode.json        # OpenCode 配置
+├── sessions/            # 会话持久化
+├── logs/                # 运行日志
+└── soul/                # 灵魂文件（每 Bot 一个目录）
+    ├── ClaudeBot/
+    ├── CodexBot/
+    └── ...
+```
+
+## 开发
+
+```bash
+bun install
+bun run index.ts          # 直接运行
+bun run bin/imtoagent setup  # 运行配置向导
+```
+
+## License
+
+MIT

package/bin/imtoagent

@@ -0,0 +1,453 @@
+#!/usr/bin/env bun
+// ================================================================
+// imtoagent CLI — 全局命令入口
+// ================================================================
+// npm install -g imtoagent 后可用：
+//   imtoagent setup    — 交互式配置向导
+//   imtoagent start    — 后台启动网关
+//   imtoagent stop     — 停止网关
+//   imtoagent status   — 查看运行状态
+//   imtoagent restore  — 热重载恢复
+//   imtoagent daemon   — 前台守护模式（自动重启 + 日志）
+// ================================================================
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { getDataDir } from '../modules/utils/paths';
+
+const PID_FILE = '/tmp/imtoagent.pid';
+
+// ================================================================
+// 命令分发
+// ================================================================
+const command = process.argv[2];
+
+switch (command) {
+  case 'setup':
+    await cmdSetup();
+    break;
+  case 'start':
+    await cmdStart();
+    break;
+  case 'stop':
+    await cmdStop();
+    break;
+  case 'status':
+    await cmdStatus();
+    break;
+  case 'restore':
+    await cmdRestore();
+    break;
+  case 'daemon':
+    await cmdDaemon();
+    break;
+  case undefined:
+  case 'help':
+  case '--help':
+  case '-h':
+    // 无命令 + 无配置 → 自动引导进入 setup
+    if (!command && !fs.existsSync(path.join(getDataDir(), 'config.json'))) {
+      console.log('⚠️  未检测到配置文件，请先完成初始配置\n');
+      await cmdSetup();
+    } else {
+      printHelp();
+    }
+    break;
+  default:
+    console.error(`❌ 未知命令: ${command}`);
+    printHelp();
+    process.exit(1);
+}
+
+// ================================================================
+// Help
+// ================================================================
+function printHelp() {
+  console.log(`
+imtoagent — IM ↔ Agent 统一网关
+
+用法:
+  imtoagent setup     交互式配置向导
+  imtoagent start     后台启动网关
+  imtoagent stop      停止网关
+  imtoagent status    查看运行状态
+  imtoagent restore   热重载恢复
+  imtoagent daemon    前台守护模式（自动重启 + 日志，适合 launchd/systemd 托管）
+
+数据目录: ${getDataDir()}
+`);
+}
+
+// ================================================================
+// setup — 交互式向导
+// ================================================================
+async function cmdSetup() {
+  const { runSetupWizard } = await import('../modules/cli/setup');
+  await runSetupWizard();
+}
+
+// ================================================================
+// start — 后台启动
+// ================================================================
+async function cmdStart() {
+  // 检查是否已在运行
+  if (fs.existsSync(PID_FILE)) {
+    const pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim());
+    try {
+      process.kill(pid, 0);
+      console.error(`❌ 网关已在运行 (PID=${pid})`);
+      console.error(`   运行 "imtoagent stop" 先停止`);
+      process.exit(1);
+    } catch {
+      // 旧 PID 文件残留，清理
+      fs.unlinkSync(PID_FILE);
+    }
+  }
+
+  // 检查配置是否存在
+  const dataDir = getDataDir();
+  const configPath = path.join(dataDir, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    console.error('❌ 未找到配置文件，请先运行 "imtoagent setup"');
+    process.exit(1);
+  }
+
+  // 检查配置的后端是否已安装
+  try {
+    const { checkBackend } = await import('../modules/utils/backend-check');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const missingBackends: string[] = [];
+    for (const bot of config.bots || []) {
+      if (bot.backend && ['claude', 'codex', 'opencode'].includes(bot.backend)) {
+        const info = checkBackend(bot.backend as any);
+        if (!info.installed && !missingBackends.includes(bot.backend)) {
+          missingBackends.push(bot.backend);
+        }
+      }
+    }
+    if (missingBackends.length > 0) {
+      console.error(`\n⚠️  以下后端已配置但未安装：`);
+      for (const name of missingBackends) {
+        const b = BACKEND_DEFS.find((d) => d.type === name);
+        console.error(`   ❌ ${name} ${b ? `(${b.label})` : ''}`);
+      }
+
+      // 交互式询问是否自动安装
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+
+      const answer = await new Promise<string>((resolve) => {
+        rl.question('\n🔧 是否自动安装缺失的后端？[Y/n]: ', resolve);
+      });
+      rl.close();
+
+      if (answer.trim().toLowerCase() !== 'n') {
+        const { installBackend } = await import('../modules/utils/backend-check');
+        let allInstalled = true;
+
+        for (const name of missingBackends) {
+          const ok = await installBackend(name as 'claude' | 'codex' | 'opencode');
+          if (!ok) allInstalled = false;
+        }
+
+        if (allInstalled) {
+          console.log('\n✅ 所有后端安装完成，正在启动网关...\n');
+        } else {
+          console.error('\n⚠️  部分后端安装失败。网关仍可启动，但使用未安装的后端时会报错。\n');
+        }
+      } else {
+        console.error('\n跳过安装。网关仍可启动，但使用未安装的后端时会报错。\n');
+      }
+    }
+  } catch {
+    // 检查失败不影响启动
+  }
+
+  console.log('🚀 启动 imtoagent 网关...');
+  console.log(`   数据目录: ${dataDir}`);
+  console.log(`   配置文件: ${configPath}`);
+
+  // 使用 Bun.spawn 后台启动
+  const pkgDir = path.resolve(import.meta.dirname, '..');
+  const indexFile = path.join(pkgDir, 'index.ts');
+
+  const child = Bun.spawn(['bun', 'run', indexFile], {
+    cwd: dataDir,
+    env: { ...process.env, IMTOAGENT_HOME: dataDir },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  fs.writeFileSync(PID_FILE, String(child.pid));
+  console.log(`✅ 网关已启动 (PID=${child.pid})`);
+
+  // 后台日志重定向到 logs/
+  const logsDir = path.join(dataDir, 'logs');
+  if (!fs.existsSync(logsDir)) fs.mkdirSync(logsDir, { recursive: true });
+  const logFile = path.join(logsDir, 'imtoagent.log');
+
+  // 启动日志收集
+  (async () => {
+    const logStream = fs.createWriteStream(logFile, { flags: 'a' });
+    for await (const chunk of child.stdout as any) {
+      const line = new TextDecoder().decode(chunk);
+      process.stdout.write(line);
+      logStream.write(line);
+    }
+  })().catch(() => {});
+
+  (async () => {
+    const logStream = fs.createWriteStream(logFile, { flags: 'a' });
+    for await (const chunk of child.stderr as any) {
+      const line = new TextDecoder().decode(chunk);
+      process.stderr.write(line);
+      logStream.write(line);
+    }
+  })().catch(() => {});
+
+  // 等待启动验证（5 秒内检查 PID 是否存活）
+  await new Promise(r => setTimeout(r, 3000));
+  try {
+    process.kill(child.pid, 0);
+    console.log('✅ 网关运行正常');
+  } catch {
+    console.error('❌ 网关启动失败，查看日志:');
+    if (fs.existsSync(logFile)) {
+      console.log(fs.readFileSync(logFile, 'utf-8').slice(-2000));
+    }
+    fs.unlinkSync(PID_FILE);
+    process.exit(1);
+  }
+}
+
+// ================================================================
+// stop — 停止
+// ================================================================
+async function cmdStop() {
+  if (!fs.existsSync(PID_FILE)) {
+    console.log('ℹ️  网关未运行');
+    return;
+  }
+
+  const pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim());
+  try {
+    process.kill(pid, 0);
+    console.log(`⏹  正在停止网关 (PID=${pid})...`);
+    process.kill(pid, 'SIGTERM');
+
+    // 等待退出
+    for (let i = 0; i < 20; i++) {
+      try {
+        process.kill(pid, 0);
+        await new Promise(r => setTimeout(r, 500));
+      } catch {
+        break;
+      }
+    }
+
+    // 检查是否还在
+    try {
+      process.kill(pid, 0);
+      console.log('⚠️  进程未响应，强制终止...');
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      console.log('✅ 网关已停止');
+    }
+  } catch {
+    console.log('ℹ️  网关未运行（PID 文件残留，已清理）');
+  }
+
+  try { fs.unlinkSync(PID_FILE); } catch {}
+}
+
+// ================================================================
+// status — 状态
+// ================================================================
+async function cmdStatus() {
+  const dataDir = getDataDir();
+
+  console.log(`\n📊 imtoagent 状态`);
+  console.log(`   数据目录: ${dataDir}`);
+
+  // 进程状态
+  if (fs.existsSync(PID_FILE)) {
+    const pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim());
+    try {
+      process.kill(pid, 0);
+      console.log(`   进程: ✅ 运行中 (PID=${pid})`);
+    } catch {
+      console.log(`   进程: ❌ 已停止 (PID=${pid} 不存在)`);
+    }
+  } else {
+    console.log(`   进程: ⏸  未运行`);
+  }
+
+  // 配置文件
+  const configPath = path.join(dataDir, 'config.json');
+  if (fs.existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      const bots = cfg.bots || [];
+      console.log(`   配置: ✅ 已配置 (${bots.length} 个 Bot)`);
+      for (const bot of bots) {
+        console.log(`     - ${bot.name} (${bot.backend})`);
+      }
+    } catch {
+      console.log(`   配置: ❌ 解析失败`);
+    }
+  } else {
+    console.log(`   配置: ❌ 未找到 (运行 "imtoagent setup")`);
+  }
+
+  // 日志
+  const logFile = path.join(dataDir, 'logs', 'imtoagent.log');
+  if (fs.existsSync(logFile)) {
+    const stats = fs.statSync(logFile);
+    const size = stats.size > 1024 * 1024
+      ? (stats.size / (1024 * 1024)).toFixed(1) + ' MB'
+      : (stats.size / 1024).toFixed(1) + ' KB';
+    console.log(`   日志: ${size} (${logFile})`);
+  }
+
+  console.log();
+}
+
+// ================================================================
+// restore — 热重载
+// ================================================================
+async function cmdRestore() {
+  if (!fs.existsSync(PID_FILE)) {
+    console.error('❌ 网关未运行，无法热重载');
+    process.exit(1);
+  }
+
+  const pid = parseInt(fs.readFileSync(PID_FILE, 'utf-8').trim());
+  console.log(`🔄 发送 SIGHUP 到网关 (PID=${pid})...`);
+  try {
+    process.kill(pid, 'SIGHUP');
+    console.log('✅ 热重载信号已发送');
+  } catch (e: any) {
+    console.error(`❌ 发送失败: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+// ================================================================
+// daemon — 前台守护模式（自动重启 + 日志 + 优雅退出）
+// ================================================================
+// 设计用途：
+//   - 前台运行，被 launchd / systemd 等进程管理器托管
+//   - 崩溃时自动重启（指数退避，最长 30s）
+//   - 收到 SIGTERM/SIGINT 时优雅关闭，不重启
+//   - 日志写入 ~/.imtoagent/logs/imtoagent.log
+// ================================================================
+async function cmdDaemon(): Promise<void> {
+  const dataDir = getDataDir();
+  const configPath = path.join(dataDir, 'config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error('❌ 未找到配置文件，请先运行 "imtoagent setup"');
+    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');
+
+  console.log(`🛡  imtoagent 守护模式`);
+  console.log(`   数据目录: ${dataDir}`);
+  console.log(`   日志文件: ${logFile}`);
+  console.log(`   按 Ctrl+C 停止\n`);
+
+  // 优雅退出标记
+  let shuttingDown = false;
+
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log('\n🛑 收到停止信号，正在关闭...');
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  let retryDelay = 0;
+  const MAX_RETRY_DELAY = 30_000; // 30s 上限
+
+  while (!shuttingDown) {
+    // 首次无延迟，之后指数退避
+    if (retryDelay > 0) {
+      console.log(`   等待 ${retryDelay / 1000}s 后重启...`);
+      await new Promise<void>(resolve => {
+        const timer = setTimeout(resolve, retryDelay);
+        // 等待期间如果收到停止信号，立即退出
+        const check = setInterval(() => {
+          if (shuttingDown) {
+            clearTimeout(timer);
+            clearInterval(check);
+            resolve();
+          }
+        }, 100);
+      });
+      if (shuttingDown) break;
+    }
+
+    const logStream = fs.createWriteStream(logFile, { flags: 'a' });
+
+    const child = Bun.spawn(['bun', 'run', indexFile], {
+      cwd: dataDir,
+      env: { ...process.env, IMTOAGENT_HOME: dataDir },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    const childPid = child.pid;
+    fs.writeFileSync(PID_FILE, String(childPid));
+    console.log(`[${new Date().toISOString()}] 🚀 启动网关 (PID=${childPid})`);
+
+    // 日志收集
+    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(() => {});
+
+    // 等待子进程退出
+    const exitCode = await child.exited;
+    await Promise.allSettled([pumpStdout, pumpStderr]);
+    logStream.end();
+
+    try { fs.unlinkSync(PID_FILE); } catch {}
+
+    if (shuttingDown) break;
+
+    // 判断是否需要重启
+    if (exitCode === 0) {
+      console.log(`[${new Date().toISOString()}] ⏹  网关正常退出 (code=0)，不重启`);
+      break;
+    }
+
+    // 崩溃 → 指数退避重启
+    retryDelay = retryDelay === 0 ? 3_000 : Math.min(retryDelay * 2, MAX_RETRY_DELAY);
+    console.log(`[${new Date().toISOString()}] ⚠️  网关异常退出 (code=${exitCode})，${retryDelay / 1000}s 后重启`);
+  }
+
+  console.log('👋 守护进程已停止');
+}
+