前言¶
用 DSH 或其它 coding agent 做长任务时，上下文很容易被整文件内容和命令输出占满：目标模糊、计划丢失、重复劳动。常见做法是「多派子代理」，但容易走向两个极端——子代理没有工具，每一步都弹回根会话；或者子代理权限过大，随意改文件、还留下后台进程。
下面介绍社区维护者 XiaoOu2024 发布的 DSH 插件 dsh-root-planner-preset（分类：工作流）。它是一套 agent 预设 bundle，把「谁决定」和「谁动手」拆开：根 agent 持有计划与决策，子代理在各自 _agents/<label>/ 里读、写、跑命令，并以摘要回报；结构上禁止子代理留下仍在运行的进程。插件在 SkillHub 目录 可检索，源码与文档在 GitHub（当前包版本 1.6.1，MIT 许可证）。SkillHub 为社区插件目录，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
dsh-root-planner-preset 是面向 DeepSeek Harness 的 agent 预设，核心理念是：根决策，工人执行，任务结束时不应再有挂起的子进程。
- 根 agent：规划、集成、决定哪些产物并入主工作区。
- 子代理（
root-planner-worker预设）：具备文件与 shell 等工具，在委派任务边界内干活；禁止run_in_background，后台跑命令在 schema 层不可达。 - 包内还通过 profile 级守卫（
dsh-root-planner-preset/guard）把「子代理只写_agents/」做成调用级拒绝，而不只靠提示词约定。
运行环境要求 DSH ≥ 0.2.1-rc.2（package.json 中 engines.dsh）。更旧版本可能被拒绝安装；若在 0.2.0 上仍能组合，子代理会静默使用平台默认预设，人设与工具集都会错位。
核心功能¶
决策与执行分离¶
根会话选 Root Planner 预设后，根 agent 负责目标、成功判据、任务拆分与集成；阅读、改文件、执行命令由委派出去的子代理完成，回报结论与最小证据，并说明改了哪些文件。
工作方式可概括为：
根 agent ──委派──▶ 子代理 ──委派──▶ … 直到 maxDepth
│ │
└── 决策、集成、指定每个工人可触及的范围
有工具、有边界的工人¶
| 要求 | 机制 | 说明 |
|---|---|---|
| 子代理能读、改文件、跑命令 | root-planner-worker 挂载 tool-fs、tool-pwsh、tool-web 及委派行 |
工具集由预设挂载的行决定，相当于 allow list |
| 不能留下运行中的进程 | pwsh 行 enableRunInBackground: false |
拒绝后台调用，并从工具 schema 移除 run_in_background |
| 委派深度 | Host 的 subagent.maxDepth |
超过上限抛 SubagentDepthError |
| 并发子代理数量 | subagent.maxActiveSubagents |
超额时报 subagent limit reached，不排队 |
| 根决策、工人执行 | persona.txt 人设 |
提示词级约束 |
Host 全局注册的工具（在 0.2.1-rc.2 上包括 ops_glob、ops_grep、ops_inspect_local_file、ops_replace 与 working_directory）任何预设都无法移除，子代理仍会看到它们；其余根专用能力（如 workflow、plugin_manager 等）不会进入 worker 预设。
每个工人一个 _agents/ 工作区¶
派活前，根 agent 创建 _agents/<label>/，把绝对路径写进任务。子代理只在该目录写入，父工作区其它路径对其只读；要改父目录文件应通过「变更申请」由根合并。_agents/ 建议加入 .gitignore，便于同一会话后续延续。
守卫在 profile 级生效：对 origin === "subagent" 的会话，落在 _agents/ 之外的 write / edit / ops_replace 会被拒绝；shell 的 workdir 越界或命令中出现指向父文件的绝对路径也会被拒。根会话不受围栏限制。
若同一 profile 里还用其它预设委派子代理，可在 profile 补丁中关闭守卫：
- id: root-planner-guard
disabled: true
注意：shell 可在运行时拼接路径，参数扫描无法覆盖所有情况；在 POSIX 上盘符路径扫描尤其有限。文档建议父 agent 在委派前后用时间戳做兜底检查：
# 派活前
touch _agents/.mark-<label>
# 子代理报告后
find . -path ./_agents -prune -o -type f -newer _agents/.mark-<label> -print
无输出表示子代理未在 _agents/ 外新建或修改文件。
大任务上常见的两个上限¶
subagent limit reached (active child limit: N)：子代理槽位在轮次结束、收件箱清空且其子代理销毁后才释放；宽扇出会占满槽位，不会自动排队。可在 设置 → 子智能体 调高maxActiveSubagents，或分批委派。subagent depth N exceeds maxDepth M：已达最大深度仍发起委派，属于深度上限正常工作，应由该层自己读材料而非再派。
安装与启用¶
先做版本检查：
dsh --version
需 ≥ 0.2.1-rc.2。推荐从 npm 安装（预构建）：
dsh plugin --profile web add dsh-root-planner-preset
也可从 GitHub 安装：
dsh plugin --profile web add github:XiaoOu2024/dsh-root-planner-preset
安装后重启 dsh web。「设置 → 插件市场」搜不到本包属正常（市场仅允许精选列表内来源），请使用上述命令。
装完必须在 Host 中设置委派深度（不属于 bundle，无法由插件写死）：
- 打开 设置 → 子智能体 → 深度上限。
- 填
2（根 0 → 子 1 → 孙 2；勿填0，否则会禁用全部委派）。
然后开新会话，在预设选择器中选择 Root Planner。已有会话锁定启动时的插件与预设，改配置后应新开会话。
卸载示例：
dsh plugin --profile web remove dsh-root-planner-preset
更完整的故障排查见仓库 INSTALL.md。
典型用法¶
- 确认 DSH 版本与插件已安装，深度上限为
2，根会话预设为 Root Planner（可用仓库脚本node tools/verify-session.mjs <会话目录>核对根是否为root-planner）。 - 根 agent 列出计划与成功判据，对需要大量阅读或局部改动的子任务创建
_agents/<label>/并委派，在任务中写明允许触及的文件或目录。 - 子代理在
_agents/<label>/内读写、执行命令，完成后回报摘要与产物列表；根 agent 决定合并哪些文件到主工作区。 - 需要再拆一层时，由深度 1 的子代理继续委派；深度 2 为叶子，再委派会收到深度错误。
适合：跨多文件调研、逆向分析、代码审查，以及「读得多、改得少」或「改动必须由根统一决策」的任务。不适合：只改单个文件的快修（多一层委派开销大），或需要多个子代理并行改同一工作区代码（本预设刻意用目录隔离，并行写主树应使用 standard 等其它预设）。
适用场景与注意¶
- 插件以当前 DSH 进程的权限运行；安装前请阅读 源码 与 MIT 许可证，自行评估守卫与人设是否符合你的安全要求。
- 守卫约束整个 profile 下所有被委派的 agent；混用其它预设时要注意是否关闭
root-planner-guard。 - 可选依赖
dsh-ops：未安装时子代理仍可有read/glob/grep/write等由预设挂载的工具；全局ops_*是否出现取决于 Host 与已装插件。 - 从 GitHub 安装时 PATH 上需要
git；跑verify-patch.mjs等校验需要 Node。
结尾¶
dsh-root-planner-preset 用双预设（根 root-planner + 工人 root-planner-worker）、深度与活跃子代理上限、_agents/ 隔离与 profile 级守卫，把长任务里的「计划留在根上下文、执行下沉到子代理」做成可复现的工作流。查阅条目与链接：
