子代理与 Agent Hub
子代理让 omp 能把较大的任务拆分成专注的子会话。当研究、实现或审查可以独立推进时使用它们:你可以获得并行进展和专项子代理的专注处理,而主会话仍然负责集成。
先从用平实语言提出请求开始。说明期望的结果、可以并行执行的部分,以及任何所有权或安全边界:
并行化这次迁移。给每个子代理分配一组文件互不重叠(file-disjoint)的包,用隔离工作区进行编辑,由主会话集成并验证结果。
用 scout 梳理出每一个认证入口,再让 security-reviewer 检查拟议的修复方案。研究阶段不要做任何编辑。
让 designer 实现响应式各状态,同时由 reviewer 检查现有的无障碍(accessibility)行为。别让它们碰到相同的文件。
你无需描述 omp 内部的委派协议。主会话会决定扇出规模,为每个子代理分派任务,并收集结果。
何时委派有帮助
好的候选任务具有清晰的边界,并且不需要反复向其他子代理索要尚未完成的信息就能推进:
- 独立的仓库研究、外部 API 研究或互相竞争的调研;
- 跨包或跨功能的、文件互不重叠的实现;
- 设计、代码审查或安全审查等专项处理;
- 可以按目录或生成的工件切分的机械性改动;
- 实现完成后进行的一次独立审查。
当工作是一次小型的串行改动、需要多个步骤持续修改同一个文件,或每一步决策都依赖前一步的结果时,请把它留在主会话中。子代理再多也无法让依赖链并行起来,而互相重叠的写入者会带来合并风险。
子会话不会继承主对话。omp 会传递任务分派和相关的共享上下文,而子会话可以看到被允许的工作区与项目说明。当某些上下文容易被遗漏时,请明确说出来:
委派出去,但请告诉每个子代理:
packages/api/schema.ts是唯一事实来源,并且生成的文件不得编辑。
选择专项子代理
你可以在提示词中点名某个专项子代理,也可以让 omp 自己选择。当前内置的集合如下:
| 专项子代理 | 适用场景 |
|---|---|
scout | 快速、只读的仓库探查,返回压缩后的发现。 |
designer | UI/UX 实现、无障碍与视觉打磨。 |
reviewer | 有证据支撑的正确性与质量审查。 |
security-reviewer | 只读的漏洞发现与安全分析。 |
librarian | 对外部库和 API 做源码验证式研究。 |
task | 具备完整可用能力集的通用多步骤工作。 |
sonic | 几乎不需要推理的严格机械性编辑或数据收集。 |
例如:"用 librarian 核实上游的重试语义"、"让 reviewer 只检查当前的 diff"、或"用 sonic 子代理更新这些文件互不重叠的测试夹具"。自定义的准确名称区分大小写。
打开 /agents 可以查看可用的定义、它们的来源、是否已启用,以及它们的模型、prewalk 与 advisor 路由。在磁盘上改动某份定义后,在那个界面按 Ctrl+R 即可重新加载。要创建或自定义某个专项子代理,请参阅编写子代理。
如果你不确定是应该改动某个专项子代理的定义,还是只调整它背后的模型,请参阅 Agent 与模型角色。
子代理运行期间你会看到什么
后台委派默认处于启用状态。主转录会先报告哪些具名子代理已启动,随后它的任务显示会随实时活动更新。完成的结果会交回主对话中;主 agent 可以对它们进行总结、调和分歧,并继续推进任务。/jobs 会打印后台任务的紧凑快照,但 Agent Hub 才是详细视图。
按 Alt+A 打开 Agent Hub。Ctrl+S 会通过旧的 session-observe 按键绑定打开同一视图。主编辑器为空时,双击 ← 也能打开它——前提是该会话有可展示的 agent。运行 /hotkeys 可确认或重新映射当前生效的按键组合。
名册的每一行都会显示子代理的状态、被分配的任务或当前活动、模型、运行时长、token 与请求用量、工具调用次数、活动时间,以及在数据可得时的成本。检查器(inspector)还会显示当前工具、重试状态、上下文窗口占用、父/子谱系,以及任何隔离工作区的补丁或分支信息。按 t 可在扁平名册与父/子树状视图之间切换。
| 控制 | 操作 |
|---|---|
| j/k、方向键或滚轮 | 选择一个子代理。 |
| Enter 或点击 | 打开它的实时或持久化转录。打开一个已停放的子代理时,若可能则会将其复活。 |
| Tab | 在窄终端上显示或隐藏检查器。 |
| PageUp/PageDown | 滚动检查器。 |
| r | 复活选中的已停放子代理。 |
| x | 必要时先中止,然后终止并释放该子代理。此操作立即生效。 |
| Esc | 先关闭检查器,再关闭 Agent Hub。 |
各个状态有着不同的含义:
- running —— 该子代理正处于活跃的轮次中;
- idle —— 它的轮次已结束,但其实时会话仍留在内存中,可供后续消息使用;
- parked —— 它的会话已保存到磁盘,通常可以复活;
- aborted —— 它已被停止并处于终态,不过它的转录仍然可用。
已完成工作的子代理仍与该会话保持关联。恢复该会话后,Agent Hub 会发现它们持久化的转录,并还原它们的谱系。
阅读、引导、跟进或停止
从 Agent Hub 打开某个子代理,即可聚焦它的会话。你可以阅读它的转录和当前的工具活动,然后输入一条普通消息并按 Enter:
停止改动 API 包。只完成客户端测试,并报告还剩下什么。
在收尾之前,把你的发现与生成的 schema 对比,并同时引用这两个文件。
给运行中的子代理发消息属于引导消息(steering),会在某个安全的步骤边界处落地;给空闲子代理发消息会开启一次后续消息(follow-up);给已停放的子代理发消息则会先把它复活。编辑器为空时,按 Esc 或双击 ← 返回主会话。返回并不会打断该子代理。
当某个子代理已经拥有正确的上下文时,优先向同一个子代理发后续消息。当它的工作不安全、超出范围、卡住或不再有用时,使用 x。终止会释放那个子代理实例,因此如果之后还需要更多工作,请重新启动一个子代理。
共享检出还是隔离工作区
默认情况下,子代理与主会话在同一个检出(checkout)中工作。这样速度快,也能让各方看到当前的改动,但并发的写入者可能覆盖彼此的假设,或产生互相交错的编辑。请给非隔离子代理划分文件互不重叠的所有权,并把最终集成放在同一个地方完成。
如果需要更强的编辑隔离,打开 /settings,选择 Tasks → Isolation 分组,把 Isolation Mode 设为 Auto。然后直接提出要求:
让这三个实现子代理在隔离工作区中运行。只应用成功的改动,并由主会话解决集成冲突。
隔离子代理会获得一个按平台选定的文件系统克隆或叠加层(overlay)。omp 会捕获它的改动,并按照配置的补丁或分支策略进行集成。隔离要求使用 Git 仓库。受管工作区通常位于 ~/.omp/wt 下;worktree.base 可以更改这个位置。在默认设置下,成功的改动会以补丁的形式应用到父检出中。
隔离保护的是并发的检出编辑,它并非通用的安全沙箱。子代理仍然可能运行命令、使用联网工具,或影响其工具集和凭据所允许访问的外部服务。隔离子代理在完成后也无法复活,因为它们的临时工作区已被拆除;不过它们的转录和补丁元数据仍然可以检查。
即使是隔离的编辑,在集成时也可能产生冲突,尤其是当多个子代理改动同一批行时。请先划分好所有权,审查产生的 diff,并让主会话验证合并后的行为。
成本、安全与限制
每个子代理都是一个独立的模型会话,因此并行会成倍增加 token 用量、Provider 请求和成本。Agent Hub 会显示实测的每个子代理用量与合计用量。从最小且够用的扇出规模开始,只把 scout 或 sonic 用于适合它们的工作,并停止那些任务分派已经过时的子代理。Advisor 与 prewalk 路由本身也可能产生模型调用。
子代理以无头方式运行,无法停下来等待逐工具的交互式审批。请把每一次任务分派都当作被委派出去的权限:限制它的范围,尽可能选择只读的专项子代理,避免把无关的密钥或生产操作交给子代理,并监督外部的副作用。工作区隔离并不能保护远程账号或服务。
重要的默认值如下:
| 设置 | 默认值 | 作用 |
|---|---|---|
async.enabled | true | 让普通子代理在后台继续运行。 |
task.maxConcurrency | 32 | 限制同时运行的子代理数量;额外的工作进入队列。0 表示不限。 |
task.maxRecursionDepth | 2 | 限制子代理可以再次向下委派的深度。 |
task.softRequestBudget | 200 | 请长时间运行的子代理收尾,并在超出预算 1.5 倍时强制产生部分结果。0 表示禁用。 |
task.maxRuntimeMs | 0 | 每个子代理的硬性实际运行时长上限;0 表示不限。 |
task.agentIdleTtlMs | 420000 | 空闲子代理在七分钟后停放;0 让它保持活跃直到退出。 |
task.isolation.mode | none | 用 auto 或某个特定后端启用隔离工作区。 |
task.isolation.apply | true | 把成功的隔离改动应用到父检出。 |
task.isolation.merge | patch | 以补丁而非分支的形式集成隔离改动。 |
用 /settings 调整这些控制项,用 /agents 管理每个 agent 的启用与模型路由。直接编辑 ~/.omp/agent/config.yml 的方法见设置。
故障排查
omp 一直把工作留在主会话里。 请明确请求:"用三个文件互不重叠的子代理并行化这项任务",或点名某个专项子代理。在 /settings 中,当你希望委派更积极时,可以把 Prefer Task Delegation 从 default 改为 preferred 或 always。
点名的专项子代理未知或不可用。 打开 /agents,核对准确且区分大小写的名称、作用域和启用状态,然后按 Ctrl+R 重新加载定义。同名时,项目级定义优先于用户级或内置定义。
子代理一直停留在队列中。 要么是运行中的子代理已达到 task.maxConcurrency,要么是模型 Provider 正在对请求限流。请减少扇出规模、等待空闲槽位,或谨慎地调高上限。
子代理产生了相互冲突的编辑。 停止重叠的写入者,给每个子代理划分文件互不重叠的所有权,并在启用隔离的情况下重试。隔离能减少对实时检出的干扰,但并不能让重叠的补丁干净地合并。
隔离不可用。 确认 task.isolation.mode 不是 none,并且 omp 正在某个 Git 仓库中运行。计划模式(plan mode)下隔离不可用,该模式会让被委派的工作保持只读。如果自动集成失败,请先在 Agent Hub 中检查补丁或分支信息,然后再手动应用任何改动。
已完成的子代理无法复活。 隔离子代理在拆除后被有意设计为不可复活,而被终止或硬中止(hard-abort)的子代理则处于终态。请启动一个新的子代理,并把旧的结果总结进它的提示词。普通的已停放子代理可以用 r 复活,也可以打开它并向它发送消息来复活。
结果不完整或中途停止。 检查转录中是否有软性预算(soft request-budget)提醒、实际运行超时、Provider 错误或手动中止。请收窄剩余的任务分派,并在同一个普通子代理空闲或已停放时向它发后续消息;否则启动一个替代子代理。
Agent Hub 显示为空。 它只展示属于当前会话的子代理。请恢复创建了这些子代理的会话,或在这里发起一项委派任务。/jobs 仍然可能显示最近的后台进程记录,但它无法替代子代理的转录。
