这在演示视频里成立，在真实表格里很难成立。

用户可能表达含糊，表格结构可能不规范，模型也可能选错工具。与其追求永不出错，不如先把系统做成：错误可见、过程可查、结果可恢复。

这也是传统软件工程比“调提示词”更有用的地方。

Undo 只能解决一步，Agent 往往走了十步

假设用户说：

按区域汇总销售额，新增一张分析表，再生成柱状图。

Agent 可能依次执行：

1. 读取数据区域；

2. 识别区域列和销售额列；

3. 新建工作表；

4. 写入汇总表头；

5. 写入区域数据；

6. 写入聚合结果；

7. 设置数字格式；

8. 创建图表；

9. 调整图表位置。

如果第 8 步失败，只撤销最后一步没什么用。用户需要的是回到任务开始前，或者保留前 7 步后换一种图表方案。

所以 Agent 需要两种恢复能力：

• 操作级撤销：撤销一个工具产生的变更；

• 任务级快照：恢复到整段任务开始前。

SpreadJS 的自定义命令可以通过 startTransaction、endTransaction 和 undoTransaction 把一组变更纳入撤销机制。工作簿级状态则可以用 toJSON() 保存、用 fromJSON() 恢复。

快照不应该只有“保存”和“恢复”

真正好用的快照至少要带元数据：

{
  "snapshotId": "snap_20260729_103512",
  "taskId": "task_1842",
  "createdAt": "2026-07-29T10:35:12+08:00",
  "reason": "before_high_risk_execution",
  "activeSheet": "销售明细",
  "userRequest": "生成区域销售分析和柱状图"
}

这样出了问题才能知道：

• 这是哪个任务的快照；

• 为什么创建；

• 恢复后会回到什么位置；

• 对应哪条用户指令。

对于大工作簿，快照还要考虑大小和频率。一个实用策略是：

• 低风险只记录可撤销命令；

• 多步骤任务开始时做一次全量快照；

• 高风险步骤前追加关键快照；

• 任务成功后按策略清理；

• 失败和用户终止时保留。

“终止”按钮必须真的能终止

很多 Agent 界面有停止按钮，但它只停止了前端的加载动画，后台请求和工具仍在继续。

对于会修改表格的 Agent，终止至少要处理三件事：

1. 不再发起新的模型请求；

2. 取消或忽略尚未执行的工具；

3. 让用户选择保留当前结果，或恢复到任务前快照。

这里会遇到一个工程细节：已经开始的浏览器端同步操作可能无法从中间打断。因此工具要尽量保持小而有边界，批量操作也应在执行前完成范围校验，避免进入一个不可控的长任务。

会话分支不是聊天产品的花活

假设 Agent 已经生成了一张销售分析表，用户觉得结果基本正确，只是不喜欢图表。

如果直接重新提问，模型可能把前面的汇总逻辑也改了。更好的方式是从“汇总完成、图表未创建”的节点分支：

任务开始
  -> 数据读取
  -> 汇总完成
      -> 分支 A：柱状图
      -> 分支 B：折线图
      -> 分支 C：不创建图表

分支背后需要的不只是聊天消息，还包括当时的工作簿快照、工具状态和任务状态。否则界面看起来回到了旧对话，表格却还停留在新状态。

这类问题说明，Agent 的会话不是纯文本历史，而是“消息 + 工具调用 + 外部状态”的组合。

没有调试台，问题最后都会怪到模型头上

表格 Agent 出错时，常见反馈是“模型不稳定”。但拆开后，问题可能出在任何一层：

• 上下文没有带当前选区；

• 工具参数描述不清；

• 地址转换多了一行；

• 合并单元格处理错误；

• 受保护区域导致部分写入失败；

• 工具返回结果过于简略，模型误以为执行成功。

一个实用的调试台至少要看到：

当前任务状态
当前可用工具
模型原始工具调用
参数校验结果
工具开始/结束时间
实际影响范围
执行前后摘要
异常堆栈
关联快照

还应该允许开发者不经过模型，直接选择某个工具、填写参数并执行。

如果 setRangeStyle 直接执行也失败，那就先修工具；如果直接执行成功、模型总是传错参数，再优化工具描述和上下文。两类问题的处理方式完全不同。

可恢复性，才是 Agent 的产品信任

用户不要求软件永远不出错。编辑器会崩，网络会断，人也会误操作。大家真正依赖的是自动保存、撤销、版本历史和恢复。

AI Agent 也一样。

当系统能清楚告诉用户“我改了哪些区域”，能在失败时恢复，能从中间节点尝试另一条路径，用户才敢把更重要的任务交给它。

相比再调一版提示词，快照、事务、分支和调试日志显得很笨重。但恰恰是这些东西，把一次聪明的表演变成了可以长期使用的工具。

SpreadJS AI Agent 实战的最后一部分会把快照、回滚、会话分支和工具调试串起来，重点不是“如何让模型永远正确”，而是如何让一次不正确的执行仍然处于工程可控范围内。

想把这套方案真正跑起来

快照、回滚和会话分支不是附加功能，而是用户敢不敢把真实工作簿交给 Agent 的基础。课程最后一部分会把工作簿快照、终止并还原、任务持久化、会话分支和工具调试串成完整流程。

课程《从0到1掌握企业级表格 Agent 搭建》基于公开的 SpreadJS AI Agent 项目，共 7 节，每节约 20 分钟，从整体架构一路讲到安全确认、快照回滚和调试体系。