dsh-paoding 0.2.2 → 0.3.1

package/README.md

@@ -9,56 +9,51 @@ dsh-paoding（中文品牌「庖丁」，典出《庄子》——庖丁顺纹理
 
 - **一支分工明确的小团队**：主 agent 当指挥，拆解任务、分派验收；联网调研、UI 设计、写代码、全仓深搜四位专属帮手各司其职，随叫随到、干完即走。
 - **高频小事不过手他人**：找代码、查引用、读文件这类顺手的事，主 agent 自己直接办，不绕委派的圈子。
-- **可招募专属帮手**：内置四角色只是起点——给新角色配好工具和技能（比如装上 `html-ppt` 技能的 PPT 帮手），之后一句「把这份大纲做成 PPT」就有人接活。向导、配置文件、图形界面三个入口都能建。
+- **可招募专属帮手**：内置四角色只是起点——给新角色配好工具和技能（比如装上 `html-ppt` 技能的 PPT 帮手），之后一句「把这份大纲做成 PPT」就有人接活。配置文件、图形界面两个入口都能建。
 - **帮手还能指定专用模型**：写代码的用强档、查资料的用轻快档，各配各的模型；不配就跟随主 agent 当前会话的模型。
+- **帮手能就地续修**：把某个角色的「会话模式」切成可续（continuable），活干砸了或干得不满意，主 agent 用 `send_message` 在同一个子会话接着修，不用从头重派；默认全员一次性（one-shot）用完即弃，不开启就一切照旧。
 - **省钱省上下文**：帮手的工具只在被叫到时才加载，用一次付一次；主 agent 每次请求的工具开销约降三分之二，上下文只收摘要，不再被搜索结果和代码改动撑爆。
-- **角色随改随用**：删掉用不上的内置角色、给角色改显示名、给主 agent 改名，都是配置里一行的事；改完跑一条命令重新生成，即刻生效。
-- **装了什么都能认出来**：MCP 服务器、本地插件、已装技能，安装与配置时全程检测；默认只装 dsh 基础工具，检测到的 host 工具在「庖丁配置」里按需勾选（或 `--suggest` 自动分派）；停用哪个，重跑一遍后相关工具自动剔除。
-- **图形界面配置**：不习惯改配置文件的话，「设置 → 庖丁配置」里点选即可，「保存并应用」与命令行走同一条生成管线。
+- **角色随改随用**：删掉用不上的内置角色、给角色改显示名、给主 agent 配显示名，都是配置里一行的事；改完在面板点一次「保存并应用」，预设即时重生成，重启 DSH / 新建会话后生效。
+- **装了什么都能认出来**：MCP 服务器、本地插件、已装技能，安装与配置时全程检测；默认只装 dsh 基础工具，检测到的 host 工具在「庖丁配置」里按需勾选；停用哪个，重新应用后相关工具自动剔除。
+- **按工作区各有各的班底**：不同项目可以配不同的主/子 agent——「庖丁配置」里选定工作区单独配置，每个工作区生成自己的预设（`orchestrator-<目录名>`），新建会话时选对应预设即可，全局默认不受影响。
+- **图形界面配置**：不习惯改配置文件的话，点开左侧栏底部动作条（设置行上方）的「庖丁配置」入口，整页点选即可，「保存并应用」即时重生成预设——与首装自动化同一条生成管线。
+- **版本更新有提醒，面板一键升级**：面板会对比 npm registry（GitHub release 兜底）上的最新版本，发现新版就地提示并附上发布页链接；点「升级」就地执行 `dsh plugin update dsh-paoding`（profile 自动探测）换上新版，重启 DSH 后生效，编排预设会在重启时按新版自动重生成。开发检出的 link 形态无法就地升级，面板会提示切回 registry 版的办法；检测失败（比如断网）就静默跳过，不影响任何使用。
 - **来去自由**：不改 DSH 一行源码；装完新会话即用，卸载即删目录。
 
 ## 插件截图
 
 ![截图 1](docs/images/1.png)
 
-![截图 2](docs/images/2.png)
+## 快速开始
 
-![截图 3](docs/images/3.png)
+前置：**Node.js ≥ 18**、**pnpm** 与一台已装好的 DSH host（**@deepseek-ai/dsh ≥ 0.1.5**，最低支持版本）。
 
-![截图 4](docs/images/4.png)
+**官方插件通道（唯一安装入口）**——不用克隆仓库，一条命令，装完重启即用：
 
-![截图 5](docs/images/5.png)
+```bash
+dsh plugin --profile web add dsh-paoding
+```
 
-![截图 6](docs/images/6.png)
+等价捷径：`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 里选。
 
-前置：**Node.js ≥ 18** 与一台已装好的 DSH host。
-
-**npx 一键安装（推荐）**——不用克隆仓库，一条命令：
+开箱默认只带 DSH 自带的基础工具，检测到的 MCP/host 工具不会自动写入——装完点开左侧栏的**「庖丁配置」**按需勾选工具与角色，「保存并应用」即生效。不想要了，三条命令卸干净（按工作区配置生成的各工作区预设也一并删除）：
 
 ```bash
