Ponytail 的 /ponytail-audit：面向整个仓库的过度工程审计命令设计与实现

/ponytail-audit 是 Ponytail 在 OpenCode 中注册的一个斜杠命令，用于对整个代码仓库做一次"只看过度工程、不看正确性"的全量扫描，输出按收益排名的删减清单。本文以 ponytail-audit 命令定义 为主体，完整拆解该命令的提示词契约、五种发现标签（tag）分类体系与输出格式，并结合仓库源码说明 OpenCode 插件如何解析、注册这条命令，以及它如何与 Claude Code、Codex、Gemini CLI 等宿主保持同一份提示词。

一、命令定位：扫全树，而不是扫 diff

Ponytail 的命令族围绕"让 AI agent 像最懒的资深工程师一样写最少的代码"这一核心目标组织。在这个命令族里，/ponytail-audit 的职责边界非常明确：审计整个仓库的过度工程问题（over-engineering only, not correctness）。

根据 README.md 的命令表，Ponytail 提供六个斜杠命令：/ponytail（切换强度档位 lite/full/ultra/off）、/ponytail-review（审查当前 diff）、/ponytail-audit（审计整个仓库）、/ponytail-debt（收割被 ponytail: 注释标记的推迟项）、/ponytail-gain（展示基准测试结果）和 /ponytail-help（速查表）。其中 review 与 audit 是一对姊妹命令：

• /ponytail-review：只审查**当前代码变更（diff）**中的过度工程；
• /ponytail-audit：扫描整棵目录树（the whole tree, not a diff），回答"这个仓库里到底有什么可以删掉"。

skills/ponytail-audit/SKILL.md 的 frontmatter 对此有一句精炼的定位："ponytail-review, repo-wide. Scan the whole tree instead of a diff. Rank findings biggest cut first."（ponytail-review 的仓库全量版，扫描整棵树而非 diff，发现项按删减幅度从大到小排序）。

二、命令的完整定义：frontmatter + 一段提示词

OpenCode 的命令以 Markdown 文件形式存放在 .opencode/command/ 目录下，文件名去掉 .md 后缀即为命令名。.opencode/command/ponytail-audit.md 的完整内容只有两部分：

---
description: Audit the whole repo for over-engineering, what can be deleted
---

Audit the entire repository for over-engineering only, not correctness. Scan the whole tree, not a diff. One line per finding, ranked biggest cut first: <tag> <what to cut>. <replacement>. [path]. Tags: delete (dead code/speculative feature), stdlib (reinvented standard library), native (dependency doing what the platform does), yagni (abstraction with one implementation), shrink (same logic, fewer lines). End with the net lines and dependencies removable. If nothing to cut: 'Lean already. Ship.'

按 OpenCode 的命令文件约定，YAML frontmatter 中的 description 字段用于命令菜单展示，正文则作为执行命令时注入的提示词模板。这段正文虽然只有一句话的长度，却是一份约束完整的"输出契约"，下面逐条拆解。

2.1 契约要素逐条解析

（1）范围约束：only, not correctness / the whole tree, not a diff

命令开头两个短语同时锁定了两个维度：审计对象是整棵目录树而非某次变更；审计目标是过度工程而非正确性缺陷。这条边界在 skill 层的 skills/ponytail-audit/SKILL.md 中被进一步显式化为 Boundaries 一节："Correctness bugs, security holes, and performance are explicitly out of scope. Route them to a normal review pass."（正确性 bug、安全漏洞、性能问题明确不在本命令范围内，应交给常规 review 流程处理。）这种"单一职责的审计命令"设计避免了 agent 在一次任务里混杂"修 bug"和"删代码"两种动机。

（2）输出粒度：One line per finding, ranked biggest cut first

每个发现项压缩成一行，且按"能删得最多"的项排在最前面。排序规则让报告的消费顺序天然就是执行顺序——先动收益最大的删减。

（3）单行格式：<tag> <what to cut>. <replacement>. [path]

一行由四要素构成：标签、删减对象、替代方案、路径占位。相比 /ponytail-review 的格式 L<line>: <tag> <what to cut>. <replacement>.（行号定位，见 commands/ponytail-review.toml），全仓库审计以 [path] 文件路径定位替代行号——全树扫描的输出粒度本来就是文件/模块级，行号在跨文件视角下意义有限。

（4）标签体系：五种 tag

Tag	含义	判据
delete	死代码 / 投机性功能（speculative feature）	无人调用、无人使用的"预留灵活性"，替代方案就是"什么都不用"
stdlib	手写的标准库功能（reinvented standard library）	标准库自带该功能，发现项中必须点名具体的标准库函数
native	依赖/代码在重复平台已有的能力	平台原生特性已覆盖（如浏览器 <input type="date"> 对日期组件库），必须点名该平台特性
yagni	只有一个实现的抽象	单实现接口、无人设置的配置项、只有一个调用方的分层
shrink	同等逻辑、更少行数	替代写法必须直接展示（"Show the shorter form"）

