> 当 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 类电子表格控件，其核心对象模型可以概括为：

```Plain
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`。

其核心逻辑可以简化为：

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

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

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

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

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

一次典型流程如下：

```Plain
用户：把“销售明细”中低于目标的金额标红
  ↓
默认模式：基础工具 + 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. 无论成功或失败，都恢复绘制、事件和计算状态。

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

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

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

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

### 1\. 降低工具选择的干扰

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

### 2\. 控制上下文成本

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

### 3\. 提升扩展时的局部性

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

### 4\. 让执行轨迹更易观察

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

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

## 对企业级表格 Agent 的启示

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

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

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

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

## 结语

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

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

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

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

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

人工智能

开发工具

前端

SpreadJSAgent通过渐进式披露机制，将91个工具按基础、网关、模块分层管理，动态收窄模型每一步的工具选择空间。结合MCP按需检索与受保护代码执行，在控制上下文成本的同时确保电子表格操作准确可靠，为企业级Agent设计提供参考。

上下文工程

代码解释

JavaScript

路由

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

SpreadJS Agent：用渐进式披露构建更可靠的电子表格智能体-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