imtoagent 0.2.0

package/modules/rate-limiter.ts

@@ -0,0 +1,58 @@
+// 滑动窗口请求限流器
+// per-chatId 滑动窗口，防止短时间内发送过多消息
+
+interface WindowEntry {
+  timestamps: number[];
+}
+
+interface RateLimitConfig {
+  maxRequests: number;
+  windowMs: number;
+}
+
+const windows = new Map<string, WindowEntry>();
+
+const DEFAULT_CONFIG: RateLimitConfig = {
+  maxRequests: 30,
+  windowMs: 60_000,
+};
+
+let currentConfig: RateLimitConfig = { ...DEFAULT_CONFIG };
+
+export function setRateLimitConfig(cfg: RateLimitConfig) {
+  currentConfig = cfg;
+}
+
+export function checkRateLimit(chatId: string): { allowed: boolean; retryAfter?: number; remaining?: number } {
+  const now = Date.now();
+  let entry = windows.get(chatId);
+
+  if (!entry) {
+    entry = { timestamps: [] };
+    windows.set(chatId, entry);
+  }
+
+  // 清理窗口外的时间戳
+  entry.timestamps = entry.timestamps.filter(ts => now - ts < currentConfig.windowMs);
+
+  if (entry.timestamps.length >= currentConfig.maxRequests) {
+    const oldestInWindow = entry.timestamps[0];
+    const retryAfter = Math.ceil((oldestInWindow + currentConfig.windowMs - now) / 1000);
+    return { allowed: false, retryAfter, remaining: 0 };
+  }
+
+  entry.timestamps.push(now);
+
+  // 定期清理过期条目（低概率触发，不影响性能）
+  if (Math.random() < 0.01) {
+    for (const [id, e] of windows.entries()) {
+      e.timestamps = e.timestamps.filter(ts => now - ts < currentConfig.windowMs);
+      if (e.timestamps.length === 0) windows.delete(id);
+    }
+  }
+
+  return {
+    allowed: true,
+    remaining: currentConfig.maxRequests - entry.timestamps.length,
+  };
+}

package/modules/types.ts

