将 hf CLI 设计为适合 Agent 使用的 Hub 交互方式

来源：https://huggingface.co/blog/hf-cli-for-agents

返回文章列表

Célina Hanouti · Lucain Pouget

• Hub 上的 AI Agent 流量
• 同时服务于人类和 Agent
  • 一条命令，多种渲染方式
  • 下一步命令提示
  • 非阻塞且可安全重试
  • 易于发现、行为可预测的命令
• 对 hf CLI 进行 Coding Agent 基准测试
  • 测试设置
  • 测试结果
  • 关键发现
  • hf-cli 技能
  • 亲自试用
  • 注册 Agent 测试框架

hf 是访问 Hugging Face Hub 的官方命令行入口。凡是可以通过 Python SDK 在 Hub 上完成的操作，都可以在终端中完成：下载和上传模型、数据集和 Spaces；创建和管理仓库、分支、标签和 Pull Request；在 HF 基础设施上运行 Jobs；管理 Buckets、Collections、Webhook 和 Inference Endpoints。

hf CLI 多年来主要为我们的用户而构建。但现在它越来越多地被 coding agent 使用：Claude Code、Codex、Cursor 等。因此我们对其进行了重构，使其同时满足两类用户的需求。

本文总结了我们所做的工作以及如何对其进行基准测试。我们发现，在复杂的多步骤任务中，不使用 CLI 的基线方案（Agent 手写 curl 或 Python SDK）所消耗的 token 数量是 hf CLI 的 6 倍之多。

Hub 上的 AI Agent 流量

我们从 2026 年 4 月开始追踪 Agent 对 Hub 的使用情况。hf CLI（及其底层的 huggingface_hub Python SDK）通过读取各 Agent 设置的环境变量来检测是否由 coding agent 驱动：Claude Code 对应 CLAUDECODE/CLAUDE_CODE，Codex 对应 CODEX_SANDBOX，此外还支持 Cursor、Gemini、Pi，以及通用的 AI_AGENT。

这个信号同时发挥两个作用：一是调整 CLI 的输出格式（详见下文），二是为每个 Hub 请求打上 agent/ 用户代理标签，从而将流量归因到驱动它的 Agent。

按独立用户数排名，Claude Code 和 Codex 遥遥领先，也正是我们在本文后续基准测试中使用的两个 Agent。

2026 年 4 月以来，各 coding agent 在 Hugging Face Hub 上的独立用户数。Claude Code 以 39,500 名用户和 4,860 万次请求位居首位，其次是 Codex（34,800 名用户和 3,640 万次请求），随后依次为 antigravity、cursor-cli、openclaw、cursor、gemini 和 pi。

柱状图统计的是各 Agent 的独立用户数，子标签为请求量。仅 Claude Code 就有约 4 万名用户和近 4,900 万次请求，Codex 紧随其后。这些数据还处于早期阶段（我们从 2026 年 4 月才开始对 Agent 流量进行归因），但规模已相当可观，随着 coding agent 成为使用 Hub 的标准方式，我们预计这一数字还会持续增长。

同时服务于人类和 Agent

对于同一条 hf 命令，人类和 coding agent 期望得到不同的输出。

人类需要丰富的终端输出：ANSI 颜色、根据屏幕宽度截断的对齐表格、成功时的绿色 ✅、用 ✔ 表示布尔值、进度条、文字提示。

Agent 的需求恰恰相反：无 ANSI 码、不截断任何内容、完整显示所有值（Agent 处理密集输出的能力远超人类）、保持紧凑结构以节省 token。此外，Agent 无法响应 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...
Hint: Use `--no-truncate` or `--format json` to display full values.

# 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
Hint: Use `hf jobs logs 6f3a1c2e9b` to fetch the logs.

对人类来说这是一种便利。对 Agent 来说这是一条引导轨道：下一个动作已命名、已用正确的 ID 参数化、随时可以运行，从而减少推断步骤。

错误信息也遵循同样的设计，直接指出修复方法而非仅仅报错：

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

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

非阻塞且可安全重试

hf 从不停在等待 Agent 无法按下的按键的交互提示上。危险操作仍会要求人类确认，但在 Agent 模式下会快速失败并在消息中给出修复方法（Use --yes to skip confirmation.），而 -y/--yes 可跳过确认。

由于 Agent 会在超时或丢失上下文后重试，操作被设计为可安全重复执行：hf repos create --exist-ok 在仓库已存在时为空操作，重新运行上传命令也会干净地重新提交。

