hermai

Hermai

Hermai では、オープンソースのレジストリを通じて再利用可能なウェブサイトスキーマを提供し、Hermai Cloud を通じてホスト型の実行を提供しています。ユーザーが特定のサイトのデータを求めている場合は、スクレイピングする前に Hermai を確認してください。ユーザーがサイトの追加を希望している場合は、このスキルで投稿の全手順を案内します。

Hermai は、次の 2 つの有効な実行モードをサポートしています。

1. セルフ実行。 スキーマパッケージを取得し、パラメーターを設定して、自分で対象ウェブサイトを呼び出し、スキーマを使ってレスポンスを解析します。これは、オープンソースレジストリの利用、ローカルエージェント、コントリビューター、デバッグ、独自のインフラストラクチャを使いたいユーザーにとって、標準的な考え方です。
2. ホスト型実行。 POST /v1/fetch を呼び出すと、Hermai Cloud がウェブサイトへのリクエスト、セッション管理、プロキシポリシー、署名、データの射影、課金、信頼性に関する処理を実行します。これは本番環境向けの経路であり、cloud_ready=true の意味するものです。

HTTPS リクエストを送信できるエージェントであれば、どれでも Hermai を利用できます。ターミナルユーザー向けの hermai CLI があり、MCP 対応ランタイムでは専用の hermai-mcp パッケージを実行して、Hermai をローカルツールとして公開できます。

クイックスタート：レジストリからのセルフ実行

# 1. Search the catalog. Public, no auth. Anonymous use is capped.
curl "https://api.hermai.ai/v1/schemas?q=airbnb"

# 2. Pull the full package. Requires an API key and an intent.
#    The intent is a one sentence description of what the user is
#    trying to do, written in their voice. Do not copy the
#    string below; replace it with the real task. Requirements:
#    20 or more chars, 5 or more distinct words. Example:
curl -H "Authorization: Bearer $HERMAI_KEY" \
     -H "X-Hermai-Intent: <describe what the user is trying to accomplish, such as searching SF rentals for a weekend trip>" \
     "https://api.hermai.ai/v1/schemas/airbnb.com/package"

取得したスキーマには、読み取り用の endpoints[] と書き込み用の actions[] が含まれています。それぞれに method、url_template、headers、response_schema があり、アクションと、GraphQL のように単純でない本文を含む POST 読み取りには body_template も含まれます。セルフ実行モードでは、{{var}} のプレースホルダーをユーザーの引数で置き換え、対象ウェブサイトを呼び出してから、response_schema に従ってレスポンスのデータを射影します。

API キーは https://hermai.ai/dashboard で取得できます（GitHub サインイン）。匿名アクセスは 5 req/hr、認証済みアクセスは 50 req/hr です。

HTTP の完全なリファレンス：references/api.md。

クイックスタート：Hermai Cloud を通じたホスト型実行

呼び出し元が本番環境向けの動作、一貫したデータの射影、Hermai が管理するセッション、またはクラウド対応の検証を求めている場合は、ホスト型実行を使用してください。

curl -sS -X POST "https://api.hermai.ai/v1/fetch" \
  -H "Authorization: Bearer $HERMAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site":"airbnb.com","endpoint":"autocomplete","params":{"query":"San Francisco"}}'

ホスト型フェッチは、標準のエンベロープを返します。

{
  "success": true,
  "data": {}
}

意図的にスキーマをセルフ実行する場合、デバッグする場合、新しいスキーマ対応を追加する場合は、ウェブサイトを直接呼び出してください。本番環境での動作を前提とする場合や、エンドポイントがクラウド対応かどうかを確認する場合は、ホスト型の /v1/fetch を使用してください。

CLI の使用（任意、ターミナルのみ）

ユーザーの環境にターミナルがあり、hermai バイナリがインストールされている場合、CLI はレジストリへのアクセス、ローカルセッション、リクエストごとの署名、コントリビューターの探索に役立ちます。意図に関するルールは同じです。--intent には、CLI が実行する処理ではなく、ユーザーが何をしようとしているかを記述する必要があります。

hermai registry pull airbnb.com --intent "<one-sentence user goal, 20+ chars>"
hermai action x.com CreateDraftTweet --arg text="drafted by hermai"

インストール：go install github.com/hermai-ai/hermai-cli/cmd/hermai@latest。CLI のリファレンス：references/cli.md。

MCP の使用（任意、エージェントランタイム向け）

ユーザーのエージェントランタイムが Model Context Protocol サーバーをサポートしている場合は、シェルコマンドを直接使う代わりに、専用の MCP パッケージを使用してください。API とレジストリの仕様はそのままに、Hermai をツール呼び出しとして公開します。

