09. 状态与可观测性¶
Claude Code 的状态分为运行状态、应用状态和持久化状态。运行状态服务于当前查询循环，例如当前消息列表、中断控制器、用量、已发现技能、已读文件缓存、权限拒绝和工具调用跟踪。应用状态服务于整个客户端，例如设置、权限上下文、MCP 客户端、智能体定义、待办事项、任务、通知、文件历史、界面回调和远端桥接信息。持久化状态写入转录记录，用于恢复、分叉、审计和压缩。
应用状态是入口、界面和运行时之间的共享界面。工具执行时需要读写待办事项、任务状态、MCP 状态、通知和文件历史，但工具代码不应直接依赖某个界面组件。因此工具使用上下文会携带应用状态读写、进度回调、文件历史更新、JSX 渲染回调、权限请求回调等能力。工具执行结果既能反馈给模型，也能同步更新界面。
转录记录是最重要的可恢复日志。它通常以 JSONL 形式写入会话目录，每条用户消息、助手消息、附件、系统事件或压缩边界都有自己的记录。写入不是简单追加字符串：运行时会维护父级 uuid、去重、批量写入队列、待写条目、压缩边界和删除标记。进度消息一般属于界面临时状态，不一定作为可恢复消息保存；真正影响会话语义的内容才进入转录主链。
查询引擎会尽早写用户消息，并在流式过程中持续记录助手输出和工具结果。这样做让会话具备崩溃恢复能力。即使进程在一次 API 请求中断，恢复也能看到用户刚刚提交了什么，已经产生了哪些工具调用或结果，哪些分支被压缩或删除标记。对于子智能体，系统会写入独立转录记录，同时保留与父会话的关系。
压缩对状态也有强影响。压缩会插入边界标记，记录摘要消息，并把被压缩前后需要保留的材料重新整理成附件。恢复时，运行时会根据边界和保留片段规则重建主线，而不是把被压缩的旧历史全部重新喂给模型。这样转录记录可以完整保留审计信息，但模型输入只使用压缩后的有效上下文。
可观测性还包括用量、请求 id、流式事件、工具进度、钩子结果和错误恢复。模型 API 层会记录每次请求的用量、停止原因、备用模型和错误类型；工具层会记录权限拒绝、钩子阻塞、输出截断、MCP 认证失败等状态；入口层会把这些事件转成界面展示或 SDK 返回值。对用户来说，这是进度条、工具卡片和最终结果；对运行时来说，这是继续循环、恢复会话和诊断问题的依据。
| 事件或状态 | 主要用途 | 是否影响恢复 |
|---|---|---|
| 流式文本增量 | 实时展示 | 通常不直接影响 |
| 完整助手消息 | 历史和后续采样 | 影响 |
| 工具开始/进度 | 展示工具状态 | 通常不直接影响 |
| 工具结果 | 后续采样和恢复 | 影响 |
| 压缩边界 | 重建有效历史 | 影响 |
| 权限拒绝 | 模型调整方案 | 影响 |
状态章节把前面几章串起来：入口产生会话状态，查询循环更新运行状态，工具和权限产生事件，压缩和恢复依赖持久化状态。下一章会说明新增能力时应沿这些边界接入。