> ## 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.

# Schemas

> 什麼是 schema、如何貢獻,以及認證徽章制度。

schema 是一份 JSON 文件,描述如何與一個網站對話。它列出網站提供的每個端點和 action - URL、HTTP method、必要 headers、參數、以及回應格式。一旦某個網站有了 schema,任何 agent 都能直接查詢並呼叫端點,不需要重新探索。

## schema 包含什麼

一個 Shopify 網站的 schema 可能包含:

| Endpoint           | Method | URL                       | 功能        |
| ------------------ | ------ | ------------------------- | --------- |
| `shopify_products` | GET    | `/products.json`          | 列出商品目錄    |
| `shopify_product`  | GET    | `/products/{handle}.json` | 取得單一商品    |
| `add_to_cart`      | POST   | `/cart/add.js`            | 將變體加入購物車  |
| `get_cart`         | GET    | `/cart.js`                | 取得目前購物車內容 |

每個端點都帶有參數、必要 headers(如 `Content-Type: application/json`)以及足夠讓 agent 構建有效 HTTP 請求的中介資料。

## Schema 格式

Schema 是 JSON 文件。以下是最小範例:

```json theme={null}
{
  "site": "allbirds.com",
  "intent_category": "commerce",
  "schema_format_version": "0.1",
  "name": "allbirds-products",
  "description": "Shopify-based product catalog and cart API for allbirds.com",
  "endpoints": [
    {
      "name": "shopify_products",
      "method": "GET",
      "url_template": "https://www.allbirds.com/products.json",
      "description": "Public product catalog from the Shopify AJAX API",
      "headers": {},
      "response_schema": {
        "type": "object",
        "fields": [
          { "name": "products", "type": "array" }
        ]
      }
    }
  ],
  "actions": [
    {
      "name": "add_to_cart",
      "method": "POST",
      "url_template": "https://www.allbirds.com/cart/add.js",
      "description": "Add a product variant to the shopping cart",
      "kind": "api_call",
      "transport": "api_call",
      "headers": { "Content-Type": "application/json" },
      "params": [
        { "name": "id", "in": "body", "type": "integer", "required": true, "description": "Product variant ID" },
        { "name": "quantity", "in": "body", "type": "integer", "required": true, "description": "Quantity to add" }
      ],
      "confidence": 0.98,
      "source": "shopify_ajax_api"
    }
  ]
}
```

### 必填欄位

