Hugging Face CLI重设计：面向Agent的Hub交互新方式

多年来，hf CLI 主要面向我们的用户构建。但现在，Claude Code、Codex、Cursor 等编程智能体也越来越多地使用它。因此，我们对其进行了重新设计，使其能够同时满足这两类用户的需求。本文总结了我们所做的工作以及评测方法。我们发现，在复杂的多步骤任务中，不使用 CLI 的基线方案（由智能体临时编写 curl 命令或使用 Python SDK）所消耗的 token 最多可达到 hf CLI 的 6 倍。

Hub 上的 AI 智能体流量

我们从 2026 年 4 月开始跟踪 AI 智能体对 Hub 的使用情况。hf CLI（以及它所基于的 huggingface_hub Python SDK）会读取智能体设置的环境变量，以检测当前操作是否由编程智能体驱动：Claude Code 使用 CLAUDECODE/CLAUDE_CODE，Codex 使用 CODEX_SANDBOX，此外还支持 Cursor、Gemini、Pi，以及通用的 AI_AGENT。这一个信号承担两项工作：一是调整 CLI 的输出形式（下文会详细介绍），二是在每个 Hub 请求中添加 agent/<name> user-agent 标记，以便我们将流量归因到驱动该请求的智能体。按独立用户数计算，规模最大的两个是 Claude Code 和 Codex，远超其他智能体；它们也是本文后续评测的两个智能体。

柱状图统计每个智能体的独立用户数，请求量则显示为副标签。仅 Claude Code 就拥有约 4 万名用户和接近 4900 万次请求，Codex 紧随其后。这些仍是早期数据（我们直到 2026 年 4 月才开始对智能体流量进行归因），但规模已经相当可观。随着编程智能体成为使用 Hub 的标准方式，我们预计这一数字还会持续增长。

同时为人类与智能体而构建

对于相同的 hf 命令，人类与编程智能体期待不同的输出。人类需要丰富的终端输出：ANSI 颜色、经过填充对齐并截断以适应屏幕的表格、成功时显示绿色 ✅、使用 ✔ 表示布尔值、进度条以及文字提示。智能体的需求正好相反：不要 ANSI，不要截断，完整显示每个值——因为智能体能够处理远比人类密集的输出——同时保持紧凑和结构化，以减少 token 消耗。智能体也无法回答 CLI 提示，并且在命令超时后会毫不犹豫地重新运行。本节其余部分将介绍 hf 如何分别满足双方的需求。我们在 hf v1.9.0 中引入了智能体模式输出，并在后续版本中逐步将 CLI 的其余部分迁移到这一模式。

一条命令，多种呈现形式

当 hf 通过前面提到的环境变量自动检测到智能体正在使用时，它会以不同方式呈现同一条命令。无需传入任何标志，它便会针对人类或智能体优化输出格式：

# human (default in a terminal): aligned table, truncated to fit, with a hint
> hf models ls --author Qwen --sort downloads --limit 3
ID                       CREATED_AT DOWNLOADS LIBRARY_NAME LIKES PIPELINE_TAG    PRIVATE TAGS
------------------------ ---------- --------- ------------ ----- --------------- ------- -------------------------
Qwen/Qwen3-0.6B          2025-04-27  21156913 transformers  1285 text-generation         transformers, safetens...
Qwen/Qwen2.5-1.5B-Ins... 2024-09-17  15143953 transformers   725 text-generation         transformers, safetens...
Qwen/Qwen3-4B            2025-04-27  14808352 transformers   625 text-generation         transformers, safetens...
Hint: Use `--no-truncate` or `--format json` to display full values.

