submit-pr

提交 Pull Request 工作流

按照项目的主干开发工作流和 PR 模板，为当前功能分支创建一份文档完善的 pull request。

注意

范围边界：此技能会推送代码、创建 pull request、监控 CI，并在获得用户批准后提交 CI 修复。它不会实现新功能或执行正式代码审查。创建 PR 且 CI 通过后，立即停止——工作流即告完成。

警告

检查点协议。当此工作流到达 ### CHECKPOINT 时，必须主动提示用户作出决定——不能只展示信息后继续。使用 Agent 的交互式提问机制（例如 Claude Code 中的 AskUserQuestion），要求用户明确回复后再继续。这样可以防止将排队中或正在处理的消息误解为批准。如果 Agent 不支持交互式提问，则输出检查点内容，并停止所有工作，直到用户明确回复。

步骤 1：提交前检查

确认分支已准备好提交 pull request：

1. 确认当前位于功能分支（而非 main）。如果位于 main，则停止并要求用户先创建功能分支。

2. 与 main 同步：

   git fetch origin
   git rebase origin/main
   

   如果存在冲突，则停止并帮助用户解决后再继续。

3. 运行项目的质量检查：

   # Adapt to your project's toolchain
   type-check      # TypeScript tsc, mypy, etc.
   lint            # ESLint, Ruff, golangci-lint, etc.
   format:check    # Prettier, Black, gofmt, etc.
   test            # Vitest, Jest, pytest, etc.
   build           # If a build step exists
   

   如果格式检查失败，则对报告的文件运行格式化工具自动修复，并暂存更改。

4. 对已更改的文件进行最终安全扫描：

   • diff 中是否存在硬编码的机密、API 密钥或凭据？
   • 是否验证并清理了所有用户输入？
   • 新增端点是否包含身份验证和授权检查？
   • 错误响应是否安全？（未泄露内部细节）
   • 依赖项是否不存在已知的 CVE？

   Claude Code 优化：如果可以使用 /security-scanning:security-sast 技能，请用它进行增强的自动扫描。否则，请按照上面的手动检查清单操作。

如果任何检查失败，请明确报告失败情况，并询问用户是现在修复还是仍要继续。

步骤 2：分析更改

了解此 PR 包含的内容：

1. 运行 git log origin/main..HEAD --oneline，查看此分支上的所有提交
2. 运行 git diff origin/main...HEAD --stat，查看文件更改摘要
3. 运行 git diff origin/main...HEAD，阅读实际更改

确定：

• 更改类型：功能、修复、文档、重构、测试、杂项（根据提交前缀判断）
• 范围：前端、后端、全栈、基础设施
• 是否包含数据库迁移？（检查迁移文件或架构更改）
• 是否包含基础设施更改？（容器、CI/CD、环境文件）
• 是否包含安全敏感更改？（身份验证、授权、API 安全、机密）
• 相关问题：从提交消息中提取（Closes #NNN、Fixes #NNN）

步骤 3：部署委员会审查（条件触发）

如果符合以下任一条件，请从技能的 councils/deployment-council.md 启用部署委员会：

• 包含数据库迁移
• 容器或基础设施文件发生更改
• 添加或修改了环境变量
• 身份验证或授权代码发生更改
• CI/CD 流水线文件发生更改

如果已启用，请阅读委员会模板并完成完整的部署检查清单。对于每位委员会成员，请阅读技能 agents/ 目录中的 Agent 定义，并使用指定的复杂度级别调整审查深度。根据部署基础设施调整检查清单：

平台工程师（负责人）

• 应用能否成功构建并打包以供部署？
• 环境变量是否已配置？
• 健康检查端点是否正常工作？
• 是否设置了资源限制（CPU、内存）？
• 是否已配置日志记录和监控？
• 是否已制定回滚策略？

安全工程师

• 是否安全地管理机密（而非将其写入代码）？
• 是否已配置 HTTPS/TLS？
• API 身份验证是否正常工作？
• CORS 是否配置正确？
• 是否已配置安全标头（例如 Content-Security-Policy、X-Frame-Options、HSTS）？
• 是否不存在高危漏洞？

