@zhin.js/adapter-telegram 7.0.12 → 7.0.14

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 7.0.14
+
+### Patch Changes
+
+- 5969c5b: Remove legacy compound-string message targets and Endpoint control probing. Endpoint control and outbound Host operations now carry structured `MessageRef` identities. Endpoint send has one exact result contract (a platform message id), which IM Runtime projects into `DeliveryReceipt.message`; arbitrary result guessing is removed.
+- 974772e: Replace the user-facing `Prompt` vocabulary with the `UserInteraction` authoring surface for input, confirmation, and selection. Commands and handlers now expose `interaction`; IM Runtime exposes `createInteraction`; schema-driven endpoint collection is named `SchemaInteraction`. The old prompt-named interaction types and properties are removed rather than aliased. User interactions render through one canonical Markdown and keyboard/list presentation module shared by commands and Agent `ask_user` turns.
+
+  Extract the transport-neutral interaction contract into `@zhin.js/interaction`. A discriminated `ask()` API supports text, number, confirmation, single-select, multi-select, and typed lists with structured `title`, `description`, and `tip` content. Typed `sequence()` interactions return one result object keyed by step id, render progress, and retry invalid replies without leaking invalid values to callers.
+
+  Preserve AI Markdown and card command actions through outbound publishing. QQ delivers Markdown with native command buttons; KOOK, Discord, Telegram, DingTalk, and Lark/Feishu now declare and encode their native Markdown dialects while retaining each adapter's interaction policy. Correct QQ callback button action encoding and button style mapping.
+
+- 5969c5b: Add SideEventGateway so adapters forward notice/request/system into HandlerIndex. HandlerContext now exposes only generation-safe capabilities and prompt ports; live Endpoint escape hatches are removed.
+- 059555a: Add the canonical conversation content port for scoped Telegram media references.
+  Opaque Bot API file ids are materialized to bounded base64 without exposing token-bearing download URLs.
+- Updated dependencies [5969c5b]
+- Updated dependencies [d336a3f]
+- Updated dependencies [0c82a7e]
+- Updated dependencies [b9217e4]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [974772e]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [2f786bd]
+- Updated dependencies [63d89f9]
+- Updated dependencies [71c7cdd]
+- Updated dependencies [3cca0ea]
+- Updated dependencies [1312ca0]
+- Updated dependencies [985fa22]
+- Updated dependencies [04b861d]
+- Updated dependencies [a23d544]
+- Updated dependencies [8cddabf]
+- Updated dependencies [dbe5081]
+  - @zhin.js/im-contract@1.0.4
+  - @zhin.js/core@1.5.12
+  - @zhin.js/adapter@1.1.11
+  - @zhin.js/agent@1.1.14
+  - @zhin.js/host-http@1.0.11
+  - @zhin.js/command@1.0.15
+  - zhin.js@6.0.12
+  - @zhin.js/permission@1.0.3
+
+## 7.0.13
+
+### Patch Changes
+
+- @zhin.js/core@1.5.11
+- @zhin.js/agent@1.1.13
+- zhin.js@6.0.11
+
 ## 7.0.12
 
 ### Patch Changes

package/README.md

@@ -7,7 +7,7 @@ Zhin.js Telegram Bot API 适配器（Plugin Runtime），默认通过 **长轮
 - 长轮询 `getUpdates` 入站（默认；无需公网 IP / host-http）
 - 解析 text / image / video / audio / voice / document / sticker / location / callback_query
 - 支持私聊与群组
-- 出站 `send({ conversation, payload })` → Bot API（text / media / keyboard）
+- 出站 `send({ conversation, payload })` → Bot API（Markdown→安全 HTML / media / keyboard）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - Webhook 模式延期（需 `httpHostToken`）；配置 `polling: false` 会明确报错
 
@@ -78,6 +78,7 @@ plugins:
 | Telegram | 入站 content（文本摘要） | 出站 wire |
 |----------|--------------------------|-----------|
 | text | 原文 | sendMessage |
+| markdown | 原文 | sendMessage（`parse_mode: HTML`） |
 | photo | `[image]` / caption | sendPhoto（`file_id` / `url`） |
 | video | `[video]` | sendVideo |
 | audio / voice | `[audio]` / `[voice]` | sendAudio / sendVoice |

package/adapters/telegram.js

