设计 hf CLI：打造面向 AI Agent 优化的 Hub 交互方式

背景

hf 是 Hugging Face Hub 的官方命令行入口。长期以来，它主要服务于人类用户，支持通过终端完成 Hub 上的几乎所有操作，包括下载和上传模型、数据集及 Spaces；创建和管理仓库、分支、标签及拉取请求（Pull Requests）；在 Hugging Face 基础设施上运行 Jobs；以及管理 Buckets、Collections、Webhooks 和 Inference Endpoints。

然而，随着编程 AI Agent（如 Claude Code、Codex、Cursor 等）的兴起，hf CLI 的使用场景发生了显著变化。这些 Agent 越来越多地通过命令行与 Hub 交互。为了同时满足人类用户和 AI Agent 的需求，Hugging Face 对 hf CLI 进行了重构。

数据显示，在复杂的、多步骤的任务中，不使用 hf CLI 基线（即 Agent 手动编写 curl 命令或使用 Python SDK）所消耗的 Token 数量，最高可达使用 hf CLI 的 6 倍。这一发现促使 Hugging Face 重新设计 CLI，以优化 Agent 的工作流并降低 Token 成本。

核心内容

1. AI Agent 在 Hub 上的流量统计

Hugging Face 自 2026 年 4 月开始追踪 Hub 上的 Agent 使用情况。hf CLI 及其底层构建的 huggingface_hub Python SDK 能够通过读取环境变量的信号来检测是否由编程 Agent 驱动。这些环境变量包括：

• CLAUDECODE / CLAUDE_CODE（用于 Claude Code）
• CODEX_SANDBOX（用于 Codex）
• 以及针对 Cursor、Gemini、Pi 的特定变量，还有通用的 AI_AGENT 变量。

这一单一信号实现了两个功能：

1. 塑造 CLI 的输出格式（详见下文）。
2. 在每个 Hub 请求中标记 agent/<name> 的 User-Agent，从而将流量归因于驱动它的 Agent。

目前，Claude Code 和 Codex 是用户数量最多的两个 Agent，远超其他工具。仅 Claude Code 就有约 40,000 名独立用户和近 4900 万次请求。尽管这是早期数据，但随着编程 Agent 成为与 Hub 交互的标准方式，预计流量将持续增长。

2. 为人类和 Agent 同时构建

人类用户和编程 AI Agent 对同一 hf 命令的输出有着截然不同的期望：

• 人类用户：期望丰富的终端输出，包括 ANSI 颜色代码、适应屏幕宽度的截断表格、成功时的绿色 ✅、布尔值的 ✔、进度条以及文本提示。
• AI Agent：期望“反向”输出。即无 ANSI 代码、无截断、所有值完整显示（因为 Agent 能处理更密集的输出），且格式紧凑结构化以保持 Token 轻量。此外，Agent 无法回答 CLI 的交互式提示，并且会在超时后愉快地重新运行命令。

为了解决这一差异，hf 在 v1.9.0 版本中引入了 Agent 模式输出，并在后续版本中逐步迁移其余 CLI 功能。

3. 一个命令，多种渲染

当 hf 通过上述环境变量自动检测到 Agent 使用时，它会以不同的方式渲染相同的命令，无需用户传递额外标志：

• 人类模式（默认）： 输出对齐的表格，为适应终端宽度进行截断，并包含如何查看完整信息的提示。状态通过颜色提示（成功绿色，错误红色）。

  > hf models ls --author Qwen --sort downloads --limit 3
  ID CREATED_AT DOWNLOADS ...
  ------------------------ ---------- --------- ...
  Qwen/Qwen3-0.6B 2025-04-27 21156913 ...
  Hint: Use `--no-truncate` or `--format json` to display full values.
  

• Agent 模式（自动检测）： 输出制表符分隔值（TSV）格式，包含完整的仓库 ID、ISO 时间戳和所有标签，无截断，无 ANSI 代码，易于解析且 Token 消耗低。

  $ hf models ls --author Qwen --sort downloads --limit 3
  id created_at downloads ...
  Qwen/Qwen3-0.6B 2025-04-27T03:40:08+00:00 21156913 ...
  

在实现层面，Hugging Face 引入了 .table(...)、.result(...)、.json() 等日志方法，接收原始数据并处理格式化。除了人类和 Agent 模式，还增加了 --json 和 --quiet 选项以便于命令管道连接。默认模式根据上下文自动选择，但用户始终可以通过 --format human | agent | json | quiet 强制指定格式。

4. 下一条命令提示（Next-command hints）

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 正在解析的输出。

5. 非阻塞且安全重试

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
  

6. 可发现且可预测的命令

hf 被设计为易于探查：运行 hf 可查看资源组，