dsh-root-planner-preset 1.0.1 → 1.0.3

package/.github/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+Thanks for looking. This repository is meant to be maintained by more than its
+author — the license is [MIT](../LICENSE), and issues and pull requests are open
+to anyone.
+## The one thing to know first
+
+**`cordis.patch.yml` is generated. Do not edit it by hand.**
+
+It is produced from `persona.txt` by `build-patch.mjs`, and it has to be indented
+into a YAML block scalar exactly — a single mis-indented line silently truncates
+the ~6 KB persona, which is very hard to spot in review and easy to introduce by
+hand. That is the whole reason the generator exists.
+
+So to change what the agent is told:
+
+```sh
+$EDITOR persona.txt
+node build-patch.mjs      # regenerates cordis.patch.yml
+node verify-patch.mjs     # must print ALL CHECKS PASSED
+```
+
+Commit **both** files. CI re-runs the generator and fails if the committed patch
+does not match `persona.txt` byte for byte, so forgetting the second command is
+caught for you.
+
+## Setup
+
+The bundle itself ships no dependencies. The repository's scripts need one YAML
+parser, which `lib-yaml.mjs` resolves from your own DSH installation — or from a
+local install:
+
+```sh
+npm ci        # installs js-yaml, the only devDependency
+```
+
+## What the checks mean
+
+`node verify-patch.mjs` asserts, among other things:
+
+- the patch parses as loader YAML (including the `!!js` scalars, read as opaque);
+- the persona parsed out of the patch is **byte-identical** to `persona.txt`;
+- both delegation tools publish `subagent` / `subagent_fork`;
+- both `toolFilter.allow` masks exclude every mutation entry point
+  (`write`, `edit`, `ops_replace`, `ops_bash`, `pwsh`) and name **only tools that
+  exist** — a name that is not a registered global tool makes
+  `tools.restrict()` throw the first time a subagent is created.
+
+That last point is the most likely thing to need changing on your machine: the
+mask was written against the author's profile. If your profile registers a
+different set of global tools, the mask is what has to adapt — edit the list near
+the bottom of `verify-patch.mjs` in the same commit.
+
+`node verify-depth-override.mjs` checks the delegation depth override. Depth is a
+**Host setting, not part of this bundle**, so on a machine that never set it the
+script prints `SKIP` and explains why. That is a pass, not a failure.
+
+## Most valuable contributions, in order
+
+1. **Bug reports with real error text**, plus your DSH version and which global
+   tools your profile registers. The `Not verified` section of the
+   [README](../README.md) names exactly where this matters: no subagent has been
+   spawned under this preset in the author's environment to date.
+2. **Mask fixes for other environments** — see above.
+3. **Persona improvements** — the text itself, when you have an observed failure
+   it would have prevented.
+4. **Documentation and translations** — [README.zh.md](../README.zh.md) and
+   [INSTALL.md](../INSTALL.md) especially.
+
+## Ground rules
+
+- **One concern per pull request.** A persona change and a mask change are two
+  pull requests unless one requires the other.
+- Say which preset you tested with, and on which platform.
+- Do not weaken the read-only guarantee. `write`, `edit`, `ops_replace`,
+  `ops_bash` and `pwsh` must stay out of the child mask; that property is the
+  point of the preset, so a change that removes it will be declined.
+- Keep `main` linear — the branch protection refuses merge commits, so rebase
+  rather than merge.
+
+## How `main` is protected
+
+`main` requires the `verify` status check (strict: the branch must be up to date),
+refuses force pushes and deletions, requires linear history, and requires
+conversations to be resolved. The repository owner can bypass these for a direct
+push in an emergency; **collaborators cannot** — send a pull request and let CI
+run.
+
+If you are added as a collaborator and want to be able to merge your own pull
+requests without waiting for the owner, say so: review requirements are off
+deliberately, because a single-maintainer repository that requires an approval it
+cannot get would deadlock.

package/.github/workflows/verify.yml

@@ -0,0 +1,51 @@
+# Verifies the bundle on every push and pull request.
+#
+# Two failure modes this exists to catch, both of which are silent locally:
+#
+#  1. `cordis.patch.yml` is generated from `persona.txt`. Someone edits the
+#     generated file by hand (or edits persona.txt and forgets to regenerate), and
+#     the persona the preset actually ships no longer matches the source. The
+#     generator is deterministic, so re-running it and diffing the result catches
+#     exactly that drift.
+#  2. A change to the child tool mask names a tool that is not a registered global
+#     tool. `tools.restrict()` throws on an unknown name at child-creation time, so
+#     this only surfaces the first time a subagent is actually spawned — never in a
+#     local syntax check.
+#
+# The bundle itself ships no dependencies; `js-yaml` is a devDependency of this
+# repository only, and `lib-yaml.mjs` picks it up from the checkout.
+
+name: verify
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install the local YAML parser
+        run: npm ci --ignore-scripts
+
+      - name: The committed patch matches persona.txt
+        run: |
+          node build-patch.mjs
+          if ! git diff --exit-code -- cordis.patch.yml; then
+            echo "::error file=cordis.patch.yml::cordis.patch.yml is out of date. Run 'node build-patch.mjs' and commit the result instead of editing it by hand."
+            exit 1
+          fi
+
+      - name: Patch structure, persona byte-identity and the child tool mask
+        run: node verify-patch.mjs

package/INSTALL.md

@@ -2,7 +2,7 @@
 
 面向**接收方**。本包是一个 DSH agent 预设（bundle），不改动 DSH 本体。
 
-[返回中文说明](README.md) | [维护者文档](docs/DEVELOPMENT.md)
+[English README](README.md) | [中文说明](README.zh.md) | [维护者文档](docs/DEVELOPMENT.md)
 
 ## 一、前置条件
 
@@ -32,27 +32,35 @@ web_search  web_fetch
 
 ## 二、安装
 
