用 Git Trees API 做仓库文档一致性核查:一条可复现的取证流程
用 Git Trees API 做仓库文档一致性核查:一条可复现的取证流程
开源仓库最常见的质量问题不是"缺少文档",而是"文档写着的东西,仓库里已经不是那样了"。这类问题在中文技术社区通常被叫做文档漂移(document drift):README 是三个月前写的,脚本已经迭代了两轮,函数签名换了、默认参数改了、目录结构挪了,但没人回头看文档。读者照着文档跑,第一步就报错,然后在 issue 区问"为什么跑不起来"——而维护者往往要等到第十个这样的提问,才意识到文档过期了。
我在华为云 AI Agent 开发实践中心(GitCode 上的 agent-best-practices 组织)陆续核对过十来个仓库的文档,用的不是"通读一遍凭感觉找问题",而是一套可以复现的取证流程:把"文档声称的东西"和"仓库实际的东西"分别取出来,做机械比对,只保留能指到"哪一节、原文是什么、哪里对不上"的差异。下面把这套流程写清楚,包括数据源、比对维度、误报防范,以及一次真实的取证案例。
一、三个数据源就够了
核对文档不需要 clone 仓库,也不需要 token。GitCode 提供了三类可以直接读取的原始数据,用任何能发 HTTP 请求的工具都能拿到:
- 单个文件的原始内容:
https://raw.gitcode.com/{owner}/{repo}/raw/main/README.md。注意是raw.gitcode.com这个独立域名,不是网页地址加/raw/。返回的是纯文本,不会掺 HTML,拿去比对最干净。 - 完整文件树:
https://gitcode.com/api/v5/repos/{owner}/{repo}/git/trees/main?recursive=1。返回 JSON,tree数组里每个条目有path、type(blob/tree)、size。recursive=1会一次性展开所有子目录,几千个文件也能一次拿完,比逐层翻页面快得多。 - 任意脚本或配置的原文:把
README.md换成对应路径即可,比如raw/main/scripts/fix_excel.py。
这三样东西的组合覆盖了绝大多数文档漂移:文件树回答"文档提到的文件在不在",raw 回答"文档描述的用法和脚本实际支持的是不是一回事"。
二、比对维度清单
拿到数据后,我按固定顺序过六个维度。这个顺序是从误报率低到高排的,先查确定性高的,避免一上来就陷进主观判断。
第一,文档提到的路径是否存在。 从 README 里抽出所有反引号包裹的路径和所有 https://gitcode.com/{owner}/{repo}/blob/main/... 形式的链接,逐个到文件树里查。这一步几乎不会误报:路径不存在就是不存在,可能是文件改了名,也可能是从来没提交过。
第二,文档示例命令引用的脚本是否存在。 比如 README 写 python scripts/check.py --fix,但文件树里只有 scripts/fix_excel.py,没有 check.py。这类问题在重构后特别常见——脚本改名了,文档里的示例没跟着改。
第三,参数名是否与脚本实际解析的一致。 这是最容易被忽略、但对读者伤害最大的一类。做法是把脚本里的参数声明抽出来(Python 的 argparse 会写成 add_argument('--xxx'),Node 的常见 --xxx 字符串),和 README 示例里的参数做集合比对。只要出现"文档里有、脚本里没有"的参数,读者必然报 unrecognized arguments。
第四,版本号是否自洽。 版本号最容易出现"同一份材料里两个数字互相打架":README 徽章写 0.1.0,pyproject.toml 写 0.2.0,脚本里还有一行 __version__ 写 0.1.3。三个地方三个值,读者不知道该信哪个。核查时要把所有出现版本号的位置列全,而不是只看最显眼的那一处。
第五,目录结构与实际文件树是否一致。 README 里常见的"项目结构"代码块,写的是理想结构,实际仓库早就多了两层。把代码块里的缩进树解析成路径列表,与文件树做差集,多出来的和少掉的都能列出来。
第六,只在一处提过的关键限制。 这类不是"矛盾",而是"缺失":比如某个脚本只在 README 末尾一句括号里提过"需要 Python 3.9+",而它用了 3.10 才有的语法;或者某个平台限制只写在 issue 里,文档完全没提。它比前五类难判定,但一旦确认,价值也最高,因为读者踩坑时无处可查。
三、一段可以直接改用的核对代码
下面这段是流程的最小实现,跑在 Node 里(浏览器控制台或本地都行),把"文档声明的路径"和"实际文件树"做差集:
const owner = 'agent-best-practices', repo = 'excel-formula-explainer';
const base = `https://gitcode.com/api/v5/repos/${owner}/${repo}`;
const [tree, readme] = await Promise.all([
fetch(`${base}/git/trees/main?recursive=1`).then(r => r.json()),
fetch(`https://raw.gitcode.com/${owner}/${repo}/raw/main/README.md`).then(r => r.text()),
]);
const actual = new Set(tree.tree.filter(t => t.type === 'blob').map(t => t.path));
// 抽出 README 里反引号包裹的、看起来像路径的片段
const claimed = new Set(
[...readme.matchAll(/`([\w./-]+\.(?:py|js|ts|sh|yml|yaml|json|toml|md))`/g)]
.map(m => m[1].replace(/^\.\//, ''))
);
const missing = [...claimed].filter(p => !actual.has(p));
console.log('文档声称但仓库中不存在的文件:', missing);
console.log('文件总数:', actual.size, '文档提及:', claimed.size);
同样的思路可以扩展出参数比对:把 add_argument 的正则结果和文档示例里的 --xxx 做交集/差集。代码不长,但它把"凭感觉读文档"变成了"两个集合做减法",结论可复核,也方便写进 issue 里让别人复现。
四、一次真实的取证
11 月初我在 excel-formula-explainer 这个仓库上跑了一遍上面六个维度,命中的是第四类(版本号不自洽),而且是一个挺典型的结构性问题:
README.md的版本徽章和正文示例里,标注的是 v0.2.0;- 仓库根目录的
pyproject.toml里,version字段是 0.1.0; scripts/fix_excel.py里有一个VERSION常量,值是 0.1.0,而这个脚本被 README 描述为"自检工具"。
关键在于最后一条:这个脚本本身是用来做一致性自检的,但它不检查自己的版本常量,也不检查 pyproject.toml 与 README 的关系。也就是说,一个号称"帮你核对版本"的工具,恰好漏掉了版本这个维度——这比单纯的数字写错更值得提,因为它说明自检的覆盖面有结构性缺口。
这条 issue 的写法是这样的(四段固定结构):
- 位置:
README.md第 1 节版本说明 +pyproject.toml第 7 行 +scripts/fix_excel.py第 12 行,三处原文各引一句。 - 现象:三处版本号给出两个不同值,且自检脚本不覆盖自身版本,导致"用自检工具核对后仍然不一致"。
- 为什么值得改:读者按 README 安装
v0.2.0,实际拿到 0.1.0 的包;自检脚本跑通会给出"通过"的假信号。 - 建议:把版本号收敛到单一来源(
pyproject.toml),README 徽章改为动态读取,自检脚本增加一条"文档版本 == 包版本"的断言。 - 已核对过什么:明确写出读了哪三个文件、用的什么地址(raw 直链)、版本号出现在第几行,让别人能一条条复核。
这条 issue 提交后没有争议,因为它不含任何主观评价,全部是可复核的事实。
五、误报防范:什么不该提
核查流程最大的风险不是漏报,而是把噪声当问题提上去,浪费维护者时间。下面几类我明确不写:
- "建议加强文档建设"这类没有落点的建议。它无法被验证,也无法被关闭。
- 基于猜测的 bug。没读原文就写"这里可能有误",等于把排查成本转嫁给维护者。
- 风格问题。中英文混排、标点、标题层级,这些属于个人偏好,不是文档漂移。
- 上游依赖的问题。某个库自己改了 API 导致示例失效,应该提给上游,不是这个仓库。
- 需要改动代码才能验证的猜测。"如果把这里改成那样可能会更快"不是文档问题。
另外一条纪律:只提建议,不动代码。核查者手上没有完整上下文,直接提 PR 改文档或脚本,很容易引入新的不一致;把取证过程写清楚,让维护者自己决定怎么改,成功率反而更高。
六、把流程变成习惯
这套流程跑熟之后,单个仓库的核对时间大概在十分钟以内:取文件树和 README 两次请求、跑一遍正则比对、人工看一遍差异、写一条 issue。它的价值不只是"给开源项目做贡献",更在于反向检查自己维护的项目——你写的那份 README,是不是也已经漂了三个月?
如果要把这件事做成日常,我的建议是把它接进 CI:不是拦截合并,而是在每次发版时跑一次差集,把"文档提到但仓库没有"的路径打印到构建日志里。漂移是渐进的,等读者来报错时,通常已经漂了很久。
- 点赞
- 收藏
- 关注作者
评论(0)