@wenaixi/dsh-ponytail 4.9.0 → 4.10.0-dsh.2

package/AGENTS.md

@@ -1,32 +1,32 @@
-# Ponytail, lazy senior dev mode
-
-You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
-
-Before writing any code, stop at the first rung that holds:
-
-1. Does this need to be built at all? (YAGNI)
-2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
-3. Does the standard library already do this? Use it.
-4. Does a native platform feature cover it? Use it.
-5. Does an already-installed dependency solve it? Use it.
-6. Can this be one line? Make it one line.
-7. Only then: write the minimum code that works.
-
-The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.
-
-Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.
-
-Rules:
-
-- No abstractions that weren't explicitly requested.
-- No new dependency if it can be avoided.
-- No boilerplate nobody asked for.
-- Deletion over addition. Boring over clever. Fewest files possible.
-- Shortest working diff wins, but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
-- Question complex requests: "Do you actually need X, or does Y cover it?"
-- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
-- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
-
-Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.
-
-(Yes, this file also applies to agents working on the ponytail repo itself. Especially to them.)
+# Ponytail, lazy senior dev mode
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
+3. Does the standard library already do this? Use it.
+4. Does a native platform feature cover it? Use it.
+5. Does an already-installed dependency solve it? Use it.
+6. Can this be one line? Make it one line.
+7. Only then: write the minimum code that works.
+
+The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.
+
+Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.
+
+Rules:
+
+- No abstractions that weren't explicitly requested.
+- No new dependency if it can be avoided.
+- No boilerplate nobody asked for.
+- Deletion over addition. Boring over clever. Fewest files possible.
+- Shortest working diff wins, but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
+
+Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.
+
+(Yes, this file also applies to agents working on the ponytail repo itself. Especially to them.)

package/CHANGELOG.md

@@ -2,7 +2,122 @@
 
 所有重要变更记录于此，格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，版本号与上游 [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) 同步。
 
