dsh-paoding 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lifangjin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# dsh-paoding（庖丁解牛）
+[English](README_en.md) · 中文
+
+庖丁解牛，游刃有余 —— 把 DSH 调教成一支分工明确、按需加载的 agent 小团队。
+
+dsh-paoding（中文品牌「庖丁」，典出《庄子》——庖丁顺纹理下刀，刀刃十九年若新发于硎）是 DSH（DeepSeek Harness agent 运行时）的**预设生成器**。DSH 原本是一个 agent 包揽约 60 个工具、每次请求全量加载；装上庖丁后变成「一个指挥 + 四个帮手」——主 agent 只带编排与内部搜索的精简工具，其余的活按角色委派给只带本行工具的子 agent。全部靠配置完成，**零 DSH 源码改动**。
+
+## 功能特性
+
+- **一支分工明确的小团队**：主 agent 当指挥，拆解任务、分派验收；联网调研、UI 设计、写代码、全仓深搜四位专属帮手各司其职，随叫随到、干完即走。
+- **高频小事不过手他人**：找代码、查引用、读文件这类顺手的事，主 agent 自己直接办，不绕委派的圈子。
+- **可招募专属帮手**：内置四角色只是起点——给新角色配好工具和技能（比如装上 `html-ppt` 技能的 PPT 帮手），之后一句「把这份大纲做成 PPT」就有人接活。向导、配置文件、图形界面三个入口都能建。
+- **帮手还能指定专用模型**：写代码的用强档、查资料的用轻快档，各配各的模型；不配就跟随主 agent 当前会话的模型。
+- **省钱省上下文**：帮手的工具只在被叫到时才加载，用一次付一次；主 agent 每次请求的工具开销约降三分之二，上下文只收摘要，不再被搜索结果和代码改动撑爆。
+- **角色随改随用**：删掉用不上的内置角色、给角色改显示名、给主 agent 改名，都是配置里一行的事；改完跑一条命令重新生成，即刻生效。
+- **装了什么都能认出来**：MCP 服务器、本地插件、已装技能，安装与配置时全程检测；默认只装 dsh 基础工具，检测到的 host 工具在「庖丁配置」里按需勾选（或 `--suggest` 自动分派）；停用哪个，重跑一遍后相关工具自动剔除。
+- **图形界面配置**：不习惯改配置文件的话，「设置 → 庖丁配置」里点选即可，「保存并应用」与命令行走同一条生成管线。
+- **来去自由**：不改 DSH 一行源码；装完新会话即用，卸载即删目录。
+
+## 插件截图
+
+![截图 1](docs/images/1.png)
+
+![截图 2](docs/images/2.png)
+
+![截图 3](docs/images/3.png)
+
+![截图 4](docs/images/4.png)
+
+![截图 5](docs/images/5.png)
+
+![截图 6](docs/images/6.png)
+
+## 快速开始
+
+前置：**Node.js ≥ 18** 与一台已装好的 DSH host。
+
+**npx 一键安装（推荐）**——不用克隆仓库，一条命令：
+
+```bash
+npx dsh-paoding@latest             # npm 发布后可用
+npx github:lifangjin/dsh-paoding   # 发布前从 GitHub 仓库直装，效果相同
+```
+
+这一条等价于 `--auto --config-ui`：生成编排预设、写好基础配置模板，并把「庖丁配置」挂进 DSH 设置页。开箱默认只带 DSH 自带的基础工具，检测到的 MCP/host 工具不会自动写入——装完在**设置 → 庖丁配置**里按需勾选工具与角色，「保存并应用」即生效；想逐项过一遍就跑 `npx dsh-paoding --wizard`，想沿用自动分配就加 `--suggest`。
+
+偏好官方插件通道的话，`dsh plugin --profile web add dsh-paoding@0.2.0` 也能把「庖丁配置」按 profile 装进设置页（preset 本体仍走 npx / `./install.sh`），详见[安装文档](docs/installation.md)。
+
+**克隆仓库安装**——老路线原样保留：
+
+```bash
+git clone <repo-url> dsh-paoding
+cd dsh-paoding
+./install.sh              # 交互向导，一路回车即用默认
+./install.sh --auto       # 非交互：有配置应用配置，没配置写基础模板（--suggest 用智能默认）
+./install.sh --config-ui  # 顺带挂上图形配置界面（可与 --auto 同用）
+./install.sh --dry-run    # 只预览将生成的内容，不写盘
+./install.sh --help       # 全部参数
+```
+
+装完**重启 DSH（`dsh web`）或新建会话**，在预设选择器里选「编排模式 (Orchestrator)」即可；要设为默认，在 Settings → Agent Presets 里选。已有 `dsh-paoding.config.yml` 的话，重跑任何入口都按配置文件应用、不覆写。卸载删掉 `~/.dsh/.agent-presets/orchestrator` 即可（npx/npm 安装的还多一个 `~/.dsh/dsh-paoding`）。详细步骤与排查见 [安装文档](docs/installation.md)。
+
+## 怎么用
+
+给主 agent 派活即可，它按分工自己路由：
+
+- 找代码 / 查引用 / 读文件 → 主 agent 自己办，不委派；
+- 联网查资料、做调研 → 联网调研帮手（`search_external`，只带联网工具、不改文件）；
+- 出界面方案、设计稿 → 设计帮手（`design`，可加载设计技能，出 spec 不写最终代码）；
+- 写代码 / 改代码 → 实现帮手（`implement`，改完自验再汇报）；
+- 超大仓库全仓探索、大文件通读 → 全仓深搜帮手（`search_internal_deep`，只读、无网络，只回浓缩摘要）；
+- 专属活（比如做 PPT）→ 先建自定义角色，之后随叫随到。
+
+帮手干活期间，主 agent 可以随时追问、查看进度、叫停；结束后只把摘要收进上下文，不把帮手的完整过程倒进来。任务失败怎么恢复、怎么多轮迭代，见 [编排文档](docs/orchestration.md)。
+
+## 配置
+
+所有偏好都写在 `~/.dsh/dsh-paoding.config.yml`：角色增删改、技能分配、专用模型、主 agent 的工具与技能……改完跑一遍 `./install.sh --auto` 即同步生效。预设每次由「静态源 + 配置」重新生成，不攒手工补丁。全部配置键说明见 [配置文档](docs/configuration.md)；背后机制与成本账见 [架构文档](docs/architecture.md)。
+
+## 文档
+
+| 文档 | 内容 |
+|---|---|
+| [架构](docs/architecture.md) | 为什么这样设计——概述、成本账、角色与工具、对应 DSH 原生机制、Token 治理、已知边界。 |
+| [安装](docs/installation.md) | npx 一键安装、官方插件通道装 UI、前置要求、交互向导六阶段、CLI 参数、host patch 检测机制、应用/升级/卸载、配置 UI 挂载、排查。 |
+| [编排](docs/orchestration.md) | 编排总览、失败如何呈现与三层处理、one-shot vs continuable、上下文隔离。 |
+| [配置](docs/configuration.md) | 配置键全参考、内置角色微调、主 agent 工具与技能、自定义角色、按角色分模型。 |
+
+## 贡献
+
+欢迎 issue 与 PR：使用中发现问题、想要新的角色、或发现文档与实现不一致，都可以提。动手前请先读 [架构](docs/architecture.md) 与 [配置](docs/configuration.md)；文档与实现冲突时，以 `presets/orchestrator/` 与 `tools/install.mjs` 源码为准。
+
+## 许可
+
+以 [MIT License](LICENSE) 发布，完整条款见仓库根目录的 `LICENSE` 文件。

