07. 并行工作

子助手与角色

子助手是主助手为有边界的任务拉起的子会话。它有自己的上下文窗口，汇报摘要回来，不能再拉子助手（嵌套深度为一）。

角色是套在子助手上的具名行为层（语气、输出形态、任务重心）。助手定义才是会话本身：模型、工具、提示。角色作用于子助手；它们不替代助手类型。

什么时候委派

会烧掉父助手上下文、或不该共享脏工作树的工作，交给子助手：

用偏读取的子助手去探索或做计划，父助手继续实现。
并行跑测试或做审查。
用 isolation: worktree 隔离文件改动，子助手就不会和父助手撞车（见 Git worktree）。

短任务、需要跟你紧来回，或准备成本高过多开一个窗口的事情，就不要用子助手。

管理定义与角色

命令	打开
`/config-agents`（别名 `/agents`）	Agents 对话框，Agents 标签
`/personas`	同一对话框，Personas 标签
命令面板 Manage Agents（`Ctrl+P`）	同一对话框

这不是助手看板（/dashboard / Ctrl+\），看板列的是活着的顶层会话。

助手定义文件在 .matcha/agents/ 或 ~/.matcha/agents/。角色在 config.toml（[subagents.personas]）或 .toml 文件里：

.matcha/personas/*.toml（项目）
~/.matcha/personas/*.toml（用户）
捆绑角色（优先级最低；只读）

写在 config.toml 里的角色优先于文件。文件名主干就是角色名。主助手不会把角色名传进 spawn_subagent；Matcha 通过子助手解析和职责套上角色。

内置助手类型

子助手总是某一种助手类型（spawn_subagent 上的 subagent_type）：

类型	职责
`general-purpose`	默认。完整工具集。
`explore`	搜索、读取、grep、shell；不改文件。
`plan`	探索并写计划；不改文件。

项目或用户助手可以增加类型，或覆盖这些名字。

在本地关闭

子助手默认开启。

export MATCHA_SUBAGENTS=0

# ~/.matcha/config.toml
[subagents]
enabled = false

CLI 上的 --no-subagents 也会关掉拉起。GROK_SUBAGENTS 是兼容别名。

按类型开关和模型覆盖：

[subagents.toggle]
plan = false

[subagents.models]
explore = "grok-build"

没有按类型指定模型时，子助手继承父助手的模型。

父助手如何拉起子助手

主助手调用 spawn_subagent。常见字段：

参数	含义
`prompt` / `description`	任务正文和短标签
`subagent_type`	默认为 `general-purpose`
`background`	立即返回子助手 id
`capability_mode`	`read-only`、`read-write`、`execute` 或 `all`
`isolation`	`none`（共享工作区，默认）或 `worktree`
`resume_from`	继续本会话里已完成的、同类型子助手
`cwd`	工作目录；不能与 `isolation: worktree` 一起用

后台子助手：用 get_command_or_subagent_output 收集输出。省略 capability mode 时，用该类型自己的工具集（explore / plan 本来就不能改文件）。

isolation: worktree 给子助手自己的检出；结果里带 worktree 路径。应用或移除走 Matcha 的 git worktree 操作（与 matcha worktree 同一族）。

角色可以设 instructions、instructions_file、description、inputs / outputs，以及可选的 model、reasoning_effort 和 default_isolation（none 或 worktree）。角色缺失或读不出会让拉起失败。

在 TUI 里查看子助手

滚动记录：生命周期块（Subagent running / started / completed）。Enter 或 Ctrl-F 在带框、以观察为主的视图里打开子助手记录（q / Esc 返回）。
**Tasks** 窗格（Ctrl+G）：分组 **Subagents**，可查看/终止。
/tasks 把同一份快照写成系统块（精简模式没有窗格，这条仍可用）。见后台任务、队列与循环。

子助手不能调用 spawn_subagent。深度为一。

本构建没有

不要指望下载远程子助手包或云端 chat-modes 目录。在这台机器上定义助手和角色。Cloud Agent（cloud_agent）也已关闭——子助手是本机子会话，不是远程虚拟机。