手把手教你实现跨 CLI 编程 Agent 的本地会话接力

52 阅读9分钟

被 Claude Code 5小时限额打断思路?手把手教你实现跨 CLI 编程 Agent 的本地会话接力

导读:在长任务代码重构或 Bug 深度排查中,最让人崩溃的莫过于终端突然跳出一句:"You have exceeded your current usage limit, please try again in 5 hours."。思路瞬间被迫中断,换个工具(如 Codex CLI / OpenCode)又得把几千行的代码背景、排查足迹与错误日志人肉重新交代一遍。
本文将深入剖析主流 CLI Agent 的本地存储底牌,详解如何通过统一事件流抽象与原子写保护,实现优雅的跨 Agent 会话“值更接力”。


一、 为什么传统的“手动复制粘贴”行不通?

随着 Claude Code、OpenAI Codex CLI、OpenCode、Kimi Code 等终端智能体深入工程日常,开发者的工作范式已经从“单次问答”演进为“多轮自主排查与工具调用”。

但在高强度编码场景下,开发者经常面临两个工程级痛点:

  1. 硬性限额打断:根据 Anthropic 官方规则,部分账户订阅计划存在 5 小时或周期性的使用额度窗口(Usage Limit)。一旦触发,当场被拒之门外;
  2. 模型死循环卡死:某个模型在特定上下文下陷入逻辑死胡同,反复修改同一个文件或生成相同报错。

这时最直觉的想法是:“换个 Agent 接着干”。但当你新开一个窗口打开 Codex 或 OpenCode 时,你会发现极高的心智摩擦:

[痛点场景还原]
开发者: "我刚才用 Claude Code 排查了一个诡异的死锁问题,它改了 A、B 两个文件,
        跑测试挂了,排查了 10 轮发现是 channel 没关闭……"
新 Agent: "请把涉及的代码和报错日志完整发给我。"
开发者: 疯狂翻找历史终端输出,复制粘贴 2000 行 Token……
新 Agent: "抱歉,上下文过长,且缺少先前的工具执行中间状态。"

传统的人工复制有三大致命缺陷:

  • 丢失工具调用链条(Tool Calls & Results):模型不知道前序 Agent 执行过哪些 bash 命令、读过哪些文件的具体版本;
  • 丢失真实工作区语境(Working Directory & Project ID):在 Monorepo 或多分支 Worktree 场景下极易跑偏;
  • 浪费宝贵的初始 Context:重复交代背景会挤占新模型的有效上下文窗口。

二、 探秘:主流 CLI Agent 的本地存储底层

要实现会话接力,第一步就是摸清各大 Agent 在你的机器里究竟把上下文存到了哪里、格式是怎样的。

1. 各家 Agent 本地存储载体对比

编程 Agent本地文件载体存储格式关键特征
Claude Code~/.claude/projects/<encoded-cwd>/<session-id>.jsonl行式 JSONL追加流式写入,以事件节点记录 message 与 tool_use
OpenAI Codex~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl行式 JSONL / SQLite配合 local app-server daemon,受 Session ID 索引
OpenCode~/.local/share/opencode/opencode.dbSQLite 数据库关系型规范表结构,强事务与关联映射
Kimi Code~/.kimi-code/sessions/.../wire.jsonl行式 JSONL包含线协议与交互回合

2. Claude Code 会话切片逆向分析

以 Claude Code 为例,其会话是以 JSONL 追加写入的,包含细粒度的事件类型:

// ~/.claude/projects/L1VzZXJzL2Rldi9teS1wcm9qZWN0/abc-123.jsonl
{"type":"user","message":{"role":"user","content":"请排查连接池泄露问题"},"timestamp":"2026-09-21T10:00:00Z"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"thinking","thinking":"正在检查 db.go..."},{"type":"tool_use","id":"tool_call_01","name":"read_file","input":{"path":"db.go"}}]},"timestamp":"2026-09-21T10:00:05Z"}
{"type":"tool_result","tool_use_id":"tool_call_01","content":"func Connect() { ... }","timestamp":"2026-09-21T10:00:08Z"}

