# 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 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 inherit the conversation**: flip a role's start mode to fork and the helper starts from the main agent's already-completed turns — no restating the context inside every delegation prompt. Every role defaults to a fresh start, so nothing changes until you flip it.
- **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, set a display name for the main agent — all one line of config; a role with a display name also stamps its sub-agent labels with that name (e.g.「民工码农 · 修复标签显示」), so the task-management page, the sub-agent tree and the background-job list all show who is doing what at a glance. 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.
- **Tool entries support wildcards**: `*` and `?` expand into concrete tool names at generation time — one `mcp__tavily__tavily_*` line covers the whole family; zero-match patterns get a warning, and artifacts and runtime behavior stay unchanged.
- **A health check before every save**: preview/apply runs a built-in check — tools configured but not mounted, zero-tool roles, unknown model names, a preset lagging behind the config — each flagged by severity; the preview also lists an itemized "changes since the last save" diff and the main-agent tool-surface stat, so what changed and what it saves are both on the table. On the CLI side, `dsh-paoding doctor` runs six read-only checks (config parses, install track, managed declaration block, orphan directories, version marker, preset drift) in one command; `--fix` automatically repairs the two safe categories (orphan directories, stale declaration rows).
- **Scenario templates swap the roster in one click**: Lite (implement only), Research (search roles only), and Full (everyone on deck, main agent carrying the whole detected inventory) — templates only touch who is present and what the main agent carries; hand-tuned role settings are never touched.
- **Delegation stats you can act on**: the panel's "Delegation" card counts delegations, average duration, and failures per role (last 30 days), aggregated locally from the host session archive — which roles get used, and which keep dropping the ball, at a glance.
- **Config export & import, with an undo**: download `dsh-paoding.config.yml` from the panel's More menu for migration or backup; imports are validated first, and overwriting the whole config (workspaces included) asks for confirmation. Every write first rotates three automatic backups, and "Restore backup" puts one back after a confirming dialog — a mistake never means digging through files.
- **Config over HTTP**: list, create, update, and delete presets through the four `/api/paoding/presets` endpoints, served in-process by the DSH web service and callable over loopback; they ride the panel's Save & Apply generation pipeline and share its write lock, so scripts and automation tools can reshape the roster without opening a browser.
- **Panel in English and Chinese**: every UI string ships in both languages, auto-detected (explicit choice first, then Chinese signals — browser language, host page language, Chinese time zones — outrank English ones, since the Electron shell pins navigator to en-US regardless of the OS), switchable from the More menu and remembered.
- **Notified of new releases, one-click upgrade in the panel**: the panel compares your local version against the latest npm registry publish (npmmirror and GitHub release as successive fallbacks) and points to the release page when a newer one is out. The Upgrade button swaps in the new version in place (profile auto-detected): regular profiles go through `dsh plugin update dsh-paoding`, while the Electron-owned desktop profile — which the dsh CLI guards against — gets a direct `pnpm add dsh-paoding@<version>` run in the profile directory, falling back to `corepack pnpm` when no bare pnpm is on PATH; a DSH restart applies it, and the orchestrator preset regenerates itself against the new version on startup. A dev checkout in link: form cannot be upgraded in place — the panel tells you how to switch back to the registry version. If the check fails (offline, rate-limited), a subdued "version check failed · retry" row stays in the header (full causes and proxy hints in its tooltip) without popping anything up.
- **Installs and uninstalls cleanly**: no DSH source changes; active in a new session right after install, gone when you delete one directory.
- **Works on both host generations**: DSH 0.1.5 through 0.2.1 are all supported (0.1.5 / 0.1.6 / 0.1.7-rc.1 / 0.1.7-rc.2 / 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2+) — the two generations discover presets differently (directory scan vs patch declaration rows), and the installer picks the right landing automatically; from 0.2.0 the workflow worker row in the orchestration composition also adapts to the host version at generation time (0.1.5 uses workflow-worker-thread, 0.1.6+ swaps to workflow-ptc); from DSH 0.2.1 the role delegation rows migrate too (0.2.1's dsh-tool-subagent rejects inline persona/toolFilter — each role gets an AgentPreset holding its persona and a role-restrict tool-surface plugin, selected via agentPreset on the spawn delegation; 0.2.0 and below keep the inline shape). Migration happens on the first save/self-heal after a host upgrade or downgrade (workspace presets, orchestrator-<slug>, are regenerated in the same self-heal pass), all without user action; the 0.2.1 prereleases are subdivided further — the tool-subagent guard landed in 0.2.1-rc.2, so rc.0/rc.1 keep the inline shape.

## Screenshots

![Screenshot 1](docs/images/1.png)

## Quick Start

Prerequisites: **Node.js ≥ 18**, **pnpm**, and a working DSH host (**@deepseek-ai/dsh 0.1.5 – 0.2.1**, all supported — the preset landing and role-row shape adapt to the host version automatically).

**The official plugin channel (the only install route)** — no clone needed; one command, then a restart:

```bash
dsh plugin --profile web add dsh-paoding
```

Equivalent shortcut: `npx dsh-paoding@latest` (delegates to the command above; default profile web; requires dsh on PATH). Whichever version npx pulls is what gets installed: the actual install is `dsh-paoding@<the version npx resolved>`.

`dsh plugin` is a transparent pass-through to pnpm: the package is installed into the profile by pnpm, and the bundle patch declared inside it mounts the 庖丁配置 (Paoding Config) page into the DSH Web left sidebar. **Restart DSH (`dsh web`)** and the install is complete — on startup the plugin checks itself, and if the orchestrator preset is missing or carries an outdated version marker it regenerates it once (applying `~/.dsh/dsh-paoding.config.yml` when present, writing the base template otherwise). Nothing else to click. From DSH 0.1.7 the host discovers presets through patch declaration rows instead, and the plugin switches the registration over by itself — the install steps stay the same. Pick "编排模式 (Orchestrator)" in the new-session preset selector; to make it the default, choose it in Settings → Agent Presets.

Out of the box only DSH's built-in base tools are enabled — detected MCP/host tools are not written in automatically. Open **庖丁配置 (Paoding Config)** in the sidebar, opt into the tools and roles you need, and hit Save & Apply. When you no longer want it, three commands uninstall it for good — the per-workspace presets created by workspace-specific configs are removed too:

```bash
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-*
```

On a DSH 0.1.7+ host there is one extra step: delete the dsh-paoding managed block from `~/.dsh/cordis.patch.yml` (the auto-generated marker comments), so no declaration rows are left pointing at the removed directories (see §7 of the [installation guide](docs/installation_en.md)).

**Dev checkout install** — to hack on the plugin or the preset sources, link the repository directly (changes go live via HMR or a restart):

```bash
git clone https://github.com/lifangjin/dsh-paoding.git
dsh plugin --profile web add link:"$PWD/dsh-paoding"
```

Upgrades go through the panel's Upgrade button (regular profiles: equivalent to `dsh plugin update dsh-paoding`; the desktop profile: a direct `pnpm add` of the exact version in the profile directory, via `corepack pnpm` when no bare pnpm exists). Full steps, upgrading, 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, per-role session modes (one-shot / continuable), per-role start modes (fresh / fork), 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).

Prefer driving it from a script? An HTTP API covers the same ground: `/api/paoding/presets` lists, creates, updates, and deletes presets. It rides the DSH web service (same port you open DSH at in the browser) and answers loopback calls directly:

```bash
curl http://127.0.0.1:19387/api/paoding/presets
```

Writes go through the same generation pipeline and write lock as the panel's Save & Apply. Methods, request bodies, and error semantics are in [section 13 of the configuration guide](docs/configuration_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) | The single official channel (`dsh plugin add`), version support and the dual preset landing (DSH 0.1.5 – 0.2.1), first-install automation and the version marker, upgrading, dev-checkout install, host patch detection, the Paoding Config panel, uninstalling (one `dsh-paoding uninstall` command), troubleshooting (doctor with `--fix`). |
| [Orchestration](docs/orchestration_en.md) | Orchestration overview, how failures surface and the three recovery layers, one-shot vs continuable, context isolation. |
| [Configuration](docs/configuration_en.md) | The full key reference, tool-entry wildcards, tuning built-in roles, main-agent tools and skills, custom roles, per-role models, per-role session and start modes, scenario templates, config export/import and backup-rollback, health-check hints, the HTTP API. |

## 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/`.

## License

Released under the [MIT License](LICENSE); see the `LICENSE` file at the repository root for the full terms.