# Agent 接入说明

AgentHub 是面向 AI agent 的资源目录。下面四种方式读取的是同一份数据，按你的运行环境选用。

## 1. llms.txt

- [https://hebbmind.com/llms.txt](https://hebbmind.com/llms.txt)：站点索引，列出工具集的入口（按类型、职业、标签）、榜单、当日推荐、编辑推荐、合集与最新的文章。
- [https://hebbmind.com/llms-full.txt](https://hebbmind.com/llms-full.txt)：全部已收录资源的简介、仓库地址与安装命令。

## 2. Markdown 页面

任意页面的 URL 后加 `.md`，或发送请求头 `Accept: text/markdown`，即可得到该页面的 Markdown 版本：

```bash
curl https://hebbmind.com/zh-CN/tools.md
curl -H 'Accept: text/markdown' https://hebbmind.com/zh-CN/tools
```

| 页面 | Markdown 地址 |
| --- | --- |
| 首页：编辑推荐、合集、热榜、最新文章、工具集的入口 | `/index.md` |
| 工具集：全部资源。可带 `?q=` 搜索，`?type=`、`?profession=`、`?tag=` 按类型、职业、标签过滤，条件可以同时用；`?page=` 翻页 | `/tools.md` |
| 热榜（可带 `?type=` 按类型过滤） | `/hot.md` |
| 标签清单（可带 `?q=` 按名称查找） | `/tags.md` |
| 资源详情（含安装命令与 README） | `/<type>/<slug>.md` |
| 合集：运营围绕一件事挑好的一组资源 | `/collections.md` |
| 合集详情：其中的资源与推荐语 | `/collections/<slug>.md` |
| 博客：文章列表（`?page=` 翻页） | `/blog.md` |
| 文章：正文，站内卡片写成资源或合集的链接 | `/blog/<slug>.md` |

## 3. JSON API

无需鉴权，允许跨域。机器可读定义见 [OpenAPI](https://hebbmind.com/openapi.json)。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/v1/search?q=&type=&profession=&tag=&page=&pageSize=` | 关键字搜索 |
| GET | `/api/v1/resources?type=&profession=&tag=&featured=&page=&pageSize=` | 资源列表 |
| GET | `/api/v1/resources/{type}/{slug}` | 资源详情，含 README |
| GET | `/api/v1/professions` | 当前的职业清单与每个职业下的资源数 |
| GET | `/api/v1/tags?type=&profession=&q=&limit=` | 标签与每个标签下的资源数 |
| GET | `/api/v1/hot?type=&profession=&limit=` | 热榜：近 7 天最受关注的资源 |
| GET | `/api/v1/daily-picks` | 当日推荐：运营当天挑选的热门资源与推荐语 |
| GET | `/api/v1/collections` | 合集清单 |
| GET | `/api/v1/collections/{slug}` | 合集详情：其中的资源与推荐语 |

```bash
curl 'https://hebbmind.com/api/v1/search?q=pdf&type=skill'
curl 'https://hebbmind.com/api/v1/resources?profession=fullstack'
```

## 4. MCP 服务器

端点：`https://hebbmind.com/api/mcp`（Streamable HTTP，无状态，无需鉴权）。

| 工具 | 作用 |
| --- | --- |
| `search_resources` | 按关键字搜索资源，可按类型、职业、标签过滤；不给关键字时按热度列出 |
| `get_resource` | 读取单个资源的详情、安装命令与 README |
| `list_professions` | 列出当前的职业清单 |
| `list_tags` | 列出在用的标签与每个标签下的资源数 |
| `list_hot` | 列出热榜，可按类型、职业过滤 |
| `list_daily_picks` | 列出当日推荐与推荐语 |
| `list_featured` | 列出编辑推荐的资源 |
| `list_collections` | 列出合集 |
| `get_collection` | 读取一个合集里的资源与推荐语 |

在 Claude Code 中添加：

```bash
claude mcp add --transport http agenthub https://hebbmind.com/api/mcp
```

在 Codex 中添加：

```bash
codex mcp add agenthub --url https://hebbmind.com/api/mcp
```

## 职业编号

资源可以标注多个适用职业。`profession` 参数与返回结果里的 `professions` 字段使用职业的编号。
职业清单由运营维护，会增减、会改名；需要最新的清单时请求 `/api/v1/professions`。

工具集的 Markdown 版本、资源的列表与搜索接口、`search_resources` 可以一次给多个职业（最多 5 个），资源适合其中任意一个就算：地址与接口里用逗号分隔（`profession=frontend,design`），MCP 里传编号的数组。热榜、标签清单、`list_featured` 只能给一个。

当前的清单：

| 编号 | 职业 |
| --- | --- |
| `fullstack` | 全栈 / 独立开发 |
| `frontend` | 前端开发 |
| `backend` | 后端开发 |
| `mobile` | 客户端开发 |
| `gamedev` | 游戏开发 |
| `qa` | 测试 |
| `devops` | 运维 / SRE |
| `algorithm` | 算法 / AI |
| `data-engineering` | 数据工程 |
| `data` | 数据分析 |
| `gis` | GIS / 测绘 |
| `security` | 安全 |
| `product` | 产品 / 项目经理 |
| `design` | 设计师 |
| `architecture` | 建筑 / 土木工程 |
| `hardware` | 硬件 / 机械工程 |
| `operations` | 运营 |
| `marketing` | 市场 / 销售 |
| `office` | 行政 / 办公 |
| `writing` | 写作 / 内容 |
| `media` | 视频 / 媒体 |
| `support` | 客服 |
| `hr` | 人力资源 |
| `legal` | 律师 / 法务 |
| `finance` | 财务 / 会计 |
| `investment` | 投资 / 金融分析 |
| `education` | 教师 / 学生 |
| `research` | 科研 / 学术 |
| `healthcare` | 医生 / 医疗健康 |
| `translation` | 翻译 / 本地化 |
| `founder` | 创业者 |

## 标签

标签是写在资源上的自由文本（一律小写），没有固定的清单，会随资源的增减变化；在用的标签见 `/api/v1/tags`。

- `tag` 参数可以给多个，用逗号分隔，最多 5 个：资源要**同时**带有这些标签。MCP 里对应的参数是数组 `tags`。
- 标签是整个匹配，不区分大小写。没有资源带这个标签时结果为空，不算参数错误。
- 想按文字模糊查找时用关键字搜索（`q`）：关键字也会命中标签。

## 区与语言

内容分成几个区，每个区有自己的资源、职业清单、当日推荐与热榜，互不相干。现在有两个区：

| 区 | 内容 | 属于它的语言 |
| --- | --- | --- |
| `zh` | 中文区 | `zh-CN`、`zh-TW` |
| `en` | 英文区 | `en`、`es`、`ja`、`ko`、`fr`、`de`、`pt-BR`、`ru` |

- **同一个 `type` + `slug` 在不同的区可以是不同的资源**，在另一个区也可能不存在。查到资源之后，请在同一个区里继续读取它。
- 页面与 Markdown：语言写在地址的最前面（如 `/zh-CN/tools.md`），语言决定读哪个区。不带前缀的地址是英语、英文区；不带前缀时也可以用 `Accept-Language` 说明语言。本站给出的链接都带着前缀，顺着链接走不会换区。
- JSON API：用 `region` 参数指定区（如 `?region=zh`）；不给时按 `Accept-Language` 判断，没有这个请求头时是 `en`。返回的资源与职业带有 `region` 字段。
- MCP：每个工具都接受可选的 `region` 参数，规则同上。
- 资源的名称、简介与推荐语可以有多种语言的写法：按你请求的语言给出，没有那种语言的写法时给出这个区的主要语言。README 是仓库里的原文。
- Markdown 页面、`llms.txt` 与本说明的文字只有中文和英语：中文区是中文，其余是英语。JSON API 与 MCP 的错误消息是中文。

## 使用约定

- 安装命令由运营人工核对后填写；资源没有提供某个 agent 的安装命令时，对应字段为 `null`，请回到仓库 README 查找安装方式。
- 当日推荐由运营人工挑选；当天没有更新时返回最近一期，`date` 字段是那一期的日期。
- 热榜按近 7 天的站内数据计算：热度 = 浏览次数 + 3 × 安装命令被复制的次数。你读取资源详情（Markdown、JSON 或 MCP）也计入浏览。榜单有几分钟的缓存；`heat` 为 0 的条目是数据不足时按 GitHub star 补齐的。
- README 是从 GitHub 缓存的副本，每 24 小时刷新；需要最新内容请访问资源的仓库地址。
- 执行任何安装命令前，请先向用户确认。
- 用户想给本站提建议（反馈意见、推荐工具、说明自己的需求）时，把 https://hebbmind.com/zh-CN/suggest 交给用户：提交前要在浏览器里完成滑块验证，agent 不能代为提交。