-npx dsh-paoding@latest             # npm 发布后可用
-npx github:lifangjin/dsh-paoding   # 发布前从 GitHub 仓库直装，效果相同
+dsh plugin --profile web remove dsh-paoding
+rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets/orchestrator"
+rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets"/orchestrator-*
 ```
 
-这一条等价于 `--auto --config-ui`：生成编排预设、写好基础配置模板，并把「庖丁配置」挂进 DSH 设置页。开箱默认只带 DSH 自带的基础工具，检测到的 MCP/host 工具不会自动写入——装完在**设置 → 庖丁配置**里按需勾选工具与角色，「保存并应用」即生效；想逐项过一遍就跑 `npx dsh-paoding --wizard`，想沿用自动分配就加 `--suggest`。
-
-偏好官方插件通道的话，`dsh plugin --profile web add dsh-paoding@latest` 也能把「庖丁配置」按 profile 装进设置页（preset 本体仍走 npx / `./install.sh`），详见[安装文档](docs/installation.md)。
-
-**克隆仓库安装**——老路线原样保留：
+**开发检出自装**——想改插件或预设源码时，用 link 形态直连仓库（改动经 HMR/重启生效）：
 
 ```bash
-git clone https://github.com/lifangjin/dsh-paoding.git dsh-paoding
-cd dsh-paoding
-./install.sh              # 交互向导，一路回车即用默认
-./install.sh --auto       # 非交互：有配置应用配置，没配置写基础模板（--suggest 用智能默认）
-./install.sh --config-ui  # 顺带挂上图形配置界面（可与 --auto 同用）
-./install.sh --dry-run    # 只预览将生成的内容，不写盘
-./install.sh --help       # 全部参数
+git clone https://github.com/lifangjin/dsh-paoding.git
+dsh plugin --profile web add link:"$PWD/dsh-paoding"
 ```
 
-装完**重启 DSH（`dsh web`）或新建会话**，在预设选择器里选「编排模式 (Orchestrator)」即可；要设为默认，在 Settings → Agent Presets 里选。已有 `dsh-paoding.config.yml` 的话，重跑任何入口都按配置文件应用、不覆写。卸载删掉 `~/.dsh/.agent-presets/orchestrator` 即可（npx/npm 安装的还多一个 `~/.dsh/dsh-paoding`）。详细步骤与排查见 [安装文档](docs/installation.md)。
+升级走面板「升级」按钮（等价 `dsh plugin update dsh-paoding`）。详细步骤、升级与排查见 [安装文档](docs/installation.md)。
 
 ## 怎么用
 
@@ -75,20 +70,20 @@ cd dsh-paoding
 
 ## 配置
 
-所有偏好都写在 `~/.dsh/dsh-paoding.config.yml`：角色增删改、技能分配、专用模型、主 agent 的工具与技能……改完跑一遍 `./install.sh --auto` 即同步生效。预设每次由「静态源 + 配置」重新生成，不攒手工补丁。全部配置键说明见 [配置文档](docs/configuration.md)；背后机制与成本账见 [架构文档](docs/architecture.md)。
+所有偏好都写在 `~/.dsh/dsh-paoding.config.yml`：角色增删改、技能分配、专用模型、会话模式（one-shot / continuable）、主 agent 的工具与技能……改完打开左侧栏底部的「庖丁配置」入口，点「保存并应用」即同步生效。预设每次由「静态源 + 配置」重新生成，不攒手工补丁。全部配置键说明见 [配置文档](docs/configuration.md)；背后机制与成本账见 [架构文档](docs/architecture.md)。
 
 ## 文档
 
 | 文档 | 内容 |
 |---|---|
 | [架构](docs/architecture.md) | 为什么这样设计——概述、成本账、角色与工具、对应 DSH 原生机制、Token 治理、已知边界。 |
-| [安装](docs/installation.md) | npx 一键安装、官方插件通道装 UI、前置要求、交互向导六阶段、CLI 参数、host patch 检测机制、应用/升级/卸载、配置 UI 挂载、排查。 |
+| [安装](docs/installation.md) | 官方插件通道一条命令安装、首装自动化与版本标记、升级、开发检出自装、host patch 检测机制、庖丁配置面板、卸载、排查。 |
 | [编排](docs/orchestration.md) | 编排总览、失败如何呈现与三层处理、one-shot vs continuable、上下文隔离。 |
-| [配置](docs/configuration.md) | 配置键全参考、内置角色微调、主 agent 工具与技能、自定义角色、按角色分模型。 |
+| [配置](docs/configuration.md) | 配置键全参考、内置角色微调、主 agent 工具与技能、自定义角色、按角色分模型、角色会话模式。 |
 
 ## 贡献
 
-欢迎 issue 与 PR：使用中发现问题、想要新的角色、或发现文档与实现不一致，都可以提。动手前请先读 [架构](docs/architecture.md) 与 [配置](docs/configuration.md)；文档与实现冲突时，以 `presets/orchestrator/` 与 `tools/install.mjs` 源码为准。
+欢迎 issue 与 PR：使用中发现问题、想要新的角色、或发现文档与实现不一致，都可以提。动手前请先读 [架构](docs/architecture.md) 与 [配置](docs/configuration.md)；文档与实现冲突时，以 `presets/orchestrator/` 与 `tools/` 源码为准。
 
 ## 许可
 

package/README_en.md

@@ -9,56 +9,51 @@ dsh-paoding (Chinese brand 「庖丁」/ Pao Ding, from the Zhuangzi parable of
 
 - **A small team with clear roles**: the main agent acts as the lead — it breaks work down, delegates, and reviews results. Four specialist helpers (web research, UI/design, coding, whole-repo search) each carry only their own tools, show up when called, and leave when done.
 - **Everyday tasks never leave the desk**: finding code, checking references, reading files — the main agent handles those itself, no delegation round-trips.
-- **Recruit your own specialists**: the four built-ins are just the start. Give a new role its tools and skills (say, an `html-ppt`-equipped slide maker), and "turn this outline into a PPT" is someone else's job from then on. Create roles in the wizard, the config file, or the config UI.
+- **Recruit your own specialists**: the four built-ins are just the start. Give a new role its tools and skills (say, an `html-ppt`-equipped slide maker), and "turn this outline into a PPT" is someone else's job from then on. Create roles in the config file or the 庖丁配置 panel.
 - **A dedicated model per helper**: pin the coder to a stronger model and the researcher to a lighter, faster one; unset, they follow the main agent's current session model.
+- **Helpers that finish the job in place**: flip a role's session mode to continuable and, when a run fails or disappoints, the main agent resumes the same child conversation with `send_message` instead of re-delegating from scratch. Every role defaults to one-shot — run and discard — so nothing changes until you flip it.
 - **Cheaper requests, cleaner context**: a helper's tools load only when it is called — pay per use. The main agent's per-request tool overhead drops by roughly two-thirds, and it keeps only summaries instead of accumulating search dumps and diffs.
-- **Roles bend to your setup**: delete built-in roles you don't need, give roles display names, rename the main agent — all one line of config; re-run one command and the preset regenerates instantly.
-- **Whatever you've installed, it's recognized**: MCP servers, local plugins, installed skills — detected throughout install and configuration; the default install carries only DSH base tools, and detected host tools are opted into per tool in **Paoding Config** (or auto-assigned with `--suggest`); disable one, re-run, and its tools drop out on their own.
-- **A visual configurator**: prefer clicking to editing YAML? "Settings → 庖丁配置" covers everything, sharing the exact same generation pipeline as the CLI.
+- **Roles bend to your setup**: delete built-in roles you don't need, give roles display names, set a display name for the main agent — all one line of config; hit Save & Apply in the panel once and the preset regenerates on the spot, taking effect after a DSH restart or a new session.
+- **Whatever you've installed, it's recognized**: MCP servers, local plugins, installed skills — detected throughout install and configuration; the default install carries only DSH base tools, and detected host tools are opted into per tool in **Paoding Config**; disable one, re-apply, and its tools drop out on their own.
+- **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.
+- **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.
 
 ## Screenshots
 
 ![Screenshot 1](docs/images/1.png)
 
-![Screenshot 2](docs/images/2.png)
+## Quick Start
 
-![Screenshot 3](docs/images/3.png)
+Prerequisites: **Node.js ≥ 18**, **pnpm**, and a working DSH host (**@deepseek-ai/dsh >= 0.1.5**, the minimum supported version).
 
-![Screenshot 4](docs/images/4.png)
+**The official plugin channel (the only install route)** — no clone needed; one command, then a restart:
 
-![Screenshot 5](docs/images/5.png)
+```bash
+dsh plugin --profile web add dsh-paoding
+```
 
-![Screenshot 6](docs/images/6.png)
+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>`.
 
