Ponytail 新手教程

FAQ 与参考

常见误解、真踩过的坑，以及仓库结构和官方链接。最后一章，可以当速查表用。

常见误解 仓库结构 GitHub 仓库

1FAQ

需要配置文件吗？

不需要。可选的 ~/.config/ponytail/config.json（Windows 是 %APPDATA%\ponytail\config.json）或者 PONYTAIL_DEFAULT_MODE 环境变量可以改默认强度，但什么都不配也能用，默认就是 full。

能跟 caveman 一起用吗？

可以，而且官方建议一起用。caveman 压缩助手说的话（代码逐字节不动），ponytail 压缩助手造的东西（不碰散文）。各占一半，不重叠。

我确实需要那个 120 行的缓存类怎么办？

那就坚持要。官方原话大意是：你坚持，他就会建，慢慢建、正确建。规则里也写明「用户坚持要完整版就完整版给，不再争」。Ponytail 不会替你拒绝需求。

它扛得住规模吗？

官方 FAQ 用了一句玩笑：「你没写的代码可以无限扩展。零 bug、零 CVE、永远 100% 可用。」玩笑背后是真实逻辑——被避免掉的代码不会产生维护成本。

为什么叫 ponytail（马尾）？

官方答案是一个反问：「你明明知道为什么。」——就是那个工龄比版本控制系统还长、扎着马尾的资深工程师形象。名字本身不承载技术含义。

Cursor 里装了但好像没生效？

先查两件事：① 工作区里是不是有 .cursor/rules/ponytail.mdc——有的话 hooks 会主动退让，这是设计如此，不是坏了；② node 在不在 Cursor 看得见的 PATH 上（nvm / Nix 用户常见的坑）。之后用「让它背出第一行」的方法验证，见第 4 章。

为什么在 Cursor 里打 /ponytail-review 没反应？

因为那个命令在 Cursor 里不存在。带 hooks 的 Cursor 只得到 /ponytail 的强度切换，而且必须当作普通消息发。review / audit / debt / gain / help 需要支持技能的宿主。变通办法是用自然语言把要求说清楚，见第 6 章。

仓库里那个 ponytail-mcp/ 是干什么的？装它有用吗？

它确实存在（有共享的 filterSkillBodyForMode 被 Claude hooks、Pi、OpenCode、MCP server、Hermes 共用），但 README 里所有宿主的安装流程都没有走 MCP。Grok 适配时更是明确移除了 MCP 接线，理由是 git 安装从来不会装 MCP 的依赖，而且 hooks + skills 已经覆盖了常驻注入的需求。新手不用管它。

卸载会有残留吗？

会有一点：强度标志文件、~/.config/ponytail/config.json、Cursor 的 hooks.json 条目，以及（如果你接受过设置提示）Claude Code settings.json 里的一个 statusLine 条目。跑 node scripts/uninstall.js 可以一次清干净。注意顺序：先跑它，再用宿主的移除命令，否则脚本会跟着插件一起被删掉。

2常见误解核对表

误解事实在第几章
它是代码生成器 / 模板库它一行代码都不产出，是注入给助手的规则文本1
「懒」= 不用验证四条红线永不削减，而且实测 20/20 安全1、8
装上会立刻自动重构仓库只影响之后的对话行为；审已有代码要显式跑命令6
能少写 80%~94% 代码旧数字已被作者撤回；可用说法是「有水分处砍六到九成」8
一定更省 token / 更省钱在遵守梯子的模型上是副产品；某些推理模型反而更贵1、8
常驻规则 + hooks 双保险两者互斥，规则文件存在时 hooks 会退让5
子代理也会拿到规则Cursor 的 subagentStart 无法注入上下文，拿不到5
能保证「永不误删 / 永不漏判」它改的是决策顺序，不是正确性证明8

3仓库结构速查

知道这几个目录的作用，看仓库时就不会迷路。注意它有一大半目录都是「宿主适配层」——同一个技能被翻译成二十种宿主的加载方式。

路径作用
skills/核心。6 个技能目录，各自一份 SKILL.md，是真正跨宿主复用的行为定义
hooks/生命周期钩子脚本：激活、模式追踪、运行时（含 Cursor 专用模板 cursor-hooks.json）
scripts/安装与维护：cursor-hooks.js、uninstall.js、check-rule-copies.js 等
commands/支持斜杠命令的宿主用的命令定义
AGENTS.md压缩版常驻指令，给不支持技能的宿主用
.cursor/rules/ · .windsurf/rules/ · .clinerules/ · .kiro/steering/ · .qoder/rules/各宿主的规则副本（必须彼此对齐，这就是 check-rule-copies.js 的用途）
.claude-plugin/ · .codex-plugin/ · .grok-plugin/ · .qoder-plugin/ · .devin-plugin/各宿主的插件清单
examples/12 个「更懒的写法」范例：debounce、deep-clone、modal-dialog、url-params、rate-limit、react-countdown……
docs/三份关键文档：agent-portability.md、cursor-hooks.md、platform-native.md
benchmarks/基准测试框架与结果（含那套可复现的无头会话管线）
tests/测试，含 cursor-hooks.test.js（喂 Cursor 输入形状、断言输出形状）
ponytail-mcp/MCP 服务器，但各宿主安装流程都没走它（见 FAQ）

4版本与许可

项值
最新发布v4.10.0（2026-09-14）
许可MIT。官方描述：「能用的最短的那个许可证」
首个仓库语言构成JavaScript / Node.js 为主，辅以 Python（基准测试）与大量 Markdown 规则文本
npm 包@dietrichgebert/ponytail
自述支持宿主20 个
本教程依据的 Cursor 契约来自仓库 docs/cursor-hooks.md，其中记录客户端核验版本为 Cursor 3.20.17（2026-09-14，Windows）。Cursor 更新较快，升级后建议用第 4 章那套「让模型背出第一行」的方法重新验证一次。