@dsh-overdrive/gateway 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@dsh-overdrive/gateway",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@dsh-overdrive/sdk": "0.1.0",
+    "@larksuiteoapi/node-sdk": "^1.50.0",
+    "@slack/bolt": "^3.0.0",
+    "@whiskeysockets/baileys": "^6.0.1",
+    "dingtalk-stream-sdk-nodejs": "^2.0.4",
+    "discord.js": "^14.27.0",
+    "grammy": "^1.45.0",
+    "pino": "^9.0.0",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@types/qrcode-terminal": "^0.12.2"
+  },
+  "license": "MIT",
+  "description": "dsh-overdrive: 多平台消息网关（WhatsApp/Telegram/Discord/Slack/飞书/钉钉/企业微信）",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/temotee2103/dsh-overdrive.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,26 @@
+export interface NormalizedMessage {
+  chatId: string;
+  userId: string;
+  text: string;
+  media?: { kind: 'voice' | 'image' | 'video' | 'file'; url?: string; mime?: string; caption?: string };
+}
+
+export interface OutboundButton { id: string; label: string; }
+
+export interface OutboundPayload {
+  text: string;
+  buttons?: OutboundButton[];
+}
+
+/** 平台适配器契约：M2/M3 的 WhatsApp/Telegram/… 都实现它。 */
+export interface Adapter {
+  readonly id: string;
+  connect(): Promise<void>;
+  send(chatId: string, payload: OutboundPayload): Promise<void>;
+  /** 可选：平台"正在输入"指示（Telegram/WhatsApp 实现，其余默认无操作）。 */
+  sendTyping?(chatId: string): Promise<void>;
+  /** 可选：连接状态（供控制台）。 */
+  status?(): { connected: boolean };
+  onMessage(cb: (msg: NormalizedMessage) => void): void;
+  onReply(cb: (buttonId: string) => void): void;
+}

package/src/adapters/cli.ts

@@ -0,0 +1,37 @@
+import { createInterface } from 'node:readline';
+import type { Adapter, NormalizedMessage, OutboundPayload } from '../adapter.js';
+
+/** 本地命令行适配器：M1 用于验证全链路，也是 M2+ 平台适配器的样板。 */
+export class CliAdapter implements Adapter {
+  readonly id = 'cli';
+  private messageCb?: (msg: NormalizedMessage) => void;
+  private replyCb?: (buttonId: string) => void;
+  private rl?: ReturnType<typeof createInterface>;
+
+  async connect(): Promise<void> {
+    this.rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+    this.rl.on('line', (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
+      const btn = trimmed.match(/^\/btn\s+(\S+)$/i);
+      if (btn) {
+        this.replyCb?.(btn[1]);
+        return;
+      }
+      this.messageCb?.({ chatId: 'cli', userId: 'local', text: trimmed });
+    });
+  }
+
+  async send(_chatId: string, payload: OutboundPayload): Promise<void> {
+    const lines = [payload.text];
+    for (const b of payload.buttons ?? []) {
+      lines.push(`  [按钮] ${b.label} → 输入 /btn ${b.id}`);
+    }
+    process.stdout.write(lines.join('\n') + '\n');
+  }
+
+  onMessage(cb: (msg: NormalizedMessage) => void): void { this.messageCb = cb; }
+  onReply(cb: (buttonId: string) => void): void { this.replyCb = cb; }
+  /** CLI 是本地进程内适配器：恒为已连接。 */
+  status(): { connected: boolean } { return { connected: true }; }
+}

package/src/adapters/dingtalk.ts

