@zhin.js/adapter-telegram 5.0.3 → 6.0.1

package/lib/webhook.js

@@ -1,6 +1,16 @@
+/**
+ * Telegram webhook HTTP: secret token → parse → handle update.
+ */
+import { timingSafeEqual } from 'node:crypto';
 import { getLogger } from '@zhin.js/logger';
 import { readTextBody } from './protocol.js';
 const logger = getLogger('telegram');
+/** 等长时才 timingSafeEqual，避免长度差异直接抛异常。 */
+export function safeTokenEqual(a, b) {
+    const bufA = Buffer.from(a, 'utf8');
+    const bufB = Buffer.from(b, 'utf8');
+    return bufA.length === bufB.length && timingSafeEqual(bufA, bufB);
+}
 export function registerTelegramWebhookRoutes(http, handler) {
     const path = handler.config.webhook.path;
     return [
@@ -15,7 +25,7 @@ export async function handleTelegramWebhookRequest(request, response, handler) {
         if (secret) {
             const header = request.headers['x-telegram-bot-api-secret-token'];
             const token = Array.isArray(header) ? header[0] : header;
-            if (token !== secret) {
+            if (!token || !safeTokenEqual(token, secret)) {
                 response.writeHead(403, { 'Content-Type': 'application/json' });
                 response.end(JSON.stringify({ ok: false, description: 'Invalid secret token' }));
                 return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "5.0.3",
+  "version": "6.0.1",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,19 +32,20 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -62,12 +63,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/host-http": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/host-http": "1.0.3",
+    "zhin.js": "5.0.1"
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -93,6 +95,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,12 +1,16 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
 import { registerTelegramPlatformPermitChecker } from './src/platform-permit.js';
+import { telegramRuntimeStateToken } from './src/telegram-runtime-state.js';
 
 export default definePlugin({
   name: 'telegram',
   metadata: {
     displayName: 'Telegram Bot API Adapter',
   },
-  setup() {
+  setup(context) {
+    // 运行中 endpoint 注册表（telegram endpoint list 的"运行中"数据源）
+    context.resources.provide(telegramRuntimeStateToken, createEndpointRuntimeState());
     // 平台权限门禁：chat_creator / chat_administrator / pin_messages 等（agent 工具 platformPermit）
     return registerTelegramPlatformPermitChecker();
   },

package/schema.json

@@ -3,13 +3,6 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "default": "telegram-bot"
-    },
-    "token": {
-      "type": "string"
-    },
     "polling": {
       "type": "boolean",
       "default": true,
@@ -20,20 +13,62 @@
       "additionalProperties": false,
       "description": "Webhook settings when polling is false.",
       "properties": {
-        "domain": { "type": "string" },
-        "path": { "type": "string", "default": "/telegram/webhook" },
-        "secretToken": { "type": "string", "description": "Verified via X-Telegram-Bot-Api-Secret-Token." }
+        "domain": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "default": "/telegram/webhook"
+        },
+        "secretToken": {
+          "type": "string",
+          "description": "Verified via X-Telegram-Bot-Api-Secret-Token."
+        }
       }
     },
     "allowedUpdates": {
       "type": "array",
-      "items": { "type": "string" },
-      "default": ["message", "callback_query"]
+      "items": {
+        "type": "string"
+      },
+      "default": [
+        "message",
+        "callback_query"
+      ]
     },
     "apiBaseUrl": {
       "type": "string",
       "default": "https://api.telegram.org"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Telegram bot name"
+          },
+          "token": {
+            "type": "string",
+            "description": "Telegram bot token"
+          }
+        },
+        "required": [
+          "name",
+          "token"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
   },
-  "required": ["token"]
+  "required": [
+    "endpoints"
+  ]
 }

package/src/endpoint.ts

@@ -1,6 +1,7 @@
 /**
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
  */
+import { readFile } from 'node:fs/promises';
 import type { EndpointInstance } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
@@ -12,14 +13,17 @@ import {
   botApiUrl,
   buildWebhookUrl,
   formatCallbackContent,
+  formatCallbackSegments,
   formatInboundContent,
-  formatOutboundActions,
+  formatInboundSegments,
+  formatOutboundPlan,
   resolveChannel,
   senderDisplayName,
   type ResolvedTelegramConfig,
   type TelegramCallbackQuery,
   type TelegramChatMember,
   type TelegramMessage,
+  type TelegramOutboundUpload,
   type TelegramUpdate,
 } from './protocol.js';
 import { registerTelegramAgentEndpoint } from './telegram-agent-deps.js';
@@ -41,7 +45,7 @@ export type TelegramFetch = (
   init?: {
     readonly method?: string;
     readonly headers?: Record<string, string>;
-    readonly body?: string;
+    readonly body?: string | FormData;
     readonly signal?: AbortSignal;
   },
 ) => Promise<{
@@ -70,6 +74,11 @@ interface TelegramApiErr {
   readonly error_code?: number;
 }
 
+/**
+ * Telegram Bot API 无列表类接口（无 getMyChats/getChatMembers），
+ * 仅 getChat/getChatMember 按已知 id 单查，不构成列表能力；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
 export class TelegramEndpoint implements EndpointInstance {
   readonly #options: TelegramEndpointOptions;
   readonly #fetch: TelegramFetch;
@@ -125,6 +134,15 @@ export class TelegramEndpoint implements EndpointInstance {
         }
         this.#routeReleases.push(...registerTelegramWebhookRoutes(this.#options.http, this));
         const webhook = this.#options.config.webhook!;
+        if (!webhook.secretToken) {
+          // 未配 secretToken 时 webhook 无鉴权：任何人知道 path 即可注入假 update。
+          logger.warn(formatCompact({
+            op: 'webhook_no_secret',
+            endpoint: this.#options.config.name,
+            path: webhook.path,
+            hint: 'set webhook.secretToken to authenticate Telegram callbacks',
+          }));
+        }
         const url = buildWebhookUrl(webhook);
         await this.callApi('setWebhook', {
           url,
@@ -182,15 +200,50 @@ export class TelegramEndpoint implements EndpointInstance {
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    const actions = formatOutboundActions(target, payload);
+    const plan = formatOutboundPlan(target, payload);
     let lastId = '';
-    for (const action of actions) {
-      const result = await this.callApi<{ message_id?: number }>(action.method, action.params);
+    for (const action of plan.actions) {
+      const form = await this.#buildUploadForm(action.params, plan.uploads);
+      const result = form
+        ? await this.callApiForm<{ message_id?: number }>(action.method, form)
+        : await this.callApi<{ message_id?: number }>(action.method, action.params);
       if (result.message_id != null) lastId = String(result.message_id);
     }
     return lastId || `telegram-${Date.now()}`;
   }
 
+  /**
+   * 含 `attach://` 占位的媒体参数 → multipart/form-data：
+   * 标量参数原样、对象参数 JSON 序列化、attach 占位替换为文件 part
+   * （base64 直接解码，本地路径读盘）。无上传时返回 undefined（走 JSON 调用）。
+   */
+  async #buildUploadForm(
+    params: Record<string, unknown>,
+    uploads: readonly TelegramOutboundUpload[],
+  ): Promise<FormData | undefined> {
+    const values = Object.values(params);
+    if (!values.some((v) => typeof v === 'string' && v.startsWith('attach://'))) return undefined;
+    const form = new FormData();
+    for (const [key, value] of Object.entries(params)) {
+      if (value == null) continue;
+      if (typeof value === 'string' && value.startsWith('attach://')) {
+        const upload = uploads.find((item) => `attach://${item.attachName}` === value);
+        if (!upload) throw new Error(`Telegram upload 未登记: ${value}`);
+        const data = upload.source.kind === 'base64'
+          ? Buffer.from(upload.source.data, 'base64')
+          : await readFile(upload.source.path);
+        form.append(
+          key,
+          new Blob([data], upload.mimeType ? { type: upload.mimeType } : undefined),
+          upload.filename,
+        );
+        continue;
+      }
+      form.append(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+    }
+    return form;
+  }
+
   /** Test / internal: admit a message when open. */
   admit(msg: TelegramMessage): void {
     if (!this.#open) return;
@@ -212,6 +265,7 @@ export class TelegramEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target: channelId,
       content: formatInboundContent(msg),
+      segments: formatInboundSegments(msg),
       sender: senderDisplayName(msg.from),
       id: String(msg.message_id),
       metadata: Object.freeze({
@@ -290,6 +344,7 @@ export class TelegramEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target: channelId,
       content: formatCallbackContent(query),
+      segments: formatCallbackSegments(query),
       sender: senderDisplayName(query.from),
       id: query.id,
       metadata: Object.freeze({
@@ -336,6 +391,28 @@ export class TelegramEndpoint implements EndpointInstance {
       body: JSON.stringify(params),
       signal,
     });
+    return this.#parseApiResponse<T>(method, response);
+  }
+
+  /** multipart/form-data 变体（attach:// 媒体上传；Content-Type 边界由 FormData 自带）。 */
+  async callApiForm<T = unknown>(
+    method: string,
+    form: FormData,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    const url = botApiUrl(this.#options.config, method);
+    const response = await this.#fetch(url, {
+      method: 'POST',
+      body: form,
+      signal,
+    });
+    return this.#parseApiResponse<T>(method, response);
+  }
+
+  async #parseApiResponse<T>(
+    method: string,
+    response: { readonly status: number; text(): Promise<string> },
+  ): Promise<T> {
     const text = await response.text();
     let body: TelegramApiOk<T> | TelegramApiErr;
     try {

package/src/index.ts

@@ -9,6 +9,7 @@ export {
   formatCallbackContent,
   formatInboundContent,
   formatOutboundActions,
+  formatOutboundPlan,
   normalizeWebhookPath,
   resolveChannel,
   resolveTelegramConfig,
@@ -20,6 +21,8 @@ export {
   type TelegramChatMember,
   type TelegramMessage,
   type TelegramOutboundAction,
+  type TelegramOutboundPlan,
+  type TelegramOutboundUpload,
   type TelegramUpdate,
   type TelegramUser,
   type TelegramWireSegment,

package/src/polling.ts

@@ -47,11 +47,12 @@ export async function runTelegramPollLoop(
         ok: false,
         error: err instanceof Error ? err.message : String(err),
       }));
+      // 不在退避后清零：对端持续挂时清零会让重试固定打满 RETRY_DELAY_MS，
+      // 保持计数才能让 BACKOFF_DELAY_MS 持续生效（成功时上面才清零）。
       await sleep(
         consecutiveFailures >= MAX_CONSECUTIVE_FAILURES ? BACKOFF_DELAY_MS : RETRY_DELAY_MS,
         abortSignal,
       );
-      if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) consecutiveFailures = 0;
     }
   }
 }

package/src/protocol.ts

@@ -4,6 +4,8 @@
  */
 
 import type { IncomingMessage } from 'node:http';
+import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+import type { Segment } from '@zhin.js/core/runtime';
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface TelegramAdapterConfig {
@@ -355,6 +357,108 @@ export function formatCallbackContent(query: TelegramCallbackQuery): string {
   return query.data ? `[action: ${query.data}]` : '[action]';
 }
 
+/**
+ * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * Telegram 附件只有不透明 file_id（需 getFile 二次解析，非 URL），
+ * 统一进 MediaRef kind=file；photo 取数组末尾（最大尺寸）。
+ */
+export function formatInboundSegments(msg: TelegramMessage): Segment[] {
+  const out: Segment[] = [];
+  if (msg.reply_to_message) {
+    out.push({
+      type: 'reply',
+      data: { message_id: String(msg.reply_to_message.message_id) },
+    });
+  }
+  const text = msg.text ?? msg.caption;
+  if (text) out.push({ type: 'text', data: { text } });
+  if (msg.photo?.length) {
+    const largest = msg.photo[msg.photo.length - 1]!;
+    out.push({
+      type: 'image',
+      data: { media: { kind: 'file', value: largest.file_id } },
+    });
+  }
+  if (msg.video) {
+    out.push({
+      type: 'video',
+      data: { media: { kind: 'file', value: msg.video.file_id } },
+    });
+  }
+  if (msg.audio) {
+    out.push({
+      type: 'audio',
+      data: {
+        media: { kind: 'file', value: msg.audio.file_id },
+        ...(msg.audio.title ? { name: msg.audio.title } : {}),
+      },
+    });
+  }
+  if (msg.voice) {
+    out.push({
+      type: 'voice',
+      data: { media: { kind: 'file', value: msg.voice.file_id } },
+    });
+  }
+  if (msg.document) {
+    out.push({
+      type: 'file',
+      data: {
+        media: {
+          kind: 'file',
+          value: msg.document.file_id,
+          ...(msg.document.mime_type ? { mime_type: msg.document.mime_type } : {}),
+        },
+        ...(msg.document.file_name ? { name: msg.document.file_name } : {}),
+      },
+    });
+  }
+  if (msg.sticker) {
+    out.push({
+      type: 'image',
+      data: {
+        media: { kind: 'file', value: msg.sticker.file_id },
+        ...(msg.sticker.emoji ? { alt: msg.sticker.emoji } : {}),
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * callback_query → action 段（Wave 1 C interactive 约定：
+ * {type:'action', data:{id, payload, sourceMessageId?}}），
+ * 与 formatCallbackContent / metadata.payload 同源。
+ */
+export function formatCallbackSegments(query: TelegramCallbackQuery): Segment[] {
+  return [{
+    type: 'action',
+    data: {
+      id: query.id,
+      payload: query.data ?? '',
+      ...(query.message ? { sourceMessageId: String(query.message.message_id) } : {}),
+    },
+  }];
+}
+
+/**
+ * 出站待上传媒体（base64 / 本地路径 MediaRef 物化为 multipart 附件）。
+ * params 里以 `attach://<attachName>` 占位，endpoint 发送时替换为文件 part。
+ */
+export interface TelegramOutboundUpload {
+  readonly attachName: string;
+  readonly filename: string;
+  readonly source:
+    | { readonly kind: 'base64'; readonly data: string }
+    | { readonly kind: 'path'; readonly path: string };
+  readonly mimeType?: string;
+}
+
+export interface TelegramOutboundPlan {
+  readonly actions: TelegramOutboundAction[];
+  readonly uploads: readonly TelegramOutboundUpload[];
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into Telegram Bot API actions.
  * Segment canonicalization is intentionally not done here.
@@ -362,6 +466,27 @@ export function formatCallbackContent(query: TelegramCallbackQuery): string {
 export function formatOutboundActions(
   target: string | number,
   payload: unknown,
+): TelegramOutboundAction[] {
+  return formatOutboundPlan(target, payload).actions;
+}
+
+/**
+ * formatOutboundActions 的上传感知变体：canonical MediaRef kind=base64/path
+ * 的媒体段产出 `attach://` 占位 + uploads 清单（endpoint 走 multipart 表单上传）；
+ * kind=url/file 与旧 wire 字段（file_id/url）保持字符串直发。
+ */
+export function formatOutboundPlan(
+  target: string | number,
+  payload: unknown,
+): TelegramOutboundPlan {
+  const uploads: TelegramOutboundUpload[] = [];
+  return { actions: buildOutboundActions(target, payload, uploads), uploads };
+}
+
+function buildOutboundActions(
+  target: string | number,
+  payload: unknown,
+  uploads: TelegramOutboundUpload[],
 ): TelegramOutboundAction[] {
   const chatId = typeof target === 'number' ? target : (/^-?\d+$/.test(target) ? Number(target) : target);
   if (typeof payload === 'string') {
@@ -395,11 +520,39 @@ export function formatOutboundActions(
     replyTo != null ? { reply_parameters: { message_id: replyTo } } : {}
   );
 
-  const mediaSource = (data: Record<string, unknown>): string | undefined => {
-    if (typeof data.file_id === 'string' && data.file_id) return data.file_id;
-    if (typeof data.url === 'string' && data.url) return data.url;
-    if (typeof data.file === 'string' && data.file) return data.file;
-    return undefined;
+  /**
+   * 媒体来源归一：canonical `data.media` 优先，旧 wire 字段
+   * `{file_id,url,file,base64}` 经 mediaRefFromLegacyData 兼容。
+   * url/file → 字符串直发；base64/path → attach:// 占位并登记上传。
+   */
+  const mediaSource = (data: Record<string, unknown>, defaultName: string): string | undefined => {
+    const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
+    if (!media) return undefined;
+    if (media.kind === 'file' || media.kind === 'url') return media.value;
+    const named = data.name ?? data.filename;
+    let filename = typeof named === 'string' && named ? named : undefined;
+    if (!filename && media.kind === 'path') {
+      const raw = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
+      filename = raw.split(/[\\/]/).filter(Boolean).pop();
+    }
+    const attachName = `attach${uploads.length}`;
+    uploads.push({
+      attachName,
+      filename: filename ?? defaultName,
+      source: media.kind === 'base64'
+        ? {
+          kind: 'base64',
+          data: media.value.startsWith('base64://')
+            ? media.value.slice('base64://'.length)
+            : media.value,
+        }
+        : {
+          kind: 'path',
+          path: media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value,
+        },
+      ...(media.mime_type ? { mimeType: media.mime_type } : {}),
+    });
+    return `attach://${attachName}`;
   };
 
   for (const item of items) {
@@ -437,7 +590,7 @@ export function formatOutboundActions(
         break;
       }
       case 'image': {
-        const photo = mediaSource(data);
+        const photo = mediaSource(data, 'image.png');
         if (photo) {
           actions.push({
             method: 'sendPhoto',
@@ -453,7 +606,7 @@ export function formatOutboundActions(
         break;
       }
       case 'video': {
-        const video = mediaSource(data);
+        const video = mediaSource(data, 'video.mp4');
         if (video) {
           actions.push({
             method: 'sendVideo',
@@ -469,7 +622,7 @@ export function formatOutboundActions(
         break;
       }
       case 'audio': {
-        const audio = mediaSource(data);
+        const audio = mediaSource(data, 'audio.mp3');
         if (audio) {
           actions.push({
             method: 'sendAudio',
@@ -485,7 +638,7 @@ export function formatOutboundActions(
         break;
       }
       case 'voice': {
-        const voice = mediaSource(data);
+        const voice = mediaSource(data, 'voice.ogg');
         if (voice) {
           actions.push({
             method: 'sendVoice',
@@ -501,7 +654,7 @@ export function formatOutboundActions(
         break;
       }
       case 'file': {
-        const document = mediaSource(data);
+        const document = mediaSource(data, 'file');
         if (document) {
           actions.push({
             method: 'sendDocument',
@@ -517,7 +670,7 @@ export function formatOutboundActions(
         break;
       }
       case 'sticker': {
-        const sticker = typeof data.file_id === 'string' ? data.file_id : mediaSource(data);
+        const sticker = typeof data.file_id === 'string' ? data.file_id : mediaSource(data, 'sticker.webp');
         if (sticker) {
           actions.push({
             method: 'sendSticker',

package/src/telegram-endpoint-commands.ts

@@ -0,0 +1,17 @@
+/**
+ * `telegram endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { telegramRuntimeStateToken } from './telegram-runtime-state.js';
+
+export const telegramEndpointCommands = createEndpointCommands({
+  adapterKey: 'telegram',
+  adapterDisplayName: 'Telegram',
+  fields: [
+    { key: 'token', required: true, env: true, description: 'Telegram bot token' },
+  ],
+  running: (use) => use(telegramRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/src/telegram-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * Telegram 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `telegram endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
+
+export const telegramRuntimeStateToken = defineEndpointRuntimeStateToken('telegram');