-## [4.9.0] - 2026-08-21
+> **版本策略**：每个版本固定带 `-dsh.N` 后缀（如 `4.10.0-dsh.0`、`4.10.0-dsh.1`），初始即 `-dsh.0`。上游发新版时重置为新上游版本的 `-dsh.0`（如 `4.10.0-dsh.0`），用 `pnpm run bump:dsh -- 4.10.0`。递增：`pnpm run bump:dsh`。遵循 SemVer 预发布语义。
+
+## [Unreleased]
+### Changed
+- 架构深化轮 4（improve-codebase-architecture 评审 5 候选全量落地）：
+  - **状态接口单一关闭契约**：`state.set('off')` 与 `set(null)` 收敛为同一关闭语义（`set` 边界归一 off→null），`agent/created` 的 off→null 镜像删除；消除「无 flag」与「flag 内容 off」两种关闭形态的契约漂移
+  - **示例行裁剪契约找回**：`filterSkillBodyForMode` 示例行正则兼容中文引号/冒号（原上游 ASCII 引号形态在中文化正文下永久失配，lite/full/ultra 三档示例区此前完全相同）
+  - **list() 失败面收敛**：删除 `stat` 预检，缺失 SKILL.md 与解析失败汇入同一条 warn+跳过路径（`readFile` 本身即可区分）
+  - **监听防御对称**：`agent/pre-step` 防御 catch 补 `warn`，与 `session/event` 失败可见性对齐
+- 发布载荷瘦身：删除与 logo.png MD5 全同的 assets/logo-dark.png（676KB×2 → 单源），README dark srcset 收为单一 <img>；零引用上游市场物料（benchmark svg ×2、logo-greenpt ×2、waitlist-banner ×3、social-preview、logo-dark.svg）移出 package.json files 白名单，包体积约 1.68MB → 约 0.35MB（文件本身保留在仓库）。
+
+
+### Changed
+- 架构深化轮 3（4 候选核实后自决 2 实施 2 驳回）：
+  - **命令调度深模块化**：在 `src/ponytail-commands.ts` 实现 `createCommandDispatcher`，将消息文本展开提取（`extractTextFromContent` 与 `extractText`）、指令语法解析、状态机流转（`state.set`）、持久化配置写入（`writeDefaultMode`）与宿主日志格式化整体封装为深模块；
+  - **消除 6-flag 浅接口泄漏**：消除此前 `CommandParseResult` 导出的 6 个松散布尔/可选字段在外部引起的时序耦合，内部锁死 `reportOnly` 优先分支，彻底杜绝裸指令误切；
+  - **插件入口骨架瘦身**：`src/ponytail.ts` 由 272 行降至 221 行（净减 51 行脆弱级联胶水），`agent/pre-step` 与 `session/event` 简化为单行委托调用，入口彻底纯化为声明式插件生命周期装配线；
+  - **架构决策自决与驳回**：正式驳回 Candidate 2（合并 state 与 runtime：破坏上游 1:1 逐行移植锚点与产物守卫，净收益为负）与 Candidate 3（合并 skill 存储与 instructions 渲染：同步高频渲染与异步 Cordis 服务范式正交，强行捏合制造上帝类，违背 YAGNI）；
+
+### Added
+- `scripts/behavior.test.mjs` 新增 6 项高杠杆行为测试（测试总数 12 → 18 项，耗时仅 10ms）：覆盖多 block 与非文本清洗、多 message 拼接、切档状态突变与日志断言、失活状态突变、裸指令防误切安全守卫、嵌套 block 消息指令识别；
+
+## [4.10.0-dsh.2] - 2026-10-02
+
+### Added
+- **状态模块对偶落盘抽象**：`src/ponytail-state.ts` 新增 `syncToFile(): void` 显式落盘方法，与 `syncFromFile()` 形成完全对称的对偶接口（Disk ↔ Memory），主入口 `agent/created` 监听器改用显式 `state.syncToFile()` 替代借用 setter 副作用的隐式刷新。
+- **命令调度器纯内存沙箱单测**：`scripts/behavior.test.mjs` 补齐针对 `createCommandDispatcher` 处理 `/ponytail default <mode>` 的两项纯内存沙箱测试（合法模式注入写入、非法模式拦截保护），消除单测写穿磁盘副作用，全量行为测试扩充至 26 项全绿。
+- **npm 标准测试脚本**：`package.json` 补全缺失的 `"test": "node scripts/behavior.test.mjs"` 标准脚本，并在 `prepublishOnly` 挂载 `npm test` 发布前守卫。
+- **CI/CD 双轨自动化流水线**：`.github/workflows/ci.yml` 扩展 `tags: ["v*"]` 触发器，确保代码 push 与 tag 推送均触发全套测试四件套；`.github/workflows/publish.yml` 补齐 `pnpm typecheck` 并对齐门禁步骤，实现 tag 推送时全套测试门禁 100% 先验通过才触发额外发版。
+
+### Fixed
+- **配置写入契约闭环**：`src/ponytail-config.ts` 的 `writeDefaultMode` 底层写操作补充顶层 `try/catch` 守卫，遇到磁盘写保护、EACCES 权限受限或 Windows EBUSY 文件锁等底层 I/O 异常时优雅回退 `null`，彻底闭合 `RuntimeMode | null` 类型契约，防止异常击穿上层。
+- **静态门禁产物断言补齐**：`scripts/verify.mjs` 产物检查清单补全遗漏的 `lib/ponytail-commands.js` 与 `lib/ponytail-state.js`，实现全量 7 个编译模块 100% 静态断言覆盖。
+- **技能解析极端格式容错**：`src/ponytail-skills.ts` 的 Frontmatter 解析状态机补充 UTF-8 BOM（`\uFEFF`）清洗与分隔行 `trimEnd()` 容错，彻底兼容 Windows 编辑器特殊换行与尾部空白。
+- **AbortSignal 迅捷响应契约**：`src/ponytail-skills.ts` 的 `list()` 遍历循环首行补位 `options.signal?.throwIfAborted()`，并在 `parseSkillFile` 优先判定 `signal?.aborted`，严格履行 WHATWG / DSH 规范的 `settle promptly` 契约。
+- **技能路径安全解析与调试支持**：`src/ponytail.ts` 的 `resolveDefaultSkillDir` 改用标准 ESM 原生 `new URL('../skills', import.meta.url)`；技能扫描放宽 `!entry.isDirectory() && !entry.isSymbolicLink()`，支持软链接技能目录本地调试；`get()` 增强对 `candidate.locator` 的类型保护与 `dirname(targetPath)` 兜底。
+
+### Removed
+- **冗余死代码清理**：`src/ponytail-skills.ts` 的 `list()` 解构精简为 `const { data } = parsed`，彻底消除未用变量与 `void body` 压制代码。
+
+## [4.10.0-dsh.1] - 2026-10-01
+
+### Changed
+- 架构深化（6 候选核实后自决 4 实施 2 否决）：
+  - 等级状态收敛为深模块 `src/ponytail-state.ts`（`createPonytailState`：`get()/set(mode)/syncFromFile()` 三方法，闭包实例随 HMR 重建）；`ponytail.ts` 的 `currentMode` 散落读写（apply 启动、section text 漂移修正、handlePromptText 四处双写、agent/created 镜像）全部收口——`set()` 内存赢原子落盘、`syncFromFile()` 文件赢纠偏（行为与 4.10.0-dsh.0 逐行等价）
+  - 指令渲染收敛为深模块 `render(skillDir, mode)`（`src/ponytail-instructions.ts`）：`systemPrompt` section 回调只留 off 短路 + 一次调用，review 短路指针 + 裁剪 + 失败回退收进模块内，对齐上游 `getPonytailInstructions(mode)` 单一出口形态（行为无可观察变更）
+  - 抽取 SkillProvider 子系统为 `src/ponytail-skills.ts`（frontmatter 解析 + 目录扫描 + `PonytailProvider.list/get`，DSH 专属层）；`Config` 接口迁 `src/ponytail-config.ts` 为 `PonytailConfig` 共享类型（entry 侧 `export type Config = PonytailConfig` 别名），消除模块循环依赖；不发明工厂——直接导出同名类，注册保持一行 `new PonytailProvider(ctx, control, { providerName, skillDir })`；`src/ponytail.ts` 由 533 行降至 272 行，只留生命周期与监听器（行为无可观察变更）
+  - frontmatter 读取瘦身：`stringField/optionalString/optionalMetadata` 折叠为 `readString/readObject/readMetadata`（调用点零改动，净减行数）
+  - `apply` 删不可达死代码 `?? null`（分支守卫已排除 undefined）；`?? 'full'` 保留并改为 `DEFAULT_MODE` 常量（DSH 测试路径直接 `apply(ctx)` 真实依赖该兜底）
+  - `PONYTAIL_DEFAULT_MODE` env 非法值由静默回退改为 `ctx.logger.warn`（DSH 差分，不改变回退语义，上游仍静默）；config 文件非法值保持静默（与上游一致）
+- `scripts/verify.mjs` 静态检查（不注册 tool）由单文件 `src/ponytail.ts` 扩为整个 `src/` 目录扫描（新模块 `ponytail-state.ts` 纳入覆盖）
+
+### Added
+- `scripts/behavior.test.mjs` 新增 2 例：`/ponytail default lite` 持久化、`/ponytail default foobar` 非法默认不切换（instruction 解析用例 6 → 8，总数 9 → 11）
+
+### Cleaned
+- `src/ponytail.ts` 由 563 行减至 ~533 行；`handlePromptText` 四处 `setMode/clearMode` 成对 try/catch 由 `state.set()` 原子化吸收
+
+## [4.10.0-dsh.0] - 2026-10-01
+
+### Fixed
+- `agent/session-start` 死监听迁移为 `agent/created`：`payload.source` 为 `startup`/`resume` 时对齐 flag 文件（`off` 清空、其余 `setMode(currentMode)`），`clear`/`compact` 不动作——DSH 官方事件模型不存在 `session-start`，原监听永不被触发
+- 对齐官方 defensive-patterns：`agent/created` 与 `session/event` 监听整体 `try/catch`，坏订阅者不再断链
+- `SkillProvider.list()`/`get()` 尊重 `options.signal`：已 abort 时立即抛 `AbortError` 快速 settle（放弃对 fs 调用的 signal 透传）
+- `SkillProvider.list()` ENOENT/ENOTDIR 由记 `warn` 返回 `[]` 改为显式 `{ candidates: [], complete: false }`（显式「发现未完成、不可缓存」）与警告并行
+- `scripts/verify.mjs` description 长度断言改用 `yaml.parse` 按 YAML 折叠块真实语义计算并输出真实长度；实测六个技能均 ≤500（262/162/165/161/104/165），无需压缩
+
+### Changed
+- 版本重置：与上游 v4.10.0 对齐由 `4.9.0-dsh.5` 重置为 `4.10.0-dsh.0`（`pnpm run bump:dsh -- 4.10.0`）
+- peer/devDeps 对齐 DSH 0.2.0-rc.2 运行时：`@deepseek-ai/cordis ^4.0.4`、`@deepseek-ai/dsh-skill >=0.1.0-rc.1 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0`、`@deepseek-ai/schemastery ^3.18.4`
+- 指令解析核心由 `handlePromptText` 抽取为纯函数 `parsePonytailCommand`（新增 `src/ponytail-commands.ts`），行为等价，可脱离插件单测；`@`/`$` 前缀与 `/ponytail:ponytail`/`/ponytail:ponytail-review` 前缀形式对齐上游 4.10.0 mode-tracker
+- **未知参数语义对齐上游 else 兜底**：`/ponytail <unknown>` 由 `warn` 不切换（4.9.0-dsh.5 引入的 DSH 差分，上游无此分支）改回静默切到默认等级——与上游 mode-tracker 逐分支一致（含默认 `off` 时落入关闭分支）
+
+### Added
+- `scripts/behavior.test.mjs` 最小行为测试（node 内置 test runner）：指令解析 6 例 + 技能裁剪 2 例 + abort 立即 settle 1 例，9/9 通过
+- `scripts/verify.mjs` 新增六个 SKILL.md `description` ≤500 静态断言（官方 `catalogDescriptionMaxLength` 默认截断线，防回归）
+
+### Cleaned
+- 删除无消费方的 `Config.hideStatus`/`Config.quietStartup` 配置项与 `getHideStatus`/`getQuietStartup`/`getPonytailInstructions`/`writeHookOutput`/`getStatePath` 死代码；删除 `normalizePersistedMode` 孤儿导出（README 与 CHANGELOG 无对应表述，无需同步清理）
+
+## [4.9.0-dsh.5] - 2026-08-22
+
+### Fixed
+- `isDeactivationCommand` 去除正则重复 `\s`，保持 spec `.!?。！？` + 空白
+- `ponytail-runtime` 平台识别由模块级常量改为函数 `isCopilot()/isCodex()/isQoder()`，修复同进程 env 变更后路径漂移
+- `/ponytail <unknown>` 未知参数由静默切默认改为 `warn` 不切换
+- `extractText` 双路径提取收敛为 `extractTextFromContent` 复用，消除 `agent/pre-step` 与 `session/event` 重复分支
+- `scripts/verify.mjs` 不注册 tool 检查由 `|| / &&` 误优先级改为单正则 `\btools\s*\.\s*register\b|\bdefineTool\b`
+- `publish.yml` 幂等：`VERSION` 检查提到 `if/else` 前共享，`workflow_dispatch` 计入 `if`，`Create Release` 受 `skipped` 守卫
+
+### Changed
+- `CLAUDE.md` Flag 描述由“三分支”更正为“四路”；验证命令 `--filter` 补 `scope`
+
+## [4.9.0-dsh.4] - 2026-08-22
+
+### Changed
+- `CLAUDE.md` 改为本地记忆，不再入仓：加入 `.gitignore`，历史提交中移除该文件，本次构建产物与 `CHANGELOG`/`README` 同步到新版本
+- README 安装示例移除括号补充说明，保持示例纯净
+
+## [4.9.0-dsh.3] - 2026-08-22
+
+### Fixed
+- `Config` 声明顺序修正为 `interface` 在前、`Schema` 在后，符合 `references/config.md` 的 Schemastery 规范写法（此前 `const` 在前会导致类型声明顺序与上游 `dsh-superpower` 不一致）
+- `isDeactivationCommand` 补全中文全句匹配 `退出 ponytail` / `正常模式`，并兼容中文标点 `。！？`
+
+## [4.9.0-dsh.2] - 2026-08-22
+
+### Changed
+- README 去版本化：徽章与正文不再写死 `4.9.0-dsh.x`，默认装 `latest`；`logo-dark` 同步为新 logo 相对路径
+
+## [4.9.0-dsh.1] - 2026-08-22
+
+### Changed
+- 替换 `assets/logo.png` 为用户指定新 Logo（692KB），原文件已移除；README 徽章同步至 `4.9.0-dsh.1`
+
+## [4.9.0-dsh.0] - 2026-08-21
 
 ### Added
 - 完整移植上游 v4.9.0：6 个 Skill（`ponytail` / `ponytail-review` / `ponytail-audit` / `ponytail-debt` / `ponytail-gain` / `ponytail-help`）
