@zhin.js/adapter-telegram 6.0.5 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 7.0.0
+
+### Patch Changes
+
+- 4fbff5d: feat!: 多模态双向 Segment 一贯制（BREAKING，无兼容层）
+
+  全框架唯一媒体表达统一为 canonical `Segment` + `MediaRef{kind: url|path|base64|file, value, mime_type?, file_name?, size?}`，新增 audio/video/file 段类型；所有第二形状（legacy `data.url/file/base64` 字段、`mediaRefFromLegacyData`/`mediaRefToLegacyFields` 桥、双写）全部删除。
+
+  - **core**：`SendContent` 一等支持 `Segment[]`；endpoint 出站载荷只含 canonical 段；`resolveOutboundMediaPolicy` 改为纯声明驱动（adapter definition `segments.outboundMedia`），内置策略表删除，未声明回退 `url-or-text`；`ImageContent` 旧桥删除。
+  - **ai**：新增 `MediaContentBlock`/`MediaBlockRef`（Segment 同构）与 `UserMessage.media`（当前 turn 媒体，**不持久化**——存储层自动剥离）；`createUserMessage(text, media?)` 签名变更（`ImageContent` 删除）；provider 边界序列化器 `filterMediaBlocksForProvider` + 能力表（缺省 image-only，不支持类型降级占位文本）；ai-sdk 桥媒体块 → SDK image/file parts。
+  - **agent**：入站 turn 注入（`turn/inbound-media.ts`）——commMessage 媒体段 → 当前 turn `UserMessage.media`；图片 path 物化、音频默认 STT（`@zhin.js/speech` 可选，失败降级占位）、视频/文件占位；`publishOutboundElements` 产出 canonical Segment；`transcribeAudioPayload` 导出。
+  - **cli**：`bridgeRuntimeMessage` 回复链路媒体段透传，不再压平为文本（`$reply` 直达 normalize → adapter）。
+  - **全部 20 个平台适配器**：出站媒体只消费 `data.media`（url 直发 / base64 直发 / 平台上传 / 读盘），入站媒体产出 canonical `data.media`；`segments.outboundMedia` 声明与实际消费逐一核对修正；QQ 入站新增 canonical segments（image/audio/video/file/mention/face/reply），图片/语音/视频不再丢失。
+
+  迁移：适配器/插件产媒体一律用 `{ type, data: { media: MediaRef } }`；发送 legacy `data.url/file/base64` 形状的段会被 warn 丢弃。
+
+- Updated dependencies [7c1e63a]
+- Updated dependencies [4fbff5d]
+- Updated dependencies [5b94d9c]
+  - @zhin.js/command@1.0.5
+  - @zhin.js/adapter@1.1.3
+  - @zhin.js/core@1.5.0
+  - @zhin.js/agent@1.1.0
+  - zhin.js@6.0.0
+
+## 6.0.6
+
+### Patch Changes
+
+- d52f3c5: fix: QQ 适配器群聊误识别为私聊、game-kit 启动崩溃、全面补齐 recallMessage
+
+  - fix(cli): `resolveChannelType` 增加 `metadata.channelKind` 检查，修复 QQ/Discord/KOOK 群聊消息被误分类为私聊
+  - fix(game-kit): `createHostGameDb` 改用延迟代理模型，避免数据库启动前解析模型导致崩溃
+  - feat(qq): 实现 `recallMessage`，解析复合 messageId 路由到对应 SDK 撤回方法；`normalizeQqMessage` 增加 `message_type` 缺失时的回退检测
+  - feat(slack): 实现 `recallMessage`，利用已有 compound ref 和 `chat.delete` API
+  - feat(onebot11): 两个 endpoint 类实现 `recallMessage`（`delete_msg`）
+  - feat(onebot12): 两个 endpoint 类实现 `recallMessage`（`delete_message`）
+  - feat(napcat): 三个 endpoint 类实现 `recallMessage`（`delete_msg`）
+  - feat(discord): 两个 endpoint 类实现 `recallMessage`；`send()` 改为返回 `channelId:snowflake` 复合 ID
+  - feat(telegram): 实现 `recallMessage`（`deleteMessage`）；`send()` 改为返回 `chatId:messageId` 复合 ID
+  - feat(kook): 两个 endpoint 类实现 `recallMessage`，利用 kook-client `recallMsg` API
+  - feat(lark): 实现 `recallMessage`（`DELETE /im/v1/messages/{id}`）
+  - feat(wecom): 实现 `recallMessage`（`POST /cgi-bin/message/recall`）
+
 ## 6.0.5
 
 ### Patch Changes

