live-dev-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

live-dev-deploy

开发-部署全流程

This skill guides local verification, test-driven auto-healing, preview URL delivery, and Git Flow release deployment.

bash

blocks are POSIX (Git Bash on Windows). Any logic beyond one command/pipe lives in

resources/*.js

, never in shell control flow. If your Bash tool is cmd.exe or PowerShell, translate each snippet before running it.

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

bash

代码块遵循POSIX标准（Windows系统使用Git Bash）。任何超出单条命令/管道的逻辑都应放在

resources/*.js

中，切勿写在shell控制流里。如果你的Bash工具是cmd.exe或PowerShell，请先转换代码片段再运行。

1. Git Flow & Release Lifecycle

1. Git Flow 与发布生命周期

Transition	Trigger	Gate
`develop` → `feature/*`	new request	—
`feature/*` → `develop`	QA loop + secret scan PASS locally	`gh pr checks <PR#> --watch` green. Local ≠ CI: CI also runs `lint` + `build` .
`develop` → `main`	user approves the release prompt below	same CI wait → merge → tag → bump
`main` → `develop`	immediately after the release PR merges	back-merge, no PR needed. The bump commit exists only on `main` ; skip this to prevent branch version collision.

Release prompt, verbatim:

"Would you like to release this to the production environment?"

Version Bump: The release PR carries both the tag
```
v<major>.<minor>.<patch>
```
and the matching
```
package.json:version
```
(read it, default
```
0.0.0
```
, bump patch unless told otherwise).
Merge Restrictions: Never merge on red or pending CI. Red after green local → back into the QA healing loop → push → wait.
Merge Conflicts: Show conflicts to the user. Do not self-resolve handwritten source conflicts.
Staging vs. Production Deploy: Deploy via Vercel GitHub integration. Production deployments must not have Vercel Deployment Protection (password protection or Vercel Authentication) by default, ensuring public access.
Public Access Validation: If a production deployment is not publicly accessible (redirects to login/fails ping), ask: "The production deployment is not publicly accessible. Would you like to enable public access?" and guide them to Vercel Project Dashboard (Settings -> Deployment Protection) to disable it.
Rollback: In case of broken production,
```
git revert
```
the merge commit on
```
main
```
→ push.

阶段过渡	触发条件	准入条件
`develop` → `feature/*`	新需求发起	—
`feature/*` → `develop`	本地QA循环+密钥扫描通过	`gh pr checks <PR#> --watch` 状态为绿色。本地验证≠CI验证：CI还会运行 `lint` + `build` 。
`develop` → `main`	用户确认下方的发布提示	等待CI验证通过 → 合并 → 打标签 → 版本号升级
`main` → `develop`	发布PR合并完成后立即执行	反向合并，无需创建PR。版本号升级提交仅存在于 `main` 分支；为避免分支版本冲突可跳过此步骤。

发布提示原文：

"是否要将此版本发布到生产环境？"

版本号升级： 发布PR需同时包含标签
```
v<major>.<minor>.<patch>
```
和对应的
```
package.json:version
```
（默认值为
```
0.0.0
```
，除非另有说明，否则升级补丁版本号）。
合并限制： CI状态为红色或待处理时切勿合并。本地验证通过但CI失败 → 回到QA修复循环 → 推送代码 → 等待验证。
合并冲突： 将冲突内容展示给用户，不要自行解决手写代码的冲突。
预发布与生产环境部署： 通过Vercel GitHub集成进行部署。生产环境部署默认不应启用Vercel部署保护（密码保护或Vercel身份验证），以确保公开访问。
公开访问验证： 如果生产环境部署无法公开访问（重定向到登录页或ping测试失败），请询问：“生产环境部署无法公开访问，是否要启用公开访问？”并引导用户前往Vercel项目控制台（设置 -> 部署保护）关闭保护功能。
回滚： 若生产环境出现故障，在
```
main
```
分支上执行
```
git revert
```
撤销合并提交 → 推送代码。

2. Local Verification & Auto-Healing

2. 本地验证与自动修复

Setup, port discovery, and test templates:

references/playwright-qa-rules.md

. One port for dev server +

baseURL

+ any test URL.

Gates, all green before any commit or push — never commit or push past a red one: the Playwright suite,

lint

build

, and

gitleaks protect --staged

(staged diff, not

detect

) before every commit.

On failure: Parse errors/traces → fix implementation code only → rerun under the healing loop of
```
references/playwright-qa-rules.md
```
(limit 3 attempts, then halt and report).
Secret Scan Gate: Any secret match blocks the commit → move to vault, reference via
```
process.env
```
.
Firestore Local Verification: If features touch Firestore, run the QA loop against the Local Emulator Suite (
```
references/react-firestore-rules.md
```
), never the real project.
Hooks: Install a committed, auto-installing hook manager (Husky/Lefthook) running lint + secret scan pre-commit.

环境配置、端口发现及测试模板：

references/playwright-qa-rules.md

。开发服务器、

baseURL

及所有测试URL使用同一个端口。

准入条件：提交或推送前必须全部验证通过——绝不允许跳过失败项进行提交或推送：每次提交前需运行Playwright测试套件、

lint

、

build

以及

gitleaks protect --staged

（针对暂存区差异，而非

detect

命令）。

失败处理： 解析错误/追踪信息 → 仅修改实现代码 → 按照
```
references/playwright-qa-rules.md
```
中的修复循环重新运行（最多尝试3次，之后停止并上报）。
密钥扫描准入： 任何匹配到的密钥都会阻止提交 → 将密钥移至密钥库，通过
```
process.env
```
引用。
Firestore本地验证： 若功能涉及Firestore，需针对本地模拟器套件（
```
references/react-firestore-rules.md
```
）运行QA循环，切勿使用真实项目。
钩子： 安装已提交的自动安装钩子管理器（Husky/Lefthook），在提交前运行lint + 密钥扫描。

3. Preview-First Delivery

3. 优先交付预览链接

Never hand the user a

localhost

link for verification. Run:

bash

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

Polling uses
```
resolve-preview-url.js
```
to query GitHub Deployments API.
If it takes too long, escalate:
- 60s: extend attempts, tell user a build is in progress.
- ~5 min: use non-interactive JSON
```
vercel list
```
  filtered to the pushed commit.
- After that: report dashboard URL or
```
vercel inspect
```
  .

text

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

切勿向用户提供

localhost

链接用于验证。运行以下命令：

bash

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

轮询通过
```
resolve-preview-url.js
```
查询GitHub Deployments API。
如果耗时过长，按以下步骤处理：
- 60秒：延长尝试次数，告知用户构建正在进行中。
- 约5分钟：使用非交互式JSON命令
```
vercel list
```
  筛选已推送的提交。
- 超过5分钟：上报控制台URL或使用
```
vercel inspect
```
  查询。

text

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

4. Guardrails

4. 防护规则

Bad pattern requested (prop drilling over Context, bypassing GitHub automation, reusing preview database for production, …) → halt and emit:

	Requested	Proposed alternative
Security risk
Maintenance cost

Resume only on the verbatim string

"I understand the risk and insist on this."

若请求使用不良模式（如通过Props传递替代Context、绕过GitHub自动化、将预览数据库用于生产环境等）→ 停止操作并输出：

	请求的操作	建议替代方案
安全风险
维护成本

仅当用户输入原文

"I understand the risk and insist on this."

时才继续操作。

5. Output Format

5. 输出格式

Verification Log

验证日志

Vercel Deployment Link: [preview or production URL]
Git Branch: [feature branch / develop / main]
PLAYWRIGHT Test Status: [PASS / FAIL]

Vercel部署链接: [预览或生产环境URL]
Git分支: [功能分支 / develop / main]
PLAYWRIGHT测试状态: [通过 / 失败]

Checklist

检查清单

ID	Item	Result	Evidence
F1	Local QA Test	PASS / FAIL / N/A	[test log snippet]
F2	Preview URL	PASS / FAIL / N/A	[live vercel preview URL]
F3	Secret Scan	PASS / FAIL / N/A	[scan result summary]

ID	检查项	结果	证据
F1	本地QA测试	通过 / 失败 / 不适用	[测试日志片段]
F2	预览URL	通过 / 失败 / 不适用	[Vercel实时预览URL]
F3	密钥扫描	通过 / 失败 / 不适用	[扫描结果摘要]

Code Changes

代码变更

```
[file path]
```
: [description of change]

```
[文件路径]
```
: [变更描述]

Smoke Test Output

冒烟测试输出

text

[Playwright execution output]

text

[Playwright execution output]

Remaining Risks

剩余风险

[untested features, credentials isolation, or "None"]

[未测试功能、凭证隔离情况，或“无”]

Recurrence Protection

重复风险防护

[Rule / Hook / Test / Skill / "Not Needed" + reason; plus the repo URL, Vercel project, and Firebase project id]

[规则 / 钩子 / 测试 / 技能 / “无需防护”+原因；同时提供仓库URL、Vercel项目及Firebase项目ID]