Hugging Face hf CLI 針對代理優化的重新設計，降低了 Token 使用量並提升了成功率

Hugging Face hf CLI 針對代理優化的重新設計，降低了 Token 使用量並提升了成功率

TL;DR

Hugging Face 宣布 hf CLI 已完成重新設計以針對代理進行優化，在 Claude Code 和 Codex 等編碼代理執行多步驟 Hub 任務時，可減少高達 6 倍的 Token 使用量並提高成功率。

Hub 上的代理流量

Hugging Face 從 2026 年 4 月開始追蹤編碼代理對 Hub 的使用情況。透過偵測如 CLAUDECODE、CODEX_SANDBOX 和通用的 AI_AGENT 等環境變數，hf CLI 會在 agent/<name> user-agent 標頭中標記請求。目前最活躍的兩個代理是 Claude Code（約 39.5k 個獨立用戶，48.6M 次請求）和 Codex（約 34.8k 個用戶，36.4M 次請求）。這些數據僅從 2026 年 4 月開始收集，就已經顯示代理已構成 Hub 流量中相當大且持續增長的比例。

為人類與代理而生

該 CLI 現在支援兩種輸出模式，系統會根據偵測到的代理環境自動選擇。

單一指令，多種呈現方式

  • 人類模式（互動式終端機中的預設模式）會列印對齊的表格、截斷長欄位、添加 ANSI 顏色並顯示實用的提示。
  • 代理模式（自動偵測）會輸出包含完整識別碼、ISO 時間戳記和完整標籤列表的原始 TSV，不含任何 ANSI 碼或截斷。這種格式對於基於 Token 的 LLM 來說非常精簡且易於解析。

兩種模式共用相同的底層日誌輔助工具（.table()、.result()、.json()），並可以透過 --format human|agent|json|quiet 強制指定。

下一個指令提示

每個成功的指令現在都會以一個確定的提示結束，顯示使用者或代理應執行的確切下一個 CLI 調用（包含 ID）。錯誤也會包含可操作的建議，例如 Use --yes to skip confirmation.。提示會列印到 stderr，因此絕不會污染代理解析的數據流。

非阻塞且安全可重試

  • 在代理模式中，破壞性指令會快速失敗並提供明確的修復訊息，而不是提示進行互動式確認。
  • 冪等標記（Idempotent flags）如 --exist-ok 和 --dry-run 讓重複執行變得安全，這對於會在超時時自動重試的代理至關重要。

可發現、可預測的指令

該 CLI 遵循一致的 resource + verb 模式（hf models ls、hf repos create、hf jobs run）。每個 --help 區段末尾都有可複製貼上的範例，使代理能夠快速匹配指令。-q（每行一個 ID）和 --json 等選項進一步簡化了管道（piping）和下游處理。

為編碼代理進行 hf CLI 基準測試

一個專用的測試框架對兩個代理——Claude Code (Sonnet 4.6) 和 Codex (GPT-5.5) 進行了 18 個真實 Hub 任務（例如：聚合熱門模型、創建帶有分支/標籤的儲存庫、同步 bucket）的評估。每個任務分別使用以下方式執行：

  1. 使用 hf CLI（包含及其技能功能，以及不包含）
  2. 直接使用 curl 調用 / huggingface_hub Python SDK

每個配置針對每個任務執行 10 次重複，總計約 1,000 次評分運行。成功率是透過重新查詢實時 Hub 來驗證，而不是信任代理的 TASK_COMPLETE 標記。

結果摘要

代理 工具 成功率 相對於 CLI 的 Token 使用量 自我報告錯誤
Claude Code (Sonnet 4.6) hf CLI 0.94 基準線
curl / SDK 0.84 1.3–1.6× 11 / 163
Codex (GPT-5.5) hf CLI 0.93 基準線
curl / SDK 0.92 1.6–1.8× 10 / 163

複雜的多步驟任務（例如：bucket 同步 + 修剪、帶有分支/標籤的儲存庫創建）在使用 curl/SDK 時會產生 2.4 倍至 6 倍的 Token 消耗，而簡單的唯讀操作則顯示出與 CLI 幾乎持平，甚至 curl/SDK 略具優勢。

關鍵結論

  • hf CLI 在多步驟工作流程中始終能實現更高的成功率和大幅降低的 Token 消耗。
  • 即使使用更強大的 LLM (GPT-5.5)，curl/SDK 仍然非常浪費資源；而使用較弱的模型 (Sonnet 4.6) 時，它們則無法完成許多寫入操作。

hf-CLI 技能 (skill)

Hugging Face 提供了一個自動生成的 skill，列出了每個指令的簽名、單行描述和必要的標記。代理可以透過以下方式載入此技能：

hf skills add            # 適用於大多數代理
hf skills add --claude   # 包含 Claude 專用條目

該技能將每個任務的平均工具調用次數從約 10 次減少到約 7 次（減少約 30%），因為代理不再需要透過 --help 來探索指令。Token 使用量保持大致不變，因為技能增加的是固定的上下文切片。

如何親自嘗試

  1. 安裝 CLI：
# macOS / Linux
curl -LsSf https://hf.co/cli/install.sh | bash
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
  1. 為您的代理添加技能：
hf skills add            # 通用代理
hf skills add --claude   # Claude Code
  1. 進行身份驗證 (hf auth login) 並給予代理一個提示，例如：
Use `hf` to list my Hugging Face Hub models, datasets, and Spaces.
Take a look at how I am currently using the Hub and suggest a few ways you could help me.

代理將生成適當的 hf 指令並以極低的 Token 開銷執行它們。

註冊新的代理測試框架

如果您開發了新的編碼代理測試框架，請透過一個小的 PR 將其偵測條目添加到 agent-harnesses.ts。這能讓 CLI 識別該代理、標記其流量，並套用針對代理優化的輸出模式。

參考資料： 完整的基準測試轉錄本可在 https://huggingface.co/buckets/celinah/hf-cli-agent-benchmark 找到。完整的指令參考指南位於 hf CLI guide。

Sources