SpreadJS Agent:用渐进式披露构建更可靠的电子表格智能体

3 阅读16分钟

当 Agent 能调用的工具从几个增长到几十个甚至上百个时,真正的挑战已经不再是“有没有能力”,而是“能否在正确的时刻,只关注正确的能力”。SpreadJS Agent 将渐进式披露引入工具调用与上下文工程,在保留完整电子表格操作面的同时,主动控制模型每一步所面对的工具空间。

摘要:本文介绍葡萄城 SpreadJS Agent 的整体架构,并重点解析其渐进式披露机制。我们将结合工具分层、模块状态机、无状态请求恢复、MCP 按需检索以及受保护的代码执行链路,说明如何在 91 个内置工具和动态扩展能力并存的情况下,控制模型每一步的工具选择空间与知识上下文。

关键词:SpreadJS、AI Agent、渐进式披露、Tool Calling、MCP、上下文工程

生成式 AI 正在改变人与电子表格交互的方式。过去,用户需要熟悉公式、菜单和对象模型;现在,用户可以直接说“把销售额低于目标的区域标红”“按地区生成透视表并增加切片器”,再由 Agent 将自然语言意图转化为可执行的表格操作。

但从“能对话”走向“能可靠地操作工作簿”,中间存在明显的工程鸿沟。电子表格并不是简单的二维文本,它包含值、公式、样式、条件格式、图表、透视表、数据验证、批注、形状、切片器等多种对象。随着能力不断增加,Agent 可调用的工具也会快速膨胀。如果把所有工具及其参数同时交给大模型,更多能力未必会带来更好的结果,反而可能增加上下文负担、工具选择冲突和误调用概率。

为解决这一问题,我们在 SpreadJS Agent 中引入了“渐进式披露”(Progressive Disclosure):不一次性把全部能力平铺给模型,而是根据任务阶段逐步开放必要的工具和知识。它不是界面层面的折叠与展开,而是一套真正参与每一步模型推理和工具调用的上下文控制机制。

从 SpreadJS 到 SpreadJS Agent

SpreadJS 是运行在浏览器中的纯前端 Excel 类电子表格控件,其核心对象模型可以概括为:

Workbook
  └─ Worksheet
       ├─ Range / Cell
       ├─ Table / PivotTable
       └─ Chart / Shape / Slicer / Comment ...

这套对象模型为业务系统提供了完整、可编程的电子表格能力。SpreadJS Agent 则在此基础上增加了一层面向自然语言的任务执行系统:模型负责理解目标、规划步骤和选择工具,结构化工具负责读取或修改工作簿,SpreadJS 负责在浏览器中完成真实执行。

当前工程基于 SpreadJS 19.0.1,内置 91 个工具,覆盖数据读写、工作表管理、格式、条件格式、图表、透视表、表格、批注、数据验证、单元格状态、单元格类型、形状与图片、超链接、切片器、导入导出、外部检索和代码执行等场景。同时,Agent 还支持通过 MCP(Model Context Protocol)连接外部能力。

从系统职责看,SpreadJS Agent 并不是让大模型直接“操作页面”,而是把一次任务拆成三个相互约束的层次:

  1. 意图与规划层:理解用户目标,判断需要读取哪些上下文,以及应进入哪个能力域。
  2. 结构化工具层:通过带有明确名称、描述和输入约束的工具执行高频操作。
  3. SpreadJS 运行时层:在真实 Workbook 上完成读写、计算、渲染和对象管理

对于少量工具,这种架构已经足够。但当工具集扩展到 91 个时,还需要第四个关键机制:控制模型在每一步究竟能看到哪些工具。

为什么不能一次性披露全部工具

工具调用依赖的不只是模型能力,也依赖提供给模型的工具描述。每个工具都包含名称、用途和参数结构,这些内容会进入模型上下文。工具越多,模型就越需要在大量相似选项之间辨别边界。

以表格场景为例,“设置样式”可能涉及普通格式、条件格式、表格主题、透视表样式或图表样式;“添加对象”可能指图表、图片、形状、批注或超链接。如果这些工具同时出现,模型不仅要理解用户要做什么,还要从大量相近定义中完成一次高成本选择。

