Telegram Bot UI 是做什麼的？
可攜式、SDK 無關的技能，涵蓋 Telegram Bot 使用者介面 的完整生命週期： 審計 → 畫面/狀態映射 → 文字、按鈕與導航設計 → 實作 → 遷移 → 測試 → 文件。
Telegram Bot 沒有 CSS 也沒有佈局引擎。其整個介面只由五種東西構成： 訊息文字、格式化、鍵盤、聊天級別的元素（指令、選單按鈕、深度連結），以及狀態之間的轉換。 此技能將這五者視為統一的設計面。
目的
幫助 Agent 讓 Bot 的介面 清晰、一致且易於變更： 選擇畫面的內容與表達方式；標籤、分組、排序、著色與佈局按鈕； 設計畫面與狀態之間的導航；確保每個畫面與 Bot 的其他部分保持一致； 保持本地化完整；並以最豐富的可用格式渲染訊息本體， 支援任何語言與任何 Telegram SDK，且不破壞現有的處理器或業務邏輯。
使用時機
- 介面工作："改善 Bot 的 UX/UI"、"重新設計這個選單"、"鍵盤過載"、"用戶看不懂這個畫面"、"新增返回按鈕"、"將這些動作分組"、"讓主要動作突出"。
- 按鈕與鍵盤：內聯鍵盤、回覆鍵盤、按鈕標籤、按鈕順序與佈局、
style顏色、icon_custom_emoji_id自訂表情符號、Web App / URL / 複製文字 / 切換內聯按鈕、ForceReply、鍵盤移除、分頁與返回導航。 - 文字與微文案：重寫 Bot 訊息、標題、說明文字、提示、確認訊息、錯誤與空狀態、語氣與長度、表情符號使用。
- 聊天級別元素：
/commands列表與範圍、選單按鈕、/start與深度連結、首次使用體驗。 - 動態回饋：串流 AI 答案（
sendMessageDraft、sendRichMessageDraft、<tg-thinking>）、進度條、「正在輸入」狀態、按鈕載入器、「Bot 在運作時感覺卡住」。 - 個人化與連結：安全地以姓名問候用戶、語言環境提示、URL 按鈕 vs 內聯連結、連結預覽、深度連結、提及。
- 一致性：同一動作以三種不同方式命名、返回按鈕僅存在於某些畫面、編輯後狀態不匹配。
- 訊息渲染：HTML / MarkdownV2 /
MessageEntity、文字中的自訂表情符號、說明文字、表格與豐富訊息、連結預覽 / 靜音 / 保護選項、長訊息分割、串流草稿、編輯、頻道貼文、本地化與 RTL、can't parse entities、損壞或過大的訊息。
不應使用時機
未在介面中呈現的 Bot 邏輯：Webhook 基礎設施、付款 處理、授權、資料庫與遷移、群組管理與審核邏輯、爬蟲、分析管道、Mini App 內部（其自己的 HTML/CSS UI 屬於一般前端工作 — 此技能僅涵蓋 Telegram 側的表面：開啟它的按鈕或選單）。
也不適用於 Microsoft .rtf 檔案。
術語 — 請勿混淆
- 內聯鍵盤 ≠ 回覆鍵盤。
InlineKeyboardMarkup附加到特定訊息並發送callback_query/ 開啟 URL。ReplyKeyboardMarkup取代用戶的輸入鍵盤，並 將文字以普通訊息的形式發送。不同的按鈕類別，不同的 UX。 style不是顏色值。 它只能是primary、success、danger其中之一。Telegram 沒有 HEX/RGB/CSS 按鈕顏色。icon_custom_emoji_id不是file_id，不是表情符號包名稱，不是連結，也不是 Unicode 表情符號。它是特定自訂表情符號的 ID。- Telegram 豐富文字並非 Microsoft RTF。 切勿將豐富訊息稱為 "RTF"。
- 豐富 Markdown ≠ MarkdownV2。 MarkdownV2 是 一般 訊息的
parse_mode，需要嚴格的跳脫。豐富 Markdown 是 豐富訊息 的文件語法。 - 豐富 HTML ≠ 任意瀏覽器 HTML。 僅限 Telegram 支援的標籤集。
- 編輯鍵盤 ≠ 重新發送畫面。
editMessageReplyMarkup和editMessageText會原地更新；發送新訊息則會疊加畫面。
事實來源政策
依此順序信任：
- 目前的 官方 Telegram 文件（Bot API、Bot Features、格式化頁面、官方部落格）。
- 官方 Bot API 更新日誌。
- 專案中 實際安裝的 SDK 文件。
- SDK 原始碼。
- SDK 問題追蹤器。
- 第三方文章 — 僅作為補充背景資訊。
在以下情況下，請在行動前 重新驗證官方文件：
任務涉及新的 API；當前日期晚於 references/official-sources.md 中的「最後驗證日期」；
專案的 Bot API 版本未知；SDK 文件與 Bot API 矛盾；
遇到不熟悉的類型/欄位；或用戶要求「最新功能」。
此技能 並非凍結 於 Bot API 10.2 — 如果 Telegram 發布了更新版本，請使用它。
UI 相關的版本閘道：references/ui-changelog.md。
核心工作流程（重新設計前先審計）
- 閱讀專案的說明文件（
AGENTS.md/CLAUDE.md/ README / docs）。 - 偵測語言、框架、Telegram SDK 與確切版本。
- 確定 SDK 實際支援的 Bot API 版本 — 這決定了
style和icon_custom_emoji_id是否可用。 - 建立 畫面/狀態映射：用戶可以看到的每條訊息、每個鍵盤、
每個
callback_data、每個指令、每個轉換 （references/navigation-and-flows.md）。 - 分類每個畫面：進入點 / 選單 / 表單步驟 / 確認 / 結果 / 錯誤 / 空白 / 通知。
- 識別 真正的 UX 缺陷（不要憑空創造問題）：模糊的標籤、 過載的鍵盤、無路可退的死胡同、不一致的命名、 破壞性動作只需一次點擊、未本地化的字串、難以閱讀的內容本體。
- 設計修正方案：先文字，再結構，然後佈局，最後顏色/表情符號 — 按此順序。顏色是最後一層，永遠不能用來解決標籤不佳的問題。
- 檢查 SDK 是否支援你計劃使用的每個欄位
（
references/sdk-compatibility.md）。 - 以專案現有的樣式和工具來實作（不要重複複製其鍵盤建構器）。
- 保留
callback_data、URL、深度連結、處理器路由以及 本地化鍵值，除非用戶明確要求更改它們。 - 新增 備援 路徑並保持舊用戶端可用
（
references/errors-and-fallbacks.md）。 - 使用專案現有的測試基礎設施新增 測試
（
references/testing-playbook.md）。 - 執行專案的 lint / typecheck / 測試 / 適用的煙霧測試。
- 報告：畫面映射、變更內容與原因、刻意保留的內容、 限制與驗證證據。
在完成步驟 1–6 之前，不要 撰寫實作程式碼。
五個 UI 層級（按此順序設計）
| # | 層級 | 問題 | 參考資料 |
|---|---|---|---|
| 1 | 文字 | 用戶是否理解這是什麼以及接下來會發生什麼？ | references/microcopy-and-labels.md |
| 2 | 結構 | 存在哪些動作，它們如何分組與排序？ | references/inline-keyboards.md、references/reply-keyboards.md |
| 3 | 導航 | 如何到達此處、返回與離開？我處於哪個狀態？ | references/navigation-and-flows.md |
| 4 | 主體渲染 | 內容是否可讀 — 表格、列表、標題、純文字？ | references/format-selection.md、references/tables.md |
| 5 | 強調 | 此畫面的主要動作是什麼？什麼是危險的？ | references/buttons-and-styles.md、references/custom-emoji.md |
在層級 1 失敗的畫面無法由層級 4–5 挽救。永遠不要從顏色開始。
按鈕要點（完整規則請見 references/buttons-and-styles.md）
每個內聯按鈕只能有一個動作。 根據 Bot API，InlineKeyboardButton 除了 text、icon_custom_emoji_id 和 style 之外，必須且只能 使用其中一個欄位（url、callback_data、web_app、login_url、switch_inline_query*、copy_text、callback_game、pay）。KeyboardButton 除了 text/icon/style 之外，最多 只能使用其中一個欄位。
style（Bot API 9.4） — 可選，只能是以下其中之一：
style | 顏色 | 含義 | 典型標籤 |
|---|---|---|---|
primary | 藍色 | 畫面的主要前進動作 | 繼續、開始、開啟、下一步、選擇 |
success | 綠色 | 提交 / 確認 / 正面完成 | 儲存、確認、發布、提交、完成 |
danger | 紅色 | 破壞性或不可逆的動作 | 刪除、重設、取消訂閱、離開、取消方案 |
| 省略 | 應用程式預設 | 其他所有情況 | 返回、設定、幫助、次要選項 |
如果省略 style，則使用應用程式特定的樣式。每個畫面最多一個 primary。
danger 僅用於真正具破壞性的動作，並應搭配確認步驟。 次要動作如「返回」通常保持無樣式。
icon_custom_emoji_id（Bot API 9.4） — 在按鈕文字前顯示一個自訂表情符號。
僅能由在 Fragment 上購買了額外使用者名稱 的 Bot 使用，或者在 Bot 由其所有者（已擁有 Telegram Premium）直接在私聊、群組和超級群組中發送 的訊息中使用。
切勿憑空發明 ID — 請取得它（references/custom-emoji.md）或詢問用戶。
這兩個欄位都是 在正常按鈕之上的裝飾：標籤必須在沒有顏色和圖示的情況下仍有意義。
訊息主體：選擇最豐富且最有幫助的格式
| 需求 | 使用 |
|---|---|
| 行/列或標籤→值資料 | 表格 — references/tables.md |
| 結構化文件：報告、AI 答案、比較、檢查清單 | 豐富 Markdown |
| 伺服器模板內容、精確的標籤控制 | 豐富 HTML |
| 從資料 / CMS / AST 進行類型化生成 | InputRichBlock 區塊 |
| 帶鍵盤的畫面：簡短提示 + 選項 | 一般 HTML，簡短 |
精確偏移控制，無需 parse_mode | MessageEntity |
| 確實不需要樣式 | 純文字 |
規則：結構化資料應使用真正的表格，切勿使用等寬字體網格 — 但選單畫面應是簡短提示加按鈕，而非長篇大論。完整矩陣：references/format-selection.md。
Bot 運作時的回饋
無訊號等待是 Bot 中最常見的 UX 問題。根據操作類型選擇（完整規則：
references/dynamic-feedback-and-streaming.md）：
| 情況 | 機制 |
|---|---|
| 點擊內聯按鈕 | 先執行 answerCallbackQuery，再進行後續工作 |
| 2–5 秒的操作 | 使用 sendChatAction（typing、upload_photo、…）— 最多 5 秒 |
| 正在生成 AI 文字（私聊） | 使用 sendMessageDraft — 使用相同的 draft_id，最後以 sendMessage 完成 |
| 帶結構的 AI 答案 | 使用 sendRichMessageDraft + <tg-thinking> → sendRichMessage |
| 真實、可命名的階段 | 使用 editMessageText，並進行節流控制 |
| 無法測量的進度 | 使用命名階段 — 絕不使用虛假的百分比 |
| 互動式流程 | Mini App（BottomButton.showProgress()、WebApp.ready()） |
切勿每個 token 都編輯：約每 800–1500 毫秒、約 30–80 個新字元、完成一個句子、或實際階段變更時更新 — 並遵循 retry_after。每個操作使用一個 draft_id / message_id / operation_id，且僅完成一次。
應閱讀的參考資料（由任務引導 — 無需全部閱讀）
UI / UX
- 按鈕標籤、訊息措辭、語氣、文字中的表情符號 →
references/microcopy-and-labels.md style顏色、強調、按鈕佈局與分組 →references/buttons-and-styles.md- 內聯鍵盤、
callback_data、分頁、原地編輯 →references/inline-keyboards.md - 回覆鍵盤、
ForceReply、鍵盤移除、佔位文字 →references/reply-keyboards.md - 畫面、狀態、返回/主頁、指令、選單按鈕、深度連結 →
references/navigation-and-flows.md - 按鈕和文字上的自訂表情符號、取得 ID、資格條件 →
references/custom-emoji.md - 串流答案、思考區塊、進度條、載入器、聊天動作 →
references/dynamic-feedback-and-streaming.md - 使用用戶資料進行個人化、連結、預覽、深度連結 →
references/personalization-and-links.md - 跨畫面一致性 + 完成前檢查清單 →
references/consistency-and-review.md - UI 相關的 Bot API 歷史與版本閘道 →
references/ui-changelog.md - 示範前後對比的情境 →
references/examples-before-after.md
內容渲染
- 表格 →
references/tables.md - 豐富訊息 / 區塊 / 功能矩陣 →
references/telegram-capabilities.md - HTML / MarkdownV2 / entities / 說明文字 / 預覽 →
references/regular-formatting.md - 選擇格式 →
references/format-selection.md - 媒體 →
references/rich-media.md - 限制與分割 →
references/limits-and-splitting.md - 串流草稿與編輯 →
references/streaming-and-editing.md - 頻道、通知、廣播 →
references/channels-and-broadcasting.md
工程
- 調查未知專案 →
references/project-adaptation.md - 跳脫 / 注入 / 用戶或 AI 內容 →
references/security-and-escaping.md - 本地化、RTL、按鈕標籤長度 →
references/localization-and-rtl.md - 錯誤、備援、舊用戶端 →
references/errors-and-fallbacks.md - SDK 缺口 / 原始 Bot API 負載 →
references/sdk-compatibility.md - 測試 →
references/testing-playbook.md - 來源與最後驗證日期 →
references/official-sources.md
本地驗證工具：scripts/validate_skill.py、scripts/validate_references.py、
scripts/validate_keyboard.py（鍵盤 JSON 規則 — 離線執行，無需 token）。
觸發情境：evals/activation-evals.md。
不可協商的規則
- 保留行為。 保留現有的
callback_data、URL、深度連結、負載和處理器路由。視覺上的重新設計不得改寫處理器。如果callback_data的變更無可避免，請在進行變更時告知並更新所有處理器/路由。 - 先文字，後視覺。 在新增顏色或表情符號之前，先修正標籤。
- 不要為了裝飾而使用顏色。 根據動作的含義來指定
style。不要為每個按鈕上色；一個全彩的鍵盤沒有層級結構。 - **`styl
…
[因翻譯而截斷]