消息級 Fork：Thread 映射存儲、Turn Anchor 與 Native Session 完整指南)
CodexHost 如何實現(xiàn)消息級 ForkThread 映射存儲、Turn Anchor 與 Native Session 完整指南【免費下載鏈接】codex-hostRun Pi and Claude Code directly in Codex Desktop. 在 Codex Desktop 中直接運行 Pi 和 Claude Code。項目地址: https://gitcode.com/gh_mirrors/co/codex-hostCodexHost 是一個讓你在 Codex Desktop 中直接運行 Pi 和 Claude Code 的宿主層。它最讓人驚艷的能力之一是消息級 Fork點擊任意一條歷史消息上的 Fork 按鈕就能從那個精確位置派生出一條全新的獨立會話而原始對話保持不動。本文帶你拆解背后三個核心機制——Thread 映射存儲Mapping Store、Turn Anchor 與 Native Session 的工作原理讓你徹底理解 CodexHost 的會話分叉是如何做到精確、可恢復、不丟消息的。什么是消息級 Fork為什么它不容易做到在 Codex Desktop 里Fork 意味著從對話的某個歷史位置復制出一條新時間線。難點在于對話的真實歷史存放在Pi 或 Claude Code 自己的會話文件里而不是 Codex 的數(shù)據(jù)庫中每條 UI 消息必須能穩(wěn)定地對應到 Harness 內(nèi)部的歷史條目Fork 之后新對話必須能獨立繼續(xù)且不能污染源會話更不能改動你的項目文件。CodexHost 用三層結(jié)構(gòu)解決了這個問題下面逐個拆解。三個核心概念先建立正確的詞匯表Native SessionHarness 原生的會話每個外部 Harness如 Pi、Claude Code維護自己的原生會話狀態(tài)稱為Native Session。CodexHost 不復制它的內(nèi)容只持有指向它的不透明引用NativeSessionRef。這是第二事實源問題的根源——歷史只存在于原生會話里CodexHost 只記錄在哪、對應誰。Turn Anchor把 UI 消息釘在歷史坐標上這是 CodexHost 的關鍵發(fā)明。領域術語表 中的定義是Turn AnchorCodexHost 保存的Host Turn ID → Native Checkpoint ID定位元數(shù)據(jù)用于 Fork 等精確會話操作。它不包含消息正文不構(gòu)成第二份會話事實源。通俗地說界面上每一條消息輪次Turn都有一個穩(wěn)定的 Host Turn ID而 Turn Anchor 記錄了這條消息在 Pi/Claude 原生歷史中的精確位置Native Checkpoint。Fork 某條消息時CodexHost 只需查出它的 Anchor就能調(diào)用原生的精確分叉操作而不是靠數(shù)第幾條消息這種脆弱的做法。Host ThreadCodex 側(cè)的影子會話Codex UI 看到的 Thread 是 Host Thread由 CodexHost 負責把它和某個 Harness 的 Native Session 綁定。Fork 時創(chuàng)建的新 Host Thread 會指向一個全新的派生 Native Session源 Thread 原封不動。Mapping StoreThread 映射存儲的賬本Thread 與 Native Session 的映射關系由獨立的 mapping-store 模塊持久化。它的源碼在 packages/mapping-store/src/mapping-store.ts記錄結(jié)構(gòu)定義在 packages/mapping-store/src/records.ts。每個外部 Thread 對應一個嚴格版本化的 JSON 文件核心字段包括hostThreadId/harnessId這條 Thread 屬于誰、歸哪個 HarnessnativeSessionRef指向原生會話的引用turnMappings[]有序的 Turn 映射列表每項含hostTurnId、nativeTurnRef和可選的nativeCheckpointRef也就是 Turn AnchorforkSource如果是 Fork 出來的記錄源 Thread 停在源 Thread 的哪個 Turnrevision版本號用于并發(fā)寫保護。幾個值得新手記住的設計原則只存坐標不存內(nèi)容——記錄中嚴禁出現(xiàn) Prompt、消息正文、工具輸出或憑據(jù)原子寫入——每次更新都是寫臨時文件 → 備份 → 原子替換失敗時舊記錄依然權(quán)威單寫者鎖——同一時間只有一個進程能寫 Store重啟后還能識別 macOS 上被復用的僵尸 PID 并恢復過期鎖啟動自愈——損壞的主記錄可從備份恢復無法恢復的被隔離臨時文件被清理。完整的行為規(guī)范見 external-thread-mapping-store spec。Fork 執(zhí)行流程一次點擊背后發(fā)生了什么當你點擊某條消息的 Fork 時external-thread-fork.ts 中的路由邏輯按下面步驟工作所有權(quán)判定thread/fork請求先按源 Thread 的所有權(quán)路由——Codex 原生的 Thread 原樣透傳外部 Thread 則由 CodexHost 本地處理絕不轉(zhuǎn)發(fā)給官方 Codex邊界解析支持三種取法——lastTurnId含該輪、beforeTurnId不含該輪、都不傳從最新一輪。邊界最終落到該輪的 Turn AnchorCheckpoint原子打開通過adapter.open(fork)讓 Harness 從精確 Checkpoint 派生一個獨立的新 Native SessionPi 內(nèi)部用原生fork/clone操作并先寫入一條預備記錄重建映射讀取派生會話的 Snapshot為派生 Thread 重新分配自己的 Host Turn ID 和 Anchor——絕不復制源 Thread 的映射提交后返回全部映射持久化成功后才返回 Fork 響應。即使原生 Fork 成功但存儲提交失敗CodexHost 會關閉派生運行時、清理預備記錄并報錯保證不留下幽靈映射。規(guī)范細節(jié)見 external-thread-fork-routing spec 與 harness-adapter-history-fork-session spec。兼容細節(jié)兩階段 Fork 與回滾修正一個有意思的現(xiàn)實問題受支持的 Codex Desktop 版本在選中非尾部消息時實際發(fā)送的是無邊界 Fork 一條thread/rollback { numTurns }的組合拳。CodexHost 專門實現(xiàn)了這條兼容路徑只對派生 Thread 恰好是源 Thread 前綴這一精確場景生效用持久化的有序 Turn 映射解析numTurns從源 Checkpoint 重新派生最終 Native Session通過帶版本號的原子替換compare-and-swap一次性換掉派生記錄的nativeSessionRef、Turn 映射與forkSource邊界同時保留派生 Host Thread IDUI 上看起來就像原地縮短了對話。這條路徑的設計記錄見 harden-history-mapping-cas它保證了并發(fā)修改時舊版本寫入會被干凈地拒絕。重啟后依然精確持久化帶來的恢復能力因為 Turn Anchor 與映射都落了盤CodexHost 重啟后任何已持久化的外部 Thread 都能通過thread/read、thread/resume、thread/fork按需恢復——Host 調(diào)用adapter.open(resume)重新打開精確的原生會話如果原生會話文件丟失會返回明確的sessionNotFound錯誤而不是靜默降級到 Codex只分配了預備記錄、尚無 Native Session 的 Thread 會在啟動時被清理不會暴露為半成品對話。代碼地圖想深入看哪里想了解的內(nèi)容入口位置映射記錄 Schema 與字段packages/mapping-store/src/records.ts原子寫、鎖與啟動恢復packages/mapping-store/src/mapping-store.tsFork 請求路由與邊界解析packages/host-runtime/src/external-thread-fork.ts兩階段回滾兼容packages/host-runtime/src/external-thread-rollback.ts歷史 Fork 能力契約openspec/specs/harness-adapter-history-fork-session/spec.md最初的設計決策記錄openspec/changes/archive/2026-07-30-implement-external-thread-history-fork-slice/design.md術語定義Turn Anchor 等docs/project/領域術語表.md小結(jié)CodexHost 的消息級 Fork 本質(zhì)上是一套坐標系統(tǒng) 精確原生操作 可靠賬本的組合Turn Anchor 把 UI 消息釘在原生歷史的精確坐標上Mapping Store 以原子方式持久化這些坐標open(fork)則讓 Harness 在原生層完成真正的分叉。三者疊加才讓點一下任意歷史消息就能開出一條新時間線這個體驗在重啟、并發(fā)和失敗場景下都依然可信?！久赓M下載鏈接】codex-hostRun Pi and Claude Code directly in Codex Desktop. 在 Codex Desktop 中直接運行 Pi 和 Claude Code。項目地址: https://gitcode.com/gh_mirrors/co/codex-host創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 CodexHost 如何實現(xiàn)消息級 Fork：Thread 映射存儲、Turn Anchor 與 Native Session 完整指南
CodexHost 如何實現(xiàn)消息級 ForkThread 映射存儲、Turn Anchor 與 Native Session 完整指南【免費下載鏈接】codex-hostRun Pi and Claude Code directly in Codex Desktop. 在 Codex Desktop 中直接運行 Pi 和 Claude Code。項目地址: https://gitcode.com/gh_mirrors/co/codex-hostCodexHost 是一個讓你在 Codex Desktop 中直接運行 Pi 和 Claude Code 的宿主層。它最讓人驚艷的能力之一是消息級 Fork點擊任意一條歷史消息上的 Fork 按鈕就能從那個精確位置派生出一條全新的獨立會話而原始對話保持不動。本文帶你拆解背后三個核心機制——Thread 映射存儲Mapping Store、Turn Anchor 與 Native Session 的工作原理讓你徹底理解 CodexHost 的會話分叉是如何做到精確、可恢復、不丟消息的。什么是消息級 Fork為什么它不容易做到在 Codex Desktop 里Fork 意味著從對話的某個歷史位置復制出一條新時間線。難點在于對話的真實歷史存放在Pi 或 Claude Code 自己的會話文件里而不是 Codex 的數(shù)據(jù)庫中每條 UI 消息必須能穩(wěn)定地對應到 Harness 內(nèi)部的歷史條目Fork 之后新對話必須能獨立繼續(xù)且不能污染源會話更不能改動你的項目文件。CodexHost 用三層結(jié)構(gòu)解決了這個問題下面逐個拆解。三個核心概念先建立正確的詞匯表Native SessionHarness 原生的會話每個外部 Harness如 Pi、Claude Code維護自己的原生會話狀態(tài)稱為Native Session。CodexHost 不復制它的內(nèi)容只持有指向它的不透明引用NativeSessionRef。這是第二事實源問題的根源——歷史只存在于原生會話里CodexHost 只記錄在哪、對應誰。Turn Anchor把 UI 消息釘在歷史坐標上這是 CodexHost 的關鍵發(fā)明。領域術語表 中的定義是Turn AnchorCodexHost 保存的Host Turn ID → Native Checkpoint ID定位元數(shù)據(jù)用于 Fork 等精確會話操作。它不包含消息正文不構(gòu)成第二份會話事實源。通俗地說界面上每一條消息輪次Turn都有一個穩(wěn)定的 Host Turn ID而 Turn Anchor 記錄了這條消息在 Pi/Claude 原生歷史中的精確位置Native Checkpoint。Fork 某條消息時CodexHost 只需查出它的 Anchor就能調(diào)用原生的精確分叉操作而不是靠數(shù)第幾條消息這種脆弱的做法。Host ThreadCodex 側(cè)的影子會話Codex UI 看到的 Thread 是 Host Thread由 CodexHost 負責把它和某個 Harness 的 Native Session 綁定。Fork 時創(chuàng)建的新 Host Thread 會指向一個全新的派生 Native Session源 Thread 原封不動。Mapping StoreThread 映射存儲的賬本Thread 與 Native Session 的映射關系由獨立的 mapping-store 模塊持久化。它的源碼在 packages/mapping-store/src/mapping-store.ts記錄結(jié)構(gòu)定義在 packages/mapping-store/src/records.ts。每個外部 Thread 對應一個嚴格版本化的 JSON 文件核心字段包括hostThreadId/harnessId這條 Thread 屬于誰、歸哪個 HarnessnativeSessionRef指向原生會話的引用turnMappings[]有序的 Turn 映射列表每項含hostTurnId、nativeTurnRef和可選的nativeCheckpointRef也就是 Turn AnchorforkSource如果是 Fork 出來的記錄源 Thread 停在源 Thread 的哪個 Turnrevision版本號用于并發(fā)寫保護。幾個值得新手記住的設計原則只存坐標不存內(nèi)容——記錄中嚴禁出現(xiàn) Prompt、消息正文、工具輸出或憑據(jù)原子寫入——每次更新都是寫臨時文件 → 備份 → 原子替換失敗時舊記錄依然權(quán)威單寫者鎖——同一時間只有一個進程能寫 Store重啟后還能識別 macOS 上被復用的僵尸 PID 并恢復過期鎖啟動自愈——損壞的主記錄可從備份恢復無法恢復的被隔離臨時文件被清理。完整的行為規(guī)范見 external-thread-mapping-store spec。Fork 執(zhí)行流程一次點擊背后發(fā)生了什么當你點擊某條消息的 Fork 時external-thread-fork.ts 中的路由邏輯按下面步驟工作所有權(quán)判定thread/fork請求先按源 Thread 的所有權(quán)路由——Codex 原生的 Thread 原樣透傳外部 Thread 則由 CodexHost 本地處理絕不轉(zhuǎn)發(fā)給官方 Codex邊界解析支持三種取法——lastTurnId含該輪、beforeTurnId不含該輪、都不傳從最新一輪。邊界最終落到該輪的 Turn AnchorCheckpoint原子打開通過adapter.open(fork)讓 Harness 從精確 Checkpoint 派生一個獨立的新 Native SessionPi 內(nèi)部用原生fork/clone操作并先寫入一條預備記錄重建映射讀取派生會話的 Snapshot為派生 Thread 重新分配自己的 Host Turn ID 和 Anchor——絕不復制源 Thread 的映射提交后返回全部映射持久化成功后才返回 Fork 響應。即使原生 Fork 成功但存儲提交失敗CodexHost 會關閉派生運行時、清理預備記錄并報錯保證不留下幽靈映射。規(guī)范細節(jié)見 external-thread-fork-routing spec 與 harness-adapter-history-fork-session spec。兼容細節(jié)兩階段 Fork 與回滾修正一個有意思的現(xiàn)實問題受支持的 Codex Desktop 版本在選中非尾部消息時實際發(fā)送的是無邊界 Fork 一條thread/rollback { numTurns }的組合拳。CodexHost 專門實現(xiàn)了這條兼容路徑只對派生 Thread 恰好是源 Thread 前綴這一精確場景生效用持久化的有序 Turn 映射解析numTurns從源 Checkpoint 重新派生最終 Native Session通過帶版本號的原子替換compare-and-swap一次性換掉派生記錄的nativeSessionRef、Turn 映射與forkSource邊界同時保留派生 Host Thread IDUI 上看起來就像原地縮短了對話。這條路徑的設計記錄見 harden-history-mapping-cas它保證了并發(fā)修改時舊版本寫入會被干凈地拒絕。重啟后依然精確持久化帶來的恢復能力因為 Turn Anchor 與映射都落了盤CodexHost 重啟后任何已持久化的外部 Thread 都能通過thread/read、thread/resume、thread/fork按需恢復——Host 調(diào)用adapter.open(resume)重新打開精確的原生會話如果原生會話文件丟失會返回明確的sessionNotFound錯誤而不是靜默降級到 Codex只分配了預備記錄、尚無 Native Session 的 Thread 會在啟動時被清理不會暴露為半成品對話。代碼地圖想深入看哪里想了解的內(nèi)容入口位置映射記錄 Schema 與字段packages/mapping-store/src/records.ts原子寫、鎖與啟動恢復packages/mapping-store/src/mapping-store.tsFork 請求路由與邊界解析packages/host-runtime/src/external-thread-fork.ts兩階段回滾兼容packages/host-runtime/src/external-thread-rollback.ts歷史 Fork 能力契約openspec/specs/harness-adapter-history-fork-session/spec.md最初的設計決策記錄openspec/changes/archive/2026-07-30-implement-external-thread-history-fork-slice/design.md術語定義Turn Anchor 等docs/project/領域術語表.md小結(jié)CodexHost 的消息級 Fork 本質(zhì)上是一套坐標系統(tǒng) 精確原生操作 可靠賬本的組合Turn Anchor 把 UI 消息釘在原生歷史的精確坐標上Mapping Store 以原子方式持久化這些坐標open(fork)則讓 Harness 在原生層完成真正的分叉。三者疊加才讓點一下任意歷史消息就能開出一條新時間線這個體驗在重啟、并發(fā)和失敗場景下都依然可信?！久赓M下載鏈接】codex-hostRun Pi and Claude Code directly in Codex Desktop. 在 Codex Desktop 中直接運行 Pi 和 Claude Code。項目地址: https://gitcode.com/gh_mirrors/co/codex-host創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考