dsh-ponytail
将 DietrichGebert/ponytail 的极简编码原则和相关 Skill 适配到 DeepSeek Harness，提供 YAGNI 决策阶梯、Lite / Full / Ultra / Off 会话级模式，以及一组用于代码精简、审查、审计和技术债追踪的 Skill。
本项目对齐上游核心理念和主要工作流，但 DSH 的模型循环、Prompt 组装、Skill 机制和工具调用不同。上游 Benchmark 仅作参考，不代表本适配版具有相同的 Token、成本或延迟收益（详见「效率（条件性收益，非保证）」）。
GitHub Release 下载
- 最新版（latest）：
https://github.com/MengYuil/dsh-ponytail/releases/latest/download/mengyuly-dsh-ponytail.tgz
- 固定版本 v0.3.2（按 Tag 不可变）：
https://github.com/MengYuil/dsh-ponytail/releases/download/v0.3.2/mengyuly-dsh-ponytail.tgz
说明：
- latest：适合快速安装体验，会随最新 Release 更新；固定资产名
mengyuly-dsh-ponytail.tgz 在每个 Release 中保持不变，因此该 URL
不会因版本号变化而失效，不适合作为不可变依赖。
- 固定版本：适合可复现安装，URL 中固定 Tag（如
v0.3.2），按 Tag
不可变；资产名同样为 mengyuly-dsh-ponytail.tgz。
- npm 安装仍走 npm Registry 或
dsh plugin 命令。
- 固定资产名由
scripts/release-assets.mjs 生成并验证（node scripts/release-assets.mjs，仅仓库维护者）。
安装
装进某个 profile（web 可换成 tui/自定义名）：
# 方式一：本地链接（当前 dsh 核 ≥ 0.1.x）
dsh plugin --profile web add link:$(pwd)
# 方式二：GitHub 直接装
dsh plugin --profile web add github:MengYuil/dsh-ponytail
# 方式三：Release 打包件（先下 tgz——latest 固定资产名恒定）
# https://github.com/MengYuil/dsh-ponytail/releases/latest/download/mengyuly-dsh-ponytail.tgz
dsh plugin --profile web add file:./mengyuly-dsh-ponytail.tgz
# 方式四：npm
dsh plugin --profile web add @mengyuly/dsh-ponytail
装完重启 profile 生效（dsh web / dsh tui）。装载完成后，会话技能目录里会出现 6 个 ponytail* 技能，发 /ponytail-help 立即验证。
lib/index.js 是自包含 bundle（已内联 dsh-llm / dsh-skill——npm 无兼容版本），运行时依赖两个已发布的 peer：@deepseek-ai/cordis（4.0.1）与 @deepseek-ai/schemastery（3.18.x）。schemastery 刻意保持外置而非内联：其 schema DSL 用 new Function 编译 callback 字符串，外置后发行产物不含任何动态代码执行（CI 有专门检查）。GitHub / tgz / npm 三种安装方式都不需要 dsh 源码树。
说明：src/ 是源码、lib/ 是预构建产物（开箱即可加载，无需编译）。源码主仓在 deepseek-harness 的 packages/community/ponytail；改源码后用 DSH_CHECKOUT=/path/to/deepseek-harness node scripts/sync-dist.mjs 重建并同步完整 lib/（见下「发行维护」）。
功能
效率（条件性收益，非保证）
Ponytail 会给每次模型请求增加一小段固定规则。它的收益是有条件的：
当 Agent 容易过度设计时，减少的代码、工具调用和返工可能抵消甚至超过
这部分开销；当任务本来已经很简单时，收益可能接近零，甚至出现额外输入
开销。它不是"省 Token 开关"，也不保证跨模型省钱——某些推理模型可能因
prompt 与推理开销变得更贵。
本 DSH 适配版当前 Prompt 段实测大小（node scripts/measure-prompt.mjs，从真实
getPonytailInstructions() 生成）：
| 档位 | 字符数 | UTF-8 字节 | 说明 |
|---|
| lite | 1915 | 1917 | 实测生成 |
| full | 3022 | 3038 | 实测生成 |
| ultra | 2797 | 2813 | 实测生成 |
| off | 0 | 0 | 不注入 |
这些是 Prompt 体积测量，不是账单金额，也不是对所有模型成立的节省
比例（无统一 tokenizer，measure:prompt 输出中 estimated_tokens 为
null；字符数/4 只是粗略估算）。同模式字节级稳定，KV-cache 前缀命中。
上游数据不是本 DSH 适配版的保证：上游 Ponytail 的 single-shot
（代码 −8094%、成本 −4275%、延迟 3.1–5.8×）与 agentic（LOC −54% 等）
结果仅作参考；DSH 适配版未建立稳定的 Token/成本/延迟节省率。DSH
Smoke Benchmark 只提供方向性证据（见 docs/dsh-smoke-summary.md）。
已知限制
- 档位差异在规则语义上（见上），三者 Prompt 体积相近（实测见上表）。
- 上游 Claude 专属的 statusline 徽标无 DSH 对应物，MCP 服务器因 DSH 有一等 system-prompt 注入点而弃用。
- 用户
config.json 热更新；PONYTAIL_DEFAULT_MODE 与 Profile config 需重启生效。
- 发行
lib/ 是预编译产物；改源码请回主仓重建后同步。
兼容矩阵（实测，不虚构）
| 组件 | 已验证环境 | 备注 |
|---|
| Node.js | 22.x / 24.x | CI 矩阵 4 组合全绿 |
| OS | ubuntu-latest / windows-latest | CI 矩阵 |
| DSH | commit b150a551（构建所用 checkout） | 与正式发布版本的精确对应关系待确认 |
| Cordis | 4.0.1（构建所用 vendor） | 同上 |
| web profile | 已验证 | 本机真实 profile 长期运行 + 三路径隔离安装实测（npm / GitHub / tgz） |
| tui profile | 未验证 | 未在 tui profile 中启动测试 |
| headless profile | 未验证 | 未完整启动；插件单元测试运行于无 UI 环境 |
| npm tarball | 已验证 | 内容/版本/安装后 smoke/NodeNext consumer |
dist-provenance.json 记录实际构建来源（checkout commit + node/typescript/tsdown/cordis 版本）。- 不要用
continue-on-error 掩盖失败——矩阵全绿才是绿。
测试环境与权威关系
- 本机（Linux，Node.js v24.16.0，deepseek-harness checkout 构建）与 CI 矩阵（ubuntu-latest + windows-latest × Node 22/24）上验证通过。与之精确匹配的已发布 DSH/Cordis 版本待确认——checkout 是预发布工作树，非发布 tag。
- 权威源码在 deepseek-harness monorepo 的
packages/community/ponytail（@deepseek-ai/dsh-ponytail）；本仓库（@mengyuly/dsh-ponytail）是发行镜像：随包附构建产物，不是独立真源。
发行维护
以下命令仅限源码仓库维护者使用。 scripts/ 目录有意不进入 npm tarball，
因此安装发布的 npm 包后这些命令不可用——npm 包用户不需要运行任何维护检查，
它们只在发布前由维护者和 CI 使用。发布包的 package.json 不暴露任何
scripts/ 命令（无维护脚本入口、无安装生命周期钩子），由
node scripts/verify-pack.mjs 回归检查强制。
- 权威源码：deepseek-harness monorepo 的
packages/community/ponytail（本仓库是发行镜像，只随包发布构建产物）。
- 维护者命令（源码仓库内直接运行
node scripts/<script>.mjs；快捷清单见
package.dev.json）：
node scripts/check-bundle.mjs # Bundle 外部依赖白名单 + 无 new Function/eval
node scripts/verify-dist.mjs # 静态一致性：src/d.ts 导出一致、关键签名、运行时导出、provenance
node scripts/verify-pack.mjs # tarball 边界（含无 scripts/ 暴露回归检查）、版本、安装后 smoke
node scripts/test-consumer.mjs # NodeNext + skipLibCheck:false 声明消费测试（对打包产物）
node scripts/test-regressions.mjs # 验证工具自身的回归测试
node scripts/test-core.mjs # 核心 Prompt 字节、安全边界、模式与 Skill 表面
node scripts/measure-prompt.mjs # 各模式 Prompt 段体积（依赖未发布的 src/）
node scripts/check-release-links.mjs # README/CHANGELOG/docs 无版本化 latest 资产链接
node scripts/check-release-consistency.mjs --version <v> # 四方发布一致性（git tag/npm/GitHub/provenance）
- 完整重新生成并同步
lib/（JS 与声明必须作为同一产物同步，禁止只复制单个 JS 文件）：
DSH_CHECKOUT=/path/to/deepseek-harness node scripts/sync-dist.mjs
该命令在权威 checkout 中重建（tsc 生成声明 + tsdown 打包运行时），同步 lib/index.js、lib/invariant.js、lib/types/*.d.ts，生成 dist-provenance.json（记录权威 checkout 的真实 commit SHA 与工具链版本），并自动执行一致性校验；产物有变化时会提示提交。完整构建一致性由本命令在发布流程中完成——发行镜像 CI 不会重新构建权威 monorepo。
- CI 能力边界（如实）：CI（ubuntu + windows 矩阵）执行上述静态验证与打包/消费测试，但不重新构建权威 monorepo；
verify:dist 是导出表面/签名/运行时导出的一致性检查，不是与权威构建的字节级等价证明——后者由 sync:dist 在发布流程中保证。
dist-provenance.json 随 npm 包发布，便于审计构建来源。- 本机验证时若
npm_execpath 指向其他包管理器（如 pnpm/yarn shim），脚本会自动回退到 PATH 上的 npm；临时目录失败时保留需设 PONYTAIL_VERIFY_KEEP_TEMP=1。
- 安全：
scripts/** 仅用于开发/构建/发行验证，不进入 npm tarball、无安装生命周期钩子、运行时入口不引用、发布包 package.json 不暴露这些维护命令；child_process 告警属于可接受的开发工具风险。详见 SECURITY.md。
许可
MIT，© 2026 DietrichGebert（上游）+ MengYuil（移植）。详见 LICENSE。
