当开源项目没人贡献、首次贡献者流失时…

诊断并修复开源项目首次贡献者从落地、找活、搭环境、改代码、提 PR、过评审到回流的整条路径，用评分表定位泄漏环节并验证修复。

适用场景

解决思路

1. 先按 Steinmacher 等人 2015 年系统综述的五类新人障碍（社交互动、先备知识、如何起步、文档、技术障碍）给每个发现归类，避免审计变成措辞抱怨清单。
2. 优先处理两个从项目内部看不见的失败：维护者从未测试过的机器上会失败的安装（不产生 issue、消息或痕迹），以及提交 PR 后的沉默（同样什么都不产生）。
3. 按调用场景产出对应交付物：审计报告、CONTRIBUTING.md 草稿加冷启动日志、重写后的新手 issue 队列加认领约定与过期规则、首条 PR 回复草稿加双时钟规则；若用户说“有 star 没 PR”，先出评分表，问题通常在步骤 3 或 6 而非文件措辞。
4. 每个交付物都附证据：文件路径与行号、命令输出、带日期的计数；没有证据的建议只是意见。
5. 访谈时一次问一个问题，能自己读仓库回答的就跳过；问题 1-7 是门槛，未答完前不要起草任何文件。
6. 访谈问题包括：哪个仓库及能否读取运行、想要哪类贡献（代码/文档翻译/分诊支持/共同维护者）、志愿者还是企业或基金会支持、每周真实可投入小时数、截止日期、要一次性还是持续产出、明确拒绝哪些贡献、最近三次外人贡献发生了什么、法律门槛（DCO/CLA）在写代码前还是提 PR 后告知、陌生人安装耗时及上次从干净机器跑是什么时候、技术栈是否有数据库/付费 API key/GPU/专有 SDK、除你之外谁能评审 PR 及你休假时怎么办。
7. 把问题 7 留空记为审计的第一项发现而非阻塞项；把问题 4、5、6 带入所有排序并说明哪个答案改变了什么：临近截止（Q5）优先下午就能落地的修复、响应目标、issue 队列、首条回复；持续产出（Q6）优先步骤 3；每周不足一天（Q4）直接删掉步骤 7 的结构化项目。
8. 步骤 1 基线：运行 scripts/contributor-path-audit.sh <repo-root>，报告社区健康文件及其显示优先级、当前文件提及的十个贡献主题、安装面、多少 CI 工作流用 secrets 因而无法在 fork PR 上运行、git 贡献者历史（独立作者数、仅一次提交率、CHAOSS 贡献者缺席因子、每年新作者数）。
9. 把脚本的内容探测当作词汇检查而非覆盖检查——它只是 grep 关键词，“评审期望：已提及”只表示匹配到词，向维护者复述任何探测结果前先读文件。
10. 从 forge 界面或 API 收集脚本看不到的：评分表报告格式中的漏斗基线数据，以及当前未认领的新手友好 issue 存量及其年龄；响应时间用 90 天窗口、贡献者计数用四个季度（均为本技能自定默认值）。
11. 读最近十个非维护者提交的 PR，从最早的评论开始，记录每个在哪里停滞、维护者首条回复说了什么（如果有）。
12. 若环境有持久记忆，加载已存储的项目范围声明、响应目标或受众定义，而不是重新推导。
13. 用 references/contributor-path-scorecard.md 给当前路径打分，并在提出改动前把结果给维护者看；不同意诊断的维护者会拒绝治疗，而他们有时是对的。
14. 步骤 2 亲自走一遍：按评分表 §3 的冷启动协议做两次运行（环境路径与任务路径），遵守“安装绝不靠目测判定可用”的规则。
15. 运行中记摩擦日志：带时间戳记录每个困惑时刻，每条给红黄绿严重度，注明期望什么、实际发生什么、必须知道但没写下来的东西；运行中不要修任何东西，修会掩盖问题规模。
16. 步骤 3 先修环境再写文档：按“每单位永久维护成本消除的安装失败数”选可复现层级，冷启动结果决定选哪个——取能消除实际发现失败的最高效率层级后停止。
17. 三个层级：bootstrap 命令（一个 make setup 或 ./script/bootstrap，装依赖、备 fixture、最后跑测试，一下午可写、到处能用、仍信任宿主工具链）；固定工具链（宿主工具管理器读取的版本文件加提交的 lockfile，用一个文件消除大部分“在我机器上能跑”）；容器定义（本地编辑器和云工作区都能消费的开发容器定义，可复现性最强但维护最高、维护者自己不用时腐烂最快）。
18. 效率排序：bootstrap 命令 > 固定工具链 > 容器定义；价值（消除的失败）：容器定义 > 固定工具链 > bootstrap 命令；工作量：容器定义 > 固定工具链 > bootstrap 命令。
19. 该顺序会饿死容器定义这一唯一能消除整类环境失败的层级；当技术栈需要服务或痛苦工具链时（访谈问题 11）提升它，此时更便宜的层级什么都消除不了，排序绝不是发布无效修复的理由。
20. 按已知情况重排：CI 里已跑容器的团队已付过该层级成本，对该项目它升到效率线首位。
21. 采用容器定义先于任何托管工作区厂商：.devcontainer/ 格式跨编辑器、云工作区和自托管 runner 可移植，托管选择则不可；厂商公布的时间节省是无同行评审测量的营销数字。
22. 然后按此顺序补缺口：让 CI 强制的每个门禁都能用一条有文档的命令在本地运行；把流水线拆成始终在 fork PR 上运行的无凭证通道和维护者触发的特权通道，需要 secrets 的 job 无法在 fork 上运行却恰好对最需要安心的人显示红色，若有审批门禁完全挡住 fork 运行，在文件里写明谁审批、多快；开启维护者可编辑贡献者分支并在文件里说明，让停滞的 PR 能被完成而非关闭；写明合并方式（squash、rebase、merge commit），因为它影响贡献者如何组织提交。
23. 每次修复后从干净环境重跑冷启动；当不再发现新问题时该步骤完成。
24. 步骤 4 备货首个 issue 队列：新手标签是指导承诺而非难度评级——Kubernetes 明确其 good first issue 表示成员承诺提供额外帮助，help wanted 是更宽泛的“我们会接受补丁”；GitHub 还会算法化展示该标签且不公布标准，所以它会从项目外拉来陌生人，背后若是一行空 issue 就把注意力变成坏印象。
25. 停止自己修简单 bug，每个都是花二十分钟自己时间换来的招募机会；Kent C. Dodds（2015 年 first-timers-only 惯例的创造者）说：“我自己做完再走不是更快吗？当然，但作为开源贡献者这不是重点。”他的诊断正是本技能的基础——“第一次进入开源最难的不是实现功能，而是搞清楚到底怎么贡献代码”。
26. 每个候选 issue 写七部分：观察到的行为、期望行为、文件及其测试、所需技能或 API、建议做法或明确“设计未定——先讨论”、确切验证命令、指定导师；一项 74 人研究（Steinmacher 等，arXiv:2103.12653）发现新人更愿选按所需技术领域标注的 issue 而非按架构区域标注的——他们问的是“我现在能做吗”而不是“这简单吗”。
27. 每个 issue 按“从未见过代码库的人一个晚上（含安装）”来定尺寸（本技能自定默认）；一个词的错别字修复什么都教不了，只会产生不再回来的贡献者。
28. 明确保留非代码入口：文档、测试、分诊、翻译、示例——它们是最宽的门，也是全代码队列最先丢掉的东西。
29. 公布认领约定和过期规则并执行；看起来满但全被消失的人认领的队列比空队列更糟。
30. 保持至少三个有效未认领 issue 的常备存量（自定下限）；找到零个的人不会以后再来查。
31. 步骤 5 写 CONTRIBUTING 文件：按 references/contributing-file-outline.md 逐节起草，每节先取得维护者同意再进入下一节；一次重写的文件会被一次性否决。
32. 起草时守四条规则：只写现在为真的内容，文件里每条命令都必须是步骤 2 或 3 中跑过的；公布你实际能守住的响应目标（来自访谈问题 4），说到做到的七天胜过说到做不到的 48 小时；把法律门槛放在读者写代码之前而非卡在门口，若项目仍有选择，sign-off 行（git commit -s）对贡献者零成本而签名工作流会挡住错别字修复，这也是 CNCF 鼓励项目用 DCO 的原因；为阅读它的 agent 而写——把约定字面写在靠近顶部、写出命令而非只写包装器、每个强制步骤都放在文件内而非链接后面（大纲 §6 把 GitHub 自己的 repo-contribution skill 读作这三条规则的规范）。
33. 把文件放在 forge 会展示的位置并只保留一份副本（大纲 §1），链接相邻文件而非吸收它们（§4）。
34. 把成稿过一遍你常用的人性化技能；读起来像生成的贡献指南会削弱它给出的欢迎，而这个受众一眼就能看出来。
35. 步骤 6 设计评审与认可循环：用双时钟规则把确认与评审分开——当天回一句“谢谢，我看到了，周四前评审”能在真正评审要等一周时保住关系，沉默才是昂贵的失败而非慢。
36. 第一条评论就回答范围问题；三轮评审后才发现 PR 超出范围是漏斗里对双方最糟的结果。
37. 按固定顺序评审：范围、正确性与测试、带推理的设计、风格——且只评格式化工具漏掉的风格；机器能修的绝不能作为人类评审评论出现。
38. 每条评论标注阻塞还是可选；不加标注的混合读起来像一堵失败之墙。
39. 必须拒绝时快速而友善：感谢、指出范围规则、链接其公布位置、提供替代 issue、关闭；快速拒绝胜过让 PR 烂六个月。
40. 合并时给予认可：保留贡献者为作者、在发布说明中点名、把非代码贡献记在提交图看不到的地方——文档、分诊和设计工作否则不可见。
41. 明确邀请第二次贡献并指定下一个 issue；这是路过者变成贡献者的时刻，几乎不会自己发生。
42. 写下 PR 停滞时双方各做什么，并主动提出自己完成它而不是让机器人关闭。
43. 按写下的范围规则和固定顺序评审，绝不按对人的印象——这是对评审者偏见最便宜的控制；Terrell 等（PeerJ CS 3:e111, 2017）分析 3,064,667 个 PR 发现，在外部贡献（正是本路径服务的人群）中，性别可识别时女性合并率 58% 对男性 61%，而性别中性档案得分最高；性别是推断的且仅 35.3% 用户可关联，所以方向稳健而具体百分比不可靠。
44. 把第 1-8 条变成维护者真正共享的简短书面手册，并把响应目标镜像进 CONTRIBUTING 文件，让贡献者和维护者读到同一个数字。
45. 步骤 7 在花钱之前先对捷径做决定：维护者在真正问题是上述六步之一时会去抓导师项目、迎新活动或机器人；每个在可用路径上是合法加速器，在坏路径上是浪费，所以明确决定而非凭热情。
46. 只在步骤 3-6 成立后再排序：坏路径上无论顺序如何每个都得零分；工作量指承诺的维护者小时数以及宣布后多难停止，价值指会回来的贡献者。
47. 效率排序：机器人 > 结构化项目 > 迎新活动；价值：结构化项目 > 机器人 > 迎新活动；工作量：结构化项目 > 迎新活动 > 机器人；合规成本：结构化项目 > 迎新活动 > 机器人。
48. 机器人可吸收机械工作但绝不吸收人类时刻：仅凭分母就领跑效率线——一小时安装、之后近乎为零、一次提交可撤销；首条回复、拒绝和停滞问候保持人工（步骤 6），把机器人或审批门禁引入的任何等待状态当作步骤 3 的缺口来记录。
49. 结构化项目（Google Summer of Code、Outreachy、LFX Mentorship、MLH、Season of Docs）提供津贴和同期学员，你提供导师小时——整个季节的常设工作，也是这里唯一不能中途放弃的东西，因为有人整个夏天押在上面；只在步骤 3-6 成立后举办，因为导师不足的实习生比没有实习生代价更高；不要承诺它能解决留存：两个最常被引用的研究互相矛盾，Mozilla 分析（Labuschagne & Holmes, MSR 2015）发现从 good-first-bug 或受指导 bug 起步的贡献者反而更不可能成为长期贡献者。
50. 迎新活动或冲刺能教好机制但本身不转化任何人：效率排最后，因为要花一周准备加后续跟进，却买到三者中最少的可测回报；Kubernetes 办过该领域资源最充足的 workshop 后停办，因为“在峰会期间办这场会从未让任何原本不贡献的人变成专注贡献者”；要么预算后续跟进（指定下一个 issue、分配导师、第二次贡献推动），要么跳过活动。
51. 删除没有质量门槛的奖励而不是把它排最后，并说明你删了它：它买来你无法评审的量，那是成本而非小收益；Hacktoberfest 2020 的垃圾 PR 潮迫使仓库改为选择加入、延长宽限期并彻底取消 T 恤。
52. 该顺序会饿死结构化项目——三者中价值最高、也是唯一能带来本来绝不会找到项目的人；当存在第二位评审者（访谈问题 12）且问题 4 的维护者小时数能撑过导师整个季节的每周承诺时提升它。
53. 把合规线读作各自签下的义务：结构化项目——第三方参与协议、导师承诺、津贴管理及其整个季节的行为准则；活动——行为准则和场地；机器人——两者皆无；被删的奖励带有已公布的奖品规则（Hacktoberfest 不得不在活动中途重写）。
54. 把该排序当默认而非法律：它随项目和维护者而变，按已知情况重排——雇主已资助导师时间、有办过同期学员的共同维护者、有现成活动可挂冲刺——每项都会在默认生效前上移。
55. 步骤 8 重新打分并守住目标：重跑评分表并迭代直到过阈值——四个阻塞检查全过加 16 分中得 12 分；该分数是本技能自定基线而非公布标准，评分表 §4 有给追问来源的维护者的措辞。
56. 然后守住它，因为路径会腐烂——新依赖弄坏 bootstrap、新手队列清空、响应目标滑落；每季度重跑审计脚本和一次冷启动（本技能自定节奏），并在构建或测试命令任何改动后重跑；环境支持定时例程就把它装成周期任务，不支持就给维护者留一个带日期的日历提醒和一行重跑命令。
57. 若环境有持久记忆，存储商定的范围声明、公布的响应目标、新手 issue 定义和带日期的分数，让下次运行测量的是增量而非从头开始。
58. 事后追踪：低量时这些信号只是带日期的轶事而非仪表盘——每季度四个外部 PR 产生不了趋势，一次会议演讲或首页提及对下列数字的影响都大过文档改动；记录每次改动上线的日期、标注混杂因素，然后才读增量。
59. 追踪评分表的漏斗基线：每季度新外部贡献者数（头条数字也最嘈杂）；90 天内第二次贡献率（整条路径存在的意义所在，窗口为本技能自定默认）；首次人类响应中位时间（排除机器人，对照 48 小时参考点）；外部首次 PR 合并率与合并中位时间（与维护者自己的 PR 分开追踪，后者总是更快并掩盖真正重要的数字）；贡献者缺席因子（应缓慢上升，是唯一衡量项目是否变得不那么脆弱的指标）；安装支持负载（本质是“我构建不了”的 issue 和聊天消息，修好的路径会把它压到近零，是最快可见的胜利）。
60. 常见失败模式：把旧 bug 标成新手友好——对熟悉代码库的人小对陌生人并不小，若没有位置、验证命令和导师就不是首个 issue；评审是瓶颈时却优化招募——更多贡献者涌向无人值守的评审队列会产生更多被放弃的 PR 和双方更多怨恨，先修步骤 6 再推广项目；把结果数字当作可迁移的来引用——“80% 实习生继续贡献”是某项目校友调查的自报数字、回应率 37%，要测量项目自己的漏斗、首次响应时间、第二次贡献率；照搬大项目流程——十人项目跑 Kubernetes 的阶梯、赞助和轮值会把全部预算花在还没有的贡献者的流程上，取形状不取规模。

适用边界 · 注意事项

• 不适用于分诊系统设计——那属于 samber/developer-relations-skills@oss-issue-triage。
• 不适用于治理或 CLA 选择——那属于 samber/developer-relations-skills@oss-governance 和 @oss-license-strategy。
• 不适用于产品首次成功路径（developer-quickstart-guide）、仓库落地页优化、社区审核、项目发布或开发者旅程图等相邻问题，遇到时应说明并转介。