package/README_en.md

@@ -0,0 +1,95 @@
+# dsh-paoding (庖丁解牛)
+English · [中文](README.md)
+
+*Pao Ding carves the ox, blade gliding through — turn DSH into a small, well-organized team of agents.*
+
+dsh-paoding (Chinese brand 「庖丁」/ Pao Ding, from the Zhuangzi parable of the butcher whose blade never dulls because he cuts along the ox's natural seams) is a **preset generator** for DSH (DeepSeek Harness, an agent runtime). Out of the box, DSH runs one monolithic agent that loads all ~60 tools on every request; with dsh-paoding it becomes one lead plus four specialists — the main agent keeps a lean orchestration-and-search toolkit, and everything else is delegated to sub-agents that carry only the tools of their trade. Pure configuration, **zero DSH source changes**.
+
+## Highlights
+
+- **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.
+- **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.
+- **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.
+- **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)
+
+![Screenshot 3](docs/images/3.png)
+
+![Screenshot 4](docs/images/4.png)
+
+![Screenshot 5](docs/images/5.png)
+
+![Screenshot 6](docs/images/6.png)
+
+## Quick Start
+
+Prerequisites: **Node.js ≥ 18** and a working DSH host.
+
+**One-command install with npx (recommended)** — no clone needed:
+
+```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
+```
+
+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@0.2.0` 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:
+
+```bash
+git clone <repo-url> 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
+```
+
+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).
+
+## How It Works in Practice
+
+Just hand work to the main agent; it routes by division of labor:
+
+- Finding code / checking references / reading files → the main agent does it itself, no delegation;
+- Web research → the research helper (`search_external`: web tools only, never modifies files);
+- UI designs and specs → the design helper (`design`: may load design skills, produces specs rather than final code);
+- Writing / editing code → the implementation helper (`implement`: verifies its changes before reporting);
+- Whole-repo exploration or full-file reads in a huge repository → the deep-search helper (`search_internal_deep`: read-only, no network, returns only a condensed summary);
+- Specialized work (e.g. making PPTs) → create a custom role once, then call it anytime.
+
+While a helper runs, the main agent can send follow-ups, check progress, or stop it; when done, it integrates only the summary, never the helper's full transcript. Failure recovery and multi-turn iteration are covered in the [orchestration guide](docs/orchestration_en.md).
+
+## 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).
+
+## 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. |
+| [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. |
+
+## 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`.
+
+## License
+
+Released under the [MIT License](LICENSE); see the `LICENSE` file at the repository root for the full terms.

