极简编码守则 MengYuil/dsh-ponytail

dsh-ponytail

dsh.so security

把 DietrichGebert/ponytail 的极简编码原则和相关技能适配到 DeepSeek Harness，提供 YAGNI 决策阶梯、Lite / Full / Ultra / Off 会话级模式，以及一组技能，用来精简代码、审查、审计和追踪技术债。

本项目对齐上游核心理念和主要工作流，但 DSH 的模型循环、提示词组装、技能机制和工具调用不同。上游 Benchmark 仅作参考，不代表本适配版具有相同的 token、成本或延迟收益（详见「效率（条件性收益，非保证）」）。

GitHub Release 下载

- 最新版（latest）： https://github.com/MengYuil/dsh-ponytail/releases/latest/download/mengyuly-dsh-ponytail.tgz
- 固定版本 v0.4.3（按 Tag 不可变）： https://github.com/MengYuil/dsh-ponytail/releases/download/v0.4.3/mengyuly-dsh-ponytail.tgz

说明：

- latest：适合快速安装体验，会随最新 Release 更新；固定资产名 mengyuly-dsh-ponytail.tgz 在每个 Release 中保持不变，因此该 URL 不会因版本号变化而失效，不适合作为不可变依赖。
- 固定版本：适合可复现安装，URL 中固定 Tag（如 v0.4.3），按 Tag 不可变；资产名同样为 mengyuly-dsh-ponytail.tgz。
- npm 安装仍走 npm Registry 或 dsh plugin 命令。
- 固定资产名由 scripts/release-assets.mjs 生成并验证（node scripts/release-assets.mjs，仅仓库维护者）。

安装

装进某个配置档（web 可换成 tui/自定义名）：

推荐从 npm 安装稳定版：dsh plugin --profile web add @mengyuly/dsh-ponytail。
需要固定本版时使用 dsh plugin --profile web add @mengyuly/dsh-ponytail@0.4.3。

方式一：本地链接（当前 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

装完重启配置档生效（例如 dsh web）。发 /ponytail status 查看实际模式与来源，或 /ponytail help 查看命令帮助；两者均不调用模型。默认注册 6 个 ponytail 技能，关闭附加技能后目录相应减少。/ponytail-help 是会请求模型工作的技能，不是零调用的安装检查。

更新已有安装

dsh plugin --profile web update @mengyuly/dsh-ponytail

更新后重启对应配置档。GitHub、链接或本地 tgz 安装请重新添加所需来源；不要把 npm 更新命令当成改变安装来源的保证。

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 是历史内联依赖基线。
下游构建使用 node scripts/build-ui.mjs；不要用 sync:dist 覆盖尚未同步到宿主的下游修改（详见「发行维护」）。

功能