@@ -10,17 +125,18 @@
 - 复刻 hooks 行为：`activate` / `mode-tracker` / `subagent` / `config` / `instructions` / `runtime`
 - `PONYTAIL_DEFAULT_MODE` env > cordis 配置 > 配置文件 > `full` 三级回退，`review` 不可作默认，BOM 处理、`isShellSafe`、`isDeactivationCommand` 全量对齐
 - 中文化：6 个 Skill 的 `description` 与正文、fallback 指令、hook 日志、systemPrompt 注入文本全部中文，触发词兼容中英文
-- `CLAUDE.md` 核心记忆库、`LICENSE`（MIT）、`README.md`/`README.en.md`、`CHANGELOG.md`、`assets/`、`AGENTS.md`
+- `CLAUDE.md` 核心记忆库、`LICENSE`（MIT）、`README.md`、`CHANGELOG.md`、`assets/`、`AGENTS.md`
 
 ### Changed
-- DSH 形态：单一插件包 `dsh-ponytail`，`dsh.bundle.patch = ./cordis.patch.yml`，包名引用挂载
+- DSH 形态：单一插件包 `@wenaixi/dsh-ponytail`，`dsh.bundle.patch = ./cordis.patch.yml`，包名引用挂载
 - 注入文本中文化：`PONYTAIL 已激活 — 等级：…`，`hook` 日志全中文
