dsh-paoding 0.4.5 → 0.4.7

package/README.md

@@ -19,12 +19,13 @@ dsh-paoding（中文品牌「庖丁」，典出《庄子》——庖丁顺纹理
 - **按工作区各有各的班底**：不同项目可以配不同的主/子 agent——「庖丁配置」里选定工作区单独配置，每个工作区生成自己的预设（`orchestrator-<目录名>`），新建会话时选对应预设即可，全局默认不受影响。
 - **图形界面配置**：不习惯改配置文件的话，点开左侧栏底部动作条（设置行上方）的「庖丁配置」入口，整页点选即可，「保存并应用」即时重生成预设——与首装自动化同一条生成管线。
 - **工具条目支持通配符**：`*` 与 `?` 在生成期展开成具体工具名——`mcp__tavily__tavily_*` 一行顶五行，MCP 工具族不必逐个点名；零匹配有提醒，产物与运行时行为不变。
-- **保存前先体检**：预览/应用时自动过一遍检查——配置了但未挂载的工具、零工具角色、查无此名的模型、预设落后于配置，分级提示一目了然；CLI 侧 `dsh-paoding doctor` 六项只读自检（配置可解析、安装轨道、声明行托管块、孤儿目录、版本标记、预设漂移），一条命令查全身。
+- **保存前先体检**：预览/应用时自动过一遍检查——配置了但未挂载的工具、零工具角色、查无此名的模型、预设落后于配置，分级提示一目了然；预览还顺带列出「本次变更」逐项明细与主 agent 工具面瘦身统计，改了什么、省了多少都在明面上。CLI 侧 `dsh-paoding doctor` 六项只读自检（配置可解析、安装轨道、声明行托管块、孤儿目录、版本标记、预设漂移），一条命令查全身；`--fix` 自动修孤儿目录与过期声明行两类安全项。
 - **场景模板一键换班底**：轻量（只留实现）、调研（只留检索）、全开（全员到齐、主 agent 带满检测库存）三档点一下就切，只动「谁在场 + 主 agent 额外带什么」，精调过的角色配置分毫不动。
-- **配置可导出可导入**：面板「更多」菜单一键下载 `dsh-paoding.config.yml`，换机迁移、备份整份拷走；导入先验格式，覆盖整体配置（含工作区段）需二次确认。
+- **配置可导出可导入，还有后悔药**：面板「更多」菜单一键下载 `dsh-paoding.config.yml`，换机迁移、备份整份拷走；导入先验格式，覆盖整体配置（含工作区段）需二次确认。每次写盘前自动轮换备份三份，「恢复备份」二次确认即回退，误操作不用翻文件。
 - **HTTP 接口直连配置**：预设的列举、新增、更新、删除走 `/api/paoding/presets` 四条接口，随 DSH Web 服务同进程挂载、本机回环直调；与面板「保存并应用」同一条生成管线、同一把写盘互斥闸——脚本和自动化工具改班底，不必开浏览器。
 - **面板中英双语**：界面文案 zh/en 全覆盖，语言自动识别（显式选择 → 中文信号优先：浏览器语言、宿主页面语言、中文时区），「更多」菜单一键切换并记住。
 - **版本更新有提醒，面板一键升级**：面板会对比 npm registry（npmmirror 镜像、GitHub release 依次兜底）上的最新版本，发现新版就地提示并附上发布页链接；点「升级」就地换上新版（profile 自动探测：普通 profile 走 `dsh plugin update dsh-paoding`；desktop profile 被 dsh CLI 的 Electron 专属守卫挡住，改在 profile 目录直跑 `pnpm add dsh-paoding@<版本>`，pnpm 找不到时自动回落 `corepack pnpm`），重启 DSH 后生效，编排预设会在重启时按新版自动重生成。开发检出的 link 形态无法就地升级，面板会提示切回 registry 版的办法；检测失败时页头留一行「版本检测失败 · 重试」（完整原因与代理排查提示在悬浮提示里），不弹窗打扰。
+- **委派效果可量化**：面板「委派效果」卡按角色统计调用数、平均耗时与失败数（近 30 天），数据读宿主会话存档本地聚合——哪个角色用得多、哪个常掉链子，一眼可见；缺省项目（宿主 cwd 换算）扫不到任何委派记录时自动回落为全项目聚合（卡片标注「全部项目」），冷读带日志 mtime 预过滤，窗口外的日志文件不再开读句柄。
 - **来去自由**：不改 DSH 一行源码；装完新会话即用，卸载即删目录。
 - **两代宿主都兼容**：DSH 0.1.5 – 0.2.1 全支持（0.1.5 / 0.1.6 / 0.1.7-rc.1 / 0.1.7-rc.2 / 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2+）——两代宿主发现预设的机制不同（目录扫描 vs patch 声明行），安装器自动检测宿主版本选对落点；编排组合里的 workflow worker 行也按宿主版本自动适配（0.1.5 用 workflow-worker-thread，0.1.6+ 换 workflow-ptc——旧包 0.1.6 起已删除，残留行正是 0.2.0 面板上「加载失败」的元凶）；DSH 0.2.1 起角色委派行同步换代（0.2.1 的 dsh-tool-subagent 拒绝内联 persona/toolFilter——人设与工具面改挂各角色的 AgentPreset，spawn 子代理按 agentPreset 选择子预设；0.2.0 及以下保持内联形状），宿主升级、降级后的首次保存/自愈自动迁移（工作区专属预设 orchestrator-<slug> 随同轮自愈一并换代），全程无感；0.2.1 的 prerelease 再细分——tool-subagent 守卫自 0.2.1-rc.2 落地，rc.0/rc.1 仍按内联形状生成。
 
@@ -95,9 +96,9 @@ curl http://127.0.0.1:19387/api/paoding/presets
 | 文档 | 内容 |
 |---|---|
 | [架构](docs/architecture.md) | 为什么这样设计——概述、成本账、角色与工具、对应 DSH 原生机制、Token 治理、已知边界。 |
-| [安装](docs/installation.md) | 官方插件通道一条命令安装、版本支持与预设落点双轨（DSH 0.1.5 – 0.2.1）、首装自动化与版本标记、升级、开发检出自装、host patch 检测机制、庖丁配置面板、卸载、排查。 |
+| [安装](docs/installation.md) | 官方插件通道一条命令安装、版本支持与预设落点双轨（DSH 0.1.5 – 0.2.1）、首装自动化与版本标记、升级、开发检出自装、host patch 检测机制、庖丁配置面板、卸载（`dsh-paoding uninstall` 一条命令）、排查（doctor 可 `--fix`）。 |
 | [编排](docs/orchestration.md) | 编排总览、失败如何呈现与三层处理、one-shot vs continuable、上下文隔离。 |
-| [配置](docs/configuration.md) | 配置键全参考、工具条目通配符、内置角色微调、主 agent 工具与技能、自定义角色、按角色分模型、角色会话与启动方式、场景模板、配置导出导入、检查提示、HTTP 接口。 |
+| [配置](docs/configuration.md) | 配置键全参考、工具条目通配符、内置角色微调、主 agent 工具与技能、自定义角色、按角色分模型、角色会话与启动方式、场景模板、配置导出导入与备份回滚、检查提示、HTTP 接口。 |
 
 ## 贡献
 

package/README_en.md

