@wenaixi/dsh-ponytail 4.10.0-dsh.9 → 5.1.0

package/CHANGELOG.md

@@ -1,12 +1,121 @@
 # Changelog
 
-所有重要变更记录于此，格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，版本号与上游 [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) 同步。
+所有重要变更记录于此，格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)。本地版本与上游参考版本独立维护。
 
-> **版本策略**：每个版本固定带 `-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 预发布语义。
+> 当前本地版本：`5.1.0`。上游参考：`DietrichGebert/ponytail 4.10.3`（2026-10-04 核验）。历史 `-dsh.N` 记录仅用于追溯，不再作为现行版本规则。
 
-## [Unreleased]
+## [5.0.0] - 2026-10-04
 
-（本段暂无待发布内容）
+### Changed
+- 本地版本从 `4.10.0-dsh.12` 切换为独立的 `5.0.0`，不再随上游版本自动重置或生成 `-dsh.N`。
+- README、架构记录和发布流程明确区分本地发行版本与上游参考版本。
+- CI 行为测试步骤改为以实际命令输出为准，不再写死历史数量。
+
+### Fixed
+- 客户端 locale 字典改为 DSH 要求的扁平键，避免界面显示 `panel.title`、`priority.title` 等裸 key。
+- 客户端产物继续禁止 `import.meta` 和 `process.`，避免浏览器导入失败。
+
+## [5.1.0] - 2026-10-05
+
+### Breaking
+
+- **配置与 flag 的落点从全局数据根改为 profile 目录**（`profiles/<name>/ponytail/`）。升级用户的当前档位会重置为 `full`：迁移读取的是 profile 内的新位置，全局共享的旧 `config.json` 只需一次性导入。
+- **优先级链从四级降为三级**（`env > patch > fallback`），`config.json` 层退役。界面上的「用户配置文件」一行已移除。
+
+### Added
+- 配置与 flag 的 profile 维度：全部配置文件读写函数与 `createDiskStorage` 接受 `profileDir`，目录来自宿主 `profileContext.dir`，落点改为 `profiles/<name>/ponytail/`。同机多实例不再共享 `$DSH_HOME/ponytail`，最后写者赢的串扰消失。`src/ponytail-settings.ts` 提供两条通道——`createSettingsSink` 经 `ctx.settings.mutate('ponytail', ops, revision)` 写入，由宿主落到 profile 补丁并自带 revision 冲突保护；`createFileSink` 在无 settings 服务的组合（headless / CLI）回退读写 profile 内 `config.json`；`migrateLegacyConfig` 把全局共享的旧 `config.json` 一次性导入 profile 补丁并改名使其幂等。
+- `src/ponytail-remote.ts`：`PonytailRemote extends TypertRemoteService`，命名空间 `ponytail`，只暴露只读端点 `snapshot()`（当前生效等级 + 三级优先级诊断链）。宿主网关按服务上的 `typertRemote` 绑定自动发现端点，浏览器侧即 `ctx.remote.ponytail.snapshot()`。
+- 客户端 Remote 贡献声明 `PONYTAIL_REMOTE`：`apply()` 先 `await ctx.remote.$mount(...)` 再建 store。此前客户端只读命名空间却从未挂载，而网关的命名空间不是按需自动开通的（`dsh-api-remotes` 只遍历编译期写死的 25 个官方贡献），`remote.ponytail` 永不出现，面板因此永久显示「诊断信息不可用」——宿主完全正常。`$mount` 返回即命名空间就绪，故 40 次 x 50ms 轮询一并删除，改为挂载失败直接降级。
+
+### Changed
+- 配置卡改用 DSH 官方插件配置组合：`Config` 的 `defaultMode` 与 `disabledSkills` 声明为 `.volatile()` 字段，宿主 `volatileForm()` 投影成官方表单；客户端经 `ctx.configForms.get('ponytail')` 读写，插槽注册包在 `configForms.whileServed(['ponytail'])` 内。
+- 优先级链从四级降为三级 `env > patch > fallback`：`config.json` 层随 1A 下沉退役。留在链里就是一层永远不生效的空壳，而「看着能改其实不生效」正是这套面板最初要解决的坑。`LEVELS` / `LABELS` / `PROBLEMS` 各删一项，`resolvePriority` 去掉 `configMode` 参数，locale 同步删除 `level.config` 与 `problem.config`。
+- `patchMode` 改为实时读取 volatile 引用，不再缓存启动期快照。
+- `PonytailConfig` 的两个可持久化字段类型为 `VolatileRef<T>`，新增 `readVolatile()` 兼容「引用 / 裸值 / 未配置」三态。
+- 技能启用态的失效触发点从自制 HTTP 端点直调改为监听宿主 `loader/volatile-update`。
+
+### Removed
+- 删除 `src/ponytail-http.ts` 与 `/api/plugins/ponytail/config` 端点，以及 `webServer` 注入。
+- 删除 `apply()` 里对 `settings.register('ponytail', Config)` 的调用——`@deepseek-ai/dsh-settings@0.2.0-rc.2` 没有 `register` 方法（全文件零次出现），该调用此前被 `typeof` 守卫静默跳过，属于从未生效的死代码。命名空间改由「唯一 profile 条目 + 含 volatile 字段的 Config」自动产生。
+- 删除平台位置兼容读取 `getLegacyConfigDir()` / `getLegacyConfigPath()`（`%APPDATA%` / `XDG_CONFIG_HOME` / `~/.config` 三条分支）。1A 下沉后它们不再有任何读取者，`scripts/verify.mjs` 的对应豁免同时移除——现在 `src/` 下出现任何平台路径字面量直接判失败。
+
+### Fixed
+- 技能禁用状态此前只存在 `config.json` 且只能由 HTTP 端点修改；迁移后 UI 改开关后模型侧目录不收敛（写入链不经过本插件任何函数）。现由 loader 的 volatile 提交事件驱动失效。
+- 客户端配置卡此前自建 `fetch` 状态机（含空配置兜底、加载态、错误态），现完全走官方表单控制器，不发起任何 HTTP 请求。
+- 等级选择器的锁定判定原为「除 patch 与 config 外、只要有层级命中就锁」，而兜底层在没有 env 与 patch 时恒命中，于是按钮永久禁用、提示永远显示「当前有更高优先级的配置在生效」——但兜底不是更高优先级的配置，改补丁立刻生效，文案在说谎。改为只认 env 命中。
+
+## [4.10.0-dsh.12] - 2026-10-04
+
+### Fixed
+- 修复默认档持久化后 HTTP 诊断仍读取旧 patch/env 快照的问题：配置端点改用实时 getter，GET 与 POST 共享当前优先级事实。
+- 修复 systemPrompt 生产接线绕过 `renderPromptSection` 的问题，保留技能禁用配置热收敛。
+
+### Changed
+- 新增两项生产接线回归测试，覆盖动态 HTTP handler 与外部 flag 变化；行为测试达到 64 项。
+- 延后统一多个 SKILL.md frontmatter 解析器：provider、HTTP 与构建脚本的输入接受范围和 fallback 语义不同，暂不引入共享 seam。
+
+### Migration
+- 无配置格式迁移；现有配置继续有效。
+
+## [4.10.0-dsh.11] - 2026-10-04
+
+### Fixed
+- **客户端产物内嵌宿侧死代码 `import.meta`（C4 回归）**：`build-client.mjs` 模板残留一行
+  `const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skills')`
+  （4.10.0-dsh.10 引入），产物 `lib/client.js` 里零引用却携带 `import.meta`——宿主把 bundle
+  原样拼接进 `<script src>` 加载，浏览器解析即 SyntaxError，整个客户端 bundle 加载失败
+  （配置面板静默消失）。删除死行；`verify.mjs` 新增反向断言：`lib/client.js` 不得含
+  `import.meta` / `process.`（先破坏实测再还原）。
+- **默认档命令层分裂（真 bug）**：apply 启动判定与 UI 面板走 `resolvePriority`（含 patch 层），
+  而命令调度器未注入 `getDefaultMode` 时落到 `getDefaultMode()`（无 patch 层）。当
+  cordis.patch.yml 显式声明 `defaultMode` 且 config.json 缺失/不同时，`/ponytail foobar`
+  （上游 else 兜底切默认档）把等级从 patch 档切到 config 档，裸 `/ponytail` 报告档也错误。
+  修复：dispatcher 注入实时 `resolvePriority` 闭包（同 apply/UI 同源同刻），
+  三条消费路径统一真源。
+
+### Changed
+- **config.json 读侧收敛单一解析出口（C2）**：新增私有 `parseConfigObject(raw)` 归一解析
+  唯一真源，`readFullConfig` 退化为薄包装；`getDefaultMode`（无 patch 层、无 trim）与
+  `writeFullConfig`（保留未知键）语义不动。
+- **HTTP 快照合并单求值（C3）**：一次 GET/POST 快照内 `resolvePriority` 双调 + 双读盘
+  （最坏 4 次 readFileSync）合并为读一次 configMode → 单次求值，`defaultMode ===
+  priority.effective` 由结构保证并以行为测试锁定。
+- **技能禁用补文件优先收敛（C1）**：`PonytailState` 新增 `reloadDisabledSkills()`
+  （与等级侧 `syncFromFile` 同构，外部手改 config.json 后注入时收敛）；「禁用 ponytail →
+  关闭等级」规则提为 `isMainSkillDisabled()` 纯函数，HTTP POST 两分支共用同一守卫。
+
+### Removed
+- **`src/ponytail-runtime.ts`（C6）**：46 行薄壳（`resolveStateDir` 只是 `getConfigDir`
+  的无谓转发）内联进 `ponytail-state.ts`，净减 1 文件 + 一层间接委托；测试 import 与
+  verify 产物清单同步；`.gitignore` 排除 `.local/`（桌面版调试备份不入库）。
+- **ADR-0007**：记录命令层默认档并入 resolvePriority 真源（修订 ADR-0006 决策 1）、
+  读侧收敛、快照合并、flag 内联、C5 维持否决（宿主 collectCache 已兜底 list 侧）。
+
+### Migration
+- 命令层兜底切档语义变更：从「独立于 patch 层」变为「并入 patch 层」——这是修复而非回归
+  （分裂本身就是 bug）；无数据丢失，无配置格式变化。
+
+
+## [4.10.0-dsh.10] - 2026-10-04
+
+### Added
+- **客户端面板接入官方 `ctx.locale`（C6）**：新增 `@deepseek-ai/dsh-client-locale` 到 `dsh.client.inject`，面板全部文案经 `ctx.locale.register('ponytail', {zh, en})` + `bind` 双语提供（36 键成对，真源 `locale/*.json`），诊断链 label/problem 在客户端按 level 查字典覆盖（宿侧契约零改动），语言切换即时刷新；**技能说明保持中文不翻译**（用户边界）。`scripts/verify.mjs` 新增 locale 接入反向断言。
+- **HTTP 配置端点剥离为独立深工厂（C1）**：新增 `src/ponytail-http.ts` 的 `createConfigHttpEndpoint(deps)`，GET/POST/405、请求体解析、快照组装、技能元数据读取全部内聚，依赖全注入不碰 `ctx`，行为测试新增 5 条端点单测（此前 0 覆盖）。
+- **技能元数据单一真源（C2）**：宿侧 `readSkillMeta` 实时读取 `skills/*/SKILL.md` frontmatter 为唯一真源（读不到回退 `FALLBACK_SKILL_META`），客户端构建期提取内嵌；删除 `rawSkillsMeta` / `SKILL_META` 两处硬编码（6/6 技能文案原已漂移）。`verify.mjs` 反向断言锁死描述不回退到硬编码。
+- **行为测试 44 → 59 项全绿**：新增 C1 端点 5 条、C2 技能元数据 4 条、C3 写盘 3 条、C4 一致性 3 条。
+- **ADR-0006**：记录优先级与配置收敛、HTTP 剥离、元数据真源、客户端 locale 接入全部决策，含 C5 否决理由（官方 `skills/change` 是消费方通知缝，提供者反向 invalidate 会同步递归栈溢出）。
+
+### Changed
+- **优先级统一为 `resolvePriority` 唯一真源（C4）**：apply initialMode 与 GET/POST defaultMode 全部消费其 `effective`（此前三处并行实现）。**行为变更声明**：patch 显式值的大小写变体/非法值从「生效（注入垃圾态）」变为「忽略（落合法档）」。
+- **配置写盘字段级 merge（C3）**：`writeFullConfig` 保留 `config.json` 中用户手写的未知字段（不再重建为两键对象），defaultMode 非法值拒绝写盘返回 null；`writeDefaultMode` 退化为其薄包装。
+- **修复 `providerInstance` 死变量（C1）**：`skills.registerProvider` 工厂现捕获实例到 `providerInstance`，UI 变更后的 `invalidateSkills()` 从空操作恢复真实失效语义（此前 UI 改禁用技能后模型侧目录不刷新）。
+
+### Removed
+- **双孤儿函数**：`ponytail-config.ts` 的 `isDeactivationCommand`（`commands` 版唯一实现保留）与 `normalizeConfigMode`（全仓零调用方），以及失效类型 `VALID_MODES` / `ValidMode`。
+- **HTTP 端点从 `apply()` 剥离**：`src/ponytail.ts` 410 行 → 约 330 行，回归纯生命周期编排。
+
+### Migration
+- 行为变更：曾有非法/大小写 patch 显式值的现有配置在升级后按新语义忽略（落合法档），属有意修复，非数据丢失。
 
 ## [4.10.0-dsh.9] - 2026-10-04
 
