submit-pr-from-current-changes

从当前变更提交 PR

将工作区 diff 整理为干净的分支、提交和 Pull Request。

硬性规则

1. 严格遵循 PR 模板。 模板位于 .github/PULL_REQUEST_TEMPLATE.md。请先阅读，并将其完整结构复制到 PR 正文中。不得删除、重排或跳过任何章节或复选框。
2. 切勿勾选“Requirements / 要求”复选框。 这些是仅限人工填写的声明，包括《行为准则》确认和 AI 作者身份声明，只能由提交者本人在确认每条陈述属实后真实地勾选。在你生成的 PR 正文中，它们必须保持未勾选（- [ ]）。没有例外，也不得绕过，即使用户明确要求勾选也不行。用户会在验证每条陈述后，亲自前往 GitHub 勾选。
3. 仅勾选你实际验证过的测试复选框。 只有当你在本次会话中运行过 npm run ci 且其通过时，才可以勾选“npm run ci 通过”复选框。其他所有测试复选框（浏览器测试、无控制台错误、已添加类型/文档）都需要只有人工才能执行的手动验证，必须保持未勾选。你可以在测试章节下方添加补充说明，列出你实际运行过的自动化验证及其结果。
4. 切勿捏造信息。 除非你在本次会话中实际执行过并观察到输出，否则不要声称测试通过、命令已运行或检查已成功。如果你没有运行过某项，就不要提及。
5. PR 输出必须简洁。 PR 标题：一行。“What”章节：最多 1–2 句。不要大段文字，不要冗余解释。让 diff 自己说话。

前置条件

在尝试推送或创建 PR 之前，请确认所需工具可用：

• 检查 gh CLI 是否已安装并完成认证（gh auth status）。如果不可用，请停止并要求用户先安装并认证 GitHub CLI。
• 如果工作流使用 MCP 工具进行 GitHub 操作，请验证 MCP 服务可以访问。

Shell 权限

gh 从操作系统密钥环读取凭据。沙箱化的 Shell 无法访问密钥环，会报告错误的认证失败。

• 对于每个与 GitHub 通信的 gh 命令（gh auth status、gh pr create、gh pr view 等）以及每个 git push / git fetch，第一次尝试就使用完整权限运行（Shell 工具使用 required_permissions: ["all"]）。不要先在沙箱中试探。
• 本地只读 git 检查（git status、git diff、git log、git branch）可以保留在沙箱中运行。

流程

