安装与宿主选择

20 个宿主其实只有三档，命令不用背。先认出你在哪一档，再复制那一条命令。

一条命令装完 20 个宿主 agent-portability 原文

1装之前先做两件事

第一件是确认 node 在 PATH 上。只有走 hooks / 插件的宿主需要它，但教训是：必须是宿主看得见的那个 PATH。如果你的 node 由 nvm 或 Nix 管理，请确认「非交互 shell」的 PATH 里也有——否则表现是：技能照常能用，只是自动激活安静地不生效，而且不会报错，你会以为装失败了。

node --version
# 应该打印出 v18 / v20 / v22 之类的版本号
# 如果 command not found：先修 PATH，再继续

第二件是想清楚你要哪一档。官方把这叫 adapter（适配层），三种形态差别很实在：

	插件档	hooks 档	规则档
常驻规则	有	有	有
强度切换 lite/full/ultra/off	有	部分	没有
`/ponytail-review` 等 5 个命令	有	部分	没有
会话自动激活	有	有（Cursor 的 sessionStart）	无（规则一直生效）
安装成本	两条命令	clone + 一条命令	拷一个文件

档位不是好坏之分。命令越多的宿主，注入机制越重、限制越少；规则档最轻，但永远只有一个固定强度。

2插件档：命令最全

Claude Code——注意必须分成两次发送，一次发一行：

/plugin marketplace add DietrichGebert/ponytail

/plugin install ponytail@ponytail

Claude Code 桌面版的 Code 标签页是同样两步：把上面两条命令打进输入框，或者点旁边的 + 按钮 → Plugins → Add plugin。

Codex——装完还要去信任 hooks，这一步别漏：

codex plugin marketplace add DietrichGebert/ponytail
codex plugin add ponytail@ponytail
# 然后启动 codex，打开 /hooks 审查并信任它的两个生命周期钩子，再开新会话

其余插件档宿主：

宿主	命令	备注
GitHub Copilot CLI	`copilot plugin marketplace add …` 然后 `copilot plugin install ponytail@ponytail`	命名空间化，命令写作 `/ponytail:ponytail ultra`
pi agent	`pi install git:github.com/DietrichGebert/ponytail`	—
Devin CLI	`devin plugins install DietrichGebert/ponytail`	技能以 `/ponytail:ponytail` 出现
OpenClaw	`clawhub install ponytail`	其它 5 个技能同理逐个装
Grok Build	`grok plugin install DietrichGebert/ponytail --trust`	插件默认关闭，要在 `/plugins` 里打开
Hermes Agent	`hermes plugins install DietrichGebert/ponytail --enable`	装完要重启 Hermes
Gemini CLI	`gemini extensions install https://github.com/DietrichGebert/ponytail`	Antigravity CLI（`agy`）用同一条

Grok 有个细节值得知道：它的生命周期 hooks 没被用，原因是 SessionStart 的输出没法注入指令。所以它靠技能描述来自动触发，需要明确激活时手动打 /ponytail。

3hooks 档：Cursor 走这条

Cursor 需要先 clone 仓库（因为 hooks 是直接跑仓库里的 node 脚本），然后一条命令完成合并写入：

git clone https://github.com/DietrichGebert/ponytail
node ponytail/scripts/cursor-hooks.js install

其它同档宿主的配置方式各不相同，大多是「加一段配置」而不是「跑一个安装脚本」：

宿主	怎么接
Cursor	`node ponytail/scripts/cursor-hooks.js install`（详见第 4 章）
Qoder	零配置读 `AGENTS.md`；按项目规则则拷 `.qoder/rules/ponytail.md`；要模式切换就把 `hooks/qoder-hooks.json` 合并进 `.qoder/settings.json` 并替换 `PONYTAIL_DIR`
OpenCode	在 `opencode.json` 里加 `{"plugin": ["@dietrichgebert/ponytail"]}`
CodeWhale	读项目根 `AGENTS.md`，零配置；或从 checkout 里跑 `codewhale`
Swival	`swival skills add --global …` 先入库，再 `swival skills add ponytail` 激活；命令行用 `$` 前缀显式激活（如 `$ponytail-review`）