-三种方式任选，推荐第 1 种。
+四种方式任选，推荐第 1 种。
 
-### 方式 1：命令行（推荐）
+### 方式 1：npm（推荐）
 
 ```sh
-dsh plugin --profile web add github:XiaoOu2024/dsh-root-planner-preset
+dsh plugin --profile web add dsh-root-planner-preset
 ```
 
-装完重启 `dsh web`。
+已发布在 npm：<https://www.npmjs.com/package/dsh-root-planner-preset>。这是**预构建安装**，跳过 pnpm 的构建授权步骤，最省事。
+
+> 也可以钉版本：`dsh plugin --profile web add dsh-root-planner-preset@1.0.0`
+
+### 方式 2：GitHub 源码
+
+```sh
+dsh plugin --profile web add github:XiaoOu2024/dsh-root-planner-preset
+```
 
-> 也可以指定版本或分支：`github:XiaoOu2024/dsh-root-planner-preset#v1.0.0`
+> 也可以指定分支或 tag：`github:XiaoOu2024/dsh-root-planner-preset#v1.0.0`
 
-### 方式 2：让 DSH 里的 agent 装
+### 方式 3：让 DSH 里的 agent 装
 
 对 agent 说：
 
-> 用 `plugin_manager` 的 `install_bundle`，target 填 `github:XiaoOu2024/dsh-root-planner-preset`
+> 用 `plugin_manager` 的 `install_bundle`，target 填 `dsh-root-planner-preset`（或 `github:XiaoOu2024/dsh-root-planner-preset`）
 
 注意：这个工具调用需要 **Full access** 权限或当次授权。
 
-### 方式 3：先克隆再按路径装
+### 方式 4：先克隆再按路径装
 
 ```sh
 git clone https://github.com/XiaoOu2024/dsh-root-planner-preset
@@ -60,6 +68,8 @@ git clone https://github.com/XiaoOu2024/dsh-root-planner-preset
 
 然后让 agent 用 `install_bundle`，target 填**克隆下来的绝对路径**。
 
+装完重启 `dsh web`。
+
 ### ❌ 不适用：插件市场界面
 
 **「设置 → 插件市场」搜不到本包，属正常。** dsh-market 只允许安装 `awesome-dsh-plugin` 精选列表内的来源，本包不在其中。请用上面三种方式。
@@ -97,7 +107,7 @@ git clone https://github.com/XiaoOu2024/dsh-root-planner-preset
 |---|---|---|
 | 预设列表里**没有 Root Planner** | bundle 没装上，或预设行激活失败（会带诊断留在名册上） | 看 DSH 的插件/加载诊断；多半是第 1 条前置不满足——本包的补丁引用了随包预设里不存在的工具行 |
 | DSH **启动失败**（进程直接退出） | DSH 启动是全有全无，一个插件加载失败整个进程就退出 | 用插件市场的「**调整插件**」恢复界面：DSH 点名的插件会标红并默认取消勾选，勾好再启动。找不到该界面时，手工编辑 profile 的 `cordis.patch.yml` 把对应行设为 `disabled: true` |
-| 子代理创建失败，报 **`tools.restrict() names unknown global tool …`** | 白名单里有你的环境**没注册**的工具名 | 按报错里点出的名字，从 `cordis.patch.yml` 两个 `toolFilter.allow` 里删掉该行，重装或重开会话 |
+| 子代理创建失败，报 **`tools.restrict() names unknown global tool …`** | 白名单里有**不是全局工具**的名字。注意有两种情况：①你的环境根本没注册该工具；②它是**agent 作用域**工具（如 `subagent`，它注册在每个被组合 Agent 自身的作用域里），而 `toolFilter` **只接受全局工具名** | 报错里会列出该环境全部的全局工具名，照着它删掉白名单里那几个不存在的名字。白名单在 `cordis.patch.yml` 的两个 `toolFilter.allow` 处（或在 `child-tools.mjs` 里改后重跑生成器），改完必须重开会话 |
 | 委派立刻返回**深度错误** | `maxDepth` 没设或设得太小 | 见第三节，设为 `2` |
 | 子代理**什么都不能读** | 白名单过窄（比如你删过头了） | 至少保留 `read`、`glob`、`grep`、`ops_inspect_local_file`、`ops_glob`、`ops_grep` |
 | 子代理**还是能改文件** | 白名单被改坏了 | 确认 `cordis.patch.yml` 里两处 `toolFilter.allow` 都**不含** `write`、`edit`、`ops_replace`、`ops_bash`、`pwsh`；改完必须重开会话 |

package/README.md

@@ -1,82 +1,111 @@
 # dsh-root-planner-preset
 
-一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的 agent 预设：**把「读书」和「决策」分开**。
+An agent preset for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) that **separates reading from deciding**.
 
-根 agent 的上下文只装任务分析、规划与决策；文件阅读、信息查询交给子代理，子代理只回摘要。而**创建、修改、删除文件只能由根 agent 执行**——子代理连工具都没有。
+The root agent's context holds task analysis, planning and decisions; file reading and information queries go to subagents that return summaries only. Creating, modifying and deleting files stays with the root agent — subagents do not even have the tools.
 
-> 一句话：让整棵树里只有一个 agent 有手，其余都只有眼睛。
+> One agent in the tree has hands. Every other agent has only eyes.
 
-[安装步骤](INSTALL.md) | [维护者文档](docs/DEVELOPMENT.md)
+[中文说明](README.zh.md) | [Install](INSTALL.md) | [Maintainer notes](docs/DEVELOPMENT.md)
 
-## 它解决什么问题
+## The problem it solves
 
-用 coding agent 干长任务，上下文很快被原始文件内容塞满，于是忘了目标、丢了计划、开始重复劳动。常见对策是「让 agent 多派子代理」，但光靠提示词约束不住——子代理照样会顺手改文件，任务也会被无限往下转派。
+On a long task a coding agent's context fills up with raw file contents, and it forgets the goal, loses the plan, and starts repeating work. The usual answer — "delegate more to subagents" — does not hold on its own: a subagent will still edit files on its way past, and work gets passed further down without limit.
 
-这个预设把两件事做成了结构约束，而不是靠自觉：
+This preset turns both of those into structural constraints rather than good intentions:
 
-| 要求 | 机制 | 强度 |
+| Requirement | Mechanism | Strength |
 |---|---|---|
-| 子代理**不能**创建/修改/删除文件 | 两个委派工具上的 `toolFilter.allow` 白名单，不含 `write`、`edit`、`ops_replace` | **结构性**：工具不存在，调不到 |
-| 子代理**没有** shell 可绕过 | 同一白名单，不含 `ops_bash`、`pwsh` | **结构性** |
-| 任务不会被无限转派 | 运行时深度上限（`subagent.maxDepth`） | **结构性**：超过上限直接抛 `SubagentDepthError` |
-| 根 agent 独揽所有修改 | 人设规则（白名单只作用于子级） | 提示词级 |
-| 根 agent 默认委派阅读 | 人设规则 | 提示词级 |
+| Subagents **cannot** create, modify or delete files | A `toolFilter.allow` list on both delegation tools, without `write`, `edit`, `ops_replace` | **Structural**: an absent tool cannot be called |
+| Subagents **have no shell** to work around it | The same list, without `ops_bash`, `pwsh` | **Structural** |
+| Subagents cannot delegate further | The same list cannot name the spawn tool, *and* the runtime depth cap | **Structural**, twice over — see below |
+| The root agent owns every mutation | Persona rules (the mask applies to children only) | Prompt-level |
+| The root agent delegates reading by default | Persona rules | Prompt-level |
 
-白名单是 **allow 而非 deny**：将来某个插件新增的工具，对子代理默认不可见。
+The mask is an **allow** list, not a deny list: a tool added by a future plugin is invisible to subagents until it is added here.
 
-## 工作方式
+## How it works
 
 ```
