这次我们聊一个更靠近“AI Agent 落地工程”的话题HumanLayer 推出了/show-me技能目标非常直接——让 agent 写的 Pull Request 更容易被人类审查。注意它说的是更容易被“审查”不是更容易被“合并”。这两者差别很大代码能不能跑、跑出来长什么样、改动会影响哪些路径这些在 AI coding agent 越来越常见的今天已经成为研发协作里最容易被低估的风险点。如果你已经习惯了让 agent 帮你修 bug、补单测、做代码重构或者正在规划把这类 agent 接到团队的 Git 工作流里那这篇文章的价值就落在一条主线上先把“agent 产物到底怎么验收”这件事拆清楚再看/show-me在哪个环节能真正切进去以及批量落地时要注意哪些工程问题。本文会从五个维度展开第一HumanLayer 和/show-me的产品定位与核心能力第二agent 提交的 PR 为什么难审难点到底在哪里第三一套可以拿来对照的“可审查”验收清单第四在 agent 工作流里接 API、设计批量审查任务的通用方法第五常见问题排查和团队最佳实践。我的重点是给你一套能拿到自己项目里验证的方案而不是替某个具体模型或工具背书。1. 核心能力速览先把最基础的信息整理成一张表方便判断这个技能适不适合你当前的研发流程。能力项说明项目类型AI Agent 可观测性与代码审查辅助技能所属方向HumanLayerhuman-in-the-loop 思路下的 agent 工具链能力目标场景AI agent 自动写代码、自动提交 PR 后的人工 code review核心作用把 agent PR 里的“黑盒改动”变成可被人类快速判断的审查证据使用形态以 skill / tool 方式加入 agent 的工具列表具体接入方式需要以官方仓库说明为准硬件要求与 agent 的运行环境强相关托管 API 服务不依赖本机 GPU本地视觉模型则需要单独确认显存批量能力适合在多个 agent 产出多个 PR 后做批量证据汇总但并发上限要看实际服务配置适用读者agent 开发者、代码审查负责人、DevOps / 研发平台工程师看这张表的时候要意识到一个前提/show-me并不是一个“帮你把 PR 写得更长更漂亮”的文案工具。从它被定位成审查辅助技能来看它真正想做的是弥合一个很具体的认知鸿沟——agent 在终端、浏览器、接口调用里做的事情人类 reviewer 在 diff 页面里通常看不到。所以评估/show-me不能只问“它能不能生成截图”而要问四个问题证据能不能追踪到具体 commit证据能不能证明最终代码的行为没有证据时 agent 能不能继续合并 PR这些证据会不会给我们的 review 流程带来额外噪声后面我会围绕这四个问题展开这也是我认为落地/show-me时最需要关心的部分。1.1 这里要特别提醒的三个边界第一/show-me不会替代代码审查。就算 agent 在 PR 描述里附上了一段看起来非常可信的运行记录人类 reviewer 依然需要检查逻辑正确性、边界条件、安全影响和团队规范。第二它并不是“代码正确性证明”。截图或回放只能说明 agent 在某个输入下跑出了某个结果不能说明所有输入都会得到合理结果。也就是说它降低的是理解成本不降低验证责任。第三它能不能用很大程度上取决于团队是否愿意接受“agent 产物走正式工单流程”。如果你的团队现在连人工 PR 都没有规范模板那/show-me这类能力不应该作为第一步先把人类 PR 的 review 规范立起来更重要。2. 为什么 agent 写的 PR 越来越难审查先说结论人工写的 PR 难审大多是因为描述不清楚agent 写的 PR 难审是因为它从生成到提交的整个过程并不出现在 diff 里你看到的是结果不是过程。2.1 AI coding agent 改变了代码提交的粒度过去一个 PR 通常对应一个明确的人类意图修一个 bug、加一个功能、调整一份文档。人类在写代码的时候会自然地把大改动拆成多个小 commit每个 commit 之间有清晰的因果关系。agent 不是这样的。很多 agent 倾向于在一个任务里横跨多个文件改动包括代码、配置、注释、测试、锁文件甚至格式化工具自动修正的部分。这种 PR 单纯从 diff 统计看会显得“很大”但真正的问题不是行数多而是 reviewer 很难判断哪些改动是任务必须的哪些是 agent 顺手做出来的。审查负担从“看代码”变成了“先还原 agent 的决策过程”。2.2 AI 生成的 PR 描述看起来完整但缺少证据现代 AI coding agent 写的 PR 描述通常格式整齐有背景、有改动清单、有测试说明甚至还有自动生成的 release note。但如果你认真看会发现很多描述是“解释型”的不是“证据型”的。解释型描述会说“修复了登录页面在移动端样式错乱的问题。”证据型描述会给出具体的浏览器视口、截图、复现步骤和运行结果。/show-me这样的技能本质上就是推动 agent 从前者走向后者。2.3 reviewer 无法在脑内模拟运行结果这是最容易被低估的一点。一个前端改动即使代码逻辑看起来完全正确人类 reviewer 也很难不做任何运行就直接确认 UI 效果是否符合预期。一个接口重构reviewer 需要知道旧的调用方有哪些、新参数如何透传、数据库字段兼容性如何。agent 在执行这些改动时是有完整上下文的它知道它自己改到了哪一步。但这些上下文不会自动出现在 PR 页面里。如果 agent 只提交 diff 和一段泛泛的描述那 review 就成了“考据”工作每个人都得重新跑一遍环境才能判断。2.4 批量并发让问题放大当团队里只有一个 agent 在辅助开发时人工 reviewer 可以直接和 agent 对话、让它补运行截图、手动重跑代码。但当有多个 agent 在多个仓库里同时提交 PR 时这种“点对点沟通”就不可行了。批量场景下reviewer 需要的是“不打开代码也能先做一轮筛选”的能力。如果一个 PR 能自动带上证据另一个 PR 只有空白描述那审查资源的分配立刻就会变得清晰。这也是show-me这类能力在批量任务中更重要而不是更次要的原因。3. HumanLayer 到底解决什么问题HumanLayer 不是做代码生成的大模型也不是另一个 AI IDE。它更接近一个“人类和 agent 之间的控制层”处理的核心问题是 agent 在自动化执行过程中哪些动作必须停下来等人类确认哪些证据必须留给人来检查。这其实就是 human-in-the-loop。大多数 agent 框架在刚接触这个概念时会简单粗暴地理解成“agent 每走一步都请求一次批准”。这种方案安全但没法用因为 agent 的多数基础操作根本不需要人类参与。真正需要人工介入的往往是那些低成本、高影响、难以自动回滚的动作例如合入 main 分支、修改生产环境配置、覆盖他人代码、触发对外发布。从HumanLayer /show-me这个组合来看它的思路是把“人类审批”继续向前推一步人类不仅要在关键动作上给批准还要在批准之前看到足够多的事实。我们平时说“让 agent 对结果负责”这个说法很含糊。/show-me更实际的落点是让 agent 在请求批准的时候把能支撑“这次改动可以合入”的证据一并交出来而不是只说一句“已测试通过”。3.1 /show-me 不是在展示过程的每一个细节一个很常见的误区是认为可观测性等于“把 agent 在终端里的所有输出都贴到 PR 上”。这会造成严重的信息过载reviewer 反而找不到重点。更合理的理解是/show-me输出的应该是一份“审查所需的最小证据集”。它要包含三部分信息这次改动改变了什么行为在什么输入或场景下验证了这个改变最终结果是否符合预期。至于 agent 中间尝试过多少次、走过哪些弯路这些内容可以放进任务日志但通常不适合直接塞进 PR 描述。从这个角度看/show-me的设计难点其实不在“能不能截图”而在“怎么从大量执行轨迹里挑出人类最需要看的那几个快照”并且把这些快照稳定地关联到代码的最终版本。如果截图是从一次旧的运行结果里取出来的而提交的 commit 又改了代码那这个证据就是负资产会误导 reviewer。3.2 从“看到输出”到“确认意图”对一个 agent 提交的 PR人类 reviewer 真正想确认的并不是“程序有没有输出”而是“agent 有没有准确理解我的意图”。这个判断非常依赖上下文。比如 agent 修一个按钮颜色你不仅要看最终按钮是什么颜色还要看它是不是把所有使用旧颜色的场景都处理干净了。所以show-me不能只对“当前页面状态”做捕获还需要考虑把它放到 diff 上下文里解释。比较稳的做法是让 agent 在交付时回答三类问题改前是什么样改后是什么样影响范围有哪些。换句话说/show-me不只是一个图像生成动作更应该是一个结构化的解释动作。如果只把截图贴上去没有解释这个截图对应的代码位置和验证条件那它依然只是一张没有来源的图片。4. 落地前先验收这些能力因为不同团队接入/show-me的技术栈不同我这里给出一套比较通用的验收标准。它在很多 human-in-the-loop agent 功能上都适用不限定于某个特定项目。4.1 调用链路是否真实你要验证的第一件事是 agent 在什么条件下会真的调用/show-me。它可以被 agent 自己决定调用也可以由宿主环境在 PR 创建前强制调用。这两者的可靠性差别很大。如果只是把工具加进提示词agent 偶尔不调用那你需要在 CI 端加一个硬校验检查 final PR 是否包含了证据标记。一种判断标准是如果 agent 没有产生任何可审查证据PR 就不能进入人类 review 队列。这个策略听起来有点强但它才是保证“每一个 agent PR 都可审查”的前提。让 agent 在需要时展示当然很好但工程实践里非强制能力很容易被跳过尤其是当任务看起来简单、agent 急于交付的时候。4.2 证据是否可追溯到 commitPR 最大的问题是它会变reviewer 要求改动agent 重新 commit然后 PR 更新。如果/show-me生成的截图是在最早一次 commit 时抓的而代码后来改过几轮那这个截图可能已经失效。验收时要设置一个规则证据必须绑定 commit SHA。当 PR head 更新后旧证据要么被标记为过期要么强制重新生成。绝对不应该出现“图片是旧版、代码是新版”还被判定为通过的情况。这会直接摧毁审查者对证据的信任感。4.3 失败场景是否可控当/show-me调用失败时系统应该怎么处理有些团队的做法是忽略并继续有些团队的做法是阻塞 PR。这两种选择没有绝对对错取决于你的风险等级。在测试环境或低风险仓库里失败继续可能影响更小因为你本来也不要求每个 PR 都达到发布级严谨度。但在生产代码或核心架构仓库里证据生成失败应该等同于“没有通过自动检查”。你可以在 UI 上给 reviewer 一个手动忽略的按钮但不能默认绕过。4.4 是否保留人工查看的上下文agent 生成证据后人类 reviewer 打开 PR看到的应该是一份带上下文的审查视图哪个文件改动对应哪张截图哪一次接口调用对应哪个输入输出。不能要求 reviewer 自己根据截图里的文件名去 diff 里寻找对应代码那样可读性依然很差。这个能力很难靠一个 agent 单独解决需要 PR 模板、diff 解析和渲染层配合。团队自建类似系统时可以从“证据和文件路径关联”做起先做到每张截图都标注它来自哪个分支、哪个 commit、哪个命令再逐步完善页面上的一体化展示。5. 为 agent PR 配置“可审查”的最小工作流如果你暂时还没有接入/show-me的 SDK或者想先验证机制是否适合团队可以先搭一个最小工作流。这个工作流不依赖 HumanLayer 的专有接口只复用它背后的审查思路因此可以直接在 GitHub、GitLab 或任意 Git 服务上做实验。5.1 定义一个 PR 描述模板强制要求 agent 生成的 PR 必须包含以下几个段落。这里用 Markdown 写一个示例模板## 变更类型 - [ ] bugfix - [ ] feature - [ ] refactor - [ ] dependency update ## 为什么由 agent 完成这次修改 填写触发这次 agent 任务的原始需求 ## 行为变化 - 改动前描述改动前的可观察行为 - 改动后描述改动后的可观察行为 ## 证据区 show-me://evidence - 验证命令命令 - 运行结果摘要截图或 stdout 关键片段 - 对应 commitcommit SHA ## 影响范围 - 关联模块模块列表 - 需要关注的风险明确说明这个模板的核心不是“让 agent 写更多字”而是让 agent 在提交前进行强制思考行为变化是什么影响范围是什么证据放在哪里。很多 agent 能写出很长的代码但不能稳定回答“你的改动改变了什么行为”这个模板恰好是在推它完成这一步。5.2 在 CI 里加一个简单的证据检查模板定义好之后你需要一个硬性校验。下面是一段基于ghCLI 的 shell 示例逻辑是拉取 PR body检查它是否包含证据区标记。注意这只是一个演示真实接入时需要根据你的 Git 平台和 CI 变量做调整。#!/usr/bin/env bash set -euo pipefail PR_NUMBER${PR_NUMBER:-} if [ -z $PR_NUMBER ]; then echo PR_NUMBER 未设置跳过检查 exit 0 fi gh pr view $PR_NUMBER --json body -q .body /tmp/pr-body.md if grep -q show-me://evidence /tmp/pr-body.md; then echo 证据区存在PR 可以进入人工审查队列 else echo 证据区缺失请让 agent 补充运行结果后再提交审查 exit 1 fi这种检查的意义在于它把“agent 是否提供了可审查材料”变成自动化的门槛而不是依赖 agent 自觉。团队里同时跑多个 agent 时这个门槛能避免大量“空壳 PR”直接涌到 reviewer 面前。5.3 把审批动作抽象成一个接口很多 human-in-the-loop 平台的最后一步都是把“人工确认”封装成一个 API调用方传一个任务 ID服务端记录请求等待人类响应。下面的 Python 代码演示的是通用模式不是某个服务的官方 SDK。你需要根据接入的网关地址、鉴权头和字段名进行替换。import json import os import requests GATEWAY_BASE_URL os.getenv(AI_CONTROL_API_BASE, http://127.0.0.1:8000) TOKEN os.getenv(AI_CONTROL_API_TOKEN, ) def request_human_approval( pr_id: str, evidence_refs: list[str], run_id: str, reviewer: str | None None, ): payload { task_type: pr_review, task_id: run_id, pr_id: pr_id, evidence_refs: evidence_refs, reviewer: reviewer, policy: require_approval_before_merge, } resp requests.post( f{GATEWAY_BASE_URL}/v1/approval-requests, headers{ Content-Type: application/json, Authorization: fBearer {TOKEN}, }, jsonpayload, timeout30, ) if resp.status_code ! 201: raise RuntimeError(f审批请求创建失败: {resp.status_code} {resp.text}) body resp.json() return body.get(approval_url)这段代码真正的价值是拆出了几个关键设计点task_id用于追踪同一轮任务的多次变更evidence_refs接收证据链接列表reviewer可以留空由策略层决定指派给谁policy明确要求合并前必须有人类批准。如果你已经在用某个 agent 框架通常可以在“PR 创建前”挂一个工具调用让它收集本次产物的证据然后调用上述接口等待结果。核心流程是agent 完成任务 - 收集 diff / 测试结果 / 截图 - 调用审批接口 - 阻塞等待 reviewer 确认 - reviewer 通过后 agent 继续进入 merge 阶段6. 批量审查与多任务下发设计当单个 PR 的证据工作流跑通后下一个问题就是批量场景多个 agent、多个仓库、多份 PR 同时出现人工 reviewer 不可能一个个点进去阅读。这时候最好的策略是把“审批请求”变成结构化的队列。6.1 先做风险分级批量场景下不要对每个 PR 一视同仁。你可以根据三个条件来判断一个 agent PR 需要多高级别的人工介入是否改动了核心分支是否会改变线上行为是否涉及安全边界或敏感数据。对于低风险 PR比如纯文档、注释、格式化改动/show-me的证据甚至可以简化为“测试命令无异常 变更内容无逻辑差异”。对于高风险 PR比如生产环境配置、支付相关代码、权限模型改动需要强制生成详细证据并且必须走正式审批链路。分级的好处是避免审查系统被海量低风险请求淹没从而把人的注意力集中到真正危险的改动上。6.2 批量证据的任务模型假设我需要在同一个 review 会话里展示多个 PR 的证据可以设计这样一个请求负载{ batch_review_id: batch_review_2025_001, items: [ { pr: frontend-repo#1280, agent_run_id: agent_run_7f3a, evidence: [ s3://evidence-bucket/frontend-repo/1280/preview.png, s3://evidence-bucket/frontend-repo/1280/test.log ], risk_level: medium }, { pr: api-repo#552, agent_run_id: agent_run_8b21, evidence: [ s3://evidence-bucket/api-repo/552/contract-diff.md, s3://evidence-bucket/api-repo/552/load-test.txt ], risk_level: high } ], action: request_human_review }这种结构化模型的好处是可以在 UI 里做分组、排序和过滤。reviewer 可以先只看 high risk 的条目再按仓库名或 agent 归类低风险条目。所有证据都放到外部存储PR 描述里只放链接和摘要避免 Git 平台页面一次性加载大量图片导致卡顿。6.3 失败重试与补偿机制批量任务不可能永远成功。常见的问题是 agent 生成了证据但对象存储上传失败或者证据过期但 PR 没有被更新。任务队列里要记录状态待审查、审查中、已通过、已驳回、证据过期、生成失败。超时也要设置。如果模型服务响应太慢整个 PR 创建流程就会被拖住。更稳妥的设计是把“生成证据”和“创建 PR”解耦PR 可以先创建成功状态标记为“等待证据”CI 里的后台任务再生成证据、回填到 PR。这种异步方式虽然实现复杂度更高但在 agent 批量写代码时会明显更稳定。7. 效果判断与资源占用观察接入/show-me这类能力后很多人只盯着“有没有截图”而我建议你从四个维度观察效果。7.1 人工审查耗时是否下降这个指标最直接。随机抽取接入前后的 agent PR分别统计从 PR 进入队列到第一次人工反馈的平均时长。如果截图和证据有效reviewer 的第一轮响应时间通常会明显缩短。如果没有任何变化说明证据可能没有命中 reviewer 的决策点或者链接被埋得太深。7.2 合入后 revert 率是否变化证据丰富且准确通常能减少不合规合入但如果证据只覆盖成功路径不覆盖边界和异常反而可能让团队误以为 agent 已经充分验证。所以还要看合入后 revert、hotfix 的数量。一旦发现 revert 增多需要检查证据是否太“表演化”比如只截了正常流程的图没有构造失败用例。7.3 证据生成成本是否可接受生成截图、录屏、调用日志会占用 runner 时间和存储空间。如果每次都生成全量录屏成本会快速上涨。这里有两个常见的优化方向一是按文件变更类型选择证据格式标记为docs的 PR 不需要录屏标记为ui-change的 PR 必须截图二是对同一 commit 多次进队列的任务做缓存避免重复生成。7.4 显存和服务端资源问题需要单独说明的是如果/show-me背后的截图、视觉理解能力由远程 API 提供本机不需要 GPU主要成本是请求量和并发配额。如果你选择自己部署一个视觉模型来辅助生成界面截图解释那就需要按模型的实际规格单测显存不能一键断定多少 G 能跑。更稳妥的方法是先在 CPU 环境跑通任务流程再用 GPU 实例做效果验证。观察资源时可以在服务端记录三类指标每次证据生成的平均耗时证据产物的大小单位时间内的成功率。这三项数据能帮你判断是模型推理瓶颈、存储瓶颈还是任务框架瓶颈。8. 常见问题与排查方法问题现象可能原因排查方式解决思路agent 在 PR 里没有调用 show-me工具权限没打开或提示词里没有把该技能设为强要求查看 agent 运行日志中是否出现过该工具调用显式把该 skill 加入“提交前必须调用”的工具列表PR 描述里有“有证据”但看不到图片截图上传失败或图片链接过期检查对象存储权限和链接有效期证据统一走内部存储并设置长有效期PR 里只放引用 ID截图内容和最终代码不一致提交后 agent 改代码但没重新生成证据对比证据生成时间与 commit 时间增加 CI 检查commit 更新后旧证据标记为过期页面加载大量图片卡顿证据全部内嵌到 PR 描述里查看 PR 页面响应耗时把大图迁移到对象存储PR 里只放缩略图和跳转链接人工审批接口超时审查任务排队过长或服务未扩容检查审批服务日志和任务队列长度设置超时告警增加 worker 数量或走异步审批批量任务里部分 PR 证据为空Agent 在某个任务里异常中断检查 agent run 的退出码增加任务重试机制并在进入人工队列前校验必填字段证据质量看上去“很表演”Agent 只记录了理想路径没覆盖异常输入抽查证据对应的命令有无失败用例在 agent 任务说明中要求补充边界测试和异常输出高噪声 PR 反而增加审查负担没有做风险分级全部都要求完整证据统计各仓库的 PR 审查耗时配置分级策略低风险简略证据高风险强制详细审批9. 最佳实践与合规边界把 agent PR 证据化看起来是技术问题实际上还涉及一个很大的团队协作问题大家到底相不相信 AI agent 提交的改动如果团队信任度低再全面截图也会被要求重做如果信任度太高则会把 agent 生成的证据当成“已验证”直接合入风险很高。最好的状态是让证据成为“人工判断的输入”而不是“自动批准的凭据”。第一从低风险仓库开始试点。不要一上来就把核心生产仓库全部开放给 agent也不要要求所有仓库都强制生成完整证据。先选一个测试充分、回滚方便的服务跑两周再看效果。第二把证据生成放在一条强制链路上。要让 agent “尽量生成”很容易但只有“必须有证据才能进入审查队列”才能保证一致性。如果平台做不到强制就让 CI 检查 PR body 的关键字段。缺证明就自动驳回这个策略会逼着 agent 在提 PR 前把测试和截图做完。第三证据产物要可复现。团队内应规定截图或日志必须附带命令和 commit SHA。任何人都能按相同命令重新执行并验证证据不是捏造的。如果 agent 在沙箱里运行时不要只贴最终截图还要附上沙箱镜像或 lockfile以便 reviewer 判断运行环境是否和真实环境一致。第四注意隐私和数据合规。/show-me可能会把屏幕内容、日志文本、接口响应传给远程模型服务。如果 agent 处理的代码库里包含用户个人信息、生产数据或未公开的商业信息要检查这些数据是否被允许送进外部服务。能内网部署就内网部署不能内网部署就要在授权边界内明确哪些目录允许进入 agent 任务。第五涉及人脸、声音、仿冒生成等更敏感能力时尤其要注意。这里的原理是一样的必须在拿到明确授权和数据合法性确认之后才能做。不要因为 agent 是在沙箱里执行就忽略最终产出对真实用户和版权方的影响。任何要发布或商用的材料都要增加一层人类复核。第六审查证据不等于从物理上消灭风险。agent 产出的 PR 最终合入后依然要经过常规的测试、灰度发布和监控。不要让/show-me截图的“看起来正常”替代灰度流程。建议团队继续保留自动测试、策略检查和回滚机制把这些当成更底层的安全网。第七控制证据噪声。一个 PR 如果贴了 20 张截图、3 段录屏看起来极其充分但真正有效信息可能只有 2 处。证据应该讲究结构和密度而不是堆数量。建议在模板里固定每个 PR 最多放哪几类截图超出的部分放进可折叠的附件链接。10. 总结与下一步/show-me这类能力的最大价值不是让 agent 的 PR “看起来更专业”而是强制 agent 在提交前先思考两个问题我这次改动到底改变了什么我有什么证据支撑这个结论这两个问题如果答不清楚任何基于 agent 的自动化开发都会在人工审查环节遭遇瓶颈无论底层模型有多强。如果你是 agent 开发者或研发平台工程师第一步要做的事并不是立刻接一个技能或工具而是先厘清你的 agent PR 现在缺什么缺截图、缺运行命令、缺风险说明还是缺一个审批闭环找到最痛的点之后再决定用/show-me还是先用 PR 模板和 CI 检查补齐流程。最容易踩的坑是“把证据生成做成花架子”。一个证据只要不能定位到 commit、不能复现、不能解释影响范围它就不可能降低审查成本。更糟的是它还消耗了 agent 的时间和存储资源。所以验证一个/show-me实现成不成功不要看它能生成多少张图要看它能否减少一次真实 review 中的来回确认次数。建议收藏备用先在一个非核心仓库里跑通最小闭环把“PR 进入队列前必须带证据”这个规则定下来再逐步推广到更多项目和更多 agent 任务。后续可以继续扩展的方向包括证据过期自动重生成、多仓库证据聚合仪表盘、把截图和模型输出接入统一的审计日志。这些东西做扎实之后agent 写代码带来的收益才会真正沉淀到交付质量里。 AI Agent提交PR难审查？/show-me让代码审查有据可依
这次我们聊一个更靠近“AI Agent 落地工程”的话题HumanLayer 推出了/show-me技能目标非常直接——让 agent 写的 Pull Request 更容易被人类审查。注意它说的是更容易被“审查”不是更容易被“合并”。这两者差别很大代码能不能跑、跑出来长什么样、改动会影响哪些路径这些在 AI coding agent 越来越常见的今天已经成为研发协作里最容易被低估的风险点。如果你已经习惯了让 agent 帮你修 bug、补单测、做代码重构或者正在规划把这类 agent 接到团队的 Git 工作流里那这篇文章的价值就落在一条主线上先把“agent 产物到底怎么验收”这件事拆清楚再看/show-me在哪个环节能真正切进去以及批量落地时要注意哪些工程问题。本文会从五个维度展开第一HumanLayer 和/show-me的产品定位与核心能力第二agent 提交的 PR 为什么难审难点到底在哪里第三一套可以拿来对照的“可审查”验收清单第四在 agent 工作流里接 API、设计批量审查任务的通用方法第五常见问题排查和团队最佳实践。我的重点是给你一套能拿到自己项目里验证的方案而不是替某个具体模型或工具背书。1. 核心能力速览先把最基础的信息整理成一张表方便判断这个技能适不适合你当前的研发流程。能力项说明项目类型AI Agent 可观测性与代码审查辅助技能所属方向HumanLayerhuman-in-the-loop 思路下的 agent 工具链能力目标场景AI agent 自动写代码、自动提交 PR 后的人工 code review核心作用把 agent PR 里的“黑盒改动”变成可被人类快速判断的审查证据使用形态以 skill / tool 方式加入 agent 的工具列表具体接入方式需要以官方仓库说明为准硬件要求与 agent 的运行环境强相关托管 API 服务不依赖本机 GPU本地视觉模型则需要单独确认显存批量能力适合在多个 agent 产出多个 PR 后做批量证据汇总但并发上限要看实际服务配置适用读者agent 开发者、代码审查负责人、DevOps / 研发平台工程师看这张表的时候要意识到一个前提/show-me并不是一个“帮你把 PR 写得更长更漂亮”的文案工具。从它被定位成审查辅助技能来看它真正想做的是弥合一个很具体的认知鸿沟——agent 在终端、浏览器、接口调用里做的事情人类 reviewer 在 diff 页面里通常看不到。所以评估/show-me不能只问“它能不能生成截图”而要问四个问题证据能不能追踪到具体 commit证据能不能证明最终代码的行为没有证据时 agent 能不能继续合并 PR这些证据会不会给我们的 review 流程带来额外噪声后面我会围绕这四个问题展开这也是我认为落地/show-me时最需要关心的部分。1.1 这里要特别提醒的三个边界第一/show-me不会替代代码审查。就算 agent 在 PR 描述里附上了一段看起来非常可信的运行记录人类 reviewer 依然需要检查逻辑正确性、边界条件、安全影响和团队规范。第二它并不是“代码正确性证明”。截图或回放只能说明 agent 在某个输入下跑出了某个结果不能说明所有输入都会得到合理结果。也就是说它降低的是理解成本不降低验证责任。第三它能不能用很大程度上取决于团队是否愿意接受“agent 产物走正式工单流程”。如果你的团队现在连人工 PR 都没有规范模板那/show-me这类能力不应该作为第一步先把人类 PR 的 review 规范立起来更重要。2. 为什么 agent 写的 PR 越来越难审查先说结论人工写的 PR 难审大多是因为描述不清楚agent 写的 PR 难审是因为它从生成到提交的整个过程并不出现在 diff 里你看到的是结果不是过程。2.1 AI coding agent 改变了代码提交的粒度过去一个 PR 通常对应一个明确的人类意图修一个 bug、加一个功能、调整一份文档。人类在写代码的时候会自然地把大改动拆成多个小 commit每个 commit 之间有清晰的因果关系。agent 不是这样的。很多 agent 倾向于在一个任务里横跨多个文件改动包括代码、配置、注释、测试、锁文件甚至格式化工具自动修正的部分。这种 PR 单纯从 diff 统计看会显得“很大”但真正的问题不是行数多而是 reviewer 很难判断哪些改动是任务必须的哪些是 agent 顺手做出来的。审查负担从“看代码”变成了“先还原 agent 的决策过程”。2.2 AI 生成的 PR 描述看起来完整但缺少证据现代 AI coding agent 写的 PR 描述通常格式整齐有背景、有改动清单、有测试说明甚至还有自动生成的 release note。但如果你认真看会发现很多描述是“解释型”的不是“证据型”的。解释型描述会说“修复了登录页面在移动端样式错乱的问题。”证据型描述会给出具体的浏览器视口、截图、复现步骤和运行结果。/show-me这样的技能本质上就是推动 agent 从前者走向后者。2.3 reviewer 无法在脑内模拟运行结果这是最容易被低估的一点。一个前端改动即使代码逻辑看起来完全正确人类 reviewer 也很难不做任何运行就直接确认 UI 效果是否符合预期。一个接口重构reviewer 需要知道旧的调用方有哪些、新参数如何透传、数据库字段兼容性如何。agent 在执行这些改动时是有完整上下文的它知道它自己改到了哪一步。但这些上下文不会自动出现在 PR 页面里。如果 agent 只提交 diff 和一段泛泛的描述那 review 就成了“考据”工作每个人都得重新跑一遍环境才能判断。2.4 批量并发让问题放大当团队里只有一个 agent 在辅助开发时人工 reviewer 可以直接和 agent 对话、让它补运行截图、手动重跑代码。但当有多个 agent 在多个仓库里同时提交 PR 时这种“点对点沟通”就不可行了。批量场景下reviewer 需要的是“不打开代码也能先做一轮筛选”的能力。如果一个 PR 能自动带上证据另一个 PR 只有空白描述那审查资源的分配立刻就会变得清晰。这也是show-me这类能力在批量任务中更重要而不是更次要的原因。3. HumanLayer 到底解决什么问题HumanLayer 不是做代码生成的大模型也不是另一个 AI IDE。它更接近一个“人类和 agent 之间的控制层”处理的核心问题是 agent 在自动化执行过程中哪些动作必须停下来等人类确认哪些证据必须留给人来检查。这其实就是 human-in-the-loop。大多数 agent 框架在刚接触这个概念时会简单粗暴地理解成“agent 每走一步都请求一次批准”。这种方案安全但没法用因为 agent 的多数基础操作根本不需要人类参与。真正需要人工介入的往往是那些低成本、高影响、难以自动回滚的动作例如合入 main 分支、修改生产环境配置、覆盖他人代码、触发对外发布。从HumanLayer /show-me这个组合来看它的思路是把“人类审批”继续向前推一步人类不仅要在关键动作上给批准还要在批准之前看到足够多的事实。我们平时说“让 agent 对结果负责”这个说法很含糊。/show-me更实际的落点是让 agent 在请求批准的时候把能支撑“这次改动可以合入”的证据一并交出来而不是只说一句“已测试通过”。3.1 /show-me 不是在展示过程的每一个细节一个很常见的误区是认为可观测性等于“把 agent 在终端里的所有输出都贴到 PR 上”。这会造成严重的信息过载reviewer 反而找不到重点。更合理的理解是/show-me输出的应该是一份“审查所需的最小证据集”。它要包含三部分信息这次改动改变了什么行为在什么输入或场景下验证了这个改变最终结果是否符合预期。至于 agent 中间尝试过多少次、走过哪些弯路这些内容可以放进任务日志但通常不适合直接塞进 PR 描述。从这个角度看/show-me的设计难点其实不在“能不能截图”而在“怎么从大量执行轨迹里挑出人类最需要看的那几个快照”并且把这些快照稳定地关联到代码的最终版本。如果截图是从一次旧的运行结果里取出来的而提交的 commit 又改了代码那这个证据就是负资产会误导 reviewer。3.2 从“看到输出”到“确认意图”对一个 agent 提交的 PR人类 reviewer 真正想确认的并不是“程序有没有输出”而是“agent 有没有准确理解我的意图”。这个判断非常依赖上下文。比如 agent 修一个按钮颜色你不仅要看最终按钮是什么颜色还要看它是不是把所有使用旧颜色的场景都处理干净了。所以show-me不能只对“当前页面状态”做捕获还需要考虑把它放到 diff 上下文里解释。比较稳的做法是让 agent 在交付时回答三类问题改前是什么样改后是什么样影响范围有哪些。换句话说/show-me不只是一个图像生成动作更应该是一个结构化的解释动作。如果只把截图贴上去没有解释这个截图对应的代码位置和验证条件那它依然只是一张没有来源的图片。4. 落地前先验收这些能力因为不同团队接入/show-me的技术栈不同我这里给出一套比较通用的验收标准。它在很多 human-in-the-loop agent 功能上都适用不限定于某个特定项目。4.1 调用链路是否真实你要验证的第一件事是 agent 在什么条件下会真的调用/show-me。它可以被 agent 自己决定调用也可以由宿主环境在 PR 创建前强制调用。这两者的可靠性差别很大。如果只是把工具加进提示词agent 偶尔不调用那你需要在 CI 端加一个硬校验检查 final PR 是否包含了证据标记。一种判断标准是如果 agent 没有产生任何可审查证据PR 就不能进入人类 review 队列。这个策略听起来有点强但它才是保证“每一个 agent PR 都可审查”的前提。让 agent 在需要时展示当然很好但工程实践里非强制能力很容易被跳过尤其是当任务看起来简单、agent 急于交付的时候。4.2 证据是否可追溯到 commitPR 最大的问题是它会变reviewer 要求改动agent 重新 commit然后 PR 更新。如果/show-me生成的截图是在最早一次 commit 时抓的而代码后来改过几轮那这个截图可能已经失效。验收时要设置一个规则证据必须绑定 commit SHA。当 PR head 更新后旧证据要么被标记为过期要么强制重新生成。绝对不应该出现“图片是旧版、代码是新版”还被判定为通过的情况。这会直接摧毁审查者对证据的信任感。4.3 失败场景是否可控当/show-me调用失败时系统应该怎么处理有些团队的做法是忽略并继续有些团队的做法是阻塞 PR。这两种选择没有绝对对错取决于你的风险等级。在测试环境或低风险仓库里失败继续可能影响更小因为你本来也不要求每个 PR 都达到发布级严谨度。但在生产代码或核心架构仓库里证据生成失败应该等同于“没有通过自动检查”。你可以在 UI 上给 reviewer 一个手动忽略的按钮但不能默认绕过。4.4 是否保留人工查看的上下文agent 生成证据后人类 reviewer 打开 PR看到的应该是一份带上下文的审查视图哪个文件改动对应哪张截图哪一次接口调用对应哪个输入输出。不能要求 reviewer 自己根据截图里的文件名去 diff 里寻找对应代码那样可读性依然很差。这个能力很难靠一个 agent 单独解决需要 PR 模板、diff 解析和渲染层配合。团队自建类似系统时可以从“证据和文件路径关联”做起先做到每张截图都标注它来自哪个分支、哪个 commit、哪个命令再逐步完善页面上的一体化展示。5. 为 agent PR 配置“可审查”的最小工作流如果你暂时还没有接入/show-me的 SDK或者想先验证机制是否适合团队可以先搭一个最小工作流。这个工作流不依赖 HumanLayer 的专有接口只复用它背后的审查思路因此可以直接在 GitHub、GitLab 或任意 Git 服务上做实验。5.1 定义一个 PR 描述模板强制要求 agent 生成的 PR 必须包含以下几个段落。这里用 Markdown 写一个示例模板## 变更类型 - [ ] bugfix - [ ] feature - [ ] refactor - [ ] dependency update ## 为什么由 agent 完成这次修改 填写触发这次 agent 任务的原始需求 ## 行为变化 - 改动前描述改动前的可观察行为 - 改动后描述改动后的可观察行为 ## 证据区 show-me://evidence - 验证命令命令 - 运行结果摘要截图或 stdout 关键片段 - 对应 commitcommit SHA ## 影响范围 - 关联模块模块列表 - 需要关注的风险明确说明这个模板的核心不是“让 agent 写更多字”而是让 agent 在提交前进行强制思考行为变化是什么影响范围是什么证据放在哪里。很多 agent 能写出很长的代码但不能稳定回答“你的改动改变了什么行为”这个模板恰好是在推它完成这一步。5.2 在 CI 里加一个简单的证据检查模板定义好之后你需要一个硬性校验。下面是一段基于ghCLI 的 shell 示例逻辑是拉取 PR body检查它是否包含证据区标记。注意这只是一个演示真实接入时需要根据你的 Git 平台和 CI 变量做调整。#!/usr/bin/env bash set -euo pipefail PR_NUMBER${PR_NUMBER:-} if [ -z $PR_NUMBER ]; then echo PR_NUMBER 未设置跳过检查 exit 0 fi gh pr view $PR_NUMBER --json body -q .body /tmp/pr-body.md if grep -q show-me://evidence /tmp/pr-body.md; then echo 证据区存在PR 可以进入人工审查队列 else echo 证据区缺失请让 agent 补充运行结果后再提交审查 exit 1 fi这种检查的意义在于它把“agent 是否提供了可审查材料”变成自动化的门槛而不是依赖 agent 自觉。团队里同时跑多个 agent 时这个门槛能避免大量“空壳 PR”直接涌到 reviewer 面前。5.3 把审批动作抽象成一个接口很多 human-in-the-loop 平台的最后一步都是把“人工确认”封装成一个 API调用方传一个任务 ID服务端记录请求等待人类响应。下面的 Python 代码演示的是通用模式不是某个服务的官方 SDK。你需要根据接入的网关地址、鉴权头和字段名进行替换。import json import os import requests GATEWAY_BASE_URL os.getenv(AI_CONTROL_API_BASE, http://127.0.0.1:8000) TOKEN os.getenv(AI_CONTROL_API_TOKEN, ) def request_human_approval( pr_id: str, evidence_refs: list[str], run_id: str, reviewer: str | None None, ): payload { task_type: pr_review, task_id: run_id, pr_id: pr_id, evidence_refs: evidence_refs, reviewer: reviewer, policy: require_approval_before_merge, } resp requests.post( f{GATEWAY_BASE_URL}/v1/approval-requests, headers{ Content-Type: application/json, Authorization: fBearer {TOKEN}, }, jsonpayload, timeout30, ) if resp.status_code ! 201: raise RuntimeError(f审批请求创建失败: {resp.status_code} {resp.text}) body resp.json() return body.get(approval_url)这段代码真正的价值是拆出了几个关键设计点task_id用于追踪同一轮任务的多次变更evidence_refs接收证据链接列表reviewer可以留空由策略层决定指派给谁policy明确要求合并前必须有人类批准。如果你已经在用某个 agent 框架通常可以在“PR 创建前”挂一个工具调用让它收集本次产物的证据然后调用上述接口等待结果。核心流程是agent 完成任务 - 收集 diff / 测试结果 / 截图 - 调用审批接口 - 阻塞等待 reviewer 确认 - reviewer 通过后 agent 继续进入 merge 阶段6. 批量审查与多任务下发设计当单个 PR 的证据工作流跑通后下一个问题就是批量场景多个 agent、多个仓库、多份 PR 同时出现人工 reviewer 不可能一个个点进去阅读。这时候最好的策略是把“审批请求”变成结构化的队列。6.1 先做风险分级批量场景下不要对每个 PR 一视同仁。你可以根据三个条件来判断一个 agent PR 需要多高级别的人工介入是否改动了核心分支是否会改变线上行为是否涉及安全边界或敏感数据。对于低风险 PR比如纯文档、注释、格式化改动/show-me的证据甚至可以简化为“测试命令无异常 变更内容无逻辑差异”。对于高风险 PR比如生产环境配置、支付相关代码、权限模型改动需要强制生成详细证据并且必须走正式审批链路。分级的好处是避免审查系统被海量低风险请求淹没从而把人的注意力集中到真正危险的改动上。6.2 批量证据的任务模型假设我需要在同一个 review 会话里展示多个 PR 的证据可以设计这样一个请求负载{ batch_review_id: batch_review_2025_001, items: [ { pr: frontend-repo#1280, agent_run_id: agent_run_7f3a, evidence: [ s3://evidence-bucket/frontend-repo/1280/preview.png, s3://evidence-bucket/frontend-repo/1280/test.log ], risk_level: medium }, { pr: api-repo#552, agent_run_id: agent_run_8b21, evidence: [ s3://evidence-bucket/api-repo/552/contract-diff.md, s3://evidence-bucket/api-repo/552/load-test.txt ], risk_level: high } ], action: request_human_review }这种结构化模型的好处是可以在 UI 里做分组、排序和过滤。reviewer 可以先只看 high risk 的条目再按仓库名或 agent 归类低风险条目。所有证据都放到外部存储PR 描述里只放链接和摘要避免 Git 平台页面一次性加载大量图片导致卡顿。6.3 失败重试与补偿机制批量任务不可能永远成功。常见的问题是 agent 生成了证据但对象存储上传失败或者证据过期但 PR 没有被更新。任务队列里要记录状态待审查、审查中、已通过、已驳回、证据过期、生成失败。超时也要设置。如果模型服务响应太慢整个 PR 创建流程就会被拖住。更稳妥的设计是把“生成证据”和“创建 PR”解耦PR 可以先创建成功状态标记为“等待证据”CI 里的后台任务再生成证据、回填到 PR。这种异步方式虽然实现复杂度更高但在 agent 批量写代码时会明显更稳定。7. 效果判断与资源占用观察接入/show-me这类能力后很多人只盯着“有没有截图”而我建议你从四个维度观察效果。7.1 人工审查耗时是否下降这个指标最直接。随机抽取接入前后的 agent PR分别统计从 PR 进入队列到第一次人工反馈的平均时长。如果截图和证据有效reviewer 的第一轮响应时间通常会明显缩短。如果没有任何变化说明证据可能没有命中 reviewer 的决策点或者链接被埋得太深。7.2 合入后 revert 率是否变化证据丰富且准确通常能减少不合规合入但如果证据只覆盖成功路径不覆盖边界和异常反而可能让团队误以为 agent 已经充分验证。所以还要看合入后 revert、hotfix 的数量。一旦发现 revert 增多需要检查证据是否太“表演化”比如只截了正常流程的图没有构造失败用例。7.3 证据生成成本是否可接受生成截图、录屏、调用日志会占用 runner 时间和存储空间。如果每次都生成全量录屏成本会快速上涨。这里有两个常见的优化方向一是按文件变更类型选择证据格式标记为docs的 PR 不需要录屏标记为ui-change的 PR 必须截图二是对同一 commit 多次进队列的任务做缓存避免重复生成。7.4 显存和服务端资源问题需要单独说明的是如果/show-me背后的截图、视觉理解能力由远程 API 提供本机不需要 GPU主要成本是请求量和并发配额。如果你选择自己部署一个视觉模型来辅助生成界面截图解释那就需要按模型的实际规格单测显存不能一键断定多少 G 能跑。更稳妥的方法是先在 CPU 环境跑通任务流程再用 GPU 实例做效果验证。观察资源时可以在服务端记录三类指标每次证据生成的平均耗时证据产物的大小单位时间内的成功率。这三项数据能帮你判断是模型推理瓶颈、存储瓶颈还是任务框架瓶颈。8. 常见问题与排查方法问题现象可能原因排查方式解决思路agent 在 PR 里没有调用 show-me工具权限没打开或提示词里没有把该技能设为强要求查看 agent 运行日志中是否出现过该工具调用显式把该 skill 加入“提交前必须调用”的工具列表PR 描述里有“有证据”但看不到图片截图上传失败或图片链接过期检查对象存储权限和链接有效期证据统一走内部存储并设置长有效期PR 里只放引用 ID截图内容和最终代码不一致提交后 agent 改代码但没重新生成证据对比证据生成时间与 commit 时间增加 CI 检查commit 更新后旧证据标记为过期页面加载大量图片卡顿证据全部内嵌到 PR 描述里查看 PR 页面响应耗时把大图迁移到对象存储PR 里只放缩略图和跳转链接人工审批接口超时审查任务排队过长或服务未扩容检查审批服务日志和任务队列长度设置超时告警增加 worker 数量或走异步审批批量任务里部分 PR 证据为空Agent 在某个任务里异常中断检查 agent run 的退出码增加任务重试机制并在进入人工队列前校验必填字段证据质量看上去“很表演”Agent 只记录了理想路径没覆盖异常输入抽查证据对应的命令有无失败用例在 agent 任务说明中要求补充边界测试和异常输出高噪声 PR 反而增加审查负担没有做风险分级全部都要求完整证据统计各仓库的 PR 审查耗时配置分级策略低风险简略证据高风险强制详细审批9. 最佳实践与合规边界把 agent PR 证据化看起来是技术问题实际上还涉及一个很大的团队协作问题大家到底相不相信 AI agent 提交的改动如果团队信任度低再全面截图也会被要求重做如果信任度太高则会把 agent 生成的证据当成“已验证”直接合入风险很高。最好的状态是让证据成为“人工判断的输入”而不是“自动批准的凭据”。第一从低风险仓库开始试点。不要一上来就把核心生产仓库全部开放给 agent也不要要求所有仓库都强制生成完整证据。先选一个测试充分、回滚方便的服务跑两周再看效果。第二把证据生成放在一条强制链路上。要让 agent “尽量生成”很容易但只有“必须有证据才能进入审查队列”才能保证一致性。如果平台做不到强制就让 CI 检查 PR body 的关键字段。缺证明就自动驳回这个策略会逼着 agent 在提 PR 前把测试和截图做完。第三证据产物要可复现。团队内应规定截图或日志必须附带命令和 commit SHA。任何人都能按相同命令重新执行并验证证据不是捏造的。如果 agent 在沙箱里运行时不要只贴最终截图还要附上沙箱镜像或 lockfile以便 reviewer 判断运行环境是否和真实环境一致。第四注意隐私和数据合规。/show-me可能会把屏幕内容、日志文本、接口响应传给远程模型服务。如果 agent 处理的代码库里包含用户个人信息、生产数据或未公开的商业信息要检查这些数据是否被允许送进外部服务。能内网部署就内网部署不能内网部署就要在授权边界内明确哪些目录允许进入 agent 任务。第五涉及人脸、声音、仿冒生成等更敏感能力时尤其要注意。这里的原理是一样的必须在拿到明确授权和数据合法性确认之后才能做。不要因为 agent 是在沙箱里执行就忽略最终产出对真实用户和版权方的影响。任何要发布或商用的材料都要增加一层人类复核。第六审查证据不等于从物理上消灭风险。agent 产出的 PR 最终合入后依然要经过常规的测试、灰度发布和监控。不要让/show-me截图的“看起来正常”替代灰度流程。建议团队继续保留自动测试、策略检查和回滚机制把这些当成更底层的安全网。第七控制证据噪声。一个 PR 如果贴了 20 张截图、3 段录屏看起来极其充分但真正有效信息可能只有 2 处。证据应该讲究结构和密度而不是堆数量。建议在模板里固定每个 PR 最多放哪几类截图超出的部分放进可折叠的附件链接。10. 总结与下一步/show-me这类能力的最大价值不是让 agent 的 PR “看起来更专业”而是强制 agent 在提交前先思考两个问题我这次改动到底改变了什么我有什么证据支撑这个结论这两个问题如果答不清楚任何基于 agent 的自动化开发都会在人工审查环节遭遇瓶颈无论底层模型有多强。如果你是 agent 开发者或研发平台工程师第一步要做的事并不是立刻接一个技能或工具而是先厘清你的 agent PR 现在缺什么缺截图、缺运行命令、缺风险说明还是缺一个审批闭环找到最痛的点之后再决定用/show-me还是先用 PR 模板和 CI 检查补齐流程。最容易踩的坑是“把证据生成做成花架子”。一个证据只要不能定位到 commit、不能复现、不能解释影响范围它就不可能降低审查成本。更糟的是它还消耗了 agent 的时间和存储资源。所以验证一个/show-me实现成不成功不要看它能生成多少张图要看它能否减少一次真实 review 中的来回确认次数。建议收藏备用先在一个非核心仓库里跑通最小闭环把“PR 进入队列前必须带证据”这个规则定下来再逐步推广到更多项目和更多 agent 任务。后续可以继续扩展的方向包括证据过期自动重生成、多仓库证据聚合仪表盘、把截图和模型输出接入统一的审计日志。这些东西做扎实之后agent 写代码带来的收益才会真正沉淀到交付质量里。