【Agent工坊】你的AI编程助手正在悄悄污染代码库：AISlop 一站式扫「AI味」实操指南

AISlop 上线一周获 155+ GitHub Stars、Hacker News 65分/56条讨论——开发者终于有了专门检测「AI 代码坏味道」的开源利器。

前言

2026 年，几乎所有开发者都在用 AI 编程助手——Claude Code、Cursor、Codex、Gemini CLI……代码量确实上去了，但一个新的问题正在蔓延：代码里的「AI 味」越来越重。

那些 AI 爱写的"叙事性注释"、吞掉的异常、as any 强制类型断言、永远不实现的 TODO 桩、废弃但没删的导入……它们不会让测试挂掉，不会让 ESLint 报错，但代码库在悄悄腐烂。

aislop 正是为此而生。它是一个 CLI 工具，专门检测 AI 编码助手留下的代码坏味道——40+ 条规则，覆盖 7 种语言，亚秒级执行，零 LLM 依赖（确定性的，同样的代码进去永远是同样的分数出来）。MIT 开源，npm 一行命令就能跑。

为什么传统 Linter 搞不定 AI 代码问题？

你可能会问："ESLint 不就能检查代码质量吗？我用 oxlint + Biome 还不够？"

先说结论：传统 linter 规则是为「人写的烂代码」设计的，但 AI 写的烂代码特征完全不同。

AI 代码的典型特征

传统 Linter 关注	AI 代码的独特问题
未使用的变量	叙事性注释：`// Step 1: First we fetch the data, then we process it...` 写了 5 行解释 2 行代码
循环复杂度	吞掉的异常：`catch (e) { console.log(e) }` — 异常被静默吞掉，不抛出也不处理
缩进/格式	`as any` 强制断言：AI 搞不定类型就加 `as any`，把 TypeScript 降级成 AnyScript
未使用的导入	幻觉导入：AI "记得"一个不存在的包或路径，import 进来根本跑不通
代码风格	重复的 helper 函数：每次生成都重写一遍同样的工具函数，导致 3 个文件里各有一个 `formatDate()`

最要命的是：传统 linter 不会因为这些报错。ESLint 看到一个 // Return the value 注释不会说它多余，但这是 AI 最经典的废话注释模式。

HN 评论区的一位开发者说得很形象

「我试了一下，它检测出不少好东西。最棒的是——可以把问题传给 AI Agent，让它自己修复。」

— hootz, HN

另一位则点出了痛点：

「我发现 AI 代码里最常见的坑是"把异常扫到地毯底下"（sweeping exceptions under the rug）。Agent 想尽快让代码跑起来，就倾向于用空 catch 块或只打 log 的 catch 块蒙混过关。」

— macNchz, HN

▲ 图1：AISlop 检测 AI 代码坏味道 vs 传统 Linter 的覆盖范围对比 — 叙事性注释、吞掉的异常、as any 类型断言等都是传统工具盲区

AISlop 六引擎体系：不只是"AI 味检测器"

AISlop 的分层设计很清晰，共有 6 个并行引擎：

1. 格式化引擎（Formatting）

调用各语言最佳实践工具：Biome（TS/JS）、ruff format（Python）、gofmt（Go）、cargo fmt（Rust）、rubocop（Ruby）、php-cs-fixer（PHP）。这部分和传统工具重叠度最高，但 AISlop 把它们统一成一个命令。

2. 静态分析引擎（Linting）

同样调用成熟工具——oxlint（含 React/Next.js 感知）、ruff（Python）、golangci-lint（Go）、clippy（Rust）。对 Expo/React Native 项目还会自动跑 expo-doctor 做项目健康检查。

3. 代码质量引擎（Code Quality）

检测结构性复杂度：函数过长（默认 >80 行）、文件过大（>400 行）、深层嵌套（>5 层）、参数过多（>6 个）。还集成了 knip 做未使用文件/导出/依赖检测——这对 AI 生成代码特别实用，因为 AI 经常生成一堆文件但只用其中一两个。

4. AI Slop 引擎（核心差异化功能）⭐

这是 AISlop 真正的杀招，17 条专为 AI 代码坏味道设计的规则：

