设计hf命令行界面以优化AI代理使用

标题: 设计 hf CLI 作为与 Hugging Face Hub 交互的代理优化方式

原文链接: https://huggingface.co/blog/hf-cli-for-agents

发布日期: 2026-06-04T00:00:00.704Z

Markdown 内容:

hf 是访问 Hugging Face Hub 的官方命令行入口。你可以通过它完成 Python SDK 中能做的任何事情：下载和上传模型、数据集和 Spaces；创建和管理仓库、分支、标签和拉取请求；在 Hugging Face 基础设施上运行作业；管理和操作桶、集合、Webhook 和推理端点。

hf CLI 主要是为我们的用户多年来设计的。但现在它越来越被 编码代理 使用：Claude Code、Codex、Cursor 等等。因此，我们重新构建了它，使其能够同时服务于这两类用户。这篇博客文章总结了我们所做的工作以及如何进行基准测试。我们发现，在复杂的多步骤任务中，没有 CLI 的基线（即代理手动编写 curl 或 Python SDK）所使用的令牌数最多比 hf CLI 多 6 倍。

Hub 上的 AI 代理流量

我们从 2026 年 4 月开始跟踪代理对 Hub 的使用情况。hf CLI（以及它所构建的基础 Python SDK huggingface_hub）通过读取代理设置的环境变量来检测是否是由编码代理驱动：对于 Claude Code 是 CLAUDECODE/CLAUDE_CODE，对于 Codex 是 CODEX_SANDBOX，再加上 Cursor、Gemini、Pi 以及通用的 AI_AGENT。这个单一信号承担了两项任务：它塑造 CLI 的输出（更多细节见下文）；并且为每个 Hub 请求添加一个 agent/<name> 用户代理标签，以便我们可以将流量归因于驱动该请求的代理。用户数量最多的两个是 Claude Code 和 Codex，远远领先其他所有内容，并且它们也是我们在这篇文章中稍后进行基准测试的两种代理。

柱状图显示了每个代理的独立用户数；子标签表示请求数量。Claude Code 单独就有约 40,000 名用户和近 49 百万次请求，Codex 接近其后。这些数字尚处于早期阶段（我们仅从 2026 年 4 月开始归因代理流量），但规模已经相当大，并且随着编码代理成为与 Hub 交互的标准方式，我们预计它将继续增长。

为人类和代理设计

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

一个命令，多种渲染

当 hf 自动检测到代码代理使用（通过上述环境变量）时，它会以不同的方式呈现同一个命令。它根据是否为人类或代理优化输出格式而无需传递标志：

