基于 Hugging Face API Tool Builder 技能构建可复用 CLI 工具链ai-engineering-hub 实战指南【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub本文以 hugging-face-skills/skills/hugging-face-tool-builder/SKILL.md 为核心骨架系统讲解如何为 AI Agent 构建用于 Hugging Face API 的可复用命令行脚本涵盖认证规范、脚本规则、OpenAPI 探索、hfCLI 用法以及基于管道piping的可组合数据流水线。读完本文你将掌握从零编写、测试并组合 HF API 脚本的完整方法论并能直接复用 ai-engineering-hub 仓库中随附的 7 个参考脚本投入实战。Skill 概览为 Agent 打造可复用的 HF API 工具hugging-face-tool-builder是 hugging-face-skills 技能集中的一个专门技能其定位非常明确当用户需要构建工具/脚本或需要借助 Hugging Face API 数据完成任务时使用该技能。它在以下场景尤其有价值需要链式组合chaining多个 API 调用任务需要重复执行或自动化需要创建可复用的脚本来获取fetch、丰富enrich或处理processHF 数据。该技能的本质是让 Agent 创建可复用的命令行脚本与工具充分发挥 API 的链式调用、管道传输piping与中间处理能力。你可以直接访问 REST API也可以使用hf命令行工具模型卡片Model Card和数据集卡片Dataset Card则可以从仓库中直接读取。SKILL.md 的 YAML 前置元数据frontmatter是该技能被 Agent 自动激活的关键--- name: hugging-face-tool-builder description: Use this skill when the user wants to build tool/scripts or achieve a task where using data from the Hugging Face API would help. This is especially useful when chaining or combining API calls or the task will be repeated/automated. This Skill creates a reusable script to fetch, enrich or process data. ---正如 hugging-face-skills/README.md 所解释的Skill 是自包含的文件夹将指令、脚本和资源打包在一起供 Agent 使用每个文件夹包含一个带 YAML frontmatter 的SKILL.mdAgent 在执行相关任务时自动加载其中的指令和辅助脚本。脚本规则Script RulesAgent 写脚本的六条铁律SKILL.md 明确列出了构建脚本时必须遵守的六条规则它们是产出高质量、可交付脚本的验收标准必须支持--help参数每个脚本都必须接受--help命令行参数用于描述其输入与输出。这是脚本可被发现、可被他人或 Agent 自己正确调用的基础。非破坏性脚本交付前必须测试不会修改数据、不会产生副作用的脚本在交给用户之前必须先自行测试通过。优先 Shell 脚本默认使用 Shell 脚本只有当复杂度或用户需求要求时才改用 Python 或 TSX。认证必须使用HF_TOKEN环境变量以HF_TOKEN作为 Authorization 头。例如curl -H Authorization: Bearer ${HF_TOKEN} https://huggingface.co/api/。这样可以获得更高的速率限制和适当的数据访问授权例如访问 gated/private 模型。先探查 API 返回结构再定型设计在最终确定脚本设计之前先调查 API 结果的形状在可组合性有利的地方充分利用管道piping与链式调用并优先采用简单方案。完成后分享用法示例脚本完成后要提供使用示例方便其他 Agent 或用户快速上手。此外在存在疑问或需要澄清时应当先确认用户偏好再进行设计。认证规范HF_TOKEN 的正确使用姿势认证是本技能强调的核心工程规范也是访问 gated/private 内容与提升速率限制的前提。仓库中的基线脚本给出了标准实现模式。在 references/baseline_hf_api.sh 中认证被封装为可选的条件头headers() if [[ -n ${HF_TOKEN:-} ]]; then headers(-H Authorization: Bearer ${HF_TOKEN}) fi curl -s ${headers[]} https://huggingface.co/api/models?limit${LIMIT}在 references/baseline_hf_api.py 中同样的逻辑用 Python 标准库urllib实现token os.getenv(HF_TOKEN) headers {Authorization: fBearer {token}} if token else {} url fhttps://huggingface.co/api/models?limit{limit} req urllib.request.Request(url, headersheaders) with urllib.request.urlopen(req) as resp: sys.stdout.write(resp.read().decode(utf-8))关键设计要点令牌来自环境变量而非硬编码绝不把 token 写死在脚本里避免泄露风险未设置 token 时优雅降级HF_TOKEN为空时构造空 headers脚本仍然可用只是速率限制较低、无法访问受限内容set -euo pipefail保证健壮性Shell 脚本通过该行让任何失败命令立即终止、未定义变量报错、管道中任何环节失败都被捕获避免静默产出脏数据。高层级 API 端点总览SKILL.md 列出了 Hugging Face 主要的高层级 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这些端点是构建脚本时的常用入口/api/models用于检索模型/api/datasets检索数据集/api/trending获取趋势内容/api/whoami-v2用于验证当前令牌身份。探索 OpenAPI 规范用 jq 精准提取端点信息Hugging Face API 采用 OpenAPI 标准文档化规范文件位于https://huggingface.co/.well-known/openapi.json。⚠️ 重要警告SKILL.md 特别强调不要直接读取完整的 openapi.json因为该文件过大无法直接处理。正确的做法是使用jq查询并提取相关部分。获取全部 160 个端点的命令curl -s https://huggingface.co/.well-known/openapi.json | jq .paths | keys | sort查看模型搜索端点/api/models的详细定义curl -s https://huggingface.co/.well-known/openapi.json | jq .paths[/api/models]还可以直接查询端点以观察数据形状shape但要把结果数量限制在较小的数值既便于处理又具有代表性。这与脚本规则第 5 条先探查 API 结果形状再定型设计一脉相承——先用jq了解字段结构再决定脚本如何解析输出。使用 hf 命令行工具除了直接调用 REST APIhf命令行工具提供了对 Hugging Face 仓库内容与基础设施的进一步访问。SKILL.md 记录了hf --help的完整输出❯ 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.注意hfCLI 已取代现已弃用的huggingface_hubCLI 命令。如果脚本或文档中还引用旧的huggingface_hub命令应迁移到hf。在 references/hf_model_card_frontmatter.sh 中可以看到对hf的存在性检查运行前会先验证环境if ! command -v hf /dev/null 21; then echo Error: hf CLI is required but not installed 2 exit 1 fi基线脚本三种语言的最小可运行实现SKILL.md 提供了一组ultra-simple基线示例它们逻辑极简、输出原始 JSON并且都带HF_TOKEN认证头。这三个脚本是理解整个工具链的起点。Shell 版本baseline_hf_api.sh完整源码见 references/baseline_hf_api.sh。其核心特性包括$0 [limit]用法limit默认值为 3--help展示使用说明参数校验LIMIT必须是纯数字否则报错退出Error: limit must be a number可选认证头 curl拉取/api/models?limitN输出原始 JSON。LIMIT${1:-3} if ! [[ $LIMIT ~ ^[0-9]$ ]]; then echo Error: limit must be a number 2 exit 1 fiPython 版本baseline_hf_api.py完整源码见 references/baseline_hf_api.py。它仅使用 Python 标准库urllib.request无第三方依赖直接可运行def main() - int: if len(sys.argv) 1 and sys.argv[1] --help: show_help() return 0 limit sys.argv[1] if len(sys.argv) 1 else 3 if not limit.isdigit(): print(Error: limit must be a number, filesys.stderr) return 1 ...该脚本以raise SystemExit(main())结尾保证非零退出码能被管道下游正确感知——这是可组合脚本的关键设计。TypeScript 版本baseline_hf_api.tsx完整源码见 references/baseline_hf_api.tsx。它以#!/usr/bin/env tsxshebang 开头可用tsx直接执行使用原生fetchAPIconst limit arg ?? 3; if (!/^\d$/.test(limit)) { console.error(Error: limit must be a number); process.exit(1); } const token process.env.HF_TOKEN; const headers: Recordstring, string token ? { Authorization: Bearer ${token} } : {}; const url https://huggingface.co/api/models?limit${limit};三个基线脚本遵循完全一致的约定默认 limit3、支持 --help、数字参数校验、HF_TOKEN 可选认证、原始 JSON 输出。这种一致性使得它们可以无差别地作为管道入口被替换。可组合工具stdin → NDJSON 流式管道可组合性的关键模式是stdin → NDJSON脚本从标准输入读取模型 ID 列表逐条获取元数据每行输出一个 JSON 对象NDJSONNewline-Delimited JSON方便流式处理。references/hf_enrich_models.sh 正是这样一个工具。它同时支持位置参数和stdin 输入两种模式# 直接传参 hf_enrich_models.sh gpt2 distilbert-base-uncased # 管道输入 baseline_hf_api.sh 50 | jq -r .[].id | hf_enrich_models.sh # 带认证 HF_TOKENyour_token hf_enrich_models.sh microsoft/DialoGPT-medium其无参数且 stdin 是终端TTY时展示帮助并退出的设计保证了交互式误调用不会挂起if [[ -t 0 ]]; then show_help exit 1 fi while IFS read -r model_id; do process_id $model_id done每个模型 ID 的处理逻辑包含了完整的错误分级设计这是生产级脚本的重要细节请求失败request_failed返回非法 JSONinvalid_json返回.error字段not_found如 404 模型不存在解析失败parse_failed。错误以{id: ..., error: ...}的 NDJSON 行输出而不是让整个管道崩溃——错误行与正常行格式一致下游jq过滤时可以选择丢弃error字段或单独处理。正常行的输出字段为id, downloads, likes, pipeline_tag, tagsjq -c --arg id $model_id { id: (.id // $id), downloads: (.downloads // 0), likes: (.likes // 0), pipeline_tag: (.pipeline_tag // unknown), tags: (.tags // []) } $response使用//提供默认值保证字段缺失时输出依然结构完整。实战管道把命令串成数据流水线SKILL.md 给出了三条可直接运行的管道示例充分展示了以简单工具组合出强大能力的设计哲学。示例 1Top 10 高下载模型baseline_hf_api.sh 25 | jq -r .[].id | hf_enrich_models.sh | jq -s sort_by(.downloads) | reverse | .[:10]链路解析拉取 25 个模型 → 提取 ID 列表 → 逐条丰富元数据NDJSON→ 按 downloads 降序排序取前 10。示例 2纯 jq 一步到位baseline_hf_api.sh 50 | jq [.[] | {id, downloads}] | sort_by(.downloads) | reverse | .[:10]当数据已经在响应中时无需额外的丰富步骤单个jq即可完成投影、排序、截取。示例 3模型卡片 frontmatter 摘要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})这条管道混合了 printf 构造输入、frontmatter 提取、批量聚合三种能力输出每个模型的 license 与是否含额外 gated 提示标志。进阶参考脚本三段源码级剖析SKILL.md 引用了三个reference examples它们展示了比基线更完整的工程模式。1. hf_model_papers_auth.sh多步 API 认证卫生完整源码见 references/hf_model_papers_auth.sh。它演示了多步 API 调用trending → 模型元数据 → 模型卡片解析并带降级策略。核心能力两种模式$0 MODEL_ID分析单个模型$0 --trending [N]分析前 N 个趋势模型默认 5认证封装hf_api_call()函数统一处理HF_TOKEN认证头并返回错误 JSON 兜底网络异常hf_api_call() { local url$1 local headers() if [[ -n ${HF_TOKEN:-} ]]; then headers(-H Authorization: Bearer $HF_TOKEN) fi curl -s ${headers[]} $url 2/dev/null || echo {error: Network error} }卡片论文提取extract_papers()从模型卡片 README 中用正则抽取 arXiv URL、DOI URL、arXiv ID格式YYYY.NNNNN以及 paper/publication 提及私有模型友好提示当 API 返回错误且未设置 token 时提示用户这可能是私有模型请尝试设置 HF_TOKEN 环境变量。从源码结构看该脚本将认证-请求-解析-展示分离为独立函数为后续扩展其他端点提供了清晰模板。2. find_models_by_paper.sh弹性检索策略完整源码见 references/find_models_by_paper.sh。它展示了搜索策略的弹性和用户友好的帮助输出arXiv ID 识别输入匹配^[0-9]{4}\.[0-9]{4,7}$时自动构造arxiv:ID搜索查询否则按普通关键词搜索检索降级路径当 arXiv 前缀搜索无结果时自动回退为去掉arxiv:前缀的宽泛搜索并再次尝试——这正是 SKILL.md 描述的resilient query strategyif [[ $IS_ARXIV_SEARCH true ]]; then echo -e ${YELLOW}Trying broader search without arxiv: prefix...${NC} SEARCH_QUERY$SEARCH_TERM ... fi可选认证--token标志控制是否使用HF_TOKEN设置了 token 但未加--token时输出黄色警告提示结构化输出用jq从响应中提取id, arxiv_tags, downloads, likes, task(pipeline_tag), library(library_name)base64 编码后逐条解码输出避免 JSON 中特殊字符破坏行结构。3. hf_model_card_frontmatter.shhf CLI YAML 解析完整源码见 references/hf_model_card_frontmatter.sh。它演示了hfCLI 与 Python 内联解析的结合用hf download $MODEL_ID README.md --repo-type model --local-dir ...下载模型卡片HF_TOKEN通过--token参数传递给hfCLI用内联 Pythonheredoc解析 README 的 YAML frontmatter输出字段为id, license, pipeline_tag, library_name, tags, language, new_version, has_extra_gated_prompt关键设计has_extra_gated_prompt是通过检测 frontmatter 中是否出现extra_gated_prompt键得出的布尔标志可用来快速筛选需要额外申请访问的模型使用mktemp -d创建临时目录并在退出时用trap cleanup EXIT清理避免残留临时文件对每个模型 ID 都保证输出一行 JSON——成功时输出解析结果失败时输出{id: ..., error: ...}管道下游永远可以按行消费。最佳实践总结综合 SKILL.md 的规则与仓库参考脚本的实现可以提炼出构建 HF API 工具的核心实践统一的--help约定每个脚本自描述输入输出是脚本可组合与可发现的前提HF_TOKEN环境变量认证不硬编码令牌认证头可选构造未设置时优雅降级先探查数据结构再定型设计用curl jq观察响应 shape避免凭猜测写解析逻辑NDJSON 作为中间格式每行一个 JSON 对象天然适配流式管道错误也按相同格式输出函数化组织将认证、请求、解析、展示拆分为独立函数如 references/hf_model_papers_auth.sh 所示便于复用与扩展交付前测试非破坏性脚本在交给用户前必须运行验证提供使用示例完成脚本后附上可复制的调用示例包括直接调用与管道组合两种形态。快速上手本技能的参考脚本位于 hugging-face-skills/skills/hugging-face-tool-builder/references/包含 7 个可直接运行的示例。按 hugging-face-skills/README.md 的说明克隆仓库后可运行bash scripts/link-skills.sh安装全部技能然后在支持 Agent Skill 的编码 Agent如 Claude Code中通过/skills命令验证技能是否就绪之后便可在对话中直接要求 Agent使用 hugging-face-tool-builder 技能构建脚本来完成任务。环境前提运行hfCLI 相关脚本如hf_model_card_frontmatter.sh需要预先安装hf工具管道示例依赖jqTSX 脚本需要tsx运行时访问 gated/private 模型或追求更高速率限制时请设置HF_TOKEN环境变量。【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
基于 Hugging Face API Tool Builder 技能构建可复用 CLI 工具链：ai-engineering-hub 实战指南
基于 Hugging Face API Tool Builder 技能构建可复用 CLI 工具链ai-engineering-hub 实战指南【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub本文以 hugging-face-skills/skills/hugging-face-tool-builder/SKILL.md 为核心骨架系统讲解如何为 AI Agent 构建用于 Hugging Face API 的可复用命令行脚本涵盖认证规范、脚本规则、OpenAPI 探索、hfCLI 用法以及基于管道piping的可组合数据流水线。读完本文你将掌握从零编写、测试并组合 HF API 脚本的完整方法论并能直接复用 ai-engineering-hub 仓库中随附的 7 个参考脚本投入实战。Skill 概览为 Agent 打造可复用的 HF API 工具hugging-face-tool-builder是 hugging-face-skills 技能集中的一个专门技能其定位非常明确当用户需要构建工具/脚本或需要借助 Hugging Face API 数据完成任务时使用该技能。它在以下场景尤其有价值需要链式组合chaining多个 API 调用任务需要重复执行或自动化需要创建可复用的脚本来获取fetch、丰富enrich或处理processHF 数据。该技能的本质是让 Agent 创建可复用的命令行脚本与工具充分发挥 API 的链式调用、管道传输piping与中间处理能力。你可以直接访问 REST API也可以使用hf命令行工具模型卡片Model Card和数据集卡片Dataset Card则可以从仓库中直接读取。SKILL.md 的 YAML 前置元数据frontmatter是该技能被 Agent 自动激活的关键--- name: hugging-face-tool-builder description: Use this skill when the user wants to build tool/scripts or achieve a task where using data from the Hugging Face API would help. This is especially useful when chaining or combining API calls or the task will be repeated/automated. This Skill creates a reusable script to fetch, enrich or process data. ---正如 hugging-face-skills/README.md 所解释的Skill 是自包含的文件夹将指令、脚本和资源打包在一起供 Agent 使用每个文件夹包含一个带 YAML frontmatter 的SKILL.mdAgent 在执行相关任务时自动加载其中的指令和辅助脚本。脚本规则Script RulesAgent 写脚本的六条铁律SKILL.md 明确列出了构建脚本时必须遵守的六条规则它们是产出高质量、可交付脚本的验收标准必须支持--help参数每个脚本都必须接受--help命令行参数用于描述其输入与输出。这是脚本可被发现、可被他人或 Agent 自己正确调用的基础。非破坏性脚本交付前必须测试不会修改数据、不会产生副作用的脚本在交给用户之前必须先自行测试通过。优先 Shell 脚本默认使用 Shell 脚本只有当复杂度或用户需求要求时才改用 Python 或 TSX。认证必须使用HF_TOKEN环境变量以HF_TOKEN作为 Authorization 头。例如curl -H Authorization: Bearer ${HF_TOKEN} https://huggingface.co/api/。这样可以获得更高的速率限制和适当的数据访问授权例如访问 gated/private 模型。先探查 API 返回结构再定型设计在最终确定脚本设计之前先调查 API 结果的形状在可组合性有利的地方充分利用管道piping与链式调用并优先采用简单方案。完成后分享用法示例脚本完成后要提供使用示例方便其他 Agent 或用户快速上手。此外在存在疑问或需要澄清时应当先确认用户偏好再进行设计。认证规范HF_TOKEN 的正确使用姿势认证是本技能强调的核心工程规范也是访问 gated/private 内容与提升速率限制的前提。仓库中的基线脚本给出了标准实现模式。在 references/baseline_hf_api.sh 中认证被封装为可选的条件头headers() if [[ -n ${HF_TOKEN:-} ]]; then headers(-H Authorization: Bearer ${HF_TOKEN}) fi curl -s ${headers[]} https://huggingface.co/api/models?limit${LIMIT}在 references/baseline_hf_api.py 中同样的逻辑用 Python 标准库urllib实现token os.getenv(HF_TOKEN) headers {Authorization: fBearer {token}} if token else {} url fhttps://huggingface.co/api/models?limit{limit} req urllib.request.Request(url, headersheaders) with urllib.request.urlopen(req) as resp: sys.stdout.write(resp.read().decode(utf-8))关键设计要点令牌来自环境变量而非硬编码绝不把 token 写死在脚本里避免泄露风险未设置 token 时优雅降级HF_TOKEN为空时构造空 headers脚本仍然可用只是速率限制较低、无法访问受限内容set -euo pipefail保证健壮性Shell 脚本通过该行让任何失败命令立即终止、未定义变量报错、管道中任何环节失败都被捕获避免静默产出脏数据。高层级 API 端点总览SKILL.md 列出了 Hugging Face 主要的高层级 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这些端点是构建脚本时的常用入口/api/models用于检索模型/api/datasets检索数据集/api/trending获取趋势内容/api/whoami-v2用于验证当前令牌身份。探索 OpenAPI 规范用 jq 精准提取端点信息Hugging Face API 采用 OpenAPI 标准文档化规范文件位于https://huggingface.co/.well-known/openapi.json。⚠️ 重要警告SKILL.md 特别强调不要直接读取完整的 openapi.json因为该文件过大无法直接处理。正确的做法是使用jq查询并提取相关部分。获取全部 160 个端点的命令curl -s https://huggingface.co/.well-known/openapi.json | jq .paths | keys | sort查看模型搜索端点/api/models的详细定义curl -s https://huggingface.co/.well-known/openapi.json | jq .paths[/api/models]还可以直接查询端点以观察数据形状shape但要把结果数量限制在较小的数值既便于处理又具有代表性。这与脚本规则第 5 条先探查 API 结果形状再定型设计一脉相承——先用jq了解字段结构再决定脚本如何解析输出。使用 hf 命令行工具除了直接调用 REST APIhf命令行工具提供了对 Hugging Face 仓库内容与基础设施的进一步访问。SKILL.md 记录了hf --help的完整输出❯ 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.注意hfCLI 已取代现已弃用的huggingface_hubCLI 命令。如果脚本或文档中还引用旧的huggingface_hub命令应迁移到hf。在 references/hf_model_card_frontmatter.sh 中可以看到对hf的存在性检查运行前会先验证环境if ! command -v hf /dev/null 21; then echo Error: hf CLI is required but not installed 2 exit 1 fi基线脚本三种语言的最小可运行实现SKILL.md 提供了一组ultra-simple基线示例它们逻辑极简、输出原始 JSON并且都带HF_TOKEN认证头。这三个脚本是理解整个工具链的起点。Shell 版本baseline_hf_api.sh完整源码见 references/baseline_hf_api.sh。其核心特性包括$0 [limit]用法limit默认值为 3--help展示使用说明参数校验LIMIT必须是纯数字否则报错退出Error: limit must be a number可选认证头 curl拉取/api/models?limitN输出原始 JSON。LIMIT${1:-3} if ! [[ $LIMIT ~ ^[0-9]$ ]]; then echo Error: limit must be a number 2 exit 1 fiPython 版本baseline_hf_api.py完整源码见 references/baseline_hf_api.py。它仅使用 Python 标准库urllib.request无第三方依赖直接可运行def main() - int: if len(sys.argv) 1 and sys.argv[1] --help: show_help() return 0 limit sys.argv[1] if len(sys.argv) 1 else 3 if not limit.isdigit(): print(Error: limit must be a number, filesys.stderr) return 1 ...该脚本以raise SystemExit(main())结尾保证非零退出码能被管道下游正确感知——这是可组合脚本的关键设计。TypeScript 版本baseline_hf_api.tsx完整源码见 references/baseline_hf_api.tsx。它以#!/usr/bin/env tsxshebang 开头可用tsx直接执行使用原生fetchAPIconst limit arg ?? 3; if (!/^\d$/.test(limit)) { console.error(Error: limit must be a number); process.exit(1); } const token process.env.HF_TOKEN; const headers: Recordstring, string token ? { Authorization: Bearer ${token} } : {}; const url https://huggingface.co/api/models?limit${limit};三个基线脚本遵循完全一致的约定默认 limit3、支持 --help、数字参数校验、HF_TOKEN 可选认证、原始 JSON 输出。这种一致性使得它们可以无差别地作为管道入口被替换。可组合工具stdin → NDJSON 流式管道可组合性的关键模式是stdin → NDJSON脚本从标准输入读取模型 ID 列表逐条获取元数据每行输出一个 JSON 对象NDJSONNewline-Delimited JSON方便流式处理。references/hf_enrich_models.sh 正是这样一个工具。它同时支持位置参数和stdin 输入两种模式# 直接传参 hf_enrich_models.sh gpt2 distilbert-base-uncased # 管道输入 baseline_hf_api.sh 50 | jq -r .[].id | hf_enrich_models.sh # 带认证 HF_TOKENyour_token hf_enrich_models.sh microsoft/DialoGPT-medium其无参数且 stdin 是终端TTY时展示帮助并退出的设计保证了交互式误调用不会挂起if [[ -t 0 ]]; then show_help exit 1 fi while IFS read -r model_id; do process_id $model_id done每个模型 ID 的处理逻辑包含了完整的错误分级设计这是生产级脚本的重要细节请求失败request_failed返回非法 JSONinvalid_json返回.error字段not_found如 404 模型不存在解析失败parse_failed。错误以{id: ..., error: ...}的 NDJSON 行输出而不是让整个管道崩溃——错误行与正常行格式一致下游jq过滤时可以选择丢弃error字段或单独处理。正常行的输出字段为id, downloads, likes, pipeline_tag, tagsjq -c --arg id $model_id { id: (.id // $id), downloads: (.downloads // 0), likes: (.likes // 0), pipeline_tag: (.pipeline_tag // unknown), tags: (.tags // []) } $response使用//提供默认值保证字段缺失时输出依然结构完整。实战管道把命令串成数据流水线SKILL.md 给出了三条可直接运行的管道示例充分展示了以简单工具组合出强大能力的设计哲学。示例 1Top 10 高下载模型baseline_hf_api.sh 25 | jq -r .[].id | hf_enrich_models.sh | jq -s sort_by(.downloads) | reverse | .[:10]链路解析拉取 25 个模型 → 提取 ID 列表 → 逐条丰富元数据NDJSON→ 按 downloads 降序排序取前 10。示例 2纯 jq 一步到位baseline_hf_api.sh 50 | jq [.[] | {id, downloads}] | sort_by(.downloads) | reverse | .[:10]当数据已经在响应中时无需额外的丰富步骤单个jq即可完成投影、排序、截取。示例 3模型卡片 frontmatter 摘要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})这条管道混合了 printf 构造输入、frontmatter 提取、批量聚合三种能力输出每个模型的 license 与是否含额外 gated 提示标志。进阶参考脚本三段源码级剖析SKILL.md 引用了三个reference examples它们展示了比基线更完整的工程模式。1. hf_model_papers_auth.sh多步 API 认证卫生完整源码见 references/hf_model_papers_auth.sh。它演示了多步 API 调用trending → 模型元数据 → 模型卡片解析并带降级策略。核心能力两种模式$0 MODEL_ID分析单个模型$0 --trending [N]分析前 N 个趋势模型默认 5认证封装hf_api_call()函数统一处理HF_TOKEN认证头并返回错误 JSON 兜底网络异常hf_api_call() { local url$1 local headers() if [[ -n ${HF_TOKEN:-} ]]; then headers(-H Authorization: Bearer $HF_TOKEN) fi curl -s ${headers[]} $url 2/dev/null || echo {error: Network error} }卡片论文提取extract_papers()从模型卡片 README 中用正则抽取 arXiv URL、DOI URL、arXiv ID格式YYYY.NNNNN以及 paper/publication 提及私有模型友好提示当 API 返回错误且未设置 token 时提示用户这可能是私有模型请尝试设置 HF_TOKEN 环境变量。从源码结构看该脚本将认证-请求-解析-展示分离为独立函数为后续扩展其他端点提供了清晰模板。2. find_models_by_paper.sh弹性检索策略完整源码见 references/find_models_by_paper.sh。它展示了搜索策略的弹性和用户友好的帮助输出arXiv ID 识别输入匹配^[0-9]{4}\.[0-9]{4,7}$时自动构造arxiv:ID搜索查询否则按普通关键词搜索检索降级路径当 arXiv 前缀搜索无结果时自动回退为去掉arxiv:前缀的宽泛搜索并再次尝试——这正是 SKILL.md 描述的resilient query strategyif [[ $IS_ARXIV_SEARCH true ]]; then echo -e ${YELLOW}Trying broader search without arxiv: prefix...${NC} SEARCH_QUERY$SEARCH_TERM ... fi可选认证--token标志控制是否使用HF_TOKEN设置了 token 但未加--token时输出黄色警告提示结构化输出用jq从响应中提取id, arxiv_tags, downloads, likes, task(pipeline_tag), library(library_name)base64 编码后逐条解码输出避免 JSON 中特殊字符破坏行结构。3. hf_model_card_frontmatter.shhf CLI YAML 解析完整源码见 references/hf_model_card_frontmatter.sh。它演示了hfCLI 与 Python 内联解析的结合用hf download $MODEL_ID README.md --repo-type model --local-dir ...下载模型卡片HF_TOKEN通过--token参数传递给hfCLI用内联 Pythonheredoc解析 README 的 YAML frontmatter输出字段为id, license, pipeline_tag, library_name, tags, language, new_version, has_extra_gated_prompt关键设计has_extra_gated_prompt是通过检测 frontmatter 中是否出现extra_gated_prompt键得出的布尔标志可用来快速筛选需要额外申请访问的模型使用mktemp -d创建临时目录并在退出时用trap cleanup EXIT清理避免残留临时文件对每个模型 ID 都保证输出一行 JSON——成功时输出解析结果失败时输出{id: ..., error: ...}管道下游永远可以按行消费。最佳实践总结综合 SKILL.md 的规则与仓库参考脚本的实现可以提炼出构建 HF API 工具的核心实践统一的--help约定每个脚本自描述输入输出是脚本可组合与可发现的前提HF_TOKEN环境变量认证不硬编码令牌认证头可选构造未设置时优雅降级先探查数据结构再定型设计用curl jq观察响应 shape避免凭猜测写解析逻辑NDJSON 作为中间格式每行一个 JSON 对象天然适配流式管道错误也按相同格式输出函数化组织将认证、请求、解析、展示拆分为独立函数如 references/hf_model_papers_auth.sh 所示便于复用与扩展交付前测试非破坏性脚本在交给用户前必须运行验证提供使用示例完成脚本后附上可复制的调用示例包括直接调用与管道组合两种形态。快速上手本技能的参考脚本位于 hugging-face-skills/skills/hugging-face-tool-builder/references/包含 7 个可直接运行的示例。按 hugging-face-skills/README.md 的说明克隆仓库后可运行bash scripts/link-skills.sh安装全部技能然后在支持 Agent Skill 的编码 Agent如 Claude Code中通过/skills命令验证技能是否就绪之后便可在对话中直接要求 Agent使用 hugging-face-tool-builder 技能构建脚本来完成任务。环境前提运行hfCLI 相关脚本如hf_model_card_frontmatter.sh需要预先安装hf工具管道示例依赖jqTSX 脚本需要tsx运行时访问 gated/private 模型或追求更高速率限制时请设置HF_TOKEN环境变量。【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
