将 hf CLI 设计为与 Hub 交互的 agent 优化方式

](https://huggingface.co/celinah)

hf 是 Hugging Face Hub 的官方命令行入口。任何你能通过 Python SDK 在 Hub 上做的事情，都可以在终端中完成：下载和上传模型、数据集和 Spaces；创建和管理仓库、分支、标签和 Pull Request；在 HF 基础设施上运行 Job；管理 Bucket、Collection、Webhook 和 Inference Endpoint。

多年来，hf CLI 主要面向我们的用户构建。但现在，它越来越多地被编码 agent 使用：Claude Code、Codex、Cursor 等。因此，我们对其进行了重构，使其能同时服务于这两类用户。这篇博文总结了我们的工作以及我们如何对其进行基准测试。我们发现，在复杂的多步骤任务中，不使用 CLI 的基线方案（agent 手动编写 curl 或使用 Python SDK）消耗的 token 数量最高可达使用 hf CLI 的 6 倍。

Hub 上的 AI Agent 流量

我们从 2026 年 4 月开始追踪 Hub 上的 agent 使用情况。hf CLI（以及它基于的 huggingface_hub Python SDK）通过读取 agent 设置的环境变量来检测是否有编码 agent 在驱动它：CLAUDECODE/CLAUDE_CODE 用于 Claude Code，CODEX_SANDBOX 用于 Codex，此外还有 Cursor、Gemini、Pi 以及通用的 AI_AGENT。这个单一信号完成两项工作：它决定了 CLI 的输出格式（下文详述），并为每个 Hub 请求打上 agent/<name> 的 user-agent 标签，这样我们就可以将流量归因于驱动它的 agent。按独立用户数计算，最大的两个是 Claude Code 和 Codex，远超其他 agent，它们也是我们后文进行基准测试的两个 agent。

柱状图统计每个 agent 的独立用户数；子标签显示请求量。仅 Claude Code 就有约 4 万用户和近 4900 万次请求，Codex 紧随其后。这些是早期数据（我们直到 2026 年 4 月才开始归因 agent 流量），但规模已经相当可观，我们预计随着编码 agent 成为与 Hub 交互的标准方式，这个数字还会继续增长。

为人类和 Agent 构建

人类和编码 agent 对相同的 hf 命令期望不同的输出。人类希望看到丰富的终端输出：ANSI 颜色、填充并截断以适应屏幕的表格、成功时的绿色 ✅、布尔值的 ✔、进度条、散文式的提示。Agent 则希望相反：没有 ANSI，没有截断，每个值都完整，因为 agent 能处理比人类密集得多的输出，保持紧凑和结构化以节省 token。它也无法回答 CLI 的提示，并且会在超时后愉快地重新运行命令。本节其余部分将介绍 hf 如何为每一方提供所需的内容。我们在 hf v1.9.0 中引入了 agent 模式输出，并在后续版本中逐步将 CLI 的其余部分迁移到该模式。

一个命令，多种渲染

当 hf 自动检测到 agent 使用时（通过上述环境变量），它会以不同方式渲染相同的命令。它无需传递标志即可为人类或 agent 优化输出格式：

# 人类（终端默认）：对齐的表格，截断以适应屏幕，带有提示
> 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...
提示：使用 `--no-truncate` 或 `--format json` 显示完整值。

# agent（自动检测）：TSV，完整的 ID + ISO 时间戳 + 每个标签，无截断
$ 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']

人类获得一个对齐的表格，截断以适应终端，并附带如何查看更多内容的提示，以及状态的颜色提示（成功时为绿色 ✓，错误时为红色）。Agent 获得完整的 TSV 记录：完整的仓库 ID、完整的 ISO 时间戳、每个标签，没有 ANSI 代码，没有截断，易于解析且节省 token。

在实践中，我们实现了诸如 .table(...)、.result(...)、.json() 等日志记录方法，这些方法接收原始数据作为输入并处理格式化。除了人类和 agent 模式，我们还引入了 --json 和 --quiet 选项，以便更容易地串联命令。默认模式会根据上下文自动选择，但用户始终可以使用 --format human | agent | json | quiet 强制选择他们想要的格式。

下一步命令提示

CLI 命令很少孤立运行：一个步骤通常暗示着下一步（git add，然后是 git commit）。许多 hf 命令现在以提示结尾：确切的下一个要运行的命令，并预先填充了你刚刚使用的 ID，这样用户或 agent 可以直接链接到下一步，而不是从头开始推导。在后台启动一个 Job，它会指向其日志；创建一个 Space，它会指向其启动状态：

$ hf jobs run --detach python:3.12 python train.py
✓ Job started
  id: 6f3a1c2e9b
  url: https://huggingface.co/jobs/celinah/6f3a1c2e9b
提示：使用 `hf jobs logs 6f3a1c2e9b` 获取日志。

对人类来说，这是一种便利。对 agent 来说，这是一条轨道：下一个动作已被命名，用正确的 ID 参数化，并准备好运行，因此它需要更少的步骤来弄清楚该做什么。错误也以同样的方式处理，指出修复方法而不是仅仅失败：

错误：未登录。请先运行 `hf auth login`。

提示、警告和错误都输出到 stderr，而数据输出到 stdout，因此这些指导信息不会污染 agent 正在解析的输出。

非阻塞且可安全重试

hf 永远不会停留在交互式提示符上等待 agent 无法按下的键。一个破坏性命令仍然会要求人类确认，但在 agent 模式下，它会_快速失败_，并在消息中给出修复方法（使用 --yes 跳过确认。），而 -y/--yes 可以跳过确认。并且由于 agent 会在超时和丢失上下文时重试，操作被设计为可安全重复：如果仓库已存在，hf repos create --exist-ok 是一个空操作，重新运行上传会干净地重新提交。另外，移动真实数据的命令会接受一个 --dry-run 参数，在执行前精确显示它们将传输的内容，这对人类和 agent 都很方便，因为两者都不必承诺进行长时间下载或盲目同步：

# agent 模式：没有 --yes 的破坏性命令会拒绝，并在消息中给出修复方法
$ hf repos delete my-org/old-model
错误：您即将永久删除模型 'my-org/old-model'。是否继续？使用 --yes 跳过确认。

# 移动数据的命令接受 --dry-run 来预览传输
$ hf download deepseek-ai/DeepSeek-V4-Pro config.json --dry-run
[dry-run] 将下载 1 个文件（共 1 个），总计 1.8K。
file         size
config.json  1.8K

可发现、可预测的命令

hf 被设计为可探查的：运行 hf 查看资源组，在你需要的资源组上运行 --help，每个 --help 都以真实、可复制粘贴的示例结尾（agent 匹配这些示例的速度远快于解析描述）：

$ hf models ls --help
...
示例
  $ 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），因此一旦 agent 学会一个命令，它就可以推断出其余的命令。并且输出是可组合的：-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

对编码 Agent 的 hf CLI 进行基准测试

为了查明 hf CLI 是否真的对 agent 更高效，我们对其进行了测量。我们构建了一个小型评估框架，并通过每种驱动 Hub 的方式多次运行同一组 Hub 任务，对照实时 Hub 对每次运行进行评分。在方法论之前先看结论：在两个 agent 上，hf CLI 都表现更好，在复杂的多步骤任务上最为明显，它使用的 token 要少得多。

agent	工具	成功得分	token 使用量	自报错误
Claude Code (Sonnet 4.6)	hf CLI	0.94	基线	2 / 163
	curl / Python SDK	0.84	1.3-1.6× tokens	11 / 163
Codex (GPT-5.5)	hf CLI	0.93	基线	3 / 163
	curl / Python SDK	0.92	1.6-1.8× tokens	10 / 163

（自报错误 = agent 在 17 个可解决的任务上报告成功，但 Hub 显示并非如此。hf CLI 行是安装了其 skill 的 CLI；skill 在裸 CLI 之上增加的内容（主要是更少的工具调用）在下面的 skill 部分中分解。代表性记录已发布在此 bucket 中。）

设置

我们定义了 18 个非平凡的 Hub 任务。不是“下载一个文件”，而是你实际会要求的那种事情：汇总一个热门组织的模型，检查仓库的文件及其大小，使用包含/排除规则上传文件夹，删除文件，跨仓库复制文件，打开一个添加许可证的 PR，创建一个带有分支和标签的仓库，同步和清理一个 bucket，构建一个 collection。每个任务都交给一个全新的编码 agent，并且只允许一种与 Hub 通信的方式：

• hf CLI，或者
• curl / Python SDK：完全没有 hf CLI，因此 agent 退回到使用 curl 调用 REST API 或使用 huggingface_hub Python 库。

我们在两种配置下运行 hf CLI，带和不带其 skill（一个生成的命令参考，我们将在其自己的部分中讨论）。但下面的主要比较仅仅是 hf CLI 对比 curl / SDK；skill 的增量效果足够小，我们将其单独分解，而不是挤入主要结果中。

配置故意保持简洁：每次运行一个全新实例，没有自定义 MCP 服务器，没有 CLAUDE.md 或 AGENTS.md，上下文中没有任何内容来影响行为。任务和工具放入单个 prompt 中，agent 以 TASK_COMPLETE 或 TASK_FAILED 标记结束，但我们不信任该标记（agent 会在工作从未落地的情况下报告成功），因此我们通过重新查询实时 Hub 独立地对每次运行进行评分：分支是否真的创建了，文件是否真的消失了，bucket 是否存在？每个任务/工具组合运行 10 次，因为编码 agent 是非确定性的，每个 agent 约 520 次运行（18 个任务 × 3 个工具 × 10 次重复，减去一个可计费 Jobs 任务的上限），总共约 1,000 次评分运行。我们在两个最流行的编码 agent（Claude Code 搭配 Sonnet 4.6 和 OpenAI Codex 搭配 GPT-5.5）上完整运行了两次。

结果

下面的两个图表分解了上面的表格。首先，Sonnet 上的任务成功率，这是 curl 和 SDK 最挣扎的 agent：

没有 CLI，curl 和 SDK 落后了十个百分点，因为在 Sonnet 上它们根本无法完成部分工作（主要是写入操作），而 hf CLI 可以顺利完成。

第二张图显示了 GPT-5.5 上的 token 影响，按任务分解。每个柱状图是 curl/SDK 的 token 数除以同一任务上 CLI 的 token 数，因此 2.4× 意味着非 hf 版本消耗了 2.4 倍的 token 来完成相同的工作：

在一次性读取（计数数据集行数、批量元数据）上，curl 和 SDK 表现良好，有时甚至更轻量。但随着任务变得更加复杂并涉及多个依赖步骤，agent 必须手动编写整个 REST 调用链（或深入挖掘 SDK），成本会急剧上升：在创建带有分支和标签的仓库、删除文件、跨仓库复制或同步 bucket 时，成本是 CLI 的 2.4 倍到 6 倍。hf CLI 允许 agent 将任务表达为几个更高级别的命令，而不是精心设计一个复杂的工作流。

关键发现

• hf CLI 比 curl 或 SDK 精简得多。 对于相同的任务，在相同或更好的成功率下，curl 和 SDK 消耗的 token 大约是 1.3 倍到 1.8 倍。在简单的读取任务上它们没问题，但在真实的多步骤工作中，它们要付出 2 倍到 6 倍的代价：CLI 将一系列 REST 调用组合成几个高级命令，而 curl 或 SDK 每次运行都手动重新推导整个链。
• 在更强的模型上，curl 和 SDK 可以工作，但仍然浪费。 在 Sonnet 上，它们无法完成部分工作（主要是写入操作）；在 GPT-5.5 上，它们大多能成功，正确地手动编写 REST 调用（或使用 SDK），但仍然支付远高于 CLI 的 token 费用。

hf-cli skill

hf 附带一个 skill：一个紧凑的整个命令表面的参考，agent 将其作为上下文加载。它是从实时的 hf 命令树自动生成的，每个命令一行（其签名、一行描述和重要的标志），按资源分组，并带有一个常用选项的简短词汇表。它故意跳过不言自明的标志，以保持简洁和轻量级上下文，并且每个版本都会重新生成。运行 hf skills preview 来打印它，或者使用以下命令安装：

# 对于 Codex、Cursor、OpenCode、Pi 和其他从 `.agents/skills` 加载 skill 的 agent
hf skills add
# 包括上述所有以及 Claude Code
hf skills add --claude

它能给你带来什么？主要是，agent 不再猜测。最清晰的单一视图是每次运行需要多少命令，带 skill 和不带 skill：

在两个 agent 上，这大约是从每个任务十个命令减少到大约七个，大约减少了 30% 的工具调用。这是因为 agent 不再需要通过 --help 来探查正确的命令和参数。skill 不会减少你的 token 消耗，因为它会在上下文中预先添加一段固定的信息，因此对于相同的任务，token 数量大致相同或略有增加。Skill 也不会使 CLI 更可靠，但它会帮助 agent 花时间运行你的任务，而不是弄清楚工具是如何工作的。这在将 hf 与本地模型一起使用时可能特别有用。

我们在新的会话中运行每个任务，因此 skill 在每个任务上都支付其上下文成本。在真实的多任务会话中，该成本会被摊销（agent 只学习一次命令表面），因此 token 情况可能会有所改善；我们没有测量这种情况。

自己试试

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

如果你的 agent 与 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 和其他从 .agents/skills 加载 skill 的 agent
hf skills add --claude   # 上述所有以及 Claude Code

然后让你的 agent 指向 Hub，让它工作。确保你已经登录（hf auth login），然后给它一个像这样的 prompt：

使用 `hf` 列出我的 Hugging Face Hub 模型、数据集和 Spaces。
看看我目前是如何使用 Hub 的，并建议一些你可以帮助我的方法。

它会自己找出命令，并返回一些有用的东西。

完整的命令参考位于 hf CLI 指南中。

注册一个 Agent 框架

正在构建一个 agent 框架？请注册它！ 这样 hf 才能学会检测它，Hub 才能将其流量归因于你的框架。你只需要打开一个小的 PR，向 agent-harnesses.ts 添加一个条目。阅读注册你的 agent 框架指南了解更多详情。