imtoagent 0.2.0

package/modules/media/feishu-inbound-adapter.ts

@@ -0,0 +1,108 @@
+// ================================================================
+// FeishuInboundAdapter — 飞书平台媒体下载适配器
+// ================================================================
+// 实现 InboundMediaAdapter 接口，负责从飞书 API 下载消息附件 buffer
+// 不负责：存储、MIME sniff、扩展名处理（由 MediaStore 处理）
+// ================================================================
+
+import type { InboundMediaAdapter, DownloadedMedia, MediaResourceType } from '../media/types';
+import * as Lark from '@larksuiteoapi/node-sdk';
+
+export interface FeishuInboundAdapterOptions {
+  appId: string;
+  appSecret: string;
+}
+
+export class FeishuInboundAdapter implements InboundMediaAdapter {
+  readonly platform = 'feishu';
+  private appId: string;
+  private appSecret: string;
+  private client: Lark.Client;
+  private _appToken: string | null = null;
+  private _appTokenExpiresAt = 0;  // 飞书 tenant_token 约 2 小时有效，提前 5 分钟刷新
+
+  constructor(options: FeishuInboundAdapterOptions) {
+    this.appId = options.appId;
+    this.appSecret = options.appSecret;
+    this.client = new Lark.Client({ appId: options.appId, appSecret: options.appSecret });
+  }
+
+  async downloadResource(
+    messageId: string,
+    resourceKey: string,
+    type: MediaResourceType,
+    fileName?: string
+  ): Promise<DownloadedMedia | null> {
+    try {
+      const token = await this.getAppToken();
+      const url = `https://open.feishu.cn/open-apis/im/v1/messages/${messageId}/resources/${resourceKey}?type=${type}`;
+
+      const resp = await fetch(url, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+
+      if (!resp.ok) {
+        // 容错：文件类型 502 时尝试用 media 类型重试
+        if (resp.status === 502 && type === 'file') {
+          console.log(`[FeishuInbound] file 类型返回 502，尝试 media 类型重试`);
+          const retryUrl = `https://open.feishu.cn/open-apis/im/v1/messages/${messageId}/resources/${resourceKey}?type=media`;
+          const retryResp = await fetch(retryUrl, {
+            headers: { Authorization: `Bearer ${token}` },
+          });
+          if (retryResp.ok) {
+            const retryBuffer = Buffer.from(await retryResp.arrayBuffer());
+            const retryContentType = retryResp.headers.get('content-type')?.split(';')[0].trim().toLowerCase() || undefined;
+            return {
+              buffer: retryBuffer,
+              fileName,
+              contentType: retryContentType,
+              sourceKey: resourceKey,
+            };
+          }
+        }
+        console.error(`[FeishuInbound] 下载消息资源失败: HTTP ${resp.status} (key=${resourceKey})`);
+        return null;
+      }
+
+      const buffer = Buffer.from(await resp.arrayBuffer());
+      const contentType = resp.headers.get('content-type')?.split(';')[0].trim().toLowerCase() || undefined;
+
+      return {
+        buffer,
+        fileName,
+        contentType,
+        sourceKey: resourceKey,
+      };
+    } catch (e: any) {
+      console.error(`[FeishuInbound] 下载消息资源异常: ${e.message}`);
+      return null;
+    }
+  }
+
+  private async getAppToken(): Promise<string> {
+    const now = Date.now();
+    // 提前 5 分钟刷新，避免刚好过期
+    if (this._appToken && this._appTokenExpiresAt > now + 5 * 60 * 1000) {
+      return this._appToken;
+    }
+
+    const resp = await fetch('https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        app_id: this.appId,
+        app_secret: this.appSecret,
+      }),
+    });
+
+    const data = await resp.json();
+    if (data.code !== 0 || !data.tenant_access_token) {
+      throw new Error(`获取飞书 tenant_access_token 失败: ${JSON.stringify(data)}`);
+    }
+
+    this._appToken = data.tenant_access_token;
+    // 飞书 tenant_token 有效期约 2 小时
+    this._appTokenExpiresAt = now + 2 * 60 * 60 * 1000;
+    return this._appToken;
+  }
+}

package/modules/media/index.ts

