前言¶

用 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
   │                      │
   └── 决策、集成、指定每个工人可触及的范围

有工具、有边界的工人¶

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/ 外新建或修改文件。

大任务上常见的两个上限¶

1. subagent limit reached (active child limit: N)：子代理槽位在轮次结束、收件箱清空且其子代理销毁后才释放；宽扇出会占满槽位，不会自动排队。可在 设置 → 子智能体 调高 maxActiveSubagents，或分批委派。
2. 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，无法由插件写死）：

1. 打开 设置 → 子智能体 → 深度上限。
2. 填 2（根 0 → 子 1 → 孙 2；勿填 0，否则会禁用全部委派）。

然后开新会话，在预设选择器中选择 Root Planner。已有会话锁定启动时的插件与预设，改配置后应新开会话。

卸载示例：

dsh plugin --profile web remove dsh-root-planner-preset

更完整的故障排查见仓库 INSTALL.md。

典型用法¶

1. 确认 DSH 版本与插件已安装，深度上限为 2，根会话预设为 Root Planner（可用仓库脚本 node tools/verify-session.mjs <会话目录> 核对根是否为 root-planner）。
2. 根 agent 列出计划与成功判据，对需要大量阅读或局部改动的子任务创建 _agents/<label>/ 并委派，在任务中写明允许触及的文件或目录。
3. 子代理在 _agents/<label>/ 内读写、执行命令，完成后回报摘要与产物列表；根 agent 决定合并哪些文件到主工作区。
4. 需要再拆一层时，由深度 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 级守卫，把长任务里的「计划留在根上下文、执行下沉到子代理」做成可复现的工作流。查阅条目与链接：

• 目录页：https://www.skillhub.cn/plugins/XiaoOu2024/dsh-root-planner-preset
• GitHub：https://github.com/XiaoOu2024/dsh-root-planner-preset