第 7 章：状态管理

在开发智能体（Agent）系统时，最常见的误区之一就是混淆“状态（State）”与“对话历史（Conversation History）”。这种混淆往往会导致系统架构在中后期付出巨大的修复代价。

设想这样一个场景：用户关闭了终端，一小时后重新打开。对话历史完整无损——每一条消息、每一次工具调用、每一条响应都在。然而，智能体却“失忆”了：它不知道自己修改了哪些文件，不记得用户曾授予过哪些权限，对之前后台运行的三个任务一无所知。用户偏好的冗长输出设置重置了，预先缓存的代码库分析结果也烟消云散。

消息（Messages）记录的是“说了什么”，而状态（State）记录的是“现在什么是事实”。 这种本质上的区别决定了它们需要完全不同的处理逻辑。

核心区别：为什么必须区分？

我们可以把对话比作商务会议的纪要（Transcript）。纪要详细记录了讨论过程：提出了什么建议、听取了哪些论点、达成了什么决策。但纪要本身并不等同于公司的“现状”。要了解公司现状，你需要查阅独立的记录——组织架构图、财务预算、项目状态仪表盘。

• 消息是“纪要”：它是追加式的（Append-only），永远不会被编辑，只会不断增加。它捕捉的是对话的流动和推理逻辑。
• 状态是“仪表盘”：它是可变的（Mutable），随情况变化而更新。它捕捉的是运行时的真相：当前有哪些权限、哪些进程在运行、用户进行了哪些配置。

两者都需要追踪，但策略不同。消息被发送给大语言模型（LLM）以维持上下文；状态则确保应用程序的功能正常运行。模型通常不需要关心用户是否在 macOS 的深色模式下运行，但你的 UI 组件必须关心。

一个简单的判断标准：如果你清空了所有对话历史并重新开始，为了保证系统继续运转，哪些信息是必须保留的？那就是状态。

状态需要追踪什么？

一个成熟的智能体系统通常需要维护以下几类状态：

• 任务（Tasks）：后台进程，如正在运行的测试套件、启动的服务、构建任务及其状态、输出和进程 ID（PID）。
• 权限（Permissions）：用户允许或拒绝的操作。例如，“允许修改 /src 下的文件”或“禁止运行 npm 命令”这类授权必须持久化。
• 设置（Settings）：塑造行为的用户偏好，包括模型选择、输出详细程度、自主权级别等。
• 会话（Session）：连接健康状况、身份验证状态、Token 过期时间、在线/离线状态。
• UI 状态：界面交互细节，如折叠的区块、滚动位置、哪些工具输出被展开了。
• 上下文（Context）：关于环境的缓存信息，如之前读取的文件内容、计划执行进度、已验证的假设。

以权限管理为例：如果没有持久化的权限状态，智能体每次操作都会变成复读机。“我可以修改 /src 吗？”“可以。”（执行修改）。“我可以修改 /src 吗？”“可以。”（再次执行）。这种体验很快就会让用户失去耐心。

提示：优秀的权限管理也应记录“拒绝”。如果用户拒绝了某项操作，短时间内再次询问会被视为一种骚扰。

外部存储模式（The External Store Pattern）

初级的实现通常将状态散落在各个模块中：这个模块管权限，那个模块管任务。这种做法在需要跨会话持久化、组件间同步或调试状态异常时会出现灾难。

更好的方案是借鉴前端框架中常见的中央状态管理模式。

其核心原则包括：

1. 单一事实来源：所有状态集中存储，查询状态只需访问一个地方，无需遍历各个模块的私有变量。
2. 基于订阅的更新：组件只关注其需要的状态切片。任务列表订阅 state.tasks，权限检查器订阅 state.permissions。更新设置不会导致任务列表重绘。
3. 不可变更新（Immutable Updates）：不直接修改对象，而是创建包含更新内容的新对象。这使得状态变化可追溯，并支持撤销操作。
4. 选择器（Selector）机制：通过函数精确提取所需数据，保持接口简洁。

这种模式让状态更新变得显式且可追踪。当系统出现异常时，通过检查存储器（Store）就能一眼看清当前的“真相”。

