where-my-hug

Where My Hug At?

告诉你的 AI Agent 你希望模型完成什么任务。它会针对任务的每个部分搜索 Hugging Face，并告诉你哪些部分已有现成方案：哪些完全符合需求，哪些需要微调，哪些需要训练，哪些只需编写代码。它提到的每个模型都是真实的、最新的，并且大小适合你的硬件。

适用于 Claude Code、Codex、Copilot、Cursor、Gemini CLI、Cline、Devin、Open WebUI 和任何其他 MCP 客户端，也可以作为 Agent Skill 使用。

它的配套工具 Git for Me! 也会为 GitHub、GitLab 和 Codeberg 上的开源仓库做同样的事。

目录

• 试用
• 工作原理：四个问题 · 拆分任务 · 搜索 · 结论 · 实时检查 · 标记 · 模型大小
• 示例：食谱卡片
• 安装（每种 Agent 的分步说明：USAGE.md）
• 哪些内容会离开你的设备 · 限制 · 安全
• 开发 · 许可证

试用

将它添加到你的 Agent（此处以 Claude Code 为例；其他所有选项见下文）：

claude mcp add --scope user where-my-hug -- npx -y where-my-hug

然后提问：

Where my hug at for transcribing handwritten recipe cards?

你的 Agent 会询问它无法推断的少数信息，将任务拆分为多个部分，然后返回类似下方示例的报告。报告中的每个模型和数据集都在刚刚查过 Hugging Face。它适用于任何可能由模型执行的任务：

Where my hug at for spotting which birds visit my feeder camera?
Where my hug at for sorting support emails by how urgent they are?
Where my hug at for pulling the totals off scanned receipts?

工作原理

1. 先问四个问题

如果你只要求“一个能识别手写内容的模型”，你得到的就会是热门模型：它们往往对你的 GPU 来说太大，许可证不允许你发布，或者格式无法被你的代码加载。因此，在推荐任何模型之前，首先要了解四项信息。你的 Agent 会补充对话或代码库中已有的信息，并询问其余部分：

	它会询问什么	这决定了什么
算力	模型将在何处运行？如果需要训练，又将在何处训练？ 一块 24 GB GPU、仅使用 CPU、一部手机、租用的 GPU	模型可以有多大，以及是否能进行微调
许可证	结果可以用于什么用途？ 商业用途、开源用途、个人用途	哪些许可证符合要求
技术栈	什么会调用模型？ Python 服务、Node、浏览器、移动应用	哪些权重格式可用
数据	有哪些训练数据，或者可以获取哪些数据？ 没有、约 300 张带标签的照片、可以继续收集	微调或训练是否切实可行

回答“还不确定”也没问题：届时会推荐不同范围的选项，并显示每个模型所需的内存，让报告帮助你做出决定。

2. 拆分任务

Agent 会将需求拆分成多个部分，每部分都有输入和输出（照片 → 文本、文本 → 字段）。不属于模型任务的部分（规则、几何计算、解析、查询）会标记为 WRITE：由代码精确完成。大多数需求都包含至少一个这样的部分。用模型做代码可以精确完成的工作，只会增加成本，并非优势。

3. 为每个部分搜索 Hugging Face

Agent 对 Hugging Face 的记忆和它的训练一样久远，也会漏掉长尾内容。因此，不会从记忆中挑选任何内容。对于其他每个部分，Agent 都会编写一条搜索语句（Hub 的任务标签、几个关键词，以及用几个词概括的工作），并通过以下四种方式进行搜索：

方式	查找内容
该任务下载量最高的内容	久经验证的内容
该任务的热门内容	新内容，包括 Agent 训练完成后发布的模型
名称包含各关键词的内容	微调模型和小众模型
模型卡和数据集卡的文本	长尾内容，按卡片上的描述查找，就像网页搜索一样

搜索结果会交替呈现这些方式的结果，因此小众微调模型不会被该任务中无论什么热门内容淹没。

4. 根据搜索结果决定每个部分

结论	含义
USE	搜索找到的模型可以直接完成这项工作。
TUNE	有个模型很接近：对其进行微调，最好使用搜索找到的数据集。
TRAIN	搜索找到的内容都不够接近：训练一个模型，并以搜索找到的数据集为起点。
WRITE	这不是模型该做的事：编写代码。

