用途:为前端应用加入轻量版本指纹,使自动化测试(如 ux-walker)、CI 或 curl 能在测试开始前确认线上运行的是正确构建。
主要能力:在 HTML head 注入不可见的 meta 标签(如 build-version,内容含 sha 与时间戳);提供 /__version 路由返回 JSON(git_sha、git_branch、build_timestamp、version、dirty);生成构建期脚本 scripts/version-stamp.sh 输出 version.json;支持按框架自动检测并接入,包括 Next.js、Vite、Remix、Angular、Gatsby、Astro、Nuxt 及通用静态/Express 项目。
使用方式:命令为 /deploy-check [--install] [--verify url] [--expected-sha sha]。无参数时自动判断:已有指纹则执行 --verify,否则执行 --install。--install 会检测框架、创建版本脚本、按框架注入 meta 与接口、把 public/version.json 加入 .gitignore 并验证。--verify 通过 agent-browser 读取 meta 标签、用 curl 读取 /__version 或 /version.json,再与 --expected-sha 或当前 HEAD 比较,输出结构化结果(status、deployed_sha、expected_sha、match、branch、build_timestamp、dirty)。
适用场景:部署后验证、CI 前置检查、ux-walker 的 Phase 0 Preflight 版本核对。
限制:版本检查为提示性而非阻断;public/version.json 不应提交;meta 标签须对用户不可见;/__version 不得泄露环境变量、密钥或内部路径;脚本需兼容 macOS 与 Linux;若项目已有 Sentry release 或 DataDog RUM 等版本标识,应检测并整合而非重复添加。