@@ -0,0 +1,27 @@
+// ================================================================
+// modules/media — Inbound Media 适配器 + 抽象层
+// ================================================================
+// 架构概览：
+//
+//   ┌──────────────────────────────────────────────┐
+//   │        InboundMediaResolver (编排层)          │
+//   │  下载 → 存储 → 分类 → 生成 Agent 提示         │
+//   └──────┬───────────────────────┬────────────────┘
+//          │                       │
+//          ▼                       ▼
+//   ┌──────────────┐      ┌──────────────┐
+//   │InboundMedia  │      │  MediaStore  │
+//   │Adapter (接口)│      │  (存储层)     │
+//   └──────┬───────┘      └──────────────┘
+//          │
+//   ┌──────▼───────┐
+//   │FeishuInbound │     (未来: TelegramInboundAdapter, ...)
+//   │Adapter       │
+//   └──────────────┘
+// ================================================================
+
+export * from './types';
+export { MediaStore, sniffMimeFromBuffer, mimeFromFileName, extensionForMime, categorizeMedia } from './media-store';
+export { InboundMediaResolver } from './resolver';
+export { FeishuInboundAdapter } from './feishu-inbound-adapter';
+export { TelegramInboundAdapter } from './telegram-inbound-adapter';

package/modules/media/media-store.ts

