@njuptlzf/dsh-ponytail

Readme

# dsh-ponytail

<details open>
<summary><b>English</b> · <i>点击下方「中文」切换中文</i></summary>

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that installs the [Ponytail](https://github.com/DietrichGebert/ponytail) "lazy senior developer" ruleset. It mirrors upstream's two-layer split:

- an **always-on, mode-switchable** system-prompt section built from the *compact* ruleset (~2.5 KB), and
- the **full** ruleset + 5 companion skills as on-demand `/` skills.

**This repo vendors no skill content.** On first boot it fetches once from upstream `DietrichGebert/ponytail`, caches to disk, and never re-fetches or hand-syncs afterwards.

### What it does

1. **Always-on section (lean)** — the compact ruleset (`.agents/rules/ponytail.md`, ~2.5 KB) as a system-prompt section, cached at `~/.dsh/ponytail-cache/compact.md`. Switch the level per session with `/ponytail lite|full|ultra|off`; `off` empties the section so the tokens are actually saved. Default `full`.
2. **On-demand skills (user-only)** — the full ruleset (`ponytail`) and the 5 companions (`ponytail-help` / `ponytail-audit` / `ponytail-debt` / `ponytail-gain` / `ponytail-review`) written once to `~/.dsh/skills/<name>/SKILL.md`, invocable from the `/` palette. Each file's frontmatter carries `disable-model-invocation: true`, so these skills stay **user-invocable** (shown in `/` with a "user only" tag) but are **not advertised to the model** — no `available_skills` catalog cost, no auto-load on "ANY coding task". The always-on compact section is the only model-facing copy.

### Install

```sh
dsh plugin --profile web add @njuptlzf/dsh-ponytail
# without a global dsh:
npx @deepseek-ai/dsh plugin --profile web add @njuptlzf/dsh-ponytail
# from git instead: dsh plugin --profile web add github:njuptlzf/dsh-ponytail
```

Restart `dsh web` after install. The first boot fetches once and caches, so later boots — online or offline — never touch the network. To update the skills, delete the corresponding cache/skill files and restart.

### Usage

- `/ponytail` — report the current level; `/ponytail lite|full|ultra|off` — switch it. Mode is per-session (`agent.id`), so one conversation's `off` does not affect another.
- The 6 skills stay in the `/` palette, tagged "user only"; type `/` and pick one (e.g. `/ponytail-review`) to trigger it manually — the model never pulls them in unprompted.

### dsh-ponytail vs codex-ponytail

| | codex-ponytail (upstream Codex plugin) | dsh-ponytail (this plugin) |
|---|---|---|
| Mechanism | Codex plugin: `SessionStart` + `SubagentStart` + `UserPromptSubmit` lifecycle hooks | DSH bundle: `systemPrompt` section + `commands` service |
| Always-on content | full ruleset, mode-filtered, at `SessionStart` | **compact ruleset (~2.5 KB)** every step |
| Per-turn cost | full rules only at session start / compact / subagent; one mode line per turn | ~2.5 KB re-rendered per step (DSH `systemPrompt` per-step semantics) |
| `off` | `UserPromptSubmit` stops injecting, tokens saved | section renders empty, tokens saved (parity) |
| Levels | `lite`/`full`/`ultra` filter the full ruleset's per-mode rows | level carried as header + behavior; per-mode detail lives in the on-demand full skill |
| Session isolation | single-session process → process-level flag file | multi-session process → per `agent.id` (== `session.id`) |
| Compaction | `SessionStart` re-fires on the `compact` matcher | compaction only shatters history, never the system prompt (inherent) |
| Subagents | `SubagentStart` + `PONYTAIL_SUBAGENT_MATCHER` | global section inherits into subagents via composition (no patch expected) |
| On-demand detail | `ponytail` skill | `ponytail` skill (parity) |
| Fallback | inline `getFallbackInstructions` | TODO (see `OPTIMIZATION_PLAN.md`) |

### Structure

```
dsh-ponytail/
├── index.js               # host plugin: fetch once → compact always-on + mirror full/companions
├── package.json           # dsh.bundle.patch declaration
├── cordis.patch.yml       # mount row
├── OPTIMIZATION_PLAN.md   # full design rationale + comparison
├── README.md
└── LICENSE                # MIT
```

### Attribution

Skill content comes from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) (MIT), fetched at runtime. The plugin wrapper is MIT © 2026 Kasakaze (njuptlzf).

</details>

<details>
<summary><b>中文</b> · <i>点击上方「English」切换英文</i></summary>

