ponytail 模式与命令完全速查：levels、skills、配置与默认模式解析指南

本文以 ponytail 仓库中的 help 技能卡片 为主体，完整覆盖 ponytail 的三档强度等级（lite/full/ultra）、六个配套 skill 的触发方式与职责、停用与恢复机制，以及默认模式的三层配置解析链（环境变量 → 配置文件 → 内置默认值），并结合 hooks/ponytail-config.js、hooks/ponytail-mode-tracker.js 和 tests/hooks.test.js 的源码与测试证据，讲清每个命令背后实际的解析与落盘行为，帮助你在 Claude Code、Codex、OpenCode 等宿主中正确配置和切换 ponytail。

一、ponytail-help 是什么：一次性速查卡片

skills/ponytail-help/SKILL.md 的 frontmatter 明确定义了它的性质：

name: ponytail-help
description: >
  Quick-reference card for all ponytail modes, skills, and commands.
  One-shot display, not a persistent mode. Trigger: /ponytail-help,
  "ponytail help", "what ponytail commands", "how do I use ponytail".

它是一个一次性展示（one-shot）技能，而不是一个持久模式：被触发时只打印速查卡片，不改变当前模式、不写任何 flag 文件、不持久化任何状态。这一点在对应的 slash 命令定义 commands/ponytail-help.toml 中也被复述为 "One shot, change nothing: do not switch mode, write flag files, or persist anything"——两个入口共用同一份文案，保证卡片内容与 slash 命令输出一致（仓库通过 scripts/check-rule-copies.js 之类的脚本约束多份副本的一致性，见 README.md Development 一节）。

触发方式包括 /ponytail-help、自然语言 "ponytail help"、"what ponytail commands"、"how do I use ponytail"。下面就是这张卡片的全部信息，再逐项展开。

二、三档强度等级（Levels）

原文档给出的等级表如下：

Level	Trigger	What change
Lite	/ponytail lite	按要求的构建，只用一行点名"更懒的替代方案"。
Full	/ponytail	完整执行梯子：YAGNI → stdlib → native → one line → minimum。默认档。
Ultra	/ponytail ultra	YAGNI 极端主义：删除先于新增，动手前先质疑需求本身。

卡片特别注明 "Level sticks until changed or session end"——等级会持续生效，直到被切换或会话结束。

这里的"梯子"（ladder）是 ponytail 核心技能 skills/ponytail/SKILL.md 定义的七级决策阶梯：先问"这东西需要存在吗"（YAGNI），再看"代码库里有没有现成的"、"标准库能不能做"、"平台原生特性是否覆盖"、"已装依赖是否解决"、"能否一行搞定"，最后才是"最小可用代码"。full 档就是把这架梯子作为强制流程执行；lite 档只在构建完所要求的东西后附一句更省事的选项；ultra 档则把 YAGNI 推到极限，在实现前先挑战需求合理性。

从 commands/ponytail.toml 可以看到 slash 命令的完整 prompt：

description = "Switch ponytail intensity level (lite/full/ultra/off)"
prompt = "Switch to ponytail {{args}} mode. If no level specified, use full. ..."

即 /ponytail 不带参数时落到 full，与卡片中 "Default" 的说法一致；off 参数则直接关闭。

三、六个 skill 一览

原文档的技能表：

Skill	Trigger	What it does
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	本卡片。

仓库中每个 skill 都对应一个目录和一个 slash 命令定义，prompt 与卡片描述一一对应：

• skills/ponytail-review/SKILL.md 与 commands/ponytail-review.toml：只审查过度设计、不审查正确性，逐行输出 L<行号>: <tag> <要删的东西>. <替代方案>，tag 限定为 delete / stdlib / native / yagni / shrink 五种，最后给出可净删的行数；无问题则输出 "Lean already. Ship."
• skills/ponytail-audit/SKILL.md 与 commands/ponytail-audit.toml：面向整棵代码树而非 diff，按"最大削减优先"排序，额外统计可删除的依赖数量。
• skills/ponytail-debt/SKILL.md 与 commands/ponytail-debt.toml：用 grep -rnE '(#|//) ?ponytail:' .（跳过 node_modules/.git/构建产物）收割注释标记，按文件分组输出 "简化了什么 / ceiling 上限 / upgrade 重审触发条件" 三要素，并把没有升级路径的标记打上 no-trigger 标签——这类标记"会静默腐化"。该命令是只读的（"Report only, change nothing"）。
• skills/ponytail-gain/SKILL.md 与 commands/ponytail-gain.toml：一次性打印基准测试（benchmarks/）中的中位数记分板。注意其中的严谨边界：展示的是发布版 benchmark 的中位数（5 个日常任务、Haiku/Sonnet/Opus 三模型），且明确 "NEVER print a per-repo savings number"——未写出的代码没有基线可减，真实仓库收益应指向 /ponytail-debt（已计数捷径台账）和 /ponytail-audit（仍可供削减项）。