@@ -0,0 +1,111 @@
+import type { Adapter, NormalizedMessage, OutboundButton, OutboundPayload } from '../adapter.js';
+import { DWClient, TOPIC_ROBOT, type RobotMessage } from 'dingtalk-stream-sdk-nodejs';
+
+// dingtalk-stream-sdk-nodejs@2.0.4 实测：exports 提供 DWClient + TOPIC_ROBOT
+// （/v1.0/im/bot/messages/get）；回调 registerCallbackListener(TOPIC_ROBOT, (msg) => …)，
+// msg.data 是 RobotMessage 的 JSON 字符串；回复直接 POST 消息内的 sessionWebhook（无需 access_token）。
+
+// ── 纯函数 ────────────────────────────────────────────────────
+
+export interface ParsedRobotMessage {
+  chatId: string;
+  userId: string;
+  text: string;
+  sessionWebhook: string;
+}
+
+export function parseBotMessage(data: RobotMessage): ParsedRobotMessage | null {
+  if (data.msgtype !== 'text' || !data.text?.content) return null;
+  if (!data.conversationId || !data.senderStaffId || !data.sessionWebhook) return null;
+  return {
+    chatId: data.conversationId,
+    userId: data.senderStaffId,
+    text: data.text.content,
+    sessionWebhook: data.sessionWebhook,
+  };
+}
+
+export function buildReplyBody(text: string): { msgtype: 'text'; text: { content: string } } {
+  return { msgtype: 'text', text: { content: text } };
+}
+
+export function buildNumberedText(text: string, buttons: OutboundButton[]): string {
+  if (buttons.length === 0) return text;
+  const options = buttons.map((b, i) => `${i + 1}) ${b.label}`).join('\n');
+  return `${text}\n\n${options}\n\n回复数字选择。`;
+}
+
+export function matchNumberedButton(text: string, buttons: OutboundButton[]): OutboundButton | undefined {
+  const n = Number(text.trim());
+  if (!Number.isInteger(n) || n < 1 || n > buttons.length) return undefined;
+  return buttons[n - 1];
+}
+
+// ── 适配器 ────────────────────────────────────────────────────
+
+export interface DingTalkAdapterOptions {
+  clientId: string;
+  clientSecret: string;
+}
+
+export class DingTalkAdapter implements Adapter {
+  readonly id = 'dingtalk';
+  private client?: DWClient;
+  private connected = false;
+  private messageCb?: (msg: NormalizedMessage) => void;
+  private replyCb?: (buttonId: string) => void;
+  private readonly pendingButtons = new Map<string, OutboundButton[]>();
+  /** conversationId → 最近的 sessionWebhook（回复通道，过期由钉钉侧管理） */
+  private readonly webhooks = new Map<string, string>();
+
+  constructor(private readonly opts: DingTalkAdapterOptions) {}
+
+  async connect(): Promise<void> {
+    const client = new DWClient({ clientId: this.opts.clientId, clientSecret: this.opts.clientSecret });
+    this.client = client;
+    client.registerCallbackListener(TOPIC_ROBOT, (msg) => {
+      let data: RobotMessage;
+      try {
+        data = JSON.parse(msg.data) as RobotMessage;
+      } catch {
+        return;
+      }
+      const parsed = parseBotMessage(data);
+      if (!parsed) return;
+      this.webhooks.set(parsed.chatId, parsed.sessionWebhook);
+      const pending = this.pendingButtons.get(parsed.chatId);
+      if (pending) {
+        const button = matchNumberedButton(parsed.text, pending);
+        if (button) {
+          this.pendingButtons.delete(parsed.chatId);
+          this.replyCb?.(button.id);
+          return;
+        }
+      }
+      this.messageCb?.({ chatId: parsed.chatId, userId: parsed.userId, text: parsed.text });
+    });
+    await client.connect();
+    this.connected = true;
+    console.log('[dingtalk] 钉钉 Stream 已连接');
+  }
+
+  async send(chatId: string, payload: OutboundPayload): Promise<void> {
+    const webhook = this.webhooks.get(chatId);
+    if (!webhook) throw new Error(`钉钉会话 ${chatId} 无可用 sessionWebhook（先让用户发一条消息）`);
+    if (payload.buttons?.length) this.pendingButtons.set(chatId, payload.buttons);
+    const text = buildNumberedText(payload.text, payload.buttons ?? []);
+    const res = await fetch(webhook, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(buildReplyBody(text)),
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`钉钉回发失败 ${res.status}: ${body.slice(0, 200)}`);
+    }
+  }
+
+  onMessage(cb: (msg: NormalizedMessage) => void): void { this.messageCb = cb; }
+  onReply(cb: (buttonId: string) => void): void { this.replyCb = cb; }
+  status(): { connected: boolean } { return { connected: this.connected }; }
+}

