Hugging Face hf CLI 针对智能体优化重构，降低了 Token 使用量并提升了成功率

Hugging Face hf CLI 针对智能体优化重构，降低了 Token 使用量并提升了成功率

TL;DR

Hugging Face 宣布对 hf CLI 进行了针对智能体（agent）优化的重构，在执行多步 Hub 任务时，为 Claude Code 和 Codex 等编程智能体提供高达 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，因此永远不会污染智能体解析的数据流。

非阻塞且安全可重试

  • 在智能体模式下，破坏性命令会快速失败并提供清晰的修复消息，而不是提示交互式确认。
  • 幂等标志（如 --exist-ok 和 --dry-run）使得重复执行变得安全，这对于在超时时自动重试的智能体至关重要。

可发现、可预测的命令

该 CLI 遵循一致的 resource + verb 模式（hf models ls、hf repos create、hf jobs run）。每个 --help 部分都以可复制粘贴的示例结束，使智能体能够快速匹配命令。-q（每行一个 ID）和 --json 等选项进一步简化了管道传输和下游处理。

为编程智能体基准测试 hf CLI

一个专门的测试框架对两个智能体——Claude Code (Sonnet 4.6) 和 Codex (GPT-5.5) 进行了 18 个真实的 Hub 任务评估（例如：聚合热门模型、创建带有分支/标签的仓库、同步 bucket）。每个任务通过以下方式之一执行：

  1. 使用 hf CLI（带有或不带有其技能/skill）
  2. 直接使用 curl 调用 / huggingface_hub Python SDK

每个配置针对每个任务运行 10 次重复，总计约 1,000 次评分运行。成功率通过重新查询实时 Hub 来验证，而不是信任智能体的 TASK_COMPLETE 标记。

结果摘要

智能体 工具 成功率 相比 CLI 的 Token 使用量 自报错误
Claude Code (Sonnet 4.6) hf CLI 0.94 基准 2 / 163
curl / SDK 0.84 1.3–1.6× 11 / 163
Codex (GPT-5.5) hf CLI 0.93 基准 3 / 163
curl / SDK 0.92 1.6–1.8× 10 / 163

复杂的多步任务（例如：bucket 同步 + 修剪、带分支/标签的仓库创建）在使用 curl/SDK 时产生的 Token 消耗是 2.4 倍到 6 倍，而简单的只读操作则显示出与 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