你好！我是葡萄城 SpreadJS 产品专家。非常高兴能与你共同迎来这篇深度技术架构解析的压轴之作！
在前面的四篇文章中，我们沿着 Harness 架构的演进脉络，从底层状态同步（SpreadContext）、认知过载的破解（ModuleTracker 状态机），一路探讨到了执行瓶颈的突破（原子化工具与 MCP 管道）。至此，一个极其聪明且无所不能的 SpreadJS AI Agent 已经初具雏形。
但是，对于严谨的 SaaS 企业级应用而言，“能力越强，风险越大”。在与众多头部金融、制造企业客户的交流中，产品经理和安全合规团队最常提出的一个直击灵魂的问题是：“大模型虽然聪明，但它不可控。万一它‘发疯’，把我们核心财务报表里的数据清空了，或者把复杂的薪算公式覆盖了，谁来承担这个‘删库跑路’的责任？”
在 Harness 的架构哲学中，“Security Testing Orchestration (安全与合规)”和“Human-in-the-loop (人工确认节点)”是不可或缺的基础设施，它确保了系统在追求极致自动化的同时，绝不以牺牲安全性为代价。
今天，作为本系列的终篇，我将为您深度揭秘 SpreadJS AI Agent 的安全防护模块。看我们是如何复刻 Harness 的安全护栏理念，在纯前端电子表格中实现极其严苛的读写物理隔离，彻底把大模型关进安全的“透明笼子”里。
第一部分：传统粗放权限的隐患——为什么简单的“开关”防不住大模型的幻觉？
在将 AI 引入前端表格的初期，很多研发团队采取了最简单的权限控制策略：要么给 AI 赋予完全的“编辑权限（Edit）”，要么限制为“只读模式（Readonly）”。然而，这种非黑即白的粗放权限模型，在复杂的企业级场景中显得极其脆弱。
1.复杂业务场景下的“破坏性操作”防不胜防
以企业财务部门极其重要的“资产负债表”为例。这张表里不仅有静态的数值，更包含了环环相扣的“会计恒等式”公式（如：资产 = 负债 + 所有者权益）。 假设用户对 AI 下达了一个看似人畜无害的指令：“帮我把所有本期余额小于 0 的单元格标红，并清空这些异常数据”。 如果 AI 产生了逻辑幻觉，它可能在执行 clear_cells（清空单元格）工具时，错误地把包含汇总公式的单元格也一并清空了。传统的权限系统只要赋予了编辑权限，就无法区分“修改背景色”和“覆盖核心公式”这两种操作在业务风险上的天壤之别。一旦底层公式被静默破坏，后续所有的财务计算都将产生雪崩式的连环错误。
2.黑盒执行带来的审计灾难
传统大模型操作的另外一个痛点是“黑盒化”。大模型在后台默默生成了一大串修改数据的代码并直接执行（例如通过 eval() 直接运行 JS 代码），终端用户根本不知道 AI 刚才到底动了哪几行数据。这种缺乏透明度与可追溯性的执行管线，完全违背了企业级 SaaS 对“严格审计与确认”的安全合规要求。
粗放的读写权限不仅防不住大模型的逻辑幻觉，更会让企业客户对 AI 助手产生极大的不信任感。我们需要一种更底层的、细粒度的架构来重构安全体系。
第二部分：底层 READ / WRITE 隔离架构——将风险关进“权限分类”的笼子
在 Harness 的安全体系设计中，Role-Based Access Control (RBAC) 和最小权限原则（Principle of Least Privilege）是核心基石。映射到 SpreadJS AI Agent 的工具封装层，我们从底层架构上引入了**“读写物理隔离（READ vs WRITE Classification）”**的精细化管线设计。
我们没有将 SpreadJS 数以千计的 API 直接“裸露”给大模型，而是通过 Bridge 层进行了严格的重重拦截与分类。所有暴露给大模型的工具，在底层被严格划分为完全不同的风险等级：
1.绝对安全的 READ 级工具（无感自动执行）
这类工具的本质是“获取上下文”，它们不会对电子表格的物理状态造成任何更改。
- 工具代表：
read_ranges（读取指定范围数据）、get_workbook_metadata（获取表单结构、行列数）、search_data（全局搜索内容）。 - 安全策略： 系统对这类工具开启最高绿灯。大模型可以随时、高频、无限制地调用这些工具来感知当前表格的环境。这确保了 AI 的“视觉与记忆”畅通无阻，且无需频繁打扰用户。
2.受控的 WRITE 级工具（精细化拦截管控）
凡是涉及到修改 Spreadsheet 实例状态的工具，全部被归入 WRITE 级别，并在底层桥接层（Bridge Layer）加装了拦截器。为了避免给用户带来过度的确认负担，我们进一步将 WRITE 操作细分为“安全写入”与“破坏性写入”：
- 安全写入（Safe WRITE）： 例如
manage_format（修改字体、颜色、边框）、create_worksheet（新建一个空白工作表）、add_chart（插入图表）。这些操作即使模型做错了，也不会导致底层业务数据的丢失。系统允许其自动执行，但会在右侧 ChatPanel 的对话流中生成显式的执行记录卡片，保障审计透明度。 - 破坏性写入（Destructive WRITE）： 这是最高风险的红线操作。例如
write_data（向单元格写入/覆盖数据）、apply_formula（注入或修改公式）、clear_cells（清空数据区域）、delete_worksheet（删除工作表）。当大模型试图调用这些工具时，底层的执行引擎会立即拉响警报，触发最高级别的拦截管线。
通过这种底层 READ / WRITE 的物理隔离，我们从根本上确保了：大模型可以自由地“看”，但绝不能随意地“改”。它所有的破坏性企图，在触达物理电子表格之前，就已经被系统的拦截网稳稳兜住。
第三部分：全链路操作挂载与审计——HITL 人工确认与快照回滚机制
仅仅拦截是不够的，一个优秀的企业级应用需要在安全与效率之间找到完美的平衡。在 Harness 的流水线编排中，经常会用到一种机制：Human-in-the-loop（HITL，人工在环）。即在自动化流水线的关键节点强制暂停，等待关键责任人的审批后，流水线才继续向后流转。
我们将这一伟大的 DevOps 理念，完美地复刻到了电子表格的操作流中。
1.强制实施的“人工确认”拦截机制
当大模型试图执行“破坏性写入（Destructive WRITE）”时，系统是如何处理的？
- 管线挂起 (Pipeline Suspend)： Frontend Bridge 层在接收到模型生成的 JSON Tool Call（例如要求覆盖财务报表 A1:B10 区域的公式）时，不会立刻调用 SpreadJS 的原生 API。相反，它会将当前的执行管线强制挂起。
- 权限询问 (Ask For Permission)： 系统会在侧边栏的对话流中，弹出一个显式的人工确认卡片（AskForPermission Card）。卡片上会清晰、透明地展示大模型即将在哪个工作表、哪个区域、写入什么样的数据。这打破了传统 AI 的“黑盒执行”，让所有的高风险动作全部暴露在阳光下。
- 用户决策与流转： 只有当终端用户（人类审查者）审查无误，并明确点击了“允许执行”按钮后，被挂起的工具管线才会被放行，底层 API 才会真正执行物理写入。如果用户发现模型产生了幻觉，只需点击“拒绝”，系统便会阻断该操作，并将错误反馈回传给模型，要求其重新推理。
这种将大模型作为“起草者”，将人类作为“审批者”的协同模式，完美满足了企业在处理敏感数据时的最高合规标准。
2.拥抱原生能力：基于 Undo/Redo 引擎的回滚快照
哪怕有了人工确认，百密仍有一疏。如果用户手滑点错了同意，导致数据被覆盖，难道就真的“删库跑路”了吗？绝对不行。
在软件工程中，数据防损的最后一道防线是状态快照与回滚。得益于 SpreadJS 极其深厚的底层架构底蕴，它内部拥有一个极其强大的命令引擎（CommandManager）和原生撤销/重做（Undo/Redo）机制。
在 SpreadJS AI Agent 的执行层中，我们进行了精妙的工程化结合：
- 在执行大模型的任何修改指令之前，系统都会静默调用
undoManager.startTransaction()开启一个事务，记录当前表格的状态快照。 - 随后，系统在沙箱中安全地执行所有被拆解的原子化 API。
- 执行完毕后，调用
undoManager.endTransaction()提交事务。
数据防损置信度评级：极高。逻辑依据： 我们不仅通过 Bridge 层将危险阻断在了引擎执行之前（前置防御），更利用 SpreadJS 原生的机制建立了全量状态快照（后置兜底）。这意味着，哪怕大模型在一次复杂任务中连续调用了 20 个工具，修改了上百个单元格，用户也只需在表格界面上按下一次 Ctrl + Z（撤销键），所有的修改就能瞬间、完整、安全地回滚到 AI 操作之前的初始快照状态！这赋予了用户极大的安全感与试错勇气。
结语：安全与信任，才是智能表格通向企业级的最后钥匙
在这一篇中，我们看到了 SpreadJS AI Agent 在安全性上的深厚考量。通过复刻 Harness 的安全护栏理念，我们彻底告别了粗放权限带来的隐患。精细的底层 READ/WRITE 物理隔离、强制的 HITL 人工在环审批，加上基于原生引擎的无缝快照回滚能力，共同铸就了一道坚不可摧的企业级数据合规防线。
至此，我们的《以 Harness 视角解构 SpreadJS AI Agent 基础设施》五篇系列技术博客已经全部完结。
回顾这趟旅程，我们从“架构基石”起航，确立了 Agent 必须拥有优质 Harness 的认知；我们通过 SpreadContext 同步引擎 破解了多实例状态的混乱；通过 ModuleTracker 状态机 实施渐进式 API 披露，终结了模型的认知过载与逻辑幻觉；我们引入 MCP 协议与原子化工具 赋予了系统联通全网与稳定执行的能力；最后，我们在今天通过读写物理隔离与快照审计，为整个系统加盖了企业级的安全穹顶。
这一切的背后，都离不开一个无法替代的底座——SpreadJS。它卓越的运行态控制力、全覆盖的深度 API 以及天生强大的 CommandManager 引擎，使得这一切前沿架构理念得以完美落地。
我们深知，未来的 Web 端办公必将是对话式与智能化的。这套融合了行业最佳实践的 SpreadJS AI Agent Framework 现已开源。我们期待每一位追求卓越的前端开发者和架构师加入我们，不用再畏手畏脚地担心“AI 删库”，放心地释放大模型的惊人生产力，共同打造真正懂业务、懂安全、可信赖的下一代企业级智能电子表格！