@@ -0,0 +1,144 @@
+// IMtoAgent 模块接口定义
+// Agent 模块和 IM 模块之间的标准合同
+
+// ================================================================
+// Session 数据结构
+// ================================================================
+
+/** 调用统计 */
+export interface CallStats {
+  calls: number;
+  totalTurns: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCostUSD: number;
+  totalDurationMs: number;
+}
+
+/** 会话数据（替代 any） */
+export interface SessionData {
+  userId: string;
+  sdkSessionId?: string;
+  codexThreadId?: string;
+  ocSessionId?: string;
+  cwd?: string;
+  permissionMode?: 'bypassPermissions' | 'default';
+  codexMode?: string;
+  startFresh?: boolean;
+  stats: CallStats;
+  recentMessages: string[];
+  lastUsed: number;
+}
+
+// ================================================================
+// Agent 模块接口
+// ================================================================
+
+/** Bot 提供给 Agent 模块的上下文 */
+export interface AgentContext {
+  readonly name: string;
+  readonly backend: 'claude' | 'codex' | 'opencode';
+  readonly activeModel: string;
+  readonly modelAliases: Record<string, string>;
+  readonly defaultCwd: string;
+  /** IM 模块实例 */
+  readonly imModule?: IMModule;
+
+  // 发送回复给 IM
+  reply(chatId: string, text: string): Promise<void>;
+
+  // 推送进度消息
+  sendProgress(chatId: string, text: string): Promise<void>;
+
+  // 工具日志
+  addToolLog(chatId: string, info: { name: string; summary: string }): void;
+  flushToolLog(chatId: string): Promise<void>;
+
+  // 格式化发送（parseToBlocks → sendBlocks/reply 统一入口）
+  sendFormattedReply(chatId: string, response: string): Promise<void>;
+
+  // 统计累加（统一 token/cost 统计）
+  accumulateStats(session: SessionData, usage: { inputTokens: number; outputTokens: number; costUSD?: number; durationMs?: number; numTurns?: number }): void;
+
+  // 会话持久化
+  persistSession(chatId: string, session: SessionData): void;
+  loadSession(chatId: string): SessionData | null;
+  deleteSession(chatId: string): void;
+
+  // 模型配置持久化
+  saveModelConfig(config: { activeModel: string; modelAliases: Record<string, string> }): void;
+  loadModelConfig(): { activeModel: string; modelAliases: Record<string, string> };
+}
+
+/** Agent 模块必须实现的接口 */
+export interface AgentModule {
+  /** 收到用户消息，处理并回复 */
+  handleMessage(chatId: string, text: string, session: SessionData): Promise<void>;
+}
+
+// ================================================================
+// IM 模块接口
+// ================================================================
+
+/** IM 模块提供给 Bot 的消息回调 */
+export type MessageHandler = (chatId: string, text: string, userId: string, attachments?: import('./core/types').MessageAttachment[]) => Promise<void>;
+
+/** IM 模块声明的输出能力 */
+export interface IMCapabilities {
+  text: boolean;
+  codeBlock: boolean;
+  cardMessage: boolean;
+  fileSend: boolean;
+  imageSend: boolean;
+  audioSend: boolean;
+  buttonAction: boolean;
+  maxTextLength: number;
+}
+
+/** Agent 可调用的输出工具定义 */
+export interface OutputToolDef {
+  name: string;
+  description: string;
+  parameters: Record<string, { type: string; description: string; required?: boolean }>;
+}
+
+/** IM 模块必须实现的接口 */
+export interface IMModule {
+  /** 发送文本回复 */
+  reply(chatId: string, text: string, maxLen?: number): Promise<void>;
+
+  /** 推送进度/工具日志 */
+  sendProgress(chatId: string, text: string): Promise<void>;
+
+  /** 获取 IM 输出能力 */
+  getCapabilities(): IMCapabilities;
+
+  /** 发送富文本块（代码块、卡片、图片等） */
+  sendBlocks(chatId: string, blocks: any[]): Promise<void>;
+
+  /** 发送图片 */
+  sendImage(chatId: string, imageKey: string, alt?: string): Promise<void>;
+
+  /** 发送文件 */
+  sendFile(chatId: string, fileKey: string, fileName: string): Promise<void>;
+
+  /** 启动消息监听 */
+  start(handler: MessageHandler): void;
+
+  /** 停止 */
+  stop(): void;
+}
+
+// ================================================================
+// Bot 配置
+// ================================================================
+
+export interface BotConfig {
+  name: string;
+  backend: 'claude' | 'codex' | 'opencode';
+  appId: string;
+  appSecret: string;
+  cwd?: string;
+  /** IM 平台类型（默认 feishu） */
+  im?: 'feishu' | 'telegram' | 'wecom' | 'wechat';
+}

package/modules/utils/backend-check.ts

