企业官网建设流程全解析

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

导读

本文以 OmX（oh-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_WORKER=<team-name>/worker-<n>环境变量启动时，才应加载 worker 技能；
• 普通单独执行、或团队模式之外的有界实现/审查任务，应使用executor等角色，而不是 worker；
• worker 只负责执行分配给它的切片，遇到阻塞、共享文件冲突、范围扩大、缺权限或模式不匹配时，向上（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 技能文件从以下路径中按顺序取第一个存在的：

1. ${CODEX_HOME:-~/.codex}/skills/worker/SKILL.md
2. ~/.codex/skills/worker/SKILL.md
3. <leader_cwd>/.codex/skills/worker/SKILL.md
4. <leader_cwd>/skills/worker/SKILL.md（仓库内兜底，即本文对应的 skills/worker/SKILL.md）

这条解析逻辑在运行时由 worker-bootstrap.ts 生成 worker 指令时反复注入，确保不同 worker CLI（Codex/Claude）行为一致。

Team State Root 解析顺序

worker 必须解析出规范的团队状态根目录，顺序为：

1. 环境变量OMX_TEAM_STATE_ROOT
2. worker 身份文件中的team_state_root
3. 团队配置/manifest 中的team_state_root
4. 本地兜底.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 发送一条启动 ACK：

omx 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-fixed（leader 的固定 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 bridge（CreateMailboxMessage）落盘，bridge 不可用时回退到 legacy JSON 文件写入，并追加message_received团队事件与投递日志。

第 2 步：读取 inbox，取第一个未阻塞的任务

<team_state_root>/team/<teamName>/workers/<workerName>/inbox.md

inbox 是 worker 的任务分派入口，由 leader 通过write-worker-inbox或 bootstrap 生成。generateInitialInbox（worker-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 步：编辑前认领任务（claim）

omx team api claim-task --input '{"team_name":"<teamName>","task_id":"<id>","worker":"<workerName>"}' --json

claim 是可选的加expected_version（乐观并发校验），不传则不校验版本。认领成功后任务进入in_progress状态。

claim-safe 原理（源码级）：在 tasks.ts 的claimTask中，认领流程是：

1. 先读任务并计算 readiness（依赖blocked_dependency检查），未就绪直接拒绝；
2. 在withTaskClaimLock锁内重新读取当前状态做二次校验（防止竞态）；
3. 校验 worker 必须存在于团队配置中（否则worker_not_found）；
4. 若任务已是in_progress，只有当 claim 租约过期（leased_until已到）才能接管；否则返回claim_conflict；
5. 若任务pending/blocked且已有他人 owner，返回claim_conflict；
6. 认领成功后写入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>"}' --json

transition-task-status的必填字段为team_name、task_id、from、to、claim_token，可选字段result（completed 时）与error（failed 时）。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']

transitionTaskStatus（tasks.ts）在锁内校验：

• 当前状态必须等于from，且from -> to必须是合法迁移（否则invalid_transition）；
• 任务不能已是终态（already_terminal）；
• claim.owner必须等于owner、claim.token必须等于传入的claim_token（否则claim_conflict）；
• claim 租约必须未过期（否则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>"}' --json

mailbox 位于<team_state_root>/team/<teamName>/mailbox/<workerName>.json，leader 的固定为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>。

常见错误与排障对照

小结

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