# agent (auto-detected): TSV, full ids + ISO timestamps + every tag, nothing truncated
$ hf models ls --author Qwen --sort downloads --limit 3
id      created_at      downloads       library_name    likes   pipeline_tag    private tags
Qwen/Qwen3-0.6B 2025-04-27T03:40:08+00:00       21156913        transformers    1285    text-generation False   ['transformers', 'safetensors', 'qwen3', 'text-generation', 'conversational', 'arxiv:2505.09388', 'base_model:Qwen/Qwen3-0.6B-Base', 'base_model:finetune:Qwen/Qwen3-0.6B-Base', 'license:apache-2.0', 'text-generation-inference', 'endpoints_compatible', 'deploy:azure', 'region:us']
Qwen/Qwen2.5-1.5B-Instruct      2024-09-17T14:10:29+00:00       15143953        transformers    725     text-generation False['transformers', 'safetensors', 'qwen2', 'text-generation', 'chat', 'conversational', 'en', 'arxiv:2407.10671', 'base_model:Qwen/Qwen2.5-1.5B', 'base_model:finetune:Qwen/Qwen2.5-1.5B', 'license:apache-2.0', 'text-generation-inference', 'endpoints_compatible', 'deploy:azure', 'region:us']
Qwen/Qwen3-4B   2025-04-27T03:41:29+00:00       14808352        transformers    625     text-generation False   ['transformers', 'safetensors', 'text-generation', 'arxiv:2309.00071', 'arxiv:2505.09388', 'base_model:Qwen/Qwen3-4B-Base', 'base_model:finetune:Qwen/Qwen3-4B-Base', 'license:apache-2.0', 'endpoints_compatible', 'deploy:azure', 'region:us']

人类看到的是对齐的表格，内容会被截断以适应终端宽度，同时还会看到如何显示更多内容的提示，以及用于表示状态的颜色提示（成功时显示绿色 ✓，出错时显示红色）。智能体则会获得以 TSV 格式呈现的完整记录：完整的仓库 ID、完整的 ISO 时间戳、所有标签、不含 ANSI 代码、没有任何截断，既便于解析，又节省 token。

在实际实现中，我们提供了 .table(...)、.result(...)、.json() 等日志记录方法，它们接收原始数据作为输入并负责处理格式。除了人类模式和智能体模式之外，我们还引入了 --json 和 --quiet 选项，以便更轻松地将命令通过管道串联起来。默认模式会根据上下文自动选择，但用户始终可以通过 --format human | agent | json | quiet 强制指定所需格式。

CLI 命令很少孤立运行：一个步骤通常意味着接下来还有另一个步骤（例如先执行 git add，再执行 git commit）。现在，许多 hf 命令都会以一条提示结尾：直接给出下一条要运行的确切命令，并预先填入你刚刚使用的 ID。这样一来，无论用户还是智能体，都可以直接衔接到下一步，无需从头推断该怎么做。在后台启动 Job 后，它会指引你查看日志；创建 Space 后，它会指引你查看启动状态：

$ hf jobs run --detach python:3.12 python train.py
✓ Job started
  id: 6f3a1c2e9b
  url: https://huggingface.co/jobs/celinah/6f3a1c2e9b
Hint: Use `hf jobs logs 6f3a1c2e9b` to fetch the logs.

对于人类来说，这是一项便利功能；对于智能体来说，它则像一条轨道：下一步操作已经明确命名，使用正确的 ID 填好了参数，并且可以直接运行，因此智能体不必花费太多步骤去判断接下来该做什么。错误也采用相同方式处理：不只是报告失败，还会直接指出修复方法：

Error: Not logged in. Run `hf auth login` first.

提示、警告和错误全部写入 stderr，数据则写入 stdout，因此这些指导信息不会污染智能体正在解析的输出。

非阻塞且可安全重试

hf 从不会停留在交互式提示上，等待智能体无法按下的按键。破坏性命令仍然会要求人类确认，但在智能体模式下，它会快速失败，并在消息中给出解决方法（Use --yes to skip confirmation.），而 -y/--yes 可以跳过确认。由于智能体会在超时和上下文丢失后重试，因此各项操作都被设计为可以安全地重复执行：如果仓库已经存在，hf repos create --exist-ok 不会执行任何操作；重新运行上传命令也会干净利落地再次提交。此外，真正传输数据的命令支持 --dry-run，可以在运行前准确显示将要传输的内容。这对人类和智能体都很实用，因为双方都不必贸然开始漫长的下载或盲目的同步：

# agent mode: a destructive command without --yes refuses, with the fix in the message
$ hf repos delete my-org/old-model
Error: You are about to permanently delete model 'my-org/old-model'. Proceed? Use --yes to skip confirmation.