此外，涉及实际数据传输的命令支持 --dry-run，可在执行前显示将要传输的内容，对人类和 Agent 都很实用，因为两者都不必在不知情的情况下提交一次长时间下载或盲目同步：

# Agent 模式：危险命令不带 --yes 时拒绝执行，并在消息中给出修复方法
$ 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.

# 涉及数据传输的命令支持 --dry-run 预览
$ 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 结尾都附有真实可复制的示例（Agent 匹配示例的速度远快于解析描述）：

$ 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），因此 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

对 hf CLI 进行 Coding Agent 基准测试

为了验证 hf CLI 对 Agent 是否真的更高效，我们进行了实测。我们构建了一个小型评估框架，将同一组 Hub 任务以不同方式运行多次，并对照真实 Hub 对每次运行进行评分。

在介绍方法论之前，先给出核心结论：在两个 Agent 上，hf CLI 均表现更优，在复杂多步骤任务上尤为突出，token 消耗显著更少。

（自报错误 = Agent 在 17 个可解任务上报告成功，但 Hub 显示实际未完成。hf CLI 行为为安装技能后的 CLI；技能在裸 CLI 基础上的增量效果（主要是减少工具调用次数）在技能章节中单独说明。代表性运行记录发布在此 bucket 中。）

测试设置

我们定义了 18 个非平凡的 Hub 任务。不是“下载一个文件“这种简单操作，而是你实际可能提出的需求：统计某个热门组织的模型、查看仓库文件及其大小、按 include/exclude 规则上传文件夹、删除文件、跨仓库复制文件、新建带许可证的 PR、创建带分支和标签的仓库、同步并清理 Bucket、构建 Collection。

每个任务都发送给一个全新的 coding agent，且只有一种与 Hub 交互的方式：

• 使用 hf CLI，或
• curl / Python SDK：完全不使用 hf CLI，Agent 只能使用 curl 调用 REST API 或使用 huggingface_hub Python 库。

我们以两种配置运行 hf CLI：有无技能（技能是我们生成的命令参考文档，详见其专属章节）。但以下主要对比仅为 hf CLI vs curl / SDK；技能的增量效果足够小，我们将其单独列出，以免混淆主要结果。

配置刻意保持简洁：每次运行使用全新实例，无自定义 MCP 服务器，无 CLAUDE.md 或 AGENTS.md，上下文中无任何引导行为的内容。任务和工具写入单个 prompt，Agent 以 TASK_COMPLETE 或 TASK_FAILED 标记结束，但我们不信任该标记（Agent 可能对从未落地的工作报告成功），因此我们通过重新查询真实 Hub 对每次运行独立评分：分支是否真的创建了？文件是否真的删除了？Bucket 是否存在？

每个任务/工具组合运行 10 次（因为 coding agent 具有不确定性），每个 Agent 约 520 次运行（18 个任务 × 3 种工具 × 10 次重复，减去一个付费 Jobs 任务的上限），总计约 1,000 次有评分的运行。

我们使用两个最流行的 coding agent 各运行了一次完整测试：Claude Code（Sonnet 4.6）和 OpenAI Codex（GPT-5.5）。

测试结果

以下两张图表对上述表格进行了详细拆解。

首先是 Sonnet 上的任务成功率，这是 curl 和 SDK 表现最差的 Agent：

Claude Code（Sonnet 4.6）任务成功率：hf CLI 94%，curl / Python SDK 84%。

不使用 CLI 时，curl 和 SDK 落后 10 个百分点，因为在 Sonnet 上它们根本无法完成部分任务（主要是写操作），而 hf CLI 轻松应对。

第二张图展示了 GPT-5.5 上的 token 消耗影响，按任务细分。每个柱代表 curl/SDK 的 token 数除以同一任务中 CLI 的 token 数，因此 2.4× 表示非 hf 版本消耗了 2.4 倍的 token 完成同一件事：

GPT-5.5 上各任务的 curl/Python SDK 与 hf CLI token 比率（由高到低排序）。多步骤任务中 curl/Python SDK 的消耗远高于 CLI：bucket 创建+同步+清理为 6.0×，按热门模型对组织排名为 4.1×，仓库创建+分支+标签 / 删除文件 / 跨仓库复制文件各为 2.4×。简单的单次读取操作接近持平或更低：批量模型元数据为 0.5×，统计数据集行数为 0.3×。