oh-my-openagent Team Mode 实战指南：基于共享邮箱与任务清单的并行多 Agent 协作

oh-my-openagent Team Mode 实战指南基于共享邮箱与任务清单的并行多 Agent 协作【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagentTeam Mode 是 oh-my-openagentOmO提供的并行多 Agent 协调机制参照 Claude Code 的 Agent Teams 设计通过共享邮箱、共享任务清单与可选的 tmux 可视化布局让一个 Lead 会话同时调度多个专用成员会话。本文以 docs/guide/team-mode.md 为主体结合 packages/team-core 与 packages/omo-opencode 的源码实现完整覆盖从配置启用、团队定义、成员资格、12 个team_*工具、生命周期到磁盘存储布局的全部细节。读完本文你将能够独立搭建并调优一个受限并行、有界协调、可优雅关停的 Agent 团队。什么是 Team Mode默认关闭的并行协调层Team Mode 是 OmO 中受限并行bounded parallelism 有界协调的实现多个成员会话围绕**共享邮箱mailbox和共享任务清单tasklist**协作全部由当前会话Lead驱动。它默认关闭OFF需要通过 JSONC 配置显式开启。从源码结构看这套能力被拆成两层领域原语层packages/team-core无 harness 依赖的注册表、邮箱、任务清单、状态存储、worktree 与 tmux 布局原语共 82 个 TypeScript 文件OpenCode 适配层packages/omo-opencode/src/features/team-mode负责会话派生、hooks、工具注册与配置集成被team_mode.enabled门控。适用场景并行探索 受限协调多个侦察成员同时扫读代码库通过任务清单汇总发现避免无边界发散跨专用 Agent 拆分的长周期多步重构不同成员各管一个模块Lead 统一派活与收口需要共享任务清单的研究 实现流水线研究成员的产出以任务形式交接给实现成员。如果只需要一次性委托单个子任务且不需要团队级协调应当走taskdelegate-task工具而不是 Team Mode——两者并不等价详见下文Team Mode 不做什么。启用 Team Mode11 个配置字段全解在[opencode]块中写入配置用户级写入~/.omo/omo.jsonc项目级写入project/.omo/omo.jsonc{ team_mode: { enabled: true, max_parallel_members: 4, max_members: 8, tmux_visualization: false } }启用后必须重启 opencode12 个team_*工具才会出现在工具注册表中——工具注册通过 packages/omo-opencode/src/plugin/tool-registry.ts 的teamModeToolsRecord完成且仅在启用时注册。Schema 与默认值11 个字段该 schema 的权威定义在 packages/team-core/src/config.ts#L3-L15由 Zod 校验字段与默认值如下字段类型 / 取值范围默认值含义enabledbooleanfalse总开关tmux_visualizationbooleanfalse是否为每个成员派生 tmux pane 布局max_parallel_membersint1..84同时在飞的成员上限max_membersint1..88硬性成员上限同时约束团队规格max_messages_per_runint110000单次运行消息总量上限max_wall_clock_minutesint1120单次运行墙钟时间上限max_member_turnsint1500单个成员轮转次数上限base_dir可选 string~/.omo覆盖团队规格 / 运行时 / worktree 的基础目录message_payload_max_bytesint102432768单条消息体字节上限recipient_unread_max_bytesint1024262144单收件人未读邮箱字节上限mailbox_poll_interval_msint5003000收件轮询间隔毫秒几点值得注意的实现细节base_dir未设置时resolveBaseDir会展开为~/.omopackages/team-core/src/team-registry/paths.ts#L68-L70并支持~/~/形式的主目录展开基础目录及其子目录teams、runtime、worktrees会在首次使用时以0o700权限创建并校验ensureBaseDirs同上文件#L209-L228。message_payload_max_bytes与消息 schema 中body的max(32 * 1024)校验packages/team-core/src/types.ts#L91-L103一致超限消息会在写入阶段被拒绝。所有运行期上限bounds会被固化到运行时状态中maxMembers、maxParallelMembers、maxMessagesPerRun、maxWallClockMinutes、maxMemberTurnspackages/team-core/src/types.ts#L151-L157。启用后的验证与排障启动日志会输出解析后的team_mode状态以及团队工具数量[tool-registry] Built tool registry条目。若重启后工具仍未出现检查oh-my-opencode.log中的已加载配置路径与[tool-registry] Built tool registry条目。仓库还配有覆盖最小配置 全新安装场景的回归测试专门防住这类配置未生效的回归。定义团队TeamSpec 与两种作用域团队规格文件TeamSpec存放在用户级~/.omo/teams/{name}/config.json项目级project/.omo/teams/{name}/config.json同一团队名在两处同时定义时项目级优先。这一优先级逻辑在discoverTeamSpecs中实现先收集项目级规格再跳过与项目级同名的用户级规格packages/team-core/src/team-registry/paths.ts#L146-L181并在冲突时输出team-spec-collision日志。一个完整的团队规格示例{ name: ccapi-explorers, description: Explore the ccapi project structure., members: [ { kind: category, name: scout-1, category: deep, prompt: Scout the source directory for auth patterns. }, { kind: category, name: scout-2, category: quick, prompt: Scout tests for auth coverage. }, { kind: subagent_type, name: auditor, subagent_type: my-security-auditor, prompt: Audit the auth findings the scouts report. } ] }字段约定与校验来自 packages/team-core/src/types.ts#L58-L89 的TeamSpecSchemaversion与createdAt为可选项loader 会自动填充version固定为 1createdAt默认当前时间戳name与成员name必须匹配正则^[a-z0-9-]$members至少 1 个、至多 8 个与max_members上限一致Lead 无需声明当前会话始终是 Lead团队中没有 lead member 条目team_create也接受同样的内联形状{ name, members: [{ name, category|subagent_type, prompt? }] }。loader 还会对常见错误给出专门的可读报错packages/team-core/src/team-registry/loader.ts成员数超过 8 报TEAM_MEMBER_LIMIT_EXCEEDED同时指定category与subagent_type报AMBIGUOUS_MEMBER_KIND缺失kind判别字段报MISSING_MEMBER_KINDcategory成员缺少必填的prompt报MISSING_CATEGORY_PROMPT。成员种类与资格边界两种成员种类kind: category路由到分类 worker——一个由该分类的模型与技能配置的全新 worker 会话。prompt必填。若分类无法解析直接以UNRESOLVABLE_CATEGORY失败错误信息会列出可用分类。kind: subagent_type别名agent直接调用omo.json中用户自定义的agents。prompt可选。kind 可根据你设置的字段自动推断因此可省略kind本身。两种成员的 schema 差异也在 packages/team-core/src/types.ts#L37-L49 中体现category成员强制要求categorypromptsubagent_type成员要求subagent_typeprompt可选。谁能成为成员合格任何可解析的 category以及任何用户自定义 agent。解析期拒绝curated 只读 agentexplore、librarian、plan-consultant、plan-reviewer与 ulw-loop 审查三件套omo-senpi-code-reviewer、omo-senpi-qa-executor、omo-senpi-gate-reviewer。拒绝原因在 packages/senpi-task/src/team/member-validator.ts#L25-L69 中给出curated agent 是只读且进程内的无法写入邮箱状态reviewer 三件套被拒绝是因为进程模式成员会丢失审查指令与工具白名单。这两类都应通过task工具路由。需要说明的是成员词汇表是宿主相关的senpi-task 宿主使用上述的CURATED_READONLY_AGENT_NAMES/ULW_REVIEWER_AGENT_NAMES校验而在 team-core 的 OpenCode 适配层AGENT_ELIGIBILITY_REGISTRYpackages/team-core/src/types.ts#L190-L237给出了三级裁决裁决Agent说明eligiblesisyphus、atlas、sisyphus-junior直接可用conditionalhephaestus默认缺少teammate: allow权限要么打 D-36 补丁在tool-config-handler.ts中加teammate: allow要么改用subagent_type: sisyphushard-rejectoracle、librarian、explore、multimodal-looker、metis、momus、prometheus只读或仅 plan 模式无法写邮箱请改用 delegate-taskhard-reject 会在 TeamSpec 解析期直接抛错Agent X is read-only…错误信息会指引使用者改用 delegate-task——即解析期拒绝、运行时永不接触的原则。生命周期从 team_create 到 team_deleteteam_create—— 派生团队与各成员会话Lead 通过team_send_message、team_task_create派活成员通过team_task_updatestatus: claimed认领任务完成后用team_send_message回报team_shutdown_request→ 成员或 Lead 通过team_approve_shutdown/team_reject_shutdown应答team_delete—— 清理运行时状态、worktrees 与可选的tmux 布局。底层有几条关键不变量packages/omo-opencode/src/features/team-mode/AGENTS.md派生竞态安全每次派生都在 sessionID 已知时同步调用registerTeamSession所有 hooks 在loadRuntimeState之前先lookupTeamSession避免 spawn-race 窗口延迟确认消息 fire-and-forget收件方通过独立调用确认ack任务加锁任务认领使用原子文件锁并发认领可安全解决原子写入状态变更走临时文件 rename见 packages/team-core/src/team-state-store/locks.ts仅合格成员解析期拒绝运行时不再复查禁止嵌套团队成员不可调用team_create。运行时状态 schemaRuntimeStateSchemapackages/team-core/src/types.ts#L176-L188记录version: 1、UUIDteamRunId、teamName、specSourceproject/user、createdAt、status、leadSessionId、可选tmuxLayout、members、shutdownRequests与bounds。运行状态机为creating → active → shutdown_requested / deleting → deleted / failed / orphaned成员状态机为pending → running → idle / errored / completed / shutdown_approved。12 个 team_* 工具工具在启用后注册teamModeToolsRecord完整清单与职责如下工具用途team_create派生团队按命名或内联 TeamSpecteam_delete拆除仅 Lead 可用存在活跃成员时拒绝除非force: trueteam_shutdown_requestLead 请求某成员收尾team_approve_shutdown/team_reject_shutdown成员或 Lead 应答关停请求team_send_message点对点邮箱Lead 可*广播team_task_create/_list/_update/_get共享任务清单的增、查、改、取team_status聚合运行时视图成员、任务、邮箱team_list已声明 活跃团队实现分布在 packages/omo-opencode/src/features/team-mode/tools 下生命周期类lifecycle.ts、lifecycle-create-tool.ts、lifecycle-participant.ts、lifecycle-shutdown-tools.ts、消息类messaging.ts及其 live-delivery 子模块、任务类tasks.ts、查询类query.ts。消息kind有五种message、shutdown_request、shutdown_approved、shutdown_rejected、announcementpackages/team-core/src/types.ts#L4-L10任务状态五种pending、claimed、in_progress、completed、deleted同上#L14。任务 schema 还支持blocks/blockedBy依赖关系与metadata可构建任务间的先后依赖同上#L105-L119。运行边界Bounds 默认值最多 8 个成员、4 个同时在飞每条消息体最大 32 KB每个收件人未读上限 256 KB单次运行最多 10000 条消息、120 分钟墙钟、每成员 500 轮。这些默认值都可被上文 11 字段配置覆盖并固化进运行时状态供审计。Worktrees可选的成员级 git 工作树在成员条目中加worktreePath: ../wt-scout即可为该成员分配独立工作树。路径支持相对文件系统路径或绝对路径裸分支名被拒绝避免把成员会话丢进无法工作的状态。需要环境存在git。工作树创建、校验与孤儿清理由 packages/team-core/src/team-worktree 负责目录约定为~/.omo/worktrees/{teamRunId}/{member}/。tmux 可视化可选的面板布局设置tmux_visualization: true后每个成员会获得一个专属 tmux pane通过opencode attach挂到该成员的会话上——pane 内运行成员完整的交互式 opencode TUI可以实时观察流式输出。要求运行在 tmux 会话内且 PATH 上有 tmux失败被隔离缺少 tmux 永远不会阻塞团队创建——依赖探测在 packages/omo-opencode/src/features/team-mode/deps.ts#L16-L30 完成tmux_visualizationtrue但 tmux 不可用时只打警告运行时跳过布局pane 默认从process.cwd()启动配置了 worktree 的成员从各自 worktree 启动team_delete关闭全部 pane 并拆除团队布局单成员关停只关闭其 pane 并重新平衡剩余布局。布局原语网格 pane 排布、调用方 tmux 会话解析、布局重平衡、陈旧会话清扫位于 packages/team-core/src/team-layout-tmux。Team Mode 不做什么无嵌套团队成员不能调用team_create由team-tool-gatinghook 强制无同步回复等待team_send_message是 fire-and-forget成员被引导不要再生子成员指导 promptmember-guidance会要求成员不再派生子会话task工具未被预算门控到 0但嵌套team_create被拒绝team_delete拒绝活跃成员除非force: true。诊断doctor 的 team-mode 检查bunx oh-my-openagent doctor包含team-mode检查项输出 tmux / git 可用性、已声明团队数量与活跃运行时目录数。其实现packages/omo-opencode/src/cli/doctor/checks/team-mode.ts#L10-L33enabled为 false 时直接skipteam_mode: disabled启用时探测tmux/git缺失则warn报告基础目录状态、teams/下声明数与runtime/下运行时目录数。存储布局邮箱、任务清单与投递预留默认base_dir未覆盖磁盘结构如下~/.omo/ ├── teams/{name}/config.json # declared specs └── runtime/{teamRunId}/ ├── state.json # durable runtime state ├── inboxes/{member}/{uuid}.json # mailbox (atomic per-message files) ├── inboxes/{member}/.delivering-{uuid}.json # transient live-delivery reservation ├── inboxes/{member}/processed/ # acked messages ├── tasks/{id}.json # shared task list ├── tasks/claims/ # task claim records └── tasks/.highwatermark # tasklist id allocator几点底层机制值得展开投递预留delivery reservation.delivering-{uuid}.json仅在消息正通过promptAsync实时投递时存在。投递成功则提交到processed/失败则释放回{uuid}.json若因崩溃遗留团队恢复时会按10 分钟 TTL回收。listUnreadMessages会忽略点文件条目因此兜底轮询绝不会重复注入已被预留的消息——这是实时投递 轮询兜底双通道不丢不重的前提相关实现见 packages/team-core/src/team-mailbox。任务 ID 分配任务 ID 为十进制自增.highwatermark分配器与 senpi 的st_*任务 ID 体系区分任务认领使用tasks/claims/{id}.lock文件锁实现原子认领packages/team-core/src/team-registry/paths.ts#L116-L123。路径安全所有运行时路径都经过resolveContainedPath校验拒绝..、空段、含/或\的段与 NUL 字符越界直接抛TeamPathTraversalErrorpackages/team-core/src/team-registry/paths.ts#L43-L66任务 ID 还额外要求纯数字。senpi-task 项目的存储差异对 senpi-task 项目状态目录默认解析到project/.omo/senpi-task团队运行时路径随之变为stateDir/teams/runtime/teamRunId/...详见 packages/team-core/AGENTS.md 与 packages/senpi-task/src/team/storage.ts。源码地图继续深入的方向用户文档docs/guide/team-mode.md本文主体配置 schemapackages/team-core/src/config.ts、packages/omo-opencode/src/config/schema/team-mode.ts领域类型与资格注册表packages/team-core/src/types.ts规格加载与校验packages/team-core/src/team-registryloader.ts、validator.ts、paths.ts、team-spec-input-normalizer.tsOpenCode 适配层packages/omo-opencode/src/features/team-mode/AGENTS.md12 工具、模块布局、集成点与反模式及其tools/目录领域原语总览packages/team-core/AGENTS.md注册表、邮箱、任务清单、状态存储、worktree、tmux 布局六大原语依赖探测与诊断packages/omo-opencode/src/features/team-mode/deps.ts、packages/omo-opencode/src/cli/doctor/checks/team-mode.tssenpi 成员校验packages/senpi-task/src/team/member-validator.ts。自检提示启用后若team_*工具未出现按顺序检查配置是否落在正确作用域用户或项目、是否已重启 opencode、oh-my-opencode.log中是否出现[tool-registry] Built tool registry若团队成员创建失败优先查看错误码UNRESOLVABLE_CATEGORY、TEAM_MEMBER_LIMIT_EXCEEDED、AMBIGUOUS_MEMBER_KIND、MISSING_MEMBER_KIND、MISSING_CATEGORY_PROMPT、hard-reject 的只读 agent 提示它们已覆盖绝大多数配置失误。【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考