github-contributor

GitHub 贡献者

一份分阶段的操作指南，帮助你提交维护者真正愿意合并的拉取请求。本技能围绕真实的 PR 生命周期构建——发现 → 实现 → 质量检查 → 描述 → 提交后——因为每个阶段都有各自容易出错的地方，而最常见的错误，就是在错误的阶段做了正确的事（例如，为一个规模超出 10 倍的 PR 写出完美的描述）。

阶段 0 — 何时使用此技能

以下条件全部满足时，使用此技能：

• 你正在为一个并非由你维护的仓库做贡献（维护者可以不作解释就关闭你的 PR）。
• 工作涉及以下一项或多项：源代码、测试、文档、构建配置。
• 你希望 PR 被合并，而不只是提交出去。

以下情况不要使用此技能：你自己的仓库、背景信息共享的内部团队 PR、维护者正等着你处理的紧急修复分支，或简单的单行修改（留一条评论就够了）。

阶段 1 — 提交 PR 前的摸底

PR 被关闭最常见的原因，是贡献者认为可以接受的做法与维护者已经写明的要求不一致。在编写代码之前解决这个问题。

步骤 1.1 — 将 CONTRIBUTING.md 视为必须遵守的约定

CONTRIBUTING.md 不是风格建议。将其中每条编号规则都视为合并的先决条件。特别留意：

• AI 辅助贡献条款。 许多项目在 2024-2026 年的 AI PR 浪潮之后添加了这类条款。常见表述包括：“未经事先讨论的 AI 生成 PR 可能会被关闭”“你必须能够解释每一行代码”“一个问题对应一个 PR”。如果存在这类条款，你就有义务向项目明确披露（见阶段 4），并且必须控制 PR 的规模。
• 先提 Issue 的规则。 有些项目要求先有功能请求 Issue，才能提交任何功能 PR。
• 按语言分类的测试命令。 如果 CONTRIBUTING.md 写着 pnpm test:unit && cargo test，你就应该运行这些命令，而不是运行 IDE 偏好的命令。

如果缺少 CONTRIBUTING.md，这本身就是一个警示信号——参见 references/project_evaluation.md。

步骤 1.2 — 根据项目基准检查 PR 的规模是否合理

“小型 PR”是相对而言的。提交 PR 之前，运行：

gh pr list --repo <owner>/<repo> --state merged --limit 10 \
  --json number,title,author,additions,deletions \
  --jq '.[] | "#\(.number) +\(.additions)/-\(.deletions): \(.title)"'

这会告诉你该项目已合并 PR 的实际规模分布。如果你的 PR 比近期最大的一次合并大 5–10 倍，这是危险信号——提交前先拆分。有关基准评估标准和拆分启发式，请参见 references/phase1_discovery.md。

步骤 1.3 — 编码前写一段范围约定

范围约定是你在打开编辑器之前写给自己的一段话：

目标：<一句话>。范围内：<项目符号列表，3–5 项>。明确排除：<项目符号列表——具体写明有哪些内容虽然很诱人，但你会克制不加进去>。

之后，每次修改时都要问自己：“这在范围内吗？”如果你发现自己开始想着“既然我已经在这里……”就停下来，重新检查约定。范围蔓延是 PR 未合并就被关闭的最大原因——范围控制部分请参见 references/phase2_implementation.md。

阶段 2 — 实现

步骤 2.1 — 获取上游代码后立即从 main 创建分支

git fetch origin
git switch -c feat/short-descriptive-name origin/main

始终从上游的 main（或项目的默认分支）创建分支，绝不要从你 fork 的 main 创建，因为它可能已经过时。

步骤 2.2 — 用最小的差异解决问题

不要加入范围约定未直接要求的任何改动。特别是：

• 不要借机重构周边代码。
• 不要重新格式化你没有改动的行（即使格式化工具都叫“Prettier”，你的工具也可能和项目使用的不同）。
• 不要为了让变量名更清晰而重命名，除非这次重命名本身就是修复内容。

如果后续改进确实有价值，可以另开一个 Issue，或在当前 PR 合并后另开一个 PR。

步骤 2.3 — 使用 Conventional Commits，每个提交只包含一个逻辑变更

使用 Conventional Commits：<type>(<scope>): <description>，其中 type 为 feat | fix | docs | refactor | test | chore | ci | perf。每个提交都应当能够单独接受审查。

审查要求修复时，使用 git commit --fixup=<sha>，并在推送前使用 git -c sequence.editor=: rebase -i --autosquash origin/main 压缩提交——完整的 fixup 工作流请参阅 references/phase2_implementation.md。

阶段 3 — 质量门槛

维护者的信任建立在证据上，而不是口头承诺上。本阶段旨在生成可粘贴到 PR 中的证据。