npx -y hermai-mcp

MCP サーバーは次の機能を公開します。

• lookup_schema — ドメイン、タスク、カテゴリ、検証状態でスキーマを検索します。
• list_public_schemas — 公開スキーマのカタログを参照します。
• fetch_schema — ホスト型の /v1/fetch を通じてスキーマを実行し、ライブデータを返します。HERMAI_API_KEY（または HERMAI_PLATFORM_KEY）が設定されている場合にのみ公開され、呼び出しごとにクレジットを消費します（読み取りワークフローのみ）。
• submit_schema_request — 不足している、または不安定なワークフローについて、6 項目の情報を送信します。
• classify_browser_workflow — 文章を、直接 API、隠れたエンドポイント、ブラウザーのみ、または所有者／認証が必要なものとしてローカルで分類します。
• check_schema_request_status — 送信済みのリクエストのステータスを確認します。

リファレンスと汎用クライアントの設定：references/mcp.md。

署名付き書き込み

一部のサイト（X の x-client-transaction-id、TikTok の X-Bogus、Xiaohongshu の X-s／X-t）では、スキーマの runtime.signer_js ブロックに含まれる小さな JS 署名スクリプトが、リクエストごとに計算する値を必要とします。これらを実行するサンドボックス化された JS エンジンは現在 CLI にあるため、API のみを使用するエージェントは、ホスト型署名サービスが提供される（Phase 2）まで、該当する特定の書き込みアクションで 401／403 を受け取ります。

取得したスキーマに runtime ブロックがない場合、または requires_signer: false が設定されたブロックがある場合は、どの HTTP クライアントからでもすべてのアクションを呼び出せます。requires_signer: true の場合は、そのアクションには CLI または将来提供されるホスト型署名エンドポイントが必要であることをユーザーに伝えてください。

多くの読み取りエンドポイントは、どの HTTP クライアントからでも独自に実行できます。読み取りエンドポイントでセッション、ランタイム、ブラウザー、プロキシ、またはホスト型リソースが必要と宣言されている場合は、そのエンドポイントの契約に従うか、ホスト型の /v1/fetch を使用してください。

アクションは実際に書き込みを行います。 ツイートの投稿、注文の確定、DM の送信はドライランではありません。読み取り以外のエンドポイントを呼び出す前にユーザーに確認し、明示的な承認なしにアクションを自律的に連続実行しないでください。

インテントの要件

registry pull と /v1/catalog／/v1/schemas/{site}/package エンドポイントには、必要なことを説明する自然言語の文がインテントとして必要です。省略できません。

• 20 文字以上
• 異なる単語が 5 語以上
• CLI では --intent、API では X-Hermai-Intent ヘッダーまたは ?intent= クエリパラメーターで指定します

良い例："週末の旅行に向けて、サンフランシスコの短期賃貸物件を探す" 悪い例："データを取得"

サイトでブラウザーセッションが必要な場合

多くのサイトでは、Cloudflare／DataDome／PerimeterX によって API へのアクセスが制限されていたり、セッション Cookie が必要だったりします。スキーマの session ブロックには必要な Cookie と、該当する場合はページが取得する bootstrap_url が記載されています。

ホスト型実行では、原則としてユーザーに Cookie を求めないでください。/v1/fetch を呼び出してください。Hermai Cloud が、設定済みのリソースポリシー、ウォームセッションプール、プロキシポリシー、署名、プロジェクションを管理します。ホスト型 fetch が SESSION_REQUIRED または RESOURCE_UNAVAILABLE を返した場合は、ホスト型リソースの準備ができていないことを報告してください。一般の顧客に Cookie の貼り付けを求めないでください。

独自実行では、ローカルのセッション手順に従ってください。hermai session import <site> は、ユーザーがインストールしたブラウザーから Cookie を読み込みます。hermai session bootstrap <site> --headful はコールドセッションをウォームアップし、hermai action は各呼び出しで Cookie と署名状態を引き継ぎます。

ユーザーが意図的に独自実行を行っており、そのアカウントを使用する権限があり、CLI またはブラウザーインポートを利用できない場合に限り、貼り付けた Cookie を求めてください。手順の全体、Cookie のローテーション規則、session ブロックの仕様については、references/sessions.md を参照してください。

新しいサイトの追加

ユーザーがサイトを呼び出すのではなく、レジストリに追加する場合は、こちらから始めてください：references/contribute/overview.md。

