实际维护开源项目时仓库不仅要面对人类贡献者还需要面对一批新的自动化参与者AI 辅助工具、AI Agent 自动提交的 Pull Request以及基于大模型生成的代码审查意见。这些参与方式对仓库的规范程度要求很高因为 AI 工具没有人类那种“先看看社区氛围再猜测流程”的能力它们更依赖明确的说明文件、模板、标签和自动化检查。RepoPolicyScore 就是用来衡量一个 GitHub 仓库是否具备这种协作就绪度的评分方法它检查仓库是否提供了 README、贡献指南、许可证、Issue 模板、PR 模板、CI 工作流等信息并把这些检查结果换算成可读的分数。本文会围绕 RepoPolicyScore 给出一套可以直接运行的参考实现。你可以在本地 clone 一个仓库后用脚本扫描它的文件结构和基础配置也可以传入 owner/repo 让脚本通过 GitHub REST API 拉取仓库元数据来评分。文章会说明每条检查项为什么重要、权重如何配置、输出怎么解读以及低分仓库应该如何补齐缺失项。1. 为什么需要 RepoPolicyScore 这样的协作就绪度评分1.1 AI 参与开源协作后评审流程发生了什么变化传统上一个开源项目是否“好上手”主要看文档是否完整、维护者是否友好、Issue 回复是否及时。这些条件对人也成立但 AI 工具和人工判断有一个关键差异AI 工具更容易被规范化输入驱动。举个例子。如果一个仓库没有CONTRIBUTING.md人类贡献者会去翻 README、搜索历史讨论、给维护者发 Issue 询问“我应该怎么提交代码”。AI 工具不会这么做它通常只能读取已经存在的文件、模板和标签再生成提交。仓库如果没有统一的 PR 模板AI 生成的 PR 描述就可能是自由发挥的文本仓库如果没有 CIAI 可能在提交代码后没有任何自动化反馈只能在本地猜测测试结果。这里真正的问题不是“AI 写代码好不好”而是“仓库的规则是否显式存在”。RepoPolicyScore 把这类问题变成可检查的配置项帮助维护者快速看到仓库对外展示的协作入口是否完整。1.2 评分体系分数不是门槛而是响应策略RepoPolicyScore 的设计思路不是给仓库贴“好”或“差”的标签而是给维护者一个决策参考分数低说明外部贡献者进入项目时缺少明确的路径AI 工具误操作的概率也更高。分数中说明仓库有基本入口但某些关键环节缺失例如没有 PR 模板或者没有 Issue 模板。分数高说明仓库的文档、规则、自动化流程相对齐全外部提交可以按既定路径进入。在这种设计下评分结果应该被理解成“响应策略”低分仓库可以优先补文档和模板高分仓库可以把精力放在自动化评审、代码权限和异常分支处理上。还有一点值得说明分数不能替代人工判断。一个仓库可能没有SECURITY.md但它只是面向内部实验的项目不需要完整的安全响应流程。所以在参考实现里我会把某些检查项设计成可跳过、可配置权重而不是强制要求所有仓库都得 100 分。1.3 内容检查维度与权重设定RepoPolicyScore 参考实现包含两类检查项一类是文件存在性另一类是仓库元数据和流程配置。文件存在性检查包括README.mdCONTRIBUTING.mdLICENSECODE_OF_CONDUCT.mdSECURITY.mdAGENTS.md元数据和配置检查包括仓库描述是否填写是否存在.github/workflows/下的 CI 工作流是否存在.github/ISSUE_TEMPLATE/下的 Issue 模板是否存在 PR 模板是否存在带good first issue标签的开放 Issue这些维度并不追求面面俱到而是围绕“一个全新的外部参与者能否在 10 分钟内知道该做什么”来设计。AGENTS.md这类文件目前还不是所有 GitHub 项目的标配但部分项目已经开始用它对 AI 工具说明构建命令、测试命令、代码风格和允许修改的范围。把它作为加分项加入评分可以让规则体系更接近真实协作场景。2. 准备环境并用最小目录跑通评分2.1 Python、git 和 GitHub Token 应满足什么条件参考实现在运行时只需要 Python 3.9 或更高版本不需要第三方依赖。为了让脚本既能扫描本地仓库文件也能调用 GitHub REST API建议开发环境中提前装好并验证以下工具Python 3.9能执行python --versiongit 客户端能执行git --version一个 GitHub Token用于 API 模式读取仓库元数据Token 的用途是提高 API 调用上限。未认证的 GitHub API 请求每小时大约只有 60 次配额而认证后的配额可以到每小时 5000 次。如果只跑一两个仓库不配置 Token 也可以如果要批量扫描就必须配置。获取 Token 时建议在 GitHub 的用户设置里创建一个 Fine-grained personal access token。如果只评估公共仓库仓库权限可以不选只保留最基本的公共只读能力即可如果评估私有仓库需要在 token 的 Repository access 和 Permissions 中配置对应读取权限。注意Token 不要写入代码仓库。脚本会从环境变量GITHUB_TOKEN中读取所有只在终端临时导出的做法。2.2 参考目录结构与配置说明最小项目目录可以按下面的结构组织repo-policy-score/ repo_policy_score.py policy_config.json README.mdrepo_policy_score.py是评分主程序。policy_config.json保存权重配置和需要跳过的检查项。README.md记录用法。先创建配置文件policy_config.json{ files: { README.md: 10, CONTRIBUTING.md: 15, LICENSE: 10, CODE_OF_CONDUCT.md: 8, SECURITY.md: 6, AGENTS.md: 8 }, meta: { has_description: 5, has_workflows: 12, has_issue_templates: 10, has_pr_template: 8, has_good_first_issues: 8 }, skip: [] }权重加起来一共 100。skip数组中可以填写需要跳过的检查项 key。例如个人项目不想强制要求good first issue标签就在skip中加入has_good_first_issues。跳过的项不参与总分计算但在输出报告中会明确标记出来。2.3 配置项速查表配置项 key默认权重检查内容为什么设计这一项README.md10根目录是否有 README 文件新参与者最先看的入口CONTRIBUTING.md15根目录是否有贡献指南说明构建、测试、提交流程LICENSE10根目录是否有许可证决定代码能否被合法复用和修改CODE_OF_CONDUCT.md8根目录是否有行为准则降低社区协作中的沟通成本SECURITY.md6根目录是否有安全说明给出漏洞上报路径AGENTS.md8根目录是否有 AI 协作说明告诉 AI 工具哪些目录可改、命令怎么跑has_description5GitHub 仓库描述是否非空让仓库在搜索和 API 结果里可识别has_workflows12是否存在 CI 工作流文件自动验证提交质量has_issue_templates10是否存在 Issue 模板规范问题描述和功能请求has_pr_template8是否存在 PR 模板规范代码变更说明has_good_first_issues8是否存在标记了 good first issue 的开放 Issue降低新参与者的选任务成本权重不是固定要求。实际项目里如果团队对 CI 要求极高可以把has_workflows权重调高如果项目根本不做社区开源只会内部协作也可以把CODE_OF_CONDUCT.md和has_good_first_issues加入skip避免分数被无关项拉低。3. 实现 RepoPolicyScore本地 git 与 GitHub API 双模式3.1 两种获取输入的方式本地目录还是远程仓库脚本需要支持两种运行方式本地模式传入一个已经 clone 到本地磁盘的仓库路径检查文件存在性。这种方式不依赖网络适合在离线环境或大规模批量扫描时使用。它只能检查文件无法获取 GitHub 上的 description、开放 Issue、CI 文件是否存在于远端分支。远程模式传入owner/repo调用 GitHub REST API 获取仓库元数据和默认分支的 git tree。这种方式能看到完整信息但依赖网络和 API 配额。远程模式的实现重点是利用 Git Trees API。直接逐个请求contents接口检查 10 个文件会产生大量请求而一次获取整个仓库文件树只需要一次请求GET /repos/{owner}/{repo}/git/trees/{branch}?recursive1返回的是一个包含所有文件路径的数组脚本只需要在数组中做字符串匹配就能判断文件是否存在。这样既快又省配额。3.2 检查哪些文件与元数据先用一个数据结构保存所有检查项便于后续扩展class CheckResult: def __init__(self, key, title, weight, passedFalse, skippedFalse, note): self.key key self.title title self.weight weight self.passed passed self.skipped skipped self.note note def to_dict(self): return { key: self.key, title: self.title, weight: self.weight, passed: self.passed, skipped: self.skipped, note: self.note, }再写一个函数根据配置和文件树生成检查结果def build_check_results(config, files, meta, skip): results [] for key, weight in config[files].items(): if key in skip: results.append(CheckResult(key, key, weight, skippedTrue, noteskip by config)) else: results.append( CheckResult( key, key, weight, passednormalize_path(key) in files, ) ) for key, weight in config[meta].items(): if key in skip: results.append(CheckResult(key, key, weight, skippedTrue, noteskip by config)) elif key has_description: results.append(CheckResult(key, key, weight, passedbool(meta.get(description)))) elif key has_workflows: results.append(CheckResult(key, key, weight, passedhas_workflows(files))) elif key has_issue_templates: results.append(CheckResult(key, key, weight, passedhas_issue_templates(files))) elif key has_pr_template: results.append(CheckResult(key, key, weight, passedhas_pr_template(files))) elif key has_good_first_issues: results.append(CheckResult(key, key, weight, passedmeta.get(has_good_first_issues, False))) return results路径匹配时要注意大小写和分隔符。Git 在 Linux 下是大小写敏感的readme.md和README.md会被视为不同文件为了方便跨平台使用者脚本在检查时统一转成小写。Windows 上路径分隔符是\git tree 返回的是/统一用/判断更稳妥。3.3 计算得分并输出 JSON分数计算采用加权求和def calculate_score(results): total 0 earned 0 for item in results: if item.skipped: continue total item.weight if item.passed: earned item.weight if total 0: return 0, 0, 0, 0 score round(earned * 100 / total) return score, total, earned, round(total - earned, 1)等级可以简单按分数区间划分80 到 100协作入口基本齐全60 到 79具备基础条件建议补齐关键模板40 到 59外部参与者会明显感到入口不足0 到 39还不适合直接开放大规模外部协作to_dict可以把全部检查结果输出为 JSONdef output_json(report, output_pathNone): text json.dumps(report, ensure_asciiFalse, indent2) if output_path: with open(output_path, w, encodingutf-8) as f: f.write(text) else: print(text)输出报告的结构可以这样设计{ target: octocat/Hello-World, mode: remote, score: 72, total_weight: 92, earned_weight: 66, level: B, items: [ { key: README.md, title: README.md, weight: 10, passed: true, skipped: false, note: } ] }3.4 命令行参数设计主入口需要支持以下参数python repo_policy_score.py --repo owner/repo python repo_policy_score.py --path /path/to/local/repo python repo_policy_score.py --repo owner/repo --config policy_config.json --output report.json对应的argparse实现import argparse def parse_args(): parser argparse.ArgumentParser(descriptionRepoPolicyScore: check if a repo is ready for AI contributors) source parser.add_mutually_exclusive_group(requiredTrue) source.add_argument(--repo, helpGitHub repository in owner/repo format) source.add_argument(--path, helpLocal git repository path) parser.add_argument(--config, defaultpolicy_config.json, helppolicy config json path) parser.add_argument(--output, helpwrite JSON report to file) return parser.parse_args()--repo和--path使用互斥组避免一次同时传入两个数据源。requiredTrue保证调用者必须明确选择一种模式。4. 运行、验证与接入 GitHub Actions4.1 在本地仓库模式运行并解读输出先复制一个现成仓库到本地例如git clone https://github.com/octocat/Hello-World.git cd Hello-World然后运行python repo_policy_score.py --path .在本地模式下脚本会扫描当前目录文件。CONTRIBUTING.md、CODE_OF_CONDUCT.md、CI 工作流等如果不存在会标记为passed: false。本地模式无法读取仓库描述和开放 Issue因此has_description、has_good_first_issues会自动记为skipped: true避免因为信息缺失而误判。这种模式适合用在批处理场景。例如团队整理了 50 个候选仓库想评估哪些仓库文档齐全可以用一个循环调用脚本并把输出写入不同 JSON 文件for repo in repo-list.txt; do git clone https://github.com/$repo.git /tmp/score-repo python repo_policy_score.py --path /tmp/score-repo --output reports/$repo.json done如果仓库体积较大批量克隆会花不少时间可以只克隆默认分支并做浅克隆git clone --depth 1 https://github.com/$repo.git /tmp/score-repo浅克隆对评分结果是足够的因为评分只需要文件是否存在不需要历史记录。4.2 API 模式运行并处理两种失败现象远程模式不需要 clone 仓库直接传入 owner/repoexport GITHUB_TOKENghp_xxx python repo_policy_score.py --repo octocat/Hello-World脚本会先请求仓库元数据再请求默认分支的完整文件树。得到文件树后检查逻辑与本地模式基本一致。唯一区别是远程模式可以读取description、检测 CI 工作流并通过开放 Issue 统计good first issue标签。运行中可能遇到两种失败现象第一种是返回404 Not Found。这通常意味着 owner/repo 拼写错误或者仓库不存在。检查时可以去掉 Token 再调用一次开放接口或者直接打开浏览器访问https://github.com/owner/repo确认仓库是否公开可见。第二种是返回403 rate limit exceeded。这说明 API 配额已经用完。原因可能是未配置 Token也可能是同一 IP 下短时间发起了太多请求。处理方式是设置GITHUB_TOKEN并让两次扫描之间至少间隔几秒sleep 2如果脚本本身出现超时优先判断网络能否稳定访问api.github.com。可以先执行curl -I https://api.github.com如果curl能返回响应但 Python 脚本超时重点检查SSL_CERT_FILE、HTTP 代理相关环境变量等终端配置是否不一致。这里的排查顺序是先确认网络连通再确认 Token再确认仓库拼写最后看 API 返回体中的 error message。4.3 用 GitHub Actions 定时跑分并生成报告RepositoryPolicyScore 不仅可以作为本地命令行工具也可以放进 GitHub Actions让仓库定期检查自身。例如每周一早上运行一次把结果提交到score-report/目录name: repo-policy-score on: schedule: - cron: 0 1 * * 1 workflow_dispatch: permissions: contents: write jobs: score: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Set up Python uses: actions/setup-pythonv5 with: python-version: 3.12 - name: Run score env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | python repo_policy_score.py --repo ${{ github.repository }} --output score-report/current.json - name: Commit report run: | git config user.name repo-policy-bot git config user.email actionsusers.noreply.github.com git add score-report/ git diff --quiet git diff --cached --quiet || git commit -m chore: update repo policy score report git push这里要注意secrets.GITHUB_TOKEN默认只对当前仓库的公共资源有读取权限。如果要扫描其他仓库需要在 workflow 里配置更细粒度的 Token并保存为环境变量POLICY_TOKEN不要直接在命令里写明文。注意让 Action 自动提交报告前要确认仓库没有开启强制推送保护和变更规则限制否则git push可能失败。5. 常见问题、排查链路和最佳实践5.1 常见报错与排查顺序问题现象常见原因检查方式处理建议--repo返回 404owner/repo 拼写错误或仓库不存在检查输入格式访问仓库主页修正 owner/repo 后再运行API 返回 403未配置 Token 或配额耗尽查看响应头和错误信息设置GITHUB_TOKEN并降低请求频率本地模式缺少多个文件clone 的不是默认分支仓库目录结构特殊查看分支名和根目录切换到默认分支或调整文件路径匹配规则配置文件权重不生效配置文件和脚本不在同一目录打印加载到的 config 内容使用绝对路径指定--config分数明显偏低skip没有排除不适用的检查项查看报告中的 skipped 字段在配置中补齐 skip 列表Windows 下路径匹配失败本地模式使用了\分隔符打印待匹配路径统一把路径转为小写并替换为/排查时需要按照“输入 - 路径 - 配置 - 权限 - 网络 - 日志”的顺序来。先确认命令行参数是否正确再确认仓库路径和文件名是否大小写一致然后看配置里是否误删了权重最后处理 Token 和网络问题。不要一上来就怀疑评分逻辑大多数偏差来自输入和配置。5.2 低分仓库从哪里开始改进如果评分结果低于 60最值得优先补齐的不是花哨的自动化而是三个基础入口第一补README.md。README 要让一个完全不了解项目的人知道“这是什么、能干什么、怎么跑起来”。很多仓库的 README 是一段功能列表缺少安装命令和最小示例这会让 AI 工具无法从文档中提取有效的构建步骤。建议在 README 中明确写清前置依赖、安装命令、测试命令和常见环境变量。第二补CONTRIBUTING.md。这份文件是贡献流程的核心。内容包括分支命名、提交信息规范、代码格式、测试要求、如何提交 PR、如何报告问题。AI 工具生成 PR 时会优先从这类文档中提取约束。第三补 Issue 模板和 PR 模板。模板的作用是强制输入结构。没有模板时AI 可能会生成一段信息密度极低的 PR 描述有模板时它必须填写变更类型、影响范围、测试结果这些字段评审人的理解成本会显著下降。之后再看 CI 工作流。CI 不是给机器人看的摆设它能在提交进入评审前就执行构建和测试。机器人提交的代码如果连基础测试都没有维护者会花大量时间做重复劳动。把 CI 配置到.github/workflows/后RepoPolicyScore 也会自动识别。如果项目想进一步表达“欢迎 AI 辅助贡献”可以在根目录增加AGENTS.md说明 AI 工具可以构建、测试、在读代码时关注哪些目录以及哪些操作是禁止的。这个文件目前不是 GitHub 的强制标准但作为一种新的协作约定它正在被更多项目接受。5.3 如何把评分结果真正用到协作决策里最后要说一个设计边界RepoPolicyScore 只能回答“文档和流程是否就绪”不能回答“AI 是否应该提交代码”。后者还涉及代码质量、测试覆盖、审查机制和回滚策略这些必须由维护者判断。实际库不建议把 100 分作为硬性门槛。可以把评分结果分成三层使用。第一层扫描阶段。用脚本筛选一批候选仓库分数高的优先进入人工复审。这样可以把时间浪费在明显不完整的仓库上的可能性降到最低。第二层治理阶段。定期对自己维护的仓库跑分把分数变化当成协作入口的一种监控指标。某个版本更新后分数从 85 降到 60通常说明新增文件覆盖了原有文件或者 CI 配置文件被移动到了错误路径。第三层沟通阶段。当外部 AI 工具提供了不合理 PR 时你可以把评分报告中的缺失项作为反馈依据例如“请先阅读CONTRIBUTING.md”“仓库目前没有 CI请先补充测试”。这比一句干巴巴的 reject 更有信息量。扩展方向上可以继续支持更多检查项检测仓库是否配置了 branch protection。检测.github/dependabot.yml是否开启依赖自动更新。检测最近 30 天的 PR 关闭率和平均响应时间。按类型输出建议例如“缺少 CI”对应推荐的工作流模板。如果你刚开始练习最值得做的不是把脚本写得复杂而是先用默认配置扫描自己的仓库亲眼看一看每条检查项的输出结果。把分数从 50 改善到 80 的过程就是建立仓库协作规范的过程。