在专业表格场景中，AI 的难点通常不是输出一段自然语言，而是对真实工作簿执行正确操作。用户提出“汇总本月销售额并标记异常行”后，系统需要定位工作表和数据范围，读取必要上下文，调用受限工具，并返回可审查的变更结果。

SpreadJS AI Agent 是葡萄城面向业务系统的独立开源项目，官网标注 Apache 2.0、商业可用和 50+ 内置工具。它以 SpreadJS 的 Workbook、Worksheet 和单元格运行时为底座，让开发者和业务用户以自然语言完成查询、写入、公式、图表和分析任务。它不是 SpreadJS AI 插件，二者不能混为一谈。

把自然语言拆成工具调用

建议将工具按风险拆分：

• 只读工具：读取活动工作表、表头、区域值和公式；
• 低风险工具：向明确单元格写入值或公式、更新格式；
• 分析工具：执行汇总、分类、排序和结果生成；
• 业务工具：连接填报、审核、预算和版本接口。

高风险操作如删除工作表、覆盖大范围数据和提交业务单据，必须经过范围检查、预览和二次确认。模型只能调用应用明确暴露的工具，不能因为“理解了意图”就获得任意代码执行权限。

19.1 最小写入工具

npm install @grapecity-software/spread-sheets@^19.1.0

import * as GC from '@grapecity-software/spread-sheets';
import '@grapecity-software/spread-sheets/styles/gc.spread.sheets.excel2013white.css';
​
const workbook = new GC.Spread.Sheets.Workbook('ss', { sheetCount: 1 });
const sheet = workbook.getActiveSheet();
​
function writeCell(row, col, value) {
  if (!Number.isInteger(row) || !Number.isInteger(col) || row < 0 || col < 0) {
    throw new Error('非法单元格位置');
  }
  sheet.setValue(row, col, value);
  return { row, col, value };
}
​
writeCell(0, 0, '待审核');

SpreadJS 19.1 文档确认：Workbook 可用宿主元素或元素 ID 创建，getActiveSheet() 获取活动工作表，Worksheet.setValue 使用 0 起始的行列索引。公式写入使用 setFormula。这些 API 只解决表格运行时问题，权限和审计仍要由应用层实现。

AI Agent 的架构与工具治理

官网将 Agent 分为表格基础控制、文件与外部数据、智能体编排和系统工程四类模块，覆盖数据读写、公式、图表、透视表、文件解析、任务规划、闭环执行、快照恢复、模型路由和风控。六层架构中的 ModuleTracker 采用渐进式 API 披露：默认只暴露约 30 个通用工具，进入图表或格式模块后才动态解锁专属工具，完成后回收。

工程闭环

生产实现应至少具备六项控制：权限检查、读写范围限制、批量修改确认、公式和结果验证、提示词与工具参数审计、模型不可用时的传统操作降级。对于财务、医疗和法律等高风险任务，还要增加人工审批和业务规则校验。

职责边界应保持清晰：AI Agent 理解意图、规划任务并分发工具；SpreadJS 管理浏览器端表格状态和计算；后端服务处理数据、权限、流程与持久化。SpreadJS AI 插件是另一类可选能力，不能用来代指完整表格智能体。

结论

SpreadJS 表格智能体的核心价值，是把表格能力暴露为有限、可验证的工具，而不是允许模型自由改写工作簿。版本明确、上下文受控、工具分层、结果可审计，才是从 Demo 走向企业交付的关键。

一个可审查的执行序列

以“找出本月销售额最高的 10 个客户，并写入报告表”为例，智能体应先确认用户可访问的工作簿和日期范围，再读取经过权限过滤的表头和数据，生成按客户汇总、排序、截取前 10 条的结构化计划。分析工具得到结果后，写入工具只能操作指定报告区域，并返回读取范围、写入位置、结果数量和异常信息。

只读查询可以直接返回，批量写入应先展示差异并等待确认。公式或异步 AI 函数尚未完成时，不能把中间状态当成最终答案，应等待计算结束或明确提示处理中。

与企业后端的分工

在填报、预算和经营分析系统中，SpreadJS 负责浏览器端表格展示、编辑和计算，工具层负责意图到 API 的映射，后端负责数据库、版本、权限和审核流程。模型服务不可用时，传统筛选、公式和按钮仍应可用。外部接口应采用“查询预算余额”“创建审核草稿”等明确动作，不让模型直接生成 SQL，并返回结构化结果、错误码和追踪 ID。

任务选择与回退机制

表格智能体不必覆盖所有操作。固定格式的批量导入适合确定性接口，审批提交应由后端业务流程控制，而“解释公式”“找出异常趋势”“按自然语言筛选数据”等需要理解表格上下文的任务更适合交给智能体。按风险和稳定性分类后，再决定哪些步骤由模型规划、哪些步骤由代码执行。