一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件：把 [Ponytail](https://github.com/DietrichGebert/ponytail)「懒高级工程师」规范接入进来，对标上游的两层结构：

- **常驻、可按档切换**的 system-prompt section，用 **精简规则**（~2.5 KB）构建；
- **全文规则** + 5 个同伴技能作为按需 `/` skill。

**本仓库不存技能内容**——首次启动从上游 `DietrichGebert/ponytail` 抓取一次并落盘缓存，之后不再联网、永不手工同步。

### 它做什么

1. **常驻 section（精简）** — 精简规则（`.agents/rules/ponytail.md`，~2.5 KB）作为 system-prompt section，缓存于 `~/.dsh/ponytail-cache/compact.md`。用 `/ponytail lite|full|ultra|off` 按会话切档；`off` 会让 section 渲染为空、真的省回 token。默认 `full`。
2. **按需 skills（仅用户可用）** — 全文规则（`ponytail`）和 5 个同伴（`ponytail-help` / `ponytail-audit` / `ponytail-debt` / `ponytail-gain` / `ponytail-review`）写入 `~/.dsh/skills/<name>/SKILL.md`，`/` 面板可调。每个 skill 的 frontmatter 都带 `disable-model-invocation: true`：技能保持**仅用户可调用**（在 `/` 里显示、带「仅用户可用」标签），但**不对模型公开**——不进 `available_skills` catalog、不会因描述写着 "ANY coding task" 被自动加载。常驻精简 section 是唯一面向模型的那一份。

### 安装

```sh
dsh plugin --profile web add @njuptlzf/dsh-ponytail
# 无全局 dsh：
npx @deepseek-ai/dsh plugin --profile web add @njuptlzf/dsh-ponytail
# 或者从 git 安装：dsh plugin --profile web add github:njuptlzf/dsh-ponytail
```

安装后**重启 `dsh web`**：首次启动联网抓取一次并缓存，之后无论在线离线都不再联网。要更新技能，删对应缓存/技能文件再重启即可触发重抓。

### 使用

- `/ponytail` — 报告当前档；`/ponytail lite|full|ultra|off` — 切档。档位按会话（`agent.id`）隔离，一个会话的 `off` 不影响其它会话。
- 6 个技能常驻 `/` 面板、标「仅用户可用」；打 `/` 看候选、手工选一个（如 `/ponytail-review`）触发——模型不会未经请求就自动加载它们。

### dsh-ponytail vs codex-ponytail

| | codex-ponytail（上游官方 Codex 插件） | dsh-ponytail（本插件） |
|---|---|---|
| 接入机制 | Codex 插件：`SessionStart` + `SubagentStart` + `UserPromptSubmit` 三个 lifecycle hook | DSH bundle：`systemPrompt` section + `commands` 服务 |
| 常驻内容 | `SessionStart` 时注入**全文**（按 mode 过滤） | 每步注入**精简规则（~2.5 KB）** |
| 每轮成本 | 全文只在会话开始/压缩/子代理时；每轮只一行 mode 标记 | 每步重渲 ~2.5 KB（DSH `systemPrompt` 的 per-step 语义） |
| off | `UserPromptSubmit` 停止注入、省回 token | section 渲染为空、省回 token（对齐） |
| 强度档 | `lite`/`full`/`ultra` 过滤全文对应档的内容 | 档位以 header + 行为承载；分档细节落在按需全文 skill |
| 会话隔离 | 单会话进程 → 进程级 flag 文件 | 多会话单进程 → 按 `agent.id`（== `session.id`）隔离 |
| 压缩/遗忘 | `SessionStart` 的 `compact` matcher 在压缩时重注入 | 压缩只 shadow 历史、不动 system prompt（天然免疫） |
| 子代理 | `SubagentStart` + `PONYTAIL_SUBAGENT_MATCHER` | 全局 section 随 composition 继承子代理（预期无需补丁） |
| 按需详情 | `ponytail` skill | `ponytail` skill（对齐） |
| 兜底 | 内置 `getFallbackInstructions` | 待补（见 `OPTIMIZATION_PLAN.md`） |

### 结构

```
dsh-ponytail/
├── index.js               # host 插件：只抓一次 → 精简常驻 + 镜像全文/同伴
├── package.json           # dsh.bundle.patch 声明
├── cordis.patch.yml       # 挂载行
├── OPTIMIZATION_PLAN.md   # 完整设计说明与对比
├── README.md
└── LICENSE                # MIT
```

### 归属

技能内容来自 [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)（MIT），运行时抓取。插件包装层 MIT © 2026 Kasakaze (njuptlzf)。

</details>