- 核心模式 /ponytail — 每轮注入结构化的懒惰开发者规则集，三个档位是真实不同的提示词片段（不只是换一行）：
- Common（所有非 off 档共享）：先把请求转成可观察的完成条件；沿真实调用流取证，但决策阶梯是快速反射、不是研究项目；按「检查 → 修改 → 最窄有效验证 → 检查最终 diff」闭环执行；非平凡逻辑只留一个最小可执行检查，不额外搭测试框架或 fixtures；只汇报已验证结果。
- Safety（任何档位都不可删）：输入校验、防数据丢失的错误处理、安全措施、无障碍、明确验收项、先理解问题、「最小 diff ≠ 正确修复」。
- lite：完整交付明确要求，必须用一句话指出更简方案，由用户选择；没有可行替代时如实说明，不编造方案，也不擅自改变需求范围。
- full（默认）：完整七级阶梯（YAGNI → 复用 → 标准库 → 原生 → 已装依赖 → 一行 → 最小实现），默认选最短正确实现，修根因而非症状。
- ultra：新增代码前先要证据，优先删除或复用；主动质疑投机性功能/缓存/抽象/配置/新依赖；复杂需求先给最小正确版并说明扩大条件；不是无脑拒绝。
- off：完全不注入。
- 档位会话级（会话 A 不影响会话 B，会话结束自动释放）。
- 裸 /ponytail：支持原生命令菜单的 Web 会打开模式选择器；其他宿主中，已启用时只报告，off 时恢复到有效默认档（默认也是 off 则回 full）。
- /ponytail status：只查询、永不修改，并显示当前模式来自会话覆盖还是配置默认值。
- /ponytail reset：清除当前会话覆盖，重新跟随有效配置默认值。
- /ponytail lite|full|ultra|off：显式切换。
- /ponytail help：直接显示操作帮助，不调用模型。
- /ponytail default <mode>：有 DSH Settings 时保存到宿主设置；没有时回退到用户级配置文件（env/Profile 仍优先，命令分别提示 saved 与 effective）。
- 状态操作立即生效，但不唤醒空闲 Agent；模型通知在下一次真实请求时接收，避免切档位额外触发模型调用。
- 一次性技能（用哪个载哪个，不进常驻 prompt）：
- /ponytail-review — 针对最近改动找过度工程；每条包含位置、替代方案和实际调用证据，不猜测精确收益。
- /ponytail-audit — 全仓库过度工程审计；区分可安全删除与需要先验证的候选，最多返回 10 条高价值发现。
- /ponytail-debt — 收割所有 ponytail: 注释成债务账本。
- /ponytail-gain — 上游 Benchmark 参考计分板（代码减少；Token/成本/延迟效果取决于模型与任务，非本适配版保证）。
- /ponytail-help — 参考卡。
- 停用：说 stop ponytail、normal mode、停止 ponytail、关闭 ponytail、普通模式 或 正常模式（兼容中英文句末标点）；随时 /ponytail 恢复。
- 默认值优先级（代码/测试/文档一致）：会话 override > PONYTAIL_DEFAULT_MODE > Profile config.defaultMode > DSH Settings > 用户 config.json > full

- Profile 级配置（Cordis 官方插件配置 API，各 profile 可不同）： ~/.dsh/profiles/tui/cordis.patch.yml 中给 ponytail 行补 config
- insert:
- id: ponytail
name: '@mengyuly/dsh-ponytail'
config:
defaultMode: lite

例：web → full、tui → lite、automation → off。支持 volatile 配置的新版宿主可热更新本插件设置；其他宿主手动改 Profile 后需重启。非法值只告警一次并回退，不影响启动。用户 config.json 仍保持热更新。
- 用户 config.json（~/.config/ponytail/config.json，Windows %APPDATA%\ponytail\config.json）：{"defaultMode": "lite"}，热更新（~1s 轮询），非法内容保留上次合法值。
- 子代理（如实边界）：DSH 内置 subagent 工具是隔离派生，但全局 system-prompt section 默认也会参与子代理的独立组装；这不是父代理 Prompt 或会话状态继承。PONYTAIL_SUBAGENT_MATCHER（匹配子代理 agentPreset 的正则）只用于筛选能进入本 Prompt 管线的子代理，不是继承开关；无 preset 时不会被 matcher 排除。DSH 当前没有公开的父子 Prompt 继承 API，因此不宣称父子 Prompt 继承（有官方 API 后再考虑只读模式快照传播）。非法正则告警一次并 fail-open。
- 配置错误：非法 JSON / 非法 defaultMode / 读取失败 / 非法正则只告警一次（不刷屏）；配置文件不存在属正常、不告警。

图形操作

0.4.3 加入新版 Web/桌面面板兼容修复；旧的 npm 0.4.2 不包含本次面板修复。
按实际宿主接口自动选择注册路径，不只针对某个 checkout：

- 旧版 settingsScope/settings.plugin.item：设置 → 插件/内置插件 → 插件配置 → Ponytail。
- 新版 configForms/settings.plugins.tab（Web 和桌面版）：设置 → 内置插件 → Ponytail。

