OmX ai-slop-cleaner 技能实战：用行为锁定与四轮 Pass 把 AI 生成代码里的“AI 味”清理干净

ai-slop-cleaner 是 OmX（oh-my-codex）内置的一个有界（bounded）反“AI 味”清理技能，用于对膨胀、嘈杂、重复、过度抽象或明显由 AI 生成的代码执行 cleanup / refactor / deslop 工作流。本文以 plugins/oh-my-codex/skills/ai-slop-cleaner/SKILL.md 为核心，结合 OmX 工作区契约 templates/AGENTS.md 及 Ralph、Ultragoal 等下游工作流的源码实现，完整讲解该技能的使用时机、编辑前纪律、七类 Smell 分类法、四轮清理 Pass、证据输出契约与退出条件，并展示它如何作为“最终清理关卡”被强制接入 Ralph 持久化模式与 Ultragoal 严格完成门禁。读完本文，你将掌握一套可复制的“先锁行为、再分类、逐 Pass 清理、以报告收尾”的 AI 代码去味方法论。

一、技能定位：有界助手，而非顶层工作流

ai-slop-cleaner 的 frontmatter 明确定义：

name: ai-slop-cleaner
description: Run an anti-slop cleanup/refactor/deslop workflow

它被设计为有界的辅助工具，服务于 cleanup / refactor / deslop 一类工作，不作为竞争性的顶层工作流。这意味着：它应当在既定的执行通道（如直接执行、Ralph 持久化模式、Ultragoal、Team）内部被调用，而不是被当作一个与这些工作流平行的独立编排器。共享的操作不变量（operating invariants）统一存放于 templates/AGENTS.md，本技能卡只负责定义**范围（scope）、Smell 分类法（taxonomy）、清理 Pass 与证据（evidence）**四件事。

在仓库的技能目录中可以看到该技能同时存在于两个位置：插件镜像 plugins/oh-my-codex/skills/ai-slop-cleaner/SKILL.md 与根级镜像 skills/ai-slop-cleaner/SKILL.md，二者内容一致；安装后技能面由 omx setup 装入 ~/.codex/skills 或项目级 .codex/ 目录。技能目录清单还可在 src/catalog/manifest.json 中查到，其分类为 shortcut、状态为 active，生成的 src/catalog/generated/public-catalog.json 也同步收录；对应测试 src/catalog/tests/schema.test.ts 与 src/catalog/tests/generator.test.ts 断言了它作为内置 active 技能的存在。

二、使用时机与输入

根据技能卡，以下场景应当启用 ai-slop-cleaner：

• 现有可运行代码膨胀（bloated）、嘈杂（noisy）、重复（repetitive）、过度抽象（over-abstracted）或明显是 AI 生成的；
• 用户明确请求 cleanup / refactor / deslop；
• 某个后续任务遗留了重复代码或死代码、薄弱边界、缺失测试、fallback 式路径、包装层（wrappers）。

输入定义为：被请求的功能/文件，以及需要保留的行为（behavior to preserve）。文件列表形式的范围是合法的，且清理 Pass 必须严格限定在该范围内，不得越界扩大。

技能卡特别给出了一条 Ralph 工作流内的约束：在 Ralph 工作流中，只对 Ralph 改动过的文件运行本技能，默认使用标准模式（standard mode），除非显式请求其他模式。这一点在源码 src/cli/ralph.ts 中体现为 changed-files.txt 种子内容——它要求“每行一个 repo 相对路径”，并强调“Step 7.5 必须将 ai-slop-cleaner 严格限定在本文件列出的路径内”。

三、编辑前五步纪律：先锁行为，再谈清理

技能卡在“Before editing”一节给出了 5 条硬性前置步骤，这是整个去味流程的安全底线：

1. 先用回归测试锁定行为：识别需要保留的行为，运行或添加最窄（narrowest）的定向测试，并且主路径与保留的兼容性/故障安全 fallback 路径都要覆盖。
2. 在写代码前先创建清理计划：列出范围与 Smell，纳入 fallback 发现/分类/升级信息，把最安全、信号最强（highest-signal）的修复排在前面。
3. 盘点范围内的 fallback 式代码：快速 hack、临时 workaround、临时 fallback、just bypass、just skip、失败即 fallback、吞掉的错误（swallowed errors）、静默默认值、宽泛兼容垫片（compatibility shims）、重复的替代执行路径等。
4. 对每个 fallback 分类：
   • Masking fallback slop（掩盖型）：隐藏证据、绕过契约、压制校验、吞掉失败、静默默认值，或添加未经测试的路径；
   • Grounded compatibility/fail-safe fallback（有据可依的兼容/故障安全型）：窄小地存在于外部/版本/故障安全边界，记录了设计理由，保留失败证据，并且主路径与 fallback 都被测试覆盖。