# commands that move data take --dry-run to preview the transfer first
$ hf download deepseek-ai/DeepSeek-V4-Pro config.json --dry-run
[dry-run] Will download 1 files (out of 1) totalling 1.8K.
file         size
config.json  1.8K

易于发现、可预测的命令

hf 的设计支持逐步探索：运行 hf 查看资源组，对所需的资源组运行 --help，而且每个 --help 的末尾都会提供真实且可直接复制粘贴的示例（智能体匹配示例的速度远快于解析文字描述）：

$ hf models ls --help
...
Examples
  $ hf models ls --sort downloads --limit 10
  $ hf models ls --search "qwen" --author Qwen
  $ hf models ls Qwen/Qwen3-4B --tree

命令树保持一致，采用“资源 + 动词”的形式，并提供直观的别名（hf models ls、hf repos create、hf jobs ps、hf collections delete；list/ls、remove/rm）。因此，智能体学会一条命令后，就能推测出其余命令。输出也可以组合使用：-q 每行只打印一个 ID，便于通过管道传给下一条命令；--json 则会生成可以交给 jq 处理的内容。

$ hf models ls --author Qwen -q | head -3
Qwen/Qwen3-0.6B
Qwen/Qwen2.5-1.5B-Instruct
Qwen/Qwen3-4B

针对编程智能体评测 hf CLI

为了验证 hf CLI 对智能体是否真的更高效，我们进行了测试。我们构建了一个小型评估框架，多次通过不同的方式运行相同的 Hub 任务集，每次都根据实时 Hub 进行评分。在介绍方法论前，先说结论：在两个智能体中，hf CLI 都领先，特别是在复杂的多步任务上，它使用的 token 数量少得多。

（自报成功 = 智能体在 17 个可解决的任务上报告成功，但 Hub 显示并非如此。hf CLI 行是指安装了 skill 的 CLI；skill 在原始 CLI 之上增加的内容（主要是减少工具调用）在下面的 skill 部分单独列出。代表性的对话记录发布在此 bucket。）

我们定义了 18 个非平凡的 Hub 任务。不是"下载一个文件"这样简单的事，而是你真实会要求的那种工作：聚合热门组织的模型、检查 repo 的文件及其大小、用包含/排除规则上传文件夹、删除文件、跨 repo 复制文件、打开添加许可证的 PR、创建带分支和标签的 repo、同步和清理 bucket、构建集合。每个任务都分配给一个全新的编码智能体，只能用一种方式与 Hub 交互：

curl / Python SDK：完全没有 hf CLI，所以智能体回退到使用 curl 调用 REST API 或 huggingface_hub Python 库。

我们在两种配置下运行 hf CLI，分别有 skill 和没有 skill（我们在下面的专门部分详述）。但下面的标题比较只是 hf CLI 对 curl / SDK；skill 的增量效果很小，我们单独列出来而不是挤进主要结果中。

配置故意保持干净：每次运行都是全新实例，没有自定义 MCP server，没有 CLAUDE.md 或 AGENTS.md，上下文中没有任何东西来引导行为。任务和工具进入单一提示，智能体以 TASK_COMPLETE 或 TASK_FAILED 标记完成，但我们不相信那个标记（智能体会报告成功的工作从未真正执行），所以我们通过重新查询实时 Hub 来独立评分每次运行：分支真的被创建了吗，文件真的删除了吗，bucket 真的存在吗？每个任务/工具组合运行 10 次，因为编码智能体是非确定性的，大约每个智能体 520 次运行（18 个任务 × 3 个工具 × 10 次重复，减去一个可计费 Jobs 任务的上限），总共约 1000 次评分的运行。我们在两个最流行的编码智能体上运行了整个测试（Claude Code with Sonnet 4.6 和 OpenAI Codex with GPT-5.5）。

下面的两个图表展开了上表。首先，Sonnet 上的任务成功率，curl 和 SDK 最吃力的智能体：

没有 CLI 的情况下，curl 和 SDK 落后十个百分点，因为在 Sonnet 上它们根本无法完成工作的部分（主要是写入操作），而 hf CLI 解决了这些问题。

