HumanSurvey

为 AI 智能体提供的反馈收集基础设施。

HumanSurvey 让执行长期任务的智能体能够从一群人那里收集结构化反馈：

Agent is doing a job
  → needs structured feedback from a group
  → creates survey from JSON schema
  → shares /s/{id} URL with respondents
  → humans respond over hours or days
  → agent retrieves structured JSON results and acts on them

这是什么？

HumanSurvey 是一个极简的 API 和 MCP 服务器，只做一件事：让智能体从人类群体中收集结构化反馈，并获得机器可用的结果。

它专为以下场景设计：

运行活动管理、产品发布或社区工作流的 AI 智能体，需要对群体进行调查
构建需要轻量级反馈收集原语的智能体产品的开发者

它不适用于：

调查仪表板
可视化表单构建器
模板库
电子邮件营销活动
分析/报告 UI

功能特性

JSON 模式输入 — 结构化、精确，且可直接由机器生成
MCP 服务器 — 直接从 Claude Code 创建调查并读取结果
极简 API 接口 — 经过身份验证的创建者路由，公开的受访者提交
四种语义问题类型 — choice（选择）、text（文本）、scale（量表）、matrix（矩阵）
条件逻辑 — Markdown 和 JSON 模式中的 showIf
明确的生命周期 — 关闭调查、过期和最大回复限制

产品原则

语义优先于视觉：HumanSurvey 协议精简，不包含各种 UI 特定的字段类型。
AI 优先的输入输出：智能体编写调查，智能体消费结果；人类处于中间环节。
一切皆 API：创建者功能必须通过经过身份验证的 HTTP 和 MCP 提供。
窄范围胜出：如果某个功能主要服务于人类调查操作员，那么它可能不属于这里。

支持的问题类型

single_choice（单选）
multi_choice（多选）
text（文本）
scale（量表）
matrix（矩阵）

Markdown 语法

# Survey Title

**Description:** Instructions for the respondent.

## Section Name

**Q1. Your question here?**

- ☐ Option A
- ☐ Option B
- ☐ Option C

**Q2. Multi-select question?** (select all that apply)

- ☐ Choice 1
- ☐ Choice 2
- ☐ Choice 3

**Q3. Open-ended question:**

> _______________

| # | Item | Rating |
|---|------|--------|
| 1 | Item A | ☐Good ☐OK ☐Bad |
| 2 | Item B | ☐Good ☐OK ☐Bad |

量表问题：

**Q4. How severe is this issue?**

[scale 1-5 min-label="Low" max-label="Critical"]

条件逻辑：

**Q1. Did the deploy fail?**

- ☐ Yes
- ☐ No

**Q2. Which step failed?**

> show if: Q1 = "Yes"

> _______________________________________________

快速入门

在 Claude Code 中使用

添加到你的 Claude Code 配置 (~/.claude.json) 中：

{
  "mcpServers": {
    "survey": {
      "command": "npx",
      "args": ["-y", "humansurvey-mcp"],
      "env": {
        "HUMANSURVEY_API_KEY": "hs_sk_your_key_here"
      }
    }
  }
}

然后在 Claude Code 中：

> Create a post-event feedback survey with a 1-5 rating, open text, and a yes/no question

可用工具：

create_survey — 从 JSON 模式创建；可选 max_responses、expires_at、webhook_url
get_results — 汇总结果 + 原始回复
list_surveys — 列出你密钥拥有的调查
close_survey — 立即关闭调查

使用 HTTP API

curl -X POST https://www.humansurvey.co/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"my claude agent"}'

然后创建一个调查：

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?" }
        ]
      }]
    }
  }'

响应：

{
  "survey_url": "/s/abc123",
  "question_count": 1
}

读取结果：

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 (App Router)
数据库	Neon (无服务器 Postgres)
解析器	remark (unified 生态系统)
前端	React + Tailwind CSS
MCP 服务器	@modelcontextprotocol/sdk
部署	Vercel

项目结构

├── apps/web/          # Next.js app (API + frontend)
├── packages/parser/   # Markdown → Survey JSON parser
├── packages/mcp-server/ # MCP server for Claude Code
└── docs/              # Architecture docs

贡献

在提交 PR 之前，请阅读 CONTRIBUTING.md。最重要的规则是范围约束：新的 UI 变体、分析仪表板和人类操作员功能通常不在范围内。

开发

pnpm install
pnpm dev              # Start Next.js dev server
pnpm --filter @mts/parser test
pnpm build            # Build all packages

许可证

MIT

humansurvey-mcp