@@ -0,0 +1,273 @@
+// ================================================================
+// MediaStore — 统一媒体存储抽象层
+// ================================================================
+// 职责：
+//   1. 保存 buffer 到本地，带正确扩展名
+//   2. MIME sniff（优先用 buffer 内容判断，其次用文件名推断）
+//   3. 媒体分类（image / document / audio / ...）
+//   4. 生命周期管理（清理过期文件）
+//
+// 参考 OpenClaw 的 parseMessageWithAttachments + saveMediaBuffer 设计
+// ================================================================
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import type { MediaEntry, MediaCategory } from './types';
+import { getDataDir } from '../utils/paths';
+
+// ================================================================
+// MIME 推断
+// ================================================================
+
+/** 通过 buffer 头部字节 sniff MIME 类型 */
+export function sniffMimeFromBuffer(buffer: Buffer): string | null {
+  if (buffer.length < 4) return null;
+
+  const header = buffer.toString('hex', 0, 16);
+
+  // PNG
+  if (header.startsWith('89504e47')) return 'image/png';
+  // JPEG
+  if (header.startsWith('ffd8ff')) return 'image/jpeg';
+  // GIF
+  if (header.startsWith('47494638')) return 'image/gif';
+  // WebP
+  if (header.startsWith('52494646') && buffer.toString('ascii', 8, 12) === 'WEBP') return 'image/webp';
+  // PDF
+  if (header.startsWith('25504446')) return 'application/pdf';
+  // ZIP / XLSX / DOCX / PPTX (PK)
+  if (header.startsWith('504b0304') || header.startsWith('504b0506')) {
+    // 需要进一步判断，先返回通用 ZIP
+    return 'application/zip';
+  }
+  // MP3
+  if (header.startsWith('494433') || header.startsWith('fff3') || header.startsWith('fff2')) return 'audio/mpeg';
+  // WAV
+  if (header.startsWith('52494646') && buffer.toString('ascii', 8, 12) === 'WAVE') return 'audio/wav';
+  // OGG
+  if (header.startsWith('4f676753')) return 'audio/ogg';
+  // MP4
+  if (header.startsWith('000000') && buffer.toString('ascii', 4, 8).includes('ftyp')) return 'video/mp4';
+
+  return null;
+}
+
+/** 从文件名推断 MIME 类型 */
+export function mimeFromFileName(fileName: string): string | null {
+  const ext = path.extname(fileName).toLowerCase();
+  const mimeMap: Record<string, string> = {
+    // 图片
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp', '.bmp': 'image/bmp', '.svg': 'image/svg+xml',
+    // 文档
+    '.pdf': 'application/pdf', '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv',
+    // 表格
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    // 演示文稿
+    '.ppt': 'application/vnd.ms-powerpoint',
+    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    // 音频
+    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg', '.m4a': 'audio/mp4', '.aac': 'audio/aac',
+    // 视频
+    '.mp4': 'video/mp4', '.avi': 'video/x-msvideo', '.mov': 'video/quicktime', '.webm': 'video/webm',
+    // 压缩包
+    '.zip': 'application/zip', '.rar': 'application/x-rar-compressed',
+    '.tar': 'application/x-tar', '.gz': 'application/gzip', '.7z': 'application/x-7z-compressed',
+    // 代码
+    '.js': 'application/javascript', '.ts': 'text/typescript', '.py': 'text/x-python',
+    '.json': 'application/json', '.xml': 'application/xml', '.yaml': 'text/yaml', '.yml': 'text/yaml',
+  };
+  return mimeMap[ext] || null;
+}
+
+/** 从 MIME 类型推断扩展名 */
+export function extensionForMime(mime: string): string {
+  const extMap: Record<string, string> = {
+    'image/png': '.png', 'image/jpeg': '.jpg', 'image/gif': '.gif',
+    'image/webp': '.webp', 'image/bmp': '.bmp',
+    'application/pdf': '.pdf',
+    'application/msword': '.doc',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+    'text/plain': '.txt', 'text/markdown': '.md', 'text/csv': '.csv',
+    'application/vnd.ms-excel': '.xls',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+    'application/vnd.ms-powerpoint': '.ppt',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',
+    'audio/mpeg': '.mp3', 'audio/wav': '.wav', 'audio/ogg': '.ogg',
+    'video/mp4': '.mp4', 'video/x-msvideo': '.avi',
+    'application/zip': '.zip', 'application/gzip': '.gz',
+    'application/json': '.json', 'application/xml': '.xml',
+  };
+  return extMap[mime] || '';
+}
+
+// ================================================================
+// 媒体分类
+// ================================================================
+
+/** 根据 MIME 类型 + 文件名判断媒体分类 */
+export function categorizeMedia(mimeType: string, fileName?: string): MediaCategory {
+  // 图片
+  if (mimeType.startsWith('image/')) return 'image';
+  // 音频
+  if (mimeType.startsWith('audio/')) return 'audio';
+  // 视频
+  if (mimeType.startsWith('video/')) return 'video';
+
+  const ext = fileName ? path.extname(fileName).toLowerCase() : '';
+
+  // 压缩包
+  if (['.zip', '.rar', '.tar', '.gz', '.7z', '.bz2', '.xz'].includes(ext)) return 'archive';
+  // 表格
+  if (['.xls', '.xlsx', '.csv', '.tsv', '.ods'].includes(ext)) return 'spreadsheet';
+  // 演示文稿
+  if (['.ppt', '.pptx', '.odp', '.key'].includes(ext)) return 'presentation';
+  // 文档
+  if (['.pdf', '.doc', '.docx', '.odt', '.rtf', '.txt', '.md'].includes(ext)) return 'document';
+  // 纯文本
+  if (mimeType.startsWith('text/') || mimeType === 'application/json' || mimeType === 'application/xml') {
+    return 'text';
+  }
+
+  return 'other';
+}
+
+// ================================================================
+// MediaStore
+// ================================================================
+
+export interface MediaStoreOptions {
+  /** 存储根目录（默认使用数据目录下的 media/inbound） */
+  rootDir?: string;
+  /** 单文件最大字节数（默认 20MB） */
+  maxBytes?: number;
+}
+
+export class MediaStore {
+  private readonly rootDir: string;
+  private readonly maxBytes: number;
+
+  constructor(options?: MediaStoreOptions) {
+    this.maxBytes = options?.maxBytes ?? 20 * 1024 * 1024;
+
+    if (options?.rootDir) {
+      this.rootDir = options.rootDir;
+    } else {
+      // 默认: ~/.imtoagent/media/inbound/
+      this.rootDir = path.join(getDataDir(), 'media', 'inbound');
+    }
+
+    fs.mkdirSync(this.rootDir, { recursive: true });
+  }
+
+  /**
+   * 保存 buffer 到本地存储
+   *
+   * 策略（参考 OpenClaw）：
+   *   1. sniff buffer 获取真实 MIME
+   *   2. 如果 sniff 失败，用 fileName 推断
+   *   3. 如果 MIME 是通用容器（octet-stream），用 fileName 覆盖
+   *   4. 文件名保留原始扩展名，前缀加时间戳防冲突
+   */
+  save(
+    buffer: Buffer,
+    mimeType: string | undefined,
+    originalFileName?: string,
+    source?: string
+  ): MediaEntry {
+    // 大小检查
+    if (buffer.length > this.maxBytes) {
+      throw new Error(`Media exceeds size limit: ${buffer.length} > ${this.maxBytes} bytes`);
+    }
+
+    // MIME 推断优先级: sniff > provided > fileName-derived
+    const sniffedMime = sniffMimeFromBuffer(buffer);
+    const fileNameMime = originalFileName ? mimeFromFileName(originalFileName) : null;
+
+    // 通用容器 MIME 不够具体，优先用 sniff 或文件名推断
+    const isGeneric = (mime?: string) => !mime || mime === 'application/octet-stream';
+
+    let finalMime = sniffedMime || mimeType || fileNameMime || 'application/octet-stream';
+
+    // 如果 sniff 到了具体类型，优先使用
+    if (sniffedMime && !isGeneric(sniffedMime)) {
+      finalMime = sniffedMime;
+    } else if (isGeneric(mimeType) && fileNameMime) {
+      finalMime = fileNameMime;
+    }
+
+    // 构造文件名（保留原始扩展名）
+    const localFileName = this.buildFileName(originalFileName, finalMime);
+
+    // 写入磁盘
+    const localPath = path.join(this.rootDir, localFileName);
+    fs.writeFileSync(localPath, buffer);
+
+    const category = categorizeMedia(finalMime, originalFileName);
+
+    return {
+      localPath,
+      mimeType: finalMime,
+      fileName: originalFileName || localFileName,
+      category,
+      sizeBytes: buffer.length,
+      source,
+    };
+  }
+
+  /** 清理过期文件（超过 maxAge 毫秒的文件） */
+  cleanup(maxAgeMs: number = 24 * 60 * 60 * 1000): number {
+    const cutoff = Date.now() - maxAgeMs;
+    let count = 0;
+
+    const files = fs.readdirSync(this.rootDir);
+    for (const file of files) {
+      const filePath = path.join(this.rootDir, file);
+      try {
+        const stat = fs.statSync(filePath);
+        if (stat.mtimeMs < cutoff) {
+          fs.unlinkSync(filePath);
+          count++;
+        }
+      } catch {
+        // 忽略删除失败
+      }
+    }
+
+    if (count > 0) {
+      console.log(`[MediaStore] Cleaned up ${count} expired files`);
+    }
+    return count;
+  }
+
+  /** 获取存储根目录 */
+  getRootDir(): string {
+    return this.rootDir;
+  }
+
+  // ================================================================
+  // Private
+  // ================================================================
+
+  private buildFileName(originalFileName?: string, mimeType?: string): string {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).slice(2, 10);
+
+    if (originalFileName) {
+      // 保留原始文件名 + 时间戳防冲突
+      const ext = path.extname(originalFileName);
+      const base = path.basename(originalFileName, ext);
+      // 截断过长的文件名
+      const truncatedBase = base.length > 50 ? base.slice(0, 50) : base;
+      return `${timestamp}-${random}-${truncatedBase}${ext}`;
+    }
+
+    // 没有原始文件名，用 MIME 推断扩展名
+    const ext = mimeType ? extensionForMime(mimeType) : '';
+    return `${timestamp}-${random}${ext}`;
+  }
+}