5. 处置倾向：优先根因修复、删除、边界修复或显式失败行为。对于宽泛/模糊/跨层/架构性发现，调用 $ralplan 进行共识裁决；若已经在 ralplan、ralph、team 或其他 OMX 工作流内部，则不得再嵌套发起 $ralplan，而是把该发现挂接到当前活动的 handoff 上。

这条“先写计划、先加测试”的纪律同时是 templates/AGENTS.md 中工作协议的一部分：“对于 cleanup/refactor/deslop 工作，在覆盖缺失时，先写清理计划并用回归测试锁定行为再编辑”，并且“优先删除、复用已有工具与既有模式，只有在显式要求时才新增依赖”，最终“用 lint、typecheck、测试与静态分析验证，最终报告包含改动文件、简化项与剩余风险”。

四、Smell 分类法：七类“AI 味”的判别清单

技能卡要求先分类再动手。完整的七类 Smell 如下：

类别	具体信号
Fallback 式代码	掩盖型 fallback、workaround 分支、绕过（bypasses）、吞掉的错误、静默默认值、宽泛垫片、替代路径
重复（Duplication）	重复逻辑、复制粘贴分支、冗余辅助函数
死代码（Dead code）	未使用/不可达代码、过时标志位、调试残留
无谓抽象（Needless abstraction）	透传包装器、投机式间接层、单次使用的分层
边界违规（Boundary violations）	隐藏耦合、职责外泄、错误的跨层导入/副作用
缺失测试（Missing tests）	行为未被锁定、边界用例未被覆盖
UI/设计 Slop	上下文敏感的信号而非绝对禁令

其中 UI/design slop 需要特别注意：技能卡明确这是上下文敏感的信号，不是绝对禁止——必须保留有意的品牌（brand）、设计系统（design-system）、可访问性（accessibility）或产品语境下的例外。需要挑战的具体信号包括：

• 韩语正文使用 11–12px 字号（一般应 14px 或更大）；
• 无理由的盒阴影（gratuitous box shadows）；
• 重复的 eyebrow + 标题 + 描述 + 正文堆叠，以及通用 emoji 徽章；
• 默认 AI 蓝/紫色，如 #3B82F6；
• 反射式的三列或四列栅格；
• 除非有语境支撑，否则拒绝极端渐变（extreme gradients）。

这一分类法的设计意图是：让清理动作有据可依、可被审计，而不是凭“我不喜欢这段代码”的观感行事。

五、清理顺序：先过 fallback 解析门，再逐类执行四轮 Pass

技能卡规定的执行顺序是：先解决 fallback 式代码解析门（fallback-like code resolution gate），然后一次只处理一种 Smell：

• Pass 1：删除死代码（Dead code deletion）；
• Pass 2：去除重复（Duplicate removal）；
• Pass 3：命名/错误处理清理（Naming/error handling cleanup）；
• Pass 4：测试加固（Test reinforcement）。

每一轮 Pass 结束后都要重新运行定向验证，并避免无关重构。整体倾向是：优先删除与复用既有工具，不新增抽象、不新增依赖，除非显式要求——这与 AGENTS.md 的 anti-slop 工作流（templates/AGENTS.md）完全一致：“一次只做一个聚焦 Smell 的 Pass；优先删除而非新增，优先复用与边界修复而非新增层次；未经明确请求不新增依赖；声称完成前必须跑 lint、typecheck、测试与静态分析”。

六、证据/输出契约：AI SLOP CLEANUP REPORT

技能卡要求最终必须输出标准化的清理报告，格式如下（可直接复制使用）：

AI SLOP CLEANUP REPORT
Scope: [files/feature]
Behavior Lock: [targeted tests added/run]
Cleanup Plan: [bounded smells/order]
Fallback Findings: [finding -> masking fallback slop | grounded compatibility/fail-safe fallback -> escalation]
UI/Design Findings: [none/N/A or signal -> action/defer -> intentional rationale]
Passes Completed: [resolution gate; Passes 1-4]
Quality Gates: Regression tests, Lint, Typecheck, Tests, Static/security scan (PASS/FAIL/N/A)
Changed Files: [path -> simplification]
Remaining Risks: [none or deferred item]

