簡介haruka-bot-1.2.3 是一個(gè)輕量級(jí)、開箱即用的 Python Telegram 機(jī)器人框架庫面向 Python 初中級(jí)開發(fā)者及自動(dòng)化運(yùn)維、社群管理場景使用者旨在簡化 Telegram Bot 的消息監(jiān)聽、命令路由、插件擴(kuò)展與基礎(chǔ)會(huì)話管理等核心開發(fā)流程。資源包共20個(gè)文件含16個(gè)核心功能模塊的 .py 源碼如事件分發(fā)器、插件加載器、消息處理器、1個(gè) pyproject.toml 構(gòu)建配置、1個(gè)結(jié)構(gòu)清晰的 README.md 文檔、1份 LICENSE 協(xié)議及1個(gè)標(biāo)準(zhǔn) PKG-INFO 元信息文件整體僅29KB便于快速集成與二次定制。已有149人學(xué)習(xí)下載適合希望快速搭建可維護(hù) Bot 服務(wù)、理解典型 bot 架構(gòu)設(shè)計(jì)如插件化組織、事件驅(qū)動(dòng)模型的實(shí)踐者。讀者可直接復(fù)用其 src 目錄下的模塊結(jié)構(gòu)、參考 plugins 示例實(shí)現(xiàn)自定義功能并通過 setup.py 完成標(biāo)準(zhǔn)化安裝與發(fā)布。 拿到一個(gè)haruka-bot-1.2.3.tar.gz很多人第一反應(yīng)就是pip install一把梭。我一開始也這么干直到有次被“裝完了卻 import 不到”卡了半小時(shí)才發(fā)現(xiàn)問題出在我根本沒搞清楚 tar.gz 這種分發(fā)格式的脾氣。今天這篇就從這個(gè)包說起聊聊三件事tar.gz 里的 Python 庫到底該怎么裝、haruka-bot 這類訂閱推送機(jī)器人解決了什么問題、以及真正跑起來之后你會(huì)踩到哪些文檔里不會(huì)寫的坑。適合兩類人看一類是剛接觸 Python 包管理、想搞明白“下載到壓縮包之后下一步干嘛”的新手另一類是已經(jīng)在寫機(jī)器人/爬蟲/自動(dòng)化腳本想把項(xiàng)目工程化、做成可分發(fā)可復(fù)用工具的老手。1. 拆開tar.gzPython庫的分發(fā)格式與安裝邏輯1.1 tar.gz里到底裝了什么tar.gz 在 Linux/macOS 里很常見它其實(shí)是兩層?xùn)|西tar 負(fù)責(zé)把一堆文件打包成一個(gè)文件gzip 負(fù)責(zé)把這個(gè)文件壓縮所以后綴是.tar.gz有些地方也簡寫為.tgz。Python 生態(tài)里這種格式通常對(duì)應(yīng)源碼發(fā)行版sdist也就是說你拿到的是一個(gè)可以直接被 Python 構(gòu)建工具讀懂、進(jìn)而安裝到當(dāng)前環(huán)境的源代碼包。正常情況下解壓之后你會(huì)看到類似這樣的目錄haruka-bot-1.2.3/ ├── pyproject.toml ├── setup.py ├── setup.cfg ├── README.md ├── LICENSE ├── src/ │ └── haruka_bot/ │ ├── __init__.py │ ├── cli.py │ ├── config.py │ ├── core/ │ │ ├── __init__.py │ │ ├── listener.py │ │ ├── notifier.py │ │ └── worker.py │ └── utils/ └── tests/不同項(xiàng)目會(huì)有差異但大體是這么個(gè)布局。pyproject.toml是現(xiàn)在 Python 打包的標(biāo)準(zhǔn)入口里面聲明了項(xiàng)目元信息、依賴項(xiàng)、構(gòu)建后端setup.py是兼容舊流程的腳本很多老項(xiàng)目還在用src/下才是真正的包代碼多一個(gè)src層的好處是避免“從項(xiàng)目根目錄 import 到本地文件夾而不是安裝包”這種經(jīng)典問題。我建議你拿到的第一時(shí)間先解壓看看而不是直接安裝tar -tzf haruka-bot-1.2.3.tar.gz這條命令只列出內(nèi)容不真正解壓幾秒鐘就能讓你確認(rèn)包里有沒有 README、有沒有測試目錄、依賴聲明放在哪個(gè)文件里。這個(gè)習(xí)慣在排查問題的時(shí)候特別有用很多“安裝失敗”其實(shí)打開pyproject.toml看一眼依賴列表就知道原因了。1.2 為什么很多包仍然用tar.gz而不是wheel先區(qū)分兩個(gè)概念sdist源碼發(fā)行版和 wheel構(gòu)建好的發(fā)行版。wheel 就像是超市里洗好切好的菜拿到就能下鍋sdist 則是一袋子帶泥的原材料需要你自己處理。那為什么很多庫還是優(yōu)先發(fā) tar.gz核心原因是兼容性和審計(jì)需求。wheel 是平臺(tái)相關(guān)的同一個(gè)庫在不同 Python 版本、不同操作系統(tǒng)上可能需要編譯成不同的 wheel而 sdist 是全平臺(tái)通用的用戶拿到后在自己的環(huán)境里構(gòu)建天然適配。另外源碼包可以直接看到所有代碼部署在服務(wù)器上時(shí)想審查依賴、確認(rèn)沒有奇怪的邏輯sdist 更方便。haruka-bot 作為 1.2.3 版本以 tar.gz 形式發(fā)布并不代表它比 wheel 差更多是選擇了“源碼分發(fā)”這條路。遇到這種包安裝方式和安裝 wheel 其實(shí)一樣只是 pip 會(huì)先在本地幫你構(gòu)建一步。1.3 安裝方式pip install還是setup.py正確姿勢只有一個(gè)用 pip 安裝本地源碼包pip install ./haruka-bot-1.2.3.tar.gz如果你已經(jīng)解壓進(jìn)了目錄也可以進(jìn)目錄后執(zhí)行python -m pip install .重點(diǎn)來了千萬別跑python setup.py install。這個(gè)命令在舊時(shí)代是合法的但現(xiàn)在它繞過了 pip 的依賴管理可能直接污染系統(tǒng)環(huán)境而且很多新項(xiàng)目用的構(gòu)建后端根本不是 setuptools直接跑 setup.py 會(huì)直接報(bào)錯(cuò)。凡是這類教程一概當(dāng)它過時(shí)就行。如果你打算改這個(gè)包本身的代碼用可編輯安裝pip install -e .這樣源碼改動(dòng)會(huì)即時(shí)生效適合二次開發(fā)。不過注意-e模式對(duì) Python 的導(dǎo)入機(jī)制有一定要求某些復(fù)雜項(xiàng)目會(huì)失效但常見的源碼包問題不大。1.4 裝完怎么驗(yàn)證安裝完別急著跑先確認(rèn)三件事pip show haruka-bot這條命令會(huì)顯示安裝路徑、依賴列表、版本號(hào)確認(rèn)版本是 1.2.3 就說明裝對(duì)了。接著在 Python 里 import 一下import haruka_bot print(haruka_bot.__file__)這一步可以排除“裝是裝了但裝到了當(dāng)前環(huán)境之外”的問題。很多人喜歡先直接運(yùn)行命令行工具報(bào)錯(cuò)后才發(fā)現(xiàn)是環(huán)境混了。我的習(xí)慣是先import再看版本路徑對(duì)了一切都好說。如果 import 報(bào)錯(cuò)說找不到模塊但pip show明明有先別懷疑人生90% 的情況是當(dāng)前終端激活的虛擬環(huán)境和安裝時(shí)用的不是同一個(gè) Python。2. haruka-bot 解決什么問題一個(gè)訂閱推送機(jī)器人的核心鏈路2.1 核心功能定位從一個(gè)包名加版本號(hào)能看出這是一只典型的“訂閱推送機(jī)器人”。這類框架的核心場景一般很明確監(jiān)聽某個(gè)數(shù)據(jù)源比如 B 站 UP 主的動(dòng)態(tài)、某個(gè) RSS 源、某個(gè)網(wǎng)站的更新把變化內(nèi)容抓下來格式化成一條可讀消息推送到聊天群或消息平臺(tái)里。你可能會(huì)問這不就是個(gè)爬蟲加一個(gè)發(fā)消息工具嗎表面上差不多但真正工程化的差距藏在細(xì)節(jié)里如何保證不重復(fù)推送如何優(yōu)雅處理網(wǎng)絡(luò)抖動(dòng)如何做到多個(gè)訂閱源并行不互相阻塞如何讓普通用戶不需要寫代碼就能配置這些都是 haruka-bot 這類項(xiàng)目真正花時(shí)間的地方。2.2 從監(jiān)聽源到消息群的完整數(shù)據(jù)流整個(gè)推送鏈路可以拆成五個(gè)環(huán)節(jié)輪詢?cè)炊〞r(shí)或長連接去數(shù)據(jù)源查最新狀態(tài)。差異比對(duì)拿到新數(shù)據(jù)后和本地緩存的上一次數(shù)據(jù)做對(duì)比。格式化把變化數(shù)據(jù)轉(zhuǎn)成帶標(biāo)題、鏈接、摘要的消息模板。推送通過機(jī)器人協(xié)議把消息發(fā)到目標(biāo)群或頻道。記錄狀態(tài)把已推送的消息 ID 或內(nèi)容指紋存下來防止下次重復(fù)。任何一個(gè)環(huán)節(jié)處理不好都會(huì)出問題。輪詢太頻繁會(huì)被對(duì)方限流差異比對(duì)如果只按最新一條判斷別人刪了一條動(dòng)態(tài)再發(fā)一條就會(huì)出現(xiàn)漏推格式化如果沒考慮消息長度上限長動(dòng)態(tài)會(huì)被截?cái)嗤扑褪∪绻麤]有重試機(jī)制丟一條就真丟了。2.3 異步和事件循環(huán)這類項(xiàng)目最關(guān)鍵的工程決策h(yuǎn)aruka-bot 這種 Python 項(xiàng)目幾乎一定會(huì)用異步編程。原因很直接機(jī)器人同時(shí)要監(jiān)聽很多個(gè)源如果每個(gè)源都開一個(gè)線程線程會(huì)隨訂閱數(shù)量線性增長內(nèi)存和上下文切換開銷都不小而用 asyncio 單線程就能管理成千上萬個(gè)并發(fā)任務(wù)協(xié)程的調(diào)度開銷比線程小很多。但也別把 asyncio 神話了異步編程的調(diào)試難度比同步代碼高一個(gè)量級(jí)。最經(jīng)典的坑是你在一個(gè)協(xié)程函數(shù)里偷偷調(diào)用了requests.get()這會(huì)同步阻塞整個(gè)事件循環(huán)導(dǎo)致其他訂閱源全部卡住。正確做法是用支持異步的 HTTP 客戶端比如httpx.AsyncClient或aiohttp。有個(gè)簡單的判斷辦法看到代碼里用了await就不要再往里面塞同步網(wǎng)絡(luò)請(qǐng)求和同步文件讀取除非你明確知道自己在干什么。2.4 去重、限流與失敗重試這三點(diǎn)是推送機(jī)器人“看起來正?！焙汀罢娴姆€(wěn)定”的分水嶺。去重不能只靠內(nèi)存緩存進(jìn)程一重啟就全沒了。實(shí)際項(xiàng)目里至少要落盤常見做法是用sqlite3存一張表或者是用一個(gè) JSON 文件把最近 N 條消息指紋持久化。消息指紋一般取內(nèi)容里的穩(wěn)定字段做哈希比如動(dòng)態(tài) ID 或鏈接。限流也有兩層面一是對(duì)數(shù)據(jù)源輪詢頻率不能太激進(jìn)遵守對(duì)方更新頻率二是對(duì)消息平臺(tái)機(jī)器人發(fā)消息有頻率限制連續(xù)推幾十條會(huì)被平臺(tái)臨時(shí)封禁。所以推送側(cè)要有一個(gè)簡單隊(duì)列控制每秒最大發(fā)送條數(shù)可用asyncio.Semaphore或rate-limiter這類庫實(shí)現(xiàn)。失敗重試要設(shè)計(jì)退避策略。第一次失敗等 2 秒重試再失敗等 4 秒、8 秒最多重試 5 次而不是失敗了立刻無限重試。重試時(shí)還要區(qū)分“這次錯(cuò)誤是臨時(shí)網(wǎng)絡(luò)問題”還是“永久性失敗比如配置文件寫錯(cuò)了”后者再怎么重試也沒用應(yīng)該直接報(bào)警打日志。3. 從零跑通環(huán)境準(zhǔn)備、安裝與最小配置3.1 Python版本和虛擬環(huán)境先確認(rèn) Python 版本建議 3.9 及以上?，F(xiàn)在很多新庫的語法和類型標(biāo)注依賴新解釋器Python 3.8 以下大概率裝不上。我強(qiáng)烈建議用虛擬環(huán)境venv就夠了python3 -m venv .venv source .venv/bin/activate在虛擬環(huán)境里裝包可以避免“全局環(huán)境里裝了幾百個(gè)包哪次刪庫跑路也不知道刪了誰”的悲劇。部署到服務(wù)器時(shí)虛擬環(huán)境還能保證生產(chǎn)環(huán)境和開發(fā)環(huán)境一致不至于代碼在本地能跑、上服務(wù)器就報(bào)依賴缺失。3.2 安裝依賴時(shí)最容易卡住的點(diǎn)裝源碼包時(shí)pip 會(huì)去拉取pyproject.toml里聲明的依賴。這一步在國內(nèi)網(wǎng)絡(luò)環(huán)境下經(jīng)常卡住我的經(jīng)驗(yàn)是先升級(jí) pip 和 wheel再裝pip install -U pip wheel setuptools pip install ./haruka-bot-1.2.3.tar.gz如果網(wǎng)絡(luò)確實(shí)很慢可以配置 PyPI 鏡像源加速。設(shè)置鏡像可以寫在命令里也可以寫成全局配置比如在~/.pip/pip.conf里加[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple提示改鏡像源只影響 pip 下載依賴的速度和項(xiàng)目本身的運(yùn)行邏輯無關(guān)。裝完建議再切回默認(rèn)源避免某些私有依賴在鏡像源上找不到。另一個(gè)容易卡住的點(diǎn)是編譯依賴。如果這個(gè)包里有 C 擴(kuò)展安裝時(shí)可能觸發(fā)本地編譯器。如果報(bào)錯(cuò)找不到 gcc 或者 Python 頭文件需要先安裝系統(tǒng)級(jí)依賴。遇到這種情況看報(bào)錯(cuò)信息里的關(guān)鍵詞比如gcc: command not found、Python.h: No such file都能快速定位是缺了哪一類工具。3.3 最小配置文件怎么搭大多數(shù)機(jī)器人框架都會(huì)提供一個(gè)示例配置文件。最小配置通常包含機(jī)器人賬號(hào)憑據(jù)、要監(jiān)聽的訂閱源列表、目標(biāo)推送群列表、輪詢間隔。下面是一個(gè)高度概括的示例配置格式不同框架具體的字段名會(huì)不同但結(jié)構(gòu)基本是這三塊# config.yaml bot: account: 你的機(jī)器人賬號(hào) platform: qq subscribe: - type: bilibili uid: 123456789 interval: 30 notify: - group_id: 目標(biāo)群號(hào) message_template: {user} 發(fā)布了新動(dòng)態(tài){title} {url}注意interval指輪詢間隔單位是秒。不要設(shè)成個(gè)位數(shù)否則你的 IP 很快會(huì)被對(duì)方服務(wù)拉黑。一個(gè)真實(shí)環(huán)境里能穩(wěn)定跑幾周的配置輪詢間隔至少在 30 秒以上。3.4 啟動(dòng)服務(wù)并驗(yàn)證推送啟動(dòng)命令通常由項(xiàng)目的 CLI 入口提供形式一般是這樣haruka-bot init haruka-bot runinit用于生成配置文件模板run才是正式啟動(dòng)。建議第一次啟動(dòng)時(shí)開著前臺(tái)日志跑別用 nohup 直接后臺(tái)化。前臺(tái)跑的好處是你能第一時(shí)間看到推送鏈路是否打通。驗(yàn)證推送是否正常有一個(gè)很實(shí)用的中間測試先手動(dòng)觸發(fā)一次推送觀察日志里有沒有“推送成功”的回執(zhí)。如果日志顯示推送成功但群里沒收到消息那問題多半在群配置或機(jī)器人權(quán)限而不是代碼邏輯。haruka-bot test-notify如果項(xiàng)目提供了這類命令啟動(dòng)前務(wù)必先跑一遍它只會(huì)浪費(fèi)你十秒鐘卻能省掉半小時(shí)的排障時(shí)間。4. 讓haruka-bot為我所用配置調(diào)優(yōu)與二次開發(fā)思路4.1 配置項(xiàng)逐條拆解我看了不少同類項(xiàng)目的配置文件最容易讓人困惑的不是寫代碼而是搞不懂每個(gè)配置項(xiàng)改了到底有什么影響。這里挑幾個(gè)高頻的講配置項(xiàng)作用推薦值備注worker_num并發(fā)任務(wù)數(shù)4~8太高會(huì)導(dǎo)致 CPU 頻繁切換太低推送延遲會(huì)變高retry_times失敗重試次數(shù)3~5超過 5 次基本說明問題無法靠重試解決backoff_factor退避系數(shù)2.0重試等待時(shí)間按指數(shù)增長2 是常見值message_limit單條消息最大長度按平臺(tái)限制設(shè)QQ/TG 等平臺(tái)限制不同log_level日志級(jí)別INFO排障時(shí)切 DEBUG日常跑 INFOworker_num這個(gè)參數(shù)很多人忽略其實(shí)它直接影響推送的及時(shí)性。假設(shè)你訂閱了 100 個(gè) UP 主單個(gè) worker 處理一個(gè)源需要 1 秒串行一輪就要 100 秒設(shè)成 4 個(gè) worker理論上可以降到 25 秒左右。但也不是越大越好因?yàn)槊總€(gè)源都會(huì)發(fā)起網(wǎng)絡(luò)請(qǐng)求并發(fā)太高容易被判定為異常行為。4.2 增加新的訂閱源好的框架在設(shè)計(jì)上會(huì)預(yù)留擴(kuò)展點(diǎn)。常見的做法是讓你繼承一個(gè)基類實(shí)現(xiàn)fetch()和parse()兩個(gè)方法。一個(gè)簡易的示例# custom_source.py from haruka_bot.core import BaseSource class RSSSource(BaseSource): async def fetch(self, url): # 用 httpx 獲取 RSS 內(nèi)容 async with httpx.AsyncClient() as client: resp await client.get(url) return resp.text async def parse(self, raw): # 把 XML 解析成標(biāo)題/鏈接/摘要 items feedparser.parse(raw).entries return [ {title: item.title, link: item.link, content: item.summary} for item in items ]然后在配置文件里注冊(cè)這個(gè)自定義源subscribe: - type: custom path: custom_source.RSSSource url: https://example.com/rss interval: 60這種“插件化”設(shè)計(jì)的關(guān)鍵在于BaseSource只要求實(shí)現(xiàn)“拉取 解析”兩個(gè)動(dòng)作把數(shù)據(jù)源差異隔離在自定義類里核心的推送、去重、重試邏輯完全復(fù)用。這就是框架存在的意義你不用每次從頭寫一遍推送鏈路。4.3 自定義消息模板消息模板一般支持字符串占位符。一定要去讀項(xiàng)目文檔里的占位符列表不同字段名在不同版本里可能不同。常見的字段有{user} # 用戶名 {user_id} # 用戶 ID {title} # 動(dòng)態(tài)標(biāo)題 {content} # 動(dòng)態(tài)摘要 {url} # 原文鏈接 {timestamp} # 發(fā)布時(shí)間我踩過的坑是模板里寫了{(lán)time}結(jié)果框架解析不出來直接把{time}原樣推送到群里。后來才發(fā)現(xiàn)那是 1.1 版本的字段1.2 版本改名成了{(lán)timestamp}。你的 haruka-bot 是 1.2.3字段大概率會(huì)以最新文檔為準(zhǔn)涉及模板的時(shí)候務(wù)必先跑一條測試消息檢查。4.4 與其他Python庫組合定時(shí)任務(wù)、持久化、可視化訂閱推送機(jī)器人往往不只是一個(gè)“搬運(yùn)工”和 Python 生態(tài)里的其他庫組合起來能玩出更多花樣。比如用APScheduler做定時(shí)統(tǒng)計(jì)每天晚上把當(dāng)天所有訂閱源的推送數(shù)量匯總成一份日?qǐng)?bào)from apscheduler.schedulers.asyncio import AsyncIOScheduler async def daily_report(): stats await get_today_stats() await send_report(stats) scheduler AsyncIOScheduler(timezoneAsia/Shanghai) scheduler.add_job(daily_report, cron, hour22, minute0) scheduler.start()再比如把推送歷史存進(jìn) SQLite后面用 pandas 分析哪個(gè)時(shí)段活躍度最高、哪個(gè) UP 主動(dòng)態(tài)被轉(zhuǎn)發(fā)次數(shù)最多甚至可以據(jù)此調(diào)整輪詢優(yōu)先級(jí)。持久化這件事一加進(jìn)來這個(gè)“小機(jī)器人”就有點(diǎn)數(shù)據(jù)產(chǎn)品的意思了。5. 運(yùn)行過程中我踩過的坑和排查路徑5.1 明明pip list里有卻ModuleNotFoundError這個(gè)坑我踩了不止一次癥狀是pip list能看到 haruka-bot或者pip show顯示正常但import haruka_bot就是報(bào)找不到。常見的排查鏈路which python python -c import sys; print(sys.executable) python -m pip show haruka-bot先看which python指向哪。如果你在虛擬環(huán)境里which python應(yīng)該指向項(xiàng)目目錄下的.venv/bin/python如果指向/usr/bin/python說明你激活虛擬環(huán)境失敗。再運(yùn)行python -m pip show注意是python -m pip而不是直接pip這能確保用的 pip 和當(dāng)前 python 是同一個(gè)環(huán)境。按這個(gè)順序排查基本五分鐘內(nèi)能定位問題。大多數(shù)時(shí)候就是激活虛擬環(huán)境的姿勢不對(duì)或者終端開了新窗口但忘了重新source .venv/bin/activate。5.2 協(xié)程與事件循環(huán)沖突跑了一段時(shí)間后某次重啟突然報(bào)錯(cuò)RuntimeError: asyncio.run() cannot be called from a running event loop或者There is no current event loop in thread。這個(gè)坑的根源在于asyncio 的事件循環(huán)是和線程綁定的。你在主線程用asyncio.run()啟動(dòng)了一個(gè)協(xié)程協(xié)程里面又有人調(diào)用了asyncio.run()就會(huì)沖突。修復(fù)方案分兩層。第一層是代碼層面確保只用一次asyncio.run()作為入口不要嵌套調(diào)用。第二層是框架層面如果你的 haruka-bot 是運(yùn)行在 NoneBot2 這類異步框架上框架本身已經(jīng)幫你管理事件循環(huán)了你就不要在插件里自己開新的循環(huán)。另一個(gè)常見坑是你在協(xié)程里用了time.sleep()而不是await asyncio.sleep()。前者會(huì)阻塞整個(gè)事件循環(huán)表現(xiàn)是“一個(gè)訂閱源卡住了所有訂閱源都卡住”。排查方法很簡單看日志里是不是只有一條任務(wù)在跑其他全部超時(shí)。把time.sleep()全局替換成await asyncio.sleep()就能解決。5.3 推送偶爾丟消息重試與去重不生效明明配置了重試但有些消息還是丟了這種情況特別讓人困惑。我排查過的實(shí)際案例中問題往往出在重試的“冪等性”上。假設(shè)推送失敗后重試重試時(shí)消息里帶的動(dòng)態(tài) ID 是新的平臺(tái)返回成功但此時(shí)去重表里記錄的不是這條消息本身而是之前失敗那次的請(qǐng)求 ID兩次數(shù)據(jù)的指紋對(duì)不上導(dǎo)致實(shí)際推送內(nèi)容還是舊的。更糟的是如果去重邏輯是“發(fā)現(xiàn)同一條動(dòng)態(tài)已經(jīng)推送過就跳過”一旦上次失敗但狀態(tài)已經(jīng)標(biāo)記為“已推送”重試永遠(yuǎn)不會(huì)發(fā)生。我的建議是去重標(biāo)記要在推送成功之后才寫入而且寫入的 key 要穩(wěn)定比如動(dòng)態(tài) ID 或內(nèi)容哈希。重試時(shí)檢查的不是“有沒有推送過”而是“這條動(dòng)態(tài)有沒有推送成功過”。這是一個(gè)很小的邏輯差異但很多人沒注意。5.4 日志里看不到有效信息怎么辦遇到問題最怕的是日志全是一片沒有上下文的 INFO這時(shí)第一件事是把日志級(jí)別調(diào)到 DEBUG。log_level: DEBUGDEBUG 日志會(huì)打印每個(gè)訂閱源的請(qǐng)求 URL 和響應(yīng)狀態(tài)碼你能直觀看到到底是網(wǎng)絡(luò)請(qǐng)求沒有發(fā)出還是發(fā)出了被對(duì)方拒絕還是解析時(shí)字段取不到值。我個(gè)人排查的經(jīng)驗(yàn)是看到HTTP 429就說明頻率太高被限流看到TimeoutError就是網(wǎng)絡(luò)超時(shí)看到KeyError: data說明接口返回結(jié)構(gòu)變了解析代碼要更新。如果項(xiàng)目自帶日志文件路徑配置記得把日志寫到獨(dú)立文件里不要把 stdout 和 stderr 混在一起。分開之后你會(huì)少掉很多困惑。最后再分享一個(gè)我在實(shí)際使用中的小技巧不要只把 haruka-bot 當(dāng)命令行工具用它本身是一個(gè) Python 包你完全可以把它作為一個(gè)模塊 import 進(jìn)自己的腳本里復(fù)用它的拉取、去重、推送邏輯再在外面包一層你自己的業(yè)務(wù)。比如我之前就寫過一個(gè)腳本把它的核心推送函數(shù)接進(jìn)自己的 Web 后臺(tái)手動(dòng)點(diǎn)擊按鈕觸發(fā)一次推送用于測試消息模板的渲染效果。這種“庫 應(yīng)用”雙模式才是 tar.gz 源碼包真正的價(jià)值所在。本文還有配套的精品資源點(diǎn)擊獲取