hugging-face-tool-builder

支持材料可用性

此目录副本包含下方的内联指南，但不包含以下支持路径。这些是外部前置条件，并非随附文件：

• <support-root>/references/hf_model_papers_auth.sh
• <support-root>/references/find_models_by_paper.sh
• <support-root>/references/hf_model_card_frontmatter.sh
• <support-root>/references/baseline_hf_api.sh
• <support-root>/references/baseline_hf_api.py
• <support-root>/references/baseline_hf_api.tsx
• <support-root>/references/hf_enrich_models.sh

在使用依赖这些路径的步骤之前，请索取原始支持材料或现有安装；此目录副本未提供经过验证的下载来源。请根据该安装解析各路径，检查其内容，并验证适用的许可证和执行前置条件。所需文件不存在时，不要运行命令，也不要声称已遵循所引用的流程。不要伪造缺失的脚本，也不要将名称相同但无关的文件视为等效文件。此处已完整记录的独立步骤可在用户授权范围内继续；请将任何依赖步骤报告为不可用。

Hugging Face API 工具构建器

你的目标是创建可复用的命令行脚本和实用工具，以便使用 Hugging Face API，并在有帮助时支持串联、管道传递和中间处理。你可以直接访问 API，也可以使用 hf 命令行工具。可以直接从仓库访问模型卡片和数据集卡片。

使用场景

• 你需要围绕 Hugging Face API 或 hf 命令行工具构建可复用的 CLI 脚本。
• 你想要支持串联、管道传递和中间处理的 shell 友好型实用工具。
• 你正在自动化重复的 Hub 任务，需要可组合的接口，而不是临时的 API 调用。

脚本规则

请务必遵循以下规则：

• 脚本必须接受 --help 命令行参数，用于说明其输入和输出
• 非破坏性脚本在交付给用户前必须经过测试
• 优先使用 Shell 脚本；若复杂度或用户需求有此要求，则使用 Python 或 TSX。
• 重要：使用 HF_TOKEN 环境变量作为 Authorization 标头。例如：curl -H "Authorization: Bearer ${HF_TOKEN}" https://huggingface.co/api/。这样可以获得更高的速率限制，以及访问数据所需的适当授权。
• 在敲定最终设计之前，先了解 API 返回结果的结构；若可组合性有优势，请利用管道传递和串联，并尽可能采用简单方案。
• 完成后分享用法示例。

如有需要澄清或确认的问题，请务必确认用户的偏好。

示例脚本

以下路径均相对于此技能目录。

参考示例：

• references/hf_model_papers_auth.sh — 自动使用 HF_TOKEN，并通过回退方案串联趋势内容 → 模型元数据 → 模型卡解析；展示了多步 API 用法，以及访问受限或私有内容时的身份验证规范。
• references/find_models_by_paper.sh — 可通过 --token 选择使用 HF_TOKEN，执行一致的身份验证搜索，并在以 arXiv 为前缀的搜索范围过窄时重试；展示了稳健的查询策略和清晰的面向用户的帮助信息。
• references/hf_model_card_frontmatter.sh — 使用 hf CLI 下载模型卡，提取 YAML frontmatter，并输出 NDJSON 摘要（许可证、pipeline 标签、标签、受限访问提示词标记），便于筛选。

基线示例（超简单、逻辑精简，使用 HF_TOKEN 标头输出原始 JSON）：

• references/baseline_hf_api.sh — bash
• references/baseline_hf_api.py — python
• references/baseline_hf_api.tsx — typescript 可执行文件

可组合的实用工具（标准输入 → NDJSON）：

• references/hf_enrich_models.sh — 从标准输入读取模型 ID，按 ID 获取元数据，并为流式处理管道每行输出一个 JSON 对象。

通过管道实现组合（便于 shell 使用的 JSON 输出）：

• <support-root>/references/baseline_hf_api.sh 25 | jq -r '.[].id' | references/hf_enrich_models.sh | jq -s 'sort_by(.downloads) | reverse | .[:10]'
• <support-root>/references/baseline_hf_api.sh 50 | jq '[.[] | {id, downloads}] | sort_by(.downloads) | reverse | .[:10]'
• printf '%s\n' openai/gpt-oss-120b meta-llama/Meta-Llama-3.1-8B | references/hf_model_card_frontmatter.sh | jq -s 'map({id, license, has_extra_gated_prompt})'

高级端点

以下是 https://huggingface.co 上提供的主要 API 端点

/api/datasets
/api/models
/api/spaces
/api/collections
/api/daily_papers
/api/notifications
/api/settings
/api/whoami-v2
/api/trending
/oauth/userinfo

访问 API

API 使用 https://huggingface.co/.well-known/openapi.json 上的 OpenAPI 标准编写文档。

**重要：**不要尝试直接读取 https://huggingface.co/.well-known/openapi.json，因为它过大，无法处理。

**重要：**使用 jq 查询并提取相关部分。例如，

获取全部 160 个端点的命令

curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths | keys | sort'

模型搜索端点详情

curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths["/api/models"]'

你也可以查询端点以了解数据结构。查询时，请将结果数量限制在较小范围，使其易于处理，同时具有代表性。

使用 HF 命令行工具

hf 命令行工具可让你进一步访问 Hugging Face 仓库内容和基础设施。

❯ hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...

  Hugging Face Hub CLI

Options:
  --help                Show this message and exit.

Commands:
  auth                 Manage authentication (login, logout, etc.).
  cache                Manage local cache directory.
  download             Download files from the Hub.
  endpoints            Manage Hugging Face Inference Endpoints.
  env                  Print information about the environment.
  jobs                 Run and manage Jobs on the Hub.
  repo                 Manage repos on the Hub.
  repo-files           Manage files in a repo on the Hub.
  upload               Upload a file or a folder to the Hub.
  upload-large-folder  Upload a large folder to the Hub.
  version              Print information about the hf version.

hf CLI 命令已取代现已弃用的 huggingface_hub CLI 命令。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。