兩周前，Telegram 正式上線了富消息（Rich Messages）格式。一條消息里，你可以塞進(jìn)標(biāo)題、列表、表格、地圖、拼貼畫、幻燈片，還能把照片、視頻、動(dòng)圖、音頻、語音消息嵌進(jìn)去，最多 50 個(gè)媒體文件，最多 500 個(gè)塊狀結(jié)構(gòu)，單條文本不超過 32768 個(gè)字符。官方文檔把這些上限寫得清清楚楚，但翻遍 npm，找不到一個(gè)能幫你把這些零件像搭積木一樣拼起來的庫。你只能手搓 HTML 字符串，自己轉(zhuǎn)義尖括號(hào)，自己數(shù)嵌套層數(shù)，自己卡著 16 層上限調(diào)整結(jié)構(gòu)——然后半夜收到用戶截圖：一句“內(nèi)部錯(cuò)誤”，因?yàn)槟阃颂幚砟硞€(gè)列表項(xiàng)里的標(biāo)簽。

我第一次踩這個(gè)坑，是在給一個(gè)團(tuán)隊(duì)協(xié)作機(jī)器人加可折疊的詳情面板。原本以為三五行 HTML 就能搞定，結(jié)果因?yàn)樾柰瑫r(shí)嵌入有序列表、復(fù)選框、引用塊和視頻字幕，寫出來的字符串越滾越大，到最后嵌套深度超限，Telegram 直接拒收。調(diào)試時(shí)盯著滿屏的

1. ，根本分不清哪一層多了一個(gè)閉合標(biāo)簽。那一刻我突然意識(shí)到，缺的不是生成 HTML 的邏輯，而是一個(gè)能在編碼階段就攔住這些錯(cuò)誤的類型化構(gòu)建器。于是我花了一個(gè)周末，用 TypeScript 寫了tg-rich-messages——一個(gè)零運(yùn)行時(shí)依賴的小型庫，專門用來把富消息的構(gòu)建過程從“手工作坊”升級(jí)成“流水線拼裝”。
   這個(gè)庫的核心設(shè)計(jì)很直白：你不需要懂 HTML，只需要關(guān)心“我要一個(gè)粗體標(biāo)題，一段帶刪除線的段落，再來一個(gè)可從 7 開始的 a) 編號(hào)列表”。它提供了一套純粹的類型化 API，所有內(nèi)聯(lián)元素和塊元素都被抽象成可組合的函數(shù)。比如內(nèi)聯(lián)部分，你現(xiàn)在可以不做任何轉(zhuǎn)義地調(diào)用bold()、italic()、underline()、strikethrough()、spoiler()、code()、marked()、sub()、sup()，還能直接附加鏈接、@提及、emoji 和日期時(shí)間戳。塊元素同樣完整：h1 到 h6 的標(biāo)題，普通段落，pre代碼塊，有序/無序列表（帶復(fù)選框那種），引用塊，pullquote 強(qiáng)調(diào)塊，支持對(duì)齊、colspan、rowspan 和斑馬紋的表格，可折疊的 details 塊，地圖、拼貼畫、幻燈片。媒體方面，photo、video、animation、audio、voice 全都有單獨(dú)的處理單元，每個(gè)還能掛載 caption 和 credits 信息。所有這些零件，你都可以在 TypeScript 里自動(dòng)補(bǔ)全看到類型提示，再也不用擔(dān)心把photo的 caption 參數(shù)錯(cuò)寫成 string 數(shù)組。
   更讓我覺得順手的，是它提供了fmtRich這個(gè)帶標(biāo)簽的模板字面量。你可以像寫 Markdown 一樣，在反引號(hào)里直接混用內(nèi)聯(lián)格式：fmtRich`${bold`Hello`} ${italic`world`}! Here is some ${code`inline code`}.`。編譯階段它會(huì)自動(dòng)拆解成內(nèi)聯(lián)片段，并生成正確的嵌套 HTML，最終輸出一個(gè)
   包裹的干凈字符串。這意味著你即使不想學(xué)習(xí)完整的塊級(jí)構(gòu)造器 API，只靠模板字面量就能把一條包含多種富格式的通知快速拼出來，對(duì)快速原型和簡(jiǎn)單回復(fù)場(chǎng)景來說，成本幾乎為零。
   實(shí)際跟 Telegram Bot API 對(duì)接的流程也非常短。你只需要構(gòu)造一個(gè)消息文檔doc()，把標(biāo)題、段落、列表、表格等塊零件串進(jìn)去，然后調(diào)toInputRichMessage()方法就能拿到sendRichMessage方法所需的InputRichMessage負(fù)載。像這樣用 fetch 發(fā)給https://api.telegram.org/bot${TOKEN}/sendRichMessage就完成了。不用額外序列化，不用手動(dòng)拼 JSON。整個(gè)鏈路的代碼行數(shù)，可能還不到你之前在字符串里寫錯(cuò)一個(gè)標(biāo)簽后排查問題所花的時(shí)間。
   構(gòu)建過程中，內(nèi)置的validate()方法會(huì)按照官方限制自動(dòng)卡位：用字符數(shù)而非字節(jié)數(shù)校驗(yàn)文本長度，確保不超過 32768；統(tǒng)計(jì)媒體附件數(shù)量，上限卡在 50；清點(diǎn)塊結(jié)構(gòu)總數(shù)，最多 500 個(gè)；遍歷嵌套深度，一旦觸及 16 層就提前報(bào)錯(cuò)。這份檢查在你本地運(yùn)行測(cè)試時(shí)就會(huì)生效，不用等到消息推送給 Telegram 被駁回后才意識(shí)到哪里超標(biāo)了。而且整個(gè)庫的設(shè)計(jì)是 tree?shakeable 的，你只用了bold和list，打包工具就不會(huì)把table或collage的代碼卷進(jìn)去，機(jī)器人的體積不會(huì)有半點(diǎn)膨脹。
   回過頭來看，這個(gè)庫解決的其實(shí)不是新技術(shù)問題，而是開發(fā)體驗(yàn)斷層。Telegram 給了一套表達(dá)能力極強(qiáng)的富消息格式，但把格式管理、嵌套關(guān)系、邊界約束全部交給了開發(fā)者硬扛。當(dāng)你的機(jī)器人還需要處理業(yè)務(wù)邏輯時(shí)，沒有人樂意再花一個(gè)小時(shí)調(diào)試 HTML 的閉合順序。我把它開源出來，一是因?yàn)樽约好恐芏家?，二是因?yàn)槲蚁嘈?，只有把?gòu)建成本壓到接近零，才會(huì)有更多 Telegram 機(jī)器人從純文本提醒，進(jìn)化到帶有信息層級(jí)、可交互塊、多媒體混排的富消息形態(tài)?，F(xiàn)在，你只需要裝好npm install tg-rich-messages，引入三四個(gè)函數(shù)，然后專注于消息內(nèi)容本身——剩下的 HTML 渲染、轉(zhuǎn)義、深度校驗(yàn)，全讓庫處理。這大概就是一個(gè)工具所能給出的最好承諾：臟活它做，你只管表達(dá)。