| 欄位                      | 型別     | 說明                                                                                         |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------ |
| `site`                  | string | schema 涵蓋的網域(例如 `allbirds.com`),一律小寫。                                                      |
| `intent_category`       | string | 須對應 [intent 分類](/zh-Hant/concepts/catalog#intent-taxonomy)(例如 `commerce`、`travel`、`jobs`)。 |
| `schema_format_version` | string | 目前必須為 `"0.1"`。若省略則預設為 `"0.1"`。                                                             |

### 選填欄位

| 欄位                 | 型別      | 說明                                           |
| ------------------ | ------- | -------------------------------------------- |
| `name`             | string  | schema 的可讀名稱                                 |
| `description`      | string  | schema 的用途說明                                 |
| `version`          | number  | schema 版本號(僅供參考)                             |
| `endpoints`        | array   | 讀取類型的 API 端點(回傳資料的 GET 請求)                   |
| `actions`          | array   | 寫入或互動類型的 action(POST、購物車操作等)                 |
| `requires_stealth` | boolean | 網站是否需要 TLS 指紋偽裝以避開 bot 偵測                    |
| `session`          | object  | Session 啟動設定(在 API 呼叫前需要的 cookies 或 headers) |

### 能力徽章

registry 會把能力訊號以徽章形式呈現,讓 agent 知道請求需要什麼:

| 徽章             | 來源欄位                                     | 意義                                                                          |
| -------------- | ---------------------------------------- | --------------------------------------------------------------------------- |
| **需要瀏覽器**      | `requires_stealth: true`                 | 網站需要類 Chrome 的 TLS 指紋。agent 應使用 stealth HTTP client,或 CLI 的 `--stealth` 旗標。 |
| **需要 session** | 存在 `session` 物件                          | 網站在 API 呼叫前需要啟動 cookies 或 headers(例如 Cloudflare 保護網站的 clearance cookies)。   |
| **需要驗證**       | `headers` 含有 `Authorization` 或 `X-API-*` | 端點需要驗證 header。                                                              |

這些徽章會顯示在公開 schema 卡片上,讓 agent 在下載完整 schema 前就能判斷自己能否處理該網站。

## 貢獻 schema

任何有 API key 的人都可以推送 schema。共有三條路徑:

### 選項 1:使用 CLI 工具組探索

```bash theme={null}
# 安裝 CLI
go install github.com/hermai-ai/hermai-cli/cmd/hermai@latest

# 分類網站並探測標準路徑
hermai detect https://example.com
hermai wellknown example.com

# 從詳細頁面擷取內嵌資料 - 可辨識 13 種模式,
# 包含 __NEXT_DATA__、JSON-LD、ytInitialData、__APOLLO_STATE__ 等。
hermai probe --body https://example.com/products/123 | hermai extract

# 動態頁面(搜尋、購物車、篩選)需要捕獲真實 XHR
hermai intercept https://example.com/search?q=test

# 若發現 GraphQL 端點,可做 introspection
hermai introspect https://example.com/graphql

# 依照確認過的端點撰寫 schema.json,然後推送
hermai registry push schema.json
```

每個子指令都輸出 JSON,可直接交給下一步處理 - 不需要 LLM key。

### 選項 2:讓你的 agent 代勞

```bash theme={null}
npx skills add hermai-ai/hermai-skills
```

Claude Code、Codex、Cursor 以及其他支援 [Vercel skills CLI](https://github.com/vercel-labs/skills) 的 agent 會載入 `hermai-contribute` skill,並能自主執行探索與推送流程。詳見 [hermai-ai/hermai-skills](https://github.com/hermai-ai/hermai-skills)。

### 選項 3:手動撰寫並推送

若你已經知道網站的 API(從 DevTools、文件或測試),可以自己撰寫 schema JSON 並透過 API 推送:

```bash theme={null}
curl -X POST "https://api.hermai.ai/v1/schemas" \
     -H "Authorization: Bearer hm_sk_..." \
     -H "Content-Type: application/json" \
     -d '{
  "site": "allbirds.com",
  "intent_category": "commerce",
  "schema_format_version": "0.1",
  "name": "allbirds-shopify",
  "description": "Shopify AJAX API for allbirds.com - product catalog and cart",
  "endpoints": [
    {
      "name": "shopify_products",
      "method": "GET",
      "url_template": "https://www.allbirds.com/products.json",
      "description": "Public product catalog",
      "headers": {},
      "response_schema": {
        "type": "object",
        "fields": [
          { "name": "products", "type": "array" }
        ]
      }
    },
    {
      "name": "shopify_product",
      "method": "GET",
      "url_template": "https://www.allbirds.com/products/{handle}.json",
      "description": "Single product detail by handle",
      "variables": [
        { "name": "handle", "source": "path" }
      ]
    }
  ],
  "actions": [
    {
      "name": "add_to_cart",
      "method": "POST",
      "url_template": "https://www.allbirds.com/cart/add.js",
      "description": "Add a product variant to the shopping cart",
      "kind": "api_call",
      "transport": "api_call",
      "headers": { "Content-Type": "application/json" },
      "params": [
        { "name": "id", "in": "body", "type": "integer", "required": true, "description": "Product variant ID" },
        { "name": "quantity", "in": "body", "type": "integer", "required": true, "default": "1", "description": "Quantity to add" }
      ],
      "confidence": 0.98,
      "source": "manual"
    },
    {
      "name": "get_cart",
      "method": "GET",
      "url_template": "https://www.allbirds.com/cart.js",
      "description": "Get current cart contents",
      "kind": "api_call",
      "transport": "api_call",
      "headers": {},
      "confidence": 0.98,
      "source": "manual"
    },
    {
      "name": "update_cart",
      "method": "POST",
      "url_template": "https://www.allbirds.com/cart/update.js",
      "description": "Update item quantities by variant ID. Pass {variant_id: new_qty} for each line. Setting qty=0 removes the item.",
      "kind": "api_call",
      "transport": "api_call",
      "headers": { "Content-Type": "application/json" },
      "params": [
        { "name": "updates", "in": "body", "type": "object", "required": true, "description": "Map of variant ID to quantity, e.g. {\"41397031600208\": 2}" }
      ],
      "confidence": 0.98,
      "source": "manual"
    }
  ]
}'
```

推送成功會回傳版本 hash 與網站:

```json theme={null}
{
  "success": true,
  "data": {
    "version_hash": "9a0a27c4085fc661...",
    "site": "allbirds.com",
    "created": true
  }
}
```

若驗證失敗,會得到特定錯誤碼:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNKNOWN_CATEGORY",
    "message": "intent_category does not exist in current taxonomy"
  }
}
```

<Tip>
  **從最小開始。** 你不需要一次對應每個端點 - 即便只有一個有用的端點,也是合格的貢獻。其他貢獻者可以後續推送涵蓋更廣的新版本。
</Tip>

Schema 會立即上線 - 沒有審核隊列。

### 驗證規則

每次推送都會經過驗證。任一檢查失敗即拒絕,並回傳對應錯誤碼。

**結構檢查:**

| 規則                  | 錯誤碼                  | 說明                                                                                                           |
| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ |
| JSON 合法             | `INVALID_JSON`       | body 必須是可解析的 JSON                                                                                            |
| 含 `site`            | `MISSING_FIELD`      | 必填欄位                                                                                                         |
| 含 `intent_category` | `MISSING_FIELD`      | 必填欄位                                                                                                         |
| 分類存在                | `UNKNOWN_CATEGORY`   | `intent_category` 必須對應[分類樹](/zh-Hant/concepts/catalog#intent-taxonomy)中的 slug。呼叫 `GET /v1/categories` 可看有效值。 |
| 格式版本                | `UNSUPPORTED_FORMAT` | `schema_format_version` 必須為 `"0.1"`                                                                          |

**內容治理:**

| 規則   | 錯誤碼               | 說明                                                                                                                            |
| ---- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 禁用名稱 | `FORBIDDEN_NAME`  | schema 名稱不可描述繞過技術。被拒絕的模式:`bypass`、`circumvent`、`cf-clearance`、`anti-bot`、`rotate-ip`。命名應反映功能(例如 `shopify-products`),而非如何攻破防禦。 |
| 禁用欄位 | `FORBIDDEN_FIELD` | schema 在任何深度都不可包含憑證或營運機密欄位。詳見下方[禁用欄位列表](#forbidden-fields)。                                                                   |
| 排除清單 | `SITE_EXCLUDED`   | 部分網站要求從 registry 移除。對排除網站推送 schema 會被拒絕。                                                                                      |

### 禁用欄位

以下 JSON key 若在 schema 的任何深度出現都會被拒絕:

| 欄位                    | 為何禁用                                                 |
| --------------------- | ---------------------------------------------------- |
| `proxy_credentials`   | 實際 proxy 登入憑證 - 絕不可公開的機密                             |
| `residential_proxy`   | Proxy 基礎設施設定 - 屬於營運而非 schema 資料                      |
| `clearance_cookie_js` | 用於產生 clearance cookies 的 JavaScript - 軍備競賽式的實作細節     |
| `clearance_cookies`   | 短暫的 session cookies - 網站特定且有時效,對其他使用者無意義             |
| `bypass_method`       | 描述繞過技術 - 違反命名政策                                      |
| `stealth_script`      | 自訂的反偵測 JavaScript - 屬於營運而非 schema 資料                 |
| `tls_fingerprint`     | 特定的 TLS profile 識別 - 變動頻繁,由 CLI 執行時管理較合適,不應寫進 schema |

<Note>
  **能力訊號是被允許的。** 差別在於:告訴 agent 網站*需要什麼*的中介資料(例如 `requires_stealth: true`)是可以的;描述*如何*繞過防禦的營運機密(例如 `proxy_credentials: "user:pass@host"`)則不可。前者屬於 schema,後者屬於 CLI 執行環境。
</Note>

### 內容定址

每份 schema 都會被雜湊(以排序 key 的正規 JSON 產生 SHA-256)。hash 即是版本 ID。對同一個網站重複推送相同內容等同無動作 - registry 會辨識為重複。

## 認證徽章

schema 預設為社群貢獻且未認證。Hermai 團隊會審核 schema 並授予**認證徽章**給達到品質標準的項目。

agent 可以只篩選已認證的 schema:

```bash theme={null}
# 只取已認證
curl "https://api.hermai.ai/v1/schemas?verified=true"
```

或全部都取(預設行為):

```bash theme={null}
# 包含認證與未認證
curl "https://api.hermai.ai/v1/schemas"
```

每個 API key 都在 dashboard 有一個 **schema access 開關**,控制該 key 在 catalog 回應中是否包含未認證的 schema。

## Schema 版本

每次推送會產生新版本。registry 會為每個網站追蹤「最新」版本。查詢 catalog 時預設取得最新版。

可取得版本歷史:

```bash theme={null}
curl "https://api.hermai.ai/v1/schemas/allbirds.com/versions"
```

## 公開卡片 vs 完整套件

registry 對每份 schema 提供兩種檢視:

**公開卡片**(不需 API key)- 描述 schema *做什麼*的中介資料:

* Site、分類、名稱、說明
* 端點名稱、method、描述
* 變數名稱與來源(path/query/body)
* Query 參數 key 與是否必填
* 回應欄位名稱與型別(僅頂層)
* 能力徽章(需要瀏覽器、需要 session、需要驗證)

**完整套件**(需 API key + intent)- agent *執行*所需的一切:

* 完整 URL 模板
* Headers 值
* Body 模板
* Session 設定
* 變數模式與預設值

分流是刻意的:卡片回答「這有用嗎?」,套件回答「要怎麼執行?」

```bash theme={null}
# 公開卡片(無需驗證)
curl "https://api.hermai.ai/v1/schemas/allbirds.com"

# 完整套件(需驗證 + intent)
curl -H "Authorization: Bearer hm_sk_..." \
     -H "X-Hermai-Intent: downloading allbirds schema for a price comparison agent" \
     "https://api.hermai.ai/v1/schemas/allbirds.com/package"
```

## 貢獻的 credits

每貢獻一個網站可獲得 **+50 credits**。Credits 會顯示在 dashboard 中,並可在支援 hosted execution 的地方使用。