第二张图显示了 GPT-5.5 上的 token 影响，按任务分解。每个条形是 curl/SDK 的 token 除以相同任务上 CLI 的 token，所以 2.4× 意味着非 hf 版本在做同样的事情时消耗了 2.4 倍的 token：

在单次读取（计数数据集行、批量元数据）上，curl 和 SDK 没问题，有时更轻量。但随着任务变得更复杂并涉及多个依赖步骤，智能体必须手工构建整个 REST 调用链（或挖掘 SDK），成本爆炸：在创建带分支和标签的 repo、删除文件、跨 repo 复制或同步 bucket 时，比 CLI 多 2.4× 到 6×。hf CLI 让智能体将任务表达为几个高级命令，而不是手工制作复杂的工作流。

hf CLI 远比 curl 或 SDK 轻。对于相同的任务，在相等或更好的成功率下，curl 和 SDK 消耗约 1.3× 到 1.8× 的 token。在简单读取上它们没问题，但在真实的多步工作上它们花费 2× 到 6×：CLI 将 REST 调用链组合成几个高级命令，而 curl 或 SDK 每次运行都手工重新推导。

在更强大的模型上，curl 和 SDK 可以工作但仍然浪费 token。在 Sonnet 上它们无法完成工作的部分（主要是写入）；在 GPT-5.5 上它们多数成功，正确地手工构建 REST 调用（或使用 SDK），但仍然支付远超过 CLI 的 token 账单。

hf 提供了一个 skill：一个紧凑的整个命令表面参考，智能体作为上下文加载。它从实时 hf 命令树自动生成，每个命令一行（其签名、单行描述和重要标志），按资源分组，附带常见选项的短词汇表。它故意跳过自说明的标志，以保持简洁并减轻上下文负担，并在每个发布时重新生成。运行 hf skills preview 来打印它，或用以下方式安装：

# for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
hf skills add
# includes the above + Claude Code
hf skills add --claude

它能为你带来什么？主要是智能体停止猜测。最清晰的单一视图是每次运行有多少命令，有 skill 和没有 skill：

在两个智能体上，这大约是每个任务十个命令降到大约七个，大约减少 30% 的工具调用。这是因为智能体没有探测 --help 来找到正确的命令和参数。skill 不会削减你的 token 账单，因为它将一个固定的信息片段前置到上下文中，所以对于相同的任务，token 保持不变或略有上升。Skill 也不会让 CLI 更可靠，但它会帮助智能体花时间运行你的任务而不是发现工具如何工作。这在使用本地模型的 hf 时特别有帮助。

我们在全新会话中运行每个任务，所以 skill 在每个任务上都付出其上下文成本。在真实的多任务会话中，该成本可以摊销（智能体学习一次命令表面），所以 token 表现可能改善；我们没有测量那个场景。

我们对所有这些进行基准测试，因为我们认为这很重要。智能体正在成为 Hub 的真实用户：他们训练模型、构建和清理数据集，以及几乎总是代表一个人在 Spaces 上发布演示。一个对智能体工作良好的 Hub 也是一个对使用它们的人工作更好的 Hub。智能体的工具越好，它为你做的就越多。

如果你的智能体与 Hugging Face Hub 交互，我们建议给它 hf 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"

然后给它 skill，这样它从第一轮就知道整个命令表面：

hf skills add            # Codex, Cursor, OpenCode, Pi and other agents that load skills from .agents/skills
hf skills add --claude   # the above + Claude Code

然后指向你的智能体进入 Hub 并让它工作。确保你已登录（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 CLI 指南中。

注册一个智能体框架

构建智能体框架？让它注册吧！那就是 hf 学会检测它的方式，以及 Hub 如何将其流量归因于你的框架。你只需要打开一个小 PR，向 agent-harnesses.ts 添加一个条目。阅读"注册你的智能体框架"指南以获得更多细节。

来自我们博客的更多文章

每周用 AI、开放工具和人工循环发布 huggingface_hub

它够智能体化吗？在你自己的工具上对开放模型进行基准测试