内容
# 人类调查
**网站：** [humansurvey.co](https://www.humansurvey.co) · **文档：** [humansurvey.co/docs](https://www.humansurvey.co/docs) · **常见问题：** [humansurvey.co/faq](https://www.humansurvey.co/faq)
[](https://glama.ai/mcp/servers/sunsiyuan/human-survey)
用于 AI 代理的反馈收集基础设施。
人类调查允许执行长期工作的代理从一组人中收集结构化的反馈：
```text
代理正在执行任务
→ 需要来自一组人的结构化反馈
→ 从 JSON 模式创建调查
→ 与受访者共享 /s/{id} URL
→ 人类在数小时或数天内响应
→ 代理检索结构化的 JSON 结果并据此采取行动
```
## 这是什么？
人类调查是一个最小的 API 和 MCP 服务器，用于执行一项狭窄的任务：允许代理从人类群体中收集结构化的反馈，并获得机器可用的结果。
它适用于：
- 运行事件管理、产品发布或社区工作流的 AI 代理，需要调查一组人
- 构建需要轻量级反馈收集原语的代理产品的开发人员
它不适用于：
- 调查仪表盘
- 可视化表单构建器
- 模板库
- 电子邮件活动
- 分析/报告 UI
## 功能
- **JSON 模式输入** — 结构化、精确、直接由机器生成
- **MCP 服务器** — 直接从 Claude Code 创建调查和读取结果
- **最小 API 接口** — 身份验证的创建者路由，公共受访者提交
- **四种语义问题类型** — `选择`、`文本`、`评分`、`矩阵`
- **条件逻辑** — Markdown 和 JSON 模式中的 `showIf`
- **显式生命周期** — 关闭调查、过期和最大响应限制
## 产品原则
- **语义优于视觉**：人类调查有一个小型协议，而不是大量的 UI 特定字段类型。
- **AI-first I/O**：代理编写调查，代理消费结果；人类在中间。
- **一切皆为 API**：创建者功能必须通过身份验证的 HTTP 和 MCP 提供。
- **狭窄范围赢得胜利**：如果某个功能主要为人类调查操作员服务，那么它可能不属于此处。
## 支持的问题类型
- `单选题`
- `多选题`
- `文本`
- `评分`
- `矩阵`
## Markdown 语法
```markdown
# 调查标题
**描述：** 受访者的说明。
## 部分名称
**Q1. 你的问题是什么？**
- ☐ 选项 A
- ☐ 选项 B
- ☐ 选项 C
**Q2. 多选问题？** （请选择所有适用项）
- ☐ 选择 1
- ☐ 选择 2
- ☐ 选择 3
**Q3. 开放式问题：**
> _______________
| # | 项目 | 评分 |
|---|------|--------|
| 1 | 项目 A | ☐好 ☐一般 ☐差 |
| 2 | 项目 B | ☐好 ☐一般 ☐差 |
```
评分问题：
```markdown
**Q4. 这个问题有多严重？**
[评分 1-5 最低标签=“低” 最高标签=“严重”]
```
条件逻辑：
```markdown
**Q1. 部署是否失败？**
- ☐ 是
- ☐ 否
**Q2. 哪个步骤失败了？**
> 如果：Q1 = “是”
> _______________________________________________
```
## 快速入门
### 与 Claude Code 一起使用
添加到您的 Claude Code 配置（`~/.claude.json`）：
```json
{
"mcpServers": {
"survey": {
"command": "npx",
"args": ["-y", "humansurvey-mcp"],
"env": {
"HUMANSURVEY_API_KEY": "hs_sk_your_key_here"
}
}
}
}
```
然后在 Claude Code 中：
```
> 创建一个包含 1-5 评分、开放式文本和是/否问题的事件后反馈调查
```
可用工具：
- `create_key` — 自行提供 API 密钥；无需人工设置
- `create_survey` — 从 JSON 模式创建；可选 `max_responses`、`expires_at`、`webhook_url`
- `get_results` — 聚合结果 + 原始响应
- `list_surveys` — 列出您的密钥拥有的调查
- `close_survey` — 立即关闭调查
### 使用 HTTP API
```bash
curl -X POST https://www.humansurvey.co/api/keys \
-H "Content-Type: application/json" \
-d '{
"name": "my claude agent",
"email": "you@example.com",
"wallet_address": "eip155:8453:0xabc..."
}'
```
所有字段均为可选。`wallet_address` 使用 [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md) 格式 — 将在未来用于代理原生支付。
然后创建调查：
```bash
curl -X POST https://www.humansurvey.co/api/surveys \
-H "Authorization: Bearer hs_sk_..." \
-H "Content-Type: application/json" \
-d '{
"schema": {
"title": "Post-Event Feedback",
"sections": [{
"questions": [
{ "type": "scale", "label": "How would you rate the event?", "min": 1, "max": 5 },
{ "type": "text", "label": "What should we improve?" }
]
}]
}
}'
```
响应：
```json
{
"survey_url": "/s/abc123",
"question_count": 1
}
```
读取结果：
```bash
curl https://www.humansurvey.co/api/surveys/abc123/responses \
-H "Authorization: Bearer hs_sk_..."
```
## 公共界面
- 文档页面：`https://www.humansurvey.co/docs`
- OpenAPI：`https://www.humansurvey.co/api/openapi.json`
- AI 索引：`https://www.humansurvey.co/llms.txt`
## 技术栈
| 组件 | 技术 |
|-----------|-----------|
| 框架 | Next.js (应用路由器) |
| 数据库 | Neon（无服务器 Postgres） |
| 解析器 | remark（统一生态系统） |
| 前端 | React + Tailwind CSS |
| MCP 服务器 | @modelcontextprotocol/sdk |
| 部署 | Vercel |
## 项目结构
```
├── apps/web/ # Next.js 应用（API + 前端）
├── packages/parser/ # Markdown → 调查 JSON 解析器
├── packages/mcp-server/ # MCP 服务器用于 Claude Code
└── docs/ # 架构文档
```
## 贡献
在打开 PR 之前，请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。最重要的规则是范围纪律：新的 UI 变体、分析仪表板和人类操作员功能通常不在此范围内。
## 开发
```bash
pnpm install
pnpm dev # 启动 Next.js 开发服务器
pnpm --filter @mts/parser test
pnpm build # 构建所有软件包
```
## 许可证
MIT
