wehub/dietrichgebert--ponytail

Fork 0

Files

T

wehub-resource-sync 487bc5f071

test / test (push) Waiting to run

Details

docs: make Chinese README the default

2026-07-13 09:50:57 +00:00

20 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Ponytail

他一言不发。只写一行。就能跑通。

代码量减少约 54%（最高可达 94%）· 成本降低约 20% · 速度提升约 27% · 100% 安全
_{基于真实 Claude Code 会话，在真实开源仓库（FastAPI + React）上实测，对比同一 agent 未启用 skill 时的表现。约 54% 为 12 项功能任务（Haiku 4.5，n=4）的均值；在 agent 过度实现（如日期选择器）时可达 94%，在代码已足够精简时则接近零。ponytail 保留全部安全护栏，而裸「写一行代码」提示词会丢掉其中一条。（较早的单次基准测试将 80–94% 作为固定数字报告；与公平的 agentic 基线相比，那是单任务上限，而非平均值。）完整报告 · 自行复现。}

_{Español · 한국어}

你认识他。长马尾。椭圆眼镜。在公司待的时间比版本控制还久。你给他看五十行代码；他看一眼，一言不发，换成一行。

Ponytail 把这位资深开发者装进你的 AI agent。

前后对比

你要一个日期选择器。你的 agent 会安装 flatpickr、写一个包装组件、加一份样式表，然后开始讨论时区。

启用 ponytail 后：

<!-- ponytail: browser has one -->
<input type="date">

更多案例见 examples/。

数据

可信的测量方式是真实 agent 做真实工作：无头 Claude Code 会话编辑 tiangolo's full-stack-fastapi-template（真实的 FastAPI + React 仓库），按留下的 git diff 计分。十二张功能工单，同一 agent 分别启用与未启用 skill，n=4，Haiku 4.5。

对比无 skill 基线	LOC	tokens	cost	time	安全
ponytail	-54%	-22%	-20%	-27%	100%
caveman（简洁散文对照组）	-20%	+7%	+3%	+2%	100%
"YAGNI + one-liners" 提示词	-33%	-14%	-21%	-30%	95%

ponytail 是唯一在所有指标上都下降的实验组，也是唯一在做到这点的同时保持完全安全的。降幅最大的是存在真实过度实现陷阱的场景（日期选择器从 404 行减到 23 行，颜色选择器从 287 行减到 23 行，因为它选用原生 <input> 而非组件）；在代码已足够精简时则接近零。完整方法、逐任务表格与局限：benchmarks/results/2026-06-18-agentic.md。

较早的单次生成数据（隔离生成）

五项日常任务，三个模型，三组实验（无 skill、caveman, ponytail），各跑十次，报告中位数。单次提示、单次补全，统计答案行数：

结果显示代码量减少 80–94%。#126 公正地指出，裸模型基线会用散文和选项填充回答，因此该差距部分来自对话基线的人为因素。上文 agentic 数据是修正后、可辩护的版本。用 npx promptfoo eval -c benchmarks/promptfooconfig.yaml 复现单次生成运行。

**规则从来不是「最少 token」。**而是：只写任务所需，且绝不削减验证、错误处理、安全或无障碍（accessibility）。代码之所以精简，是因为有必要，而非代码高尔夫。在遵循阶梯的模型上，更低成本与更低延迟是副作用；简洁推理模型若把思考 token 花在斟酌阶梯上，结果可能相反（在 GPT-5.5 上确实如此）。

工作原理

写代码之前，agent 会在第一个能站住的阶梯处停下：

1. Does this need to exist?   → no: skip it (YAGNI)
2. Already in this codebase?  → reuse it, don't rewrite
3. Stdlib does it?            → use it
4. Native platform feature?   → use it
5. Installed dependency?      → use it
6. One line?                  → one line
7. Only then: the minimum that works

阶梯在理解问题之后运行，而非取而代之：它会阅读变更所涉及的代码，并追踪真实流程，再选择阶梯。对解法偷懒，对阅读从不偷懒。

懒，而非疏忽：信任边界验证、数据丢失处理、安全与无障碍永远不在削减之列。

安装

