dsh-paoding 0.2.2 → 0.3.0

package/docs/architecture_en.md

@@ -36,7 +36,7 @@ The essential differences from monolithic mode:
 | Dimension | Monolithic mode (default) | Orchestrator mode (this preset) |
 |---|---|---|
 | Responsibility | One agent does everything | Main agent decomposes and integrates; role sub-agents each do one job |
-| Cost | ~16.2k tokens tool tax paid on every request | Main agent ~5.5k; role surfaces ~3.0k–3.7k, paid only when delegated |
+| Cost | ~16.2k tokens tool tax paid on every request | Main agent ~5.5k; role surfaces ~3.0k–3.8k, paid only when delegated |
 | Context | Every search dump, design draft and diff accumulates in the main context | Worker contexts are small and specialized and discarded after use; the main agent receives only summaries |
 
 The static source of the composition is `presets/orchestrator/agent.cordis.yml`, layered on top of DSH's
@@ -68,16 +68,17 @@ allow lists are in the "Roles & tool surfaces" section below):
       (on demand)            (on demand)      (on demand)        (on demand)            
             │                   │                   │                   │               
             ▼                   ▼                   ▼                   ▼               
-    web_search           read/read_image      read/write/edit      glob/grep/read       
-    mcp__tavily__*       glob/grep/bash       glob/grep/bash       read_image/bash      
-    (5 tools)            skill/write/edit     skill/web_search     ask_user_question    
-    glob/grep/read       ask_user_question    ask_user_question    todo_write           
-    ask_user_question    todo_write           todo_write           job_output           
-    (no write/edit)      job_output           job_output           job_list             
-                         job_list             job_list/job_kill    job_kill             
-                         job_kill             get_goal             (read-only; no       
-                                              create_goal          file writes,         
-                                              update_goal          no network)          
+    web_search           read/read_image      read/read_image      glob/grep/read
+    mcp__tavily__*       glob/grep/bash       write/edit           read_image/bash
+    (5 tools)            skill/web_search     glob/grep/bash       ask_user_question
+    glob/grep/read       ask_user_question    skill/web_search     todo_write
+    ask_user_question    todo_write           ask_user_question    job_output
+    (no write/edit)      job_output           todo_write           job_list
+                         job_list             job_output           job_kill
+                         job_kill             job_list/job_kill    (read-only; no
+                                              get_goal             file writes,
+                                              create_goal          no network)
+                                              update_goal 
 ```
 
 In the diagram:
@@ -89,8 +90,9 @@ In the diagram:
   job_kill);
 - Four arrows fan out to the **role sub-agents**, each created on demand (cold path). search_external
   carries web_search, the five `mcp__tavily__*` tools, plus glob/grep/read and ask_user_question, with no
-  write/edit; design carries read/read_image/glob/grep/bash/skill/write/edit plus coordination tools;
-  implement carries read/write/edit/glob/grep/bash/skill/web_search plus coordination and goal tools;
+  write/edit; design carries read/read_image/glob/grep/bash/skill/web_search plus coordination tools;
+  implement carries read/read_image/write/edit/glob/grep/bash/skill/web_search plus coordination and
+  goal tools;
   search_internal_deep carries the full read-only internal-search surface (glob/grep/read/read_image/bash
   plus ask_user_question and job tools) — no file modification, no network.
 
@@ -105,19 +107,21 @@ measured calibration; figures are order-of-magnitude estimates):
 | Monolithic (status quo, untrimmed) | All 60 tools | **~16.2k** | Paid in full on every request |
 | Orchestrator main agent | 21-entry whitelist (∩ registry) | **~5.5k** | ↓66%; zero delegation latency for internal search |
 | search_external sub-agent | 10 allowed entries | ~3.0k | Paid only when web research actually runs |
-| design sub-agent | 13 allowed entries | ~3.2k | Paid only when a design task is delegated |
-| implement sub-agent | 16 allowed entries | ~3.7k | Paid only when an implementation task is delegated |
+| design sub-agent | 12 allowed entries | ~3.3k | Paid only when a design task is delegated |
+| implement sub-agent | 17 allowed entries | ~3.8k | Paid only when an implementation task is delegated |
 | search_internal_deep sub-agent | 10 allowed entries | not separately estimated | Paid only when a deep repo search is delegated |
 
-Note: role tool counts above follow the actual `allow` entries in `agent.cordis.yml` (design 13 / implement
-16); the old README figures of 14 / 17 and a 22-entry whitelist are outdated.
+Note: role tool counts above follow the actual `allow` entries in `agent.cordis.yml` (design 12 / implement
+17); the old README figures of 14 / 17 and a 22-entry whitelist are outdated.
 
 **The real win is context isolation, not the few thousand tokens saved per se**:
 
 - A monolithic agent's context accumulates every search dump, every design draft and every diff — even when a
   tool is unused in the current request, its past outputs still occupy the window;
 - In the orchestrator architecture every worker keeps a small, specialized context (its own role tools and
-  outputs only); roles are one-shot by default and discarded after use. The main agent receives only
+  outputs only); roles are one-shot by default and discarded after use (the session mode is per-role
+  configurable — a role that genuinely needs multi-round polishing can switch to continuable, see
+  [Orchestration](orchestration_en.md)). The main agent receives only
   structured summaries and integrates them — it never pours a sub-agent's full context into its own window;
 - Consequently the main agent's window size is decoupled from "how much work this round delegated"; in long
   sessions the token level is dominated by the orchestrator's own summaries and decisions (combined with
@@ -168,7 +172,7 @@ persona and the delegation-failure SOP live in [docs/orchestration_en.md](orches
 
 The four built-in roles are just the factory division of labor: through the same mechanism, any combination
 of tools and skills becomes a new delegation tool — write a toolName under the config `roles` key (or create
-it in the wizard / config UI), the installer generates a `delegation-<toolName>` block, injects the
+it in the 庖丁配置 panel), the generator produces a `delegation-<toolName>` block, injects the
 toolName into the main-agent allow list, and appends the role's persona first line (its duty sentence)
 to the main-agent persona as a delegation row (a role with no tools is rejected at apply time); see
 section 6 of [docs/configuration_en.md](configuration_en.md).
@@ -179,8 +183,8 @@ For example, a `ppt` agent carrying the `html-ppt` skill gives slide-making its
 | Delegation tool | Instance ID | Persona in one sentence | Load cost |
 |---|---|---|---|
 | `search_external` | `delegation-search-external` | Web research only (web_search + tavily), never modifies files; returns a structured research summary (findings, sources, open questions) | ~3.0k, only when delegated |
-| `design` | `delegation-design` | Produces UI/UX designs, wireframes and frontend specs; may load design skills (frontend-design, html-ppt) via the skill tool; reads reference material first, delivers a spec, does not implement final code | ~3.2k, only when delegated |
-| `implement` | `delegation-implement` | Writes and edits code: read surrounding context → surgical change → verify (build/test/grep); does not redesign architecture | ~3.7k, only when delegated |
+| `design` | `delegation-design` | Produces UI/UX designs, wireframes and frontend specs; may load design skills (frontend-design, html-ppt) via the skill tool; reads reference material first, delivers a spec, does not implement final code | ~3.3k, only when delegated |
+| `implement` | `delegation-implement` | Writes and edits code: read surrounding context → surgical change → verify (build/test/grep); does not redesign architecture | ~3.8k, only when delegated |
 | `search_internal_deep` | `delegation-search-internal-deep` | Repository exploration only: never modifies files, never uses the network; handles tasks too heavy for the main agent's context (whole-repo grep dumps, full-file reads beyond a page, cross-directory symbol/definition tracking); returns condensed summaries only | not separately estimated, only when delegated |
 
 The table above is the factory default; the configuration layer can trim and customize it (see
@@ -188,13 +192,18 @@ The table above is the factory default; the configuration layer can trim and cus
 deleted wholesale via `roles_remove` (2.3; `search_internal_deep` cannot); a built-in role can carry a display
 name `roles.<toolName>.name`, which rewrites only the subject of its persona identity sentence (2.4); it can
 also be pinned to a dedicated model `roles.<toolName>.model` / `.provider`, injected by the generator as
-`agentOptions` in the delegation block, defaulting to following the main agent (2.5); and the main agent itself
-can be renamed via `main_agent_name` — one key, two places (section 5).
+`agentOptions` in the delegation block, defaulting to following the main agent (2.5); and it can carry a session
+mode `roles.<toolName>.background_mode` — configured as `continuable`, the delegation block gets a
+`backgroundMode` row and the child conversation is kept across turns (2.6); the main agent's persona
+identity line cannot be renamed (the orchestrator's identity is not a configurable item); `main_agent_display_name`
+(see configuration_en.md section 5) changes only the preset display name and leaves the persona
+identity line untouched.
 
 ### Per-role toolFilter.allow detail
 
 The allow lists below are transcribed verbatim from `agent.cordis.yml` (at install time the generator
-rewrites each list as "config/static intent ∩ runtime-detected host tools", see
+rewrites each list against the whitelist "preset's own tool face ∪ runtime detection inventory"; names in
+neither are dropped with a stated reason, see
 [docs/configuration_en.md](configuration_en.md)).
 
 **`search_external` (external research, 10 entries)**
@@ -205,21 +214,21 @@ rewrites each list as "config/static intent ∩ runtime-detected host tools", se
 | 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` |
 | Load cost | ~3.0k tokens, incurred only when web research actually runs |
 