# 对于人类（默认在终端中）：对齐的表格，截断以适应屏幕，并带有提示
> 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` 来显示完整值。

# 对于代码代理（自动检测）：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']

一个人会得到一个对齐的表格，截断以适应终端，并附带一条提示信息，说明如何查看更多信息。状态指示带有颜色线索（成功时为绿色 ✓，错误时为红色）。代理则获得完整的记录，格式为 TSV：包含完整的仓库 ID、完整的时间戳和所有标签，没有 ANSI 代码，没有任何内容被截断，易于解析且令牌较少。

实际上，我们实现了如 .table(...), .result(...), .json() 等日志方法，这些方法接收原始数据作为输入并处理格式化。除了人机模式外，还引入了 --json 和 --quiet 选项以方便命令的组合使用。默认模式会根据上下文自动选择，但用户可以始终通过 --format human | agent | json | quiet 强制指定所需的格式。

下一个命令提示

CLI 命令很少独立运行：通常一步会暗示下一步（如 git add，然后是 git commit）。许多 hf 命令现在以 提示 结尾：确切的下一个要运行的命令，预填充了你刚刚使用的 ID，这样用户或代理可以直接链到下一步而不是从头开始计算。在后台启动一个作业时，它会指向其日志；创建一个空间时，则会指向其启动状态：

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

对于人来说这是方便的。而对于代理来说则是导向：下一步操作被命名，参数化了正确的 ID，并准备好运行，因此不需要更多步骤来确定要做什么。错误行为相同，命名修复而不是简单失败：

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

提示、警告和错误都发送到 stderr 而数据则发送到 stdout，所以这些指导不会污染代理正在解析的输出。

非阻塞且可重试

hf 从不坐在交互提示符上等待一个代理无法按下的按键。破坏性命令仍然会询问人类确认，但在代理模式下它会快速失败并在消息中提供修复（使用 --yes 跳过确认），并且 -y/--yes 可以跳过此步骤。由于代理在超时和丢失上下文的情况下可以重试，因此操作被构建为安全可重复执行：hf repos create --exist-ok 如果仓库已存在则不会做任何事情，并且重新运行上传会干净地重新提交。另外，移动实际数据的命令带有 --dry-run 选项，在运行之前显示它们将传输的内容，这对人类和代理都很有用，因为两者都不必承诺进行长时间下载或盲目同步：

# 在代理模式下：没有 --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
[干运行] 将下载 1 个文件（总共 1.8K）。
文件         大小
config.json  1.8K

可发现且可预测的命令

hf 被设计为可探测的：运行 hf 可查看资源组，对需要的部分运行 --help，每个 --help 都以实际可复制粘贴的例子结束（这些例子比解析描述更快地被代理匹配）：

$ 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），因此一旦代理学会了某个命令，就能猜出其他命令。输出也可以组合：-q 会按一行一个 ID 的方式打印以供管道传递到下一个命令中，--json 则提供给 jq（<https://jqlang.org/>）使用。

$ 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 总是表现更好，在复杂、多步骤的任务上尤其明显，使用了远少于其他工具的令牌数。

| 代理 | 工具 | 成功分数 | 令牌使用量 | 自我报告错误 | | --- | --- | --- | --- | --- | | Claude Code (Sonnet 4.6) | hf CLI | 0.94 | 基准 | 2 / 163 | | | curl / Python SDK | 0.84 | 1.3-1.6× 令牌 | 11 / 163 | | Codex (GPT-5.5) | hf CLI | 0.93 | 基准 | 3 / 163 | | | curl / Python SDK | 0.92 | 1.6-1.8× 令牌 | 10 / 163 |

_(自我报告错误 = 代理在可解决的 17 个任务中报告成功，但 Hub 并非如此。hf CLI 行为行是安装了技能后的 CLI；技能在此基础上增加了的功能（主要是减少工具调用）将在 技能部分 中详细说明。代表性对话记录发布在 此存储桶中。)_

评估设置

我们定义了 18 个非平凡的 Hub 任务。不是“下载一个文件”，而是实际会问到的任务：聚合一个热门组织的模型，检查仓库中的文件及其大小，上传带有包含/排除规则的文件夹，删除文件，跨仓库复制文件，创建添加许可证的拉取请求，创建带分支和标签的仓库，同步并修剪存储桶，构建集合。每个任务都会交给一个新的编程代理，并且只有一种与 Hub 交互的方式：

• hf CLI，
• curl / Python SDK：没有 hf CLI，因此代理会回退到 REST API 的 curl 或 huggingface_hub Python 库。

我们以两种配置运行 hf CLI，有技能和无技能（我们在 其独立部分 回顾了该技能）。但下面的主要比较只是 `hf` CLI vs curl / SDK；技能的增量影响足够小，我们将其单独列出以避免挤占主要结果。

配置故意保持简洁：每次运行一个新实例，没有自定义 MCP 服务器，也没有 CLAUDE.md 或 AGENTS.md 文件，在上下文中不会引导行为。任务和工具被合并到一个提示中，代理完成时会带有 TASK_COMPLETE 或 TASK_FAILED 标记，但我们不信任这个标记（因为代理可能会报告成功而实际上工作从未落地），因此我们通过重新查询实时 Hub 独立评估每次运行：分支是否真的创建了？文件是否真正不存在？桶是否存在？每个任务/工具组合运行 10 次，由于编码代理是非确定性的，大约每种代理有 520 次运行（18 个任务 × 3 种工具 × 10 次重复，减去一个可收费 Jobs 任务的上限），总共约 1,000 次评估。我们整个过程共进行了两次，在最受欢迎的两种编码代理上进行：Claude Code 配合 Sonnet 4.6 和 OpenAI Codex 配合 GPT-5.5。

结果

下面两张图表拆解了上面的表格内容。首先，Sonnet 上的任务成功情况，这是 curl 和 SDK 最挣扎的地方：

没有 CLI，curl 和 SDK 落后了 10 个百分点，因为在 Sonnet 上它们根本无法完成任务的一部分（主要是写操作），而 hf CLI 却能成功。

第二张图表展示了 GPT-5.5 的令牌影响，按任务拆分。每个条形图表示 curl/SDK 与 CLI 在同一任务上的令牌比值，因此 2.4× 意味着非-hf 版本执行相同操作消耗的令牌是 CLI 的 2.4 倍：

对于一次性的读取操作（如计数数据集行数、批量元数据），curl 和 SDK 表现良好，有时甚至更轻便。但随着任务变得复杂并涉及多个依赖步骤时，代理需要手写整个 REST 调用链（或深入 SDK 中查找），成本会急剧上升：创建带有分支和标签的仓库、删除文件、跨仓库复制文件或同步桶的成本分别是 CLI 的 2.4 倍到 6 倍。hf CLI 允许代理将任务表达为几个高级命令，而不是构建复杂的流程。

关键发现

• `hf` 命令行界面远比 curl 或 SDK 精简。 对于同样的任务，在同等或更好的成功率下，curl 和 SDK 所消耗的标记量大约是 hf 的 1.3 到 1.8 倍。在简单的操作中它们表现良好，但在真正的多步骤工作中则要付出 2 到 6 倍的成本：hf CLI 将一系列 REST 调用组合成几条高级命令，而 curl 或 SDK 每次运行都需要手动重新构建这些调用链。
• 在更强的模型上，curl 和 SDK 可以工作但仍然浪费资源。 在 Sonnet 上它们无法完成部分任务（主要是写操作）；而在 GPT-5.5 上它们大部分都能成功，正确地手工编写了 REST 调用（或使用 SDK），但仍比 CLI 的标记量消耗要高得多。

hf-cli 技能

hf 提供了一个 技能：一个紧凑的命令表面参考，代理可以将其加载为上下文。它是由实时 hf 命令树自动生成的，每条命令一行（其签名、简短描述以及重要的标志），按资源分组，并附带常见选项的简要词汇表。它特意省略了显而易见的标志以保持简洁和轻量级上下文，并且每次发布都会重新生成。运行 hf skills preview 可打印该技能，或安装如下：

# 对于从 `.agents/skills` 加载技能的 Codex、Cursor、OpenCode 和 Pi 等代理
hf skills add
# 包括上述内容 + Claude Code
hf skills add --claude

这能为你带来什么？主要的是，代理不再猜测。最清晰的一点是每运行一次任务所使用的命令数量差异：

在两个代理上，每项任务的命令数从大约十条减少到约七条，工具调用减少了约 30%。这是因为代理不再通过 --help 查找正确的命令和参数。技能不会降低你的标记量消耗，因为它会在上下文中添加固定的信息片断，因此对于相同的任务，标记量大致保持不变或略有上升。技能也不会使 CLI 更加可靠，但它可以帮助代理花费更多时间运行你的任务而不是了解工具的用法。这在使用 hf 与本地模型时尤其有用。

我们为每项任务启动了一个新的会话，所以每次任务都会支付技能的上下文成本。在一个真正的多任务会话中，这种成本会被摊销（代理只需学习一次命令表面），因此标记量的情况可能会有所改善；我们没有测量这种情况。

亲自尝试一下

我们进行了这些基准测试，因为我们认为这很重要。代理正在成为 Hub 的真实用户：它们训练模型、构建和清理数据集，并以 Spaces 形式发布演示文稿，几乎总是代表某个人进行操作。一个对代理友好的 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"

然后将技能授予代理，使其了解整个命令界面：

hf skills add            # Codex, Cursor, OpenCode, Pi 和其他从 .agents/skills 加载技能的代理
hf skills add --claude   # 以上 + Claude Code

然后将代理指向 Hub 并让它工作。确保你已登录（hf auth login），然后提供一个提示，例如：

使用 `hf` 列出我的 Hugging Face Hub 模型、数据集和 Spaces。
看看我目前如何使用 Hub，并提出几条可以帮助我的建议。

它会自行确定命令并返回有用的信息。

完整的命令参考可以在 `hf` CLI 指南 中找到。

注册代理框架

正在构建代理框架？请将其注册！ 这是 hf 学习检测它的方法，也是 Hub 将其流量归因于你的框架的方式。你只需要打开一个小 PR，在 `agent-harnesses.ts` 中添加一条记录即可。请参阅 注册你的代理框架 指南以获取更多详细信息。