Hugging Face 为编码智能体重塑 hf CLI 输出格式

hf是 Hugging Face Hub 的官方命令行入口。你在 Hub 上通过 Python SDK 能做的任何事情，都可以在终端中完成：下载和上传模型、数据集与 Spaces；创建和管理仓库、分支、标签与拉取请求；在 HF 基础设施上运行 Jobs；管理 Buckets、Collections、webhooks 和 Inference Endpoints。该hfCLI 多年来主要是为我们的用户而构建的。但如今它越来越多地被编程智能体所使用：Claude Code、Codex、Cursor 等等。因此我们重新构建了它，使其能同时服务于这两类受众。这篇博文总结了我们所做的工作，以及我们如何对其进行基准测试。我们发现，在复杂的多步骤任务上，无 CLI 的基线方案（智能体手工拼凑curl或使用 Python SDK）消耗的 token 最多可达6 倍于使用hfCLI 的量。

Hub 上的 AI 智能体流量

我们从 2026 年 4 月开始追踪智能体对 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 任务反复运行了多次，每次运行都对照实时 Hub 进行评分。在介绍方法之前，先给出核心结论：在两个智能体上，hf CLI 都更胜一筹，在复杂的多步骤任务上尤为明显，使用的 token 少得多。

（自报错误 = 智能体在 17 个可解任务上报告成功，但 Hub 的说法并非如此。hf CLI 行是安装了其技能的 CLI；该技能在裸 CLI 之上额外增加的内容（主要是更少的工具调用）在下方技能部分中单独列出。代表性对话记录发布在此存储桶中。）

设置

我们定义了18 个非平凡的 Hub 任务。不是"下载一个文件"，而是你实际会提出的那种需求：聚合某个热门组织的模型、检查某个仓库的文件及其大小、按包含/排除规则上传文件夹、删除文件、跨仓库复制文件、发起一个添加许可证的 PR、创建一个带分支和标签的仓库、同步并清理存储桶、构建一个 collection。每个任务都交给一个全新的编码智能体，且只有一种与 Hub 对话的方式：

• hf CLI，或者
• curl / Python SDK：完全没有 hf CLI，因此智能体只能退回到针对 REST API 的 curl 或 huggingface_hub Python 库。

我们在两种配置下运行 hf CLI，分别带和不带它的技能（一份生成的命令参考，我们会在专门的一节中再回到它）。但下面最重要的对比其实只是 hf CLI 对比 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 会落后十分，因为在 Sonnet 上它们根本无法完成部分工作（主要是写入操作），而 hf CLI 则能顺利完成这些任务。

第二张图展示了 token 对 GPT-5.5 的影响，按任务细分。每根柱子是同一任务上 curl/SDK 的 token 数除以 CLI 的 token 数，因此 2.4× 意味着非 hf 版本完成同样的事情消耗了 2.4 倍的 token：

在一次性的读取操作中（统计数据行数、批量获取元数据），curl 和 SDK 表现良好，有时甚至更轻量。但随着任务变得更加复杂、涉及多个相互依赖的步骤，智能体不得不手工编写整条 REST 调用链（或者翻找 SDK），成本随之飙升：在创建带分支和标签的仓库、删除文件、跨仓库复制或同步存储桶等操作上，达到 CLI 的 2.4 倍到 6 倍。hf CLI 让智能体可以将任务表达为几条更高层的命令，而不必精心构造复杂的工作流。

关键发现

• 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），但付出的 token 开销仍远高于 CLI。

hf-cli 技能

hf附带了一个技能：一份整个命令面的紧凑参考，供 AI 智能体作为上下文加载。它自动生成自实时的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

它能带来什么好处？主要是，智能体不再靠猜了。最直观的一个视角是每次运行需要执行多少条命令，有技能和没有技能的对比：

在两个智能体上，每个任务大约从十条命令降到约七条，工具调用大约减少了 30%。这是因为智能体不再需要反复试探 --help 来找到正确的命令和参数。这项技能不会削减你的 token 开销，因为它会在上下文前面固定附加一段信息，所以同一任务下 token 数量基本持平，甚至略有上升。这项技能也不会让 CLI 变得更可靠，但它能帮助智能体把时间花在执行你的任务上，而不是去摸索这个工具怎么用。在使用 hf 搭配本地模型时，这一点可能特别有帮助。

我们在全新会话中运行了每一项任务，因此该技能在每项任务上都要付出其上下文成本。在真实的多任务会话中，这一成本会被摊薄（智能体只需学习一次命令界面），所以 token 情况在那里很可能会改善；我们没有测量那种情况。

自己动手试试

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

然后把这个技能交给它，这样它从第一轮起就能了解整个命令界面：

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 添加一个条目即可。更多详情请阅读 注册你的智能体运行框架 指南。