用 Hugging Face API…

当需要反复或自动化地获取、加工 Hugging Face 上的模型/数据集/论文等数据时，构建可复用的命令行脚本。

适用场景

解决思路

1. 脚本必须支持 `--help` 命令行参数，用于说明其输入与输出。
2. 非破坏性脚本在交付给用户前应先进行测试。
3. 优先使用 Shell 脚本；若复杂度或用户需求需要，则改用 Python 或 TSX。
4. 使用 `HF_TOKEN` 环境变量作为 Authorization 头，例如：`curl -H "Authorization: Bearer ${HF_TOKEN}" https://huggingface.co/api/`，以获得更高的速率限制和适当的数据访问授权。
5. 在确定最终设计前先调查 API 返回结果的结构；在可组合性有优势时利用管道和链式调用，尽量优先选择简单方案。
6. 完成后分享使用示例。
7. 在有疑问或需要澄清时，确认用户偏好。
8. 参考示例脚本（路径相对于本 skill 目录）：`references/hf_model_papers_auth.sh`（自动使用 `HF_TOKEN`，链式调用 trending → 模型元数据 → 模型卡解析并带 fallback，展示多步 API 使用及针对 gated/私有内容的认证卫生）；`references/find_models_by_paper.sh`（通过 `--token` 可选使用 `HF_TOKEN`，一致的认证搜索，以及当 arXiv 前缀搜索过窄时的重试路径，展示弹性查询策略和清晰的用户帮助）；`references/hf_model_card_frontmatter.sh`（使用 `hf` CLI 下载模型卡，提取 YAML frontmatter，输出 NDJSON 摘要，包括 license、pipeline tag、tags、gated prompt flag，便于过滤）。
9. 基线示例（超简单、最少逻辑、带 `HF_TOKEN` 头的原始 JSON 输出）：`references/baseline_hf_api.sh`（bash）、`references/baseline_hf_api.py`（python）、`references/baseline_hf_api.tsx`（typescript 可执行文件）。
10. 可组合工具（stdin → NDJSON）：`references/hf_enrich_models.sh` 从 stdin 读取模型 ID，逐个获取元数据，每行输出一个 JSON 对象，用于流式管道。
11. 通过管道实现可组合性（shell 友好的 JSON 输出）示例：`references/baseline_hf_api.sh 25 | jq -r '.[].id' | references/hf_enrich_models.sh | jq -s 'sort_by(.downloads) | reverse | .[:10]'`；`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})'`。
12. 主要 API 端点位于 `https://huggingface.co`：`/api/datasets`、`/api/models`、`/api/spaces`、`/api/collections`、`/api/daily_papers`、`/api/notifications`、`/api/settings`、`/api/whoami-v2`、`/api/trending`、`/oauth/userinfo`。
13. API 以 OpenAPI 标准记录在 `https://huggingface.co/.well-known/openapi.json`。
14. 不要直接读取 `https://huggingface.co/.well-known/openapi.json`，因为它太大无法处理。
15. 使用 `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"]'`。
16. 也可以查询端点以查看数据形状；查询时将结果限制在较小的数量，使其易于处理但仍具代表性。
17. 使用 `hf` 命令行工具进一步访问 Hugging Face 仓库内容和基础设施（`hf --help` 列出 auth、buckets、cache、collections、datasets、discussions、download、endpoints、env、extensions、jobs、models、papers、repos、skills、spaces、sync、upload、upload-large-folder、version、webhooks 等命令）。
18. 注意 `hf` CLI 命令已取代已弃用的 `huggingface-cli` 命令。