企业官网建设流程全解析

oh-my-codex v0.8.9 深度解析：团队 Worker 路由角色端到端落地与 Scale-Up 任务身份保真

【免费下载链接】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

导读

oh-my-codex v0.8.9 是一个聚焦团队（Team）模式正确性的热修复（hotfix）版本，核心解决了两个"启动路径上的身份断点"：一是规划阶段推断出的路由角色（routed role）此前只停留在计划层面，没有真正进入 worker 的启动指令与运行期元数据；二是动态扩容（scale-up）新增 worker 时，任务在 worker 引导前未经过规范化的团队状态持久化，导致任务 id、角色、inbox 元数据与初始团队启动时的运行时契约不一致。读完本文，你将掌握：路由角色如何从规划一路传递到 worker 的AGENTS.md与 identity 文件、动态扩容如何"先持久化任务再引导 worker"以保证任务身份保真，以及升级后需要执行的omx setup刷新操作与对应的测试回归覆盖。

版本背景与发布范围

本版本发布于 2026-03-08，包含v0.8.8..dev之间的 2 个非合并提交，贡献者为 @Yeachan-Heo，对应 PR #643。完整的提交记录如下：

11b2640 fix(team): persist scaled tasks before worker bootstrap 5591cf6 fix(team): persist routed roles into startup instructions (#643)

从提交信息可以看出，v0.8.9 的改动全部集中在src/team团队运行时模块，属于对上一版本团队启动与扩容路径的缺陷修复与契约收口。

核心修复一：路由角色在 Worker 启动路径上的端到端落地

问题本质：角色只在"规划"层被推断

团队模式下，leader 会对任务做角色路由（role routing），即根据任务描述的关键词与意图启发式地将任务分配给特定专业角色（如test-engineer、writer、debugger等）。v0.8.9 之前，路由结果主要停留在规划阶段，worker 真正启动时拿到的指令面与运行期身份信息并没有完整携带这一角色，导致 worker 实际执行行为与计划分配的角色脱节。

修复后的三条链路

v0.8.9 将路由角色落到了三个相互印证的位置：

1. 运行期团队配置与 worker 身份（identity）持久化：worker 的role字段被写入 live team config 以及 worker 目录下的identity.json，使角色成为运行期元数据而非一次性计划结果。这在 src/team/scaling.ts 中体现为ScaleUpWorkerInfo携带role: runtimeRole，并经writeWorkerIdentity写入<team_state_root>/team/<team>/workers/<worker>/identity.json。
2. 逐 worker 的启动AGENTS.md组合：启动时为每个 worker 组合一份专用指令文件，将解析出的角色 prompt 内容嵌入其中。核心实现在 src/team/worker-bootstrap.ts：
   • writeWorkerWorktreeRootAgentsFile：当 worker 运行在 git worktree 中时，在 worktree 根目录生成AGENTS.md，其中包含<!-- OMX:TEAM:ROLE:START -->与<!-- OMX:TEAM:ROLE:END -->包裹的角色块；
   • writeWorkerRoleInstructionsFile：非 worktree 场景下，将团队级指令（worker-agents.md）与角色 overlay 组合，写入.omx/state/team/<team>/workers/<worker>/AGENTS.md；
   • generateWorkerRootAgentsContent生成的指令中明确写出You are operating as the **${workerRole}** role for this team run. Apply the following role-local guidance.并跟随rolePromptContent。
3. inbox 指令面：generateInitialInbox会输出**Role:** <workerRole>，并在存在角色 prompt 时生成## Your Specialization小节，将行为准则直接呈现在 worker 的收件箱指令中。

角色 prompt 的加载与合成

路由角色要变成可执行指令，需要先加载对应的角色 prompt 文件。在 src/team/role-router.ts 中：

• loadRolePrompt(role, promptsDir)从 prompts 目录读取<role>.md文件，并要求角色名匹配^[a-z][a-z0-9-]*$安全模式；
• 查找顺序为 leader 项目内.codex/prompts优先，其次为仓库内置的codexPromptsDir()（即仓库根下的 prompts 目录，内含executor.md、test-engineer.md、writer.md等专业角色定义）；
• 随后经composeRoleInstructionsForRole（定义于 src/agents/native-config.ts）结合解析出的模型覆盖（model override）合成最终角色指令内容。

该加载与合成逻辑在初始团队启动路径 src/team/runtime.ts（约 L3717-L3786）与扩容路径 src/team/scaling.ts（约 L1151-L1169）中保持一致，这正是"路由角色端到端"的代码级保证。

角色默认推理分配与启动覆盖

v0.8.9 同时明确了角色与模型推理参数（reasoning effort）的关系：除非显式传入启动覆盖（launch override），否则按角色保持默认推理分配。在 src/team/scaling.ts 的buildScaleUpWorkerLaunchPlans中，runtimeRole的计算规则是：若某 worker 被分配的任务角色唯一，则采用该任务角色，否则回退到agentType；随后resolveAgentReasoningEffort(runtimeRole, codexHomeOverride)按角色解析首选推理强度，失败时再回退到agentType的默认值。也就是说，角色既驱动指令面，也驱动默认推理策略，且显式启动参数始终拥有更高优先级。

核心修复二：Scale-Up 任务引导先持久化，后引导 Worker

问题本质：合成式 inbox 元数据破坏任务身份

v0.8.9 之前，动态扩容新增 worker 时，新任务在 worker 引导前没有经过规范化团队状态（canonical team state）的写入，而是临时重建了一份仅存在于 inbox 中的任务元数据。后果是：扩容 worker 拿到的任务 id、角色、inbox 信息与初始团队启动时的运行时契约不一致，容易造成任务身份漂移与生命周期状态错乱。

修复后的顺序保证

修复后，scaleUp的执行顺序被调整为"先持久化任务，再引导 worker"：

1. 先冻结启动策略（launch policy）：buildScaleUpWorkerLaunchPlans在任务持久化之前构建并校验全部 worker 启动计划，计划成为唯一的启动策略来源；
2. 再通过规范化团队状态写入任务：对每个传入任务调用createStateTask（来自 src/team/team-ops.ts），以pending状态写入<team_state_root>/team/<team>/tasks/task-<id>.json，携带subject、description、owner、blocked_by、role等完整字段（见 src/team/scaling.ts L1033-L1053 的scale_up_task_materialization段）；
3. 用持久化后的任务清单生成 inbox 与身份：materializedTasks = await listTasks(...)读取规范化的任务列表，worker 的 inbox（generateInitialInbox）、identity（writeWorkerIdentity）与任务文件全部基于这份持久化状态生成，保证角色、owner、任务 id 三者一致。

由此，扩容 worker 与初始启动 worker 共享同一套任务读写契约：任务文件是tasks/task-<id>.json，API 与状态层使用裸task_id（如"1"）而非"task-1"前缀。

扩容启动计划的角色保真细节

ScaleUpWorkerLaunchPlan（src/team/scaling.ts L317-L324）记录了workerIndex、workerName、runtimeRole、workerLaunchArgs、workerCli与mixedTaskRoles。其中runtimeRole从已持久化任务的role字段聚合而来（taskAssignments.filter(t => t.owner === workerName).map(t => t.role)），这保证了扩容时角色判断建立在持久化任务之上，而不是建立在临时构造的合成数据上。若一个 worker 的任务角色不唯一，则回退到 agentType，并打印mixed task roles提示。

失败回滚的契约化保障

扩容路径还配套了完善的失败回滚机制rollbackScaleUp（同文件 L778 起）：包括通过commitTeamMembershipTaskTransaction/recoverTeamMembershipTaskTransaction做成员与任务的事务化持久化回滚、基于 pane 身份（pid、session、window、team owner tag）的授权清理、worktree 回滚，以及 cleanup debt 事件上报。这些机制确保"先持久化再引导"的每一步都处于可恢复的事务边界内。

升级注意事项：项目级安装需刷新配置

如果你使用的是项目级（project-scoped）OMX 安装，升级到 v0.8.9 后需要重新执行：

omx setup --force --scope project

以刷新受管的项目配置与 native-agent 路径。该命令在 src/cli/setup.ts 中的语义为：--force是对 catalog 已知项的显式破坏性选择（在备份后进行替换，setup 输出中也提示"omx setup ${scopeFlag} --merge-agents"可用于保留本地指引，--force则备份后整体替换），--scope project限定安装范围到项目根（scope === "project"分支管理项目根下的.codex配置、skills 收据与 native-agent 路径）。

注意：--force会替换已存在的托管配置，升级刷新前请确认项目中不存在需要保留的本地手写指引，或改用--merge-agents保留合并语义。

测试回归覆盖与验证

v0.8.9 的两个修复均有对应的自动化测试支撑，主要位于 src/team/tests/scaling.test.ts：

• 规范化任务状态与 inbox id 的回归测试（约 L910 起，persists scaled-up task roles in canonical task state and inbox ids）：断言扩容创建的任务经readTask读取后role === 'writer'；worker 的identity.json中role === 'writer'；inbox 中携带任务角色与正确 id。
• 非 worktree 扩容的角色指令组合测试（约 L1843、L1924 起）：断言生成的.omx/state/team/<team>/workers/worker-2/AGENTS.md包含You are operating as the **writer** role与<identity>You are Writer.</identity>，验证writeWorkerRoleInstructionsFile的输出。
• worktree 扩容的根级 AGENTS 引导测试（约 L1976 起，uses canonical root AGENTS bootstrap for scaled worktree workers）：断言 worktree 根目录.omx/team/<team>/worktrees/worker-2/AGENTS.md同样包含 writer 角色指令与身份内容。
• frontier 角色测试（约 L2083 起）：验证test-engineer角色的组合结果同样正确落入 worker 的 AGENTS 文件。

此外，src/team/tests/runtime.test.ts、src/team/tests/tmux-session.test.ts 与 src/team/tests/worker-bootstrap.test.ts 共同覆盖了 live worker 启动路径上的运行时、tmux 会话与 worker 引导三个阶段，与发布说明中"runtime、tmux-session、worker-bootstrap 三层覆盖"的描述一致。

小结

v0.8.9 虽然只有两个提交，却堵住了团队模式下两个关键的身份断裂点：

• 角色端到端：路由角色从规划、启动指令（AGENTS.md/inbox）到运行期元数据（identity.json/config）全程保真，并驱动默认推理分配；
• 扩容身份保真：动态扩容先经规范化团队状态持久化任务，再引导 worker，使扩容 worker 与初始 worker 遵循同一运行时契约，任务 id、角色、owner 不再漂移。

对团队模式重度用户而言，升级后务必执行omx setup --force --scope project刷新项目级安装，并可通过上述测试用例与 src/team 目录下的worker-bootstrap.ts、scaling.ts、runtime.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