-## Quick Start
+`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.
 
-Prerequisites: **Node.js ≥ 18** and a working DSH host.
-
-**One-command install with npx (recommended)** — no clone needed:
+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:
 
 ```bash
-npx dsh-paoding@latest             # available once the package is published to npm
-npx github:lifangjin/dsh-paoding   # before publishing: runs straight from GitHub, same effect
+dsh plugin --profile web remove dsh-paoding
+rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets/orchestrator"
+rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets"/orchestrator-*
 ```
 
-This one command equals `--auto --config-ui`: it generates the orchestrator preset, writes the base config template, and mounts the config UI into the DSH Settings page. Out of the box the template only carries DSH's built-in base tools — detected MCP/host tools are not written in automatically. After installing, pick the tools and roles you need in **Settings → 庖丁配置 (Paoding Config)** and hit Save & Apply, or run `npx dsh-paoding --wizard` for a guided pass; add `--suggest` if you prefer the old auto-assignment.
-
-If you prefer the official plugin channel, `dsh plugin --profile web add dsh-paoding@latest` installs the Paoding Config UI into Settings, scoped per profile (the preset itself still comes from npx / `./install.sh`) — see the [installation guide](docs/installation_en.md).
-
-**Clone and install** — the classic route, unchanged:
+**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
-git clone https://github.com/lifangjin/dsh-paoding.git dsh-paoding
-cd dsh-paoding
-./install.sh              # interactive wizard; press Enter to keep defaults
-./install.sh --auto       # non-interactive: apply the config if present, else write the base template (--suggest for smart defaults)
-./install.sh --config-ui  # also mount the visual configurator (can be combined with --auto)
-./install.sh --dry-run    # preview what would be generated; writes nothing
-./install.sh --help       # all flags
+git clone https://github.com/lifangjin/dsh-paoding.git
+dsh plugin --profile web add link:"$PWD/dsh-paoding"
 ```
 
