企业官网建设流程全解析

这周收到一条让我印象很深的PR：提交者的头像是一个机器人，commit message写得规范工整，代码也过了编译，但把边界条件改错了。这不是我第一次看到AI直接往开源仓库发PR。GitHub上早就不是只有人类开发者在活跃，AI如今真的会读文档、提issue、开PR。于是我开始考虑一个更本质的问题：一个repo到底满足什么条件，才称得上"准备好"让AI贡献者进入？带着这个疑问，我做了RepoPolicyScore这个小工具，作用一句话就能说清——check if a GitHub repo is ready for AI contributors。它会拉取仓库结构、解析维护文档、检查CI和自动化配置，最后给这个仓库打一个0到100分的"AI贡献者就绪度"评分，并告诉你到底缺了什么。

1. AI贡献者不是"低配版人类开发者"，准备工作得另算

1.1 人类靠交情与提问补足的隐性信息，AI只能靠文档

大多数仓库维护者觉得"我的README写得挺全，issue也有人管，AI要贡献就贡献呗"，但实际上AI和人类开发者的行为模式差异非常大。人类新贡献者看一个陌生项目时，会先逛逛issue列表，看看最近有没有人在问类似问题，甚至直接在讨论区发一句"这功能怎么跑起来"。AI不会。它拿到提示词后，行为路径非常直接：读README，找入口，看代码结构，然后开始写改动。中途遇到不清楚的地方，它的默认策略是"从现有代码里推断出一个自洽的答案"，而不是向维护者提问。

这个推断过程正是大量低质量AI PR的来源。代码里存在已久的隐式约定，比如"这个工具函数只在server目录下使用""error handling必须走统一包装""import顺序按第三方包、本地模块、类型声明排列"，人类维护者能在review时靠经验和上下文自然遵守，但AI不具备这种项目内感受力。它更倾向于按照主流代码风格或者自己的训练语料来"补全"认知，结果就是：单独看每一行改得都不算错，放在整个项目语境里就非常违和。

1.2 就绪度评分的本质：把隐性知识显性化

RepoPolicyScore真正想评分的东西，不是"代码好不好"，也不是"文档多不多"，而是这个仓库把"隐形知识显性化"的程度。一个AI能够相对安全地贡献PR的仓库，一定具备以下能力：新贡献者能在15分钟内本地跑起来；代码规范能以lint脚本形式一键执行；测试命令明确、能快速反馈；贡献指南写明了PR范围、commit格式和分支策略；issue模板和PR模板能强制提供足够上下文。

这些条件几乎每一项都在做同一件事——把原本存在维护者脑子里的规则，变成机器和AI都能读取的文件、脚本和配置。理解了这层逻辑，评分维度的设计就有了统一的指导思想：我检查的不是文档数量，而是知识被"文件化"和"可执行化"的程度。

2. RepoPolicyScore的评分维度拆解：每个分数都有明确出处

RepoPolicyScore并不是一个简单的"文件存在性检查器"。如果只判断有没有CONTRIBUTING.md，那这个工具三小时就能写完，但没什么用。实际开发过程中，我针对每个维度都设计了"文件存在 + 内容质量 + 可执行性"三层校验，具体维度如下：

2.1 贡献指南不能只看"有没有"，要看能不能执行

CONTRIBUTING.md在这个评分体系里占了最高权重，但检测逻辑并不简单。很多仓库有这份文件，打开一看却是空泛的套话："We welcome all contributions.""Please fork and submit a pull request."这种情况下，AI读了和没读没区别。我的解析逻辑是：先用tree-sitter-markdown把文档的标题结构解析出来，再确认是否覆盖了几类关键section：Getting Started、Build、Test、Code Style、Pull Request Process。如果标题不完全匹配，就做关键词模糊匹配，比如"npm install""poetry install""go mod tidy""docker compose up"这类环境搭建命令，以及"pytest""go test""npm test""cargo test"这类测试指令。

只有同时具备"环境搭建命令"和"测试执行命令"，这份贡献指南才会被判为有效。这个设计是从实际教训里来的：我开始只检查标题结构，结果一个测试项目的CONTRIBUTING.md写了完整的"如何提PR"，但整篇没有一个命令，AI按文档操作根本跑不起来，评分还给了80以上。后来才加上命令检测，至少把"能执行"这条底线守住。

