Schemas - Hermai

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 文件。以下是最小範例:

{
  "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 分類(例如 `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 工具組探索

# 安裝 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 代勞

npx skills add hermai-ai/hermai-skills

Claude Code、Codex、Cursor 以及其他支援 Vercel skills CLI 的 agent 會載入 hermai-contribute skill,並能自主執行探索與推送流程。詳見 hermai-ai/hermai-skills。

選項 3:手動撰寫並推送

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

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 與網站:

{
  "success": true,
  "data": {
    "version_hash": "9a0a27c4085fc661...",
    "site": "allbirds.com",
    "created": true
  }
}

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

{
  "success": false,
  "error": {
    "code": "UNKNOWN_CATEGORY",
    "message": "intent_category does not exist in current taxonomy"
  }
}

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

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

驗證規則

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

規則	錯誤碼	說明
JSON 合法	`INVALID_JSON`	body 必須是可解析的 JSON
含 `site`	`MISSING_FIELD`	必填欄位
含 `intent_category`	`MISSING_FIELD`	必填欄位
分類存在	`UNKNOWN_CATEGORY`	`intent_category` 必須對應分類樹中的 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 在任何深度都不可包含憑證或營運機密欄位。詳見下方禁用欄位列表。
排除清單	`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

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

內容定址

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

認證徽章

schema 預設為社群貢獻且未認證。Hermai 團隊會審核 schema 並授予認證徽章給達到品質標準的項目。 agent 可以只篩選已認證的 schema:

# 只取已認證
curl "https://api.hermai.ai/v1/schemas?verified=true"

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

# 包含認證與未認證
curl "https://api.hermai.ai/v1/schemas"

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

Schema 版本

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

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 設定
變數模式與預設值

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

# 公開卡片(無需驗證)
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 的地方使用。

​schema 包含什麼

​Schema 格式

​必填欄位

​選填欄位

​能力徽章

​貢獻 schema

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

​選項 2:讓你的 agent 代勞

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

​驗證規則

​禁用欄位

​內容定址

​認證徽章

​Schema 版本

​公開卡片 vs 完整套件

​貢獻的 credits

schema 包含什麼

Schema 格式

必填欄位

選填欄位

能力徽章

貢獻 schema

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

選項 2:讓你的 agent 代勞

選項 3:手動撰寫並推送

驗證規則

禁用欄位

內容定址

認證徽章

Schema 版本

公開卡片 vs 完整套件

貢獻的 credits