dsh-paoding 0.3.3 → 0.3.4

package/README.md

@@ -19,6 +19,7 @@ dsh-paoding（中文品牌「庖丁」，典出《庄子》——庖丁顺纹理
 - **图形界面配置**：不习惯改配置文件的话，点开左侧栏底部动作条（设置行上方）的「庖丁配置」入口，整页点选即可，「保存并应用」即时重生成预设——与首装自动化同一条生成管线。
 - **版本更新有提醒，面板一键升级**：面板会对比 npm registry（GitHub release 兜底）上的最新版本，发现新版就地提示并附上发布页链接；点「升级」就地执行 `dsh plugin update dsh-paoding`（profile 自动探测）换上新版，重启 DSH 后生效，编排预设会在重启时按新版自动重生成。开发检出的 link 形态无法就地升级，面板会提示切回 registry 版的办法；检测失败（比如断网）就静默跳过，不影响任何使用。
 - **来去自由**：不改 DSH 一行源码；装完新会话即用，卸载即删目录。
+- **两代宿主都兼容**：DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 全支持——两代宿主发现预设的机制不同（目录扫描 vs patch 声明行），安装器自动检测宿主版本选对落点，宿主升级、降级后的首次保存/自愈自动迁移，全程无感。
 
 ## 插件截图
 
@@ -26,7 +27,7 @@ dsh-paoding（中文品牌「庖丁」，典出《庄子》——庖丁顺纹理
 
 ## 快速开始
 
-前置：**Node.js ≥ 18**、**pnpm** 与一台已装好的 DSH host（**@deepseek-ai/dsh ≥ 0.1.5**，最低支持版本）。
+前置：**Node.js ≥ 18**、**pnpm** 与一台已装好的 DSH host（**@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.1** 全支持，预设落点自动适配两代宿主机制）。
 
 **官方插件通道（唯一安装入口）**——不用克隆仓库，一条命令，装完重启即用：
 
@@ -36,7 +37,7 @@ dsh plugin --profile web add dsh-paoding
 
 等价捷径：`npx dsh-paoding@latest`（内部转成上面这条命令，默认 profile web，需本机已装 dsh）。npx 拉到哪版就装哪版：实际安装的是 `dsh-paoding@<npx 拉取到的版本>`。
 
-`dsh plugin` 是 pnpm 的透明转发器：包被 pnpm 装进 profile，包内声明的 bundle patch 把「庖丁配置」面板挂进 DSH Web 左侧栏。**重启 DSH（`dsh web`）**即完成全部安装——插件启动时会自动检测，编排预设缺失或版本不符就自动生成一次（有 `~/.dsh/dsh-paoding.config.yml` 按配置应用，没有则写基础模板），无需再点任何按钮。新会话的预设选择器里选「编排模式 (Orchestrator)」即可；要设为默认，在 Settings → Agent Presets 里选。
+`dsh plugin` 是 pnpm 的透明转发器：包被 pnpm 装进 profile，包内声明的 bundle patch 把「庖丁配置」面板挂进 DSH Web 左侧栏。**重启 DSH（`dsh web`）**即完成全部安装——插件启动时会自动检测，编排预设缺失或版本不符就自动生成一次（有 `~/.dsh/dsh-paoding.config.yml` 按配置应用，没有则写基础模板），无需再点任何按钮。DSH 0.1.7 起宿主改用 patch 声明行发现预设，插件会自动改写登记方式，装法不变。新会话的预设选择器里选「编排模式 (Orchestrator)」即可；要设为默认，在 Settings → Agent Presets 里选。
 
 开箱默认只带 DSH 自带的基础工具，检测到的 MCP/host 工具不会自动写入——装完点开左侧栏的**「庖丁配置」**按需勾选工具与角色，「保存并应用」即生效。不想要了，三条命令卸干净（按工作区配置生成的各工作区预设也一并删除）：
 
@@ -46,6 +47,8 @@ rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets/orchestrator"
 rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets"/orchestrator-*
 ```
 
+宿主是 DSH 0.1.7+ 时再补一步：删去 `~/.dsh/cordis.patch.yml` 里的 dsh-paoding 托管块（带 auto-generated 起止标记），免得留下指向已删目录的声明行（详见[安装文档](docs/installation.md)第 7 节）。
+
 **开发检出自装**——想改插件或预设源码时，用 link 形态直连仓库（改动经 HMR/重启生效）：
 
 ```bash
@@ -77,7 +80,7 @@ dsh plugin --profile web add link:"$PWD/dsh-paoding"
 | 文档 | 内容 |
 |---|---|
 | [架构](docs/architecture.md) | 为什么这样设计——概述、成本账、角色与工具、对应 DSH 原生机制、Token 治理、已知边界。 |
-| [安装](docs/installation.md) | 官方插件通道一条命令安装、首装自动化与版本标记、升级、开发检出自装、host patch 检测机制、庖丁配置面板、卸载、排查。 |
+| [安装](docs/installation.md) | 官方插件通道一条命令安装、版本支持与预设落点双轨（DSH 0.1.5 – 0.1.7-rc.1）、首装自动化与版本标记、升级、开发检出自装、host patch 检测机制、庖丁配置面板、卸载、排查。 |
 | [编排](docs/orchestration.md) | 编排总览、失败如何呈现与三层处理、one-shot vs continuable、上下文隔离。 |
 | [配置](docs/configuration.md) | 配置键全参考、内置角色微调、主 agent 工具与技能、自定义角色、按角色分模型、角色会话模式。 |
 

package/README_en.md

@@ -19,6 +19,7 @@ dsh-paoding (Chinese brand 「庖丁」/ Pao Ding, from the Zhuangzi parable of
 - **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.
 - **Notified of new releases, one-click upgrade in the panel**: the panel compares your local version against the latest npm registry publish (GitHub release as fallback) and points to the release page when a newer one is out. The Upgrade button runs `dsh plugin update dsh-paoding` in place (profile auto-detected) to swap in the new version; 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), it stays silent and nothing is interrupted.
 - **Installs and uninstalls cleanly**: no DSH source changes; active in a new session right after install, gone when you delete one directory.
+- **Works on both host generations**: DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 are all supported — the two generations discover presets differently (directory scan vs patch declaration rows), and the installer picks the right landing automatically, then migrates on the first save/self-heal after a host upgrade or downgrade, all without user action.
 
 ## Screenshots
 