@@ -229,7 +338,8 @@
 - 不注册 tool（不在 `ctx.tools` 注册任何占位），`scripts/verify.mjs` 校验
 - 构建：`pnpm build` (`tsc -p tsconfig.build.json`)，`pnpm typecheck`，`pnpm verify`
 
-[Unreleased]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.2...HEAD
+[Unreleased]: https://github.com/Wenaixi/dsh-ponytail/compare/v5.0.0...HEAD
+[5.0.0]: https://github.com/Wenaixi/dsh-ponytail/releases/tag/v5.0.0
 [4.10.0-dsh.2]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.1...v4.10.0-dsh.2
 [4.10.0-dsh.1]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.0...v4.10.0-dsh.1
 [4.10.0-dsh.0]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.9.0-dsh.5...v4.10.0-dsh.0
@@ -241,3 +351,10 @@
 [4.9.0-dsh.0]: https://github.com/Wenaixi/dsh-ponytail/releases/tag/v4.9.0-dsh.0
 
 [4.10.0-dsh.4]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.3...v4.10.0-dsh.4
+[4.10.0-dsh.5]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.4...v4.10.0-dsh.5
+[4.10.0-dsh.6]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.5...v4.10.0-dsh.6
+[4.10.0-dsh.7]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.6...v4.10.0-dsh.7
+[4.10.0-dsh.8]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.7...v4.10.0-dsh.8
+[4.10.0-dsh.9]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.8...v4.10.0-dsh.9
+[4.10.0-dsh.10]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.9...v4.10.0-dsh.10
+[4.10.0-dsh.11]: https://github.com/Wenaixi/dsh-ponytail/compare/v4.10.0-dsh.10...v4.10.0-dsh.11