这份标签表在 skills/ponytail-audit/SKILL.md 的 Tags 一节中有逐项展开，并注明每个标签对"替代方案"的写法要求：stdlib 要给出函数名，native 要给出平台特性名，delete 的替代方案是"nothing"，shrink 要展示更短的写法。标签体系本质上是把"删什么、为什么、换成什么"三件事压进一行可解析的文本里。

（5）收尾指标：net lines and dependencies removable

报告末尾必须给出净删减量："End with the net lines and dependencies removable." 即全部发现项若逐一执行，预计可删除多少行代码、多少个依赖。skill 层把这一行固化为模板：net: -<N> lines, -<M> deps possible.。这个指标让审计结果可以量化比较——它是报告的唯一"记分牌"。

（6）空结果兜底：'Lean already. Ship.'

如果没有任何可删减项，命令要求 agent 输出一句固定短语 "Lean already. Ship." 并结束，而不是编造发现项或输出冗长的免责声明。这一兜底短语与 /ponytail-review 共享（其 skill 定义在 skills/ponytail-review/SKILL.md 中同样规定），保证两个命令在"代码已经很精简"时行为一致。

三、纵深一层：ponytail-audit skill 的"狩猎清单"与边界

.opencode/command/ 下的命令文件是"最小可执行契约"，而完整的操作手册在同名的 skill 中。skills/ponytail-audit/SKILL.md 在命令文件之外补充了三块内容：

（1）Hunt 清单——审计时优先翻找什么

skill 列出了一组高命中率的过度工程特征，等价于一份"检查表"：

• 标准库或平台已经自带的依赖（对应 stdlib / native 标签）；
• 单实现的接口、只有一个产品的工厂、只做转发的包装器、只导出一个东西的文件（对应 yagni）；
• 死掉的标志位与没人设置的配置（对应 delete）；
• 手写的标准库（对应 stdlib）。

这份清单把命令文件中抽象的 tag 落地为具体的代码模式，agent 执行审计时可以直接按单巡查。

（2）与 ponytail-review 的关系

skill 明确声明标签体系 "Same as ponytail-review"，两者共享同一套五标签词汇表。区别仅在扫描范围（整树 vs diff）、定位方式（[path] vs L<line>）和收尾指标（audit 多统计 -<M> deps）。这意味着 Ponytail 用同一套语义模型驱动两个粒度的审计，降低了使用者在两者之间切换的心智成本。

（3）边界与退出机制

skill 的 Boundaries 一节规定了四条纪律：只审计过度工程与复杂度；正确性/安全/性能问题路由到常规 review；"Lists findings, applies nothing"（只列清单、绝不自动应用修改）；一次性报告（one-shot）。退出方式是说 "stop ponytail-audit" 或 "normal mode"。"只报告不落盘"这一点很关键：审计命令产出的是一份待办清单，删代码的动作仍由人类确认后续做。

值得一提的是，skill 层对"什么不能删"有保护条款的延伸：/ponytail-review 明确规定单个冒烟测试或 assert 自检属于"ponytail 最小值而非冗余，永远不要标记为删除"（见 skills/ponytail-review/SKILL.md Boundaries 节）。这与主 skill skills/ponytail/SKILL.md 中"Lazy code without its check is unfinished"（没有检查的懒代码是不完整的）原则一脉相承——审计命令的激进删减是被这些条款约束住的。

四、OpenCode 侧：这条命令是如何被解析和注册的