+- 版本统一带 `-dsh.N` 后缀，初始 `4.9.0-dsh.0`
 
 ### Fixed
 - `initialMode` 优先级修正为 `env > cordis 显式 config > 文件 > full`，与上游语义一致
 
 ### Notes
-- 无空 tool（不在 `ctx.tools` 注册任何占位），`scripts/verify.mjs` 校验
+- 不注册 tool（不在 `ctx.tools` 注册任何占位），`scripts/verify.mjs` 校验
 - 构建：`pnpm build` (`tsc -p tsconfig.build.json`)，`pnpm typecheck`，`pnpm verify`
 
-[4.9.0]: https://github.com/Wenaixi/dsh-ponytail/releases/tag/v4.9.0
+[4.9.0-dsh.0]: https://github.com/Wenaixi/dsh-ponytail/releases/tag/v4.9.0-dsh.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 DietrichGebert
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 DietrichGebert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,135 +5,134 @@
 </p>
 
 <p align="center">
-  <strong>懒惰的资深工程师 · 移植�?DeepSeek Harness</strong><br/>
+  <strong>懒惰的资深工程师 · 移植到 DeepSeek Harness</strong><br/>
   <em>The best code is the code you never wrote.</em>
 </p>
 
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT"/></a>
-  <a href="https://www.npmjs.com/package/dsh-ponytail"><img src="https://img.shields.io/npm/v/dsh-ponytail?color=111111&style=flat-square" alt="npm"/></a>
-  <img src="https://img.shields.io/badge/version-4.9.0-111111?style=flat-square" alt="version"/>
-  <img src="https://img.shields.io/badge/DSH-0.1.1--rc.2-333333?style=flat-square" alt="DSH"/>
+  <a href="https://www.npmjs.com/package/@wenaixi/dsh-ponytail"><img src="https://img.shields.io/npm/v/@wenaixi/dsh-ponytail?color=111111&style=flat-square" alt="npm"/></a>
+  <img src="https://img.shields.io/badge/DSH-333333?style=flat-square" alt="DSH"/>
   <img src="https://img.shields.io/badge/skills-6-008080?style=flat-square" alt="skills"/>