-**`design` (design, 13 entries)**
+**`design` (design, 12 entries)**
 
 | Field | Value |
 |---|---|
 | Persona job | Produces UI/UX designs, wireframes and frontend specs; loads design skills (frontend-design, html-ppt) via the skill tool; reads reference material first, then delivers a spec; does not implement final code |
-| toolFilter.allow | `read`, `read_image`, `glob`, `grep`, `bash`, `skill`, `write`, `edit`, `ask_user_question`, `todo_write`, `job_output`, `job_list`, `job_kill` |
-| Load cost | ~3.2k tokens, incurred only when a design task is delegated |
+| toolFilter.allow | `read`, `read_image`, `glob`, `grep`, `bash`, `skill`, `web_search`, `ask_user_question`, `todo_write`, `job_output`, `job_list`, `job_kill` |
+| Load cost | ~3.3k tokens, incurred only when a design task is delegated |
 
-**`implement` (implementation, 16 entries)**
+**`implement` (implementation, 17 entries)**
 
 | Field | Value |
 |---|---|
 | Persona job | Writes and edits code: read surrounding context first → surgical changes → verify (build/test/grep), reporting what changed and how it was verified; does not redesign architecture |
-| 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` |
-| Load cost | ~3.7k tokens, incurred only when an implementation task is delegated |
+| 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` |
+| Load cost | ~3.8k tokens, incurred only when an implementation task is delegated |
 
 **`search_internal_deep` (whole-repo deep search, 10 entries)**
 
@@ -298,11 +307,17 @@ stop reason: `error` → re-delegate once; `max-tokens` → split the task; `ref
 failures of the same task, stop and report to the user; every re-delegation must carry the previous
 integration summary) — see [docs/orchestration_en.md](orchestration_en.md).
 
-**⑦ Hot-swap means presets are static directories.** Install, uninstall and modification are plain file
-operations: the generator copies/rewrites the static sources into `$DSH_HOME/.agent-presets/orchestrator`;
-editing the YAML / mjs, re-running the generator, and restarting the host or opening a new session takes
-effect. Uninstalling means deleting the directory. No DSH source changes; the preset leaves nothing behind
-when removed.
+**⑦ Hot-swap means a static preset directory plus plugin-channel mounting.** The plugin itself is installed
+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
+remove` plus deleting the directory (see [Installation](installation_en.md)). No DSH source changes; the
+preset leaves nothing behind when removed.
+
+## Web config panel client bundle: multi-file sources, single-file artifact
+
+The panel's front-end code lives in `plugins/paoding-config-ui/src/client/` as a dozen-odd fragment files whose two-digit filename prefixes fix the concatenation order; `scripts/build-client.mjs` concatenates them verbatim into `plugins/paoding-config-ui/lib/client.js` — no transpiling, no minifying, no inserted separators, so the artifact matches the fragments byte for byte. The DSH platform serves exactly one entry per package (`exports["./client"]`), which is why the published artifact stays that single file. Edit the fragments, then rerun the build script to regenerate the artifact; hand-editing `lib/client.js` is caught by the `--check` mode wired into the `prepublishOnly` hook.
 
 ## Performance: token governance
 
@@ -334,7 +349,7 @@ summarizing too frequently.
 | 0.45 (landed in this preset) | 117,965 tokens | ~80K | ~16% tail ≈42K + summary checkpoint |
 | 0.35 (optional, more aggressive) | ~92K tokens | ~67K | Saves more tokens, summarizes more often |
 
-After changing the threshold, re-run `./install.sh --auto` to apply. Companion components in the same
+After changing the threshold, hit Save & Apply in 庖丁配置 to regenerate. Companion components in the same
 composition:
 
 - `tool-result-pruner`: oversized tool results are trimmed with `thresholdChars: 8192 / headChars: 4096 /
@@ -356,8 +371,9 @@ composition:
   listed in full (`mcp__tavily__tavily_search/crawl/extract/map/research`).
 - **Tools absent from the main-agent whitelist raise no error**: the waterfall filter only matches by name
   against the resolved `assembly.tools`, so a tool that is not mounted (e.g. a commented-out MCP) simply
-  never appears — install and runtime both pass silently. Config intent and actual mounts are reconciled by
-  install-time detection (`install.sh --auto` / `--dry-run`); re-run it after changing host patches.
+  never appears — generation and runtime both pass silently. Config intent and actual mounts are reconciled
+  by generation-time detection; after changing host patches, hit Save & Apply in 庖丁配置 to sync (Preview
+  shows the list first).
 - **Whole-repo exploration tasks should be delegated to `search_internal_deep` rather than done by the
   main agent**: whole-repo grep dumps and full-file reads that repeatedly flood the main context are
   exactly what that role isolates (read-only, no network, condensed summaries only).

package/docs/configuration.md

@@ -4,27 +4,27 @@
 
 # 配置
 
-dsh-paoding 把「按角色分工的编排 preset」做成**配置驱动**：你手编（或让交互向导 / Web 配置 UI 帮你写）一个 YAML 配置文件，安装器（`tools/install.mjs`，CLI 与配置 UI 共用同一生成管线 `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 + 本配置文件」重新生成：改配置 → 重跑安装 = 幂等同步，不会累积手工补丁。
+配置文件描述的是**声明式意图**。目标文件每次都由「源码 preset + 本配置文件」重新生成：改配置 → 在面板点「保存并应用」= 幂等同步，不会累积手工补丁。
 
 ## 1. 配置文件
 
 ### 1.1 位置与优先级
 