package/src/adapters/discord.ts

@@ -0,0 +1,117 @@
+import {
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  Client,
+  Events,
+  GatewayIntentBits,
+  type ButtonInteraction,
+  type Message,
+} from 'discord.js';
+import type { Adapter, NormalizedMessage, OutboundButton, OutboundPayload } from '../adapter.js';
+
+// ── 纯函数 ────────────────────────────────────────────────────
+
+export interface RawDiscordMessage {
+  channelId?: string;
+  author?: { id?: string; bot?: boolean };
+  content?: string;
+  attachments?: Array<{ url?: string; contentType?: string }>;
+}
+
+/** 纯函数：取第一条附件的下载 URL（attachments.first().url）；无附件返回 undefined。 */
+export function discordAttachmentUrl(raw: RawDiscordMessage): string | undefined {
+  return raw.attachments?.[0]?.url;
+}
+
+type MediaKind = 'voice' | 'image' | 'video' | 'file';
+
+function mediaKindFromMime(mime?: string): MediaKind {
+  if (mime?.startsWith('image/')) return 'image';
+  if (mime?.startsWith('audio/')) return 'voice';
+  if (mime?.startsWith('video/')) return 'video';
+  return 'file';
+}
+
+export function normalizeDiscordMessage(raw: RawDiscordMessage): NormalizedMessage | null {
+  if (!raw.channelId || !raw.author?.id || raw.author.bot) return null;
+  const text = raw.content ?? '';
+  const url = discordAttachmentUrl(raw);
+  if (!text && !url) return null;
+  const out: NormalizedMessage = { chatId: raw.channelId, userId: raw.author.id, text };
+  if (url) out.media = { kind: mediaKindFromMime(raw.attachments?.[0]?.contentType), url };
+  return out;
+}
+
+export function discordComponents(buttons: OutboundButton[]): Array<{ type: 1; components: unknown[] }> {
+  return [{
+    type: 1,
+    components: buttons.map((b) => ({
+      type: 2,
+      custom_id: b.id,
+      label: b.label,
+      style: 1, // ButtonStyle.Primary
+    })),
+  }];
+}
+
+// ── 适配器 ────────────────────────────────────────────────────
+
+export interface DiscordAdapterOptions { token: string; }
+
+export class DiscordAdapter implements Adapter {
+  readonly id = 'discord';
+  private readonly client: Client;
+  private connected = false;
+  private messageCb?: (msg: NormalizedMessage) => void;
+  private replyCb?: (buttonId: string) => void;
+
+  constructor(opts: DiscordAdapterOptions) {
+    this.client = new Client({
+      intents: [
+        GatewayIntentBits.Guilds,
+        GatewayIntentBits.GuildMessages,
+        GatewayIntentBits.DirectMessages,
+        GatewayIntentBits.MessageContent,
+      ],
+    });
+    void opts.token;
+    this.client.login(opts.token).catch((e) => console.error('[discord] 登录失败:', e));
+  }
+
+  async connect(): Promise<void> {
+    this.client.once(Events.ClientReady, () => { this.connected = true; console.log('[discord] 已连接 Discord'); });
+    this.client.on(Events.MessageCreate, (m: Message) => {
+      const msg = normalizeDiscordMessage(m as never);
+      if (msg) this.messageCb?.(msg);
+    });
+    this.client.on(Events.InteractionCreate, async (interaction) => {
+      if (!interaction.isButton()) return;
+      const button = interaction as ButtonInteraction;
+      await button.deferUpdate().catch(() => undefined);
+      this.replyCb?.(button.customId);
+    });
+  }
+
+  async send(chatId: string, payload: OutboundPayload): Promise<void> {
+    const channel = await this.client.channels.fetch(chatId);
+    if (!channel || !('send' in channel)) {
+      console.error(`[discord] 无法向 ${chatId} 发送（channel 不可用）`);
+      return;
+    }
+    if (payload.buttons?.length) {
+      const row = new ActionRowBuilder<ButtonBuilder>().addComponents(
+        payload.buttons.map((b) =>
+          new ButtonBuilder().setCustomId(b.id).setLabel(b.label).setStyle(ButtonStyle.Primary),
+        ),
+      );
+      await (channel as { send: (o: unknown) => Promise<unknown> }).send({ content: payload.text, components: [row] });
+      return;
+    }
+    await (channel as { send: (o: unknown) => Promise<unknown> }).send(payload.text);
+  }
+
+  onMessage(cb: (msg: NormalizedMessage) => void): void { this.messageCb = cb; }
+  onReply(cb: (buttonId: string) => void): void { this.replyCb = cb; }
+  status(): { connected: boolean } { return { connected: this.connected }; }
+}

