MeatSpace

MeatSpace

面向 AI Agent 的人工参与服务。当 Agent 遇到主观、风险高或模棱两可的决策时，MeatSpace 会将其转交给人工处理，由人工从 2–4 个选项中选出一个，并返回结构化结果。

已上线：meatspace.run

功能介绍

Agent 提交标题、可选内容（文本、Markdown、HTML 或图片）以及 2–4 个带标签的选项。人工审核者会看到请求并选出一个选项，API 随后返回所选选项的 id 和 label。Agent 通过长轮询或 webhook 等待结果。

典型用例：

• 在执行具有破坏性或不可逆的操作（部署、删除、付款）之前设置审批关卡。
• 模型置信度低于阈值时，进行主观判断以打破平局。
• 需要审美判断的决策——文案选项、设计偏好、排名平局。
• Agent 用尽确定性检查方法时进行升级处理。

如果任务结果是确定的、可自动验证，或风险低且易于撤销，请勿使用。

三种集成方式

方式	端点	适用场景
REST API	POST /api/requests	任何 HTTP 客户端、自定义 Agent 框架、服务间调用。
MCP	POST /api/mcp（Streamable HTTP）	Claude、Claude Code、兼容 MCP 的客户端。
浏览器 SDK	/sdk/meatspace.js	在浏览器标签页中运行的 Agent。

三种方式都使用同一底层 API，并接受相同的 Bearer 令牌。

零配置自助流程

新 Agent 只需调用三次即可完成全部接入——无需注册页面、审批队列，也无需人工参与配置：

1. 使用 {"name": "your-agent", "email": "[email protected]"} 调用 POST /api/keys → 立即返回 API 密钥。每个电子邮件地址最多可创建 5 个密钥。
2. 携带 Bearer 令牌、标题和选项调用 POST /api/requests → 创建审核请求。
3. 调用 GET /api/requests/{id}/wait → 阻塞等待人工回复；如果超时，则返回 pending，并附带 review_url 和 poll_url。

MCP 也支持相同流程：initialize → tools/list → provision_api_key → ask_human。provision_api_key 和 get_service_status 工具无需身份验证，因此全新的 MCP 客户端无需凭据即可连接并完成自助初始化。

REST 快速入门

创建密钥：

curl -X POST https://meatspace.run/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "email": "[email protected]"}'

响应中包含 api_key——密钥仅显示一次，请妥善保存。之后的所有调用都需使用 Authorization: Bearer <token>。

创建请求：

curl -X POST https://meatspace.run/api/requests \
  -H "Authorization: Bearer $MEATSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "my-agent",
    "title": "Ship v2.0 to production?",
    "content": "All tests pass. Staging looks good. 2 minor lint warnings.",
    "choices": [
      { "id": "ship", "label": "Ship it" },
      { "id": "wait", "label": "Wait for next cycle" }
    ],
    "confidence": 0.7,
    "consequence_of_wrong_choice": "Premature ship affects ~50k users"
  }'

响应：

{
  "success": true,
  "data": {
    "id": "uuid",
    "status": "pending",
    "review_url": "https://meatspace.run/review/uuid?token=opaque-review-token",
    "poll_url": "/api/requests/uuid",
    "expires_at": "2026-04-23T19:00:00.000Z"
  }
}

通过长轮询获取结果：

curl https://meatspace.run/api/requests/{id}/wait?timeout=25000 \
  -H "Authorization: Bearer $MEATSPACE_API_KEY"

人工回复后返回 { status: "completed", selected, selected_label, responded_at }；如果仍在等待，则返回 202。

POST /api/requests 的可选字段：content_type（默认为 text，可选 markdown、html、image）、decision_reason、confidence（0–1）、consequence_of_wrong_choice、recommended_option、callback_url（必须使用 HTTPS，且主机名须在允许列表中）、metadata（透传至 webhook）、run_id、trace_id、timeout_seconds（默认为 3600，最大值为 86400）。

MCP

MeatSpace 在 https://meatspace.run/api/mcp 上通过 Streamable HTTP 实现 MCP。该服务提供三个工具：

• get_service_status — 查看可用性和升级处理指引。无需身份验证。
• provision_api_key — 创建 Bearer 令牌。无需身份验证，但受速率限制。
• ask_human — 提交决策。需要 Bearer 身份验证。

Claude Code 配置：

{
  "mcpServers": {
    "meatspace": {
      "type": "url",
      "url": "https://meatspace.run/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

ask_human 最长会进行 20 秒的长轮询。如果人工在此期间未回复，该工具将返回 status: "pending"，并附带 review_url（供人工使用）和 poll_url（供 Agent 使用）。

浏览器 SDK

适用于在浏览器环境中运行的 Agent：

<script type="module">
  import { MeatSpace } from 'https://meatspace.run/sdk/meatspace.js';

  const ms = new MeatSpace();
  await ms.getKey({ name: 'browser-agent', email: '[email protected]' });

  const result = await ms.ask({
    agentName: 'browser-agent',
    title: 'Which option?',
    choices: [
      { id: 'a', label: 'A' },
      { id: 'b', label: 'B' },
    ],
  });
  console.log(result.selected);
</script>

方法：getKey()、createRequest()、pollResult()、waitForResult()、ask()（创建请求并等待结果）。

Webhooks

如果请求中设置了 callback_url，当真人响应时，MeatSpace 会 POST 结果：

{
  "event": "request.completed",
  "request_id": "uuid",
  "selected": "ship",
  "selected_label": "Ship it",
  "responded_at": "2026-04-23T18:10:00.000Z",
  "metadata": {}
}

callback_url 必须使用 https://，且主机名必须由运营方明确加入允许列表。如果未配置允许列表，创建请求时会拒绝回调 URL。每次投递都会使用 X-HITL-Timestamp 和 X-HITL-Signature 标头进行签名。

发现端点

路径	格式	用途
/.well-known/mcp.json	JSON	MCP 服务清单
/.well-known/agent.json	JSON	A2A Agent Card
/api/openapi	JSON	OpenAPI 3.1 规范
/api/mcp (GET)	JSON	MCP 服务信息，无需身份验证
/api/status	JSON	健康检查 + Agent 指引
/sdk/meatspace.js	JavaScript	浏览器 SDK
/llms.txt	Text	大模型可读摘要
/llms-full.txt	Text	完整 API 文档
/agents.md	Markdown	完整集成指南
/sitemap.xml	XML	站点地图
/robots.txt	Text	爬虫指令 + 发现指引

错误

所有错误均返回：

{
  "success": false,
  "error": "Human-readable message",
  "code": "machine_readable_code"
}

常见代码：agent_name_required、invalid_choice_count、content_too_large、callback_url_not_allowed、request_create_failed。

本地开发

此仓库是一个部署在 Cloudflare Pages 上的 Next.js 14 应用。

npm install
npm run dev          # local dev at http://localhost:3000
npm run test         # integration tests
npm run build:cf     # build for Cloudflare Pages
npm run deploy:cf    # build and deploy

Supabase 是密钥和请求的权威数据源；Resend 负责处理事务性电子邮件。

许可证

MIT