宿主的调用语法差异：卡片指出 Codex 使用 @ponytail、@ponytail-review、@ponytail-help 这类 at-sign 形式，而 Claude Code 和 OpenCode 使用上面的 slash 命令形式（OpenCode 会把全部六个都注册为 slash 命令）。这一差异在 hooks/ponytail-mode-tracker.js 的源码中有对应实现——模式追踪 hook 同时匹配 /、@、$ 三种前缀：

if (/^[/@$]ponytail/.test(prompt)) {
  const parts = prompt.split(/\s+/);
  const cmd = parts[0].replace(/^[@$]/, '/');
  // ...
}

也就是说 @ponytail（Codex）、$ponytail（Swival 等宿主）和 /ponytail（Claude Code/OpenCode）会被归一化为同一条 /ponytail 命令来解析，卡片里描述的三套触发形式由此在同一个运行时里统一工作。

四、停用与恢复（Deactivate）

卡片给出的操作是：

Say "stop ponytail" or "normal mode". Resume anytime with /ponytail. /ponytail off also works.

两种自然语言停用词由 hooks/ponytail-config.js 中的 isDeactivationCommand() 精确判定：

function isDeactivationCommand(text) {
  const t = String(text || '').trim().toLowerCase().replace(/[.!?\s]+$/, '');
  return t === 'stop ponytail' || t === 'normal mode';
}

注意两个关键实现细节：

1. 必须是整条消息：源码注释解释，早期"消息里任何位置出现该短语就停用"的逻辑，会在用户说 "add a normal mode toggle"（添加一个普通模式切换器）这种普通开发请求时误关 ponytail，所以改为要求整条消息（忽略大小写与结尾标点）恰好是停用命令。
2. 有回归测试守护：tests/hooks.test.js 中有一条用例明确验证 'incidental "normal mode" in a request must not turn ponytail off'，即提到 "normal mode" 的普通请求不得关闭模式。

恢复路径有两条：/ponytail（无参数，按默认档激活）或 /ponytail off 后再 /ponytail。从 hooks/ponytail-mode-tracker.js 可以看到 /ponytail off 会 clearMode() 并输出 "PONYTAIL MODE OFF"；而 /ponytail 无参数时是 report-only 行为——读取当前 flag 或回落到默认模式并报告级别（对应 README.md Commands 表中 "No argument reports the current level" 的描述）。

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

这是卡片中最有实战价值的部分。原文档说明：默认模式为 full，每次会话自动激活，可通过两种方式修改：

方式一：环境变量（优先级最高）

export PONYTAIL_DEFAULT_MODE=ultra

方式二：配置文件

路径为 ~/.config/ponytail/config.json，Windows 上是 %APPDATA%\ponytail\config.json：

{ "defaultMode": "lite" }

将值设为 "off" 可关闭"会话启动时自动激活"，需要时再手动 /ponytail 打开。

解析顺序：env var > config file > full。

源码级印证：解析链如何实现

hooks/ponytail-config.js 的文件头注释把解析顺序写成了规范：

// Resolution order for default mode:
//   1. PONYTAIL_DEFAULT_MODE environment variable
//   2. Config file defaultMode field:
//      - $XDG_CONFIG_HOME/ponytail/config.json (any platform, if set)
//      - ~/.config/ponytail/config.json (macOS / Linux fallback)
//      - %APPDATA%\ponytail\config.json (Windows fallback)
//   3. 'full'

这里有一个卡片未提及但实际存在的细节：如果设置了 XDG_CONFIG_HOME，配置文件优先读取 $XDG_CONFIG_HOME/ponytail/config.json（任何平台），未设置才回落到 ~/.config/ponytail/config.json（macOS/Linux）或 %APPDATA%\ponytail\config.json（Windows）。

getDefaultMode() 的实现还包含若干健壮性设计，直接决定了你在配置时的行为边界：

