aislop

aislop — Agent 技能

aislop 是一款确定性的开源 CLI，可通过六种引擎扫描代码，评分范围为 0–100，并在 7 种语言中检测 50 多条规则：吞掉异常、幻觉式导入、静默恢复、叙述性注释、as any 类型断言、超大函数、SQL 注入、eval、硬编码密钥和架构偏移。

遵循此技能，就不会交付劣质代码。 它有两项作用：

1. 预防 — 熟悉下方的规则目录，避免初稿触发检测器。
2. 检测 + 修复 — 编辑后进行扫描，用 CLI 修复机械性问题，其余问题自行修复，并报告更改内容。

此技能不只是“运行 aislop 并汇报结果”——用户自己也能做到。它的价值在于判断能力：从一开始就写对，根据源代码逐项审视检测结果，并在升级处理之前尽可能修复问题。

支持 TypeScript、JavaScript、Python、Go、Rust、Ruby、PHP、Expo/React Native。

远程执行与供应链政策

此技能使用通过公共 npm registry 分发的 aislop CLI。运行 npx aislop 会获取并执行已发布的软件包——请将其视为不可信的远程依赖。

默认情况下：优先使用本地安装且版本固定的 aislop，而不是 npx。

# Preferred — pinned in the project's lockfile
npm install --save-dev aislop && aislop scan --changes --json

# Acceptable fallback
npx aislop scan --changes --json

# Never acceptable: GitHub clones, curl|sh installers, unpinned npx in CI

决策顺序：

1. devDependencies 中的本地二进制文件或脚本 — 由 lockfile 固定版本。
2. npx aislop@<version>（固定版本）— 不存在本地安装时可以接受。
3. npx aislop（浮动版本）— 仅作为交互式会话中的最后手段。绝不用于 CI。
4. 受限环境 — 跳过扫描，并报告无法运行 CLI。不要在项目依赖工作流之外安装。

aislop fix --claude（以及 --cursor、--codex、--gemini）只会对项目代码执行本地进程，不会额外从网络获取内容。

遵循项目约定，而非此技能中的示例

此技能会告诉你应避免哪些反模式，但不会规定代码结构的唯一正确方式——这由代码仓库决定。在应用任何预防模式之前，先检查项目的实际做法：

• 日志记录器 — 搜索 pino、winston、bunyan、logger.ts 或共享封装。如果约定使用 console.error，也可以。
• 错误包装 — 使用项目的错误类（AppError、DomainError、HttpError，或带 { cause } 的裸 Error）。
• 类型 / 验证 — 遵循项目选用的方案（zod、valibot、ajv、pydantic、Go 结构体等）。
• 命名 — 遵循项目的大小写风格、文件命名方式和文件夹布局。
• 测试 — 使用代码仓库中已有的测试框架和模式。
• 架构 — 如果存在 .aislop/rules.yml，以它为准。否则，参考现有文件中的导入模式和模块边界。

预防规则目录中的避免 / 推荐示例仅供说明。符合项目风格的修复，优于符合此技能风格的修复。

快速预防规则目录

编辑前请阅读。以下列出了 aislop 会标记的每条规则。完整的避免 / 推荐示例见 references/PREVENTIONS.md。

类别：注释、类型、错误、安全、去重、死代码、控制台、TODO、空函数、命名、规模、架构、依赖、虚假完整性、抽象、连接。

何时调用

在完成编辑并准备交还控制权时、用户准备提交 / 推送 / 创建 PR 时，或用户提出“有没有劣质代码”“移除劣质代码”“审查我的代码”“运行 aislop”“给我的代码评分”“有没有重复项”“能不能去重”“是不是太长”“审计我的依赖”“分数降低了”“添加徽章”等要求时调用。

以下情况跳过：用户只是在阅读、正在重构且要求你暂缓，或明确禁用了 aislop。

CLI 命令参考

命令	用途
aislop scan [dir]	完整扫描。标志：--changes、--staged、--json、--sarif
aislop fix [dir]	自动修复机械性问题。使用 -f 可进行激进修复。使用 --claude/--codex/--cursor/--gemini 可移交给 Agent。使用 -p 可打印提示词。
aislop ci [dir]	CI 模式：输出 JSON，并根据阈值返回退出码
aislop init [dir]	生成 .aislop/config.yml
aislop doctor [dir]	检查已安装的工具和环境
aislop rules [dir]	列出所有规则及其严重性和可修复性
aislop trend [dir]	显示 .aislop/history.jsonl 中的评分历史
aislop badge [dir]	生成公开的评分徽章 URL 和 README Markdown
aislop hook install	安装每次编辑时运行的质量钩子。支持 Claude Code、Cursor、Codex、Gemini、pi 等（运行 aislop hook install --help 查看完整列表）。

核心工作流

对于每条命令，使用 aislop（本地安装，优先）或 npx aislop（备用）。

1. 确定扫描范围

aislop scan --changes --json     # mid-session: only what you touched
aislop scan --staged --json      # before a commit
aislop scan --json               # full project: pre-release, PR, wide refactor