package/modules/media/resolver.ts

@@ -0,0 +1,178 @@
+// ================================================================
+// InboundMediaResolver — 媒体下载 → 存储 → Agent 提示 的编排层
+// ================================================================
+// 职责：
+//   1. 使用 InboundMediaAdapter 下载原始 buffer
+//   2. 使用 MediaStore 存储并获取标准化 MediaEntry
+//   3. 构建 MessageAttachment 列表
+//   4. 生成给 Agent 的差异化提示（按文件类型）
+//
+// 参考 OpenClaw 的 parseMessageWithAttachments 设计
+// ================================================================
+
+import type { InboundMediaAdapter, DownloadedMedia, MediaResourceType } from './types';
+import type { MediaEntry } from './types';
+import type { MessageAttachment } from '../core/types';
+import { MediaStore } from './media-store';
+
+/** 单个附件的下载请求描述 */
+export interface MediaDownloadRequest {
+  /** 消息 ID */
+  messageId: string;
+  /** 平台资源 key（image_key / file_key 等） */
+  resourceKey: string;
+  /** 资源类型 */
+  type: MediaResourceType;
+  /** 原始文件名（如有） */
+  fileName?: string;
+}
+
+/** Resolver 返回结果 */
+export interface ResolveMediaResult {
+  /** 标准化附件列表（供 Agent 使用） */
+  attachments: MessageAttachment[];
+  /** 存储的媒体条目（含分类信息） */
+  entries: MediaEntry[];
+}
+
+/**
+ * 按媒体分类生成差异化的 Agent 提示
+ *
+ * 相比旧版 buildAttachmentHint，这里根据文件类型给 Agent 不同的操作引导：
+ * - PDF → 提示用 PDF 工具
+ * - Excel → 提示用表格解析
+ * - 纯文本 → 提示可直接 read
+ * - 压缩包 → 提示先解压
+ * - 未知二进制 → 提示用 file 命令或 sniff
+ */
+function buildHintForCategory(entry: MediaEntry): string {
+  const { localPath, mimeType, category, fileName } = entry;
+
+  switch (category) {
+    case 'image':
+      return `图片已保存到本地，路径: \`${localPath}\`，格式: ${mimeType}，可使用图片查看工具打开`;
+
+    case 'audio':
+      return `音频文件路径: \`${localPath}\`，格式: ${mimeType}，可用语音识别工具处理`;
+
+    case 'video':
+      return `视频文件路径: \`${localPath}\`，格式: ${mimeType}`;
+
+    case 'document':
+      return `文档文件路径: \`${localPath}\`，类型: ${mimeType}，可直接读取（如果是文本/PDF）或用相应工具处理`;
+
+    case 'text':
+      return `文本文件路径: \`${localPath}\`，可直接用文件读取工具读取内容`;
+
+    case 'spreadsheet':
+      return `表格文件路径: \`${localPath}\`，类型: ${mimeType}，可用表格解析工具（如 Python pandas/openpyxl）处理`;
+
+    case 'presentation':
+      return `演示文稿路径: \`${localPath}\`，类型: ${mimeType}`;
+
+    case 'archive':
+      return `压缩文件路径: \`${localPath}\`，类型: ${mimeType}，需要先解压再处理`;
+
+    default:
+      return `文件路径: \`${localPath}\`，格式: ${mimeType}，可用文件工具分析或直接读取`;
+  }
+}
+
+/**
+ * InboundMediaResolver
+ *
+ * 编排 IM 适配器的下载 + MediaStore 的存储，产出标准 MessageAttachment
+ */
+export class InboundMediaResolver {
+  private readonly adapter: InboundMediaAdapter;
+  private readonly store: MediaStore;
+
+  constructor(adapter: InboundMediaAdapter, store?: MediaStore) {
+    this.adapter = adapter;
+    this.store = store ?? new MediaStore();
+  }
+
+  /**
+   * 解析单个媒体附件
+   */
+  async resolveOne(request: MediaDownloadRequest): Promise<{
+    attachment: MessageAttachment;
+    entry: MediaEntry;
+  } | null> {
+    try {
+      // 1. 通过适配器下载
+      const downloaded = await this.adapter.downloadResource(
+        request.messageId,
+        request.resourceKey,
+        request.type,
+        request.fileName
+      );
+
+      if (!downloaded) {
+        console.log(`[${this.adapter.platform}] 下载资源失败: ${request.resourceKey}`);
+        return null;
+      }
+
+      // 2. 存入 MediaStore
+      const entry = this.store.save(
+        downloaded.buffer,
+        downloaded.contentType,
+        downloaded.fileName || request.fileName,
+        this.adapter.platform
+      );
+
+      // 3. 构建 MessageAttachment（向后兼容旧格式）
+      const attachment = this.buildAttachment(entry, downloaded, request);
+
+      return { attachment, entry };
+    } catch (e: any) {
+      console.error(`[${this.adapter.platform}] 解析媒体异常: ${e.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * 批量解析多个媒体附件
+   */
+  async resolveAll(requests: MediaDownloadRequest[]): Promise<ResolveMediaResult> {
+    const results = await Promise.all(
+      requests.map(req => this.resolveOne(req))
+    );
+
+    const attachments: MessageAttachment[] = [];
+    const entries: MediaEntry[] = [];
+
+    for (const r of results) {
+      if (r) {
+        attachments.push(r.attachment);
+        entries.push(r.entry);
+      }
+    }
+
+    return { attachments, entries };
+  }
+
+  // ================================================================
+  // Private
+  // ================================================================
+
+  private buildAttachment(
+    entry: MediaEntry,
+    downloaded: DownloadedMedia,
+    request: MediaDownloadRequest
+  ): MessageAttachment {
+    const type = entry.category === 'image' ? 'image'
+      : entry.category === 'audio' ? 'audio'
+      : 'file';
+
+    return {
+      type,
+      localPath: entry.localPath,
+      filename: entry.fileName,
+      sourceKey: downloaded.sourceKey || request.resourceKey,
+      mimeType: entry.mimeType,
+      durationMs: undefined, // 音频需要的话由调用方补充
+      hint: buildHintForCategory(entry), // 预计算的差异化提示
+    };
+  }
+}