最近我尋找一個可以在終端機管理 Dev.to 文章的 CLI 工具。我每月撰寫 4-5 篇文章，會強迫症式追蹤分析數據，並希望有基於 git 的工作流程。

我找到了 9 個現有工具。全部試過後，結果如下：

  • devto-cli (Node): 最後一次提交是 2 年前。安裝時就壞掉。
  • dev-to-git (Node): 只能同步到本地。無法推回。
  • slinkity: 已棄置。
  • forem-cli: 40+ 個端點中只實作了 3 個。

每個工具都做同一件事：發布文章。就這樣。也許拉取。也許驗證標籤。

與此同時，Dev.to API 有 40+ 個端點，包含分析、語意搜尋、機器學習驅動的內容概念、追隨者互動、趨勢追蹤，以及閱讀清單管理。沒有人在使用這些功能。

所以我建立了 devpub。

目錄

devpub 的功能（其他工具沒有的） 

# 基本功能（每個工具都做）
devpub push -f articles/my-post.md
devpub pull

# 在終端機查看分析數據
devpub stats
# Views: 246.5K | Reactions: 4.4K | Comments: 402 | Followers: 18.9K

# 完整儀表板與熱門文章
devpub dashboard

# AI 驅動的搜尋（語意，而非關鍵字）
devpub search "building serverless apps" --semantic

# 現在正在流行的內容
devpub trends

# 發布前先找出問題
devpub validate

Enter fullscreen mode Exit fullscreen mode

差異不在於單一功能，而在於涵蓋範圍。以下是比較表：

功能 devpub 其他工具
發布/更新文章 Yes Yes
將文章拉取到本地 Yes Some
分析數據（7 個端點） Yes No
語意搜尋 Yes No
趨勢發現 Yes No
文章驗證 Yes No
速率限制（30 req/30s） Yes No
失敗重試機制 Yes No
Concepts API（機器學習主題） Yes No

我在 Dev.to API 中發現的功能

在建立 devpub 的過程中，我發現了幾個沒有明顯文件記載的 API 端點：

1. 語意搜尋 -- Dev.to 有一個完整的基於嵌入的搜尋系統，使用 Gemini 嵌入（768 維向量）搭配 pgvector。您可以依據意義搜尋文章，而非僅靠關鍵字。該端點會回傳餘弦相似度分數。

2. Concepts API -- 這些是機器學習生成的話題分類，附帶每日指標：頁面瀏覽量、反應、評論、人氣分數。比手動標籤強大得多。

3. V1 Accept Header -- V1 API 需要 Accept: application/vnd.forem.api-v1+json。若無此標頭，您會收到 V0 的回應。我在任何競爭對手的程式碼中都沒看到這一點被提及。

4. 巢狀分析回應 -- 分析端點回傳巢狀物件，例如 {"page_views": {"total": 246454, "average_read_time_in_seconds": 306}}，而非扁平整數。我檢查過的每個工具要麼不使用分析，要麼會在這種結構上出錯。

建置故事（實際發生的事）

我用一天的時間建立了 devpub 的核心。從星期一下午 2 點開始，晚上就有了可運作的 CLI。以下是真實的時間軸：

第 1-2 小時：研究

在寫任何程式碼之前，我分析了 9 個競爭工具。下載、閱讀它們的原始碼，整理每個工具使用了哪些 API 端點。發現最「完整」的工具涵蓋了 40+ 個端點中的 12 個。大多數只涵蓋 3-5 個。

然後我閱讀了整個 Forem API 文件。不是大家都會看的摘要頁面，而是完整的 V1 規格。這就是我找到語意搜尋、概念，以及其他工具都不知道存在的分析端點的地方。

第 3 小時：搭建骨架

pyproject.toml、src 佈局、Click CLI 入口點。雖然無聊，但我花了 15 分鐘就讓 devpub --help 運作。這裡的關鍵決定是：使用 httpx 而非 requests。httpx 提供連線池、適當的逾時設定，以及日後切換到 async 的選項，而不需要改變介面。

第 4-5 小時：API 用戶端

這是我花最多時間的地方。不是因為 HTTP 呼叫很難，而是因為我希望用戶端從第一天起就具備生產等級：

  • 真正有效的速率限制（滑動視窗，而非單純的睡眠計時器）
  • 針對 429 與 5xx 錯誤的指數退避重試
  • 適當的錯誤訊息，而非堆疊追蹤

第一版並沒有這些功能。它只是呼叫 raise_for_status() 並對使用者丟出難看的 httpx.HTTPStatusError 例外。我在測試時發現了這個問題，當我拉取自己的 86 篇文章，在第 30 篇時遇到速率限制。整個程式就崩潰了。

第 6 小時：使用我的真實帳號測試

這就是有趣的地方。我第一次呼叫 devpub stats 時發生崩潰：

