OmX Rust Runtime Thin-Adapter 发布门禁解析从 G1–G5 验证矩阵到兼容视图的权威性设计【免费下载链接】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项目中决定 Rust 运行时核心Runtime Core与 TS 薄适配器Thin Adapter切换能否放行的硬性发布门禁文档展开系统讲解Rust 引擎作为唯一语义真相所有者、JS/HUD/CLI/tmux 作为只读投递适配器这一架构在验证、契约、实现与测试四个层面的落地方式。读完本文你将掌握 OmX 的 G1–G5 门禁矩阵、兼容性工件Compatibility Artifacts的优先级规则、Rust 引擎持久化与兼容视图的写入机制以及 TS 侧 RuntimeBridge 如何以只读方式消费 Rust 权威状态。为什么需要一份发布门禁文档OmX 的核心团队运行时team/runtime正在经历一次大规模架构切换把权威状态authoritative state的语义所有权从 JavaScript 迁移到 Rust core。这个过程中老一代的 TS 读取器omx team status、omx doctor --team、HUD、notify/watcher并不会立刻被删除而是继续读取由 Rust 引擎输出的兼容视图文件。这就带来一个典型的迁移风险如果 Rust 侧已经接管了语义真相但某些读取器仍在按旧的 JS 默认值或旧的优先级逻辑工作就会出现双写发散语义泄漏进旧读取器优先级漂移等问题。为避免这类回归悄悄溜进发布版本仓库在 docs/qa/rust-runtime-thin-adapter-gate.md 中定义了一份硬性发布门禁hard gate任何缺失或失败的场景都会直接导致 CI/发布验证失败。这份门禁文档本身不是建议而是与 CI 测试绑定的强制契约。对应的门禁测试 rust-runtime-thin-adapter-gate.test.ts 会直接读取本文档与契约文档校验关键段落和 G1–G5 标识是否齐全。验证矩阵门禁五道硬性关卡 G1–G5门禁文档用一张验证矩阵表把必须被覆盖的场景映射到必须存在的测试证据ID场景所需证据测试/文档路径G1omx team status读取 manifest 授权的兼容视图src/compat/tests/rust-runtime-compat.test.tsG2Doctor 保持 manifest 优先的 tmux/session 优先级src/compat/tests/rust-runtime-compat.test.tsG3HUD 保持 session 作用域状态优先于根级回退src/compat/tests/rust-runtime-compat.test.tsG4薄适配器契约文档与读取器兼容车道保持一致docs/contracts/rust-runtime-thin-adapter-contract.md rust-runtime-thin-adapter-gate.test.tsG5Watcher send-keys 对等性由 Step 3 配套测试套件覆盖notify-hook-team-dispatch.test.ts、notify-hook-team-leader-nudge.test.ts、tmux-detector.test.ts这五道关卡分别对应三种旧读取器团队状态、doctor 诊断、HUD、一份架构契约文档和 watcher 投递通道。门禁测试会对每个 IDG1–G5做正则匹配并抽查关键语义字符串例如Semantic leakage survives into legacy readersWatcher send-keys parity breaks等确保门禁文档没有退化成空壳。Pre-mortem 场景映射从最可能崩在哪反推门槛门禁文档还给出了一张事前验尸pre-mortem映射表把团队最担心的四种失败模式与上面的门禁一一对应Pre-mortem 场景对应门禁语义泄漏存活在旧读取器中G1、G2、G3、G4读取器优先级在 config/manifest 或 session/root 作用域间漂移G1、G2、G3Watcher send-keys 对等性被破坏G5Mux 契约仍是 tmux 形状而非 Rust 规范形状G4这种先设想失败再反推验证项的编排方式保证了门禁不是按方便测试来设计而是按迁移最容易踩的坑来设计。其中语义泄漏与优先级漂移是同一类风险的两个侧面旧读取器必须继续工作但又绝不能把旧的默认值当成真相。契约核心谁是语义真相的唯一所有者门禁 G4 所依赖的契约文档 rust-runtime-thin-adapter-contract.md 首先划定了canonical ownership权威所有权边界Rust core 是以下语义的唯一所有者authority权威租约lifecycle/session state生命周期与会话状态dispatch/backlog派发与积压mailbox delivery state信箱投递状态replay/recovery重放与恢复readiness/diagnostics就绪性与诊断canonical mux operations规范 mux 操作相应地JS、HUD、CLI 和 tmux 只是薄的投递/观察适配器它们可以读取兼容性工件但绝不能自行定义或变更语义真相。契约还定义了五条薄适配器规则兼容读取器必须忽略未知字段并保留现有的 JSON 信封结构遗留 tmux 键入typing仅用于投递不建立语义真相当 Rust 作者兼容文件与遗留 JS 默认值冲突时Rust 作者文件胜出只有在桥接bridge被禁用或不可用的降级通道上JS 文件写入才允许作为回退当 Rust bridge 成功时它们不是权威的未知投递失败应作为适配器失败暴露而不是作为语义所有者变更。契约同时给出了消费者矩阵Team CLI 负责忠实渲染 Rust 兼容工件Doctor CLI 先报告 Rust 工件的就绪性再叠加适配器健康检查HUD 保持只读且感知作用域Notify/watchers 只负责投递事件永不成为运行的语义所有者。兼容性工件与优先级规则契约文档用一张表明确了三类遗留读取器各自读取的兼容文件与优先级保证读取器兼容文件兼容保证omx team status.omx/state/team/team/config.json、manifest.v2.json、tasks/*.json、approvals/*.json、workers/*config 与 manifest 同时存在时manifest 授权的团队配置为权威omx doctor --team团队目录下的config.json、manifest.v2.json、workers/*/status.json、workers/*/heartbeat.json、.omx/state/hud-state.jsonconfig 与 manifest 同时存在时manifest 授权的 tmux/session 身份为权威HUD readers.omx/state/session.json、.omx/state/sessions/session/team-state.json、.omx/state/team-state.json、.omx/state/ralph-state.json会话激活时session 作用域文件为权威根文件仅是兼容回退这三条优先级规则正是 G1/G2/G3 的验证对象。在 rust-runtime-compat.test.ts 中可以看到它们的端到端验证方式G1team status测试先在临时团队状态根目录初始化团队然后故意让config.json与manifest.v2.json冲突config 声明workspace_mode: single、旧 tmux 会话名manifest 声明worktree、新会话名再运行omx team status team --json并断言输出中的workspace_mode是 manifest 的worktreeG2doctor测试让 config 与 manifest 的tmux_session冲突并把一个假的tmux二进制注入 PATH只回显 manifest 中的会话名然后运行omx doctor --team断言输出包含team diagnostics: no issues与All team checks passed.且不出现resume_blockerG3HUD测试同时写入根级team-state.jsonactive: false、team_name: legacy-root、agent_count: 1与 session 级sessions/id/team-state.jsonactive: true、team_name: rust-session、agent_count: 3再调用 HUD 的readTeamState断言读到的是 session 级数据。优先级解析在源码中的体现是 src/mcp/state-paths.ts 的resolveStateScope与getStateFilePath显式 session id 当前 session id 根级回退HUD 侧 src/hud/state.ts 的readAuthoritativeModeState会先解析当前 session id再拼接mode-state.json的路径。Rust 引擎如何写出这些兼容视图契约文档明确给出了文件级证据RuntimeEngine位于 crates/omx-runtime-core/src/engine.rs通过persist()与write_compatibility_view()两个方法写出以下文件文件写入方法内容snapshot.jsonpersist()完整RuntimeSnapshotschema_version、authority、backlog、replay、readinessevents.jsonpersist()追加式事件日志RuntimeEvent数组#[serde(tag event)]格式authority.jsonwrite_compatibility_view()供 TS 读取器使用的AuthoritySnapshot分区backlog.jsonwrite_compatibility_view()BacklogSnapshot计数pending/notified/delivered/failedreadiness.jsonwrite_compatibility_view()ReadinessSnapshotready、reasonsreplay.jsonwrite_compatibility_view()ReplaySnapshot状态dispatch.jsonwrite_compatibility_view()完整DispatchLogDispatchRecord数组供团队状态读取器使用mailbox.jsonwrite_compatibility_view()完整MailboxLogMailboxRecord数组供团队/消息读取器使用从源码看两个方法的职责划分非常清晰engine.rspersist()约第 291 行会先创建engine.lock并加排他锁随后写入snapshot.json、events.json、mailbox.json、dispatch.json并额外落盘dispatch-seen.json派发去重账本schema_version2、ledger_epoch1保证崩溃后已接受的 request_id 永不重用write_compatibility_view()约第 322 行则基于snapshot()的结果把各分区拆成独立小文件方便 TS 读取器只读自己关心的部分。所有文件都写入配置的state_dir原子替换 目录 fsync见persist_dispatch_seen_ledger与sync_directory。契约明确要求TS 读取器必须把这些文件视为只读Rust 引擎是唯一写入者。CLI 二进制 crates/omx-runtime/src/main.rs 提供了与引擎配套的子命令schema [--json]契约摘要、snapshot [--json] [--state-dirDIR]、exec json [--state-dirDIR] [--compact]、init state-dir、mux-contract以及fs-rename-no-replace、process-identity。其中exec每次执行都会先加runtime-mutation.lock排他锁然后load→process→ 可选compact→persist→write_compatibility_view即一次命令完成权威持久化 兼容视图刷新两件事。TS 侧薄适配器RuntimeBridge 的只读消费门禁所依赖的另一半实现是 src/runtime/bridge.ts 中的RuntimeBridge它是 TS 侧对omx-runtime二进制的薄封装。它的三条设计原则在文件头注释中写明所有语义状态变更都经由execCommand()路由到 Rust 二进制所有状态查询都读取 Rust 作者兼容 JSON 文件设置OMX_RUNTIME_BRIDGE0可禁用桥接回退到 TS 直写。桥接的读取接口高度模块化readAuthority()、readReadiness()、readBacklog()、readDispatchRecords()、readMailboxRecords()分别对应authority.json、readiness.json、backlog.json、dispatch.json、mailbox.json。其中readCompatFileT()是统一入口它对文件正在被原子替换读到空内容临时文件尚未落定等跨边界场景做了容错——返回null让上层本 tick 回退到 JS 推断状态而不是抛异常打断整个查询路径。对于要求更严格的读取场景如 dispatch 循环readDispatchRecordsStrict()会失败关闭fail closed状态目录不可用、文件缺失、形状非法、记录不满足DispatchRecord严格校验request_id/target/status/时间戳/metadata字段类型逐一检查时直接抛出RuntimeBridgeError。execCommand()对 Rust 返回非 JSON 输出同样抛出带上下文的RuntimeBridgeError让 dispatch 调用方可以用instanceof精确处理解析失败而不是让SyntaxError冒泡到无关层次。桥接的启动还包含一次契约自检validateSchemaOnce()会调用omx-runtime schema --json校验预期命令集合acquire-authority、renew-authority、queue-dispatch、mark-notified、mark-delivered、mark-failed、remove-dispatch-records、request-replay、capture-snapshot是否齐全缺命令即判定TS 桥接类型与 Rust 二进制不同步。二进制定位顺序见resolveRuntimeBinaryPath()OMX_RUNTIME_BINARY环境变量覆盖 → 已验证的 native 缓存带.sha256伴生校验文件→ workspacetarget/debug/omx-runtime→target/release/omx-runtime→ 回退到 PATH 上的omx-runtime。在 rust-runtime-compat.test.ts 的第四个测试约第 226 行中可以看到桥接兼容视图胜过陈旧遗留文件的端到端验证测试先在遗留dispatch/requests.json与mailbox/worker-2.json中预置仅存在于旧通道的legacy-only记录再通过enqueueDispatchRequest/sendDirectMessage走真实桥接写入最后断言listDispatchRequests/listMailboxMessages读到的是桥接记录旧遗留记录不再出现——这正是 thin-adapter 规则 3Rust 文件胜出的直接证据。Watcher send-keys 对等性G5门禁 G5 关注的是 notify/watcher 通道的投递对等性当 Rust bridge 接管权威状态后watcher 仍然需要通过 tmuxsend-keys向目标 pane 投递键击这条投递路径不能因迁移而改变形状。证据落在三个测试套件notify-hook-team-dispatch.test.ts断言通知 hook 产生的send-keys -t pane目标 pane 正确如send-keys -t %99且不会错误命中开发会话或替换 panenotify-hook-team-leader-nudge.test.ts覆盖 leader nudge 场景下的投递目标tmux-detector.test.ts覆盖 tmux 环境检测。与 G4 呼应的是投递层允许tmux 形状但规范 mux 操作canonical mux operations的所有权在 Rust。契约与 docs/interop-team-mutation-contract.md 都强调直接 tmux 键入只是操作层面的回退operational fallback绝不构成变更契约——broker 必须通过 JSON 信封 状态读取来确认变更是否成功。门禁之外非门禁的后续 seam audit门禁文档最后明确指出当前 thin-adapter 切换仍存在少数已知的接缝缺口seam gaps它们被有意地排除在发布门禁之外记录在 docs/qa/runtime-team-seam-audit-2026-04-01.md基线提交51579ceissue #1108 之后的快照。这份 audit 记录了四个接缝点其中两个已解决、两个待跟进Rust runtime ↔ TS team state 双写已由 issue #1108 解决。src/team/state/dispatch.ts与src/team/state/mailbox.ts中的 Rust 桥接/兼容文件现在是 dispatch 与 mailbox 的权威面遗留 TS 文件仅在桥接禁用/不可用时作为降级回退团队元数据解析横跨多个文件未解决src/team/api-interop.ts约第 423–438 行先查 worker identity 元数据再查manifest.v2.json最后查config.json工作目录/状态根解析可能依赖回退顺序而非单一权威源运行时所有权契约 vs 切换现实dispatch/mailbox 所有权已与契约一致剩余工作是元数据/回退层的简化兼容读取器仍携带回退优先级逻辑未解决rust-runtime-compat.test.ts约第 47–170 行与 src/hud/state.ts约第 107–123 行有意保留旧优先级以保证迁移安全但这也让读路径比目标架构更复杂未来格式漂移可能藏在回退行为里。audit 给出的后续顺序是先把团队状态根/工作目录解析收敛到单一规范元数据源再在写路径单所有者之后削减兼容回退层。门禁文档之所以把这些排除在外正是因为它们属于演进方向而非切换正确性——切换本身权威性、优先级、投递对等已由 G1–G5 牢牢锁住。如何在本仓库中验证门禁门禁测试与契约测试均使用 Node 内置node:test编写可从仓库根目录直接运行# 校验门禁文档与契约文档的关键语义G4 node --test src/verification/__tests__/rust-runtime-thin-adapter-gate.test.ts # 端到端验证 G1/G2/G3 及桥接兼容视图优先级 node --test src/compat/__tests__/rust-runtime-compat.test.ts # G5 配套套件 node --test src/hooks/__tests__/notify-hook-team-dispatch.test.ts node --test src/hooks/__tests__/notify-hook-team-leader-nudge.test.ts node --test src/notifications/__tests__/tmux-detector.test.tsRust 侧的引擎单元测试persist/load往返、兼容视图分区文件写出、dispatch 去重账本、mailbox body 回填等位于 crates/omx-runtime-core/src/engine.rs 的#[cfg(test)] mod tests中cargo test -p omx-runtime-core注意rust-runtime-compat.test.ts会真正 spawndist/cli/omx.js需要先完成 TS 构建同时它会通过OMX_TEAM_STATE_ROOT、OMX_RUNTIME_BINARY、PATH等环境变量注入隔离的临时状态目录与假tmux/假 runtime 二进制因此验证时不依赖真实环境。若在部分受限文件系统权限下运行出现EPERM/EACCES测试会按shouldSkipForSpawnPermissions跳过 spawn 类断言。小结门禁文档的工程价值rust-runtime-thin-adapter-gate.md看似只是一张核对清单但它实际上定义了一套可执行的架构治理机制G1–G5 验证矩阵把Rust 权威、TS 只读的架构原则翻译成了可断言的测试证据Pre-mortem 映射确保门禁覆盖的是真实迁移风险而非随机场景契约文档划清了权威所有权与五条薄适配器规则任何一边越界都会被门禁测试或运行时校验抓住非门禁 audit则把正确性与演进分开治理既不放行已知回归也不阻塞架构优化。对任何正在做语言/运行时边界重构 老读取器兼容的团队来说这套契约文档 门禁矩阵 端到端兼容测试 非门禁跟进审计的组合是一个可以直接借鉴的迁移治理模板。【免费下载链接】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），仅供参考