步骤 3.1 — 确定项目要求的检查

阅读 CONTRIBUTING.md 和当前 CI 工作流，了解要求执行的命令和平台矩阵。如果输入仍然适用，可复用在完全相同内容上成功完成的检查；否则，运行缺失或受影响的检查。典型示例（请以项目的要求为准）：

pnpm typecheck && pnpm format:check && pnpm test:unit
cargo fmt --check && cargo clippy --all-targets && cargo test

如果检查失败，请在隔离的 worktree 中对不可变的当前基线运行相同命令，再判断问题是否由 PR 引起。保留失败结果，并区分回归、现有缺陷和环境阻碍；切勿为了让测试通过而停止其他会话的服务。声称已准备好合并之前，必须完成仓库要求的检查。

步骤 3.2 — 对于 GUI / 桌面应用：隔离环境并执行真实端到端测试

对于 Tauri/Electron/Cocoa 应用，你几乎肯定不能直接使用 pnpm dev，否则会污染真实安装。做法是先隔离数据目录，再运行真实二进制文件：

1. 找到项目的测试隔离钩子（通常是 XXX_TEST_HOME、XXX_DATA_DIR，或 config.rs / paths.go 中的配置标志）。
2. 启动前，将其指向 /tmp/<app-name>-e2e/。
3. 通过用户实际会使用的入口触发功能（URL scheme、CLI 参数、deeplink）。
4. 读取实际持久化的状态（SQLite、JSON 文件）来验证，而不只是目视检查。
5. 为 PR 描述截取 GUI 屏幕截图。

完整的隔离方案，包括如何通过 Tauri 的单实例转发触发 deeplink 而不触碰 macOS LaunchServices，请参阅 references/phase3_quality_gates_and_e2e.md。

步骤 3.3 — 自我审查：你确实做了即将声称做过的事吗？

对于会影响下游行为的变更，在接受本地检查通过之前，以及根据审查意见修复之后，再次使用 行为影响审查 选择保留测试。如果在此市场之外做出贡献，请通过已安装的 github-review-pr Skill 查找该参考资料；如果无法获取，则要求针对原始结果／保留契约进行实际的使用方检查，并说明缺少的参考资料。这不会触发独立审查，也不会授予维护者权限。

撰写 PR 描述前，列出你打算写下的每一条“我测试了……”／“我验证了……”／“我运行了……”陈述。逐条自问：“我的证据是什么？”如果答案是“我觉得我做过”或“应该能正常工作”，那就说明你实际上并未完成。只写你能证明的内容。

这条规则旨在避免最严重的信任损害：维护者运行你声称“已测试”的命令，却发现它无法正常工作。

当用户明确要求以独立维护者的角度评估其贡献时，请调用 github-review-pr:github-review-pr，使用其只读审查方法。向处于全新上下文的审查者提供原始 Issue／审查讨论以及不可变的 head/base 对象。请求者仍处于作者角色：这会产生一项建议，而非正式批准或合并许可。仅在现有授权范围内，继续通过此贡献者工作流进行修复。普通的自我审查不会触发该流程。

第 3.4 步 — 推送时验证

本地测试通过并不代表大功告成。在你认为 PR 已准备好合并之前，请运行推送时检查清单：

1. 可见性检查 — 确认目标仓库的公开或私有状态确实符合你的预期：

   gh repo view <owner>/<repo> --json visibility,isPrivate,defaultBranchRef
   

2. 安全钩子 — 如果 pre-push 失败，请修正规则或内容；不要使用 --no-verify。
3. 推送成功 — 如果推送因 503 或身份验证错误而失败，请检查 git config --global --get-regexp url，确认是否存在过时的 URL 重写规则。
4. 可合并性检查 — git push 成功不代表 GitHub 可以合并：

   gh pr view <pr-number> --repo <owner>/<repo> --json mergeable,mergeStateStatus
   

完整详情（URL 重写、PII 钩子的误报、--force-with-lease 注意事项）请参阅 references/push_time_gotchas.md。

第 4 阶段 — 撰写 PR 描述

出色的 PR 描述有三项作用：（1）让维护者能在 30 秒内决定是否合并；（2）为审查者提供验证所需的一切信息，无需私信你；（3）留下可供团队交接后查阅的书面记录。

第 4.1 步 — 结构

使用以下框架。详细模板和测试覆盖矩阵示例见 references/phase4_pr_description.md 和 references/communication_templates.md。

## Summary / 概述
<two sentences — what changed and why it matters>

## What / 变更内容
<bulleted list of commits with their purpose, or files with their purpose>

## Why / 动机
<the problem this solves; if no prior issue, briefly justify why>

## Test Plan / 测试计划
<exact commands a maintainer can run; coverage matrix for non-trivial changes>

