aislop - 给 AI 生成代码加一道确定性的质量门禁

AI coding agent 已经能写出能编译、能跑测试、甚至看起来很完整的代码。但这不代表代码一定适合长期维护。很多问题不会立刻被类型检查或单元测试抓住：为了向人解释而写在代码里的叙事型注释、空的 fallback、吞掉异常的 catch、随手加的 as any、未清理的 console.log、过大的函数、重复 helper、TODO stub、幻觉式 import。这些东西单个看都不一定严重，但堆在一起会让代码库慢慢变钝。

今天推荐的 scanaislop/aislop 就是围绕这个问题做的工具。它不是再套一个 LLM 做代码评审，而是用确定性的静态规则给项目打分，并把适合机械修复的问题先自动处理。GitHub 页面当前显示项目约 329 stars、13 forks，主要语言是 TypeScript，许可是 MIT；latest release 是 v0.10.2，发布时间为 2026-06-02。

项目概览

属性	详情
仓库	scanaislop/aislop
定位	面向 AI 生成代码痕迹的静态检查与质量门禁 CLI
Stars	约 329
Forks	13
主要语言	TypeScript
许可	MIT
当前版本	v0.10.2
支持语言	TypeScript、JavaScript、Python、Go、Rust、Ruby、PHP

它抓的不是传统 lint 已经覆盖的那一层

aislop 最有意思的地方，是它把“AI 写出来但不够像可维护工程代码”的模式单独拿出来处理。传统 lint 很擅长抓格式、未使用变量、明显错误、一些安全规则；类型系统也能阻止很多接口层面的误用。但 AI 生成代码常见的问题更像是工程判断残留：注释解释显而易见的代码、异常被静默吞掉、用 any 绕过类型问题、为了完成当前任务复制一段 helper、留下未来再补的占位逻辑。

这些问题经常不会让 CI 变红。甚至在短期内，它们可能让功能更快通过验收。真正的代价出现在几周后：下一个人读代码时不知道哪些分支是认真设计的，哪些只是 agent 为了不报错加的缓冲；reviewer 看到过多解释性注释，反而更难判断真实意图；类型边界被 as any 打开后，后续改动失去保护。

aislop 的思路是把这类痕迹变成可扫描、可配置、可门禁的规则。README 里列出的规则覆盖 narrative comments、trivial comments、dead patterns、unused imports、as any、console leftover、TODO stubs、generic names 等方向。它不会替代团队自己的 review，但可以先把“明显不该混进主线的 agent 残留”拦下来。

确定性比再找一个模型评审更适合门禁

很多 AI 代码评审工具会调用模型给建议，这对复杂设计问题很有用。但如果目标是 CI 里的质量门禁，确定性反而更重要。门禁应该满足几个条件：

同一份代码重复跑，结果应该一致。
失败原因要能定位到规则和行。
规则误报时可以关闭、降级或 inline suppress。
输出可以进入 GitHub code scanning、CI JSON 或 PR workflow。

aislop 明确把 runtime path 设计成不依赖 LLM。它使用 regex、AST 和常见语言工具组合扫描，给项目输出 0-100 分，并按 severity 计算影响。这种设计不一定能理解所有上下文，但适合作为“先把低级坏味道挡住”的自动化层。

README 里也提供了常见配置能力：可以在 .aislop/config.yml 里调整规则 severity，把某条规则设为 error、warning 或 off；也可以用 aislop-ignore-next-line、aislop-ignore-line、aislop-ignore-file 这类注释做局部抑制，并附上原因。对团队来说，这比“模型这次觉得不好”更容易治理。

从 `npx aislop scan` 开始很轻

入门路径很直接：

npx aislop scan

它也支持只扫指定目录、只扫变更文件、只扫 staged 文件，并能输出 JSON 或 SARIF：

npx aislop scan ./src
npx aislop scan --changes
npx aislop scan --staged
npx aislop scan --json
npx aislop scan --sarif

默认排除 node_modules、.git、dist、build、coverage 这类目录。项目如果有生成代码、快照或遗留目录，也可以通过 .aislop/config.yml 或 .aislopignore 排除。这里的设计比较像成熟 lint 工具：先让默认行为能跑，再允许团队逐步收紧。

一个值得注意的细节是 unsupported language 处理。README 说明，如果仓库主体不是它支持的语言，只扫到少量偶然存在的文件会误导评分，所以工具会 withheld score，而不是给出一个看似精确但其实没覆盖主要代码的分数。这比硬给 0-100 分更稳。

Auto-fix 和 agent handoff 是两个层级

aislop 不只是报问题。它提供 fix 命令，把能机械处理的部分先解决：

npx aislop fix
npx aislop fix --safe
npx aislop fix -f

其中 --safe 只做可逆或低风险修复，例如移除未使用 import、合并 import、删除叙事型注释、格式化。更激进的 -f 会扩展到依赖、未使用文件等方向。这个分层很关键：不是所有“看起来能自动修”的问题都应该在同一安全等级里处理。

对剩下需要上下文判断的问题，aislop 提供 agent handoff：

npx aislop fix --codex
npx aislop fix --claude
npx aislop fix --gemini
npx aislop fix --prompt

