Nate_gu's Brain

Claude Code 长会话工程总览

11分钟阅读

Claude Code 长会话工程总览

这页回答什么

为什么 Claude Code 看起来不只是一个 query() + tools 的 agent，而更像一套能长期运行、不断自我修补、把后台结果重新注回上下文的工程系统？所谓“长会话工程”到底包括哪些横切机制？

这页不试图替代各单页 walkthrough，而是把已经确认的横切能力收束成一张更高层的图。

一句话结论

Claude Code 的成熟度，不主要体现在“能调很多工具”，而在于它围绕 长会话持续运行 建了一整套横切机制：prompt cache 稳定性、上下文压缩、前台到后台切换、任务回流、shell 持久化输出、失败后的安全收口与重试空间。

更直接一点说：

query() 是心脏，但长会话工程才是循环能活得久的器官系统。

1. 为什么需要“长会话工程”这个视角

如果系统只回答一次简单问题，那这些机制很多都不重要。

但 Claude Code 要处理的是：

  • 多轮对话
  • 大量 tool call
  • 子 agent / fork / remote agent
  • 长时间运行的 shell / monitor
  • 可能中途 background 化的任务
  • 用户随时插入新消息
  • token / context window /缓存成本约束

一旦系统目标变成“持续运行的工程型 agent”，关注点就会从“这次调用对不对”变成：

  • 上下文怎么活得久
  • 输出怎么不丢
  • 后台任务怎么回流
  • 阻塞怎么解耦
  • 失败怎么不把整轮对话打死
  • token 成本怎么不爆炸

所以这里的核心问题不再只是功能，而是可持续运行性。

2. 第一根主骨架：query() 统一循环

Claude Code 的大前提始终没变：

  • 主 agent 走 query()
  • 子 agent 也走 query()
  • 后台任务完成后，最终仍回到 query()

这意味着长会话工程不是另起一套 runtime，而是围绕同一个主循环，增加各种：

  • 前缀稳定性约束
  • 回流协议
  • 生命周期壳
  • 结果缓冲层

所以更准确的说法是：

Claude Code 不是“一个循环 + 一堆外挂”，而是“一个循环 + 一套使其长期可持续运行的横切补偿机制”。

3. prompt cache：为长会话降成本的前缀稳定工程

Prompt cache 设计 已经说明：Claude Code 很在意 cache-critical prefix 的字节稳定性。

这会反过来影响很多架构决策：

  • fork child 尽量继承父 renderedSystemPrompt
  • 工具集合强调排序稳定
  • useExactTools 避免工具池重组
  • replacement state 倾向 clone 而不是 fresh
  • 差异尽量压到前缀末尾

这套设计的意义不只是“快一点”，而是：

在多轮、多 agent、长上下文场景下，不让每一轮都从零烧 token。

所以 prompt cache 在这里属于基础设施，而不是小优化。

4. Task 系统：为长时任务提供生命周期壳

Task 系统总览 已经确认：

  • runAgent() 负责执行
  • Task 层负责生命周期

这里的 Task 并不是附属 UI 状态，而是长会话工程的关键层。它承接的是：

  • 后台 agent
  • remote agent
  • shell / monitor
  • progress
  • output file
  • kill / completion / failure
  • 恢复与通知

也就是说，Task 层回答的是：

一个还没结束、但已经脱离当前 tool call 的执行体，如何继续被系统管理？

这正是长会话系统必须有的中间层。

5. foreground → background：把阻塞从当前调用栈里拆出去

这条机制在 agent 和 shell 两边都成立，只是 execution shell 不同。

agent 侧

foreground 到 background 热切换机制 说明：

  • sync agent 一开始就注册成可背景化 task
  • 真切后台时，不是简单改 flag
  • 而是结束 foreground iterator，再重启 async lifecycle

shell 侧

ShellCommand TaskOutput LocalShellTask 后台执行模型 说明：

  • 前台 shell 由 BashTool inline 消费
  • 后台化时，不重跑命令
  • 而是把同一个 shellCommand 的 ownership 移交给 LocalShellTask

两者共同点很清楚：

Claude Code 遇到长时阻塞，不是“卡死当前 turn”，而是把执行体迁移到后台生命周期壳里，让主循环继续保持响应。

这就是长会话工程最核心的 responsiveness 机制之一。

