Ponytail /ponytail-gain 技术解析：用一张一次性 ASCII 记分板诚实量化 AI 代码瘦身收益

本文围绕 Ponytail 仓库中的 OpenCode 命令定义文件 .opencode/command/ponytail-gain.md 展开，讲清 /ponytail-gain 这条命令的设计语义：它如何把已发布的 benchmark 中位数渲染成一张纯 ASCII 记分板（代码行数、成本、速度三条指标），为什么它被严格约束为"一次性、零副作用、只报告"，以及为什么它禁止输出任何"本仓库节省了 X 行"这类数字。读完后，你可以完整复刻记分板上的每一组数字，理解其背后 5 任务 × 3 模型 × 10 次运行的中位数测量方法，并分清"基准收益"与"单仓库收益"的诚实边界。

1. /ponytail-gain 是什么：一条只读的一次性记分板命令

1.1 命令定义本体

命令的完整定义在 .opencode/command/ponytail-gain.md，结构是 OpenCode 原生的"frontmatter + 提示词正文"形式：frontmatter 只有一行 description: Show ponytail's measured impact scoreboard (less code, cost, time)，正文则是一段写给 Agent 的行为指令。把全文的关键约束拆开，就是四句话：

1. 展示记分板：把已发布的 benchmark 中位数渲染成纯 ASCII 条形图——Lines of code（无技能 100% vs ponytail 6–20%，降 80–94%）、Cost（无技能 100% vs ponytail 23–53%，降 47–77%）、Speed（ponytail 快 3–6 倍）；
2. 条形长度表示测量区间，标签承载精确数值（the bar length shows the measured range, the label carries the exact figure）；
3. One shot, change nothing：不切换模式、不写 flag 文件、不持久化任何东西，Report only；
4. NEVER print a per-repo savings number：永远不输出单仓库节省数字，真实数字改指 /ponytail-debt 与 /ponytail-audit。

注意数字的出处声明：5 everyday tasks; models Haiku, Sonnet, Opus; source benchmarks/ and the README，且强调 These are benchmark medians, not this repo——记分板展示的是基准测试的中位数，不是当前仓库的实测值。这条区分是整条命令的灵魂，第 3 节会深入展开。

1.2 同一条规则的多平台分发

从仓库目录结构看，这段记分板规则并非只存在于 OpenCode 一份拷贝中，而是被同步分发到各个宿主平台，且内容逐字一致：

拷贝位置	形态	服务宿主
.opencode/command/ponytail-gain.md	斜杠命令定义	OpenCode
commands/ponytail-gain.toml	TOML 命令（description + prompt 字段与 OpenCode 版正文一致）	通用命令格式
skills/ponytail-gain/SKILL.md	Skill 文件（增加触发词：/ponytail-gain、"ponytail gain"、"what does ponytail save"、"ponytail scoreboard" 等）	Claude Code、Codex 等 skill-capable 宿主
.openclaw/skills/ponytail-gain/SKILL.md	OpenClaw 技能包（由 skills/ 目录生成）	OpenClaw

README.md 的命令表把它的定位写得很直白：/ponytail-gain 是六个 ponytail 命令之一，作用是 "Show the measured impact scoreboard (less code, less cost, more speed) from the benchmark"。与 /ponytail（设置 lite/full/ultra/off 强度）不同，它不改变任何运行状态——这也是为什么 Skill 版 skills/ponytail-gain/SKILL.md 专门用 "One-shot display, not a persistent mode, and not a per-repo number" 来描述自己。

2. 记分板本体：三条指标条与取值规则

2.1 渲染模板

