human-survey

HumanSurvey

网站： humansurvey.co · 文档： humansurvey.co/docs · 常见问题： humansurvey.co/faq

为没有来源标记的渠道提供归因。

HumanSurvey 会在宿主自身的注册或付款流程中提出一个问题——你是如何知道我们的——并细化到真正可采取行动的程度：先了解平台，再了解具体的创作者、播客、活动或商店。

Agent configures a form   → platforms from the catalog, creators supplied by the caller
Host embeds /s/{id}       → in its signup flow, its payment flow, or both
Respondent answers        → picks a platform; that pick expands the follow-up in place
Host pushes conversions   → POST /api/attribution/events, keyed on its own user id
Agent reads back          → rollup, raw response stream, free text awaiting a mapping

这是什么？

一款用于自述归因的 API 和 MCP 服务。TikTok 应用内、Instagram、播客、社群、口碑传播、AI 助手：曝光发生在追踪无法触及的地方，而询问用户是唯一始终有效、能够跨越所有来源信息丢失情况的信号。

两种放置方式回答不同的问题。在付款流程中，受访者已经是付费客户，因此答案可以直接关联收入，无需导入转化数据。在注册流程中，这是了解渠道带来的未付费用户的唯一方式。用某渠道在付费用户中的占比除以它在注册用户中的占比。比值大于 1，表示其转化率高于平均水平；小于 1，则表示低于平均水平。将这个比值乘以整体注册转付费率，即可得出该渠道自身的转化率。

它专为以下场景设计：

• 在自有引导流程或结账流程中嵌入表单的宿主
• 维护候选列表并读取结果的 Agent

它不适用于以下场景：

• 通用调查问卷——在转向归因后，任意问题类型、Markdown 编辑和条件逻辑都已移除
• 面向用户的分析仪表板：汇总数据是一个 API 资源，而 Agent 就是仪表板
• 代你触达受众——HumanSurvey 从不联系受访者；它提供的传输方式（/s/{id} URL 和 iframe 嵌入）均由你控制

功能

• 渐进式展示，而非分页 — 先 POST 平台答案，再 PATCH 后续答案。第一个答案在询问第二个答案之前就已持久化；即使受访者中途放弃后续问题，也仍是有效数据。
• 默认轮换顺序 — 可排序的候选项会针对每位受访者进行排列，并以客户端生成的 render_id 作为种子，因此原始占比在设计上就不受顺序偏差影响。调用方可以选择 fixed 顺序，但它不会掩盖其中的偏差。
• 追溯映射 — 自由文本会按原样存储，并在每次读取时依据映射表进行解析，因此只需一次映射，就能修正数月的历史数据，无需回填。
• 不可变的配置快照 — 响应会关联到呈现时所依据的版本，因此重新配置不会改写历史记录中的展示内容。
• 双向共用一个关联键 — external_id 可导入收入，也可将每位用户的归因信息回传到你自己的用户表。
• 游标读取 — 响应完成后即可见，只会发出一次，且发出后即为最终结果。下游无需执行 upsert。

产品原则

• AI 优先的输入输出：由 Agent 配置表单并使用结果；人类参与其中。
• 一切皆为 API：创作者功能必须可通过经过身份验证的 HTTP 和 MCP 使用。
• 专注于窄领域：把一个问题问好。主要服务于人工问卷操作员的功能可能不适合这里。
• 不提供缺乏依据的百分比：每个数字都与计算它所依据的分母一同提供；无法如实计算的数字将显示为 null，而不是经过平滑处理。

快速开始

获取 API 密钥

curl -X POST https://www.humansurvey.co/api/auth/code \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

curl -X POST https://www.humansurvey.co/api/auth/verify \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "code": "481920", "grant": "api_key" }'

匿名创建密钥的方式已取消。每个密钥从创建之初就属于某个账户，因此密钥丢失后可以恢复，轮换密钥也无需付费。

创建表单，然后进行配置

curl -X POST https://www.humansurvey.co/api/attribution/forms \
  -H "Authorization: Bearer hs_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout — how did you hear about us",
    "allowed_origins": ["https://app.example.com"]
  }'

{
  "id": "abc123efgh45",
  "form_url": "https://www.humansurvey.co/s/abc123efgh45",
  "warnings": ["this form has no config yet; PUT /api/attribution/forms/abc123efgh45 with {nodes} before embedding it"]
}

表单在配置完成前不会呈现任何内容。PUT 会将配置保存为不可变快照：

curl -X PUT https://www.humansurvey.co/api/attribution/forms/abc123efgh45 \
  -H "Authorization: Bearer hs_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {
        "id": "channel",
        "prompt": "Where did you first hear about us?",
        "candidates": [
          { "id": "tiktok", "catalog_slug": "tiktok", "expands": "creator" },
          { "id": "reddit", "catalog_slug": "reddit" },
          { "id": "friend", "label": "A friend or colleague" },
          { "id": "dunno", "label": "I don'\''t remember", "pinned": "end", "dont_remember": true }
        ]
      },
      {
        "id": "creator",
        "prompt": "Which account was it?",
        "candidates": [
          { "id": "oecuid_8812", "label": "Jade", "handle": "@jade.work0" }
        ]
      }
    ]
  }'

平台标签、标记和别名来自 GET /api/attribution/catalog，并会复制到快照中。创作者候选项由你提供：产品会呈现候选集并返回所选项的 id；将模糊描述与创作者数据库匹配则属于上游工作。

读取结果

curl "https://www.humansurvey.co/api/attribution/rollup?form_id=abc123efgh45&by=candidate&from=2026-07-01&to=2026-08-01" \
  -H "Authorization: Bearer hs_sk_..."

读取端还提供：GET /api/attribution/forms/{id}/responses（游标流，或通过 ?external_id= 获取单个身份的结果）、用于查看等待映射的自由文本的 .../unresolved，以及用于追溯解决问题的 POST .../remaps。完整的请求和响应结构请参阅OpenAPI 文档。

与 Claude Code 搭配使用

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

服务名称仍为 survey，包名称仍为 humansurvey-mcp——两者都包含在每位现有用户的配置中。其十个工具现已接入归因 API——请参阅 packages/mcp-server/README.md。npm 的发布与此仓库分开，因此 npm 上的版本可能落后于此处的版本。

公共资源

• 文档页面：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）
前端	React + Tailwind CSS
MCP 服务	@modelcontextprotocol/sdk
部署	Vercel

项目结构

├── apps/web/            # Next.js app (API + respondent page + site)
│   ├── lib/attribution/ # config, responses, reads, rollup, remap
│   └── supabase/migrations/  # applied through scripts/migrate.sh, with a ledger
├── packages/mcp-server/ # MCP server for Claude Code
└── docs/                # architecture, roadmap, design docs

贡献

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

开发

pnpm install
pnpm dev               # Start Next.js dev server
pnpm test              # node --test over apps/web/lib/**/*.test.ts
pnpm build             # Build all packages

许可证

MIT