@@ -26,7 +27,7 @@ dsh-paoding (Chinese brand 「庖丁」/ Pao Ding, from the Zhuangzi parable of
 
 ## Quick Start
 
-Prerequisites: **Node.js ≥ 18**, **pnpm**, and a working DSH host (**@deepseek-ai/dsh >= 0.1.5**, the minimum supported version).
+Prerequisites: **Node.js ≥ 18**, **pnpm**, and a working DSH host (**@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.1**, all supported — the preset landing adapts to the host generation automatically).
 
 **The official plugin channel (the only install route)** — no clone needed; one command, then a restart:
 
@@ -36,7 +37,7 @@ dsh plugin --profile web add dsh-paoding
 
 Equivalent shortcut: `npx dsh-paoding@latest` (delegates to the command above; default profile web; requires dsh on PATH). Whichever version npx pulls is what gets installed: the actual install is `dsh-paoding@<the version npx resolved>`.
 
-`dsh plugin` is a transparent pass-through to pnpm: the package is installed into the profile by pnpm, and the bundle patch declared inside it mounts the 庖丁配置 (Paoding Config) page into the DSH Web left sidebar. **Restart DSH (`dsh web`)** and the install is complete — on startup the plugin checks itself, and if the orchestrator preset is missing or carries an outdated version marker it regenerates it once (applying `~/.dsh/dsh-paoding.config.yml` when present, writing the base template otherwise). Nothing else to click. Pick "编排模式 (Orchestrator)" in the new-session preset selector; to make it the default, choose it in Settings → Agent Presets.
+`dsh plugin` is a transparent pass-through to pnpm: the package is installed into the profile by pnpm, and the bundle patch declared inside it mounts the 庖丁配置 (Paoding Config) page into the DSH Web left sidebar. **Restart DSH (`dsh web`)** and the install is complete — on startup the plugin checks itself, and if the orchestrator preset is missing or carries an outdated version marker it regenerates it once (applying `~/.dsh/dsh-paoding.config.yml` when present, writing the base template otherwise). Nothing else to click. From DSH 0.1.7 the host discovers presets through patch declaration rows instead, and the plugin switches the registration over by itself — the install steps stay the same. Pick "编排模式 (Orchestrator)" in the new-session preset selector; to make it the default, choose it in Settings → Agent Presets.
 
 Out of the box only DSH's built-in base tools are enabled — detected MCP/host tools are not written in automatically. Open **庖丁配置 (Paoding Config)** in the sidebar, opt into the tools and roles you need, and hit Save & Apply. When you no longer want it, three commands uninstall it for good — the per-workspace presets created by workspace-specific configs are removed too:
 
@@ -46,6 +47,8 @@ rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets/orchestrator"
 rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets"/orchestrator-*
 ```
 
+On a DSH 0.1.7+ host there is one extra step: delete the dsh-paoding managed block from `~/.dsh/cordis.patch.yml` (the auto-generated marker comments), so no declaration rows are left pointing at the removed directories (see §7 of the [installation guide](docs/installation_en.md)).
+
 **Dev checkout install** — to hack on the plugin or the preset sources, link the repository directly (changes go live via HMR or a restart):
 
 ```bash
@@ -77,7 +80,7 @@ All preferences live in `~/.dsh/dsh-paoding.config.yml`: role add/remove/tweak,
 | 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`), 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.1.7-rc.1), first-install automation and the version marker, upgrading, dev-checkout install, host patch detection, the Paoding Config panel, uninstalling, troubleshooting. |
 | [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, tuning built-in roles, main-agent tools and skills, custom roles, per-role models, per-role session modes. |
 

package/docs/architecture.md

@@ -246,6 +246,8 @@ SOP（按 stop reason 分流：error 重委派一次 / max-tokens 拆小 / refus
 
 **⑦ 热插拔 = preset 是静态目录 + 插件通道挂载。** 插件本体经 `dsh plugin add`（pnpm + 包内 bundle patch）装入 profile，侧栏面板即挂即卸；编排预设本身是一个静态目录——生成器把静态源复制/改写为
 `$DSH_HOME/.agent-presets/orchestrator`，编辑 YAML / mjs、面板「保存并应用」重新生成、重启 host 或新建会话即生效；
+产物路径两代宿主一致，登记机制按宿主版本双轨——DSH ≤ 0.1.6 目录扫描即注册，DSH ≥ 0.1.7 由 `$DSH_HOME/cordis.patch.yml`
+托管块里的 `@deepseek-ai/dsh-agent-preset` 声明行注册，安装器自动适配与迁移（见[安装](installation.md)第 2 节）；
 卸载 = `dsh plugin remove` 加删目录（见[安装](installation.md)）。DSH 源码零改动，preset 可整体移除、不残留。
 
 ## Web 配置页 client bundle：源头多文件，产物单文件
@@ -266,7 +268,8 @@ grep inline cap 与对照同设计）后，根因锁定为：**默认压缩从
 **已落地配置。** `agent.cordis.yml` 的 compaction-basic 已设 `thresholdRatio: 0.45`（≈117,965 tokens
 触发），配合 retainRatio 默认保留约 16% 尾部（≈42K）+ 摘要 checkpoint，稳态平均回落到 ~80K 量级。
 压缩每次触发调用一次 LLM 摘要——复用前缀缓存，成本极低——因此触发频繁一点也几乎不额外花钱；
-0.45 是「省 token 与不频繁摘要」之间的平衡点。
+0.45 是「省 token 与不频繁摘要」之间的平衡点。compaction-basic 另显式钉了 `maxTokens: 8192`：
+DSH 0.1.7 起宿主默认升到 65536，显式值让 0.1.5 – 0.1.7-rc.1 全系的摘要预算行为保持一致。
 
 **参数与效果。**
 

package/docs/architecture_en.md

@@ -318,7 +318,11 @@ integration summary) — see [docs/orchestration_en.md](orchestration_en.md).
 into a profile via `dsh plugin add` (pnpm plus the in-package bundle patch), so the sidebar panel mounts and
 unmounts with it; the orchestrator preset is a static directory — the generator copies/rewrites the static
 sources into `$DSH_HOME/.agent-presets/orchestrator`; editing the YAML / mjs, hitting Save & Apply in the
-panel to regenerate, and restarting the host or opening a new session takes effect. Uninstall = `dsh plugin
+panel to regenerate, and restarting the host or opening a new session takes effect. The artifact path is the
+same on both host generations, while registration is dual-track by host version — DSH ≤ 0.1.6 registers by
+directory scan, DSH ≥ 0.1.7 registers through `@deepseek-ai/dsh-agent-preset` declaration rows in the managed
+block of `$DSH_HOME/cordis.patch.yml`, with the installer adapting and migrating automatically (see §2 of the
+[Installation guide](installation_en.md)). Uninstall = `dsh plugin
 remove` plus deleting the directory (see [Installation](installation_en.md)). No DSH source changes; the
 preset leaves nothing behind when removed.
 
@@ -346,7 +350,9 @@ history periodically compressed back down.
 (≈42K) plus a summary checkpoint; the steady-state average falls to the ~80K range. Each compaction run
 performs one LLM summarization call that reuses the prefix cache, so its cost is negligible — triggering
 somewhat more often costs almost nothing extra; 0.45 is the balance point between saving tokens and not
-summarizing too frequently.
+summarizing too frequently. compaction-basic also pins `maxTokens: 8192` explicitly: from DSH 0.1.7 the host
+default rises to 65536, and the explicit value keeps the summary-budget behavior identical across
+0.1.5 – 0.1.7-rc.1.
 
 **Parameters and effect.**
 

package/docs/configuration.md

@@ -4,7 +4,7 @@
 
 # 配置
 
-dsh-paoding 把「按角色分工的编排 preset」做成**配置驱动**：你手编（或在「庖丁配置」面板里点选）一个 YAML 配置文件，生成器（`tools/`，面板「保存并应用」与仓库内兜底 CLI 共用同一生成管线 `collectState` / `generateAndInstall`）在应用时据此重写目标 preset —— `~/.dsh/.agent-presets/orchestrator/agent.cordis.yml`，覆盖角色 allow、角色 persona、主 agent 白名单（`config.allow` 注入）、主 agent persona 的技能行/内联与人设追加。
+dsh-paoding 把「按角色分工的编排 preset」做成**配置驱动**：你手编（或在「庖丁配置」面板里点选）一个 YAML 配置文件，生成器（`tools/`，面板「保存并应用」与仓库内兜底 CLI 共用同一生成管线 `collectState` / `generateAndInstall`）在应用时据此重写目标 preset —— `~/.dsh/.agent-presets/orchestrator/agent.cordis.yml`，覆盖角色 allow、角色 persona、主 agent 白名单（`config.allow` 注入）、主 agent persona 的技能行/内联与人设追加。产物路径在两代宿主上一致；两代宿主发现 preset 的机制不同（≤ 0.1.6 目录扫描 / ≥ 0.1.7 patch 声明行托管块），安装器自动适配，见[安装](installation.md)的「版本支持与预设落点双轨」。
 
 配置文件描述的是**声明式意图**。目标文件每次都由「源码 preset + 本配置文件」重新生成：改配置 → 在面板点「保存并应用」= 幂等同步，不会累积手工补丁。
 
@@ -632,7 +632,7 @@ workspaces:
 ### 9.4 生效方式与边界
 
 - **预设选择发生在新建会话时**：新建会话界面选好工作区后，在预设选择器里选对应的 `orchestrator-<slug>`。全局默认预设不受任何影响。预设生效需要新会话（或 DSH 重启后可见）。
-- 预设目录落在 `$DSH_HOME/.agent-presets/` 下，全机共享：同一台机器上不同项目各起的 DSH 实例，因 slug 不同互不覆盖。
+- 预设目录落在 `$DSH_HOME/.agent-presets/` 下，全机共享：同一台机器上不同项目各起的 DSH 实例，因 slug 不同互不覆盖。DSH ≥ 0.1.7 上这些预设另经 `$DSH_HOME/cordis.patch.yml` 托管块里的声明行登记（`config.id` 即 `orchestrator` / `orchestrator-<slug>`），同一套 slug 命名两代宿主通用，见[安装](installation.md)的「版本支持与预设落点双轨」。
 - 兜底 CLI 本次仍只作用于全局条目；`workspaces` 段在 CLI 应用后原样保留，不会被冲掉。
 - 运行中的会话不会换预设——子 agent 的角色与工具面在会话创建时随预设组装定型，会话内不可变；要换套班底，开新会话选新预设。
 

package/docs/configuration_en.md

@@ -4,7 +4,7 @@
 
 # Configuration
 
-dsh-paoding makes the role-based orchestration preset **configuration-driven**: you hand-write (or click together in the 庖丁配置 panel) a YAML config file, and the generator (`tools/`; the panel's Save & Apply and the in-repo fallback CLI share the same generation pipeline, `collectState` / `generateAndInstall`) rewrites the target preset — `~/.dsh/.agent-presets/orchestrator/agent.cordis.yml` — when it is applied, covering the role allows, role personas, the main-agent allow list (`config.allow` injection) and the main-agent persona's skill rows / inlines and persona extra.
+dsh-paoding makes the role-based orchestration preset **configuration-driven**: you hand-write (or click together in the 庖丁配置 panel) a YAML config file, and the generator (`tools/`; the panel's Save & Apply and the in-repo fallback CLI share the same generation pipeline, `collectState` / `generateAndInstall`) rewrites the target preset — `~/.dsh/.agent-presets/orchestrator/agent.cordis.yml` — when it is applied, covering the role allows, role personas, the main-agent allow list (`config.allow` injection) and the main-agent persona's skill rows / inlines and persona extra. The artifact path is the same on both host generations; the generations discover the preset differently (≤ 0.1.6 directory scan / ≥ 0.1.7 declaration managed block in the patch), and the installer adapts automatically — see "Version support and the dual preset landing" in the [installation guide](installation_en.md).
 
 The config file describes **declarative intent**. The target file is regenerated from scratch every time — "source preset + this config file": edit the config → hit Save & Apply in the panel = idempotent sync, with no accumulating hand patches.
 
@@ -642,7 +642,7 @@ With a workspace selected, preview and apply target it alone; the success note r
 ### 9.4 How it takes effect, and boundaries
 
 - **Preset choice happens at session creation**: pick the workspace on the new-session screen, then pick the matching `orchestrator-<slug>` in the preset selector. The global default preset is untouched. A new session (or a DSH restart) is needed for a freshly generated preset to appear.
-- Preset directories live under `$DSH_HOME/.agent-presets/` and are shared machine-wide: separate DSH instances launched from different projects never clobber each other, because their slugs differ.
+- Preset directories live under `$DSH_HOME/.agent-presets/` and are shared machine-wide: separate DSH instances launched from different projects never clobber each other, because their slugs differ. On DSH ≥ 0.1.7 these presets are additionally registered through declaration rows in the managed block of `$DSH_HOME/cordis.patch.yml` (`config.id` being `orchestrator` / `orchestrator-<slug>`); the same slug naming works on both generations — see "Version support and the dual preset landing" in the [installation guide](installation_en.md).
 - The fallback CLI still targets the global entry only; the `workspaces` section survives a CLI apply unchanged.
 - A running session never switches presets — a session's roles and tool surfaces are assembled at creation and fixed for its lifetime; to change the lineup, start a new session with the new preset.
 

package/docs/installation.md

@@ -12,14 +12,15 @@
 
 - **Node.js ≥ 18**。DSH host 与插件链路都跑在 Node 上；版本过低时 `dsh` 本身就起不来。可用 `node --version` 自查。
 - **pnpm 可用**。`dsh plugin` 是 pnpm 的透明转发器：插件包装进 profile 时由 pnpm 完成。缺失时安装命令会报 pnpm 相关错误，装好 pnpm（`npm i -g pnpm` 或 `corepack enable`）后重试。
-- **已安装 DSH host**（`dsh` 可用，含其 Web/agent 运行时；**@deepseek-ai/dsh ≥ 0.1.5**，最低支持版本）。本插件不改 DSH 源码，只往 DSH 的 preset roster 写入编排预设、并把「庖丁配置」面板挂进 Web 左侧栏，因此先要有可用的 DSH 家目录。
+- **已安装 DSH host**（`dsh` 可用，含其 Web/agent 运行时；**@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.1** 全支持，安装器自动适配两代预设机制，详见第 2 节「版本支持与预设落点双轨」）。本插件不改 DSH 源码，只往 DSH 的 preset roster 写入编排预设、并把「庖丁配置」面板挂进 Web 左侧栏，因此先要有可用的 DSH 家目录。
 - **路径事实**（生成管线内建常量，写死前先了解它们）：
 
 | 项 | 默认值 | 说明 |
 |---|---|---|
 | `$DSH_HOME` | `~/.dsh` | DSH 家目录（认环境变量 `DSH_HOME`，缺省 `$HOME/.dsh`）。host 层配置 `cordis.patch.yml`、`node_modules`、`profiles/<name>/cordis.patch.yml`、插件 profile 目录都在其下 |
-| preset roster 根目录 | `$DSH_HOME/.agent-presets/` | `dsh-agent-presets` 扫描本地 authored presets 的目录 |
-| 本预设安装目标 | `$DSH_HOME/.agent-presets/orchestrator` | 生成产物：`agent.cordis.yml`（重写后的角色配置）、`preset.yml`、`restrict.mjs`、`.generator-version` 版本标记，是一个静态目录 |
+| preset roster 根目录 | `$DSH_HOME/.agent-presets/` | DSH ≤ 0.1.6 由 `dsh-agent-presets` 扫描此目录发现本地 authored presets；DSH ≥ 0.1.7 宿主不再扫目录，此目录退为预设文件存放处（见第 2 节「版本支持与预设落点双轨」） |
+| 本预设安装目标 | `$DSH_HOME/.agent-presets/orchestrator` | 生成产物：`agent.cordis.yml`（重写后的角色配置）、`preset.yml`、`restrict.mjs`、`.generator-version` 版本标记，是一个静态目录；按工作区配置生成的预设落同一父目录下的 `orchestrator-<slug>` |
+| 声明行托管块（仅 DSH ≥ 0.1.7） | `$DSH_HOME/cordis.patch.yml` 内的托管块 | 以 `# --- dsh-paoding presets (auto-generated; do not edit) ---` 起始、配套 end 标记收尾，块内 `- insert:` 写 `@deepseek-ai/dsh-agent-preset` 声明行；安装器自动维护，详见第 2 节 |
 | 配置文件 | `$DSH_HOME/dsh-paoding.config.yml` | 「庖丁配置」面板「保存并应用」写入的角色与工具分配（`0o600`，可手编）；首装自动化同样读写它 |
 
 - **环境变量**：`DSH_HOME` 覆盖 DSH 家目录（默认 `~/.dsh`）；`DSH_PAODING_CONFIG` 覆盖配置文件路径（面板认它；仓库内兜底 CLI 则用 `--config <file>` 指定）。
@@ -47,13 +48,39 @@ 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 走——在任何 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 的面板里「保存并应用」，写的都是同一份预设。
+
+### 版本支持与预设落点双轨（DSH 0.1.5 – 0.1.7-rc.1）
+
+本插件兼容两代宿主：**DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 全部支持**，安装与使用流程完全一致。插件 0.3.4 起，package.json 显式声明 `peerDependencies: @deepseek-ai/dsh >= 0.1.5`——0.1.7 起宿主装插件前做兼容性预检，无声明等于默认放行，显式声明后按真实兼容面把关；0.1.5 / 0.1.6 不读这个字段，声明纯属元数据，不影响安装。
+
+两代宿主发现「本地 authored preset」的机制不同，安装器据此分双轨落点，宿主检测全自动、用户无感：
+
+- **目录轨（DSH ≤ 0.1.6）**：宿主扫描 `$DSH_HOME/.agent-presets/` 下的目录来发现 preset，目录即注册。安装器照旧把产物写成 `$DSH_HOME/.agent-presets/orchestrator/`（`agent.cordis.yml` + `preset.yml` + `restrict.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` 以绝对 `file:` URL 引用。产物三件套仍落在 `.agent-presets/<id>/`，只是从「目录即注册」变成「文件存放处」。托管块之外的用户内容一字节不动；块内带 do not edit 标记，手改块内内容会在下次保存时被覆盖。
+
+安装器按下面的顺序判定走哪条轨：
+
+1. Web 面板运行时探测优先——`agentPresets` 服务的 `register` 方法 0.1.7 才有，探测到即在声明行轨；
+2. CLI 侧 `dsh --version`；
+3. 兜底探测 `$DSH_HOME/node_modules/@deepseek-ai/dsh-agent-preset`（这个单数包在，即为 0.1.7+）；
+4. 都失败时默认按 ≤ 0.1.6 处理（安全侧）。
+
+宿主版本变化后的首次保存/自愈会自动迁移，双向都不用手动干预：
+
+- **降级自愈（0.1.7 → 0.1.6）**：0.1.6 不认识声明行，声明行留在 patch 里会让 profile 启动失败——安装器自动撤下 home patch 里的托管块；目录轨产物本就齐全，预设无缝回到目录扫描。
+- **升级迁移（0.1.6 → 0.1.7）**：安装器自动补写托管块；`.agent-presets/` 里按旧轨生成的 preset 会话（`agentPreset: orchestrator`）在新轨下按 `config.id` 继续对上，老会话恢复不断档。
+
+另有两处跨版本行为对齐，同样自动完成、无需用户动作：
+
+- **摘要预算**：0.1.7 起宿主把 compaction 的 `maxTokens` 默认升到 65536；本 preset 对 `dsh-compaction-basic` 显式钉 `maxTokens: 8192`，0.1.5 / 0.1.6 的摘要预算行为原样保持，两代宿主上一致。
+- **面板图标**：0.1.7 改了 ui-primitives 的图标命名，面板图标已做跨版本兜底，同一 bundle 在两代宿主上都能正常渲染；面板功能在两代宿主上一致。
 
 ### 首装自动化：重启即完整安装
 
 插件启动时自动检测编排预设是否就位：`$DSH_HOME/.agent-presets/orchestrator` 目录缺失，或其中的 `.generator-version` 标记与插件包版本不符时，自动执行一次等价 `--auto` 的安装——`~/.dsh/dsh-paoding.config.yml` 已存在就按配置应用；没有就写基础模板（只含 DSH 自带的基础工具，见下）。它走的是与面板「保存并应用」同一条检测/生成管线（`collectState` / `generateAndInstall`）——同一管线，但启动自愈的检测是纯文件扫描、不带运行时检测事实，面板则带；host 上装有 bundle 形态插件时，两者的检测库存可能不同，产物随之略有差异。
 
-所以 **`dsh plugin add` + 重启 = 完整安装**：预设生成、配置模板落盘、面板可点，一步到位。自动生成失败不会拖垮插件启动——只在 DSH 日志里记一条告警，可到面板手动「保存并应用」补上。
+所以 **`dsh plugin add` + 重启 = 完整安装**：预设生成、配置模板落盘、面板可点，一步到位。自动生成失败不会拖垮插件启动——只在 DSH 日志里记一条告警，可到面板手动「保存并应用」补上。启动自愈同时负责双轨落点的维护与跨版本迁移——宿主在 0.1.6 与 0.1.7 之间升级、降级后，首次自愈会自动补写或撤下 `$DSH_HOME/cordis.patch.yml` 里的托管块（见上节「版本支持与预设落点双轨」）。
 
 ### 版本标记与自动重生成
 
@@ -164,7 +191,7 @@ patch 与配置文件用 **`yaml` 包**解析——通过 `createRequire` 从 `$
 - **Agent 工具分配卡片**：主 agent 一张固定卡（基础工具取消勾选 = 加入 `main_agent_remove` 从主 agent 剔除；MCP / 插件工具勾选 = 加入 `main_agent_extra`；技能「read 按需」与「内联全文」两组勾选；另有「人设追加」编辑区，可改、清空、恢复默认）＋ `search_external` / `design` / `implement` 三张内置角色卡 ＋ 任意自定义角色卡（带删除按钮）；每张角色卡把工具按「基础工具 / MCP 工具 / 插件工具」三组呈现、可逐项勾选，并可编辑 persona。底部「新建自定义 agent 角色」。
 - **技能分配**：每个 skill 一行，勾选分配给哪些 agent（写入对应 persona 的 `Available skills` 软引导；角色技能软引导，主 agent 技能另有 read 按需/内联两组）。
 - **预览生成**：不写盘生成 `agent.cordis.yml`，显示每个角色 allow 的 intent → kept 计数与生成全文。
-- **保存并应用**：确认后写入 preset（覆盖 `$DSH_HOME/.agent-presets/orchestrator`）并把当前分配保存到 `$DSH_HOME/dsh-paoding.config.yml`；应用成功后提示重启 DSH 或新建会话生效（检测到 patch 比生成结果新时提示重启后生效）。打开面板时会加载既有配置文件作为当前值——手编过的选择直接可见、可改。
+- **保存并应用**：确认后写入 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 比生成结果新时提示重启后生效）。打开面板时会加载既有配置文件作为当前值——手编过的选择直接可见、可改。
 
 ## 7. 卸载
 
@@ -178,6 +205,8 @@ 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 标记行）一并删去——块外内容不受影响。
+
 卸载不影响 host 的其它内容（MCP、插件、会话等），与 DSH 源码零耦合；之后新建会话时「编排模式 (Orchestrator)」不再出现在预设选择器里。
 
 ## 8. 常见问题与排查
@@ -188,7 +217,7 @@ rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets"/orchestrator-*
 
 **装了插件，预设列表里却没有「编排模式 (Orchestrator)」**
 
-预设由插件启动时自动生成：先确认装完后**重启过 DSH**；预设在新会话创建时装载，重启后还要新建一个会话才会出现在选择器里。仍没有就查 DSH 日志里 `paoding-config-ui` 的告警（自动生成失败会记日志，可到面板手动「保存并应用」补上），再检查 `ls "${DSH_HOME:-$HOME/.dsh}/.agent-presets/orchestrator"`——目录为空多半是插件运行时的 `$DSH_HOME` 与你以为的家目录不一致（启动 DSH 前显式 `export DSH_HOME=…`）。
+预设由插件启动时自动生成：先确认装完后**重启过 DSH**；预设在新会话创建时装载，重启后还要新建一个会话才会出现在选择器里。仍没有就查 DSH 日志里 `paoding-config-ui` 的告警（自动生成失败会记日志，可到面板手动「保存并应用」补上），再检查 `ls "${DSH_HOME:-$HOME/.dsh}/.agent-presets/orchestrator"`——目录为空多半是插件运行时的 `$DSH_HOME` 与你以为的家目录不一致（启动 DSH 前显式 `export DSH_HOME=…`）。目录在、宿主又是 0.1.7+ 而选择器里仍没有时，再查 `$DSH_HOME/cordis.patch.yml` 里有无 dsh-paoding 托管块——0.1.7 靠块内声明行发现预设，缺块就到面板点一次「保存并应用」补写（见第 2 节「版本支持与预设落点双轨」）。
 
 **`tools.restrict()` 报 unknown tools / 子 agent 创建被拒**
 

package/docs/installation_en.md

@@ -12,14 +12,15 @@ Check the following before installing:
 
 - **Node.js ≥ 18**. The DSH host and the plugin chain both run on Node; with an older version `dsh` won't start in the first place. Check with `node --version`.
 - **pnpm available**. `dsh plugin` is a transparent pass-through to pnpm: installing a plugin package into a profile is done by pnpm. If pnpm is missing the install command fails with a pnpm error — install pnpm (`npm i -g pnpm` or `corepack enable`) and retry.
-- **A working DSH host** (the `dsh` command, including its Web/agent runtime; **@deepseek-ai/dsh ≥ 0.1.5**, the minimum supported version). This plugin does not modify DSH source code; it only writes the orchestrator preset into DSH's preset roster and mounts the Paoding Config page into the Web sidebar, so a usable DSH home directory must exist first.
+- **A working DSH host** (the `dsh` command, including its Web/agent runtime; **@deepseek-ai/dsh 0.1.5 – 0.1.7-rc.1**, all supported — the installer adapts to the two preset mechanisms automatically; see §2 "Version support and the dual preset landing"). This plugin does not modify DSH source code; it only writes the orchestrator preset into DSH's preset roster and mounts the Paoding Config page into the Web sidebar, so a usable DSH home directory must exist first.
 - **Path facts** (constants built into the generation pipeline; know them before customizing):
 
 | Item | Default | Description |
 |---|---|---|
 | `$DSH_HOME` | `~/.dsh` | The DSH home directory (the `DSH_HOME` environment variable is honored, defaulting to `$HOME/.dsh`). The home-layer `cordis.patch.yml`, `node_modules`, `profiles/<name>/cordis.patch.yml`, and plugin profile directories live under it |
-| preset roster root | `$DSH_HOME/.agent-presets/` | The directory `dsh-agent-presets` scans for locally authored presets |
-| Install target of this preset | `$DSH_HOME/.agent-presets/orchestrator` | The generated artifact: `agent.cordis.yml` (rewritten role config), `preset.yml`, `restrict.mjs`, and the `.generator-version` marker — a static directory |
+| preset roster root | `$DSH_HOME/.agent-presets/` | Under DSH ≤ 0.1.6, `dsh-agent-presets` scans this directory for locally authored presets; under DSH ≥ 0.1.7 the host no longer scans it and the directory is just where the preset files live (see §2 "Version support and the dual preset landing") |
+| Install target of this preset | `$DSH_HOME/.agent-presets/orchestrator` | The generated artifact: `agent.cordis.yml` (rewritten role config), `preset.yml`, `restrict.mjs`, and the `.generator-version` marker — a static directory; per-workspace presets land in sibling `orchestrator-<slug>` directories |
+| Declaration managed block (DSH ≥ 0.1.7 only) | a managed block inside `$DSH_HOME/cordis.patch.yml` | Opens with `# --- dsh-paoding presets (auto-generated; do not edit) ---` and closes with the matching end marker; the `- insert:` rows inside carry `@deepseek-ai/dsh-agent-preset` declarations, maintained by the installer — see §2 |
 | Config file | `$DSH_HOME/dsh-paoding.config.yml` | Role/tool assignments written by the Paoding Config panel's Save & Apply (`0o600`, hand-editable); first-install automation reads and writes it too |
 
 - **Environment variables**: `DSH_HOME` overrides the DSH home directory (default `~/.dsh`); `DSH_PAODING_CONFIG` overrides the config-file path (honored by the panel; the in-repo fallback CLI uses `--config <file>` instead).
@@ -47,13 +48,39 @@ 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 — 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`, equally profile-independent — Save & Apply from any profile's panel writes the same preset.
+
+### Version support and the dual preset landing (DSH 0.1.5 – 0.1.7-rc.1)
+
+The plugin supports two host generations: **DSH 0.1.5 / 0.1.6 / 0.1.7-rc.1 are all supported**, with an identical install and usage flow. As of plugin 0.3.4, package.json declares `peerDependencies: @deepseek-ai/dsh >= 0.1.5` explicitly — from 0.1.7 the host runs a plugin-compatibility precheck before installing: no declaration meant a default pass, an explicit one gets checked against the real compatibility surface; 0.1.5 / 0.1.6 never read the field, where the declaration is pure metadata and changes nothing about the install.
+
+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`) 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` is referenced by an absolute `file:` URL. The artifact trio 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:
+
+1. runtime probe from the Web panel first — the `agentPresets` service's `register` method exists only since 0.1.7; finding it means the declaration track;
+2. `dsh --version` on the CLI side;
+3. a last-resort probe of `$DSH_HOME/node_modules/@deepseek-ai/dsh-agent-preset` (that singular package being present means 0.1.7+);
+4. if all fail, default to ≤ 0.1.6 (the safe side).
+
+The first save/self-heal after the host version changes migrates automatically, in both directions, with no manual steps:
+
+- **Downgrade self-heal (0.1.7 → 0.1.6)**: 0.1.6 does not understand declaration rows — leaving them in the patch breaks profile startup — so the installer removes the managed block from the home patch automatically; the directory-track artifacts are already complete, and the preset slips back to directory scanning seamlessly.
+- **Upgrade migration (0.1.6 → 0.1.7)**: the installer writes the managed block automatically; sessions on presets generated under the old track (`.agent-presets/`, `agentPreset: orchestrator`) keep matching under the new track by `config.id`, so old sessions resume without a gap.
+
+Two cross-version behavior alignments happen the same automatic way, with no user action:
+
+- **Summary budget**: from 0.1.7 the host raises the compaction `maxTokens` default to 65536; this preset pins `maxTokens: 8192` on `dsh-compaction-basic` explicitly, so the 0.1.5 / 0.1.6 summary-budget behavior is preserved identically on both generations.
+- **Panel icons**: 0.1.7 changed the ui-primitives icon naming; the panel's icons carry a cross-version fallback, so one bundle renders correctly on both host generations and the panel behaves identically on either.
 
 ### First-install automation: restart = full install
 
 At startup the plugin checks whether the orchestrator preset is in place: if the `$DSH_HOME/.agent-presets/orchestrator` directory is missing, or its `.generator-version` marker does not match the plugin package version, it automatically performs one install equivalent to `--auto` — applying `~/.dsh/dsh-paoding.config.yml` when it exists, writing the base template otherwise (DSH base tools only; see below). It runs the same detection/generation pipeline as the panel's Save & Apply (`collectState` / `generateAndInstall`) — the same pipeline, but the startup self-heal detects with a pure file scan and no runtime detection facts while the panel detects with them; when a bundle-form plugin is installed on the host, the two detection inventories may differ, and the outputs differ slightly with them.
 
-So **`dsh plugin add` + restart = a complete install**: preset generated, config template on disk, panel ready — all in one step. If the automatic generation fails it never takes the plugin down — a warning is logged, and you can apply manually from the panel.
+So **`dsh plugin add` + restart = a complete install**: preset generated, config template on disk, panel ready — all in one step. If the automatic generation fails it never takes the plugin down — a warning is logged, and you can apply manually from the panel. The startup self-heal also maintains the dual landing and the cross-version migration: after the host moves between 0.1.6 and 0.1.7, the first self-heal writes or removes the managed block in `$DSH_HOME/cordis.patch.yml` automatically (see "Version support and the dual preset landing" above).
 
 ### The version marker and auto-regeneration
 
@@ -164,7 +191,7 @@ Panel data goes over the **same-origin `/api/paoding/*`**: the Node side registe
 - **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.
 - **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.
-- **Save & Apply**: after confirmation, writes the preset (overwriting `$DSH_HOME/.agent-presets/orchestrator`) and 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.
+- **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.
 
 ## 7. Uninstalling
 
@@ -178,6 +205,8 @@ rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets"/orchestrator-*
 
 The first removes the plugin and the sidebar panel (scoped to the given profile), the second deletes the orchestrator preset directory, and the third removes the per-workspace preset directories (`orchestrator-<basename>`) created when you configured individual workspaces (if you never did, the glob matches nothing and it's harmless) — the base `orchestrator` directory is already gone with the previous command and is not covered by that glob. The config file `~/.dsh/dsh-paoding.config.yml` is not removed with them — keep it or delete it, it does not affect any other DSH configuration, and a reinstall's first-install automation would apply it again.
 
+On a DSH ≥ 0.1.7 host, check one more place: `$DSH_HOME/cordis.patch.yml` may still carry the dsh-paoding managed block (the `- insert:` declaration rows wrapped in marker comments). Once the preset directories are gone those declaration rows dangle, pointing at deleted directories — remove the whole managed block (from the `# --- dsh-paoding presets (auto-generated; do not edit) ---` opening line through the end marker) as well; content outside the block is untouched.
+
 Uninstalling touches nothing else on the host (MCP, plugins, sessions), and stays decoupled from DSH source code; "编排模式 (Orchestrator)" disappears from the preset selector for new sessions.
 
 ## 8. Troubleshooting
@@ -188,7 +217,7 @@ Uninstalling touches nothing else on the host (MCP, plugins, sessions), and stay
 
 **The plugin is installed but "编排模式 (Orchestrator)" is not in the preset list**
 
-The preset is generated automatically when the plugin starts: first make sure you **restarted DSH** after installing; presets load when a session is created, so after the restart you also need a new session for it to appear in the selector. Still nothing? Check the DSH log for `paoding-config-ui` warnings (a failed auto-generation is logged; apply manually from the panel), then check `ls "${DSH_HOME:-$HOME/.dsh}/.agent-presets/orchestrator"` — an empty directory usually means the plugin's runtime `$DSH_HOME` differs from the home directory you assumed (export `DSH_HOME=…` explicitly before launching DSH).
+The preset is generated automatically when the plugin starts: first make sure you **restarted DSH** after installing; presets load when a session is created, so after the restart you also need a new session for it to appear in the selector. Still nothing? Check the DSH log for `paoding-config-ui` warnings (a failed auto-generation is logged; apply manually from the panel), then check `ls "${DSH_HOME:-$HOME/.dsh}/.agent-presets/orchestrator"` — an empty directory usually means the plugin's runtime `$DSH_HOME` differs from the home directory you assumed (export `DSH_HOME=…` explicitly before launching DSH). If the directory is there, the host is 0.1.7+, and the selector still shows nothing, check `$DSH_HOME/cordis.patch.yml` for the dsh-paoding managed block — 0.1.7 discovers presets through the declaration rows inside it; if the block is missing, hit Save & Apply once in the panel to write it (see §2 "Version support and the dual preset landing").
 
 **`tools.restrict()` reports unknown tools / subagent creation is rejected**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-paoding",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "庖丁 — DSH (DeepSeek Harness) 编排模式安装器：host 感知的角色工具过滤 + Web 设置页可视化配置器",
   "type": "module",
   "license": "MIT",
@@ -19,6 +19,9 @@
   "engines": {
     "node": ">=18"
   },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.1.5"
+  },
   "scripts": {
     "prepublishOnly": "node scripts/build-client.mjs --check"
   },
@@ -46,7 +49,6 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-connection"
       ]

package/plugins/paoding-config-ui/api-core.mjs

@@ -118,6 +118,9 @@ export function serializeState(s) {
     suggested: s.suggested,
     installedPresets,
     workspaceMeta,
+    // 预设安装轨道（declarative = 0.1.7+ 声明行 / directory = ≤0.1.6 目录扫描），
+    // 面板可据此展示；旧版 collectState 产出的 state 无此字段时按目录轨兜底
+    presetSystem: s.presetSystem ?? 'directory',
     // 主 persona 尾部追加的默认常量（供 UI「人设追加」默认展示 / 恢复默认）
     mainPersonaExtraDefault: s.mainPersonaExtraDefault ?? null,
     // 运行时识别结果透传（字段缺失视为未启用运行时检测，与旧版 UI 行为一致）
@@ -166,9 +169,11 @@ const PRESET_ENSURE_ABORTED = '插件已卸载（dispose），本次 preset 生
  *
  * 判定：preset 目录缺失，或 .generator-version 标记缺失 / 版本与 generatorVersion
  * 不符 → 执行一次自动安装：局部 collectState()（不带运行时事实的纯文件扫描，
- * 首装触发点在插件启动、宿主服务未必就绪，且与 CLI --auto 语义对齐；不走
- * refreshState()——那会拿无事实的扫描覆盖路由层的共享缓存）后按既有配置合成
- * assignments（无配置写基础模板），经 generateAndInstall 落盘，最后写标记文件。
+ * 首装触发点在插件启动、宿主服务未必就绪，且与 CLI --auto 语义对齐；预设安装
+ * 轨道由 collectState 内部按 dsh --version / 文件探测兜底，state.presetSystem
+ * 随 state 一并进 generateAndInstall 双轨收尾；不走 refreshState()——那会拿
+ * 无事实的扫描覆盖路由层的共享缓存）后按既有配置合成 assignments（无配置写
+ * 基础模板），经 generateAndInstall 落盘，最后写标记文件。
  * shouldAbort 在各 await 点后检查：插件 dispose 后在途的生成不再继续写盘。
  * 可脱离 ctx 独立调用（单测友好），任何异常自捕、绝不抛出。
  *

package/plugins/paoding-config-ui/lib/base.css

@@ -44,7 +44,7 @@
   flex: none;
   padding: 1px 8px;
   border-radius: 999px;
-  background: var(--dsw-alias-accent-soft, var(--dsw-alias-bg-layer-2));
+  background: var(--dsw-alias-interactive-bg-hover-accent, var(--dsw-alias-bg-layer-2));
   font-size: 11px;
   line-height: 16px;
   font-weight: 500;

package/plugins/paoding-config-ui/lib/client.js

@@ -24,6 +24,8 @@
  *  - factory 内 require() 只解析平台 seed 模块（react / cordis /
  *    ui-slots / ui-primitives 与已物化模块）；本 bundle 依赖 react 与
  *    @deepseek-ai/dsh-client-ui-primitives。
+ *  - 图标跨版本兜底：DSH ≤0.1.6 图标导出名带尺寸后缀（IconCheckOutline16），
+ *    0.1.7-rc.1 起改粗细命名 + size prop，factory 内把旧名别名到 Regular 版。
  *  - 挂载点：左侧栏底部动作位入口（sidebar.footer.action 键控槽，与插件
  *    广场 cordis 徽章同槽，设置行上方）+ 会话中栏全页 overlay
  *    （data-dsh-paoding-view / html[data-dsh-paoding-active]）；
@@ -51,6 +53,36 @@ window.__ModuleLoader__.load({
     var useState = React.useState, useEffect = React.useEffect, useCallback = React.useCallback, useRef = React.useRef;
     var P = require("@deepseek-ai/dsh-client-ui-primitives");
 
+    // 图标跨版本兜底：DSH ≤0.1.6 的 ui-primitives 图标导出名带尺寸后缀
+    // （IconCheckOutline16 / IconChevronDownOutline14，IconProps { size,
+    // className }）；0.1.7-rc.1 起改粗细命名（…OutlineRegular / …Medium，
+    // size 变 prop、默认 16），12 个旧名全部消失。同一份 bundle 要在两代
+    // 宿主上都能跑：旧名缺、新名在，才把旧名别名到对应 Regular 版——新
+    // 组件接受 size prop，ic() 的 size 传参照常生效，旧 14px 名 → Regular
+    // + size 14 视觉等价（同为 1px 描边）。旧宿主上有原生实现就用原生，
+    // Button / Pill 等两代都有的导出一律不动。
+    P = Object.assign({}, P); // 复制一份导出面再补别名：不往共享模块对象上写属性（避免污染宿主里其他 ui-primitives 消费者）；P 是 factory 作用域的 var，重赋值后所有后续片段看到的就是这份副本
+    (function () {
+      var ICON_ALIAS = {
+        IconCheckOutline16: "IconCheckOutlineRegular",
+        IconChevronDownOutline14: "IconChevronDownOutlineRegular",
+        IconCordisPluginOutline14: "IconCordisPluginOutlineRegular",
+        IconDataOutline16: "IconDataOutlineRegular",
+        IconEditOutline16: "IconEditOutlineRegular",
+        IconLoadingOutline16: "IconLoadingOutlineRegular",
+        IconPlusOutline16: "IconPlusOutlineRegular",
+        IconRefreshOutline16: "IconRefreshOutlineRegular",
+        IconSkillOutline16: "IconSkillOutlineRegular",
+        IconTrashOutline16: "IconTrashOutlineRegular",
+        IconUserOutline16: "IconUserOutlineRegular",
+        IconWarningOutline16: "IconWarningOutlineRegular",
+      };
+      Object.keys(ICON_ALIAS).forEach(function (oldName) {
+        var newName = ICON_ALIAS[oldName];
+        if (P[oldName] === undefined && P[newName] !== undefined) P[oldName] = P[newName];
+      });
+    })();
+
     // ── 样式注入（幂等）─────────────────────────────────────────────────
     //
     // 样式正文在 lib/base.css，由 Node 半经 GET /api/paoding/client.css 下发

package/plugins/paoding-config-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paoding-config-ui",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "private": true,
   "type": "module",
   "main": "index.mjs",
@@ -9,7 +9,6 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-connection"
       ]

package/plugins/paoding-config-ui/runtime-inventory.mjs

@@ -18,6 +18,9 @@
  *     MCP 工具由 dsh-mcp-client 以 `mcp__<server>__<tool>` 公开名注册，
  *     故 schemas()/entries() 等能枚举出形如 mcp__tavily__tavily_search 的
  *     全名，与 tools/install.mjs 的 inventory 命名约定一致。
+ *   - 预设安装轨道（presetSystem）：agentPresets 服务有无 register 方法——
+ *     0.1.7+ 的 agent-preset-registry（声明行轨）有，≤0.1.6 的目录扫描服务
+ *     没有；collectState 拿它免掉 dsh --version 子进程探测。
  *
  * 约定：本模块只负责“取数”，任何一步失败都不抛出——错误记入 error 字符串
  * （多条用 '; ' 连接、整体截断），返回可用的部分结果；列表带截断上限防爆。
@@ -187,6 +190,22 @@ function readRegisteredToolNames(ctx, errors) {
   return { names: out, ok: acquired }
 }
 
+/**
+ * 预设安装轨道探测：0.1.7+ 宿主的 agentPresets 服务是 agent-preset-registry
+ * （带 register 方法，声明行轨）；≤0.1.6 的同名服务只做 .agent-presets 目录
+ * 扫描、没有 register。ctx.reflect.get(name, false) 读不到服务返回 undefined、
+ * 不触发 inject 护栏，整个探测自捕——任何异常都按 directory（安全侧）处理，
+ * 永不抛出。
+ */
+function detectPresetSystemOf(ctx) {
+  try {
+    const svc = ctx?.reflect?.get?.('agentPresets', false)
+    return svc != null && typeof svc.register === 'function' ? 'declarative' : 'directory'
+  } catch {
+    return 'directory'
+  }
+}
+
 /**
  * 采集运行时事实（供 collectState 合并 / UI 展示）。
  * 永不抛出：任何异常都会落到 error 里，返回部分结果。
@@ -209,5 +228,6 @@ export function collectRuntimeFacts(ctx) {
     ...(error !== '' ? { error } : {}),
     pluginEntries: plugin.entries,
     toolNames: tools.names,
+    presetSystem: detectPresetSystemOf(ctx),
   }
 }

package/presets/orchestrator/agent.cordis.yml

@@ -147,6 +147,9 @@
       name: '@deepseek-ai/dsh-compaction-basic'
       config:
         thresholdRatio: 0.45
+        # 钉住摘要预算：0.1.7 起该键默认从 8192 升到 65536，显式 8192 保持
+        # 0.1.5/0.1.6 的实际行为不变（摘要单次预算不随宿主版本漂移）。
+        maxTokens: 8192
 
     - id: command-compact
       name: '@deepseek-ai/dsh-command-compact'

package/tools/lib/preset-system.mjs

@@ -0,0 +1,390 @@
+/**
+ * 预设安装机制双轨 —— DSH ≤0.1.6 靠宿主 dsh-agent-presets（复数）扫描
+ * $DSH_HOME/.agent-presets/<id>/ 目录成 preset（目录扫描轨）；0.1.7 起目录扫描
+ * 机制删除，改为声明行：bundle/profile/home 任一 patch 层里 - insert: 一条
+ * name: '@deepseek-ai/dsh-agent-preset' 的行（config = { id 必填, name?,
+ * description?, order?, plugins[] 必填 }，宿主 agent-preset-registry 挂载
+ * plugins 子树；行 name 相对声明行 baseUrl 解析，绝对 file: URL 直接采用）。
+ * 本模块为双轨化提供三件事：
+ *   1) 轨道探测 detectPresetSystem：运行时探测（Web 插件对宿主服务的实时反射，
+ *      最权威）> `dsh --version` 版本号 > $DSH_HOME 单数包存在性 > 默认
+ *      directory（安全侧：声明行误落 0.1.6 会炸 profile 启动，目录轨误落
+ *      0.1.7 只是预设不显示）；
+ *   2) 声明行构造 buildPresetRowText：把生成的 agent.cordis.yml 全文内联成
+ *      一条声明行的 config.plugins（restrict 行 name 换成 restrict.mjs 的绝对
+ *      file: URL——声明轨没有「相对 preset 目录」语义，必须绝对化）；
+ *   3) home patch 托管块手术 upsertHomePatchRows / stripHomePatchRows /
+ *      readHomePatchRows：对 $DSH_HOME/cordis.patch.yml 的 MANAGED 标记块做
+ *      行级增删查，块外用户内容一字节不动；托管块损坏（缺结束标记）时拒绝
+ *      写盘并明确报错，与仓库「配置不可信时拒绝落盘」口径一致。
+ * 零运行时依赖（node:child_process / node:fs / node:path）；被 state 引用。
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { warn } from './util.mjs'
+
+/** 托管块起始标记：其后到结束标记之间是本工具自动生成的声明行，用户勿改。 */
+export const MANAGED_BEGIN = '# --- dsh-paoding presets (auto-generated; do not edit) ---'
+/** 托管块结束标记。两个标记成对出现；缺一即视为托管块损坏，拒绝写盘。 */
+export const MANAGED_END = '# --- end dsh-paoding presets ---'
+
+/** 声明行挂载的宿主 preset 包名（0.1.7+ 的 agent-preset-registry 组件包）。 */
+export const PRESET_ROW_NAME = '@deepseek-ai/dsh-agent-preset'
+
+/** preset 目录名（orchestrator / orchestrator-<slug>）→ home patch 声明行 id。 */
+export function presetRowId(presetId) {
+  return `preset-${presetId}`
+}
+
+// ── 版本解析与轨道判定 ──────────────────────────────────────────────────────
+
+/**
+ * 解析裸版本号文本为 [major, minor, patch] 数字三元组；解析不了返回 null。
+ * prerelease / build 标签忽略（0.1.7-rc.1 → [0, 1, 7]）。
+ */
+export function parseVersionTriple(text) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(String(text ?? '').trim())
+  if (!m) return null
+  return [Number(m[1]), Number(m[2]), Number(m[3])]
+}
+
+/** 三元组是否达到声明行轨（0.1.7+）：逐段数值比较，prerelease 已在上游剥掉。 */
+export function isDeclarativeTriple(triple) {
+  if (!Array.isArray(triple) || triple.length !== 3 || triple.some((n) => !Number.isInteger(n))) return false
+  const base = [0, 1, 7]
+  for (let i = 0; i < 3; i++) {
+    if (triple[i] !== base[i]) return triple[i] > base[i]
+  }
+  return true
+}
+
+/**
+ * 探测当前宿主的预设安装轨道，返回 'declarative' | 'directory'。逐级降级：
+ *   1) runtimeSystem 直通：Web 插件运行时对宿主服务的实时探测结果最权威；
+ *   2) `dsh --version`（timeout 10s；spawn 失败 / 超时 / 输出不可解析一律吞掉
+ *      落到下一级）；
+ *   3) 文件探测：单数包 @deepseek-ai/dsh-agent-preset 是 0.1.7 的声明行宿主
+ *      组件，在即声明轨（复数包时代没有它）；
+ *   4) 默认 directory —— 安全侧兜底（理由见模块头注释）。
+ */
+export async function detectPresetSystem({ dshHome, runtimeSystem = null } = {}) {
+  if (runtimeSystem === 'declarative' || runtimeSystem === 'directory') return runtimeSystem
+  const versionText = dshVersionText()
+  if (versionText !== null) {
+    const triple = parseVersionTriple(versionText)
+    if (triple !== null) return isDeclarativeTriple(triple) ? 'declarative' : 'directory'
+  }
+  if (existsSync(path.join(dshHome, 'node_modules', '@deepseek-ai', 'dsh-agent-preset'))) return 'declarative'
+  return 'directory'
+}
+
+/** `dsh --version` 取裸版本号文本；任何失败（ENOENT / 超时 / 非零退出）返回 null。 */
+function dshVersionText() {
+  try {
+    const res = spawnSync('dsh', ['--version'], { timeout: 10_000, encoding: 'utf8' })
+    if (res.error || res.status !== 0) return null
+    const text = String(res.stdout ?? '').trim()
+    return text === '' ? null : text
+  } catch {
+    return null
+  }
+}
+
+// ── 声明行构造 ──────────────────────────────────────────────────────────────
+
+/**
+ * 构造一条 preset 声明行（insert 列表元素）的 YAML 文本：
+ *
+ *     - id: preset-orchestrator
+ *       name: '@deepseek-ai/dsh-agent-preset'
+ *       config:
+ *         id: orchestrator
+ *         name: "编排模式 (Orchestrator)"
+ *         description: "..."
+ *         order: 5
+ *         plugins:
+ *           <agent.cordis.yml 全文，每非空行加 10 空格>
+ *
+ * 缩进基准：4 空格起排（`- insert:` 列表项层级由 upsertHomePatchRows 拼），
+ * plugins: 落 8 空格、插件条目行落 10 空格。name/description 用 JSON.stringify
+ * 落值——JSON 字符串即合法 YAML 双引号标量，换行/引号自动转义。agentYmlText
+ * 先把 restrict 行的 `name: ./restrict.mjs` 替换为 restrictFileUrl（绝对 file:
+ * URL），再整体 +10 缩进；空行保持空行（块标量相对缩进不变），`!!js` 表达式
+ * 行原样保留（宿主 patch schema 支持，求值仍由 cordis 装载时完成）。
+ */
+export function buildPresetRowText({ presetId, name = null, description = null, order = null, agentYmlText, restrictFileUrl }) {
+  if (typeof presetId !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(presetId)) {
+    throw new Error(`buildPresetRowText: 非法 presetId: ${presetId}`)
+  }
+  if (typeof agentYmlText !== 'string' || agentYmlText === '') {
+    throw new Error('buildPresetRowText: agentYmlText 不能为空')
+  }
+  if (typeof restrictFileUrl !== 'string' || restrictFileUrl === '') {
+    throw new Error('buildPresetRowText: restrictFileUrl 不能为空')
+  }
+  const lines = [
+    `    - id: ${presetRowId(presetId)}`,
+    `      name: '${PRESET_ROW_NAME}'`,
+    '      config:',
+    `        id: ${presetId}`,
+  ]
+  if (typeof name === 'string' && name !== '') lines.push(`        name: ${JSON.stringify(name)}`)
+  if (typeof description === 'string' && description !== '') lines.push(`        description: ${JSON.stringify(description)}`)
+  if (Number.isInteger(order)) lines.push(`        order: ${order}`)
+  lines.push('        plugins:')
+  for (const line of String(agentYmlText).split(/\r?\n/)) {
+    if (line.trim() === '') {
+      lines.push('')
+      continue
+    }
+    // restrict 行换绝对 file: URL（按行精确内容匹配，缩进原样保留）
+    const replaced = line.trim() === 'name: ./restrict.mjs'
+      ? `${line.match(/^[ \t]*/)[0]}name: ${restrictFileUrl}`
+      : line
+    lines.push(`          ${replaced}`)
+  }
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop() // 去尾部空行，段拼接才紧凑
+  return lines.join('\n')
+}
+
+// ── home patch 托管块手术 ───────────────────────────────────────────────────
+//
+// 托管块落在 $DSH_HOME/cordis.patch.yml（home 层 patch，作用于所有 profile），
+// 形态：
+//
+//     # --- dsh-paoding presets (auto-generated; do not edit) ---
+//     - insert:
+//         - id: preset-orchestrator
+//           name: '@deepseek-ai/dsh-agent-preset'
+//           config:
+//             ...
+//     # --- end dsh-paoding presets ---
+//
+// 每条声明行各自包一层 0 缩进的 `- insert:`（宿主约定「自定义【新增】条目必须
+// 用 - insert: 包一层」，顶层 - id: 是修改已有条目语义），声明行本体按
+// buildPresetRowText 的 4 空格基准缩进，作 insert 列表元素。块外用户内容除
+// strip 的空行收敛外一字节不动。
+
+/** home 层 patch 文件路径。 */
+function patchFilePath(dshHome) {
+  return path.join(dshHome, 'cordis.patch.yml')
+}
+
+/** 读 home patch 为行数组；文件缺失当空文件。行尾换行符风格随原文件保留。 */
+function readPatchLines(dshHome) {
+  let text = ''
+  try {
+    text = readFileSync(patchFilePath(dshHome), 'utf8')
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err
+    return { lines: [], eol: '\n' }
+  }
+  if (text === '') return { lines: [], eol: '\n' }
+  return { lines: text.split(/\r?\n/), eol: text.includes('\r\n') ? '\r\n' : '\n' }
+}
+
+function writePatchLines(dshHome, lines, eol) {
+  mkdirSync(dshHome, { recursive: true })
+  writeFileSync(patchFilePath(dshHome), lines.join(eol), 'utf8')
+}
+
+/**
+ * 在行数组里定位托管块 [begin, end]（闭区间下标）。无起始标记返回 null；
+ * 有起始无结束（托管块损坏，多半是用户手删了半截）throw 明确错误——后续写盘
+ * 一律拒绝，绝不覆盖手工内容。
+ */
+function findManagedSpan(lines) {
+  const begin = lines.findIndex((l) => l.trim() === MANAGED_BEGIN)
+  if (begin === -1) return null
+  let end = -1
+  for (let i = begin + 1; i < lines.length; i++) {
+    if (lines[i].trim() === MANAGED_END) {
+      end = i
+      break
+    }
+  }
+  if (end === -1) {
+    throw new Error(
+      `cordis.patch.yml 的 dsh-paoding 托管块已损坏（只有起始标记、找不到结束标记 "${MANAGED_END}"）：` +
+        '请手工补回结束标记，或把整个托管块删除后重试；已拒绝写盘以免覆盖手工内容',
+    )
+  }
+  return { begin, end }
+}
+
+/** 托管块内声明行段的起始行：4 空格缩进的 `- id: preset-...`。 */
+const ROW_ID_LINE_RE = /^ {4}- id: (preset-\S+)[ \t]*$/
+
+/**
+ * 把托管块内容行解析成行段数组 [{ rowId, lines }]：每个段由 `- insert:` 包裹行
+ * （若紧邻在 `- id:` 行上方）加声明行本体组成，到下一段或块尾止。段尾空行归
+ * 所属段，重写时裁掉保持块紧凑。
+ */
+function parseRowSegments(blockLines) {
+  const marks = []
+  for (let i = 0; i < blockLines.length; i++) {
+    const m = ROW_ID_LINE_RE.exec(blockLines[i])
+    if (!m) continue
+    // 段首含紧邻的 `- insert:` 包裹行；包裹行不在（手工摆弄过）则从行本体起段
+    const segStart = i > 0 && blockLines[i - 1].trim() === '- insert:' ? i - 1 : i
+    marks.push({ rowId: m[1], segStart })
+  }
+  return marks.map((mk, idx) => ({
+    rowId: mk.rowId,
+    lines: blockLines.slice(mk.segStart, idx + 1 < marks.length ? marks[idx + 1].segStart : blockLines.length),
+  }))
+}
+
+/** 裁掉行数组尾部的空行（不含末尾那个代表「文件以换行结束」的空元素）。 */
+function trimTrailingBlankLines(lines) {
+  const out = [...lines]
+  while (out.length > 1 && out[out.length - 1].trim() === '') out.pop()
+  return out
+}
+
+/** 3+ 连续空行收敛为一个空行（strip 撤行后的兜底收拾；1-2 连续空行原样保留）。 */
+function collapseBlankRuns(lines) {
+  const out = []
+  let blankRun = 0
+  for (const line of lines) {
+    if (line.trim() === '') {
+      blankRun++
+      continue
+    }
+    if (blankRun > 0) {
+      if (blankRun >= 3) out.push('')
+      else for (let i = 0; i < blankRun; i++) out.push('')
+      blankRun = 0
+    }
+    out.push(line)
+  }
+  for (let i = 0; i < blankRun; i++) out.push('') // 文件尾空行原样保留
+  return out
+}
+
+/**
+ * 把若干声明行（buildPresetRowText 产物）行级 upsert 进 home patch 托管块。
+ * 托管块不存在则文末新建（非空文件先补尾换行、块前空一行）；已存在则块内按
+ * rowId 替换 / 追加，块外用户内容一字节不动。托管块损坏时 throw（不写盘）。
+ */
+export function upsertHomePatchRows(dshHome, rowTexts) {
+  const rows = (Array.isArray(rowTexts) ? rowTexts : [])
+    .filter((t) => typeof t === 'string' && t.trim() !== '')
+  if (rows.length === 0) return
+  const wanted = rows.map((text) => {
+    const rowLines = text.replace(/\r?\n$/, '').split('\n')
+    const m = ROW_ID_LINE_RE.exec(rowLines[0])
+    if (!m) {
+      throw new Error(`buildPresetRowText 产出的行文本缺少 4 空格缩进的 "- id: preset-..." 首行: ${rowLines[0]}`)
+    }
+    return { rowId: m[1], lines: ['- insert:', ...rowLines] }
+  })
+  // 同 rowId 传多条时后者生效（Map 去重，保证替换语义而非重复追加）
+  const wantedById = new Map(wanted.map((w) => [w.rowId, w]))
+
+  const { lines, eol } = readPatchLines(dshHome)
+  const span = findManagedSpan(lines) // 损坏块 throw，直接中止（未写任何盘）
+  if (span !== null) {
+    const segments = parseRowSegments(lines.slice(span.begin + 1, span.end))
+    const merged = []
+    for (const seg of segments) {
+      if (wantedById.has(seg.rowId)) merged.push(...wantedById.get(seg.rowId).lines)
+      else merged.push(...trimTrailingBlankLines(seg.lines)) // 块内其余 preset 的行原样保留
+    }
+    for (const w of wanted) {
+      if (!segments.some((s) => s.rowId === w.rowId)) merged.push(...w.lines) // 新行追加到块尾
+    }
+    const next = [...lines.slice(0, span.begin), MANAGED_BEGIN, ...merged, MANAGED_END, ...lines.slice(span.end + 1)]
+    writePatchLines(dshHome, next, eol)
+    return
+  }
+  // 无托管块：文末新建。非空文件先补尾换行（若缺）。块前空一行不再单独推：
+  // split 出的末尾 '' 元素（文件尾换行）后面紧跟新内容时，join 天然渲染出一个
+  // 空行，正好兼任块前分隔——补的尾换行元素同理。额外再推一个空行会变成两个。
+  const out = [...lines]
+  const hasContent = out.some((l) => l.trim() !== '')
+  if (hasContent && out[out.length - 1].trim() !== '') out.push('')
+  out.push(MANAGED_BEGIN)
+  for (const w of wanted) out.push(...w.lines)
+  out.push(MANAGED_END, '')
+  writePatchLines(dshHome, out, eol)
+}
+
+/**
+ * 从 home patch 托管块撤掉指定 rowId 的声明行段；rowIdsOrAll 传 null 删整块
+ * （含起止标记与块前自加的空行分隔，用户内容回到插入前的字节形态）。
+ * 块不存在 / 指定行都不在场返回 false（未写盘）；托管块损坏时 warn 后返回
+ * false（撤行是锦上添花的自愈路径，不值得为此中断安装，修复由 upsert 的
+ * 明确报错引导）。
+ */
+export function stripHomePatchRows(dshHome, rowIdsOrAll = null) {
+  let lines
+  let eol
+  try {
+    ({ lines, eol } = readPatchLines(dshHome))
+  } catch (err) {
+    warn(`cordis.patch.yml 读取失败，声明行撤除跳过: ${err?.message ?? err}`)
+    return false
+  }
+  let span = null
+  try {
+    span = findManagedSpan(lines)
+  } catch (err) {
+    warn(`${err.message}（声明行撤除跳过）`)
+    return false
+  }
+  if (span === null) return false
+
+  const allSegments = parseRowSegments(lines.slice(span.begin + 1, span.end))
+  const targets = rowIdsOrAll === null
+    ? allSegments
+    : allSegments.filter((s) => new Set(rowIdsOrAll).has(s.rowId))
+  if (targets.length === 0) return false
+
+  if (targets.length === allSegments.length) {
+    // 整块摘除：连同块前那行本工具自加的空行分隔一起拿掉（空行分隔是自己
+    // 加的，摘掉才算「用户内容回到插入前」）
+    let start = span.begin
+    if (start > 0 && lines[start - 1].trim() === '' && lines.slice(0, start).some((l) => l.trim() !== '')) start -= 1
+    const next = [...lines.slice(0, start), ...lines.slice(span.end + 1)]
+    // 文件撤空（只剩空行）就落空文件，不留一撮换行尾巴
+    const empty = next.every((l) => l.trim() === '')
+    writePatchLines(dshHome, empty ? [] : collapseBlankRuns(next), eol)
+    return true
+  }
+  // 块内还有其余 preset 的行：只摘指定段，标记与块结构保留
+  const removeIds = new Set(targets.map((t) => t.rowId))
+  const merged = []
+  for (const seg of allSegments) {
+    if (!removeIds.has(seg.rowId)) merged.push(...trimTrailingBlankLines(seg.lines))
+  }
+  const next = [...lines.slice(0, span.begin), MANAGED_BEGIN, ...merged, MANAGED_END, ...lines.slice(span.end + 1)]
+  writePatchLines(dshHome, collapseBlankRuns(next), eol)
+  return true
+}
+
+/**
+ * 读 home patch 托管块里现有的声明行 [{ rowId, presetId }]（presetId 取自声明
+ * 行 config 的 id: 值，8 空格缩进；解析不出为 null）。文件缺失 / 无托管块 /
+ * 托管块损坏一律返回空数组——调用方只拿它做「块在不在」的判断。
+ */
+export function readHomePatchRows(dshHome) {
+  let lines
+  try {
+    ({ lines } = readPatchLines(dshHome))
+  } catch {
+    return []
+  }
+  try {
+    const span = findManagedSpan(lines)
+    if (span === null) return []
+    const configIdRe = /^ {8}id: (\S+)[ \t]*$/
+    return parseRowSegments(lines.slice(span.begin + 1, span.end)).map((seg) => {
+      const idLine = seg.lines.find((l) => configIdRe.test(l))
+      return { rowId: seg.rowId, presetId: idLine ? configIdRe.exec(idLine)[1] : null }
+    })
+  } catch {
+    return []
+  }
+}

package/tools/lib/state.mjs

@@ -1,12 +1,15 @@
 /**
  * 公共状态管线：collectState（patch 分层扫描 / MCP 工具名解析 / 插件与技能检测 /
- * smart defaults，含可选 runtimeFacts 合并 / 已落盘 preset 目录扫描）与
- * generateAndInstall（compose + yaml 校验 + dst 目录落盘 + saveConfig，支持按
- * 工作区落到 orchestrator-<slug> 独立 preset 目录并把条目并进配置 workspaces 段；
- * 配置读取失败 / 状态不可信时拒绝破坏性落盘，成功后回收孤儿工作区 preset）。
+ * smart defaults，含可选 runtimeFacts 合并 / 预设安装轨道探测 / 已落盘 preset
+ * 目录扫描）与 generateAndInstall（compose + yaml 校验 + dst 目录落盘 +
+ * saveConfig，支持按工作区落到 orchestrator-<slug> 独立 preset 目录并把条目
+ * 并进配置 workspaces 段；配置读取失败 / 状态不可信时拒绝破坏性落盘，成功后
+ * 回收孤儿工作区 preset；并按 presetSystem 双轨收尾——0.1.7+ 声明行轨把声明行
+ * upsert 进 home patch 托管块，≤0.1.6 目录扫描轨撤掉残留声明块自愈）。
  * install.mjs 的公共导出（collectState / generateAndInstall）即来自本模块。
- * 依赖 util / yaml / config / host / skills / spans / compose / alloc / workspaces
- * 与 node:fs / node:path；被 cli 与 plugins/paoding-config-ui 引用。
+ * 依赖 util / yaml / config / host / skills / spans / compose / alloc /
+ * workspaces / preset-system 与 node:fs / node:path / node:url；被 cli 与
+ * plugins/paoding-config-ui 引用。
  */
 import {
   chmodSync,
@@ -20,6 +23,7 @@ import {
   writeFileSync,
 } from 'node:fs'
 import path from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { DEFAULT_MAIN_AGENT_PERSONA_EXTRA, ROLES, SRC_DIR, warn } from './util.mjs'
 import { flattenEntries, loadYaml, parsePatchFile } from './yaml.mjs'
 import {
@@ -43,6 +47,14 @@ import { detectSkills, findSkillMeta } from './skills.mjs'
 import { locateAllowBlocks, locatePersonaBlocks } from './spans.mjs'
 import { composeGenerated, extractMainAgentAllow } from './compose.mjs'
 import { smartDefaults } from './alloc.mjs'
+import {
+  buildPresetRowText,
+  detectPresetSystem,
+  presetRowId,
+  readHomePatchRows,
+  stripHomePatchRows,
+  upsertHomePatchRows,
+} from './preset-system.mjs'
 
 /**
  * Reusable state collection for the CLI and the visual config UI.
@@ -51,11 +63,13 @@ import { smartDefaults } from './alloc.mjs'
  * without writing anything or prompting. Throws on hard errors.
  *
  * `runtimeFacts`（可选，仅 Web 配置器经 ctx 传入）是运行时优先的补充事实：
- * { ok, error?, pluginEntries, toolNames }，来自 plugins/paoding-config-ui/
- * runtime-inventory.mjs。不传时整段合并逻辑跳过，行为与旧版完全一致；传入时
- * 把 preset 未覆盖的运行时工具并进 inventory / mcpReports / pluginReports，
- * 让 bundle 形态加载的插件（@hyzyn/dsh-codegraph、dsh-mnemon 等）也能被识别。
- * 文件扫描路径（KNOWN_HOST_PLUGINS 白名单等）始终保持为兜底，不动。
+ * { ok, error?, pluginEntries, toolNames, presetSystem }，来自
+ * plugins/paoding-config-ui/runtime-inventory.mjs。不传时整段合并逻辑跳过，
+ * 行为与旧版完全一致；传入时把 preset 未覆盖的运行时工具并进 inventory /
+ * mcpReports / pluginReports，让 bundle 形态加载的插件（@hyzyn/dsh-codegraph、
+ * dsh-mnemon 等）也能被识别；presetSystem（预设安装轨道）直接采信，免去
+ * dsh --version 子进程探测。文件扫描路径（KNOWN_HOST_PLUGINS 白名单等）
+ * 始终保持为兜底，不动。
  */
 export async function collectState({ dshHome, configFile, profile = null, patches = [], cwd = process.cwd(), runtimeFacts = null }) {
   const dstDir = path.join(dshHome, '.agent-presets', 'orchestrator')
@@ -211,10 +225,17 @@ export async function collectState({ dshHome, configFile, profile = null, patche
     }
   }
 
+  // 预设安装轨道探测（declarative = 0.1.7+ 声明行轨 / directory = ≤0.1.6 目录
+  // 扫描轨）。运行时事实里带 presetSystem（Web 插件对宿主服务的实时探测）时
+  // 直接采信零开销；CLI / 首装链路没有运行时事实，走 dsh --version + 文件探测
+  //（见 preset-system.detectPresetSystem 的降级链）。
+  const presetSystem = await detectPresetSystem({ dshHome, runtimeSystem: runtimeFacts?.presetSystem ?? null })
+
   // 已落盘 preset 目录扫描（编排类）：.agent-presets 下的 orchestrator 基础
   // preset 与 orchestrator-<slug> 工作区专属 preset。扫描失败（目录尚不存在、
   // 无读权限等）一律降级为空列表，绝不影响检测结果本体；generateAndInstall
-  // 成功落盘后以它为对账清单做孤儿工作区 preset 回收。
+  // 成功落盘后以它为对账清单做孤儿工作区 preset 回收。两轨的产物目录同名同
+  // 位置（.agent-presets/<presetId>/），这一扫描天然覆盖两轨的 installed 判定。
   let installedPresets = []
   try {
     installedPresets = readdirSync(path.join(dshHome, '.agent-presets'))
@@ -248,6 +269,8 @@ export async function collectState({ dshHome, configFile, profile = null, patche
     // 已落盘的编排类 preset 目录名列表（含基础 orchestrator 与各工作区专属），
     // 供 UI 的 workspaceMeta 对账「该工作区 preset 是否已生成」。
     installedPresets,
+    // 预设安装轨道（generateAndInstall 据此双轨收尾；serializeState 透传给面板）
+    presetSystem,
     // 主 persona 尾部追加的默认常量（配置键 main_agent_persona_extra 缺省值）：
     // 供 UI state（serializeState → /api/paoding/state）展示与「恢复默认」用。
     mainPersonaExtraDefault: DEFAULT_MAIN_AGENT_PERSONA_EXTRA,
@@ -259,16 +282,64 @@ export async function collectState({ dshHome, configFile, profile = null, patche
   }
 }
 
+/**
+ * SRC preset.yml 显示元数据提取（name / description / order）：声明行轨把这些
+ * 值写进 home patch 声明行的 config，取值口径与目录轨写 preset.yml 完全同源
+ * （name 可被 main_agent_display_name / 工作区派生名覆盖，见 generateAndInstall
+ * 调用处）。preset.yml 是仓库内受控格式：顶层 name / order 单行标量 +
+ * description 多行纯量（续行按 YAML 折叠语义以空格拼接成单值，落声明行时由
+ * JSON.stringify 转义）。读不到 / 解析不出时返回空元数据——声明行的
+ * name / description / order 都是宿主可选键，缺省不致命。
+ */
+function readPresetMeta() {
+  try {
+    const text = readFileSync(path.join(SRC_DIR, 'preset.yml'), 'utf8')
+    const lines = text.split(/\r?\n/)
+    const firstMatch = (re) => {
+      for (const line of lines) {
+        const m = re.exec(line)
+        if (m) return m
+      }
+      return null
+    }
+    const name = firstMatch(/^name:[ \t]*(.+?)[ \t]*$/)?.[1] ?? null
+    const orderRaw = firstMatch(/^order:[ \t]*(\d+)[ \t]*$/)
+    const order = orderRaw ? Number(orderRaw[1]) : null
+    let description = null
+    const di = lines.findIndex((l) => /^description:/.test(l))
+    if (di !== -1) {
+      const parts = [lines[di].slice('description:'.length).trim()]
+      for (let i = di + 1; i < lines.length; i++) {
+        const line = lines[i]
+        if (line.trim() === '' || !/^[ \t]/.test(line)) break // 续行尽 / 撞上下一个顶层键
+        parts.push(line.trim())
+      }
+      description = parts.filter((p) => p !== '').join(' ') || null
+    }
+    return { name, description, order }
+  } catch {
+    return { name: null, description: null, order: null }
+  }
+}
+
 /**
  * Compose, validate and (unless dry-run) install the generated preset from an
  * assignments object. Shared by the CLI and the visual config UI.
- * Returns { text, roleResults, staleNote, wrote, presetId }.
+ * Returns { text, roleResults, staleNote, wrote, presetId, presetSystem }.
  *
  * 破坏性落盘护栏：配置读取失败直接抛错中止（不静默降级 prev=null 继续装）；
  * 配置缺失（prev=null）而目标 preset 目录已存在时同样拒绝重建。落盘成功后对
  * state.installedPresets 做孤儿工作区 preset 回收（不被 workspaces 引用的
  * orchestrator-<slug> 目录 rmSync + warn；基础 preset 永不清）。
  *
+ * 预设安装双轨收尾（wrote=true 才动，dry-run 零副作用）：
+ *   - declarative（0.1.7+，目录扫描机制已删）：把本 preset 以一条 `- insert:`
+ *     声明行 upsert 进 $DSH_HOME/cordis.patch.yml 托管块（restrict.mjs 用绝对
+ *     file: URL）；孤儿工作区回收处同步撤对应声明行——目录与行同生同灭。
+ *   - directory（≤0.1.6）：上面落盘即完成；home patch 里若有残留托管声明块
+ *    （宿主刚从 0.1.7 降级等场景）整块撤下自愈——残留声明行会让 profile 启动
+ *     失败。
+ *
  * workspacePath（可选）：传工作区绝对路径时生成落到 orchestrator-<slug> 独立
  * preset 目录（slug 由磁盘配置现有 workspaces 键 ∪ 本路径统一分配，同名目录
  * 冲突自动加 hash 后缀），preset 显示名按 main_agent_display_name >
@@ -283,6 +354,10 @@ export function generateAndInstall(state, assignments, { dryRun = false, saveCon
   // 一律丢弃，防其混进生成的 preset 或覆盖配置文件里对应的段。
   assignments = stripNonTargetKeys(assignments)
 
+  // 预设安装轨道（collectState 已探测；缺省按目录轨兜底——安全侧，理由见
+  // preset-system 模块头注释）
+  const presetSystem = state.presetSystem ?? 'directory'
+
   // 工作区定位：路径归一（容忍尾斜杠 / 相对写法），空值一律视为全局。
   const wsPath = workspacePath === null || workspacePath === undefined || workspacePath === ''
     ? null
@@ -452,9 +527,45 @@ export function generateAndInstall(state, assignments, { dryRun = false, saveCon
         warn(`孤儿工作区 preset 已回收: ${dir}（配置 workspaces 已无引用）`)
       } catch (err) {
         warn(`孤儿工作区 preset 回收失败（已保留）: ${dir}: ${err?.message ?? err}`)
+        continue
       }
+      if (presetSystem === 'declarative') {
+        // 声明行轨：目录回收了，home patch 托管块里的对应声明行同步撤下——
+        // 目录与行必须同生同灭，否则 0.1.7 宿主会挂出一个指向已删目录的 preset。
+        try {
+          stripHomePatchRows(dshHome, [presetRowId(name)])
+        } catch (err) {
+          warn(`孤儿 preset 的声明行撤除失败（${presetRowId(name)}）: ${err?.message ?? err}`)
+        }
+      }
+    }
+  }
+
+  // ── 预设安装双轨收尾（wrote=true 才动；dry-run 零副作用）────────────────
+  // declarative（0.1.7+）：目录扫描机制已删，必须把本 preset 以一条 `- insert:`
+  // 声明行写进 home patch 托管块才算安装完成（preset 元信息与写 preset.yml 同
+  // 源：显示名取 displayName ?? SRC preset.yml 的 name，description / order 取
+  // SRC；restrict.mjs 用绝对 file: URL——声明行没有「相对 preset 目录」语义）。
+  // directory（≤0.1.6）：上面落盘即完成；home patch 里若有残留托管声明块
+  //（宿主刚从 0.1.7 降级等场景）整块撤下自愈——残留声明行会让 profile 启动失败。
+  if (wrote) {
+    if (presetSystem === 'declarative') {
+      const meta = readPresetMeta()
+      upsertHomePatchRows(dshHome, [
+        buildPresetRowText({
+          presetId,
+          name: displayName ?? meta.name,
+          description: meta.description,
+          order: meta.order,
+          agentYmlText: generatedText,
+          restrictFileUrl: pathToFileURL(path.join(dstDir, 'restrict.mjs')).href,
+        }),
+      ])
+    } else if (readHomePatchRows(dshHome).length > 0) {
+      stripHomePatchRows(dshHome, null)
+      warn('cordis.patch.yml 检出 dsh-paoding 声明块，但当前宿主是目录扫描轨（DSH ≤ 0.1.6），已整块撤下（残留声明行会导致 profile 启动失败）')
     }
   }
 
-  return { text: generatedText, roleResults, staleNote, wrote, presetId }
+  return { text: generatedText, roleResults, staleNote, wrote, presetId, presetSystem }
 }