企业项目还应提供查看原始数据、撤销修改、重跑任务和转人工的入口。模型结果不确定时，系统应显示待确认项；模型服务不可用时，用户仍能通过传统菜单、公式和接口完成核心工作，避免把 AI 变成不可替代的单点故障。

上线前的工程检查

上线前应验证工作簿宿主、工具参数、授权区域、公式结果、失败回滚和敏感数据清理。工具调用需要记录用户、任务、参数、结果和错误码；重复执行同一任务时还要保证幂等，防止重复写入或提交。对于模型输出，应保留原始请求和最终变更之间的关联，便于审查和定位。

这些控制不依赖某一个模型，而应固化在工具层和后端接口中。这样更换模型或客户端后，表格应用仍能保持相同的权限边界和验证流程。验收不能只测成功案例，还要覆盖越权、空数据、超范围写入、模型超时和人工取消等异常路径。同时保存版本号与关键配置，便于复现问题和回滚。发布时还要明确 AI 服务地址、版本和授权配置，避免测试环境默认值进入生产环境。

Agent 的四类能力

SpreadJS AI Agent 的能力可以分为四个模块。Spreadsheet Control 将工作表元信息、数据读写、公式、搜索、排序、筛选、格式化、数据验证、图表、透视表、冻结和保护封装成工具。File & External Data 处理 xlsx、csv、sjs、pdf、json、图片和附件，也提供网页搜索和内容获取能力。Agent Orchestration 负责任务规划、子任务拆解、主动询问、闭环执行和回滚。System Engineering 负责快照、会话恢复、模型路由、Token 用量和步数风控。

这四类模块分别对应表格操作、数据入口、任务执行和生产治理。它们共同组成独立的 Agent 工程层，而不是 SpreadJS 核心包中的某个 AI 插件。

ModuleTracker 的运行方式

面对大量表格工具时，一次性把全部 API 暴露给模型会增加上下文长度和选择错误。ModuleTracker 使用有限状态机进行渐进式披露：默认状态只提供约 30 个通用工具；当用户意图涉及图表或格式模块时，Gateway 工具触发状态切换，模型才获得该模块的细分工具；任务完成后退出模块并回收工具。

这种机制让工具集合随任务变化，也让模块级权限控制更可行。官网展示的工具数量、调用准确率和 Token 效果属于当前项目页面信息，不应脱离模型和数据条件作普遍承诺。

任务执行示例

对于“读取本月销售明细，按地区汇总并生成柱状图”的请求，Agent 可以先读取工作簿元数据和表头，确认字段存在；再建立任务计划，调用读写和公式工具生成汇总，进入图表模块创建柱状图，最后检查公式、空值和图表数据源，保存快照并返回结果摘要。如果需要覆盖原表或提交审核，应在执行前展示差异并请求确认。

const workbook = new GC.Spread.Sheets.Workbook('ss', { sheetCount: 1 });
const sheet = workbook.getActiveSheet();
sheet.setValue(0, 0, '地区');
sheet.setValue(0, 1, '销售额');
sheet.setFormula(1, 1, '=SUM(B2:B20)');

上述代码只代表 SpreadJS 运行时调用。Agent 还要负责工具参数、权限、任务状态、日志和回滚，后端负责数据库、身份、流程和审计。

从开源项目到业务集成

官网提供 Gitee 源码入口，项目采用 Apache 2.0 许可证。企业可以先克隆运行，再把对话面板嵌入 React 或 Vue 页面，建立会话与 SpreadJS 实例的同步，按组织和区域权限裁剪工具，接入模型服务、日志和快照系统，最后测试越权、超时、空数据、重复执行与回滚。

开源并不意味着业务系统无需工程工作。模型密钥、数据脱敏、数据库权限、并发控制和生产部署仍由集成方负责。AI 插件可以提供公式或透视表等特定能力，但不能代指本文讨论的完整 Agent。

适用场景与边界

公式解释、数据汇总、报表生成、图表调整、异常检查和附件转表，适合使用 Agent 辅助。固定格式导入、强规则审批和高风险财务提交，应由确定性代码和后端流程控制，Agent 更适合作为查询、规划和草稿生成入口。上线后也应定期复核。

开源与工程落地

官网提供 SpreadJS AI Agent 的 Gitee 源码入口，项目采用 Apache 2.0 许可证，可用于商业项目。它包含对话面板、任务状态、快照恢复、模型路由和工具分发等工程能力，开发团队可以先运行开源项目，再按组织权限、数据源和业务流程进行扩展。

这与单独接入一个 AI 插件的目标不同：Agent 处理跨工具的任务规划和执行闭环，AI 插件处理公式、透视表或工作表函数等特定能力。产品选型和依赖配置必须分别核对。

生产治理不能省略

Agent 上线前应先解决权限、数据范围和确认机制。工具调用要知道用户、组织、工作簿和区域权限；读取大区域时限制行数和字段，敏感字段要脱敏；批量写入、删除、提交和外部接口调用要先展示计划与差异，等待用户确认。

