@foxden-app/foxclaw 0.5.32 → 0.5.34

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.5.34 - 2026-06-17
+
+### 中文
+- 普通 Codex 输出接入 Telegram RichMessage：流式阶段继续稳定发送纯文本，segment 完成后自动把已发消息编辑为富文本，支持标题、列表、引用、代码块、行内 code、粗体和安全链接。
+- draft 流式路径优先使用官方 `sendRichMessageDraft`，发送失败时对当前 turn 自动熔断回原纯文本 draft，避免影响实时输出。
+- 新增 Markdown 到 RichMessage HTML 的安全转换与回归测试，保留 Telegram/微信 fallback：RichMessage 失败时不会破坏原纯文本输出，微信继续使用原 HTML/plain 降级通道。
+
+### English
+- Wired normal Codex output into Telegram RichMessage: live streaming still sends stable plain text, then completed segments are edited into rich text with headings, lists, quotes, fenced code, inline code, bold text, and safe links.
+- Draft streaming now prefers the official `sendRichMessageDraft` API and automatically disables rich drafts for the current turn if it fails, preserving the previous plain draft behavior.
+- Added a safe Markdown-to-RichMessage HTML renderer with regression coverage while preserving Telegram/Weixin fallbacks so RichMessage failures do not break existing output.
+
+## 0.5.33 - 2026-06-16
+
+### 中文
+- 新增 Telegram Rich Message 适配专项盘点，明确现有 HTML 通道、Bot API 10.1 rich message 能力、FoxClaw 可用功能面和分阶段接入路线。
+- 接入 `sendRichMessage` / rich HTML 发送链路，新增 `/rich` 诊断命令用于在 Telegram 客户端直接查看 heading、table、details、pre/code、list 的 RichMessage 渲染效果。
+- 集中 Telegram HTML 转义与常用标签 helper，并把 `/diff` 改为优先使用 RichMessage details + diff code block；发送失败时回退到原 Telegram HTML 折叠展示。
+
+### English
+- Added a Telegram Rich Message adaptation check covering the current HTML path, Bot API 10.1 rich message capabilities, FoxClaw candidate surfaces, and a phased rollout plan.
+- Wired the `sendRichMessage` / rich HTML send path and added `/rich` as a diagnostic command for checking heading, table, details, pre/code, and list rendering in Telegram clients.
+- Centralized Telegram HTML escaping/tag helpers and changed `/diff` to prefer RichMessage details plus a diff code block, falling back to the previous Telegram HTML collapsible rendering if rich sending fails.
+
 ## 0.5.32 - 2026-06-11
 
 ### 中文

package/dist/channels/bridge_messaging_router.d.ts

@@ -15,12 +15,15 @@ export declare class BridgeMessagingRouter {
     private requireWeixinTransport;
     sendPlain(scopeId: string, text: string, keyboard?: InlineKeyboard): Promise<number>;
     sendHtml(scopeId: string, text: string, keyboard?: InlineKeyboard): Promise<number>;
+    sendRichHtml(scopeId: string, html: string, fallbackHtml: string, keyboard?: InlineKeyboard): Promise<number>;
     editPlain(scopeId: string, messageId: number, text: string, keyboard?: InlineKeyboard): Promise<void>;
     editHtml(scopeId: string, messageId: number, text: string, keyboard?: InlineKeyboard): Promise<void>;
+    editRichHtml(scopeId: string, messageId: number, html: string, fallbackHtml: string, keyboard?: InlineKeyboard): Promise<void>;
     deleteMessage(scopeId: string, messageId: number): Promise<void>;
     sendTypingInScope(scopeId: string): Promise<void>;
     clearInlineKeyboard(scopeId: string, messageId: number): Promise<void>;
     sendDraft(scopeId: string, draftId: number, text: string): Promise<void>;
+    sendRichDraft(scopeId: string, draftId: number, html: string, fallbackText: string): Promise<void>;
     answerCallback(callbackQueryId: string, text: string): Promise<void>;
     getFile(fileId: string): Promise<TelegramRemoteFile>;
     downloadResolvedFile(remoteFilePath: string, destinationPath: string): Promise<number>;

package/dist/channels/bridge_messaging_router.js

@@ -37,6 +37,12 @@ export class BridgeMessagingRouter {
         }
         return this.telegram.sendHtml(scopeId, text, keyboard);
     }
