Files
shanxia2.0/.agents/skills/personal-dev/references/local-validation.md
T

6.3 KiB

本机环境验证与集成

本文件定义任务版本验证、集成环境冒烟、失败修复和环境恢复的顺序。测试责任遵循测试规则,远端动作遵循交付授权。这是 Agent 工作流程,不是自动启停服务或部署脚本。

适用范围与准备

应用代码、依赖、配置、构建、数据库迁移或启动方式受影响时,执行本机环境验证。纯文档等不影响运行的任务,记录“不适用”及依据,执行对应文档/脚本检查,不为走流程额外启动应用。相同代码树可复用完整业务测试证据,但不能代替环境切换后的冒烟检查。

开始前在当前工单或已有任务记录中保留最小环境清单:集成主分支与当前远端提交、任务分支/worktree、实际运行目录、前后端入口与端口、启动/停止/构建命令、配置来源、依赖/镜像/数据环境、测试责任及服务启停权限。只记录来源和可核对版本,不记录密钥值。未知项先核实,不从浏览器页面正常或 Git 当前分支推断运行版本。

worktree 只隔离代码;端口、Docker 项目名/容器/卷、数据库和构建产物需另行核对。优先按工程现有方式隔离任务环境。只有一套可复用环境时,按授权切换运行目录并记录恢复方法;不覆盖其他任务配置、抢占端口、共用可破坏的数据卷或擅自清理用户改动。需要迁移、重建镜像或调整数据时单独核对权限与恢复方案,切回代码不会自动还原数据库。

验证与集成顺序

  1. 任务版本验证:在任务分支/worktree 修复,按影响执行测试与必要构建,核对进程工作目录、容器挂载/镜像、前后端配套版本和实际入口对应待验收提交。修改后产生的新提交须有相应验证证据,不能以旧结果代替。失败继续在任务分支修复,不推进集成。
  2. 准备合并结果:读取最新远端集成分支,与已验收提交比较,在任务或临时集成分支处理冲突。代码树变化时按原测试责任补验;相同代码树不机械重复全量测试。保留基线和候选提交,使用 Git 合并,不复制 worktree 文件覆盖主目录。
  3. 验证集成本机环境:允许直接推送集成分支的工程,可先本地合并、暂不推送,然后把本机环境切到该集成版本;PR 保护分支走下节候选流程。核对实际运行版本,按权限执行必要重建/重启。检查受影响服务启动/健康状态、前后端连通、BUG 或需求的关键操作路径及相关错误日志。依赖、配置、数据库或产物有变化时补做对应检查,不能只验证页面能打开;与任务无关的功能不要求全量重测。
  4. 更新远端主版本:集成环境冒烟通过或有明确不适用依据后,再核对目标分支未变化,按授权推送集成分支或合并 PR。若目标又有新提交,重新准备候选、核对证据并补验,不能用强推绕过。任务分支提前推送用于备份/审查不受此门槛限制,不能把它当作主版本已交付。
  5. 恢复与交付核对:同步本地主分支和远端,确认本机实际运行目录/版本已恢复到本次集成结果,不遗留任务 worktree 服务或旧产物冒充主版本。环境完全沿用刚才已验收实例且代码树、产物、配置和数据条件未变时,记录等价证据,不再重复冒烟;若更换了目录、实例、挂载、镜像或其他运行条件则补做相应冒烟。全部条件满足后才按交付流程回写并关闭工单、清理本任务环境。

必须通过 PR 合并的工程

先以最新目标分支和任务提交准备本地临时集成候选,用工程约定的主分支运行条件验证该候选,记录目标 SHA、候选代码树和环境证据;保护分支流程不能变成“先远端合并,再首次验证”。本地主分支可以暂留原提交,避免生成与平台合并策略不同的本地历史。

合并前核对 PR 的 base/head、拟合并内容及所需 CI 检查;平台使用 squash/rebase 时提交号可变化,但最终内容必须对应已验收候选。无法证明结果一致或目标已更新时重新准备并验证,不把未验证的变化直接合入远端。合并后拉取平台结果,安全同步本地主分支,按上节完成运行环境恢复核对。不要通过自动关单关键字提前绕过环境恢复与交付核对。

失败、用户自测与停止

  • 任务测试或集成冒烟失败:记录失败阶段、提交、入口和原因,暂停远端主分支更新与关单。保留未推送合并、用户改动和诊断依据,在原任务分支/worktree 修复后重新进行必要测试、准备合并结果和冒烟;不直接在主分支补丁式修改。恢复本地主分支或运行环境时先核查未提交/未推送内容,不用破坏性重置掩盖失败;数据迁移失败另按已授权方案处理。
  • 远端已合并但恢复检查失败:如实记录远端已变化,保持工单未完成,停止后续发布,继续任务分支修复或按已有授权制定回退方案;不强制改写远端历史、不宣称尚未推送。仓库级环境问题也不能在队列中跳单继续使用故障环境。
  • 用户自测:任务验证和集成冒烟都由用户执行,Agent 只做源码/Git 核对并交付对应分支、提交、运行入口和步骤。用户仅确认任务版本通过,不能代替不同环境中的集成冒烟;分别取得证据。是否转由 Agent 测试仍按既有反馈规则,用户要求必须等回复时保持等待。
  • 无服务启停权限:说明需要用户执行的准确操作及验证入口,记录待操作/待验证;不自行启停、不因超时绕过工程禁令。可完成独立工作,必要环境验证未完成前不更新远端主分支或关单。
  • 用户停止队列:停止优先,保存阶段和当前运行环境说明,不继续测试、合并、推送或为收尾擅自重启;必要环境恢复按已有授权或交用户操作。续接先核对实际环境和远端状态。

交付证据统一保留在既有工单/任务记录中:任务与集成提交、验证责任、运行来源与入口、测试/冒烟结果或不适用依据、环境恢复状态和未解决项。无需为每次切分支新建永久报告。