一次性披露全部工具主要会带来四类问题:

  • 上下文占用增加:工具定义会持续占用输入上下文,并在多步调用中重复出现。
  • 选择空间扩大:模型需要在更多候选项中判断,语义相近的工具更容易相互干扰。
  • 参数关注分散:与当前任务无关的参数结构也会进入注意力范围。
  • 扩展成本上升:每新增一个能力,都会进一步影响所有任务,而不只是使用该能力的任务。

因此,渐进式披露的目标不是削减能力,而是让完整能力以更适合模型决策的方式出现:默认提供高频操作和能力入口;当意图明确后,再把当前任务域的专属工具交给模型。

两级工具空间:基础工具、网关与模块

SpreadJS Agent 将 91 个内置工具划分为四类:

类型数量可见时机典型能力
基础工具35始终可见数据读写、Sheet 管理、分析、导入导出、任务控制、代码执行
网关工具12默认模式可见进入格式、图表、透视表、批注等能力域
模块子工具43进入对应模块后可见具体的创建、修改、删除和查询操作
退出工具1模块模式可见显式返回默认工具集

在默认模式下,模型看到的是 35 个基础工具和 12 个网关工具,共 47 个内置工具。进入某个模块后,12 个网关会被当前模块的 3 至 5 个专属工具替换,并增加一个 exit_module,因此模型通常只看到 39 至 41 个内置工具。

以格式操作为例,默认模式只披露 manage_format。模型调用该网关后,下一步才会获得:

  • format_range:设置字体、颜色、对齐、数字格式和边框等;
  • merge_cells:合并或取消合并单元格;
  • get_cell_format:读取单元格的详细格式。

此时,图表、透视表、切片器等其他模块的网关和子工具都不会出现在当前工具列表中。模型的注意力被收敛到“格式”这一任务域,但数据读写、工作表管理等基础能力仍然保留,因此它依旧可以完成必要的前置读取或辅助操作。

这是一种“能力不丢失、选择面动态收窄”的设计。

技术核心:每一步都重新计算可见工具

渐进式披露并不是在会话开始时做一次静态筛选。SpreadJS Agent 在每个生成步骤开始前,都会根据当前模块状态计算 activeTools。

其核心逻辑可以简化为:

if (activeModule) {
  return [
    ...baseTools,
    ...moduleToolMap[activeModule],
    "exit_module",
    ...mcpTools,
  ];
}

return [
  ...baseTools,
  ...gatewayTools,
  ...mcpTools,
];

这里有两个值得关注的设计点。

第一,完整工具定义仍由系统统一注册,activeTools 只决定当前步骤允许模型使用哪些工具。工具注册与工具披露相互分离,使模块切换不需要重新建立整套执行环境。

第二,切换发生在工具调用的步骤边界。默认模式下,模型先调用网关;本步结束后,状态机记录目标模块;下一步生成前,系统再把该模块的子工具开放给模型。这样,工具空间的变化与 Agent 的行动轨迹保持一致。

一次典型流程如下:

用户:把“销售明细”中低于目标的金额标红
  ↓
默认模式:基础工具 + 12 个模块网关
  ↓ 读取数据与范围
调用 manage_conditional_formatting
  ↓
条件格式模式:基础工具 + 条件格式子工具 + exit_module
  ↓
调用 add_highlight_rule
  ↓
完成操作并退出模块
  ↓
返回默认模式或直接生成最终回复

网关在这里并非 UI 分类标签,而是 Agent 状态机中的真实动作。它既向模型确认“已进入哪个能力域”,也可以执行必要的目标检查并返回当前工作表等环境信息,为下一步调用提供更明确的上下文。

状态机如何避免 Agent 长时间滞留在模块中

模块化工具披露还需要解决一个问题:什么时候退出模块?如果 Agent 在完成格式操作后仍然停留在格式模块,下一项任务需要图表工具时就会受到限制。

SpreadJS Agent 同时支持自动退出与显式退出:

  • 调用网关后,状态切换到对应模块;
  • 调用模块子工具后,可以在同一模块内继续后续操作;
  • 当某一步没有工具调用时,模块自动结束;
  • 如果本步既没有调用网关,也没有使用当前模块工具,状态机会主动清空模块;
  • 遇到需要强制切换的场景,可以调用 exit_module 返回默认模式。