2.2 README评分的反直觉之处：代码块比文字更有价值

README的评分方法相对温和。我先用tree-sitter解析出所有二级标题和三级标题，然后重点找Quick Start、Getting Started、Installation、Usage这几个section。关键指标其实是这些section内嵌的代码块数量和非空命令数量——一个只有截图、没有命令的README，AI根本无法上手。相比之下，哪怕README只有五十行，但有一个完整的快速开始命令，实际可用性反而更高。

经过几十个仓库的测试，我得出的经验值是：一个对AI友好的README，至少包含一个安装命令、一个最小可用示例、一个运行测试的方式。这三个信息不一定要齐全，但缺一不可的其实是"运行测试的方式"。AI拿到一个项目后，最想做的事就是快速证明自己没把环境搞坏，如果README没写怎么跑测试，它大概率会自己猜，猜错的概率并不低。

3. 技术实现剖析：从GitHub API到文档解析的完整链路

3.1 核心技术选型与原因

实现RepoPolicyScore时我选择的是TypeScript + Node.js，主要理由有三个：第一，Octokit是成熟的GitHub REST API客户端，省去大量鉴权和请求细节；第二，tree-sitter官方提供了tree-sitter-markdown的Node绑定，可以直接把Markdown解析成AST结构，比正则匹配稳定得多；第三，CLI工具用Node打包发布，对应的生态已经非常成熟，最终产物可以一个命令搞定。

整个工具的运行时序分四段：先通过GitHub API获取仓库的默认分支和完整文件树，再按需拉取关键文件内容，然后逐一跑各维度的检测规则，最后汇总评分并输出Markdown格式的报告。

3.2 一个关键优化：用Git Trees API减少请求次数

最初版本是逐文件调用API获取内容，一个检测目标至少要发十几个请求，遇到大仓库很容易撞上GitHub API的限流。后来我改成调用一次Git Trees API，用递归方式把整个默认分支的文件树拉回来，再在本地过滤出需要解析的文件路径，只有真正需要的文件才走Raw类型的contents接口。经过这个调整，评分一个仓库通常只需要5到7个API请求，花费的时间大幅下降。

GitHub API的限流是个要特别留意的问题。匿名请求一小时只能发60次，哪怕拿到token也只有5000次/小时，但实际跑批量评测的时候，最怕的是跑一半突然收到403。RepoPolicyScore的处理方式是支持加载GITHUB_TOKEN环境变量，并在每次请求后检查响应头里的ratelimit-remaining字段，低于安全阈值就停止评测，给出提示。这个设计看起来不起眼，但在你一口气评测几十个仓库的时候，能避免大量无效请求。

3.3 解析Markdown结构时的取舍与坑

用tree-sitter-markdown解析文档，比正则表达式稳定，但也不是没有坑。Markdown里的heading如果包含链接、内联代码，AST的节点类型会有差异，比如### Quick Start是atx_heading，而### <a name="quick"></a>Quick Start会拆成多个子节点。我在做heading归一化时，需要把每个heading节点的所有子节点文本拼起来，再统一转小写、去掉标点。另外，有些仓库的README会写# GETTING STARTED，或者## Quickstart，单纯匹配"Quick Start"会漏判。

我最终的方案是构建一个同义词表，把Getting Started、Quickstart、Quick Start、Installation归为一组，Usage、Examples、API Reference归为一组，然后按优先级排序，读到任何一个就算命中对应维度。这个表需要根据实际仓库的表现持续维护。GitHub上不同语言项目的文档习惯差异很大，Rust项目爱写"Usage"，前端项目爱写"Getting Started"，Go项目可能直接放一个example.go，如果词典不够宽泛，评分会失真。

3.4 CI状态检查：动态与静态两条腿走路

对于仓库的CI情况，RepoPolicyScore从两个角度判断：第一个是静态角度，检查.github/workflows目录下是否有YAML文件，是否存在test、build、lint相关的工作流；第二个是动态角度，调用GitHub的commits status接口，查默认分支最新一次提交的combined status是success、pending还是failure。

