1. 项目概述当AI成为你的“初级程序员”如果你和我一样在过去一年里深度使用了 Cursor、Claude Code 或者 GitHub Copilot那你一定对那种“一半惊喜一半惊吓”的感觉深有体会。惊喜的是一个模糊的想法几秒钟内就能变成可运行的代码骨架惊吓的是这些代码里总藏着一些让人哭笑不得的“AI式坏习惯”。比如一个光秃秃的try...catch块错误被默默吞掉让你在深夜排查生产环境故障时一头雾水又或者一个本该用参数化查询的 SQL 语句被 AI 用字符串拼接粗暴地写出来留下了 SQL 注入的隐患。更让人头疼的是这些问题并非偶发而是高度可预测、可复现的模式。AI 模型基于海量公开代码训练而公开代码库中本身就充斥着大量不严谨的示例。于是AI 学会了快速生成“能跑”的代码却未必是“健壮”或“安全”的代码。标准的 ESLint 规则集如eslint:recommended或typescript-eslint/recommended主要针对通用的 JavaScript/TypeScript 最佳实践对于这些新兴的、由 AI 编码风格催生的特定反模式往往力有不逮。这就是我动手构建eslint-plugin-ai-guard的初衷。我不想再手动审查每一段 AI 生成的代码也不想在代码评审中反复指出同样的低级错误。我需要一个能自动识别这些“AI代码糟粕”的守卫。这个插件不是一个庞大的、包含数百条规则的代码风格指南而是一把精准的手术刀专门切除由 AI 工具高频引入的 17 种典型问题。更关键的是我把它做成了零配置的 CLI 工具ai-guard你只需要npx ai-guard run它就能在几秒钟内扫描你的项目并给出报告。自发布以来它在几天内获得了超过一千次的 npm 下载这让我确信痛恨“AI代码糟粕”的开发者远不止我一个。2. 核心设计思路为何通用ESLint规则不够用在决定造轮子之前我首先系统性地回顾了现有 ESLint 生态能否解决我的问题。结论是部分可以但存在显著缺口。通用规则和 AI 反模式之间存在一个“匹配度”的鸿沟。2.1 通用规则的盲区现有的优秀规则如no-empty可以捕获空的catch块typescript-eslint/no-floating-promises能发现未处理的 Promisesecurity/detect-object-injection也能防范一些安全问题。但它们的设计初衷是普适性的缺乏对“AI代码生成场景”的针对性优化。举个例子AI 经常在 Express.js 或类似框架的路由处理函数中忘记添加身份验证中间件。没有一个通用规则会叫require-auth-middleware因为“是否需要认证”是业务逻辑不是语法问题。但在这个上下文中这又是一个极高频、高风险的遗漏。再比如AI 喜欢在循环内部使用await这会导致性能极差的串行执行而通用规则no-await-in-loop虽然存在但在许多预设中并未被启用或者其报告的信息不够直白无法让开发者立刻联想到这是 AI 的惯用写法。2.2 AI反模式的“指纹”特征经过对数百个由 Cursor、Claude 生成的代码片段进行分析我归纳出 AI 引入的问题具有高度集中的“指纹”特征。它们通常不是复杂的逻辑错误而是模式化的“偷懒”或“模仿”行为错误处理的敷衍了事直接生成try { ... } catch {}或try { ... } catch (e) {}没有日志没有错误传播没有用户反馈。这是最典型的“代码能编译就行”思维。安全意识的普遍缺失对用户输入缺乏警惕。除了 SQL 拼接还包括不安全的反序列化如直接JSON.parse(req.body)、未经验证的跳转等。异步控制的混乱滥用async/await而不理解其执行模型导致出现无意义的async函数、循环内await或漏掉关键的await。权限检查的遗漏在 Web 开发中几乎每个需要鉴权的接口AI 都可能忘记添加中间件或权限判断逻辑。这些特征如此明显和集中以至于为它们定制专属的 lint 规则变得非常有价值。eslint-plugin-ai-guard的核心思路就是将这些“指纹”编码成具体的 AST抽象语法树匹配模式在代码静态分析阶段就将其拦截。2.3 “零配置”哲学与预设策略我深知为现有项目引入一个新的 lint 工具最大的阻力往往是配置成本。因此“零配置”是ai-guardCLI 的核心理念。你不需要理解 ESLint 的扁平配置Flat Config或传统配置的区别不需要手动安装和配置插件甚至不需要创建一个.eslintrc文件。其背后是三层预设策略recommended(默认)这是噪音最低的预设。只包含那些误报率极低、问题严重性较高的规则。目标是让你可以毫无心理负担地将其接入任何现有项目它只会报告那些“几乎可以肯定是问题”的情况。strict包含所有 17 条规则。适合在新项目启动时使用或者当你希望对代码库进行彻底“AI糟粕”清理时使用。可能会产生一些需要你主观判断的警告例如某些情况下空的catch块可能是设计使然。security专注于安全相关的子集如防止 SQL 拼接、不安全的反序列化、缺失的身份验证等。适合在 CI/CD 流水线中作为安全门禁。通过npx ai-guard run工具会自动应用recommended预设。你也可以通过npx ai-guard run --preset strict来切换。这种设计极大地降低了使用门槛让开发者能够专注于解决问题而非配置工具。3. 规则深度解析与实战场景eslint-plugin-ai-guard的 17 条规则并非随意堆砌每一类都针对一个明确的、由 AI 引发的痛点。下面我们来深入剖析几类核心规则看看它们具体拦截什么以及为什么这些模式如此危险。3.1 错误处理与健壮性规则这类规则旨在防止 AI 生成“脆弱”的代码这些代码在异常情况下会静默失败给调试和运维带来噩梦。ai-guard/no-empty-catch这可能是排名第一的“AI糟粕”。AI 倾向于生成最简单的结构来满足语法要求。// AI 生成的典型糟粕 try { const data JSON.parse(userInput); } catch { // 空空如也错误被完全忽略。 }为什么危险当JSON.parse失败时程序会继续执行但data是undefined后续使用data的代码很可能抛出另一个难以追溯根源的错误。修正建议至少应该记录错误console.error(‘Failed to parse input:’, e)或者根据上下文向上抛出错误、返回错误响应。ai-guard/no-floating-promises虽然类似规则存在于其他插件但 AI 生成异步代码时特别容易犯这个错误。// AI 可能这样写一个事件处理器 function handleClick() { saveDataToAPI(); // 这是一个返回 Promise 的函数但未被 await 或 .then() 处理 showSuccessMessage(); // 这条消息可能在 saveDataToAPI 失败前就显示了 }为什么危险未处理的 Promise 如果被拒绝rejected错误会被悄无声息地吞掉在 Node.js 最新版本中会触发unhandledRejection但浏览器环境或旧版 Node 中可能不会。这会导致数据保存失败而用户浑然不知。修正建议使用await在async函数中或添加.catch()处理。3.2 异步代码稳定性规则AI 对异步编程模型的理解常常停留在表面导致生成性能低下或逻辑错误的代码。ai-guard/no-await-in-loop这是 Claude 和 Cursor 的“经典之作”。当被要求处理一个数组时AI 会不假思索地写出串行代码。// 低效的 AI 写法 for (const item of items) { const result await processItem(item); // 每个 await 都会阻塞循环 }为什么危险如果items有 100 个processItem每个耗时 100ms那么总耗时将是 10 秒。修正建议使用Promise.all进行并行处理除非处理项之间有严格的先后依赖关系。// 高效的写法 const results await Promise.all(items.map(item processItem(item)));ai-guard/no-async-without-await将一个函数标记为async却不在其内部使用await通常是无用或错误的。// 无意义的 async 标记 async function getConfig() { return cachedConfig; // 直接返回一个非 Promise 值 }为什么危险这会造成微小的性能开销函数返回一个 Promise 包装的值更重要的是它反映了开发者或 AI对函数是否真正异步的混淆。如果调用者以为它是异步的而使用了await就会增加不必要的复杂性。修正建议移除async关键字。3.3 安全防护规则这是最致命的一类规则。AI 在生成代码时几乎不会主动考虑安全边界。ai-guard/no-unsafe-sql-concat直接使用字符串拼接来构造 SQL 查询是安全领域的“原罪”。// 高危SQL 注入漏洞 const query SELECT * FROM users WHERE username ${username};为什么危险如果username是admin --整个查询的逻辑就会被改变。修正建议使用参数化查询或预编译语句。对于不同的数据库驱动写法不同如?占位符、$1等。ai-guard/no-unsafe-deserialize不假思索地反序列化来自外部的数据。// 在 Express 路由中危险的做法 app.post(‘/data‘, (req, res) { const obj JSON.parse(req.body); // req.body 可能已被污染 // ... });为什么危险恶意构造的 JSON 字符串可能触发原型污染攻击或消耗大量资源导致拒绝服务。修正建议对来源不可信的数据使用安全的解析方式如限制深度、过滤原型或者直接使用 Web 框架内置的、安全的 body-parser 中间件如express.json()它们通常有内置的保护。ai-guard/require-auth-middleware与ai-guard/require-authz-check这两条是语义级规则。它们不会分析代码语法而是检查在特定的路由或控制器上下文中是否出现了认证(auth)和授权(authz)的关键字或模式。// AI 可能生成这样的“裸”路由 app.get(‘/api/admin/users‘, (req, res) { // 缺少 auth 中间件 if (req.user.role ! ‘admin‘) { // 缺少前置的 authz 检查且这个检查本身可能也不够早 return res.status(403).send(‘Forbidden‘); } // ... 获取用户列表 });规则逻辑require-auth-middleware会扫描类似app.get(‘/api/...‘, handler)的模式检查handler之前是否有常见的认证中间件引用如auth,authenticate,passport.authenticate等。require-authz-check则更深入一步在路由处理函数内部检查是否在访问受保护资源如查询用户数据、修改设置前进行了角色或权限的判断。为什么重要权限漏洞是最高危的漏洞之一。这两条规则通过模式匹配为常见的 Web 框架提供了一道重要的安全提醒防线。虽然无法理解复杂的业务逻辑但能捕捉到完全缺失这类检查的明显漏洞。3.4 代码质量规则这类规则关注那些不会立即导致崩溃或漏洞但会降低代码可维护性和可读性的模式。ai-guard/no-magic-numbersAI 经常在条件判断或计算中直接使用字面量数字。if (user.age 18) { // 这个 18 是什么法定成年年龄 return ‘minor‘; } const discount price * 0.1; // 0.1 是折扣率为什么是 10%为什么不好“魔数”使得代码意图模糊难以维护。如果“成年年龄”或“折扣率”在业务中发生变化你需要搜索并修改所有出现这个数字的地方极易出错。修正建议将数字定义为有意义的常量const LEGAL_ADULT_AGE 18;。注意ai-guard的规则是“可调节的警报器”而非“不可违背的法则”。有些规则如no-magic-numbers在严格模式下触发可能需要你根据实际情况判断是否违反。例如if (retries 3)中的3可能就是一个可以接受的、明确的阈值。规则的意义在于促使你思考并做出有意识的选择。4. 从安装到集成无缝接入你的工作流让一个工具真正产生价值关键在于它能多平滑地融入你现有的开发流程。eslint-plugin-ai-guard和ai-guardCLI 的设计目标就是“开箱即用无缝集成”。4.1 快速启动零配置扫描对于只想快速体验或一次性检查项目的人来说ai-guardCLI 是最佳入口。它不需要你在项目中安装任何东西。打开你的项目根目录。在终端中运行一条命令npx ai-guard run这条命令会在后台自动下载并执行ai-guard。使用内置的recommended预设规则。自动探测项目中的 JavaScript/TypeScript 文件支持.js,.jsx,.ts,.tsx。在几秒到几十秒内取决于项目大小完成扫描并在终端输出一个清晰的报告列出每个问题所在的文件、行号、列号以及规则说明。实战示例输出✔ Scanning 154 files with ai-guard/recommended ⏱ Scanned in 7.2s ⚠ Found 61 warnings src/api/users.js:45:3 ai-guard/require-auth-middleware Route handler for ‘/api/users‘ is missing authentication middleware. src/utils/db.js:12:21 ai-guard/no-unsafe-sql-concat Potential SQL injection vulnerability. Use parameterized queries. src/scripts/processInvoices.js:67:7 ai-guard/no-await-in-loop Avoid using ‘await‘ inside a loop. Consider using ‘Promise.all‘.这个报告直接指出了问题类型、位置和修复方向 actionable 非常强。4.2 深度集成作为ESLint插件安装如果你希望将 AI Guard 的规则作为你日常 ESLint 检查的一部分例如在编辑器中实时提示或在npm run lint中执行则需要将其作为插件安装。安装插件npm install --save-dev eslint eslint-plugin-ai-guard # 或者使用 yarn/pnpm yarn add --dev eslint eslint-plugin-ai-guard pnpm add -D eslint eslint-plugin-ai-guard配置 ESLint 根据你的 ESLint 配置格式传统.eslintrc.*或新的eslint.config.jsFlat Config进行配置。对于 Flat Config (eslint.config.js)import aiGuard from ‘eslint-plugin-ai-guard‘; export default [ // ... 你的其他配置 { plugins: { ‘ai-guard‘: aiGuard, }, rules: { // 启用推荐的规则集 ...aiGuard.configs.recommended.rules, // 或者启用严格规则集 // ...aiGuard.configs.strict.rules, // 你也可以单独启用某条规则并自定义级别 // ‘ai-guard/no-empty-catch‘: ‘error‘, }, }, ];对于传统配置 (.eslintrc.js)module.exports { plugins: [‘ai-guard‘], extends: [ // 启用推荐配置 ‘plugin:ai-guard/recommended‘, // 或者 ‘plugin:ai-guard/strict‘, ‘plugin:ai-guard/security‘ ], // 也可以单独配置规则 rules: { ‘ai-guard/no-magic-numbers‘: ‘off‘, // 关闭某条规则 }, };运行与体验 配置完成后你就可以像平时一样使用 ESLint 了。命令行npx eslint .编辑器集成如果你有 ESLint 编辑器扩展如 VS Code 的 ESLint 扩展保存文件时就能实时看到ai-guard规则的提示。Git Hook通过husky和lint-staged在提交代码前自动运行检查防止“AI糟粕”进入仓库。4.3 与现有工具链的协作你可能会担心ai-guard与现有的typescript-eslint、eslint-plugin-react等插件冲突。完全不会。ESLint 的配置是可以叠加的。ai-guard的规则命名都带有ai-guard/前缀避免了与其他插件规则的冲突。你只需要在配置数组中添加一个新的配置对象即可。一个典型的现代项目 ESLint Flat Config 可能长这样import js from ‘eslint/js‘; import tseslint from ‘typescript-eslint/eslint-plugin‘; import aiGuard from ‘eslint-plugin-ai-guard‘; export default [ js.configs.recommended, ...tseslint.configs.recommended, { plugins: { ‘ai-guard‘: aiGuard, }, rules: { ...aiGuard.configs.recommended.rules, // 你可以覆盖任何规则的严重程度 ‘ai-guard/no-empty-catch‘: ‘error‘, // 将警告提升为错误 ‘typescript-eslint/no-explicit-any‘: ‘warn‘, }, }, ];实操心得从 CLI 到插件。我建议的路径是先用npx ai-guard run快速扫描你的项目感受一下它能发现多少问题。如果觉得有价值再将其作为插件集成到开发流程中。对于大型存量项目一开始使用strict预设可能会产生大量警告让人望而却步。更好的策略是先集成recommended预设解决掉那些高严重性问题然后定期用strict预设进行扫描像“技术债清理日”一样分批分模块地修复那些代码质量问题。这样阻力最小收益持续。5. 实战案例剖析在真实项目中发现了什么理论说再多不如看一个真实的例子。我在自己的一个模拟生产环境的“发票应用”Next.js 前端 Express.js 后端上运行了ai-guard它在大约 7 秒内扫描了约 150 个文件抛出了 61 个警告。这个结果非常有代表性揭示了 AI 辅助编码在真实项目中的“犯罪现场”。5.1 问题分布与典型代码片段让我们看看排名前几的问题require-auth-middleware(34个警告)这是重灾区。Express 路由文件中大量类似/api/invoices、/api/clients的端点处理函数前都没有auth()或jwt.verify()之类的中间件。AI 在生成 CRUD 接口时默认假设它们是公开的。// 被 AI Guard 捕获的代码 router.get(‘/api/invoices‘, async (req, res) { const invoices await db.invoice.findMany(); res.json(invoices); // 任何未经验证的用户都能获取所有发票 });require-authz-check(13个警告)即使在有基础认证的路由中AI 也经常忘记进行细粒度的授权检查。例如在GET /api/users/:userId中没有验证当前登录用户是否就是:userId本人或有管理员权限。router.get(‘/api/users/:id‘, authMiddleware, async (req, res) { const user await db.user.findUnique({ where: { id: req.params.id } }); res.json(user); // 用户A可以查看用户B的私密信息 });no-await-in-loop(5个警告)出现在后台脚本和数据处理函数中。例如一个用于批量发送邮件的脚本AI 写出了for (const user of users) { await sendEmail(user); }这样的代码使得发送 1000 封邮件变成了串行任务。no-async-without-await(6个警告)一些工具函数或事件监听器被不必要地标记为async。这通常发生在 AI 复制粘贴了某个async函数模板但实际函数体内并没有异步操作。no-unsafe-deserialize(3个警告)在一个接收 Webhook 的端点中AI 直接使用了JSON.parse(req.rawBody)而没有对数据大小或结构做任何验证。5.2 修复过程与收益修复这些警告的过程本身就是一次绝佳的安全和代码质量审查。对于缺失的中间件我创建了一个统一的authMiddleware并将其应用到所有需要认证的路由器上。这不仅仅是修复 lint 错误更是强制建立了一道安全基线。对于授权问题我实现了一个简单的canViewUser权限检查函数并在每个涉及资源访问的地方调用它。这促使我思考了应用的权限模型。对于await in loop我将其重构为Promise.all那个批量发邮件的脚本执行时间从预计的十几分钟缩短到了几十秒。对于不安全的JSON.parse我引入了zod库对 Webhook 负载进行模式验证和解析同时拒绝了过大的 payload。这次扫描带来的直接收益堵住了多个严重的安全漏洞未授权访问、潜在的拒绝服务。显著提升了关键后台任务的性能。统一了项目的错误处理和认证授权模式代码更加一致和可维护。为团队建立了新的代码质量红线以后所有 AI 生成的代码都必须先过一遍ai-guard的检查。这个过程清晰地证明ai-guard发现的不是吹毛求疵的风格问题而是实实在在会影响应用稳定性、安全性和性能的缺陷。它充当了 AI 这位“初级程序员”的资深代码评审员。6. 常见问题、排查与贡献指南在开发和推广eslint-plugin-ai-guard的过程中我遇到了不少问题也收到了很多用户的反馈。这里整理一份常见问题清单希望能帮你更快地上手和解决问题。6.1 安装与运行问题Q1: 运行npx ai-guard run时报错 “Command not found” 或类似错误。A1: 这通常是因为网络问题导致npx无法从 npm registry 下载包。请确保你的网络连接正常并且能够访问registry.npmjs.org。你也可以尝试清除 npm 缓存npm cache clean --force然后重试。Q2: 我已经全局安装了 ESLint但ai-guard作为插件运行时报版本不兼容。A2:ai-guard同时支持 ESLint 8 和 9包括 Flat Config。请确保你的项目本地安装的 ESLint 版本在^8.0.0或^9.0.0范围内。你可以运行npx eslint --version检查项目使用的版本。如果版本过低升级 ESLint 通常是解决方案npm install --save-dev eslintlatest。Q3: 在 VS Code 中ai-guard的规则没有实时提示。A3: 请按以下步骤排查确保 VS Code 的 ESLint 扩展已安装并启用。检查你的 ESLint 配置文件.eslintrc.js或eslint.config.js是否正确引入了ai-guard插件和配置。在 VS Code 中按CtrlShiftP(或CmdShiftP)输入 “ESLint: Restart ESLint Server” 并执行重启 ESLint 语言服务器。打开 VS Code 的输出面板View - Output选择 “ESLint” 频道查看是否有错误日志。6.2 规则误报与漏报Q4: 规则ai-guard/no-empty-catch报告了错误但我这个catch块确实是故意留空的比如在可选的第三方 API 调用失败时忽略错误。A4: 这是一个典型的“误报”False Positive。ai-guard的规则是启发式的无法理解你的业务意图。在这种情况下你有几种选择添加注释在catch块内添加一行注释如// Intentionally ignored: optional feature。这能让其他开发者明白这不是疏忽。禁用规则如果这种情况在项目中很常见你可以在该文件顶部或该特定行禁用此规则。// eslint-disable-next-line ai-guard/no-empty-catch try { ... } catch {}报告给作者如果你认为这种情况非常普遍且规则应该能更智能地识别例如忽略console.warn或特定错误类型的 catch欢迎在 GitHub 仓库提交 issue附上代码示例这有助于改进规则。Q5: 我发现了一个明显的 AI 引入的 bug比如一个特定的不安全模式但ai-guard没有报告。A5: 这就是“漏报”False Negative。ai-guard的规则集还在不断完善中。请务必在 GitHub 仓库提交一个 issue详细描述你使用的 AI 工具Cursor, Claude, Copilot。触发该 bug 的提示词Prompt或上下文。AI 生成的有问题的代码片段。你认为正确的代码应该是什么样。 你的反馈是让这个工具变得更强大的最重要动力。6.3 性能与配置Q6: 在我的大型单体仓库中扫描速度有点慢。A6: ESLint 的性能主要受文件数量和分析复杂度影响。你可以尝试使用.eslintignore文件忽略不需要检查的目录如node_modules,dist,build。在 CI/CD 环境中可以只对变更的文件进行 lint (eslint --fix $(git diff --name-only HEAD))但全量扫描对于确保代码库整体健康仍是必要的。ai-guard规则本身经过优化AST 匹配逻辑是高效的。如果仍感觉慢可能是项目本身文件过多考虑拆分代码库或许是根本解决方案。Q7: 我想自定义某条规则的严重程度如把no-empty-catch从warn改成error或者修改它的配置选项。A7: 完全支持。在 ESLint 配置文件的rules部分你可以像配置任何其他 ESLint 规则一样配置ai-guard的规则。rules: { ‘ai-guard/no-empty-catch‘: [‘error‘, { allowComments: true }], // 设置为错误且允许带注释的空 catch ‘ai-guard/no-magic-numbers‘: [‘warn‘, { ignore: [0, 1, -1] }], // 设置为警告并忽略 0, 1, -1 }具体的可配置选项请查阅项目 GitHub 仓库中每条规则的文档。6.4 如何贡献eslint-plugin-ai-guard是一个开源项目它的成长离不开社区的贡献。如果你觉得它有用并希望它变得更好以下是你参与的方式报告 Bug 或误报在 GitHub Issues 页面清晰描述你遇到的问题。提议新规则如果你发现了一种新的、反复出现的 AI 反模式欢迎提交规则请求。请提供尽可能多的真实 AI 生成代码示例。贡献代码如果你熟悉 ESLint 规则开发可以直接 Fork 仓库实现新规则或修复 Bug然后提交 Pull Request。项目结构清晰有贡献指南。分享案例在社交媒体、技术社区分享你使用ai-guard捕获到的“经典” AI bug 案例让更多开发者受益。我个人在维护这个项目中发现与社区互动是最大的动力来源。每一次 issue 讨论每一次 pull request都让这个工具更贴近真实开发场景更能精准地狙击那些让我们头疼的“AI代码糟粕”。
AI代码质量守卫：eslint-plugin-ai-guard 实战指南
发布时间：2026/5/27 9:19:50
1. 项目概述当AI成为你的“初级程序员”如果你和我一样在过去一年里深度使用了 Cursor、Claude Code 或者 GitHub Copilot那你一定对那种“一半惊喜一半惊吓”的感觉深有体会。惊喜的是一个模糊的想法几秒钟内就能变成可运行的代码骨架惊吓的是这些代码里总藏着一些让人哭笑不得的“AI式坏习惯”。比如一个光秃秃的try...catch块错误被默默吞掉让你在深夜排查生产环境故障时一头雾水又或者一个本该用参数化查询的 SQL 语句被 AI 用字符串拼接粗暴地写出来留下了 SQL 注入的隐患。更让人头疼的是这些问题并非偶发而是高度可预测、可复现的模式。AI 模型基于海量公开代码训练而公开代码库中本身就充斥着大量不严谨的示例。于是AI 学会了快速生成“能跑”的代码却未必是“健壮”或“安全”的代码。标准的 ESLint 规则集如eslint:recommended或typescript-eslint/recommended主要针对通用的 JavaScript/TypeScript 最佳实践对于这些新兴的、由 AI 编码风格催生的特定反模式往往力有不逮。这就是我动手构建eslint-plugin-ai-guard的初衷。我不想再手动审查每一段 AI 生成的代码也不想在代码评审中反复指出同样的低级错误。我需要一个能自动识别这些“AI代码糟粕”的守卫。这个插件不是一个庞大的、包含数百条规则的代码风格指南而是一把精准的手术刀专门切除由 AI 工具高频引入的 17 种典型问题。更关键的是我把它做成了零配置的 CLI 工具ai-guard你只需要npx ai-guard run它就能在几秒钟内扫描你的项目并给出报告。自发布以来它在几天内获得了超过一千次的 npm 下载这让我确信痛恨“AI代码糟粕”的开发者远不止我一个。2. 核心设计思路为何通用ESLint规则不够用在决定造轮子之前我首先系统性地回顾了现有 ESLint 生态能否解决我的问题。结论是部分可以但存在显著缺口。通用规则和 AI 反模式之间存在一个“匹配度”的鸿沟。2.1 通用规则的盲区现有的优秀规则如no-empty可以捕获空的catch块typescript-eslint/no-floating-promises能发现未处理的 Promisesecurity/detect-object-injection也能防范一些安全问题。但它们的设计初衷是普适性的缺乏对“AI代码生成场景”的针对性优化。举个例子AI 经常在 Express.js 或类似框架的路由处理函数中忘记添加身份验证中间件。没有一个通用规则会叫require-auth-middleware因为“是否需要认证”是业务逻辑不是语法问题。但在这个上下文中这又是一个极高频、高风险的遗漏。再比如AI 喜欢在循环内部使用await这会导致性能极差的串行执行而通用规则no-await-in-loop虽然存在但在许多预设中并未被启用或者其报告的信息不够直白无法让开发者立刻联想到这是 AI 的惯用写法。2.2 AI反模式的“指纹”特征经过对数百个由 Cursor、Claude 生成的代码片段进行分析我归纳出 AI 引入的问题具有高度集中的“指纹”特征。它们通常不是复杂的逻辑错误而是模式化的“偷懒”或“模仿”行为错误处理的敷衍了事直接生成try { ... } catch {}或try { ... } catch (e) {}没有日志没有错误传播没有用户反馈。这是最典型的“代码能编译就行”思维。安全意识的普遍缺失对用户输入缺乏警惕。除了 SQL 拼接还包括不安全的反序列化如直接JSON.parse(req.body)、未经验证的跳转等。异步控制的混乱滥用async/await而不理解其执行模型导致出现无意义的async函数、循环内await或漏掉关键的await。权限检查的遗漏在 Web 开发中几乎每个需要鉴权的接口AI 都可能忘记添加中间件或权限判断逻辑。这些特征如此明显和集中以至于为它们定制专属的 lint 规则变得非常有价值。eslint-plugin-ai-guard的核心思路就是将这些“指纹”编码成具体的 AST抽象语法树匹配模式在代码静态分析阶段就将其拦截。2.3 “零配置”哲学与预设策略我深知为现有项目引入一个新的 lint 工具最大的阻力往往是配置成本。因此“零配置”是ai-guardCLI 的核心理念。你不需要理解 ESLint 的扁平配置Flat Config或传统配置的区别不需要手动安装和配置插件甚至不需要创建一个.eslintrc文件。其背后是三层预设策略recommended(默认)这是噪音最低的预设。只包含那些误报率极低、问题严重性较高的规则。目标是让你可以毫无心理负担地将其接入任何现有项目它只会报告那些“几乎可以肯定是问题”的情况。strict包含所有 17 条规则。适合在新项目启动时使用或者当你希望对代码库进行彻底“AI糟粕”清理时使用。可能会产生一些需要你主观判断的警告例如某些情况下空的catch块可能是设计使然。security专注于安全相关的子集如防止 SQL 拼接、不安全的反序列化、缺失的身份验证等。适合在 CI/CD 流水线中作为安全门禁。通过npx ai-guard run工具会自动应用recommended预设。你也可以通过npx ai-guard run --preset strict来切换。这种设计极大地降低了使用门槛让开发者能够专注于解决问题而非配置工具。3. 规则深度解析与实战场景eslint-plugin-ai-guard的 17 条规则并非随意堆砌每一类都针对一个明确的、由 AI 引发的痛点。下面我们来深入剖析几类核心规则看看它们具体拦截什么以及为什么这些模式如此危险。3.1 错误处理与健壮性规则这类规则旨在防止 AI 生成“脆弱”的代码这些代码在异常情况下会静默失败给调试和运维带来噩梦。ai-guard/no-empty-catch这可能是排名第一的“AI糟粕”。AI 倾向于生成最简单的结构来满足语法要求。// AI 生成的典型糟粕 try { const data JSON.parse(userInput); } catch { // 空空如也错误被完全忽略。 }为什么危险当JSON.parse失败时程序会继续执行但data是undefined后续使用data的代码很可能抛出另一个难以追溯根源的错误。修正建议至少应该记录错误console.error(‘Failed to parse input:’, e)或者根据上下文向上抛出错误、返回错误响应。ai-guard/no-floating-promises虽然类似规则存在于其他插件但 AI 生成异步代码时特别容易犯这个错误。// AI 可能这样写一个事件处理器 function handleClick() { saveDataToAPI(); // 这是一个返回 Promise 的函数但未被 await 或 .then() 处理 showSuccessMessage(); // 这条消息可能在 saveDataToAPI 失败前就显示了 }为什么危险未处理的 Promise 如果被拒绝rejected错误会被悄无声息地吞掉在 Node.js 最新版本中会触发unhandledRejection但浏览器环境或旧版 Node 中可能不会。这会导致数据保存失败而用户浑然不知。修正建议使用await在async函数中或添加.catch()处理。3.2 异步代码稳定性规则AI 对异步编程模型的理解常常停留在表面导致生成性能低下或逻辑错误的代码。ai-guard/no-await-in-loop这是 Claude 和 Cursor 的“经典之作”。当被要求处理一个数组时AI 会不假思索地写出串行代码。// 低效的 AI 写法 for (const item of items) { const result await processItem(item); // 每个 await 都会阻塞循环 }为什么危险如果items有 100 个processItem每个耗时 100ms那么总耗时将是 10 秒。修正建议使用Promise.all进行并行处理除非处理项之间有严格的先后依赖关系。// 高效的写法 const results await Promise.all(items.map(item processItem(item)));ai-guard/no-async-without-await将一个函数标记为async却不在其内部使用await通常是无用或错误的。// 无意义的 async 标记 async function getConfig() { return cachedConfig; // 直接返回一个非 Promise 值 }为什么危险这会造成微小的性能开销函数返回一个 Promise 包装的值更重要的是它反映了开发者或 AI对函数是否真正异步的混淆。如果调用者以为它是异步的而使用了await就会增加不必要的复杂性。修正建议移除async关键字。3.3 安全防护规则这是最致命的一类规则。AI 在生成代码时几乎不会主动考虑安全边界。ai-guard/no-unsafe-sql-concat直接使用字符串拼接来构造 SQL 查询是安全领域的“原罪”。// 高危SQL 注入漏洞 const query SELECT * FROM users WHERE username ${username};为什么危险如果username是admin --整个查询的逻辑就会被改变。修正建议使用参数化查询或预编译语句。对于不同的数据库驱动写法不同如?占位符、$1等。ai-guard/no-unsafe-deserialize不假思索地反序列化来自外部的数据。// 在 Express 路由中危险的做法 app.post(‘/data‘, (req, res) { const obj JSON.parse(req.body); // req.body 可能已被污染 // ... });为什么危险恶意构造的 JSON 字符串可能触发原型污染攻击或消耗大量资源导致拒绝服务。修正建议对来源不可信的数据使用安全的解析方式如限制深度、过滤原型或者直接使用 Web 框架内置的、安全的 body-parser 中间件如express.json()它们通常有内置的保护。ai-guard/require-auth-middleware与ai-guard/require-authz-check这两条是语义级规则。它们不会分析代码语法而是检查在特定的路由或控制器上下文中是否出现了认证(auth)和授权(authz)的关键字或模式。// AI 可能生成这样的“裸”路由 app.get(‘/api/admin/users‘, (req, res) { // 缺少 auth 中间件 if (req.user.role ! ‘admin‘) { // 缺少前置的 authz 检查且这个检查本身可能也不够早 return res.status(403).send(‘Forbidden‘); } // ... 获取用户列表 });规则逻辑require-auth-middleware会扫描类似app.get(‘/api/...‘, handler)的模式检查handler之前是否有常见的认证中间件引用如auth,authenticate,passport.authenticate等。require-authz-check则更深入一步在路由处理函数内部检查是否在访问受保护资源如查询用户数据、修改设置前进行了角色或权限的判断。为什么重要权限漏洞是最高危的漏洞之一。这两条规则通过模式匹配为常见的 Web 框架提供了一道重要的安全提醒防线。虽然无法理解复杂的业务逻辑但能捕捉到完全缺失这类检查的明显漏洞。3.4 代码质量规则这类规则关注那些不会立即导致崩溃或漏洞但会降低代码可维护性和可读性的模式。ai-guard/no-magic-numbersAI 经常在条件判断或计算中直接使用字面量数字。if (user.age 18) { // 这个 18 是什么法定成年年龄 return ‘minor‘; } const discount price * 0.1; // 0.1 是折扣率为什么是 10%为什么不好“魔数”使得代码意图模糊难以维护。如果“成年年龄”或“折扣率”在业务中发生变化你需要搜索并修改所有出现这个数字的地方极易出错。修正建议将数字定义为有意义的常量const LEGAL_ADULT_AGE 18;。注意ai-guard的规则是“可调节的警报器”而非“不可违背的法则”。有些规则如no-magic-numbers在严格模式下触发可能需要你根据实际情况判断是否违反。例如if (retries 3)中的3可能就是一个可以接受的、明确的阈值。规则的意义在于促使你思考并做出有意识的选择。4. 从安装到集成无缝接入你的工作流让一个工具真正产生价值关键在于它能多平滑地融入你现有的开发流程。eslint-plugin-ai-guard和ai-guardCLI 的设计目标就是“开箱即用无缝集成”。4.1 快速启动零配置扫描对于只想快速体验或一次性检查项目的人来说ai-guardCLI 是最佳入口。它不需要你在项目中安装任何东西。打开你的项目根目录。在终端中运行一条命令npx ai-guard run这条命令会在后台自动下载并执行ai-guard。使用内置的recommended预设规则。自动探测项目中的 JavaScript/TypeScript 文件支持.js,.jsx,.ts,.tsx。在几秒到几十秒内取决于项目大小完成扫描并在终端输出一个清晰的报告列出每个问题所在的文件、行号、列号以及规则说明。实战示例输出✔ Scanning 154 files with ai-guard/recommended ⏱ Scanned in 7.2s ⚠ Found 61 warnings src/api/users.js:45:3 ai-guard/require-auth-middleware Route handler for ‘/api/users‘ is missing authentication middleware. src/utils/db.js:12:21 ai-guard/no-unsafe-sql-concat Potential SQL injection vulnerability. Use parameterized queries. src/scripts/processInvoices.js:67:7 ai-guard/no-await-in-loop Avoid using ‘await‘ inside a loop. Consider using ‘Promise.all‘.这个报告直接指出了问题类型、位置和修复方向 actionable 非常强。4.2 深度集成作为ESLint插件安装如果你希望将 AI Guard 的规则作为你日常 ESLint 检查的一部分例如在编辑器中实时提示或在npm run lint中执行则需要将其作为插件安装。安装插件npm install --save-dev eslint eslint-plugin-ai-guard # 或者使用 yarn/pnpm yarn add --dev eslint eslint-plugin-ai-guard pnpm add -D eslint eslint-plugin-ai-guard配置 ESLint 根据你的 ESLint 配置格式传统.eslintrc.*或新的eslint.config.jsFlat Config进行配置。对于 Flat Config (eslint.config.js)import aiGuard from ‘eslint-plugin-ai-guard‘; export default [ // ... 你的其他配置 { plugins: { ‘ai-guard‘: aiGuard, }, rules: { // 启用推荐的规则集 ...aiGuard.configs.recommended.rules, // 或者启用严格规则集 // ...aiGuard.configs.strict.rules, // 你也可以单独启用某条规则并自定义级别 // ‘ai-guard/no-empty-catch‘: ‘error‘, }, }, ];对于传统配置 (.eslintrc.js)module.exports { plugins: [‘ai-guard‘], extends: [ // 启用推荐配置 ‘plugin:ai-guard/recommended‘, // 或者 ‘plugin:ai-guard/strict‘, ‘plugin:ai-guard/security‘ ], // 也可以单独配置规则 rules: { ‘ai-guard/no-magic-numbers‘: ‘off‘, // 关闭某条规则 }, };运行与体验 配置完成后你就可以像平时一样使用 ESLint 了。命令行npx eslint .编辑器集成如果你有 ESLint 编辑器扩展如 VS Code 的 ESLint 扩展保存文件时就能实时看到ai-guard规则的提示。Git Hook通过husky和lint-staged在提交代码前自动运行检查防止“AI糟粕”进入仓库。4.3 与现有工具链的协作你可能会担心ai-guard与现有的typescript-eslint、eslint-plugin-react等插件冲突。完全不会。ESLint 的配置是可以叠加的。ai-guard的规则命名都带有ai-guard/前缀避免了与其他插件规则的冲突。你只需要在配置数组中添加一个新的配置对象即可。一个典型的现代项目 ESLint Flat Config 可能长这样import js from ‘eslint/js‘; import tseslint from ‘typescript-eslint/eslint-plugin‘; import aiGuard from ‘eslint-plugin-ai-guard‘; export default [ js.configs.recommended, ...tseslint.configs.recommended, { plugins: { ‘ai-guard‘: aiGuard, }, rules: { ...aiGuard.configs.recommended.rules, // 你可以覆盖任何规则的严重程度 ‘ai-guard/no-empty-catch‘: ‘error‘, // 将警告提升为错误 ‘typescript-eslint/no-explicit-any‘: ‘warn‘, }, }, ];实操心得从 CLI 到插件。我建议的路径是先用npx ai-guard run快速扫描你的项目感受一下它能发现多少问题。如果觉得有价值再将其作为插件集成到开发流程中。对于大型存量项目一开始使用strict预设可能会产生大量警告让人望而却步。更好的策略是先集成recommended预设解决掉那些高严重性问题然后定期用strict预设进行扫描像“技术债清理日”一样分批分模块地修复那些代码质量问题。这样阻力最小收益持续。5. 实战案例剖析在真实项目中发现了什么理论说再多不如看一个真实的例子。我在自己的一个模拟生产环境的“发票应用”Next.js 前端 Express.js 后端上运行了ai-guard它在大约 7 秒内扫描了约 150 个文件抛出了 61 个警告。这个结果非常有代表性揭示了 AI 辅助编码在真实项目中的“犯罪现场”。5.1 问题分布与典型代码片段让我们看看排名前几的问题require-auth-middleware(34个警告)这是重灾区。Express 路由文件中大量类似/api/invoices、/api/clients的端点处理函数前都没有auth()或jwt.verify()之类的中间件。AI 在生成 CRUD 接口时默认假设它们是公开的。// 被 AI Guard 捕获的代码 router.get(‘/api/invoices‘, async (req, res) { const invoices await db.invoice.findMany(); res.json(invoices); // 任何未经验证的用户都能获取所有发票 });require-authz-check(13个警告)即使在有基础认证的路由中AI 也经常忘记进行细粒度的授权检查。例如在GET /api/users/:userId中没有验证当前登录用户是否就是:userId本人或有管理员权限。router.get(‘/api/users/:id‘, authMiddleware, async (req, res) { const user await db.user.findUnique({ where: { id: req.params.id } }); res.json(user); // 用户A可以查看用户B的私密信息 });no-await-in-loop(5个警告)出现在后台脚本和数据处理函数中。例如一个用于批量发送邮件的脚本AI 写出了for (const user of users) { await sendEmail(user); }这样的代码使得发送 1000 封邮件变成了串行任务。no-async-without-await(6个警告)一些工具函数或事件监听器被不必要地标记为async。这通常发生在 AI 复制粘贴了某个async函数模板但实际函数体内并没有异步操作。no-unsafe-deserialize(3个警告)在一个接收 Webhook 的端点中AI 直接使用了JSON.parse(req.rawBody)而没有对数据大小或结构做任何验证。5.2 修复过程与收益修复这些警告的过程本身就是一次绝佳的安全和代码质量审查。对于缺失的中间件我创建了一个统一的authMiddleware并将其应用到所有需要认证的路由器上。这不仅仅是修复 lint 错误更是强制建立了一道安全基线。对于授权问题我实现了一个简单的canViewUser权限检查函数并在每个涉及资源访问的地方调用它。这促使我思考了应用的权限模型。对于await in loop我将其重构为Promise.all那个批量发邮件的脚本执行时间从预计的十几分钟缩短到了几十秒。对于不安全的JSON.parse我引入了zod库对 Webhook 负载进行模式验证和解析同时拒绝了过大的 payload。这次扫描带来的直接收益堵住了多个严重的安全漏洞未授权访问、潜在的拒绝服务。显著提升了关键后台任务的性能。统一了项目的错误处理和认证授权模式代码更加一致和可维护。为团队建立了新的代码质量红线以后所有 AI 生成的代码都必须先过一遍ai-guard的检查。这个过程清晰地证明ai-guard发现的不是吹毛求疵的风格问题而是实实在在会影响应用稳定性、安全性和性能的缺陷。它充当了 AI 这位“初级程序员”的资深代码评审员。6. 常见问题、排查与贡献指南在开发和推广eslint-plugin-ai-guard的过程中我遇到了不少问题也收到了很多用户的反馈。这里整理一份常见问题清单希望能帮你更快地上手和解决问题。6.1 安装与运行问题Q1: 运行npx ai-guard run时报错 “Command not found” 或类似错误。A1: 这通常是因为网络问题导致npx无法从 npm registry 下载包。请确保你的网络连接正常并且能够访问registry.npmjs.org。你也可以尝试清除 npm 缓存npm cache clean --force然后重试。Q2: 我已经全局安装了 ESLint但ai-guard作为插件运行时报版本不兼容。A2:ai-guard同时支持 ESLint 8 和 9包括 Flat Config。请确保你的项目本地安装的 ESLint 版本在^8.0.0或^9.0.0范围内。你可以运行npx eslint --version检查项目使用的版本。如果版本过低升级 ESLint 通常是解决方案npm install --save-dev eslintlatest。Q3: 在 VS Code 中ai-guard的规则没有实时提示。A3: 请按以下步骤排查确保 VS Code 的 ESLint 扩展已安装并启用。检查你的 ESLint 配置文件.eslintrc.js或eslint.config.js是否正确引入了ai-guard插件和配置。在 VS Code 中按CtrlShiftP(或CmdShiftP)输入 “ESLint: Restart ESLint Server” 并执行重启 ESLint 语言服务器。打开 VS Code 的输出面板View - Output选择 “ESLint” 频道查看是否有错误日志。6.2 规则误报与漏报Q4: 规则ai-guard/no-empty-catch报告了错误但我这个catch块确实是故意留空的比如在可选的第三方 API 调用失败时忽略错误。A4: 这是一个典型的“误报”False Positive。ai-guard的规则是启发式的无法理解你的业务意图。在这种情况下你有几种选择添加注释在catch块内添加一行注释如// Intentionally ignored: optional feature。这能让其他开发者明白这不是疏忽。禁用规则如果这种情况在项目中很常见你可以在该文件顶部或该特定行禁用此规则。// eslint-disable-next-line ai-guard/no-empty-catch try { ... } catch {}报告给作者如果你认为这种情况非常普遍且规则应该能更智能地识别例如忽略console.warn或特定错误类型的 catch欢迎在 GitHub 仓库提交 issue附上代码示例这有助于改进规则。Q5: 我发现了一个明显的 AI 引入的 bug比如一个特定的不安全模式但ai-guard没有报告。A5: 这就是“漏报”False Negative。ai-guard的规则集还在不断完善中。请务必在 GitHub 仓库提交一个 issue详细描述你使用的 AI 工具Cursor, Claude, Copilot。触发该 bug 的提示词Prompt或上下文。AI 生成的有问题的代码片段。你认为正确的代码应该是什么样。 你的反馈是让这个工具变得更强大的最重要动力。6.3 性能与配置Q6: 在我的大型单体仓库中扫描速度有点慢。A6: ESLint 的性能主要受文件数量和分析复杂度影响。你可以尝试使用.eslintignore文件忽略不需要检查的目录如node_modules,dist,build。在 CI/CD 环境中可以只对变更的文件进行 lint (eslint --fix $(git diff --name-only HEAD))但全量扫描对于确保代码库整体健康仍是必要的。ai-guard规则本身经过优化AST 匹配逻辑是高效的。如果仍感觉慢可能是项目本身文件过多考虑拆分代码库或许是根本解决方案。Q7: 我想自定义某条规则的严重程度如把no-empty-catch从warn改成error或者修改它的配置选项。A7: 完全支持。在 ESLint 配置文件的rules部分你可以像配置任何其他 ESLint 规则一样配置ai-guard的规则。rules: { ‘ai-guard/no-empty-catch‘: [‘error‘, { allowComments: true }], // 设置为错误且允许带注释的空 catch ‘ai-guard/no-magic-numbers‘: [‘warn‘, { ignore: [0, 1, -1] }], // 设置为警告并忽略 0, 1, -1 }具体的可配置选项请查阅项目 GitHub 仓库中每条规则的文档。6.4 如何贡献eslint-plugin-ai-guard是一个开源项目它的成长离不开社区的贡献。如果你觉得它有用并希望它变得更好以下是你参与的方式报告 Bug 或误报在 GitHub Issues 页面清晰描述你遇到的问题。提议新规则如果你发现了一种新的、反复出现的 AI 反模式欢迎提交规则请求。请提供尽可能多的真实 AI 生成代码示例。贡献代码如果你熟悉 ESLint 规则开发可以直接 Fork 仓库实现新规则或修复 Bug然后提交 Pull Request。项目结构清晰有贡献指南。分享案例在社交媒体、技术社区分享你使用ai-guard捕获到的“经典” AI bug 案例让更多开发者受益。我个人在维护这个项目中发现与社区互动是最大的动力来源。每一次 issue 讨论每一次 pull request都让这个工具更贴近真实开发场景更能精准地狙击那些让我们头疼的“AI代码糟粕”。
