OmX v0.8.6 事件感知团队编排omx team await与 prompt-guidance 体系升级实战解析【免费下载链接】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-codexOmXoh-my-codex在 v0.8.6 中为团队编排引入了「事件感知等待」能力编排方不再只能等到任务终态而是可以监听团队事件流中的任意关键事件如 worker 状态迁移、合并冲突、消息到达并新增omx team await team-nameCLI 命令支撑这一流程同期还完成了 GPT-5.4 prompt-guidance 模式在核心提示词与技能体系中的两轮推广。本文以 docs/release-notes-0.8.6.md 为主干结合 src/team/state/events.ts、src/team/contracts.ts、src/team/runtime.ts 与 src/cli/team.ts 等源码讲清事件等待的调用链、事件类型与规范化语义、CLI 实战参数以及 prompt 体系的落地文件清单帮助你在自己的编排脚本与工作流中直接复用这套能力。一、版本背景v0.8.6 定位与变更总览v0.8.6 发布于 2026-03-07是main..dev分支上的一个紧凑迭代共包含4 个非 merge 提交、69 个文件变更1,745 / -71。从完整提交日志v0.8.5..v0.8.6可以看出本次版本的全部工作内容9d3e2a2 fix(team): harden leader follow-up and event-aware waiting (#609) c13290a fix(team): keep team-ops gateway contract stable (#610) 9d4b1ea feat: apply GPT-5.4 prompt-guidance patterns 76e3918 feat: expand GPT-5.4 prompt guidance across prompts and skills两条主线一目了然事件感知团队等待与运行时协调#609让团队编排在「终态完成」之外还可以等待规范的团队事件。GPT-5.4 prompt-guidance 推广与扩展#611、#612对应 issue #608对核心提示词表面与更广泛的提示词/技能目录进行两轮更新。下文将分别深入这两条主线。二、事件感知团队等待Event-aware team waiting核心机制2.1 能力概览从「等待终态」到「等待事件」在 v0.8.6 之前OMX 团队编排的等待语义主要围绕任务/团队的「终结完成」展开。v0.8.6 将其扩展为事件驱动模型新增能力包括对omx_run_team_wait增加**增量式additive**的wake_onevent/after_event_id支持在团队状态层team state layer引入共享的事件读取、规范化与游标cursor辅助函数在契约层contracts、运行时状态runtime state与 API 互操作层API interop中统一规范事件类型新增omx team await team-nameCLI 支持运行时在保留旧版worker_idle兼容性的同时发出规范的worker_state_changed事件提升 notify-fallback watcher 的派发/排空进度与延迟 leader 状态的可观测性。从实现位置看这套能力落在团队状态层的事件模块 src/team/state/events.ts并被 CLIsrc/cli/team.ts与 API 互操作层src/team/api-interop.ts共同复用。2.2 事件类型契约TEAM_EVENT_TYPES与可唤醒事件集合团队事件的全部合法类型定义在 src/team/contracts.ts 中共 31 种export const TEAM_EVENT_TYPES [ task_completed, task_failed, worker_state_changed, worker_idle, worker_stopped, message_received, leader_notification_deferred, all_workers_idle, shutdown_ack, shutdown_gate, shutdown_gate_forced, ralph_cleanup_policy, ralph_cleanup_summary, approval_decision, team_leader_nudge, worker_diff_activity, worker_diff_report, worker_merge_report, worker_merge_conflict, worker_integration_failed, worker_integration_attempt_requested, worker_cherry_pick_detected, worker_cherry_pick_applied, worker_cherry_pick_conflict, worker_rebase_applied, worker_rebase_conflict, worker_cross_rebase_applied, worker_cross_rebase_conflict, worker_cross_rebase_skipped, worker_stale_diff, worker_stale_heartbeat, worker_stale_stdout, ] as const;并非所有事件都适合唤醒等待者。契约层进一步定义了可唤醒事件集合TEAM_WAKEABLE_EVENT_TYPESsrc/team/contracts.ts并由isWakeableTeamEventType(type)判定src/team/contracts.tsexport const TEAM_WAKEABLE_EVENT_TYPES: ReadonlySetTeamEventType new Set([ worker_state_changed, task_completed, task_failed, worker_stopped, message_received, leader_notification_deferred, all_workers_idle, team_leader_nudge, worker_integration_failed, worker_integration_attempt_requested, worker_merge_conflict, worker_cherry_pick_conflict, worker_rebase_conflict, worker_cross_rebase_conflict, worker_stale_diff, worker_stale_heartbeat, worker_stale_stdout, ]);值得注意可唤醒集合不仅覆盖基础状态变化worker_state_changed、all_workers_idle、worker_stopped还包含合并冲突与各类 stale 告警worker_merge_conflict、worker_cherry_pick_conflict、worker_rebase_conflict、worker_stale_diff、worker_stale_heartbeat、worker_stale_stdout。这正是 v0.8.6 中「可唤醒事件现在包括合并冲突和按信号区分的 stale 告警」的契约层来源——编排方可以及时感知 worker 卡死或集成冲突而不是傻等终态。2.3 事件读取与规范化readTeamEvents的游标语义src/team/state/events.ts 是这套能力的核心实现。先看读取函数readTeamEventssrc/team/state/events.tsexport async function readTeamEvents( teamName: string, cwd: string, opts: TeamEventReadOptions {}, ): PromiseTeamEvent[] { const path teamEventLogPath(teamName, cwd); if (!existsSync(path)) return []; const raw await readFile(path, utf-8).catch(() ); if (!raw.trim()) return []; const events: TeamEvent[] []; let started !opts.afterEventId; // ...逐行 JSON.parse经 normalizeRawTeamEvent 规范化 // 以 afterEventId 为游标跳过旧事件再按 wakeableOnly/type/worker/taskId 过滤 return events; }其关键设计是游标cursor语义after_event_id指定从哪个事件 ID 之后开始读取不含该事件本身。若未提供则从日志头读取。getLatestTeamEventCursorsrc/team/state/events.ts返回事件日志中最后一条事件的 event_id作为「当前位置」的基准游标。读取选项TeamEventReadOptionssrc/team/state/events.ts还支持wakeableOnly、type、worker、taskId等过滤条件。2.4 兼容性核心worker_idle→worker_state_changed的规范化v0.8.6 强调「运行时发出worker_state_changed同时保留旧版worker_idle兼容性」。这一语义由normalizeRawTeamEventsrc/team/state/events.ts实现if (type worker_idle) { return { ...(value as TeamEvent), event_id: eventId, team, type: worker_state_changed, // 归一化为规范事件类型 source_type: worker_idle, // 保留来源标记 worker, state: idle, prev_state: asWorkerState(value.prev_state), created_at: createdAt, }; }也就是说事件日志中若存在旧格式的worker_idle记录读取层会自动将其规范化为worker_state_changed类型、state: idle并通过source_type: worker_idle保留溯源信息。matchesEventTypesrc/team/state/events.ts进一步允许以typeworker_idle查询时命中source_type worker_idle的事件。这样旧消费者仍然可以按worker_idle查询新消费者则统一消费规范的worker_state_changed。此外isDuplicateNormalizedEventsrc/team/state/events.ts会对紧邻的重复状态变化事件去重避免状态相同、仅来源不同的事件重复计数。运行时侧的实际写入证据在 src/team/runtime.ts当 monitor 发现 worker 状态从prevState变为新状态时追加worker_state_changed事件当 worker 从非idle转入idle时追加worker_idle事件带source_type: worker_idle两者同时保留正是「双轨兼容」的实现基础if (prevState prevState ! worker.status.state) { await appendTeamEvent(teamName, { type: worker_state_changed, worker: worker.name, task_id: worker.status.current_task_id, reason: worker.status.reason, state: worker.status.state, prev_state: prevState, }, cwd); } if (prevState prevState ! idle worker.status.state idle) { await appendTeamEvent(teamName, { type: worker_idle, worker: worker.name, task_id: worker.status.current_task_id, reason: undefined, prev_state: prevState, state: idle, source_type: worker_idle, }, cwd); }2.5 等待原语waitForTeamEvent的轮询与退避waitForTeamEventsrc/team/state/events.ts是底层等待原语export async function waitForTeamEvent( teamName: string, cwd: string, opts: { afterEventId?: string; timeoutMs: number; pollMs?: number; wakeableOnly?: boolean; type?: TeamEvent[type] | worker_idle; worker?: string; taskId?: string; }, ): Promise{ status: event | timeout; event?: TeamEvent; cursor: string } { const deadline Date.now() Math.max(0, Math.floor(opts.timeoutMs)); let pollMs Math.max(25, Math.floor(opts.pollMs ?? 100)); const baseline opts.afterEventId ?? await getLatestTeamEventCursor(teamName, cwd); while (Date.now() deadline) { const events await readTeamEvents(teamName, cwd, { afterEventId: baseline, wakeableOnly: opts.wakeableOnly ! false, type: opts.type, worker: opts.worker, taskId: opts.taskId, }); const event events[0]; if (event) return { status: event, event, cursor: event.event_id }; await new Promise((resolve) setTimeout(resolve, pollMs)); pollMs Math.min(Math.floor(pollMs * 1.5), 500); // 指数退避25ms 起步上限 500ms } return { status: timeout, cursor: baseline }; }要点超时语义到timeoutMs仍未等到匹配事件时返回{ status: timeout }不会无限阻塞。轮询退避初始轮询间隔为pollMs默认 100ms下限 25ms每次未命中按 1.5 倍递增封顶 500ms兼顾响应速度与 IO 开销。默认过滤wakeableOnly默认true即默认只关心可唤醒事件调用方也可显式关闭以读取全量事件流。返回值命中时返回事件对象与新游标该事件的event_id便于调用方接力下一次等待。三、omx team awaitCLI 实战用法3.1 命令形态与参数v0.8.6 新增的 CLI 入口位于 src/cli/team.ts帮助文本给出如下用法src/cli/team.tsomx team await team-name [--timeout-ms ms] [--after-event-id id] [--json]参数说明依据 src/cli/team.ts 的实现参数含义默认值说明team-name要等待的团队名必填会经resolveTeamNameForCurrentContext解析当前上下文中的团队名--timeout-ms ms等待超时毫秒30_00030 秒使用parseInt解析并强制 1--after-event-id id游标仅等待该事件 ID 之后的新事件事件日志中最后一条可唤醒事件的 ID用于多次调用间接力、避免重复消费--json以 JSON 输出结果关闭结构化输出便于脚本消费3.2 执行流程与边界情况await子命令的完整执行逻辑src/cli/team.ts可以概括为团队存在性检查调用readTeamConfig若团队状态不存在输出No team state found for nameJSON 模式下输出{ team_name, status: missing, cursor, event: null }并直接返回。基准游标计算baselineCursor afterEventId || 事件日志中最后一条可唤醒事件的 ID。也就是说未显式传游标时默认从当前最后一条可唤醒事件之后开始等待「新事件」。立即命中检查先读取afterEventId之后的第一条可唤醒事件若存在直接返回status: event无需进入轮询。死 worker 特殊处理若monitorTeam快照显示存在死 worker 停摆snapshotHasDeadWorkerStall会尝试返回最后一条可唤醒事件或在无事件时构造一个dead_worker_detected_during_await的 fallback 事件buildDeadWorkerAwaitEventsrc/cli/team.ts避免编排方在 worker 挂掉后无限等待。常规轮询否则进入waitForTeamEventpollMs: 100、wakeableOnly: true直到命中或超时。输出格式非 JSON 模式下命中时输出一行紧凑上下文例如teammy-team eventworker_state_changed workerworker-1 stateidle prevworking task3 cursorevt-00017JSON 模式下输出结构化对象src/cli/team.ts{ team_name: my-team, status: event, cursor: evt-00017, event: { event_id: evt-00017, type: worker_state_changed, worker: worker-1, task_id: 3, created_at: 2026-03-07T..., state: idle, prev_state: working } }超时则输出No new event for name before timeout (timeoutMsms).。3.3 典型编排场景场景一等待某个 worker 进入 idle再接续下一批任务# 等待 my-team 中任何可唤醒事件默认 30s 超时 omx team await my-team --json # 显式延长超时并指定游标从上次位置继续等 omx team await my-team --timeout-ms 120000 --after-event-id evt-00017 --json场景二把await嵌入脚本做流水线门控# 启动团队 → 等待终态/关键事件 → 继续后续流程 omx team 3:executor fix failing tests omx team await my-team --timeout-ms 300000 --json # 依据返回的 event.type 决定下一步动作如处理 worker_merge_conflict场景三通过 API 互操作层使用等价的await-event操作omx team api await-event提供与 CLI 等价的底层操作src/cli/team.ts可选字段为after_event_id、timeout_ms、poll_ms、wakeable_only、type、worker、task_idsrc/cli/team.tsomx team api await-event \ --input {team_name:my-team,type:worker_state_changed,worker:worker-1,timeout_ms:60000} \ --json对应的read-events操作则可用于非阻塞地查询事件可选after_event_id、wakeable_only、type、worker、task_id其帮助说明特别指出事件以规范形式返回worker_idle日志项会规范化为type: worker_state_changedsource_type: worker_idlewakeable_only默认false设为true可镜像omx team await的语义src/cli/team.ts。四、notify-fallback watcher 与 leader 状态可见性提升v0.8.6 还改进了notify-fallback watcher的可观测性派发/排空dispatch/drain进度与延迟的 leader 状态deferred leader state现在更透明。这在状态读取侧有直接体现。readTeamEvents返回的规范事件中包含leader_notification_deferredleader 通知被延迟与team_leader_nudgeleader 被提醒等事件类型而 API 互操作层的read-stall-state操作src/team/api-interop.ts会把它们聚合进结构化的停摆诊断中last_team_leader_nudge_event最近一次 leader 提醒事件last_leader_notification_deferred_event最近一次 leader 通知被延迟的事件leader_attention_pending存在未读 leader 邮件、待派发请求或 leader 会话停止时置真reasons以机器可读字符串列出停摆原因如workers_non_reporting:names、leader_decision_pending:done_waiting_on_leader。这意味着编排方不仅能等待事件还能在事件到来后快速解释「团队为什么没有进展」——是 worker 失联、leader 决策挂起还是通知被延迟。配合read-idle-state基于 monitor 快照、团队摘要与近期事件构建 idle 摘要见 src/team/api-interop.ts可以在等待循环里同时做健康巡检。五、GPT-5.4 prompt-guidance 推广与扩展5.1 两轮更新的覆盖范围v0.8.6 的另一主线是将 OpenAI GPT-5.4 的 prompt-guidance 模式落到 OMX 的提示词与工作流表面分两轮完成核心表面Core-surface pass#611对应 issue #608根目录AGENTS.mdAGENTS.md模板目录 templates/AGENTS.md提示词 prompts/executor.md、prompts/planner.md、prompts/verifier.mdsrc/config/generator.ts中生成的developer_instructions文本针对 prompt-contract 预期的聚焦回归覆盖focused regression coverage。扩展表面Expansion pass#612作为 #611 的跟进更广泛的 agent 提示词目录analyst、architect、debugger、researcher、security-reviewer、writer等执行密集型技能analyze、autopilot、build-fix、code-review、plan、ralph、ralplan、security-review、team、ultraqa等针对提示词目录、场景示例、第二波引导wave-two guidance与技能引导契约的额外回归覆盖。5.2 行为侧重点五条执行契约根据发布说明两轮更新后提示词对行为侧的强调更明确地覆盖五条执行契约默认紧凑、信息密集的输出compact, information-dense output by default对清晰、低风险、可逆的下一步自动跟进automatic follow-through on clear, low-risk, reversible next steps对任务中途用户干预的本地化处理localized handling of mid-task user overrides当正确性依赖于检索、诊断或验证时持续使用工具continued tool usage when correctness depends on retrieval, diagnostics, or verification用场景式示例强化跨提示词与技能的预期执行契约scenario-style examples that reinforce the intended execution contract。这五条契约与仓库中已有的 prompt-guidance 体系一致例如 docs/prompt-guidance-contract.md 定义了引导契约而 docs/prompt-guidance-fragments/ 下的executor-constraints.md、planner-investigation.md、verifier-output.md等片段分别约束了执行者、规划者与验证者的行为面v0.8.6 只是把 GPT-5.4 的表述方式进一步统一进这些表面。5.3 配套测试证据两轮更新都强调「聚焦回归覆盖」涉及 prompt 契约、提示词目录、场景示例、第二波引导与技能引导契约。这与仓库现有测试结构吻合——例如 src/config/tests/ 与 src/hooks/tests/prompt-guidance-contract* 区域都是验证生成提示词与契约一致性的典型位置。需要说明的是v0.8.6 对应年代的测试用例可能已被后续版本演进此处引用的是当前仓库中仍然存在的 prompt 契约测试骨架src/hooks/tests/prompt-guidance-contract.ts、src/hooks/prompt-guidance-contract.ts用于佐证「回归覆盖」这一做法在该项目中是持续存在的。六、Bug 修复team-ops gateway 契约恢复v0.8.6 同时修复了一个由事件感知等待改动引入的回归合并后的一次跟进#610恢复了team-opsgateway 的预期公开导出面。具体做法是移除误加的teamEventLogPath再导出使严格的team-ops模块契约测试保持稳定。从当前源码可以看到这一契约纪律仍然生效src/team/api-interop.ts 从team-ops.js精确导入了一组命名符号teamAppendEvent、teamGetSummary、teamReadConfig等并只将受控的LEGACY_TEAM_MCP_TOOLS与TEAM_API_OPERATIONS作为公开面导出src/team/api-interop.ts——公开导出面是经过显式审计的任何误加的符号都会被严格的契约测试拦截。七、小结与上手建议v0.8.6 为 OMX 团队编排补上了两块拼图事件驱动的等待语义omx team awaitread-events/await-eventAPI 互操作配合after_event_id游标、可唤醒事件集合与worker_idle→worker_state_changed兼容规范化让编排方可以精确等待「关键状态迁移、合并冲突、stale 告警」等中间事件而不是只能等待终态。底层原语集中在 src/team/state/events.ts类型契约在 src/team/contracts.tsCLI 入口在 src/cli/team.ts。统一的行为执行契约以 GPT-5.4 prompt-guidance 模式重写核心与扩展提示词/技能强调紧凑输出、自动跟进、局部化干预处理、持续工具使用与场景式示例。上手建议编写团队流水线脚本时优先使用omx team await team-name --after-event-id last-cursor --json做幂等接力等待将返回的cursor存下来传给下一轮需要等待特定 worker 或特定事件类型时用omx team api await-event传入type/worker/task_id过滤怀疑团队停滞时结合omx team api read-stall-state的reasons字段定位是 worker 失联、leader 决策挂起还是通知延迟再决定干预动作。需要注意的边界omx team默认是 tmux 运行时表面在 Codex App 或普通非 tmux 会话中应先从 shell 启动 OMX CLI 再使用团队命令src/cli/team.ts 的 help 说明小而短的 fanout 更适合原生 Codex subagentsomx team用于需要持久 tmux/状态/worktree 协调的场景。以上 CLI 参数与默认值均以当前仓库 src/cli/team.ts 的实现为准不同版本可能有细微差异。【免费下载链接】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 v0.8.6 事件感知团队编排：`omx team await` 与 prompt-guidance 体系升级实战解析
OmX v0.8.6 事件感知团队编排omx team await与 prompt-guidance 体系升级实战解析【免费下载链接】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-codexOmXoh-my-codex在 v0.8.6 中为团队编排引入了「事件感知等待」能力编排方不再只能等到任务终态而是可以监听团队事件流中的任意关键事件如 worker 状态迁移、合并冲突、消息到达并新增omx team await team-nameCLI 命令支撑这一流程同期还完成了 GPT-5.4 prompt-guidance 模式在核心提示词与技能体系中的两轮推广。本文以 docs/release-notes-0.8.6.md 为主干结合 src/team/state/events.ts、src/team/contracts.ts、src/team/runtime.ts 与 src/cli/team.ts 等源码讲清事件等待的调用链、事件类型与规范化语义、CLI 实战参数以及 prompt 体系的落地文件清单帮助你在自己的编排脚本与工作流中直接复用这套能力。一、版本背景v0.8.6 定位与变更总览v0.8.6 发布于 2026-03-07是main..dev分支上的一个紧凑迭代共包含4 个非 merge 提交、69 个文件变更1,745 / -71。从完整提交日志v0.8.5..v0.8.6可以看出本次版本的全部工作内容9d3e2a2 fix(team): harden leader follow-up and event-aware waiting (#609) c13290a fix(team): keep team-ops gateway contract stable (#610) 9d4b1ea feat: apply GPT-5.4 prompt-guidance patterns 76e3918 feat: expand GPT-5.4 prompt guidance across prompts and skills两条主线一目了然事件感知团队等待与运行时协调#609让团队编排在「终态完成」之外还可以等待规范的团队事件。GPT-5.4 prompt-guidance 推广与扩展#611、#612对应 issue #608对核心提示词表面与更广泛的提示词/技能目录进行两轮更新。下文将分别深入这两条主线。二、事件感知团队等待Event-aware team waiting核心机制2.1 能力概览从「等待终态」到「等待事件」在 v0.8.6 之前OMX 团队编排的等待语义主要围绕任务/团队的「终结完成」展开。v0.8.6 将其扩展为事件驱动模型新增能力包括对omx_run_team_wait增加**增量式additive**的wake_onevent/after_event_id支持在团队状态层team state layer引入共享的事件读取、规范化与游标cursor辅助函数在契约层contracts、运行时状态runtime state与 API 互操作层API interop中统一规范事件类型新增omx team await team-nameCLI 支持运行时在保留旧版worker_idle兼容性的同时发出规范的worker_state_changed事件提升 notify-fallback watcher 的派发/排空进度与延迟 leader 状态的可观测性。从实现位置看这套能力落在团队状态层的事件模块 src/team/state/events.ts并被 CLIsrc/cli/team.ts与 API 互操作层src/team/api-interop.ts共同复用。2.2 事件类型契约TEAM_EVENT_TYPES与可唤醒事件集合团队事件的全部合法类型定义在 src/team/contracts.ts 中共 31 种export const TEAM_EVENT_TYPES [ task_completed, task_failed, worker_state_changed, worker_idle, worker_stopped, message_received, leader_notification_deferred, all_workers_idle, shutdown_ack, shutdown_gate, shutdown_gate_forced, ralph_cleanup_policy, ralph_cleanup_summary, approval_decision, team_leader_nudge, worker_diff_activity, worker_diff_report, worker_merge_report, worker_merge_conflict, worker_integration_failed, worker_integration_attempt_requested, worker_cherry_pick_detected, worker_cherry_pick_applied, worker_cherry_pick_conflict, worker_rebase_applied, worker_rebase_conflict, worker_cross_rebase_applied, worker_cross_rebase_conflict, worker_cross_rebase_skipped, worker_stale_diff, worker_stale_heartbeat, worker_stale_stdout, ] as const;并非所有事件都适合唤醒等待者。契约层进一步定义了可唤醒事件集合TEAM_WAKEABLE_EVENT_TYPESsrc/team/contracts.ts并由isWakeableTeamEventType(type)判定src/team/contracts.tsexport const TEAM_WAKEABLE_EVENT_TYPES: ReadonlySetTeamEventType new Set([ worker_state_changed, task_completed, task_failed, worker_stopped, message_received, leader_notification_deferred, all_workers_idle, team_leader_nudge, worker_integration_failed, worker_integration_attempt_requested, worker_merge_conflict, worker_cherry_pick_conflict, worker_rebase_conflict, worker_cross_rebase_conflict, worker_stale_diff, worker_stale_heartbeat, worker_stale_stdout, ]);值得注意可唤醒集合不仅覆盖基础状态变化worker_state_changed、all_workers_idle、worker_stopped还包含合并冲突与各类 stale 告警worker_merge_conflict、worker_cherry_pick_conflict、worker_rebase_conflict、worker_stale_diff、worker_stale_heartbeat、worker_stale_stdout。这正是 v0.8.6 中「可唤醒事件现在包括合并冲突和按信号区分的 stale 告警」的契约层来源——编排方可以及时感知 worker 卡死或集成冲突而不是傻等终态。2.3 事件读取与规范化readTeamEvents的游标语义src/team/state/events.ts 是这套能力的核心实现。先看读取函数readTeamEventssrc/team/state/events.tsexport async function readTeamEvents( teamName: string, cwd: string, opts: TeamEventReadOptions {}, ): PromiseTeamEvent[] { const path teamEventLogPath(teamName, cwd); if (!existsSync(path)) return []; const raw await readFile(path, utf-8).catch(() ); if (!raw.trim()) return []; const events: TeamEvent[] []; let started !opts.afterEventId; // ...逐行 JSON.parse经 normalizeRawTeamEvent 规范化 // 以 afterEventId 为游标跳过旧事件再按 wakeableOnly/type/worker/taskId 过滤 return events; }其关键设计是游标cursor语义after_event_id指定从哪个事件 ID 之后开始读取不含该事件本身。若未提供则从日志头读取。getLatestTeamEventCursorsrc/team/state/events.ts返回事件日志中最后一条事件的 event_id作为「当前位置」的基准游标。读取选项TeamEventReadOptionssrc/team/state/events.ts还支持wakeableOnly、type、worker、taskId等过滤条件。2.4 兼容性核心worker_idle→worker_state_changed的规范化v0.8.6 强调「运行时发出worker_state_changed同时保留旧版worker_idle兼容性」。这一语义由normalizeRawTeamEventsrc/team/state/events.ts实现if (type worker_idle) { return { ...(value as TeamEvent), event_id: eventId, team, type: worker_state_changed, // 归一化为规范事件类型 source_type: worker_idle, // 保留来源标记 worker, state: idle, prev_state: asWorkerState(value.prev_state), created_at: createdAt, }; }也就是说事件日志中若存在旧格式的worker_idle记录读取层会自动将其规范化为worker_state_changed类型、state: idle并通过source_type: worker_idle保留溯源信息。matchesEventTypesrc/team/state/events.ts进一步允许以typeworker_idle查询时命中source_type worker_idle的事件。这样旧消费者仍然可以按worker_idle查询新消费者则统一消费规范的worker_state_changed。此外isDuplicateNormalizedEventsrc/team/state/events.ts会对紧邻的重复状态变化事件去重避免状态相同、仅来源不同的事件重复计数。运行时侧的实际写入证据在 src/team/runtime.ts当 monitor 发现 worker 状态从prevState变为新状态时追加worker_state_changed事件当 worker 从非idle转入idle时追加worker_idle事件带source_type: worker_idle两者同时保留正是「双轨兼容」的实现基础if (prevState prevState ! worker.status.state) { await appendTeamEvent(teamName, { type: worker_state_changed, worker: worker.name, task_id: worker.status.current_task_id, reason: worker.status.reason, state: worker.status.state, prev_state: prevState, }, cwd); } if (prevState prevState ! idle worker.status.state idle) { await appendTeamEvent(teamName, { type: worker_idle, worker: worker.name, task_id: worker.status.current_task_id, reason: undefined, prev_state: prevState, state: idle, source_type: worker_idle, }, cwd); }2.5 等待原语waitForTeamEvent的轮询与退避waitForTeamEventsrc/team/state/events.ts是底层等待原语export async function waitForTeamEvent( teamName: string, cwd: string, opts: { afterEventId?: string; timeoutMs: number; pollMs?: number; wakeableOnly?: boolean; type?: TeamEvent[type] | worker_idle; worker?: string; taskId?: string; }, ): Promise{ status: event | timeout; event?: TeamEvent; cursor: string } { const deadline Date.now() Math.max(0, Math.floor(opts.timeoutMs)); let pollMs Math.max(25, Math.floor(opts.pollMs ?? 100)); const baseline opts.afterEventId ?? await getLatestTeamEventCursor(teamName, cwd); while (Date.now() deadline) { const events await readTeamEvents(teamName, cwd, { afterEventId: baseline, wakeableOnly: opts.wakeableOnly ! false, type: opts.type, worker: opts.worker, taskId: opts.taskId, }); const event events[0]; if (event) return { status: event, event, cursor: event.event_id }; await new Promise((resolve) setTimeout(resolve, pollMs)); pollMs Math.min(Math.floor(pollMs * 1.5), 500); // 指数退避25ms 起步上限 500ms } return { status: timeout, cursor: baseline }; }要点超时语义到timeoutMs仍未等到匹配事件时返回{ status: timeout }不会无限阻塞。轮询退避初始轮询间隔为pollMs默认 100ms下限 25ms每次未命中按 1.5 倍递增封顶 500ms兼顾响应速度与 IO 开销。默认过滤wakeableOnly默认true即默认只关心可唤醒事件调用方也可显式关闭以读取全量事件流。返回值命中时返回事件对象与新游标该事件的event_id便于调用方接力下一次等待。三、omx team awaitCLI 实战用法3.1 命令形态与参数v0.8.6 新增的 CLI 入口位于 src/cli/team.ts帮助文本给出如下用法src/cli/team.tsomx team await team-name [--timeout-ms ms] [--after-event-id id] [--json]参数说明依据 src/cli/team.ts 的实现参数含义默认值说明team-name要等待的团队名必填会经resolveTeamNameForCurrentContext解析当前上下文中的团队名--timeout-ms ms等待超时毫秒30_00030 秒使用parseInt解析并强制 1--after-event-id id游标仅等待该事件 ID 之后的新事件事件日志中最后一条可唤醒事件的 ID用于多次调用间接力、避免重复消费--json以 JSON 输出结果关闭结构化输出便于脚本消费3.2 执行流程与边界情况await子命令的完整执行逻辑src/cli/team.ts可以概括为团队存在性检查调用readTeamConfig若团队状态不存在输出No team state found for nameJSON 模式下输出{ team_name, status: missing, cursor, event: null }并直接返回。基准游标计算baselineCursor afterEventId || 事件日志中最后一条可唤醒事件的 ID。也就是说未显式传游标时默认从当前最后一条可唤醒事件之后开始等待「新事件」。立即命中检查先读取afterEventId之后的第一条可唤醒事件若存在直接返回status: event无需进入轮询。死 worker 特殊处理若monitorTeam快照显示存在死 worker 停摆snapshotHasDeadWorkerStall会尝试返回最后一条可唤醒事件或在无事件时构造一个dead_worker_detected_during_await的 fallback 事件buildDeadWorkerAwaitEventsrc/cli/team.ts避免编排方在 worker 挂掉后无限等待。常规轮询否则进入waitForTeamEventpollMs: 100、wakeableOnly: true直到命中或超时。输出格式非 JSON 模式下命中时输出一行紧凑上下文例如teammy-team eventworker_state_changed workerworker-1 stateidle prevworking task3 cursorevt-00017JSON 模式下输出结构化对象src/cli/team.ts{ team_name: my-team, status: event, cursor: evt-00017, event: { event_id: evt-00017, type: worker_state_changed, worker: worker-1, task_id: 3, created_at: 2026-03-07T..., state: idle, prev_state: working } }超时则输出No new event for name before timeout (timeoutMsms).。3.3 典型编排场景场景一等待某个 worker 进入 idle再接续下一批任务# 等待 my-team 中任何可唤醒事件默认 30s 超时 omx team await my-team --json # 显式延长超时并指定游标从上次位置继续等 omx team await my-team --timeout-ms 120000 --after-event-id evt-00017 --json场景二把await嵌入脚本做流水线门控# 启动团队 → 等待终态/关键事件 → 继续后续流程 omx team 3:executor fix failing tests omx team await my-team --timeout-ms 300000 --json # 依据返回的 event.type 决定下一步动作如处理 worker_merge_conflict场景三通过 API 互操作层使用等价的await-event操作omx team api await-event提供与 CLI 等价的底层操作src/cli/team.ts可选字段为after_event_id、timeout_ms、poll_ms、wakeable_only、type、worker、task_idsrc/cli/team.tsomx team api await-event \ --input {team_name:my-team,type:worker_state_changed,worker:worker-1,timeout_ms:60000} \ --json对应的read-events操作则可用于非阻塞地查询事件可选after_event_id、wakeable_only、type、worker、task_id其帮助说明特别指出事件以规范形式返回worker_idle日志项会规范化为type: worker_state_changedsource_type: worker_idlewakeable_only默认false设为true可镜像omx team await的语义src/cli/team.ts。四、notify-fallback watcher 与 leader 状态可见性提升v0.8.6 还改进了notify-fallback watcher的可观测性派发/排空dispatch/drain进度与延迟的 leader 状态deferred leader state现在更透明。这在状态读取侧有直接体现。readTeamEvents返回的规范事件中包含leader_notification_deferredleader 通知被延迟与team_leader_nudgeleader 被提醒等事件类型而 API 互操作层的read-stall-state操作src/team/api-interop.ts会把它们聚合进结构化的停摆诊断中last_team_leader_nudge_event最近一次 leader 提醒事件last_leader_notification_deferred_event最近一次 leader 通知被延迟的事件leader_attention_pending存在未读 leader 邮件、待派发请求或 leader 会话停止时置真reasons以机器可读字符串列出停摆原因如workers_non_reporting:names、leader_decision_pending:done_waiting_on_leader。这意味着编排方不仅能等待事件还能在事件到来后快速解释「团队为什么没有进展」——是 worker 失联、leader 决策挂起还是通知被延迟。配合read-idle-state基于 monitor 快照、团队摘要与近期事件构建 idle 摘要见 src/team/api-interop.ts可以在等待循环里同时做健康巡检。五、GPT-5.4 prompt-guidance 推广与扩展5.1 两轮更新的覆盖范围v0.8.6 的另一主线是将 OpenAI GPT-5.4 的 prompt-guidance 模式落到 OMX 的提示词与工作流表面分两轮完成核心表面Core-surface pass#611对应 issue #608根目录AGENTS.mdAGENTS.md模板目录 templates/AGENTS.md提示词 prompts/executor.md、prompts/planner.md、prompts/verifier.mdsrc/config/generator.ts中生成的developer_instructions文本针对 prompt-contract 预期的聚焦回归覆盖focused regression coverage。扩展表面Expansion pass#612作为 #611 的跟进更广泛的 agent 提示词目录analyst、architect、debugger、researcher、security-reviewer、writer等执行密集型技能analyze、autopilot、build-fix、code-review、plan、ralph、ralplan、security-review、team、ultraqa等针对提示词目录、场景示例、第二波引导wave-two guidance与技能引导契约的额外回归覆盖。5.2 行为侧重点五条执行契约根据发布说明两轮更新后提示词对行为侧的强调更明确地覆盖五条执行契约默认紧凑、信息密集的输出compact, information-dense output by default对清晰、低风险、可逆的下一步自动跟进automatic follow-through on clear, low-risk, reversible next steps对任务中途用户干预的本地化处理localized handling of mid-task user overrides当正确性依赖于检索、诊断或验证时持续使用工具continued tool usage when correctness depends on retrieval, diagnostics, or verification用场景式示例强化跨提示词与技能的预期执行契约scenario-style examples that reinforce the intended execution contract。这五条契约与仓库中已有的 prompt-guidance 体系一致例如 docs/prompt-guidance-contract.md 定义了引导契约而 docs/prompt-guidance-fragments/ 下的executor-constraints.md、planner-investigation.md、verifier-output.md等片段分别约束了执行者、规划者与验证者的行为面v0.8.6 只是把 GPT-5.4 的表述方式进一步统一进这些表面。5.3 配套测试证据两轮更新都强调「聚焦回归覆盖」涉及 prompt 契约、提示词目录、场景示例、第二波引导与技能引导契约。这与仓库现有测试结构吻合——例如 src/config/tests/ 与 src/hooks/tests/prompt-guidance-contract* 区域都是验证生成提示词与契约一致性的典型位置。需要说明的是v0.8.6 对应年代的测试用例可能已被后续版本演进此处引用的是当前仓库中仍然存在的 prompt 契约测试骨架src/hooks/tests/prompt-guidance-contract.ts、src/hooks/prompt-guidance-contract.ts用于佐证「回归覆盖」这一做法在该项目中是持续存在的。六、Bug 修复team-ops gateway 契约恢复v0.8.6 同时修复了一个由事件感知等待改动引入的回归合并后的一次跟进#610恢复了team-opsgateway 的预期公开导出面。具体做法是移除误加的teamEventLogPath再导出使严格的team-ops模块契约测试保持稳定。从当前源码可以看到这一契约纪律仍然生效src/team/api-interop.ts 从team-ops.js精确导入了一组命名符号teamAppendEvent、teamGetSummary、teamReadConfig等并只将受控的LEGACY_TEAM_MCP_TOOLS与TEAM_API_OPERATIONS作为公开面导出src/team/api-interop.ts——公开导出面是经过显式审计的任何误加的符号都会被严格的契约测试拦截。七、小结与上手建议v0.8.6 为 OMX 团队编排补上了两块拼图事件驱动的等待语义omx team awaitread-events/await-eventAPI 互操作配合after_event_id游标、可唤醒事件集合与worker_idle→worker_state_changed兼容规范化让编排方可以精确等待「关键状态迁移、合并冲突、stale 告警」等中间事件而不是只能等待终态。底层原语集中在 src/team/state/events.ts类型契约在 src/team/contracts.tsCLI 入口在 src/cli/team.ts。统一的行为执行契约以 GPT-5.4 prompt-guidance 模式重写核心与扩展提示词/技能强调紧凑输出、自动跟进、局部化干预处理、持续工具使用与场景式示例。上手建议编写团队流水线脚本时优先使用omx team await team-name --after-event-id last-cursor --json做幂等接力等待将返回的cursor存下来传给下一轮需要等待特定 worker 或特定事件类型时用omx team api await-event传入type/worker/task_id过滤怀疑团队停滞时结合omx team api read-stall-state的reasons字段定位是 worker 失联、leader 决策挂起还是通知延迟再决定干预动作。需要注意的边界omx team默认是 tmux 运行时表面在 Codex App 或普通非 tmux 会话中应先从 shell 启动 OMX CLI 再使用团队命令src/cli/team.ts 的 help 说明小而短的 fanout 更适合原生 Codex subagentsomx team用于需要持久 tmux/状态/worktree 协调的场景。以上 CLI 参数与默认值均以当前仓库 src/cli/team.ts 的实现为准不同版本可能有细微差异。【免费下载链接】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），仅供参考