动态检查受网络和GitHub服务状态影响比较大，偶尔会出现仓库本身没问题、GitHub API临时抽风导致查不到状态的情况。所以在动态检查失败时，我选择直接跳过该维度而不判零分，避免把服务可用性问题错误转化为"仓库就绪度低"的结论。如果是真实环境里的CI红叉，那才是真正需要扣分的点，通常一个常年构建失败的仓库，AI贡献者改了代码也得不到有效反馈，整体的就绪度分数一定高不了。

4. 实测复盘：高分局与低分局之间真正的差距

写到这里，很多人肯定会问：拿真实仓库跑一遍结果如何？我在开发过程中评测了多个类型的仓库，覆盖活跃的中小型工具库、文档体量很大的老牌项目，以及已经被AI PR淹没的社区项目，下面把印象比较深的几种典型情况整理一下。

4.1 典型的高分仓库长什么样

高分区仓库通常有一个共性：CI配置非常完整，而且工作流拆分得很细。比如一个前端组件库，它的.github/workflows目录里会同时存在lint.yml、test.yml、build.yml三个独立文件，每个文件的触发条件都很明确，test还会分node版本矩阵跑。这类仓库的CONTRIBUTING.md同样可读性很强，开头就是一个"Prerequisites"列表，明确写出Node版本要求、包管理器要求，然后是四五个复制粘贴就能跑的命令。

给这类仓库打出80分以上的时候，我去翻了它们近期合并的PR，发现AI生成的提交其实已经混入其中，而且大部分能通过自动化检查。这印证了一个观点：CI和文档完备的项目，对AI贡献者的接受度天然就高，因为大部分质量门槛自动化兜住了。

4.2 看起来用心、实际拿低分的仓库类型

另一种让我比较意外的仓库类型是"文档丰富但命令缺失"。有个项目README洋洋洒洒几千字，贡献指南里甚至细到commit message的动词含义，但整个仓库找不到一条可执行的本地构建命令，也没有自动化测试。这种仓库的分数很尴尬——维护者显然花了心思，但AI贡献者进来了几乎寸步难行，它能读到大量规则，却无法验证自己的改动对不对。

这类仓库恰恰解释了为什么RepoPolicyScore必须坚持"可执行性"原则：文档是给人看的，命令和脚本才是给AI执行闭环用的。评价AI就绪度，必须优先尊重AI的"行动导向"特性。

4.3 评分失真案例：分支保护信息获取的权限问题

开发过程中还遇到过一类错判。某个仓库各项配置都很完善，但动态检查分支保护时返回了403，结果分支保护维度被判成"未启用"，总分明显偏低。后来排查发现，GitHub REST API对于分支保护信息的匿名访问极其严格，很多字段不授权就拿不到。RepoPolicyScore在这个维度上做了一层降级处理：如果拿不到分支保护数据，就根据仓库是否配置了CODEOWNERS文件来做推测评分，并在报告里专门说明"当前无权限读取分支保护设置，该维度结果不完整"。

这个处理方式适合很多类似的"权限受限"场景，宁可降级成半可信分数，也不要直接当成问题项报给用户，不然维护者会为了一个误报去反复折腾配置。

5. 拿到低分之后：维护者实际改造仓库的推荐顺序

RepoPolicyScore的价值不仅在于打分，更在于给出可执行的修复建议。每个报告里，低分维度后面都会附一段"为什么扣分"和"建议改动"的说明。基于我自己跑完一批仓库后的经验，我归纳了一个改造顺序，适合时间有限的维护者按优先级推进。

5.1 第一优先级：把测试和CI跑通

任何仓库要接受AI贡献者，第一步不是写文档，而是确保现有测试能在CI里稳定通过。AI的行为模式非常依赖反馈循环，提交-触发CI-看结果-改代码，这个循环越快越稳定，AI改进PR的效率就越高。如果CI本身常年是红的，AI根本无从判断自己的改动是否引入了新问题。

在这个阶段，也不需要一次搞定复杂的工作流，先来一个最简单的测试工作流就够了：