-配置文件默认位置是 `$DSH_HOME/dsh-paoding.config.yml`；`$DSH_HOME` 未设置时默认为 `~/.dsh`。CLI 参数 `--config <file>` 可指定任意其它路径。
+配置文件默认位置是 `$DSH_HOME/dsh-paoding.config.yml`；`$DSH_HOME` 未设置时默认为 `~/.dsh`。环境变量 `DSH_PAODING_CONFIG` 可给面板改路径；仓库内兜底 CLI 的 `--config <file>` 参数也可指定任意其它路径。
+
+改完配置怎么应用（下文「重新应用」均指第一行）：
 
 | 场景 | 行为 |
 |---|---|
-| 交互向导（`./install.sh`） | 检测并分配后，确认时把选择**持久化**到配置文件（默认 `~/.dsh/dsh-paoding.config.yml`，以 `0o600` 权限写入）；向导重启时会以既有配置作为种子值 |
-| `./install.sh --auto` | 非交互应用：有配置文件则应用，没有则用智能默认（≈ 静态 preset 现状，零回归）；改配置后重跑即幂等应用 |
-| `./install.sh --dry-run` | 只打印检测报告与将生成的 allow / persona 变化，不写任何文件（含配置文件）；适合先预览再动手 |
-| `./install.sh --auto --config <file>` | 用指定文件替代默认位置 |
-| Web 配置 UI（设置 → 庖丁配置） | 面板「保存并应用」写入 preset 并把分配保存到配置文件，等价于 `--auto` + 向导保存 |
+| Web 面板（左侧栏「庖丁配置」入口） | **主路径**：打开面板会把既有配置加载为当前值，点「保存并应用」写入 preset 并把分配保存到配置文件（默认 `~/.dsh/dsh-paoding.config.yml`，以 `0o600` 权限写入）。手编过配置文件的话，先开面板再应用即可 |
+| 首装自动化 | 插件启动时发现 preset 缺失或版本标记不符，自动按配置文件应用一次（无配置则写基础模板）——日常无需手动触发 |
+| 兜底 CLI（仅限克隆仓库的开发者） | `node tools/install.mjs --auto`：有配置文件则幂等应用，没有则写基础模板；`--dry-run` 只打印检测报告与将生成的 allow / persona 变化，不写任何文件（含配置文件），适合先预览再动手；`--config <file>` 用指定文件替代默认位置 |
 
-配置文件**存在但解析失败**是硬错误（直接报错退出）；**不存在**则视为无配置（走智能默认或向导）。`profile`、`roles` 等顶层键的语义见下节。
+配置文件**存在但解析失败**是硬错误（直接报错退出）；**不存在**则视为无配置（写基础模板）。`profile`、`roles` 等顶层键的语义见下节。
 
-CLI 参数优先级：`--profile` 显式给出时覆盖配置文件里的 `profile` 键，否则以配置文件为准，再否则默认 `web`。
+兜底 CLI 的参数优先级：`--profile` 显式给出时覆盖配置文件里的 `profile` 键，否则以配置文件为准，再否则默认 `web`。
 
 ### 1.2 顶层键
 
@@ -33,15 +33,16 @@ CLI 参数优先级：`--profile` 显式给出时覆盖配置文件里的 `profi
 | 顶层键 | 类型 | 语义 |
 |---|---|---|
 | `profile` | string | 检测时纳入哪个 profile 的 patch 层（`$DSH_HOME/profiles/<profile>/cordis.patch.yml`）；缺省 `web` |
-| `roles` | map | `toolName` → `{ persona?, name?, tools[], model?, provider? }`。对内置三角色（`search_external` / `design` / `implement`）：覆盖 persona 与 allow 意图，并可配 `name` 显示名（只替换该角色默认 persona 首行身份句的主语，见 2.4）与专用模型（`model` / `provider`，见 2.5）；其它键名 = **自定义角色**：生成全新 `delegation-<toolName>` 块并把 toolName 注入主 agent 的 `config.allow`（详见第 2、6 节） |
+| `roles` | map | `toolName` → `{ persona?, name?, tools[], model?, provider?, background_mode? }`。对内置三角色（`search_external` / `design` / `implement`）：覆盖 persona 与 allow 意图，并可配 `name` 显示名（只替换该角色默认 persona 首行身份句的主语，见 2.4）、专用模型（`model` / `provider`，见 2.5）与会话模式（`background_mode`，见 2.6）；其它键名 = **自定义角色**：生成全新 `delegation-<toolName>` 块并把 toolName 注入主 agent 的 `config.allow`（详见第 2、6 节） |
 | `roles_remove` | string[] | 整条删除的内置角色 toolName 列表（只认 `search_external` / `design` / `implement`，其它名字忽略并告警；缺省 = `[]`）。删除 = 委派行 / 工具面 / 角色 persona / 主 agent 侧委派指引全部不再生成（详见 2.3） |
 | `skills` | map | `skill` → 分配给该技能的角色 toolName 列表；安装时把 `Available skills: …` 引导句写进这些角色 persona 的尾部（详见第 7 节） |
-| `main_agent_extra` | string[] | 追加到主 agent 白名单的工具（host 工具，如 `mcp__codegraph__codegraph_explore`、`memory_search`、`mnemon_*`）；与检测库存求交，未检测到则不注入 |
+| `main_agent_extra` | string[] | 追加到主 agent 白名单的工具（host 工具，如 `mcp__codegraph__codegraph_explore`、`memory_search`、`mnemon_*`）；按「preset 自带工具面 ∪ 检测库存」对账，两头都不占的名字不注入 |
 | `main_agent_remove` | string[] | 从主 agent 白名单裁掉的基础工具（如 goal 工具族、`exit_plan_mode`）；不在当前 allow 的名字警告并跳过；移除结果为空列表直接报错 |
 | `main_agent_skills` | string[] | 主 agent 技能软引导（默认通道）：每技能在 persona 末尾写一行紧凑技能行 + `Read full rules:` 路径 |
 | `main_agent_skills_inline` | string[] | 主 agent 技能硬内联（可选）：选中技能 SKILL.md 全文内联进 persona，每轮固定生效 |
 | `main_agent_persona_extra` | string \| null | 主 agent persona 尾部追加文本。`null` / 缺省 = 用默认常量；`''` = 不追加任何内容；其它字符串 = 覆盖默认 |
-| `main_agent_name` | string \| null | 主 agent 名称（一改两处：部署 preset 显示名与 persona 身份行 `You are the <name> agent powered by the {{model}} model.`）。trim 后 1–60 字符、不可含换行；空 / 缺省 = 保持默认（详见第 5 节） |
+| `main_agent_display_name` | string \| null | 主 agent 显示名，**只改部署 preset 显示名**（GUI 预设选择器里那个名字），不动 persona 身份行。约束：trim 后 1–60 字符、不可含换行；空 / 缺省 = 默认「编排模式 (Orchestrator)」（工作区预设用派生名，详见 5.1） |
+| `workspaces` | map | 工作区目录绝对路径 → 该工作区的专属配置条目，字段与顶层同构（`profile` 除外）；每个条目单独生成一份预设 `orchestrator-<slug>`，与全局预设互不影响（详见第 9 节） |
 
 `roles` 语义细节：
 
@@ -50,6 +51,7 @@ CLI 参数优先级：`--profile` 显式给出时覆盖配置文件里的 `profi
 - `roles.<toolName>.name`：仅对内置三角色生效的可选 `string | null` 显示名（缺省 `null` = 用该角色内置默认身份）。只替换该角色**默认** persona 首行身份句的主语——design 默认 `You are the design agent.`，配 `name: UI 设计` 后为 `You are the UI 设计 agent.`，句子其余文字不动；约束、边界与示例见 2.4。
 - `roles.<toolName>.model`：该角色的专用模型 id（可选 `string`）。配置后，该角色派出的每个子 agent 都固定用这个模型，不再随主 agent 会话当前模型走；缺省 = 不注入 `agentOptions`，子 agent 继承主 agent 的模型（详见 2.5）。
 - `roles.<toolName>.provider`：该角色模型所在的 provider 路由（可选 `string`）。须与 `model` 成对配置才生效，只配 `provider` 会被安装器告警并忽略；只配 `model` 时沿用主 agent 的 provider 路由（详见 2.5）。
