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