Ponytail Help 速查手册：一次掌握 Ponytail 的三档强度、六大技能与默认模式配置

本文基于 Ponytail 仓库中 OpenClaw 分发的 ponytail-help 技能卡（.openclaw/skills/ponytail-help/SKILL.md）展开，完整覆盖 Ponytail 的三级强度（Lite / Full / Ultra）、六个配套技能、停用方式与默认模式配置方法，并结合 hooks/ponytail-config.js、hooks/ponytail-mode-tracker.js 等源码，解释每条命令背后的实际解析与持久化逻辑。读完本文，你可以准确切换强度档位、配置跨会话的默认模式，并理解 Ponytail 各命令在运行时是如何被识别、执行和持久化的。

ponytail-help：一张"一次性"参考卡

ponytail-help 的定位在技能文件的 frontmatter 中写得很明确：

Quick reference for ponytail's modes, skills, and commands. One-shot display.

它与其他 Ponytail 技能的关键区别在于**一次性（one-shot）**语义：被调用时只展示这张参考卡，不切换模式、不写 flag 文件、不持久化任何状态。这一点同样体现在 Claude Code 侧的命令定义 commands/ponytail-help.toml 中，其 prompt 开头即写明 "One shot, change nothing: do not switch mode, write flag files, or persist anything"。

仓库中实际上存在两份内容几乎一致的 help 卡片，分属不同宿主生态：

文件	分发渠道
.openclaw/skills/ponytail-help/SKILL.md	OpenClaw（clawhub install ponytail-help）
skills/ponytail-help/SKILL.md	Claude Code / Codex 等技能宿主

frontmatter 还登记了触发短语："ponytail help"、"what ponytail commands"、"how do I use ponytail" 都可以唤起这张卡片，无需精确输入 /ponytail-help。

三档强度：Lite、Full、Ultra

help 卡片的 "Levels" 表格完整给出了三档强度及其触发方式：

Level	触发命令	行为变化
Lite	/ponytail lite	照需求实现，并用一行指出更懒的替代方案
Full	/ponytail	强制执行"阶梯"：YAGNI → 标准库 → 原生能力 → 一行代码 → 最小实现。这是默认档
Ultra	/ponytail ultra	YAGNI 极端主义者：先删后加，构建前先质疑需求本身

卡片强调 "Level sticks until changed or session end"（档位保持到切换或会话结束）。这句话在源码中得到印证：hooks/ponytail-mode-tracker.js 是 UserPromptSubmit 钩子，它解析用户输入开头的 /ponytail 命令（兼容 Codex 的 @ponytail 与 $ponytail 前缀），调用 setMode(mode) 把档位写入会话级 flag 文件——所以它是会话作用域的，而非永久配置。

Full 档的"阶梯"（the ladder）具体顺序，可以在共享指令构建器 hooks/ponytail-instructions.js 的兜底指令文本中看到完整定义：

1. 这东西到底需要构建吗？（YAGNI）
2. 这个代码库里是否已经存在？复用已有的，不要重写
3. 标准库能做吗？用它
4. 平台原生能力覆盖吗？用它
5. 已安装的依赖能解决吗？用它
6. 能写成一行吗？那就一行
7. 最后才写"能工作的最小代码"

getPonytailInstructions(mode) 会读取主技能 skills/ponytail/SKILL.md 并按当前档位过滤出对应的强度表格行与示例（filterSkillBodyForMode），也就是说不同档位注入的指令文本确实不同，而不是只改个标签。

从源码结构看，档位取值还有两层校验，值得配置时注意：

• 会话档位（/ponytail lite|full|ultra|off）：hooks/ponytail-config.js 中 RUNTIME_MODES = ['off', 'lite', 'full', 'ultra']，全部小写归一化后匹配。
• 可持久化档位：review 也是一个合法模式（对应 /ponytail-review），但它被归入 VALID_MODES 却不在 RUNTIME_MODES 中——hooks/ponytail-config.js 的注释明确说明 review 只是会话内模式，永远不能作为默认值（对应上游 issue #377），所以环境变量或配置文件里写 review 会被忽略。

另外，/ponytail default <mode> 是一个特殊的持久化入口：hooks/ponytail-mode-tracker.js 中，它会把 off|lite|full|ultra 之一写入配置文件（writeDefaultMode），影响之后所有新会话；而普通的 /ponytail lite 只作用于当前会话。

六个技能：Ponytail 的命令矩阵

help 卡片的 "Skills" 表格列出了完整的技能矩阵：

Skill	触发命令	作用
ponytail	/ponytail	"懒惰模式"本体：给出能工作的最简方案
ponytail-review	/ponytail-review	针对当前改动的过度设计审查，形如 L42: yagni: factory, one product. Inline.
ponytail-audit	/ponytail-audit	全仓库过度设计审计：输出一份"该删什么"的排序清单
ponytail-debt	/ponytail-debt	把代码中的 ponytail: 快捷注释收割成一份可跟踪的债务台账
ponytail-gain	/ponytail-gain	实测收益记分板：更少的代码、更低的成本、更快的速度
ponytail-help	/ponytail-help	即这张卡片本身

各宿主的前缀差异同样写在卡片中：Codex 使用 @ponytail、@ponytail-review、@ponytail-help 等 @ 形式；Claude Code 与 OpenCode 使用上述斜杠命令（OpenCode 以斜杠命令形式内置全部六个）。

下面结合各技能的实际定义，补充这张表格里没展开的行为细节：

