SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场code-smells-audit

code-smells-audit

编程与开发

查看项目

更新于 10-23 16:18

技能介绍

用途

code-smells-audit 是一个目录驱动的代码异味审计技能。它不依赖评审者的临场记忆，而是把发现结果逐条对照 56 张精炼参考卡，这些卡源自 Marcel Jerzyk 的 Code Smells Catalog，并在进入报告前按每项异味的实际定义进行核验。适用于对代码库、指定路径或分支差异做系统性异味排查。

主要能力

  • 范围解析：参数可以是路径（递归扫描该文件或目录）、glob（匹配文件）、diff（当前分支变更，即 git diff --name-only $(git merge-base <default-branch> HEAD) 列出的文件加上 git status --porcelain 中的未提交改动，只审计这些文件，判断严重度时只看变更区域），或为空（全仓库扫描）。
  • 排除依赖与生成代码：始终排除 vendor/、node_modules/、锁文件、构建产物以及 .gitignore 忽略的内容，只审计源码。
  • 分片扫描：全仓库扫描时按代码库规模分派子代理——小型（约 100 个源文件以内）由主代理顺序执行透镜扫描；中型（约 1,000 以内）每个发生场景透镜一个子代理并行扫描全目标；大型按顶层模块或目录分区，每个分区一个子代理跑全部透镜，验证前合并候选列表。在 Claude Code 中安装了该插件时，可分发 subagent_type=leek-skills:smell-sweeper（只读、不加载项目 CLAUDE.md、使用更便宜的模型）；其他环境下可用任意只读子代理和最便宜的模型，扫描只负责召回，验证在主模型上进行。
  • 透镜扫描：先读 references/index.md，它把 56 项异味归入 9 个发生场景透镜并各附一行描述；透镜归属只以该索引为准，不从记忆中的异味清单出发。每个透镜跑一次检测，凭该透镜的一行描述扫描目标，疑似匹配即记录候选：candidate: <smell slug> · <file:line-range> · <one-line evidence>。扫描阶段不读完整卡、不判断、不排序、不过滤，偏向召回。
  • 对抗性验证：每个候选都要读 references/smells/<slug>.md 完整卡，以怀疑视角重读代码，确认是否真正满足卡中的定义段与检测启发式，还是仅触碰了表面信号（长度、关键词、形状）的近似误判。存活的发现必须引用或紧密转述卡定义中代码所满足的具体句子，作为合格理由；若无一句定义契合，候选即失败。对依赖引用关系的异味（Dead Code、Lazy Element、Middle Man、Feature Envy、Shotgun Surgery、Speculative Generality），应统计调用点而非目测：有语言服务器时用 LSP 的 findReferences / incomingCalls，否则用 rg 搜索符号，并在理由中说明计数为近似值。失败候选不进入报告，仅在报告头部保留数量。
  • 报告输出：写入被审计仓库的 docs/audits/code-smells-<scope>-<YYYY-MM-DD>.md（必要时创建目录），用户另行指定路径时除外。发现按判断的严重度/影响力排序：影响范围、定义契合程度、代码再次被改动的可能性；逐条独立判断，绝不把分类法当作严重度代理。每条发现包含：异味名称、位置（file:line-range）、合格理由（引用卡定义）、阻碍标签（卡分类行的中间项）、建议重构（来自卡）、卡片路径。报告骨架含目标、扫描透镜数、候选数、验证剔除数、发现数等统计，写完文件后在会话中概述主要发现并指向该文件。切片为工单不在范围内，报告交由用户或 /to-tickets 处理。

参考材料

  • references/index.md：56 项异味按 9 个透镜分组，各一行，检测分派从此出发。
  • references/smells/<slug>.md：每项异味一张卡，含分类行、定义、检测启发式（通用 + PHP/Laravel + TS/React）、示例、重构建议、类型化关联异味链接、别名。
  • references/refactoring-names.md：规范重构词汇及上游 103 个原始名称的归一化映射。
  • references/ATTRIBUTION.md：上游 MIT 声明与所请求的学术引用。

校验卡片集

卡片编辑、批量新增或上游重新同步后运行：

bash scripts/validate-cards.sh            # strict: all 56 cards must exist (ship gate)
bash scripts/validate-cards.sh --partial  # mid-build: missing cards reported as pending

人类可读状态输出到 stderr，stdout 输出 JSON 结果；通过退出码 0，失败退出码 1（每个失败指明问题文件与原因），用法错误退出码 2。脚本内置 56 个 slug 目录与封闭分类词汇，并从 references/refactoring-names.md 读取规范重构名，无需网络和上游克隆。

适用场景与限制

适用于对代码库、路径或分支差异做结构化异味审计，结果可留存以便跨时间对比。局限：检测与验证依赖上述参考卡与透镜索引，需具备相应文件；规则集聚焦 PHP/Laravel 与 TS/React 启发式；不负责把发现拆成工单；子代理分派方式视宿主环境而定，具体可用模型与工具未在本资料中给出。