Sweep
让 AI agent 把一个代码库查全的工具:先用程序列出所有该查的格子,agent 一格一格填,表上还有空格就说明没查完。
为什么
让 agent 自由扫描代码,它会从某个入口顺着一条线读,读满上下文就停,没读到的地方没有记录。所以每次扫都有"新发现",却永远说不清扫全了没有。
Sweep 先定分母,再填格子:
视角(列)
logic guard async errors ... hard-one
单元(行) ┌──────┬──────┬──────┬──────┬───┬────────┐
函数 A │ 无问题 │ 问题 │ 不适用 │ 无问题 │ │ │
函数 B │ 空 │ 空 │ 无问题 │ 空 │ │ │
写死值 120 │ │ │ │ │ │ 问题 │
└──────┴──────┴──────┴──────┴───┴────────┘
覆盖率 = 已填格 / 适用格
- 行(单元)由程序生成:函数、跨文件重复的字面量、复制的代码块、同名函数、做同一件事的两个入口、全部用户可见文案、写死的值、外部输入到危险操作的调用链、agent 登记的机制。后面几种专门对付"同一件事在另一个地方做得不一样",这是逐函数阅读结构上看不到的。
- 列(视角)是固定的问题清单,在
lenses.json。不适用的格子由程序判定。
- 一个包只带一个视角,agent 一次只拿一份清单,查得更深。
record 全有或全无:包里每格都要答;"无问题"必须写出看过的行号;有问题必须写出具体场景。
- 每格记着单元内容的哈希。改代码后
scan 让变了的格子重新变空,调用了被改函数的那些函数也一起重开(改了返回值或报错,调用方最容易坏),日常只补这些格子。
- 核实发现时,项目能跑测试就写最小复现,核实结论里写明复现没有。
安装
需要 graphify(uv tool install graphifyy),sweep 借它的调用图和 tree-sitter 语法。sweep.py 用系统 python3 启动,找不到 tree-sitter 时自动换到 graphify 的解释器。
作为 Claude Code / Codex 的 skill 使用:把这个目录链接到 ~/.claude/skills/sweep(Codex 是 ~/.codex/skills/sweep)。agent 按 SKILL.md 的流程用它。
用法
S=/path/to/Sweep/sweep.py
$S --root <项目> init --include 'src/*' --exclude '*.test.*' # 建表
$S --root <项目> status # 覆盖率
$S --root <项目> next [--path x.js] # 领一个包(worker 用)
$S --root <项目> record <包号> <answers.json> # 交答案(worker 用)
$S --root <项目> scan # 改代码后:只重开变了的格子
$S --root <项目> dedupe && $S --root <项目> report # 去重,出问题清单
$S --root <项目> judge F12 confirmed "理由" # 核实结论
$S --root <项目> sample --pct 10 && … && $S --root <项目> estimate # 抽检,估算漏了多少
状态存在项目里的 .sweep/sweep.db,init 会把 .sweep/ 和 graphify-out/ 加进 .git/info/exclude。
实测(MoonDigest,2026-10-16)
|
结果 |
| 试点(2 个文件,拿后来修掉的 71 条当标准答案) |
v1 找到 17 条;加跨文件单元、每包一个视角后 30 条 |
| 验证(分拣台 3 个文件,94 条标准答案) |
44 → 加写死值单元和匹配修正后 54 条;写死类 37/46 |
| 全仓(19k 行,7050 格,511 包) |
去重后 762 条;81 条中等核实成立 57 条;681 条低严重度逐条核对后修了 441 条 |
另一个发现:sweep 和以往的自由扫描各自只抓到对方的约三分之一,两者重叠很少,说明两种方法都远没扫全。
成本
每 1000 行生产代码约 20 个包、80 万 token;一个 worker 做 5–6 个包约 20–30 万 token。全仓一遍约 2000 万 token、2.5 小时。之后只扫改动的部分。
不覆盖什么
只查视角问到的问题。行为类问题(状态、时序、跨入口协议)的召回率仍明显低于文案和重复类。只在真实环境里出现的行为,比如真浏览器、真网络,还要靠项目自己的冒烟测试。反复出现的类别应该写成项目的 lint,不靠每次扫描。
许可
MIT,见 LICENSE。