改了一版提示词，拿三个例子试了试，全部成功。大家觉得“这版明显稳定了”，于是发布。

一周后，用户反馈排序错列、公式覆盖、图表选错数据源。团队再改一轮提示词，又拿那三个熟悉的例子测试。

这不叫优化，叫循环制造错觉。

表格 Agent 的成功不能只看最终回答

普通问答可以比较答案文本。表格 Agent 的结果是工作簿状态，评测维度要多得多：

• 是否选择了正确工具；
• 参数中的工作表和区域是否正确；
• 是否修改了不该修改的单元格；
• 公式是否正确；
• 样式是否符合要求；
• 是否触发了必要确认；
• 失败后是否保持原状态；
• 总调用步数是否合理。

同样一句“完成了”，背后可能是正确修改，也可能只是模型自信地总结了一次失败。

从真实任务建立最小评测集

不要一开始追求几千条测试。先收集 30 到 50 个高频任务：

给当前选区加边框
按销售额降序排列
在最后一列计算毛利率
删除空白工作表
把已有公式区域整体向下扩展
生成月度趋势图

每个案例保存四样东西：

1. 初始工作簿快照；
2. 用户指令；
3. 允许的工具和风险策略；
4. 预期的状态断言。

状态断言不必保存一份完整“标准答案”工作簿。很多任务用局部断言更稳定：

{
  "mustChange": ["销售明细!H2:H101"],
  "mustNotChange": ["销售明细!A1:G101"],
  "formulaPattern": "=F{row}-G{row}",
  "confirmationRequired": false
}

这样模板里的无关样式变化不会让整个测试失效。

分清模型错误和工具错误

每次失败都要打标签：

context_missing
wrong_tool
invalid_arguments
tool_execution_failed
incorrect_result
confirmation_missing
timeout

如果 20 个案例都因为活动选区没传对，继续调提示词没有意义。如果模型选对了工具，但合并单元格场景下工具报错，就该补工具测试。

这也是为什么工具要支持绕过模型直接执行。只有把推理层和执行层分开测，才能知道钱和时间该花在哪里。

利用事件记录真实变化

SpreadJS 可以监听活动表切换、选区变化、编辑开始与结束、单元格变化等事件。对于 Agent 评测，这些事件可以形成一份实际变更轨迹。

例如记录：

{
  "event": "CellChanged",
  "sheetName": "销售明细",
  "row": 18,
  "col": 7,
  "propertyName": "value",
  "source": "agent",
  "toolCallId": "call_27"
}

需要注意，事件量可能很大。批量写入一万格时，不应把一万条原始日志都发到服务端。更实用的是在客户端聚合为范围、数量和属性摘要。

线上指标不要只看成功率

“任务成功率 92%”听起来不错，但它可能来自模型自己的成功判断。

更值得看的指标包括：

• 工具参数校验失败率；
• 用户取消确认的比例；
• 平均工具调用步数；
• 任务回滚率；
• 同一任务重复尝试率；
• 用户执行后立即撤销的比例；
• 每类工具的错误分布；
• 上下文大小和响应时间。

“执行后 10 秒内被用户撤销”是一个很有价值的负反馈信号。它不一定代表工具报错，却说明结果很可能不符合预期。

每次改动都跑回归

Agent 系统的变化来源很多：

• 更换模型；
• 修改系统提示；
• 调整工具描述；
• 新增工具；
• 改变上下文摘要；
• 升级表格组件；
• 调整确认策略。

任何一项都可能影响旧任务。发布前跑固定评测集，至少能发现“新能力好了，旧能力坏了”。

尤其是工具渐进加载后，状态恢复是否正确很难靠人工点几次覆盖。评测集应该包含多轮、取消、失败重试和分支任务，而不只是单句成功案例。

可观测性不是上线后的补丁

没有任务 ID、工具调用 ID、状态快照和变更摘要，出了问题就只能翻聊天记录。等上线后再补日志，很多关键上下文已经拿不到了。

Agent 的每一步都应该能回答：

它当时看到了什么？
为什么选择这个工具？
工具收到了什么参数？
实际改了哪里？
用户是否确认？
最终为什么被判定为成功？

能回答这些问题，才谈得上持续优化。

SpreadJS AI Agent 实战会把工具独立调试、任务持久化和工作簿变更串到同一条链路里。比起展示一次成功，我更关心失败后能不能准确定位到是哪一层。

想把这套方案真正跑起来

Agent 的问题不能都归结为“模型不稳定”。课程会展示工具如何独立调试、任务状态如何持久化、工作簿快照如何关联消息，以及开发者怎样区分推理错误、参数错误和执行错误。
课程《从 0 到 1 掌握企业级表格 Agent 搭建》基于公开的 SpreadJS AI Agent 项目，共 7 节，每节约 20 分钟，从整体架构一路讲到安全确认、快照回滚和调试体系。

课程地址

对应源码：https://gitee.com/GrapeCity/spreadjs-ai-agent。项目基于 TypeScript/TSX 和 SpreadJS，README 已整理工具体系、MCP 配置、受控代码执行、快照与恢复等入口，适合边读代码边验证。本文相关看点：工具调试、任务状态、消息快照和可复现的执行链路。