-After installing, **restart DSH (`dsh web`) or open a new session** and pick "编排模式 (Orchestrator)" in the preset selector; to make it the default, choose it in Settings → Agent Presets. Already have a `dsh-paoding.config.yml`? Re-running any entry point applies your config file instead of overwriting it. Uninstalling means deleting the `~/.dsh/.agent-presets/orchestrator` directory (npx/npm installs also put a copy at `~/.dsh/dsh-paoding`, which you remove as well). Full steps and troubleshooting are in the [installation guide](docs/installation_en.md).
+Upgrades go through the panel's Upgrade button (equivalent to `dsh plugin update dsh-paoding`). Full steps, upgrading, and troubleshooting are in the [installation guide](docs/installation_en.md).
 
 ## How It Works in Practice
 
@@ -75,20 +70,20 @@ While a helper runs, the main agent can send follow-ups, check progress, or stop
 
 ## Configuration
 
-All preferences live in `~/.dsh/dsh-paoding.config.yml`: role add/remove/tweak, skill assignment, per-role models, the main agent's tools and skills… Edit it, re-run `./install.sh --auto`, and the preset syncs. It is regenerated from "static source + config" every time, so no manual patches pile up. The full key reference is in the [configuration guide](docs/configuration_en.md); the rationale and the cost ledger are in the [architecture guide](docs/architecture_en.md).
+All preferences live in `~/.dsh/dsh-paoding.config.yml`: role add/remove/tweak, skill assignment, per-role models, per-role session modes (one-shot / continuable), the main agent's tools and skills… Edit it, open the 庖丁配置 (Paoding Config) entry at the bottom of the sidebar, and hit Save & Apply — the preset syncs. It is regenerated from "static source + config" every time, so no manual patches pile up. The full key reference is in the [configuration guide](docs/configuration_en.md); the rationale and the cost ledger are in the [architecture guide](docs/architecture_en.md).
 
 ## Documentation
 
 | 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) | One-command install with npx, the official `dsh plugin` channel for the config UI, prerequisites, the six wizard stages, CLI flags, host patch detection, applying/upgrading/uninstalling, mounting the config UI, troubleshooting. |