ponytail 对你要求的最大 effort 也就这些：

Claude Code 与 Codex 插件会运行两个极小的 Node.js 生命周期钩子，因此 node 需要在 PATH 中（Nix/nvm 用户注意：必须出现在非交互式 shell 的 PATH 里）。若没有，skill 仍可用，只是常驻激活会保持静默，而不会在每次提示时报错。

Claude Code

/plugin marketplace add DietrichGebert/ponytail

/plugin install ponytail@ponytail

（安装需分两次发送提示才能生效）

Claude Code Desktop 应用的 Code 标签页步骤相同：在提示框输入上述两条 /plugin 命令，或点击旁边的 + 按钮，选择 Plugins → Add plugin 浏览已配置的市场，并在侧栏 Customize 中管理市场。

Codex

codex plugin marketplace add DietrichGebert/ponytail
codex plugin add ponytail@ponytail

运行 codex 并打开 /hooks，审查并信任其两个生命周期钩子，然后开启新线程。

同一安装方式也适用于 Codex 桌面应用：安装后重启应用即可加载插件。

GitHub Copilot CLI

copilot plugin marketplace add DietrichGebert/ponytail
copilot plugin install ponytail@ponytail

在交互式 Copilot CLI 会话中，使用对应的斜杠命令：

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

Copilot CLI 按插件名称对插件命令进行命名空间划分。例如：

/ponytail:ponytail ultra
/ponytail:ponytail-review

Pi agent harness

pi install git:github.com/DietrichGebert/ponytail

OpenCode

添加到 opencode.json：

{ "plugin": ["@dietrichgebert/ponytail"] }

也可以从 checkout（检出）运行（插件会复用 hooks/ 和 skills/）：

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

在每个回合按当前激活级别注入规则集；并添加 /ponytail 命令（参见命令）。OpenCode 还会自动加载本仓库的 AGENTS.md，因此即使不安装插件也能生效。插件会添加 lite/full/ultra/off 级别。

./ 路径会相对于项目的 opencode.json 解析；若要在多个项目间共享同一份 checkout，请改为指向 .mjs 的绝对路径（它会相对于自身文件定位 hooks/ 和 skills/）。

Gemini CLI

gemini extensions install https://github.com/DietrichGebert/ponytail

每个会话都将规则集作为常驻上下文加载，并注册 /ponytail 命令；skills/ 也会一并提供，在任务需要时激活。 Gemini 适配器有意不提供根级 hooks/hooks.json：Gemini 会自动加载该路径，而 Ponytail 的生命周期钩子使用 Claude/Codex 事件名。

Qoder

Qoder 会从仓库根目录自动加载 AGENTS.md 作为常驻上下文，因此从 checkout 运行 ponytail 无需任何配置。若要使用按项目规则，请将 .qoder/rules/ponytail.md 复制到项目的 .qoder/rules/。六个 ponytail 技能（/ponytail、/ponytail-review、/ponytail-audit、/ponytail-debt、/ponytail-gain、/ponytail-help）可通过 Qoder 的 Skill 系统使用；.qoder-plugin/plugin.json 处的插件清单指向 skills/ 目录。

若要获得完整插件级支持（自动模式激活 + 每次提示注入规则集），请将 hooks/qoder-hooks.json 中的钩子添加到 .qoder/settings.json。将 PONYTAIL_DIR 替换为你的 ponytail checkout 路径。Qoder 的 UserPromptSubmit 钩子会在首次提示时激活默认模式，并在每个回合注入规则集；搭配 task|Task 匹配器的 PreToolUse 会向子代理注入规则集。级别切换（/ponytail lite|full|ultra|off）会自动生效。

Antigravity CLI

Google 正在将 Gemini CLI 重命名为 Antigravity CLI（agy 二进制文件）；同一扩展也可安装到该环境：

agy plugin install https://github.com/DietrichGebert/ponytail

它会复用本仓库的 gemini-extension.json。一个区别是：Antigravity 将 /ponytail 命令转换为技能，因此你需要在聊天中输入它们（例如将 /ponytail-review 作为消息发送），而不是从斜杠菜单中选择。在迁移完成之前（约 2026 年 6 月 18 日），gemini extensions install 仍可使用。若要以常驻规则方式运行，将规则集放入 .agents/rules/ 即可。