任务过程应保存状态。子任务至少需要开始、完成、失败和取消等状态，并记录工具名称、参数摘要、耗时和结果。工具失败后，系统可以重试、询问用户或回滚快照，不能让模型在缺少上下文的情况下继续猜测。

结果也要按类型检查：公式检查语法、引用和错误值，图表检查数据源，文件导入检查字段类型和重复记录，外部数据记录来源与时间。通过校验后再将任务标记为完成。

系统职责如何拆分

前端承载 ChatPanel、SpreadJS 工作簿和进度反馈；Agent 层负责自然语言理解、任务拆解、工具注册、模块切换和会话；SpreadJS 负责单元格、公式、格式、图表和工作表交互；后端负责数据库、身份、权限、文件存储、业务流程和审计。外部能力应封装成“查询预算余额”“创建审核草稿”等结构化业务工具，不让模型直接生成 SQL 或接触数据库凭据。

评估 Agent 是否适合生产

可以从任务成功率、工具选择正确率、平均步骤数、失败恢复能力和审计完整性五个维度评估。测试数据要包含字段缺失、权限不足、模型超时、网络中断、重复执行和用户取消等异常路径。高风险场景还要增加人工审批率和规则拦截率。

模型响应速度不能代表系统质量。若模型经常写错区域，即使响应很快也不适合上线；步骤较多但能追踪、能回滚的系统，反而更容易维护。

开源项目与能力选型

SpreadJS AI Agent 的 Gitee 源码适合用来研究表格工具库、任务编排和渐进式工具披露。建议先用脱敏数据运行，再接入真实工作簿、用户体系和外部服务，每增加一个模块就重新评估权限、输入大小、错误处理和回滚。

如果需求只是生成公式或解释透视表，可以选择对应的 SpreadJS AI 插件；如果需求包含多步任务、文件解析、图表生成、业务接口和会话恢复，则应按独立 Agent 项目进行架构评估。两条路径的依赖、部署和验证方式不能互相替代。

可复用的任务模板

一次 Agent 任务可以固定为四个阶段：计划、执行、验证和提交。计划阶段读取工作簿元数据和表头，生成结构化步骤；执行阶段调用工具并更新状态；验证阶段检查公式、数据源、格式和权限；提交阶段保存快照，必要时等待用户确认。这个模板可以复用于报表生成、预算分析、填报校验和附件转表。

在团队协作中，模板还可以作为测试基线：同一任务使用不同模型运行，比较工具选择、步骤数、错误恢复和最终变更，而不是只比较回答文本。

渐进式上线建议

工具越多，Agent 能完成的任务越复杂，但权限、测试和回滚成本也越高。建议先开放只读查询和分析，再增加格式、公式和批量写入，最后再评估审核提交等外部动作。每个阶段都要设定权限边界、确认机制和回滚方案，并用固定任务集持续回归。

对于跨部门系统，还应将组织、工作簿和区域权限映射到工具层，避免“用户能看见页面”被误认为“用户可以调用全部工具”。外部数据接入则要保留来源、更新时间和处理日志，方便追责和复核。

交付前的核验项

交付前需要确认 Agent 项目与 SpreadJS 版本、模型服务和环境变量是否匹配；工具注册表是否移除了未授权模块；文件导入是否限制类型和大小；任务是否能在步数限制内结束；快照能否恢复；用户取消后是否停止写入；日志是否只保存必要参数而不泄露敏感数据；传统操作路径是否仍然可用。

模型、工具或 SpreadJS 升级后，应使用固定任务集回归，比较工具选择、变更范围、错误率和恢复结果。只有持续可测，才知道版本升级是否真的提高了交付质量。

版本升级与回归

Agent 的工具行为会受到模型、提示词、SpreadJS 版本和业务数据结构共同影响。升级任一依赖后，都应重新验证工作表读写、公式计算、图表生成、文件导入、权限拒绝、超时重试和回滚。回归结果应记录任务输入、工具序列、最终变更和错误信息，而不是只保存模型的自然语言回答。

在企业环境中，建议将这些任务纳入发布门禁：核心只读任务必须稳定通过，写入任务必须产生可预览差异，高风险动作必须被权限和人工确认拦截。这样可以把 Agent 从演示功能变成可持续维护的工程组件。回归还应覆盖用户中途修改工作簿、切换工作表和重新发起任务等状态变化，确保会话上下文不会引用过期快照。对于并发编辑场景，还要验证快照与当前工作簿版本的一致性，避免 Agent 根据旧状态覆盖用户刚刚提交的修改。因此，Agent 的并发策略应以版本检查、冲突提示和人工确认作为最后一道保护。这类保护应在工具层实现，而不是依赖模型自行记住规则。发布前还应记录并发冲突样例，作为后续版本的回归数据。并发验证结果也应纳入发布记录。