BorisLoveDev/dsh-plugin-ponytail

dsh-plugin-ponytail

ponytail —— “懒惰资深开发者模式” ——
作为原生 DeepSeek Harness
插件。

上游 ponytail 为 Claude Code、Codex、Cursor、OpenCode、Kiro、
Windsurf 等提供了适配器，但没有为 DSH 提供：它的常驻层是一个 UserPromptSubmit
生命周期钩子，而 DSH 代理没有这个钩子。本包在 DSH 实际存在的扩展点上重建了该层，
因此你无需修补上游，也无需在仓库中植入生成的文件，就能获得参考行为。

它贡献了什么

| 贡献 | DSH 扩展点 |
|---|---|
| 常驻规则，针对每个提示重新计算 | systemPrompt.context() |
| 六个 ponytail 技能，仅在模式开启时列出 | skills.registerProvider() |
| /ponytail lite\|full\|ultra\|off\|status | commands.register() |

不会向你的项目中写入任何内容：没有 AGENTS.local.md，没有
.agents/skills 中的符号链接。唯一的产物是你已经拥有的 .ponytail/ 目录。

与其他 DSH ponytail 插件的关系

已经存在另外两个移植版本，它们覆盖了不同的部分：

- dsh-ponytail（ccll）将
@dietrichgebert/ponytail 作为依赖项内置，把规则集作为全局
系统提示词部分注入（也会触达子代理），将六个技能添加为运行时
技能，并检测“停止 ponytail”/“普通模式”的停用指令。全局且
按会话生效。
- dsh-ponytail-skills
（gongyijie85，仓库 gongyijie85/dsh-ponytail）将六个技能打包在
包内，并且只注册一个 ctx.skills 提供者。仅技能：它
不注入规则，因此风格是在模型选择加载
技能时被采用，而不是在每个提示上强制执行。
- 本包：常驻规则加上技能加上命令，通过
.ponytail/ 的存在来限定到某个项目。

|  | dsh-ponytail | dsh-ponytail-skills | 本包 |
|---|---|---|---|
| 常驻规则 | 是（系统提示词部分） | 否 | 是（运行时上下文，或一个部分） |
| 技能 | 6 个，在挂载时注册 | 6 个，来自包内的提供者 | .ponytail/skills/ 中的任何内容 |
| /ponytail 命令 | 是 | 否 | 是 |
| 停用手势 | 是 | 否 | 是 |
| 哪些项目会获得它 | 所有 | 所有 | 仅 cwd 之上存在 .ponytail/ 的项目 |
| 模式存储 | 进程内，按会话 | 不适用 | .ponytail/state，磁盘上，按项目 |
| 恢复会话后的模式 | 回到默认值 | 不适用 | 保留 |
| 上游文本 | 运行时 require | 随包提供 | 由你自己的工具链内置到 .ponytail/ |
| 名称/调用 frontmatter 规则 | 不适用 | 遵循内置提供者 | 遵循内置提供者 |

从 dsh-ponytail 借鉴的想法，因为它们是对的：可选的按功能
改为软性 inject 而非硬性 inject（没有命令面的 profile 绝不能丢失规则）、对未知配置键的显式拒绝、整条消息停用手势、/ponytail default 命令，以及随包发布的类型。

思路取自 dsh-ponytail-skills：遵循内置 provider 的 frontmatter 契约——disable-model-invocation / user-invocable 调用策略以及 kebab-case 名称语法，因此放在 .ponytail/skills/ 中的 skill 的行为与放在 .agents/skills/ 中完全一致。

本包贡献的思路：通过从 cwd 向上遍历实现按项目 opt-in（这会跨越嵌套的仓库根目录）、将模式状态保存在磁盘上以便在 resume 和 restart 后仍然保留，以及将 systemPrompt.context 作为默认放置位置，这样级别变化不会扰动 system-prompt 前缀。

只安装其中之一，不要两个都装：dsh-ponytail 和本包各自注册一个 /ponytail 命令，第二次注册会失败。

如果你希望 ponytail 在所有地方都生效且无需按项目设置，请使用 dsh-ponytail。如果你只希望 skill 可用，并且乐意让模型自行决定何时使用它们，dsh-ponytail-skills 是更小的安装。如果你希望按项目 opt-in、在每条 prompt 上强制执行规则，并将模式与代码放在一起，请使用本包。

安装

dsh plugin --profile web add dsh-plugin-ponytail

manifest 声明了 dsh.bundle.patch，因此该包也会加入 dsh.profile.bundles，加载器会将其 patch 作为又一层应用。重启 profile 以便新层启动。

如果要从 checkout 而非 registry 安装：

dsh plugin --profile web add /path/to/dsh-plugin-ponytail

挂载到正在运行的 host

DSH 在启动时从 profile 的 package.json 读取 dsh.profile.bundles，因此 bundle 通常会在下次启动时生效。带有 patchReload: live 的 profile 会持续监视其 patch 文件，因此正在运行的 host 无需重启即可拾取该行。将包保留在 dependencies 中，从 dsh.profile.bundles 中移除它，并向 profile 自己的 patch 层（~/.dsh/profiles/web/cordis.patch.yml）添加一个纯 insert：