面板可选择默认模式、分别开关五个附加技能、保存设置，或恢复面板默认。
新版保存到当前 Profile；旧版保存到宿主 Settings 文档。
「跟随现有配置」不覆盖环境变量；旧版面板也不覆盖已有 Profile 模式。
面板默认值不是当前会话模式；已有会话覆盖不变，实际模式与来源用 /ponytail status 查询。
附加技能开关不会移除常驻核心规则，只有 off 模式关闭规则注入。
原生菜单支持时，裸 /ponytail 打开模式选择器，并提供状态、会话重置和帮助入口。
有参数的命令、TUI/CLI 用法保持原样。没有这些界面服务的旧宿主保留命令与文件配置路径。
保存失败不显示成功，面板保留修改；只读连接禁用写入。面板重置仅清除自身设置，不删除旧配置、不清除已有会话覆盖，也不请求模型工作。

已在 WSL Debian 的真实 DSH checkout b150a551 上用隔离 profile 联调界面与文件设置。
本轮还对 npm DSH 0.1.1-rc.2、0.1.2-rc.1、0.1.5-rc.3、0.1.7-rc.2、0.2.0-rc.2、0.2.1-rc.2 运行真实浏览器验证：面板加载、模式/技能保存、宿主重启保留和恢复默认；Windows 桌面版 0.2.0-rc.2 也已实测。不代表所有 alpha、未来版本或自定义裁剪宿主均已验证。
完整检查项及构建标识见 图形设置兼容记录。
旧版仅有 set/unset 的 Settings scope 通过宿主原子 RPC 保存，仍保留版本冲突检查。
DSH 宿主契约 peer 保留版本声明，但标记为包管理器可选，由实际宿主提供； cordis 与 schemastery 仍是必需的运行时 peer。正常安装不需要关闭自动 peer 安装，也不会为了安装本插件拉取整套 DSH 和尚未发布的 dsh-type-meta。
「可选」仅指依赖解析：实际运行仍需要 DSH 的 systemPrompt、skills 等宿主服务，不能脱离 DSH 独立运行。

开发者界面验证（工具安装在仓库外，不进入 npm 包）： $env:PONYTAIL_TOOL_ROOT = Join-Path $env:TEMP 'ponytail-ui-tools'
npm install --prefix $env:PONYTAIL_TOOL_ROOT --ignore-scripts typescript@6.0.3 esbuild@0.28.2 react@18.3.1 react-dom@18.3.1 jsdom@26.1.0 @deepseek-ai/cordis@4.0.4
node scripts/build-ui.mjs
node scripts/test-ui.mjs
build-ui 保留已有内联宿主依赖，编译下游规则片段、插件入口和浏览器界面，不是权威 monorepo 完整重建。
dist-provenance.json 中旧 sourceCommit 表示基线，downstreamBuild 记录当前修改的源码和产物 SHA-256。

真实宿主跨版本检查（CI 分别运行上表六个版本，不调用模型）：
npm install --prefix $env:PONYTAIL_TOOL_ROOT --ignore-scripts playwright@1.64.0
node (Join-Path $env:PONYTAIL_TOOL_ROOT 'node_modules/playwright/cli.js') install chromium
node scripts/test-host-ui.mjs 0.2.1-rc.2
脚本为指定版本创建临时宿主与 Profile，使用真实 npm tarball，不读取日常配置或凭证。
0.1.1-rc.2 测试固定同代 Cordis 依赖，避免旧宿主的宽松 peer 范围混装新版；这只是历史宿主测试环境配置，不改变插件的正常安装方式。
设置 PONYTAIL_VERIFY_KEEP_TEMP=1 可保留截图与检查结果；PONYTAIL_DSH_RUNTIME 可复用指定版本的测试运行时。

效率（条件性收益，非保证）