规则	严重度	检测什么	为什么是 AI 特征
`trivial-comment`	warning	`// Import React`、`// Return the value`	AI 爱写"解释代码的代码"
`narrative-comment`	warning	5+ 行散文式注释、装饰性分隔符、阶段标题	Claude Code 特别爱写"第一阶段：数据获取"
`swallowed-exception`	error	空 catch 块、只 log 不抛的 catch	AI 的"快速让代码跑起来"策略
`thin-wrapper`	warning	只调用另一个函数的函数	AI 过度封装
`generic-naming`	info	`helper_1`、`data2`、`temp1`	AI 对变量名不走心
`unused-import`	warning	未使用的导入	AI"记错路径"或忘了清理
`console-leftover`	warning	生产代码里的 console.log	AI 调试完忘了删
`todo-stub`	info	未解决的 TODO/FIXME/HACK	AI 留的"以后再说"
`unsafe-type-assertion`	warning	`as any`	AI 搞不定类型时的万能药
`double-type-assertion`	warning	`as unknown as X` 模式	AI 的"双重保险"
`python-range-len-loop`	info	`for i in range(len(items))`	AI 写 Python 时最经典的 C 思维
`python-chained-dict-get`	warning	`.get(..., {}).get(...)` 链	隐藏了数据缺失的真实原因
`python-repetitive-dispatch`	warning	重复的等值分支阶梯	应该用表/集合替代
`python-isinstance-ladder`	warning	重复的 isinstance 检查阶梯	应该用 handler map

5. 安全引擎（Security）

检测硬编码密钥、eval() 调用、innerHTML/dangerouslySetInnerHTML、SQL 注入、Shell 注入、依赖漏洞审计。AI 生成测试用例时常会写假 API key，这个检测非常实用。

6. 架构引擎（Architecture，可选）

自定义导入和路径规则。比如：禁止全项目用 axios、Controller 不许 import 数据库模块、API 路由必须有错误处理。

▲ 图2：AISlop 六引擎并行扫描架构 — 格式化、静态分析、代码质量、AI Slop（核心）、安全、架构六引擎协同工作，输出 0-100 综合评分

一分钟上手

# 无需安装，一行扫描

npx aislop scan

# 安装到项目

npm install --save-dev aislop

# 自动修复

npx aislop fix

# 激进修复（含依赖清理 & 未使用文件删除）

npx aislop fix -f

# CI 模式（JSON 输出，分数低于阈值则 exit 1）

npx aislop ci

# 只扫描变更文件

npx aislop scan --changes

# 只看暂存区

npx aislop scan --staged

扫描结果是一个 0-100 的分数和一个问题清单。分数越低，AI 味道越重。

与 AI 编程助手的深度集成

AISlop 最亮眼的设计是它不是为了"在 AI 之外"跑——它是为了和 AI 编程助手协同工作而设计的。

1. 编辑器 Hook（实时反馈）

# Claude Code 专用 hook（每编辑一次自动扫）

npx aislop hook install --claude

# Cursor 专用

npx aislop hook install --cursor

# Gemini CLI

npx aislop hook install --gemini

# 一键安装所有支持的 Agent

npx aislop hook install

安装后，每次 AI 编辑完代码，AISlop 自动扫描并反馈。支持两种模式：

Runtime 适配器（扫描 + 反馈）：Claude、Cursor、Gemini
规则只读（Agent 自行读取规则）：Codex、Windsurf、Cline、KiloCode、Antigravity、Copilot

还有一个质量门禁模式：分数低于基线时自动阻止提交。

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

npx aislop hook baseline # 重新设定基线分数

2. 问题转交 Agent（Hand Off）

当自动修复搞不定时，AISlop 把剩余问题连同完整诊断信息打包发给 AI 编程助手：

npx aislop fix --claude # Claude Code

npx aislop fix --cursor # Cursor（复制到剪贴板）

npx aislop fix --codex # Codex CLI

npx aislop fix --gemini # Gemini CLI

# 还支持: --windsurf, --amp, --aider, --goose, --opencode,

# --warp, --kimi, --antigravity, --deep-agents, --vscode

# 通用模式（Agent 无关）

npx aislop fix --prompt # 只打印 prompt，自行粘贴给 Agent

3. MCP 服务器（给 AI Agent 提供工具）

AISlop 还暴露了 MCP（Model Context Protocol）服务，让 Claude Desktop、Cursor、Codex 可以直接调用扫描工具：

// ~/.cursor/mcp.json 或 Claude Desktop 配置