- insert:
- id: ponytail
name: dsh-plugin-ponytail

在该 insert 存在期间，将其排除在 dsh.profile.bundles 之外。applyEntryPatches 不会按 id 对 insert 去重，因此该行会被挂载两次——一次来自 bundle patch，一次来自 profile 层。

设置项目

在找到 .ponytail/ 目录之前，该插件不会贡献任何内容。存在即 opt-in。

mkdir -p .ponytail/skills
rules.md            — 静态规则（上游 AGENTS.md）
skills//SKILL.md   — 供应商 skill
state               — off | lite | full | ultra
printf 'full\n' > .ponytail/state

将上游的 skills/ 和 AGENTS.md 复制到 .ponytail/ 中即可：

git clone --depth 1 https://github.com/DietrichGebert/ponytail /tmp/ponytail
mkdir -p .ponytail/skills
cp /tmp/ponytail/AGENTS.md .ponytail/rules.mdsh
cp -R /tmp/ponytail/skills/. .ponytail/skills/
printf 'full\n' > .ponytail/state

你自己添加的技能遵循内置文件系统提供者的约定，因此它们的行为与在 .agents/skills/ 中完全一致：name 必须是 kebab-case，而 disable-model-invocation: true / user-invocable: false 控制谁可以调用它们。名称或调用 frontmatter 无效的技能会被跳过，而不是半注册。

目录是如何被找到的

插件从会话的工作目录向上遍历，直到找到 .ponytail/，并在文件系统根目录处停止。

这一条规则就是整个作用域模型，它的行为与种在单个项目树中的文件不同：

- 在嵌套仓库中启动的会话仍然能找到 .ponytail/。如果持有 .ponytail/ 的树中包含一个本身就是 git 仓库的检出，那么在该检出内启动的会话也会被覆盖，因为遍历会跨越项目根目录，而不是在最近的一个处停止。
- 每个后代目录都继承该模式，无需按项目安装。
- 同级项目不受影响：它们上方没有 .ponytail/ 就意味着没有规则，也没有技能。

级别
sh
/ponytail                        # 显示当前级别、目录和技能数量
/ponytail lite                   # 用一行说明更省事的替代方案
/ponytail full                   # 强制执行阶梯（默认）
/ponytail ultra                  # YAGNI 极端主义者，删除先于添加
/ponytail off                    # 撤回规则和技能
/ponytail default lite           # 跨项目持久化用户级默认值

/ponytail  写入 .ponytail/state。规则会在下一个提示时重新计算，因此 off 会立即生效，无需重新生成任何内容。

上游的整条消息停用手势同样有效：一条恰好为 stop ponytail 或 normal mode 的消息会将该项目的模式切换为 off。仅仅提及该短语的消息（“add a normal mode toggle”）则不会。

/ponytail default  写入上游自己的 $XDG_CONFIG_HOME/ponytail/config.json（或 ~/.config/ponytail/config.json、%APPDATA%\ponytail\config.json），这与参考适配器以及本插件自身的解析顺序所读取的是同一个文件。当不存在 .ponytail/state 时，使用的就是该级别。

级别的解析方式与上游完全一致：先是 PONYTAIL_DEFAULT_MODE，然后是配置文件中的 defaultMode，再是本行的 defaultMode，最后是 full。按项目的 .ponytail/state 优先于所有这些。

ponytail-review 是一个技能，而不是一个级别；/ponytail review 会说明这一点。

模型看到的内容

上游自己的载荷，逐字节一致：

PONYTAIL MODE ACTIVE — level:

filterSkillBodyForMode 是对上游 hooks/ponytail-instructions.js 的忠实移植，包括它的两个微妙之处：只有强度
表格行和带引号的示例是按级别区分的，而一个普通的规则条目，只要其标签恰好以级别词开头，就会原样保留。当
skills/ponytail/SKILL.md 缺失时，改用 .ponytail/rules.md。

已针对随附的 SKILL.md 与上游进行验证：对于 lite、full
和 ultra 完全一致，仅末尾换行符有差异。

上下文、缓存与成本

规则会在每个提示词中重新计算，因此有理由质疑这是否会搅动提示词前缀并消耗缓存命中。实测结果：

- 系统提示词从不被触碰。 默认的 placement: context 是一个
持久的用户角色快照，而非系统提示词的一部分。可缓存的前缀——
系统提示词和工具 schema——不包含任何 ponytail 文本。
- 载荷字节稳定。 对同一组未更改的文件渲染三次，
包括从全新挂载点渲染，会产生完全相同的字节，且不携带任何
时间戳、路径、摘要或进程 ID。这一点由测试断言，因此未来的
修改无法悄悄使其变得不确定。
- 未更改的贡献不会被重新发送。 测试框架会将渲染出的
运行时上下文与它已持有的快照进行比较，仅在文本不同时才发出消息；
当文本确实不同时，新文本会替换旧文本，而不是
累积。在一个使用同一接缝的 209 步实时会话上实测：恰好
一条快照消息。
- 技能顺序不会抖动。 此提供程序读取 readdirSync，其顺序并不
保证，但 ctx.skills.snapshot() 会排序，且目录摘要仅对
[name, description] 对进行哈希，因此顺序和元数据都无法触发
重新发出。
- 每个会话添加的内容： 规则载荷（full 下为 5228 个字符）
加上六个技能目录条目（2368 个字符，每个描述上限为 500）——
大约 2.1k token，此后被缓存。/ponytail 不会向模型
上下文添加任何内容；命令面向人类，从不进入提示词。

