Jev 给这行打标签，代码负责调用。
TL;DR: README Clew 2 用于检查公开 GitHub 仓库的 README 是否与其代码一致，适用于 JavaScript 和 TypeScript 项目。一个名为 Jev 的小型决策模型为每行 README 的说法贴上标签，五项固定的代码检查判断其真伪，而 Claude Haiku 负责撰写摘要。我用 AdaL 在五天内完成了它，AdaL 是 SylphAI 的编码 Agent，这是为 AdaL 的 "What Would Jev Do?" 黑客马拉松而构建的。它的首次真实测试是在我的旧仓库上进行的，结果出错了。
AdaL 的 "What Would Jev Do?" 黑客马拉松只有一个要求：使用 SylphAI 的编码 Agent AdaL 构建一个项目，让 Jev 得到实际应用。我并没有待解决的问题。我只有模型和截止日期。
Jev 是 TypeSafe 提供的一个小型决策模型。DigitalOcean 的文章将其称为“一个不能写句子的 AI 模型”，这正是它的设计目的。你给它一个问题、回答的规则以及一组固定的标签。它会选择一个标签，并给出一个 0 到 1 之间的确定度数字。你通过 Glasser 使用它，Glasser 负责运行 Jev 调用并按次收费。
我又想起了之前的理由。五月份，我因为总担心自己的 README 与仓库不一致，于是构建了 README Clew。它确实起作用了，它的 README 列出了两个诚实的局限。我们让 Claude 按照逐字引用 README，这属于提示词规则，而非代码检查。它有时会把诸如 “Frontend (Vite)” 这样的散文标签当作包名读取，从而产生误报。
这两个局限都属于标注问题。标注正是 Jev 所做的唯一事情。
clew（读作 clue）是一团线。在希腊神话中，阿里阿德涅给了忒修斯一个 clew，让他能够顺着线找出迷宫，而“clue”一词正是由此而来。README Clew 沿着每一行 README 的线索追溯到代码。这也是我开发的 Clew Suite 公民技术工具集的名称。
README Clew 2
检查 GitHub README 与代码是否一致。
在线： https://readme-clew-2.vercel.app
粘贴一个公开的 JavaScript 或 TypeScript 仓库，点击 SCAN，即可得到索赔账本：列出 README 中每条可检查的行、代码对其的说明以及决策者。
为 AdaL “What Would Jev Do?” 黑客马拉松而构建，时间为 2026 年 10 月 6 日至 11 日。
为什么叫 “clew”？ clew（读作 clue）是一团线。在希腊神话中，阿里阿德涅给了忒修斯一个 clew，让他能够顺着线找出迷宫，而“clue”一词正是由此而来。README Clew 沿着每一行 README 的线索追溯到代码。这也是作者的公民技术工具集的名称。
它的功能
README 会漂移。命令可能被重命名，环境变量可能被删除，包可能被替换，而 README 仍然承诺旧内容。README Clew 2 会读取……
它的功能
README 会过时。命令改名，环境变量删除，包被替换，而 README 仍在承诺旧内容。README Clew 2 逐行读取 README，并把每行归入四类之一：
| 类别 | 含义 |
|---|---|
| 矛盾 | README 说它，代码持不同意见 |
| 缺失 | 代码实现了，但 README 未提及 |
| 不可验证 | 没有代码检验能够测试它，或者 Jev 不确定该行属于哪种类型 |
| 已验证 | README 与代码一致 |
每行都显示准确的 README 行、代码证据以及裁决者：规则或 Jev。
这是 v1 的实际扫描结果。没有矛盾，且代码导入的四个包在 README 中未被命名。新版本审计了旧版本。
Jev 永远不会有最后一句话
我建立的规则是：模型永不决定什么是真实。
代码在不使用任何模型情况下，将 README 拆分成行并处理简单行：标题、徽章、空白行。其余行由 Jev 判断该行属于哪种声明类型：依赖、命令、环境变量、文件或 URL，或者无法通过代码检验覆盖的内容。
只有当 Jev 对该行属于四种可检验类型之一的信心达到 0.8 或以上时，才会送入代码检验。低于此阈值，则归入不可验证，并标注“Jev 不确定”。随后，五个确定性验证器读取 package.json、文件树和源码，作出判断。输入相同，输出相同。Claude Haiku 仅根据计数和名称在末尾生成简短摘要。它从不读取 README 行，因而含有植入指令的 README 无法与其交互。
这两种错误并不等同。将一行标记为不可验证只会略微降低覆盖率；将一条正确行标记为矛盾会损害你的信任。我借鉴了 MLH 上 Swift 的这一框架，他在同一天我编写 Jev 问题时发表了《我让 Jev 零错误，我仍在使用 Flash-Lite》。他的教训重塑了构建方式：不再描述 README 行长什么样子，而是说明每个检查器看不到什么；不给 Jev 提供任何示例；并且按行计算错误，而不按运行计算。
我的做法是把最可怕的失败转化为代码，而非提示词。只要某个包名仅出现在散文中，无论 Jev 有多确定，都不可能被标记为矛盾。
在保留的 32 行 README 上，使用固定设置运行两次：
| 指标 | 运行 1 | 运行 2 |
|---|---|---|
| 超过 0.8 阈值的错误标签 | 0 | 0 |
| 端到端的虚假矛盾 | 0 | 0 |
| 实际漂移发现 | 3 of 3 | 3 of 3 |
三十二行只是一个小样本。它只能说明‘足够安全可发布’，而不能给出具体的错误率。
完整扫描大约花费一美分。其中大约 0.009 美元是 Jev。
一个智能体，一个构建日志
我负责指导、验证和决策。AdaL 编写了代码和测试，运行了 Jev 评估，部署到 Vercel，并驱动真实浏览器进行 QA。Claude (Opus 5.5) 编写了规格和架构，在每个检查点审查了 AdaL 的工作，并编写了文档。
AdaL 每轮都从它读取的 AGENTS.md 出发：先提出方案，一次处理一个模块，仅触及命名的文件，在 QA 检查点停止。我上一次构建留下了一个 1,200 行的巨型文件，因此这次每文件限制 200 行，由一个会导致测试套件失败的测试强制执行。提示词中的规则仅是一个请求。失败的测试才是规则。
AdaL 全程遵循了这些步骤，而且速度很快。在计划模式下，它提出并确认计划如此之快，以至于我粘贴一个提示词，离开一下，再回来时工作已经完成。它还发现了没人让它找的真实 bug：
- Glasser，运行 Jev 调用的服务，将单次调用限制在 100 个问题。只有实时 API 如此说明，而 schema 没有。
- 一个计时器让测试悄悄取消而不是失败。
- 一个修剪器测量了错误的文本版本。
- 两个仅在真实浏览器中出现的布局 bug。 最后这一个让我感到惊讶。AdaL 启用了它自己的浏览器工具来截图并计时页面。我从未切换过它。
事情并不总是顺利。在文件写完且所有测试通过后，AdaL 在 “Create lib/report.js” 上停留了 22 分钟。只有屏幕卡住了。与去年相比，我本周的笔记本风扇转动得更频繁。AdaL 内部的 Glasser 连接器在我关闭它并报告之前，一直导致每次 Claude 调用失败。第四天，在我批准最大的代码块之后，我的每周计划额度用完了。
解决办法就在 AdaL 的文档中：自带 API key。我已经有了 Claude API 凭证。大约 35 分钟后，AdaL 在我的 key 上重新开始构建。
AdaL 团队值得单独一段。他们在我报告当天就修复了 Glasser 连接器。当我告诉他们我已经达到每周限额时，他们给我发放了额度，以便我能够完成。这是我第一次在黑客松中直接快速地与运营方联系，让为期五天的冲刺感觉不那么孤单。
吉祥物也体现了这种分工。AdaL 用代码绘制了第一个线索，以 SVG 面孔的形式呈现，然后提供了两种线球样式供选择。最终发布的那个是由 ChatGPT 绘制，随后由 Claude 裁剪并调整大小。擦除路径绘图的 Agent 和绘图的图像模型各有所长。
是我，我才是问题
除了连接器错误之外，这次构建中的大部分摩擦都源于我。
我害怕交付低质量的代码，于是我要求每个测试都至少展示一次失败。故意破坏代码，观察测试变红，然后恢复。在 Block 1 这意味着 102 个测试和 75 次有意的破坏。之后情况一直持续。
| 构建阶段 | 测试数 |
|---|---|
| Block 1 | 102 |
| Blocks 3 and 4 | 197 |
| Monorepo fix | 222 |
| Before the UI polish | 353 |
| Saturday night | 452 |
| Submission | 474 |
其中有些测试非常重要。守护五个检查器、0.8 阈值、文案规则以及 monorepo 回归的那些测试，正是保持 README 正确不被误判的关键。其余大部分测试只是重复验证浏览器已经覆盖的页面连线。对于一个五天的构建来说，这简直荒谬。
这也产生了真实的费用。每次有意的破坏都会触发一次完整的测试运行，而每次运行都消耗 Agent 时间。我的第二个新手错误是从未启动新的 AdaL 会话。每次交互都会重新发送整个对话，因此长会话中的后续交互成本最高。到周六晚上，我在大约三个半小时内已经花费了我为密钥设定的 50 美元上限中的 36 美元。
AdaL 完全按照提示词的要求执行。指导设定了标准，我和 Claude 都遵循了。
修复方法是在每个提示词顶部加入一个「lean mode」头部：每个块使用全新会话，只读取所需文件，对每个新测试文件只显示一次失败（而不是每个测试），最后一次运行浏览器 QA。其余的构建、加固、扩展、README 以及最后的修复大约花费 4 美元。Agent 的最终账单为 40.35 美元。该应用每次扫描成本约为一美分。
下次我会在每个块开始前设定测试预算，并将其与用户因失败可能产生的成本挂钩，而不是凭习惯。
它最初出错在于我的
第一次真实扫描是我自己的 v1 仓库。README Clew 2 标记了三行矛盾，并将四个包标记为 Missing。Claude 打开了 v1 的文件进行检查。全部七项均为误报。
v1 是一个 pnpm 单仓库，工作区位于工作区查找器未识别的文件夹。此外，pnpm 的 --filter 选项被误读为脚本名称。该工具在此点上出错，恰恰是它承诺永不出错的方式；就在我的仓库里，任何评审看到它之前几小时。
AdaL 在一个块中修复了它。现在它无法解决的内容返回 Unverifiable，而不再是 Contradicted，v1 成为已保存的回归测试。重新扫描后，Contradicted 从 3 降至 0，之前标记为 Missing 的四个包实际上是真实存在的。
对 polka 仓库的第二次实时扫描发现 14 个 Missing 包，它们全部来源于带有自身 package 文件的 examples 文件夹。修复方法相同，测试类型也相同。
最后两个问题源于我周六深夜提出的一个疑问：我们是否在故意制造假矛盾？Claude 重新读取了所有检查器，发现了两种新的指控正确 README 的方式。一个环境变量在第 20 个文件读取限制之后被使用。另一种情况是 README 指向 dist/ 构建输出，而这类文件从未被提交。AdaL 使这两种情况都返回 Unverifiable。
最后的 bug 来自于提出工具应回答的问题。
它不能做到
- 仅支持 JavaScript 和 TypeScript。在 JS 和 TS 中，单个文件
package.json同时列出包和命令。Python 将相同事实分散到若干可选文件中。没有package.json的仓库会收到明确提示，且不会调用任何模型。 - 大多数行最终显示为 Unverifiable。README 中的大多数文本是无法通过代码检测的散文。Unverifiable 表示“无法判断”，而非“错误”。
- 对单仓库的支持涵盖简单的工作区模式以及最多 30 个工作区。超出此范围，Missing 将转为 Unverifiable。
- 每次扫描最多读取 20 个源文件，并跳过超过 50 KB 的 README。
- 同一份 README 在两次扫描之间可能会将一条边界线移入不同的桶。0.8 的阈值能够将这种偏移保持在 Contradicted 之外。
有三种方式可以进入，它们都会触发同一次扫描：
| 方式 | 最佳场景 |
|---|---|
| 在线页面 | 您想要完整的账目，或者您正在使用手机，无需安装 |
| Chrome 扩展 | 您已经在该仓库的 GitHub 页面，只需点击一下 |
| 书签小程序 | 您无法安装扩展，例如在受限的工作电脑上；将其从关于选项卡拖出来 |
书签小程序存在是因为我的日常工作。工作电脑会阻止扩展，而一个打开已填充仓库页面的书签可以绕过此限制。
没有数据库也没有账户。扫描从不存储，日志仅保存计数和时间。由于没有保存任何内容，下载 JSON 会以文件形式提供报告，附带扫描凭证：仓库和提交、README 文本指纹以及报告指纹，以便以后判断是否被修改。没有模型会写入任何内容。将其附加到拉取请求，或保留作为前后对比。
在我提交之前，README Clew 2 扫描了自己的 README：285 行，发送给 Jev 154 行，耗时 5.6 秒。0 项矛盾，0 项缺失，1 项已验证，107 项无法验证。唯一已验证的行是 npm test，且 package.json 中包含测试脚本。这个 107 是诚实的数字。README 大部分内容是散文。在 "Built for the AdaL 'What Would Jev Do?' hackathon" 上，Jev 表示这不是可检查的主张，确定度只有 0.52，且该行从未接近任何检查器。
按下 USE DEMO REPO，然后点击 SCAN，观看新版本如何评分旧版本。代码、决策日志以及每一次错误操作都在仓库中。
如果你是新手，这里有一些快速背景。我在加利福尼亚州法院工作，负责县一级的法院运营。我从 2025 年 7 月开始使用 AI 构建项目，此后一直在公开学习。我不编写代码。我负责指导，智能体生成内容，我进行验证并做出决定。
本文写于2026年10月，是AdaL"What Would Jev Do?"黑客松的作品，AI辅助完成。其中Jev by TypeSafe通过Glasser调用。这类工具迭代飞快，引用时请以源代码为准。
AI辅助，人工把关，NLP驱动。