-根 agent (depth 0)          ← 只有它有 write / edit / shell
-├── 子代理 (depth 1)        ← 只读；可以再派一层
-│   └── 孙代理 (depth 2)    ← 只读；叶子
-└── 子代理 (depth 1)
+root agent    <- the only one with write / edit / shell
+└── subagent  <- read-only, and cannot delegate further
 ```
 
-- **根 agent**：先立计划（目标、成功判据、约束、任务清单），把阅读/搜索/定位默认派出去，自己只在「单个已知文件、一小段范围、或核实子代理的某个断言」时才亲自读。
-- **子代理**：只读、只定位、只总结。发现**需要改文件**时不动手，而是回报精确的改动方案——目标路径、位置（file:line）、当前内容、建议替换、理由。
-- **根 agent 收到方案后决策**，然后亲自落盘。
+The tree is two levels, enforced twice over. The runtime depth cap does it, and so
+does the mask: `subagent` is mounted inside each composed Agent's own scope rather
+than globally, while a `toolFilter` accepts global tool names only — so a child
+cannot even name it. An earlier version of this bundle did list `subagent` in the
+mask, and **every subagent creation failed** with
+`tools.restrict() names unknown global tool "subagent"`. Raising the depth setting
+therefore does not re-open delegation; there is no tool left to call.
 
-子代理怎么知道自己是子代理？DSH 会在每个子代理的提示词里强制插入一句 `You are a delegated subagent: …`，运行时注入、无法移除，而预设人设**没有** `{{role}}` 这类变量可用。所以人设里写的是一条**判定指令**：读自己的提示词里有没有那句话。这让人设只需要一份，父与子读到的是同一份文本，因此不会出现「父以为子被这么约束、子其实没读到」的漂移。
+- **Root agent**: plans first (goal, success criteria, constraints, ordered task list), delegates reading, searching and locating by default, and reads directly only for one known file, a short targeted range, or to check a claim a subagent made.
+- **Subagent**: reads, locates and summarizes. On finding that a file **needs changing** it does not act; it reports the exact change — target path, location (`file:line`), current content, proposed replacement, and why.
+- **The root agent decides** on that proposal and then makes the change itself.
 
-## 快速开始
+How does a subagent know it is a subagent? DSH force-inserts the sentence `You are a delegated subagent: …` into every subagent's prompt, injected by the runtime and impossible to remove — while a preset persona has **no** `{{role}}`-style variable available. So the persona states a **test** instead: read your own prompt for that sentence. One persona then serves both roles, and parent and child read the same text, which is what prevents the drift where a parent believes a child is constrained and the child never saw it.
+
+## Quick start
+
+Install from npm (prebuilt, no build-approval step):
+
+```sh
+dsh plugin --profile web add dsh-root-planner-preset
+```
+
+Or straight from GitHub source:
 
 ```sh
 dsh plugin --profile web add github:XiaoOu2024/dsh-root-planner-preset
 ```
 
-装完**必须**再做一步：**设置 → 子智能体 → 深度上限 = `2`**。（这是 Host 的 `subagent` 设置节，**全局生效、不属于** bundle；设成 `0` 会禁掉全部委派，设计就废了。）
+Then **one required step**: set **Settings → Subagents → depth limit** to **`2`**. (This is the Host's `subagent` settings section — global, and **not** part of the bundle. Setting it to `0` disables all delegation and breaks the design.)
 
-然后**开新会话**，在预设选择器里选 **Root Planner**。完整步骤与故障排查见 [INSTALL.md](INSTALL.md)。
+Then **start a new session** and pick **Root Planner** in the preset selector. Full steps and troubleshooting are in [INSTALL.md](INSTALL.md).
 
-## 适合 / 不适合
+## When it fits, and when it does not
 
-**适合**：需要跨很多文件调研的长任务、逆向分析、代码审查，以及任何「读得多、改得少」或「改动必须被仔细决策」的工作。
+**Fits**: long research-heavy tasks across many files, reverse engineering, code review — anything read-heavy, or where a change must be carefully decided.
 
-**不适合**：
+**Does not fit**:
 
-- 只想快速改一个文件——多一层委派是纯粹的开销；
-- 需要子代理**并行写代码**——这是本预设**故意**禁止的，请改用 `standard` 预设；
-- 环境缺少 DSH 的工具基础（见 [INSTALL.md](INSTALL.md) 的前置条件）。
+- changing one file quickly — the extra delegation layer is pure overhead;
+- wanting subagents to **write code in parallel** — this preset forbids that on purpose; use the `standard` preset instead;
+- an environment missing the DSH tooling listed in [INSTALL.md](INSTALL.md).
 
-## 仓库内容
+## Repository contents
 
-| 文件 | 说明 |
+| File | Purpose |
 |---|---|
-| `cordis.patch.yml` | 预设声明（**由脚本生成，不要手改**） |
-| `persona.txt` | 人设正文，**要改就改这个** |
-| `build-patch.mjs` | 从 `persona.txt` 生成 `cordis.patch.yml` |
-| `verify-patch.mjs` | 校验补丁结构、工具白名单，并断言人设逐字节一致 |
-| `verify-depth-override.mjs` | 校验深度覆盖是否落到合成配置 |
-| `lib-yaml.mjs` | 从本地 DSH 安装里解析 YAML，因此本包**零依赖** |
-| `docs/DEVELOPMENT.md` | 维护者文档：设计取舍、机制细节、已验证/未验证边界 |
+| `cordis.patch.yml` | The preset declaration (**generated — do not hand-edit**) |
+| `persona.txt` | The persona prose; **edit this one** |
+| `build-patch.mjs` | Generates `cordis.patch.yml` from `persona.txt` |
+| `verify-patch.mjs` | Checks patch structure and the tool mask, and asserts byte identity of the persona |
+| `verify-depth-override.mjs` | Checks that the depth override reached the composed profile |
+| `lib-yaml.mjs` | Resolves a YAML parser from the local DSH install, so this package has **no dependencies** |
+| `docs/DEVELOPMENT.md` | Maintainer notes: design trade-offs, mechanics, verified/unverified boundaries |
+
+## Verified / not verified
+
+**Verified**: the patch parses as loader YAML; the parsed persona is **byte-identical** to `persona.txt`; both delegation masks exclude every mutation entry point and name only tools the runtime reports as global; a clean checkout passes verification (`.gitattributes` pins LF, without which a Windows clone breaks the byte-identity check); the depth override reached the composed profile.
+
+**Fixed after a real failure**: a subagent spawn on a live `root-planner` session failed with `tools.restrict() names unknown global tool "subagent"`. The cause was a design error in this bundle, not a misconfiguration — `subagent` is registered inside each composed Agent's own scope, and a `toolFilter` takes global names only. The mask no longer names it, `verify-patch.mjs` now asserts its absence by intent, and the mask is defined once in `child-tools.mjs` so the generator and the verifier cannot drift apart.
+
+**Still not verified**: no subagent has been spawned successfully under this preset yet — the failure above is the only end-to-end evidence there is. The global-tool inventory in `verify-patch.mjs` was transcribed from that runtime error; if your profile registers a different set, the mask is what has to adapt.
+
+## Contributing
+
+Issues and pull requests are welcome — this repository is meant to be maintained by more than its author. The license is [MIT](LICENSE), so forking, modifying and redistributing are all permitted. **[CONTRIBUTING.md](.github/CONTRIBUTING.md) has the workflow, the checks, and the ground rules** — read it before changing the persona.
 
-## 已验证 / 未验证
+Useful contributions, roughly in order of value:
 
-**已验证**：补丁可被 loader 解析；解析出的人设与 `persona.txt` **逐字节相同**；两个委派工具的白名单排除了所有写入入口、且只包含本机实际注册的工具名；干净检出后校验通过（`.gitattributes` 已钉死 LF，否则 Windows 克隆会破坏逐字节校验）；深度覆盖已落到合成配置。
+- **Report what broke**, with the error text and your DSH version. The unverified area above is exactly where real reports matter most.
+- **Report a mask mismatch** on your platform: which global tools your profile registers and which name the mask got wrong.
+- **Improve the persona** (`persona.txt`) — but run `node build-patch.mjs && node verify-patch.mjs` and include the result, since `cordis.patch.yml` is generated and a hand-edited one will be rejected.
+- **Translate or fix the docs** — [README.zh.md](README.zh.md) and [INSTALL.md](INSTALL.md).
 
-**未验证**：**尚未在 `root-planner` 预设下真正派出过一个子代理。** 白名单里的工具名是按作者环境的实际工具清单交叉核对出来的，不是运行时实测。若你的环境缺少其中某个全局工具名，子代理创建会失败并报 `tools.restrict() names unknown global tool …`。详见 [INSTALL.md](INSTALL.md) 的故障排查。
+Please keep a change to one concern per pull request, and say which preset it was tested with.
 
-## 许可
+## License
 
 [MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,105 @@
+# dsh-root-planner-preset
+
+一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的 agent 预设：**把「读书」和「决策」分开**。
+
+根 agent 的上下文只装任务分析、规划与决策；文件阅读、信息查询交给子代理，子代理只回摘要。而**创建、修改、删除文件只能由根 agent 执行**——子代理连工具都没有。
+
+> 一句话：让整棵树里只有一个 agent 有手，其余都只有眼睛。
+
+[English](README.md) | [安装步骤](INSTALL.md) | [维护者文档](docs/DEVELOPMENT.md)
+
+## 它解决什么问题
+
+用 coding agent 干长任务，上下文很快被原始文件内容塞满，于是忘了目标、丢了计划、开始重复劳动。常见对策是「让 agent 多派子代理」，但光靠提示词约束不住——子代理照样会顺手改文件，任务也会被无限往下转派。
+
+这个预设把两件事做成了结构约束，而不是靠自觉：
+
+| 要求 | 机制 | 强度 |
+|---|---|---|
+| 子代理**不能**创建/修改/删除文件 | 两个委派工具上的 `toolFilter.allow` 白名单，不含 `write`、`edit`、`ops_replace` | **结构性**：工具不存在，调不到 |
+| 子代理**没有** shell 可绕过 | 同一白名单，不含 `ops_bash`、`pwsh` | **结构性** |
+| 子代理不能再往下派 | 同一白名单无法写上 spawn 工具名，**且**运行时深度上限 | **双重结构性**，见下 |
+| 根 agent 独揽所有修改 | 人设规则（白名单只作用于子级） | 提示词级 |
+| 根 agent 默认委派阅读 | 人设规则 | 提示词级 |
+
+白名单是 **allow 而非 deny**：将来某个插件新增的工具，对子代理默认不可见。
+
+## 工作方式
+
+```
+根 agent     ← 只有它有 write / edit / shell
+└── 子代理   ← 只读，且不能再往下派
+```
+
+树只有两层，而且是**双重强制**的：运行时深度上限挡一层，白名单再挡一层。因为 `subagent` 是注册在每个被组合 Agent **自身作用域**里的，而 `toolFilter` 只接受全局工具名——子代理连它的名字都写不上。本包早期版本确实把 `subagent` 写进了白名单，结果是**每一次子代理创建都失败**，报 `tools.restrict() names unknown global tool "subagent"`。所以调高深度设置也不会重新打开委派：已经没有可调用的工具了。
+
+- **根 agent**：先立计划（目标、成功判据、约束、任务清单），把阅读/搜索/定位默认派出去，自己只在「单个已知文件、一小段范围、或核实子代理的某个断言」时才亲自读。
+- **子代理**：只读、只定位、只总结。发现**需要改文件**时不动手，而是回报精确的改动方案——目标路径、位置（file:line）、当前内容、建议替换、理由。
+- **根 agent 收到方案后决策**，然后亲自落盘。
+
+子代理怎么知道自己是子代理？DSH 会在每个子代理的提示词里强制插入一句 `You are a delegated subagent: …`，运行时注入、无法移除，而预设人设**没有** `{{role}}` 这类变量可用。所以人设里写的是一条**判定指令**：读自己的提示词里有没有那句话。这让人设只需要一份，父与子读到的是同一份文本，因此不会出现「父以为子被这么约束、子其实没读到」的漂移。
+
+## 快速开始
+
+推荐从 npm 安装（预构建，免构建授权步骤）：
+
+```sh
+dsh plugin --profile web add dsh-root-planner-preset
+```
+
+或直接从 GitHub 源码安装：
+
+```sh
+dsh plugin --profile web add github:XiaoOu2024/dsh-root-planner-preset
+```
+
+装完**必须**再做一步：**设置 → 子智能体 → 深度上限 = `2`**。（这是 Host 的 `subagent` 设置节，**全局生效、不属于** bundle；设成 `0` 会禁掉全部委派，设计就废了。）
+
+然后**开新会话**，在预设选择器里选 **Root Planner**。完整步骤与故障排查见 [INSTALL.md](INSTALL.md)。
+
+## 适合 / 不适合
+
+**适合**：需要跨很多文件调研的长任务、逆向分析、代码审查，以及任何「读得多、改得少」或「改动必须被仔细决策」的工作。
+
+**不适合**：
+
+- 只想快速改一个文件——多一层委派是纯粹的开销；
+- 需要子代理**并行写代码**——这是本预设**故意**禁止的，请改用 `standard` 预设；
+- 环境缺少 DSH 的工具基础（见 [INSTALL.md](INSTALL.md) 的前置条件）。
+
+## 仓库内容
+
+| 文件 | 说明 |
+|---|---|
+| `cordis.patch.yml` | 预设声明（**由脚本生成，不要手改**） |
+| `persona.txt` | 人设正文，**要改就改这个** |
+| `build-patch.mjs` | 从 `persona.txt` 生成 `cordis.patch.yml` |
+| `verify-patch.mjs` | 校验补丁结构、工具白名单，并断言人设逐字节一致 |
+| `verify-depth-override.mjs` | 校验深度覆盖是否落到合成配置 |
+| `lib-yaml.mjs` | 从本地 DSH 安装里解析 YAML，因此本包**零依赖** |
+| `docs/DEVELOPMENT.md` | 维护者文档：设计取舍、机制细节、已验证/未验证边界 |
+
+## 已验证 / 未验证
+
+**已验证**：补丁可被 loader 解析；解析出的人设与 `persona.txt` **逐字节相同**；两个委派工具的白名单排除了所有写入入口、且只包含**运行时报告的全局工具**；干净检出后校验通过（`.gitattributes` 已钉死 LF，否则 Windows 克隆会破坏逐字节校验）；深度覆盖已落到合成配置。
+
+**因一次真实故障而修复**：在跑着 `root-planner` 的会话里创建子代理失败，报 `tools.restrict() names unknown global tool "subagent"`。根因是本包**设计上的错误**，不是配置错误——`subagent` 注册在每个被组合 Agent 自身的作用域里，而 `toolFilter` 只接受全局工具名。现在白名单不再写它，`verify-patch.mjs` 会**按意图断言它必须缺席**，白名单也收敛到 `child-tools.mjs` 单一真源，生成器与校验脚本不可能再各说各话。
+
+**仍未验证**：还没有一次**成功**的子代理派出——上面那次失败是目前唯一的端到端证据。`verify-patch.mjs` 里的全局工具清单就是**从那次的运行时报错里抄下来的**；你的 profile 若注册了不同的集合，需要改的是白名单。
+
+## 参与维护
+
+**欢迎提 issue 和 PR——这个仓库本来就打算由作者之外的人一起维护。** 许可证是 [MIT](LICENSE)，fork、修改、再分发都是允许的。**[CONTRIBUTING.md](.github/CONTRIBUTING.md) 写清了流程、校验项和底线要求**，改人设之前请先读它。
+
+按价值排序，有用的贡献大概是这样：
+
+- **报告你遇到的故障**，带上完整报错和你使用的 DSH 版本。上面「未验证」那段正是最需要真实反馈的地方。
+- **报告工具白名单在你的环境里不匹配**：你的 profile 注册了哪些全局工具、白名单里哪个名字报错了。
+- **改进人设**（`persona.txt`）——但请跑一次 `node build-patch.mjs && node verify-patch.mjs` 并把结果一并附上，因为 `cordis.patch.yml` 是生成文件，手工改过的会被拒。
+- **翻译或修订文档**——[README.md](README.md) 与 [INSTALL.md](INSTALL.md)。
+
+请一个 PR 只做一件事，并说明你在哪个预设下验证过。
+
+## 许可
+
+[MIT](LICENSE)

package/build-patch.mjs

@@ -10,6 +10,7 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CHILD_TOOLS } from './child-tools.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -44,32 +45,10 @@ function allowList(names, keyDepth) {
 }
 
 /**
- * The child mask: the only global tools a subagent may call. Everything absent
- * is invisible to the child, including every mutation entry point.
+ * The child mask lives in `child-tools.mjs` so this generator and
+ * `verify-patch.mjs` cannot disagree about it. See that file for why `subagent`
+ * cannot appear in the list.
  */
-const CHILD_TOOLS = [
-  'read',
-  'glob',
-  'grep',
-  'ops_inspect_local_file',
-  'ops_glob',
-  'ops_grep',
-  'web_search',
-  'web_fetch',
-  'read_image',
-  'skill',
-  'todo_write',
-  'ask_user_question',
-  'get_goal',
-  'create_goal',
-  'update_goal',
-  'list_agents',
-  'send_message',
-  'interrupt_agent',
-  'subagent',
-  'subagent_fork',
-];
-
 const persona = readPersona();
 
 /** The delegation group is shared by both shapes of child, so the mask is declared once. */

package/child-tools.mjs

@@ -0,0 +1,56 @@
+/**
+ * The child tool mask — the single source of truth shared by the generator and
+ * the verifier, so the two cannot disagree about what a subagent may call.
+ *
+ * These are the only GLOBAL tools a subagent may call. Everything absent is
+ * invisible to the child, including every mutation entry point.
+ *
+ * `subagent` is deliberately NOT here, and cannot be. With
+ * `modelSelectionSettings: true` that tool is registered per agent inside the
+ * composed Agent's own scope (`dsh-tool-subagent` mounts it through
+ * `installScoped`), and `tools.restrict()` takes a mask of *global* tools only —
+ * it throws on a scope-local name exactly as it throws on an unknown one:
+ *
+ *   Error: tools.restrict() names unknown global tool "subagent"; known global
+ *   tools: ask_user_question, create_goal, edit, … subagent_fork, …
+ *
+ * `subagent_fork` is registered in the preset's own scope instead, so it IS
+ * visible to the mask and stays. Both names were in this list until a real
+ * subagent spawn failed, which is exactly the class of mistake no amount of
+ * reading the source had caught.
+ */
+export const CHILD_TOOLS = [
+  'read',
+  'glob',
+  'grep',
+  'ops_inspect_local_file',
+  'ops_glob',
+  'ops_grep',
+  'web_search',
+  'web_fetch',
+  'read_image',
+  'skill',
+  'todo_write',
+  'ask_user_question',
+  'get_goal',
+  'create_goal',
+  'update_goal',
+  'list_agents',
+  'send_message',
+  'interrupt_agent',
+  'subagent_fork',
+];
+
+/**
+ * Tools that are agent-scoped rather than global, so a mask can never name them.
+ * Kept separate so the verifier can assert their absence by intent rather than
+ * by accident.
+ */
+export const SCOPE_LOCAL_TOOLS = ['subagent'];
+
+/**
+ * The mutation entry points this bundle promises a subagent cannot reach. The
+ * verifier asserts each one is absent; `ops_bash` and `bash` are included even
+ * when a profile registers neither, because their absence is the property.
+ */
+export const MUTATION_TOOLS = ['write', 'edit', 'ops_replace', 'ops_bash', 'pwsh', 'bash'];

package/cordis.patch.yml

@@ -42,7 +42,7 @@
                 ## Root agent rules
 
                 1. Plan first. Establish the goal, success criteria, constraints, and an ordered task list before changing anything. Revise the plan when evidence contradicts it.
-                2. Delegate research by default. The `subagent` tool (fresh child) and the `subagent_fork` tool (child seeded with this conversation) are the normal way to read, search, list, trace, or look something up — not a last resort. Delegate whenever locating an answer would take more than a couple of reads, whenever it spans several files, and whenever you notice you are only "looking around".
+                2. Delegate research by default. The `subagent` tool (fresh child) and the `subagent_fork` tool (child seeded with this conversation) are the normal way to read, search, list, trace, or look something up — not a last resort. Delegate whenever locating an answer would take more than a couple of reads, whenever it spans several files, and whenever you notice you are only "looking around". A subagent does not have `subagent`; it reads for itself, or uses `subagent_fork` if the tree still allows one more level.
                 3. Keep delegations independent and concurrent. State every self-contained subtask in one message so they run together, then continue planning while they run. Wait only when your next action needs a specific result.
                 4. Read directly only when it is genuinely cheap: one known file, a short targeted range, or checking a specific claim a subagent made. Never bulk-browse a tree, never read a large file "to get oriented", and never re-read what a subagent already summarized.
                 5. Ask for the summary shape you need. Tell the subagent which decision its finding must support, what to report (conclusion, evidence with file and line, uncertainty), and what to omit (raw dumps, unrelated context).
@@ -179,7 +179,6 @@
                       - list_agents
                       - send_message
                       - interrupt_agent
-                      - subagent
                       - subagent_fork
               - id: tool-subagent-fork
                 name: '@deepseek-ai/dsh-tool-subagent'
@@ -207,7 +206,6 @@
                       - list_agents
                       - send_message
                       - interrupt_agent
-                      - subagent
                       - subagent_fork
               - id: tool-subagent-codex
                 name: '@deepseek-ai/dsh-tool-subagent'

package/docs/DEVELOPMENT.md

@@ -1,6 +1,6 @@
 # root-planner preset bundle — maintainer notes
 
-[中文说明](../README.md) | [安装步骤](../INSTALL.md)
+[English README](../README.md) | [中文说明](../README.zh.md) | [Install](../INSTALL.md)
 
 An agent preset for DSH Web that splits **reading** from **planning and mutating**:
 the root agent keeps its context for analysis, planning, and decisions, delegates
@@ -29,6 +29,10 @@ Paths below are relative to the repository root; this file lives in `docs/`.
 | `verify-depth-override.mjs` | Checks that the profile patch layer still parses and that the `subagent` depth override landed in the composed profile. |
 | `package.json` | Bundle manifest (`dsh.bundle.patch`). |
 | `.gitattributes` | Pins LF; without it a Windows checkout breaks the byte-identity check. |
+| `README.md` / `README.zh.md` | The English and Chinese front pages, cross-linked. npm renders the repository root `README.md`, which is why the English one holds that name. |
+| `INSTALL.md` | Recipient-facing setup steps and troubleshooting (Chinese). |
+| `.github/CONTRIBUTING.md` | The contributor workflow: regenerate, verify, and the rules a change must not break. |
+| `.github/workflows/verify.yml` | CI: fails when `cordis.patch.yml` drifts from `persona.txt`, and runs the mask check. |
 
 ```sh
 node build-patch.mjs             # after every persona.txt edit