+- `roles.<toolName>.background_mode`：该角色的会话模式（可选 `'one-shot' | 'continuable'`，缺省 `one-shot`）——一次性用完即弃，或可续：子会话跨轮保留，主 agent 用 `send_message` 就地续修。内置角色与自定义角色同语义；continuable 的前置、代价与面板路径见 2.6。
 - `roles` 下键名不在三角色内 = 自定义角色（见第 6 节）；请勿把静态角色 `search_internal_deep` 写进 `roles`（见 2.2）。
 - 内置角色可**整体删除**：`roles_remove` 键只认三角色名，删除效果、与 `roles` 键的一致性及恢复路径见 2.3。
 
@@ -57,11 +59,10 @@ CLI 参数优先级：`--profile` 显式给出时覆盖配置文件里的 `profi
 
 ### 1.3 完整最小示例
 
-一个覆盖全部常用键的配置文件（键序与安装器写出的 `serializeConfig` 一致）：
+一个覆盖全部常用键的配置文件（键序与面板写出的 `serializeConfig` 一致）：
 
 ```yaml
-# dsh-paoding（庖丁）安装配置 —— 可手编；改后重跑 ./install.sh --auto 应用。
-# 交互向导 / 配置 UI 也会写本文件（0o600）。
+# dsh-paoding（庖丁）安装配置 —— 可手编；改后在 设置 → 庖丁配置 应用，或重跑 node tools/install.mjs --auto
 
 profile: web            # 检测时扫描 profiles/<profile>/cordis.patch.yml
 
@@ -116,7 +117,7 @@ skills:                 # skill -> 分配给的角色（写进角色 persona 的
 
 对上例的几点说明：
 
-- `roles.search_external` 的 tools 是**意图**：若 tavily 未启用，安装器会把 5 个 `mcp__tavily__*` 剔除，保留其余（`--dry-run` 的 removed 列表会给出原因）。
+- `roles.search_external` 的 tools 是**意图**：若 tavily 未启用，生成器会把 5 个 `mcp__tavily__*` 剔除，保留其余（「预览生成」的 removed 列表会给出原因）。
 - `roles.design` 未写 `tools` → 保留静态 allow，只换 persona。
 - `roles.code-reviewer` 安装后生成 `delegation-code-reviewer` 委派块，主 agent 白名单加入 `code-reviewer`，对话里直接调该 toolName 即可委派。
 - `main_agent_persona_extra` 里的 `{{cwd}}` / `{{model}}` 是 DSH 运行时替换的占位符，必须原样保留。
@@ -143,6 +144,7 @@ roles:
       operation: report the failure compactly so the orchestrator can re-delegate.
     tools:
       - read
+      - read_image
       - write
       - edit
       - glob
@@ -168,11 +170,11 @@ roles:
 
 - **不要**把 `search_internal_deep` 写进配置文件 `roles` 键 —— 非三角色键名会被当作**自定义角色**处理，安装器会再生成一个重复的 `delegation-search-internal-deep` 块，与静态块冲突。
 - 同理它也**不在** `roles_remove` 可删名单内（该键只认三角色名，见 2.3）——它刻意保留为静态角色，不在任何配置键 / UI 里，本键也删不掉它。
-- 想调整它的 persona / 工具面：直接编辑 `presets/orchestrator/agent.cordis.yml` 里对应 `delegation-search-internal-deep` 块的 `persona` 与 `toolFilter.allow`，然后重跑 `./install.sh --auto`。安装器只重写三角色与主 agent persona 的有限区间，静态源里其余内容（包括你这个改动）原样保留到生成文件。
+- 想调整它的 persona / 工具面：直接编辑 `presets/orchestrator/agent.cordis.yml` 里对应 `delegation-search-internal-deep` 块的 `persona` 与 `toolFilter.allow`，然后在「庖丁配置」点「保存并应用」重新生成（开发者也可用兜底 CLI `node tools/install.mjs --auto`）。生成器只重写三角色与主 agent persona 的有限区间，静态源里其余内容（包括你这个改动）原样保留到生成文件。
 
 ### 2.3 删除内置角色：roles_remove
 
-顶层可选键 `roles_remove`（string[]，缺省 = `[]`）把内置委派角色从部署中**整条删除**，值为被删角色的 toolName。可删范围只有 `search_external` / `design` / `implement`——正好是 `roles` 键能覆盖的三个默认角色（配置 UI 里带「内置」徽标的三张卡）。范围之外的名字会被**忽略并告警**；`search_internal_deep` 删不掉（静态角色，见 2.2）。
+顶层可选键 `roles_remove`（string[]，缺省 = `[]`）把内置委派角色从部署中**整条删除**，值为被删角色的 toolName。可删范围只有 `search_external` / `design` / `implement`——正好是 `roles` 键能覆盖的三个默认角色（面板里带「内置」徽标的三张卡）。范围之外的名字会被**忽略并告警**；`search_internal_deep` 删不掉（静态角色，见 2.2）。
 
 删除即整条移除，被删角色在生成结果里整体不再出现：
 
@@ -193,8 +195,8 @@ roles_remove:
 
 恢复：
 