@@ -3,7 +3,7 @@
  * Convention entry: discover `adapters/telegram.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { TelegramEndpoint } from "../lib/endpoint.js";
 import { resolveTelegramConfig, } from "../lib/protocol.js";
@@ -17,6 +17,7 @@ export default defineAdapter({
     segments: {
         outboundMedia: ['url', 'upload'],
         interactive: 'native',
+        markdown: 'native',
     },
     create(context) {
         const config = resolveTelegramConfig(context.config);
@@ -28,6 +29,7 @@ export default defineAdapter({
         return new TelegramEndpoint({
             id: context.id,
             gateway: context.use(messageGatewayToken),
+            sideEvents: context.use(sideEventGatewayToken),
             config,
             http: config.mode === 'webhook' ? context.use(httpHostToken) : undefined,
         });

package/adapters/telegram.ts

@@ -2,7 +2,7 @@
  * Convention entry: discover `adapters/telegram.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { TelegramEndpoint } from '../src/endpoint.js';
 import {
@@ -22,6 +22,7 @@ export default defineAdapter<TelegramAdapterConfig>({
   segments: {
     outboundMedia: ['url', 'upload'],
     interactive: 'native',
+    markdown: 'native',
   },
   create(context) {
     const config = resolveTelegramConfig(context.config);
@@ -33,6 +34,7 @@ export default defineAdapter<TelegramAdapterConfig>({
     return new TelegramEndpoint({
       id: context.id,
       gateway: context.use(messageGatewayToken),
+      sideEvents: context.use(sideEventGatewayToken),
       config,
       http: config.mode === 'webhook' ? context.use(httpHostToken) : undefined,
     });

package/lib/endpoint.d.ts

@@ -1,5 +1,5 @@
-import type { EndpointControl, EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { EndpointContentPort, EndpointControl, EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import { type MessageRef } from '@zhin.js/im-contract';
 import type { CapabilityId } from 'zhin.js';
@@ -14,10 +14,15 @@ export type TelegramFetch = (url: string, init?: {
     readonly status: number;
     text(): Promise<string>;
     json(): Promise<unknown>;
+    arrayBuffer?(): Promise<ArrayBuffer>;
+    readonly headers?: {
+        get(name: string): string | null;
+    };
 }>;
 export interface TelegramEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly config: ResolvedTelegramConfig;
     readonly http?: HttpHost;
     readonly fetch?: TelegramFetch;
@@ -30,6 +35,7 @@ export interface TelegramEndpointOptions {
 export declare class TelegramEndpoint implements EndpointInstance {
     #private;
     readonly control: EndpointControl;
+    readonly content: EndpointContentPort;
     constructor(options: TelegramEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;

package/lib/endpoint.js

@@ -32,6 +32,9 @@ export class TelegramEndpoint {
     control = Object.freeze({
         recall: (message) => this.recallMessage(message),
     });
+    content = Object.freeze({
+        resolve: (reference, context) => this.#resolveContent(reference, context.signal),
+    });
     constructor(options) {
         this.#logger = getAdapterLogger('telegram', options.config.id);
         this.#options = options;
@@ -152,6 +155,50 @@ export class TelegramEndpoint {
             message_id: Number(message.id),
         });
     }
+    async #resolveContent(reference, signal) {
+        if (reference.kind !== 'media') {
+            return Object.freeze({ status: 'unsupported', code: 'telegram_message_lookup_unavailable' });
+        }
+        if (reference.media.kind !== 'file') {
+            return Object.freeze({ status: 'resolved', reference, value: reference.media });
+        }
+        try {
+            signal.throwIfAborted();
+            const file = await this.callApi('getFile', {
+                file_id: reference.media.value,
+            });
+            if (!file.file_path)
+                return Object.freeze({ status: 'not_found', code: 'telegram_file_not_found' });
+            if ((file.file_size ?? 0) > 26_214_400)
+                return Object.freeze({ status: 'forbidden', code: 'media_size_limit' });
+            const response = await this.#fetch(`${this.#options.config.apiBaseUrl}/file/bot${this.#options.config.token}/${file.file_path}`, { signal });
+            if (!response.ok)
+                return Object.freeze({ status: 'failed', code: 'telegram_file_download_failed' });
+            if (!response.arrayBuffer)
+                return Object.freeze({ status: 'failed', code: 'telegram_binary_transport_unavailable' });
+            const bytes = Buffer.from(await response.arrayBuffer());
+            if (bytes.byteLength > 26_214_400)
+                return Object.freeze({ status: 'forbidden', code: 'media_size_limit' });
+            return Object.freeze({
+                status: 'resolved',
+                reference,
+                value: Object.freeze({
+                    kind: 'base64',
+                    value: bytes.toString('base64'),
+                    ...(response.headers?.get('content-type')?.split(';')[0] || reference.media.mime_type
+                        ? { mime_type: response.headers?.get('content-type')?.split(';')[0] ?? reference.media.mime_type }
+                        : {}),
+                    ...(reference.media.file_name ? { file_name: reference.media.file_name } : {}),
+                    size: bytes.byteLength,
+                }),
+            });
+        }
+        catch (error) {
+            if (signal.aborted)
+                return Object.freeze({ status: 'expired', code: 'turn_aborted' });
+            return Object.freeze({ status: 'failed', code: 'telegram_file_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+        }
+    }
     /**
      * 含 `attach://` 占位的媒体参数 → multipart/form-data：
      * 标量参数原样、对象参数 JSON 序列化、attach 占位替换为文件 part

package/lib/markdown-to-html.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Canonical Markdown → Telegram Bot API HTML.
+ *
+ * Telegram's MarkdownV2 is not CommonMark-compatible and rejects unescaped
+ * punctuation. HTML gives the adapter a safer dialect seam: user text is
+ * escaped first and only the subset supported by Bot API is emitted as tags.
+ */
+export declare function markdownToTelegramHtml(markdown: string): string;
+export declare function escapeTelegramHtml(value: string): string;

package/lib/markdown-to-html.js

@@ -0,0 +1,75 @@
+/**
+ * Canonical Markdown → Telegram Bot API HTML.
+ *
+ * Telegram's MarkdownV2 is not CommonMark-compatible and rejects unescaped
+ * punctuation. HTML gives the adapter a safer dialect seam: user text is
+ * escaped first and only the subset supported by Bot API is emitted as tags.
+ */
+export function markdownToTelegramHtml(markdown) {
+    const protectedFragments = [];
+    const protect = (html) => {
+        const token = `\uE000${protectedFragments.length}\uE001`;
+        protectedFragments.push(html);
+        return token;
+    };
+    let value = protectTelegramFencedCode(markdown, protect);
+    value = value.replace(/`([^`\n]+)`/g, (_match, code) => (protect(`<code>${escapeTelegramHtml(String(code))}</code>`)));
+    value = escapeTelegramHtml(value);
+    value = value
+        .replace(/!\[([^\[\]]*)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, '$1')
+        .replace(/\[([^\[\]]+)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, (_match, label, href) => isSafeTelegramHref(href)
+        ? `<a href="${href}">${label}</a>`
+        : label)
+        .replace(/^#{1,6}\s+(.+)$/gm, '<b>$1</b>')
+        .replace(/^&gt;\s?(.*)$/gm, '<blockquote>$1</blockquote>')
+        .replace(/^\s*[-+*]\s+(.+)$/gm, '• $1')
+        .replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>')
+        .replace(/__([^_\n]+)__/g, '<b>$1</b>')
+        .replace(/~~([^~\n]+)~~/g, '<s>$1</s>')
+        .replace(/(^|[^*])\*([^*\n]+)\*/g, '$1<i>$2</i>')
+        .replace(/(^|[^_])_([^_\n]+)_/g, '$1<i>$2</i>');
+    for (let index = 0; index < protectedFragments.length; index += 1) {
+        value = value.replace(`\uE000${index}\uE001`, protectedFragments[index]);
+    }
+    return value;
+}
+function protectTelegramFencedCode(markdown, protect) {
+    const chunks = [];
+    let cursor = 0;
+    while (cursor < markdown.length) {
+        const opening = markdown.indexOf('```', cursor);
+        if (opening < 0) {
+            chunks.push(markdown.slice(cursor));
+            break;
+        }
+        chunks.push(markdown.slice(cursor, opening));
+        const contentStart = opening + 3;
+        const closing = markdown.indexOf('```', contentStart);
+        if (closing < 0) {
+            chunks.push(markdown.slice(opening));
+            break;
+        }
+        const newline = markdown.indexOf('\n', contentStart);
+        const hasHeader = newline >= 0 && newline < closing;
+        const language = markdown.slice(contentStart, hasHeader ? newline : closing).trim();
+        let code = hasHeader ? markdown.slice(newline + 1, closing) : '';
+        if (code.endsWith('\n'))
+            code = code.slice(0, -1);
+        const escapedCode = escapeTelegramHtml(code);
+        chunks.push(/^[A-Za-z0-9_+-]+$/.test(language)
+            ? protect(`<pre><code class="language-${language}">${escapedCode}</code></pre>`)
+            : protect(`<pre>${escapedCode}</pre>`));
+        cursor = closing + 3;
+    }
+    return chunks.join('');
+}
+function isSafeTelegramHref(value) {
+    return /^(?:https?:\/\/|tg:\/\/|mailto:)[^\s<>]+$/iu.test(value);
+}
+export function escapeTelegramHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}

package/lib/protocol.d.ts

@@ -153,6 +153,7 @@ export type TelegramOutboundAction = {
     readonly params: {
         readonly chat_id: number | string;
         readonly text: string;
+        readonly parse_mode?: 'HTML';
         readonly reply_parameters?: {
             readonly message_id: number;
         };
@@ -166,6 +167,7 @@ export type TelegramOutboundAction = {
         readonly chat_id: number | string;
         readonly photo: string;
         readonly caption?: string;
+        readonly parse_mode?: 'HTML';
         readonly reply_parameters?: {
             readonly message_id: number;
         };
@@ -176,6 +178,7 @@ export type TelegramOutboundAction = {
         readonly chat_id: number | string;
         readonly video: string;
         readonly caption?: string;
+        readonly parse_mode?: 'HTML';
         readonly reply_parameters?: {
             readonly message_id: number;
         };
@@ -186,6 +189,7 @@ export type TelegramOutboundAction = {
         readonly chat_id: number | string;
         readonly audio: string;
         readonly caption?: string;
+        readonly parse_mode?: 'HTML';
         readonly reply_parameters?: {
             readonly message_id: number;
         };
@@ -196,6 +200,7 @@ export type TelegramOutboundAction = {
         readonly chat_id: number | string;
         readonly voice: string;
         readonly caption?: string;
+        readonly parse_mode?: 'HTML';
         readonly reply_parameters?: {
             readonly message_id: number;
         };
@@ -206,6 +211,7 @@ export type TelegramOutboundAction = {
         readonly chat_id: number | string;
         readonly document: string;
         readonly caption?: string;
+        readonly parse_mode?: 'HTML';
         readonly reply_parameters?: {
             readonly message_id: number;
         };
@@ -249,7 +255,7 @@ export declare function senderDisplayName(user?: TelegramUser): string;
 export declare function formatInboundContent(msg: TelegramMessage): string;
 export declare function formatCallbackContent(query: TelegramCallbackQuery): string;
 /**
- * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 入站消息 → canonical Segment[]；媒体只存在于 canonical 段，不重复写入文本。
  * Telegram 附件只有不透明 file_id（需 getFile 二次解析，非 URL），
  * 统一进 MediaRef kind=file；photo 取数组末尾（最大尺寸）。
  */

package/lib/protocol.js

@@ -4,6 +4,7 @@
  */
 import { isMediaRef } from '@zhin.js/core';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.js';
 const logger = getLogger('telegram');
 export function resolveTelegramConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'telegram');
@@ -106,17 +107,6 @@ export function formatInboundContent(msg) {
         return msg.text;
     if (msg.caption)
         return msg.caption;
-    if (msg.photo?.length)
-        return '[image]';
-    if (msg.video)
-        return '[video]';
-    if (msg.audio)
-        return '[audio]';
-    if (msg.voice)
-        return '[voice]';
-    if (msg.document) {
-        return msg.document.file_name ? `[file: ${msg.document.file_name}]` : '[file]';
-    }
     if (msg.sticker) {
         return msg.sticker.emoji ? `[sticker: ${msg.sticker.emoji}]` : '[sticker]';
     }
@@ -129,7 +119,7 @@ export function formatCallbackContent(query) {
     return query.data ? `[action: ${query.data}]` : '[action]';
 }
 /**
- * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 入站消息 → canonical Segment[]；媒体只存在于 canonical 段，不重复写入文本。
  * Telegram 附件只有不透明 file_id（需 getFile 二次解析，非 URL），
  * 统一进 MediaRef kind=file；photo 取数组末尾（最大尺寸）。
  */
@@ -240,6 +230,11 @@ function buildOutboundActions(target, payload, uploads) {
         : payload && typeof payload === 'object' && 'type' in payload
             ? [payload]
             : [];
+    const hasMarkdown = items.some((item) => typeof item !== 'string' && item.type === 'markdown');
+    const appendPlain = (value) => hasMarkdown
+        ? escapeTelegramHtml(String(value ?? ''))
+        : String(value ?? '');
+    const htmlMode = hasMarkdown ? { parse_mode: 'HTML' } : {};
     if (items.length === 0) {
         const text = payload == null
             ? ''
@@ -300,17 +295,20 @@ function buildOutboundActions(target, payload, uploads) {
     };
     for (const item of items) {
         if (typeof item === 'string') {
-            textContent += item;
+            textContent += appendPlain(item);
             continue;
         }
         const data = item.data ?? {};
         switch (item.type) {
             case 'text':
-                textContent += String(data.text ?? data.content ?? '');
+                textContent += appendPlain(data.text ?? data.content ?? '');
+                break;
+            case 'markdown':
+                textContent += markdownToTelegramHtml(String(data.content ?? data.text ?? ''));
                 break;
             case 'at':
                 if (data.id)
-                    textContent += `@${String(data.name || data.id)}`;
+                    textContent += `@${appendPlain(data.name || data.id)}`;
                 break;
             case 'reply': {
                 const id = Number(data.id ?? data.message_id);
@@ -343,6 +341,7 @@ function buildOutboundActions(target, payload, uploads) {
                             chat_id: chatId,
                             photo,
                             caption: textContent.trim() || undefined,
+                            ...(textContent.trim() ? htmlMode : {}),
                             ...replyParams(),
                         },
                     });
@@ -359,6 +358,7 @@ function buildOutboundActions(target, payload, uploads) {
                             chat_id: chatId,
                             video,
                             caption: textContent.trim() || undefined,
+                            ...(textContent.trim() ? htmlMode : {}),
                             ...replyParams(),
                         },
                     });
@@ -375,6 +375,7 @@ function buildOutboundActions(target, payload, uploads) {
                             chat_id: chatId,
                             audio,
                             caption: textContent.trim() || undefined,
+                            ...(textContent.trim() ? htmlMode : {}),
                             ...replyParams(),
                         },
                     });
@@ -391,6 +392,7 @@ function buildOutboundActions(target, payload, uploads) {
                             chat_id: chatId,
                             voice,
                             caption: textContent.trim() || undefined,
+                            ...(textContent.trim() ? htmlMode : {}),
                             ...replyParams(),
                         },
                     });
@@ -407,6 +409,7 @@ function buildOutboundActions(target, payload, uploads) {
                             chat_id: chatId,
                             document,
                             caption: textContent.trim() || undefined,
+                            ...(textContent.trim() ? htmlMode : {}),
                             ...replyParams(),
                         },
                     });
@@ -437,7 +440,7 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             default:
-                textContent += String(data.text ?? `[${item.type}]`);
+                textContent += appendPlain(data.text ?? `[${item.type}]`);
         }
     }
     if (actions.length === 0) {
@@ -449,6 +452,7 @@ function buildOutboundActions(target, payload, uploads) {
                 params: {
                     chat_id: chatId,
                     text: text || ' ',
+                    ...htmlMode,
                     ...replyParams(),
                     ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
                 },
@@ -460,6 +464,7 @@ function buildOutboundActions(target, payload, uploads) {
             params: {
                 chat_id: chatId,
                 text: textContent.trim() || ' ',
+                ...htmlMode,
                 ...replyParams(),
                 ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "7.0.12",
+  "version": "7.0.14",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,20 +32,20 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/core": "1.5.10",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/adapter": "1.1.11",
+    "@zhin.js/core": "1.5.12",
+    "@zhin.js/host-http": "1.0.11",
+    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/logger": "1.0.76"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/agent": "1.1.12",
-    "@zhin.js/command": "1.0.14",
-    "@zhin.js/core": "1.5.10",
-    "@zhin.js/permission": "1.0.2",
-    "zhin.js": "6.0.10"
+    "@zhin.js/adapter": "1.1.11",
+    "@zhin.js/agent": "1.1.14",
+    "@zhin.js/command": "1.0.15",
+    "@zhin.js/core": "1.5.12",
+    "@zhin.js/permission": "1.0.3",
+    "zhin.js": "6.0.12"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -66,9 +66,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.12",
-    "@zhin.js/host-http": "1.0.10",
-    "zhin.js": "6.0.10"
+    "@zhin.js/agent": "1.1.14",
+    "@zhin.js/host-http": "1.0.11",
+    "zhin.js": "6.0.12"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -2,11 +2,13 @@
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
  */
 import { readFile } from 'node:fs/promises';
-import type { EndpointControl, EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { EndpointContentPort, EndpointContentResolveContext, EndpointControl, EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import {
   type ConversationRef,
+  type ConversationReference,
+  type ConversationResolution,
   type MessageRef,
 } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
@@ -56,11 +58,14 @@ export type TelegramFetch = (
   readonly status: number;
   text(): Promise<string>;
   json(): Promise<unknown>;
+  arrayBuffer?(): Promise<ArrayBuffer>;
+  readonly headers?: { get(name: string): string | null };
 }>;
 
 export interface TelegramEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly config: ResolvedTelegramConfig;
   readonly http?: HttpHost;
   readonly fetch?: TelegramFetch;
@@ -100,6 +105,9 @@ export class TelegramEndpoint implements EndpointInstance {
   readonly control: EndpointControl = Object.freeze({
     recall: (message: MessageRef) => this.recallMessage(message),
   });
+  readonly content: EndpointContentPort = Object.freeze({
+    resolve: (reference: ConversationReference, context: EndpointContentResolveContext) => this.#resolveContent(reference, context.signal),
+  });
 
   constructor(options: TelegramEndpointOptions) {
     this.#logger = getAdapterLogger('telegram', options.config.id);
@@ -229,6 +237,50 @@ export class TelegramEndpoint implements EndpointInstance {
     });
   }
 
+  async #resolveContent(
+    reference: Parameters<EndpointContentPort['resolve']>[0],
+    signal: AbortSignal,
+  ): Promise<ConversationResolution> {
+    if (reference.kind !== 'media') {
+      return Object.freeze({ status: 'unsupported', code: 'telegram_message_lookup_unavailable' });
+    }
+    if (reference.media.kind !== 'file') {
+      return Object.freeze({ status: 'resolved', reference, value: reference.media });
+    }
+    try {
+      signal.throwIfAborted();
+      const file = await this.callApi<{ file_path?: string; file_size?: number }>('getFile', {
+        file_id: reference.media.value,
+      });
+      if (!file.file_path) return Object.freeze({ status: 'not_found', code: 'telegram_file_not_found' });
+      if ((file.file_size ?? 0) > 26_214_400) return Object.freeze({ status: 'forbidden', code: 'media_size_limit' });
+      const response = await this.#fetch(
+        `${this.#options.config.apiBaseUrl}/file/bot${this.#options.config.token}/${file.file_path}`,
+        { signal },
+      );
+      if (!response.ok) return Object.freeze({ status: 'failed', code: 'telegram_file_download_failed' });
+      if (!response.arrayBuffer) return Object.freeze({ status: 'failed', code: 'telegram_binary_transport_unavailable' });
+      const bytes = Buffer.from(await response.arrayBuffer());
+      if (bytes.byteLength > 26_214_400) return Object.freeze({ status: 'forbidden', code: 'media_size_limit' });
+      return Object.freeze({
+        status: 'resolved',
+        reference,
+        value: Object.freeze({
+          kind: 'base64',
+          value: bytes.toString('base64'),
+          ...(response.headers?.get('content-type')?.split(';')[0] || reference.media.mime_type
+            ? { mime_type: response.headers?.get('content-type')?.split(';')[0] ?? reference.media.mime_type }
+            : {}),
+          ...(reference.media.file_name ? { file_name: reference.media.file_name } : {}),
+          size: bytes.byteLength,
+        }),
+      });
+    } catch (error) {
+      if (signal.aborted) return Object.freeze({ status: 'expired', code: 'turn_aborted' });
+      return Object.freeze({ status: 'failed', code: 'telegram_file_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
   /**
    * 含 `attach://` 占位的媒体参数 → multipart/form-data：
    * 标量参数原样、对象参数 JSON 序列化、attach 占位替换为文件 part

package/src/markdown-to-html.ts

@@ -0,0 +1,86 @@
+/**
+ * Canonical Markdown → Telegram Bot API HTML.
+ *
+ * Telegram's MarkdownV2 is not CommonMark-compatible and rejects unescaped
+ * punctuation. HTML gives the adapter a safer dialect seam: user text is
+ * escaped first and only the subset supported by Bot API is emitted as tags.
+ */
+export function markdownToTelegramHtml(markdown: string): string {
+  const protectedFragments: string[] = [];
+  const protect = (html: string): string => {
+    const token = `\uE000${protectedFragments.length}\uE001`;
+    protectedFragments.push(html);
+    return token;
+  };
+
+  let value = protectTelegramFencedCode(markdown, protect);
+  value = value.replace(/`([^`\n]+)`/g, (_match, code) => (
+    protect(`<code>${escapeTelegramHtml(String(code))}</code>`)
+  ));
+  value = escapeTelegramHtml(value);
+
+  value = value
+    .replace(/!\[([^\[\]]*)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, '$1')
+    .replace(/\[([^\[\]]+)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g,
+      (_match, label: string, href: string) => isSafeTelegramHref(href)
+        ? `<a href="${href}">${label}</a>`
+        : label)
+    .replace(/^#{1,6}\s+(.+)$/gm, '<b>$1</b>')
+    .replace(/^&gt;\s?(.*)$/gm, '<blockquote>$1</blockquote>')
+    .replace(/^\s*[-+*]\s+(.+)$/gm, '• $1')
+    .replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>')
+    .replace(/__([^_\n]+)__/g, '<b>$1</b>')
+    .replace(/~~([^~\n]+)~~/g, '<s>$1</s>')
+    .replace(/(^|[^*])\*([^*\n]+)\*/g, '$1<i>$2</i>')
+    .replace(/(^|[^_])_([^_\n]+)_/g, '$1<i>$2</i>');
+
+  for (let index = 0; index < protectedFragments.length; index += 1) {
+    value = value.replace(`\uE000${index}\uE001`, protectedFragments[index]!);
+  }
+  return value;
+}
+
+function protectTelegramFencedCode(
+  markdown: string,
+  protect: (html: string) => string,
+): string {
+  const chunks: string[] = [];
+  let cursor = 0;
+  while (cursor < markdown.length) {
+    const opening = markdown.indexOf('```', cursor);
+    if (opening < 0) {
+      chunks.push(markdown.slice(cursor));
+      break;
+    }
+    chunks.push(markdown.slice(cursor, opening));
+    const contentStart = opening + 3;
+    const closing = markdown.indexOf('```', contentStart);
+    if (closing < 0) {
+      chunks.push(markdown.slice(opening));
+      break;
+    }
+    const newline = markdown.indexOf('\n', contentStart);
+    const hasHeader = newline >= 0 && newline < closing;
+    const language = markdown.slice(contentStart, hasHeader ? newline : closing).trim();
+    let code = hasHeader ? markdown.slice(newline + 1, closing) : '';
+    if (code.endsWith('\n')) code = code.slice(0, -1);
+    const escapedCode = escapeTelegramHtml(code);
+    chunks.push(/^[A-Za-z0-9_+-]+$/.test(language)
+      ? protect(`<pre><code class="language-${language}">${escapedCode}</code></pre>`)
+      : protect(`<pre>${escapedCode}</pre>`));
+    cursor = closing + 3;
+  }
+  return chunks.join('');
+}
+
+function isSafeTelegramHref(value: string): boolean {
+  return /^(?:https?:\/\/|tg:\/\/|mailto:)[^\s<>]+$/iu.test(value);
+}
+
+export function escapeTelegramHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/src/protocol.ts

@@ -8,6 +8,7 @@ import { isMediaRef } from '@zhin.js/core';
 import type { Segment } from '@zhin.js/core/runtime';
 import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.js';
 
 const logger = getLogger('telegram');
 
@@ -172,6 +173,7 @@ export type TelegramOutboundAction =
     readonly params: {
       readonly chat_id: number | string;
       readonly text: string;
+      readonly parse_mode?: 'HTML';
       readonly reply_parameters?: { readonly message_id: number };
       readonly reply_markup?: { readonly inline_keyboard: TelegramInlineButton[][] };
     };
@@ -182,6 +184,7 @@ export type TelegramOutboundAction =
       readonly chat_id: number | string;
       readonly photo: string;
       readonly caption?: string;
+      readonly parse_mode?: 'HTML';
       readonly reply_parameters?: { readonly message_id: number };
     };
   }
@@ -191,6 +194,7 @@ export type TelegramOutboundAction =
       readonly chat_id: number | string;
       readonly video: string;
       readonly caption?: string;
+      readonly parse_mode?: 'HTML';
       readonly reply_parameters?: { readonly message_id: number };
     };
   }
@@ -200,6 +204,7 @@ export type TelegramOutboundAction =
       readonly chat_id: number | string;
       readonly audio: string;
       readonly caption?: string;
+      readonly parse_mode?: 'HTML';
       readonly reply_parameters?: { readonly message_id: number };
     };
   }
@@ -209,6 +214,7 @@ export type TelegramOutboundAction =
       readonly chat_id: number | string;
       readonly voice: string;
       readonly caption?: string;
+      readonly parse_mode?: 'HTML';
       readonly reply_parameters?: { readonly message_id: number };
     };
   }
@@ -218,6 +224,7 @@ export type TelegramOutboundAction =
       readonly chat_id: number | string;
       readonly document: string;
       readonly caption?: string;
+      readonly parse_mode?: 'HTML';
       readonly reply_parameters?: { readonly message_id: number };
     };
   }
@@ -355,13 +362,6 @@ export function senderDisplayName(user?: TelegramUser): string {
 export function formatInboundContent(msg: TelegramMessage): string {
   if (msg.text) return msg.text;
   if (msg.caption) return msg.caption;
-  if (msg.photo?.length) return '[image]';
-  if (msg.video) return '[video]';
-  if (msg.audio) return '[audio]';
-  if (msg.voice) return '[voice]';
-  if (msg.document) {
-    return msg.document.file_name ? `[file: ${msg.document.file_name}]` : '[file]';
-  }
   if (msg.sticker) {
     return msg.sticker.emoji ? `[sticker: ${msg.sticker.emoji}]` : '[sticker]';
   }
@@ -376,7 +376,7 @@ export function formatCallbackContent(query: TelegramCallbackQuery): string {
 }
 
 /**
- * 入站消息 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 入站消息 → canonical Segment[]；媒体只存在于 canonical 段，不重复写入文本。
  * Telegram 附件只有不透明 file_id（需 getFile 二次解析，非 URL），
  * 统一进 MediaRef kind=file；photo 取数组末尾（最大尺寸）。
  */
@@ -518,6 +518,11 @@ function buildOutboundActions(
     : payload && typeof payload === 'object' && 'type' in (payload as object)
       ? [payload as TelegramWireSegment]
       : [];
+  const hasMarkdown = items.some((item) => typeof item !== 'string' && item.type === 'markdown');
+  const appendPlain = (value: unknown): string => hasMarkdown
+    ? escapeTelegramHtml(String(value ?? ''))
+    : String(value ?? '');
+  const htmlMode = hasMarkdown ? { parse_mode: 'HTML' as const } : {};
 
   if (items.length === 0) {
     const text = payload == null
@@ -583,16 +588,19 @@ function buildOutboundActions(
 
   for (const item of items) {
     if (typeof item === 'string') {
-      textContent += item;
+      textContent += appendPlain(item);
       continue;
     }
     const data = item.data ?? {};
     switch (item.type) {
       case 'text':
-        textContent += String(data.text ?? data.content ?? '');
+        textContent += appendPlain(data.text ?? data.content ?? '');
+        break;
+      case 'markdown':
+        textContent += markdownToTelegramHtml(String(data.content ?? data.text ?? ''));
         break;
       case 'at':
-        if (data.id) textContent += `@${String(data.name || data.id)}`;
+        if (data.id) textContent += `@${appendPlain(data.name || data.id)}`;
         break;
       case 'reply': {
         const id = Number(data.id ?? data.message_id);
@@ -624,6 +632,7 @@ function buildOutboundActions(
               chat_id: chatId,
               photo,
               caption: textContent.trim() || undefined,
+              ...(textContent.trim() ? htmlMode : {}),
               ...replyParams(),
             },
           });
@@ -640,6 +649,7 @@ function buildOutboundActions(
               chat_id: chatId,
               video,
               caption: textContent.trim() || undefined,
+              ...(textContent.trim() ? htmlMode : {}),
               ...replyParams(),
             },
           });
@@ -656,6 +666,7 @@ function buildOutboundActions(
               chat_id: chatId,
               audio,
               caption: textContent.trim() || undefined,
+              ...(textContent.trim() ? htmlMode : {}),
               ...replyParams(),
             },
           });
@@ -672,6 +683,7 @@ function buildOutboundActions(
               chat_id: chatId,
               voice,
               caption: textContent.trim() || undefined,
+              ...(textContent.trim() ? htmlMode : {}),
               ...replyParams(),
             },
           });
@@ -688,6 +700,7 @@ function buildOutboundActions(
               chat_id: chatId,
               document,
               caption: textContent.trim() || undefined,
+              ...(textContent.trim() ? htmlMode : {}),
               ...replyParams(),
             },
           });
@@ -718,7 +731,7 @@ function buildOutboundActions(
         break;
       }
       default:
-        textContent += String(data.text ?? `[${item.type}]`);
+        textContent += appendPlain(data.text ?? `[${item.type}]`);
     }
   }
 
@@ -730,6 +743,7 @@ function buildOutboundActions(
       params: {
         chat_id: chatId,
         text: text || ' ',
+        ...htmlMode,
         ...replyParams(),
         ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
       },
@@ -742,6 +756,7 @@ function buildOutboundActions(
       params: {
         chat_id: chatId,
         text: textContent.trim() || ' ',
+        ...htmlMode,
         ...replyParams(),
         ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
       },