name: test on: pull_request: push: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - run: npm test - run: npm run lint

5.2 第二优先级：给AI一行命令就能复现的自检流程

AI与人类不同，它不会去开一个bash终端调试半天，它更愿意遵循文档里给的命令步骤。因此CONTRIBUTING.md里一定要有一块"How to verify your changes"，这块要写得极其死板：从安装依赖，到跑lint，到跑单测，到跑集成测试，一步一步列清楚。我在自己的项目里甚至会把每个命令都写成代码块，让AI可以直接复制。

建议直接复制这份最小模板，比大多数仓库现有的CONTRIBUTING.md更适合作为起点：

# Contributing ## Prerequisites - Node.js 20+ - pnpm 9+ ## Setup 1. pnpm install 2. cp .env.example .env ## Verify - pnpm lint - pnpm test - pnpm build ## Pull Request Rules - Keep PRs focused on one concern - Add tests for any logic changes - Do not modify files outside the scope of your PR

5.3 第三优先级：用模板与自动化配置约束PR形态

第三优先级是GitHub的issue和PR模板。我不建议写很长的模板，AI填长模板时很容易产生超长废话，反而淹没关键信息。更好的做法是写一个紧凑的清单式模板，要求提交者明确写出改动目的、测试方式、以及是否新增了依赖。比如PR模板可以包含三个固定问题：这个问题解决什么场景、如何验证改动、改动涉及哪些文件。

分支保护也建议尽早打开，至少给main分支配置"要求PR通过后再合并"，同时设置一个CODEOWNERS文件，把核心目录的审查责任落到具体维护者头上。对AI贡献者来说，"有明确review人"是一种安全网，即使它写出了有问题的代码，至少不会直接污染主线。

5.4 最容易忽略的一步：明确告诉AI哪些事不能做

大多数开源仓库的贡献指南都在写"我们欢迎什么"，但很少写"我们禁止什么"。AI恰恰需要这个负面清单。我建议在CONTRIBUTING.md里明确列出几条硬性规定，例如"禁止无关联的重构""禁止修改格式化配置""禁止批量替换API调用""禁止升级锁文件里的传递依赖"。这不是要限制AI创造力，而是给它的行为划一个边界。

从实际效果看，这份负面清单能显著减少"AI顺手把整个文件格式化了一遍"这类最令维护者头疼的PR。有时候AI提交的问题不在逻辑，而在它太爱顺手做很多无关的修改，明确禁止项可以大幅降低review负担。

6. 工具边界和后续方向：静态评分只能做到这一步

RepoPolicyScore的定位很清楚，它是一个"静态就绪度检查器"，不是"AI贡献效果预测器"。它无法判断一个仓库的代码架构是否清晰、测试覆盖率是否足够、模块耦合度是否合理，更无法预判AI进入之后会不会把代码库搅成一团。这些动态质量问题需要结合代码分析工具和实际PR表现来综合判断。

在后续迭代里，我在考虑两个方向。一个是把CI最新的运行状态引入评分缓存，让分数不再是一个瞬间快照，而是能反映过去三十天的持续通过率；另一个是尝试引入LLM对文档的自然语言质量做一次粗评，比如自动判断README的描述是否存在明显歧义，贡献指南是否覆盖了环境搭建的例外情况。不过这两个方向都还比较早期，稳定性还需要大量样本验证。

从实际使用体验来说，RepoPolicyScore最适合的场景是：你维护的仓库已经有了一些AI PR涌入，但quality参差不齐，你想知道自己仓库在流程上哪里最薄弱。它不适合作为"是否欢迎AI"的道德判断工具，有人就是不想接受AI贡献，这完全没问题，工具只负责呈现客观状态，不负责劝人改变立场。

最后分享一个我评测大量仓库之后的最大感触：很多仓库表面看维护得不错，一旦用"AI能不能直接上手"这个标准重新审视，到处都是隐性断层。这反而是一个很好的自省契机——让AI贡献者顺利工作的那些要求，本质上是让所有新贡献者都更舒服的要求。把规则从维护者的大脑里搬到仓库里，受益的远不止机器人。