-- **手编**：把名字从 `roles_remove` 移除（想恢复自定义 persona / tools，同时在 `roles` 键写回该项），重跑 `./install.sh --auto`——角色按 SRC 默认 persona 与工具面重新生成。
-- **配置 UI**：角色列表末尾「已删除的内置角色」区一键恢复（恢复为 SRC 默认工具面）。
+- **手编**：把名字从 `roles_remove` 移除（想恢复自定义 persona / tools，同时在 `roles` 键写回该项），在「庖丁配置」点「保存并应用」——角色按 SRC 默认 persona 与工具面重新生成。
+- **面板**：角色列表末尾「已删除的内置角色」区一键恢复（恢复为 SRC 默认工具面）。
 
 ### 2.4 内置角色显示名：roles.\<toolName>.name
 
@@ -217,10 +219,10 @@ roles:
 - **被删除的角色不涉及**：`roles_remove` 整条删除的角色没有 persona 可改（见 2.3）。
 - **静态角色不在列**：`search_internal_deep` 不在安装器管理的三角色内，无此子键（见 2.2）。
 
-生效方式与主 agent 改名同构（见 5.1）：
+生效方式与主 agent 显示名同款（见 5.1）：
 
-- **手编**：写子键后重跑 `./install.sh --auto`，再重启 DSH / 新会话生效。
-- **配置 UI**：设置 → 庖丁配置 → 内置角色卡（徽标「内置」）顶部「角色显示名」输入框，空 = 默认；点「保存并应用」后**重启 GUI / 新会话**生效。
+- **手编**：写子键后在「庖丁配置」点「保存并应用」，再重启 DSH / 新会话生效。
+- **面板**：左侧栏「庖丁配置」→ 内置角色卡（徽标「内置」）顶部「角色显示名」输入框，空 = 默认；点「保存并应用」后**重启 GUI / 新会话**生效。
 
 ### 2.5 角色专用模型：roles.\<toolName>.model / .provider
 
@@ -244,19 +246,46 @@ roles:
 - **被删除的角色不涉及**：`roles_remove` 整条删除的角色，条目里残留的 `model` / `provider` 被忽略并告警（见 2.3）。
 - **静态角色不在列**：`search_internal_deep` 无这两个子键（见 2.2）。
 
-配置 UI（设置 → 庖丁配置 → 角色卡「专用模型」）中这一项是下拉选择，选项直接来自 DSH 已注册的模型路由；目录外的值（如手编配置）会以「当前配置」选项保真显示，不会被静默丢弃。
+配置页（左侧栏「庖丁配置」→ 角色卡「专用模型」）中这一项是下拉选择，选项直接来自 DSH 已注册的模型路由；目录外的值（如手编配置）会以「当前配置」选项保真显示，不会被静默丢弃。
 
-生效方式与其他配置键相同：改完重新应用（`./install.sh --auto`，或配置 UI「保存并应用」），再重启 DSH / 新会话。
+生效方式与其他配置键相同：改完在「庖丁配置」点「保存并应用」，再重启 DSH / 新会话。
 
 这两个子键是 8.1 静态源 `agentOptions` 写法的配置层等价物（免改源码，推荐优先）；需要连 `maxTokens` 一起控制时才落静态源（见 8.1）。
 
+### 2.6 角色会话模式：roles.\<toolName>.background_mode
+
+角色条目的可选子键 `background_mode`，决定该角色派出的子 agent 会话怎么收场：`'one-shot'`（一次性，用完即弃）或 `'continuable'`（可续，子会话跨轮保留）。缺省 `one-shot`；内置角色与自定义角色条目同语义，没有角色差异。
+
+```yaml
+roles:
+  implement:
+    background_mode: continuable   # 该角色的委派转后台、跨轮保留；主 agent 用 send_message 就地续修
+```
+
+生成语义：基础模板在四个内置角色的委派块里各预置一行 `backgroundMode: one-shot`（纯为可见性——打开生成文件不用猜默认值）；配成 `continuable` 的角色，生成器把该行**原位改写**为 `backgroundMode: continuable`（块内无此行时才兜底注入，不会出现两行），`one-shot` / 缺省原样保留。自定义角色块同样恒写此行。两种模式的编排取舍、失败恢复分支见[编排](orchestration.md)「one-shot 与多轮迭代」。
+
+continuable 的前置与代价（如实说明）：
+
+- **前置：host 层挂 `sessionPersistence` 后端。** 在 `~/.dsh/cordis.patch.yml` 挂 `@deepseek-ai/dsh-session-persistence-jsonl`（`config.root` 必填）。未挂载时 continuable 创建/续跑直接报错（错误码 `PERSISTENCE_UNAVAILABLE`）。这是机器级全局改动，卸载 preset 不撤销。
+- **代价：无 TTL 落盘累积、每轮携带累积上下文。** 持久化会话没有 TTL，会持续写盘；continuable 子 agent 每轮带着自己攒下的上下文，长期挂只增不减。只给多轮打磨类委派用，用完 `interrupt_agent` 停掉、顺手清理落盘。
+
+面板操作路径：左侧栏「庖丁配置」→ 角色卡「会话模式」单选（「一次性（one-shot）」/「可续（continuable）」）。未探测到 `sessionPersistence` 时面板会就地警告但不拦截——警告只是提醒先把 persistence 后端挂上，保存照常可执行。
+
+边界：
+
+- **静态角色不在列**：`search_internal_deep` 不经 `roles` 键（见 2.2）。它的委派块在基础模板里同样显式标了 `backgroundMode: one-shot`；要把它改成可续，直接改静态源那一行再「保存并应用」重新生成（生成器不重写该行，原样保留）。
+- **被删除的角色不涉及**：`roles_remove` 整条删除的角色，条目里残留的 `background_mode` 被忽略并告警（见 2.3）。
+- **主 persona 已有对应分支**：可续角色失败或产出不满时，主 agent 的委派失败 SOP 先 `send_message` 同会话续修，重委派退为续修无效后的退路（见[编排](orchestration.md)）。
+
+生效方式与其他配置键相同：改完在「庖丁配置」点「保存并应用」，再重启 DSH / 新会话。
+
 ## 3. 主 agent 工具面
 
 ### 3.1 机制与 21 项白名单基线
 
 主 agent 的工具面由 `presets/orchestrator/restrict.mjs`（`orchestrator-restrict`）在 `system-prompt/assemble` 瀑布上按白名单过滤。过滤是**失败自动放行全量**的（过滤器自身出错不会锁死会话）；名字按已解析的工具逐个匹配，**未挂载的名字只是缺席、永远不是错误**。
 
-`restrict.mjs` 里的常量 `MAIN_AGENT_ALLOW` 是生成 `config.allow` 的 **base**（21 项）：`config.allow` 未注入时运行时直接回落该常量。要改主 agent 工具面，**不要改 `restrict.mjs` 源码**——一律用配置文件（`main_agent_extra` / `main_agent_remove`），或交互向导里的移除/恢复步骤。
+`restrict.mjs` 里的常量 `MAIN_AGENT_ALLOW` 是生成 `config.allow` 的 **base**（21 项）：`config.allow` 未注入时运行时直接回落该常量。要改主 agent 工具面，**不要改 `restrict.mjs` 源码**——一律用配置文件（`main_agent_extra` / `main_agent_remove`），或在面板「主 agent」卡片里勾选/取消。
 
 | 分组 | 工具（21 项） |
 |---|---|
@@ -280,9 +309,9 @@ main_agent_extra:
 
 要点：
 