package/src/adapters/feishu.ts

@@ -0,0 +1,126 @@
+import lark from '@larksuiteoapi/node-sdk';
+import type { Adapter, NormalizedMessage, OutboundButton, OutboundPayload } from '../adapter.js';
+
+// @larksuiteoapi/node-sdk 是 CommonJS 包（main=lib/index.js，无 "type":"module"）：
+// Node 原生 ESM 下必须 default 导入后解构（同 M2b 的 @slack/bolt 处理）。
+const { Client, WSClient, EventDispatcher } = lark;
+
+// ── 纯函数 ────────────────────────────────────────────────────
+
+export interface FeishuReceivePayload {
+  event?: {
+    message?: {
+      message_id?: string;
+      chat_id?: string;
+      message_type?: string;
+      content?: string;
+    };
+    sender?: { sender_id?: { open_id?: string } };
+  };
+}
+
+export function parseFeishuTextMessage(payload: FeishuReceivePayload): NormalizedMessage | null {
+  const message = payload.event?.message;
+  const sender = payload.event?.sender?.sender_id?.open_id;
+  if (!message?.chat_id || !sender) return null;
+  if (message.message_type !== 'text') return null;
+  let text = '';
+  try {
+    text = (JSON.parse(message.content ?? '{}') as { text?: string }).text ?? '';
+  } catch {
+    return null;
+  }
+  if (!text) return null;
+  return { chatId: message.chat_id, userId: sender, text };
+}
+
+export function buildNumberedText(text: string, buttons: OutboundButton[]): string {
+  if (buttons.length === 0) return text;
+  const options = buttons.map((b, i) => `${i + 1}) ${b.label}`).join('\n');
+  return `${text}\n\n${options}\n\n回复数字选择。`;
+}
+
+export function matchNumberedButton(text: string, buttons: OutboundButton[]): OutboundButton | undefined {
+  const n = Number(text.trim());
+  if (!Number.isInteger(n) || n < 1 || n > buttons.length) return undefined;
+  return buttons[n - 1];
+}
+
+// ── 适配器 ────────────────────────────────────────────────────
+
+export interface FeishuAdapterOptions {
+  appId: string;
+  appSecret: string;
+}
+
+export class FeishuAdapter implements Adapter {
+  readonly id = 'feishu';
+  private readonly client: InstanceType<typeof Client>;
+  private ws?: InstanceType<typeof WSClient>;
+  private connected = false;
+  private messageCb?: (msg: NormalizedMessage) => void;
+  private replyCb?: (buttonId: string) => void;
+  private readonly pendingButtons = new Map<string, OutboundButton[]>();
+  /** chatId → 最近一条入站消息的 message_id（send 优先 reply，缺失则 create 兜底） */
+  private readonly lastMessageIds = new Map<string, string>();
+
+  constructor(private readonly opts: FeishuAdapterOptions) {
+    this.client = new Client({ appId: opts.appId, appSecret: opts.appSecret });
+  }
+
+  async connect(): Promise<void> {
+    const dispatcher = new EventDispatcher({}).register({
+      'im.message.receive_v1': async (data: FeishuReceivePayload) => {
+        const message = data.event?.message;
+        if (message?.chat_id && message.message_id) {
+          this.lastMessageIds.set(message.chat_id, message.message_id);
+        }
+        const normalized = parseFeishuTextMessage(data);
+        if (!normalized) return;
+        const chatId = normalized.chatId;
+        const pending = this.pendingButtons.get(chatId);
+        if (pending) {
+          const button = matchNumberedButton(normalized.text, pending);
+          if (button) {
+            this.pendingButtons.delete(chatId);
+            this.replyCb?.(button.id);
+            return;
+          }
+        }
+        this.messageCb?.(normalized);
+      },
+    });
+    this.ws = new WSClient({
+      appId: this.opts.appId,
+      appSecret: this.opts.appSecret,
+      loggerLevel: lark.LoggerLevel.error,
+    });
+    await this.ws.start({ eventDispatcher: dispatcher });
+    this.connected = true;
+    console.log('[feishu] 飞书长连接已建立');
+  }
+
+  async send(chatId: string, payload: OutboundPayload): Promise<void> {
+    if (payload.buttons?.length) this.pendingButtons.set(chatId, payload.buttons);
+    const text = buildNumberedText(payload.text, payload.buttons ?? []);
+    const content = JSON.stringify({ text });
+    const messageId = this.lastMessageIds.get(chatId);
+    if (messageId) {
+      // 有最近入站消息：im.message.reply（path=message_id）回复原消息
+      await this.client.im.message.reply({
+        path: { message_id: messageId },
+        data: { msg_type: 'text', content },
+      });
+    } else {
+      // 无入站消息（主动下发）：im.message.create 按 receive_id=chat_id 发送
+      await this.client.im.message.create({
+        params: { receive_id_type: 'chat_id' },
+        data: { receive_id: chatId, msg_type: 'text', content },
+      });
+    }
+  }
+
+  onMessage(cb: (msg: NormalizedMessage) => void): void { this.messageCb = cb; }
+  onReply(cb: (buttonId: string) => void): void { this.replyCb = cb; }
+  status(): { connected: boolean } { return { connected: this.connected }; }
+}