+| [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. |
 | [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. |
+| [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. |
 
 ## Contributing
 
-Issues and PRs are welcome: report problems, request new roles, or point out where the docs and the implementation disagree. Before contributing, read the [architecture](docs/architecture_en.md) and [configuration](docs/configuration_en.md) guides; when a document and the code conflict, the source of truth is `presets/orchestrator/` and `tools/install.mjs`.
+Issues and PRs are welcome: report problems, request new roles, or point out where the docs and the implementation disagree. Before contributing, read the [architecture](docs/architecture_en.md) and [configuration](docs/configuration_en.md) guides; when a document and the code conflict, the source of truth is `presets/orchestrator/` and `tools/`.
 
 ## License
 

package/bin/dsh-paoding.mjs

@@ -1,12 +1,74 @@
 #!/usr/bin/env node
-/**
- * npx 一键安装入口（package.json bin.dsh-paoding）。经 .bin 符号链接运行时
- * import.meta.url 与 argv[1] 比对会失效，故不复用 tools/install.mjs 的直接运行
- * 守卫，而是直接调 lib/cli.mjs 的 main() 并注入 bin 默认值：快速安装 = 非交互
- * （--auto）+ 挂载配置 UI（--config-ui）；用户显式旗标（--wizard / --no-ui /
- * --suggest 等）优先。
- */
-import { main } from '../tools/lib/cli.mjs'
-
-const exitCode = await main({ bin: true, argv: process.argv.slice(2) })
-process.exit(exitCode)
+// npx dsh-paoding 的薄委托入口：本身零安装逻辑，只把安装动作转交 `dsh plugin add`。
+// 为什么不在这里复刻挂载：唯一挂载通道在 dsh host 侧（pnpm 装包 + bundle patch），
+// 复刻一份就是第二条会漂移的路径——旧版多通道（symlink/稳定载荷）的清理成本是前车之鉴。
+// 幂等：pnpm 对已装同版本的包是 no-op，重复执行本入口安全。
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import os from 'node:os';
+// profile 名白名单与 tools/lib/cli.mjs 共用同一份常量（抽在 util 防两处漂移）。
+import { PROFILE_NAME_RE } from '../tools/lib/util.mjs';
+
+const REFUSE =
+  '本入口是 dsh plugin 的快捷方式，完整功能见 dsh plugin --help / 侧栏底部「庖丁配置」入口';
+
+const usage = `dsh-paoding 安装快捷方式（等价于 dsh plugin --profile <name> add dsh-paoding@<version>）
+
+用法：npx dsh-paoding@latest [--profile <name>]
+
+选项：
+  --profile <name>  插件装入的 profile，默认 web（dsh web 的默认 profile）
+  --help            显示本帮助
+  --version         显示包版本
+
+${REFUSE}`;
+
+// 版本读自身包根 package.json 而非 latest：npx 拉到哪个版本就装哪个版本，两边才必然一致；
+// 写 latest 会让 host 再解析一次 registry，可能装出另一个版本。
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+const argv = process.argv.slice(2);
+let profile;
+for (let i = 0; i < argv.length; i++) {
+  const arg = argv[i];
+  if (arg === '--help') { console.log(usage); process.exit(0); }
+  if (arg === '--version') { console.log(version); process.exit(0); }
+  if (arg === '--profile' || arg.startsWith('--profile=')) {
+    profile = arg.includes('=') ? arg.slice('--profile='.length) : argv[++i];
+    // 只收常规 profile 名（PROFILE_NAME_RE，与 tools/lib/cli.mjs 同一份常量）：
+    // win32 经 shell 拼接命令行，在源头排除空格与元字符
+    if (!profile || !PROFILE_NAME_RE.test(profile)) {
+      console.error(`无效的 --profile 值：${profile ?? '(缺值)'}\n${REFUSE}`);
+      process.exit(2);
+    }
+    continue;
+  }
+  console.error(`不认识的参数：${arg}\n${REFUSE}`);
+  process.exit(2);
+}
+
+// cwd 用临时目录：安装动作不该在用户当前目录留任何副作用。
+// win32 的 dsh 是 .cmd shim，必须借 shell 拉起（Node 直接 spawn .cmd 会 EINVAL）。
+const child = spawn(process.platform === 'win32' ? 'dsh.cmd' : 'dsh',
+  ['plugin', '--profile', profile ?? 'web', 'add', `dsh-paoding@${version}`], {
+    stdio: 'inherit', // pnpm 下载输出直接进终端；下载时长不定，不设超时
+    cwd: os.tmpdir(),
+    shell: process.platform === 'win32',
+  });
+
+child.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    console.error('未找到 dsh 命令——本入口依赖已安装的 DSH host，请先安装 dsh 再用，或直接阅读文档安装说明。');
+  } else {
+    console.error(`dsh 启动失败：${err.message}`);
+  }
+  process.exit(1);
+});
+
+child.on('close', (code) => {
+  if (code === 0) {
+    console.log(`已通过插件通道安装到 profile ${profile ?? 'web'}。`);
+    console.log('重启 DSH 后生效——preset 会在启动时自动生成，面板入口在左侧栏底部（设置行上方）的「庖丁配置」入口。');
+  }
+  process.exitCode = code ?? 1; // 子进程退出码原样透传，别吞掉 dsh/pnpm 的失败信号
+});

package/docs/architecture.md

@@ -31,11 +31,10 @@ dsh-paoding（中文品牌「庖丁」，取庖丁解牛之意）是 DSH（DeepS
 | 维度 | 单体模式（默认） | 编排模式（本 preset） |
 |---|---|---|
 | 职责 | 一个 agent 承担全部任务 | 主 agent 拆任务与集成，角色子 agent 各干一摊 |
-| 开销 | 每请求固定承载 ~16.2k tokens 工具定义 | 主 agent ~5.5k；角色工具面 ~3.0k–3.7k，仅委派时发生 |
+| 开销 | 每请求固定承载 ~16.2k tokens 工具定义 | 主 agent ~5.5k；角色工具面 ~3.0k–3.8k，仅委派时发生 |
 | 上下文 | 每次搜索 dump、每轮设计稿、每段 diff 都累积进主上下文 | worker 上下文小而专、用完即弃，主 agent 只收摘要 |
 
-组合的静态源是 `presets/orchestrator/agent.cordis.yml`（叠加在 DSH builtin `standard` preset 全量组合
-之上，见「原理：对应 DSH 原生机制」一节），运行时由 `restrict.mjs` 裁剪主 agent 工具面。
+组合的静态源是 `presets/orchestrator/agent.cordis.yml`（原样包含 DSH builtin `standard` preset 的全部组合行——同一组合内复制，而非运行时继承，见「原理：对应 DSH 原生机制」之机制①），运行时由 `restrict.mjs` 裁剪主 agent 工具面。
 四个角色委派实例的 ID 为 `delegation-search-external` / `delegation-design` /
 `delegation-implement` / `delegation-search-internal-deep`，均在组合的 delegation 组内；该组还挂有
 通用委派工具 `subagent` / `subagent_fork` / `workflow` / `ralph`（主 agent 白名单不包含它们，角色委派
@@ -58,14 +57,15 @@ dsh-paoding（中文品牌「庖丁」，取庖丁解牛之意）是 DSH（DeepS
    （外部调研·按需）  （设计·按需）     （实现·按需）     （全仓深搜·按需）
         │               │               │               │
         ▼               ▼               ▼               ▼
