当 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 并不是让大模型直接“操作页面”,而是把一次任务拆成三个相互约束的层次:
- 意图与规划层:理解用户目标,判断需要读取哪些上下文,以及应进入哪个能力域。
- 结构化工具层:通过带有明确名称、描述和输入约束的工具执行高频操作。
- 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 的知识访问流程为例,信息同样采用逐层展开的方式:
overview建立 SpreadJS 对象模型、包结构和集成方式的整体认知;search根据当前任务检索相关 API 或专题文档,只返回排序后的候选结果;fetch根据doc_id获取选中文档的完整内容,用于核实签名和细节;- 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 的签名与用法。代码进入真实工作簿前,还会经过以下保护:
- 将当前工作簿序列化;
- 在隐藏的临时 SpreadJS 实例中预执行;
- 预执行通过后保存快照;
- 在真实 Workbook 上执行;
- 发生异常时通过快照回滚;
- 无论成功或失败,都恢复绘制、事件和计算状态。
因此,渐进式披露并不是孤立的提示词技巧,而是与工具约束、知识检索、预执行和回滚共同组成可靠性链路:
自然语言目标
→ 收敛工具空间
→ 按需获取官方知识
→ 选择结构化工具或生成代码
→ 预执行与快照保护
→ 修改真实工作簿
→ 返回可验证结果
渐进式披露带来的工程价值
对 SpreadJS Agent 而言,渐进式披露的价值主要体现在四个方面。
1. 降低工具选择的干扰
模型不再需要在 91 个内置工具中同时寻找唯一答案,而是先选择能力域,再在少量专属工具中完成具体动作。两阶段选择与用户意图的层次结构更加一致。
2. 控制上下文成本
不相关模块的工具定义不会进入当前步骤的可用工具集合。与此同时,系统提示词中的稳定规则与动态工作簿状态也被分离:稳定内容保持在可缓存的前缀,易变化的工作簿状态、任务计划和修改记录放在末尾刷新。这使工具披露与提示词缓存共同服务于上下文效率。
3. 提升扩展时的局部性
新增某个专业能力时,可以把它放入对应模块,而不必让所有任务都承担新增工具的认知成本。模块边界也为工具命名、输入结构和测试范围提供了清晰的组织方式。
4. 让执行轨迹更易观察
“进入模块—调用子工具—退出模块”的轨迹比在大工具集中直接跳转更容易记录和诊断。开发者可以清楚判断错误发生在意图路由、参数生成、工具执行还是状态恢复阶段。
需要保持客观的是,渐进式披露不会自动保证每一次调用都正确。网关描述是否清晰、模块划分是否符合用户任务、工具输入是否足够结构化、执行后是否验证结果,仍然决定着系统的最终质量。它解决的是大工具集中的注意力与选择问题,而不是替代测试、回滚和权限控制。
对企业级表格 Agent 的启示
随着 Agent 能力增加,一个常见误区是不断增加工具和提示词,期待模型“自行理解”。但企业级系统真正需要的是可管理的能力边界:哪些工具应该常驻,哪些能力应该按任务域展开,哪些知识必须实时检索,哪些高风险动作需要预执行、确认或回滚。
SpreadJS Agent 的实践表明,构建专业 Agent 可以遵循以下原则:
- 高频、通用、低歧义的能力作为基础工具常驻;
- 低频、专业、语义相近的能力通过网关按域披露;
- 状态切换放在明确的步骤边界,并能够从事件历史恢复;
- 产品 API 与版本知识通过 MCP 按需核验,不依赖模型记忆;
- 优先使用结构化工具,任意代码只作为复杂任务的补充;
- 对可变更业务数据的动作提供预执行、快照、回滚和结果验证。
这些原则并不局限于电子表格。但电子表格对象丰富、状态复杂、用户又对结果准确性高度敏感,因此非常适合验证一套 Agent 架构是否真正可靠。
结语
SpreadJS 为 Web 应用提供了成熟的电子表格运行时,SpreadJS Agent 则进一步探索如何让大模型以自然语言安全、准确地使用这些能力。当工具数量达到一定规模后,Agent 的竞争力不再只取决于“拥有多少工具”,更取决于“如何组织工具、知识与状态”。
渐进式披露的核心,是把一次复杂决策拆成一系列边界清晰的小决策:先理解任务域,再开放专属操作;先检索相关知识,再生成具体调用;先在受控环境中验证,再修改真实工作簿。
对我们而言,这不仅是一种降低上下文占用的优化,更是一种面向专业场景的 Agent 设计方法。它让 SpreadJS 的丰富能力可以持续扩展,同时让模型在每一步仍然保持明确、可控和可观察的行动空间。