Agent 会根据结果中写明的内容来判断：任务、卡片、下载量、更新时间。它可能会补充搜索遗漏的已知模型，但这些模型的排名会在搜索结果之后，报告中也会标记为来自记忆。

5. 核实每个选择

每个选择都会实时在 Hugging Face 上查询。不存在的条目会被删除，Agent 会重新搜索其他条目。其余条目会标出可能导致后续问题的事项，并根据你的计算资源评估所需规模，最终生成报告供你查看。报告还会列出搜索找到但未选中的内容，不会隐藏任何搜索结果。如果某个 TRAIN 部分的搜索找到了模型，报告会提示你在训练模型前先检查这些模型。报告中的每条事实（许可证、大小、下载量、新鲜度）都来自 Hugging Face。

底层使用的是一个 MCP 服务，包含三个工具：where_my_hug 用于执行方法中的步骤 1、2 和 4，where_my_hug_search 用于步骤 3，where_my_hug_verify 用于步骤 5。

标记

标记	情况
UNCHECKED	Hugging Face 未响应（服务宕机或受到速率限制）。保留该 ID，并在下次再次查询。
GATED	下载前必须先在 Hugging Face 上接受相关条款。
NO_LICENSE	卡片上没有许可证。
NON_COMMERCIAL	非商业或仅限研究用途的条款（cc-by-nc-*、*-research 等）。
OWN_TERMS	自定义、限制用途或禁止衍生作品的条款（other、Llama、Gemma、RAIL、-nd-）。也可能同时带有 NON_COMMERCIAL：cc-by-nc-nd 两者兼有。
STALE	两年内未更新。
LITTLE_USED	上个月下载量不足 100 次。

模型大小：哪些能在这里运行，以及哪些可能效果更好

每个模型都会显示运行所需的内存：每个参数 2.4 字节，采用半精度，并为激活值预留空间。需要微调的模型也会显示所需内存：使用 QLoRA 时每个参数约 1 字节，全量微调时为 16 字节。针对你提供的计算资源（第一个“N GB”）：

• 第一个能装下的模型会列在该部分的首位。
• 更大的模型会列在“如果能设法运行”的部分：先列搜索选出的模型，再列来自记忆的模型。 勉强可行表示只能以 4 位量化（每个参数 0.6 字节）运行，或需要更大的 GPU。云端表示所需资源超过上述范围：报告会列出 Hugging Face 上提供该模型的服务商，或注明需要租用 GPU。
• 如果没有模型能装下，该部分仍会显示更大的选项。不会重新搜索替代项，因为你可能会找到相应硬件。

以数据集名义找到的模型（或反过来）会归到正确的类别。许可证来自卡片元数据：license、表示自定义条款的 license_name（报告为 other (qwen-research)），或 license: 标签。

示例：菜谱卡片

以上提示词来自 2026-10-14 针对一块 24 GB GPU 的实时运行（已删节）：

_Searched and checked on Hugging Face just now: 7 named, 1 from memory rather than the search, 0 not there and dropped._

## USE  ·  Read the card
**Model: zai-org/GLM-OCR**
license mit · 1.3B parameters (~3.2 GB to run) · 1.7M downloads a month · found: name has ocr, most downloaded for image-to-text
If you can make it work, bigger than one 24 GB GPU:
- Qwen/Qwen3.8-27B: a stretch: ~66.7 GB to run, ~16.7 GB quantized to 4 bits, hosted by novita, cerebras, …
- google/gemma-4-31B-it: a stretch: ~75.1 GB to run, ~18.8 GB quantized to 4 bits, hosted by novita, …
Also: deepseek-ai/DeepSeek-OCR
The search also found, not picked:
- google/gemma-4-26B-A4B-it (11.3M downloads a month): found as most downloaded for image-text-to-text
- openbmb/MiniCPM-V-4.7-35B-A3B (4.2k downloads a month): found as trending for image-text-to-text

## TUNE  ·  Read the hard hands
**Model: microsoft/trocr-base-handwritten**
license mit · 333.3M parameters (~0.8 GB to run; to fine-tune, ~0.3 GB with QLoRA, ~5.3 GB in full) · found: name has handwritten
**Data: Voxel51/iam_handwriting_finevision**
license cc · 1.9k downloads a month · found: name has handwriting
Also: Teklia/IAM-line (stale, from memory)