@@ -0,0 +1,121 @@
+// ================================================================
+// backend-check.ts — 检测后端 Agent 是否已安装
+// ================================================================
+
+import { execSync } from 'child_process';
+
+export interface BackendInfo {
+  type: 'claude' | 'codex' | 'opencode';
+  label: string;
+  installed: boolean;
+  version: string | null;
+  installHint: string;
+}
+
+const BACKEND_DEFS: Omit<BackendInfo, 'installed' | 'version'>[] = [
+  { type: 'claude', label: 'Claude Code', installHint: 'npm install -g @anthropic-ai/claude-agent-sdk' },
+  { type: 'codex',  label: 'Codex',       installHint: 'npm install -g @openai/codex' },
+  { type: 'opencode', label: 'OpenCode',   installHint: 'npm install -g opencode' },
+];
+
+function checkOne(b: Omit<BackendInfo, 'installed' | 'version'>): BackendInfo {
+  try {
+    let version: string | null = null;
+    if (b.type === 'claude') {
+      version = execSync('claude --version', { encoding: 'utf-8', timeout: 5000 }).trim();
+    } else if (b.type === 'codex') {
+      version = execSync('codex --version', { encoding: 'utf-8', timeout: 5000 }).trim();
+    } else {
+      version = execSync('opencode version', { encoding: 'utf-8', timeout: 5000 }).trim();
+    }
+    return { ...b, installed: true, version };
+  } catch {
+    return { ...b, installed: false, version: null };
+  }
+}
+
+export function checkAllBackends(): BackendInfo[] {
+  return BACKEND_DEFS.map(checkOne);
+}
+
+export function checkBackend(type: 'claude' | 'codex' | 'opencode'): BackendInfo {
+  const b = BACKEND_DEFS.find(x => x.type === type);
+  if (!b) return { type, label: type, installed: false, version: null, installHint: '' };
+  return checkOne(b);
+}
+
+export function formatBackendStatus(backends: BackendInfo[]): string {
+  return backends.map(b => {
+    const icon = b.installed ? '✅' : '❌';
+    const ver = b.version ? ` v${b.version}` : '';
+    const hint = b.installed ? '' : ` → ${b.installHint}`;
+    return `  ${icon} ${b.label}${ver}${hint}`;
+  }).join('\n');
+}
+
+// ================================================================
+// 自动安装后端 CLI
+// ================================================================
+
+/**
+ * 自动安装缺失的后端 CLI
+ * 使用 Bun.spawn 流式输出 npm install -g 的进度
+ */
+export async function installBackend(
+  type: 'claude' | 'codex' | 'opencode',
+): Promise<boolean> {
+  const b = BACKEND_DEFS.find((x) => x.type === type);
+  if (!b) {
+    console.error(`❌ 未知后端类型: ${type}`);
+    return false;
+  }
+
+  console.log(`\n📦 正在安装 ${b.label}...`);
+  console.log(`   命令: ${b.installHint}\n`);
+
+  try {
+    const child = Bun.spawn(b.installHint.split(' '), {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      stdin: 'inherit',
+    });
+
+    const decoder = new TextDecoder();
+
+    // 实时输出 stdout
+    const stdoutReader = child.stdout.getReader();
+    while (true) {
+      const { done, value } = await stdoutReader.read();
+      if (done) break;
+      process.stdout.write(decoder.decode(value, { stream: true }));
+    }
+
+    // 实时输出 stderr
+    const stderrReader = child.stderr.getReader();
+    while (true) {
+      const { done, value } = await stderrReader.read();
+      if (done) break;
+      process.stderr.write(decoder.decode(value, { stream: true }));
+    }
+
+    const exitCode = await child.exited;
+
+    if (exitCode !== 0) {
+      console.error(`\n❌ ${b.label} 安装失败 (退出码: ${exitCode})`);
+      return false;
+    }
+
+    // 安装完成后验证
+    const info = checkOne(b);
+    if (info.installed) {
+      console.log(`\n✅ ${b.label} 安装成功! 版本: ${info.version}`);
+      return true;
+    } else {
+      console.error(`\n❌ ${b.label} 安装后仍未检测到，请手动运行: ${b.installHint}`);
+      return false;
+    }
+  } catch (e: any) {
+    console.error(`\n❌ 安装 ${b.label} 时出错: ${e.message || e}`);
+    return false;
+  }
+}

package/modules/utils/paths.ts