这一策略在连续操作和及时释放之间取得平衡。例如,模型可以连续设置格式并读取结果,而在开始生成文字答复或转向其他任务时,模块状态会自然结束。

在无状态 HTTP 请求中恢复模块状态

浏览器端工具调用会形成多轮请求。服务端每次处理请求时,内存中的 activeModule 都会重新创建。如果只把模块状态保存在单次请求变量里,下一次请求就会回到默认模式,导致模型刚调用网关却看不到子工具。

SpreadJS Agent 没有依赖额外的服务端会话锁,而是从消息历史重建状态。恢复逻辑会从后向前查找最近一条 Assistant 消息,并按顺序分析其中的工具调用:

  • 最近调用的是 manage_* 网关,则恢复到对应模块;
  • 最近调用的是某个模块子工具,则通过反向映射恢复所属模块;
  • 出现 exit_module,则恢复为默认模式;
  • 工具调用后已经产生完整文本答复,则认为模块工作已结束。

因此,消息历史不仅是给模型阅读的对话记录,也是状态机的事件日志。它让渐进式披露能够适配无状态的 HTTP 多轮工具调用,并且在页面刷新、请求重试或会话恢复时保持一致的行为。

MCP:把“按需披露”延伸到专业知识

工具空间解决的是“Agent 此刻可以做什么”,但复杂电子表格任务还涉及另一个问题:模型是否准确知道某个 SpreadJS API 的签名、对象归属、插件依赖与调用方式。

SpreadJS 拥有 Workbook、Worksheet、Range、Cell、Table、Shape 等层次化对象,以及图表、透视表、切片器、导入导出等扩展能力。直接依赖模型记忆生成 API 代码,容易在方法名称、宿主对象、参数顺序或版本差异上产生偏差。

为此,SpreadJS Agent 支持接入 SpreadJS MCP。MCP Server 将官方 API 文档、示例、教程和功能说明以可调用工具的形式提供给 Agent。工程会动态发现 MCP 工具,将其转换为统一的工具定义,并以 mcp__{serverName}__{toolName} 的命名方式加入 Agent。

以当前 SpreadJS MCP 的知识访问流程为例,信息同样采用逐层展开的方式:

  1. overview 建立 SpreadJS 对象模型、包结构和集成方式的整体认知;
  2. search 根据当前任务检索相关 API 或专题文档,只返回排序后的候选结果;
  3. fetch 根据 doc_id 获取选中文档的完整内容,用于核实签名和细节;
  4. Agent 基于已核验的信息生成代码或选择结构化工具。

例如,当任务需要通过代码处理一个复杂区域时,Agent 可以先从 MCP 确认 Worksheet.getRange 同时支持行列索引与 A1 地址两种方式,再生成与当前场景匹配的代码,而不是把整套 SpreadJS 文档一次性放入提示词。

需要说明的是,内置模块状态机与 MCP 扮演不同角色:模块状态机负责收窄操作工具;MCP 负责按需提供权威知识和外部能力。在当前工程中,已连接的 MCP 工具会动态加入默认模式和模块模式,它们不计入 91 个内置工具的统计。两者结合后,渐进式披露形成了两个维度:

维度回答的问题实现方式
操作能力披露当前这一步允许模型做什么?基础工具 + 网关 + 当前模块子工具
专业知识披露当前这一步需要模型知道什么?MCP 的 overview → search → fetch

这也是我们理解的上下文工程:不是把更多内容塞给模型,而是让正确的信息在正确的阶段出现。

结构化工具优先,代码执行兜底

SpreadJS Agent 并不把所有任务都转换成任意 JavaScript。对于常见操作,结构化工具拥有明确的参数约束、可预测的执行路径和更容易检查的结果,应当优先使用。只有在循环、分支、复杂批量处理或跨 Sheet 联动等场景下,Agent 才会使用 execute_code。

