droboticflow-new/docs/agents/verification.md

6.2 KiB
Raw Permalink Blame History

分层验证

适用于日常功能开发、修复及本批改动交付。发布仍使用 release.py 流程。

工作步骤

  1. 开工时用几句话确定业务结果、兼容范围、任务基线和风险。普通小改动不另写长计划;在已授权范围内连续完成实现、验证、修正。
  2. npm run verify:plan -- --base <任务起点提交> 查看范围。默认 HEAD 只包含未提交改动;交付已提交任务时必须指定任务起点,不能用干净树的空计划证明已提交代码通过。
  3. 编辑过程中运行 npm run verify:quick -- --base <任务起点提交>。相关单元测试被合并、去重执行;不默认启动浏览器、Mongo 或长时压测。
  4. 本批完成后运行 npm run verify:task -- --base <任务起点提交>,集中验证受影响的真实业务流程。失败只修复并重跑有关部分;新改动影响其他范围时扩大验证。
  5. 跨模块集成或公共依赖变化时运行 verify:integration。最终报告列出通过、失败、待验证和日志路径;部署单独执行发布门禁。

命令支持 --plan(不执行)及 --budget-seconds N。默认执行预算:quick 180 秒、task 600 秒、integration 3600 秒;预算耗尽会停止进程组并报告待验证,不自动重跑或改成通过。冷编译、安装依赖和机器负载会影响耗时,预算不是延迟承诺。

风险与完成标准

变更 开发检查 本批完成还需确认
文档、纯样式 差异/格式检查 界面样式实际查看正常与错误状态;文案遵循现有最简规则
交互、状态和页面切换 类型、有关单元回归 一条覆盖进入、操作、退出的真实浏览器流程
领取、权限、保存、校验、返工 相关接口和规则回归 隔离存储、冲突、失败恢复及旧数据兼容
查询、轮询、缓存 结果等价回归 相同代表性规模的查询量、扫描量、耗时、取消及并发对照
工作流、迁移、资源或容量 专项验证 在途任务、回退和恢复;生产写入按具体授权执行

风险取决于行为和影响面,不按行数判断。共享工作台页面可能同时影响多个流程,脚本会扩大映射;确认只是文案/样式时可记录实际差异与人工检查,执行有关检查并说明未运行项,不把整批列为全通过。

120 人完整作业、8 小时运行、媒体容量和节点故障属于专项验收:容量承诺、相关架构或资源变更时执行,不绑定每次普通功能提交。发布基础门禁未因本规则减少。

选择与兜底

  • 映射的唯一配置为 scripts/verification-scopes.json;当前覆盖审查切换、源校验/个人池、搜索分页、标注编辑、审核决定和统计面板。
  • Git 检测包含起点以来提交、暂存、未暂存、未跟踪文件,重命名检查新旧路径。改动的前端测试和 Go 同名测试自动加入。CSS 不因单纯样式修改启动全套类型/业务测试。
  • 未映射的前端代码扩大到前端基线门禁,未映射 Go 实现扩大到所属包;浏览器流程仍需人工核对。其他未映射行为报告待验证,补充映射或专项证据后才算交付完成。
  • 退出码 0 仅表示所选检查通过;1 表示检查失败;2 表示超时、跳过、未映射、执行中源码变化或入口异常。报告中的 deferred/notCovered 始终保留,不把快速通过解释成完整通过。
  • 遇到已有测试债务,使用既有 test:frontend:gate / test:go:gate 比较具体用例。不因失败而扩大 known-failures 基线,不手工忽略断言。

检查选择与环境初始化

标准开发入口与本地验证先检查并补齐当前 worktree 的 Husky wrappers,复用依赖目录也执行该步骤。自定义 hooksPath 保持原样并报告冲突;CI、导出源码和显式 HUSKY=0 保留原有行为。

快速 Go 检查按包内实际用例展开范围规则,交互预览、Mongo、浏览器及容量用例由专项入口处理。任务映射显式声明所需 opt-in 环境;执行器清理继承的测试开关,避免误连外部服务。领取池 Mongo 等价和大载荷回归在任务级执行,也由 CI 的隔离 Mongo 服务执行。

独立检查在其他项失败或跳过后继续执行,报告保留每一项结果;依赖检查仅在前置检查通过后执行。例如构建失败时,生产产物启动检查标为未运行,避免读取旧 dist。预算耗尽仍停止后续执行,失败和未完成仍决定最终退出码。

浏览器门禁共用解析器:优先 BROWSER_EXECUTABLE,兼容 BROWSER_PATH;Mac 优先使用已安装的 Edge/Chrome,其余环境优先使用已安装的 Playwright Chromium,再查找本机 Chromium 浏览器。显式路径无效会报错。倍速回归默认创建并清理临时本地 Vite 服务,也支持显式指定本地测试 URL。

减少重复与环境准备

  • 同一批同一输入只做一次成功验证;优先复用已有 npm 测试组、Go 编译/测试缓存和本地隔离 Mongo 服务,不为每次小改动重装依赖、重建镜像或重启整套副本。
  • 浏览器/数据库测试串行运行,继续使用各自独立合成数据和清理机制。共享服务不等于共享业务状态;公司集群和 BOS 不用于这些写入测试。
  • 日志及 JSON 报告写入忽略目录 local-data/test-results/verify-*,包含命令、基线、源码摘要、环境摘要、工具版本、安装锁文件摘要、耗时和未覆盖项。原始环境值不写入报告。
  • 同任务内复用记录前,核对源码/测试/夹具、依赖安装、配置、工具版本、测试环境均未变化。源码摘要和环境摘要不是依赖安装或外部数据状态的证明。此入口不做跨运行的自动“免测缓存”;Go 自有缓存正常使用。浏览器、数据库和生产证据按各自环境重新核验。
  • 更换依赖、修复失败、修改夹具、出现新问题或范围扩大时,重跑相关检查。测试报错、跳过和未启动永远不是可复用的成功证据。

此流程不增加日常审批。普通本地修改、测试及本地提交持续推进;推送、PR、公司部署、生产数据和资源修改仍遵循 AGENTS.md 的授权边界。