@zhin.js/adapter-telegram 6.0.0 → 6.0.2

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 6.0.2
+
+### Patch Changes
+
+- d5cd4aa: Publish Plugin Runtime entry points and convention modules as JavaScript so
+  installed npm plugins load on Node without TypeScript stripping. Workspace
+  development continues to prefer TypeScript sources for local HMR.
+
+  Remove the unconsumed legacy game hub APIs from game-kit; game navigation and
+  records now use ordinary convention commands owned by the game hub plugin.
+
+- Updated dependencies [d5cd4aa]
+  - @zhin.js/command@1.0.4
+  - zhin.js@5.0.2
+  - @zhin.js/adapter@1.1.2
+  - @zhin.js/core@1.4.2
+  - @zhin.js/agent@1.0.7
+
+## 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.js

@@ -0,0 +1,34 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/telegram.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { TelegramEndpoint } from "../lib/endpoint.js";
+import { resolveTelegramConfig, } from "../lib/protocol.js";
+import { telegramRuntimeStateToken } from "../lib/telegram-runtime-state.js";
+export { TelegramEndpoint } from "../lib/endpoint.js";
+export default defineAdapter({
+    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),
+            config,
+            http: config.mode === 'webhook' ? context.use(httpHostToken) : undefined,
+        });
+    },
+});

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].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { telegramEndpointCommands } from "../../../lib/telegram-endpoint-commands.js";
+export default telegramEndpointCommands.add;

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.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { telegramEndpointCommands } from "../../lib/telegram-endpoint-commands.js";
+export default telegramEndpointCommands.list;

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].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { telegramEndpointCommands } from "../../../lib/telegram-endpoint-commands.js";
+export default telegramEndpointCommands.remove;

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');