-- 追加项会进入生成的 `orchestrator-restrict config.allow`。`mcp__*` 与插件工具属 **host 依赖**：安装器只把**实际检测到**的注入 allow；没检测到（MCP 未启用、拼写错误）就静默不注入、不报错。
-- 向导 / 配置 UI 的「主 agent」卡片里可勾选的具体 host 工具，以检测面板（工具池）为准。
-- `main_agent_extra` 缺省/为空时，安装器回落到智能默认（检测到的 codegraph、`memory_search` 建议归主 agent）。
+- 追加项会进入生成的 `orchestrator-restrict config.allow`。注入同样走白名单对账：名字必须落在 **preset 自带工具面**（`restrict.mjs` 主 agent 白名单 ∪ 源 preset 各角色静态 allow）或**检测库存**里，host 工具（`mcp__*`、`mnemon_*` 等插件工具）以实际检测结果为准——没检测到（MCP/插件未启用、拼写错误）就不注入、不报错，「预览生成」的角色 removed 列表可看原因。
+- 面板的「主 agent」卡片里可勾选的具体 MCP / 插件工具，以检测结果（工具池）为准。
+- `main_agent_extra` 缺省/为空时，生成器回落到智能默认（检测到的 codegraph、`memory_search` 建议归主 agent）。
 
 ### 3.3 移除基础工具：main_agent_remove
 
@@ -362,28 +391,35 @@ main_agent_skills_inline:
 | 找不到对应 SKILL.md | **警告并跳过**（不中断安装）；对两条键各警告一次、去重 |
 | SKILL.md 存在但正文为空 | 视为找不到，跳过 |
 | `description` 解析 | 支持单行、引号（单/双）、折叠块（`>`）与字面块（`\|`，含标记独立成行）；空白折叠、去外层引号、截断至 200 字符；缺省为空串 |
-| SKILL.md 扫描范围 | `$DSH_HOME/skills`（默认 `~/.dsh/skills`）、`$DSH_AGENTS_HOME/skills`（默认 `~/.agents/skills`）、`<cwd>/.dsh/skills`、`<cwd>/.agents/skills`；同根内 `<root>/<name>/SKILL.md` 优先于裸 `<root>/<name>.md` |
+| SKILL.md 扫描范围 | 全局（CLI 安装 / 面板「全局默认」）只扫用户级两根：`$DSH_HOME/skills`（默认 `~/.dsh/skills`）、`$DSH_AGENTS_HOME/skills`（默认 `~/.agents/skills`）；按工作区生成时另加该工作区目录的 `.dsh/skills` 与 `.agents/skills`（见第 9 节）。同根内 `<root>/<name>/SKILL.md` 优先于裸 `<root>/<name>.md` |
 
-技能名来自安装时的技能检测（同上四个根）；向导 / 配置 UI 只会列出检测到的技能。
+技能名来自应用时的技能检测（同上四个根）；面板只会列出检测到的技能。
 
 ## 5. 主 agent 人设
 
-### 5.1 主 agent 名称：main_agent_name
+### 5.1 只改显示名：main_agent_display_name
+
+`main_agent_display_name`（顶层可选键，string | null）只改**部署 preset 显示名**——GUI 预设选择器里看到的那个名字；persona 身份行 `You are the orchestrator agent powered by the {{model}} model.` 完全不动。编排主 agent 的身份是编排预设提示词语义的一部分，**不支持改名**（旧版「主 agent 名称」键已下线；老配置里的残留行下次「保存并应用」时自动清除，安装器会提示该键已忽略）。
+
+约束：trim 后 1–60 字符、不可含换行，违规直接报错；空 / 缺省 = 默认「编排模式 (Orchestrator)」（工作区预设用派生名）。
 
-顶层可选键 `main_agent_name`（string | null）改主 agent 的名字，**一改两处**：
+生成 `preset.yml` 时显示名按下面的顺序取值：
 
-- **部署 preset 显示名**：`preset.yml` 的显示名——GUI 预设选择器里看到的那个名字，默认「编排模式 (Orchestrator)」；
-- **persona 身份行**：主 agent persona 的 `You are the <name> agent powered by the {{model}} model.`，`<name>` = 本键值。
+1. `main_agent_display_name`（本键非空时最优先）；
+2. 「SRC 名·目录名」派生名（仅工作区预设，见 9.2）；
+3. SRC 原名。
 
-约束：trim 后 1–60 字符、不可含换行；空字符串 / 缺省 = 保持默认（不写此键时，显示名与身份行都是 SRC 原文，安装器不做任何替换）。
+不写本键时一切行为与从前逐字节一致（向后兼容，老配置零感升级）。
 
 ```yaml
-main_agent_name: orchestration-lead   # 缺省 = 默认编排名（preset 显示名「编排模式 (Orchestrator)」）
+main_agent_display_name: 庖丁   # 仅 preset 显示名换成「庖丁」，persona 身份行不动
 ```
 
-- **手编**：写键后重跑 `./install.sh --auto`，再重启 DSH / 新会话生效。
-- **配置 UI**：设置 → 庖丁配置 → 主 agent 卡顶部「主 agent 名称」输入框（带「恢复默认」按钮）；点「保存并应用」后**重启 GUI / 新会话**生效。
-- **对照**：本键只改**主 agent**。内置角色的显示名是角色级子键 `roles.<toolName>.name`——只替换该角色默认 persona 首行身份句的主语、不改工具调用名（见 2.4），两条改名线互不牵连、可各自独立配置。
+生效方式：
+
+- **手编**：写键后在「庖丁配置」点「保存并应用」，再重启 GUI / 新会话生效。
+- **面板**：左侧栏「庖丁配置」→ 主 agent 卡「主 agent 显示名（仅 preset 显示名）」输入框（带「恢复默认」按钮），点「保存并应用」后**重启 GUI / 新会话**生效。
+- **对照**：显示名线共两条、互不牵连：`main_agent_display_name`（仅主 agent 的 preset 显示名，见 5.1）、`roles.<toolName>.name`（内置角色默认 persona 首行身份句的主语，不改工具调用名，见 2.4），可各自独立配置。
 
 ### 5.2 追加三态语义：main_agent_persona_extra
 
@@ -407,9 +443,8 @@ main_agent_name: orchestration-lead   # 缺省 = 默认编排名（preset 显示
 
 ### 5.4 编辑途径
 
-- **手编**：直接编辑配置文件的 `main_agent_persona_extra` 键，重跑 `./install.sh --auto`。
-- **配置 UI**：设置 → 庖丁配置 → 主 agent 卡片「人设追加」（编辑器带「恢复默认」按钮），可编辑 / 清空 / 恢复默认；点「保存并应用」后**重启 GUI / 新会话**生效。
-- 交互向导没有独立的人设追加步骤（从既有配置原样继承）——CLI 下改它请手编或走 UI。
+- **手编**：直接编辑配置文件的 `main_agent_persona_extra` 键，然后在「庖丁配置」点「保存并应用」。
+- **面板**：左侧栏「庖丁配置」→ 主 agent 卡片「人设追加」（编辑器带「恢复默认」按钮），可编辑 / 清空 / 恢复默认；点「保存并应用」后**重启 GUI / 新会话**生效。
 
 ## 6. 自定义角色
 