package/src/adapters/slack.ts

@@ -0,0 +1,105 @@
+import Bolt from '@slack/bolt';
+import type { Adapter, NormalizedMessage, OutboundButton, OutboundPayload } from '../adapter.js';
+
+// @slack/bolt 是 CommonJS 包：Node 原生 ESM 下 `import { App }`（命名导入）会因
+// cjs-module-lexer 无法识别其导出而失败（App 为 undefined / 静态导入抛 SyntaxError），
+// 必须 default 导入后解构。
+const { App } = Bolt;
+
+// ── 纯函数 ────────────────────────────────────────────────────
+
+export interface RawSlackMessage {
+  channel?: string;
+  user?: string;
+  text?: string;
+  subtype?: string;
+  bot_id?: string;
+  files?: Array<{ url_private?: string; mimetype?: string }>;
+}
+
+/** 纯函数：取第一条文件的私有 URL（files[0].url_private）；无文件返回 undefined。 */
+export function slackFileUrl(raw: RawSlackMessage): string | undefined {
+  return raw.files?.[0]?.url_private;
+}
+
+type MediaKind = 'voice' | 'image' | 'video' | 'file';
+
+function mediaKindFromMime(mime?: string): MediaKind {
+  if (mime?.startsWith('image/')) return 'image';
+  if (mime?.startsWith('audio/')) return 'voice';
+  if (mime?.startsWith('video/')) return 'video';
+  return 'file';
+}
+
+export function normalizeSlackMessage(raw: RawSlackMessage): NormalizedMessage | null {
+  if (!raw.channel || !raw.user || raw.subtype === 'bot_message' || raw.bot_id) return null;
+  const text = raw.text ?? '';
+  const url = slackFileUrl(raw);
+  if (!text && !url) return null;
+  const out: NormalizedMessage = { chatId: raw.channel, userId: raw.user, text };
+  if (url) out.media = { kind: mediaKindFromMime(raw.files?.[0]?.mimetype), url };
+  return out;
+}
+
+export function slackBlocks(text: string, buttons: OutboundButton[]): unknown[] {
+  const blocks: unknown[] = [{ type: 'section', text: { type: 'mrkdwn', text } }];
+  if (buttons.length > 0) {
+    blocks.push({
+      type: 'actions',
+      elements: buttons.map((b) => ({
+        type: 'button',
+        value: b.id,
+        text: { type: 'plain_text', text: b.label },
+      })),
+    });
+  }
+  return blocks;
+}
+
+// ── 适配器 ────────────────────────────────────────────────────
+
+export interface SlackAdapterOptions {
+  botToken: string;
+  appToken: string;
+}
+
+export class SlackAdapter implements Adapter {
+  readonly id = 'slack';
+  // 解构出的 App 只有值绑定（无类型绑定），实例类型需用 InstanceType<typeof App>
+  private readonly app: InstanceType<typeof App>;
+  private connected = false;
+  private messageCb?: (msg: NormalizedMessage) => void;
+  private replyCb?: (buttonId: string) => void;
+
+  constructor(opts: SlackAdapterOptions) {
+    this.app = new App({ token: opts.botToken, appToken: opts.appToken, socketMode: true });
+  }
+
+  async connect(): Promise<void> {
+    this.app.message(async ({ message }) => {
+      const msg = normalizeSlackMessage(message as RawSlackMessage);
+      if (msg) this.messageCb?.(msg);
+    });
+    this.app.action(/^approve:|^reject:/, async ({ ack, body, respond }) => {
+      await ack();
+      const action = (body as { actions?: Array<{ value?: string }> }).actions?.[0];
+      if (action?.value) this.replyCb?.(action.value);
+      await respond({ text: '处理中…', replace_original: false }).catch(() => undefined);
+    });
+    await this.app.start(0); // Socket Mode 不需要端口；start(0) 仅建立连接
+    this.connected = true;
+    console.log('[slack] 已连接 Slack（Socket Mode）');
+  }
+
+  async send(chatId: string, payload: OutboundPayload): Promise<void> {
+    await this.app.client.chat.postMessage({
+      channel: chatId,
+      text: payload.text,
+      blocks: slackBlocks(payload.text, payload.buttons ?? []) as never,
+    });
+  }
+
+  onMessage(cb: (msg: NormalizedMessage) => void): void { this.messageCb = cb; }
+  onReply(cb: (buttonId: string) => void): void { this.replyCb = cb; }
+  status(): { connected: boolean } { return { connected: this.connected }; }
+}