.opencode/command/*.md 文件本身是静态的，真正让 /ponytail-audit 在 OpenCode 里可用的是仓库内的 OpenCode 服务端插件 .opencode/plugins/ponytail.mjs。

4.1 命令注册流程

插件的 config 钩子在 OpenCode 初始化时执行（.opencode/plugins/ponytail.mjs）：

1. 遍历 .opencode/command/ 目录下所有 .md 文件；
2. 用文件名（去掉 .md）作为命令名——ponytail-audit.md 因此注册为 /ponytail-audit；
3. 调用 parseCommandFile 解析出 frontmatter 的 description 和正文模板，写入 config.command[name]；
4. 同时把 skills/ 目录追加到 config.skills.paths，使 skill 体系对 OpenCode 可见。

注释中说明了这一设计的前提：该插件在"从 npm 安装包安装时"让斜杠命令依然可用——即用户不必手工往 OpenCode 配置里逐个粘贴命令文件。

4.2 frontmatter 解析器的两个工程细节

解析逻辑独立在 .opencode/plugins/ponytail-frontmatter.cjs 中：

const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
if (!match) return null;
const description = match[1].match(/description:\s*(.+)/)?.[1]?.trim();
return { description, template: match[2].trim() };

两个值得注意的点：

• CRLF 容忍：正则中用 \r?\n 匹配分隔线换行，注释解释原因是"Windows checkout（autocrlf）给出 \r\n，npm 发布产物是 \n"——否则在 Windows 上 clone 后命令文件会被解析为 null 而静默失效；
• 解析器单独成模块：模块头部注释说明，OpenCode 的旧版插件加载器会把插件模块导出的每个函数都当作插件调用，当年把 frontmatter 解析器与插件函数放在同一模块时曾抛出 "path must be a string or a file descriptor"。因此把解析器拆到独立 CommonJS 模块，保证 ponytail.mjs 只有唯一一个"插件形态"的顶层导出。

对照 .opencode/command/ponytail-audit.md 的结构可以看到，frontmatter 恰好只用了 description 一个字段，解析器也只提取 description，正文整体作为 template 返回——两者是对齐的最小约定。

五、跨宿主一致性：同一提示词的三份副本与守护测试

/ponytail-audit 的提示词并非 OpenCode 独有。从源码结构看，Ponytail 的命令采用"一份提示词、按宿主格式各出一份文件"的策略：

宿主	文件	格式
OpenCode	.opencode/command/ponytail-audit.md	Markdown + frontmatter
Claude Code / Gemini CLI	commands/ponytail-audit.toml	TOML：description + prompt
pi agent	pi-extension/index.js 中的 registerCommand 别名	转发到 /skill:ponytail-audit

commands/ponytail-audit.toml 的 prompt 字段与 OpenCode 命令正文是同一段文字："Audit the entire repository for over-engineering only, not correctness. Scan the whole tree, not a diff. One line per finding, ranked biggest cut first: ..."——逐字相同，只是载体不同。pi-extension/index.js 中则把 ponytail-audit 注册为指向 ponytail-audit skill 的别名命令，由 skill 文件 skills/ponytail-audit/SKILL.md 提供完整版指令。

为防止多份副本漂移，tests/commands.test.js 用 node:test 写了两条守护测试：从 pi 扩展源码中正则提取全部 registerCommand 注册的命令名，然后断言每个命令名都同时存在 commands/<name>.toml 和 .opencode/command/<name>.md 两份适配文件，缺任何一份测试即失败。测试文件头部注释还记录了这条测试的由来——/ponytail-help 曾只在 README 和 help 卡片里宣传、却漏了两份适配文件，该测试就是为了防住这种"注册了但没适配器"的漂移。

六、使用方法与适用边界

在支持 skill 的宿主中（README 列出 Claude Code、Codex、Devin CLI、OpenCode、Gemini、pi、Swival、Hermes Agent、Qoder 等），安装 Ponytail 后直接输入 /ponytail-audit 即可触发；skill 的 description 中还登记了若干自然语言触发词，如 "audit this codebase"、"what can I delete from this repo"、"find bloat"。在 OpenCode 中，插件注册机制（第四节）保证该命令随 npm 包或本地 checkout 安装自动可用；此外 OpenCode 会自动加载本仓库根部的 AGENTS.md，即使不装插件，主规则集也保持常驻。

使用该命令时需要理解它的前提与限制：

1. 只读、一次性：审计是一次性报告，列出发现但不应用任何修改，适合在动手前拿到全量删减清单；
2. 范围外问题要另走流程：正确性 bug、安全漏洞、性能问题被显式排除，agent 发现后应建议走常规 review，而不是混在删减清单里；
3. 最小检查不被误删：单个冒烟测试/assert 自检在 ponytail 体系中是"最小必需"而非冗余，审计不应将其标记为 delete；
4. 净指标是估算：net: -<N> lines, -<M> deps possible 是"若全部执行"的潜在删减量，实际执行顺序与合并冲突会影响最终数字；
5. 与 /ponytail-review 分工使用：开发中审 diff 用 review，评估存量代码或新接手仓库用 audit，两者的标签体系一致，输出可以直接互相衔接。

七、相关文件索引

文件	作用
.opencode/command/ponytail-audit.md	本文主体：OpenCode 斜杠命令定义（frontmatter + 提示词）
skills/ponytail-audit/SKILL.md	完整 skill：标签细则、Hunt 清单、输出模板、边界与退出机制
commands/ponytail-audit.toml	同一提示词的 Claude Code / Gemini CLI 适配文件
skills/ponytail-review/SKILL.md	姊妹命令 review 的完整定义，含发现项正反示例
.opencode/plugins/ponytail.mjs	OpenCode 插件：遍历并注册 command 目录、注入规则集
.opencode/plugins/ponytail-frontmatter.cjs	命令文件 frontmatter 解析器（CRLF 容忍）
tests/commands.test.js	守护测试：确保每个注册命令都有 toml 与 md 两份适配文件
skills/ponytail/SKILL.md	主规则集：七级"阶梯"、强度档位与安全边界
README.md	命令表、各宿主安装方式与基准测试说明

/ponytail-audit 的设计把"审计过度工程"这件主观性很强的事收敛成了一份机器可读的契约：五种标签定义"删什么"，单行格式定义"怎么报告"，净删减指标定义"值多少"，明确的边界条款定义"不碰什么"。配合跨宿主的同文适配与漂移守护测试，这条命令在 OpenCode、Claude Code、Codex、Gemini CLI 等不同环境中呈现的是同一套审计纪律。