## Backward Compatibility / 向后兼容
<state explicitly; don't make the maintainer infer>

## Security Considerations
<only if the change touches auth, inputs, or shared state>

## Screenshots / 截图
<for UI changes — see Step 4.3>

## Related Issue
<Fixes #N, or explain why no issue exists>

## Checklist
<the project's PR template checklist, with real evidence of each>

## AI-Assisted Disclosure
<see Step 4.4>

第 4.2 步 — 测试覆盖矩阵（适用于非简单改动）

如果你添加了 2 个以上的测试，请用表格列出每项测试及其锁定的行为。与阅读测试代码相比，这能大幅加快审查速度：

| Layer | Test | What it proves |
|---|---|---|
| URL parsing | `test_parse_provider_with_extra_env` | extraEnv query param extracted |
| Security | `test_extra_env_stringifies_scalars_and_skips_invalid_values` | bool/number stringified; null/array/object dropped |

第 4.3 步 — 添加截图而不污染仓库

gh CLI 不支持向 PR 添加图片附件（底层的 uploads.github.com 上传 API 仅供浏览器使用，并且会拒绝 PAT 令牌）。有三种可行方法：

1. 首选 — 让用户在 GitHub 网页界面中拖入图片。 在 PR 正文草稿中留下清晰标记的占位符（例如 [SCREENSHOT_1_PLACEHOLDER]）。用户在 github.com 编辑 PR 时，将图片拖入 Markdown，GitHub 会把图片上传到 user-images.githubusercontent.com，并替换占位符。不会造成任何污染。
2. 备用方案 — 在你的 fork 上创建孤立分支。 创建一个孤立分支（例如命名为 assets-pr-N-screenshots），提交图片，并通过 raw.githubusercontent.com 引用。这样会污染你的 fork，但不会影响 PR 差异。
3. 最后手段 — 使用第三方图片托管服务。 图片的持久性和隐私性不明确；请避免用于任何敏感内容。

第 4.4 步 — AI 辅助披露（当 CONTRIBUTING.md 或维护者惯例要求时）

如果项目的 CONTRIBUTING.md 提到了 AI 辅助的 PR，或维护者曾在过去的 PR 中对 AI 生成的内容表示怀疑，请在 PR 正文末尾添加简短说明。具体说明你做了什么，不要含糊其辞地保证。

## AI-Assisted Disclosure

Per CONTRIBUTING.md §N:

1. I have read every line; happy to walk through any function or design choice.
2. Tested locally: <list actual commands you ran with their results>.
3. Single-topic PR scoped to <one sentence>.
4. <opened/will open> Issue #N for discussion.
5. AI tools used: Claude Code for drafting; <list any others>. Final review and decisions are mine.

披露并非灵丹妙药——它不能让糟糕的 PR 变好。但如果项目要求披露而你没有做到，会立刻损害信任。

第 5 阶段 — 提交后

第 5.1 步 — 明确回复自动化机器人审查意见

现代项目会使用 Codex、Claude bot、CodeRabbit 等工具进行首轮审查。它们的评论会以针对特定行的审查评论形式出现，而非 PR 级评论。请直接回复每条意见（这样维护者可以在意见旁看到处理结果），并注明修复该问题的提交哈希以及相关函数或测试：

gh api repos/<owner>/<repo>/pulls/<pr>/comments \
  -X POST \
  -F in_reply_to=<finding_comment_id> \
  -f body="Addressed in commit \`<sha>\`: <function or test name>. <one-sentence explanation>. Thanks for the catch!"

<finding_comment_id> 是评论 URL 中的数字 ID（#discussion_rXXXXXXXX）。完整的机器人回复工作流请参阅 references/phase5_post_submission.md。

步骤 5.2 — 基于上游 main 变基，同时保留评审历史

当上游 main 更新，而你的 PR 出现冲突时：

git fetch origin
git rebase origin/main
# resolve conflicts file by file
git add <files>
git -c sequence.editor=: rebase --continue
git push fork <branch> --force-with-lease

使用 --force-with-lease，绝不要直接使用 --force。lease 变体会在其他人（或机器人）期间向你的分支推送了内容时中止操作，从而避免你悄无声息地破坏评审讨论串。

如果你在评审后做了小幅清理（提交了一个 --fixup），请使用 autosquash 将其压入相关提交，以保持合并后的历史整洁。完整步骤请参见 references/phase2_implementation.md。

步骤 5.3 — 子 Agent／反向评审出现“发现”时，先筛选再回应

如果你运行了反向评审 Agent（或者维护者的机器人一次发来 20 多条发现），不要把它们全部贴到 PR 中。针对每条发现，问自己三个问题：