package/src/adapters/telegram.ts

@@ -0,0 +1,112 @@
+import { Bot, InlineKeyboard } from 'grammy';
+import type { Adapter, NormalizedMessage, OutboundButton, OutboundPayload } from '../adapter.js';
+
+// ── 纯函数 ────────────────────────────────────────────────────
+
+export interface RawTelegramMessage {
+  chat?: { id?: number | string };
+  from?: { id?: number | string };
+  message?: {
+    text?: string;
+    caption?: string;
+    photo?: Array<{ file_id?: string }>;
+    voice?: { file_id?: string };
+    audio?: { file_id?: string };
+    video?: { file_id?: string };
+    document?: { file_id?: string };
+  };
+}
+
+/** 纯函数：取 photo 数组最后一张（最大尺寸）的 file_id；无图返回 undefined。 */
+export function telegramPhotoFileId(photo: Array<{ file_id?: string }>): string | undefined {
+  return photo[photo.length - 1]?.file_id;
+}
+
+/** 纯函数：Telegram 文件下载 URL 模板。file_path 需 getFile(file_id) 换取（真实调用在 adapter 薄层）。 */
+export function telegramImageUrl(token: string, filePath: string): string {
+  return `https://api.telegram.org/file/bot${token}/${filePath}`;
+}
+
+export function normalizeTelegramMessage(raw: RawTelegramMessage): NormalizedMessage | null {
+  if (raw.chat?.id === undefined || raw.from?.id === undefined) return null;
+  const msg = raw.message;
+  if (!msg) return null;
+  const text = msg.text ?? msg.caption ?? '';
+  let media: NormalizedMessage['media'];
+  if (msg.photo?.length) media = { kind: 'image' }; // url 由 adapter getFile 薄层填充
+  else if (msg.voice || msg.audio) media = { kind: 'voice' };
+  else if (msg.video) media = { kind: 'video' };
+  else if (msg.document) media = { kind: 'file' };
+  if (!text && !media) return null;
+  const out: NormalizedMessage = { chatId: String(raw.chat.id), userId: String(raw.from.id), text };
+  if (media) out.media = media;
+  return out;
+}
+
+export function buttonRows(buttons: OutboundButton[]): Array<[string, string]> {
+  return buttons.map((b) => [b.label, b.id]);
+}
+
+// ── 适配器 ────────────────────────────────────────────────────
+
+export interface TelegramAdapterOptions { token: string; }
+
+export class TelegramAdapter implements Adapter {
+  readonly id = 'telegram';
+  private readonly bot: Bot;
+  private readonly token: string;
+  private connected = false;
+  private messageCb?: (msg: NormalizedMessage) => void;
+  private replyCb?: (buttonId: string) => void;
+
+  constructor(opts: TelegramAdapterOptions) {
+    this.token = opts.token;
+    this.bot = new Bot(opts.token);
+  }
+
+  async connect(): Promise<void> {
+    await this.bot.api.getMe(); // 校验 token
+    this.connected = true;
+    this.bot.on('message', (ctx) => {
+      console.log(`[telegram] 收到更新: chat=${ctx.chat?.id} from=${ctx.from?.id} text="${ctx.message?.text?.slice(0, 40) ?? ''}"`);
+      void this.handleMessage(ctx as never);
+    });
+    this.bot.on('callback_query:data', async (ctx) => {
+      const data = ctx.callbackQuery.data;
+      await ctx.answerCallbackQuery().catch(() => undefined);
+      this.replyCb?.(data);
+    });
+    this.bot.catch((err) => console.error('[telegram]', err));
+    void this.bot.start(); // 长轮询（自托管无需 webhook）
+  }
+
+  /** 薄层：photo → getFile(file_id) 换 file_path → 下载 URL 填充 msg.media.url（纯函数只做模板）。 */
+  private async handleMessage(raw: RawTelegramMessage): Promise<void> {
+    const msg = normalizeTelegramMessage(raw);
+    if (!msg) return;
+    const fileId = msg.media?.kind === 'image' ? telegramPhotoFileId(raw.message?.photo ?? []) : undefined;
+    if (fileId) {
+      try {
+        const file = await this.bot.api.getFile(fileId);
+        if (file.file_path) msg.media!.url = telegramImageUrl(this.token, file.file_path);
+      } catch (error) {
+        console.error('[telegram] getFile 失败:', error);
+      }
+    }
+    this.messageCb?.(msg);
+  }
+
+  async send(chatId: string, payload: OutboundPayload): Promise<void> {
+    if (payload.buttons?.length) {
+      const kb = new InlineKeyboard();
+      for (const [label, id] of buttonRows(payload.buttons)) kb.text(label, id);
+      await this.bot.api.sendMessage(chatId, payload.text, { reply_markup: kb });
+      return;
+    }
+    await this.bot.api.sendMessage(chatId, payload.text);
+  }
+
+  onMessage(cb: (msg: NormalizedMessage) => void): void { this.messageCb = cb; }
+  onReply(cb: (buttonId: string) => void): void { this.replyCb = cb; }
+  status(): { connected: boolean } { return { connected: this.connected }; }
+}