fix(telegram): allow opt-in CJK rich messages

This commit is contained in:
wang2
2026-07-01 15:56:05 +08:00
committed by Teknium
parent 0ea0c53e89
commit fa12d7556c
6 changed files with 70 additions and 3 deletions
+1
View File
@@ -1312,6 +1312,7 @@ platform_toolsets:
# disable_link_previews: false # Set true to suppress Telegram URL previews in bot messages
# rich_messages: false # Bot API 10.1 rich messages (tables/task lists/details/math); default false for copyable legacy MarkdownV2, set true to opt in
# rich_drafts: false # Experimental rich draft previews during Telegram DM streaming; default false because Telegram Desktop/macOS can visually overlay draft frames
# allow_cjk_rich_messages: false # Keep CJK content on the safe MarkdownV2 path unless an unaffected client explicitly opts in to native rich rendering
# command_menu:
# # Telegram allows up to 100 BotCommands; Hermes defaults to 60 so
# # all built-in commands plus common skill commands stay visible
+3
View File
@@ -1523,6 +1523,9 @@ DEFAULT_CONFIG = {
# Experimental rich draft previews while streaming DMs; off because Telegram
# Desktop/macOS can overlay draft frames until the chat redraws.
"rich_drafts": False,
# CJK stays on legacy MarkdownV2 (Telegram Desktop/macOS garbles rich CJK, #47653);
# set True on an unaffected client to get native rich tables for CJK.
"allow_cjk_rich_messages": False,
},
},
+6 -1
View File
@@ -446,6 +446,8 @@ class TelegramAdapter(BasePlatformAdapter):
# separate opt-in (Desktop can leave rich draft frames overlaid): off keeps native draft transport
# but skips rich draft rendering; the final reply still lands via sendRichMessage.
self._rich_messages_enabled: bool = self._coerce_bool_extra("rich_messages", False)
# CJK stays on legacy MarkdownV2 by default (Desktop/macOS garble, #47653); opt-in for unaffected clients.
self._allow_cjk_rich_messages: bool = self._coerce_bool_extra("allow_cjk_rich_messages", False)
self._rich_drafts_enabled: bool = self._coerce_bool_extra("rich_drafts", False)
self._rich_send_disabled = self._rich_draft_disabled = False # latched after a capability failure
# Transient sendChatAction failures recur on every keep-typing tick; back off per chat.
@@ -1283,7 +1285,10 @@ class TelegramAdapter(BasePlatformAdapter):
return bool(
content and content.strip()
and not self._has_telegram_desktop_details_math_crash_shape(content)
and not self._has_telegram_desktop_cjk_rich_garble_shape(content)
and (
getattr(self, "_allow_cjk_rich_messages", False)
or not self._has_telegram_desktop_cjk_rich_garble_shape(content)
)
and self._content_fits_rich_limits(content)
and self._bot_supports_rich())
@@ -125,6 +125,19 @@ async def test_astral_cjk_rich_content_skips_rich_send_to_avoid_tdesktop_garble(
adapter._bot.send_message.assert_awaited_once()
@pytest.mark.asyncio
@pytest.mark.parametrize("content", [CJK_RICH_CONTENT, ASTRAL_CJK_RICH_CONTENT])
async def test_cjk_rich_content_can_be_opted_in(content):
adapter = _make_adapter(extra={"allow_cjk_rich_messages": True})
result = await adapter.send("12345", content)
assert result.success is True
api_kwargs = _rich_api_kwargs(adapter)
assert api_kwargs["rich_message"]["markdown"] == content
adapter._bot.send_message.assert_not_called()
@pytest.mark.asyncio
async def test_plain_markdown_stays_on_legacy_path():
"""Ordinary replies (no table/task-list/details/math) stay on the legacy
@@ -376,6 +389,24 @@ async def test_cjk_rich_content_skips_rich_draft_to_avoid_tdesktop_garble():
adapter._bot.send_message_draft.assert_awaited_once()
@pytest.mark.asyncio
async def test_cjk_rich_draft_can_be_opted_in():
adapter = _make_adapter(
extra={"rich_drafts": True, "allow_cjk_rich_messages": True}
)
adapter._bot.do_api_request = AsyncMock(return_value=True)
result = await adapter.send_draft("12345", draft_id=7, content=CJK_RICH_CONTENT)
assert result.success is True
adapter._bot.do_api_request.assert_awaited_once()
call = adapter._bot.do_api_request.call_args
assert call.args[0] == "sendRichMessageDraft"
api_kwargs = call.kwargs["api_kwargs"]
assert api_kwargs["rich_message"]["markdown"] == CJK_RICH_CONTENT
adapter._bot.send_message_draft.assert_not_called()
# ----------------------------------------------------------------------
# prefers_fresh_final_streaming: root DMs stay on the no-duplicate edit/draft
# path (#47048). DM topics that degrade off drafts still need a fresh
@@ -712,6 +743,22 @@ async def test_finalize_edit_dm_topic_omits_send_only_routing_fields():
adapter._bot.edit_message_text.assert_not_called()
@pytest.mark.asyncio
async def test_finalize_edit_cjk_rich_content_can_be_opted_in():
adapter = _make_adapter(extra={"allow_cjk_rich_messages": True})
result = await adapter.edit_message(
"12345", "555", CJK_RICH_CONTENT, finalize=True,
)
assert result.success is True
assert result.message_id == "555"
api_kwargs = _rich_edit_kwargs(adapter)
assert api_kwargs["message_id"] == 555
assert api_kwargs["rich_message"]["markdown"] == CJK_RICH_CONTENT
adapter._bot.edit_message_text.assert_not_called()
@pytest.mark.asyncio
async def test_legacy_edit_error_logs_redacted_bot_token_without_traceback(monkeypatch, caplog):
import agent.redact as redact
@@ -1019,9 +1019,14 @@ gateway:
extra:
rich_messages: true
rich_drafts: false
allow_cjk_rich_messages: false
```
This setting is for client-rendering/copy compatibility; Hermes already falls back automatically when Telegram rejects the rich API call. `rich_drafts` controls whether the DM streaming preview *renders* rich (`sendRichMessageDraft`) and stays off by default because Telegram Desktop/macOS can visually overlay rich draft frames until the chat redraws; with it off, the preview streams plain and the final still arrives as a native Rich Message. If you only want the legacy "always code-block" table behavior while keeping rich messages enabled, disable table normalization by setting `telegram.pretty_tables: false` in `config.yaml` (default: `true`).
This setting is for client-rendering/copy compatibility; Hermes already falls back automatically when Telegram rejects the rich API call. `rich_drafts` controls whether the DM streaming preview *renders* rich (`sendRichMessageDraft`) and stays off by default because Telegram Desktop/macOS can visually overlay rich draft frames until the chat redraws; with it off, the preview streams plain and the final still arrives as a native Rich Message.
CJK text (Chinese, Japanese, Korean, and rare Han extensions) stays on the legacy MarkdownV2 path by default because affected Telegram Desktop/macOS clients have rendered Bot API rich messages with overlapping CJK glyph artifacts. If you use an unaffected client and prefer native rich tables/task lists/details/math for CJK payloads, set `allow_cjk_rich_messages: true` alongside `rich_messages: true` to opt in to that client-side risk.
If you only want the legacy "always code-block" table behavior while keeping rich messages enabled, disable table normalization by setting `telegram.pretty_tables: false` in `config.yaml` (default: `true`).
**Link previews.** Telegram auto-generates link previews for URLs in bot messages. If you'd rather suppress those (long `/tools` output, agent reply that mentions ten links, etc.):
@@ -894,9 +894,15 @@ gateway:
telegram:
extra:
rich_messages: true
rich_drafts: false
allow_cjk_rich_messages: false
```
这个设置用于客户端渲染/复制兼容性;当 Telegram 拒绝富消息 API 调用时,Hermes 已经会自动回退。如果你只是想在保持富消息启用的同时恢复旧版「始终使用代码块」表格行为,可在 `config.yaml` 中设置 `telegram.pretty_tables: false` 禁用表格规范化(默认:`true`)。
这个设置用于客户端渲染/复制兼容性;当 Telegram 拒绝富消息 API 调用时,Hermes 已经会自动回退。`rich_drafts` 控制私聊流式预览是否使用富渲染(`sendRichMessageDraft`),默认关闭,因为 Telegram Desktop/macOS 可能在聊天重绘前视觉叠加富草稿帧;关闭时,预览以纯文本流式显示,最终消息仍以原生富消息送达。
CJK 文本(中文、日文、韩文以及罕见汉字扩展)默认仍走旧版 MarkdownV2 路径,因为受影响的 Telegram Desktop/macOS 客户端曾将 Bot API 富消息渲染成重叠的 CJK 字形。如果你使用不受影响的客户端,并希望 CJK 内容里的表格、任务列表、折叠详情和公式走原生富渲染,可以在 `rich_messages: true` 旁显式设置 `allow_cjk_rich_messages: true`,接受该客户端侧风险。
如果你只是想在保持富消息启用的同时恢复旧版「始终使用代码块」表格行为,可在 `config.yaml` 中设置 `telegram.pretty_tables: false` 禁用表格规范化(默认:`true`)。
**链接预览。** Telegram 会为机器人消息中的 URL 自动生成链接预览。如果你希望抑制这些预览(长 `/tools` 输出、提及十个链接的 Agent 回复等):