这条执行路径与 MCP 形成了进一步的约束关系:如果 SpreadJS MCP 可用,Agent 在调用 execute_code 前必须先检索相关 API 的签名与用法。代码进入真实工作簿前,还会经过以下保护:

  1. 将当前工作簿序列化;
  2. 在隐藏的临时 SpreadJS 实例中预执行;
  3. 预执行通过后保存快照;
  4. 在真实 Workbook 上执行;
  5. 发生异常时通过快照回滚;
  6. 无论成功或失败,都恢复绘制、事件和计算状态。

因此,渐进式披露并不是孤立的提示词技巧,而是与工具约束、知识检索、预执行和回滚共同组成可靠性链路:

自然语言目标
  → 收敛工具空间
  → 按需获取官方知识
  → 选择结构化工具或生成代码
  → 预执行与快照保护
  → 修改真实工作簿
  → 返回可验证结果

渐进式披露带来的工程价值

对 SpreadJS Agent 而言,渐进式披露的价值主要体现在四个方面。

1. 降低工具选择的干扰

模型不再需要在 91 个内置工具中同时寻找唯一答案,而是先选择能力域,再在少量专属工具中完成具体动作。两阶段选择与用户意图的层次结构更加一致。

2. 控制上下文成本

不相关模块的工具定义不会进入当前步骤的可用工具集合。与此同时,系统提示词中的稳定规则与动态工作簿状态也被分离:稳定内容保持在可缓存的前缀,易变化的工作簿状态、任务计划和修改记录放在末尾刷新。这使工具披露与提示词缓存共同服务于上下文效率。

3. 提升扩展时的局部性

新增某个专业能力时,可以把它放入对应模块,而不必让所有任务都承担新增工具的认知成本。模块边界也为工具命名、输入结构和测试范围提供了清晰的组织方式。

4. 让执行轨迹更易观察

“进入模块—调用子工具—退出模块”的轨迹比在大工具集中直接跳转更容易记录和诊断。开发者可以清楚判断错误发生在意图路由、参数生成、工具执行还是状态恢复阶段。

需要保持客观的是,渐进式披露不会自动保证每一次调用都正确。网关描述是否清晰、模块划分是否符合用户任务、工具输入是否足够结构化、执行后是否验证结果,仍然决定着系统的最终质量。它解决的是大工具集中的注意力与选择问题,而不是替代测试、回滚和权限控制。

对企业级表格 Agent 的启示

随着 Agent 能力增加,一个常见误区是不断增加工具和提示词,期待模型“自行理解”。但企业级系统真正需要的是可管理的能力边界:哪些工具应该常驻,哪些能力应该按任务域展开,哪些知识必须实时检索,哪些高风险动作需要预执行、确认或回滚。

SpreadJS Agent 的实践表明,构建专业 Agent 可以遵循以下原则:

  • 高频、通用、低歧义的能力作为基础工具常驻;
  • 低频、专业、语义相近的能力通过网关按域披露;
  • 状态切换放在明确的步骤边界,并能够从事件历史恢复;
  • 产品 API 与版本知识通过 MCP 按需核验,不依赖模型记忆;
  • 优先使用结构化工具,任意代码只作为复杂任务的补充;
  • 对可变更业务数据的动作提供预执行、快照、回滚和结果验证。

这些原则并不局限于电子表格。但电子表格对象丰富、状态复杂、用户又对结果准确性高度敏感,因此非常适合验证一套 Agent 架构是否真正可靠。

结语

SpreadJS 为 Web 应用提供了成熟的电子表格运行时,SpreadJS Agent 则进一步探索如何让大模型以自然语言安全、准确地使用这些能力。当工具数量达到一定规模后,Agent 的竞争力不再只取决于“拥有多少工具”,更取决于“如何组织工具、知识与状态”。

渐进式披露的核心,是把一次复杂决策拆成一系列边界清晰的小决策:先理解任务域,再开放专属操作;先检索相关知识,再生成具体调用;先在受控环境中验证,再修改真实工作簿。

对我们而言,这不仅是一种降低上下文占用的优化,更是一种面向专业场景的 Agent 设计方法。它让 SpreadJS 的丰富能力可以持续扩展,同时让模型在每一步仍然保持明确、可控和可观察的行动空间。