持久化：即发即弃与顺序写入

内存中的状态会随程序关闭而消失。对于生产级系统，这通常是不可接受的。用户希望关闭终端后，第二天回来能无缝衔接。

然而，同步持久化会带来性能问题：如果每次状态变更都阻塞在磁盘 I/O 上，UI 会变得卡顿。

解决方案是：即发即弃（Fire-and-Forget）与顺序写入（Ordered Writes）。

• 即发即弃：发起写入操作后立即继续执行后续逻辑。写入在后台异步完成。
• 顺序写入：虽然是异步执行，但必须保证写入顺序。通过写入队列确保第二次状态变更不会覆盖第一次还在处理中的写入，避免竞态条件。

警告：持久化失败不应导致应用崩溃。记录错误并继续运行，保证用户当前的交互体验优于数据的绝对实时同步。

记录模式（The Transcript Pattern）

对于对话消息，一种专门的持久化方式是 追加式记录（Append-only Transcript）。

不再存储当前的“最终状态”，而是顺序列出发生的所有事件。这种方式类似于数据库的“事件溯源（Event Sourcing）”。 其优势在于：

• 故障恢复：崩溃后回放记录即可还原现场。
• 调试友好：逐步回放以理解失败原因。
• 安全审计：为敏感操作提供不可篡改的证据。

会话恢复（Session Restore）

会话恢复是衡量一个智能体系统是否具备“生产力”的关键指标。

当用户在一小时后重新打开终端：

1. 检测前次会话：检查是否存在未过期的会话文件。
2. 验证时效性：判断会话是否过旧。两小时前的会话值得恢复，半年前的可能就不必了。
3. 处理被中断的轮次：如果用户在智能体响应中途关闭了程序，需要检测到这种不完整的状态，并决定是丢弃还是提示用户如何处理。
4. 选择性恢复：
   • 消息：通常需要恢复，但可提供“开启新对话”的选择。
   • 权限：恢复已授权限，对高风险权限可考虑重新验证。
   • 任务：检查相关进程是否还在运行（通常已经终止）。
   • 文件缓存：验证磁盘文件是否发生变动以决定缓存是否失效。

配置分层机制

智能体的设置通常来源广泛。建立清晰的优先级（Precedence）至关重要：

1. 命令行参数（最高优先级）：--model gpt-4
2. 环境变量：AGENT_MODEL=gpt-4
3. 项目配置：.agent/config.json
4. 用户全局配置：~/.config/agent/settings.json
5. 托管/组织配置：公司统一下发的默认值
6. 硬编码默认值（最低优先级）：当没有其他来源提供值时，使用默认值。

这种层级结构确保了灵活性：用户可以通过命令行临时覆盖所有设置，也可以通过项目配置文件为特定的代码库定制行为。

UI 集成与同步

如果智能体有 UI（如 React 或桌面端），状态管理的效率直接决定了用户体验。

• Context API：使状态在组件树中全局可用。
• 自定义 Hooks：实现高效的按需订阅。
• 稳定引用（Memoization）：防止因状态无关变更导致的无效重绘。

目标是最小化重绘：只更新发生变化的组件。在实时更新的复杂界面中，优秀的状态管理能让交互感觉顺滑。

综合应用

让我们追踪一个真实场景：用户输入“在后台运行测试，完成后告诉我”。

1. 消息记录：该请求被追加到对话历史中。
2. 状态更新：智能体在 Store 中创建一个任务条目，状态为 running，记录 PID。
3. 持久化与 UI 更新：任务状态异步写入磁盘，UI 立即显示任务进度条。
4. 异步完成：测试完成，任务状态更新为 completed。再次触发磁盘写入和 UI 变化。
5. 会话恢复：用户关闭并重启后，系统加载持久化状态。虽然测试进程已结束，但智能体依然能准确告知用户上一次测试的结果和输出。

当状态管理得当时，它是隐形的。权限被记住，任务被追踪，设置被持久化。系统就这样正常运转。

当它失效时，用户面临的是持续的摩擦：反复授权、丢失进度、与无法生效的配置抗争。

消息是用户看到的对话。状态是确保系统在对话之间正常运行的底层事实。