package/README.md

@@ -22,7 +22,9 @@
 
 ---
 
-> [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) 的 DSH 完整移植：常驻懒人 senior 模式与七阶梯子（YAGNI 到最小实现），6 个中文原生技能（本体、评审、审计、债务、收益、帮助），零 tool 注册。
+> 这是面向 DeepSeek Harness 的 Ponytail 适配插件：提供常驻懒人 senior 模式、七阶梯子、6 个中文原生技能和零 tool 注册。实现参考 [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)，但本地版本、发布节奏和 DSH 兼容边界独立维护。
+>
+> **版本对照（2026-10-05 核验）**：本地发行版本为 `5.1.0`；上游参考版本为 `4.10.3`。上游参考版本不会自动决定本地版本号。
 
 ## 🚀 安装（默认装到 `web`）
 
@@ -54,7 +56,7 @@ dsh --profile web --dump-config | grep -A2 ponytail
 
 - **梯子 7 阶**：YAGNI → 复用 → 标准库 → 平台原生 → 已有依赖 → 一行 → 最小实现，`off` 时静默
 - **6 个中文 Skill**（`rank: 550`）：`ponytail` / `ponytail-review` / `ponytail-audit` / `ponytail-debt` / `ponytail-gain` / `ponytail-help`
-- **三档强度**：`lite` / `full`（默认）/ `ultra`
+- **四种运行模式**：`off` / `lite` / `full`（默认）/ `ultra`
 - **无 tool 注册**：全部能力经 `ctx.skills` 暴露
 
 | 能力 | 说明 |