-  <img src="https://img.shields.io/badge/node-%3E%3D18-3C873A?style=flat-square" alt="node"/>
 </p>
 
 <p align="center">
-  <a href="README.md">中文</a> · <a href="README.en.md">English</a> · <a href="CHANGELOG.md">Changelog</a> · <a href="https://github.com/DietrichGebert/ponytail">上游</a> · <a href="https://www.npmjs.com/package/dsh-ponytail">npm</a>
+  <a href="CHANGELOG.md">Changelog</a> · <a href="https://github.com/DietrichGebert/ponytail">上游</a> · <a href="https://www.npmjs.com/package/@wenaixi/dsh-ponytail">npm</a>
 </p>
 
 ---
 
-> [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) v4.9.0 �?**DSH 完整移植�?*�?> 把「懒惰的资深工程师」带�?DeepSeek Harness：always-on 梯子注入 + 6 个中�?Skill，无�?tool，开箱即用�?
-## �?特�?
-- **Always-on 梯子**�? 阶决策（YAGNI �?复用 �?标准�?�?平台原生 �?已有依赖 �?一�?�?最小实现），每轮模型请求前自动注入，`off` 时静默�?- **6 个中�?Skill**：`ponytail` / `ponytail-review` / `ponytail-audit` / `ponytail-debt` / `ponytail-gain` / `ponytail-help`，`rank: 550` 可被项目级覆盖�?- **三档强度**：`lite`（点出更懒的替代�?/ `full`（默认，强制走梯子） / `ultra`（先删后加，挑战需求本身）�?- **上游行为全量复刻**：`PONYTAIL_DEFAULT_MODE` env > cordis 配置 > 配置文件 > `full`；`review` 不可作默认；`stop ponytail` 全句匹配；`ponytail:` 债务台账；`PONYTAIL_SUBAGENT_MATCHER` 过滤�?- **无空 tool**：不�?`ctx.tools` 注册任何占位 tool，全部能力经 `ctx.skills` 暴露�?
-## 📦 包含能力
+> [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) 的 DSH 完整移植版 — always-on 注入 + 6 个中文 Skill，无 tool 注册。
 
-| 能力 | 类型 | 说明 |
-|---|---|---|
-| `ponytail` | skill + always-on | 7 级梯子，lite/full/ultra 三档，触发词兼容中英�?|
-| `ponytail-review` | skill | diff 过度设计评审，`delete/stdlib/native/yagni/shrink` |
-| `ponytail-audit` | skill | 全仓审计，按可删收益排序 |
-| `ponytail-debt` | skill | 收割 `ponytail:` 注释台账 |
-| `ponytail-gain` | skill | 收益看板（benchmark 中位数） |
-| `ponytail-help` | skill | 速查�?|
-| 模式切换 | hook | `agent/pre-step` + `session/event` 双路径，/ponytail 族指�?|
-| 持久�?| 文件 | `~/.config/ponytail/config.json`（Win: `%APPDATA%`），`/ponytail default <mode>` 写入 |
+## 🚀 安装（默认装到 `web`）
 