Hermes Agent

hermes plugins install DietrichGebert/ponytail --enable

安装后请重启 Hermes。插件会在每次 LLM 回合前注入当前激活的 Ponytail 模式，将捆绑技能注册为 ponytail:<skill>，并添加 /ponytail、/ponytail-review、/ponytail-audit、/ponytail-debt、/ponytail-gain 和 /ponytail-help。在共享网关中，请通过 Hermes 斜杠命令访问控制将 /ponytail 限制为受信任用户；运行模式为进程本地。

CodeWhale

从项目根目录读取 AGENTS.md，零配置。将 AGENTS.md 复制到项目，或从本仓库的 checkout 运行 codewhale。仅此而已。

Swival

先将集合暂存到库中，再添加所需技能：

swival skills add --global https://github.com/DietrichGebert/ponytail  # stage into ~/.config/swival/library
swival skills add ponytail                                             # install the collection into this project
swival skills add --global ponytail                                    # or activate it in every project

Swival 还会从项目根目录读取 AGENTS.md，并全局读取 ~/.config/swival/AGENTS.md（仅指令的回退方案）。

在命令行中，使用 $ 前缀可显式激活某个技能。例如：$ponytail-review。

Devin CLI

devin plugins install DietrichGebert/ponytail

将 ponytail 安装为 Devin 插件；技能以 /ponytail:ponytail、/ponytail:ponytail-review 等形式提供。

OpenClaw

clawhub install ponytail

从 ClawHub 将 ponytail 安装为 OpenClaw 技能；review、audit、debt、gain 和 help 技能以同样方式安装（clawhub install ponytail-review 等）。OpenClaw 会在编码任务中应用它，并同时以 /ponytail 命令形式暴露。若不使用 ClawHub，请将 .openclaw/skills/ponytail 复制到 ~/.openclaw/skills/。

就这样。他会感到骄傲。他不会说出口。

每个会话都会激活，并提供少量命令（参见命令）。当代码库让你本人深受其害时，可使用 /ponytail ultra。启动及模式切换时的文本会显示当前模式。

可通过 PONYTAIL_DEFAULT_MODE 环境变量（lite/full/ultra/off），或在 ~/.config/ponytail/config.json 中设置 defaultMode 字段（Windows 上为 %APPDATA%\ponytail\config.json），为每个新会话设置级别。默认为 full。

激活后，规则集还会注入通过 Agent 工具生成的每个子代理。若只想作用于特定代理类型（例如不对只读搜索代理生效），请将 PONYTAIL_SUBAGENT_MATCHER 环境变量设为正则表达式，对照子代理的 agent_type 进行匹配。该匹配未锚定且忽略大小写：explore|general 可匹配两者之一，^general$ 为精确匹配，插件代理类型形如 plugin:name。未设置时表示注入所有子代理（默认）；无效正则，或平台未报告类型的子代理，也会回退为注入。

Cursor、Windsurf、Cline、GitHub Copilot Chat（VS Code、JetBrains 和 Visual Studio 编辑器扩展，而非安装中介绍的独立 Copilot CLI）、Aider、Kiro、Zed、CodeWhale、Swival、Qoder：从本仓库复制对应的规则文件（.cursor/rules/、.windsurf/rules/、.clinerules/、.github/copilot-instructions.md、AGENTS.md、.kiro/steering/、.qoder/rules/）。

Kiro：将 .kiro/steering/ponytail.md 复制到 ~/.kiro/steering/（全局），或复制到项目中的 .kiro/steering/。

GitHub Copilot CLI 回退方案（仅指令模式）：它会在项目中读取 AGENTS.md 和 .github/copilot-instructions.md，或将规则复制到 ~/.copilot/copilot-instructions.md，以便在每个项目中运行 ponytail。该路径保留常驻指导，但不会添加插件模式切换或钩子。

安装了 Codex 扩展的 VS Code 会读取 AGENTS.md（本仓库已提供），因此从仓库根目录即可使用，无需配置（~/.codex/AGENTS.md 可使 Codex 全局生效）。