筛选项	满足以下条件时忽略
概率	“这在当前代码库中真的可能发生吗？” → 否
成本	“修复它的成本是否高于风险？” → 是
场景	“上游是否已阻止这种情况？” → 是

反向评审的目的是发现你没想到的问题，而不是要求你修复每个理论上的隐患。严格筛选，然后在 PR 中说明你接受或拒绝每条建议的原因。

参考文件

文件	用途
references/phase1_discovery.md	解析 CONTRIBUTING.md、PR 大小基准评估标准、范围约定模板
references/phase2_implementation.md	Fixup 提交与 autosquash 工作流、范围纪律反模式
references/phase3_quality_gates_and_e2e.md	隔离主目录模式、单实例转发、SQLite 验证、屏幕截图与窗口焦点
references/phase4_pr_description.md	正文框架、测试覆盖矩阵、AI 使用披露模板、截图占位符模式
references/phase5_post_submission.md	gh api in_reply_to 用法、--force-with-lease 语义、反向评审筛选
references/push_time_gotchas.md	Git 远程 URL 重写、PII 钩子误报、合并状态验证、强制推送注意事项
references/case_study_cc-switch_pr_2634.md	完整的真实案例演练，包含开发日志、SQLite 转储和截图
references/case_study_cc-switch_pr_1624.md	前端／状态管理变基案例分析——异步初始化保护、测试耦合、i18n 冲突
references/pr_checklist.md	原始整合清单（旧版；各阶段文档已取代其中的工作流部分）
references/project_evaluation.md	用于发现阶段的项目健康状况评估标准
references/communication_templates.md	议题认领、评审回应和合并后沟通模板
references/high_quality_pr_case_study.md	OpenClaw PR #39763 演练——小型修复案例分析

应避免的反模式

即使底层代码没有问题，这些失败模式也会导致 PR 被关闭。以下每一种都来自真实的 PR。

1. 捏造测试声明。 实际上只运行了单元测试，却写“已在本地通过 pnpm dev 测试”。维护者会亲自尝试，之后便会彻底失去信任。
2. PR 规模达到项目近期合并基线的 5–10 倍。 即使代码质量不错，这种规模也会让许多维护者觉得是“AI 倾倒的代码”。
3. 变基时扩大范围。 在“解决冲突”时把无关的上游功能带进自己的分支，会让修复类 PR 变成毫无预警的功能类 PR。
4. 在修复提交中混入重构。 审查者无法判断哪一行修复了 Bug；请拆分提交，或在重构提交上使用 --fixup。
5. 审查期间强制推送却不加 --lease。 这会悄无声息地破坏审查讨论串。
6. 忽略机器人审查意见。 即使机器人说错了，也要回复并说明原因——保持沉默会让人觉得你“没注意到”。
7. 把披露信息藏起来。 AI 辅助披露应写在 PR 正文中，而不是放在没人会看的提交说明脚注里。
8. 写完 PR 后才阅读 CONTRIBUTING.md。 CONTRIBUTING.md 中有一半规则讲的是 PR 的结构，而不是代码的功能。
9. 项目要求先有 Issue，却在没有 Issue 的情况下提交功能。 即使同一小时内事后补建 Issue，时间戳对维护者来说依然很重要。
10. 粘贴未经筛选的反向审查结果。 PR 正文里列出 20 条发现看起来像噪声。请先筛选，再作回复。

快速参考

必需的 gh CLI 命令

gh repo view <owner>/<repo> --json visibility,isPrivate,defaultBranchRef
gh pr list --repo <owner>/<repo> --state merged --limit 10
gh pr view <pr-number> --repo <owner>/<repo> --json title,body,commits,mergeable,reviewDecision
gh pr edit <pr-number> --repo <owner>/<repo> --body-file pr_body.md
gh api repos/<owner>/<repo>/pulls/<pr>/comments -X POST -F in_reply_to=<id> -f body="..."

Conventional Commits 速查表

feat(<scope>): user-visible new behavior
fix(<scope>):  user-visible bug fix
refactor(<scope>): no behavior change
docs(<scope>): documentation only
test(<scope>): tests only
chore(<scope>): tooling / build / housekeeping
perf(<scope>): measurable performance change
ci(<scope>): CI config only

高质量 PR 的关键指标

根据对活跃项目的成功贡献总结：

• 更改文件数：修复类 PR 为 1-5 个，带测试的功能类 PR 最多约 15 个
• 生产代码差异：尽可能少于 200 行；其余内容为测试／文档
• PR 描述：包括证据在内为 200-600 行；欢迎使用矩阵表格
• 对机器人／维护者首次回复的响应时间：少于 24 小时
• 首次推送后 CI 通过：目标

如果你的 PR 有两项或更多指标远远不达标，请在提交前重新阅读第 1 阶段。