Ponytail 会给每次模型请求增加一小段固定规则。它的收益是有条件的：当 Agent 容易过度设计时，减少的代码、工具调用和返工可能抵消甚至超过这部分开销；当任务本来已经很简单时，收益可能接近零，甚至出现额外输入开销。它不是"省 Token 开关"，也不保证跨模型省钱——某些推理模型可能因 prompt 与推理开销变得更贵。

本 DSH 适配版当前 Prompt 段实测大小（node scripts/measure-prompt.mjs，从真实
getPonytailInstructions() 生成）：

| 档位 | 字符数 | UTF-8 字节 | 说明 |
| lite | 3911 | 3913 | 实测生成 |
| full | 4818 | 4834 | 实测生成 |
| ultra | 5034 | 5050 | 实测生成 |
| off | 0 | 0 | 不注入 |

这些是 Prompt 体积测量，不是账单金额，也不是对所有模型成立的节省比例（无统一 tokenizer，measure:prompt 输出中 estimated_tokens 为 null；字符数/4 只是粗略估算）。同模式字节级稳定，有利于 Prompt 缓存，但不保证宿主或模型缓存命中。

所有启用档位均保留上游边界：修复前检查所有调用方、同等大小方案优先边界正确性、有已知局限的捷径留下 ponytail: <ceiling>, <upgrade path> 注释、保留硬件校准，以及完整回答用户明确要求的解释。规则仅用于编码任务，不改写一般问答或翻译。
所有启用档位包含完整七阶梯。Lite 必须用一句话指出更简单的替代方案，但由用户选定范围； Full 执行阶梯；Ultra 执行阶梯并更积极质疑不必要的复杂度。几行代码足够时不得新增依赖，在正确完整的前提下触及最少文件；用户坚持完整版本后直接实现，不反复争辩。
非平凡逻辑保留一个最小可运行检查，不擅自增加逐函数测试套件；简单一行代码不要求额外测试。
ponytail-debt 支持块注释和 lib 源码，两条扫描路径均跳过嵌套依赖与构建目录。
验证覆盖规则内容、真实搜索命令及安装产物与源码的 Prompt/Skill 一致性；这些检查不代表模型遵循率或实际性能已经通过对照评测。

上游数据不是本 DSH 适配版的保证：上游 Ponytail 的 single-shot （代码 −80~94%、成本 −42~75%、延迟 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/ 是预编译产物；下游修改在本仓库构建，并核对安装包与源码的一致性。

V4 会话兼容与恢复

0.4.2 修复 issue #3：模式切换、默认设置、重置和文本关闭通知使用生产者来源 kind: 'ponytail'，不再写入 V4 拒绝的旧 kind: 'plugin'。规则内容、模式优先级和显式技能调用来源未改变，模式通知仍不会额外唤醒模型。

真实 DSH 0.2.0-rc.2 / Cordis 4.0.4 / Schemastery 3.18.4 核心流程已验证： V4 落盘、正常重启恢复、flush 后强制终止恢复、后续写入与投影缓存更新。
本地一次完整运行保留 189 条事件、12 个回合，并逐条比较历史前缀。
使用本地固定回复适配器，不调用付费模型；不是新版 Web 设置验收或模型效果评测。
详见 验证范围与复跑说明。

如果旧版已出现保存阻塞，先备份当前可见的未保存内容，再升级并重启宿主。
本修复防止新的旧来源事件，不会自动清理已污染的内存缓冲，也不保证未落盘内容可恢复。

兼容矩阵（实测，不虚构）