核心观察: 所有的排查结论、中间读过的文件内容、执行过的 Bash 测试结果,全部完整安静地躺在你的本地磁盘中。我们完全不需要云端中继,直接在本机读取并做结构化转录即可!


三、 会话接力核心设计:统一抽象与写入守卫

为了实现跨工具平滑流转,开源工具 Watch(值更) 设计了一套干净的架构:

┌─────────────────────────────────────────────────────────────┐
│                      用户交互界面 (UI / CLI)                 │
│       反查当前会话 ID  ──►  选择目标 Agent (如 Codex)         │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│                    核心接力引擎 (Core Engine)                │
│                                                             │
│   1. 统一数据流抽象 (UnifiedTurn & ProcessEvent)             │
│   2. 增量比对与对齐 (diffTurns 提取未完成步骤)                 │
│   3. 目标协议适配器 (Claude / Codex / OpenCode / Kimi)      │
│   4. 原子写与防并发锁 (writeFileAtomic + .lock)             │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│                    本地 Agent 原生载体                       │
│    Claude JSONL  ──►  Codex app-server RPC / OpenCode DB    │
└─────────────────────────────────────────────────────────────┘

1. 统一时间线抽象 (UnifiedTurn)

不同 Agent 对“消息”和“工具”的称呼各异。核心引擎将其归一化为统一的回合:

// src/core/types.ts
export type ProcessEvent =
  | { type: 'text'; text: string }
  | { type: 'thinking'; thinking: string }
  | { type: 'tool_call'; id: string; name: string; args: Record<string, unknown> }
  | { type: 'tool_result'; toolCallId: string; content: string; isError?: boolean };

export type UnifiedTurn = {
  role: 'user' | 'assistant';
  text: string;                  // 纯净用户指令或最终助手回复
  timestamp: string;             // ISO 8601
  provider?: string;             // 来源标识,例如 'claude'
  events?: ProcessEvent[];       // 详细的过程事件(思考、工具调用链)
};

2. 增量提取:只把“新进展”带给目标

当两个 Agent 互相轮换时,必须避免把历史内容重复追加导致上下文爆炸。引擎采用增量指纹对比:

// 提取来源会话相对于目标已有会话的增量 Turns
export function diffTurns(sourceTurns: UnifiedTurn[], targetTurns: UnifiedTurn[]): UnifiedTurn[] {
  if (targetTurns.length === 0) return sourceTurns;
  
  // 基于首个 user turn 的哈希与后缀指纹对齐
  const anchorIndex = findMatchingAnchor(sourceTurns, targetTurns);
  return sourceTurns.slice(anchorIndex);
}

3. 数据安全边界:零损坏原子写

直接修改 AI 客户端的文件是非常危险的,一旦进程被强杀或遭遇 TOCTOU(Time-of-check to time-of-use)竞争,可能损坏已有历史。必须遵循双重保护:

  • 写入前校验:校验目标文件指纹(Digest);
  • 原子替换:先写入 .tmp 临时文件,校验无误后通过 rename 原子替换,并生成 .bak 备份;
  • 锁隔离:在目标目录创建 .watch-official-import.lock,防止并发冲突。

四、 实战演练:当 Claude Code 限额后,如何转入 Codex 继续

下面以 Claude Code 限额后转入 OpenAI Codex Desktop 为例,演示标准的工程化接力步骤。

⚠️ 先决条件:

  1. 本机已安装 Claude Code 和 OpenAI Codex;
  2. 确认由于使用量触发限额,而非单次上下文超长(若是单次上下文超长,优先在 Claude 中输入 /compact 压缩)。

步骤 1:确认来源会话与项目目录

在终端确认刚才正在跑的会话 ID 与绝对路径:

# 查看 Claude Code 最近的会话信息
ls -lt ~/.claude/projects/
# 假定得到当前会话 ID: 7d2f5a8b-c9e1-4b72-8721-39801b691122
# 项目所在绝对路径: /Users/bobochang/Documents/CODE/my-project

