在屏幕右侧的聊天框里输入一句"在 A1 写入 Hello"，按下回车。几秒钟后，屏幕左侧的表格里，A1 单元格真的出现了 Hello 这几个字。
如果只盯着结果看，这像是一次普通的自动化。但这个动作其实至少穿过了五个边界：用户界面、浏览器里的工作簿状态、服务端的模型推理、工具选择，以及真正修改表格的那一层 API。任何一个边界没处理好，都会冒出一些让人摸不着头脑的问题------"AI 说它写完了，可表格没变化""表格明明改了，模型却不知道结果""服务端根本拿不到当前工作簿"。
第一课不急着钻进某个函数，而是先把整条链路走一遍。因为只有看清一句话是怎么流动的，后面要讲的上下文、安全、快照和调试，才有地方可以挂靠。
为大家准备了可以在线体验的表格Agent，点击体验
左边是表格，右边是 Agent
打开这个项目，首页是左右两块。
左边是 SpreadJS 的设计器。它不是浏览器里一个普通的 HTML 表格，而是一个完整的电子表格环境，承担工作表、单元格、公式、样式、图表、各种对象和用户交互。用户可以像用桌面表格软件一样，选区域、改内容、检查结果。
右边是聊天面板。它接收自然语言，展示模型的回复、任务计划和工具调用，也处理附件、会话、停止和恢复这些 Agent 特有的交互。
看起来只是左右分屏，工程上却是两个截然不同的世界：左边保存真实的业务状态，右边组织 AI 的决策流程。这条界线后面会反复出现，它是整套架构的地基。
一个绕不开的核心矛盾
要把 AI 接到表格上，最先撞墙的就是一个技术矛盾：SpreadJS 的工作簿是一个活在大模型浏览器内存里的大型 JavaScript 对象，它依赖 DOM、Canvas、事件系统，根本没法被一次网络请求原样打包送到服务端。而模型的推理，恰恰发生在服务端。
服务端够不着浏览器里的工作簿，怎么办？
项目给出的答案是定下一条铁律：服务端负责让模型理解和做决策，浏览器负责执行真实的表格操作。 这不是被技术限制逼出来的将就，而是合理的分工。浏览器本来就持有当前表格和用户的实时交互，在这里执行能立刻看到结果，也方便执行前做检查、弹确认、存快照。服务端则更适合管模型调用、系统规则和外部工具。
很多人做 AI 表格的第一反应是"把文件传到服务端改完再传回来"。这条路会打断用户正在进行的编辑，也很难支撑"AI 改两格、用户又手动改一行"这种交替发生的实时体验。
一条指令的完整旅程
把这条链路先画成一张图，再逐段拆解：
shell
用户输入
-> 聊天面板收集输入与上下文
-> /api/chat（服务端）
-> 大模型选择工具，产生 tool call
-> tool call 回到浏览器
-> 工具分发器 useToolDispatch
-> handler 与 bridge
-> 真实的 SpreadJS 工作簿
-> 工具结果返回模型，形成闭环第一站，聊天面板发起请求。 用户发消息时，前端并不是只把一段文字发出去。它还会顺手把本轮需要的东西打包进去：当前工作簿的摘要、任务计划的进度、以及上次请求之后表格发生了哪些变化。这些"环境信息"会跟着消息一起送到服务端。而且因为用的是流式交互，用户能逐步看到模型在输出什么、在调哪个工具，不用干等一个复杂任务跑完。
第二站，服务端让模型做决策。 /api/chat 是整套系统的大脑入口。它会把系统提示词、聊天历史、工作簿上下文，以及"这一轮模型能用哪些工具"一起交给大模型。注意，这里模型不应该吐出"我已经写好 A1 了"这种没法验证的话，而应该产生一个结构化的工具调用，比如：
lua
{
"toolName": "write_data",
"input": {
"address": "A1",
"data": [["Hello"]]
}
}工具调用把一句模糊的自然语言，变成了一份能检查的数据：要调哪个能力、目标是哪个区域、写入什么内容。后面的参数校验、风险检查、日志记录，全都有了明确的着力点。
第三站，工具调用回到浏览器。 模型产生工具调用后，并不是所有工具都在同一个地方跑。查数据库、做外部搜索这类可以由服务端完成；但要动 SpreadJS 工作簿，就必须回到浏览器。前端的工具分发器会做几件事：判断这是不是服务端工具、工作簿准备好没有、能不能找到对应的处理函数。如果工作簿还没初始化好，它该返回一个明确错误，而不是让模型误以为已经执行成功。这一层看起来只是"按名字找函数"，实际是整个架构的交通枢纽。
第四站，handler 和 bridge 真正改表格。 以写入数据为例，工具定义描述了输入长什么样，处理函数拿到当前工作簿，再调用 bridge 里的写入逻辑。bridge 才是真正碰 SpreadJS API 的地方------它会定位到具体的工作表和目标区域，逐个处理输入值。如果某个字符串以等号开头，就当作公式处理；否则当作普通值。批量操作时还会先暂停重绘和计算，干完再恢复，避免中间状态把界面卡得乱七八糟。
把 bridge 单独拎出来分层，好处很多：模型不必记 API 细节；多个工具能复用选工作表、解析区域、抓错误这些逻辑；开发者甚至能绕开模型，直接测 bridge 对不对。SpreadJS 在这里真正的身份，是执行业务动作的表格引擎，而不是 AI 回复的展示框。
第五站，结果必须回到模型。 工具执行完，结果会被写回消息历史------成功与否、实际改了哪个范围、读到了什么数据、或者出了什么错。为什么不能执行完就结束？因为模型得根据真实结果决定下一步。假如模型想在 A1:C4 建图表，但读取工具发现这片区域是空的，它应该停下来问用户，而不是硬着头皮继续画。只有结果回到推理环路里，这个系统才从"模型光下命令"变成了"边看结果边行动"。
这是"操作表格"，不是"分析表格"
很多人会把这两件事混在一起。把表格导出成文本交给模型，再让它返回一段分析，那叫"AI 看表格"。而这个项目要做的是"AI 动表格"：模型选能力，浏览器执行，结果真实落到工作簿上。
两者的工程复杂度不在一个量级。看表格只需要解决"怎么把数据给模型"；动表格还要解决"模型改坏了怎么办""用户中途反悔怎么办""几十个工具它会不会选错"。后面这些，才是这套课程真正花力气的地方。
这张地图，最大的价值是"出问题知道从哪查"
链路清晰了，最直接的收益是可定位性。模型只回文字、不调工具，就去查工具对模型可不可见、描述清不清楚；工具选对了但参数不对，去查输入 Schema；界面显示成功了表格却没动，去查前端有没有拿到工作簿、bridge 有没有解析对区域；表格变了模型却还在反复重做，去查工具结果有没有回传。每类故障都能被收敛到某一层，而不是笼统地归咎于"模型今天状态不好"。这种可定位性，是工程项目和演示 Demo 最明显的分水岭。
而对使用它的人来说，这条链路也悄悄决定了体验：任务分好几步时，界面有没有让你看到"正在读取""正在写入""正在建图"？工具失败时，你看到的是一句看得懂的原因，还是冰冷的"未知错误"？一个好的 Agent 界面不必把技术细节全摊开，但应该让你随时知道系统在干嘛、干过什么、现在还能不能撤回。这种"看得见、叫得停、退得回"的感觉，恰恰来自背后清晰的分层。
这条链路，并不只属于表格
虽然项目操作的是 SpreadJS，但这条链路可以搬走。在文档编辑器里，浏览器持有文档对象，服务端让模型决定插入、改写还是评论；在低代码平台里，模型选组件和布局工具，浏览器改画布；在 BI 系统里，模型读指标上下文，再调查询和可视化能力。规律都是同一个：真实业务对象留在它最合适的运行环境，模型负责高层决策，结构化工具连接两者，执行结果回到推理环路。
到这里，一句话变成表格操作的主链路已经清楚了。但链路上还留着一个没回答的问题：服务端的模型够不到浏览器内存里的工作簿，它到底凭什么知道当前有哪些工作表、用户选中了哪里、表格刚刚被改过什么？
下一篇，我们就走进表格智能体最容易被低估的地方------上下文设计。你会发现，正确做法不是把整张表一股脑塞给模型，而是为它画一张能导航、能按需查、还能持续更新的"工作簿地图"。