OMX Team Worker 协议实战指南：tmux 团队协作下的 ACK、任务生命周期与邮箱协议全解析-北京尧图网络

OMX Team Worker 协议实战指南tmux 团队协作下的 ACK、任务生命周期与邮箱协议全解析【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex导读本文以 OmXoh-my-codex仓库中的 worker 技能定义为主体系统讲解在 OMX Team基于 tmux 的多 Agent 团队运行时中worker 角色从启动、认领任务、执行、上报到退出的完整协议。你将掌握 worker 的启动 ACK、claim-safe 任务认领、生命周期状态迁移、邮箱消息确认与 idle 状态写回等全部操作细节并借助仓库源码理解底层状态机与并发安全设计可直接用于排障和二次开发。Worker 角色定位何时启用何时禁用OMX 的团队模式omx team是显式的多 Agent 编排面worker 是团队运行时分配的执行 lane不是通用子角色。在 AGENTS.md 的 delegation rules 中明确写着Reserveworkerstrictly for activeteam/swarmsessions、worker is a team-runtime surface, not a general-purpose child role。这意味着仅在会话以OMX_TEAM_WORKERteam-name/worker-n环境变量启动时才应加载 worker 技能普通单独执行、或团队模式之外的有界实现/审查任务应使用executor等角色而不是 workerworker 只负责执行分配给它的切片遇到阻塞、共享文件冲突、范围扩大、缺权限或模式不匹配时向上leader上报而不是递归编排其他人。在开始任何动作之前worker 必须先阅读AGENTS.md中的 Durable Runtime Invariants (canonical SSOT) 一节该节是持久状态所有权、hook 边界、取消与团队协调的唯一事实来源single source of truth。其中与 worker 直接相关的核心规则包括Team 状态文件与omx team api ... --json是任务生命周期与邮箱协调的事实来源worker 应优先使用持久状态写入与omx team api分发直接tmux send-keys只能作为兜底绝非首选分发方式worker 只上报任务证据不创建自己的 ledger、不修改 Ultragoal 工件、不 checkpoint 目标详见 AGENTS.md 的 Ultragoal ownership 一节。启动前置Skill 与 Team State Root 的解析顺序Worker Skill 路径解析worker 技能文件从以下路径中按顺序取第一个存在的${CODEX_HOME:-~/.codex}/skills/worker/SKILL.md~/.codex/skills/worker/SKILL.mdleader_cwd/.codex/skills/worker/SKILL.mdleader_cwd/skills/worker/SKILL.md仓库内兜底即本文对应的 skills/worker/SKILL.md这条解析逻辑在运行时由 worker-bootstrap.ts 生成 worker 指令时反复注入确保不同 worker CLICodex/Claude行为一致。Team State Root 解析顺序worker 必须解析出规范的团队状态根目录顺序为环境变量OMX_TEAM_STATE_ROOTworker 身份文件中的team_state_root团队配置/manifest 中的team_state_root本地兜底.omx/state这一顺序在 state-root.ts 中实现如env.OMX_TEAM_STATE_ROOT的显式读取以及身份文件team_state_root的元数据路径解析并且源码注释特别强调不得在运行时未提供规范根目录时凭空发明cwd/.omx/state以免把跨 worker 的运行时状态写到错误位置。worker 相关持久状态统一落在team_state_root/team/teamName/之下。Worker 操作步骤全解8 步协议skills/worker/SKILL.md 给出了 worker 的 8 步操作流程下面逐条展开并给出源码依据。第 1 步拆解身份并发送启动 ACK先把环境变量拆成teamName与workerName然后在做任何任务之前向 leader 发送一条启动 ACKomx team api send-message --input {team_name:teamName,from_worker:workerName,to_worker:leader-fixed,body:ACK: workerName initialized} --json关键约束绝不可省略from_worker。因为 MCP 服务器无法自动探测 worker 身份from_worker必须始终携带。目标固定为leader-fixedleader 的固定 mailbox 名。在 worker-bootstrap.ts 生成的 worker overlay 中ACK 被描述为 Startup Handshake (Required)并要求 body 保持简短、确定性以便跨 CLI 一致解析。从源码看send-message的必填字段为team_name、from_worker、to_worker、body见 src/cli/team.ts 的TEAM_API_OPERATION_REQUIRED_FIELDS。底层实现位于 mailbox.ts 的sendDirectMessage它会先去重相同from_worker to_worker body且未投递的重复消息直接复用然后生成randomUUID()作为message_id优先通过 runtime bridgeCreateMailboxMessage落盘bridge 不可用时回退到 legacy JSON 文件写入并追加message_received团队事件与投递日志。第 2 步读取 inbox取第一个未阻塞的任务team_state_root/team/teamName/workers/workerName/inbox.mdinbox 是 worker 的任务分派入口由 leader 通过write-worker-inbox或 bootstrap 生成。generateInitialInboxworker-bootstrap.ts生成的 inbox 会列出该 worker 的分配任务包含任务 id、主题、描述、状态、blocked_by/depends_on依赖、角色、文件路径、领域、lane 与分配原因等结构化信息并附带从第一个非阻塞任务开始的指示。第 3 步读取任务文件注意 task_id 格式team_state_root/team/teamName/tasks/task-id.json任务文件的命名带task-前缀如task-1.json但所有 API 使用裸数字task_id例如1绝不是task-1。这一点在 worker-bootstrap 生成的指令里被反复强调State/MCP APIs use task_id: (example: 1), never task-1。第 4 步编辑前认领任务claimomx team api claim-task --input {team_name:teamName,task_id:id,worker:workerName} --jsonclaim 是可选的加expected_version乐观并发校验不传则不校验版本。认领成功后任务进入in_progress状态。claim-safe 原理源码级在 tasks.ts 的claimTask中认领流程是先读任务并计算 readiness依赖blocked_dependency检查未就绪直接拒绝在withTaskClaimLock锁内重新读取当前状态做二次校验防止竞态校验 worker 必须存在于团队配置中否则worker_not_found若任务已是in_progress只有当 claim 租约过期leased_until已到才能接管否则返回claim_conflict若任务pending/blocked且已有他人 owner返回claim_conflict认领成功后写入claim: { owner, token, leased_until }其中leased_until默认是15 分钟租约Date.now() 15 * 60 * 1000并递增version。因此一个 worker 拿到的是带 token 的租约式认领过期后其他 worker 才能接管reclaimExpiredTaskClaim会把过期in_progress任务回滚到pending。第 5 步执行分配的工作只编辑任务描述中列出的文件路径不得直接写任务生命周期字段status、owner、result、error这些只能通过生命周期 API 修改若需要修改共享文件应把状态文件写成{state: blocked, reason: ...}并向上报告worker 可以在 pane 内派生 Codex 原生 subagent 提升吞吐但只限独立、有界、可在本 pane 安全运行的子任务。第 6 步通过生命周期 API 完成或失败omx team api transition-task-status --input {team_name:teamName,task_id:id,from:in_progress,to:completed,claim_token:token,result:evidence} --jsontransition-task-status的必填字段为team_name、task_id、from、to、claim_token可选字段resultcompleted 时与errorfailed 时。release-task-claim只用于把阻塞任务回退到pending回滚/requeue不用于完成。状态机源码级contracts.ts 定义了完整的状态集合与合法迁移TEAM_TASK_STATUSES [pending, blocked, in_progress, completed, failed]; TEAM_TERMINAL_TASK_STATUSES {completed, failed}; // 合法迁移in_progress - [completed, failed]transitionTaskStatustasks.ts在锁内校验当前状态必须等于from且from - to必须是合法迁移否则invalid_transition任务不能已是终态already_terminalclaim.owner必须等于owner、claim.token必须等于传入的claim_token否则claim_conflictclaim 租约必须未过期否则lease_expired对completed且有 delegation/coordination 合规要求的任务会从result中解析Subagent spawn evidence:/Subagent skip reason:/Coordination protocol: ...等证据行缺失时返回missing_delegation_compliance_evidence/missing_coordination_compliance_evidence拒绝完成成功后清空 claim写入completed_at、result/error并追加task_completed/task_failed团队事件。典型建议的迁移路径就是in_progress - completed|failed见 src/cli/team.ts 的操作注释。第 7 步检查并确认邮箱消息omx team api mailbox-list --input {team_name:teamName,worker:workerName} --json omx team api mailbox-mark-delivered --input {team_name:teamName,worker:workerName,message_id:MESSAGE_ID} --jsonmailbox 位于team_state_root/team/teamName/mailbox/workerName.jsonleader 的固定为leader-fixed.json。底层实现mailbox.ts中markMessageDelivered优先走 bridge 的MarkMailboxDelivered命令随后在锁内把消息的delivered_at写为当前 ISO 时间并追加投递日志listMailboxMessages直接读取 worker 的 mailbox 消息列表。消息结构包含message_id、from_worker、to_worker、body、created_at、notified_at?、delivered_at?。收到消息后要继续执行分配的工作或下一个可行任务不要发完回复就停下。第 8 步迁移后写 idle 状态{state: idle, updated_at: ISO timestamp}写入路径为team_state_root/team/teamName/workers/workerName/status.json。阻塞时则写{state: blocked, reason: ...}。状态写入通过omx team api的write-worker-status对应操作完成源码入口在 workers.ts再导出自 state.ts。之后等待 leader 通过终端或 mailbox 发送的下一步指令。退出与证据要求worker 的退出与证据纪律同样重要完成证据必须命名任务 id、变更的工件、执行的验证verification、以及任何阻塞项ACK、任务迁移、邮箱确认、状态写入都必须通过 Team API/状态文件可观测关机shutdown时遵循 leader inbox 中的指示并在退出前写入所需的关机确认对应write-shutdown-request/read-shutdown-ack等 Team API 操作提交纪律在报告完成前先提交变更git add -A git commit -m task: task-subject确保变更可供 leader 分支增量集成完成时在result中包含结构化验证证据Verification:后跟一条或多条带命令/输出引用的 PASS/FAIL 检查这一要求在 worker-bootstrap.ts 的buildVerificationSection中生成。跨 CLI 一致性与团队协调门worker 协议设计为跨 CLI 一致ACK body 单行简短便于 Codex 与 Claude worker 解析。消息协议要求始终携带from_worker: workerName发给 leader 用to_worker: leader-fixed发给同伴用to_worker: worker-N对于独立扇出fan-out正常的 ACK、claim-safe 生命周期、状态与验证就足够保持轻量只有当任务涉及依赖、共享文件/表面、交接、集成、被阻塞 lane 或假设变化时才激活 Team Big Five / ATEM 启发式协调协议共享心智模型/单一事实源、ACK-readback 交接、边界监控、备份/重新分配请求、适应性检查点、团队结果导向。这一轻量默认按需升级的门控在 worker-bootstrap.ts 生成的 worker 指令Team Coordination Gate与renderCoordinationProtocol中体现协调任务的完成证据必须写明Coordination protocol: coordinated - handoffs/boundaries checked或Coordination protocol: no boundary handoff - why no boundary remained。常见错误与排障对照现象底层错误码源码处理方式认领任务失败提示冲突claim_conflicttasks.ts任务已被他人认领或租约未过期等待或改用其他任务认领失败提示依赖未就绪blocked_dependency检查blocked_by/depends_on先处理前置任务迁移被拒绝invalid_transition/already_terminal状态必须是in_progress且目标为completed/failed迁移失败提示租约过期lease_expiredclaim 已过期默认 15 分钟需重新认领完成任务被拒缺证据missing_delegation_compliance_evidence/missing_coordination_compliance_evidence在result中补充合规证据行使用旧team_*MCP 工具已硬弃用hard-deprecated改用omx team apiCLI interop不要传workingDirectory除非 leader 明确要求小结worker 是 OMX 团队运行时中职责最清晰的角色之一启动 ACK 建立存在感claim-safe 认领保证并发安全生命周期 API 保证状态机不被绕过邮箱协议保证双向消息可追踪idle/blocked 状态写回让 leader 与监视器可观测。理解 skills/worker/SKILL.md 这份协议再对照 worker-bootstrap.ts、tasks.ts、mailbox.ts 与 contracts.ts 的实现即可完整掌握 OMX 团队模式下 worker 的正确打开方式。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OMX Team Worker 协议实战指南：tmux 团队协作下的 ACK、任务生命周期与邮箱协议全解析

相关推荐

PyTorch TorchElastic Rendezvous 完整指南：分布式任务会合机制、Backend 注册与动态集群编排

龙芯2K0300平台VL53L0X激光测距驱动移植指南

如何把 Auth0 登录接入 Refine 并重写 /login 页面完成跳转？

更多资讯

分散搅拌釜选型指南与2023年TOP5机型评测

Java ThreadLocal原理、应用与内存泄漏防范

昇腾GE获取算子类型API

使用 @payloadcms/payload-cloud 插件：为 Payload Cloud 接入 S3 文件存储、Resend 邮件与上传缓存

CPython 跨语言错误提示机制详解：为 tuple / frozenset / frozendict 的 `.clear()` 提供可变类型纠正建议

机器人软件开发中实时性能优化的核心：无锁队列技术

今日更新

CopilotKit Vue Demo 与 React Demo 的 Parity 实现指南：路由、运行时端点与交互语义的全框架对齐

Harbor RBAC 实战：db_auth 模式下非管理员用户管理项目成员的完整验证与权限模型解析

STM32平衡车纯平衡程序从拆包到参数整定的完整调试指南

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？