@@ -54,9 +58,30 @@ targets:
 |---|---|---|
 | Absolute path | `C:\path\to\root-planner-preset` | Works from a checkout, a share, or a USB drive. Already-installed bundles must be addressed by package name, not path. |
 | Git repository | `github:you/root-planner-preset` | Also `https://…`, `git+…`, `gitlab:`/`gist:` forms. The manager pre-checks GitHub reachability with `git ls-remote`. |
-| npm registry | `dsh-root-planner-preset` or `…@1.0.0` | **Not published yet**, and `private: true` blocks it. Drop `private`, bump the version, then publish. |
+| npm registry | `dsh-root-planner-preset` (`@1.0.0` to pin) | **Published.** Preferred: a prebuilt install skips pnpm's build-approval step. |
 | Tarball URL | `https://…/dsh-root-planner-preset-1.0.0.tgz` | For a file server or release asset. |
 
+### Publishing to npm
+
+The package is live at <https://www.npmjs.com/package/dsh-root-planner-preset>.
+Two things about this machine and account cost real time to discover; both are
+permanent conditions, not accidents:
+
+- **The configured registry is `registry.npmmirror.com`**, a read-only mirror.
+  Every publish must name the official registry explicitly:
+  `npm publish --registry https://registry.npmjs.org/ --access public`.
+- **The publishing account uses npm's staged publishing.** A `npm publish` can
+  report success and still leave the version off the registry, because it went to
+  the stage instead; `npm stage list` may show nothing while the registry refuses
+  that version with `E409 Cannot publish over previously staged version`. The
+  reliable check is never the command's exit code — it is
+  `https://registry.npmjs.org/<name>/<version>` returning 200. Version `1.0.0`
+  reached the registry only after approval on npmjs.com, not from the CLI.
+
+The `0.0.0-stage` version on the registry is an automatic placeholder from that
+workflow. It is harmless but pointless; deprecate it rather than treat it as a
+release. Never publish a real version below it.
+
 ### What the recipient's environment must provide
 
 1. **A DSH version whose presets carry the same tool row ids.** The patch mirrors

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-root-planner-preset",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
-  "description": "DSH agent preset: a context-conserving root agent that delegates reading to strictly read-only subagents and owns every file mutation.",
+  "description": "DSH agent preset that outsources file reading to strictly read-only subagents, while the root agent keeps the plan and owns every file mutation.",
   "license": "MIT",
   "author": "XiaoOu2024",
   "homepage": "https://github.com/XiaoOu2024/dsh-root-planner-preset#readme",
