@@ -7,17 +7,17 @@ import { Tab, Tabs } from '@rspress/core/theme';
77
88# 持久化
99
10- 持久化让 session 可以跨进程恢复，也让产品界面拥有稳定 session ID 。
10+ 持久化让会话可以跨进程恢复，也让产品界面拥有稳定的会话标识 。
1111
12- 恢复后的 Session 可以重新填充任务列表 、执行记录、Artifact 和交付摘要 ，不必重放已经完成的运行。
12+ 恢复后的会话可以重新填充任务列表 、执行记录、制品和交付摘要 ，不必重放已经完成的运行。
1313
1414A3S Code 会持久化三种相关但不同的对象：
1515
16- | 对象 | 写入方 | 恢复入口 | 用途 |
17- | ------------------- | ------------------------------------ | -------------------------------------- | ------------------------------- -------------------------------------------------------------------------------------------- |
18- | ` SessionSnapshotV1 ` | ` session.save() ` 或 ` autoSave ` | ` agent.resumeSession(id, options) ` | 恢复一个带版本的完整 generation ，其中包含对话、artifact、trace、run record、verification report 与 subagent task snapshot 。 |
19- | Loop checkpoint | run 执行中的 agent loop | ` session.resumeRun(runId) ` | 从上一个完成的 tool-round 边界继续一次被中断的 run。进程内正常完成的 run 会删除这个 checkpoint。 |
20- | Workflow checkpoint | ` parallelResumable ` / workflow phase | ` parallelResumable(specs, workflowId) ` | 进程重启后跳过已经完成的编排 step。 |
16+ | 对象 | 写入方 | 恢复入口 | 用途 |
17+ | ------------------- | -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------- |
18+ | ` SessionSnapshotV1 ` | ` session.save() ` 或 ` autoSave ` | ` agent.resumeSession(id, options) ` | 恢复一个带版本号的完整代次 ，其中包含对话、制品、追踪、运行记录、验证报告与子智能体任务快照 。 |
19+ | 循环检查点 | 智能体循环运行期间 | ` session.resumeRun(runId) ` | 从上一个完成的工具回合边界继续被中断的运行。进程内正常完成的运行会删除这个检查点。 |
20+ | 工作流检查点 | ` parallelResumable ` / 工作流阶段 | ` parallelResumable(specs, workflowId) ` | 进程重启后跳过已经完成的编排步骤。 |
2121
2222## 文件会话存储
2323
@@ -78,34 +78,33 @@ if err := session.Save(ctx); err != nil {
7878</Tab >
7979</Tabs >
8080
81- Go 通过 ` FileSessionStoreDir ` 选择内置文件 Store ；自定义 ` SessionStore ` Trait
82- 实现仍属于 Rust embedding 能力 。
81+ Go 通过 ` FileSessionStoreDir ` 选择内置文件存储 ；自定义 ` SessionStore ` trait
82+ 实现仍属于 Rust 嵌入能力 。
8383
8484## 原子快照代次
8585
8686` session.save() ` 会把当前持久化状态收集成一个 ` SessionSnapshotV1 ` ，并且只调用一次
87- ` SessionStore::save_snapshot ` 。Envelope 包含 ：
87+ ` SessionStore::save_snapshot ` 。信封包含 ：
8888
8989- ` schema_version ` 与 ` SessionData `
90- - tool artifact
91- - trace event 与 run record
92- - verification report
93- - delegated subagent task snapshot
94-
95- File store 会把完整 JSON envelope 写入并同步临时文件，然后 atomic replace
96- ` <session-id>.json ` 。因此 reader 看到的是上一代或下一代，不会读到“新 conversation
97- 搭配旧 run/trace fragment”的组合。Memory store 在同一把锁下发布同一个 aggregate。
98- 两者都报告 ` SessionStoreCapabilities { atomic_session_snapshots: true } ` 。
99-
100- 历史文件仍可读取。Bare ` SessionData ` 会在 load 时与旧 artifact/trace/run/
101- verification/subagent fragment location 合并，再通过 v1 内存形状恢复。新 aggregate
102- 保存后，单个 envelope 成为 authoritative generation。已经具有 aggregate 外形、但
103- schema 损坏或版本不支持的文档会直接被拒绝，不会重新解释成 legacy data。
104-
105- 自定义 store 必须显式实现 ` save_snapshot ` 。默认实现返回错误，不会把 aggregate
106- 拆成多次独立 write，也不会把 no-op 当成成功。默认 ` load_snapshot ` 只用于
107- best-effort legacy assembly；宿主可以通过 ` capabilities() ` 区分这种行为与 atomic
108- backend。
90+ - 工具制品
91+ - 追踪事件与运行记录
92+ - 验证报告
93+ - 委派的子智能体任务快照
94+
95+ 文件存储会把完整 JSON 信封写入并同步临时文件，然后原子替换
96+ ` <session-id>.json ` 。因此读取方看到的是上一代或下一代，不会读到“新对话搭配旧
97+ 运行或追踪分片”的组合。内存存储在同一把锁下发布同一个聚合快照。两者都报告
98+ ` SessionStoreCapabilities { atomic_session_snapshots: true } ` 。
99+
100+ 历史文件仍可读取。裸 ` SessionData ` 会在加载时与旧制品、追踪、运行、验证和
101+ 子智能体分片位置合并，再通过 v1 内存形状恢复。保存新聚合快照后，单个信封会成为
102+ 权威代次。已经具有聚合外形、但模式损坏或版本不支持的文档会直接被拒绝，不会重新
103+ 解释成旧式数据。
104+
105+ 自定义存储必须显式实现 ` save_snapshot ` 。默认实现返回错误，不会把聚合快照拆成
106+ 多次独立写入，也不会把空操作当成成功。默认 ` load_snapshot ` 只用于尽力组装旧式
107+ 数据；宿主可以通过 ` capabilities() ` 区分这种行为与原子后端。
109108
110109## 恢复
111110
@@ -139,33 +138,32 @@ resumed, err := agent.ResumeSession(ctx, "release-review", &code.SessionOptions{
139138</Tab >
140139</Tabs >
141140
142- ` resumeSession ` 恢复的是已保存的 session snapshot。它不同于
143- ` resumeRun ` ：用户继续一个已保存对话时用 ` resumeSession ` ；只有存在中断 run 的
144- checkpoint 时，才用 ` resumeRun(runId) ` 。Resume 会在恢复任何 history 或 runtime
145- evidence 前先校验 snapshot schema。
141+ ` resumeSession ` 恢复的是已保存的会话快照。它不同于 ` resumeRun ` ：用户继续一个
142+ 已保存对话时用 ` resumeSession ` ；只有存在中断运行的检查点时，才用
143+ ` resumeRun(runId) ` 。恢复操作会在恢复任何历史或运行时证据前先校验快照模式。
146144
147145## 记忆与会话
148146
149- Session 持久化保存对话和可回放证据；memory 保存可复用任务事实 。当你需要既可
147+ 会话持久化保存对话和可回放证据；记忆保存可复用任务事实 。当你需要既可
150148恢复、又能从重复任务中学习的工作流时，两者一起使用。
151149
152150## 循环检查点与运行恢复
153151
154- 配置了 ` SessionStore ` 后，agent loop 会在每个完成的 tool round 之后持久化一个
155- ` LoopCheckpoint ` 。边界策略很严格：checkpoint ** 只** 在 tool round 之间产生，
156- 绝不在 tool 执行中途。如果进程在某个 tool 执行时崩溃，那一轮的工作会在 resume
157- 时丢失，由 LLM 从上一个 checkpoint 重新推演——在边界错误的一侧重跑一个非幂等
158- tool（write、bash）比让 LLM 重新提问更糟 。
152+ 配置了 ` SessionStore ` 后，智能体循环会在每个完成的工具回合之后持久化一个
153+ ` LoopCheckpoint ` 。边界策略很严格：检查点 ** 只** 在工具回合之间产生，绝不在工具
154+ 执行中途产生。如果进程在某个工具执行时崩溃，那一轮的工作会在恢复时丢失，由
155+ 大语言模型从上一个检查点重新推演——在错误边界一侧重跑非幂等工具（写入、命令行）
156+ 比让模型重新思考更糟 。
159157
160158` session.resumeRun(runId) ` （Node）/ ` session.resume_run(run_id) ` （Python）——
161- 对应 core 的 ` AgentSession::resume_run(checkpoint_run_id) ` ——会加载该 run ID 下
162- 最新的 checkpoint，并从最后一个边界回放 loop。由于 checkpoint 存放在共享 store
163- 中，resume 可以发生在 ** 任何** 共享该 store 的节点上。累计计量会延续而不是从零
164- 重启： ` total_usage ` 和 ` tool_calls_count ` 从 checkpoint 继续累加。resume 出来的
165- 工作会分配一个新的 run ID；新旧 run 的关系是宿主元数据 ，框架不予解释。
159+ 对应核心的 ` AgentSession::resume_run(checkpoint_run_id) ` ——会加载该运行标识下
160+ 最新的检查点，并从最后一个边界回放循环。由于检查点存放在共享存储中，恢复可以
161+ 发生在 ** 任何** 共享该存储的节点上。累计计量会延续而不是从零重启： ` total_usage `
162+ 和 ` tool_calls_count ` 从检查点继续累加。恢复出的工作会分配新的运行标识；新旧运行
163+ 的关系由宿主通过元数据表达 ，框架不予解释。
166164
167- 已正常完成的 run 不通过 ` resumeRun ` 恢复；它们的最终状态应通过 ` runs() ` 、
168- ` runEvents(runId) ` 、artifacts、verification reports 和 session snapshot 查看 。
165+ 已正常完成的运行不通过 ` resumeRun ` 恢复；它们的最终状态应通过 ` runs() ` 、
166+ ` runEvents(runId) ` 、制品、验证报告和会话快照查看 。
169167
170168``` ts
171169const = await session .resumeRun (' run-abc123'
@@ -177,45 +175,45 @@ result = session.resume_run('run-abc123')
177175print (result.total_tokens)
178176```
179177
180- 当前 Go 桥接层提供 Snapshot ` Save ` / ` ResumeSession ` 、Run 记录和事件回放，但还
181- 没有 ` resumeRun ` Loop Checkpoint 操作或 Workflow Checkpoint 编排 。本文只在 Go
182- Surface 确实提供对应操作的位置展示 Go Tab 。
178+ 当前 Go 桥接层提供快照 ` Save ` / ` ResumeSession ` 、运行记录和事件回放，但还没有
179+ ` resumeRun ` 循环检查点操作或工作流检查点编排 。本文只在 Go 接口确实提供对应操作的
180+ 位置展示 Go 标签页 。
183181
184- 当 session 没有配置 ` sessionStore ` （或给定 ID 下不存在 checkpoint ）时，
182+ 当会话没有配置 ` sessionStore ` （或给定标识下不存在检查点 ）时，
185183` resume_run ` 会拒绝。` SessionStore ` 新增了 ` save_loop_checkpoint ` /
186- ` load_loop_checkpoint ` / ` delete_loop_checkpoint ` ；file store 的写入是
187- crash-atomic 的 。` LoopCheckpoint::ensure_loadable() ` 在反序列化之后立即被调用，
188- 会拒绝来自未来的、不兼容 schema 版本的 checkpoint ，因此 ` resume_run ` 和实时
189- run 的 sink 都不会对一个无法读取的 checkpoint 采取行动 。
184+ ` load_loop_checkpoint ` / ` delete_loop_checkpoint ` ；文件存储采用崩溃安全的原子
185+ 写入 。` LoopCheckpoint::ensure_loadable() ` 在反序列化之后立即被调用，会拒绝
186+ 来自未来且不兼容的检查点模式版本 ，因此 ` resume_run ` 和实时运行的接收端都不会
187+ 对无法读取的检查点采取行动 。
190188
191189参见 CHANGELOG ` [3.3.0] ` ——"Loop checkpoints + run resumption"——以及
192190` [3.4.0] ` 的 "LoopCheckpoint::ensure_loadable()"。
193191
194192## 工作流检查点
195193
196- ` WorkflowCheckpoint ` 是 tool-round ` LoopCheckpoint ` 在上一层的 step 边界对应物 ：
197- 它把已完成的编排 step 记入日志 ，使被中断的工作流从最长的已完成前缀恢复。它的
198- 字段是 ` schema_version ` 、` workflow_id ` 、` steps ` 和 ` checkpoint_ms ` ，schema 由
199- ` WORKFLOW_CHECKPOINT_SCHEMA_VERSION ` 常量固定。恢复的 run 会跳过已记录的 step ，
194+ ` WorkflowCheckpoint ` 是工具回合 ` LoopCheckpoint ` 在上一层的步骤边界对应物 ：
195+ 它把已完成的编排步骤记入日志 ，使被中断的工作流从最长的已完成前缀恢复。它的
196+ 字段是 ` schema_version ` 、` workflow_id ` 、` steps ` 和 ` checkpoint_ms ` ，模式由
197+ ` WORKFLOW_CHECKPOINT_SCHEMA_VERSION ` 常量固定。恢复的运行会跳过已记录的步骤 ，
200198只重新派发其余的。
201199
202200` SessionStore ` 新增了 ` save_workflow_checkpoint ` / ` load_workflow_checkpoint ` /
203- ` delete_workflow_checkpoint ` （默认 no-op；file store 以 crash-atomic 方式写入 ）。
204- 来自未来的、不兼容 schema 版本的加载会通过
201+ ` delete_workflow_checkpoint ` （默认为空操作；文件存储采用崩溃安全的原子写入 ）。
202+ 来自未来且不兼容的模式版本会在加载时通过
205203` WorkflowCheckpoint::ensure_loadable() ` 被拒绝。
206204
207205这与编排语法配套使用——参见
208- [ Orchestration ] ( /guide/orchestration ) 和
209- [ Multi-Machine ] ( /guide/multi-machine ) 。
206+ [ 编排 ] ( /guide/orchestration ) 和
207+ [ 多机执行 ] ( /guide/multi-machine ) 。
210208
211209参见 CHANGELOG ` [3.4.0] ` ——"WorkflowCheckpoint"。
212210
213211## 在其他节点恢复
214212
215- 两种 checkpoint 类型都是可序列化的 。配合共享的 ` SessionStore ` 和可插拔的
216- executor，宿主就能在与启动节点 ** 不同** 的节点上恢复被中断的 run 或工作流——
217- 框架持有可序列化的契约，宿主持有放置（placement）与传输（transport） 。
213+ 两种检查点类型都是可序列化的 。配合共享的 ` SessionStore ` 和可插拔执行器，宿主
214+ 就能在与启动节点 ** 不同** 的节点上恢复被中断的运行或工作流——框架持有可序列化
215+ 契约，宿主负责放置与传输 。
218216
219217## 运维注意事项
220218
221- 包含私有 prompt、tool output 或路径的 store 不应公开提交 。
219+ 包含私有提示词、工具输出或路径的存储不应公开提交 。
0 commit comments