这类命令的意义不是让 aislop 自己变成 agent，而是把诊断信息整理成 agent 能继续处理的上下文。对 Codex、Claude Code、Gemini CLI、Cursor、OpenCode 等工具来说，这可以把“请帮我清一下质量问题”变成更具体的任务：哪些规则触发、文件在哪里、哪些可以自动修、哪些需要人工判断。

Hook 模式适合 agent-heavy workflow

如果团队已经高频使用 coding agent，只在 PR 前扫描可能有点晚。aislop 提供 hook 安装，让 agent 编辑后立即得到反馈：

npx aislop hook install --claude
npx aislop hook install --cursor
npx aislop hook install --gemini
npx aislop hook install --quality-gate

README 里把 hook 分成两类：Claude、Cursor、Gemini、pi 这类 runtime adapters 可以做 scan 和 feedback；Codex、Windsurf、Cline、Kilo Code、Copilot 等则偏 rules-only，让 agent 读取规则。这个边界值得留意，因为不同 agent 的可插拔程度不同，不能假设所有工具都能被同样深度地拦截。

质量门禁模式还能记录 baseline，并在分数回退时阻止继续。这很适合渐进式治理：老仓库一开始不必要求 100 分，而是先约定“不让当前分数变差”，再逐步清掉历史问题。

CI 和 SARIF 让它进入正常工程流程

aislop 支持 npx aislop ci，也提供 GitHub Actions 用法。配置里可以设置：

ci:
  failBelow: 70

这样分数低于阈值时 CI 退出 1。它也支持 SARIF 2.1.0 输出，可以上传到 GitHub code scanning。对团队来说，这比只在终端里看到一段报告更实用：问题可以进入既有安全和代码扫描视图，也能和 PR 流程结合。

我更推荐从温和阈值开始，而不是第一天就把门槛设得很高。AI 生成代码的坏味道并不总是二元的，有些规则需要根据团队风格调整。先用 warning 和报告跑几轮，确认误报范围，再把高价值规则提升到 error，会比一次性强推更容易长期留下来。

它和普通 linter 的关系

aislop 不是 Biome、ruff、golangci-lint、clippy、rubocop、php-cs-fixer 的替代品。README 里也明确把这些工具作为底层引擎或生态能力的一部分。更准确的定位是：在已有格式化、lint、类型检查、安全扫描之外，增加一组专门面向 AI 生成代码痕迹的规则和评分。

这也决定了它的使用方式。不要把 aislop 当作唯一的质量来源，而是把它放进更完整的链路：

formatter 保证风格一致；
language linter 抓语言生态里的常见错误；
typecheck 保证接口边界；
tests 验证行为；
aislop 抓 agent output 容易留下的维护性痕迹；
human review 判断设计、领域语义和取舍。

它最适合填补的是最后两层之间的缝隙：很多 reviewer 不想反复指出“这段注释没有信息量”“这里不要吞异常”“不要用 any 绕过类型”。这类反馈适合交给自动门禁先处理。

需要保留的怀疑

aislop 的方向很实用，但也要避免把分数神化。0-100 的评分能帮助沟通，但代码质量不可能完全压缩成一个数字。特别是“AI 痕迹”这类规则，天然会受团队风格影响：有些团队允许更多解释性注释，有些团队对 TODO 更严格，有些仓库有大量生成代码或历史包袱。

我会特别关注三类风险：

误报成本：如果 narrative comment 或 generic name 规则太敏感，可能让开发者为了分数修改本来合理的代码。
安全修复边界：fix -f 这类激进模式不适合无脑在大仓库里跑，最好先从 --safe 开始。
评分覆盖范围：多语言仓库或不支持语言占主体时，分数是否有代表性需要看 coverage。

所以它更适合作为工程反馈系统，而不是绝对裁判。把规则、阈值、抑制原因都纳入 review 文化，效果会更好。

适合谁尝试

aislop 适合这些场景：

团队已经频繁使用 Codex、Claude Code、Cursor、Gemini CLI、OpenCode 等 coding agent。
PR 里常出现“能跑但不够像人维护的代码”。
你希望把 AI 生成代码的常见坏味道变成可自动检查的规则。
项目主要使用 TypeScript、JavaScript、Python、Go、Rust、Ruby 或 PHP。
你想在 CI 里引入质量分数、SARIF 或 GitHub Actions 门禁。
你需要把剩余诊断整理给 agent 继续修，而不是手写长 prompt。

如果团队还没有大量使用 agent，或者项目本身很小，aislop 的收益可能不明显。但只要 AI 代码已经开始稳定进入主线，它就提供了一个很轻的治理入口。

小结

scanaislop/aislop 抓住了 AI coding agent 普及后的一个真实问题：生成代码越来越容易，保持代码库不被细碎坏味道拖慢反而更难。它的价值不在于“用 AI 检查 AI”，而在于把一批可识别、可配置、可重复执行的问题做成确定性门禁。

我喜欢它的几个设计：零配置扫描、可调规则、safe fix、agent handoff、hook、CI、SARIF、baseline gate。它仍然需要团队根据自己的代码风格调参，也不该替代人类 review。但作为一层自动化清洁过滤器，它很适合放在 agent-heavy 的开发流程里。