hermai

Hermai

Hermai 通过开源注册表提供可复用的网站架构，并通过 Hermai Cloud 提供托管执行服务。当用户请求获取某个特定网站的数据时，请先检查 Hermai，再进行抓取。当用户想添加网站时，本技能会引导其完成完整的贡献流程。

Hermai 支持两种有效的执行模式：

1. 自行执行。 拉取架构包，填写其 params，自行调用目标网站，并使用架构解析响应。这是使用开源注册表、本地 Agent、贡献者、调试以及希望使用自有基础设施的用户默认采用的模式。
2. 托管执行。 调用 POST /v1/fetch，由 Hermai Cloud 处理网站请求、会话、代理策略、签名、投影、计费和可靠性工作。这是生产环境使用的方式，也是 cloud_ready=true 的含义。

任何能够发出 HTTPS 请求的 Agent 都可以使用 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；对于 action 以及任何包含 GraphQL 等非简单请求体的 POST 读取请求，还包含 body_template。在自行执行模式下，用用户参数填充 {{var}} 占位符，调用目标网站，然后根据 response_schema 投影响应。

API 密钥可在 https://hermai.ai/dashboard 获取（使用 GitHub 登录）。匿名访问每小时可请求 5 次；认证后每小时可请求 50 次。

完整 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"}}'

托管 fetch 会返回标准信封：

{
  "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（可选，适用于 Agent 运行时）

如果用户的 Agent 运行时支持 Model Context Protocol 服务端，请优先使用专用 MCP 软件包，而不是原始 shell 命令。它会将 Hermai 暴露为工具调用，同时保持相同的 API 和注册表语义：

npx -y hermai-mcp

MCP 服务提供：

• lookup_schema — 按域名、任务、类别或验证状态搜索架构。
• list_public_schemas — 浏览公开架构目录。
• fetch_schema — 通过托管 /v1/fetch 执行架构并返回实时数据。仅当设置了 HERMAI_API_KEY（或 HERMAI_PLATFORM_KEY）时才会提供，并且每次调用都会消耗额度（仅限读取工作流）。
• submit_schema_request — 为缺失或不稳定的工作流提交六字段需求表。
• classify_browser_workflow — 在本地将自然语言分类为直接 API、隐藏端点、仅限浏览器或需要所有者/认证。
• check_schema_request_status — 检查已提交请求的状态。

参考文档和通用客户端配置：references/mcp.md。

签名写入

少数网站（X 的 x-client-transaction-id、TikTok 的 X-Bogus、小红书的 X-s/X-t）要求每个请求都使用一个由小型 JS 签名器计算出的值，该签名器包含在架构的 runtime.signer_js 块中。目前，执行这些签名器的沙箱 JS 引擎位于 CLI 中，因此在托管签名服务上线（第 2 阶段）之前，仅使用 API 的 Agent 在执行这些特定写入操作时会收到 401/403 错误。

如果拉取的架构没有 runtime 块，或者卡片中的 requires_signer: false，那么任何 HTTP 客户端都可以调用所有操作。如果 requires_signer: true，请告知用户该操作需要 CLI 或未来的托管签名端点。

许多读取端点可由任何 HTTP 客户端自行执行。如果读取端点声明了 session、runtime、browser、proxy 或 hosted 资源要求，请遵循该端点的约定，或使用托管 /v1/fetch。

操作会执行真实写入。 发布推文、下单或发送私信都不是试运行。调用任何非读取端点前，必须先向用户确认；未经明确批准，绝不能自主串联执行操作。

意图要求

registry pull 和 /v1/catalog / /v1/schemas/{site}/package 端点都要求提供意图，即说明你需要什么的自然语言句子。此项为必填。

• 至少 20 个字符
• 至少 5 个不同的词
• 通过 CLI 的 --intent 传入，或通过 API 的 X-Hermai-Intent 标头 / ?intent= 查询参数传入

正确示例："finding short-term rental listings in San Francisco for a weekend trip" 错误示例："get data"

网站需要浏览器会话时

许多网站会通过 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 验证选择器 → 编写架构 JSON，其中包含可执行的请求结构、具体的 response_schema、用于非简单 POST 读取／写入操作的 body_template，以及（如果站点需要签名）runtime 块 → 填充探测固定数据 → hermai registry push。

可用于云端意味着可运行且实用，而不只是通过接收。 生产端点必须具备真实的请求约定（method、url_template、占位符参数、稳定的标头，以及必要时捕获的请求正文模板）和投影约定（response_schema / response_schema.html_list），以返回调用方合理期望的关键业务字段。当页面包含价格、货币、库存情况、年费、APR、奖励、酒店房间、航班时间、评论等结构化信息时，仅有 HTTP 200、title、html_raw 或一个庞大的 page_summary 并不足够。

推送架构或将其标记为就绪前，请使用稳定的固定参数通过 /v1/fetch 对每个端点进行冒烟测试，并检查 JSON 输出。如果架构注明需要 Cookie、浏览器引导、签名标头或绑定 IP 的会话，请确认资源策略、引导步骤和预热池均已就绪；架构描述的是需求，本身不会创建生产资源。推送的内容可能会在验证通过前出现在注册表中，因此在健康检查通过前，应将 verified=false / cloud_ready=false 视为生产阻断项。

公开的架构内容应当像产品文档一样易于理解。 为架构使用者描述功能、输入、输出、就绪状态和限制。请勿在架构描述、端点用途、端点描述、cloud_ready_reason、资源策略备注、生成的文档、卡片、示例、测试和工作流名称中包含内部业务背景、凭据和运维细节。使用明确获准用于验证的凭据运行就绪检查。

Hermai 是面向 Agent 的交互层，而不只是一个读取目录。 优质贡献应覆盖用户在站点上的实际操作——浏览、搜索、查看、加入购物车、登录、发帖——而不只是首页内容。仅包含 product_detail 的架构只完成了 10%。

保持最新

每次 API 调用都要发送 X-Hermai-Skill-Name: hermai 和 X-Hermai-Skill-Version（从此文件的 frontmatter 中读取，切勿硬编码）。如果响应包含 meta.skill_update 对象，请先用简短句子告知用户一次，再继续操作。完整的负载结构和界面规则见：references/versioning.md。

参考文档

按需加载参考文档。无需全部阅读。

使用注册表

• references/cli.md — hermai CLI 的所有命令和标志
• references/mcp.md — MCP 服务设置和工具参考
• references/api.md — 直接 HTTP API，包含 curl 示例和错误代码
• references/sessions.md — 会话处理、Cookie 导入、有头启动、架构中的会话区块

了解架构和运行时

• references/schema-format.md — v0.1 JSON 规范、所有字段、公共版/完整包拆分
• references/runtime.md — 路径 1 与路径 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 — 验证器错误代码和运行时错误排查