模型规划得没问题，工具参数也完全正确，但用户点下执行后，页面停住几秒，滚动条不动，浏览器甚至提示“页面无响应”。

原因往往很朴素：Agent 把一次批量任务拆成了成千上万次单元格更新，每次更新又触发绘制、事件和公式重算。

AI 没做错，执行方式错了。

工具调用少，不代表底层操作少

模型可能只调用了一次：

{
  "tool": "formatReport",
  "range": "A1:Z10000"
}

但工具内部如果逐单元格设置值、字体、背景色和格式，实际可能产生几十万次对象操作。

表格组件在数据变化后需要刷新界面；公式相关单元格还会触发计算；监听器可能继续更新任务摘要。三个成本叠加，页面就会卡住。

批量更新先暂停绘制

SpreadJS 提供 suspendPaint() 和 resumePaint()。当一组修改需要连续完成时，可以暂停中间绘制，最后统一刷新。

spread.suspendPaint();
try {
  applyValues();
  applyFormulas();
  applyStyles();
} finally {
  spread.resumePaint();
}

finally 不能省。如果执行中间抛错，却没有恢复绘制，工作簿可能一直处于不刷新的状态。

对于会触发大量监听逻辑的确定性批处理，还可以评估是否临时暂停事件；涉及密集公式更新时，则要单独设计计算时机。重点不是把所有机制一律关闭，而是避免每改一格就完整走一遍刷新链。

能按区域操作，就不要逐格循环

Agent 工具的粒度会直接影响性能。

低效的工具常常只提供：

setCellValue(row, col, value)

于是模型或调度器为了填一块区域，调用它几千次。

更合理的是提供批量语义：

setRangeValues({
  sheetName,
  startRow,
  startCol,
  values: unknown[][]
})

样式也应该尽量针对 Range 设置，而不是每个 Cell 设置一次。工具层表达的是业务批量动作，执行层才有机会做合并和优化。

进度条不能靠猜

超过一两秒的任务，用户需要知道系统还在工作。

但进度不能只做一个循环动画。批量工具在执行前已经知道目标行数，可以分块并返回实际进度：

正在写入数据  4000 / 10000
正在应用公式  7200 / 10000
正在生成样式

如果公式计算量很大，也要把“数据写入完成”和“计算仍在进行”分开表达。否则用户看到表格已经有数据，以为任务完成，马上开始编辑，容易和后续计算冲突。

分块执行不只是为了流畅

十万行一次性执行失败时，错误很难定位。按块处理可以记录每一块的状态：

{
  "taskId": "task_901",
  "chunks": [
    {"range": "A1:Z2000", "status": "success"},
    {"range": "A2001:Z4000", "status": "success"},
    {"range": "A4001:Z6000", "status": "failed"}
  ]
}

但分块也会引入一致性问题。前两块成功、第三块失败后，是保留已完成部分，还是整体回滚？这必须在工具定义时决定，不能等出错后临时猜。

对于“导入数据”可以支持断点续传；对于“重算整份报价表”可能更适合全有或全无。

性能预算应该写进工具约束

一个工具除了参数 Schema，还可以声明成本：

{
  "maxCells": 50000,
  "estimatedMs": 1800,
  "supportsChunking": true,
  "requiresProgress": true,
  "rollbackMode": "snapshot"
}

模型不一定需要看到所有底层指标，但调度器可以据此决定：

• 是否拆分任务；
• 是否先询问用户；
• 是否创建快照；
• 是否切换到后台执行；
• 是否拒绝超大范围。

Agent 的“自动”不能等于不设资源上限。

性能问题，本质上也是工具设计问题

同一个 SpreadJS API，人工点一次按钮可能很顺；交给 Agent 后，因为操作范围变大、步骤变多，性能瓶颈会被迅速放大。

因此表格工具不只要安全、可验证，还要有批量语义、执行预算和进度反馈。

当模型说“处理整张表”时，执行器首先想到的不该是 for 循环，而应该是：影响多少单元格、能否合并操作、何时绘制、何时计算、失败怎么收场。

SpreadJS AI Agent 实战中的工具执行放在浏览器端，这意味着性能和任务状态必须一起设计。后续会继续拆解如何让工具既能被模型调用，也符合前端应用的运行规律。

想把这套方案真正跑起来

批量操作一旦进入真实工作簿，绘制、事件、计算和异常恢复都会变成前端工程问题。课程基于真实 SpreadJS AI Agent 项目拆解浏览器端工具执行，让你看到模型调用之外，那些决定页面能否稳定运行的实现细节。

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

点击查看课程地址

对应源码：https://gitee.com/GrapeCity/spreadjs-ai-agent。项目基于 TypeScript/TSX 和 SpreadJS，README 已整理工具体系、MCP 配置、受控代码执行、快照与恢复等入口，适合边读代码边验证。本文相关看点：批量表格工具、suspendPaint 状态管理和异常后的自动恢复。