> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hermai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermai 如何运作

> 贡献者发现,agent 使用。两分钟掌握心智模型。

## 分工

Hermai 有三个组成部分:

1. **CLI**([hermai-cli](https://github.com/hermai-ai/hermai-cli),开源)- 在你的机器上运行。贡献者用它检视网站、编写描述端点的 schema,然后把 schema 推送到 registry。

2. **Registry**(`api.hermai.ai`)- 存储并提供贡献者推送的 schema。agent 在运行时查询它,获取 registry 中任何域名的端点名称、参数、URL template 和响应形状。

3. **Hosted fetch**(`POST /v1/fetch`)- 通过 Hermai 执行已注册端点并返回结果。当你希望 Hermai 运行请求,而不是自行执行 schema 时使用。

```
Contributor                        Platform                         Agent
    │                                  │                               │
    │  discovery toolkit (local)       │                               │
    │  hermai registry push            │                               │
    │──────────────────────────────>   │                               │
    │                                  │   GET /v1/catalog/{domain}    │
    │                                  │ <────────────────────────────│
    │                                  │   { endpoints, actions }      │
    │                                  │ ────────────────────────────> │
    │                                  │                               │
    │                                  │   POST /v1/fetch              │
    │                                  │ <────────────────────────────│
    │                                  │   structured result           │
    │                                  │ ────────────────────────────> │
```

## CLI 做什么

CLI 提供一组确定性的工具组 - 每个子命令做一件事,并输出可供下一步处理的 JSON:

* **`hermai detect`** - 分类网站平台(Shopify、WordPress、Next.js 等)并检测 anti-bot 系统。
* **`hermai wellknown`** - 探测 `robots.txt`、sitemap、RSS feed 与 GraphQL 端点。
* **`hermai probe --body | hermai extract`** - 从页面提取嵌入数据。可识别 13 种 SSR/hydration 模式(`__NEXT_DATA__`、`ytInitialData`、`__APOLLO_STATE__`、`SIGI_STATE` 等)。
* **`hermai intercept`** - 启动浏览器并捕获真实 XHR 流量,适用于动态功能(搜索、购物车、筛选)。
* **`hermai introspect`** - 获取 GraphQL schema。
* **`hermai session bootstrap`** - 为 anti-bot 网站预热浏览器 session。

贡献者根据发现结果编写 schema JSON 文件,并通过 `hermai registry push` 推送。不需要 LLM key 或托管服务。

## Platform 做什么

Platform 同时提供 lookup 和 hosted execution:

* **`GET /v1/catalog/{domain}`** - 返回该域名所有端点与 action。这是主要的 agent 接口,需要 [intent](/zh-Hans/concepts/catalog#intent) 说明用途。
* **`GET /v1/schemas`** - 浏览并搜索整个 registry。
* **`POST /v1/fetch`** - 通过 Hermai 执行已注册端点。需要 API key。
* **`POST /v1/schemas`** - 推送新 schema。将按照 [intent 分类](/zh-Hans/concepts/catalog#intent-taxonomy) 进行校验并立即发布。

你仍然可以只把 Hermai 当 registry 使用:拉取 schema package,然后从自己的基础设施执行上游请求。Hosted fetch 是当你希望 Hermai 运行已注册端点时使用的托管路径。

## 为什么要这样分工?

发现很贵(浏览器 + LLM + 时间)。查询很便宜(数据库读取)。分开之后:

* **贡献者**只需在自己机器上,本地付一次发现成本
* **之后的每个 agent**都能免费获得即时结构化数据
* **Registry**把发现和运行时执行分开
* **不锁死平台** - CLI 是开源(AGPL-3.0)且可离线运行