为什么开始这次实践
我希望借助 Agent 参与开源项目，降低搜索、环境准备和实现的时间成本，同时接触值得学习的技术。最初的设想是让 AI 多承担执行，自己投入有限的人工时间。实践之后，我更关心的是：人应该在哪些位置参与，才能逐渐形成对项目的理解和判断力。
截至 2026 年 11 月 3 日，我们已提交 JBang 和 Keycloak Config CLI 两个 PR，跑通了找题、核查、实现、自测、投稿和一部分自动反馈处理。维护者人工评审到最终合并的完整过程仍待验证。这是一份阶段性方法记录。
先选值得理解的项目
我把 500 Star 作为初筛门槛，搜索范围覆盖 Java 开发工具、配置自动化、中间件和工业通信。这个门槛只是个人筛选条件，不能证明项目容易贡献，也不能代替维护活动、贡献规则和任务质量的判断。
比较仓库时，我会先看项目解决什么问题、应用场景、维护组织和相关模块，再看下面几项：
| 判断项 | 需要回答的问题 |
|---|---|
| 成长价值 | 做完后能更理解哪些技术，是否与自己的兴趣有关？ |
| 维护与协作 | 最近有没有接受外部贡献，反馈是否具体？机器人依赖更新不能代表这一点 |
| 问题池 | 有没有范围明确、能够验证的问题？开放数量不是可领取数量 |
| 贡献规则 | 是否接受 AI 辅助，是否有 CLA、测试或沟通要求？ |
| 环境投入 | 首次搭建需要什么，后续换题能复用多少？ |
前期搜索曾过度集中在 AI 和 Agent 项目。后来改为按方向分别查找，才得到更符合个人兴趣的候选。GitHub topic 由维护者填写，因此搜索结果也不是完整的项目地图。
一道开放 issue 未必还有贡献空间
有些 issue 无指派、仍开放，但评论中已经有人认领，或关联了尚未合并的修复 PR。仅按状态和标签挑题，会在投入之后才发现重复劳动。
我们使用 GitHub CLI 查询 issue 正文、评论和时间线，再搜索所有状态的 PR。题号搜索之外还要查关键词，并核对结果：纯数字可能匹配到无关的依赖更新。开始实现前和投稿前都要复查一次。
gh issue view ISSUE_NUMBER --repo OWNER/REPO --json state,assignees,comments,body
gh api repos/OWNER/REPO/issues/ISSUE_NUMBER/timeline
gh search prs ISSUE_NUMBER --repo OWNER/REPO --json number,title,state,url
需求也需要验证。报告者遇到的问题可能已有配置可以解决，或者修复会改变原有语义；这时应先澄清范围，不能为了提交 PR 而扩大改动。
环境难度和环境通用性分开看
环境难度决定这一题要付出多少准备成本；环境通用性决定这次投入以后还能服务哪些工作。两者应分别记录。
例如，JDK 和 Maven 可以服务多个 Java 项目，而设备网络、特定版本的服务镜像和测试数据通常更专用。即使基础工具相同，不同仓库也仍可能需要重新下载依赖。
还要区分最小复现、定向回归和完整验收。文档题可能只需运行发行版并渲染页面；这并不意味着已构建源码或完整网站。代码题可以先用无容器单测证明关键行为，再说明尚未覆盖的服务集成和版本矩阵。
这次实践也发生过不必要的提前投入：先下载了 JDK 21，后来发现 JBang 文档示例使用本机 Java 8 就能验证。JDK 21 在下一题得到了复用，但它不应被写成前一道题的必要环境。
人和 Agent 如何分工
flowchart TD A["比较技术方向、项目背景与成长价值"] --> B{"人：选择仓库和问题"} B --> C["Agent：核查认领、同题 PR 与贡献规则"] C --> D["评估环境难度和可复用部分"] D --> E{"人：接受投入与方案取舍"} E --> F["Agent：复现、最小修改、自测与技术复核"] F --> G["说明改动、测试证据与剩余风险"] G --> H{"人：理解内容并确认投稿"} H --> I["提交 PR，跟进 CI 与评审"] I --> J["记录结果，逐步深入同一仓库"]
我的参与重点是选方向、理解真实问题、讨论关键取舍，以及确认愿意以自己的账号投稿。Agent 负责技术核查与验证，并把证据和限制解释清楚。提交前可以采用简短说明，不要求我逐行检查陌生代码。
这里仍有一个必要的边界：选择题目与允许公开投稿要分别确认。我们曾把“继续做下一题”理解得过宽，因此把提交前的具体结果展示重新明确下来。已有明确授权时无需反复询问，但不能用“低风险”代替投稿决定。
自测证据如何进入 PR
PR 正文应让维护者迅速理解问题、改动和验证范围。通常需要关联 issue、说明为什么修改、列出关键测试命令与结果，并明确未验证项。完整日志保存在本地，正文摘录足够判断的证据；截图用于帮助理解可见变化。
本地测试、上游 CI、机器人评审和维护者认可分别记录。机器人通过不能证明测试覆盖充分，PR Open 也不能记作合并成果。收到建议后，先核对事实，再决定修改。
把工作台和公开文章分开
本地保留候选清单、过期题、PR 状态、环境路径、完整日志和执行记录。公开文章沉淀可复用的方法、必要的验证证据，以及已经理解的技术问题。尚未投稿的失效候选可以删除独立档案；已经投稿的案例保留结果和复盘。
提交新 PR 后，我们顺手复查之前尚未结束的 PR，更新评审、检查和下一步。这是附着于实际工作的跟进习惯。
下一阶段，我希望先讨论适合持续参与的方向，再集中学习少量仓库。环境、模块知识和维护者反馈都需要积累，持续参与的价值会比不断寻找小题更大。
具体投稿实践见一次开源 PR 热身：自测、自动评审与 CI 等待。