Cursor 这一档是整篇教程的重点，第 4 章从安装讲到验证，第 5 章讲它特有的坑。如果想直接跳到最实用的部分，现在去第 4 章。

4规则档：拷一个文件就行

这一档没有注入机制，就是把一份压缩过的规则文本放进助手会读的位置。好处是零风险、可提交进仓库、对团队可见；代价是永远只有一个固定强度，没有命令。

宿主	拷哪个文件到哪
Cursor（只用规则时）	`.cursor/rules/ponytail.mdc` → 项目 `.cursor/rules/`
Windsurf	`.windsurf/rules/ponytail.md`
Cline	`.clinerules/ponytail.md`
Kiro	`.kiro/steering/ponytail.md`（可放全局或项目）
Copilot Chat（VS Code / JetBrains / VS 扩展）	`.github/copilot-instructions.md`
Aider / Zed / Jules / Amp / CodeWhale / Antigravity	根目录 `AGENTS.md`（多数是自动读，零配置）
JetBrains Junie	`AGENTS.md`，但要先去 Settings → Tools → Junie → Project Settings → Guidelines Path 指过去（不是自动的）

同一份规则文本在仓库里有多份对齐副本（.cursor/rules/、.windsurf/rules/、AGENTS.md…）。所以项目维护者改规则时要跑 node scripts/check-rule-copies.js 保证各副本同步——这是他们自己的开发约束，不是你安装时要做的。

5设定每个新会话的默认强度

默认是 full。要改默认值有两个入口，优先级是「环境变量 → 配置文件 → full」：

# 方式一：环境变量（不用重启宿主的话最方便）
export PONYTAIL_DEFAULT_MODE=lite   # lite / full / ultra / off

# 方式二：配置文件
# macOS / Linux: ~/.config/ponytail/config.json
# Windows:        %APPDATA%\ponytail\config.json
{ "defaultMode": "lite" }

默认值写 off 的效果是：不写标志文件、不输出任何东西——等于装上但静音。想彻底停用就用它。

另外还有一个子代理专用的环境变量 PONYTAIL_SUBAGENT_MATCHER，用正则筛选哪些子代理类型才注入规则（例如 explore|general），但它在 Cursor 里完全无效，原因见第 5 章。

6卸载：有一个顺序陷阱

常规卸载就是各宿主自己的移除命令：

宿主	命令
Claude Code	`/plugin remove ponytail`
Codex	`codex plugin remove ponytail`
Devin CLI	`devin plugins remove ponytail`
Grok Build	`grok plugin uninstall ponytail`
pi agent	`pi uninstall ponytail`
Cursor hooks	`node scripts/cursor-hooks.js uninstall`（加 `--project` 对付项目级）
规则档宿主	删掉你拷进去的那个规则文件

但上面这些命令只删插件自己的文件，会留下一些插件写在别处的状态：强度标志文件（~/.claude/.ponytail-active，Cursor 是 ~/.cursor/.ponytail-active）、~/.config/ponytail/config.json、以及 Cursor 的 hooks.json 里那几条。要一起清掉就跑：

node scripts/uninstall.js

顺序陷阱：先跑 uninstall.js，再用宿主的移除命令。因为这个脚本本身也是插件文件——你先把插件删了，脚本就一起没了。如果已经删了，就另 clone 一份仓库来跑。

这个脚本只在 statusLine 指向 ponytail 自己的脚本时才删它，你自己配的 statusLine 不会被碰。

7只想先试一下？最小路径

git clone https://github.com/DietrichGebert/ponytail
node ponytail/scripts/cursor-hooks.js install
# 然后：在 Cursor 里开一个新对话，问它：
# 「Quote the first line of any ponytail context you were given.」

如果它回答的是一行 PONYTAIL MODE ACTIVE — level: full，说明装好了。下一步看第 4 章把原理和验证做扎实，或者看第 6 章开始调强度。