• ponytail-review（skills/ponytail-review/SKILL.md）：只审"过度设计"，不审正确性。每个发现一行，格式为 L<行号>: <标签> <删什么>. <替换成什么>.，标签体系是 delete:（死代码）、stdlib:（标准库自带）、native:（平台已实现）、yagni:（只有一个实现的抽象）、shrink:（更少行的等价写法）。示例：L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.
• ponytail-audit（skills/ponytail-audit/SKILL.md）：review 的全仓库版本，按"最大的削减在前"排序输出，结尾给出 net: -<N> lines, -<M> deps possible.；明确声明正确性 bug、安全漏洞与性能问题不在其范围内。
• ponytail-debt（skills/ponytail-debt/SKILL.md）：用 grep -rnE '(#|//) ?ponytail:' . 扫描代码库，把每条 ponytail: 注释（约定格式为 ponytail: <上限>, <升级路径>）收进台账；没有写明"重新审视触发条件"的注释会被打上 no-trigger 标签，标记其静默腐烂的风险。
• ponytail-gain（skills/ponytail-gain/SKILL.md）：展示基准测试中位数记分板（5 个日常任务 × 3 个模型）。它同样是一次性展示，且明确说明数字来自 benchmarks/ 目录的实测中位数，而非针对当前仓库计算。
• ponytail（skills/ponytail/SKILL.md）：主技能，其正文就是上一节"阶梯"与规则（不请求的抽象不写、删除优先于新增、故意削减时留下 ponytail: 注释）的完整来源，也是 hooks/ponytail-instructions.js 每轮注入的指令主体。

停用与恢复

卡片给出三种停用方式，两种恢复方式：

• 停用：说 "stop ponytail" 或 "normal mode"；或者执行 /ponytail off。
• 恢复：随时再执行 /ponytail。

"stop ponytail" / "normal mode" 这两句自然语言指令的识别逻辑在 hooks/ponytail-config.js 的 isDeactivationCommand 中实现，有一个值得注意的细节：它要求整条消息（忽略大小写、忽略结尾标点）恰好等于该短语。源码注释解释了原因——如果只匹配短语出现的任意位置，像 "add a normal mode toggle" 这样的普通开发请求会在任务中途把 Ponytail 关掉，所以收紧为独立命令才生效。/ponytail off 则走 hooks/ponytail-mode-tracker.js 中的 clearMode() 分支，清空 flag 文件并输出 "PONYTAIL MODE OFF"。

配置默认模式：环境变量、配置文件与解析顺序

Ponytail 的默认模式是 full，且每个会话自动激活。help 卡片的 "Configure Default Mode" 一节给出两条修改途径：

1. 环境变量（最高优先级）

export PONYTAIL_DEFAULT_MODE=ultra

2. 配置文件：~/.config/ponytail/config.json（Windows 为 %APPDATA%\ponytail\config.json）

{ "defaultMode": "lite" }

把 defaultMode 设为 "off" 可以禁用会话开始时的自动激活，之后需要时再用 /ponytail 手动打开。

卡片总结的解析顺序是 env var > config file > full。完整的实现位于 hooks/ponytail-config.js 的 getDefaultMode()，从源码看实际行为比卡片略多一些细节：

1. PONYTAIL_DEFAULT_MODE 环境变量
   └─ 必须属于 RUNTIME_MODES（off/lite/full/ultra），小写匹配；否则跳过
2. 配置文件 config.json 的 defaultMode 字段
   ├─ 配置目录解析：$XDG_CONFIG_HOME/ponytail（若设置）
   │                 → ~/.config/ponytail（macOS/Linux 回退）
   │                 → %APPDATA%\ponytail（Windows 回退）
   └─ 读取时先剥离 UTF-8 BOM（Windows 下保存的 JSON 常见），JSON 解析失败则静默跳过
3. 兜底常量 'full'

几个源码层面可以确认的边界行为：

• 取值白名单：环境变量与配置文件中的值都不在 RUNTIME_MODES 之内（例如拼写错误、review）时，不会报错而是直接落到下一级，最终回退到 full。
• review 不可作为默认值：如前所述，normalizeMode 与 normalizeConfigMode 的区分专门为此设计（hooks/ponytail-config.js）。
• 写入路径同样受校验：writeDefaultMode（供 /ponytail default <mode> 使用）也只接受 RUNTIME_MODES 中的值，写入前 mkdir -p 配置目录。
• README 中的口径一致：README.md 写明 "Set the level for every new session with the PONYTAIL_DEFAULT_MODE env var (lite/full/ultra/off), or a defaultMode field in ~/.config/ponytail/config.json … The default is full."，并确认 "nothing is required"——配置文件是可选的。

更新机制

卡片 "Update" 一节针对 Claude Code 宿主给出了更新流程：

1. 开启自动更新（一次性设置）：打开 /plugin → Marketplaces → 选择 ponytail → Enable auto-update。之后 Claude Code 在启动时拉取新版本（提示时执行 /reload-plugins）。
2. 手动刷新：/plugin marketplace update ponytail，然后 /reload-plugins。
3. /plugin 命令不被识别时：说明 Claude Code 版本过旧，先升级宿主（npm install -g @anthropic-ai/claude-code@latest 或 brew upgrade claude-code）并重启。其他宿主（Codex、OpenCode、OpenClaw 等）使用各自的更新流程。

小结：从帮助卡到运行时

ponytail-help 这张卡片虽然只有几十行，但它浓缩了 Ponytail 的完整控制面：三档强度对应"阶梯"约束的松紧，六个技能覆盖从写代码（ponytail）到删代码（review/audit）再到记账（debt/gain）的闭环，停用与默认模式配置则分别对应会话级 flag 文件与全局 config.json 两条持久化路径。仓库中 hooks/ponytail-mode-tracker.js（命令识别与会话状态）、hooks/ponytail-config.js（默认模式解析）与 hooks/ponytail-instructions.js（按档位注入指令）三个文件，构成了卡片上每一条行为的源码级对应关系——这也是阅读 Ponytail 其余文档时的最佳入口。