ponytail-gain：用 benchmark 中位数给 AI 代码精简量化的记分板技能解析

本篇以 ponytail 仓库中 OpenClaw 技能变体 .openclaw/skills/ponytail-gain/SKILL.md 为主体，逐条拆解这个“一次性记分板”技能的渲染规范、数据来源与诚实性边界；读完后你将理解 /ponytail-gain 输出的每一组数字（代码量 6–20%、成本 23–53%、速度 3–6×）是如何由 benchmarks/ 目录下的三组模型 × 五项日常任务 × 每格 10 次运行的中位数得到的，以及为什么该技能被明令禁止输出“你在这个仓库省了多少行”这类无基线的数字。

1. 技能定位：一次性展示，而非持久化模式

ponytail 是一个让 AI Agent 以“最懒资深工程师”心态写代码的技能集——最好的代码是你根本没写出来的代码。它的六个捆绑技能（/ponytail、/ponytail-review、/ponytail-audit、/ponytail-debt、/ponytail-gain、/ponytail-help）分别负责强度控制、diff 审查、全仓库审计、技术债台账、收益记分板和帮助。其中 ponytail-gain 是唯一一个纯展示类技能。

技能定义文件的 frontmatter 声明了身份：

name: ponytail-gain
description: "Show ponytail measured impact as a scoreboard: less code, less cost, more speed, from the benchmark medians. One-shot display."
license: MIT

文档正文（.openclaw/skills/ponytail-gain/SKILL.md）第一段就给出三条硬约束：

1. 一次性（One-shot）：被调用时展示记分板即可，不得切换模式、不得写 flag 文件、不得持久化任何状态；
2. 数据来源固定：所有数字是“已发布的 benchmark 中位数”（5 个日常任务 × 3 个模型），是在 benchmarks/ 中实测的，而不是从当前仓库计算出来的；
3. 明确指向数据源：Source 声明为 benchmarks/ 目录和 README。

值得注意的一个细节：.openclaw/skills/ 下这份文件是 OpenClaw 平台的技能分发变体。从仓库脚本看，scripts/build-openclaw-skills.js 中内置了 ponytail-gain 的描述文案（“Show ponytail measured impact as a scoreboard: less code, less cost, more speed, from the benchmark medians. One-shot display.”），与源技能 skills/ponytail-gain/SKILL.md 同源同构，仅 frontmatter 因平台要求多带了 homepage 与 license 字段。也就是说，同一套行为契约在不同 Agent 宿主（OpenClaw、Hermes、pi 等）上保持一致。

2. 记分板渲染规范：条形图表示区间，标签承载精确值

文档的 “Scoreboard” 一节规定：用纯 ASCII 条形渲染，条形长度表示实测范围（range），标签（label）承载精确数字。这是该技能最值得学习的设计——它用视觉长度传达“这是区间不是点值”，用文本标签保留精度，两者互不替代。

完整记分板如下（原文档中的渲染模板，可直接复现）：

  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)

三个维度逐条解读：

维度	no-skill 基线	ponytail	解读
代码行数	100%	6–20%（▼ 80–94%）	ponytail 输出的代码量仅为无技能基线的 6%–20%，三个模型间跨度即条形长度
成本	100%	23–53%（▼ 47–77%）	API 成本（含 token 与延迟）相对基线下降约一半以上
速度	—	3–6× faster	延迟维度，无 no-skill 对比条，仅标注倍率

记分板尾部的两行不是装饰，而是技能内建的“出口路由”：把读者从“benchmark 数字”引导到“当前仓库可操作的数字”——/ponytail-debt 查你主动推迟的捷径台账，/ponytail-audit 查仓库里还能删什么。这个设计呼应了下一节的诚实性边界：既然不能在本仓库报数，就把读者指向真正能报数的工具。

2.1 斜杠命令侧的同一契约

技能文件不是唯一入口。commands/ponytail-gain.toml 把同一套指令压缩成一段 prompt，供不支持 Skill 系统的宿主使用：

description = "Show ponytail's measured impact scoreboard (less code, cost, time)"
prompt = "Show the ponytail gain scoreboard. One shot, change nothing: do not switch mode, write flag files, or persist anything. Render the published benchmark medians (5 everyday tasks; models Haiku, Sonnet, Opus; source benchmarks/ and the README) as plain ASCII bars: Lines of code, no-skill 100% vs ponytail 6-20% (down 80-94%); Cost, no-skill 100% vs ponytail 23-53% (down 47-77%); Speed, ponytail 3-6x faster. The bar length shows the measured range, the label carries the exact figure. 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. For real per-repo figures, point to /ponytail-debt (the counted shortcut ledger) and /ponytail-audit (what is still cuttable). Report only."