package/adapters/telegram.js

@@ -11,6 +11,7 @@ import { telegramRuntimeStateToken } from "../lib/telegram-runtime-state.js";
 export { TelegramEndpoint } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
     // 媒体 url / file_id 直发，base64 / 本地路径经 multipart attach:// 上传物化；
     // inline keyboard 原生按钮承载交互段。
     segments: {
@@ -19,7 +20,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveTelegramConfig(context.config);
-        // 注册到插件运行时状态（telegram endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（telegram.endpoint list 的"运行中"数据源）
         context.use(telegramRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: config.mode,

package/adapters/telegram.ts

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

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointControl, EndpointInstance, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -28,6 +28,7 @@ export interface TelegramEndpointOptions {
  */
 export declare class TelegramEndpoint implements EndpointInstance {
     #private;
+    readonly control: EndpointControl;
     constructor(options: TelegramEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;
@@ -39,10 +40,8 @@ export declare class TelegramEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ target, conversation, payload }: EndpointSendRequest): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
     /** Test / internal: admit a message when open. */
     admit(msg: TelegramMessage): void;
     /** Test / internal: admit a callback query when open. */

package/lib/endpoint.js

@@ -2,6 +2,7 @@
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
  */
 import { readFile } from 'node:fs/promises';
+import { formatLegacyMessageReference, nativeConversationId, parseLegacyMessageReference, } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { runTelegramPollLoop } from './polling.js';
 import { normalizeTelegramChatMember } from './platform-permit.js';
@@ -29,6 +30,9 @@ export class TelegramEndpoint {
     #botUserId;
     #botUsername;
     #chatMemberCache = new Map();
+    control = Object.freeze({
+        recall: (messageId) => this.recallMessage(messageId),
+    });
     constructor(options) {
         this.#options = options;
         this.#fetch = options.fetch ?? globalThis.fetch;
@@ -127,8 +131,9 @@ export class TelegramEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
-        const plan = formatOutboundPlan(target, payload);
+    async send({ target, conversation, payload }) {
+        const chatId = nativeConversationId(target, conversation);
+        const plan = formatOutboundPlan(chatId, payload);
         let lastId = '';
         for (const action of plan.actions) {
             const form = await this.#buildUploadForm(action.params, plan.uploads);
@@ -138,7 +143,19 @@ export class TelegramEndpoint {
             if (result.message_id != null)
                 lastId = String(result.message_id);
         }
-        return lastId || `telegram-${Date.now()}`;
+        if (!lastId)
+            return `telegram-${Date.now()}`;
+        return formatLegacyMessageReference({ target, messageId: lastId });
+    }
+    async recallMessage(messageId) {
+        if (!messageId || messageId.startsWith('telegram-'))
+            return;
+        const reference = parseLegacyMessageReference(messageId);
+        if (!reference)
+            return;
+        const chatId = nativeConversationId(reference.target);
+        const msgId = reference.messageId;
+        await this.callApi('deleteMessage', { chat_id: chatId, message_id: Number(msgId) });
     }
     /**
      * 含 `attach://` 占位的媒体参数 → multipart/form-data：
@@ -193,6 +210,9 @@ export class TelegramEndpoint {
             id: String(msg.message_id),
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
+                // Preserve Telegram's native value below, but publish the canonical
+                // scene kind so every Runtime consumer sees the same conversation type.
+                channelType: resolveTelegramChannelType(msg.chat.type),
                 chatType: msg.chat.type,
                 userId: msg.from?.id,
                 date: msg.date,
@@ -393,3 +413,10 @@ export class TelegramEndpoint {
         });
     }
 }
+function resolveTelegramChannelType(chatType) {
+    if (chatType === 'private')
+        return 'private';
+    if (chatType === 'channel')
+        return 'channel';
+    return 'group';
+}

package/lib/protocol.d.ts

@@ -284,6 +284,6 @@ export declare function formatOutboundActions(target: string | number, payload:
 /**
  * formatOutboundActions 的上传感知变体：canonical MediaRef kind=base64/path
  * 的媒体段产出 `attach://` 占位 + uploads 清单（endpoint 走 multipart 表单上传）；
- * kind=url/file 与旧 wire 字段（file_id/url）保持字符串直发。
+ * kind=url/file 保持字符串直发（file 即 Telegram file_id 不透明引用）。
  */
 export declare function formatOutboundPlan(target: string | number, payload: unknown): TelegramOutboundPlan;

package/lib/protocol.js

@@ -2,7 +2,9 @@
  * 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';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('telegram');
 export function resolveTelegramConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'telegram');
     const token = config.token
@@ -206,7 +208,7 @@ export function formatOutboundActions(target, payload) {
 /**
  * formatOutboundActions 的上传感知变体：canonical MediaRef kind=base64/path
  * 的媒体段产出 `attach://` 占位 + uploads 清单（endpoint 走 multipart 表单上传）；
- * kind=url/file 与旧 wire 字段（file_id/url）保持字符串直发。
+ * kind=url/file 保持字符串直发（file 即 Telegram file_id 不透明引用）。
  */
 export function formatOutboundPlan(target, payload) {
     const uploads = [];
@@ -241,14 +243,21 @@ function buildOutboundActions(target, payload, uploads) {
     const actions = [];
     const replyParams = () => (replyTo != null ? { reply_parameters: { message_id: replyTo } } : {});
     /**
-     * 媒体来源归一：canonical `data.media` 优先，旧 wire 字段
-     * `{file_id,url,file,base64}` 经 mediaRefFromLegacyData 兼容。
-     * url/file → 字符串直发；base64/path → attach:// 占位并登记上传。
+     * 媒体来源归一：唯一来源是 canonical `data.media` MediaRef。
+     * kind=url/file → 字符串直发（file 即 Telegram file_id 不透明引用）；
+     * kind=base64/path → attach:// 占位并登记上传。
+     * 无 MediaRef 时 warn + 丢弃（返回 undefined）。
      */
-    const mediaSource = (data, defaultName) => {
-        const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
-        if (!media)
+    const mediaSource = (segType, data, defaultName) => {
+        const media = isMediaRef(data.media) ? data.media : undefined;
+        if (!media) {
+            logger.warn(formatCompact({
+                op: 'telegram_outbound_media_dropped',
+                type: segType,
+                reason: 'missing_media_ref',
+            }));
             return undefined;
+        }
         if (media.kind === 'file' || media.kind === 'url')
             return media.value;
         const named = data.name ?? data.filename;
@@ -313,7 +322,7 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'image': {
-                const photo = mediaSource(data, 'image.png');
+                const photo = mediaSource('image', data, 'image.png');
                 if (photo) {
                     actions.push({
                         method: 'sendPhoto',
@@ -329,7 +338,7 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'video': {
-                const video = mediaSource(data, 'video.mp4');
+                const video = mediaSource('video', data, 'video.mp4');
                 if (video) {
                     actions.push({
                         method: 'sendVideo',
@@ -345,7 +354,7 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'audio': {
-                const audio = mediaSource(data, 'audio.mp3');
+                const audio = mediaSource('audio', data, 'audio.mp3');
                 if (audio) {
                     actions.push({
                         method: 'sendAudio',
@@ -361,7 +370,7 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'voice': {
-                const voice = mediaSource(data, 'voice.ogg');
+                const voice = mediaSource('voice', data, 'voice.ogg');
                 if (voice) {
                     actions.push({
                         method: 'sendVoice',
@@ -377,7 +386,7 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'file': {
-                const document = mediaSource(data, 'file');
+                const document = mediaSource('file', data, 'file');
                 if (document) {
                     actions.push({
                         method: 'sendDocument',
@@ -393,7 +402,7 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'sticker': {
-                const sticker = typeof data.file_id === 'string' ? data.file_id : mediaSource(data, 'sticker.webp');
+                const sticker = mediaSource('sticker', data, 'sticker.webp');
                 if (sticker) {
                     actions.push({
                         method: 'sendSticker',

package/lib/telegram-endpoint-commands.js

@@ -1,5 +1,5 @@
 /**
- * `telegram endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `telegram.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from '@zhin.js/adapter';

package/lib/telegram-runtime-state.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "6.0.5",
+  "version": "7.0.0",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,20 +32,21 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/command": "1.0.5",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/host-http": "1.0.4",
+    "@zhin.js/im-contract": "1.0.0",
     "@zhin.js/logger": "1.0.75",
     "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/agent": "1.0.10",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/agent": "1.1.0",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -63,9 +64,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.10",
+    "@zhin.js/agent": "1.1.0",
     "@zhin.js/host-http": "1.0.4",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -9,7 +9,7 @@ export default definePlugin({
         displayName: 'Telegram Bot API Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（telegram endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（telegram.endpoint list 的"运行中"数据源）
         context.resources.provide(telegramRuntimeStateToken, createEndpointRuntimeState());
         // 平台权限门禁：chat_creator / chat_administrator / pin_messages 等（agent 工具 platformPermit）
         return registerTelegramPlatformPermitChecker();

package/src/endpoint.ts

@@ -2,9 +2,14 @@
  * 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 { EndpointControl, EndpointInstance, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import {
+  formatLegacyMessageReference,
+  nativeConversationId,
+  parseLegacyMessageReference,
+} from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { runTelegramPollLoop } from './polling.js';
@@ -92,6 +97,9 @@ export class TelegramEndpoint implements EndpointInstance {
   #botUserId?: number;
   #botUsername?: string;
   readonly #chatMemberCache = new Map<string, ChatMemberPermit>();
+  readonly control: EndpointControl = Object.freeze({
+    recall: (messageId: string) => this.recallMessage(messageId),
+  });
 
   constructor(options: TelegramEndpointOptions) {
     this.#options = options;
@@ -199,8 +207,9 @@ export class TelegramEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    const plan = formatOutboundPlan(target, payload);
+  async send({ target, conversation, payload }: EndpointSendRequest): Promise<string> {
+    const chatId = nativeConversationId(target, conversation);
+    const plan = formatOutboundPlan(chatId, payload);
     let lastId = '';
     for (const action of plan.actions) {
       const form = await this.#buildUploadForm(action.params, plan.uploads);
@@ -209,7 +218,17 @@ export class TelegramEndpoint implements EndpointInstance {
         : 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()}`;
+    if (!lastId) return `telegram-${Date.now()}`;
+    return formatLegacyMessageReference({ target, messageId: lastId });
+  }
+
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId || messageId.startsWith('telegram-')) return;
+    const reference = parseLegacyMessageReference(messageId);
+    if (!reference) return;
+    const chatId = nativeConversationId(reference.target);
+    const msgId = reference.messageId;
+    await this.callApi('deleteMessage', { chat_id: chatId, message_id: Number(msgId) });
   }
 
   /**
@@ -270,6 +289,9 @@ export class TelegramEndpoint implements EndpointInstance {
       id: String(msg.message_id),
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
+        // Preserve Telegram's native value below, but publish the canonical
+        // scene kind so every Runtime consumer sees the same conversation type.
+        channelType: resolveTelegramChannelType(msg.chat.type),
         chatType: msg.chat.type,
         userId: msg.from?.id,
         date: msg.date,
@@ -499,3 +521,11 @@ export class TelegramEndpoint implements EndpointInstance {
     });
   }
 }
+
+function resolveTelegramChannelType(
+  chatType: TelegramMessage['chat']['type'],
+): 'private' | 'group' | 'channel' {
+  if (chatType === 'private') return 'private';
+  if (chatType === 'channel') return 'channel';
+  return 'group';
+}

package/src/protocol.ts

@@ -4,8 +4,11 @@
  */
 
 import type { IncomingMessage } from 'node:http';
-import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/core';
 import type { Segment } from '@zhin.js/core/runtime';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('telegram');
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface TelegramAdapterConfig {
@@ -473,7 +476,7 @@ export function formatOutboundActions(
 /**
  * formatOutboundActions 的上传感知变体：canonical MediaRef kind=base64/path
  * 的媒体段产出 `attach://` 占位 + uploads 清单（endpoint 走 multipart 表单上传）；
- * kind=url/file 与旧 wire 字段（file_id/url）保持字符串直发。
+ * kind=url/file 保持字符串直发（file 即 Telegram file_id 不透明引用）。
  */
 export function formatOutboundPlan(
   target: string | number,
@@ -521,13 +524,21 @@ function buildOutboundActions(
   );
 
   /**
-   * 媒体来源归一：canonical `data.media` 优先，旧 wire 字段
-   * `{file_id,url,file,base64}` 经 mediaRefFromLegacyData 兼容。
-   * url/file → 字符串直发；base64/path → attach:// 占位并登记上传。
+   * 媒体来源归一：唯一来源是 canonical `data.media` MediaRef。
+   * kind=url/file → 字符串直发（file 即 Telegram file_id 不透明引用）；
+   * kind=base64/path → attach:// 占位并登记上传。
+   * 无 MediaRef 时 warn + 丢弃（返回 undefined）。
    */
-  const mediaSource = (data: Record<string, unknown>, defaultName: string): string | undefined => {
-    const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
-    if (!media) return undefined;
+  const mediaSource = (segType: string, data: Record<string, unknown>, defaultName: string): string | undefined => {
+    const media = isMediaRef(data.media) ? data.media : undefined;
+    if (!media) {
+      logger.warn(formatCompact({
+        op: 'telegram_outbound_media_dropped',
+        type: segType,
+        reason: 'missing_media_ref',
+      }));
+      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;
@@ -590,7 +601,7 @@ function buildOutboundActions(
         break;
       }
       case 'image': {
-        const photo = mediaSource(data, 'image.png');
+        const photo = mediaSource('image', data, 'image.png');
         if (photo) {
           actions.push({
             method: 'sendPhoto',
@@ -606,7 +617,7 @@ function buildOutboundActions(
         break;
       }
       case 'video': {
-        const video = mediaSource(data, 'video.mp4');
+        const video = mediaSource('video', data, 'video.mp4');
         if (video) {
           actions.push({
             method: 'sendVideo',
@@ -622,7 +633,7 @@ function buildOutboundActions(
         break;
       }
       case 'audio': {
-        const audio = mediaSource(data, 'audio.mp3');
+        const audio = mediaSource('audio', data, 'audio.mp3');
         if (audio) {
           actions.push({
             method: 'sendAudio',
@@ -638,7 +649,7 @@ function buildOutboundActions(
         break;
       }
       case 'voice': {
-        const voice = mediaSource(data, 'voice.ogg');
+        const voice = mediaSource('voice', data, 'voice.ogg');
         if (voice) {
           actions.push({
             method: 'sendVoice',
@@ -654,7 +665,7 @@ function buildOutboundActions(
         break;
       }
       case 'file': {
-        const document = mediaSource(data, 'file');
+        const document = mediaSource('file', data, 'file');
         if (document) {
           actions.push({
             method: 'sendDocument',
@@ -670,7 +681,7 @@ function buildOutboundActions(
         break;
       }
       case 'sticker': {
-        const sticker = typeof data.file_id === 'string' ? data.file_id : mediaSource(data, 'sticker.webp');
+        const sticker = mediaSource('sticker', data, 'sticker.webp');
         if (sticker) {
           actions.push({
             method: 'sendSticker',

package/src/telegram-endpoint-commands.ts

@@ -1,5 +1,5 @@
 /**
- * `telegram endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `telegram.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from '@zhin.js/adapter';

package/src/telegram-runtime-state.ts

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