{

"mcpServers": {

"aislop": {

"command": "npx",

"args": ["-y", "aislop-mcp"]

}

暴露 4 个 MCP Tool：aislop_scan、aislop_fix、aislop_why、aislop_baseline。这意味着你的 AI Agent 可以在对话中主动扫描代码质量——AI 自己调用 AISlop 检查 AI 自己的代码，这可能是 2026 年最"元"的开发工作流。

4. GitHub Actions（CI 门禁）

# 自动生成 CI 配置

npx aislop init

# 按提示接受 workflow 自动创建，或手动添加：

- uses: actions/checkout@v4

- uses: actions/setup-node@v4

with:

node-version: 20

- run: npx aislop ci

CI 模式下如果分数低于阈值，工作流直接失败——把 AI 代码质量的把关从"仰仗开发者自觉"变成"自动化强制"。

▲ 图3：AISlop 完整开发工作流集成 — 从编码阶段（Claude Code/Cursor/Codex）到扫描修复再到 CI 门禁的端到端质量流水线

实战：在一个 AI 辅助项目中跑 AISlop

假设你有一个用 Claude Code 开发了两周的 Next.js 项目。跑一下看看：

$ npx aislop scan

🔍 Scanning 47 files in 1.2s...

📊 Score: 72/100

⚠️ AI Slop Issues (12):

src/lib/api.ts:23 narrative-comment 5-line prose block above getUsers()

src/utils/format.ts:8 thin-wrapper formatDate() only calls toLocaleDateString()

src/hooks/useAuth.ts:45 swallowed-exception Empty catch block in token refresh

src/components/Card.tsx:3 trivial-comment "// Import React"

src/lib/db.ts:112 unsafe-type-assertion `data as any`

...and 7 more

然后：

# 自动修复能修的

npx aislop fix

# 把修不了的传给 Claude Code

npx aislop fix --claude

Claude 收到完整的问题清单和诊断信息，逐个修复。修完再跑：

$ npx aislop scan

📊 Score: 91/100 ✅

HN 社区的反应：褒贬不一，但方向正确

这次 HN 讨论（65 分 / 56 条评论）很有参考价值。总结几种典型观点：

支持派 👍

"试了，检测出不少好东西"（hootz）—— 实战有效
"AI 代码里死代码检查非常有用，Claude 迭代时常留下无用函数"（throw03172019）—— 痛点精准
"终于有人关心节约 token 这件事了"（maddhruvhn）—— 意外的正面视角
"给 Elixir 也有类似的 hex 包"（bratsche）—— 生态开始形成

质疑派 🤔

"和 oxlint/ESLint 重叠太多"（sync）—— 建议更聚焦 AI Slop 引擎
"假阳性不少，删注释删得太激进"（vinnymac）—— 精度还需打磨
"应该专注代码质量而非区分人写还是 AI 写"（axod）—— 哲学讨论
"『Slop』这个词不太好"（pixel_popping）—— 命名争议

我们的判断

AISlop 最大的价值不在和 ESLint 重叠的部分，而在于那 17 条 AI Slop 规则。如果需要精简，完全可以在 .aislop/config.yml 里只开启 AI Slop 引擎，关掉格式化和常规 Linting：

# .aislop/config.yml

engines:

formatting: false

linting: false

codeQuality: true # 保留，knip 对 AI 代码很有用

aiSlop: true # 核心引擎

security: true # AI 常写假 key

architecture: false

这样它就变成了一个纯粹的"AI 代码坏味道检测器"，和现有 lint 工具栈互补而非冲突。

踩坑提醒（实测）

npx aislop fix -f 会删未使用文件 — 先确认没有"即将用到但还没引用的文件"。建议先跑 npx aislop scan 看看 knip 报告再决定是否加 -f。
narrative-comment 规则偏激进 — 如果你的团队有写详细注释的文档文化，建议在 config 里调高阈值或关闭此规则。AI 的"叙事注释"通常有明显的模式特征（阶段标题、JSDoc 空壳），但不排除好的注释也被误杀。
swallowed-exception 误报 — 某些场景（如 React Error Boundary 内部的日志记录）合法地只 log 不抛。可以通过 .aislop/config.yml 的排除规则或内联注释来豁免。
MCP 模式需要 Node ≥20 — 较老的开发环境可能不兼容，建议在项目中锁定 Node 版本。
Python 规则目前只覆盖基础场景 — range-len-loop、chained-dict-get 等规则很好，但相比 JS/TS 的覆盖度还有差距，Python 开发者最好搭配 ruff 一起用。

总结：AI 编程时代的新基建

AISlop 代表了一类正在崛起的新工具：AI 编程助手的配套质量守护者。

它的核心逻辑很清晰：AI 生成的代码需要一类传统 linter 不会报、但人工 code review 能闻出来的检测规则。把这种"直觉"固化为自动化规则，让 AI 辅助编程的产出也能维持人工代码的质量标准。

对于 AI 创业者/一人开发者来说，AISlop 的价值尤其明显——你就是你自己的 code reviewer，没有同事帮你把关 AI 写出来的代码。AISlop 相当于给你配了一个免费的、不知疲倦的结对审查员。

行动建议

今天就跑一次：npx aislop scan，看看你的项目得分多少
装 hook：npx aislop hook install --claude（或其他 Agent），让 AI 每次编辑后自检
加 CI 门禁：npx aislop init 生成 GitHub Actions 配置
贡献规则：如果你发现新的 AI 代码坏味道模式，AISlop 是开源的，欢迎 PR

*AI辅助创作，经人工审核编辑发布*

#AI创业 #Agent工坊 #AI编程 #代码质量 #一人公司

本文由AI辅助创作，经人工审核编辑发布