QA 负责人

• E2E 测试是否通过？
• 是否已验证关键用户流程？
• 是否已完成性能测试？
• 是否不存在已知的 P0/P1 Bug？
• 回归测试是否通过？
• 是否已为部署后定义冒烟测试？

部署决策

• 状态：已批准 / 尚未就绪 / 已阻止
• 部署策略：滚动 / 蓝绿 / 金丝雀
• 回滚计划：出现问题时如何回滚

检查点（仅当已启动部署委员会时）：向用户展示部署就绪情况评估。等待用户确认后再继续。

步骤 4：生成 PR 描述

如果项目有 PR 模板（例如 .github/PULL_REQUEST_TEMPLATE.md），请使用该模板。否则，请生成一份包含以下部分的完整 PR：

标题

• 格式：<type>(<scope>): <short description>，符合 Conventional Commits 规范
• 长度少于 70 个字符
• 使用主要的提交类型和范围

正文

描述：根据提交消息和变更文件进行综合说明。解释为什么要进行这些更改，而不仅是说明改了什么。

变更类型：根据提交前缀自动检测并勾选相应复选框。

相关议题：从提交消息中提取（Closes #NNN）。

所做变更：按领域（前端、后端、数据库等）整理关键变更的项目符号列表。

测试：记录新增或更新了哪些测试，以及如何进行手动测试。

检查清单：根据实际情况预先填写：

• 勾选确实已完成的项目（测试通过、Lint 通过等）
• 对仍需处理的项目保留未勾选状态

破坏性变更：标明是否更改了 API 契约、数据库架构或公共接口。

部署说明：包括迁移步骤、新环境变量、基础设施变更。如果已启动部署委员会，请参考其评估结果。

更新日志条目

如果 PR 包含面向用户的变更，请起草一条更新日志条目：

• 确定类别：新增 / 变更 / 修复 / 移除
• 从用户角度撰写一行描述
• 引用 PR 编号

检查点：向用户展示 PR 标题和完整正文。允许用户在提交前审阅并要求修改。

步骤 5：推送并创建 PR

1. 将分支推送到远程：

   git push origin <branch-name> -u
   

2. 创建 PR。以下以 GitHub CLI 为例：

   gh pr create --title "<title>" --body "<body>" --base main
   

   如果使用的不是 GitHub，请根据项目的版本控制平台进行调整。

3. 如果 PR 模板包含标签，请添加适当的标签。

步骤 6：监控 CI 流水线

创建 PR 后，持续关注 CI 流水线，直到其运行完成：

1. 检查该分支最新的 CI 运行。

2. 监控运行状态，直到其结束。以下以 GitHub CLI 为例：

   gh run list --branch <branch-name> --limit 1 --json databaseId,status
   gh run watch <run-id> --exit-status
   

3. 如果 CI 失败，请获取失败任务的日志并进行诊断：

   • 格式错误：使用格式化工具自动修复，然后提交、推送并重新监控。无需检查点。
   • 其他所有失败：检查点——向用户说明诊断结果和建议的修复方案。等待批准后再提交。获批后，进行修复、提交、推送并重新监控。

4. 如果 CI 通过：继续步骤 7。

步骤 7：PR 提交后总结

向用户展示：

• PR URL（可点击链接）
• 已提交内容的摘要
• CI 状态（所有检查均已通过）
• 更新日志条目（如果已生成）
• 分支生命周期提醒：合并后删除分支

如果已启用 Deployment Council，请提醒用户合并后需要执行的任何部署专属步骤。

提示

工作流已完成。 PR 已提交，CI 状态为绿色。PR 合并且分支删除后，功能生命周期即告结束。

流水线：/plan-feature → /build-feature 或 /build-api → /review-code → /submit-pr（当前步骤）

如果用户想开始下一个功能，请建议：“运行 /plan-feature，开始规划下一个功能。”