写给大模型、智能体，以及负责接入的人

Hawkerline 智能体接口

Hawkerline 是一套 AI 智能体可以直接操作的餐饮点餐、厨房看板、菜单与收银系统，源码公开，面向新加坡餐饮商户，运行在一个 Cloudflare Worker 和一个 D1 数据库上。本页说明 AI 智能体如何接入一家 Hawkerline 店铺。

四种接入方式

接口	地址	说明
MCP 服务	`/mcp`	Model Context Protocol，Streamable HTTP 传输，密钥（bearer）鉴权。响应为 POST 上的 JSON（不使用 server-sent events）。支持协议版本 2025-11-25、2025-06-18、2025-03-26。
REST API	`POST /api/agent/v1/tools/<tool>`	通过 HTTP 提供同样的工具，适用于任何能发 HTTP 请求的智能体、工作流工具或脚本。
OpenAPI 文档	`/api/agent/v1/openapi.json`	OpenAPI 3.1 描述，供能导入 OpenAPI 的工具调用框架使用。
llms.txt	`/llms.txt`	每个部署都会提供，告诉大模型这家店提供什么、如何操作。

兼容性。任何能通过 Streamable HTTP 发送 Authorization: Bearer 请求头的 MCP 客户端都可以使用，例如 Claude Code。系统未实现 OAuth，因此只支持 OAuth 的连接器无法直接接入；这类智能体可改用 REST API。

智能体密钥与权限

店主在 /admin 的 AI 接入页面创建和吊销智能体密钥。密钥形如 hlk_ 加 40 位十六进制字符，只显示一次，系统只保存其哈希。吊销后智能体立即失去访问权限。每个密钥每分钟最多调用 120 次。

权限	允许
`menu:read`	读取商品、分类与发布状态；预览草稿
`menu:write`	创建和编辑草稿中的商品、图片、显示顺序与分类
`menu:publish`	把已预览的草稿发布给顾客，可立即或定时发布
`orders:read`	读取订单与厨房看板
`orders:write`	推进订单的厨房流程（新单、制作中、待取、完成）
`store:write`	暂停或恢复在线下单
`reports:read`	读取销售汇总

每个智能体只授予它需要的权限。

工具与对应权限

每个工具都同时提供 MCP 与 REST 两种调用方式。

工具	权限	作用
`get_store_overview`	`menu:read`	起点：店名、是否接单、分类、商品数量、当前线上版本与草稿版本号
`list_categories`	`menu:read`	菜单分类（键、中文名称、英文名称）及各分类下的草稿商品数
`list_products`	`menu:read`	全部草稿商品，含新元价格、分类、组成项与图片状态
`preview_menu`	`menu:read`	对比草稿与线上菜单，并给出 10 分钟有效的预览链接；返回 draft_checksum 与 live_release_id
`set_categories`	`menu:write`	整体替换分类列表，顺序即显示顺序
`upsert_product`	`menu:write`	创建商品，或按 sku 只更新传入的字段
`bulk_upsert_products`	`menu:write`	一次调用创建或更新最多 100 个商品，例如从照片或 PDF 读出的整份菜单
`set_product_availability`	`menu:write`	在草稿中把商品上架或下架
`set_product_image`	`menu:write`	用 https 链接或 base64 数据设置商品图（PNG、JPEG 或 WebP，不超过 640 KB）
`reorder_products`	`menu:write`	按传入的 sku 顺序设置显示顺序
`publish_menu`	`menu:publish`	只发布已预览的草稿；需要 preview_menu 返回的 draft_checksum 与 live_release_id；可用 effective_at_sgt 定时发布
`list_orders`	`orders:read`	近期订单；除非 include_contact 为 true，否则电话号码会被遮盖
`get_kitchen_board`	`orders:read`	今日已付款且未完成的订单，套餐组成项已展开
`advance_order`	`orders:write`	把已付款订单推进到下一个厨房状态，或用 "to" 指定更靠后的状态
`set_store_open`	`store:write`	立即暂停或恢复在线新订单
`get_sales_summary`	`reports:read`	指定新加坡时间日期范围内的已付款订单、营收（新元）、GST、服务费与热销商品

菜单修改先进入草稿，顾客只能看到已发布的版本。批量调用一次最多 100 个商品。

MCP 示例流程：菜单照片，生成商品，预览，发布

接入。在 MCP 客户端中添加你的店铺，并使用带有所需权限的智能体密钥。
菜单照片。把菜单的照片或 PDF 交给智能体。
生成商品。智能体按需调用 set_categories，再调用 bulk_upsert_products，单品排在引用它们的套餐之前；可用 set_product_image 添加图片。
预览。preview_menu 对比草稿与线上菜单，返回 draft_checksum、live_release_id 和 10 分钟有效的预览链接。
发布。publish_menu 需要传入这个 draft_checksum 与 live_release_id。预览之后若有任何变动，就不会发布，智能体必须重新预览。
运营。如果密钥带有相应权限，同一个智能体还可以使用 list_orders、get_kitchen_board、advance_order、set_store_open 与 get_sales_summary。

接入客户端

把 your-store.example 换成你店铺的域名，把 hlk_… 换成在 /admin 创建的密钥。

Claude Code

claude mcp add --transport http my-store https://your-store.example/mcp \
  --header "Authorization: Bearer hlk_…"

使用 JSON 配置的 MCP 客户端

不同客户端的字段名称不同；客户端必须能向远程 HTTP 服务发送 Authorization 请求头。

{
  "mcpServers": {
    "my-store": {
      "type": "http",
      "url": "https://your-store.example/mcp",
      "headers": { "Authorization": "Bearer hlk_…" }
    }
  }
}

REST

curl -s https://your-store.example/api/agent/v1/tools/list_products \
  -H "Authorization: Bearer hlk_…" -H "content-type: application/json" \
  -d '{"only_on_sale":true}'

响应为 {"ok":true,"result":{…}} 或 {"ok":false,"error":"…","code":"…"}，并附 HTTP 状态码：400 参数无效，401 密钥无效，403 缺少权限，404，409 冲突，429 超出频率限制。

安全机制

预览校验码。智能体只能发布它预览过的那一版草稿。
权限。每个密钥只能做它的权限允许的事。智能体密钥、支付、会员、退款与店铺设置仍只对店主开放。
审计日志。智能体的每次调用都写入审计日志，店主可在 /admin 的 AI 接入页面查看。
吊销。店主可立即吊销密钥。
隐私。订单数据中的电话号码默认被遮盖，除非智能体用 include_contact 明确要求联系方式。
过期修改保护。并发修改由版本号检查保护，过期的修改会被拒绝，而不是覆盖。
回滚。回滚会用旧版本生成一个新的发布版本。

更多说明：GitHub 上的智能体接入指南与工具参考。返回 Hawkerline 概览。