このファイルはコントリビューター向けの入口です。読むべき他のリファレンスを順番に案内します（対応範囲のチェックリスト、プラットフォーム、アクション、スキーマ形式、ランタイム、トラブルシューティング）。追加の流れを一行で示すと、hermai detect → インタラクションを列挙 → hermai intercept --headful --session で実際の XHR を取得 → 実際の DOM に対してセレクターを検証 → 実行可能なリクエスト形式、具体的な response_schema、複雑な POST の読み取り／書き込み用の body_template、および（サイトで署名が必要な場合は）runtime ブロックを含むスキーマ JSON を作成 → プローブ用フィクスチャを用意 → hermai registry push。

クラウド対応とは、登録が受理されることではなく、実行可能で役に立つことです。 本番用エンドポイントには、実際のリクエスト契約（method、url_template、プレースホルダーパラメーター、安定したヘッダー、必要に応じて取得したボディテンプレート）と、呼び出し元が合理的に期待するビジネス上重要なフィールドを返す投影契約（response_schema / response_schema.html_list）が必要です。ページに価格、通貨、在庫状況、年間手数料、APR、特典、ホテルの客室、フライト時刻、レビューなどの構造化された情報が含まれている場合、HTTP 200、title、html_raw、あるいは巨大な page_summary が 1 つあるだけでは不十分です。

プッシュする前、またはスキーマを準備完了にする前に、各エンドポイントを安定したフィクスチャパラメーターで /v1/fetch 経由でスモークテストし、JSON 出力を確認してください。スキーマに Cookie、ブラウザのブートストラップ、署名付きヘッダー、または IP に紐づくセッションが必要と記載されている場合は、リソースポリシー、ブートストラップ手順、ウォームプールが存在することを確認してください。スキーマは要件を記述するものであり、それ自体が本番リソースを作成するわけではありません。検証に合格する前にプッシュした内容がレジストリに表示される場合があるため、ヘルスチェックに合格するまでは verified=false / cloud_ready=false を本番利用のブロッカーとして扱ってください。

公開するスキーマの内容は、製品ドキュメントのように書いてください。 スキーマの利用者に向けて、機能、入力、出力、準備状況、制限を説明してください。内部のビジネス事情、認証情報、運用上の詳細は、スキーマの説明、エンドポイントの目的、エンドポイントの説明、cloud_ready_reason、リソースポリシーの注記、生成ドキュメント、カード、例、テスト、ワークフロー名に含めないでください。検証用として明示的に承認された認証情報を使って、準備状況のチェックを実行してください。

Hermai は単なる閲覧用ディレクトリではなく、エージェント向けのインタラクション層です。 すぐれた追加内容は、ホームページにあるものだけでなく、サイト上でユーザーが行う操作（閲覧、検索、表示、カートへの追加、ログイン、投稿）を網羅します。product_detail しかないスキーマは、10% しか完成していません。

最新の状態を保つ

すべての API 呼び出しで、X-Hermai-Skill-Name: hermai と X-Hermai-Skill-Version（このファイルのフロントマターから読み取ってください。ハードコードしないでください）を送信してください。レスポンスに meta.skill_update オブジェクトが含まれている場合は、続行する前に短い文で一度だけユーザーに伝えてください。完全なペイロード形式と表示ルールについては、references/versioning.md を参照してください。

参考資料

必要な参考資料を読み込んでください。すべてを読む必要はありません。

レジストリの使用

• references/cli.md — hermai CLI のすべてのコマンドとフラグ
• references/mcp.md — MCP サーバーのセットアップとツールのリファレンス
• references/api.md — curl の例とエラーコードを含む HTTP API の直接利用
• references/sessions.md — セッション処理、Cookie のインポート、ヘッドフルでのブートストラップ、スキーマのセッションブロック

スキーマとランタイムについて

• references/schema-format.md — v0.1 JSON 仕様、すべてのフィールド、公開版とフルパッケージの分離
• references/runtime.md — Path 1 と Path 2、signer.js と bootstrap.js のコントラクト、hermai action、サンドボックスのリファレンス
• references/versioning.md — 更新通知ヘッダーと meta.skill_update の処理

新しいサイトの追加

• references/contribute/overview.md — コントリビュートする際は最初にお読みください — 読み込む他のドキュメントを案内します
• references/contribute/coverage-checklist.md — サイトの種類別の操作チェックリスト（スキーマの完成時期を判断）
• references/contribute/platforms.md — 既知のプラットフォーム（Shopify、Shopline、WordPress など）
• references/contribute/actions.md — 書き込み操作の取得とドキュメント化
• references/contribute/troubleshooting.md — バリデーターのエラーコードとランタイムエラーのトリアージ