报告必须包含：改动文件、简化项、fallback 分类与升级状态、运行过的测试/诊断/构建检查、相关时的 UI 发现，以及延期的风险。同时要求保持 writer/reviewer 分离：清理计划的制定与批准不能由同一方完成，这一点同样被 templates/AGENTS.md 的工作协议强调（“保持清理计划与批准的 writer/reviewer 通道分离”）。

七、退出条件：何时才算清理完成

技能卡定义了明确的停止条件，防止“清理本身变成无底洞”：

• 请求范围内已具备行为锁定证据（behavior-lock evidence）；
• 每个被选中的 Smell Pass 要么完成，要么带理由显式延期；
• 验证结果已报告；
• 没有遗留无关文件或临时工件。

两条红线必须遵守：绝不把未经验证的清理宣称完成；遇到真正的架构性阻塞时，要升级问题而非掩盖问题。

八、与 OmX 生态的集成：Ralph 强制清理关与 Ultragoal 严格门禁

ai-slop-cleaner 不只是孤立技能，它被深度接入了 OmX 的两条关键工作流，这从源码中可以清晰看到：

8.1 Ralph 持久化模式的“强制最终清理 Pass”

在 src/cli/ralph.ts 中：

• buildRalphChangedFilesSeedContents() 生成 .omx/ralph/changed-files.txt 种子，要求“每行一个 repo 相对路径”，并把 ai-slop-cleaner 严格限定在这些路径内（Step 7.5）；
• buildRalphAppendInstructions() 在最终 deslop 指导中写入：Step 7.5 必须在改动文件上以标准模式运行 oh-my-codex:ai-slop-cleaner，且不得扩大到整个代码库或无关文件；Step 7.6 必须在 ai-slop-cleaner 之后重跑当前测试/构建/lint 验证，若回归则回滚清理改动或修复后重试；
• CLI 提供了 --no-deslop 退出开关（src/cli/ralph.ts），运行时 noDeslop 会被消费并记录到模式状态 deslop_enabled / deslop_opt_out / deslop_changed_files_path / deslop_scope: 'changed-files-only'（src/cli/ralph.ts）；
• 对应测试 src/cli/tests/ralph.test.ts 验证了 --no-deslop 不会被转发给 codex、默认会注入 ai-slop-cleaner 指导、以及 --no-deslop 时改而引用“最近一次成功的 deslop 前验证证据”。

8.2 Ultragoal 严格完成门禁的 fail-closed 队列

在 src/cli/ultragoal.ts 中，Ultragoal 的帮助文本说明：普通完成只需定向验证（advisory review），但 --strict 会保留 fail-closed 的队列门禁（cohort gate），其成员正是 ai-slop-cleaner、verification、code-review（带 independentReview）、architecture-invariant gate，并通过 --quality-gate-json 输出。非干净（non-clean）的最终审查必须先 record-review-blockers 再调用 update_goal。也就是说，在严格模式下，ai-slop-cleaner 的通过是目标完成的前置条件之一。

九、实操要点速览

综合技能卡、AGENTS.md 与源码实现，一次合格的 ai-slop-cleaner 调用应当做到：

1. 明确输入范围：给出功能/文件清单与“要保留的行为”；Ralph 场景只覆盖 .omx/ralph/changed-files.txt 中的路径。
2. 先写计划再动手：范围 + Smell 清单 + fallback 发现/分类/升级 + 最安全最高信号优先的排序。
3. 盘点并分类所有 fallback：区分“掩盖型 slop”与“有据可依的兼容/故障安全 fallback”，前者修复、后者保留并测试。
4. 按序执行四轮 Pass：死代码 → 重复 → 命名/错误处理 → 测试加固；每轮后重跑定向验证，不做无关重构。
5. 输出标准报告：按 AI SLOP CLEANUP REPORT 模板逐项填写，保持 writer/reviewer 分离。
6. 核对退出条件：行为锁定证据齐全、Pass 完成或带理由延期、验证已报告、无遗留工件，然后才可宣布完成。

十、总结

ai-slop-cleaner 把“清理 AI 生成代码”从凭感觉的随手重构，变成了一条可审计、可复现、有边界的工程流程：用回归测试锁定行为，用七类 Smell 分类法把模糊的“AI 味”拆解为可操作的信号，用四轮 Pass 保证清理有序推进，用标准报告契约保证改动可追溯，用退出条件防止清理失控。在 OmX 体系中，它既是开发者可随时手动调用的 $ai-slop-cleaner 快捷技能，也是 Ralph 模式收尾阶段与 Ultragoal 严格完成门禁中强制执行的“质量最后一道闸”，是理解 OmX 如何约束 AI 协作产出的关键一环。