OmX 发布就绪验证与团队状态根防护OMX_TEAM_* 环境变量跨工作树隔离实战指南【免费下载链接】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仓库中的发布就绪跟进文档docs/qa/release-readiness-follow-up.md展开系统讲解团队Team模式下的状态根team state root防护机制如何在多 worker、多 git worktree 场景下通过OMX_TEAM_STATE_ROOT等环境变量显式锚定状态目录以及为什么本地跑测试前必须清理OMX_TEAM_*环境变量否则会导致跨测试的状态污染。读完本文你将掌握一套可复制的发布就绪本地验证命令序列理解OMX_TEAM_STATE_ROOT/OMX_TEAM_WORKER/OMX_TEAM_LEADER_CWD三者的语义与解析优先级并学会在测试代码中安全地保存/恢复这些环境变量。一、背景为什么需要 Team State Root GuardOmX 的团队模式会把一个任务拆给多个 agent worker 并行执行每个 worker 运行在独立的 git worktree 中共享一份团队运行时状态。这份状态默认落在 leader 工作目录下的.omx/state其典型目录结构为.omx/state/ └── team/ └── {teamName}/ ├── config.json # 团队配置含 team_state_root / leader_cwd ├── manifest.v2.json # 团队清单schema_version: 2 ├── workers/ │ └── {workerName}/ │ ├── identity.json # 身份 worktree_path team_state_root │ ├── status.json # 心跳/状态 │ └── inbox.md # 任务收件箱 ├── tasks/ # task-id.json ├── mailbox/ # 各 worker 邮箱 └── dispatch/ # 调度请求从 src/team/state.ts 的实现可见所有状态文件路径都由resolveTeamStateRoot(cwd, env)派生teamDir/workerDir/teamConfigPath等函数均以其为根。问题随之而来worker 进程跑在各自的 worktree 里如果每个进程都猜一个本地的.omx/state就可能把状态写到错误的位置造成跨 worker 污染。这正是发布就绪跟进文档标题中 Team state root guard 的含义让状态根的解析显式、可验证、fail-closed而不是靠进程 cwd 猜测。二、本地验证命令发布就绪的第一步在仓库根目录按顺序执行以下命令即可完成对状态根防护相关改动的发布前验证npm run build # TypeScript 构建 node --test dist/team/__tests__/state.test.js node --test dist/mcp/__tests__/state-server-team-tools.test.js npm test各步骤含义如下npm run build把 TypeScript 源码编译到dist/。注意 package.json 中的build脚本会先删除旧dist再执行tsc并给dist/cli/omx.js添加可执行权限。后续node --test运行的必须是编译后的 JS因此构建是第一步。node --test dist/team/__tests__/state.test.js团队状态层核心测试约 3200 行。它覆盖任务创建/认领/状态迁移、成员事务日志membership transaction journal、原子写入writeAtomic写临时文件 → fsync → rename → fsync 父目录、邮箱/调度等其中也包含了OMX_TEAM_STATE_ROOT的保存/恢复模式见第四节。node --test dist/mcp/__tests__/state-server-team-tools.test.js验证 MCP state-server 对team_*工具的弃用行为。测试断言ListTools输出中不再暴露team_*工具且直接调用team_send_message会返回deprecated_cli_only错误并附带 CLI 提示omx team api send-message --json。也就是说团队状态操作已从 MCP 工具收敛到 CLI 互操作入口。npm test完整测试流水线从 package.json 可见其由buildverify:native-agentsverify:plugin-bundleverify:capabilities-lockverify:prompt-guidancetest:node及 catalog/prompt 清单一致性检查组成。注意若只改了状态根相关代码可以先跑前两条精准测试快速反馈再跑全量npm test兜底。三、OMX_TEAM_* 环境变量语义显式锚定状态根文档明确指出Team/path resolution now supports explicitOMX_TEAM_STATE_ROOTacross worker worktrees.团队状态根解析现在支持通过显式的OMX_TEAM_STATE_ROOT跨 worker worktree 锚定到同一个状态根。三个相关变量的语义如下环境变量语义典型来源OMX_TEAM_STATE_ROOT显式指定团队状态根最高优先级可为绝对路径也可为相对 leader cwd 的相对路径leader 启动团队时写入 worker 环境OMX_TEAM_WORKER公开 worker 身份令牌格式为{teamName}/{workerName}worker 启动时注入OMX_TEAM_LEADER_CWDleader 工作目录用于推导默认状态根leaderCwd/.omx/state以及校验leader_cwd元数据leader 启动团队时写入 worker 环境3.1 解析优先级resolveCanonicalTeamStateRoot见 src/team/state-root.ts的解析顺序为OMX_TEAM_STATE_ROOT存在且非空则直接采用相对路径会基于 leader cwd 解析见 state-root.test.ts 中../shared/state解析为/tmp/demo/shared/state的用例OMX_ROOT/OMX_STATE_ROOT作为 boxed workspace 根取其下.omx/state默认omxStateDir(leaderCwd)即leaderCwd/.omx/state。这一优先级同样被写入 worker 的运行时指令。在 src/team/worker-bootstrap.ts 生成的 worker AGENTS.md 协议中明确写着Resolve canonical team state root in this order:OMX_TEAM_STATE_ROOTenv → worker identityteam_state_root→ config/manifestteam_state_root→ local cwd fallback.3.2 worker 侧解析的 fail-closed 设计worker 进程内的解析比 leader 更严格且区分两条路径resolveWorkerTeamStateRootstate-root.ts用于 worker 的 PostToolUse / git 类 hookallowCwdFallback: true。只有当cwd/.omx/state中存在匹配的 worker identity且 worktree 路径匹配时才允许本地回退防止 hook 在 worker worktree 中猜一个本地状态根导致跨 worker 状态写错位置。resolveWorkerNotifyTeamStateRoot用于非 git 的 notify hook心跳、空闲、派发通知。此类路径禁用 cwd 回退只认显式的 env / leader 元数据根且所有成功结果都必须能通过 worker 身份校验——notify hook 不允许凭空发明cwd/.omx/state。两条路径最终都调用validateWorkerStateRoot会逐一核对identity.json、manifest.v2.json、config.json中的team_state_root、worktree_path、pane_id是否与候选根一致任何一项不一致都会返回*_state_root_mismatch之类的失败原因。3.3 外部状态根场景的回归保障src/scripts/tests/issue-3536-external-team-state-root.test.ts 记录了一个关键回归场景已验证的 worker 使用外部 OMX 状态根且没有单例 session.json 时不应被通用 Conductor 策略根守卫误拒绝。测试构建了leader/ external/.omx/state/的 fixture写入 identity/manifest/config 三方一致元数据后验证worker 对被委派的业务文件Write、Bash的写入不会被PROVENANCE_DENIED拦截但对config.json、manifest.v2.json、identity.json等受保护团队元数据的写入仍被拒绝。这说明状态根防护的目标是放开业务文件、守住元数据。四、环境变量污染问题与清理规范文档给出的是最容易被忽略的坑本地手动跑测试时上一轮运行残留的 worker 环境变量会泄漏到下一轮测试进程。由于很多状态函数直接读取process.env残留的OMX_TEAM_STATE_ROOT会让后续测试把所有状态写到别人的临时目录造成跨测试污染。4.1 手动运行后的清理命令每次手动跑完测试后执行unset OMX_TEAM_STATE_ROOT OMX_TEAM_WORKER OMX_TEAM_LEADER_CWD这条命令的三种变量分别对应上表语义清掉显式状态根锚点、清掉 worker 身份令牌、清掉 leader 工作目录线索确保下一轮测试进程从干净的环境出发。4.2 测试内保存/恢复模式推荐文档进一步要求If a test needs these vars, save/restore them inside the test (const prev process.env...finallycleanup).也就是说与其依赖外部 unset不如在测试内部自包含地管理环境。仓库中已有两处现成的实现范本src/team/tests/state.test.ts 在模块顶部保存ORIGINAL_OMX_TEAM_STATE_ROOTbeforeEach中delete process.env.OMX_TEAM_STATE_ROOTafterEach中按原值恢复或删除同时复位原子写入的测试替身rename/open/platform。src/scripts/tests/issue-3536-external-team-state-root.test.ts 的withWorkerEnv助手更加完整把TMUX、TMUX_PANE、OMX_TEAM_INTERNAL_WORKER、OMX_TEAM_WORKER、OMX_TEAM_STATE_ROOT、OMX_TEAM_LEADER_CWD六键先快照保存、全部删除再注入 fixture 值最后在finally中恢复——这正是const prev process.env...finallycleanup的标准实现。建议新测试照抄此模式而不是依赖全局环境。五、与 Release Readiness 系列的衔接这份跟进文档属于仓库 QA 文档族docs/qa 下的release-readiness-*.md系列的补充条目聚焦状态根守卫这一特定改动的验证与操作约束。它与系列中其他主题形成互补例如 docs/qa/release-readiness-0.19.0.md 记录过 Rust 侧unique_temp_dir()因共享 PID 并行线程在高负载下产生相同 nanos 值、导致两个测试线程解析出同一个OMX_TEAM_STATE_ROOT互相覆盖状态文件的 flaky 问题最终以AtomicU64单调计数器保证每条路径唯一。可见OMX_TEAM_STATE_ROOT既是运行期锚点也是测试隔离的敏感点任何改动都值得在发布前按本文命令复核。六、最佳实践小结发布前按顺序跑npm run build→ 精准的node --test dist/team/__tests__/state.test.js与dist/mcp/__tests__/state-server-team-tools.test.js→ 全量npm test。手动调试后必清理unset OMX_TEAM_STATE_ROOT OMX_TEAM_WORKER OMX_TEAM_LEADER_CWD防止残留环境变量泄漏进下一轮测试。测试内自包含需要这些变量时用const prev process.env.X快照 finally恢复参考 issue-3536 测试 的withWorkerEnv。理解 fail-closed 边界worker 侧状态根解析不信任 cwd 猜测notify hook 路径更是完全禁用 cwd 回退。修改解析逻辑时务必同时跑 state-root.test.ts 覆盖 env 优先级、相对路径、元数据校验、身份不匹配拒绝等场景。团队状态操作走 CLIteam_*MCP 工具已硬弃用一律通过omx team api ... --json互操作避免遗留调用路径绕过状态根校验。【免费下载链接】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），仅供参考