@@ -68,19 +70,19 @@ dsh --profile web --dump-config | grep -A2 ponytail
 
 ## 🪝 Hook 注入
 
-> 上游 `hooks/` 的 6 个 Hook（config / instructions / runtime / activate / mode-tracker / subagent）已合并进单一 DSH 插件，无需宿主配置。
+> 上游 `hooks/` 的 6 个 Hook（config / instructions / runtime / activate / mode-tracker / subagent）已合并进单一 DSH 插件（runtime 的 flag 存取并入 state），无需宿主配置。
 
 | 上游 | DSH 侧 |
 |---|---|
 | `ponytail-config.js` | `src/ponytail-config.ts`（`env > 文件 > full`，`review` 不可默认） |
 | `ponytail-instructions.js` | `src/ponytail-instructions.ts`（唯一出口 `renderPromptSection(skillDir, state)`：review 短路 + 按档裁剪 + 中文 fallback 全部内聚） |
-| `ponytail-runtime.js` | `src/ponytail-runtime.ts`（`.ponytail-active`，DSH 单一宿主，无外部平台探针） |
+| `ponytail-state.js` | `src/ponytail-state.ts`（`.ponytail-active` 物理存取内联于此——上游 runtime 的 flag 存取已并入 state，DSH 单一宿主无外部探针；技能禁用 reload 收敛同在此） |
 | `ponytail-activate.js` | `src/ponytail.ts` 的 `agent/created`（startup/resume 对齐 flag） |
 | `ponytail-mode-tracker.js` | `src/ponytail-commands.ts` 的 `createCommandDispatcher`（指令解析纯函数 + 状态机副作用） |
 | `ponytail-subagent.js` | `src/ponytail.ts` 的 `agent/created`（`PONYTAIL_SUBAGENT_MATCHER`） |
 
 ```
-启动:  env PONYTAIL_DEFAULT_MODE → cordis defaultMode → $DSH_HOME/ponytail/config.json → full
+启动:  env PONYTAIL_DEFAULT_MODE → cordis defaultMode → full
        → setMode(flag 文件)   // 会话启动对齐语义，见下方说明
 
 每轮请求前: agent/pre-step (waterfall, 必须 return next())
@@ -90,14 +92,14 @@ dsh --profile web --dump-config | grep -A2 ponytail
       order 50 在 persona(0) 之后、工具(100) 之前；回调收敛为单行 text: () => renderPromptSection(skillDir, state)
       off → 空，review → 指向技能，读盘失败 → 中文 fallback，assembly 前以 readMode() 对齐
 
-持久化: /ponytail default <mode> → 写入 config.json
+持久化: /ponytail default <mode> → 写入 profile 补丁或 profile 内 config.json
 子智能体: PONYTAIL_SUBAGENT_MATCHER 正则（非法 warn 回退），共享同一 section
 HMR: 全部走 ctx，热重载逆序自动清理
 ```
 