@@ -419,25 +454,32 @@ main_agent_name: orchestration-lead   # 缺省 = 默认编排名（preset 显示
 与 `read` / `write` / `edit` / `bash` 等、persona 说明调用 `html-ppt` 技能产出 HTML 幻灯片，再把
 `html-ppt` 技能分给它（第 7 节）。装好后主 agent 说「把这份大纲做成 PPT」即委派给会做幻灯片的子 agent，
 通用角色不用什么都碰。任意已装技能都能这样变成专属角色（前端稿、图表、文档排版……）。下分三小节：
-向导/UI 路径（6.1）、手写静态源路径（6.2）与配置示例（6.3，含技能型 PPT agent）。
+面板路径（6.1）、手写静态源路径（6.2）与配置示例（6.3，含技能型 PPT agent）。
 
 先说两个生成期行为：其一，**零工具的自定义角色装不上**——`tools` 缺省或写成空列表会得到一张空白
 名单（`toolFilter.allow:` 落成 null），子 agent 创建后一个工具都没有；生成器对此与内置角色一视同仁，
-应用时直接报错拒绝安装，给角色配上至少一个工具再应用即可（向导里选不出工具也会一直重问）。其二，
+应用时直接报错拒绝安装，给角色配上至少一个工具再应用即可。其二，
 生成器会把角色 persona 的**首行职责句自动追加为主 agent persona 的委派行**（`- <职责>: delegate to
 <toolName>.`，紧跟既有委派行之后）——主 agent 全靠这行知道什么活该派给谁，因此建议把 persona 首行
 写成一句简短职责（例如「你的职责就是查找符合用户要求的技能」）。
 
-### 6.1 路径一：交互向导 / 配置 UI（推荐）
+### 6.1 路径一：庖丁配置面板（推荐）
 
-向导流程（`./install.sh` 交互模式，或配置 UI 的「Agent 工具分配」）：
+面板流程（左侧栏「庖丁配置」→「Agent 工具分配」→ 底部「新建自定义 agent 角色」）：
 
 1. 新建角色：输入 `toolName`，须匹配 `/^[a-z][a-z0-9_]*$/`；
-2. 从工具池多选工具（工具池 = 三角色静态 allow ∪ 检测到的 host 工具）；
-3. 写一句 persona（向导自动展开为 `You are the <name> agent. <你的描述>`；配置 UI 可给完整 persona）；
-4. 向导自动把新 `toolName` 注入主 agent 的 `orchestrator-restrict config.allow` —— **`restrict.mjs` 文件本身不用改**；并把分配持久化到配置文件（`roles` 键下多一项）。
+2. 从工具池多选工具（工具池 = 三角色静态 allow ∪ 检测到的 MCP / 插件工具）；
+3. 写 persona（可给完整 persona，首行写成一句简短职责）；
+4. 点「保存并应用」——生成器自动把新 `toolName` 注入主 agent 的 `orchestrator-restrict config.allow` —— **`restrict.mjs` 文件本身不用改**；并把分配持久化到配置文件（`roles` 键下多一项）。
+
+角色卡上工具清单的口径：候选 = 源码 preset 的静态 allow 面（内置角色自带；本身含核心工具）∪ 主 agent 核心
+allow（`restrictBase`，供自定义角色回落）∪ 检测库存，按三组呈现——「**基础工具**」= 非 `mcp__` 且不在检测
+库存的核心面（`read` / `glob` / `grep` / `bash` / `todo_write` 等，委派名 `search_external` / `design` /
+`implement` / `search_internal_deep` 不进网格）；「**MCP 工具**」= `mcp__` 前缀（含源码 preset 自带的
+tavily 等行）；「**插件工具**」= 检测库存中无 `mcp__` 前缀的插件直注册工具（`mnemon_*` 等）。新建角色的出厂
+`tools` 即核心面加检测库存，默认全选，应用前可逐项增删。
 
-之后对话里直接调该 toolName 即可委派。删除角色 = 从配置文件移除该项再重跑 `--auto`（目标文件每次重新生成，不留残留块）。**内置角色**的整条删除不同——那是 `roles_remove`（见 2.3），`roles` 键下不写即可不覆盖。
+之后对话里直接调该 toolName 即可委派。删除角色 = 面板里删卡（或从配置文件移除该项）后再点「保存并应用」（目标文件每次重新生成，不留残留块）。**内置角色**的整条删除不同——那是 `roles_remove`（见 2.3），`roles` 键下不写即可不覆盖。
 
 ### 6.2 路径二：手写静态源
 
@@ -446,7 +488,7 @@ main_agent_name: orchestration-lead   # 缺省 = 默认编排名（preset 显示
 1. 复制 `presets/orchestrator/agent.cordis.yml` 里一个 `delegation-*` 块（delegation 组内）；
 2. 改 `toolName` / `persona` / `toolFilter.allow`；
 3. 把新 `toolName` 加进 `presets/orchestrator/restrict.mjs` 的 `MAIN_AGENT_ALLOW`（这是生成 `config.allow` 的 base，主 agent 白名单不出现该名字就无法调用委派工具）；
-4. 重跑 `./install.sh --auto`（安装器只重写三角色与主 agent persona 的有限区间，你新增的块原样保留）。
+4. 重新应用（「庖丁配置」点「保存并应用」；开发者也可 `node tools/install.mjs --auto`）——生成器只重写三角色与主 agent persona 的有限区间，你新增的块原样保留。
 
 两条路径生成同一结构（`delegation-<toolName>` + 白名单含 toolName）；路径一免改源码、可经 UI 管理，推荐优先。
 
@@ -470,7 +512,7 @@ roles:
       - todo_write
 ```
 
-重跑 `./install.sh --auto` 后：生成 `delegation-code-reviewer` 块（persona 原样、tools 原样进 allow），主 agent `config.allow` 注入 `code-reviewer`。注意：自定义角色的 `tools` **原样写入** allow，不做 host 检测求交（向导/UI 的工具池已保证可选项都在注册面内）——手编时只列实际挂载的工具，否则子 agent 创建时 `tools.restrict()` 会以 unknown tools 拒绝。
+在「庖丁配置」点「保存并应用」后：生成 `delegation-code-reviewer` 块（persona 原样、tools 原样进 allow），主 agent `config.allow` 注入 `code-reviewer`。注意：自定义角色的 `tools` **原样写入** allow，不做 host 检测求交（面板的工具池已保证可选项都在注册面内）——手编时只列实际挂载的工具，否则子 agent 创建时 `tools.restrict()` 会以 unknown tools 拒绝。
 
 **技能型示例：`ppt` agent（做 PPT 的专属子 agent）**——工具面含 `skill` 与读写编辑，persona 引导加载
 `html-ppt` 技能，`skills` 键把技能分给该角色（persona 尾部生成 Available skills 引导行）：
@@ -499,14 +541,14 @@ skills:
 
 效果与 `code-reviewer` 相同（生成 `delegation-ppt` 块、白名单注入 `ppt`）；区别在多一步 `skills` 映射。
 子 agent 创建后 skill 目录对角色全量可见（DSH 机制），persona 的引导行只是**软约束**——真正干活靠子 agent
-按需用 `skill` 工具读正文，装配别的技能（如做简历、出图表）同理。向导 / 配置 UI 里也能搭出同款：工具池勾
+按需用 `skill` 工具读正文，装配别的技能（如做简历、出图表）同理。庖丁配置面板里也能搭出同款：工具池勾
 `skill` + 读写编辑、写一句 persona、在技能分配面板把 `html-ppt` 分给 `ppt`。
 
 ## 7. skill 分配
 
 ### 7.1 写法与效果
 
-顶层 `skills` 键把技能分给角色（值 = 角色 toolName 列表，与向导「技能分配」步骤、配置 UI「技能分配」面板同一映射）：
+顶层 `skills` 键把技能分给角色（值 = 角色 toolName 列表，与面板「技能分配」网格同一映射）：
 
 ```yaml
 skills:
@@ -520,6 +562,8 @@ skills:
 
 这是一条**软约束**而非硬隔离：目录可见性是 DSH 机制（按 cwd 收集、对角色全量可见），persona 引导句只是提示。硬隔离靠工具面（allow 里有没有 `skill`）实现。主 agent 例外：其注册层 deny 了 `skill`（见 3.1），所以技能对其不可见——需要时走 `main_agent_skills` / `main_agent_skills_inline`（第 4 节），而不是 `skills` 键。
 
+技能候选的扫描范围随配置对象走：全局视角只含用户级技能；工作区视角另含该工作区目录下的项目级技能（面板里带「项目」角标），见 9.5。
+
 ## 8. 子 agent 模型与平台细节
 
 ### 8.1 按角色分模型
@@ -548,4 +592,54 @@ skills:
 
 ### 8.3 停用 MCP / 插件后的同步
 
-停用 tavily / codegraph / magic-memory（在 `~/.dsh/cordis.patch.yml` 或 profile patch 注释相应条目）后**不需要手动改 allow**：重跑 `./install.sh --auto`，安装器检测到停用后自动把对应 `mcp__tavily__*` / `memory_search` 从三角色 allow 剔除（`--dry-run` 可先预览剔除项）。检测不到或握手失败的 MCP 会被跳过：对应角色只是缺这些工具，安装不报错。检测与 patch 层的细节链见 [安装](installation.md)。
+停用 tavily / codegraph / magic-memory（在 `~/.dsh/cordis.patch.yml` 或 profile patch 注释相应条目）后**不需要手动改 allow**：在「庖丁配置」点一次「保存并应用」，生成器检测到停用后自动把对应 `mcp__tavily__*` / `memory_search` 从三角色 allow 剔除（「预览生成」可先看剔除项）。检测不到或握手失败的 MCP 会被跳过：对应角色只是缺这些工具，应用不报错。检测与 patch 层的细节链见 [安装](installation.md)。
+
+## 9. 按工作区配置
+
+### 9.1 一份全局，各自成套
+
+DSH 用工作区（workspace，即项目目录）组织会话。顶层 `workspaces` 键让每个工作区有自己的主/子 agent 配置：全局条目照旧生成共享的 `orchestrator` 预设；工作区条目各自生成 `orchestrator-<slug>` 专属预设，预设列表里并存、互不覆盖。
+
+每个工作区条目是**完整一套配置**，不是增量差异：字段与顶层同构（`profile` 除外，检测层全局共享）。角色子键照搬——`background_mode`（见 2.6）同样按工作区生效：某个项目想让 implement 可续、别的项目保持一次性，各配各的。在面板里第一次配置某个工作区时，以当前全局配置为起点，改完点「保存并应用」即生成该工作区的预设。
+
+```yaml
+workspaces:
+  '/Users/me/code/shop-api':      # 键 = 工作区目录绝对路径（写入时归一，恒带引号）
+    main_agent_display_name: 店铺后端主控   # 仅该工作区预设的显示名
+    roles:
+      implement:
+        model: deepseek-reasoner  # 这个项目写代码用推理档
+  '/Users/me/code/blog':
+    roles_remove: [design]        # 写博客的项目不需要设计帮手
+```
+
+### 9.2 预设命名规则
+
+- **slug** 取工作区目录名：小写、非法字符归并为 `-`；归并后为空、或恰好叫 `orchestrator`（与全局预设撞名）时改用 `ws`。
+- 多个工作区目录同名时，自动追加路径哈希（sha1 前 6 位）后缀，如同为 `Shop` 的两个项目得到 `orchestrator-shop-acd95b` 与 `orchestrator-shop-34b6aa`——改名或挪动目录后重新应用即可，旧预设目录不会被自动清理，不再需要的可在 DSH 预设页删除。
+- 预设显示名：条目配了 `main_agent_display_name` 就用它；没配则在默认名后缀「·目录名」（如 `编排模式 (Orchestrator)·Shop`），预设列表里一眼可辨。
+
+### 9.3 面板用法
+
+「庖丁配置」页面顶部是**配置对象**标签页：
+
+- **全局默认**：编辑并写入共享的 `orchestrator` 预设，行为与从前完全一致；
+- **工作区标签页**：列表来自宿主工作区注册表（开过会话的目录才会登记），带绿点的表示预设已生成，悬停可见路径、会话数与预设 id；
+- **添加工作区**：输入目录绝对路径即注册（幂等），注册表拉不到时降级为只显示配置文件里已有的工作区，面板其余功能不受影响。
+
+选定某个工作区后，预览 / 应用都只作用于它；应用成功的提示里会给出预设 id。
+
+### 9.4 生效方式与边界
+
+- **预设选择发生在新建会话时**：新建会话界面选好工作区后，在预设选择器里选对应的 `orchestrator-<slug>`。全局默认预设不受任何影响。预设生效需要新会话（或 DSH 重启后可见）。
+- 预设目录落在 `$DSH_HOME/.agent-presets/` 下，全机共享：同一台机器上不同项目各起的 DSH 实例，因 slug 不同互不覆盖。
+- 兜底 CLI 本次仍只作用于全局条目；`workspaces` 段在 CLI 应用后原样保留，不会被冲掉。
+- 运行中的会话不会换预设——子 agent 的角色与工具面在会话创建时随预设组装定型，会话内不可变；要换套班底，开新会话选新预设。
+
+### 9.5 技能扫描范围随配置对象走
+
+技能候选不跟随 GUI 的启动目录：**全局默认**视角只扫用户级两根（`~/.dsh/skills`、`~/.agents/skills`），**工作区**视角另加该工作区目录下的 `.dsh/skills` 与 `.agents/skills`。于是：
+
+- 只装在某个项目里的技能（比如知识库项目里的 `bento-slides`），在全局配置里不可见、配不上；选中那个工作区后出现在技能网格里，带「项目」角标，可分配给该工作区预设的主 agent 或角色。
+- 生成时技能解析同口径：工作区预设能写出项目级技能的 SKILL.md 绝对路径（主 agent 用 `read` 按需读，路径在盘上就能读）；全局预设只解析用户级，配了项目级技能名会告警跳过——全局预设要在所有项目通用，引用单一项目的技能本就不该写进去。
+- 兜底 CLI 没有工作区概念，只扫用户级两根（与全局默认一致）。