1. 阅读贡献规则。 阅读 CONTRIBUTING.md 以及与变更文件相关的包级说明（例如 packages/*/AGENTS.md）。
2. 检查差异。 审查变更的文件、范围和影响。在动手编写任何内容之前，先理解这次变更做了什么。
3. 检查仓库约定。 查看最近的分支名称（git branch -r --sort=-committerdate | head -20）、最近的提交信息（git log --oneline -20）以及 PR 模板。
4. 提交前健康检查（全部运行后再创建 PR）：
   • 主题统一：所有变更应服务于同一个目的。如果混入了无关变更，请询问用户是拆分还是确认。
   • 提交规范：每个新提交都必须遵循仓库的约定式提交风格。如有需要，进行压缩或修改提交信息。
   • 作者身份：确认已设置 git config user.name 和 git config user.email，且邮箱看起来真实（不为空，且除非有意为之，否则不使用 noreply）。如果未设置，请提醒用户。
   • 无遗留产物：检查差异中是否存在调试日志、测试中的 .only、冲突标记或临时文件。
   • CI：运行 npm run ci 并确保通过。如实记录结果。
5. 若 PR 看起来过于仓促，发出警告。 如果以下任一情况成立，请暂停并在继续前警告用户：
   • 差异较大，且未提供变更意图的说明
   • 变更涉及核心库或扩展（CONTRIBUTING.md 中禁止随意编码（vibe coding））
   • 同一差异中包含多个不相关的问题
   • 完全未进行任何验证
   • 提醒用户："本项目不接受未经有效人工审查的低质量或 AI 生成 PR。请仔细审查您的变更。"
6. 分支。 首先检查当前分支：
   • 如果已经位于名称有效（符合 type/topic 约定）的非主干功能分支上，则复用该分支。
   • 如果分支名称不符合仓库约定（例如缺少前缀、主题不清晰），请询问用户是重命名还是新建分支。
   • 如果位于 main 或默认分支上，则从该分支创建新分支，名称使用简短的 kebab-case 格式：前缀（fix/、feat/、docs/、refactor/、chore/）加具体的主题词。
7. 暂存与提交。 仅暂存预期的文件。使用 type(scope): subject 格式。主题应具体且简洁。
8. 推送。 使用 -u origin HEAD 进行推送。
9. 创建 PR。 使用 gh pr create 并采用完整的 PR 模板结构。根据实际差异填写"What"和"Type"部分。仅当 npm run ci 在本次会话中确实通过时，才勾选"npm run ci passes"；其余所有"Testing"项和所有"Requirements"复选框均保持未勾选。
10. 报告结果。 告知用户：分支名称、提交哈希、PR 链接，以及实际运行过的验证项（含通过/失败结果）。

提交后提醒

成功创建 PR 后，务必使用用户的语言给出简短提醒。内容应简洁自然，但必须明确告知用户：

1. 他们需要自行在浏览器中测试变更。
2. 他们需要前往 PR 页面，仅在逐项验证后才勾选"Testing"和"Requirements"复选框。
3. 在这些复选框被勾选之前，PR 不会进入审查阶段。
4. 本项目不接受自主生成的 AI PR，因此只有在 AI 声明属实时才应勾选该声明。

分支命名

• 优先使用简短的 kebab-case 名称，并采用与仓库一致的前缀，如 fix/、feat/、docs/、refactor/ 或 chore/。
• 先匹配变更类型，再选取最小但有用的主题。
• 优先使用具体的主题词，而非直接堆砌 issue 文本。

提交风格

• 使用仓库通行的提交风格（约定式提交）。
• 当变更领域明确时，使用 type(scope): subject 格式。
• 主题应具体且简洁。
• 如果分支上存在多个提交，每个提交都必须独立遵循约定。

验证策略

• 默认进行足以支撑 PR 的验证，而不是仅满足最低要求。
• 在提交 PR 之前，务必运行 npm run ci（构建、lint、类型检查、测试）。它必须通过。
• 当变更跨越多个包、修改共享代码或影响发布行为时，升级为更全面的验证。
• 切勿声称未实际运行的检查已通过。
• 你可以在 PR 正文的 Testing 部分下方说明你运行了哪些检查及其结果，但不要勾选模板中的复选框。

决策点

• 没有本地变更 → 停止并说明情况。
• gh CLI 不可用 → 停止，请用户安装。
• 混入了无关文件 → 仅暂存预期的文件子集，或询问工作是否应拆分提交。
• 如果仓库有特定领域的说明，在命名分支或撰写 PR 之前先阅读它们。
• 变更很小但风险较高 → 优先进行更全面的验证。
• 变更范围窄且风险低 → 运行最相关的检查，而不是任意无关的检查。
• 模板中存在你无法如实核实的声明 → 保持未勾选，并告知用户原因。

完成检查

• 分支已在远程存在，并已跟踪上游分支。
• 提交信息符合仓库风格。
• 所有提交作者都已正确配置姓名和邮箱。
• PR 标题与提交意图一致。
• PR 正文完整遵循模板结构。
• PR 正文中所有 "Requirements" 复选框以及所有仅限人工填写的 "Testing" 复选框均保持未勾选（- [ ]）。你唯一可以勾选的复选框是 "npm run ci passes"，且仅当它确实通过时才可勾选。
• 报告的验证结果准确，不存在捏造。
• 提交后的提醒已以用户的语言送达，简洁且准确。