用途
HumanSurvey 是一款专为 AI 智能体设计的反馈收集工具，核心用途是自报告归因（self-reported attribution）。它解决的是传统追踪无法覆盖的渠道归因问题：当曝光发生在 TikTok 应用内、Instagram、播客、社区、口碑或 AI 助手中时，追踪信号会丢失，直接询问用户是唯一始终有效的信号。
主要能力
- 创建表单：通过 PUT 请求存储不可变的配置快照，表单在配置前不渲染任何内容。平台标签、标记和别名来自
GET /api/attribution/catalog，并复制到快照中。创作者候选集由用户自行提供。 - 渐进式披露：先 POST 平台答案，再 PATCH 后续追问。第一个答案在第二个问题提出前已持久化，中途放弃的受访者仍贡献有效数据。
- 默认轮换：可排序候选按受访者排列，由客户端生成的
render_id作为种子，确保原始份额无偏差。也支持固定顺序，但不隐藏其偏差。 - 回溯重映射：自由文本按原样存储，每次读取时根据重映射表解析，一次映射即可修正数月历史，无需回填。
- 不可变配置快照：响应与渲染时的版本关联，重新配置无法改写历史记录。
- 单一连接键双向使用：
external_id可引入收入数据，并将每用户归因回传到自己的用户表。 - 游标读取：响应完成后可见，仅发出一次，且为最终状态，下游无需 upsert。
使用方式
- 创建并配置表单：先创建表单，然后用 PUT 存储配置快照。
- 读取结果：使用
GET /api/attribution/forms/{id}/responses（游标流，或通过?external_id=查询单个身份）、.../unresolved查看待映射的自由文本、POST .../remaps进行回溯解析。完整请求和响应结构见 OpenAPI 文档。 - 与 Claude Code 配合：服务器名称为
survey，包名为humansurvey-mcp。其十个工具现使用归属 API。npm 发布独立于本仓库，版本可能滞后。 - 文档与 API：
- 文档页：https://www.humansurvey.co/docs
- OpenAPI：https://www.humansurvey.co/api/openapi.json
- AI 索引：https://www.humansurvey.co/llms.txt
适用场景
- 宿主在自身注册或支付流程中嵌入表单。在支付流程中，受访者已是付费客户，答案无需转换摄取即可与收入关联；在注册流程中，可看到渠道带来但从未付费的人群。通过计算渠道在付费人群中的份额除以其在注册人群中的份额，可判断转化优劣（比值大于 1 好于平均，小于 1 差于平均），再乘以整体注册到付费转化率得到该渠道自身转化率。
- 智能体维护候选列表并读取结果。
限制
- 不适合通用调查：在归因转向后，任意问题类型、Markdown 编写和条件逻辑已被移除。
- 不提供面向人的分析仪表板：聚合结果是 API 资源，智能体即仪表板。
- 不代为触达受众：HumanSurvey 从不联系受访者；提供的传输方式（
/s/{id}URL 和 iframe 嵌入）由用户自行控制。 - 匿名密钥创建已移除：每个密钥从创建起即属于一个账户，这提供了密钥恢复路径并使轮换免费。
- 范围纪律：新 UI 变体、分析仪表板和人工操作员功能通常不在范围内。
产品原则
- AI 优先 I/O：智能体配置表单并消费结果，人在中间。
- 一切皆 API：创作者功能必须通过认证的 HTTP 和 MCP 可用。
- 窄范围胜出：一个问题，问好它。
- 不提供确信的百分比：每个数字都附带其计算所基于的分母，无法诚实计算的数字为 null 而非平滑处理。