布門禁解析：從 G1–G5 驗(yàn)證矩陣到兼容視圖的權(quán)威性設(shè)計(jì))
OmX Rust Runtime Thin-Adapter 發(fā)布門禁解析從 G1–G5 驗(yàn)證矩陣到兼容視圖的權(quán)威性設(shè)計(jì)【免費(fèi)下載鏈接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex導(dǎo)讀本文圍繞 OmXoh-my-codex項(xiàng)目中決定 Rust 運(yùn)行時(shí)核心Runtime Core與 TS 薄適配器Thin Adapter切換能否放行的硬性發(fā)布門禁文檔展開系統(tǒng)講解Rust 引擎作為唯一語義真相所有者、JS/HUD/CLI/tmux 作為只讀投遞適配器這一架構(gòu)在驗(yàn)證、契約、實(shí)現(xiàn)與測(cè)試四個(gè)層面的落地方式。讀完本文你將掌握 OmX 的 G1–G5 門禁矩陣、兼容性工件Compatibility Artifacts的優(yōu)先級(jí)規(guī)則、Rust 引擎持久化與兼容視圖的寫入機(jī)制以及 TS 側(cè) RuntimeBridge 如何以只讀方式消費(fèi) Rust 權(quán)威狀態(tài)。為什么需要一份發(fā)布門禁文檔OmX 的核心團(tuán)隊(duì)運(yùn)行時(shí)team/runtime正在經(jīng)歷一次大規(guī)模架構(gòu)切換把權(quán)威狀態(tài)authoritative state的語義所有權(quán)從 JavaScript 遷移到 Rust core。這個(gè)過程中老一代的 TS 讀取器omx team status、omx doctor --team、HUD、notify/watcher并不會(huì)立刻被刪除而是繼續(xù)讀取由 Rust 引擎輸出的兼容視圖文件。這就帶來一個(gè)典型的遷移風(fēng)險(xiǎn)如果 Rust 側(cè)已經(jīng)接管了語義真相但某些讀取器仍在按舊的 JS 默認(rèn)值或舊的優(yōu)先級(jí)邏輯工作就會(huì)出現(xiàn)雙寫發(fā)散語義泄漏進(jìn)舊讀取器優(yōu)先級(jí)漂移等問題。為避免這類回歸悄悄溜進(jìn)發(fā)布版本倉庫在 docs/qa/rust-runtime-thin-adapter-gate.md 中定義了一份硬性發(fā)布門禁hard gate任何缺失或失敗的場(chǎng)景都會(huì)直接導(dǎo)致 CI/發(fā)布驗(yàn)證失敗。這份門禁文檔本身不是建議而是與 CI 測(cè)試綁定的強(qiáng)制契約。對(duì)應(yīng)的門禁測(cè)試 rust-runtime-thin-adapter-gate.test.ts 會(huì)直接讀取本文檔與契約文檔校驗(yàn)關(guān)鍵段落和 G1–G5 標(biāo)識(shí)是否齊全。驗(yàn)證矩陣門禁五道硬性關(guān)卡 G1–G5門禁文檔用一張驗(yàn)證矩陣表把必須被覆蓋的場(chǎng)景映射到必須存在的測(cè)試證據(jù)ID場(chǎng)景所需證據(jù)測(cè)試/文檔路徑G1omx team status讀取 manifest 授權(quán)的兼容視圖src/compat/tests/rust-runtime-compat.test.tsG2Doctor 保持 manifest 優(yōu)先的 tmux/session 優(yōu)先級(jí)src/compat/tests/rust-runtime-compat.test.tsG3HUD 保持 session 作用域狀態(tài)優(yōu)先于根級(jí)回退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 對(duì)等性由 Step 3 配套測(cè)試套件覆蓋notify-hook-team-dispatch.test.ts、notify-hook-team-leader-nudge.test.ts、tmux-detector.test.ts這五道關(guān)卡分別對(duì)應(yīng)三種舊讀取器團(tuán)隊(duì)狀態(tài)、doctor 診斷、HUD、一份架構(gòu)契約文檔和 watcher 投遞通道。門禁測(cè)試會(huì)對(duì)每個(gè) IDG1–G5做正則匹配并抽查關(guān)鍵語義字符串例如Semantic leakage survives into legacy readersWatcher send-keys parity breaks等確保門禁文檔沒有退化成空殼。Pre-mortem 場(chǎng)景映射從最可能崩在哪反推門檻門禁文檔還給出了一張事前驗(yàn)尸pre-mortem映射表把團(tuán)隊(duì)最擔(dān)心的四種失敗模式與上面的門禁一一對(duì)應(yīng)Pre-mortem 場(chǎng)景對(duì)應(yīng)門禁語義泄漏存活在舊讀取器中G1、G2、G3、G4讀取器優(yōu)先級(jí)在 config/manifest 或 session/root 作用域間漂移G1、G2、G3Watcher send-keys 對(duì)等性被破壞G5Mux 契約仍是 tmux 形狀而非 Rust 規(guī)范形狀G4這種先設(shè)想失敗再反推驗(yàn)證項(xiàng)的編排方式保證了門禁不是按方便測(cè)試來設(shè)計(jì)而是按遷移最容易踩的坑來設(shè)計(jì)。其中語義泄漏與優(yōu)先級(jí)漂移是同一類風(fēng)險(xiǎn)的兩個(gè)側(cè)面舊讀取器必須繼續(xù)工作但又絕不能把舊的默認(rèn)值當(dāng)成真相。契約核心誰是語義真相的唯一所有者門禁 G4 所依賴的契約文檔 rust-runtime-thin-adapter-contract.md 首先劃定了canonical ownership權(quán)威所有權(quán)邊界Rust core 是以下語義的唯一所有者authority權(quán)威租約lifecycle/session state生命周期與會(huì)話狀態(tài)dispatch/backlog派發(fā)與積壓mailbox delivery state信箱投遞狀態(tài)replay/recovery重放與恢復(fù)readiness/diagnostics就緒性與診斷canonical mux operations規(guī)范 mux 操作相應(yīng)地JS、HUD、CLI 和 tmux 只是薄的投遞/觀察適配器它們可以讀取兼容性工件但絕不能自行定義或變更語義真相。契約還定義了五條薄適配器規(guī)則兼容讀取器必須忽略未知字段并保留現(xiàn)有的 JSON 信封結(jié)構(gòu)遺留 tmux 鍵入typing僅用于投遞不建立語義真相當(dāng) Rust 作者兼容文件與遺留 JS 默認(rèn)值沖突時(shí)Rust 作者文件勝出只有在橋接bridge被禁用或不可用的降級(jí)通道上JS 文件寫入才允許作為回退當(dāng) Rust bridge 成功時(shí)它們不是權(quán)威的未知投遞失敗應(yīng)作為適配器失敗暴露而不是作為語義所有者變更。契約同時(shí)給出了消費(fèi)者矩陣Team CLI 負(fù)責(zé)忠實(shí)渲染 Rust 兼容工件Doctor CLI 先報(bào)告 Rust 工件的就緒性再疊加適配器健康檢查HUD 保持只讀且感知作用域Notify/watchers 只負(fù)責(zé)投遞事件永不成為運(yùn)行的語義所有者。兼容性工件與優(yōu)先級(jí)規(guī)則契約文檔用一張表明確了三類遺留讀取器各自讀取的兼容文件與優(yōu)先級(jí)保證讀取器兼容文件兼容保證omx team status.omx/state/team/team/config.json、manifest.v2.json、tasks/*.json、approvals/*.json、workers/*config 與 manifest 同時(shí)存在時(shí)manifest 授權(quán)的團(tuán)隊(duì)配置為權(quán)威omx doctor --team團(tuán)隊(duì)目錄下的config.json、manifest.v2.json、workers/*/status.json、workers/*/heartbeat.json、.omx/state/hud-state.jsonconfig 與 manifest 同時(shí)存在時(shí)manifest 授權(quán)的 tmux/session 身份為權(quán)威HUD readers.omx/state/session.json、.omx/state/sessions/session/team-state.json、.omx/state/team-state.json、.omx/state/ralph-state.json會(huì)話激活時(shí)session 作用域文件為權(quán)威根文件僅是兼容回退這三條優(yōu)先級(jí)規(guī)則正是 G1/G2/G3 的驗(yàn)證對(duì)象。在 rust-runtime-compat.test.ts 中可以看到它們的端到端驗(yàn)證方式G1team status測(cè)試先在臨時(shí)團(tuán)隊(duì)狀態(tài)根目錄初始化團(tuán)隊(duì)然后故意讓config.json與manifest.v2.json沖突config 聲明workspace_mode: single、舊 tmux 會(huì)話名manifest 聲明worktree、新會(huì)話名再運(yùn)行omx team status team --json并斷言輸出中的workspace_mode是 manifest 的worktreeG2doctor測(cè)試讓 config 與 manifest 的tmux_session沖突并把一個(gè)假的tmux二進(jìn)制注入 PATH只回顯 manifest 中的會(huì)話名然后運(yùn)行omx doctor --team斷言輸出包含team diagnostics: no issues與All team checks passed.且不出現(xiàn)resume_blockerG3HUD測(cè)試同時(shí)寫入根級(jí)team-state.jsonactive: false、team_name: legacy-root、agent_count: 1與 session 級(jí)sessions/id/team-state.jsonactive: true、team_name: rust-session、agent_count: 3再調(diào)用 HUD 的readTeamState斷言讀到的是 session 級(jí)數(shù)據(jù)。優(yōu)先級(jí)解析在源碼中的體現(xiàn)是 src/mcp/state-paths.ts 的resolveStateScope與getStateFilePath顯式 session id 當(dāng)前 session id 根級(jí)回退HUD 側(cè) src/hud/state.ts 的readAuthoritativeModeState會(huì)先解析當(dāng)前 session id再拼接mode-state.json的路徑。Rust 引擎如何寫出這些兼容視圖契約文檔明確給出了文件級(jí)證據(jù)RuntimeEngine位于 crates/omx-runtime-core/src/engine.rs通過persist()與write_compatibility_view()兩個(gè)方法寫出以下文件文件寫入方法內(nèi)容snapshot.jsonpersist()完整RuntimeSnapshotschema_version、authority、backlog、replay、readinessevents.jsonpersist()追加式事件日志RuntimeEvent數(shù)組#[serde(tag event)]格式authority.jsonwrite_compatibility_view()供 TS 讀取器使用的AuthoritySnapshot分區(qū)backlog.jsonwrite_compatibility_view()BacklogSnapshot計(jì)數(shù)pending/notified/delivered/failedreadiness.jsonwrite_compatibility_view()ReadinessSnapshotready、reasonsreplay.jsonwrite_compatibility_view()ReplaySnapshot狀態(tài)dispatch.jsonwrite_compatibility_view()完整DispatchLogDispatchRecord數(shù)組供團(tuán)隊(duì)狀態(tài)讀取器使用mailbox.jsonwrite_compatibility_view()完整MailboxLogMailboxRecord數(shù)組供團(tuán)隊(duì)/消息讀取器使用從源碼看兩個(gè)方法的職責(zé)劃分非常清晰engine.rspersist()約第 291 行會(huì)先創(chuàng)建engine.lock并加排他鎖隨后寫入snapshot.json、events.json、mailbox.json、dispatch.json并額外落盤dispatch-seen.json派發(fā)去重賬本schema_version2、ledger_epoch1保證崩潰后已接受的 request_id 永不重用write_compatibility_view()約第 322 行則基于snapshot()的結(jié)果把各分區(qū)拆成獨(dú)立小文件方便 TS 讀取器只讀自己關(guān)心的部分。所有文件都寫入配置的state_dir原子替換 目錄 fsync見persist_dispatch_seen_ledger與sync_directory。契約明確要求TS 讀取器必須把這些文件視為只讀Rust 引擎是唯一寫入者。CLI 二進(jìn)制 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每次執(zhí)行都會(huì)先加runtime-mutation.lock排他鎖然后load→process→ 可選compact→persist→write_compatibility_view即一次命令完成權(quán)威持久化 兼容視圖刷新兩件事。TS 側(cè)薄適配器RuntimeBridge 的只讀消費(fèi)門禁所依賴的另一半實(shí)現(xiàn)是 src/runtime/bridge.ts 中的RuntimeBridge它是 TS 側(cè)對(duì)omx-runtime二進(jìn)制的薄封裝。它的三條設(shè)計(jì)原則在文件頭注釋中寫明所有語義狀態(tài)變更都經(jīng)由execCommand()路由到 Rust 二進(jìn)制所有狀態(tài)查詢都讀取 Rust 作者兼容 JSON 文件設(shè)置OMX_RUNTIME_BRIDGE0可禁用橋接回退到 TS 直寫。橋接的讀取接口高度模塊化readAuthority()、readReadiness()、readBacklog()、readDispatchRecords()、readMailboxRecords()分別對(duì)應(yīng)authority.json、readiness.json、backlog.json、dispatch.json、mailbox.json。其中readCompatFileT()是統(tǒng)一入口它對(duì)文件正在被原子替換讀到空內(nèi)容臨時(shí)文件尚未落定等跨邊界場(chǎng)景做了容錯(cuò)——返回null讓上層本 tick 回退到 JS 推斷狀態(tài)而不是拋異常打斷整個(gè)查詢路徑。對(duì)于要求更嚴(yán)格的讀取場(chǎng)景如 dispatch 循環(huán)readDispatchRecordsStrict()會(huì)失敗關(guān)閉fail closed狀態(tài)目錄不可用、文件缺失、形狀非法、記錄不滿足DispatchRecord嚴(yán)格校驗(yàn)request_id/target/status/時(shí)間戳/metadata字段類型逐一檢查時(shí)直接拋出RuntimeBridgeError。execCommand()對(duì) Rust 返回非 JSON 輸出同樣拋出帶上下文的RuntimeBridgeError讓 dispatch 調(diào)用方可以用instanceof精確處理解析失敗而不是讓SyntaxError冒泡到無關(guān)層次。橋接的啟動(dòng)還包含一次契約自檢validateSchemaOnce()會(huì)調(diào)用omx-runtime schema --json校驗(yàn)預(yù)期命令集合acquire-authority、renew-authority、queue-dispatch、mark-notified、mark-delivered、mark-failed、remove-dispatch-records、request-replay、capture-snapshot是否齊全缺命令即判定TS 橋接類型與 Rust 二進(jìn)制不同步。二進(jìn)制定位順序見resolveRuntimeBinaryPath()OMX_RUNTIME_BINARY環(huán)境變量覆蓋 → 已驗(yàn)證的 native 緩存帶.sha256伴生校驗(yàn)文件→ workspacetarget/debug/omx-runtime→target/release/omx-runtime→ 回退到 PATH 上的omx-runtime。在 rust-runtime-compat.test.ts 的第四個(gè)測(cè)試約第 226 行中可以看到橋接兼容視圖勝過陳舊遺留文件的端到端驗(yàn)證測(cè)試先在遺留dispatch/requests.json與mailbox/worker-2.json中預(yù)置僅存在于舊通道的legacy-only記錄再通過enqueueDispatchRequest/sendDirectMessage走真實(shí)橋接寫入最后斷言listDispatchRequests/listMailboxMessages讀到的是橋接記錄舊遺留記錄不再出現(xiàn)——這正是 thin-adapter 規(guī)則 3Rust 文件勝出的直接證據(jù)。Watcher send-keys 對(duì)等性G5門禁 G5 關(guān)注的是 notify/watcher 通道的投遞對(duì)等性當(dāng) Rust bridge 接管權(quán)威狀態(tài)后watcher 仍然需要通過 tmuxsend-keys向目標(biāo) pane 投遞鍵擊這條投遞路徑不能因遷移而改變形狀。證據(jù)落在三個(gè)測(cè)試套件notify-hook-team-dispatch.test.ts斷言通知 hook 產(chǎn)生的send-keys -t pane目標(biāo) pane 正確如send-keys -t %99且不會(huì)錯(cuò)誤命中開發(fā)會(huì)話或替換 panenotify-hook-team-leader-nudge.test.ts覆蓋 leader nudge 場(chǎng)景下的投遞目標(biāo)tmux-detector.test.ts覆蓋 tmux 環(huán)境檢測(cè)。與 G4 呼應(yīng)的是投遞層允許tmux 形狀但規(guī)范 mux 操作canonical mux operations的所有權(quán)在 Rust。契約與 docs/interop-team-mutation-contract.md 都強(qiáng)調(diào)直接 tmux 鍵入只是操作層面的回退operational fallback絕不構(gòu)成變更契約——broker 必須通過 JSON 信封 狀態(tài)讀取來確認(rèn)變更是否成功。門禁之外非門禁的后續(xù) seam audit門禁文檔最后明確指出當(dāng)前 thin-adapter 切換仍存在少數(shù)已知的接縫缺口seam gaps它們被有意地排除在發(fā)布門禁之外記錄在 docs/qa/runtime-team-seam-audit-2026-04-01.md基線提交51579ceissue #1108 之后的快照。這份 audit 記錄了四個(gè)接縫點(diǎn)其中兩個(gè)已解決、兩個(gè)待跟進(jìn)Rust runtime ? TS team state 雙寫已由 issue #1108 解決。src/team/state/dispatch.ts與src/team/state/mailbox.ts中的 Rust 橋接/兼容文件現(xiàn)在是 dispatch 與 mailbox 的權(quán)威面遺留 TS 文件僅在橋接禁用/不可用時(shí)作為降級(jí)回退團(tuán)隊(duì)元數(shù)據(jù)解析橫跨多個(gè)文件未解決src/team/api-interop.ts約第 423–438 行先查 worker identity 元數(shù)據(jù)再查manifest.v2.json最后查config.json工作目錄/狀態(tài)根解析可能依賴回退順序而非單一權(quán)威源運(yùn)行時(shí)所有權(quán)契約 vs 切換現(xiàn)實(shí)dispatch/mailbox 所有權(quán)已與契約一致剩余工作是元數(shù)據(jù)/回退層的簡化兼容讀取器仍攜帶回退優(yōu)先級(jí)邏輯未解決rust-runtime-compat.test.ts約第 47–170 行與 src/hud/state.ts約第 107–123 行有意保留舊優(yōu)先級(jí)以保證遷移安全但這也讓讀路徑比目標(biāo)架構(gòu)更復(fù)雜未來格式漂移可能藏在回退行為里。audit 給出的后續(xù)順序是先把團(tuán)隊(duì)狀態(tài)根/工作目錄解析收斂到單一規(guī)范元數(shù)據(jù)源再在寫路徑單所有者之后削減兼容回退層。門禁文檔之所以把這些排除在外正是因?yàn)樗鼈儗儆谘葸M(jìn)方向而非切換正確性——切換本身權(quán)威性、優(yōu)先級(jí)、投遞對(duì)等已由 G1–G5 牢牢鎖住。如何在本倉庫中驗(yàn)證門禁門禁測(cè)試與契約測(cè)試均使用 Node 內(nèi)置node:test編寫可從倉庫根目錄直接運(yùn)行# 校驗(yàn)門禁文檔與契約文檔的關(guān)鍵語義G4 node --test src/verification/__tests__/rust-runtime-thin-adapter-gate.test.ts # 端到端驗(yàn)證 G1/G2/G3 及橋接兼容視圖優(yōu)先級(jí) 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 側(cè)的引擎單元測(cè)試persist/load往返、兼容視圖分區(qū)文件寫出、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會(huì)真正 spawndist/cli/omx.js需要先完成 TS 構(gòu)建同時(shí)它會(huì)通過OMX_TEAM_STATE_ROOT、OMX_RUNTIME_BINARY、PATH等環(huán)境變量注入隔離的臨時(shí)狀態(tài)目錄與假tmux/假 runtime 二進(jìn)制因此驗(yàn)證時(shí)不依賴真實(shí)環(huán)境。若在部分受限文件系統(tǒng)權(quán)限下運(yùn)行出現(xiàn)EPERM/EACCES測(cè)試會(huì)按shouldSkipForSpawnPermissions跳過 spawn 類斷言。小結(jié)門禁文檔的工程價(jià)值rust-runtime-thin-adapter-gate.md看似只是一張核對(duì)清單但它實(shí)際上定義了一套可執(zhí)行的架構(gòu)治理機(jī)制G1–G5 驗(yàn)證矩陣把Rust 權(quán)威、TS 只讀的架構(gòu)原則翻譯成了可斷言的測(cè)試證據(jù)Pre-mortem 映射確保門禁覆蓋的是真實(shí)遷移風(fēng)險(xiǎn)而非隨機(jī)場(chǎng)景契約文檔劃清了權(quán)威所有權(quán)與五條薄適配器規(guī)則任何一邊越界都會(huì)被門禁測(cè)試或運(yùn)行時(shí)校驗(yàn)抓住非門禁 audit則把正確性與演進(jìn)分開治理既不放行已知回歸也不阻塞架構(gòu)優(yōu)化。對(duì)任何正在做語言/運(yùn)行時(shí)邊界重構(gòu) 老讀取器兼容的團(tuán)隊(duì)來說這套契約文檔 門禁矩陣 端到端兼容測(cè)試 非門禁跟進(jìn)審計(jì)的組合是一個(gè)可以直接借鑒的遷移治理模板?！久赓M(fèi)下載鏈接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 OmX Rust Runtime Thin-Adapter 發(fā)布門禁解析：從 G1–G5 驗(yàn)證矩陣到兼容視圖的權(quán)威性設(shè)計(jì)
OmX Rust Runtime Thin-Adapter 發(fā)布門禁解析從 G1–G5 驗(yàn)證矩陣到兼容視圖的權(quán)威性設(shè)計(jì)【免費(fèi)下載鏈接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex導(dǎo)讀本文圍繞 OmXoh-my-codex項(xiàng)目中決定 Rust 運(yùn)行時(shí)核心Runtime Core與 TS 薄適配器Thin Adapter切換能否放行的硬性發(fā)布門禁文檔展開系統(tǒng)講解Rust 引擎作為唯一語義真相所有者、JS/HUD/CLI/tmux 作為只讀投遞適配器這一架構(gòu)在驗(yàn)證、契約、實(shí)現(xiàn)與測(cè)試四個(gè)層面的落地方式。讀完本文你將掌握 OmX 的 G1–G5 門禁矩陣、兼容性工件Compatibility Artifacts的優(yōu)先級(jí)規(guī)則、Rust 引擎持久化與兼容視圖的寫入機(jī)制以及 TS 側(cè) RuntimeBridge 如何以只讀方式消費(fèi) Rust 權(quán)威狀態(tài)。為什么需要一份發(fā)布門禁文檔OmX 的核心團(tuán)隊(duì)運(yùn)行時(shí)team/runtime正在經(jīng)歷一次大規(guī)模架構(gòu)切換把權(quán)威狀態(tài)authoritative state的語義所有權(quán)從 JavaScript 遷移到 Rust core。這個(gè)過程中老一代的 TS 讀取器omx team status、omx doctor --team、HUD、notify/watcher并不會(huì)立刻被刪除而是繼續(xù)讀取由 Rust 引擎輸出的兼容視圖文件。這就帶來一個(gè)典型的遷移風(fēng)險(xiǎn)如果 Rust 側(cè)已經(jīng)接管了語義真相但某些讀取器仍在按舊的 JS 默認(rèn)值或舊的優(yōu)先級(jí)邏輯工作就會(huì)出現(xiàn)雙寫發(fā)散語義泄漏進(jìn)舊讀取器優(yōu)先級(jí)漂移等問題。為避免這類回歸悄悄溜進(jìn)發(fā)布版本倉庫在 docs/qa/rust-runtime-thin-adapter-gate.md 中定義了一份硬性發(fā)布門禁hard gate任何缺失或失敗的場(chǎng)景都會(huì)直接導(dǎo)致 CI/發(fā)布驗(yàn)證失敗。這份門禁文檔本身不是建議而是與 CI 測(cè)試綁定的強(qiáng)制契約。對(duì)應(yīng)的門禁測(cè)試 rust-runtime-thin-adapter-gate.test.ts 會(huì)直接讀取本文檔與契約文檔校驗(yàn)關(guān)鍵段落和 G1–G5 標(biāo)識(shí)是否齊全。驗(yàn)證矩陣門禁五道硬性關(guān)卡 G1–G5門禁文檔用一張驗(yàn)證矩陣表把必須被覆蓋的場(chǎng)景映射到必須存在的測(cè)試證據(jù)ID場(chǎng)景所需證據(jù)測(cè)試/文檔路徑G1omx team status讀取 manifest 授權(quán)的兼容視圖src/compat/tests/rust-runtime-compat.test.tsG2Doctor 保持 manifest 優(yōu)先的 tmux/session 優(yōu)先級(jí)src/compat/tests/rust-runtime-compat.test.tsG3HUD 保持 session 作用域狀態(tài)優(yōu)先于根級(jí)回退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 對(duì)等性由 Step 3 配套測(cè)試套件覆蓋notify-hook-team-dispatch.test.ts、notify-hook-team-leader-nudge.test.ts、tmux-detector.test.ts這五道關(guān)卡分別對(duì)應(yīng)三種舊讀取器團(tuán)隊(duì)狀態(tài)、doctor 診斷、HUD、一份架構(gòu)契約文檔和 watcher 投遞通道。門禁測(cè)試會(huì)對(duì)每個(gè) IDG1–G5做正則匹配并抽查關(guān)鍵語義字符串例如Semantic leakage survives into legacy readersWatcher send-keys parity breaks等確保門禁文檔沒有退化成空殼。Pre-mortem 場(chǎng)景映射從最可能崩在哪反推門檻門禁文檔還給出了一張事前驗(yàn)尸pre-mortem映射表把團(tuán)隊(duì)最擔(dān)心的四種失敗模式與上面的門禁一一對(duì)應(yīng)Pre-mortem 場(chǎng)景對(duì)應(yīng)門禁語義泄漏存活在舊讀取器中G1、G2、G3、G4讀取器優(yōu)先級(jí)在 config/manifest 或 session/root 作用域間漂移G1、G2、G3Watcher send-keys 對(duì)等性被破壞G5Mux 契約仍是 tmux 形狀而非 Rust 規(guī)范形狀G4這種先設(shè)想失敗再反推驗(yàn)證項(xiàng)的編排方式保證了門禁不是按方便測(cè)試來設(shè)計(jì)而是按遷移最容易踩的坑來設(shè)計(jì)。其中語義泄漏與優(yōu)先級(jí)漂移是同一類風(fēng)險(xiǎn)的兩個(gè)側(cè)面舊讀取器必須繼續(xù)工作但又絕不能把舊的默認(rèn)值當(dāng)成真相。契約核心誰是語義真相的唯一所有者門禁 G4 所依賴的契約文檔 rust-runtime-thin-adapter-contract.md 首先劃定了canonical ownership權(quán)威所有權(quán)邊界Rust core 是以下語義的唯一所有者authority權(quán)威租約lifecycle/session state生命周期與會(huì)話狀態(tài)dispatch/backlog派發(fā)與積壓mailbox delivery state信箱投遞狀態(tài)replay/recovery重放與恢復(fù)readiness/diagnostics就緒性與診斷canonical mux operations規(guī)范 mux 操作相應(yīng)地JS、HUD、CLI 和 tmux 只是薄的投遞/觀察適配器它們可以讀取兼容性工件但絕不能自行定義或變更語義真相。契約還定義了五條薄適配器規(guī)則兼容讀取器必須忽略未知字段并保留現(xiàn)有的 JSON 信封結(jié)構(gòu)遺留 tmux 鍵入typing僅用于投遞不建立語義真相當(dāng) Rust 作者兼容文件與遺留 JS 默認(rèn)值沖突時(shí)Rust 作者文件勝出只有在橋接bridge被禁用或不可用的降級(jí)通道上JS 文件寫入才允許作為回退當(dāng) Rust bridge 成功時(shí)它們不是權(quán)威的未知投遞失敗應(yīng)作為適配器失敗暴露而不是作為語義所有者變更。契約同時(shí)給出了消費(fèi)者矩陣Team CLI 負(fù)責(zé)忠實(shí)渲染 Rust 兼容工件Doctor CLI 先報(bào)告 Rust 工件的就緒性再疊加適配器健康檢查HUD 保持只讀且感知作用域Notify/watchers 只負(fù)責(zé)投遞事件永不成為運(yùn)行的語義所有者。兼容性工件與優(yōu)先級(jí)規(guī)則契約文檔用一張表明確了三類遺留讀取器各自讀取的兼容文件與優(yōu)先級(jí)保證讀取器兼容文件兼容保證omx team status.omx/state/team/team/config.json、manifest.v2.json、tasks/*.json、approvals/*.json、workers/*config 與 manifest 同時(shí)存在時(shí)manifest 授權(quán)的團(tuán)隊(duì)配置為權(quán)威omx doctor --team團(tuán)隊(duì)目錄下的config.json、manifest.v2.json、workers/*/status.json、workers/*/heartbeat.json、.omx/state/hud-state.jsonconfig 與 manifest 同時(shí)存在時(shí)manifest 授權(quán)的 tmux/session 身份為權(quán)威HUD readers.omx/state/session.json、.omx/state/sessions/session/team-state.json、.omx/state/team-state.json、.omx/state/ralph-state.json會(huì)話激活時(shí)session 作用域文件為權(quán)威根文件僅是兼容回退這三條優(yōu)先級(jí)規(guī)則正是 G1/G2/G3 的驗(yàn)證對(duì)象。在 rust-runtime-compat.test.ts 中可以看到它們的端到端驗(yàn)證方式G1team status測(cè)試先在臨時(shí)團(tuán)隊(duì)狀態(tài)根目錄初始化團(tuán)隊(duì)然后故意讓config.json與manifest.v2.json沖突config 聲明workspace_mode: single、舊 tmux 會(huì)話名manifest 聲明worktree、新會(huì)話名再運(yùn)行omx team status team --json并斷言輸出中的workspace_mode是 manifest 的worktreeG2doctor測(cè)試讓 config 與 manifest 的tmux_session沖突并把一個(gè)假的tmux二進(jìn)制注入 PATH只回顯 manifest 中的會(huì)話名然后運(yùn)行omx doctor --team斷言輸出包含team diagnostics: no issues與All team checks passed.且不出現(xiàn)resume_blockerG3HUD測(cè)試同時(shí)寫入根級(jí)team-state.jsonactive: false、team_name: legacy-root、agent_count: 1與 session 級(jí)sessions/id/team-state.jsonactive: true、team_name: rust-session、agent_count: 3再調(diào)用 HUD 的readTeamState斷言讀到的是 session 級(jí)數(shù)據(jù)。優(yōu)先級(jí)解析在源碼中的體現(xiàn)是 src/mcp/state-paths.ts 的resolveStateScope與getStateFilePath顯式 session id 當(dāng)前 session id 根級(jí)回退HUD 側(cè) src/hud/state.ts 的readAuthoritativeModeState會(huì)先解析當(dāng)前 session id再拼接mode-state.json的路徑。Rust 引擎如何寫出這些兼容視圖契約文檔明確給出了文件級(jí)證據(jù)RuntimeEngine位于 crates/omx-runtime-core/src/engine.rs通過persist()與write_compatibility_view()兩個(gè)方法寫出以下文件文件寫入方法內(nèi)容snapshot.jsonpersist()完整RuntimeSnapshotschema_version、authority、backlog、replay、readinessevents.jsonpersist()追加式事件日志RuntimeEvent數(shù)組#[serde(tag event)]格式authority.jsonwrite_compatibility_view()供 TS 讀取器使用的AuthoritySnapshot分區(qū)backlog.jsonwrite_compatibility_view()BacklogSnapshot計(jì)數(shù)pending/notified/delivered/failedreadiness.jsonwrite_compatibility_view()ReadinessSnapshotready、reasonsreplay.jsonwrite_compatibility_view()ReplaySnapshot狀態(tài)dispatch.jsonwrite_compatibility_view()完整DispatchLogDispatchRecord數(shù)組供團(tuán)隊(duì)狀態(tài)讀取器使用mailbox.jsonwrite_compatibility_view()完整MailboxLogMailboxRecord數(shù)組供團(tuán)隊(duì)/消息讀取器使用從源碼看兩個(gè)方法的職責(zé)劃分非常清晰engine.rspersist()約第 291 行會(huì)先創(chuàng)建engine.lock并加排他鎖隨后寫入snapshot.json、events.json、mailbox.json、dispatch.json并額外落盤dispatch-seen.json派發(fā)去重賬本schema_version2、ledger_epoch1保證崩潰后已接受的 request_id 永不重用write_compatibility_view()約第 322 行則基于snapshot()的結(jié)果把各分區(qū)拆成獨(dú)立小文件方便 TS 讀取器只讀自己關(guān)心的部分。所有文件都寫入配置的state_dir原子替換 目錄 fsync見persist_dispatch_seen_ledger與sync_directory。契約明確要求TS 讀取器必須把這些文件視為只讀Rust 引擎是唯一寫入者。CLI 二進(jìn)制 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每次執(zhí)行都會(huì)先加runtime-mutation.lock排他鎖然后load→process→ 可選compact→persist→write_compatibility_view即一次命令完成權(quán)威持久化 兼容視圖刷新兩件事。TS 側(cè)薄適配器RuntimeBridge 的只讀消費(fèi)門禁所依賴的另一半實(shí)現(xiàn)是 src/runtime/bridge.ts 中的RuntimeBridge它是 TS 側(cè)對(duì)omx-runtime二進(jìn)制的薄封裝。它的三條設(shè)計(jì)原則在文件頭注釋中寫明所有語義狀態(tài)變更都經(jīng)由execCommand()路由到 Rust 二進(jìn)制所有狀態(tài)查詢都讀取 Rust 作者兼容 JSON 文件設(shè)置OMX_RUNTIME_BRIDGE0可禁用橋接回退到 TS 直寫。橋接的讀取接口高度模塊化readAuthority()、readReadiness()、readBacklog()、readDispatchRecords()、readMailboxRecords()分別對(duì)應(yīng)authority.json、readiness.json、backlog.json、dispatch.json、mailbox.json。其中readCompatFileT()是統(tǒng)一入口它對(duì)文件正在被原子替換讀到空內(nèi)容臨時(shí)文件尚未落定等跨邊界場(chǎng)景做了容錯(cuò)——返回null讓上層本 tick 回退到 JS 推斷狀態(tài)而不是拋異常打斷整個(gè)查詢路徑。對(duì)于要求更嚴(yán)格的讀取場(chǎng)景如 dispatch 循環(huán)readDispatchRecordsStrict()會(huì)失敗關(guān)閉fail closed狀態(tài)目錄不可用、文件缺失、形狀非法、記錄不滿足DispatchRecord嚴(yán)格校驗(yàn)request_id/target/status/時(shí)間戳/metadata字段類型逐一檢查時(shí)直接拋出RuntimeBridgeError。execCommand()對(duì) Rust 返回非 JSON 輸出同樣拋出帶上下文的RuntimeBridgeError讓 dispatch 調(diào)用方可以用instanceof精確處理解析失敗而不是讓SyntaxError冒泡到無關(guān)層次。橋接的啟動(dòng)還包含一次契約自檢validateSchemaOnce()會(huì)調(diào)用omx-runtime schema --json校驗(yàn)預(yù)期命令集合acquire-authority、renew-authority、queue-dispatch、mark-notified、mark-delivered、mark-failed、remove-dispatch-records、request-replay、capture-snapshot是否齊全缺命令即判定TS 橋接類型與 Rust 二進(jìn)制不同步。二進(jìn)制定位順序見resolveRuntimeBinaryPath()OMX_RUNTIME_BINARY環(huán)境變量覆蓋 → 已驗(yàn)證的 native 緩存帶.sha256伴生校驗(yàn)文件→ workspacetarget/debug/omx-runtime→target/release/omx-runtime→ 回退到 PATH 上的omx-runtime。在 rust-runtime-compat.test.ts 的第四個(gè)測(cè)試約第 226 行中可以看到橋接兼容視圖勝過陳舊遺留文件的端到端驗(yàn)證測(cè)試先在遺留dispatch/requests.json與mailbox/worker-2.json中預(yù)置僅存在于舊通道的legacy-only記錄再通過enqueueDispatchRequest/sendDirectMessage走真實(shí)橋接寫入最后斷言listDispatchRequests/listMailboxMessages讀到的是橋接記錄舊遺留記錄不再出現(xiàn)——這正是 thin-adapter 規(guī)則 3Rust 文件勝出的直接證據(jù)。Watcher send-keys 對(duì)等性G5門禁 G5 關(guān)注的是 notify/watcher 通道的投遞對(duì)等性當(dāng) Rust bridge 接管權(quán)威狀態(tài)后watcher 仍然需要通過 tmuxsend-keys向目標(biāo) pane 投遞鍵擊這條投遞路徑不能因遷移而改變形狀。證據(jù)落在三個(gè)測(cè)試套件notify-hook-team-dispatch.test.ts斷言通知 hook 產(chǎn)生的send-keys -t pane目標(biāo) pane 正確如send-keys -t %99且不會(huì)錯(cuò)誤命中開發(fā)會(huì)話或替換 panenotify-hook-team-leader-nudge.test.ts覆蓋 leader nudge 場(chǎng)景下的投遞目標(biāo)tmux-detector.test.ts覆蓋 tmux 環(huán)境檢測(cè)。與 G4 呼應(yīng)的是投遞層允許tmux 形狀但規(guī)范 mux 操作canonical mux operations的所有權(quán)在 Rust。契約與 docs/interop-team-mutation-contract.md 都強(qiáng)調(diào)直接 tmux 鍵入只是操作層面的回退operational fallback絕不構(gòu)成變更契約——broker 必須通過 JSON 信封 狀態(tài)讀取來確認(rèn)變更是否成功。門禁之外非門禁的后續(xù) seam audit門禁文檔最后明確指出當(dāng)前 thin-adapter 切換仍存在少數(shù)已知的接縫缺口seam gaps它們被有意地排除在發(fā)布門禁之外記錄在 docs/qa/runtime-team-seam-audit-2026-04-01.md基線提交51579ceissue #1108 之后的快照。這份 audit 記錄了四個(gè)接縫點(diǎn)其中兩個(gè)已解決、兩個(gè)待跟進(jìn)Rust runtime ? TS team state 雙寫已由 issue #1108 解決。src/team/state/dispatch.ts與src/team/state/mailbox.ts中的 Rust 橋接/兼容文件現(xiàn)在是 dispatch 與 mailbox 的權(quán)威面遺留 TS 文件僅在橋接禁用/不可用時(shí)作為降級(jí)回退團(tuán)隊(duì)元數(shù)據(jù)解析橫跨多個(gè)文件未解決src/team/api-interop.ts約第 423–438 行先查 worker identity 元數(shù)據(jù)再查manifest.v2.json最后查config.json工作目錄/狀態(tài)根解析可能依賴回退順序而非單一權(quán)威源運(yùn)行時(shí)所有權(quán)契約 vs 切換現(xiàn)實(shí)dispatch/mailbox 所有權(quán)已與契約一致剩余工作是元數(shù)據(jù)/回退層的簡化兼容讀取器仍攜帶回退優(yōu)先級(jí)邏輯未解決rust-runtime-compat.test.ts約第 47–170 行與 src/hud/state.ts約第 107–123 行有意保留舊優(yōu)先級(jí)以保證遷移安全但這也讓讀路徑比目標(biāo)架構(gòu)更復(fù)雜未來格式漂移可能藏在回退行為里。audit 給出的后續(xù)順序是先把團(tuán)隊(duì)狀態(tài)根/工作目錄解析收斂到單一規(guī)范元數(shù)據(jù)源再在寫路徑單所有者之后削減兼容回退層。門禁文檔之所以把這些排除在外正是因?yàn)樗鼈儗儆谘葸M(jìn)方向而非切換正確性——切換本身權(quán)威性、優(yōu)先級(jí)、投遞對(duì)等已由 G1–G5 牢牢鎖住。如何在本倉庫中驗(yàn)證門禁門禁測(cè)試與契約測(cè)試均使用 Node 內(nèi)置node:test編寫可從倉庫根目錄直接運(yùn)行# 校驗(yàn)門禁文檔與契約文檔的關(guān)鍵語義G4 node --test src/verification/__tests__/rust-runtime-thin-adapter-gate.test.ts # 端到端驗(yàn)證 G1/G2/G3 及橋接兼容視圖優(yōu)先級(jí) 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 側(cè)的引擎單元測(cè)試persist/load往返、兼容視圖分區(qū)文件寫出、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會(huì)真正 spawndist/cli/omx.js需要先完成 TS 構(gòu)建同時(shí)它會(huì)通過OMX_TEAM_STATE_ROOT、OMX_RUNTIME_BINARY、PATH等環(huán)境變量注入隔離的臨時(shí)狀態(tài)目錄與假tmux/假 runtime 二進(jìn)制因此驗(yàn)證時(shí)不依賴真實(shí)環(huán)境。若在部分受限文件系統(tǒng)權(quán)限下運(yùn)行出現(xiàn)EPERM/EACCES測(cè)試會(huì)按shouldSkipForSpawnPermissions跳過 spawn 類斷言。小結(jié)門禁文檔的工程價(jià)值rust-runtime-thin-adapter-gate.md看似只是一張核對(duì)清單但它實(shí)際上定義了一套可執(zhí)行的架構(gòu)治理機(jī)制G1–G5 驗(yàn)證矩陣把Rust 權(quán)威、TS 只讀的架構(gòu)原則翻譯成了可斷言的測(cè)試證據(jù)Pre-mortem 映射確保門禁覆蓋的是真實(shí)遷移風(fēng)險(xiǎn)而非隨機(jī)場(chǎng)景契約文檔劃清了權(quán)威所有權(quán)與五條薄適配器規(guī)則任何一邊越界都會(huì)被門禁測(cè)試或運(yùn)行時(shí)校驗(yàn)抓住非門禁 audit則把正確性與演進(jìn)分開治理既不放行已知回歸也不阻塞架構(gòu)優(yōu)化。對(duì)任何正在做語言/運(yùn)行時(shí)邊界重構(gòu) 老讀取器兼容的團(tuán)隊(duì)來說這套契約文檔 門禁矩陣 端到端兼容測(cè)試 非門禁跟進(jìn)審計(jì)的組合是一個(gè)可以直接借鑒的遷移治理模板?！久赓M(fèi)下載鏈接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考