@@ -0,0 +1,218 @@
+// ================================================================
+// 路径解析模块 — 首次部署自动初始化的核心地基
+// ================================================================
+// 职责：
+//   1. 统一解析数据目录（~/.imtoagent/ 或开发时的 cwd）
+//   2. 统一解析 npm 包安装目录（读取模板用）
+//   3. 兼容旧开发模式（bun run index.ts 在旧项目目录）
+//   4. 首次部署自动初始化数据目录 + 配置文件
+// ================================================================
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// ===== 缓存 =====
+let _dataDir: string | null = null;
+let _pkgDir: string | null = null;
+
+// ===== 数据目录解析 =====
+/**
+ * 返回 imtoagent 的用户数据目录（读写）。
+ *
+ * 优先级：
+ *   1. IMTOAGENT_HOME 环境变量 → 如果有 config.json 则直接用
+ *   2. ~/.imtoagent/ 存在且有 config.json → 用
+ *   3. cwd 有 config.json → 开发模式（从 cwd 初始化 ~/.imtoagent）
+ *   4. 从包目录模板初始化 ~/.imtoagent（npm 全局安装首次运行）
+ *   5. 包目录 fallback（极端情况）
+ *
+ * 关键改进：IMTOAGENT_HOME 不再是"强制覆盖"——如果目录为空，
+ * 会继续尝试从其他来源找到配置文件，并自动初始化。
+ */
+export function getDataDir(): string {
+  if (_dataDir) return _dataDir;
+
+  const home = process.env.HOME || process.env.USERPROFILE?.replace(/\\/g, '/') || '';
+  const dotDir = path.join(home, '.imtoagent');
+  const envHome = process.env.IMTOAGENT_HOME || '';
+
+  // ====== 第 1 步：查找已有的配置文件 ======
+  const candidates: { dir: string; label: string }[] = [];
+
+  // IMTOAGENT_HOME（优先检查，但不强制）
+  if (envHome && fs.existsSync(path.join(envHome, 'config.json'))) {
+    candidates.push({ dir: envHome, label: 'IMTOAGENT_HOME' });
+  }
+
+  // ~/.imtoagent/
+  if (fs.existsSync(path.join(dotDir, 'config.json'))) {
+    candidates.push({ dir: dotDir, label: '~/.imtoagent' });
+  }
+
+  // cwd（开发模式）
+  const cwd = process.cwd();
+  if (fs.existsSync(path.join(cwd, 'config.json'))) {
+    candidates.push({ dir: cwd, label: 'cwd 开发模式' });
+  }
+
+  if (candidates.length > 0) {
+    // 有现成配置，直接用最优先的那个
+    const chosen = candidates[0];
+    _dataDir = chosen.dir;
+    console.log(`[Paths] 数据目录: ${_dataDir} (${chosen.label})`);
+    return _dataDir;
+  }
+
+  // ====== 第 2 步：没有配置文件 → 自动初始化 ======
+  _dataDir = initDataDir(dotDir, envHome);
+  return _dataDir;
+}
+
+/**
+ * 首次部署：自动创建 ~/.imtoagent/ 并初始化配置文件。
+ *
+ * 配置文件来源（按优先级）：
+ *   1. IMTOAGENT_HOME 下的 config.json（目录存在但没文件）
+ *   2. cwd 下的 config.json / providers.json（手动部署/git clone）
+ *   3. 包安装目录的 templates/（npm 全局安装）
+ */
+function initDataDir(dotDir: string, envHome: string): string {
+  const target = dotDir; // 统一使用 ~/.imtoagent/
+
+  // 确定配置文件来源
+  let sourceDir: string | null = null;
+  let sourceLabel = '';
+
+  if (envHome && fs.existsSync(path.join(envHome, 'config.json'))) {
+    sourceDir = envHome;
+    sourceLabel = 'IMTOAGENT_HOME';
+  } else if (fs.existsSync(path.join(process.cwd(), 'config.json'))) {
+    sourceDir = process.cwd();
+    sourceLabel = 'cwd';
+  } else {
+    const pkgDir = getPkgDir();
+    if (fs.existsSync(path.join(pkgDir, 'templates', 'config.template.json'))) {
+      sourceDir = path.join(pkgDir, 'templates');
+      sourceLabel = '包模板';
+    }
+  }
+
+  // 创建目录结构
+  fs.mkdirSync(target, { recursive: true });
+  fs.mkdirSync(path.join(target, 'logs'), { recursive: true });
+  fs.mkdirSync(path.join(target, 'sessions'), { recursive: true });
+
+  if (sourceDir && sourceLabel === 'cwd') {
+    // 开发模式：直接拷贝项目目录下的配置
+    copyIfExists(sourceDir, target, 'config.json');
+    copyIfExists(sourceDir, target, 'providers.json');
+    copyIfExists(sourceDir, target, 'opencode.json');
+  } else if (sourceDir && sourceLabel === '包模板') {
+    // npm 安装：从模板拷贝（去掉 .template 后缀）
+    copyTemplateIfExists(sourceDir, target, 'config.template.json', 'config.json');
+    copyTemplateIfExists(sourceDir, target, 'providers.template.json', 'providers.json');
+    copyTemplateIfExists(sourceDir, target, 'opencode.template.json', 'opencode.json');
+    // 拷贝 soul 模板
+    const soulSrc = path.join(sourceDir, 'soul.template');
+    if (fs.existsSync(soulSrc)) {
+      copyDirSync(soulSrc, path.join(target, 'soul'));
+    }
+  }
+
+  console.log(`[Paths] ✨ 首次初始化数据目录: ${target} (来源: ${sourceLabel || '默认模板'})`);
+  console.log(`[Paths] 请编辑 ${path.join(target, 'config.json')} 配置你的凭证`);
+
+  return target;
+}
+
+function copyIfExists(src: string, dst: string, filename: string) {
+  const srcPath = path.join(src, filename);
+  const dstPath = path.join(dst, filename);
+  if (fs.existsSync(srcPath) && !fs.existsSync(dstPath)) {
+    fs.copyFileSync(srcPath, dstPath);
+  }
+}
+
+function copyTemplateIfExists(src: string, dst: string, templateName: string, outName: string) {
+  const srcPath = path.join(src, templateName);
+  const dstPath = path.join(dst, outName);
+  if (fs.existsSync(srcPath) && !fs.existsSync(dstPath)) {
+    fs.copyFileSync(srcPath, dstPath);
+  }
+}
+
+function copyDirSync(src: string, dst: string) {
+  if (!fs.existsSync(dst)) fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src)) {
+    const srcPath = path.join(src, entry);
+    const dstPath = path.join(dst, entry);
+    if (fs.statSync(srcPath).isDirectory()) {
+      copyDirSync(srcPath, dstPath);
+    } else {
+      fs.copyFileSync(srcPath, dstPath);
+    }
+  }
+}
+
+/**
+ * 返回 npm 包安装目录（只读，模板读取用）。
+ *
+ * import.meta.dirname 在 Bun/Node ESM 中返回当前文件所在目录。
+ * 对于全局安装的包，这就是 /usr/local/lib/node_modules/imtoagent/。
+ */
+export function getPkgDir(): string {
+  if (_pkgDir) return _pkgDir;
+
+  // import.meta.dirname 是当前文件（paths.ts）所在目录 → modules/utils/
+  // 向上两级就是包根目录
+  _pkgDir = path.resolve(import.meta.dirname, '../..');
+  return _pkgDir;
+}
+
+// ===== 便捷路径函数 =====
+
+export function getConfigPath(): string {
+  return path.join(getDataDir(), 'config.json');
+}
+
+export function getProvidersPath(): string {
+  return path.join(getDataDir(), 'providers.json');
+}
+
+export function getOpencodeConfigPath(): string {
+  return path.join(getDataDir(), 'opencode.json');
+}
+
+export function getSessionsDir(): string {
+  return path.join(getDataDir(), 'sessions');
+}
+
+export function getLogsDir(): string {
+  return path.join(getDataDir(), 'logs');
+}
+
+export function getSoulDir(botName: string): string {
+  return path.join(getDataDir(), 'soul', botName);
+}
+
+export function getRestoreMarkerPath(): string {
+  return path.join(getSessionsDir(), '.restore');
+}
+
+export function getTemplatePath(relativePath: string): string {
+  const tplPath = path.join(getPkgDir(), 'templates', relativePath);
+  if (!fs.existsSync(tplPath)) console.warn(`⚠️  模板不存在: ${tplPath}`);
+  return tplPath;
+}
+
+export function getTemplateSoulPath(filename: string): string {
+  const tplPath = path.join(getPkgDir(), 'templates', 'soul.template', filename);
+  if (!fs.existsSync(tplPath)) console.warn(`⚠️  灵魂模板不存在: ${tplPath}`);
+  return tplPath;
+}
+
+// ===== 重置缓存（测试用） =====
+export function resetPathCache(): void {
+  _dataDir = null;
+  _pkgDir = null;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "imtoagent",
+  "version": "0.2.0",
+  "description": "IM ↔ Agent 统一网关 — 飞书/Telegram/微信/企业微信对接 Claude Code/Codex/OpenCode",
+  "type": "module",
+  "bin": {
+    "imtoagent": "./bin/imtoagent"
+  },
+  "files": [
+    "index.ts",
+    "modules/",
+    "bin/",
+    "templates/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "bun run scripts/postinstall.ts",
+    "start": "bun run index.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.119",
+    "@larksuiteoapi/node-sdk": "^1.62.0",
+    "@wecom/aibot-node-sdk": "^1.0.7",
+    "qrcode": "^1.5.4"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_USERNAME/imtoagent.git"
+  },
+  "keywords": [
+    "im",
+    "gateway",
+    "claude-code",
+    "codex",
+    "opencode",
+    "feishu",
+    "telegram",
+    "wechat",
+    "wecom",
+    "ai-agent",
+    "bot-framework"
+  ],
+  "author": "Keyi",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/YOUR_USERNAME/imtoagent/issues"
+  },
+  "homepage": "https://github.com/YOUR_USERNAME/imtoagent#readme"
+}

