CodexHost 如何实现消息级 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 的数据库中每条 UI 消息必须能稳定地对应到 Harness 内部的历史条目Fork 之后新对话必须能独立继续且不能污染源会话更不能改动你的项目文件。CodexHost 用三层结构解决了这个问题下面逐个拆解。三个核心概念先建立正确的词汇表Native SessionHarness 原生的会话每个外部 Harness如 Pi、Claude Code维护自己的原生会话状态称为Native Session。CodexHost 不复制它的内容只持有指向它的不透明引用NativeSessionRef。这是第二事实源问题的根源——历史只存在于原生会话里CodexHost 只记录在哪、对应谁。Turn Anchor把 UI 消息钉在历史坐标上这是 CodexHost 的关键发明。领域术语表 中的定义是Turn AnchorCodexHost 保存的Host Turn ID → Native Checkpoint ID定位元数据用于 Fork 等精确会话操作。它不包含消息正文不构成第二份会话事实源。通俗地说界面上每一条消息轮次Turn都有一个稳定的 Host Turn ID而 Turn Anchor 记录了这条消息在 Pi/Claude 原生历史中的精确位置Native Checkpoint。Fork 某条消息时CodexHost 只需查出它的 Anchor就能调用原生的精确分叉操作而不是靠数第几条消息这种脆弱的做法。Host ThreadCodex 侧的影子会话Codex UI 看到的 Thread 是 Host Thread由 CodexHost 负责把它和某个 Harness 的 Native Session 绑定。Fork 时创建的新 Host Thread 会指向一个全新的派生 Native Session源 Thread 原封不动。Mapping StoreThread 映射存储的账本Thread 与 Native Session 的映射关系由独立的 mapping-store 模块持久化。它的源码在 packages/mapping-store/src/mapping-store.ts记录结构定义在 packages/mapping-store/src/records.ts。每个外部 Thread 对应一个严格版本化的 JSON 文件核心字段包括hostThreadId/harnessId这条 Thread 属于谁、归哪个 HarnessnativeSessionRef指向原生会话的引用turnMappings[]有序的 Turn 映射列表每项含hostTurnId、nativeTurnRef和可选的nativeCheckpointRef也就是 Turn AnchorforkSource如果是 Fork 出来的记录源 Thread 停在源 Thread 的哪个 Turnrevision版本号用于并发写保护。几个值得新手记住的设计原则只存坐标不存内容——记录中严禁出现 Prompt、消息正文、工具输出或凭据原子写入——每次更新都是写临时文件 → 备份 → 原子替换失败时旧记录依然权威单写者锁——同一时间只有一个进程能写 Store重启后还能识别 macOS 上被复用的僵尸 PID 并恢复过期锁启动自愈——损坏的主记录可从备份恢复无法恢复的被隔离临时文件被清理。完整的行为规范见 external-thread-mapping-store spec。Fork 执行流程一次点击背后发生了什么当你点击某条消息的 Fork 时external-thread-fork.ts 中的路由逻辑按下面步骤工作所有权判定thread/fork请求先按源 Thread 的所有权路由——Codex 原生的 Thread 原样透传外部 Thread 则由 CodexHost 本地处理绝不转发给官方 Codex边界解析支持三种取法——lastTurnId含该轮、beforeTurnId不含该轮、都不传从最新一轮。边界最终落到该轮的 Turn AnchorCheckpoint原子打开通过adapter.open(fork)让 Harness 从精确 Checkpoint 派生一个独立的新 Native SessionPi 内部用原生fork/clone操作并先写入一条预备记录重建映射读取派生会话的 Snapshot为派生 Thread 重新分配自己的 Host Turn ID 和 Anchor——绝不复制源 Thread 的映射提交后返回全部映射持久化成功后才返回 Fork 响应。即使原生 Fork 成功但存储提交失败CodexHost 会关闭派生运行时、清理预备记录并报错保证不留下幽灵映射。规范细节见 external-thread-fork-routing spec 与 harness-adapter-history-fork-session spec。兼容细节两阶段 Fork 与回滚修正一个有意思的现实问题受支持的 Codex Desktop 版本在选中非尾部消息时实际发送的是无边界 Fork 一条thread/rollback { numTurns }的组合拳。CodexHost 专门实现了这条兼容路径只对派生 Thread 恰好是源 Thread 前缀这一精确场景生效用持久化的有序 Turn 映射解析numTurns从源 Checkpoint 重新派生最终 Native Session通过带版本号的原子替换compare-and-swap一次性换掉派生记录的nativeSessionRef、Turn 映射与forkSource边界同时保留派生 Host Thread IDUI 上看起来就像原地缩短了对话。这条路径的设计记录见 harden-history-mapping-cas它保证了并发修改时旧版本写入会被干净地拒绝。重启后依然精确持久化带来的恢复能力因为 Turn Anchor 与映射都落了盘CodexHost 重启后任何已持久化的外部 Thread 都能通过thread/read、thread/resume、thread/fork按需恢复——Host 调用adapter.open(resume)重新打开精确的原生会话如果原生会话文件丢失会返回明确的sessionNotFound错误而不是静默降级到 Codex只分配了预备记录、尚无 Native Session 的 Thread 会在启动时被清理不会暴露为半成品对话。代码地图想深入看哪里想了解的内容入口位置映射记录 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小结CodexHost 的消息级 Fork 本质上是一套坐标系统 精确原生操作 可靠账本的组合Turn Anchor 把 UI 消息钉在原生历史的精确坐标上Mapping Store 以原子方式持久化这些坐标open(fork)则让 Harness 在原生层完成真正的分叉。三者叠加才让点一下任意历史消息就能开出一条新时间线这个体验在重启、并发和失败场景下都依然可信。【免费下载链接】codex-hostRun Pi and Claude Code directly in Codex Desktop. 在 Codex Desktop 中直接运行 Pi 和 Claude Code。项目地址: https://gitcode.com/gh_mirrors/co/codex-host创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考