人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载导读本篇技术指南围绕 GSD-2GitHub 加速计划 / gs / gsd-2一个面向 Agent 的元提示、上下文工程与规格驱动开发系统中负责用户验收测试UAT执行的 auto-mode 单元提示词 run-uat.md 展开完整讲解 UAT 检查的执行规则、六种验收模式、证据采集规范、PASS/FAIL/PARTIAL/NEEDS-HUMAN 判定语义以及结果如何通过gsd_summary_save以 ASSESSMENT 工件形式落库落盘。读完本文你将掌握在 GSD auto-mode 工作流中切片slice完成后如何自动化执行验收、如何避免把主观体验类检查降级成伪证、如何写出可被调度门verdict gate正确消费的验收结果并获得源码与集成测试级别的原理支撑。一、run-uat 提示词在 GSD auto-mode 中的角色在 GSD-2 的自动化工作流中每一个里程碑milestone被拆分为若干切片slice切片完成后需要经过验收UAT才能进入后续规划与收尾。run-uat.md就是这一验收单元Unit注入给执行 Agent 的完整指令模板其单元头声明为## UNIT: Run UAT — {{milestoneId}}/{{sliceId}}提示词通过{{...}}占位符在派发时被替换为真实值由 auto-prompts.ts 中的buildRunUatPrompt()完成模板渲染。该函数接收mid、sliceId、uatPath、uatContent与工作区根目录随后通过composeUnitContext(run-uat, ...)组装预加载上下文——只内联 UAT 文件正文slice-uat切片摘要slice-summary以摘要摘录形式提供项目级上下文则标记为按需读取on-demand避免验收单元为完整收尾上下文支付额外 token使用resolveEffectiveUatType(uatContent)判定验收模式并写入模板变量uatType计算结果文件路径uatResultPath固定指向切片的 ASSESSMENT 工件S{sid}-ASSESSMENT.md注入技能激活块{{skillActivation}}最终返回可执行的提示词。在 auto-dispatch.ts 中派发器先调用checkNeedsRunUat()判断是否应该派发验收单元再调用buildRunUatPrompt()构造提示词——判定是否需要验收与渲染验收指令是两个相互独立的阶段。二、单元运行约束工作目录与预加载上下文提示词开头对执行环境给出两条硬性约束这是避免 Agent 跑错目录、重复读文件的关键工作目录锁定所有文件读取、写入和 shell 命令必须相对于{{workingDirectory}}执行且明确禁止cd到任何其他目录上下文预加载相关上下文已在提示词中通过{{inlinedContext}}预先注入Agent 应立即开始工作不得重新读取这些文件。后一条约束在 buildRunUatPrompt 中有具体实现内联上下文组装完成后会经过capPreamble()做长度封顶超出预算时丢弃尾部并记录丢弃字符数再叠加上下文模式块后注入提示词。从源码结构可以推断这种先内联、后裁剪的机制让验收单元在保持证据完整性的同时不会因历史上下文过长而挤占执行模型的有效窗口。技能激活skillActivation{{skillActivation}}由buildSkillActivationBlock()生成如果存在与当前单元清晰匹配的已安装技能则激活否则跳过显式技能激活、按既定工作流继续执行。这意味着 run-uat 单元是自包含的不依赖外部技能即可独立完成验收任务。三、UAT 输入、输出与验收模式判定提示词中显式注入三个关键输入变量含义实际取值示例{{uatPath}}待执行的 UAT 规格文件路径.gsd/milestones/M001/slices/S01/S01-UAT.md{{uatResultPath}}验收结果文件路径.gsd/milestones/M001/slices/S01/S01-ASSESSMENT.md{{uatType}}从 UAT 文件解析出的验收模式artifact-driven/live-runtime/ ...UAT 规格文件没有 YAML frontmatter验收模式是从正文## UAT Type小节中读取- UAT mode: 关键词列表项解析出来的。核心实现位于 files.ts 的extractUatType()解析采用仅取首关键字策略例如mixed (artifact-driven live-runtime)归一为mixed大小写不敏感解析前统一toLowerCase()支持artifact-driven、browser-executable、runtime-executable、live-runtime、human-experience、mixed六种类型当## UAT Type小节缺失、小节内没有UAT mode:列表项、或值不以任一已知关键词开头时返回undefined。此外 verdict-parser.ts 的getUatType()提供兜底当解析不出类型时默认按artifact-driven处理——这是整个代码库沿用的默认验收模式。模式升级artifact-driven → browser-executableauto-prompts.ts 中的resolveEffectiveUatType()实现了一个重要增强当 UAT 文件声明artifact-driven、但正文包含浏览器可观测browser-observable要求文本时自动升级为browser-executable。集成测试 run-uat.test.ts 验证了这一点包含Open index.html in a browser等步骤的 UAT 会被解析为browser-executable并注入use browser tools指令。这意味着单纯按文件静态标注模式是不够的——系统会结合内容真实可执行性动态校正。四、六种 UAT 验收模式与自动化规则提示词为每一种模式定义了明确的执行边界核心原则是以该模式允许的真实深度执行每一条检查不得把实时/主观检查降级为廉价的工件检查来换取 PASS。模式自动化规则适用场景artifact-driven用 shell 命令、脚本、文件读取和工件结构检查验证静态产物、生成文件、目录结构browser-executable用浏览器工具导航到目标 URL 验证预期行为截图留证逐条断言记录前端页面、交互行为runtime-executable执行指定命令/脚本捕获 stdout/stderr按退出码与输出判定CLI 工具、脚本、可执行程序live-runtime走真实运行时路径必要时启动/连接应用或服务结合浏览器/运行时/网络检查验证可观测行为服务端应用、端到端链路mixed运行所有可自动化的工件检查与运行时检查显式分离剩余的人类专属检查混合验收场景human-experience自动化设置、前置条件、截图、日志与客观检查但不得伪造主观 PASS体验性、品味性、纯人类判断类检查标记为NEEDS-HUMANUI 体验、可用性、主观评估对于human-experience模式提示词进一步给出判定细则当所有可自动化检查成功时即使存在遗留的NEEDS-HUMAN人类检查整体结论仍可判PASS只有当可自动化检查本身无法得出结论时才使用PARTIAL。模式与 PARTIAL 的兼容性源码佐证这条语义并非仅存在于提示词文本中而是被硬编码进判定逻辑。verdict-parser.ts 定义了const PARTIAL_ELIGIBLE_UAT_TYPES [mixed, human-experience, live-runtime]; export function isAcceptableUatVerdict(verdict: string, uatType: UatType | undefined): boolean { if (UAT_ACCEPTABLE_VERDICTS.includes(verdict)) return true; if (verdict partial uatType PARTIAL_ELIGIBLE_UAT_TYPES.includes(uatType)) return true; return false; }即pass/passed对任意模式都可接受partial只对包含不可自动化人类检查的三种模式可接受。artifact-driven、browser-executable、runtime-executable属于完全可自动化模式不允许用 PARTIAL 放行——这一契约在 run-uat.test.ts 中有逐条断言。五、证据工具选择原则与逐项检查记录格式提示词要求选择能诚实证明该检查的最轻量工具给出的证据手段包括bash运行 shell 命令grep/rg对文件做内容校验node或其他脚本调用直接读取文件并验证内容检查预期工件存在且结构正确对实时/运行时/UI 检查在浏览器中走真实流程并检查运行时/网络/控制台状态当某条检查无法诚实自动化时收集所能获得的最佳客观证据并标记NEEDS-HUMAN。对每条检查Agent 必须记录四要素检查描述取自 UAT 文件证据模式artifact、runtime或human-follow-up所执行的命令或动作实际观察到的结果以及PASS、FAIL或NEEDS-HUMAN判定。这套先选最轻证据、逐条留痕、诚实标记的规范保证了验收报告既可用于自动化门禁判定也可回溯人工复核。六、总体判定语义PASS / FAIL / PARTIAL / NEEDS-HUMAN提示词明确区分三种总体结论并强调PARTIAL与NEEDS-HUMAN不是一回事PASS— 所有可自动化检查全部通过。剩余确实需要人类判断的检查以NEEDS-HUMAN标记并附清晰的人工复核指引。这是 mixed / human-experience / live-runtime 模式在可自动化部分全部成功时的正确结论FAIL— 存在一条或多条可自动化检查失败PARTIAL— 一条或多条可自动化检查被跳过或结果不确定。它仅在Agent 本应自动化却无法判定通过/失败时使用不等同于NEEDS-HUMAN。集成测试 run-uat.test.ts 验证了提示词确实允许在人类检查遗留为 NEEDS-HUMAN 时给出 PASS且不强制 human-experience 模式在可自动化检查通过时使用 PARTIAL——提示词中不包含use an overall verdict ofPARTIAL字样。调度门如何消费 verdictverdict的消费逻辑集中在 auto-dispatch.tsUAT 门禁与verdict-parser.ts的isAcceptableUatVerdict()。验收结果写入 ASSESSMENT 文件后complete-milestone等后续单元的派发会被非 PASS 结论拦截相关守卫测试见 dispatch-complete-milestone-guard.test.ts当uat_dispatch开启且 UAT 结论缺失或非 PASS 时完成里程碑的派发被阻止。七、结果持久化gsd_summary_save 与 ASSESSMENT 工件提示词强制要求结束前必须调用gsd_summary_save携带milestone_id: {{milestoneId}}、slice_id: {{sliceId}}、artifact_type: ASSESSMENT将完整 UAT 结果 Markdown 作为content传入——文件路径由工具自动计算并同时持久化到数据库与磁盘。gsd_summary_save工具定义于 db-tools.ts其执行逻辑委托给 workflow-tool-executors.ts 的executeSummarySave()通过ensureDbOpen保证数据库可用后写入。工具还注册了历史别名gsd_save_summary以兼容旧调用。它支持的工件类型包括 SUMMARY、RESEARCH、CONTEXT、ASSESSMENT、CONTEXT-DRAFT、PROJECT、PROJECT-DRAFT、REQUIREMENTS、REQUIREMENTS-DRAFT 等。验收结果标准格式提示词给出了结果内容的规范模板--- sliceId: {{sliceId}} uatType: {{uatType}} verdict: PASS | FAIL | PARTIAL date: ISO 8601 timestamp --- # UAT Result — {{sliceId}} ## Checks | Check | Mode | Result | Notes | |-------|------|--------|-------| | 检查描述 | artifact / runtime / human-follow-up | PASS / FAIL / NEEDS-HUMAN | 观察输出、证据或原因 | ## Overall Verdict PASS / FAIL / PARTIAL — 一句话总结 ## Notes 额外上下文、遇到的错误、采集到的截图/日志、仍需的人工跟进YAML frontmatter 中的verdict是机器可读的关键字段。verdict-parser.ts 的extractVerdict()优先从 frontmatter 提取并做归一化小写化、passed→pass作为兜底它还支持从 Markdown 正文中识别**Verdict:** PASS这类模式用于人工手写结果对应回归 #2960。防重复派发幂等性——回归 #2644为什么结果要写进 ASSESSMENT 而不是写回 UAT 规格文件答案在 checkNeedsRunUat() 的跳过逻辑中优先走数据库路径gsd-db数据库不可用时回退到基于 ROADMAP 勾选状态的纯文件路径对每个已完成切片先检查 UAT 文件是否已含 verdict含则跳过同时检查 ASSESSMENT 文件是否已含 verdict——这是回归 #2644 的修复点run-uat 提示词把结论写入S{sid}-ASSESSMENT.md若只检查 UAT 文件会导致已验收却反复重新派发的卡死循环无 ASSESSMENT 文件时不产生误跳过ASSESSMENT 存在但无 verdict 也不抑制派发最终由shouldDispatchUatForContent()决定uat_dispatch开启、或 UAT 类型非 artifact-driven、或正文含浏览器要求时派发。上述 5 个分支全部在 run-uat.test.ts 中有对应集成测试stale replay guard、ASSESSMENT verdict 跳过、无 ASSESSMENT 正常派发、ASSESSMENT 无 verdict 不跳过等。八、UAT 派发的开关配置UAT 自动化派发由偏好项uat_dispatch控制类型为 boolean默认false置为true时切片完成后自动派发验收单元失败会暂停后续流程见 preferences-reference.md但该开关不影响含运行时/浏览器证据要求的 UATshouldDispatchUatForContent()表明只要 UAT 类型非 artifact-driven 或正文含浏览器可观测文本即使开关关闭也会派发对应测试见 run-uat.test.ts最终切片的浏览器可观测 UAT 在uat_dispatch关闭时仍必须运行。偏好项可通过偏好向导或配置覆盖设置相关实现见 commands-prefs-wizard.ts、config-overlay.ts 与 preferences.ts。九、端到端数据流与可验证依据把整个验收链路串起来一次 run-uat 单元的生命周期为切片完成 →checkNeedsRunUat()依据数据库/ROADMAP 判断最近完成的切片是否需要验收并解析 UAT 模式auto-prompts.ts需要派发 →buildRunUatPrompt()组装上下文、计算 ASSESSMENT 结果路径、渲染 run-uat 模板auto-prompts.tsAgent 按提示词逐条执行检查、采集证据、得出 verdict调用gsd_summary_saveartifact_typeASSESSMENT落库落盘db-tools.ts后续单元经isAcceptableUatVerdict()与 complete-milestone 守卫消费 verdict非 PASS 结论阻断收尾verdict-parser.ts、dispatch-complete-milestone-guard.test.ts单元结束时输出固定句UAT {{sliceId}} complete.。验证依据集成测试 run-uat.test.ts 覆盖了模式解析含空白、大小写、未知关键词、父括号混合、模板渲染变量替换完整、无残留{{...}}、必须引用gsd_summary_save且注明artifact_type: ASSESSMENT、页脚不得出现直接文件写入指令、派发前置条件与幂等跳过自动化验收的端到端场景见 tests/e2e 下的 multi-slice-milestone-closeout、remediation-milestone-closeout 等 e2e 用例。十、实战要点总结写 UAT 规格文件时显式声明## UAT Type小节用- UAT mode: 关键词明确验收模式不写则默认按 artifact-driven 处理区分 NEEDS-HUMAN 与 PARTIAL人类专属检查用 NEEDS-HUMAN 人工指引可自动化检查无法判定才用 PARTIALhuman-experience 模式不要用 PARTIAL 代替 PASS验收结果写 ASSESSMENT不要改 UAT 文件verdict 必须进入gsd_summary_saveartifact_typeASSESSMENT产出的 frontmatter调度门只认这里优先最轻证据能rg验证就别启动浏览器能用退出码判定的就别截图只有实时/运行时检查才走真实链路不要降级验证把 live-runtime 或 human-experience 检查压成纯工件检查换取 PASS会被 verdict gate 与人工复核双重否决内容真实性优先于模式标注artifact-driven 规格若含浏览器可观测步骤系统会自动升级为 browser-executable——写规格时就按真实行为描述让解析器替你校正模式。适用前提说明以上机制均以当前仓库代码为事实依据src/resources/extensions/gsd目录提示词中的{{...}}变量由 GSD-2 的 auto-mode 派发器在运行时注入若直接阅读 run-uat.md 原文需结合派发源码理解其运行语义。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐GSD-2 用户验收测试UAT模板与自动化执行机制实战指南GSD 2 用户验收测试UAT模板与自动化执行机制实战指南 导读 GSD 2GitHub 加速计划 / gs / gsd 2是一套面向 Agent 长时人工智能AI Agent代码智能体Agent 编排CLIAI 应用gsd-2 Complete Slice 单元深度解析切片收尾者如何完成验证、摘要与 UAT 交付gsd 2 Complete Slice 单元深度解析切片收尾者如何完成验证、摘要与 UAT 交付 导读 Complete Slice 是 gsd 2GSD人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD Core 的 phase uat-passed一个防 Markdown 注入的 UAT 通过性谓词查询与 SDK 导出GSD Core 的 phase uat passed一个防 Markdown 注入的 UAT 通过性谓词查询与 SDK 导出 本篇以变更单 .changes上一篇【亲测免费】 SVG to Android VectorDrawable 项目常见问题解决方案下一篇TweetNaCl.js 常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考