imtoagent 0.2.0

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

@@ -0,0 +1,124 @@
+// ================================================================
+// TelegramInboundAdapter — Telegram 平台媒体下载适配器
+// ================================================================
+// 实现 InboundMediaAdapter 接口，负责从 Telegram Bot API 下载消息附件 buffer
+// 不负责：存储、MIME sniff、扩展名处理（由 MediaStore 处理）
+//
+// Telegram Bot API 文件下载流程：
+//   1. 调用 /getFile 传入 file_id → 获取 file_path
+//   2. 通过 https://api.telegram.org/file/bot<token>/<file_path> 下载
+// ================================================================
+
+import type { InboundMediaAdapter, DownloadedMedia, MediaResourceType } from './types';
+
+export interface TelegramInboundAdapterOptions {
+  token: string;
+  proxy?: string;
+  /** 可选：复用父类的代理感知 fetch，避免重复初始化 dispatcher */
+  fetchFn?: (url: string, init?: RequestInit) => Promise<Response>;
+}
+
+export class TelegramInboundAdapter implements InboundMediaAdapter {
+  readonly platform = 'telegram';
+  private token: string;
+  private apiUrl: string;
+  private fileUrl: string;
+  private proxy?: string;
+  private dispatcher?: any; // undici Dispatcher
+  private fetchFn?: (url: string, init?: RequestInit) => Promise<Response>;
+
+  constructor(options: TelegramInboundAdapterOptions) {
+    this.token = options.token;
+    this.proxy = options.proxy;
+    this.fetchFn = options.fetchFn;
+    this.apiUrl = `https://api.telegram.org/bot${this.token}`;
+    this.fileUrl = `https://api.telegram.org/file/bot${this.token}/`;
+
+    // 仅在没有外部 fetchFn 时，自己初始化代理 dispatcher（undici 风格）
+    if (!this.fetchFn && this.proxy) {
+      try {
+        const ProxyAgent = (globalThis as any).ProxyAgent;
+        if (ProxyAgent) {
+          this.dispatcher = new ProxyAgent(this.proxy);
+          console.log(`[TelegramInbound] 已配置代理 dispatcher: ${this.proxy}`);
+        } else {
+          console.log(`[TelegramInbound] ⚠️ 代理已配置但 ProxyAgent 不可用，将尝试直接连接`);
+        }
+      } catch (e: any) {
+        console.log(`[TelegramInbound] ⚠️ 代理 dispatcher 初始化失败: ${e.message}`);
+      }
+    }
+  }
+
+  async downloadResource(
+    messageId: string,
+    resourceKey: string,
+    type: MediaResourceType,
+    fileName?: string
+  ): Promise<DownloadedMedia | null> {
+    try {
+      // Step 1: 调用 getFile 获取 file_path
+      const fileResp = await this._fetch(`${this.apiUrl}/getFile`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ file_id: resourceKey }),
+      });
+
+      if (!fileResp.ok) {
+        console.error(`[TelegramInbound] getFile 失败: HTTP ${fileResp.status} (file_id=${resourceKey.slice(-10)})`);
+        return null;
+      }
+
+      const fileData = await fileResp.json();
+      if (!fileData.ok || !fileData.result?.file_path) {
+        console.error(`[TelegramInbound] getFile 返回无效: ${JSON.stringify(fileData).slice(0, 200)}`);
+        return null;
+      }
+
+      const filePath = fileData.result.file_path;
+      const fileSize = fileData.result.file_size;
+
+      if (fileSize && fileSize > 20 * 1024 * 1024) {
+        console.log(`[TelegramInbound] 文件过大 (${fileSize} bytes)，跳过下载`);
+        return null;
+      }
+
+      // Step 2: 下载文件内容
+      const downloadUrl = this.fileUrl + filePath;
+      const contentResp = await this._fetch(downloadUrl);
+
+      if (!contentResp.ok) {
+        console.error(`[TelegramInbound] 下载文件失败: HTTP ${contentResp.status} (path=${filePath})`);
+        return null;
+      }
+
+      const buffer = Buffer.from(await contentResp.arrayBuffer());
+      const contentType = contentResp.headers.get('content-type')?.split(';')[0].trim().toLowerCase() || undefined;
+
+      // 如果 Telegram 没有提供文件名，尝试从 file_path 提取
+      const finalFileName = fileName || filePath.split('/').pop() || 'unknown';
+
+      return {
+        buffer,
+        fileName: finalFileName,
+        contentType,
+        sourceKey: resourceKey,
+      };
+    } catch (e: any) {
+      console.error(`[TelegramInbound] 下载资源异常: ${e.message}`);
+      return null;
+    }
+  }
+
+  private async _fetch(url: string, init?: RequestInit): Promise<Response> {
+    // 优先使用外部注入的 fetchFn（复用父类的代理感知 fetch）
+    if (this.fetchFn) {
+      return this.fetchFn(url, init);
+    }
+    // 否则使用自己的 dispatcher
+    if (this.dispatcher) {
+      return fetch(url, { ...init, dispatcher: this.dispatcher } as any);
+    }
+    return fetch(url, init);
+  }
+}