## WRITE  ·  Parse the amounts
No model: write this one.

其中的每个模型都是通过搜索找到的，包括今年发布的模型。Agent 根据记忆补充的那个数据集已作标记。

安装

需要 Node 22.18 或更高版本。USAGE.md 提供分步设置说明，以及 20 多种 Agent 的链接：Claude Code 和 Desktop、Codex、Copilot（CLI 和 VS Code）、Cursor、Windsurf、Devin、Cline、Gemini CLI、Goose、OpenCode、Zed、Junie、Kiro、Amp、Warp、Continue、LM Studio、Hermes、Mistral Vibe 和 Open WebUI。快速安装方式：

Claude Code、Codex、Copilot CLI，以插件形式安装：包含工具，以及一个知道何时调用这些工具的技能。三者共用同一个市场。

/plugin marketplace add bikemeardsley/where-my-hug          # Claude Code
/plugin install where-my-hug@where-my-hug

codex plugin marketplace add bikemeardsley/where-my-hug      # Codex
codex plugin add where-my-hug@where-my-hug

copilot plugin marketplace add bikemeardsley/where-my-hug    # Copilot CLI
copilot plugin install where-my-hug@where-my-hug

其他任何 MCP 客户端：在客户端配置中添加一个 stdio 服务。大多数客户端使用 mcpServers 这个键（例外情况见 USAGE.md）。

{ "mcpServers": { "where-my-hug": { "command": "npx", "args": ["-y", "where-my-hug"] } } }

Antigravity CLI，以插件形式安装：agy plugin install https://github.com/bikemeardsley/where-my-hug/tree/main/plugin

Gemini CLI，以扩展形式安装：gemini extensions install https://github.com/bikemeardsley/where-my-hug

作为 Agent Skill，适用于会读取 SKILL.md 的 Agent： npx skills add bikemeardsley/where-my-hug。

HF_TOKEN（可选）。 无需令牌即可使用所有公开内容。若要包含你的账号可访问的私有或受限仓库，请传入 Hugging Face 令牌作为 HF_TOKEN（各 Agent 的设置方法）；Claude Code 插件会提示你提供令牌，并将其保存在安全存储中。没有令牌时，私有仓库会显示为缺失，因为 Hugging Face 对两种情况都会返回 401。

哪些内容会离开你的设备

Agent 为每个部分编写的搜索内容（任务标签、关键词、关于任务的简短描述），以及它选取的 ID，会作为 GET 请求发送到 huggingface.co/api；如果你设置了令牌，也会发送令牌。令牌只会发送到那里，且绝不会出现在报告中。你撰写的需求、方法和报告只会在你和 Agent 之间传递。

通过 npx 启动（作为 MCP 服务，或作为技能的 shell 回退方案）时，会从 npm 注册表 registry.npmjs.org 下载 where-my-hug 包。发送到该注册表的内容只有包请求。

限制

• 大小信息来自 safetensors 元数据。只有 GGUF 或 .bin 权重的仓库不会显示参数量，因此无法据此评估其与计算能力的匹配情况。
• 许可证标记读取的是模型卡元数据，而非许可证文本。
• 搜索能找到 Hub 自带搜索能找到的内容：名称和标签，以及模型卡文本。名称不相关且模型卡内容很少的模型仍可能被漏掉。
• 模型卡文本通过 Hub 搜索页面背后的 API 搜索，该 API 没有文档说明。如果 API 发生变化，这种搜索方式就会失效，结果中也会说明；另外三种搜索方式仍会继续运行。

安全

请通过 GitHub 安全公告私下报告漏洞，不要公开提交 issue。SECURITY.md 列出了它会访问的内容：向 Hugging Face 发送 GET 请求，不会访问你设备上的任何内容。

开发

node src/server.ts   # the server, straight from source
npm test             # offline: Hugging Face is mocked, and the server is driven over stdio and HTTP
npm run check        # types

npm install 还会将 JavaScript 构建到 build/ 中，npx 运行的就是这些文件：Node 不会对 node_modules 中的包移除类型。

许可证

MIT