-`systemPrompt` 而非 `agent.inject`：落入日志可重建，`order: 50` 优先级高，每次 `assemble` 动态求值，`off` 零成本。flag（`.ponytail-active`）与配置同源持久化于 DSH 用户数据根目录（`$DSH_HOME/ponytail`，默认 `~/.dsh/ponytail`），`/ponytail` 切换在 DSH 内闭环。
+`systemPrompt` 而非 `agent.inject`：落入日志可重建，`order: 50` 优先级高，每次 `assemble` 动态求值，`off` 零成本。flag（`.ponytail-active`）与配置同源持久化在当前 profile 内（`profiles/<name>/ponytail/`），`/ponytail` 切换在 DSH 内闭环。作用域随 profile 隔离，同机多实例互不干扰。
 
-**会话启动对齐**：每次会话启动都会按默认档（env > patch > 配置文件 > full）重写 flag，这是对齐上游 SessionStart 语义。因此 `/ponytail <档>` **只在本会话生效**；要让某个等级跨会话持久化，必须用 `/ponytail default <档>` 写进配置文件。
+**会话启动对齐**：每次会话启动都会按默认档（env > patch > full）重写 flag，这是对齐上游 SessionStart 语义。因此 `/ponytail <档>` **只在本会话生效**；要让某个等级跨会话持久化，必须用 `/ponytail default <档>` 写进配置文件。
 
 ## ⚙️ 配置
 