可以看到 toml 与 SKILL.md 在数字、边界约束上完全一致——包括“NEVER print a per-repo savings number”这条红线。plugin.yaml 则把 ponytail-gain 注册进插件的技能清单，使技能在各宿主中可被发现。在 pi Agent 上，该命令由 pi-extension/index.js 注册为 /ponytail-gain 并转发到 /skill:ponytail-gain；在 Hermes 上，after-install.md 列出它是可用斜杠命令之一，且捆绑技能以 ponytail:ponytail-gain 命名空间暴露。跨平台行为一致性由 docs/agent-portability.md 明确描述：“skills/ponytail-gain/SKILL.md: measured-impact scoreboard from the benchmark”。

3. 数字从哪来：benchmark 方法论与中位数

记分板的每一个区间都能回溯到 benchmarks/README.md 的实测数据。其实验设计是：三个对照组（no-skill 基线、caveman 技能、ponytail 技能）× 三个模型（Claude Haiku、Sonnet、Opus）× 五个日常任务（邮件校验、JS debounce、CSV 求和、React 倒计时、FastAPI 限流），每格 10 次运行，报告中位数。

3.1 五项任务与两个度量

度量由两个独立文件实现，分工是“记录”与“把关”：

文件	度量名	性质
benchmarks/loc.js	loc	纯测量——永远通过，只记录代码行数
benchmarks/correctness.js	correct	质量门——生成的代码跑不起来就判失败

loc.js 的计数逻辑值得细看：它先正则提取 fenced code block（模型只输出裸代码时退化为整段响应），剔除 /* ... */ 块注释（早期版本只过滤了 JSDoc 星号行，普通块注释会被误计为代码），然后统计非空、非 //、非 # 开头的行。这就是记分板里“Lines of code”一行的定义——有效代码行，不含注释与空行。correctness.js 则从 fenced 块中提取代码并按任务执行检查（邮件、debounce、CSV 三项真的 spawn Python/Node 跑起来；React 与 FastAPI 两项因运行时依赖仅做结构/关键词校验，README 中对此有明确声明）。这个门的存在保证了“LOC 极低但代码是坏的”不能刷分。

3.2 中位数结果（10 runs，2026-06-13）

代码行数（LOC）：

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

成本（USD，5 任务合计；30 runs 复核，2026-06-17）：

arm	Haiku	Sonnet	Opus
baseline (no skill)	0.030	0.137	0.137
caveman	0.014	0.046	0.072
ponytail	0.011	0.035	0.079

延迟（秒，5 任务）：

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

用表格数字反向验证记分板区间：LOC 维度 ponytail 占基线比例分别为 39/518≈7.5%、44/693≈6.3%、51/256=20%——正是记分板的“6–20%”与“▼ 80–94%”；延迟维度 37.7/9.9≈3.8×、124.1/20.1≈6.2×、58.7/18.0≈3.3×——正是“3–6× faster”。成本维度 README 在 30 次复核后给出的结论是“42–75% 更低”，而记分板标注的是 10 次运行中位数对应的“23–53%（▼ 47–77%）”——两者口径不同，文章引用时应按各自来源表述。

3.3 如何复现（适用前提与限制）

benchmarks/README.md 给出两条复现路径：

1. Claude API 路径：需要 Anthropic API key 与 Node.js ≥ 22.22.0（promptfoo 引擎约束）：

   cp ../.env.example .env      # add your 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，而文件在仓库根目录。

2. 本地模型路径（Ollama）：无需 API key 与 promptfoo：

   ollama pull llama3.2          # or any other model
   python benchmarks/benchmark-local.py --model llama3.2 --repeat 3
   

   注意 benchmarks/results/2026-06-15-llama3.2-local.md 的结论：该技能在指令跟随能力强的模型（Claude 级别）上表现良好，但迁移到小型本地模型时，多步决策梯子不能稳定被遵循，收益显著缩水。

前提条件：Python 3、pandas、Node.js ≥ 22.22.0。

3.4 README 的诚实性修正：agentic 基准