步骤 2:在目标 Codex 中预建项目(避免孤立)

根据 OpenAI 官方导入协议要求,目标工作空间必须预先存在于 Codex 中:

  • 打开 Codex Desktop;
  • 点击 Open Folder,选择 /Users/bobochang/Documents/CODE/my-project 并完成信任确认。

步骤 3:CLI 准备阶段(Prepare,只读生成计划)

在 Watch 中执行 prepare 命令。该命令只做只读检查并锁定会话元数据,绝不写入任何文件:

npm run watch -- import-codex prepare 7d2f5a8b-c9e1-4b72-8721-39801b691122 \
  --cwd /Users/bobochang/Documents/CODE/my-project \
  --desktop-project \
  --experimental \
  --json

返回的计划切片(示例):

{
  "status": "prepared",
  "planId": "imp_9f83a21b4e",
  "sourceSessionId": "7d2f5a8b-c9e1-4b72-8721-39801b691122",
  "turnCount": 14,
  "toolCallCount": 6,
  "warnings": [
    "Tool call structures will degrade to text representations in Codex."
  ]
}

步骤 4:明确确认导入(Confirm)

核对 planId 与降级警告后,显式执行确认:

npm run watch -- import-codex confirm imp_9f83a21b4e --json

底层将通过 Codex 本地 app-server 的 externalAgentConfig/import 接口安全注入会话,并自动验证项目归属。

步骤 5:启动 Codex 继续开发

导入与打开是解耦的。导入成功后,直接打开 Codex Desktop 或通过 CLI 恢复:

# 或者直接启动 Codex 交互恢复
codex resume --last

此时 Codex 已经读到了 Claude Code 之前排查到的第 14 步进展及代码变动。你在 Codex 中的第一句话建议:

“我已从 Claude Code 接力本会话。请根据上文排查出的连接池泄漏结论,继续完成单元测试编写。”

新 Agent 将立刻基于已有的足迹继续编码,无需任何多余废话!


五、 掘友关心的高频问题(FAQ)

Q1: 这算不算“破解”或“绕过”了 Claude Code 的限额?

不算,也绝不可能。
Watch 是一个 100% 运行在本机的工程接力工具,不提供任何黑客破解、不提供免费 Token,也不会碰你的 API Key 或官方账号。
它的本质相当于**“将水手 A 记录在航海日志上的笔录,端端正正抄送一份到水手 B 的桌案前”**。

Q2: 跨 Agent 接力后,工具调用(Tool Calls)能完美复原吗?

不同厂商对工具调用的定义存在差异。例如 Claude Code 的 tool call 在转入 Codex 时,为了保证目标 Agent 不崩溃,核心引擎会将复杂的工具参数和返回值降级为结构化文本展示。这意味着新 Agent 能够“看懂”之前查出的结果,但无法像原生回溯那样重放当时的 RPC 调用。

Q3: 如果进程意外中断了怎么办?

引擎设计了严密的锁定机制:如果导入过程中机器断电或终端退出,计划会保持在 uncertain 状态,并且 .lock 会防止误操作。你可以通过:

npm run watch -- import-codex status <plan-id> --json

进行只读核验,确定已写入的边界,严禁强删锁文件。


六、 总结与结语

在 AI Coding 逐渐成为主流生产力的今天,我们不应该受制于单一客户端的断线或限额。 “代码是漫长的远洋航行,会话历史是你的航海日志,而各家 Agent 只是轮班值更的水手。”

理解本地文件模型,善用统一会话接力,能让你在面对高难度工程任务时,真正实现多个 Agent 协同作业、前更交接、航程不歇。

欢迎在评论区分享你在用 Claude Code 或 Codex 编程时踩过的坑,一起交流多 Agent 协同的最佳实践!


欢迎关注作者,持续分享 AI 编程 Agent 架构设计与极客硬核实战!