Digital → Physical · Open source · Docs v2.0.0

HumanAPI
接口文档

HumanAPI 是连接 AI Agent 与人类专家的开源参考实现:检索能力、记录任务、创建预约,再通过明确的接口查询进度。本站提供 REST API 完整参考、MCP 工具参考与本地部署指南。

v2.0.0
接口规范版本
12
个 MCP 工具
MIT
开放许可
request.trace reference
  1. 01discoverGET /api/humans
  2. 02arrangePOST /api/bookings
  3. 03observeGET /api/bookings/:id
一条从结构化请求到物理执行记录的可读路径。

三份文档,覆盖集成全过程。

从零开始跑通本地服务,到按端点检索专家、创建预约、处理评价与争议,所有字段都以仓库中的实现为准。

示例与接口规范保持一致。

不使用虚构 SDK。下面的字段直接对应仓库中的 Next.js Route Handlers,便于在本地阅读与验证。

REST

检索专家

GET /api/humans
// 携带 API Key 检索已验证的专家档案
const apiKey = process.env.HUMANAPI_API_KEY;

const query = new URLSearchParams({
  skills: "现场调研",
  ratingMin: "4",
  rateMax: "200",
  availableNow: "true",
});

const response = await fetch(`/api/humans?${query}`, {
  headers: {
    authorization: `Bearer ${apiKey}`,
  },
});
const { data, pagination } = await response.json();

支持 skills、lat、lon、maxDistance、费率、评分与可用性查询字段;提供坐标时返回 locationMatch 与 distance。

MCP route

分派工具请求

POST /api/mcp
// 统一的工具调用包络 { tool, arguments }
const response = await fetch("/api/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "search_humans",
    arguments: {
      skills: ["现场调研"],
      location: { lat: 31.2304, lon: 121.4737 },
      max_distance: 5000,
      rating_min: 4,
    },
  }),
});

工具参数使用 snake_case,与 REST 的 camelCase 对应;认证同样支持 x-api-key 头。

先约定,再调用。

认证、ID 语义与响应包络在全站保持一致;任何私有端点缺少 API Key 都会得到 401。

Envelope

成功响应

200 / 201
{
  "success": true,
  "data": {},
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

列表端点返回 data 数组与 pagination;单资源端点直接返回 data 对象。

Envelope

失败响应

4xx / 5xx
{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "rating", "message": "rating must be at most 5" }
  ]
}

details 携带字段级错误;未知路由同样返回 JSON 格式的 404。

ID 语义对照表

字段含义
id(humans)HumanProfile.id,专家档案主键
agentId / userId / reviewerId / senderIdUser.id,用户主键
taskId / bookingId / disputeId / messageId各资源自主键

当前边界,明确写在文档里。

这是用于开发与评估的开源参考实现,不是对托管服务或生产能力的承诺。

文档与仓库已经包含

  • 专家、任务与预约的 REST Route Handlers
  • Prisma 数据模型与匹配逻辑
  • 12 个 MCP 工具入口
  • API Key 校验与输入验证基础

生产使用前仍需完成

  • 完整的身份体系、细粒度授权、分布式限流与审计
  • 真实支付通道、结算与异常处理
  • 生产级实时通讯与通知基础设施
  • 独立安全评估、加密方案与合规认证

本项目当前不声称已提供生产支付、实时通讯、端到端加密或 SOC 2 认证。

从源码开始,而不是从承诺开始。

克隆仓库,在本地检查数据模型、路由实现与接口返回,再决定下一步如何扩展。

阅读快速开始
local.setup
git clone https://github.com/bit-cook/HumanAPI.git
cd HumanAPI
npm ci
cp .env.example .env
npx prisma generate
npx prisma migrate dev
npm run dev