package/modules/media/types.ts

@@ -0,0 +1,76 @@
+// ================================================================
+// Inbound Media — 适配器 + 抽象层类型定义
+// ================================================================
+// 设计思路（参考 OpenClaw）：
+//   1. IM 平台只管从自己平台下载原始 buffer（InboundMediaAdapter）
+//   2. MediaStore 负责存储、MIME sniff、生命周期管理
+//   3. InboundMediaResolver 负责串联下载→存储→生成 Agent 提示
+// ================================================================
+
+/** 媒体资源类型（对应飞书 API 的 type 参数） */
+export type MediaResourceType = 'image' | 'file' | 'media';
+
+/** 下载后的原始媒体元数据 */
+export interface DownloadedMedia {
+  /** 文件内容 buffer */
+  buffer: Buffer;
+  /** 平台提供的原始文件名（如有） */
+  fileName?: string;
+  /** 平台提供的 MIME 类型（如有，可能不准确） */
+  contentType?: string;
+  /** 平台资源标识（image_key / file_key 等，调试用） */
+  sourceKey?: string;
+}
+
+/** 统一媒体条目 — MediaStore 返回的标准格式 */
+export interface MediaEntry {
+  /** 本地存储路径 */
+  localPath: string;
+  /** 嗅探/推断出的 MIME 类型 */
+  mimeType: string;
+  /** 原始文件名（保留扩展名信息） */
+  fileName: string;
+  /** 媒体分类：image | document | audio | video | archive | spreadsheet | presentation | text | other */
+  category: MediaCategory;
+  /** 文件大小（bytes） */
+  sizeBytes: number;
+  /** 平台来源标识 */
+  source?: string;
+}
+
+/** 媒体分类（用于差异化 Agent 提示） */
+export type MediaCategory =
+  | 'image'
+  | 'document'     // PDF, DOC, DOCX, TXT, MD 等
+  | 'audio'
+  | 'video'
+  | 'archive'      // ZIP, TAR, RAR, 7Z 等
+  | 'spreadsheet'  // XLS, XLSX, CSV 等
+  | 'presentation' // PPT, PPTX 等
+  | 'text'         // 纯文本文件
+  | 'other';
+
+/**
+ * InboundMediaAdapter — IM 平台必须实现的媒体下载接口
+ *
+ * 职责：从各自 IM 平台下载消息附件的原始 buffer
+ * 不负责：存储、MIME sniff、扩展名处理
+ */
+export interface InboundMediaAdapter {
+  /**
+   * 从 IM 平台下载消息附件
+   * @param messageId  消息 ID
+   * @param resourceKey 平台资源 key（image_key / file_key 等）
+   * @param type       资源类型
+   * @param fileName   原始文件名（如有，用于扩展名推断）
+   */
+  downloadResource(
+    messageId: string,
+    resourceKey: string,
+    type: MediaResourceType,
+    fileName?: string
+  ): Promise<DownloadedMedia | null>;
+
+  /** 平台标识（'feishu' / 'telegram' / ...） */
+  readonly platform: string;
+}

package/modules/prompt-builder.ts