@@ -110,15 +112,24 @@ HMR: 全部走 ctx，热重载逆序自动清理
         defaultMode: full  # off|lite|full|ultra
 ```
 
-优先级（四级，取第一个有效值）：`PONYTAIL_DEFAULT_MODE` env > `cordis.defaultMode` > `$DSH_HOME/ponytail/config.json`（默认 `~/.dsh/ponytail/config.json`） > `full`。持久化：`/ponytail default <mode>` 写入文件，`review` 不可作默认。
+优先级（三级，取第一个有效值）：`PONYTAIL_DEFAULT_MODE` env > `cordis.defaultMode` > 内置兜底 `full`。持久化：`/ponytail default <mode>` 写入 profile 补丁，`review` 不可作默认。
 
-**注意**：`Config.defaultMode` 的 Schema 刻意不带默认值。Cordis 校验会把缺省 fill 成显式配置，一旦填上就会永久压过 `config.json` 里用户设置的档位，让 UI 上的改动看起来"不生效"。
+**注意**：`Config.defaultMode` 的 Schema 刻意不带默认值。Cordis 校验会把缺省 fill 成显式配置——补丁里显式写 `full` 与什么都不写会读出同一个值，诊断面板就无法区分"用户配过"与"没配过"，界面因此说谎。
 
 ### 界面配置
 
-插件在已安装插件卡片详情内嵌配置面板（`plugins.bundle.config` 插槽），支持四档运行等级、6 个技能的独立开关、一键恢复默认，并给出**四级优先级诊断链**——逐行显示环境变量、Profile 补丁、配置文件、内置兜底各自的值与生效状态，被更高优先级压制的那一级会显式标为"被覆盖"，等级选择器同时禁用。面板读写均经 `/api/plugins/ponytail/config`，落盘位置同样是 `$DSH_HOME/ponytail/config.json`。
+插件在已安装插件卡片详情内嵌配置面板（`plugins.bundle.config` 插槽），支持四档运行等级、6 个技能的独立开关、一键恢复默认，并给出**三级优先级诊断链**——逐行显示环境变量、Profile 补丁、内置兜底各自的值与生效状态，被更高优先级压制的那一级会显式标为"被覆盖"。只有环境变量命中时等级选择器才禁用（env 压过一切，此时改补丁确实无效）；兜底命中属于"补丁与 env 都没写"，不是更高优先级的配置，必须放行。
 
-若从旧位置（`%APPDATA%\ponytail` / `~/.config/ponytail`）升级，首次读取会兼容旧配置，但新写入一律落到 DSH 数据根；旧目录不删不改。
+面板不使用自制 HTTP 端点，读写分两条官方通道：
+
+| 通道 | 内容 | 落点 |
+| --- | --- | --- |
+| `ctx.configForms.get('ponytail')` | 默认档、技能启用列表（写入自带 revision 冲突检测） | Profile 补丁 `profiles/<name>/cordis.patch.yml` |
+| `ctx.remote.ponytail.snapshot()` | 当前生效等级、三级优先级诊断链（只读） | 不落盘，按需拉取 |
+
+在无 Profile 上下文的组合（headless / CLI）里，宿主没有装配 Settings 服务，此时配置读写回退到 profile 内的 `ponytail/config.json`。从旧版本升级时，全局共享的 `$DSH_HOME/ponytail/config.json` 会在首次启动时一次性导入 Profile 补丁，随后旧文件被改名为 `config.json.imported`；导入失败不影响启动，可用 `/ponytail default <档>` 重新设置。
+
+旧的平台位置（`%APPDATA%` / `XDG_CONFIG_HOME` / `~/.config`）兼容读取已随 1A 下沉一并删除；`scripts/verify.mjs` 现在对 `src/` 下任何平台路径字面量直接判失败。
 
 ## 🎮 使用
 
@@ -133,16 +144,17 @@ HMR: 全部走 ctx，热重载逆序自动清理
 # 四道门禁，改完必须全绿
 pnpm typecheck        # tsc --noEmit
 pnpm build            # tsc 出 lib/，再由 build-client.mjs 生成 lib/client.js
-node scripts/verify.mjs        # 静态门禁：产物清单、6 技能 frontmatter、description<=500、零 tool 注册、零平台路径字面量
-node scripts/behavior.test.mjs # 行为单测（44 项）
+node scripts/verify.mjs        # 静态门禁：38 条断言（含 client.js Node API 残留反向断言）（产物/技能/零 tool/落点/元数据真源/locale）
+node scripts/behavior.test.mjs # 行为单测（64 项）
 
 # 0 侵入联调
-dsh --profile web --patch ./cordis.patch.yml --dump-config
+dsh --profile web --patch ./cordis.patch.yml --dump-config  # 仅验证补丁解析，不替代真实启动验收
 pnpm dsh web --patch ./cordis.patch.yml   # 热重载
 ```
 