-## 🚀 安装
-
-### 方式一：npm（推荐，发布后可用）
+> `web` 即日常的 DSH Web UI（3080）。示例中的 `demo` 可换成任意 `--profile <name>`。
 
 ```bash
-# 作为 DSH 插件安装（自动走 dsh.bundle�?dsh plugin --profile demo add @wenaixi/dsh-ponytail
+# 方式一：npm
+dsh plugin --profile web add @wenaixi/dsh-ponytail
 
-# 或作为普�?npm �?npm i @wenaixi/dsh-ponytail
-# �?pnpm / yarn
-pnpm add @wenaixi/dsh-ponytail
-```
+# 方式二：GitHub 直装（lib 已提交，无需构建）
+dsh plugin --profile web add github:Wenaixi/dsh-ponytail
 
-> 版本与上游同步，当前 `4.9.0`，`npm view dsh-ponytail version` 可查�?
-### 方式二：GitHub 直装（无需构建，lib 已提交）
+# 方式三：本地 / tarball
+pnpm install && pnpm build && dsh plugin --profile web add ./
+pnpm pack && dsh plugin --profile web add ./wenaixi-dsh-ponytail-*.tgz
 
-```bash
-dsh plugin --profile demo add github:Wenaixi/dsh-ponytail
-# 指定 tag / 分支亦可
-dsh plugin --profile demo add github:Wenaixi/dsh-ponytail#v4.9.0
+# 卸载
+dsh plugin --profile web remove @wenaixi/dsh-ponytail
+
+# 验证
+dsh --profile web --dump-config | grep -A2 ponytail
 ```
 
-### 方式三：本地联调 / tarball
+> `WARN missing peer @deepseek-ai/...` 属正常，peer 由 DSH 运行时提供；`Packages: +2 Done` 即成功。
 
-```bash
-pnpm install && pnpm build
-dsh plugin --profile demo add ./
-dsh --profile demo --dump-config  # 应能看到 ponytail �?
-# �?pnpm pack && dsh plugin --profile demo add ./dsh-ponytail-4.9.0.tgz
-```
+## ✨ 特性
 
-### 卸载
+- **梯子 7 阶**：YAGNI → 复用 → 标准库 → 平台原生 → 已有依赖 → 一行 → 最小实现，`off` 时静默
+- **6 个中文 Skill**（`rank: 550`）：`ponytail` / `ponytail-review` / `ponytail-audit` / `ponytail-debt` / `ponytail-gain` / `ponytail-help`
+- **三档强度**：`lite` / `full`（默认）/ `ultra`
+- **无 tool 注册**：全部能力经 `ctx.skills` 暴露
+
+| 能力 | 说明 |
+|---|---|
+| `ponytail` | 7 阶梯子，触发词兼容中英文 |
+| `ponytail-review` | diff 评审，`delete/stdlib/native/yagni/shrink` |
+| `ponytail-audit` | 全仓审计，按可删收益排序 |
+| `ponytail-debt` | 收割 `ponytail:` 注释 |
+| `ponytail-gain` | 收益看板（benchmark 中位数） |
+| `ponytail-help` | 速查卡 |
+
+## 🪝 Hook 注入
+
+> 上游 `hooks/` 的 6 个 Hook（config / instructions / runtime / activate / mode-tracker / subagent）已合并进单一 DSH 插件，无需宿主配置。
+
+| 上游 | DSH 侧 |
+|---|---|
+| `ponytail-config.js` | `src/ponytail-config.ts`（`env > 文件 > full`，`review` 不可默认） |
+| `ponytail-instructions.js` | `src/ponytail-instructions.ts`（`getPonytailInstructions(mode)` → `render(skillDir, mode)`：review 短路 + 按档裁剪 + 中文 fallback） |
+| `ponytail-runtime.js` | `src/ponytail-runtime.ts`（`.ponytail-active` + 四路识别） |
+| `ponytail-activate.js` | `src/ponytail.ts` 的 `agent/created`（startup/resume 对齐 flag） |
+| `ponytail-mode-tracker.js` | `src/ponytail-commands.ts` + `handlePromptText`（指令解析纯函数 + 副作用层） |
+| `ponytail-subagent.js` | `src/ponytail.ts` 的 `agent/created`（`PONYTAIL_SUBAGENT_MATCHER`） |
 
-```bash
-dsh plugin --profile demo remove @wenaixi/dsh-ponytail
 ```
+启动:  env PONYTAIL_DEFAULT_MODE → cordis defaultMode → ~/.config/ponytail/config.json → full
+       → setMode(flag 文件)
 
