1. 项目概述当AI开发遇上真人测试最近在折腾一个挺有意思的项目叫human_test()。这名字听起来像个函数调用实际上它也确实是一个可以被AI智能体Agent直接调用的“技能”。简单来说它解决了一个AI原生开发流程中一个非常现实的痛点AI可以快速生成一个产品原型但它怎么知道这个产品对真人用户来说好不好用我们可能都经历过用Claude Code或者Cursor几分钟内就能搭出一个功能完整的登录页面或一个购物车流程。代码跑起来了界面看起来也没问题但当你把它丢给一个真实用户时问题就来了——“这个按钮怎么点不动”“这个步骤我没看懂”“这个提示信息是什么意思”传统的解决方案是开发者需要手动招募测试用户或者自己化身产品经理去走查费时费力而且主观性强。human_test()想做的就是把这个“真人可用性测试”的环节也自动化、结构化并且无缝嵌入到AI驱动的开发工作流中。它不是一个给人类产品经理看的、充满视频和主观评论的仪表盘而是一个为AI智能体设计的API。AI可以调用它它会自动安排真人测试员目前看来是平台内建的测试员池去执行测试任务录制屏幕和语音然后由另一个AI来分析这些录像最终生成一份结构化的、可被机器直接解析的问题报告。更绝的是如果提供了代码仓库地址它还能基于报告自动生成修复代码并提交Pull Request。这相当于在“AI写代码”和“产品上线”之间插入了一个自动化的、基于真人反馈的“质量检验与修复”闭环。对于追求快速迭代和自动化交付的团队或个人开发者来说这无疑是一个极具吸引力的构想。2. 核心设计思路为AI智能体而生的测试工具2.1 与传统UX测试平台的本质区别在深入细节之前有必要先厘清human_test()与传统UserTesting、Maze等平台的根本不同。这不是一个“更好”或“更便宜”的替代品而是一个不同物种。传统UX测试平台的核心用户是人类产品经理或设计师。它们提供丰富的视频、热力图、点击流数据以及需要人类去解读和归纳的定性反馈。输出是一份“报告”但这份报告的理解、优先级排序和转化为具体开发任务仍然需要人类来完成。这是一个“人-机-人”的流程。human_test()的核心用户是AI智能体。它的设计目标是让AI能“理解”测试结果并“行动”。因此它的输出必须是高度结构化的、无歧义的、并且包含足够上下文以便AI生成修复代码。它追求的是一个“机-人-机”的闭环。这体现在几个关键设计上结构化输出优先报告不是自由文本的总结而是严格遵循“问题-证据-影响-建议”模板的Markdown并带有明确的严重性等级CRITICAL, MAJOR, MINOR和优先级标签P0-P3。这种结构就像给AI喂了一份格式清晰的“需求说明书”。API与Webhook驱动整个流程通过API触发并通过Webhook异步通知结果。这完美契合了AI智能体作为“调用者”和“响应者”的角色可以轻松集成到自动化流水线中。自动修复与PR这是闭环的关键一步。平台不仅能指出问题还能尝试自动修复。它通过分析报告理解问题本质如“按钮太小”定位到代码库中的相关文件生成具体的代码差异diff并直接创建PR。这大大缩短了从发现问题到部署修复的周期。2.2 技术栈选型与架构考量从项目结构看human_test()选择了非常现代且高效的Web全栈方案前端/全栈框架Next.js 16 (App Router)。这是一个明智的选择。Next.js 的App Router提供了优秀的服务端组件、API路由和构建体验非常适合需要复杂交互和实时状态管理的管理后台。同时它的全栈能力使得在同一项目中处理前端页面、API逻辑和服务器端操作如视频处理、AI调用变得非常顺畅。数据库ORMPrisma。Prisma以其类型安全和直观的数据模型定义而闻名。它同时支持SQLite和MySQL这为部署提供了极大的灵活性。项目默认使用SQLite实现了“零外部依赖”的本地一键启动降低了体验门槛而在生产环境或需要更高并发时可以无缝切换到MySQL。身份验证NextAuth.js。这是Next.js生态的事实标准认证方案轻松处理用户注册、登录、会话管理并支持多种Provider如邮箱/密码、OAuth。项目采用了邮箱验证流程来管理测试员账户。样式Tailwind CSS。实用优先的CSS框架能快速构建出美观且一致的管理界面符合现代工具类产品的审美。这种技术栈组合Next.js Prisma NextAuth Tailwind几乎是当前构建现代B端管理台的“黄金组合”保证了开发效率、代码质量和可维护性。架构上它将核心逻辑清晰地分为了几个模块lib/ai-report.ts: 负责协调整个报告生成流程。lib/media-analysis.ts: 处理最复杂的部分——从测试员上传的屏幕录像中提取关键帧并调用视觉AI如GPT-4V、Claude-3 Opus分析界面问题。lib/code-fixer.ts: 实现从问题描述到代码修复的魔法涉及仓库克隆、代码分析、Diff生成和GitHub API操作。独立的skill/目录存放AI技能定义方便被Claude Code、Cursor等编辑器插件直接识别和安装。这种模块化设计使得每个核心功能都有明确的边界便于理解、测试和扩展。3. 实操部署与核心配置详解3.1 两种启动方式CLI快速体验与手动部署项目提供了极其友好的CLI工具这是降低使用门槛的关键。方式一CLI一键启动推荐初学者npm i -g humantest-app humantest init cd humantest humantest start这三行命令背后做了很多事情humantest init: 启动一个交互式向导。它会询问你使用哪种数据库默认SQLite、设置管理员邮箱密码、配置AI服务商和API密钥、设置SMTP用于发送验证邮件等。如果你在环境变量中已经预设了ANTHROPIC_API_KEY或OPENAI_API_KEY它会自动读取。命令执行完毕后会在当前目录创建一个humantest文件夹里面包含了整个项目的代码和初始化好的数据库。humantest start: 启动Next.js开发服务器。默认在http://localhost:3000运行。实操心得第一次运行init时如果网络环境访问npm或GitHub较慢可能会在安装依赖步骤卡住。可以尝试提前设置好npm镜像源。另外对于自动化部署如CI/CD可以使用humantest init --non-interactive非交互模式它会读取所有配置来自环境变量非常适合Docker或脚本化部署。方式二手动克隆与部署适合定制化git clone https://github.com/avivahe326/humantest.git cd humantest cp .env.example .env # 编辑 .env 文件填入你的配置 npm install npx prisma db push npm run build npm start这种方式让你拥有完整的代码控制权方便进行二次开发或深度定制。你需要手动创建.env文件并配置所有环境变量。3.2 关键环境变量解析配置文件是项目的核心。理解每个变量的作用至关重要尤其是涉及到外部服务集成的部分。变量名是否必需说明与配置建议DATABASE_URL是数据库连接字符串。本地开发强烈建议用SQLitefile:./data/humantest.db。生产环境可换为MySQLmysql://user:passwordlocalhost:3306/humantest。NEXTAUTH_SECRET是NextAuth的加密密钥。必须是一个足够长的随机字符串。可以用openssl rand -base64 32命令生成。NEXTAUTH_URL是应用的公开访问地址。开发时是http://localhost:3000生产环境需改为你的域名如https://humantest.yourcompany.com。这个值不对会导致登录回调失败。AI_PROVIDER否AI服务商默认为anthropic。可选openai,deepseek,gemini等取决于项目支持情况。AI_API_KEY功能必需对应AI服务商的API密钥。没有它报告生成和代码分析功能将无法工作。SMTP_HOST,SMTP_PORT,SMTP_USER,SMTP_PASS否SMTP服务器配置用于发送账户注册验证邮件。如果不配置系统将允许直接注册无邮箱验证适合内网或快速测试。OSS_REGION,OSS_ACCESS_KEY,OSS_SECRET_KEY等否对象存储配置如AWS S3、阿里云OSS。用于存储测试员上传的屏幕录制视频。如果不配置视频将保存在服务器本地磁盘。对于生产环境强烈建议配置对象存储以解决本地存储空间、文件管理和CDN分发问题。GITHUB_TOKEN否GitHub个人访问令牌。这是启用自动修复和创建PR功能的关键。需要具备对目标仓库的读写权限用于创建PR或只读权限用于生成建议Diff。注意事项关于GITHUB_TOKEN的权限。如果你只希望AI分析代码并给出修复建议但不自动提交PR那么一个具有repo范围只读权限的token就足够了。如果你希望实现全自动闭环则需要一个具有repo和workflow等范围读写权限的token。务必在GitHub的Token设置页面仔细勾选所需权限并在一个安全的、权限最小的仓库中先行测试。3.3 管理员与测试员体系项目启动后第一个通过注册页面如果未配SMTP则为直接注册创建的用户会自动成为管理员。管理员拥有最高权限可以访问/settings页面在那里动态修改几乎所有平台配置包括上面提到的环境变量而无需重启服务。这是一个非常贴心的设计。测试员则是通过平台注册的普通用户。他们可以浏览“任务大厅”认领待测试的任务然后按照指引完成测试流程录制屏幕和麦克风、记录第一印象、分步完成任务、最后给出NPS评分。这些数据构成了AI生成报告的原始素材。4. 核心工作流与集成实践4.1 完整任务生命周期一个典型的human_test()任务流程如下创建任务通过Web界面或直接调用API创建。需要提供产品URL或对非Web产品的描述、测试重点如“测试结账流程的易用性”、需要的测试员数量等。任务发布与认领任务进入平台的任务列表。注册的测试员可以看到并认领任务。执行测试与录制测试员在引导下使用浏览器提供的MediaRecorder API进行屏幕和语音录制同时完成结构化的反馈表单。媒体上传与处理录制完成后视频文件被上传至OSS或本地。后台服务开始工作从视频中按时间或关键动作提取多帧截图。AI分析生成报告核心的lib/ai-report.ts和lib/media-analysis.ts模块被调用。它们将提取的视频帧、测试员的语音转文字稿、以及结构化反馈一并发送给配置的视觉/语言大模型如Claude-3.5 Sonnet要求其按照既定模板分析可用性问题生成带严重性等级的结构化报告。报告交付报告生成后会通过Webhook如果创建任务时提供了webhookUrl异步通知调用方。同时报告也会保存在平台内供查看。可选自动修复如果创建任务时提供了repoUrl和具有足够权限的GITHUB_TOKEN平台会克隆代码库让AI根据报告中的问题描述定位相关代码文件生成具体的修复代码差异Diff。可选创建PR在自动修复的基础上如果有写入权限平台会直接创建一个新的分支提交修改并向主仓库发起Pull Request。整个过程无需人工介入。4.2 如何与你的AI工作流集成这才是human_test()的威力所在。它提供了两种主要的集成方式方式一作为AI编辑器技能最无缝如果你的开发环境是Claude Code、Cursor或Windsurf这类AI原生编辑器可以直接安装其技能。npx skills add avivahe326/human-test-skill安装后你就可以在编辑器中直接用自然语言对AI助手说“帮我对当前这个本地运行在http://localhost:3000的购物车页面做个可用性测试重点看价格计算和优惠券应用是否清晰找3个测试员。” AI助手会理解你的意图并自动在后台调用human_test()API。方式二直接调用REST API最灵活你也可以在任何能发送HTTP请求的地方调用它比如在CI/CD流水线中、在自定义的自动化脚本里或者从另一个服务中调用。curl -X POST http://your-humantest-server.com/api/skill/human-test \ -H Content-Type: application/json \ -d { url: https://staging.your-app.com/checkout, focus: 验证新用户使用礼品卡结账的全流程是否顺畅有无迷惑步骤。, maxTesters: 3, repoUrl: https://github.com/your-team/ecommerce-frontend, webhookUrl: https://your-slack-bot.com/webhook/humantest, creator: deploy-bot-v1.2 }这个例子展示了一个接近真实的场景在预发布环境部署后自动触发一个可用性测试任务并将结果通知到团队的Slack频道。实操心得Webhook的运用是关键。你的接收服务比如一个Slack机器人或内部告警系统在收到报告后可以进一步解析报告内容提取P0级紧急问题并相关负责人或者将报告内容格式化后存入项目管理系统如Jira自动创建工单。这样就把human_test()真正嵌入了你的DevOps流程。4.3 报告结构深度解读AI生成的报告是核心交付物。它的质量直接决定了后续自动修复的准确性。一份标准的报告长这样## 元数据 | 字段 | 值 | |------|-----| | 产品 | 你的应用 | | 测试员数 | 5 | | 平均NPS得分 | 7.2/10 | ## 执行摘要 3-5句话按问题严重性降序排列概述最关键发现 ## 发现的问题 ### [严重] 移动端注册按钮无响应 - **证据** 5位测试员中有3位在iPhone上无法完成注册视频显示多次点击无反应。 - **影响** 预计导致60%的移动端新用户流失直接影响转化率。 - **建议修复** 检查并修正按钮的CSS touch-action 属性确保触摸目标尺寸不小于44x44像素并排查可能的事件冒泡阻止。 ### [重要] 价格页面布局令人困惑 - **证据** 多位测试员在对比套餐时表示“不知道哪个更划算”眼动热图基于视频分析显示视线在价格卡片间频繁跳跃。 - **影响** 降低用户决策效率可能增加客服咨询量。 - **建议修复** 考虑引入对比表格高亮推荐套餐并使用更清晰的视觉层次区分不同功能点。 ... ## 优先级建议 - **P0立即修复** 移动端注册按钮响应问题。 - **P1本迭代修复** 价格页面布局优化。 - **P2下个迭代考虑** ...你可以看到报告为AI提供了清晰的行动指令“证据”描述了现象“影响”量化了问题严重性“建议修复”则给出了具体、可操作的代码级或设计级修改方向。这比“用户体验不好”这种模糊反馈要有用得多。5. 深入原理AI如何从视频中“看懂”问题这是human_test()技术栈中最具挑战性也最有趣的部分。它如何把一段真人录制的、充满噪音的屏幕操作视频变成结构化的可用性问题报告其核心在lib/media-analysis.ts模块。5.1 视频处理与关键帧提取直接让AI模型处理长视频不仅成本高昂API按Token收费而且效率低下无关帧会带来大量干扰信息。因此第一步是智能抽帧。均匀抽帧最简单的方法每隔N秒抽取一帧。这能保证覆盖测试全过程但可能错过关键瞬间。基于变化的抽帧更高级的方法。计算连续帧之间的差异如像素差异、结构相似性在画面发生显著变化时如页面跳转、弹窗出现、大量输入抽取帧。这能更精准地捕捉到“交互时刻”。结合用户行为标记如果测试员在反馈流程中标记了“这一步遇到了问题”那么对应时间点附近的帧就是重点分析对象。项目文档中提到“extracts key frames from recordings”推测采用了第2种或结合第2、3种策略以在分析效果和成本之间取得平衡。5.2 多模态AI分析与报告合成抽取出的一系列关键帧图片和测试员的语音转文字稿被一起送入多模态大模型如GPT-4V, Claude-3 Opus。给模型的提示词Prompt工程至关重要。它需要引导模型完成以下任务视觉元素识别“这是哪个页面页面上有哪些主要组件按钮、输入框、菜单”交互问题检测“用户在这个界面做了什么操作点击、输入界面反馈是否符合预期如按钮状态变化、页面跳转、提示信息是否存在无响应、延迟、错误提示”可用性启发式评估“这个布局符合尼尔森十大可用性原则吗信息层次是否清晰操作流程是否简洁”关联文本反馈“测试员在此时的口头描述是什么他的困惑点是否在界面上有体现”结构化归纳“将以上观察按照‘问题描述-证据-影响-建议’的格式归纳为一条条记录并评估其严重性。”这个过程本质上是在让AI扮演一个经验丰富的UX专家观看用户测试录像并做笔记。项目的价值在于它通过精心设计的Prompt和流程将这种原本高度依赖个人经验的任务标准化、自动化了。5.3 从问题描述到代码修复如果开启了自动修复功能lib/code-fixer.ts模块会接手。它拿到AI生成的结构化报告后会进行以下操作代码库克隆与分析使用提供的GITHUB_TOKEN克隆目标仓库到临时目录。问题定位这是难点。AI需要理解“移动端注册按钮无响应”这个问题对应到前端代码库中的哪些文件可能是SignupButton.tsx组件也可能是button.css样式文件或者是某个全局事件监听器。这需要AI对代码结构有深刻理解。实践中可能会结合向量检索RAG技术先将代码库索引化然后根据问题描述进行语义搜索找到最相关的代码片段。生成修复DiffAI在理解问题和相关代码后会尝试生成修改建议。例如对于“按钮太小”的问题它可能会修改CSS中的padding和min-height属性。生成的不是完整的新文件而是标准的Git Diff格式清晰地展示了“改前”和“改后”。创建PR如果有写入权限工具会创建一个形如fix/button-tap-target-{taskId}的新分支应用修改提交代码并通过GitHub API创建Pull Request甚至可能自动填写PR描述引用发现的问题。注意事项与局限性自动修复功能目前仍处于“辅助”阶段。对于复杂的逻辑错误或涉及多个模块联动的交互问题AI可能无法给出完美修复甚至可能引入新Bug。因此将自动生成的PR视为一份高质量的“修复建议”而非最终方案由开发人员审查后合并是更稳妥的做法。这个功能最大的价值在于节省了开发人员定位问题和构思初步解决方案的时间。6. 常见问题、排查与进阶技巧6.1 部署与运行问题Q1: 运行humantest start后访问localhost:3000报错或白屏。检查点1端口占用。默认端口3000可能被其他应用占用。可以查看启动日志或尝试humantest start --port 3001指定其他端口。检查点2数据库初始化。确保prisma db push成功执行并且DATABASE_URL指向的SQLite文件路径有写入权限。可以检查humantest目录下是否生成了data/humantest.db文件。检查点3环境变量。确认.env文件已正确创建并位于项目根目录且NEXTAUTH_URL与实际访问地址一致。检查点4依赖安装。尝试删除node_modules和package-lock.json重新运行npm install。Q2: 测试员录制视频上传失败或报告生成时卡住。检查点1存储配置。如果使用了OSS检查OSS_*相关环境变量是否正确尤其是Bucket权限和区域Region是否匹配。最简单的方法是暂时注释掉OSS配置回退到本地存储测试以判断是否是OSS问题。检查点2AI API密钥与额度。报告生成依赖AI服务。检查AI_API_KEY是否有效以及对应账户的API调用额度是否充足。可以在服务器的日志通过humantest logs查看中寻找AI调用相关的错误信息。检查点3文件大小与格式。确保服务器有足够的磁盘空间处理临时视频文件。浏览器的MediaRecorder API通常输出webm或mp4格式后端处理库需要支持。6.2 功能使用问题Q3: 创建任务时测试员一直无人认领。这通常是因为平台内没有活跃的测试员。在自托管模式下你需要自己“招募”测试员。初期可以自己注册几个测试员账号。在创建任务时使用creator字段指定一个已存在的测试员ID系统可能会将该任务直接分配给该测试员取决于实现逻辑需查阅代码。考虑将测试任务开放给团队内部成员或小范围用户让他们注册为测试员来完成。这也是开源项目初期的常见挑战。项目方未来可能会提供付费的、接入真人测试员池的云端服务选项。Q4: AI生成的报告感觉不准确或流于表面。优化Prompt报告质量极大依赖于发给AI模型的指令。你可以尝试修改lib/ai-report.ts中的提示词模板让它更聚焦于你关心的方面如“重点关注无障碍访问问题”、“从首次用户的角度出发”。提供更详细的focus参数在创建任务时focus字段不要写得太笼统。例如不要写“测试整个应用”而是写“测试从商品详情页点击‘加入购物车’到进入购物车页面的流程观察按钮反馈、页面加载速度和库存提示信息的清晰度”。选择更强的模型在.env中尝试切换AI_PROVIDER和AI_API_KEY使用能力更强的模型如从GPT-4 Turbo切换到Claude-3.5 Sonnet通常能获得更深度的分析。人工复核与反馈目前系统可能缺乏一个“报告质量评分”的反馈循环。你可以手动标记哪些AI发现的问题是真实有效的哪些是误报这些数据未来可以用于微调提示词或训练更专用的模型。Q5: 自动修复功能创建PR失败。权限问题确保GITHUB_TOKEN具有目标仓库的写入权限用于创建分支和PR或至少读权限用于生成Diff。Token的权限范围scopes需要包含repo私有仓库或public_repo公开仓库。仓库地址格式repoUrl必须是有效的GitHub HTTPS URL如https://github.com/username/repo。分支冲突如果自动生成的分支名已存在会导致创建失败。可以查看code-fixer.ts的逻辑看是否有重试或命名后缀机制。网络问题确保你的部署服务器能够正常访问api.github.com。6.3 安全与性能考量数据安全屏幕录制视频包含敏感信息。在自托管时务必确保服务器安全并谨慎考虑OSS存储的访问策略。对于内部测试使用本地存储可能是更安全的选择。速率限制平台内置了API速率限制如注册5次/分钟/IP。在生产环境面对大量用户时可能需要根据实际情况调整这些限制或者在前端接入更专业的防刷服务。成本控制AI API调用尤其是视觉模型和OSS存储是主要成本来源。需要监控使用量并为AI调用设置预算警报。可以考虑对视频进行压缩、限制单次测试时长、或使用更经济的模型进行初步筛选。可扩展性当前架构使用SQLite和单Node进程适合小规模使用。如果测试任务量增长需要考虑将数据库迁移至MySQL/PostgreSQL使用PM2或Docker进行进程管理并将视频处理、AI调用等耗时任务放入消息队列如Bull异步执行避免阻塞Web请求。这个项目代表了一种前沿的思考方向将人类的主观经验和判断力通过结构化的流程和AI的能力转化为可自动化执行、可规模化的质量保障环节。它可能还不完美但无疑为“AI原生开发”的完整闭环提供了一个激动人心的拼图。