@@ -19,9 +19,10 @@ dsh-paoding (Chinese brand 「庖丁」/ Pao Ding, from the Zhuangzi parable of
 - **A different lineup per workspace**: each project can carry its own main/sub-agent setup — pick the workspace in 庖丁配置, configure it separately, and it gets its own preset (`orchestrator-<basename>`); choose that preset when starting a session. The global default stays untouched.
 - **A visual configurator**: prefer clicking to editing YAML? the 庖丁配置 (Paoding Config) entry in the sidebar bottom action bar (above the Settings row) covers everything; Save & Apply regenerates the preset on the spot — the same generation pipeline as first-install automation.
 - **Tool entries support wildcards**: `*` and `?` expand into concrete tool names at generation time — one `mcp__tavily__tavily_*` line covers the whole family; zero-match patterns get a warning, and artifacts and runtime behavior stay unchanged.
-- **A health check before every save**: preview/apply runs a built-in check — tools configured but not mounted, zero-tool roles, unknown model names, a preset lagging behind the config — each flagged by severity; on the CLI side, `dsh-paoding doctor` runs six read-only checks (config parses, install track, managed declaration block, orphan directories, version marker, preset drift) in one command.
+- **A health check before every save**: preview/apply runs a built-in check — tools configured but not mounted, zero-tool roles, unknown model names, a preset lagging behind the config — each flagged by severity; the preview also lists an itemized "changes since the last save" diff and the main-agent tool-surface stat, so what changed and what it saves are both on the table. On the CLI side, `dsh-paoding doctor` runs six read-only checks (config parses, install track, managed declaration block, orphan directories, version marker, preset drift) in one command; `--fix` automatically repairs the two safe categories (orphan directories, stale declaration rows).
 - **Scenario templates swap the roster in one click**: Lite (implement only), Research (search roles only), and Full (everyone on deck, main agent carrying the whole detected inventory) — templates only touch who is present and what the main agent carries; hand-tuned role settings are never touched.
-- **Config export & import**: download `dsh-paoding.config.yml` from the panel's More menu for migration or backup; imports are validated first, and overwriting the whole config (workspaces included) asks for confirmation.
+- **Delegation stats you can act on**: the panel's "Delegation" card counts delegations, average duration, and failures per role (last 30 days), aggregated locally from the host session archive — which roles get used, and which keep dropping the ball, at a glance.
+- **Config export & import, with an undo**: download `dsh-paoding.config.yml` from the panel's More menu for migration or backup; imports are validated first, and overwriting the whole config (workspaces included) asks for confirmation. Every write first rotates three automatic backups, and "Restore backup" puts one back after a confirming dialog — a mistake never means digging through files.
 - **Config over HTTP**: list, create, update, and delete presets through the four `/api/paoding/presets` endpoints, served in-process by the DSH web service and callable over loopback; they ride the panel's Save & Apply generation pipeline and share its write lock, so scripts and automation tools can reshape the roster without opening a browser.
 - **Panel in English and Chinese**: every UI string ships in both languages, auto-detected (explicit choice first, then Chinese signals — browser language, host page language, Chinese time zones — outrank English ones, since the Electron shell pins navigator to en-US regardless of the OS), switchable from the More menu and remembered.
 - **Notified of new releases, one-click upgrade in the panel**: the panel compares your local version against the latest npm registry publish (npmmirror and GitHub release as successive fallbacks) and points to the release page when a newer one is out. The Upgrade button swaps in the new version in place (profile auto-detected): regular profiles go through `dsh plugin update dsh-paoding`, while the Electron-owned desktop profile — which the dsh CLI guards against — gets a direct `pnpm add dsh-paoding@<version>` run in the profile directory, falling back to `corepack pnpm` when no bare pnpm is on PATH; a DSH restart applies it, and the orchestrator preset regenerates itself against the new version on startup. A dev checkout in link: form cannot be upgraded in place — the panel tells you how to switch back to the registry version. If the check fails (offline, rate-limited), a subdued "version check failed · retry" row stays in the header (full causes and proxy hints in its tooltip) without popping anything up.
@@ -95,9 +96,9 @@ Writes go through the same generation pipeline and write lock as the panel's Sav
 | Document | Contents |
 |---|---|
 | [Architecture](docs/architecture_en.md) | Why it is designed this way — overview, the cost ledger, roles and tools, mapping to DSH's native mechanisms, token governance, known limits. |
-| [Installation](docs/installation_en.md) | The single official channel (`dsh plugin add`), version support and the dual preset landing (DSH 0.1.5 – 0.2.1), first-install automation and the version marker, upgrading, dev-checkout install, host patch detection, the Paoding Config panel, uninstalling, troubleshooting. |
+| [Installation](docs/installation_en.md) | The single official channel (`dsh plugin add`), version support and the dual preset landing (DSH 0.1.5 – 0.2.1), first-install automation and the version marker, upgrading, dev-checkout install, host patch detection, the Paoding Config panel, uninstalling (one `dsh-paoding uninstall` command), troubleshooting (doctor with `--fix`). |
 | [Orchestration](docs/orchestration_en.md) | Orchestration overview, how failures surface and the three recovery layers, one-shot vs continuable, context isolation. |
-| [Configuration](docs/configuration_en.md) | The full key reference, tool-entry wildcards, tuning built-in roles, main-agent tools and skills, custom roles, per-role models, per-role session and start modes, scenario templates, config export/import, health-check hints, the HTTP API. |
+| [Configuration](docs/configuration_en.md) | The full key reference, tool-entry wildcards, tuning built-in roles, main-agent tools and skills, custom roles, per-role models, per-role session and start modes, scenario templates, config export/import and backup-rollback, health-check hints, the HTTP API. |
 
 ## Contributing
 

package/bin/dsh-paoding.mjs

@@ -15,16 +15,27 @@ const REFUSE =
 const usage = `dsh-paoding 安装快捷方式（等价于 dsh plugin --profile <name> add dsh-paoding@<version>）
 
 用法：npx dsh-paoding@latest [--profile <name>]
-      npx dsh-paoding@latest doctor [--profile <name>] [--config <file>]
+      npx dsh-paoding@latest doctor [--profile <name>] [--config <file>] [--fix] [--yes]
+      npx dsh-paoding@latest uninstall [--purge] [--yes] [--config <file>]
 
 子命令：
-  doctor            本机安装体检（只读）：配置文件 / 预设轨道 / 托管声明行 /
+  doctor            本机安装体检（默认只读）：配置文件 / 预设轨道 / 托管声明行 /
                     孤儿工作区预设 / 预设漂移 / 版本标记，结尾给汇总；
-                    有错误级发现时退出码 1。
+                    有错误级发现时退出码 1。--fix 对其中可安全自动修的两类动手
+                    （孤儿预设目录、孤儿/过期声明行；写盘前备份 .bak-1），其余
+                    发现只给处理建议，输出逐项标注「已修 / 需手动」。
+  uninstall         清理庖丁写进宿主目录的东西：cordis.patch.yml 托管声明块、
+                    .agent-presets 下的 orchestrator* 预设目录、.generator-version
+                    标记。默认保留配置文件及其备份（用户数据），--purge 才连配置
+                    一起删；不碰插件包自身（包本体用 dsh plugin remove 卸载）。
+                    非交互终端（非 TTY）下没带 --yes 只列计划不执行，退出码 2。
 
 选项：
   --profile <name>  插件装入的 profile，默认 web（dsh web 的默认 profile）
-  --config <file>   配置文件路径（仅 doctor 子命令使用）
+  --config <file>   配置文件路径（doctor / uninstall 子命令使用）
+  --purge           uninstall 连配置文件及其备份一起删（默认保留）
+  --yes             跳过逐类确认直接执行（uninstall / doctor --fix）
+  --fix             doctor 体检后自动修可安全处理的问题
   --help            显示本帮助
   --version         显示包版本
 
@@ -36,17 +47,18 @@ const { version } = JSON.parse(readFileSync(new URL('../package.json', import.me
 
 const argv = process.argv.slice(2);
 
-// doctor 子命令：包不再携带独立 CLI，但 tools/ 随包发布（package.json files），
-// 体检逻辑本体在 tools/lib/cli.mjs——这里 dynamic import 转发（--profile /
-// --config 等参数原样透传，由它自己的 parseArgs 解析），退出码语义：
-// 无错误 0，有 error 级发现 1。放在参数循环之前：doctor 的参数不用本入口的
+// doctor / uninstall 子命令：包不再携带独立 CLI，但 tools/ 随包发布
+//（package.json files），逻辑本体在 tools/lib/cli.mjs——这里 dynamic import
+// 转发（--profile / --config / --fix / --purge / --yes 等参数原样透传，由它
+// 自己的 parseArgs 解析），退出码语义：成功 0，有 error 级发现或清理失败 1，
+// 非 TTY 无 --yes 的防呆拒做 2。放在参数循环之前：子命令的参数不用本入口的
 // profile 解析兜底。
-if (argv.includes('doctor')) {
+if (argv.includes('doctor') || argv.includes('uninstall')) {
   try {
     const { main } = await import('../tools/lib/cli.mjs');
     process.exit((await main({ argv })) ?? 0);
   } catch (err) {
-    console.error(`doctor 运行失败：${err?.message ?? err}`);
+    console.error(`子命令运行失败：${err?.message ?? err}`);
     process.exit(1);
   }
 }

package/docs/configuration.md

@@ -33,6 +33,7 @@ dsh-paoding 把「按角色分工的编排 preset」做成**配置驱动**：你
 | 顶层键 | 类型 | 语义 |
 |---|---|---|
 | `profile` | string | 检测时纳入哪个 profile 的 patch 层（`$DSH_HOME/profiles/<profile>/cordis.patch.yml`）；缺省 `web` |
+| `patch_layer` | `'home' \| 'profile'` | 庖丁声明行写入哪个 patch 层的托管块：`home` = `$DSH_HOME/cordis.patch.yml`，`profile` = `$DSH_HOME/profiles/<profile>/cordis.patch.yml`。缺省（键缺失 / `null`）= 按环境自动判定：Android 宿主或 compat 壳（DSH 家目录在容器路径下）自动落 `profile` 层，其余环境落 `home` 层；非法值告警并忽略（按缺省自动判定）。判定细节与迁移行为见 1.4 |
 | `roles` | map | `toolName` → `{ persona?, name?, tools[], model?, provider?, start_mode?, background_mode? }`。对内置三角色（`search_external` / `design` / `implement`）：覆盖 persona 与 allow 意图，并可配 `name` 显示名（只替换该角色默认 persona 首行身份句的主语，见 2.4）、专用模型（`model` / `provider`，见 2.5）、会话模式（`background_mode`，见 2.6）与启动方式（`start_mode`，见 2.7）；其它键名 = **自定义角色**：生成全新 `delegation-<toolName>` 块并把 toolName 注入主 agent 的 `config.allow`（详见第 2、6 节） |
 | `roles_remove` | string[] | 整条删除的内置角色 toolName 列表（只认 `search_external` / `design` / `implement`，其它名字忽略并告警；缺省 = `[]`）。删除 = 委派行 / 工具面 / 角色 persona / 主 agent 侧委派指引全部不再生成（详见 2.3） |
 | `skills` | map | `skill` → 分配给该技能的角色 toolName 列表；安装时把 `Available skills: …` 引导句写进这些角色 persona 的尾部（详见第 7 节） |
@@ -124,6 +125,24 @@ skills:                 # skill -> 分配给的角色（写进角色 persona 的
 - `roles.code-reviewer` 安装后生成 `delegation-code-reviewer` 委派块，主 agent 白名单加入 `code-reviewer`，对话里直接调该 toolName 即可委派。
 - `main_agent_persona_extra` 里的 `{{cwd}}` / `{{model}}` 是 DSH 运行时替换的占位符，必须原样保留。
 
+### 1.4 patch 层判定与 Android compat 壳（dsh-maoying#1）
+
+庖丁的预设声明行写在 `$DSH_HOME` 下某个 `cordis.patch.yml` 的托管块里（`# --- dsh-paoding presets (auto-generated; do not edit) ---` 与结束标记之间）。patch 层有两处：
+
+- **home 层**：`$DSH_HOME/cordis.patch.yml`（桌面 / Linux 直装环境的缺省）。
+- **profile 层**：`$DSH_HOME/profiles/<profile>/cordis.patch.yml`（Android compat 壳的缺省，`<profile>` 取 `--profile` 参数 > 配置 `profile` 键 > `web`）。
+
+**判定优先级**：配置 `patch_layer` 键 > 环境变量 `DSH_PAODING_PATCH_LAYER` > 自动判定（Android 平台或 DSH 家目录在 `/data/(user|data)/` 容器路径下 → `profile` 层；其余 → `home` 层）。
+
+**为什么 Android 上要落 profile 层**：compat 壳（DeepSeekHarnessCompat）每次 boot 都会**重写 home 层** `cordis.patch.yml`，把 preset 注册表元数据压平成 `- id: 显示名 (英文名)` + 深缩进键的坏行——宿主在任何插件代码运行前就死于 YAML 解析（dsh-maoying#1 同款问题，跟本插件无关也会被牵连）。声明行搬进 profile 层后，compat 壳不再碰它。
+
+配套护栏（0.4.6 起）：
+
+- **写盘校验 + 逐字节回滚**：每次托管块写入（补行 / 撤行 / 整盘重生成）后整文件重新解析一遍，解析不过就回滚为写入前的精确字节并报错（错误信息含行号与 `dsh-paoding doctor` 指引）——文件已含坏行时，宁可不动也不把坏文件写得更坏。
+- **可疑行探测**：启动自愈与 `dsh-paoding doctor` 会扫描托管块**外**的 `- id:` 坏行（id 含空白或非 ASCII，形如 compat 壳压平产物），只警告点名行号不自动删。
+- **层迁移**：目标层是 `profile` 而目标层文件存在时，写入成功后会自动撤掉 home 层的庖丁托管块（用户内容逐字节保留）；反方向同理（`reconcilePatchLayers`）。
+- **doctor 双层体检**：托管块损坏 / 整文件解析失败为 error（后者 = 宿主启动必死），可疑行为 warn，托管块落在非目标层报「层漂移」warn（下次自愈 / 保存会迁移）。
+
 ## 2. 默认角色微调
 
 ### 2.1 persona 与 tools 的覆盖语义
@@ -739,6 +758,8 @@ workspaces:
 - 落盘即改 mtime，面板的检测状态缓存按对账自动失效，视图随后按新配置重建。
 - 与「保存并应用」共用同一把写盘互斥闸：应用进行中导入（或反过来）会收到 409，稍后重试即可。
 
+**备份与恢复**：凡是往配置文件写盘的动作（保存并应用、导入、恢复备份）都会先把当前文件轮换备份三份——`dsh-paoding.config.yml.bak-1`（最新）到 `.bak-3`，逐份后移、最旧的淘汰；备份与配置文件同目录，首次保存前没有旧值就不备份。回滚走「更多」→「恢复备份…」：列出各备份的生成时间与大小，二次确认后整份覆盖回当前配置（恢复前当前文件还会再自动备份一份，连按恢复也能原路退回）；恢复同样先验格式（解析不出顶层映射的备份拒收），共用写盘互斥闸。没有面板时，手动把 `.bak-N` 拷回主文件名即可。
+
 ## 12. 检查提示（体检）
 
 预览或应用后，若服务端体检发现问题，预览区上方会出现一张**检查提示**卡：逐条列出示意，红（error）/ 琥珀（warn）/ 中性（info）三色分级，悬停可见检查项代号（排障用）。没有问题就没有这张卡，零占位。
@@ -755,6 +776,8 @@ workspaces:
 
 作废口径：**预览**产生的提示随配置草稿的任何改动一并作废（与预览同一逻辑）；**应用**产生的提示描述的是已落盘结果，保留到下一次预览或应用。应用失败时错误 toast 照旧，同时卡片给出每条失败原因；应用成功但存在 warn/error 级提示时，成功 toast 会换成琥珀档「有 N 条检查提示，见下方」。
 
+体检之外，预览还带两样「看得见」的东西：一是**本次变更**——相对上次保存配置的逐项明细（角色增删、各角色工具与 persona、专用模型、启动方式、后台续跑、主 agent 工具增删、`roles_remove` 与 `main_agent_extra` 通道），没有任何改动就一行「与上次保存的配置一致」；二是**工具面瘦身统计**——主 agent 当前 allow 数对照单体全量数的百分比，页头常驻一份（按已保存配置），预览区再示一份（按当前未保存配置），保存前后各看各的。
+
 ## 13. HTTP 接口
 
 插件的 Web 后端随 DSH Web 服务同进程挂载在 `/api/paoding/*` 前缀下（回环地址 + 端口随部署，信任围栏与面板一致），面板能做的配置读写，脚本与自动化工具也能照做。预设对象的完整 CRUD 四条：

package/docs/configuration_en.md

@@ -33,6 +33,7 @@ The key names below match `normalizeConfig` in `tools/lib/config.mjs` — the si
 | Top-level key | Type | Semantics |
 |---|---|---|
 | `profile` | string | Which profile's patch layer (`$DSH_HOME/profiles/<profile>/cordis.patch.yml`) is scanned during detection; default `web` |
+| `patch_layer` | `'home' \| 'profile'` | Which patch layer receives Paoding's managed preset rows: `home` = `$DSH_HOME/cordis.patch.yml`, `profile` = `$DSH_HOME/profiles/<profile>/cordis.patch.yml`. Default (key missing / `null`) = automatic per environment: Android hosts and compat shells (DSH home under a container path) land on the `profile` layer, everything else on the `home` layer; an invalid value is warned about and ignored (falls back to automatic). See 1.4 for the full decision chain and migration behavior |
 | `roles` | map | `toolName` → `{ persona?, name?, tools[], model?, provider?, start_mode?, background_mode? }`. For the three built-in roles (`search_external` / `design` / `implement`): overrides the persona and the allow intent, and may carry a `name` display name (rewrites the subject of that role's default persona identity sentence and prefixes its delegation labels — see 2.4), a dedicated model (`model` / `provider`, see 2.5), a session mode (`background_mode`, see 2.6) and a start mode (`start_mode`, see 2.7). Any other key is a **custom role**: the installer emits a fresh `delegation-<toolName>` block and injects the toolName into the main agent's `config.allow` (sections 2 and 6) |
 | `roles_remove` | string[] | toolNames of built-in roles deleted wholesale (only `search_external` / `design` / `implement` are accepted; other names are ignored with a warning; default `[]`). Deleting means the delegation block / tool surface / role persona / main-agent delegation guidance are no longer generated (see 2.3) |
 | `skills` | map | `skill` → the list of role toolNames the skill is assigned to; the installer appends an `Available skills: …` guidance sentence to those roles' personas (section 7) |
@@ -124,6 +125,24 @@ Notes:
 - After installation, `roles.code-reviewer` becomes a generated `delegation-code-reviewer` block, `code-reviewer` joins the main-agent allow list, and the main agent can delegate to it directly by calling that toolName.
 - `{{cwd}}` and `{{model}}` inside `main_agent_persona_extra` are persona placeholders that DSH substitutes at runtime — keep them verbatim.
 
+### 1.4 Patch layer selection and the Android compat shell (dsh-maoying#1)
+
+Paoding writes its preset rows into the managed block (`# --- dsh-paoding presets (auto-generated; do not edit) ---` … end marker) of one `cordis.patch.yml` under `$DSH_HOME`. There are two patch layers:
+
+- **home layer**: `$DSH_HOME/cordis.patch.yml` (the default on desktop / plain-Linux installs).
+- **profile layer**: `$DSH_HOME/profiles/<profile>/cordis.patch.yml` (the default on the Android compat shell; `<profile>` resolves from the `--profile` argument > the config `profile` key > `web`).
+
+**Decision order**: the config `patch_layer` key > the `DSH_PAODING_PATCH_LAYER` environment variable > automatic detection (Android platform, or the DSH home under a `/data/(user|data)/` container path → the `profile` layer; otherwise → the `home` layer).
+
+**Why Android lands on the profile layer**: the compat shell (DeepSeekHarnessCompat) rewrites the home-layer `cordis.patch.yml` on every boot, flattening the preset-registry metadata into malformed rows like `- id: Display Name (English Name)` with deeply indented keys — the host dies at YAML parse time before any plugin code runs (the dsh-maoying#1 failure shape; it takes down the host even when Paoding is not involved). With the rows living in the profile layer, the compat shell no longer touches them.
+
+Guard rails shipped alongside (since 0.4.6):
+
+- **Write validation + exact-byte rollback**: every managed-block write (row backfill / row strip / full regen) re-parses the whole file afterwards; if it fails to parse, the file is rolled back to the exact pre-write bytes and an error is raised (with a line number and a `dsh-paoding doctor` hint). When a file already contains bad rows, doing nothing beats writing it into a worse state.
+- **Suspect-row detection**: startup self-heal and `dsh-paoding doctor` scan for `- id:` rows **outside** the managed block whose id contains whitespace or non-ASCII characters (the compat-shell flattening shape); they warn with line numbers and never auto-delete.
+- **Layer migration**: when the target layer is `profile` and that file exists, a successful write also strips Paoding's managed block from the home layer (user content preserved byte-for-byte); the reverse direction works the same way (`reconcilePatchLayers`).
+- **Doctor checks both layers**: a damaged managed block and a whole-file parse failure are errors (the latter means the host cannot boot at all); suspect rows are warnings; a managed block sitting in a non-target layer reports a "layer drift" warning (the next self-heal / save migrates it).
+
 ## 2. Tuning the built-in roles
 
 ### 2.1 Override semantics of persona and tools
@@ -751,6 +770,8 @@ The header "More" menu offers export and import of the whole config file (the §
 - Writing changes the file's mtime, so the panel's detection-state cache invalidates automatically through the existing reconciliation, and the view rebuilds from the new config.
 - Import shares the same in-flight write gate as "save & apply": applying during an import (or the reverse) answers 409 — retry shortly.
 
+**Backups and restore**: every action that writes the config file (save & apply, import, restore) first rotates the current file through three backups — `dsh-paoding.config.yml.bak-1` (newest) to `.bak-3`, each shifting one slot and the oldest falling off; backups live next to the config file, and a first-ever save with no previous file backs up nothing. Rollback runs through "More" → "Restore backup…": each backup is listed with its time and size, one confirming dialog puts it back in place (the current file is backed up once more first, so even a mistaken restore can be walked back); the restore validates the backup too (a backup that parses to a non-mapping is rejected) and shares the write gate. Without the panel, copy a `.bak-N` back over the main filename by hand.
+
 ## 12. Check messages (health review)
 
 After a preview or an apply, if the server-side health review finds problems, a **check messages** card appears above the preview area: one row per finding, color-coded red (error) / amber (warn) / neutral (info), with the check code available on hover for troubleshooting. No findings — no card, zero footprint.
@@ -767,6 +788,8 @@ Entries come from the structured health review (`tools/lib/health.mjs`); codes a
 
 Invalidation scope: messages from a **preview** are discarded together with the draft on any config edit (same rule as the preview itself); messages from an **apply** describe what has already been written and survive until the next preview or apply. When an apply fails, the error toast stays as usual and the card lists every reason; when an apply succeeds but warn/error-level findings exist, the success toast switches to the amber variant "N check messages, see below".
 
+Beside the checks, a preview carries two more pieces of visibility. One is **changes since the last save** — an itemized diff against the saved config (roles added/removed, each role's tools and persona, dedicated model, start mode, background continuation, main-agent tool changes, the `roles_remove` and `main_agent_extra` channels); with nothing changed it collapses to a single "identical to the last saved config" line. The other is the **tool-surface stat** — the main agent's current allow count against the monolithic total as a percentage: one permanent line in the header (from the saved config) and one in the preview (from the unsaved config), one for each side of a save.
+
 ## 13. HTTP API
 
 The plugin's web backend is mounted under the `/api/paoding/*` prefix inside the DSH web server itself (loopback address + port per your deployment; the same trust fence as the panel). Anything the panel can do to the config, scripts and automation can do too. Full CRUD for preset objects:

package/docs/installation.md

@@ -48,7 +48,7 @@ dsh plugin --profile web add dsh-paoding
 
 ### profile 语义
 
-`--profile web` 决定插件装进哪个 profile：「庖丁配置」面板只在以该 profile 启动的 DSH Web 里出现。`web` 是 `dsh web` 的默认 profile，多数机器无需改动；多 profile 用户对每个需要的 profile 各执行一次 `dsh plugin add`。编排预设本体落在 `$DSH_HOME/.agent-presets/`，全机共享、不随 profile 走——DSH ≥ 0.1.7 的声明行写在 home 层 `$DSH_HOME/cordis.patch.yml`，同样与 profile 无关——在任何 profile 的面板里「保存并应用」，写的都是同一份预设。
+`--profile web` 决定插件装进哪个 profile：「庖丁配置」面板只在以该 profile 启动的 DSH Web 里出现。`web` 是 `dsh web` 的默认 profile，多数机器无需改动；多 profile 用户对每个需要的 profile 各执行一次 `dsh plugin add`。编排预设本体落在 `$DSH_HOME/.agent-presets/`，全机共享、不随 profile 走——DSH ≥ 0.1.7 的声明行缺省写在 home 层 `$DSH_HOME/cordis.patch.yml`（Android compat 壳或配置 `patch_layer: profile` 时改写 profile 层 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`，见下节「patch 层与写盘护栏」）——在任何 profile 的面板里「保存并应用」，写的都是同一份预设。
 
 ### 版本支持与预设落点双轨（DSH 0.1.5 – 0.2.1）
 
@@ -57,7 +57,7 @@ dsh plugin --profile web add dsh-paoding
 两代宿主发现「本地 authored preset」的机制不同，安装器据此分双轨落点，宿主检测全自动、用户无感：
 
 - **目录轨（DSH ≤ 0.1.6）**：宿主扫描 `$DSH_HOME/.agent-presets/` 下的目录来发现 preset，目录即注册。安装器照旧把产物写成 `$DSH_HOME/.agent-presets/orchestrator/`（`agent.cordis.yml` + `preset.yml` + `restrict.mjs` + `delegation-labels.mjs`）；按工作区配置生成的预设落同目录下的 `orchestrator-<slug>`。
-- **声明行轨（DSH ≥ 0.1.7）**：宿主不再扫目录，改为读取 patch 里的 `@deepseek-ai/dsh-agent-preset` 声明行。安装器在 `$DSH_HOME/cordis.patch.yml` 里维护一个托管块——以 `# --- dsh-paoding presets (auto-generated; do not edit) ---` 起始、以配套的 end 标记收尾——块内用 `- insert:` 写声明行：全局预设 `config.id: orchestrator`，工作区预设 `config.id: orchestrator-<slug>`，各自的 `plugins` 内联全部插件行；`restrict.mjs` / `delegation-labels.mjs` 以绝对 `file:` URL 引用。产物四件套仍落在 `.agent-presets/<id>/`，只是从「目录即注册」变成「文件存放处」。托管块之外的用户内容一字节不动；块内带 do not edit 标记，手改块内内容会在下次保存时被覆盖。
+- **声明行轨（DSH ≥ 0.1.7）**：宿主不再扫目录，改为读取 patch 里的 `@deepseek-ai/dsh-agent-preset` 声明行。安装器在目标 patch 层（缺省 home 层 `$DSH_HOME/cordis.patch.yml`；Android compat 壳 / `patch_layer: profile` 时为 profile 层 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`，见下节「patch 层与写盘护栏」）里维护一个托管块——以 `# --- dsh-paoding presets (auto-generated; do not edit) ---` 起始、以配套的 end 标记收尾——块内用 `- insert:` 写声明行：全局预设 `config.id: orchestrator`，工作区预设 `config.id: orchestrator-<slug>`，各自的 `plugins` 内联全部插件行；`restrict.mjs` / `delegation-labels.mjs` 以绝对 `file:` URL 引用。产物四件套仍落在 `.agent-presets/<id>/`，只是从「目录即注册」变成「文件存放处」。托管块之外的用户内容一字节不动；块内带 do not edit 标记，手改块内内容会在下次保存时被覆盖。
 
 安装器按下面的顺序判定走哪条轨：
 
@@ -94,6 +94,10 @@ dsh plugin --profile web add dsh-paoding
 
 面板不监视配置文件改动；想立刻按当前配置重新生成，点面板「保存并应用」。
 
+### patch 层与写盘护栏（Android compat 壳，dsh-maoying#1）
+
+声明行写在哪一层由判定链决定：配置 `patch_layer` 键 > 环境变量 `DSH_PAODING_PATCH_LAYER` > 自动判定（Android 平台或 DSH 家目录在 `/data/(user|data)/` 容器路径下 → profile 层；其余 → home 层）。为什么 Android 要落 profile 层：compat 壳（DeepSeekHarnessCompat）每次 boot 重写 home 层 `cordis.patch.yml`，把 preset 注册表元数据压平成 `- id: 显示名 (英文名)` + 深缩进键的坏行，宿主在任何插件代码运行前就死于 YAML 解析（dsh-maoying#1 同款问题）——声明行搬进 profile 层后 compat 壳不再碰它；层切换后的首次写入会自动撤掉另一层的庖丁托管块（用户内容逐字节保留）。写盘护栏：每次托管块写入后整文件重新解析一遍，解析不过立即回滚为写入前字节并报错（含行号与 `dsh-paoding doctor` 指引）；启动自愈与 `dsh-paoding doctor` 会扫描托管块外的可疑坏行（id 含空白或非 ASCII，形如 compat 壳压平产物），只警告点名行号不自动删——`dsh-paoding doctor` 的双层体检把「整文件解析失败」报为 error（宿主启动必死），可疑行为 warn，托管块落在非目标层报「层漂移」warn。
+
 ### 基础模板与工具勾选
 
 全新安装（无配置文件）生成的基础模板只含 DSH 自带的基础工具——主 agent 21 项核心工具，加各委派角色的基础工具集；检测到的 host/MCP 工具**默认不写入**。检测管线照常运行：点开左侧栏「庖丁配置」，候选清单列出全部已识别工具，按需勾选后点「保存并应用」即可。
@@ -191,22 +195,30 @@ patch 与配置文件用 **`yaml` 包**解析——通过 `createRequire` 从 `$
 
 ### 数据接口与安全
 
-面板数据走**同源 `/api/paoding/*`**：Node 侧注册前缀路由——`GET /api/paoding/state`（带缓存的检测状态）、`GET /api/paoding/version`（最新版检测，版本/更新卡的数据源）、`GET /api/paoding/models`（宿主模型运行时的模型清单）、`GET` + `POST /api/paoding/workspaces`（工作区列表 / 添加工作区）、`POST /api/paoding/rescan`（强制重检测，含 MCP 握手）、`POST /api/paoding/preview`（不写盘生成）、`POST /api/paoding/apply`（安装并保存配置）、`POST /api/paoding/upgrade`（就地升级：普通 profile 走 `dsh plugin update`，desktop profile 直跑 `pnpm add`，pnpm 按「裸 pnpm → `corepack pnpm` → PNPM_HOME 落位」候选链解析）、`GET /api/paoding/config/export`（配置文件原文导出，下载/备份用）、`POST /api/paoding/config/import`（整份导入：先验格式、与「保存并应用」共用写盘闸）、`GET /api/paoding/client.css`（面板样式静态下发）——复用 `tools/` 的检测与生成管线（`plugins/paoding-config-ui/api-core.mjs`）。路由自带**浏览器信任围栏**：Host 必须回环或落在 `webRuntime.trustedHosts`，并拒绝 cross-site 请求（复刻 DSH `/api` 网关围栏语义，因为 `/api/paoding` 前缀更长会命中本插件而绕开网关）。面板**没有独立服务端/端口**：DSH Web 端口只监听 `127.0.0.1`，不对外网暴露。
+面板数据走**同源 `/api/paoding/*`**：Node 侧注册前缀路由——`GET /api/paoding/state`（带缓存的检测状态）、`GET /api/paoding/version`（最新版检测，版本/更新卡的数据源）、`GET /api/paoding/models`（宿主模型运行时的模型清单）、`GET` + `POST /api/paoding/workspaces`（工作区列表 / 添加工作区）、`POST /api/paoding/rescan`（强制重检测，含 MCP 握手）、`POST /api/paoding/preview`（不写盘生成）、`POST /api/paoding/apply`（安装并保存配置）、`POST /api/paoding/upgrade`（就地升级：普通 profile 走 `dsh plugin update`，desktop profile 直跑 `pnpm add`，pnpm 按「裸 pnpm → `corepack pnpm` → PNPM_HOME 落位」候选链解析）、`GET /api/paoding/config/export`（配置文件原文导出，下载/备份用）、`POST /api/paoding/config/import`（整份导入：先验格式、与「保存并应用」共用写盘闸）、`GET /api/paoding/config/backups`（自动备份清单）、`POST /api/paoding/config/restore`（恢复备份：文件名白名单防穿越，先验可解析再覆盖）、`GET /api/paoding/stats`（委派效果统计：冷读会话存档聚合，days 窗口与 project 过滤）、`GET /api/paoding/client.css`（面板样式静态下发）——复用 `tools/` 的检测与生成管线（`plugins/paoding-config-ui/api-core.mjs`）。路由自带**浏览器信任围栏**：Host 必须回环或落在 `webRuntime.trustedHosts`，并拒绝 cross-site 请求（复刻 DSH `/api` 网关围栏语义，因为 `/api/paoding` 前缀更长会命中本插件而绕开网关）。面板**没有独立服务端/端口**：DSH Web 端口只监听 `127.0.0.1`，不对外网暴露。
 
 ### 面板能力
 
-- **状态与操作**：页头是标题 + 版本/更新卡（新版就地提示与一键升级）+ 副标题，正文直接就是工作区与角色卡，没有单独的检测摘要与 chips 区；操作按钮「**保存并应用**」「预览生成」「重新检测」固定在面板底部悬浮操作坞（sticky bottom），滚动任意位置都可直接点击。
-- **Agent 工具分配卡片**：主 agent 一张固定卡（基础工具取消勾选 = 加入 `main_agent_remove` 从主 agent 剔除；MCP / 插件工具勾选 = 加入 `main_agent_extra`；技能「read 按需」与「内联全文」两组勾选；另有「人设追加」编辑区，可改、清空、恢复默认）＋ `search_external` / `design` / `implement` 三张内置角色卡 ＋ 任意自定义角色卡（带删除按钮）；每张角色卡把工具按「基础工具 / MCP 工具 / 插件工具」三组呈现、可逐项勾选，并可编辑 persona。底部「新建自定义 agent 角色」。
+- **状态与操作**：页头是标题 + 版本/更新卡（新版就地提示与一键升级）+ 副标题，副标题下一行常驻主 agent 工具面瘦身统计（当前 allow 数 / 单体全量数与瘦身百分比，配完第一次能看到省了多少），正文直接就是工作区与角色卡，没有单独的检测摘要与 chips 区；操作按钮「**保存并应用**」「预览生成」「重新检测」固定在面板底部悬浮操作坞（sticky bottom），滚动任意位置都可直接点击。
+- **Agent 工具分配卡片**：主 agent 一张固定卡（基础工具取消勾选 = 加入 `main_agent_remove` 从主 agent 剔除；MCP / 插件工具勾选 = 加入 `main_agent_extra`；技能「read 按需」与「内联全文」两组勾选；另有「人设追加」编辑区，可改、清空、恢复默认）＋ `search_external` / `design` / `implement` 三张内置角色卡 ＋ 任意自定义角色卡（带删除按钮）；每张角色卡把工具按「基础工具 / MCP 工具 / 插件工具」三组呈现、可逐项勾选（任一组超过 8 项时组顶出现筛选框，输入即滤），并可编辑 persona。底部「新建自定义 agent 角色」。
 - **技能分配**：每个 skill 一行，勾选分配给哪些 agent（写入对应 persona 的 `Available skills` 软引导；角色技能软引导，主 agent 技能另有 read 按需/内联两组）。
-- **预览生成**：不写盘生成 `agent.cordis.yml`，显示每个角色 allow 的 intent → kept 计数与生成全文。
+- **预览生成**：不写盘生成 `agent.cordis.yml`，显示每个角色 allow 的 intent → kept 计数与生成全文；同时列「本次变更」——相对上次保存配置的逐项明细（角色增删、各角色工具与 persona、专用模型、启动方式、后台续跑、主 agent 工具增删），无改动时一行带过；瘦身统计在这里按当前未保存配置另示一行。
 - **保存并应用**：确认后写入 preset（覆盖 `$DSH_HOME/.agent-presets/orchestrator`）并按宿主版本同步登记——≤ 0.1.6 目录扫描即生效，≥ 0.1.7 同步维护 `$DSH_HOME/cordis.patch.yml` 里的声明行托管块（见第 2 节）——再把当前分配保存到 `$DSH_HOME/dsh-paoding.config.yml`；应用成功后提示重启 DSH 或新建会话生效（检测到 patch 比生成结果新时提示重启后生效）。打开面板时会加载既有配置文件作为当前值——手编过的选择直接可见、可改。
 - **场景模板**：页头三档切换（轻量：只留实现角色；调研：只留检索角色；全开：全员到齐、主 agent 额外工具带满检测库存），一键换「班底」；只动 `roles_remove` 与 `main_agent_extra`，各角色精调过的工具面、persona、模型、启动方式分毫不动，切回即原样复原。
 - **检查提示卡**：每次「预览生成 / 保存并应用」自动过一遍体检（配置了未挂载的工具、零工具角色、查无此名的模型、预设落后于配置），分级提示以卡片形式贴在页头下方，处理完再保存不迟。
-- **「更多」菜单**：配置导出（下载 `dsh-paoding.config.yml` 原文）/ 导入（先验格式，整份覆盖含工作区段，需二次确认）与面板语言切换（中英自动识别、手动选择优先并记住）。
+- **备份与回滚**：保存、导入、恢复配置前都会自动把当前配置轮换备份三份（`config.yml.bak-1..3`，新压旧）；「更多」→「恢复备份…」列时间与大小、二次确认后回退，恢复前当前配置还会再自动备份一份——误操作有后悔药。
+- **委派效果统计**：页头「委派效果」卡按角色统计被委派的调用数、平均耗时与失败数（近 30 天，`days` 参数可调）。数据来自宿主会话存档的冷读——经宿主 `sessionPersistence` 服务逐会话抽摘要、本地聚合，不出机、不带负载；失败记的是子会话零轮次或轮次中断（spawn 后即死、中途终止两种形态）。缺省项目（宿主 cwd 换算）扫不到任何委派记录时自动回落为全项目聚合（响应 `project='all'`，卡片标注「全部项目」）；冷读带日志 mtime 预过滤，窗口外的日志文件不再开读句柄。宿主缺会话服务时整卡不渲染。
+- **「更多」菜单**：配置导出（下载 `dsh-paoding.config.yml` 原文）/ 导入（先验格式，整份覆盖含工作区段，需二次确认）/ 恢复备份（见上条）与面板语言切换（中英自动识别、手动选择优先并记住）。
 
 ## 7. 卸载
 
-三条命令，删得干干净净：
+先用一条命令清掉庖丁写进宿主目录的东西（托管声明块、`orchestrator*` 预设目录、版本标记；配置文件默认保留，`--purge` 才连配置与备份一起删；非交互终端需加 `--yes`）：
+
+```bash
+npx dsh-paoding@latest uninstall
+```
+
+包本体再按 profile 摘掉，三条命令删得干干净净：
 
 ```bash
 dsh plugin --profile web remove dsh-paoding
@@ -216,7 +228,7 @@ rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets"/orchestrator-*
 
 第一条摘掉插件与侧栏面板（只影响指定 profile），第二条删掉编排预设目录，第三条清掉按工作区配置时生成的各工作区预设目录（`orchestrator-<目录名>`；没用过按工作区配置就没有这类目录，通配不命中、无害）——基础 `orchestrator` 目录已由上一条命令删掉，不含在这个通配里。配置文件 `~/.dsh/dsh-paoding.config.yml` 不随之上删——留着或删掉都不影响 DSH 其它配置，重装时首装自动化会再次按它应用。
 
-宿主为 DSH ≥ 0.1.7 时再多看一眼：`$DSH_HOME/cordis.patch.yml` 里可能还留着 dsh-paoding 托管块（起止标记注释包着 `- insert:` 声明行）。预设目录删掉后，块内声明行就成了指向已删目录的悬空引用，请把整个托管块（从 `# --- dsh-paoding presets (auto-generated; do not edit) ---` 起始行到 end 标记行）一并删去——块外内容不受影响。
+（走了上面的 `uninstall` 就免了这一步和下一眼的托管块手删——它已一并清掉。）宿主为 DSH ≥ 0.1.7 时若手动删目录，再多看一眼：`$DSH_HOME/cordis.patch.yml` 里可能还留着 dsh-paoding 托管块（起止标记注释包着 `- insert:` 声明行）。预设目录删掉后，块内声明行就成了指向已删目录的悬空引用，请把整个托管块（从 `# --- dsh-paoding presets (auto-generated; do not edit) ---` 起始行到 end 标记行）一并删去——块外内容不受影响。
 
 卸载不影响 host 的其它内容（MCP、插件、会话等），与 DSH 源码零耦合；之后新建会话时「编排模式 (Orchestrator)」不再出现在预设选择器里。
 
@@ -232,6 +244,8 @@ npx dsh-paoding@latest doctor          # 或仓库内：node tools/install.mjs d
 
 doctor 不改任何文件，逐项检查并给出 `✔ 正常 / ⚠ 警告 / ✘ 错误 / – 跳过` 四档结论：配置文件能否解析、预设安装轨道与宿主版本是否匹配、托管声明行有无孤儿行或损坏块、`.agent-presets/orchestrator-*` 有没有配置里已不引用的孤儿目录、已装预设与当前配置的再生成结果有无漂移、`.generator-version` 版本标记是否对得上。结尾有汇总；出现 ✘ 时退出码为 1，⚠ 与 – 不影响使用（跳过多见于全新机器，属正常）。`--config` / `--profile` 与安装时同义。
 
+`doctor --fix` 会在这份诊断之后自动修两类可安全处理的问题——孤儿 `orchestrator-*` 预设目录、托管块里的孤儿/过期声明行（写盘前自动备份 `.bak-1`），其余发现只给处理建议不代做（预设漂移就提示跑 `--auto` 重新生成）；输出逐项标注「已修 / 需手动」。非交互终端下 `--fix` 与 `uninstall` 都要显式 `--yes` 才落盘，否则只列计划、退出码 2。
+
 面板侧也有同源的保存时体检：每次「预览生成 / 保存并应用」的响应都带 `warnings` 字段（配置了未挂载工具、零工具角色、角色专用模型不在模型目录、预设落后于配置等），按条目提示处理即可，不用等运行时报错。
 
 **pnpm 缺失**

package/docs/installation_en.md

@@ -48,7 +48,7 @@ The orchestrator preset needs no separate install — the plugin fills it in aut
 
 ### Profile semantics
 
-`--profile web` decides which profile the plugin is installed into: the Paoding Config page appears only in a DSH Web launched with that profile. `web` is the default profile of `dsh web`, so most machines need no change; multi-profile users run `dsh plugin add` once per profile they want it in. The orchestrator preset itself lives under `$DSH_HOME/.agent-presets/` and is shared machine-wide, independent of profiles — under DSH ≥ 0.1.7 the declaration rows go into the home-layer `$DSH_HOME/cordis.patch.yml`, equally profile-independent — Save & Apply from any profile's panel writes the same preset.
+`--profile web` decides which profile the plugin is installed into: the Paoding Config page appears only in a DSH Web launched with that profile. `web` is the default profile of `dsh web`, so most machines need no change; multi-profile users run `dsh plugin add` once per profile they want it in. The orchestrator preset itself lives under `$DSH_HOME/.agent-presets/` and is shared machine-wide, independent of profiles — under DSH ≥ 0.1.7 the declaration rows go into the home-layer `$DSH_HOME/cordis.patch.yml` by default (on the Android compat shell, or with `patch_layer: profile` in the config, they go into the profile layer at `$DSH_HOME/profiles/<profile>/cordis.patch.yml` instead — see "Patch layers and write guard rails" below) — Save & Apply from any profile's panel writes the same preset.
 
 ### Version support and the dual preset landing (DSH 0.1.5 – 0.2.1)
 
@@ -57,7 +57,7 @@ The plugin supports two host generations: **DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 / 0.1
 The two generations discover "local authored presets" differently, so the installer maintains a dual landing, detecting the host automatically — nothing for the user to do:
 
 - **Directory track (DSH ≤ 0.1.6)**: the host discovers presets by scanning directories under `$DSH_HOME/.agent-presets/` — the directory is the registration. The installer writes the artifacts to `$DSH_HOME/.agent-presets/orchestrator/` (`agent.cordis.yml` + `preset.yml` + `restrict.mjs` + `delegation-labels.mjs`) as before; workspace-specific presets land in sibling `orchestrator-<slug>` directories.
-- **Declaration track (DSH ≥ 0.1.7)**: the host no longer scans directories; it reads `@deepseek-ai/dsh-agent-preset` declaration rows from the patch instead. The installer maintains a managed block in `$DSH_HOME/cordis.patch.yml` — opening with `# --- dsh-paoding presets (auto-generated; do not edit) ---` and closing with the matching end marker — whose `- insert:` rows write the declarations: the global preset gets `config.id: orchestrator`, a workspace preset gets `config.id: orchestrator-<slug>`, each with all plugin rows inlined under `plugins`; `restrict.mjs` / `delegation-labels.mjs` are referenced by absolute `file:` URLs. The artifact quartet still lands in `.agent-presets/<id>/` — demoted from "the directory is the registration" to "a place where the files live". User content outside the block is left untouched, byte for byte; the block carries a do-not-edit marker, and anything hand-edited inside it is overwritten by the next save.
+- **Declaration track (DSH ≥ 0.1.7)**: the host no longer scans directories; it reads `@deepseek-ai/dsh-agent-preset` declaration rows from the patch instead. The installer maintains a managed block in the target patch layer (home layer `$DSH_HOME/cordis.patch.yml` by default; on the Android compat shell or with `patch_layer: profile`, the profile layer at `$DSH_HOME/profiles/<profile>/cordis.patch.yml` — see "Patch layers and write guard rails" below) — opening with `# --- dsh-paoding presets (auto-generated; do not edit) ---` and closing with the matching end marker — whose `- insert:` rows write the declarations: the global preset gets `config.id: orchestrator`, a workspace preset gets `config.id: orchestrator-<slug>`, each with all plugin rows inlined under `plugins`; `restrict.mjs` / `delegation-labels.mjs` are referenced by absolute `file:` URLs. The artifact quartet still lands in `.agent-presets/<id>/` — demoted from "the directory is the registration" to "a place where the files live". User content outside the block is left untouched, byte for byte; the block carries a do-not-edit marker, and anything hand-edited inside it is overwritten by the next save.
 
 The installer decides which track to take in this order:
 
@@ -94,6 +94,10 @@ The `.generator-version` marker is written by the plugin's startup self-heal aft
 
 The panel does not watch the config file; to regenerate from the current config right away, hit Save & Apply.
 
+### Patch layers and write guard rails (Android compat shell, dsh-maoying#1)
+
+Which layer receives the declaration rows follows a decision chain: the config `patch_layer` key > the `DSH_PAODING_PATCH_LAYER` environment variable > automatic detection (Android platform, or the DSH home under a `/data/(user|data)/` container path → the profile layer; otherwise → the home layer). Why Android lands on the profile layer: the compat shell (DeepSeekHarnessCompat) rewrites the home-layer `cordis.patch.yml` on every boot, flattening the preset-registry metadata into malformed rows like `- id: Display Name (English Name)` with deeply indented keys, and the host dies at YAML parse time before any plugin code runs (the dsh-maoying#1 failure shape) — with the rows living in the profile layer, the compat shell no longer touches them; the first write after a layer switch also strips Paoding's managed block from the other layer (user content preserved byte for byte). Write guard rails: every managed-block write re-parses the whole file afterwards, and on failure rolls back to the exact pre-write bytes and raises an error (with a line number and a `dsh-paoding doctor` hint); startup self-heal and `dsh-paoding doctor` scan for suspect rows outside the managed block (ids containing whitespace or non-ASCII characters — the compat-shell flattening shape) and warn with line numbers without auto-deleting — the doctor's dual-layer check reports a whole-file parse failure as an error (the host cannot boot at all), suspect rows as warnings, and a managed block sitting in a non-target layer as a "layer drift" warning.
+
 ### Base template and tool opt-in
 
 A fresh install (no config file) generates the base template: only DSH's built-in base tools — the main agent's 21 core tools plus each delegated role's base set. Detected host/MCP tools are **not written in** by default. The detection pipeline still runs: open 庖丁配置 in the sidebar, the candidate list shows every recognized tool, opt in as needed, and hit Save & Apply.
@@ -191,22 +195,30 @@ If you'd rather not hand-edit `dsh-paoding.config.yml`, open the **庖丁配置
 
 ### Data interface and security
 
-Panel data goes over the **same-origin `/api/paoding/*`**: the Node side registers prefix routes — `GET /api/paoding/state` (cached detection state), `GET /api/paoding/version` (latest-version check, the data source of the version/update card), `GET /api/paoding/models` (model list from the host LLM runtime), `GET` + `POST /api/paoding/workspaces` (list / add workspaces), `POST /api/paoding/rescan` (forced re-detection, MCP handshakes included), `POST /api/paoding/preview` (generate without writing), `POST /api/paoding/apply` (install and save config), `POST /api/paoding/upgrade` (in-place upgrade: `dsh plugin update` for regular profiles, a direct `pnpm add` for the desktop profile — pnpm is resolved through a candidate chain: bare `pnpm` → `corepack pnpm` → PNPM_HOME locations), `GET /api/paoding/config/export` (raw config file for download/backup), `POST /api/paoding/config/import` (whole-file import: validated first, shares the apply write mutex), `GET /api/paoding/client.css` (statically served panel stylesheet) — reusing the detection/generation pipeline in `tools/` (`plugins/paoding-config-ui/api-core.mjs`). The routes carry a **browser trust fence**: the Host must be loopback or listed in `webRuntime.trustedHosts`, and cross-site requests are rejected (mirroring DSH's `/api` gateway fence semantics, since the longer `/api/paoding` prefix would otherwise hit this plugin and bypass the gateway). The panel has **no separate server or port**: the DSH Web port listens on `127.0.0.1` only and is never exposed to the outside.
+Panel data goes over the **same-origin `/api/paoding/*`**: the Node side registers prefix routes — `GET /api/paoding/state` (cached detection state), `GET /api/paoding/version` (latest-version check, the data source of the version/update card), `GET /api/paoding/models` (model list from the host LLM runtime), `GET` + `POST /api/paoding/workspaces` (list / add workspaces), `POST /api/paoding/rescan` (forced re-detection, MCP handshakes included), `POST /api/paoding/preview` (generate without writing), `POST /api/paoding/apply` (install and save config), `POST /api/paoding/upgrade` (in-place upgrade: `dsh plugin update` for regular profiles, a direct `pnpm add` for the desktop profile — pnpm is resolved through a candidate chain: bare `pnpm` → `corepack pnpm` → PNPM_HOME locations), `GET /api/paoding/config/export` (raw config file for download/backup), `POST /api/paoding/config/import` (whole-file import: validated first, shares the apply write mutex), `GET /api/paoding/config/backups` (automatic backup list), `POST /api/paoding/config/restore` (restore a backup: filename whitelist against path traversal, validated for parseability before overwriting), `GET /api/paoding/stats` (delegation stats: cold-read aggregation over the session archive, with a days window and project filter), `GET /api/paoding/client.css` (statically served panel stylesheet) — reusing the detection/generation pipeline in `tools/` (`plugins/paoding-config-ui/api-core.mjs`). The routes carry a **browser trust fence**: the Host must be loopback or listed in `webRuntime.trustedHosts`, and cross-site requests are rejected (mirroring DSH's `/api` gateway fence semantics, since the longer `/api/paoding` prefix would otherwise hit this plugin and bypass the gateway). The panel has **no separate server or port**: the DSH Web port listens on `127.0.0.1` only and is never exposed to the outside.
 
 ### Panel capabilities
 
-- **State and actions**: the page header is a title + version/update card (in-place new-version notice and one-click upgrade) + subtitle, and the body goes straight to the workspace and role cards with no separate detection-summary/chips section; the action buttons「**保存并应用**」(Save & Apply), Preview, and Rescan sit in a sticky bottom dock, clickable from any scroll position.
-- **Agent tool-assignment cards**: one fixed card for the main agent (unchecking a base tool adds it to `main_agent_remove`, dropping it from the main agent; checking an MCP / plugin tool adds it to `main_agent_extra`; skills in two groups, "read on demand" and "inline full text"; plus a "persona extra" editor — edit, clear, or restore the default) ＋ three built-in role cards (`search_external` / `design` / `implement`) ＋ any number of custom role cards (with a delete button); every role card presents its tools in three groups — base / MCP / plugin — with per-item checkboxes, and the persona is editable. "Create a custom agent role" at the bottom.
+- **State and actions**: the page header is a title + version/update card (in-place new-version notice and one-click upgrade) + subtitle, with a permanent main-agent tool-surface line under the subtitle (current allow count vs the monolithic total, plus the slimming percentage — the first visible payoff of configuring), and the body goes straight to the workspace and role cards with no separate detection-summary/chips section; the action buttons「**保存并应用**」(Save & Apply), Preview, and Rescan sit in a sticky bottom dock, clickable from any scroll position.
+- **Agent tool-assignment cards**: one fixed card for the main agent (unchecking a base tool adds it to `main_agent_remove`, dropping it from the main agent; checking an MCP / plugin tool adds it to `main_agent_extra`; skills in two groups, "read on demand" and "inline full text"; plus a "persona extra" editor — edit, clear, or restore the default) ＋ three built-in role cards (`search_external` / `design` / `implement`) ＋ any number of custom role cards (with a delete button); every role card presents its tools in three groups — base / MCP / plugin — with per-item checkboxes (any group over 8 items grows a filter box on top; type to narrow), and the persona is editable. "Create a custom agent role" at the bottom.
 - **Skill assignment**: one row per skill, check which agents it goes to (written into the matching personas as `Available skills` soft guidance; role skills are soft guidance, main-agent skills have the read-on-demand/inline groups).
-- **Preview**: generates `agent.cordis.yml` without writing, showing each role's intent → kept counts plus the full generated text.
+- **Preview**: generates `agent.cordis.yml` without writing, showing each role's intent → kept counts plus the full generated text; it also lists "changes since the last save" — an itemized diff (roles added/removed, each role's tools and persona, dedicated model, start mode, background continuation, main-agent tool changes) reduced to a single line when nothing changed; the tool-surface stat appears here too, computed from the unsaved config.
 - **Save & Apply**: after confirmation, writes the preset (overwriting `$DSH_HOME/.agent-presets/orchestrator`) and registers it per host generation — on ≤ 0.1.6 the directory scan picks it up as-is, on ≥ 0.1.7 the declaration managed block in `$DSH_HOME/cordis.patch.yml` is maintained in the same pass (see §2) — then saves the current assignments to `$DSH_HOME/dsh-paoding.config.yml`; success asks you to restart DSH or start a new session (and flags when a patch is newer than the generated output). Opening the panel loads the existing config file as the current values — hand-edited choices are visible and editable right away.
 - **Scenario templates**: three one-click presets in the header (Lite: implement role only; Research: search roles only; Full: everyone on deck with the main agent carrying the whole detected inventory) swap the roster — they only touch `roles_remove` and `main_agent_extra`; each role's hand-tuned tools, persona, model, and start mode stay untouched and restore as-is when you switch back.
 - **Health-check card**: every Preview / Save & Apply runs a check pass (tools configured but not mounted, zero-tool roles, unknown model names, a preset lagging behind the config); findings show as a severity-tagged card under the header so you can fix them before saving.
-- **"More" menu**: config export (download the raw `dsh-paoding.config.yml`) / import (validated first; overwrites the whole file, workspaces included, with confirmation) and the panel language toggle (English/Chinese auto-detected, manual choice wins and is remembered).
+- **Backups and rollback**: every write to the config (save & apply, import, restore) first rotates the current file through three backups — `config.yml.bak-1` (newest) through `.bak-3`; "More" → "Restore backup…" lists each backup's time and size and, after a confirming dialog, puts it back (the current file is backed up once more before the restore, so even a wrong restore can be undone).
+- **Delegation stats**: the "Delegation" card in the header counts, per role, delegations, average duration, and failures (last 30 days, adjustable via `days`). The data is a cold read of the host session archive — summaries drawn per session through the host `sessionPersistence` service and aggregated locally; nothing leaves the machine and no payloads are read. A failure means the child session ran zero turns or was interrupted mid-turn (died right after spawn, or cut off). When the host lacks the session service the card simply doesn't render.
+- **"More" menu**: config export (download the raw `dsh-paoding.config.yml`) / import (validated first; overwrites the whole file, workspaces included, with confirmation) / restore backup (see above) and the panel language toggle (English/Chinese auto-detected, manual choice wins and is remembered).
 
 ## 7. Uninstalling
 
-Three commands, and it's gone cleanly:
+One command first clears what dsh-paoding wrote into the host directory (the managed declaration block, the `orchestrator*` preset directories, the version marker; the config file is kept unless `--purge`; non-interactive terminals need `--yes`):
+
+```bash
+npx dsh-paoding@latest uninstall
+```
+
+Then lift the package itself off the profile with three commands:Three commands, and it's gone cleanly:
 
 ```bash
 dsh plugin --profile web remove dsh-paoding

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-paoding",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "庖丁 — DSH (DeepSeek Harness) 编排模式安装器：host 感知的角色工具过滤 + Web 设置页可视化配置器",
   "type": "module",
   "license": "MIT",