-   web_search       read/read_image  read/write/edit  glob/grep/read/
-   mcp__tavily__*   glob/grep/bash/  glob/grep/bash/  read_image/bash/
-   (5 个)           skill/write/     skill/web_search ask_user_question/
-   glob/grep/read   edit/ask_user_   ask_user_question todo_write/
-   ask_user_        question/        todo_write/      job_output/job_list/
-   question         todo_write/      job_output/      job_kill
-   （无 write/edit） job_output/      job_list/job_kill/   （只读、不改文件、
-                    job_list/        get_goal/          无网络）
+   web_search       read/read_image  read/read_image  glob/grep/read/
+   mcp__tavily__*   glob/grep/bash/  write/edit/      read_image/bash/
+   (5 个)           skill/           glob/grep/bash/  ask_user_question/
+   glob/grep/read   web_search       skill/web_search todo_write/
+   ask_user_        ask_user_        ask_user_question job_output/job_list/
+   question         question/        todo_write/      job_kill
+   （无 write/edit） todo_write/        job_output/      （只读、不改文件、
+                    job_output/      job_list/job_kill/ 无网络）
+                    job_list/        get_goal/
                     job_kill         create_goal/update_goal
 ```
 
@@ -79,18 +79,18 @@ dsh-paoding（中文品牌「庖丁」，取庖丁解牛之意）是 DSH（DeepS
 | 单体（现状，未裁剪） | 60 工具全量 | **~16.2k** | 每请求固定注入 |
 | 编排主 agent | 21 项白名单（∩ 注册面） | **~5.5k** | ↓66%；内部搜索零委派延迟 |
 | search_external 子 agent | 10 项 allow | ~3.0k | 仅实际联网调研时才产生 |
-| design 子 agent | 13 项 allow | ~3.2k | 仅实际委派设计时才产生 |
-| implement 子 agent | 16 项 allow | ~3.7k | 仅实际委派实现时才产生 |
+| design 子 agent | 12 项 allow | ~3.3k | 仅实际委派设计时才产生 |
+| implement 子 agent | 17 项 allow | ~3.8k | 仅实际委派实现时才产生 |
 | search_internal_deep 子 agent | 10 项 allow | 未单独估算 | 仅实际委派全仓深搜时才产生 |
 
-注：表中角色工具数按 `agent.cordis.yml` 实际 allow 条目数计（design 13 / implement 16），README 旧表
+注：表中角色工具数按 `agent.cordis.yml` 实际 allow 条目数计（design 12 / implement 17），README 旧表
 中的 14 / 17 与白名单 22 已过时。
 
 **真正的收益是上下文隔离，而不是省下的几千 token 本身**：
 
 - 单体 agent 的上下文会累积每一次搜索 dump、每一轮设计稿、每一段 diff——即使某工具本请求没用上，
   它过往的产物仍占着窗口；
-- 编排架构里每个 worker 上下文小而专（各自只带本角色的工具与产物），角色默认 one-shot、用完即弃；
+- 编排架构里每个 worker 上下文小而专（各自只带本角色的工具与产物），角色默认 one-shot、用完即弃（会话模式按角色可配——确需多轮打磨的角色可切 continuable，见[编排](orchestration.md)）；
   主 agent 只接收结构化摘要并集成，不会把子 agent 的完整上下文倒进自己的窗口；
 - 因而主 agent 的窗口大小与"本轮派了多少活"解耦，长会话的 token 水位主要由编排者自身的
   摘要与决策构成（配合压缩治理，见「Token 治理（性能调优）」一节）。
@@ -135,24 +135,27 @@ dsh-paoding（中文品牌「庖丁」，取庖丁解牛之意）是 DSH（DeepS
 [docs/orchestration.md](orchestration.md)。
 
 内置四角色只是**出厂分工**：任何「工具 + 技能」组合都能以同一机制成为新委派工具——在配置文件 `roles`
-键写一个 toolName（或经向导 / 配置 UI 新建），安装器生成 `delegation-<toolName>` 块、把 toolName
+键写一个 toolName（或在庖丁配置面板新建），生成器生成 `delegation-<toolName>` 块、把 toolName
 注入主 agent 白名单，并把角色 persona 首行职责句自动追加为主 agent persona 的委派行（tools 为空的
-角色应用时会被拒绝安装），详见 [docs/configuration.md](configuration.md) 第 6 节；自定义角色同样支持 `model` / `provider` 专用模型（与内置角色同一子键、同一生成机制，见 2.5）。例如建一个装配 `html-ppt`
+角色应用时会被拒绝安装），详见 [docs/configuration.md](configuration.md) 第 6 节；自定义角色同样支持 `model` / `provider` 专用模型与 `background_mode` 会话模式（与内置角色同一子键、同一生成机制——生成器为自定义角色块恒写 `backgroundMode` 行，`continuable` 同样生效，见 2.5 / 2.6）。例如建一个装配 `html-ppt`
 技能的 `ppt` agent，做 PPT 这类任务就有了专属子 agent。
 
 | 委派工具 | 实例 ID | persona 一句话职责 | 加载成本 |
 |---|---|---|---|
 | `search_external` | `delegation-search-external` | 只做联网调研（web_search + tavily），绝不改文件；返回结构化研究摘要（发现、来源、待答问题） | ~3.0k，仅委派时 |
-| `design` | `delegation-design` | 产出 UI/UX 设计、线框与前端 spec，可用 skill 工具加载设计技能（frontend-design、html-ppt）；先读参考再交付 spec，不写最终代码 | ~3.2k，仅委派时 |
-| `implement` | `delegation-implement` | 写与改代码：先读上下文 → 精准修改 → 验证（build/test/grep）；不改架构 | ~3.7k，仅委派时 |
+| `design` | `delegation-design` | 产出 UI/UX 设计、线框与前端 spec，可用 skill 工具加载设计技能（frontend-design、html-ppt）；先读参考再交付 spec，不写最终代码 | ~3.3k，仅委派时 |
+| `implement` | `delegation-implement` | 写与改代码：先读上下文 → 精准修改 → 验证（build/test/grep）；不改架构 | ~3.8k，仅委派时 |
 | `search_internal_deep` | `delegation-search-internal-deep` | 只做仓库探索：不改文件、不联网；处理主 agent 上下文装不下的任务（全仓 grep dump、超页大文件通读、跨目录符号/定义追踪），只回浓缩摘要 | 未单独估算，仅委派时 |
 
-上表是出厂默认形态，配置层可再裁剪与定制（详见 [docs/configuration.md](configuration.md)）：`search_external` / `design` / `implement` 三个可经 `roles_remove` 整条删除（2.3，`search_internal_deep` 删不掉）；内置角色可配显示名 `roles.<toolName>.name`，只替换该角色 persona 首行身份句主语（2.4）；可配专用模型 `roles.<toolName>.model` / `.provider`，生成器在委派块注入 `agentOptions`，不配则跟随主 agent（2.5）；主 agent 可经 `main_agent_name` 改名，一改两处（第 5 节）。
+上表是出厂默认形态，配置层可再裁剪与定制（详见 [docs/configuration.md](configuration.md)）：`search_external` / `design` / `implement` 三个可经 `roles_remove` 整条删除（2.3，`search_internal_deep` 删不掉）；内置角色可配显示名 `roles.<toolName>.name`，只替换该角色 persona 首行身份句主语（2.4）；可配专用模型 `roles.<toolName>.model` / `.provider`，生成器在委派块注入 `agentOptions`，不配则跟随主 agent（2.5）；可配会话模式 `roles.<toolName>.background_mode`，配成 `continuable` 时委派块注入 `backgroundMode` 行、子会话跨轮保留——内置角色与自定义角色同语义，生成器为自定义角色块恒写 `backgroundMode` 行（2.6）；主 agent 的 persona 身份行不可改名（编排主 agent 的身份不属于可配置项），另有 `main_agent_display_name` 只改 preset 显示名、不动 persona 身份行（见 configuration.md 第 5 节）。
 
 ### 角色 toolFilter.allow 明细
 
-以下 allow 列表逐字抄录自 `agent.cordis.yml`（安装期生成器会按运行时检测到的 host 工具对列表做
-「配置/静态意图 ∩ 实际检测工具」重写，见 [docs/configuration.md](configuration.md)）。
+以下 allow 列表逐字抄录自 `agent.cordis.yml`（安装期生成器按「preset 自带工具面 ∪ 运行时检测库存」
+白名单对账重写的只是 `search_external` / `design` / `implement` 三个可配角色的 allow——两头都不占的
+名字被剔除并在「预览生成」的 removed 列表给出原因；`search_internal_deep` 为静态委派，其 allow 列表
+**不做**库存对账：手写进去、两头都不占的名字不会被剔除，会静默落盘、运行时以 unknown tools 拒创建
+（与下方该角色的 codegraph 注同一口径），见 [docs/configuration.md](configuration.md)）。
 
 **`search_external`（外部调研，10 项）**
 
@@ -162,21 +165,21 @@ dsh-paoding（中文品牌「庖丁」，取庖丁解牛之意）是 DSH（DeepS
 | toolFilter.allow | `web_search`、`mcp__tavily__tavily_search`、`mcp__tavily__tavily_crawl`、`mcp__tavily__tavily_extract`、`mcp__tavily__tavily_map`、`mcp__tavily__tavily_research`、`glob`、`grep`、`read`、`ask_user_question` |
 | 加载成本 | ~3.0k tokens，仅实际联网调研时发生 |
 
-**`design`（设计，13 项）**
+**`design`（设计，12 项）**
 
 | 字段 | 值 |
 |---|---|
 | persona 职责 | 产出 UI/UX 设计、线框与前端 spec；经 skill 工具加载设计技能（frontend-design、html-ppt）；先读参考再交付 spec，不实现最终代码 |
-| toolFilter.allow | `read`、`read_image`、`glob`、`grep`、`bash`、`skill`、`write`、`edit`、`ask_user_question`、`todo_write`、`job_output`、`job_list`、`job_kill` |
-| 加载成本 | ~3.2k tokens，仅实际委派设计时发生 |
+| toolFilter.allow | `read`、`read_image`、`glob`、`grep`、`bash`、`skill`、`web_search`、`ask_user_question`、`todo_write`、`job_output`、`job_list`、`job_kill` |
+| 加载成本 | ~3.3k tokens，仅实际委派设计时发生 |
 
-**`implement`（实现，16 项）**
+**`implement`（实现，17 项）**
 
 | 字段 | 值 |
 |---|---|
 | persona 职责 | 写与改代码：先读上下文 → 精准修改 → 验证（build/test/grep）并汇报改动与验证方式；不做架构重设计 |
-| toolFilter.allow | `read`、`write`、`edit`、`glob`、`grep`、`bash`、`skill`、`web_search`、`ask_user_question`、`todo_write`、`job_output`、`job_list`、`job_kill`、`get_goal`、`create_goal`、`update_goal` |
-| 加载成本 | ~3.7k tokens，仅实际委派实现时发生 |
+| toolFilter.allow | `read`、`read_image`、`write`、`edit`、`glob`、`grep`、`bash`、`skill`、`web_search`、`ask_user_question`、`todo_write`、`job_output`、`job_list`、`job_kill`、`get_goal`、`create_goal`、`update_goal` |
+| 加载成本 | ~3.8k tokens，仅实际委派实现时发生 |
 
 **`search_internal_deep`（全仓深搜，10 项）**
 
@@ -241,9 +244,13 @@ SOP（按 stop reason 分流：error 重委派一次 / max-tokens 拆小 / refus
 重试 / 产出差带具体缺失点补做；同一任务失败两次即停止，向用户报告；重委派必须携带上次集成摘要），
 详见 [docs/orchestration.md](orchestration.md)。
 
-**⑦ 热插拔 = preset 是静态目录。** 安装、卸载、修改都是文件操作：生成器把静态源复制/改写为
-`$DSH_HOME/.agent-presets/orchestrator`，编辑 YAML / mjs、重跑生成器、重启 host 或新建会话即生效；
-卸载即删目录。DSH 源码零改动，preset 可整体移除、不残留。
+**⑦ 热插拔 = preset 是静态目录 + 插件通道挂载。** 插件本体经 `dsh plugin add`（pnpm + 包内 bundle patch）装入 profile，侧栏面板即挂即卸；编排预设本身是一个静态目录——生成器把静态源复制/改写为
+`$DSH_HOME/.agent-presets/orchestrator`，编辑 YAML / mjs、面板「保存并应用」重新生成、重启 host 或新建会话即生效；
+卸载 = `dsh plugin remove` 加删目录（见[安装](installation.md)）。DSH 源码零改动，preset 可整体移除、不残留。
+
+## Web 配置页 client bundle：源头多文件，产物单文件
+
+配置页的前端代码按分区存放在 `plugins/paoding-config-ui/src/client/`，是十几个带两位序号前缀的片段文件，文件名顺序即拼接顺序；`scripts/build-client.mjs` 把它们按序原样相连，写出 `plugins/paoding-config-ui/lib/client.js`——不转译、不压缩、不插入任何分隔符，产物与片段逐字节对得上。DSH 平台对每个插件包只认 `exports["./client"]` 这一个入口，所以发布物必须仍是这一个单文件。要改前端就改片段，跑一次拼接脚本重新生成产物；直接手改 `lib/client.js` 会被 `prepublishOnly` 钩子里的 `--check` 当场拦下。
 
 ## Token 治理（性能调优）
 
@@ -269,7 +276,7 @@ grep inline cap 与对照同设计）后，根因锁定为：**默认压缩从
 | 0.45（本 preset 已落地） | 117,965 tokens | ~80K | 保留 ~16% 尾部 ≈42K + 摘要 checkpoint |
 | 0.35（可选更激进） | ~92K tokens | ~67K | 更省 token，摘要更频繁 |
 
-改阈值后重跑 `./install.sh --auto` 应用。同组合内另有配套组件：
+改阈值后在「庖丁配置」点「保存并应用」重新生成。同组合内另有配套组件：
 
 - `tool-result-pruner`：超长工具结果按 `thresholdChars: 8192 / headChars: 4096 / tailChars: 1024`
   截头留尾，防止单条巨型输出撑大窗口；
@@ -286,7 +293,7 @@ grep inline cap 与对照同设计）后，根因锁定为：**默认压缩从
 - **`toolFilter.allow` 是精确名匹配，不支持 glob**：tavily 的 5 个工具必须逐个写全
   （`mcp__tavily__tavily_search/crawl/extract/map/research`）。
 - **主 agent 白名单里未挂载的工具不会报错**：瀑布过滤只在已解析的 `assembly.tools` 里按名匹配，
-  某工具（如被注释的 MCP）不在其中就只是不出现，安装与运行都静默通过——配置意图与实际挂载
-  靠安装期检测（`install.sh --auto` / `--dry-run`）对齐，改动 host patch 后需重跑。
+  某工具（如被注释的 MCP）不在其中就只是不出现，生成与运行都静默通过——配置意图与实际挂载
+  靠生成期检测对齐，改动 host patch 后在「庖丁配置」点「保存并应用」同步即可（「预览生成」可先看清单）。
 - **超大仓库全量探索场景应委派 `search_internal_deep` 而非主 agent 自做**：全仓 grep dump、大文件
   通读反复灌满主上下文，正是该角色的隔离价值所在（只读、无网络、只回浓缩摘要）。