@@ -0,0 +1,123 @@
+// ================================================================
+// Prompt Builder — 统一的 Agent 系统提示词构建层
+// ================================================================
+// 职责：
+//   1. 加载 Soul（用户自定义指令）
+//   2. 构建 IM 能力说明
+//   3. 组合成完整 system prompt
+//
+// 设计原则：
+//   - 单一入口：所有 Agent 路径都调用 buildSystemPrompt()
+//   - 与 Agent 类型无关：Claude / Codex / 未来任何 Agent 都用同一套
+//   - 与 IM 类型无关：通过 IMCapabilities 接口抽象，飞书/微信/Telegram 都行
+//   - 无重复：loadSoul、fallback caps、构建逻辑只有一份
+// ================================================================
+
+import type { IMCapabilities } from './types';
+import { buildCapabilityPrompt } from './capabilities';
+import { getSoulDir } from './utils/paths';
+
+// ================================================================
+// 默认终端能力（无 IM 模块时的 fallback）
+// 唯一数据源 — 所有模块都用这个
+// ================================================================
+export const DEFAULT_TERMINAL_CAPS: IMCapabilities = {
+  text: true,
+  codeBlock: true,
+  cardMessage: false,
+  fileSend: false,
+  imageSend: false,
+  buttonAction: false,
+  maxTextLength: 50000,
+};
+
+// ================================================================
+// Soul 加载
+// ================================================================
+// 从 ~/Desktop/imtoagent/soul/{botName}/ 按顺序加载
+// 加载顺序：rules → identity → profile → workspace → skills
+// ================================================================
+export function loadSoul(botName: string): string {
+  const soulDir = getSoulDir(botName);
+  const soulOrder = ['rules.md', 'identity.md', 'profile.md', 'workspace.md', 'skills.md'];
+  const parts: string[] = [];
+  try {
+    const fs = require('fs');
+    if (!fs.existsSync(soulDir)) return '';
+    for (const file of soulOrder) {
+      const fp = soulDir + '/' + file;
+      if (fs.existsSync(fp)) {
+        const content = fs.readFileSync(fp, 'utf-8').trim();
+        if (content) parts.push(content);
+      }
+    }
+  } catch {}
+  return parts.join('\n\n');
+}
+
+// ================================================================
+// 上下文接口
+// ================================================================
+export interface PromptBuilderContext {
+  /** IM 模块实例，用于动态获取当前能力 */
+  imModule?: { getCapabilities(): IMCapabilities } | null;
+  /** 当 imModule 不可用时，手动指定的能力 */
+  caps?: IMCapabilities | null;
+  /** Bot 名称，用于加载 Soul */
+  botName: string;
+  /** Agent 特有的额外系统提示（如工具使用指南、工作目录约束等） */
+  agentInstructions?: string;
+}
+
+// ================================================================
+// 主入口：构建完整 system prompt
+// ================================================================
+// 组合顺序（从上到下，优先级递减）：
+//   1. Agent 特有指令（最高优先级，Agent 最关心）
+//   2. IM 能力说明（告诉 Agent 输出格式约束）
+//   3. Soul / 用户自定义指令（长期人格和规则）
+// ================================================================
+export function buildSystemPrompt(ctx: PromptBuilderContext): string {
+  const sections: string[] = [];
+
+  // 1. Agent 特有指令
+  if (ctx.agentInstructions) {
+    sections.push(ctx.agentInstructions.trim());
+  }
+
+  // 2. IM 能力
+  const caps = ctx.imModule?.getCapabilities() ?? ctx.caps ?? DEFAULT_TERMINAL_CAPS;
+  const capSection = buildCapabilityPrompt(caps);
+  sections.push('# 当前对接 IM 能力\n\n' + capSection);
+
+  // 3. 网关运行日志（Agent 可主动查询）
+  sections.push(`# 网关运行日志
+
+网关运行日志: ~/.imtoagent/logs/imtoagent.log
+
+你可以通过查看日志来了解网关状态、排查问题、感知重启事件：
+- \`tail -n 30 ~/.imtoagent/logs/imtoagent.log\` — 最近 30 行
+- \`grep -i "restart\|reload\|shutdown\|SIGTERM" ~/.imtoagent/logs/imtoagent.log | tail -n 10\` — 重启/关闭记录
+- \`grep -i "error\|fail\|crash" ~/.imtoagent/logs/imtoagent.log | tail -n 10\` — 错误记录
+- \`grep -i "online\|connected\|disconnected" ~/.imtoagent/logs/imtoagent.log | tail -n 10\` — Bot 连接状态
+
+注意：你启动后第一条消息的对话记忆可能已丢失（如果网关重启过），请先检查日志了解上下文。`);
+
+  // 4. Soul
+  const soul = loadSoul(ctx.botName);
+  if (soul) {
+    sections.push('# 用户自定义指令 (IMtoAgent Soul)\n\n' + soul);
+  }
+
+  return sections.join('\n\n---\n\n');
+}
+
+// ================================================================
+// 便捷函数：直接获取能力（消除各处 inline fallback）
+// ================================================================
+export function resolveCapabilities(
+  imModule?: { getCapabilities(): IMCapabilities } | null,
+  fallback?: IMCapabilities | null
+): IMCapabilities {
+  return imModule?.getCapabilities() ?? fallback ?? DEFAULT_TERMINAL_CAPS;
+}