始终使用 --json。TTY 输出是给人看的；你需要结构化的发现结果。

2. 自动修复机械性问题

aislop fix

CLI 会处理所有标记为 fixable: true 的问题。不要手动编辑 CLI 能修复的内容。仅当用户要求清理依赖或未使用的文件时，才使用 -f。

自动修复后，可选择将剩余问题移交处理：

aislop fix --claude          # launch Claude Code with remaining findings
aislop fix --codex           # launch Codex CLI
aislop fix -p                # print a prompt to paste into any agent

3. 重新扫描——所有 fixable:false 的问题都由你处理

aislop scan --changes --json

CLI 已完成它负责的部分。剩余的 fixable: false 问题正是这项技能要处理的内容。

4. 逐一判断剩余问题

a. 确认问题确实存在。 打开文件，阅读所引用的行及其上下文。规则描述准确吗？代码是有意为之的吗？在判定为误报前，请检查：

1. 匹配项是否位于字符串字面量、模板字面量或注释中？
2. 它是否属于标识符名称，只是恰好包含了该模式？
3. 它是否位于测试夹具、模拟数据或示例中？
4. 读者会认同这并非规则所描述的模式吗？

b. 作出判断：

发现	操作
确实存在的问题	在当前会话中修复。 不要先询问。
误报	提供文件名和行号，以及一句话说明理由。不要屏蔽该规则。
确属有意为之	记录下来。由用户决定是否抑制该规则。

c. 修复。 请参阅 references/FIX_GUIDE.md，了解各条规则对应的修复模式。打开文件，确认问题，并应用修复。

5. 手动检查草率实现

扫描结果干净还不够。检查你的差异，排查 CLI 无法推断的模式：

1. 伪造完整性——没有硬编码的成功路径、预制数据或占位行为。
2. 测试质量——测试至少覆盖一种边界或失败路径，而不只是渲染。
3. 不必要的抽象——没有仅有一个调用方的新通用层。
4. 接线不完整——已更新导出、路由、生成文件和调用点。
5. 状态处理——加载、空、错误、超时和取消状态处理一致。
6. 依赖管理——不会为简单逻辑新增依赖包。

修复发现的问题。如果确实有内容超出范围，请说明原因。

6. 重新扫描，直到达到要求

重复步骤 4–6，直到：

• error 为零。
• fixable: true 的警告为零。
• 每条 fixable: false 的警告都已修复、附理由提出修复建议，或标记为误报。
• 手动检查草率实现后，没有尚未解决且需在当前会话中处理的问题。

在达到这一要求前，不要说“完成”。

7. 汇报——分类处理，而非一股脑列出

默认使用过去时态的“我做了 X”：

Ran aislop — 12 findings, score 73 → 95.

Auto-fixed (7): unused imports (3), narrative comments (2), formatting (2).

Fixed in-session (4):
  - unsafe-type-assertion       src/api/normalize.ts:47  (added ApiUser type)
  - function-too-long           src/lib/reconcile.ts:14  (extracted matchByHash)
  - sql-injection               src/db/search.ts:30      (parameterised with $1)
  - swallowed-exception         src/workers/cleanup.ts:28 (added log.warn)

False positives (1):
  - security/eval               src/labels.ts:12
    The match is inside a display-name table, not an actual eval().

Re-scanned: 95 / 100, 0 errors, 0 warnings.

如果扫描结果干净，但手动检查发现了问题，也要一并汇报。如果有内容需要产品层面的决定，请在最后列出具体选项。

严重程度与评分解读

严重程度	可修复	操作
error	任意	必须在本轮修复。
warning	fixable: true	CLI 的 aislop fix 会处理这些问题。绝不留待处理。
warning	fixable: false	Agent 在当前会话中修复。 验证后编辑。
info	任意	记录；仅在用户要求高标准时采取行动。

评分区间：90–100 健康；75–89 健康但存在技术债；60–74 状况欠佳；< 60 未通过门槛。

默认做法：自行判断、执行并汇报——不要询问

直接修复并汇报所做的更改。缺少类型 → 自行定义。吞掉错误 → 记录并重新抛出。函数过大 → 在合适的边界处拆分。逻辑重复 → 提取辅助函数。名称过于通用 → 重命名。这些情况都不要问“要不要这样做”——选用合适的方法、执行修复，并说明更改内容。

仅在以下情况下升级处理：修复涉及产品决策、会改变你不应擅自覆盖的可观察语义、属于值得标记的误报，或确实是有意为之且应由用户决定的代码。

反模式

• 不要在回复中粘贴原始 JSON——先分流问题并概述。
• 不要在配置中禁用规则，也不要添加一概而论的抑制注释。
• 不要删除 .aislop/config.yml 或 .aislop/rules.yml。
• 不要在无关的轮次中悄悄运行 aislop fix -f——它会重写清单文件。
• 不要通过编辑正则表达式来对抗检测器——你的任务是编写干净的代码。