@@ -26,5 +26,8 @@
     "bundle": {
       "patch": "./cordis.patch.yml"
     }
+  },
+  "devDependencies": {
+    "js-yaml": "^4.1.0"
   }
 }

package/persona.txt

@@ -21,7 +21,7 @@ Reading is not planning. Raw file contents and raw query results belong in the a
 ## Root agent rules
 
 1. Plan first. Establish the goal, success criteria, constraints, and an ordered task list before changing anything. Revise the plan when evidence contradicts it.
-2. Delegate research by default. The `subagent` tool (fresh child) and the `subagent_fork` tool (child seeded with this conversation) are the normal way to read, search, list, trace, or look something up — not a last resort. Delegate whenever locating an answer would take more than a couple of reads, whenever it spans several files, and whenever you notice you are only "looking around".
+2. Delegate research by default. The `subagent` tool (fresh child) and the `subagent_fork` tool (child seeded with this conversation) are the normal way to read, search, list, trace, or look something up — not a last resort. Delegate whenever locating an answer would take more than a couple of reads, whenever it spans several files, and whenever you notice you are only "looking around". A subagent does not have `subagent`; it reads for itself, or uses `subagent_fork` if the tree still allows one more level.
 3. Keep delegations independent and concurrent. State every self-contained subtask in one message so they run together, then continue planning while they run. Wait only when your next action needs a specific result.
 4. Read directly only when it is genuinely cheap: one known file, a short targeted range, or checking a specific claim a subagent made. Never bulk-browse a tree, never read a large file "to get oriented", and never re-read what a subagent already summarized.
 5. Ask for the summary shape you need. Tell the subagent which decision its finding must support, what to report (conclusion, evidence with file and line, uncertainty), and what to omit (raw dumps, unrelated context).

