@zhin.js/adapter-telegram 6.0.0 → 6.0.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 6.0.1
+
+### Patch Changes
+
+- 5691aba: 第二轮全量审计修复批（8 面 ~60 bug）：
+
+  - **安全**：email 附件路径穿越修复（basename + downloadPath 约束）；lark/telegram/satori webhook 鉴权（缺密钥告警、timingSafeEqual、±5min 时效窗、chat_type 修正）；onebot wss/webhook 缺 token 告警；qq webhook 改原始字节验签；renderJsx/JSX 转义注入修复；console runtime token 401 死循环。
+  - **P0 功能**：sandbox 多 endpoint 解析 + WS 路径隔离；short-url expand（undici opaqueredirect）改 follow；AI 压缩摘要失败不再静默丢历史（熔断恢复生效）；console-ui 实时推送事件名归一化 + IndexedDB schema 对齐；process-monitor 热重载不再误判崩溃。
+  - **生命周期**：email IMAP 断线重连 + 在飞锁；onebot11/12 start 失败清理；line replyToken TTL + push 兜底；wechat-mp token 过期重试 + MsgId 去重；weixin-ilink buf 推进/防抖写盘/媒体 TTL/QR abort；satori PONG 看门狗；退避自毁修复。
+  - **游戏**：text-adventure 终局 restart 复活 + requires 服务端校验；tic-tac-toe PvP 占用/restart/队列清理/TTL；idiom-chain/word-riddle 闲聊不扣失误；别名中间件不劫持普通聊天。
+  - **共享库**：schema falsy 默认值/date/tuple/union 修复；database parseCondition Date/未知操作符、sqlite TEXT 往返、query 分派、belongsToMany 方言、migration dry-run；schedule DST 回拨死循环、重复 id 去重、flush 串行化；game-kit fallback 编号/onboarding 提示/尾缀边界/活引用拷贝。
+  - **渲染语音**：fetch 全部超时 + 渲染并发闸；sanitizeHtml form 保文本；STT 扩展名映射 + 删临时文件；TTS 未知 provider 报错；emojiCache LRU 负缓存/fontCache style/clearFonts 恢复；register 错误分类收窄。
+
+- 9c997b2: 通用 endpoint 管理命令套件：`@zhin.js/adapter` 新增 `createEndpointCommands(spec, defineCommand)`——`<adapter> endpoint list / add <name> key=value... / remove <name>` 三件套，含 kv 解析、`.env` 凭据派生（`<ADAPTER>_<NAME>_<FIELD>`）、yaml 写回保留注释、master 权限门禁（通用 `isEndpointOperator`）、自定义 bindFlow 钩子。QQ 迁移至套件（行为与扫码绑定流程不变）；napcat / onebot11 / onebot12 / milky / slack / telegram 接入（字段对齐各自 schema，features 补 @zhin.js/command）。
+- 6cb6152: 统一消息元素通道（UNI-Channel）落地：
+
+  - **入站契约**：`IncomingMessage.segments`（canonical Segment[]，与 content 纯文本视图同源双轨），Message 透传；AI 兜底链路经 `collectSegmentMedia` 把图片/语音/视频/文件 MediaRef 写入会话 extra——多模态输入不再丢失。
+  - **出站协商**：`normalizeOutboundPayload` 升级全量 canonical 归一（复用 generic-segment-mapper），html→image 按端点 `segments.outboundMedia` 声明降级（base64 直发 / url-or-text / passthrough 自行物化）；`MediaRef.kind` 新增 `'file'` 承载平台不透明引用（file_id/resource_id）。
+  - **能力声明**：`defineAdapter.segments` policy（outboundMedia / interactive），三道段门禁复活（探测点改 adapters/\*.ts，豁免名单渐进收敛）。
+  - **首批迁移**：icqq 全保真出入站（CQ ↔ canonical，quote→reply 段）；milky/telegram/discord 入站媒体段恢复（附件/贴纸/callback action）；napcat/onebot11/onebot12 出站 canonical→OneBot 数组段；wechat-mp/wecom `/cgi-bin/media/upload` 与 lark `/im/v1/images` 上传通路（base64/URL 图片不再静默丢图，失败降级文本）。
+
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/agent@1.0.6
+  - @zhin.js/plugin-runtime@1.1.1
+  - @zhin.js/host-http@1.0.3
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
 ## 6.0.0
 
 ### Patch Changes