1. 值必须是合法运行档位：合法值常量定义为 RUNTIME_MODES = ['off', 'lite', 'full', 'ultra']。环境变量或配置文件里写了其他值（拼写错误、或 review 这类会话专属模式）会被静默忽略，落回下一优先级，最终落到 full。review 不能作为默认值这一约束在 tests/hooks.test.js 中有专门用例："PONYTAIL_DEFAULT_MODE=review must fall back to the built-in default"。
2. off 是合法的默认值：它表示"不自动激活"，与卡片中 "Set "off" to disable auto-activation" 对应——off 在 RUNTIME_MODES 列表内，所以会被正常接受。
3. UTF-8 BOM 容错：读取配置时执行 fs.readFileSync(configPath, 'utf8').replace(/^\uFEFF/, '')，专门处理 Windows 编辑器保存的带 BOM 的 JSON 文件，避免 JSON.parse 抛错。
4. 配置文件不存在或损坏时静默穿透到默认值 full，不会让会话启动失败。

交互式持久化默认值

除了手动改配置文件，hooks/ponytail-mode-tracker.js 还实现了一条卡片未展开的持久化路径：

if (arg === 'default') {
  const dmode = parts[2];
  if (dmode === 'off' || dmode === 'lite' || dmode === 'full' || dmode === 'ultra') {
    writeDefaultMode(dmode);
    writeHookOutput('UserPromptSubmit', dmode, 'PONYTAIL DEFAULT SET — new sessions start in ' + dmode + '.');
  }
  return; // don't fall through to the session-mode switch
}

即输入 /ponytail default lite 会通过 hooks/ponytail-config.js 的 writeDefaultMode() 把 defaultMode 写进配置文件（自动创建目录、合并已有字段），"新会话从 lite 开始"。源码注释明确区分：普通切换（/ponytail lite）只作用于当前会话（session-scoped），只有 default 子命令这一条路径会写配置、跨重启生效。测试用例 'plain switch must not persist the default' 验证了这一点。

六、更新机制（Update）

卡片给出的更新流程面向 Claude Code 插件形态：

• 自动更新：打开 /plugin → Marketplaces → 选择 ponytail → Enable auto-update。此后 Claude Code 会在启动时拉取新版本（提示时执行 /reload-plugins）。
• 手动刷新：/plugin marketplace update ponytail 然后 /reload-plugins。
• /plugin 不被识别时：说明 Claude Code 版本过旧，需要先升级（npm install -g @anthropic-ai/claude-code@latest 或 brew upgrade claude-code）再重启；其他宿主（Codex、OpenCode、Gemini 等）走各自的更新流程。

各宿主的安装/卸载命令矩阵可参考 README.md 的 Install / Uninstall 章节，例如 Claude Code 用 /plugin remove ponytail、Codex 用 codex plugin remove ponytail；插件目录之外的残留状态（模式 flag、~/.config/ponytail/config.json、statusLine 配置）需要运行 node scripts/uninstall.js 清理（见 scripts/uninstall.js）。

七、速查：卡片信息 × 仓库证据对照

卡片要点	仓库证据位置
三档等级 + 无参默认 full	commands/ponytail.toml、skills/ponytail/SKILL.md 的 Intensity 表
六个 skill 与触发词	skills/ 六个目录 + commands/ 六个 .toml
"One-shot, 不写状态"	commands/ponytail-help.toml 的 prompt
Codex @ 前缀 / $ 前缀归一	hooks/ponytail-mode-tracker.js 的正则 /^[/@$]ponytail/
"stop ponytail" / "normal mode" 整句匹配	hooks/ponytail-config.js isDeactivationCommand()、tests/hooks.test.js 回归用例
env > config > full；XDG 优先；BOM 容错	hooks/ponytail-config.js getDefaultMode() / getConfigDir()
/ponytail default <mode> 持久化，普通切换不持久	hooks/ponytail-mode-tracker.js arg === 'default' 分支、tests/hooks.test.js
各宿主命令表	README.md Commands 章节

适用前提与限制：以上 slash 命令与模式切换依赖"skill 能力宿主"（Claude Code、Codex、Devin CLI、OpenCode、Gemini、pi、Swival、Hermes Agent、Qoder）；Cursor、Windsurf、Cline、Copilot 等 instruction-only 适配器只加载常驻规则集，不提供命令切换（见 README.md Commands 一节）。配置解析（第五节）由 hook 运行时执行，仅在插件/插件 hook 完整安装的场景下生效；纯复制规则文件（AGENTS.md 等）的场景下，模式与配置概念不适用。