package/verify-patch.mjs

@@ -2,13 +2,15 @@
 //  1. every patch file parses as YAML,
 //  2. the preset row and its delegation rows exist,
 //  3. the parsed persona is byte-identical to persona.txt (no YAML mangling),
-//  4. the child tool mask contains only names that exist in this profile.
+//  4. the child tool mask names only global tools, excludes every mutation entry
+//     point, and excludes agent-scoped names that tools.restrict() would reject.
 //
 // Usage: node verify-patch.mjs
 
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CHILD_TOOLS, MUTATION_TOOLS, SCOPE_LOCAL_TOOLS } from './child-tools.mjs';
 import { loadYaml, loaderSchema as makeLoaderSchema } from './lib-yaml.mjs';
 
 const yaml = loadYaml();
@@ -69,55 +71,80 @@ const childTools = [
   return { id, toolName, allow: row?.config?.toolFilter?.allow };
 });
 
-// The mask must deny every mutation entry point this profile registers.
-const mutations = ['write', 'edit', 'ops_replace', 'ops_bash', 'pwsh', 'bash', 'ops_run_background'];
+// The mask must deny every mutation entry point, and it can only name global tools.
 for (const { id, allow } of childTools) {
   check(Array.isArray(allow) && allow.length > 0, `${id} declares a non-empty allow list`);
-  for (const denied of mutations) {
+  for (const denied of MUTATION_TOOLS) {
     check(!allow?.includes(denied), `${id} mask excludes ${denied}`);
   }
   check(allow?.includes('read'), `${id} mask keeps read`);
-  check(allow?.includes('subagent'), `${id} mask keeps subagent (read-only recursion stays possible)`);
+  for (const scoped of SCOPE_LOCAL_TOOLS) {
+    check(
+      !allow?.includes(scoped),
+      `${id} mask excludes the agent-scoped tool "${scoped}" (tools.restrict() would refuse it)`,
+    );
+  }
 }
 
-// Every masked name must be a tool this profile actually registers, because
-// tools.restrict() rejects unknown global names when a child is created.
-const liveTools = new Set([
-  'read',
+/**
+ * The global tool inventory of the author's profile, captured from a runtime
+ * error rather than hand-kept: `tools.restrict()` prints every known global tool
+ * when it refuses a name. Replace this list with the equivalent line from your
+ * own environment — it is what makes the check below meaningful.
+ */
+const OBSERVED_GLOBAL_TOOLS = new Set([
+  'ask_user_question',
+  'create_goal',
+  'edit',
+  'exit_plan_mode',
+  'get_goal',
   'glob',
   'grep',
-  'ops_inspect_local_file',
+  'interrupt_agent',
+  'job_kill',
+  'job_list',
+  'job_output',
+  'list_agents',
   'ops_glob',
   'ops_grep',
+  'ops_inspect_local_file',
   'ops_replace',
-  'web_search',
-  'web_fetch',
+  'present',
+  'pwsh',
+  'read',
   'read_image',
+  'send_message',
   'skill',
+  'subagent_fork',
   'todo_write',
-  'ask_user_question',
-  'get_goal',
-  'create_goal',
   'update_goal',
-  'list_agents',
-  'send_message',
-  'interrupt_agent',
-  'subagent',
-  'subagent_fork',
-  'present',
-  'write',
-  'edit',
-  'pwsh',
-  'ops_bash',
-  'job_output',
-  'job_list',
-  'job_kill',
+  'web_fetch',
+  'web_search',
   'workflow',
-  'exit_plan_mode',
+  'write',
 ]);
+
+/**
+ * Tools that are agent-scoped rather than global, so the mask can never name
+ * them. `subagent` is the one this bundle ran into: with
+ * `modelSelectionSettings: true` it is mounted inside each composed Agent's own
+ * scope, and `tools.restrict()` accepts global names only.
+ */
 for (const { id, allow } of childTools) {
-  const unknown = (allow ?? []).filter((name) => !liveTools.has(name));
-  check(unknown.length === 0, `${id} mask names only live tools${unknown.length ? ` (unknown: ${unknown.join(', ')})` : ''}`);
+  const unknown = (allow ?? []).filter((name) => !OBSERVED_GLOBAL_TOOLS.has(name));
+  check(
+    unknown.length === 0,
+    `${id} mask names only tools the runtime reports as global` +
+      (unknown.length ? ` (not global: ${unknown.join(', ')})` : ''),
+  );
+  const missing = CHILD_TOOLS.filter((name) => !(allow ?? []).includes(name));
+  const extra = (allow ?? []).filter((name) => !CHILD_TOOLS.includes(name));
+  check(
+    missing.length === 0 && extra.length === 0,
+    `${id} mask matches child-tools.mjs (${CHILD_TOOLS.length} entries)` +
+      (missing.length ? ` — missing: ${missing.join(', ')}` : '') +
+      (extra.length ? ` — unexpected: ${extra.join(', ')}` : ''),
+  );
 }
 
 process.stdout.write(failures.length === 0 ? '\nALL CHECKS PASSED\n' : `\n${failures.length} CHECK(S) FAILED\n`);