在 Settings → Tools → Junie → Project Settings → Guidelines Path 中指向该路径后，JetBrains Junie 即可读取 AGENTS.md（目前尚不能自动识别）。本仓库提供 AGENTS.md；.junie/guidelines.md 是 Junie 的旧版路径。

Amp（Sourcegraph）会从工作目录及其父目录向上读取 AGENTS.md，直至 $HOME（本仓库已提供），因此无需配置即可使用（~/.config/amp/AGENTS.md 可全局生效）。

Jules（Google）会从仓库根目录读取 AGENTS.md（本仓库已提供），因此无需配置即可加载规则集。

各文件与代理的对应关系：Agent portability。

卸载

宿主	命令
Claude Code	`/plugin remove ponytail`
Codex	`codex plugin remove ponytail`
Devin CLI	`devin plugins remove ponytail`
Pi agent	`pi uninstall ponytail`
Cursor / Windsurf / Cline / Qoder / 等	删除已复制的规则文件

这些命令会移除插件自身的文件。它们会留下 ponytail 写入插件文件夹外的一小部分状态：模式标记、~/.config/ponytail/config.json，以及（如果你接受了设置提示）~/.claude/settings.json 中的一条 statusLine 记录。运行 node scripts/uninstall.js 也会清理这些残留。请在上方的主机移除命令之前运行它——脚本本身属于插件文件，因此先移除插件会删除它（也可以从本仓库的另一个克隆中运行）。它只会在状态栏记录指向 ponytail 自身脚本时才会移除该记录，因此你自己设置的状态栏条目不会被触碰。

命令

命令	功能
`/ponytail [lite \| full \| ultra \| off]`	设置强度等级，或将其关闭。不加参数则显示当前等级。
`/ponytail-review`	审查当前差异中的过度工程化问题，返回待删除列表。
`/ponytail-audit`	审计整个仓库的过度工程化问题，而不仅仅是差异部分。
`/ponytail-debt`	将已延后的 `ponytail:` 快捷键收集到账本中，避免"以后再做"变成"永远不做"。
`/ponytail-gain`	显示基准测试的影响得分榜（更少的代码、更低的成本、更高的速度）。
`/ponytail-help`	上述命令的快速参考。

命令需要具备技能能力的宿主（Claude Code、Codex、Devin CLI、OpenCode、Gemini、pi、Swival、Hermes Agent、Qoder）。在 Codex 中它们作为技能使用，通过 @（@ponytail-review）调用。仅指令适配器（Cursor、Windsurf、Cline、Copilot、Kiro、Antigravity）加载始终生效的规则集，不含命令。

开发

更改紧凑规则文本时，请保持各代理副本同步：

node scripts/check-rule-copies.js
npm test

OpenClaw 技能包（.openclaw/skills/）由 skills/ 生成；更改技能后重新运行 node scripts/build-openclaw-skills.js，测试套件会在技能包过时时失败。要将技能发布到 ClawHub，先运行 clawhub login，再运行 node scripts/publish-openclaw-skills.js（它会以 package.json 版本发布全部六个技能；传入 --dry-run 可预览）。

正确性基准测试会启动 Python 进行邮件和 CSV 检查；系统会优先尝试 python3，再尝试 python。CSV 检查需要在本地安装 pandas。

常见问题

需要配置文件吗？ 不需要。可选的 ~/.config/ponytail/config.json 或 PONYTAIL_DEFAULT_MODE 环境变量可以设置默认等级，但并非必需。

如果我确实需要那个 120 行的缓存类怎么办？ 你不需要。如果你坚持要，他会给你写。慢慢地。正确地。一边看着你写。

它能扩展吗？ 你从未写过的代码可以无限扩展。零 Bug、零 CVE、自诞生以来 100% 正常运行。

为什么叫"ponytail"？ 你心知肚明。

赞助商

许可证

MIT。最简短的可用许可证。

Star 历史

USD 预算：$0/$3；剩余 $3。

^{由 nanobebe / GreenPill / @karmatic 创建。}

20 KiB Raw Permalink Blame History Unescape Escape