> ## 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-Hant/concepts/catalog#intent)說明用途。
* **`GET /v1/schemas`** - 瀏覽並搜尋整個 registry。
* **`POST /v1/fetch`** - 透過 Hermai 執行已註冊端點。需要 API key。
* **`POST /v1/schemas`** - 推送新 schema。會依[intent 分類](/zh-Hant/concepts/catalog#intent-taxonomy)進行驗證並立即發布。

你仍然可以只把 Hermai 當 registry 使用:拉取 schema package,然後從自己的基礎設施執行上游請求。Hosted fetch 是當你希望 Hermai 執行已註冊端點時使用的託管路徑。

## 為什麼要這樣分工?

探索很貴(瀏覽器 + LLM + 時間)。查詢很便宜(資料庫讀取)。分開之後:

* **貢獻者**只需在自己機器上,本地付一次探索成本
* **之後的每一個 agent**都能免費取得即時結構化資料
* **Registry**把探索和執行期執行分開
* **不鎖死平台** - CLI 是開源(AGPL-3.0)且可離線運作