记分板呈现的是 single-shot（一问一答）口径，而 README 在“Read this number honestly”一节主动承认了这一局限：对照的是直接回答案几套方案加一大段散文的裸模型，所以差距里把散文也计入了，会夸大收益。仓库给出的更诚实口径在 benchmarks/agentic/：把对比放到真实 Claude Code 会话 + 真实公开仓库上重跑，ponytail 在“有过度构建陷阱”的特性任务上削减 60–94%，在已经极简的代码上打平，从不写更多，且安全性保持 100%（对照的裸“one-liner”提示词漏掉了一个 guard）。详见 benchmarks/results/2026-06-18-agentic.md。引用 ponytail 收益数字时，应同时说明这是 single-shot 中位数，并知晓 agentic 口径的存在。

4. 诚实性边界：为什么禁止报“本仓库省了多少”

文档的 “Honesty boundary” 一节是整个技能中最有原则性的部分，其论证链值得完整保留：

1. 记分板数字是 benchmark 中位数，不是当前仓库的数字；
2. 永远不要输出逐仓库的节省数字（“you saved X lines/tokens here”）；
3. 原因：没被写出来的版本从未存在过——在真实仓库里没有可减去的真实基线，减法不成立；
4. 唯一真实的逐仓库数字来自 /ponytail-debt，它是一个被计数的台账（counted ledger）；记分板因此只做指向，不自己发明数字。

第 4 条在 ponytail 的设计里是自洽的：skills/ponytail-debt/SKILL.md 定义了 ponytail: 注释约定——每个被 ponytail 有意留下的捷径都带一条注明“上限（ceiling）”和“升级路径（upgrade path）”的注释，debt 技能通过 grep -rnE '(#|//) ?ponytail:' . 扫描这些标记，按文件分组输出台账，结尾给出 <N> markers, <M> with no trigger 的计数。台账里每一行都是真实存在的行号与注释，所以它是合法的逐仓库数字来源；而“省了多少”这类反事实数字则没有这种落地物。记分板尾部的两行路由（/ponytail-debt 与 /ponytail-audit）正是这条原则在 UI 层的体现：与其自己造数，不如把读者送去做真计数。

对照 skills/ponytail-audit/SKILL.md：audit 是 ponytail-review 的全仓库版，产出 delete: / stdlib: / native: / yagni: / shrink: 五类标签的排序清单，同样 one-shot、只列不改。两个被指向的技能一个负责“已推迟的捷径”，一个负责“仍可裁剪的冗余”，与 gain 的“历史实测收益”三者拼出完整的度量三角。

5. 行为边界与退出语义

“Boundaries” 一节只有两行，但把运行契约钉死了：

• One-shot display. Edits nothing, changes no mode.——只读展示，不修改文件、不改变 /ponytail 的强度档位（lite/full/ultra/off）；
• "stop ponytail" or "normal mode": revert.——用户说出这两个短语即恢复默认，这是 ponytail 各技能共享的退出词。

把这两条与第 1 节的 frontmatter 约束合起来看，ponytail-gain 的运行画像完全无副作用：无写操作、无状态变更、无模式切换。这类“展示型技能”之所以可以如此轻约束，正因为它的数据源（benchmark 中位数）是静态发布的，展示端不需要任何实时计算。

6. 小结：如何正确地引用 ponytail 的收益数字

结合技能文档与 benchmarks/ 的实现，引用 /ponytail-gain 数字时应遵守四条规则：

1. 口径先行：数字是 single-shot 基准的中位数（10 runs/cell，2026-06-13），成本经 30 runs 复核（2026-06-17），成本复核细节见 benchmarks/results/2026-06-17-cost-verification.md；
2. 区间而非点值：6–20% / 23–53% / 3–6× 是跨三个模型的范围，条形长度就是区间本身；
3. 不分仓库报数：逐仓库的节省是反事实数字，无基线可减；真实可报的逐仓库数字只有 /ponytail-debt 台账；
4. 知晓更强口径：真实会话场景参考 agentic 基准（60–94% 削减、100% 安全），它比 single-shot 数字更保守也更可辩护。

ponytail-gain 本身只有几十行，但它把“怎么诚实地展示一个工具的收益”做成了可执行的规范：数据来源固定、渲染格式固定、红线（不报逐仓库数字）写进 prompt、出口（指向 debt 与 audit）内建到记分板尾部。对任何想给 AI 技能加“效果面板”的项目，这都是一个可以直接参照的最小实现。