package/scripts/postinstall.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+// ================================================================
+// postinstall.ts — npm 安装后引导脚本
+// ================================================================
+// package.json 中 "scripts": { "postinstall": "bun run scripts/postinstall.ts" }
+// 安装后自动运行，检测是否需要初始化配置
+// 如果是全新安装且终端交互，自动引导进入 setup
+// ================================================================
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+const HOME = process.env.HOME || process.env.USERPROFILE || '';
+const DATA_DIR = path.join(HOME, '.imtoagent');
+
+try {
+  const configExists = fs.existsSync(path.join(DATA_DIR, 'config.json'));
+
+  if (configExists) {
+    console.log(`
+✅ imtoagent 升级成功！
+   数据目录: ${DATA_DIR}
+   配置文件保持不变，无需重新配置。
+   运行 "imtoagent start" 启动网关。
+`);
+  } else {
+    console.log(`
+╔══════════════════════════════════════════════════════════╗
+║                                                          ║
+║   🎉  imtoagent 安装成功！                               ║
+║                                                          ║
+║   首次使用需要配置 IM 凭证和模型供应商                    ║
+║                                                          ║
+╚══════════════════════════════════════════════════════════╝
+`);
+
+    // 检测是否为交互式终端，是则自动引导进入 setup
+    if (process.stdin.isTTY) {
+      const readline = await import('readline');
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise<string>(resolve => {
+        rl.question('是否立即运行配置向导？[Y/n]: ', resolve);
+      });
+      rl.close();
+
+      const yes = answer.trim().toLowerCase();
+      if (yes === '' || yes === 'y' || yes === 'yes') {
+        console.log('\n🚀 启动配置向导...\n');
+        // 调用 setup 向导
+        const pkgDir = path.resolve(import.meta.dirname, '..');
+        execSync('bun run bin/imtoagent setup', {
+          cwd: pkgDir,
+          stdio: 'inherit',
+          env: { ...process.env },
+        });
+      } else {
+        console.log('\n稍后运行 "imtoagent setup" 即可开始配置。');
+      }
+    } else {
+      console.log('   运行 "imtoagent setup" 开始配置');
+      console.log('   然后运行 "imtoagent start" 启动网关\n');
+    }
+  }
+} catch (e: any) {
+  // 静默失败，不影响安装
+  if (e.message && !e.message.includes('readline')) {
+    console.error(`[postinstall] 提示失败: ${e.message}`);
+  }
+}