-### 验证（不重启 3080�?
-```bash
-pnpm build && pnpm typecheck && node scripts/verify.mjs
-dsh --profile demo --dump-config | grep -A2 ponytail  # 应出�?- id: ponytail
-# 隔离 profile 验证 GitHub 直装（不影响 web/3080�?dsh plugin --profile ponytail-test add github:Wenaixi/dsh-ponytail
-dsh --profile ponytail-test --dump-config | grep -A2 ponytail
+每轮请求前: agent/pre-step (waterfall, 必须 return next())
+            → 解析 /ponytail 族 / stop ponytail → 切 currentMode + 写 flag → next()
+
+注入: systemPrompt:section { name: ponytail, order: 50 }
+      order 50 在 persona(0) 之后、工具(100) 之前；回调只做 off 短路，渲染收敛于 render(skillDir, mode)
+      off → 空，review → 指向技能，读盘失败 → 中文 fallback，assembly 前以 readMode() 对齐
+
+持久化: /ponytail default <mode> → 写入 config.json
+子智能体: PONYTAIL_SUBAGENT_MATCHER 正则（非法 warn 回退），共享同一 section
+HMR: 全部走 ctx，热重载逆序自动清理
 ```
 
+`systemPrompt` 而非 `agent.inject`：落入日志可重建，`order: 50` 优先级高，每次 `assemble` 动态求值，`off` 零成本。Flag 兼容 `COPILOT_PLUGIN_DATA` / `PLUGIN_DATA` / `QODER_SESSION_ID` / `CLAUDE_PLUGIN_ROOT`。`isCopilot()/isCodex()/isQoder()` 每次读 env，常驻进程 env 变更即时生效。
+
 ## ⚙️ 配置
 
-�?`cordis.patch.yml` 行内覆盖�?
 ```yaml
 - insert:
     - id: ponytail
-      name: dsh-ponytail
+      name: "@wenaixi/dsh-ponytail"
       config:
         providerName: ponytail
-        skillDir: E:/path/to/skills   # 调试用，默认包内 skills/
-        defaultMode: full             # off|lite|full|ultra
+        defaultMode: full  # off|lite|full|ultra
 ```
 
-优先级（与上游一致）�?
-1. `PONYTAIL_DEFAULT_MODE=ultra` 环境变量（最高）
-2. `cordis.patch.yml` 中显式的 `defaultMode`
-3. `~/.config/ponytail/config.json`（Windows: `%APPDATA%\ponytail\config.json`，`XDG_CONFIG_HOME` 优先�?4. `full`
+优先级：`PONYTAIL_DEFAULT_MODE` env > `cordis.defaultMode` > `~/.config/ponytail/config.json` > `full`。持久化：`/ponytail default <mode>` 写入文件，`review` 不可作默认。
 
-持久化：`/ponytail default <mode>` 会写入上述配置文件；`review` 不可作默认�?
 ## 🎮 使用
 
-- **自动生效**：任一编码任务都会注入梯子，无需手动触发�?- **显式切换**：`/ponytail`（full）、`/ponytail lite|full|ultra|off`、`/ponytail default <mode>`、`/ponytail-review`
-- **一键技�?*：`/ponytail-review`、`/ponytail-audit`、`/ponytail-debt`、`/ponytail-gain`、`/ponytail-help`
-- **退�?*：`stop ponytail` �?`normal mode`（需整句匹配）或 `/ponytail off`，随时用 `/ponytail` 恢复
-- **子智能体**：`PONYTAIL_SUBAGENT_MATCHER` 正则过滤（与上游一致），DSH 侧所�?agent 共享同一 section
+- 自动生效，无需手动触发
+- `/ponytail [lite|full|ultra|off]` / `/ponytail default <mode>` / `/ponytail-review` / `/ponytail-audit` / `/ponytail-debt` / `/ponytail-gain` / `/ponytail-help`
+- 退出：`stop ponytail` / `normal mode`（整句）或 `/ponytail off`
+
+## 🛠️ 开发
 
