live-dev-deploy

live-dev-deploy

此技能指导本地验证、测试驱动的自动修复、预览 URL 交付以及 Git Flow 发布部署。

bash 代码块遵循 POSIX（Windows 上使用 Git Bash）。任何超过单条命令或管道的逻辑都放在 resources/*.js 中，绝不写入 shell 控制流。如果你的 Bash 工具是 cmd.exe 或 PowerShell，请先转换每段代码再运行。

1. Git Flow 与发布生命周期

转换	触发条件	门槛
develop → feature/*	新请求	—
feature/* → develop	本地 QA 循环 + 密钥扫描通过	gh pr checks <PR#> --watch 全部通过。本地 ≠ CI：CI 还会运行 lint + build。
develop → main	用户批准下方的发布提示	同样等待 CI → 合并 → 打标签 → 升级版本
main → develop	发布 PR 合并后立即执行	回合并，无需 PR。升级版本的提交只存在于 main；跳过此步骤以避免分支版本冲突。

发布提示，原文照录："Would you like to release this to the production environment?"

• 版本升级： 发布 PR 同时包含标签 v<major>.<minor>.<patch> 和匹配的 package.json:version（读取当前值，默认 0.0.0，除非另有说明，否则升级补丁版本）。
• 合并限制： CI 未通过或仍在运行时，绝不合并。本地通过后 CI 未通过 → 返回 QA 修复循环 → 推送 → 等待。
• 合并冲突： 向用户展示冲突。不要自行解决手写源代码中的冲突。
• 预发布与生产部署： 通过 Vercel GitHub 集成部署。默认情况下，生产部署不得启用 Vercel Deployment Protection（密码保护或 Vercel Authentication），以确保可公开访问。
• 公开访问验证： 如果生产部署无法公开访问（重定向到登录页面／ping 失败），请询问：“The production deployment is not publicly accessible. Would you like to enable public access?” 并引导用户前往 Vercel Project Dashboard（Settings -> Deployment Protection）将其禁用。
• 回滚： 如果生产环境出现故障，在 main 上对合并提交执行 git revert → 推送。

2. 本地验证与自动修复

设置、端口发现和测试模板：references/playwright-qa-rules.md。开发服务器、baseURL 和任何测试 URL 均使用同一个端口。

提交或推送前，所有门槛都必须通过；任何一项未通过，都绝不提交或推送：Playwright 测试套件、lint、build，以及每次提交前执行的 gitleaks protect --staged（扫描暂存区差异，而非 detect）。

• 失败时： 解析错误／跟踪信息 → 只修复实现代码 → 按照 references/playwright-qa-rules.md 中的修复循环重新运行（最多尝试 3 次，然后停止并报告）。
• 密钥扫描门槛： 任何密钥匹配都会阻止提交 → 将密钥移入保险库，并通过 process.env 引用。
• Firestore 本地验证： 如果功能涉及 Firestore，使用 Local Emulator Suite 运行 QA 循环（references/react-firestore-rules.md），绝不使用真实项目。
• 钩子： 安装已提交且会自动安装的钩子管理器（Husky/Lefthook），在提交前运行 lint + 密钥扫描。

3. 预览优先交付

绝不向用户提供 localhost 链接用于验证。运行：

node resources/resolve-preview-url.js   # exit 0 -> prints PREVIEW_URL=<url>

• 轮询使用 resolve-preview-url.js 查询 GitHub Deployments API。
• 如果耗时过长，逐步升级处理：
  • 60s：增加尝试次数，并告知用户构建正在进行。
  • 约 5 min：使用非交互式 JSON vercel list，筛选已推送的提交。
  • 之后：报告仪表板 URL 或 vercel inspect。

⚡️ Features deployed successfully! Preview URL: https://project-git-develop-user.vercel.app

4. 防护措施

如果用户要求采用不良模式（通过 Context 进行属性逐层传递、绕过 GitHub 自动化、将预览数据库用于生产环境，……）→ 停止并输出：

	请求内容	建议替代方案
安全风险
维护成本

只有收到原文照录的字符串 "I understand the risk and insist on this." 后才继续。

5. 输出格式

验证日志

• Vercel 部署链接：[预览或生产 URL]
• Git 分支：[feature 分支 / develop / main]
• PLAYWRIGHT 测试状态：[PASS / FAIL]

检查清单

ID	项目	结果	证据
F1	本地 QA 测试	PASS / FAIL / N/A	[测试日志片段]
F2	预览 URL	PASS / FAIL / N/A	[实时 Vercel 预览 URL]
F3	密钥扫描	PASS / FAIL / N/A	[扫描结果摘要]

代码变更

• [file path]：[变更说明]

冒烟测试输出

[Playwright execution output]

剩余风险

• [未测试的功能、凭据隔离，或“无”]

防止问题复发

• [规则 / Hook / 测试 / 技能 /“不需要”+ 原因；以及仓库 URL、Vercel 项目和 Firebase 项目 ID]