Ponytail `/ponytail-debt` 命令实战：把 `ponytail:` 快捷注释收割成可追踪的债务台账

本篇技术指南以 ponytail 仓库中的 OpenCode 斜杠命令定义 .opencode/command/ponytail-debt.md 为主体，完整拆解 /ponytail-debt 命令的工作机制：它如何用一条 grep 扫描全仓的 ponytail: 注释标记、按统一行格式生成债务台账（debt ledger）、通过 no-trigger 标签识别"静默腐烂"的欠账，并在只读边界内输出统计结论。读完本文，你能理解该命令背后的注释约定（ceiling + upgrade path）、精确掌握扫描正则与输出格式，并能结合仓库源码中的真实标记验证整套机制。

背景：ponytail: 注释约定从哪里来

要理解 /ponytail-debt，必须先理解它收割的对象。ponytail 项目的主技能定义 skills/ponytail/SKILL.md 中有一条明确规则：

Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a ponytail: comment naming the ceiling and upgrade path (# ponytail: global lock, per-account locks if throughput matters).

也就是说，当 AI agent 在"最懒资深工程师"模式下刻意做了带已知天花板的简化（全局锁、O(n²) 扫描、朴素启发式）时，必须留下一条 ponytail: 注释，其中写明两样东西：

• ceiling（天花板）：这个简化在什么极限下会失效；
• upgrade path（升级路径/触发条件）：什么情况下要回来重新审视。

AGENTS.md 中也内嵌了同一条规则，保证该约定在不同 agent 宿主中一致生效。/ponytail-debt 命令的存在意义，正是把这些分散在代码各处的"刻意欠账"集中收割，防止"以后再说"腐烂成"永远不会做"（the command 原文：so deferrals do not rot into 'later means never'）。

命令定义原文解析

.opencode/command/ponytail-debt.md 是 OpenCode 平台的斜杠命令定义，采用 frontmatter + 正文的结构。frontmatter 只声明描述：

description: "Harvest ponytail: comments into a tracked debt ledger"

正文是该命令的完整提示词（prompt），一次性给出全部行为规格，可以逐句拆解为五个动作：

1. 全树扫描：Grep the whole tree for comment markers (grep -rnE '(#|//) ?ponytail:' ., skipping node_modules/.git/build output) —— 使用正则 (#|//) ?ponytail: 递归搜索整棵目录树，跳过 node_modules、.git 与构建产物；
2. 逐标记建账：One row per marker, grouped by file: <file>:<line>, <what was simplified>. ceiling: <the limit named in the comment>. upgrade: <the trigger to revisit>. —— 每个标记一行，按文件分组，行内必须填出"简化了什么、天花板是什么、重新审视的触发条件是什么"；
3. 腐烂标记：Tag any marker that names no upgrade path or trigger as no-trigger, those rot silently. —— 凡是没写升级路径或触发条件的标记，打上 no-trigger 标签，因为这类欠账会静默腐烂；
4. 结尾统计：End with the count of markers and how many lack a trigger. —— 报告以总标记数和缺触发器的数量收尾；
5. 只读边界：Report only, change nothing. —— 只报告，不改动任何文件；若一条标记都没有，则输出 No ponytail: debt. Clean ledger.。

扫描正则的细节与适用边界

核心扫描命令在命令定义和完整版技能 skills/ponytail-debt/SKILL.md 中完全一致：

grep -rnE '(#|//) ?ponytail:' .

这个正则的匹配语义值得注意：

• (#|//) 覆盖了 Python/Shell 风格的 # 注释和 JS/TS/C 风格的 // 注释；
• ? 允许 ponytail: 前有一个可选空格，即同时匹配 #ponytail: xxx 和 # ponytail: xxx 两种写法；
• 前缀是强制的——SKILL.md 中明确解释：The comment prefix keeps prose that merely mentions the convention out of the ledger. 也就是说，纯文字提到 "ponytail:" 这个约定（而非作为注释标记出现）不会被计入台账，避免噪声。

适用边界方面，skills/ponytail-debt/SKILL.md 补了一句：add other comment prefixes if your stack uses them。这一点在 ponytail 仓库自身就能得到印证——README.md 中有一条 HTML 注释标记 <!-- ponytail: browser has one -->，默认的 (#|//) 正则匹配不到这种前缀，需要自行扩展。这也说明该命令的扫描规格是按注释前缀"可配置"设计的：标记语法本身（ponytail: <ceiling>, <upgrade path>）是核心，前缀随技术栈而变。

台账输出格式与 no-trigger 机制

完整版技能 skills/ponytail-debt/SKILL.md 对输出格式给出了与命令定义一致但更展开的说明，台账行格式为：

<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.

由于约定本身就是 ponytail: <ceiling>, <upgrade path> 两段式，ceiling 和 trigger 可以直接从注释文本中原样摘出，无需推断。SKILL 还提供了一个可选增强：想给每一行加上负责人时，追加执行 git blame -L<line>,<line> 即可。

no-trigger 机制是该命令最有判断力的部分。它不是简单罗列标记，而是对每条标记做质量审计：注释里如果只有简化说明、没有"何时回来重审"的触发条件，就会被标记为 no-trigger。命令定义原文把这类欠账定性为 those rot silently——没有触发器的延期不会有人想起来，最终永久化。报告结尾固定输出统计行（SKILL 版写法）：

<N> markers, <M> with no trigger.

零标记时的固定输出则是：

No ponytail: debt. Clean ledger.

仓库中的真实标记验证

ponytail 仓库自身就是该机制的实践场，可以直接用上面的 grep 验证。几条真实的 ponytail: 标记及其质量分布：

• benchmarks/agentic/judge.py：ponytail: stdlib urllib for the API call, no requests dependency. —— ceiling 是"零第三方依赖"，隐含 upgrade 是"需要更成熟 HTTP 能力时引入 requests"，属于有触发器的规范标记；
• benchmarks/agentic/run.py：ponytail: the claude CLI is the harness (already installed, we run inside it). No SDK —— 用已装 CLI 代替 SDK 的简化，ceiling 明确；
• benchmarks/agentic/tasks.py：# ponytail: short, but full-string anchored -- \s excludes the newline so the injection is rejected. —— 这条甚至解释了简化为何在安全边界上仍然成立，是"带安全论证的欠账"范例；
• benchmarks/correctness.js：// ponytail: terse models often answer with bare, unfenced code. Treat the whole —— 解释了对简短模型输出的兜底处理；
• README.md：<!-- ponytail: browser has one --> —— 这条只说明了简化原因（浏览器原生已有该功能），没有写明升级触发条件，恰好是 no-trigger 标签的典型对象。

benchmarks/results/2026-06-12-v4-hardening-vs-caveman.md 中还记录了团队对该约定本身的审计结论：带 ceiling 的 ponytail: 注释必须写明升级路径（Ceiling-bearing ponytail: comments name upgrade paths — pass），说明 no-trigger 检测规则与仓库内部质量把关标准是对齐的。

边界声明与跨平台形态

skills/ponytail-debt/SKILL.md 的 Boundaries 一节给出了比命令定义更完整的边界说明：

• 只读：Reads and reports only, changes nothing（只读只报告，不改动任何文件）；
• 可选持久化：To persist it, ask and it writes the ledger to a file (e.g. PONYTAIL-DEBT.md) —— 需要落盘时显式要求，它才会把台账写成文件，默认不落盘；
• 一次性：One-shot，跑完即止，不驻留；
• 退出方式："stop ponytail-debt" or "normal mode" to revert。

同一命令规格在仓库中还有两种等价的跨平台形态，可供对照阅读：

形态	路径	用途
OpenCode 命令（本文主体）	.opencode/command/ponytail-debt.md	OpenCode 中注册为 /ponytail-debt 斜杠命令
通用技能	skills/ponytail-debt/SKILL.md	供各 agent 宿主加载的完整技能，含触发词（"ponytail debt"、"list the shortcuts"、"what did we mark to do later" 等）
TOML 命令	commands/ponytail-debt.toml	同一 prompt 的 TOML 封装，description 与命令 frontmatter 一致

此外，Python 侧的 init.py 中对该命令的一句话定义——"List every deliberate ponytail: shortcut and its upgrade path."——与 README 命令表（/ponytail-debt | Harvest the ponytail: shortcuts you've deferred into a ledger, so "later" doesn't become "never".，见 README.md）共同说明了它的定位：这是一个纯报告型的审计工具，与代码变更类命令严格隔离。

使用前提与操作方式

要在 OpenCode 中使用该命令，前提是把 ponytail 注册为项目插件。按 README.md 的说明，在项目的 opencode.json 中加入：

{ "plugin": ["./.opencode/plugins/ponytail.mjs"] }

仓库根目录的 opencode.json 本身就是该配置的最小示例，加载的插件实现位于 .opencode/plugins/ponytail.mjs（README 指出 ./ 相对项目根的 opencode.json 解析；要跨项目共享一份 checkout 时，可改为指向该 .mjs 的绝对路径，插件会相对自身文件定位 hooks/ 与 skills/）。

配置完成后，在 OpenCode 会话中输入 /ponytail-debt（或说 "ponytail debt"、"what did ponytail defer"），agent 即按前文所述的五步规格执行：全树 grep → 逐标记建账 → 打 no-trigger 标签 → 输出统计 → 全程零改动。对于使用 ponytail 模式长期迭代的项目，定期跑一次该命令，等于给"刻意简化"做一次对账：有触发器的欠账排期重审，no-trigger 的欠账要么补上升级路径、要么升级为正式任务，让台账真正成为债务管理工具而非注释考古报告。