6. task-notification 回流：让后台世界重新进入主对话

后台任务如果只是默默跑完，系统其实并没有真正“闭环”。

Claude Code 的做法是统一回流：

  • LocalAgentTask 终态发 notification
  • RemoteAgentTask 终态发 notification
  • LocalShellTask 终态发 notification
  • shell stalled prompt 也能发 statusless notification

然后：

  • messageQueueManager 入队
  • query.ts turn 尾 drain
  • attachments.ts 转 queued_command
  • messages.ts 再包装成 reminder 风格 user message
  • 下一轮模型真正看到它

所以长会话工程的关键不是后台任务本身，而是：

后台执行结果如何重新变成主循环可消费的上下文。

没有这一层，后台只会变成黑洞。

7. output file / TaskOutput：让长时输出有稳定落点

长会话里另一个现实问题是：

  • 输出可能很长
  • 执行可能很久
  • 当前 turn 不一定等得完
  • UI / 模型 / tools 可能在不同时间读取同一份结果

TaskOutput 解决的是这个问题。

它提供：

  • file mode / pipe mode 统一输出账本
  • 小输出 inline，大输出给路径
  • shared poller 提供 progress
  • background shell 的 watchdog 防爆盘
  • 输出文件成为 UI、Read tool、task-notification 共用的事实源

这让 Claude Code 的长会话输出不是 ephemeral stream，而是：

可复读、可回流、可延后读取、可供多层消费的持久化对象。

8. 失败与异常不一定抛给用户，而是优先内部收口

目前已确认的设计里，能看到明显的“先内部消化”的倾向：

  • shell interrupt 不直接 kill，优先给后台化机会
  • shell stalled prompt 先发中间事件，而不是误关任务
  • 后台化与完成抢跑时，会修补竞态，避免双重结果
  • output file 丢失时，不静默空返回，而是生成 diagnostic 文本，避免模型被误导
  • shell cleanup 会显式拆 listener / child / abort 引用，避免后续微任务崩溃与泄漏

这说明系统的目标不是“任何异常都冒泡”，而是：

先把长会话维持住，再尽量把异常转成可理解、可恢复的结构化信息。

这正是工程型 agent 和 demo 型 agent 的分水岭之一。

9. shell / agent / remote 的“中间执行壳”不同，但横切协议在收敛

中间执行层其实并不统一：

  • local sync agent 走 runAgent() inline
  • local async agent 走 LocalAgentTask
  • remote agent 走 remote session + polling
  • shell 走 ShellCommand + LocalShellTask

但它们在长会话工程上的协议正在收敛：

  • 都会进入 task 系统或 task-like 管理层
  • 都有 output file / transcript 路径
  • 都会发 task-notification
  • 都会在 turn 尾部重新进入主循环

所以这套系统不是“执行引擎统一”，而是：

执行中层各不相同，但长会话治理协议越来越统一。

10. 用这个视角重看 Claude Code 架构

如果只看 Claude Code 架构总览，会得到一张经典图：

  • QueryEngine
  • query
  • Tool
  • AgentTool
  • Task

但加上长会话工程视角后，会更接近下面这个理解：

核心心脏

  • query() 主循环

成本控制

  • prompt cache 稳定性
  • 未来还应继续补压缩流水线

生命周期治理

  • Task 系统
  • foreground/background 切换
  • remote / local / shell 的后台托管

结果回流

  • task-notification
  • queue
  • attachment
  • next query context

输出持久化

  • output file
  • transcript symlink
  • TaskOutput

韧性机制

  • interrupt 不粗暴 kill
  • stalled prompt 识别
  • 竞态修补
  • cleanup ownership 明确化

所以这不再只是“模块图”，而是一张持续运行系统图。

当前仍待补的部分

这页目前仍是不完整总图，至少还缺：

  • 上下文压缩流水线的源码级落点
  • QueryEngine / query 层的失败恢复与重试路径
  • memory / skills / plan mode 在长会话中的真正作用
  • print / UI / collapse 层如何帮助用户承受长时任务噪音

但就当前已确认部分，至少可以先稳定地说：

Claude Code 的产品级完成度，来自一组围绕“长会话持续运行”构建的横切工程能力，而不只是 tool call 数量。

与其他页面的关系

关系图谱

反向链接