package/adapters/telegram.ts

@@ -9,14 +9,26 @@ import {
   resolveTelegramConfig,
   type TelegramAdapterConfig,
 } from '../src/protocol.js';
+import { telegramRuntimeStateToken } from '../src/telegram-runtime-state.js';
 
 export { TelegramEndpoint } from '../src/endpoint.js';
 export type { TelegramEndpointOptions, TelegramFetch } from '../src/endpoint.js';
 
 export default defineAdapter<TelegramAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // 媒体 url / file_id 直发，base64 / 本地路径经 multipart attach:// 上传物化；
+  // inline keyboard 原生按钮承载交互段。
+  segments: {
+    outboundMedia: ['url', 'upload'],
+    interactive: 'native',
+  },
   create(context) {
     const config = resolveTelegramConfig(context.config);
+    // 注册到插件运行时状态（telegram endpoint list 的"运行中"数据源）
+    context.use(telegramRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.mode,
+    });
     return new TelegramEndpoint({
       id: context.id,
       gateway: context.use(messageGatewayToken),

package/commands/endpoint/add/[name:string].ts

@@ -0,0 +1,3 @@
+import { telegramEndpointCommands } from '../../../src/telegram-endpoint-commands.js';
+
+export default telegramEndpointCommands.add;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { telegramEndpointCommands } from '../../src/telegram-endpoint-commands.js';
+
+export default telegramEndpointCommands.list;

package/commands/endpoint/remove/[name:string].ts

@@ -0,0 +1,3 @@
+import { telegramEndpointCommands } from '../../../src/telegram-endpoint-commands.js';
+
+export default telegramEndpointCommands.remove;

package/lib/endpoint.d.ts

@@ -1,6 +1,3 @@
-/**
- * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
- */
 import type { EndpointInstance } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
@@ -9,7 +6,7 @@ import { type ResolvedTelegramConfig, type TelegramCallbackQuery, type TelegramC
 export type TelegramFetch = (url: string, init?: {
     readonly method?: string;
     readonly headers?: Record<string, string>;
-    readonly body?: string;
+    readonly body?: string | FormData;
     readonly signal?: AbortSignal;
 }) => Promise<{
     readonly ok: boolean;
@@ -24,6 +21,11 @@ export interface TelegramEndpointOptions {
     readonly http?: HttpHost;
     readonly fetch?: TelegramFetch;
 }
+/**
+ * Telegram Bot API 无列表类接口（无 getMyChats/getChatMembers），
+ * 仅 getChat/getChatMember 按已知 id 单查，不构成列表能力；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
 export declare class TelegramEndpoint implements EndpointInstance {
     #private;
     constructor(options: TelegramEndpointOptions);
@@ -48,6 +50,8 @@ export declare class TelegramEndpoint implements EndpointInstance {
     /** Used by webhook / polling handlers. */
     handleUpdate(update: TelegramUpdate): void;
     callApi<T = unknown>(method: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    /** multipart/form-data 变体（attach:// 媒体上传；Content-Type 边界由 FormData 自带）。 */
+    callApiForm<T = unknown>(method: string, form: FormData, signal?: AbortSignal): Promise<T>;
     pinMessage(chatId: number, messageId: number): Promise<boolean>;
     unpinMessage(chatId: number, messageId?: number): Promise<boolean>;
     setChatDescription(chatId: number, description: string): Promise<boolean>;

package/lib/endpoint.js

@@ -1,12 +1,21 @@
+/**
+ * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
+ */
+import { readFile } from 'node:fs/promises';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { runTelegramPollLoop } from './polling.js';
 import { normalizeTelegramChatMember } from './platform-permit.js';
-import { botApiUrl, buildWebhookUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, resolveChannel, senderDisplayName, } from './protocol.js';
+import { botApiUrl, buildWebhookUrl, formatCallbackContent, formatCallbackSegments, formatInboundContent, formatInboundSegments, formatOutboundPlan, resolveChannel, senderDisplayName, } from './protocol.js';
 import { registerTelegramAgentEndpoint } from './telegram-agent-deps.js';
 import { registerTelegramWebhookRoutes } from './webhook.js';
 const logger = getLogger('telegram');
 const CHAT_MEMBER_CACHE_TTL_MS = 60_000;
 const CHAT_MEMBER_CACHE_MAX = 2_000;
+/**
+ * Telegram Bot API 无列表类接口（无 getMyChats/getChatMembers），
+ * 仅 getChat/getChatMember 按已知 id 单查，不构成列表能力；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
 export class TelegramEndpoint {
     #options;
     #fetch;
@@ -55,6 +64,15 @@ export class TelegramEndpoint {
                 }
                 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,
@@ -110,15 +128,45 @@ export class TelegramEndpoint {
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
     async send({ target, payload }) {
-        const actions = formatOutboundActions(target, payload);
+        const plan = formatOutboundPlan(target, payload);
         let lastId = '';
-        for (const action of actions) {
-            const result = await this.callApi(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(action.method, form)
+                : await this.callApi(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, uploads) {
+        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) {
         if (!this.#open)
@@ -140,6 +188,7 @@ export class TelegramEndpoint {
             adapter: this.#options.id,
             target: channelId,
             content: formatInboundContent(msg),
+            segments: formatInboundSegments(msg),
             sender: senderDisplayName(msg.from),
             id: String(msg.message_id),
             metadata: Object.freeze({
@@ -224,6 +273,7 @@ export class TelegramEndpoint {
             adapter: this.#options.id,
             target: channelId,
             content: formatCallbackContent(query),
+            segments: formatCallbackSegments(query),
             sender: senderDisplayName(query.from),
             id: query.id,
             metadata: Object.freeze({
@@ -264,6 +314,19 @@ export class TelegramEndpoint {
             body: JSON.stringify(params),
             signal,
         });
+        return this.#parseApiResponse(method, response);
+    }
+    /** multipart/form-data 变体（attach:// 媒体上传；Content-Type 边界由 FormData 自带）。 */
+    async callApiForm(method, form, signal) {
+        const url = botApiUrl(this.#options.config, method);
+        const response = await this.#fetch(url, {
+            method: 'POST',
+            body: form,
+            signal,
+        });
+        return this.#parseApiResponse(method, response);
+    }
+    async #parseApiResponse(method, response) {
         const text = await response.text();
         let body;
         try {

package/lib/index.d.ts

@@ -1,4 +1,4 @@
 export { TelegramEndpoint, type TelegramEndpointOptions, type TelegramFetch, } from './endpoint.js';
-export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, normalizeWebhookPath, resolveChannel, resolveTelegramConfig, senderDisplayName, type ResolvedTelegramConfig, type TelegramAdapterConfig, type TelegramCallbackQuery, type TelegramChat, type TelegramChatMember, type TelegramMessage, type TelegramOutboundAction, type TelegramUpdate, type TelegramUser, type TelegramWireSegment, } from './protocol.js';
+export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveChannel, resolveTelegramConfig, senderDisplayName, type ResolvedTelegramConfig, type TelegramAdapterConfig, type TelegramCallbackQuery, type TelegramChat, type TelegramChatMember, type TelegramMessage, type TelegramOutboundAction, type TelegramOutboundPlan, type TelegramOutboundUpload, type TelegramUpdate, type TelegramUser, type TelegramWireSegment, } from './protocol.js';
 export { getTelegramAgentDeps, registerTelegramAgentEndpoint, setTelegramAgentDeps, type TelegramAgentDeps, type TelegramAgentEndpoint, } from './telegram-agent-deps.js';
 export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, registerTelegramPlatformPermitChecker, telegramGroupPermitResolver, } from './platform-permit.js';

package/lib/index.js

@@ -1,4 +1,4 @@
 export { TelegramEndpoint, } from './endpoint.js';
-export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, normalizeWebhookPath, resolveChannel, resolveTelegramConfig, senderDisplayName, } from './protocol.js';
+export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveChannel, resolveTelegramConfig, senderDisplayName, } from './protocol.js';
 export { getTelegramAgentDeps, registerTelegramAgentEndpoint, setTelegramAgentDeps, } from './telegram-agent-deps.js';
 export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, registerTelegramPlatformPermitChecker, telegramGroupPermitResolver, } from './platform-permit.js';