package/bin/dsh-paoding.mjs

@@ -0,0 +1,12 @@
+#!/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)

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-paoding bundle patch — `dsh plugin --profile <name> add dsh-paoding` 时由
+# reconcilePlugins 并入该 profile 的 dsh.profile.bundles，boot 时并入补丁树。
+# name: dsh-paoding 指向 pnpm 装进 profile 的本包（main: plugins/paoding-config-ui/index.mjs）。
+- insert:
+    - id: paoding-config-ui
+      name: dsh-paoding

package/docs/architecture.md

@@ -0,0 +1,292 @@
+<!-- docs/architecture.md — dsh-paoding（庖丁）架构说明 -->
+
+← [dsh-paoding](../README.md) ｜ [安装](installation.md) ｜ **架构** ｜ [编排](orchestration.md) ｜ [配置](configuration.md)
+
+[中文](architecture.md) · [English](architecture_en.md)
+
+# 架构
+
+> 读者对象：想理解「为什么这样设计、成本/收益、底层机制」的技术用户与贡献者。本文事实以仓库源码
+> （`presets/orchestrator/agent.cordis.yml`、`presets/orchestrator/restrict.mjs`、
+> `presets/orchestrator/preset.yml`）为准；与 README 冲突处以源码为准。
+
+## 概述
+
+dsh-paoding（中文品牌「庖丁」，取庖丁解牛之意）是 DSH（DeepSeek Harness，一个 agent 运行时）的
+**编排模式（orchestrator）preset 生成器与配置器**。它把 DSH 的默认形态——单体 agent 每次请求全量加载
+全部工具（约 60 个，每请求约 16.2k tokens 的工具定义开销）——改造成「主 agent 编排 + 角色子 agent 分工、
+按需加载」：
+
+- **热路径留在主 agent**：内部文件搜索（glob / grep / read / read_image / bash）由主 agent 零成本直达，
+  不产生委派往返；
+- **冷路径委派给角色子 agent**：联网外部调研（search_external）、设计（design）、代码实现（implement）、
+  全仓深搜（search_internal_deep）分别交给只带必要工具的子 agent，**用一次才付一次**；
+- **上下文隔离**：每个子 agent 上下文小而专，主 agent 只收集成摘要。
+
+整个方案是「纯配置 + 一个核心逻辑约 130 行的瀑布过滤插件（`restrict.mjs`，含注释约 190 行）」，
+**零 DSH 源码改动**，热插拔（装/卸/改都是文件操作）。
+
+与单体模式的本质区别有三点：
+
+| 维度 | 单体模式（默认） | 编排模式（本 preset） |
+|---|---|---|
+| 职责 | 一个 agent 承担全部任务 | 主 agent 拆任务与集成，角色子 agent 各干一摊 |
+| 开销 | 每请求固定承载 ~16.2k tokens 工具定义 | 主 agent ~5.5k；角色工具面 ~3.0k–3.7k，仅委派时发生 |
+| 上下文 | 每次搜索 dump、每轮设计稿、每段 diff 都累积进主上下文 | worker 上下文小而专、用完即弃，主 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 白名单不包含它们，角色委派
+才是本 preset 的主路径）。
+
+架构图（主 agent 工具面与四个角色委派；完整 allow 列表见「角色与工具面」一节）：
+
+```
+┌─ 主 agent · orchestrator（编排模式 preset，白名单 21 项）────────────────┐
+│ 委派   : search_external / design / implement / search_internal_deep     │
+│ 管理   : send_message / list_agents / interrupt_agent                    │
+│ 内部搜索: glob / grep / read / read_image / bash   ◄── 热路径，零委派直达  │
+│ 协调   : todo_write / ask_user_question / get_goal / create_goal /       │
+│          update_goal / exit_plan_mode / job_output / job_list / job_kill │
+│ 职责   : 拆任务 → 内部问题自解 → 调研/设计/实现/全仓深搜才委派 → 只集成摘要  │
+└───────┬───────────────┬───────────────┬───────────────┬──────────────────┘
+        │               │               │               │
+        ▼               ▼               ▼               ▼
+   search_external  design          implement      search_internal_deep
+   （外部调研·按需）  （设计·按需）     （实现·按需）     （全仓深搜·按需）
+        │               │               │               │
+        ▼               ▼               ▼               ▼
+   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/          无网络）
+                    job_kill         create_goal/update_goal
+```
+
+## 成本账：工具开销与上下文
+
+本 preset 的核心收益是**按需加载 + 上下文隔离**，工具开销只是最直观的一部分。每请求工具开销估算值如下
+（来源：`agent.cordis.yml` 文件头注释与实测校准；数字为量级估算）：
+
+| 方案 | 工具面 | tokens/请求 | 备注 |
+|---|---|---|---|
+| 单体（现状，未裁剪） | 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 | 仅实际委派实现时才产生 |
+| search_internal_deep 子 agent | 10 项 allow | 未单独估算 | 仅实际委派全仓深搜时才产生 |
+
+注：表中角色工具数按 `agent.cordis.yml` 实际 allow 条目数计（design 13 / implement 16），README 旧表
+中的 14 / 17 与白名单 22 已过时。
+
+**真正的收益是上下文隔离，而不是省下的几千 token 本身**：
+
+- 单体 agent 的上下文会累积每一次搜索 dump、每一轮设计稿、每一段 diff——即使某工具本请求没用上，
+  它过往的产物仍占着窗口；
+- 编排架构里每个 worker 上下文小而专（各自只带本角色的工具与产物），角色默认 one-shot、用完即弃；
+  主 agent 只接收结构化摘要并集成，不会把子 agent 的完整上下文倒进自己的窗口；
+- 因而主 agent 的窗口大小与"本轮派了多少活"解耦，长会话的 token 水位主要由编排者自身的
+  摘要与决策构成（配合压缩治理，见「Token 治理（性能调优）」一节）。
+
+**技能目录注入对主 agent 归零**（实测技能目录注入 ≈1.3k tokens/轮——目录 4455 字节 / 10 技能——
+随注册层 deny 一并归零，机制见「原理」之 ⑤）。主 agent 不使用
+`skill` 工具时仍然要能按需用技能，两条通道：
+
+- `main_agent_skills`（软引导，默认通道）：每个技能在主 agent persona 里只占一行（技能名 + 描述 +
+  SKILL.md 路径），目录注入为零；主 agent 任务匹配到该技能时用自带的 read 按需读全文再遵循，
+  未用到零花费；
+- `main_agent_skills_inline`（可选硬内联）：列出的技能 SKILL.md 全文内联进 persona，每轮固定开销，
+  适合 caveman 这类必须无条件生效的风格技能。
+
+两条通道的配置细节见 [docs/configuration.md](configuration.md)。
+
+## 角色与工具面
+
+### 主 agent 工具面（21 项白名单）
+
+`restrict.mjs` 中硬编码的 `MAIN_AGENT_ALLOW` 共 **21 项**，按用途分四组（顺序同源码注释）：
+
+| 分组 | 工具 |
+|---|---|
+| 角色委派（4；默认全员，可经配置整删三角色） | `search_external` `design` `implement` `search_internal_deep` |
+| 子 agent 管理（3） | `send_message` `list_agents` `interrupt_agent` |
+| 内部搜索·热路径（5） | `glob` `grep` `read` `read_image` `bash` |
+| 协调（9） | `todo_write` `ask_user_question` `get_goal` `create_goal` `update_goal` `exit_plan_mode` `job_output` `job_list` `job_kill` |
+
+**host 工具不在白名单常量内硬编码**：`mcp__*` 与插件工具（codegraph / memory_search / mnemon_* 等）
+是"检测期事实"——主 agent 需要时经配置文件 `$DSH_HOME/dsh-paoding.config.yml` 的 `main_agent_extra`
+勾选，生成层按运行时检测把仍启用的注入 restrict 的 `config.allow`，停用即自动清除（详见
+[docs/configuration.md](configuration.md)）。因此主 agent 的默认面**不包含** `web_search`、全部
+`mcp__tavily__*`、`write` / `edit` / `str_replace_editor`、`skill`、`workflow`、`ralph` 及未过滤的
+`subagent` / `subagent_fork`——这些要么属于角色子 agent，要么成本被刻意清零。
+
+### 内置角色总览
+
+每个角色是一个 `dsh-tool-subagent` 实例：主 agent 调用哪个委派工具，即选择该子 agent 的工具面
+（子 agent 创建时按 `toolFilter` 做 `tools.restrict()`，见「原理」之 ④）。
+主 agent persona 中的角色人设文本与委派失败处理 SOP 见
+[docs/orchestration.md](orchestration.md)。
+
+内置四角色只是**出厂分工**：任何「工具 + 技能」组合都能以同一机制成为新委派工具——在配置文件 `roles`
+键写一个 toolName（或经向导 / 配置 UI 新建），安装器生成 `delegation-<toolName>` 块、把 toolName
+注入主 agent 白名单，并把角色 persona 首行职责句自动追加为主 agent persona 的委派行（tools 为空的
+角色应用时会被拒绝安装），详见 [docs/configuration.md](configuration.md) 第 6 节；自定义角色同样支持 `model` / `provider` 专用模型（与内置角色同一子键、同一生成机制，见 2.5）。例如建一个装配 `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，仅委派时 |
+| `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 节）。
+
+### 角色 toolFilter.allow 明细
+
+以下 allow 列表逐字抄录自 `agent.cordis.yml`（安装期生成器会按运行时检测到的 host 工具对列表做
+「配置/静态意图 ∩ 实际检测工具」重写，见 [docs/configuration.md](configuration.md)）。
+
+**`search_external`（外部调研，10 项）**
+
+| 字段 | 值 |
+|---|---|
+| persona 职责 | 只做联网调研并返回结构化研究摘要（发现、来源、待答问题）；绝不修改文件 |
+| 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 项）**
+
+| 字段 | 值 |
+|---|---|
+| 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，仅实际委派设计时发生 |
+
+**`implement`（实现，16 项）**
+
+| 字段 | 值 |
+|---|---|
+| 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，仅实际委派实现时发生 |
+
+**`search_internal_deep`（全仓深搜，10 项）**
+
+| 字段 | 值 |
+|---|---|
+| persona 职责 | 只做仓库探索：不改文件、不联网；处理全仓 grep dump、超页大文件通读、跨目录符号/定义追踪；搜索透彻后返回浓缩结构化摘要（搜了什么、关键文件与行号、找到的定义/符号、供决策的结论），绝不回灌大 dump |
+| toolFilter.allow | `glob`、`grep`、`read`、`read_image`、`bash`、`ask_user_question`、`todo_write`、`job_output`、`job_list`、`job_kill` |
+| 加载成本 | 未单独估算，仅实际委派全仓深搜时发生 |
+
+> 注：`codegraph` 与 `memory_search` 已于 2026-09-02 从该角色移除——二者对应插件（codegraph MCP /
+> magic-memory）停用时不在子 agent 可见注册面内，`tools.restrict()` 会以 unknown tools 拒绝创建该角色；
+> 重新启用插件后按需加回即可（列表精确名匹配，不支持 glob，见「已知边界」一节）。
+
+## 原理：对应 DSH 原生机制
+
+本 preset 不发明新机制——每一层都落在 DSH 已有的原生能力上，只是把它们组合起来。以下按设计决策逐条说明
+（首版曾因遗漏①而运行失败，教训已固化为①的设计约束，现为组合的必选项）。
+
+**① 基础工具注册在 preset 层，orchestrator 必须全量组合 standard preset。** DSH 中 read/write/edit/
+glob/grep/bash/skill/web_search 等基础工具**不由 global 层提供**，而是由 builtin `standard` preset 的
+组合挂载。因此 orchestrator 组合必须原样包含 standard 的全部行——tool-bash / tool-pwsh / fs /
+fs-search / jobs / skill / goal / planning / compaction / delegation / ask-user / todo / web——否则子
+agent 创建时 `tools.restrict()` 会报 `unknown global tools`。这是设计上的硬约束：子 agent 继承的是
+**组合自身注册的工具**，组合缺一行，对应工具就在子 agent 注册面中缺席。host 层（如
+`~/.dsh/cordis.patch.yml`）只挂 MCP 服务器与本地插件工具。
+
+**② 主 agent 工具面裁剪 = 瀑布过滤器按白名单过滤模型可见面。** `restrict.mjs` 挂在
+`system-prompt/assemble` 瀑布上（`prepend: true` 使过滤器位于最外层，`await next()` 看到下游完整组装
+结果后再按白名单过滤 `assembly.tools`）。设计要点：
+
+- **失败自动放行（fail-open）**：过滤器自身任何异常都返回未过滤的组装结果，一个过滤 bug 永远不会
+  锁死会话的每次请求；
+- **空 allow 拒绝加载**：`config.allow` 为空列表时 `apply()` 直接抛 `TypeError`——防止把主 agent 的
+  全部工具剥光（安装期生成器也会拦截"移除结果为空"）。
+
+**③ 主/子 agent 的区分靠会话 header。** 子 agent 会话的 header 带 `origin: 'subagent'`
+（`delegationDepth >= 1` 兜底，见 dsh-subagent 的 childSessionMeta）。瀑布对子 agent 放行——角色的
+工具面已由各自 `toolFilter` 约束，主 agent 的过滤器若再套一层会与角色面取交集、错误收窄它们。
+
+**④ 角色子 agent 工具面 = per-child `tools.restrict()`。** 每个角色是 `dsh-tool-subagent` 实例，声明
+`toolName`（主 agent 调用的工具名）与 `toolFilter.allow`。子 agent 创建时对子上下文
+`childCtx.tools.restrict(toolFilter)`：allow 名必须在子 agent 可见注册面（= 本组合全量 + host 层
+MCP/插件）内，否则创建被拒（unknown tools）。因此「主 agent 调哪个工具 = 选哪个工具面」；未被
+`toolFilter` 显式允许的工具对子 agent 完全不可见。
+
+**⑤ 主 agent 技能目录归零需要两层过滤。** 只把 `skill` 从模型可见面滤掉是不够的：
+`dsh-tool-skill` 的目录注入守卫查的是**注册面可见性**（`ctx.tools.get('skill', agent)`）而非模型可见
+面，仅 prompt 级过滤挡不住目录注入（实测目录 4455 字节 / 10 技能 ≈1.3k tokens/轮）。于是：
+
+- `system-prompt/assemble` 瀑布把 `skill` 从主 agent 模型可见面滤掉（第一层）；
+- `MAIN_AGENT_REGISTRY_DENY = ['skill']` 在 `agent/created` 时对主 agent 注册面做 deny（第二层），
+  目录注入随即停止、成本归零；
+- 子 agent 豁免：其工具面来自各委派的 `toolFilter`，且按 agent 的 restrict 不跨作用域层传播（子作用域
+  是共享常驻挂载下的兄弟，不是主 agent 作用域的后代）；
+- design/implement 等子 agent 保留 `skill`——DSH 无按 agent 的目录过滤，目录按 cwd 收集后对子 agent
+  全量可见，由其 persona 软引导使用；若显式把 `skill` 加回主 agent 的 allow，注册层 deny 自动跳过，
+  主 agent 重新接入目录。
+
+**⑥ 角色人设 = `dsh-tool-subagent` 的 `persona` 字段。** 每个委派实例自带 persona（子 agent 的
+deployment:persona 段落），内容含角色职责边界与失败汇报协议；主 agent persona 内另有委派失败处理
+SOP（按 stop reason 分流：error 重委派一次 / max-tokens 拆小 / refusal 不重试 / aborted 仅意外取消才
+重试 / 产出差带具体缺失点补做；同一任务失败两次即停止，向用户报告；重委派必须携带上次集成摘要），
+详见 [docs/orchestration.md](orchestration.md)。
+
+**⑦ 热插拔 = preset 是静态目录。** 安装、卸载、修改都是文件操作：生成器把静态源复制/改写为
+`$DSH_HOME/.agent-presets/orchestrator`，编辑 YAML / mjs、重跑生成器、重启 host 或新建会话即生效；
+卸载即删目录。DSH 源码零改动，preset 可整体移除、不残留。
+
+## Token 治理（性能调优）
+
+本节把长会话的 token 治理写成基准式说明：现象（测量口径）→ 根因 → 已落地配置 → 可调参数。
+
+**现象与基准（2026-08-20 校准）。** 同一工作目录、同等任务下，长会话 DSH 的平均每请求 token 约为对照
+实现的 ~2 倍。排除了工具输出截断口径差异（read 默认 2000 行 + 50KB 字节 cap、bash tail+spill 写盘、
+grep inline cap 与对照同设计）后，根因锁定为：**默认压缩从未触发**。`dsh-compaction-basic` 默认
+`thresholdRatio: 0.8`——在 256K token 窗口中要到 ≈209,715 tokens 才压缩——长会话的每请求 token 裸涨到
+~137K–142K 稳态且从不回落（水位始终低于触发线）。对照实现同项目会话全部发生过周期压缩，历史被周期性
+压回。
+
+**已落地配置。** `agent.cordis.yml` 的 compaction-basic 已设 `thresholdRatio: 0.45`（≈117,965 tokens
+触发），配合 retainRatio 默认保留约 16% 尾部（≈42K）+ 摘要 checkpoint，稳态平均回落到 ~80K 量级。
+压缩每次触发调用一次 LLM 摘要——复用前缀缓存，成本极低——因此触发频繁一点也几乎不额外花钱；
+0.45 是「省 token 与不频繁摘要」之间的平衡点。
+
+**参数与效果。**
+
+| thresholdRatio | 触发线（≈） | 稳态平均（≈） | 说明 |
+|---|---|---|---|
+| 0.8（DSH 默认） | 209,715 tokens（窗口 256K） | 137K–142K，不回落 | 长会话几乎不压缩 |
+| 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`
+  截头留尾，防止单条巨型输出撑大窗口；
+- `command-compact`：长会话中可随时手动 `/compact` 即时压缩；
+- `search_internal_deep` 角色：把「全仓 dump」这类大输出隔离出主上下文——热路径（单文件读、精准
+  grep）仍由主 agent 自做、零委派延迟；只有全仓 dump / 大文件通读 / 跨目录符号追踪才委派，子 agent
+  内部消化大输出、只回浓缩摘要（见「角色与工具面」一节）。
+
+## 已知边界
+
+- **角色工具面是静态绑定的**（由配置/`toolFilter.allow` 决定），不是模型在运行时任意指定；
+  「选角色工具 = 选工具面」对固定分工恰好是优点，但无法在对话中临时给某个角色加工具
+  （要加需改配置/静态源后重跑生成器）。
+- **`toolFilter.allow` 是精确名匹配，不支持 glob**：tavily 的 5 个工具必须逐个写全
+  （`mcp__tavily__tavily_search/crawl/extract/map/research`）。
+- **主 agent 白名单里未挂载的工具不会报错**：瀑布过滤只在已解析的 `assembly.tools` 里按名匹配，
+  某工具（如被注释的 MCP）不在其中就只是不出现，安装与运行都静默通过——配置意图与实际挂载
+  靠安装期检测（`install.sh --auto` / `--dry-run`）对齐，改动 host patch 后需重跑。
+- **超大仓库全量探索场景应委派 `search_internal_deep` 而非主 agent 自做**：全仓 grep dump、大文件
+  通读反复灌满主上下文，正是该角色的隔离价值所在（只读、无网络、只回浓缩摘要）。