唯一会改变文本的是你所做的更改：

- /ponytail lite|full|ultra（或编辑 .ponytail/state）会更改一次；
到那时为止的前缀保持缓存，因此这是一次普通的缓存未命中。
- payload: rules 使用 rules.md（2590 个字符）而非上游按模式
过滤的 SKILL.md 正文（5228），用于大约一半的常驻文本，代价是
失去按级别过滤。
- 重新启用基于文件的层（bash .ponytail/switch on）会将规则
第二次作为工作区指令传递，使文本翻倍。

双规则集警告

最后一种配置是唯一真正的陷阱，因此插件会检测它。当从
ponytail 根目录到会话 cwd 的任意位置存在 AGENTS.md、CLAUDE.md、AGENTS.local.md 或 CLAUDE.local.md
且带有上游 ponytail 标记时，代理会在提示词中收到警告，且 /ponytail status 会报告：

duplicate : /path/to/AGENTS.local.md — rules also arrive as workspace instructions
该警告本身就是一个提示条目，因此健康的项目不会贡献任何内容，规则负载与上游保持字节级一致。它要求出现上游短语（PONYTAIL MODE ACTIVE、"lazy senior dev"、"best code is the code never written"），而不仅仅是 "ponytail" 这个词，因此仅提及该名称的项目不会被标记。设置 warnOnDuplicateInstructions: false 可将其关闭。

配置

该行接受一个可选配置。每个字段都是可选的。
yaml
- insert:
- id: ponytail
name: dsh-plugin-ponytail
config:
dirName: .ponytail # directory searched for, upward from the cwd
placement: context # context (default) | section
payload: skill # skill (default, upstream payload) | rules
skills: true # serve .ponytail/skills/
skillRank: 260 # precedence vs the built-in roots (project 100/200, custom 300)
command: true # register /ponytail
commandName: ponytail
contextOrder: 130 # placement after the harness policy contexts (110-120)
contextName: ponytail
defaultMode: full # used when state is absent and upstream resolves nothing
warnOnDuplicateInstructions: true # warn the agent when the rules arrive twice

placement: section 会注册一个系统提示区段，而不是运行时上下文。仅当你需要将规则固定到系统提示中时才使用它：每当级别变化时它都会改变提示前缀，而默认的 context 放置方式与 harness 用于工作区指令的持久用户角色快照形态相同。

注意事项

- minimal 代理预设会调用 suppressRuntimeContext()，这会关闭该作用域内的所有动态上下文。在默认的 placement: context 下，规则在那里是静默的；如果你需要在 minimal 上使用它们，请使用 placement: section。
- 目录读取会列出技能，但不会加载其正文；每个正文会在技能实际被使用时从磁盘读取。
- 该插件会提供 .ponytail/skills/ 中的任何内容。保持该目录为最新是上游的问题，而不是本包的问题。

从基于文件的安装迁移

如果你之前通过生成的 AGENTS.local.md 以及 .agents/skills/ 中的符号链接来接入 ponytail，请关闭该层并保留 .ponytail/：
sh
bash .ponytail/switch off # removes AGENTS.local.md and the symlinks

该插件读取相同的 .ponytail/rules.md、.ponytail/skills/ 和 .ponytail/state，因此其他任何内容都无需移动。同时保留两层会导致规则显示两次。

发现与列出

DSH 没有第一方插件注册表：dsh plugin 会在 profile 内转发到 pnpm，因此 npm 就是分发渠道。社区目录是 DSH Plugin Hub，它通过 npm 关键词 dsh-plugin 和 GitHub 主题 dsh-plugin 来索引插件。

- npm：npm search dsh-plugin
- 在代理内部：安装 dsh-find-plugin 并搜索 dsh-plugin 主题
- 在 GUI 中：dsh plugin --profile web add dsh-plugin 会向设置中添加一个插件市场

要列出一个插件：使用 dsh-plugin 关键字发布到 npm，为仓库添加 dsh-plugin 主题，然后在  提交以供审核。

开发
sh
pnpm install
pnpm test

test/selfcheck.test.mjs 针对三个宿主注册表的桩件驱动该插件，因此发现、级别解析、模式过滤、技能提供程序以及 /ponytail 处理程序都能在没有运行测试框架的情况下得到检验。

许可证

MIT。ponytail 本身是 Dietrich Gebert 的一个独立项目，遵循其自己的许可证；本包仅对其进行了适配。