+    sendRichHtml(scopeId, html, fallbackHtml, keyboard) {
+        if (this.isWeixinScope(scopeId)) {
+            return this.requireWeixinTransport(scopeId).sendHtml(scopeId, fallbackHtml, keyboard);
+        }
+        return this.telegram.sendRichHtml(scopeId, html, keyboard);
+    }
     editPlain(scopeId, messageId, text, keyboard) {
         if (this.isWeixinScope(scopeId)) {
             return this.requireWeixinTransport(scopeId).editPlain(scopeId, messageId, text, keyboard);
@@ -49,6 +55,12 @@ export class BridgeMessagingRouter {
         }
         return this.telegram.editHtml(scopeId, messageId, text, keyboard);
     }
+    editRichHtml(scopeId, messageId, html, fallbackHtml, keyboard) {
+        if (this.isWeixinScope(scopeId)) {
+            return this.requireWeixinTransport(scopeId).editHtml(scopeId, messageId, fallbackHtml, keyboard);
+        }
+        return this.telegram.editRichHtml(scopeId, messageId, html, keyboard);
+    }
     deleteMessage(scopeId, messageId) {
         if (this.isWeixinScope(scopeId)) {
             return this.requireWeixinTransport(scopeId).deleteMessage(scopeId, messageId);
@@ -73,6 +85,12 @@ export class BridgeMessagingRouter {
         }
         return this.telegram.sendDraft(scopeId, draftId, text);
     }
+    sendRichDraft(scopeId, draftId, html, fallbackText) {
+        if (this.isWeixinScope(scopeId)) {
+            return this.requireWeixinTransport(scopeId).sendDraft(scopeId, draftId, fallbackText);
+        }
+        return this.telegram.sendRichDraft(scopeId, draftId, html);
+    }
     answerCallback(callbackQueryId, text) {
         return this.telegram.answerCallback(callbackQueryId, text);
     }

package/dist/channels/telegram/telegram_messaging_port.d.ts

@@ -13,12 +13,15 @@ export declare class TelegramMessagingPort implements ChannelPort {
     constructor(gateway: TelegramGateway);
     sendPlain(bridgeScopeId: string, text: string, inlineKeyboard?: InlineKeyboard): Promise<number>;
     sendHtml(bridgeScopeId: string, text: string, inlineKeyboard?: InlineKeyboard): Promise<number>;
+    sendRichHtml(bridgeScopeId: string, html: string, inlineKeyboard?: InlineKeyboard): Promise<number>;
     editPlain(bridgeScopeId: string, messageId: number, text: string, inlineKeyboard?: InlineKeyboard): Promise<void>;
     editHtml(bridgeScopeId: string, messageId: number, text: string, inlineKeyboard?: InlineKeyboard): Promise<void>;
+    editRichHtml(bridgeScopeId: string, messageId: number, html: string, inlineKeyboard?: InlineKeyboard): Promise<void>;
     deleteMessage(bridgeScopeId: string, messageId: number): Promise<void>;
     sendTypingInScope(bridgeScopeId: string): Promise<void>;
     clearInlineKeyboard(bridgeScopeId: string, messageId: number): Promise<void>;
     sendDraft(bridgeScopeId: string, draftId: number, text: string): Promise<void>;
+    sendRichDraft(bridgeScopeId: string, draftId: number, html: string): Promise<void>;
     answerCallback(callbackQueryId: string, text: string): Promise<void>;
     getFile(fileId: string): Promise<TelegramRemoteFile>;
     downloadResolvedFile(remoteFilePath: string, destinationPath: string): Promise<number>;

package/dist/channels/telegram/telegram_messaging_port.js

@@ -1,4 +1,5 @@
 import { parseTelegramTargetFromBridgeScope } from '../../core/bridge_scope.js';
+import { telegramRichHtml } from '../../telegram/rich.js';
 /**
  * Telegram outbound operations addressed by bridge scope id (`telegram:…`).
  */
@@ -15,6 +16,10 @@ export class TelegramMessagingPort {
         const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
         return this.gateway.sendHtmlMessage(target.chatId, text, inlineKeyboard, target.topicId);
     }
+    async sendRichHtml(bridgeScopeId, html, inlineKeyboard) {
+        const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
+        return this.gateway.sendRichMessage(target.chatId, telegramRichHtml(html, { skipEntityDetection: true }), inlineKeyboard, target.topicId);
+    }
     async editPlain(bridgeScopeId, messageId, text, inlineKeyboard) {
         const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
         await this.gateway.editMessage(target.chatId, messageId, text, inlineKeyboard);
@@ -23,6 +28,10 @@ export class TelegramMessagingPort {
         const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
         await this.gateway.editHtmlMessage(target.chatId, messageId, text, inlineKeyboard);
     }
+    async editRichHtml(bridgeScopeId, messageId, html, inlineKeyboard) {
+        const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
+        await this.gateway.editRichMessage(target.chatId, messageId, telegramRichHtml(html, { skipEntityDetection: true }), inlineKeyboard);
+    }
     async deleteMessage(bridgeScopeId, messageId) {
         const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
         await this.gateway.deleteMessage(target.chatId, messageId);
@@ -39,6 +48,10 @@ export class TelegramMessagingPort {
         const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
         await this.gateway.sendMessageDraft(target.chatId, draftId, text, target.topicId);
     }
+    async sendRichDraft(bridgeScopeId, draftId, html) {
+        const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
+        await this.gateway.sendRichMessageDraft(target.chatId, draftId, telegramRichHtml(html, { skipEntityDetection: true }), target.topicId);
+    }
     answerCallback(callbackQueryId, text) {
         return this.gateway.answerCallback(callbackQueryId, text);
     }

package/dist/controller/controller.d.ts

@@ -227,8 +227,11 @@ export declare class BridgeSessionCore {
     private updateStatus;
     private sendMessage;
     private sendHtmlMessage;
+    private sendRichHtmlMessage;
+    private sendRichMarkdownMessage;
     private editMessage;
     private editHtmlMessage;
+    private editRichHtmlMessage;
     private deleteMessage;
     private sendTyping;
     private sendObservedCliUserMessage;
@@ -318,6 +321,7 @@ export declare class BridgeSessionCore {
     private handleArchiveCommand;
     private handleUnarchiveCommand;
     private handleReviewCommand;
+    private handleRichCommand;
     private handleDiffCommand;
     private handleLoadedCommand;
     private handleSkillsCommand;
@@ -436,6 +440,7 @@ export declare class BridgeSessionCore {
     private forgetPreviewRecord;
     private clearMessageButtons;
     private sendDraft;
+    private sendRichDraft;
     private renderActiveStatus;
     private dismissTurnPreview;
     private ensureStatusMessage;
@@ -456,5 +461,7 @@ export declare class BridgeSessionCore {
     private findActiveTurnByThreadId;
     private findActiveTurnsByThreadId;
     private syncSegmentTimeline;
+    private shouldPromoteSegmentToRich;
+    private promoteSegmentMessagesToRich;
 }
 export { BridgeSessionCore as BridgeController };

package/dist/controller/controller.js

@@ -9,6 +9,9 @@ import { buildAccessSettingsKeyboard, buildModelSettingsKeyboard, buildSetupPane
 import { clampServiceTierToModel, resolveFastTierForModel } from './service_tier.js';
 import { TELEGRAM_BOT_API_DOWNLOAD_LIMIT_BYTES, buildAttachmentPrompt, isNativeImageAttachment, planAttachmentStoragePath, summarizeTelegramInput, } from '../telegram/media.js';
 import { TELEGRAM_MESSAGE_LIMIT, chunkTelegramMessage, chunkTelegramStreamMessage, clipTelegramDraftMessage, } from '../telegram/text.js';
+import { escapeTelegramHtml, telegramBold, telegramDetails, telegramExpandableBlockquote, telegramPre, telegramPreCode, } from '../telegram/html.js';
+import { TELEGRAM_RICH_MESSAGE_TEXT_LIMIT } from '../telegram/rich.js';
+import { renderTelegramMarkdownRichHtml } from '../telegram/rich_markdown.js';
 import { isDefaultTelegramScope, resolveTelegramAddressing } from '../telegram/addressing.js';
 import { BRIDGE_SCOPE_WEIXIN_PREFIX, parseTelegramTargetFromBridgeScope, parseWeixinBridgeScope } from '../core/bridge_scope.js';
 import { resolveTelegramRenderRoute } from '../telegram/rendering.js';
@@ -50,6 +53,7 @@ const PINNED_HELP_COMMANDS = [
 const DYNAMIC_HELP_COMMANDS = [
     { key: 'fast', line: '/fast <on|off|toggle>' },
     { key: 'active', line: '/active <steer|queue>' },
+    { key: 'rich', line: '/rich' },
     { key: 'account', line: '/account' },
     { key: 'quota', line: '/quota' },
     { key: 'update', line: '/update' },
@@ -717,6 +721,10 @@ export class BridgeSessionCore {
                 await this.handleReviewCommand(event, locale, args);
                 return;
             }
+            case 'rich': {
+                await this.handleRichCommand(scopeId, locale);
+                return;
+            }
             case 'diff': {
                 await this.handleDiffCommand(scopeId, locale);
                 return;
@@ -2923,6 +2931,7 @@ export class BridgeSessionCore {
             previewActive: previewMessageId > 0,
             draftId: null,
             draftText: null,
+            richDraftDisabled: false,
             buffer: '',
             finalText: null,
             interruptRequested: false,
@@ -3126,7 +3135,7 @@ export class BridgeSessionCore {
                 const fallbackKey = active.interruptRequested ? 'interrupted' : 'completed';
                 const finalChunks = chunkTelegramMessage(active.finalText || active.buffer, undefined, t(locale, fallbackKey));
                 for (const chunk of finalChunks) {
-                    await this.sendMessage(active.scopeId, chunk);
+                    await this.sendRichMarkdownMessage(active.scopeId, chunk);
                 }
             }
             shouldMarkPartialOutput = active.interruptRequested
@@ -3356,12 +3365,33 @@ export class BridgeSessionCore {
     async sendHtmlMessage(scopeId, text, inlineKeyboard) {
         return this.messaging.sendHtml(scopeId, text, inlineKeyboard);
     }
+    async sendRichHtmlMessage(scopeId, html, fallbackHtml, inlineKeyboard) {
+        try {
+            return await this.messaging.sendRichHtml(scopeId, html, fallbackHtml, inlineKeyboard);
+        }
+        catch (error) {
+            this.logger.warn('telegram.rich_message_send_failed', { scopeId, error: toErrorMeta(error) });
+            return this.sendHtmlMessage(scopeId, fallbackHtml, inlineKeyboard);
+        }
+    }
+    async sendRichMarkdownMessage(scopeId, text, inlineKeyboard) {
+        return this.sendRichHtmlMessage(scopeId, renderTelegramMarkdownRichHtml(text), escapeTelegramHtml(text), inlineKeyboard);
+    }
     async editMessage(scopeId, messageId, text, inlineKeyboard) {
         await this.messaging.editPlain(scopeId, messageId, text, inlineKeyboard);
     }
     async editHtmlMessage(scopeId, messageId, text, inlineKeyboard) {
         await this.messaging.editHtml(scopeId, messageId, text, inlineKeyboard);
     }
+    async editRichHtmlMessage(scopeId, messageId, html, fallbackHtml, inlineKeyboard) {
+        try {
+            await this.messaging.editRichHtml(scopeId, messageId, html, fallbackHtml, inlineKeyboard);
+        }
+        catch (error) {
+            this.logger.warn('telegram.rich_message_edit_failed', { scopeId, messageId, error: toErrorMeta(error) });
+            await this.editHtmlMessage(scopeId, messageId, fallbackHtml, inlineKeyboard);
+        }
+    }
     async deleteMessage(scopeId, messageId) {
         await this.messaging.deleteMessage(scopeId, messageId);
     }
@@ -3373,8 +3403,8 @@ export class BridgeSessionCore {
         for (let index = 0; index < chunks.length; index += 1) {
             const chunk = chunks[index];
             const body = index === 0
-                ? `<b>${escapeTelegramHtml(OBSERVED_CLI_USER_LABEL)}</b>\n<pre>${escapeTelegramHtml(chunk)}</pre>`
-                : `<pre>${escapeTelegramHtml(chunk)}</pre>`;
+                ? `${telegramBold(OBSERVED_CLI_USER_LABEL)}\n${telegramPre(chunk)}`
+                : telegramPre(chunk);
             await this.sendHtmlMessage(scopeId, body);
         }
     }
@@ -5052,13 +5082,16 @@ export class BridgeSessionCore {
             await this.registerActiveTurn(event.scopeId, event.chatId, event.chatType, event.topicId, result.reviewThreadId, result.turnId, 0);
         }
     }
+    async handleRichCommand(scopeId, locale) {
+        await this.sendRichHtmlMessage(scopeId, formatRichDemoMessage(locale), formatRichDemoFallbackMessage(locale));
+    }
     async handleDiffCommand(scopeId, locale) {
         const diff = this.latestTurnDiffs.get(scopeId);
         if (!diff?.diff.trim()) {
             await this.sendMessage(scopeId, t(locale, 'diff_unavailable'));
             return;
         }
-        await this.sendMessage(scopeId, formatDiffMessage(locale, diff.diff));
+        await this.sendRichHtmlMessage(scopeId, formatRichDiffMessage(locale, diff.diff), formatDiffMessage(locale, diff.diff));
     }
     async handleLoadedCommand(scopeId, locale) {
         const threadIds = await this.app.listLoadedThreads();
@@ -7591,6 +7624,9 @@ export class BridgeSessionCore {
     async sendDraft(scopeId, draftId, text) {
         await this.messaging.sendDraft(scopeId, draftId, text);
     }
+    async sendRichDraft(scopeId, draftId, html, fallbackText) {
+        await this.messaging.sendRichDraft(scopeId, draftId, html, fallbackText);
+    }
     renderActiveStatus(active) {
         const locale = this.localeForChat(active.scopeId);
         return renderActiveTurnStatus(locale, {
@@ -7836,12 +7872,34 @@ export class BridgeSessionCore {
             active.draftId = crypto.randomInt(1, 2_147_483_647);
         }
         try {
-            await this.sendDraft(active.scopeId, active.draftId, draftText);
+            if (active.richDraftDisabled) {
+                await this.sendDraft(active.scopeId, active.draftId, draftText);
+            }
+            else {
+                await this.sendRichDraft(active.scopeId, active.draftId, renderTelegramMarkdownRichHtml(draftText), draftText);
+            }
             active.draftText = draftText;
         }
         catch (error) {
+            let finalError = error;
+            if (!active.richDraftDisabled) {
+                active.richDraftDisabled = true;
+                this.logger.warn('telegram.rich_draft_send_failed', {
+                    error: String(finalError),
+                    turnId: active.turnId,
+                    draftId: active.draftId,
+                });
+                try {
+                    await this.sendDraft(active.scopeId, active.draftId, draftText);
+                    active.draftText = draftText;
+                    return;
+                }
+                catch (fallbackError) {
+                    finalError = fallbackError;
+                }
+            }
             this.logger.warn('telegram.draft_send_failed', {
-                error: String(error),
+                error: String(finalError),
                 turnId: active.turnId,
                 draftId: active.draftId,
             });
@@ -7876,7 +7934,7 @@ export class BridgeSessionCore {
             if (!existing) {
                 try {
                     const messageId = await this.sendMessage(active.scopeId, chunk);
-                    segment.messages.push({ messageId, text: chunk });
+                    segment.messages.push({ messageId, text: chunk, richHtml: null, richFailedForText: null });
                     active.statusNeedsRebase = true;
                 }
                 catch (error) {
@@ -7899,6 +7957,8 @@ export class BridgeSessionCore {
             try {
                 await this.editMessage(active.scopeId, existing.messageId, chunk);
                 existing.text = chunk;
+                existing.richHtml = null;
+                existing.richFailedForText = null;
                 index += 1;
             }
             catch (error) {
@@ -7936,6 +7996,47 @@ export class BridgeSessionCore {
                 }
             }
         }
+        if (this.shouldPromoteSegmentToRich(active, segment)) {
+            await this.promoteSegmentMessagesToRich(active, segment, chunks);
+        }
+    }
+    shouldPromoteSegmentToRich(active, segment) {
+        return !active.scopeId.startsWith(BRIDGE_SCOPE_WEIXIN_PREFIX)
+            && segment.completed
+            && segment.outputKind !== 'error'
+            && Boolean(segment.text.trim());
+    }
+    async promoteSegmentMessagesToRich(active, segment, chunks) {
+        for (let index = 0; index < chunks.length; index += 1) {
+            const chunk = chunks[index];
+            const existing = segment.messages[index];
+            if (!existing || !chunk.trim()) {
+                continue;
+            }
+            const richHtml = renderTelegramMarkdownRichHtml(chunk);
+            if (existing.richHtml === richHtml || existing.richFailedForText === chunk) {
+                continue;
+            }
+            try {
+                await this.messaging.editRichHtml(active.scopeId, existing.messageId, richHtml, escapeTelegramHtml(chunk));
+                existing.richHtml = richHtml;
+                existing.richFailedForText = null;
+            }
+            catch (error) {
+                if (isTelegramMessageGone(error)) {
+                    segment.messages.splice(index);
+                    return;
+                }
+                existing.richFailedForText = chunk;
+                this.logger.warn('telegram.stream_rich_edit_failed', {
+                    error: String(error),
+                    turnId: active.turnId,
+                    itemId: segment.itemId,
+                    messageId: existing.messageId,
+                    chunkIndex: index,
+                });
+            }
+        }
     }
 }
 function ensureTurnSegment(active, itemId, phase, outputKind, isPlan) {
@@ -7990,10 +8091,9 @@ function renderArchivedToolBatchStatus(locale, counts, actionLines) {
         return { text, html: null };
     }
     const heading = formatToolBatchHeading(locale, counts, false);
-    const detailLines = actionLines.slice(0, 12).map(line => escapeTelegramHtml(line));
     const html = [
-        `<b>${escapeTelegramHtml(heading)}</b>`,
-        `<blockquote expandable>${detailLines.join('\n')}</blockquote>`,
+        telegramBold(heading),
+        telegramExpandableBlockquote(actionLines.slice(0, 12).join('\n')),
     ].join('\n');
     return { text, html };
 }
@@ -8142,12 +8242,6 @@ function truncateInline(value, limit) {
     }
     return `${value.slice(0, Math.max(0, limit - 1))}…`;
 }
-function escapeTelegramHtml(value) {
-    return value
-        .replaceAll('&', '&amp;')
-        .replaceAll('<', '&lt;')
-        .replaceAll('>', '&gt;');
-}
 function parseReviewTarget(args) {
     if (args.length === 0) {
         return { type: 'uncommittedChanges' };
@@ -8260,7 +8354,97 @@ function formatMcpResourceMessage(locale, server, uri, contents) {
 }
 function formatDiffMessage(locale, diff) {
     const clipped = diff.length > 3500 ? `${diff.slice(0, 3500)}\n...` : diff;
-    return `${t(locale, 'diff_title')}\n${clipped}`;
+    return [
+        telegramBold(t(locale, 'diff_title')),
+        telegramExpandableBlockquote(clipped),
+    ].join('\n');
+}
+function formatRichDiffMessage(locale, diff) {
+    const clipped = clipRichMessageText(diff, Math.min(24_000, TELEGRAM_RICH_MESSAGE_TEXT_LIMIT - 1024));
+    const summary = locale === 'zh' ? '展开 diff' : 'Expand diff';
+    const footer = locale === 'zh'
+        ? 'FoxClaw · sendRichMessage · details/pre/code'
+        : 'FoxClaw · sendRichMessage · details/pre/code';
+    return [
+        `<h3>${escapeTelegramHtml(t(locale, 'diff_title'))}</h3>`,
+        telegramDetails(summary, telegramPreCode(clipped, 'diff')),
+        `<footer>${escapeTelegramHtml(footer)}</footer>`,
+    ].join('\n');
+}
+function formatRichDemoMessage(locale) {
+    const title = 'FoxClaw RichMessage';
+    const intro = locale === 'zh'
+        ? '这条消息通过 Telegram Bot API sendRichMessage 发送，用来验证 Rich Message 在真实客户端里的渲染。'
+        : 'This message is sent through Telegram Bot API sendRichMessage to verify Rich Message rendering in a real client.';
+    const detailsSummary = locale === 'zh' ? '展开 details + pre 示例' : 'Open details + pre sample';
+    const diffSample = [
+        'diff --git a/src/telegram/rich.ts b/src/telegram/rich.ts',
+        '+ sendRichMessage({ rich_message: { html } })',
+        '+ <details><summary>Expandable</summary>...</details>',
+        '+ <table bordered striped>...</table>',
+    ].join('\n');
+    const tableCaption = locale === 'zh' ? 'FoxClaw 可用 rich 面' : 'FoxClaw rich surfaces';
+    const surfaceHeader = locale === 'zh' ? '功能面' : 'Surface';
+    const richHeader = locale === 'zh' ? 'Rich 用法' : 'Rich usage';
+    const tableRows = locale === 'zh'
+        ? [
+            ['`/diff`', 'details + pre/code'],
+            ['工具状态', 'details/list'],
+            ['`/status`', 'table'],
+        ]
+        : [
+            ['`/diff`', 'details + pre/code'],
+            ['Tool status', 'details/list'],
+            ['`/status`', 'table'],
+        ];
+    const listItems = locale === 'zh'
+        ? ['Gateway 已接入 sendRichMessage', '/diff 已优先使用 RichMessage', '失败会回退到 Telegram HTML']
+        : ['Gateway now supports sendRichMessage', '/diff prefers RichMessage', 'Failures fall back to Telegram HTML'];
+    const detailBody = [
+        `<p>${escapeTelegramHtml(locale === 'zh' ? '下面是 rich pre/code block，客户端支持时会按代码块渲染。' : 'This is a rich pre/code block rendered as code by supported clients.')}</p>`,
+        telegramPreCode(diffSample, 'diff'),
+    ].join('\n');
+    return [
+        `<h2>${escapeTelegramHtml(title)}</h2>`,
+        `<p><b>Bot API 10.1</b> ${escapeTelegramHtml(intro)}</p>`,
+        '<hr/>',
+        '<table bordered striped>',
+        `<caption>${escapeTelegramHtml(tableCaption)}</caption>`,
+        `<tr><th>${escapeTelegramHtml(surfaceHeader)}</th><th>${escapeTelegramHtml(richHeader)}</th></tr>`,
+        ...tableRows.map(([surface, usage]) => `<tr><td>${escapeTelegramHtml(surface)}</td><td>${escapeTelegramHtml(usage)}</td></tr>`),
+        '</table>',
+        telegramDetails(detailsSummary, detailBody, true),
+        '<ul>',
+        ...listItems.map(item => `<li>${escapeTelegramHtml(item)}</li>`),
+        '</ul>',
+        '<footer>FoxClaw · sendRichMessage</footer>',
+    ].join('\n');
+}
+function formatRichDemoFallbackMessage(locale) {
+    const lines = locale === 'zh'
+        ? [
+            'RichMessage fallback 预览',
+            'Gateway 已接入 sendRichMessage',
+            '/diff 已优先使用 RichMessage',
+            '如果你看到这条 HTML fallback，说明 Telegram rich API 返回了失败，正常功能仍可用。',
+        ]
+        : [
+            'RichMessage fallback preview',
+            'Gateway now supports sendRichMessage',
+            '/diff prefers RichMessage',
+            'If you see this HTML fallback, Telegram rich API failed but normal messaging still works.',
+        ];
+    return [
+        telegramBold('FoxClaw RichMessage'),
+        telegramExpandableBlockquote(lines.join('\n')),
+        telegramPreCode('sendRichMessage({ rich_message: { html } })', 'typescript'),
+    ].join('\n');
+}
+function clipRichMessageText(value, limit) {
+    if (value.length <= limit) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, limit - 4))}\n...`;
 }
 function formatLoadedThreadsMessage(locale, threadIds) {
     const lines = [t(locale, 'loaded_title')];

package/dist/controller/presentation.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { t } from '../i18n.js';
+import { escapeTelegramHtml } from '../telegram/html.js';
 import { resolveFastTierForModel } from './service_tier.js';
 export function formatThreadsMessage(locale, threads, currentThreadId, searchTerm, listState) {
     if (threads.length === 0) {
@@ -642,12 +643,6 @@ function formatIsoTime(locale, unixSeconds) {
         return t(locale, 'unknown');
     return new Date(unixSeconds * 1000).toISOString();
 }
-function escapeTelegramHtml(value) {
-    return value
-        .replaceAll('&', '&')
-        .replaceAll('<', '&lt;')
-        .replaceAll('>', '&gt;');
-}
 function chunkButtons(buttons, width) {
     const rows = [];
     for (let index = 0; index < buttons.length; index += width) {

package/dist/i18n.d.ts

@@ -45,6 +45,7 @@ declare const MESSAGES: {
         readonly cmd_desc_setup: "Unified preference panel";
         readonly cmd_desc_fast: "Toggle Fast mode";
         readonly cmd_desc_active: "Active-turn message behavior";
+        readonly cmd_desc_rich: "Telegram RichMessage demo";
         readonly cmd_desc_status: "Bridge status";
         readonly cmd_desc_update: "Update and restart FoxClaw";
         readonly cmd_desc_account: "Codex account";
@@ -742,6 +743,7 @@ declare const MESSAGES: {
         readonly cmd_desc_setup: "统一偏好面板";
         readonly cmd_desc_fast: "切换 Fast 模式";
         readonly cmd_desc_active: "运行中新消息处理方式";
+        readonly cmd_desc_rich: "Telegram RichMessage 演示";
         readonly cmd_desc_status: "查看桥接状态";
         readonly cmd_desc_update: "升级并重启 FoxClaw";
         readonly cmd_desc_account: "Codex 账号";

package/dist/i18n.js

@@ -43,6 +43,7 @@ const MESSAGES = {
         cmd_desc_setup: 'Unified preference panel',
         cmd_desc_fast: 'Toggle Fast mode',
         cmd_desc_active: 'Active-turn message behavior',
+        cmd_desc_rich: 'Telegram RichMessage demo',
         cmd_desc_status: 'Bridge status',
         cmd_desc_update: 'Update and restart FoxClaw',
         cmd_desc_account: 'Codex account',
@@ -740,6 +741,7 @@ const MESSAGES = {
         cmd_desc_setup: '统一偏好面板',
         cmd_desc_fast: '切换 Fast 模式',
         cmd_desc_active: '运行中新消息处理方式',
+        cmd_desc_rich: 'Telegram RichMessage 演示',
         cmd_desc_status: '查看桥接状态',
         cmd_desc_update: '升级并重启 FoxClaw',
         cmd_desc_account: 'Codex 账号',
@@ -1412,6 +1414,7 @@ export function getTelegramCommands(locale) {
         { command: 'auth', description: t(locale, 'cmd_desc_auth') },
         { command: 'fast', description: t(locale, 'cmd_desc_fast') },
         { command: 'active', description: t(locale, 'cmd_desc_active') },
+        { command: 'rich', description: t(locale, 'cmd_desc_rich') },
         { command: 'account', description: t(locale, 'cmd_desc_account') },
         { command: 'quota', description: t(locale, 'cmd_desc_quota') },
         { command: 'login_device', description: t(locale, 'cmd_desc_login_device') },

package/dist/telegram/gateway.d.ts

@@ -4,6 +4,7 @@ import type { BridgeStore } from '../store/database.js';
 import type { Logger } from '../logger.js';
 import type { TelegramMessageEntity } from './addressing.js';
 import type { TelegramInboundAttachment } from './media.js';
+import type { TelegramInputRichMessage } from './rich.js';
 export interface TelegramTextEvent {
     chatId: string;
     topicId: number | null;
@@ -62,8 +63,13 @@ export declare class TelegramGateway extends EventEmitter {
         text: string;
         callback_data: string;
     }>>, messageThreadId?: number | null): Promise<number>;
+    sendRichMessage(chatId: string, richMessage: TelegramInputRichMessage, inlineKeyboard?: Array<Array<{
+        text: string;
+        callback_data: string;
+    }>>, messageThreadId?: number | null): Promise<number>;
     sendDocument(chatId: string, filename: string, contents: Buffer, caption?: string): Promise<number>;
     sendMessageDraft(chatId: string, draftId: number, text: string, messageThreadId?: number | null): Promise<void>;
+    sendRichMessageDraft(chatId: string, draftId: number, richMessage: TelegramInputRichMessage, messageThreadId?: number | null): Promise<void>;
     editMessage(chatId: string, messageId: number, text: string, inlineKeyboard?: Array<Array<{
         text: string;
         callback_data: string;
@@ -72,6 +78,10 @@ export declare class TelegramGateway extends EventEmitter {
         text: string;
         callback_data: string;
     }>>): Promise<void>;
+    editRichMessage(chatId: string, messageId: number, richMessage: TelegramInputRichMessage, inlineKeyboard?: Array<Array<{
+        text: string;
+        callback_data: string;
+    }>>): Promise<void>;
     clearMessageInlineKeyboard(chatId: string, messageId: number): Promise<void>;
     private sendMessageWithOptions;
     private editMessageWithOptions;

package/dist/telegram/gateway.js

@@ -56,6 +56,18 @@ export class TelegramGateway extends EventEmitter {
     async sendHtmlMessage(chatId, text, inlineKeyboard, messageThreadId) {
         return this.sendMessageWithOptions(chatId, text, inlineKeyboard, 'HTML', messageThreadId);
     }
+    async sendRichMessage(chatId, richMessage, inlineKeyboard, messageThreadId) {
+        const result = await callTelegramApi(this.botToken, 'sendRichMessage', {
+            chat_id: chatId,
+            rich_message: richMessage,
+            ...(messageThreadId !== null && messageThreadId !== undefined ? { message_thread_id: messageThreadId } : {}),
+            ...(inlineKeyboard ? { reply_markup: { inline_keyboard: inlineKeyboard } } : {}),
+        });
+        if (!result.ok || !result.result) {
+            throw new Error(result.description || 'Failed to send Telegram rich message');
+        }
+        return result.result.message_id;
+    }
     async sendDocument(chatId, filename, contents, caption) {
         const result = await callTelegramMultipartApi(this.botToken, 'sendDocument', {
             chat_id: chatId,
@@ -83,12 +95,34 @@ export class TelegramGateway extends EventEmitter {
             throw new Error(result.description || 'Failed to send Telegram draft message');
         }
     }
+    async sendRichMessageDraft(chatId, draftId, richMessage, messageThreadId) {
+        const result = await callTelegramApi(this.botToken, 'sendRichMessageDraft', {
+            chat_id: chatId,
+            draft_id: draftId,
+            rich_message: richMessage,
+            ...(messageThreadId !== null && messageThreadId !== undefined ? { message_thread_id: messageThreadId } : {}),
+        });
+        if (!result.ok) {
+            throw new Error(result.description || 'Failed to send Telegram rich draft message');
+        }
+    }
     async editMessage(chatId, messageId, text, inlineKeyboard) {
         return this.editMessageWithOptions(chatId, messageId, text, inlineKeyboard);
     }
     async editHtmlMessage(chatId, messageId, text, inlineKeyboard) {
         return this.editMessageWithOptions(chatId, messageId, text, inlineKeyboard, 'HTML');
     }
+    async editRichMessage(chatId, messageId, richMessage, inlineKeyboard) {
+        const result = await callTelegramApi(this.botToken, 'editMessageText', {
+            chat_id: chatId,
+            message_id: messageId,
+            rich_message: richMessage,
+            ...(inlineKeyboard ? { reply_markup: { inline_keyboard: inlineKeyboard } } : {}),
+        });
+        if (!result.ok && !String(result.description || '').includes('message is not modified')) {
+            throw new Error(result.description || 'Failed to edit Telegram rich message');
+        }
+    }
     async clearMessageInlineKeyboard(chatId, messageId) {
         const result = await callTelegramApi(this.botToken, 'editMessageReplyMarkup', {
             chat_id: chatId,

package/dist/telegram/html.d.ts

@@ -0,0 +1,8 @@
+export declare function escapeTelegramHtml(value: string): string;
+export declare function telegramBold(value: string): string;
+export declare function telegramCode(value: string): string;
+export declare function telegramPre(value: string): string;
+export declare function telegramPreCode(value: string, language?: string): string;
+export declare function telegramExpandableBlockquote(value: string): string;
+export declare function telegramSpoiler(value: string): string;
+export declare function telegramDetails(summary: string, bodyHtml: string, open?: boolean): string;

package/dist/telegram/html.js

@@ -0,0 +1,31 @@
+export function escapeTelegramHtml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}
+function escapeTelegramHtmlAttribute(value) {
+    return escapeTelegramHtml(value).replaceAll('"', '&quot;');
+}
+export function telegramBold(value) {
+    return `<b>${escapeTelegramHtml(value)}</b>`;
+}
+export function telegramCode(value) {
+    return `<code>${escapeTelegramHtml(value)}</code>`;
+}
+export function telegramPre(value) {
+    return `<pre>${escapeTelegramHtml(value)}</pre>`;
+}
+export function telegramPreCode(value, language) {
+    const classAttr = language ? ` class="language-${escapeTelegramHtmlAttribute(language)}"` : '';
+    return `<pre><code${classAttr}>${escapeTelegramHtml(value)}</code></pre>`;
+}
+export function telegramExpandableBlockquote(value) {
+    return `<blockquote expandable>${escapeTelegramHtml(value)}</blockquote>`;
+}
+export function telegramSpoiler(value) {
+    return `<tg-spoiler>${escapeTelegramHtml(value)}</tg-spoiler>`;
+}
+export function telegramDetails(summary, bodyHtml, open = false) {
+    return `<details${open ? ' open' : ''}><summary>${escapeTelegramHtml(summary)}</summary>${bodyHtml}</details>`;
+}

package/dist/telegram/rich.d.ts

@@ -0,0 +1,13 @@
+export declare const TELEGRAM_RICH_MESSAGE_TEXT_LIMIT = 32768;
+export declare const TELEGRAM_RICH_MESSAGE_BLOCK_LIMIT = 500;
+export interface TelegramInputRichMessage {
+    html?: string;
+    markdown?: string;
+    is_rtl?: true;
+    skip_entity_detection?: true;
+}
+export interface TelegramRichMessageOptions {
+    isRtl?: boolean;
+    skipEntityDetection?: boolean;
+}
+export declare function telegramRichHtml(html: string, options?: TelegramRichMessageOptions): TelegramInputRichMessage;

package/dist/telegram/rich.js

@@ -0,0 +1,12 @@
+export const TELEGRAM_RICH_MESSAGE_TEXT_LIMIT = 32_768;
+export const TELEGRAM_RICH_MESSAGE_BLOCK_LIMIT = 500;
+export function telegramRichHtml(html, options = {}) {
+    const message = { html };
+    if (options.isRtl) {
+        message.is_rtl = true;
+    }
+    if (options.skipEntityDetection) {
+        message.skip_entity_detection = true;
+    }
+    return message;
+}

package/dist/telegram/rich_markdown.d.ts

@@ -0,0 +1,2 @@
+export declare function renderTelegramMarkdownRichHtml(markdown: string): string;
+export declare function renderInlineRichHtml(markdown: string): string;

package/dist/telegram/rich_markdown.js

@@ -0,0 +1,115 @@
+import { escapeTelegramHtml, telegramPreCode } from './html.js';
+const SAFE_LINK_SCHEMES = /^(https?:|mailto:|tg:)/i;
+export function renderTelegramMarkdownRichHtml(markdown) {
+    const lines = markdown.replace(/\r\n/g, '\n').split('\n');
+    const blocks = [];
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (!line.trim()) {
+            index += 1;
+            continue;
+        }
+        const fence = line.match(/^```([A-Za-z0-9_+-]*)\s*$/);
+        if (fence) {
+            const codeLines = [];
+            index += 1;
+            while (index < lines.length && !/^```\s*$/.test(lines[index])) {
+                codeLines.push(lines[index]);
+                index += 1;
+            }
+            if (index < lines.length) {
+                index += 1;
+            }
+            blocks.push(telegramPreCode(codeLines.join('\n'), sanitizeCodeLanguage(fence[1] ?? '')));
+            continue;
+        }
+        const heading = line.match(/^(#{1,4})\s+(.+?)\s*#*\s*$/);
+        if (heading) {
+            const level = Math.min(4, Math.max(2, heading[1].length + 1));
+            blocks.push(`<h${level}>${renderInlineRichHtml(heading[2])}</h${level}>`);
+            index += 1;
+            continue;
+        }
+        if (/^\s*[-*+]\s+/.test(line)) {
+            const items = [];
+            while (index < lines.length && /^\s*[-*+]\s+/.test(lines[index])) {
+                items.push(stripListMarker(lines[index], false));
+                index += 1;
+            }
+            blocks.push(`<ul>${items.map(item => `<li>${renderInlineRichHtml(item)}</li>`).join('')}</ul>`);
+            continue;
+        }
+        if (/^\s*\d+[.)]\s+/.test(line)) {
+            const items = [];
+            while (index < lines.length && /^\s*\d+[.)]\s+/.test(lines[index])) {
+                items.push(stripListMarker(lines[index], true));
+                index += 1;
+            }
+            blocks.push(`<ol>${items.map(item => `<li>${renderInlineRichHtml(item)}</li>`).join('')}</ol>`);
+            continue;
+        }
+        if (/^\s*>\s?/.test(line)) {
+            const quoteLines = [];
+            while (index < lines.length && /^\s*>\s?/.test(lines[index])) {
+                quoteLines.push(lines[index].replace(/^\s*>\s?/, ''));
+                index += 1;
+            }
+            blocks.push(`<blockquote>${quoteLines.map(renderInlineRichHtml).join('<br>')}</blockquote>`);
+            continue;
+        }
+        const paragraphLines = [line.trimEnd()];
+        index += 1;
+        while (index < lines.length
+            && lines[index].trim()
+            && !/^```/.test(lines[index])
+            && !/^(#{1,4})\s+/.test(lines[index])
+            && !/^\s*[-*+]\s+/.test(lines[index])
+            && !/^\s*\d+[.)]\s+/.test(lines[index])
+            && !/^\s*>\s?/.test(lines[index])) {
+            paragraphLines.push(lines[index].trimEnd());
+            index += 1;
+        }
+        blocks.push(`<p>${renderInlineRichHtml(paragraphLines.join('\n'))}</p>`);
+    }
+    return blocks.join('\n') || '<p></p>';
+}
+export function renderInlineRichHtml(markdown) {
+    const tokens = [];
+    const protectedText = markdown.replace(/`([^`\n]+)`/g, (_match, code) => {
+        const token = `{{FOXCLAW_RICH_CODE_${tokens.length}}}`;
+        tokens.push(`<code>${escapeTelegramHtml(code)}</code>`);
+        return token;
+    });
+    let html = escapeTelegramHtml(protectedText);
+    html = html.replace(/\[([^\]\n]+)\]\(((?:[^()\s]+|\([^)\s]*\))+)\)/g, (_match, label, url) => {
+        const normalizedUrl = unescapeHtmlAttribute(url);
+        if (!SAFE_LINK_SCHEMES.test(normalizedUrl)) {
+            return label;
+        }
+        return `<a href="${escapeTelegramHtmlAttribute(normalizedUrl)}">${label}</a>`;
+    });
+    html = html.replace(/\*\*([^*\n][\s\S]*?[^*\n])\*\*/g, '<b>$1</b>');
+    html = html.replace(/__([^_\n][\s\S]*?[^_\n])__/g, '<b>$1</b>');
+    html = html.replace(/\{\{FOXCLAW_RICH_CODE_(\d+)}}/g, (_match, tokenIndex) => tokens[Number(tokenIndex)] ?? '');
+    return html.replaceAll('\n', '<br>');
+}
+function stripListMarker(line, ordered) {
+    return ordered
+        ? line.replace(/^\s*\d+[.)]\s+/, '')
+        : line.replace(/^\s*[-*+]\s+/, '');
+}
+function sanitizeCodeLanguage(language) {
+    const normalized = language.trim().replace(/[^A-Za-z0-9_+-]/g, '');
+    return normalized || undefined;
+}
+function escapeTelegramHtmlAttribute(value) {
+    return escapeTelegramHtml(value).replaceAll('"', '&quot;');
+}
+function unescapeHtmlAttribute(value) {
+    return value
+        .replaceAll('&amp;', '&')
+        .replaceAll('&lt;', '<')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&quot;', '"');
+}

package/docs/telegram-rich-messages.md

@@ -0,0 +1,99 @@
+# Telegram Rich Message Adaptation Check
+
+Checked on 2026-06-16 against Telegram Bot API Rich Messages, especially `RichMessage`, `sendRichMessage`, `sendRichMessageDraft`, and Rich Message Formatting Options.
+
+Official references:
+
+- https://core.telegram.org/bots/api#rich-message-formatting-options
+- https://core.telegram.org/bots/api#sendrichmessage
+- https://core.telegram.org/bots/api#sendrichmessagedraft
+
+## Conclusion
+
+FoxClaw can benefit from the new rich message surface, and RichMessage is now wired into Telegram surfaces that are easy to inspect and safe to fall back.
+
+The current strategy is to try `sendRichMessage` first on Telegram, then fall back to the existing Telegram HTML path on failure. Weixin continues to use HTML/plain fallback. Bot API 10.1 Rich Messages start with diagnostics and structured long text, then can expand to status, auth/quota, and AI draft streaming.
+
+Already landed in this pass:
+
+- Added `src/telegram/html.ts` for centralized Telegram HTML escaping and tag helpers.
+- Added `src/telegram/rich.ts` and wired `sendRichMessage` / rich HTML through `TelegramGateway`, `TelegramMessagingPort`, and `BridgeMessagingRouter`.
+- Added `/rich` as a diagnostic command for checking heading, table, details, pre/code, and list rendering in a real Telegram client.
+- Changed `/diff` to prefer RichMessage with a heading plus details/pre/code diff block, falling back to HTML bold title plus expandable quote body.
+- Moved existing CLI observation and archived tool-batch HTML generation onto the shared helper.
+
+## Official Capability
+
+Bot API 10.1 adds Rich Messages:
+
+- `RichText*`: bold, italic, underline, strikethrough, spoiler, code, marked, math, URL, email, phone, mention, hashtag, bot command, anchors, and references.
+- `RichBlock*`: paragraph, heading, preformatted, footer, divider, math block, anchor, list, block quote, pull quote, collage, slideshow, table, details, map, media blocks, and thinking.
+- `sendRichMessage`: sends a complete rich message.
+- `sendRichMessageDraft`: streams an ephemeral partial rich message in private chat; the final answer must still be persisted with `sendRichMessage`.
+- `editMessageText` accepts `rich_message` for editing rich messages.
+
+Rich Message HTML also supports tags such as `<details>`, `<table>`, `<pre><code class="language-...">`, `<ul>/<ol>`, `<hr/>`, `<tg-math-block>`, and `<tg-thinking>`. `RichBlockThinking` is draft-only.
+
+## FoxClaw Inventory
+
+Current Telegram send layer:
+
+- `src/telegram/gateway.ts`: plain/html/rich send and edit are wired; regular HTML uses `parse_mode=HTML`, while rich messages use `rich_message.html`.
+- `src/channels/telegram/telegram_messaging_port.ts`: controller-facing plain/html/rich-html send/edit and text draft operations.
+- `src/telegram/rendering.ts`: `segmented_stream` is the default; `draft_stream` still uses the old text draft path.
+- `src/controller/controller.ts`: central dispatcher for status cards, approvals, tool batches, diffs, auth, MCP, plugins, files, and runtime summaries.
+- `src/controller/presentation.ts`: `/threads`, `/setup`, model, and access panels already use Telegram HTML.
+
+Useful mapping:
+
+| Surface | Current state | Useful rich capabilities | Recommendation |
+| --- | --- | --- | --- |
+| Active turn status | Short plain text, frequent edits | heading, list, thinking draft | Keep stable; use `RichBlockThinking` later only for private draft streaming |
+| Codex streaming replies | Segmented plain text | rich draft, paragraph, pre, details | Feature flag only; needs fallback |
+| Archived tool batches | Expandable HTML quote | details, pre, list | Keep HTML now; later use rich details |
+| `/diff` | RichMessage first, HTML fallback | pre language, details | Landed |
+| Approvals | Plain text plus inline keyboard | code, pre, spoiler, details | Command/path/patch fit code/pre/details; sensitive params should be hidden |
+| `/status` and runtime summaries | Plain text lists | table, heading, footer | Good candidate for rich tables |
+| `/auth` and `/quota` | Compact text plus buttons | table, marked, spoiler | Quota windows fit tables; abnormal candidates fit marked text |
+| `/threads` and `/setup` | HTML panels | heading, list, anchor | Current HTML is enough; medium priority |
+| MCP resources and plugin skills | Long plain text | details, pre, anchor/reference | Good candidate for collapsible schema/resource blocks |
+| Help and setup text | Plain text | heading, list, code | Low priority |
+| Media attachment feedback | Plain summary | collage/slideshow/media captions | Use only if FoxClaw starts returning media previews |
+
+## Rollout Plan
+
+Phase 1: HTML-compatible enhancement.
+
+- Centralize Telegram HTML helpers.
+- Collapse long content by default: diffs, tool logs, MCP resources, plugin skill contents.
+- Render commands, paths, models, and candidate names as code.
+- Use spoilers or omission for secret/token-like diagnostics.
+
+Phase 2: Rich Message builder.
+
+Done:
+
+- Added a minimal typed `src/telegram/rich.ts`.
+- Added `sendRichMessage`, `editRichMessage`, and `sendRichMessageDraft` to `TelegramGateway`.
+- Added rich HTML send/edit to `TelegramMessagingPort` and `BridgeMessagingRouter`; Weixin scopes use fallback HTML.
+- `/rich` and `/diff` use rich sending first and fall back to HTML.
+
+Next:
+
+- Move `/status`, `/auth`, `/quota`, and MCP resources to rich table/details.
+- Decide whether a global config flag is needed after real Telegram client checks.
+
+Phase 3: Rich draft streaming.
+
+- Enable only in Telegram private chats first; keep group/topic rendering on the current segmented stream.
+- Use `RichBlockThinking` while generating and paragraph/pre/details for partial output.
+- Persist the final answer with `sendRichMessage`.
+- Keep the old text draft and segmented stream as fallback paths.
+
+## Risks
+
+- Rich Messages landed in Bot API 10.1 on 2026-06-11, so client compatibility should be checked with `/rich` and `/diff`.
+- `sendRichMessageDraft` targets private users; group, topic, and multi-bot paths must keep existing rendering.
+- Rich media blocks add bot permission and media URL/upload constraints; they are not a Phase 1 target.
+- Automatic entity detection can mis-detect paths, emails, URLs, and commands; rich builders should choose `skip_entity_detection` per message type.
+- All Codex, shell, and file output must pass through centralized escaping before entering HTML/rich markup.

package/docs/user-manual.md

@@ -265,6 +265,10 @@ It controls:
 
 Telegram renders the HTML and buttons. This text block approximates the real panel:
 
+For the Telegram Rich Message inventory and rollout plan, see [Telegram Rich Message Adaptation Check](./telegram-rich-messages.md). The default path still favors Telegram HTML for compatibility.
+
+Send `/rich` to view a RichMessage demo in the current Telegram client. `/diff` also prefers RichMessage details plus a diff code block, with automatic Telegram HTML fallback.
+
 ```text
 Session preferences
 Current: gpt-5.5 · high · fast=off · default · Agent · Steer current turn

package/docs/zh/telegram-rich-messages.md

@@ -0,0 +1,125 @@
+# Telegram Rich Message 适配专项检查
+
+检查日期：2026-06-16。依据：Telegram Bot API Rich Messages 文档，尤其是 `RichMessage`、`sendRichMessage`、`sendRichMessageDraft` 与 Rich Message Formatting Options。
+
+官方入口：
+
+- https://core.telegram.org/bots/api#rich-message-formatting-options
+- https://core.telegram.org/bots/api#sendrichmessage
+- https://core.telegram.org/bots/api#sendrichmessagedraft
+
+## 结论
+
+FoxClaw 有明确收益，并已开始把 RichMessage 用在适合看效果、可安全回退的 Telegram 功能面。
+
+现在的策略是：Telegram 优先尝试 `sendRichMessage`，失败时回退到既有 Telegram HTML；微信继续使用 HTML/plain 回退。Bot API 10.1 的 Rich Message 先用于可观察的诊断和结构化长文本，再逐步扩展到状态、auth/quota 和 AI draft streaming。
+
+本次已先落地低风险增强：
+
+- 新增 `src/telegram/html.ts`，统一 Telegram HTML 转义和常用标签生成。
+- 新增 `src/telegram/rich.ts`，并在 `TelegramGateway` / `TelegramMessagingPort` / `BridgeMessagingRouter` 接入 `sendRichMessage` / rich HTML 发送链路。
+- 新增 `/rich` 诊断命令，用来在真实 Telegram 客户端查看 heading、table、details、pre/code、list 的 RichMessage 效果。
+- `/diff` 改为优先发送 RichMessage：标题用 heading，diff 内容放入 details + pre/code；rich 发送失败时回退到 HTML 加粗标题和可展开引用块。
+- 现有 CLI 观察消息和归档工具批次状态复用同一套 HTML helper。
+
+## 官方能力摘录
+
+Bot API 10.1 新增 Rich Messages：
+
+- `RichText*`：bold、italic、underline、strikethrough、spoiler、code、marked、math、url、email、phone、mention、hashtag、bot command、anchor/reference 等。
+- `RichBlock*`：paragraph、heading、pre、footer、divider、math block、anchor、list、blockquote、pullquote、collage、slideshow、table、details、map、photo/video/audio/animation/voice、thinking。
+- `sendRichMessage`：发送完整 rich message。
+- `sendRichMessageDraft`：在私聊里流式发送临时 rich draft；draft 是短暂预览，最终仍要用 `sendRichMessage` 发送完整消息。
+- `editMessageText` 新增 `rich_message` 参数，可编辑 rich message。
+
+Rich Message HTML 还支持 `<details>`、`<table>`、`<pre><code class="language-...">`、`<ul>/<ol>`、`<hr/>`、`<tg-math-block>`、`<tg-thinking>` 等标签。`RichBlockThinking` 只能用于 `sendRichMessageDraft`。
+
+## FoxClaw 现状
+
+当前 Telegram 发送层：
+
+- `src/telegram/gateway.ts`：`sendMessage`、`sendHtmlMessage`、`sendRichMessage`、`editMessage`、`editHtmlMessage`、`editRichMessage` 已接入；HTML 普通消息使用 `parse_mode=HTML`，rich 消息使用 `rich_message.html`。
+- `src/channels/telegram/telegram_messaging_port.ts`：对 controller 暴露 plain/html/rich-html send/edit 和 `sendDraft`。
+- `src/telegram/rendering.ts`：默认 `segmented_stream`；`draft_stream` 仍是旧 `sendMessageDraft` 文本 draft。
+- `src/controller/controller.ts`：状态卡、审批、工具批次、diff、auth、MCP、插件、文件等功能面都在这里汇总发送。
+- `src/controller/presentation.ts`：`/threads`、`/setup`、模型/权限面板已经使用 Telegram HTML。
+
+已经使用的格式能力：
+
+- `/threads`、`/setup` 等面板：加粗、code、HTML escape。
+- CLI 观察消息：`<pre>`。
+- 归档工具批次状态：`<blockquote expandable>`。
+- 本次增强后的 `/diff`：加粗标题和可展开引用块。
+
+已经接入：
+
+- `sendRichMessage`：Telegram rich HTML 发送链路。
+- `/rich`：RichMessage demo。
+- `/diff`：RichMessage details + diff pre/code，失败回退 HTML。
+
+尚未接入：
+
+- Rich table/status 面板、auth/quota 表格、MCP resource details、rich draft streaming。
+- `sendRichMessageDraft` 的 thinking block 和最终 rich message 持久化。
+
+## 功能面盘点
+
+| 功能面 | 现状 | 可用 rich 能力 | 建议 |
+| --- | --- | --- | --- |
+| 活动 turn 状态卡 | 普通短文本，频繁编辑 | heading、list、thinking draft | 保持普通状态卡稳定；私聊 draft streaming 后续用 `RichBlockThinking` |
+| Codex streaming 回复 | 分段纯文本为主 | rich draft、paragraph、pre、details | 先不默认切；需要 feature flag 和失败回退 |
+| 归档工具批次 | 已用 expandable blockquote | details、pre、list | 短期维持 HTML；后续 rich details 展开命令、文件、搜索结果 |
+| `/diff` | 已优先 RichMessage，失败回退 HTML | pre language、details | 已落地 |
+| 审批请求 | 多行纯文本 + inline keyboard | code、pre、spoiler、details | 命令、路径、patch 适合 code/pre/details；敏感参数可 spoiler |
+| `/status` / runtime 摘要 | 纯文本列表 | table、heading、footer | 多 bot、多 auth、多 quota 适合 rich table |
+| `/auth` / `/quota` | 紧凑纯文本 + 按钮 | table、marked、spoiler | quota 窗口适合 table；异常候选用 marked；隐藏敏感候选信息需谨慎 |
+| `/threads` / `/setup` | 已用 HTML 面板 | heading、list、anchor | 现状够用；rich message 价值中等 |
+| MCP resource / plugin skill | 纯文本长内容 | details、pre、anchor/reference | schema、resource 文本可放 details/pre，引用可用 anchor/reference |
+| 说明类消息 / help | 纯文本 | heading、list、code | 可转 rich list，但优先级低 |
+| 媒体附件反馈 | 纯文本摘要 | collage/slideshow/photo/video caption | 只在需要回显媒体结果时考虑，当前不是主路径 |
+
+## 落地路线
+
+### Phase 1：HTML 兼容增强
+
+目标：不改变 Bot API 主方法，先改善现有客户端体验。
+
+- 统一 Telegram HTML helper，禁止散落手写转义。
+- 长内容默认折叠：diff、工具日志、MCP resource、插件 skill 内容。
+- 命令、路径、模型、候选名使用 `<code>`。
+- 对可能包含 secret/token 的诊断内容使用 `<tg-spoiler>` 或直接不展示。
+
+已完成：HTML helper、`/diff` 折叠、现有 CLI/工具归档复用 helper。
+
+### Phase 2：Rich Message builder
+
+目标：让 rich message 作为可回退能力存在，而不是替换全部消息。
+
+已完成：
+
+- 新增 `src/telegram/rich.ts`，定义 `InputRichMessage` 的最小 HTML 输入。
+- `TelegramGateway` 增加 `sendRichMessage`、`editRichMessage`、`sendRichMessageDraft`。
+- `TelegramMessagingPort` 和 `BridgeMessagingRouter` 增加 rich HTML send/edit；微信 scope 自动用 fallback HTML。
+- `/rich` 和 `/diff` 先使用 rich 发送，失败回退到 HTML。
+
+下一步：
+
+- 把 `/status`、`/auth`、`/quota`、MCP resource 等结构消息迁移到 rich table/details。
+- 按真实客户端表现决定是否加入全局配置开关。
+
+### Phase 3：Rich draft streaming
+
+目标：私聊里的 AI 生成过程更自然。
+
+- 仅对 Telegram 私聊启用；群组、topic 默认继续走现有 segmented stream。
+- draft 中使用 `RichBlockThinking` 表示思考中，已生成文本用 paragraph/pre/details。
+- 生成完成后调用 `sendRichMessage` 发送完整消息，不能只依赖 ephemeral draft。
+- 保留旧 `sendMessageDraft` 和 plain segmented stream 回退。
+
+## 风险和注意点
+
+- Rich Messages 是 2026-06-11 Bot API 10.1 新能力，客户端兼容性需要通过 `/rich` 和 `/diff` 实测。
+- `sendRichMessageDraft` 只面向用户私聊；FoxClaw 的群组、topic、多 bot 场景必须保留旧路径。
+- Rich media block 需要 bot 具备对应发送权限，且媒体 URL/上传处理比文本复杂，暂不作为第一阶段目标。
+- 自动实体识别可能把路径、邮箱、URL、命令误识别；rich builder 应按消息类型决定是否设置 `skip_entity_detection`。
+- HTML/rich 格式必须集中 escape，不能让 Codex 输出或 shell 输出直接拼进标签。

package/docs/zh/user-manual.md

@@ -265,6 +265,10 @@ TG_ALLOWED_TOPIC_ID=42
 
 Telegram 会把 HTML 和按钮渲染出来。这里用等宽框模拟实际面板：
 
+Telegram Rich Message 能力的专项盘点和后续接入路线见 [Telegram Rich Message 适配专项检查](./telegram-rich-messages.md)。当前默认通道仍优先使用兼容性更稳的 Telegram HTML。
+
+可以发送 `/rich` 在当前 Telegram 客户端查看 RichMessage demo。`/diff` 也会优先用 RichMessage 展示 details 和 diff code block，失败时自动回退到 Telegram HTML。
+
 ```text
 会话偏好
 当前：gpt-5.5 · high · fast=off · default · Agent · Steer current turn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.5.32",
+  "version": "0.5.34",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",