| 组件 | 已验证环境 | 备注 |
| Node.js | 22.x / 24.x | 基础 CI 矩阵；V4 持久化集成使用 Linux Node 24 |
| OS | ubuntu-24.04 / windows-latest | CI 矩阵 |
| DSH 历史宿主 | checkout b150a551 / CLI 0.1.1-rc.2 | 历史构建与 Web 联调，不代表所有发行版 |
| DSH V4 核心 | npm 0.2.0-rc.2 | 真实 Agent/命令/JSONL/投影缓存，正常与强制终止后恢复 |
| Cordis / Schemastery | 4.0.4 / 3.18.4 | V4 实测；历史内联基线 Cordis 4.0.1 |
| Web 面板（0.4.3） | 0.1.1-rc.2 / 0.1.2-rc.1 / 0.1.5-rc.3 / 0.1.7-rc.2 / 0.2.0-rc.2 / 0.2.1-rc.2 | 真实浏览器、保存、宿主重启保留、恢复默认；CI 逐版本检查 |
| Windows 桌面面板（0.4.3） | 官方 0.2.0-rc.2 | 真实 Electron 界面、模式/技能保存、重启保留、恢复默认 |
| tui profile | 未验证 | 未在 tui profile 中启动测试 |
| headless profile | 未验证 | 未完整启动；插件单元测试运行于无 UI 环境 |
| npm tarball | 已验证 | 内容/版本/安装后 smoke/NodeNext consumer |

- dist-provenance.json 记录实际构建来源（checkout commit + node/typescript/tsdown/cordis 版本）。
- 不要用 continue-on-error 掩盖失败——矩阵全绿才是绿。

测试环境与权威关系

- 本机 WSL Debian（Node.js v24.16.0，DSH checkout CLI 标识 0.1.1-rc.2）、Windows Node 24 与 CI（ubuntu-24.04 + windows-latest × Node 22/24）上验证。真实宿主 checkout 为 b150a551，不是正式发布 tag；不能据此声称所有 DSH 发布版本都兼容。
- V4 持久化独立使用 npm DSH 0.2.0-rc.2 的真实核心服务和隔离目录；默认值测试覆盖旧 config.json 兼容路径，不包括新版 Web 原生 Settings/技能开关复测。
- 历史宿主构建基线来自 deepseek-harness monorepo 的 packages/community/ponytail；当前 @mengyuly/dsh-ponytail 的下游适配修改以本仓库 src/ 为准，随包附构建产物。

发行维护

以下命令仅限源码仓库维护者使用。 scripts/ 目录有意不进入 npm tarball，因此安装发布的 npm 包后这些命令不可用——npm 包用户不需要运行任何维护检查，它们只在发布前由维护者和 CI 使用。发布包的 package.json 不暴露任何 scripts/ 命令（无维护脚本入口、无安装生命周期钩子），由
node scripts/verify-pack.mjs 回归检查强制。

- 构建来源：monorepo 提供历史内联依赖基线；当前下游适配源码在本仓库。build-ui 与完整 sync:dist 的证据范围不同，不能混称。
- 维护者命令（源码仓库内直接运行 node scripts/.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-persistence.mjs # Linux/WSL：真实 DSH V4 写入、重启/强制终止恢复与缓存；无付费模型
node scripts/test-consumer.mjs # NodeNext + skipLibCheck:false 声明消费测试（对打包产物）

node scripts/test-regressions.mjs # 验证工具自身的回归测试
node scripts/test-core.mjs # 核心 Prompt 字节、安全边界、模式与 Skill 表面
node scripts/test-install.mjs # pnpm 11 默认 peer 安装，无宿主源码树或规避配置
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 文件）： bash
DSH_CHECKOUT=/path/to/deepseek-harness node scripts/sync-dist.mjs

该命令重建宿主 checkout 的基线，并覆盖本仓库的源码、JS、声明和 provenance。
仅在下游修改已经同步到该 checkout、且确认需要完整重建时使用；不应作为日常下游构建命令。
- CI 能力边界（如实）：CI 执行静态验证、源码/下游产物哈希、打包/消费测试和真实 V4 消息校验，独立 Linux 任务执行真实 DSH 持久化与恢复测试并保存证据；不重新构建宿主 monorepo。这些检查不证明当前下游产物等同于宿主基线的全量重新构建，也不证明模型服从率或效率收益。
- 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。