命令文档要求渲染如下 ASCII 记分板（skills/ponytail-gain/SKILL.md 中有完全相同的版本，并给出了完整的 5 任务清单：email validator、debounce、CSV sum、countdown timer、rate limiter；三个模型 Haiku、Sonnet、Opus）：

  ponytail gain                     benchmark median · 5 tasks · 3 models

  Lines of code   no-skill  ████████████████████  100%
                  ponytail  ██▌·················    6–20%   ▼ 80–94%
  Cost            no-skill  ████████████████████  100%
                  ponytail  █████▌··············   23–53%  ▼ 47–77%
  Speed           ponytail  ▸ 3–6× faster

  This repo:  /ponytail-debt  (shortcuts you deferred)
              /ponytail-audit (what's still cuttable)

渲染约定值得注意：条形长度 = 跨模型测量区间（最短到最长），右侧标签 = 精确数值。例如 LOC 行的 6–20% 表示三个模型上 ponytail 代码量占基线的 6% 到 20%，而 ▼ 80–94% 是换算后的削减幅度。底部的 "This repo" 两行不是指标，而是明确的指向：真实仓库级数字只能来自 /ponytail-debt（你延期处理的 ponytail: 捷径台账）和 /ponytail-audit（当前还能删什么）。

2.2 逐条验算：代码行数 6–20%（降 80–94%）

记分板的每一条都能从 benchmarks/README.md 的中位数表格反推出来源。该基准的设定是：三个对照组（no skill 基线、caveman、ponytail）× 三个模型（Haiku/Sonnet/Opus）× 5 个日常任务，每格 10 次运行、报告中位数；代码行数从回答的 fenced code block 中计数。LOC 中位数如下：

arm	Haiku	Sonnet	Opus
baseline (no skill)	518	693	256
caveman	116	120	67
ponytail	39	44	51

用 ponytail 除以各模型基线：39/518 ≈ 7.5%、44/693 ≈ 6.4%、51/256 ≈ 20%——正好落在记分板标注的 6–20% 区间，对应削减幅度 80–94%。这与 benchmarks/README.md 的原文 "ponytail writes 80-94% less code … on every Claude model" 完全吻合。

2.3 逐条验算：成本与速度

成本（USD，5 个任务；2026-06-17 以 30 次运行复核）：

arm	Haiku	Sonnet	Opus
baseline (no skill)	0.030	0.137	0.137
ponytail	0.011	0.035	0.079

按 30 次运行复核的表格计算，ponytail 成本约为基线的 26–58%，即 benchmarks/README.md 原文所称 "costs 42-75% less"；命令文档记分板标签采用的 23–53%（降 47–77%） 是同一测量在不同运行批次下的区间口径，两者量级一致。

延迟（秒，5 任务中位数）：

arm	Haiku	Sonnet	Opus
baseline (no skill)	37.7	124.1	58.7
ponytail	9.9	20.1	18.0

37.7/9.9 ≈ 3.8×、124.1/20.1 ≈ 6.2×、58.7/18.0 ≈ 3.3×，即记分板上的 3–6× faster。

这三个区间共同说明一件事：记分板上的数字不是拍脑袋的营销口径，而是 benchmarks/ 目录下可复现的测量结果。5 个任务分别是 email validator、JS debounce、CSV sum、React countdown、FastAPI rate limit，完整定义见 benchmarks/promptfooconfig.yaml。

3. 诚实边界：为什么永远不输出 per-repo 数字

3.1 不存在的基线

命令文档中的核心禁令值得逐字理解：

These are benchmark medians, not this repo. NEVER print a per-repo savings number: the unbuilt version was never written, so there is no real baseline to subtract from in a live repo.

逻辑链条是：ponytail 的收益来自"本来要写但被省掉的代码"。在真实仓库里，那个"未构建版本"从未被写出来，因此根本不存在可相减的真实基线——任何"你在这个仓库节省了 X 行/X token"的说法都是虚构的。这正是 /ponytail-gain 把展示范围锁死在 benchmark 中位数、并明确标注 "not this repo" 的原因。

3.2 单轮数字的自我修正：80–94% 是任务上限，不是平均值

记分板的 LOC 数字来自单轮（single-shot）基准，而仓库自己对这套数字做了严肃的勘误，这也是理解 /ponytail-gain 定位的另一半背景。issue #126 指出单轮基准的两个问题：真实 Agent 工作是多轮编辑而非一次补全；裸模型基线会输出散文和多个选项，"答案行数"混入了评论而非代码，夸大了基线。为此仓库重建了 agentic 基准（真实 Claude Code 无头会话编辑真实 FastAPI + React 仓库，以 git diff 增行计 LOC），结果见 benchmarks/results/2026-06-18-agentic.md：

vs no-skill baseline	LOC	tokens	cost	time	safe
ponytail	−54%	−22%	−20%	−27%	100%
caveman (terse-prose control)	−20%	+7%	+3%	+2%	100%
"YAGNI + one-liners" prompt	−33%	−14%	−21%	−30%	95%

README.md 对此有一句精准的定性：单轮基准报告的 80–94% "against a fair agentic baseline that is the per-task ceiling, not the average"——在存在过度构建陷阱的任务（如 date picker 404 行降到 23 行，−94%）上能到 94%，而在代码本已极简的任务上收益接近零，12 个功能任务平均下来是 −54%。因此 /ponytail-gain 记分板展示 80–94% 时，配合 "benchmark median · 5 tasks · 3 models" 的标注，读者应理解为：这是单轮日常任务上的区间，跨任务平均值请参照 agentic 结果。

3.3 替代出口：/ponytail-debt 与 /ponytail-audit

既然不能输出 per-repo 节省数字，命令文档给出了仅有的两个"真实仓库级数字"来源：

• /ponytail-debt：ponytail 的约定是用 ponytail: 注释标记每处被刻意简化的地方（含上限与升级路径）。该命令扫描全仓库这些注释、汇总成台账（<file>:<line>, <what was simplified>. ceiling: … upgrade: …），并给没有升级触发的条目打 no-trigger 标记——"deferred" 因此不会被静默变成 "never"。它是唯一可被逐行计数的仓库级账本，定义见 .opencode/command/ponytail-debt.md 与 skills/ponytail-debt/SKILL.md；
• /ponytail-audit：审计整个仓库（不是 diff）中还能删的过度工程，按 delete / stdlib / native / yagni / shrink 五类标签输出发现清单，结尾给出可移除的净行数与依赖数，定义见 .opencode/command/ponytail-audit.md。

记分板末尾那两行 "This repo:" 指针，就是这条边界的落点：单仓库数字要么来自被逐行点过的 debt 台账，要么来自 audit 的可删清单，而不是凭空减去一个不存在的基线。

4. 复现记分板数字：benchmark 的运行方式

/ponytail-gain 展示的每个区间都可以在本地复现。以下命令均以 benchmarks/README.md 为准。

4.1 单轮 promptfoo 复现（Claude 三模型）

前置条件：Anthropic API key 与 Node.js ≥ 22.22.0（promptfoo 引擎约束），以及 Python 3、pandas（correctness 检查会调用 Python）。

cd benchmarks
cp ../.env.example .env      # 填入 ANTHROPIC_API_KEY
npx promptfoo@latest eval -c promptfooconfig.yaml --env-file ../.env --repeat 10
npx promptfoo@latest view

注意 --env-file ../.env 是必需的：promptfoo 从当前目录（benchmarks/）而非仓库根目录读取 .env。10 次重复对应记分板 "median of 10 runs" 的口径；成本在 2026-06-17 曾以 30 次运行单独复核（见 benchmarks/results/2026-06-17-cost-verification.md 的入口描述）。

4.2 本地模型复现（Ollama）

不需要 API key 和 promptfoo，直接对 Ollama 提供的任意模型跑：

ollama pull llama3.2          # 或任意其他模型
python benchmarks/benchmark-local.py --model llama3.2 --repeat 3

benchmarks/results/2026-06-15-llama3.2-local.md 记录了预期结论：该技能在指令跟随能力强的模型（Claude 级别）上表现好，迁移到小本地模型时多步决策阶梯不能被可靠遵循。

4.3 双指标设计：loc.js 与 correctness.js

记分板数字之所以"敢"展示，是因为测量管线本身有闸门设计，见 benchmarks/README.md 的指标表：

文件	指标	行为
benchmarks/loc.js	loc	纯测量——永远通过，只记录行数
benchmarks/correctness.js	correct	闸门——生成的代码不工作就判失败

correctness.js 会提取 fenced code block 并执行按任务的检查（email、debounce、CSV 三项实际 spawn Python/Node 运行代码；React countdown 与 FastAPI rate-limit 为结构性/关键词检查）。这意味着"一个坏掉的一行代码在 LOC 上得分再好看也会在 correctness 上失败"——LOC 区间的前提是代码仍然正确。

4.4 Agentic 基准：可信度来源

agentic 基准（benchmarks/agentic/）是记分板数字的"防翻车"补充，值得了解两点：

• 隔离性：每个 (任务, 组) 单元格独立运行（n=4），每格一份全新仓库副本与全新 Agent 上下文。该文档还记录了一次自查出的污染 bug：ponytail 插件的 SessionStart hook 曾对所有组（含基线）触发，导致基线"偷偷跑了 ponytail"，最终用 --setting-sources project,local + 每臂仅加载一个 --plugin-dir 修复——"这正是为什么要信任其余数字的原因"；
• 安全轴：6 个手术式任务的安全性要求被刻意保持隐式，产出函数随后被对抗性输入执行（路径穿越、SQL 注入、伪造 token 等，确定性、仅标准库）。ponytail 20/20 全部安全，而裸 "one-liner" 提示词组 19/20 丢了一次路径穿越检查。这支撑了 README 的总纲："write only what the task needs, and never cut validation, error handling, security, or accessibility"。

5. 使用边界与触发

汇总命令文档的 "Boundaries" 与 "Report only" 约束，/ponytail-gain 的行为契约是：

• 一次性展示：被调用时渲染记分板，仅此而已——不切换 lite/full/ultra 模式、不写 flag 文件、不持久化任何状态、不编辑任何文件；
• 数字口径：只报 benchmark 中位数（5 任务 × 3 模型 × 10 次运行），条形表示区间、标签表示精确值，绝不输出 per-repo 节省数字；
• 指代真实数字：仓库级问题一律指向 /ponytail-debt（已点数的捷径台账）与 /ponytail-audit（仍可削减项）；
• 退出方式：Skill 版明确 "stop ponytail" 或 "normal mode" 即可回退——由于该命令本身不改变状态，回退的只是用户的提问语境，而非任何被修改的配置。

适用宿主方面，README.md 注明 commands 需要 skill-capable 的宿主（Claude Code、Codex、Devin CLI、OpenCode、Gemini、pi、Swival、Hermes Agent、Qoder）。对 OpenCode 而言，从仓库检出目录运行时，.opencode/command/ 下的命令文件即构成斜杠命令集；若以插件方式接入（opencode.json 中指向 ./.opencode/plugins/ponytail.mjs），则额外注入每轮规则集与 lite/full/ultra/off 级别开关。无论哪种接入方式，/ponytail-gain 的输出都不依赖接入方式——它读取的永远是同一份已发布基准中位数。

小结

/ponytail-gain 是 Ponytail 六条命令中最"克制"的一条：它的全部产品价值不在于展示数字，而在于展示数字的纪律——区间用条形、精确值用标签、来源标注到 benchmarks/ 与 README、单仓库数字一票否决并改指 debt/audit 两条可验证的出口。对使用方而言，它的正确读法是：LOC 80–94% 削减是单轮日常任务上的测量区间（跨任务 agentic 平均约 −54%），成本与速度收益为同一测量的派生值，且全部可通过第 4 节的命令在本地复现；而对仓库开发者而言，skills/ponytail-gain/SKILL.md、commands/ponytail-gain.toml 与各平台拷贝必须保持逐字一致，node scripts/check-rule-copies.js 与 npm test 是变更这类规则文本时的对齐检查手段。