TypeError: '>=' not supported between instances of 'dict' and 'int'

Enter fullscreen mode Exit fullscreen mode

原來分析端點回傳 {"page_views": {"total": 246454}}，而不是 {"page_views": 246454}。巢狀字典。現有工具都無法正確處理，因為現有工具都不使用分析功能。

健康檢查端點也讓我驚訝。在 V1 API（帶有 Accept 標頭）中，/health_checks/app 需要驗證。若無標頭，會回傳 401。所以我將健康檢查改為呼叫 /users/me。

第 7 小時：push --all 的驚嚇

在測試期間，push --all 差點把我的 README.md 發布到 Dev.to。原本的邏輯是：找到任何在 frontmatter 中有 title 的 .md 檔案就推送。我的 README 有帶 title 的 YAML frontmatter。

我修正了這個問題，要求同時擁有 title 與 published 鍵，並且只掃描已知的目錄（articles/、posts/、content/、drafts/）。雖然是小事，但想像一下不小心把 CONTRIBUTING.md 當成 Dev.to 文章發布出去。

如果重來我會做什麼改變

  1. 從 pull 指令開始，而不是 push。 Pull 會強迫您在建立資料模型之前先了解 API 回應格式。我先根據文件建立模型，之後發現真實回應不同時才修正。

  2. 從一開始就撰寫模擬測試。 我先寫完所有程式碼才寫測試。應該在撰寫用戶端方法時就同時撰寫 API 模擬回應。這樣就能立刻發現巢狀字典的問題。

  3. 在 v0.0.1 就包含速率限制器。 我一開始想著「晚點再加」。在真實測試的 30 分鐘內就遇到限制。應該從第一個 commit 就加入。

架構（給貢獻者）

src/devpub/
  api/        # 帶有速率限制與重試的 HTTP 用戶端
  cli/        # Click 指令 + Rich 終端機輸出  
  core/       # 商業邏輯（文章、同步、驗證、設定）

Enter fullscreen mode Exit fullscreen mode

關鍵決定：

  • Python + Click + Rich -- 大多數貢獻者熟悉，終端機使用者體驗佳
  • httpx -- 支援 async，內建逾時處理
  • 滑動視窗速率限制器 -- 每 30 秒 30 個請求，自動睡眠
  • 3 次指數退避重試 -- 處理 429 與 5xx 錯誤而不崩潰
  • 基於 frontmatter 的追蹤 -- 文章 ID 儲存在您的 markdown 檔案中，無需資料庫

57 個測試，全部通過

$ pytest -v
57 passed in 1.08s

Enter fullscreen mode Exit fullscreen mode

測試使用 respx 模擬 HTTP 層。CI 中沒有真實的 API 呼叫。涵蓋：

  • API 用戶端（所有端點、錯誤碼、重試）
  • 文章模型（frontmatter 往返、slug 生成、標籤解析）
  • 同步邏輯（推送新文章、更新現有文章、dry run、錯誤處理）
  • 驗證（標題長度、標籤數量、正文檢查、canonical URL）

試用

pip install devpub
export DEVPUB_API_KEY=your_key_here
devpub doctor

Enter fullscreen mode Exit fullscreen mode

或從原始碼安裝：

git clone https://github.com/simplynadaf/devpub.git
cd devpub
pip install -e .

Enter fullscreen mode Exit fullscreen mode

在以下網址取得您的 API 金鑰：https://dev.to/settings/extensions

與 AI 代理相容

每個指令都回傳結構化輸出，會自動處理速率限制，並支援 --dry-run。AI 程式碼代理（Claude Code、Copilot、Cursor）可以將 devpub 作為其發布層。代理撰寫文章，devpub 驗證、推送並追蹤表現。初始設定後無需人工介入。

貢獻

本專案目前處於 beta 階段。歡迎提交 PR。以下是一些需要協助的地方：

  • 效能：pull 指令會對每篇文章發出一次 API 呼叫。可以批次處理嗎？
  • 圖片重寫：推送時應將相對路徑轉換為 GitHub raw URL
  • 終端機圖表：--graph 旗標已被接受但尚未實作
  • Hashnode 配接器：跨平台發布的骨架已就緒，需要實作

請查看 issues 尋找標有 good first issue 的項目。

GitHub: github.com/simplynadaf/devpub

如果這節省了您的時間，請給 repo 按星。如果有東西壞了，請開 issue。如果您想要某個功能，請送 PR。

您目前的 Dev.to 工作流程是什麼？您是在瀏覽器編輯器中撰寫，還是已經有本地設定？想知道大家遇到的痛點是什麼。

📺 在 YouTube 觀看完整示範

由 Sarvar Nadaf 建立 - Cloud Architect
追蹤我： Dev.to | GitHub | YouTube | LinkedIn