-## 🛠�?本地开�?
 ```bash
-pnpm typecheck
-pnpm build
-pnpm verify                         # 6 技�?+ 产物 + 无空 tool 校验
+pnpm typecheck && pnpm build && node scripts/verify.mjs
 dsh --profile web --patch ./cordis.patch.yml --dump-config
-pnpm dsh web --patch ./cordis.patch.yml   # 热重载：�?src/ �?skills/ 即生�?```
+pnpm dsh web --patch ./cordis.patch.yml  # 热重载
+# 发版：pnpm run bump:dsh && pnpm build && npm publish --provenance --access public
+# 或 push tag v* 触发 GitHub Actions publish.yml
+```
 
-- `skills/` 中文化后需重跑 `build` �?`verify`（已处理 BOM �?`\r\n`�?- HMR：改 `src/*.ts` �?`skills/**/SKILL.md` 后旧 provider/section 自动清理
-- 发布：`pnpm build && npm publish --access public --provenance`（需 npm Trusted Publisher 或带 2FA �?granular token�?
-## 📂 目录
+- 版本：与上游 SemVer 同步，每个版本固定带 `-dsh.N`（对齐上游 v4.10.0 重置为 `4.10.0-dsh.0`），`pnpm run bump:dsh` 递增，上游发新版时 `pnpm run bump:dsh -- <版本>` 重置
 
-```
-src/ponytail.ts              # 唯一入口，name/inject/Config/apply
-src/ponytail-config.ts       # env > 文件 > full（含 BOM、review 限制、shell 白名单）
-src/ponytail-instructions.ts # �?mode 裁剪 SKILL.md + 中文 fallback
-src/ponytail-runtime.ts      # flag 文件 + 多平台识别（Claude/Codex/Qoder�?skills/ponytail/*.md         # 6 个中�?Skill
-assets/                      # logo / benchmark �?lib/                         # 构建产物（已提交，支�?GitHub 直装�?cordis.patch.yml             # - insert: { id: ponytail, name: dsh-ponytail }
-```
+---
 
 ## 🔗 上游
 
-- 原仓：https://github.com/DietrichGebert/ponytail（MIT，v4.9.0�?- 本包：MIT，`skills/` �?`AGENTS.md` 原样拷贝自上游，仅为 DSH 运行时做适配
-- 关联：`ponytail:` 债务台账、`ponytail-gain` 永不输出本仓实时节省�?
+原仓 https://github.com/DietrichGebert/ponytail（MIT）
+
 ## 📄 许可
 
-[MIT](LICENSE) © DietrichGebert / Wenaixi
+[MIT](LICENSE)
+© DietrichGebert / Wenaixi

package/cordis.patch.yml

@@ -1,3 +1,4 @@
 - insert:
     - id: ponytail
       name: "@wenaixi/dsh-ponytail"
+

package/lib/ponytail-commands.d.ts

@@ -0,0 +1,54 @@
+import type { PonytailState } from './ponytail-state.js';
+import { type RuntimeMode } from './ponytail-config.js';
+/**
+ * 指令解析结果（底层纯数据结构，供单元测试与内部调度使用）
+ */
+export interface CommandParseResult {
+    handled: boolean;
+    switched: boolean;
+    mode?: RuntimeMode | 'review';
+    deactivate?: boolean;
+    reportOnly?: boolean;
+    persistDefault?: {
+        mode: string;
+    } | null;
+}
+/**
+ * 从单条消息 content 结构中提取纯文本
+ */
+export declare function extractTextFromContent(content: unknown): string;
+/**
+ * 从消息数组中提取并拼接纯文本
+ */
+export declare function extractText(messages: unknown): string;
+/**
+ * 解析用户输入的文本是否为 ponytail 命令
+ * 移植自 hooks/ponytail-mode-tracker.js 的核心解析逻辑
+ */
+export declare function parsePonytailCommand(rawText: string, currentMode: string | null, getDefault: () => RuntimeMode): CommandParseResult;
+export interface CommandDispatcherLogger {
+    info: (msg: string) => void;
+    warn?: (msg: string) => void;
+    debug?: (msg: string) => void;
+}
+export interface CommandDispatcherEnv {
+    state: PonytailState;
+    logger: CommandDispatcherLogger;
+    getDefaultMode?: () => RuntimeMode;
+    writeDefaultMode?: (mode: string) => RuntimeMode | null;
+}
+export interface CommandDispatchResult {
+    handled: boolean;
+    switched: boolean;
+}
+export interface CommandDispatcher {
+    dispatchText: (rawText: string) => CommandDispatchResult;
+    dispatchContent: (content: unknown) => CommandDispatchResult;
+    dispatchMessages: (messages: unknown) => CommandDispatchResult;
+}
+/**
+ * 创建高内聚的命令调度器深模块
+ * 将文本提取、指令语法解析、状态机流转与副作用执行完整封装
+ */
+export declare function createCommandDispatcher(env: CommandDispatcherEnv): CommandDispatcher;
+//# sourceMappingURL=ponytail-commands.d.ts.map

package/lib/ponytail-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ponytail-commands.d.ts","sourceRoot":"","sources":["../src/ponytail-commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAA;AAE7B;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAA;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CACzC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAS/D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAOrD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,UAAU,EAAE,MAAM,WAAW,GAC5B,kBAAkB,CAiDpB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3B,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC5B,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,aAAa,CAAA;IACpB,MAAM,EAAE,uBAAuB,CAAA;IAC/B,cAAc,CAAC,EAAE,MAAM,WAAW,CAAA;IAClC,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,GAAG,IAAI,CAAA;CACxD;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,qBAAqB,CAAA;IACxD,eAAe,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,qBAAqB,CAAA;IAC5D,gBAAgB,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,qBAAqB,CAAA;CAC/D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,oBAAoB,GAAG,iBAAiB,CAyDpF"}