package/lib/polling.js

@@ -31,9 +31,9 @@ export async function runTelegramPollLoop(host, abortSignal) {
                 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/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import type { IncomingMessage } from 'node:http';
+import type { Segment } from '@zhin.js/core/runtime';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface TelegramAdapterConfig {
     readonly name?: string;
@@ -243,8 +244,46 @@ export declare function senderDisplayName(user?: TelegramUser): string;
 /** Build inbound text for MessageGateway.receive. */
 export declare function formatInboundContent(msg: TelegramMessage): string;
 export declare function formatCallbackContent(query: TelegramCallbackQuery): string;
+/**
+ * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * Telegram 附件只有不透明 file_id（需 getFile 二次解析，非 URL），
+ * 统一进 MediaRef kind=file；photo 取数组末尾（最大尺寸）。
+ */
+export declare function formatInboundSegments(msg: TelegramMessage): Segment[];
+/**
+ * callback_query → action 段（Wave 1 C interactive 约定：
+ * {type:'action', data:{id, payload, sourceMessageId?}}），
+ * 与 formatCallbackContent / metadata.payload 同源。
+ */
+export declare function formatCallbackSegments(query: TelegramCallbackQuery): Segment[];
+/**
+ * 出站待上传媒体（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.
  */
 export declare function formatOutboundActions(target: string | number, payload: unknown): TelegramOutboundAction[];
+/**
+ * formatOutboundActions 的上传感知变体：canonical MediaRef kind=base64/path
+ * 的媒体段产出 `attach://` 占位 + uploads 清单（endpoint 走 multipart 表单上传）；
+ * kind=url/file 与旧 wire 字段（file_id/url）保持字符串直发。
+ */
+export declare function formatOutboundPlan(target: string | number, payload: unknown): TelegramOutboundPlan;

package/lib/protocol.js

@@ -2,6 +2,7 @@
  * Telegram Bot API protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
+import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
 export function resolveTelegramConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'telegram');
     const token = config.token
@@ -112,11 +113,106 @@ export function formatInboundContent(msg) {
 export function formatCallbackContent(query) {
     return query.data ? `[action: ${query.data}]` : '[action]';
 }
+/**
+ * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * Telegram 附件只有不透明 file_id（需 getFile 二次解析，非 URL），
+ * 统一进 MediaRef kind=file；photo 取数组末尾（最大尺寸）。
+ */
+export function formatInboundSegments(msg) {
+    const out = [];
+    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) {
+    return [{
+            type: 'action',
+            data: {
+                id: query.id,
+                payload: query.data ?? '',
+                ...(query.message ? { sourceMessageId: String(query.message.message_id) } : {}),
+            },
+        }];
+}
 /**
  * Wire-encode an already-rendered outbound payload into Telegram Bot API actions.
  * Segment canonicalization is intentionally not done here.
  */
 export function formatOutboundActions(target, payload) {
+    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, payload) {
+    const uploads = [];
+    return { actions: buildOutboundActions(target, payload, uploads), uploads };
+}
+function buildOutboundActions(target, payload, uploads) {
     const chatId = typeof target === 'number' ? target : (/^-?\d+$/.test(target) ? Number(target) : target);
     if (typeof payload === 'string') {
         const text = payload.trim();
@@ -144,14 +240,41 @@ export function formatOutboundActions(target, payload) {
     let keyboard;
     const actions = [];
     const replyParams = () => (replyTo != null ? { reply_parameters: { message_id: replyTo } } : {});
-    const mediaSource = (data) => {
-        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, defaultName) => {
+        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) {
         if (typeof item === 'string') {
@@ -190,7 +313,7 @@ export function formatOutboundActions(target, payload) {
                 break;
             }
             case 'image': {
-                const photo = mediaSource(data);
+                const photo = mediaSource(data, 'image.png');
                 if (photo) {
                     actions.push({
                         method: 'sendPhoto',
@@ -206,7 +329,7 @@ export function formatOutboundActions(target, payload) {
                 break;
             }
             case 'video': {
-                const video = mediaSource(data);
+                const video = mediaSource(data, 'video.mp4');
                 if (video) {
                     actions.push({
                         method: 'sendVideo',
@@ -222,7 +345,7 @@ export function formatOutboundActions(target, payload) {
                 break;
             }
             case 'audio': {
-                const audio = mediaSource(data);
+                const audio = mediaSource(data, 'audio.mp3');
                 if (audio) {
                     actions.push({
                         method: 'sendAudio',
@@ -238,7 +361,7 @@ export function formatOutboundActions(target, payload) {
                 break;
             }
             case 'voice': {
-                const voice = mediaSource(data);
+                const voice = mediaSource(data, 'voice.ogg');
                 if (voice) {
                     actions.push({
                         method: 'sendVoice',
@@ -254,7 +377,7 @@ export function formatOutboundActions(target, payload) {
                 break;
             }
             case 'file': {
-                const document = mediaSource(data);
+                const document = mediaSource(data, 'file');
                 if (document) {
                     actions.push({
                         method: 'sendDocument',
@@ -270,7 +393,7 @@ export function formatOutboundActions(target, payload) {
                 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/lib/telegram-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const telegramEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

package/lib/telegram-endpoint-commands.js

@@ -0,0 +1,16 @@
+/**
+ * `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/lib/telegram-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const telegramRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/telegram-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * 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');

package/lib/webhook.d.ts

@@ -1,9 +1,8 @@
-/**
- * Telegram webhook HTTP: secret token → parse → handle update.
- */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { type ResolvedTelegramConfig, type TelegramUpdate } from './protocol.js';
+/** 等长时才 timingSafeEqual，避免长度差异直接抛异常。 */
+export declare function safeTokenEqual(a: string, b: string): boolean;
 export interface TelegramWebhookHandler {
     readonly config: ResolvedTelegramConfig;
     readonly isOpen: boolean;

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": "6.0.0",
+  "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.1.0",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/host-http": "1.0.2",
+    "@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.1.0"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/agent": "1.0.5",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/plugin-runtime": "1.1.0",
-    "zhin.js": "5.0.0"
+    "@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.5",
-    "@zhin.js/host-http": "1.0.2",
-    "zhin.js": "5.0.0"
+    "@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/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');

package/src/webhook.ts

@@ -1,6 +1,7 @@
 /**
  * Telegram webhook HTTP: secret token → parse → handle update.
  */
+import { timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { getLogger } from '@zhin.js/logger';
@@ -8,6 +9,13 @@ import { readTextBody, type ResolvedTelegramConfig, type TelegramUpdate } from '
 
 const logger = getLogger('telegram');
 
+/** 等长时才 timingSafeEqual，避免长度差异直接抛异常。 */
+export function safeTokenEqual(a: string, b: string): boolean {
+  const bufA = Buffer.from(a, 'utf8');
+  const bufB = Buffer.from(b, 'utf8');
+  return bufA.length === bufB.length && timingSafeEqual(bufA, bufB);
+}
+
 export interface TelegramWebhookHandler {
   readonly config: ResolvedTelegramConfig;
   readonly isOpen: boolean;
@@ -36,7 +44,7 @@ export async function handleTelegramWebhookRequest(
     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;