-- **版本策略**：与上游 SemVer 同步，每个版本固定带 `-dsh.N`（对齐上游 v4.10.0 重置为 `4.10.0-dsh.0`）。递增 `pnpm run bump:dsh`；上游发新版时 `pnpm run bump:dsh -- <版本>` 重置。
-- **发布铁律**：严禁本地 `npm publish`。发布通过推送 git tag（`git tag v4.10.0-dsh.N && git push origin v4.10.0-dsh.N`）触发 `publish.yml`，流水线内先跑全套门禁再幂等发布 npm 与 GitHub Release。
+- **版本策略**：本地发行版本使用独立的标准 SemVer，例如当前 `5.1.0`；使用 `pnpm version:bump` 递增 patch，或 `pnpm version:set -- 5.1.1` 设置明确版本。旧的 `-dsh.N` 仅属于历史版本策略，不再生成。
+- **上游参考**：README 记录上游参考版本和核验日期，但上游发布不会自动改变本地版本；是否升级参考实现由本地兼容性评估决定。
+- **发布铁律**：严禁本地 `npm publish` 和未经授权的 `git push`。本地完成门禁后，由授权的 CI tag 流程发布 npm 与 GitHub Release。
 - **客户端产物单一来源**：`lib/client.js` 只由 `scripts/build-client.mjs` 生成。`tsconfig.build.json` 不得把它列入编译输入，否则会出现同名双产物并静默漂移。
 
 ---