diff --git a/cli-config.yaml.example b/cli-config.yaml.example index 82e3bf7a10..1151892263 100644 --- a/cli-config.yaml.example +++ b/cli-config.yaml.example @@ -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 diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py index 22a09277ca..b082581fdb 100644 --- a/hermes_cli/config_defaults.py +++ b/hermes_cli/config_defaults.py @@ -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, }, }, diff --git a/plugins/platforms/telegram/adapter.py b/plugins/platforms/telegram/adapter.py index 59b91ab5cc..3f1d69bc2e 100644 --- a/plugins/platforms/telegram/adapter.py +++ b/plugins/platforms/telegram/adapter.py @@ -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()) diff --git a/tests/gateway/test_telegram_rich_messages.py b/tests/gateway/test_telegram_rich_messages.py index 522591ecb1..2b76baf576 100644 --- a/tests/gateway/test_telegram_rich_messages.py +++ b/tests/gateway/test_telegram_rich_messages.py @@ -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 diff --git a/website/docs/user-guide/messaging/telegram.md b/website/docs/user-guide/messaging/telegram.md index d9d7b26bc1..ea7744e115 100644 --- a/website/docs/user-guide/messaging/telegram.md +++ b/website/docs/user-guide/messaging/telegram.md @@ -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.): diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/telegram.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/telegram.md index 40fe14bc98..71387c25fa 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/telegram.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/telegram.md @@ -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 回复等):