企业官网建设流程全解析

1. 项目缘起与整体架构设计

1.1 为什么要在本地搭一套AI智能体Office套件

日常办公里最割裂的一件事，就是文档、表格、演示稿三件套各自为政，而AI能力通常以插件或网页对话框的形式游离在它们之外。你写一份周报，得先在文档工具里敲字，再切到某个AI对话页面润色，最后复制回来；做一份数据周报，得在表格里算完指标，再手动把结论誊到演示稿里。这个项目要解决的，就是把“AI智能体”直接嵌进Office文档流的骨架里，让文档、表格、演示三种载体共享同一套智能体调度层。

我给它起的定位是：一个以文档对象模型为中枢、以智能体编排为大脑的轻量办公套件。它不是一个要替代成熟商业办公软件的产品，而是一个可拆解、可复现、适合计算机科学与技术方向同学做课程设计或毕业设计的完整工程样本。你如果正在找“AI智能体”落地到具体场景的题目，又不想只停留在调用API写个聊天框，那这套东西的架构思路值得参考。

核心关键词有三个：AI智能体负责理解意图与调度工具，Office套件负责承载文档、表格、演示三类结构化内容，计算机科学与技术则决定了它的技术选型必须兼顾工程规范、可扩展性和可演示性。三者叠加，最终产物是一个能“听懂人话、动手改文档”的桌面级应用。

1.2 整体分层架构与选型逻辑

整套系统我按四层来切，从上到下依次是交互层、智能体编排层、文档能力层、存储与运行时层。这样切的好处是每一层都能单独替换，比如你不想用某个大模型，只换编排层里的模型适配器即可，文档能力层完全不用动。

交互层选的是Electron加React。理由很直接：Office套件的核心是富文本编辑和表格渲染，Web技术栈在这块的生态最成熟，而Electron能把Web应用打包成桌面程序，方便调用本地文件系统。React负责组件化，文档编辑器、表格网格、演示画布各自是独立组件，通过状态管理共享当前打开的文件上下文。

智能体编排层是整个项目的心脏。我采用的是“规划器加执行器”的双阶段结构，规划器负责把用户一句话拆成若干可执行步骤，执行器负责逐步调用文档能力层提供的工具函数。这里参考了ReAct模式的思路——推理与行动交替进行，每一步行动后把观察结果回灌给规划器，让它决定下一步。之所以不用一次性生成完整计划再执行，是因为文档操作有强依赖，比如“把第二段加粗”必须先知道第二段在哪，一次性规划容易在中间步骤失败后全盘崩溃。

文档能力层是套件的“手和脚”。它把文档、表格、演示的操作抽象成一组原子工具，比如insertParagraph、setCellValue、addSlide、applyStyle。每个工具都有明确的输入输出契约，智能体只能通过这些工具改文档，不能直接操作底层数据结构。这层抽象是安全边界，也是可测试性的保障。

存储与运行时层负责文件持久化和会话状态。文档用JSON格式存储抽象语法树，表格用二维数组加元数据，演示稿用幻灯片对象数组。选JSON而不是二进制格式，是为了让智能体的每次修改都能被diff出来，方便做撤销重做和操作审计。

提示：分层不是为了好看，是为了让“智能体出错”这件事的影响范围可控。编排层出问题最多是任务没完成，文档能力层出问题才会破坏文件内容，所以工具函数的参数校验必须做在最前面。

1.3 与纯云端方案的取舍

市面上不少方案是把文档传到云端，由云端AI处理后再传回来。我没走这条路，原因有三。第一，课程设计场景下，本地运行能避免网络依赖，演示时不怕断网。第二，文档内容往往包含个人信息或未公开数据，本地处理更稳妥。第三，本地架构能让你完整看到数据从输入到输出的每一步流转，对理解智能体工作原理更有帮助。

代价是本地模型能力有限。我的处理方式是双模型适配：简单任务走本地小模型，复杂任务走可配置的远程接口，但接口地址和密钥由用户自己填，程序本身不内置任何第三方服务。这样既保证了开箱即用的体验，又保留了扩展空间。

2. 智能体编排层的核心细节与实操要点

2.1 规划器与执行器的职责边界

规划器的输入是用户自然语言指令加上当前文档的摘要信息，输出是一个步骤列表，每个步骤包含工具名、参数和预期结果描述。执行器拿到步骤后，逐个调用工具，把每次调用的返回值作为观察结果记录下来，再交回规划器判断是否继续。

这里有个容易踩的坑：规划器如果看不到文档当前状态，就会瞎规划。比如用户说“把标题改成红色”，规划器得先知道标题在第几段、当前是什么样式。我的做法是在每轮规划前，把文档的结构摘要注入提示词，摘要只包含段落索引、类型和前若干字符，不传全文，既控制token消耗又保留必要上下文。

执行器的关键设计是幂等性。同一个工具用相同参数调用两次，结果应该一致。比如setCellValue设置单元格值，重复调用不会产生副作用。但insertParagraph这类插入操作天然不幂等，我的处理是给每次插入分配唯一ID，重复执行时先检查ID是否存在，存在就跳过。这个细节在任务重试时特别重要。

2.2 工具函数的定义规范

每个工具函数必须包含四要素：名称、描述、参数schema、返回值schema。名称用动词加名词的驼峰格式，比如insertParagraphAfter。描述要写清楚“什么时候用这个工具”，而不是“这个工具做什么”，因为规划器是根据场景选工具的。

参数schema我用JSON Schema描述，每个参数标注类型、是否必填、取值范围。比如段落索引参数，类型是整数，最小值0，最大值是当前段落数减一。规划器生成参数时会参考这个约束，减少越界错误。

返回值schema统一包含三个字段：success布尔值、data具体数据、error错误信息。执行器根据success决定是否继续，根据error决定是否让规划器重新规划。这套规范看起来繁琐，但实测下来能把工具调用的失败率降低不少，因为规划器有了明确的反馈信号。

2.3 上下文管理与记忆机制

智能体做多轮任务时，上下文会越来越长。我的策略是分层记忆：短期记忆保存当前任务的步骤历史和观察结果，长期记忆保存用户偏好和常用操作模式。短期记忆在任务完成后清空，长期记忆持久化到本地。

短期记忆的裁剪规则是保留最近若干轮完整记录，更早的只保留步骤摘要。摘要由规划器自己生成，比如“已完成：在第二段后插入一段文字，内容关于项目进度”。这样即使任务很长，规划器也能快速回顾已完成的部分。

长期记忆我设计成一个简单的键值存储，键是操作类型，值是用户历史选择。比如用户多次把标题样式设为“一级标题加粗”，下次规划时就把这个偏好注入提示词。这个机制不复杂，但能让智能体越用越顺手。

注意：上下文注入要控制长度，我一般把文档摘要控制在500字以内，短期记忆控制在2000字以内。超过这个量，规划器的响应速度会明显下降，而且容易忽略关键信息。

3. 文档能力层的实现与关键参数

3.1 文档编辑器的数据模型

文档编辑器的核心是一个段落数组，每个段落对象包含id、type、content、style四个字段。type区分普通段落、标题、列表项、代码块等。content是行内元素数组，支持文本、加粗、斜体、链接等。style保存段落级样式，比如对齐方式、缩进、行距。

选这个模型而不是直接操作HTML，是因为HTML太灵活，智能体容易生成不合法的结构。段落数组的约束更强，智能体只能在既定类型里选，生成的内容天然合法。渲染时再把段落数组转成HTML，这一步是纯函数，不涉及智能体逻辑。

行内元素的处理有个细节：加粗和斜体可以嵌套，但链接不能嵌套链接。我在工具函数里做了校验，遇到非法嵌套直接返回错误，让规划器重新生成。这个校验逻辑大概三十行代码，但省去了大量调试时间。

3.2 表格模块的公式与依赖计算

表格模块支持基础公式，比如求和、平均值、计数。公式以字符串形式存储，比如=SUM(A1:A10)。计算时先解析公式，提取依赖的单元格范围，然后按依赖顺序求值。这里我用的是简单的拓扑排序，因为表格公式一般不会太复杂，没必要上完整的电子表格计算引擎。

依赖计算的关键是循环引用检测。如果A1的公式引用了B1，B1的公式又引用了A1，就得报错。我的做法是在求值前先构建依赖图，用深度优先搜索检测环，检测到环就把涉及的单元格标记为错误值，并在界面上高亮提示。

单元格值的类型我做了区分：数字、文本、布尔、错误、空。公式计算时按类型做隐式转换，比如文本加数字，文本能转数字就转，转不了就返回类型错误。这套规则和主流表格软件基本一致，用户不会感到陌生。

3.3 演示稿的幻灯片对象结构

每张幻灯片是一个对象，包含id、layout、elements三个字段。layout决定占位符的位置和数量，比如“标题加内容”“两栏对比”“纯图片”。elements是元素数组，每个元素有类型、位置、尺寸、内容。

元素定位我用的是相对坐标，左上角为原点，宽高按百分比算。这样换不同尺寸的屏幕或导出不同比例的图片时，布局不会乱。智能体添加元素时只需要指定相对位置，不用关心绝对像素。

演示稿和文档、表格共享同一套智能体工具接口，但工具集不同。比如演示稿有addSlide、setSlideLayout、addElementToSlide，文档有insertParagraph、applyStyle。规划器根据当前打开的文件类型选择对应工具集，这个切换对用户透明。

4. 实操过程与核心环节实现

4.1 环境搭建与项目初始化

先装Node.js，版本建议18以上，因为要用到一些较新的API。然后初始化项目，我用的包管理工具是pnpm，比npm快且省磁盘。初始化命令是pnpm init，然后装核心依赖：Electron、React、TypeScript、Vite。Vite负责开发时的热更新，Electron负责桌面壳。

目录结构我按功能切分：src/main放Electron主进程代码，src/renderer放React应用，src/agent放智能体编排逻辑，src/document放文档能力层，src/shared放共享类型定义。这个结构清晰，新人接手能快速定位代码。

TypeScript配置里我开了严格模式，strict设为true，noImplicitAny也设为true。刚开始写会有点痛苦，但能避免大量运行时错误，尤其是智能体生成的参数类型不对时，编译期就能发现。

4.2 智能体调度循环的代码实现

调度循环的核心是一个异步函数，接收用户指令，返回执行结果。伪代码逻辑如下：先获取当前文档摘要，调用规划器生成步骤列表，然后遍历步骤，逐个调用执行器，每次调用后把结果追加到观察历史，再判断是否需要重新规划。

规划器的提示词模板我调了很多版，最终稳定下来的结构是：系统角色说明、可用工具列表、当前文档摘要、历史观察记录、用户指令、输出格式要求。输出格式要求规划器返回JSON数组，每个元素包含工具名和参数。这个格式约束很重要，不约束的话规划器会返回自然语言，解析起来很麻烦。

执行器调用工具时要做参数校验，校验失败不抛异常，而是返回错误对象。规划器看到错误对象后，会尝试修正参数重新调用。我设了最大重试次数，默认3次，超过就终止任务并提示用户。这个重试机制能解决大部分参数格式问题。

4.3 文档操作的原子工具实现示例

以insertParagraphAfter为例，输入是参考段落ID和新段落内容，输出是新段落ID。实现步骤是：先根据参考段落ID找到索引，然后在索引加一的位置插入新段落对象，最后返回新段落ID。插入前要校验参考段落ID是否存在，不存在就返回错误。

再以setCellValue为例，输入是工作表名、单元格地址、值，输出是操作结果。实现时要先解析单元格地址，比如B3解析成行2列1，然后检查行列是否越界，越界返回错误。设置值后要触发依赖重算，把受影响的公式单元格重新求值。

每个工具函数我都写了单元测试，覆盖正常路径和边界情况。测试用Vitest，跑起来很快。智能体逻辑的测试比较麻烦，我用的是模拟规划器，预设固定的步骤列表，验证执行器能正确调用工具并处理返回值。

4.4 界面与智能体的联动

界面上有个指令输入框，用户输入后按回车触发智能体调度。调度过程中界面显示进度指示，每一步完成后更新状态文字，比如“正在分析文档结构”“正在插入段落”“正在调整样式”。这些状态文字来自执行器的观察结果，用户能看到智能体在做什么。

文档修改后界面实时刷新，因为文档数据模型是响应式的，工具函数修改数据后React组件自动重渲染。这个联动是双向的：用户手动编辑文档后，文档摘要会更新，下次智能体调度时能看到最新状态。

撤销重做我基于操作历史实现，每次工具调用前记录文档快照，撤销时回滚到上一个快照。快照用结构化克隆存储，避免引用共享导致的状态污染。这个机制对智能体操作尤其重要，因为智能体可能连续做多个修改，用户想撤销时得能一步步回退。

5. 常见问题与排查技巧实录

5.1 智能体不按预期调用工具

最常见的问题是规划器选错工具。比如用户说“把这段文字放大”，规划器可能选了setFontSize，但当前文档能力层根本没这个工具，只有applyStyle。排查方法是看规划器输出的工具名是否在可用工具列表里，不在的话就是提示词里的工具描述不够清晰。

我的解决经验是：工具描述里一定要写“什么时候用”，而不是“这个工具做什么”。比如applyStyle的描述写成“当用户想改变文字外观（大小、颜色、粗细）时使用此工具”，比“设置文字样式”有效得多。另外在提示词里加一句“只能使用下列工具，不得虚构工具名”，能显著减少幻觉。

还有一种情况是参数格式不对。比如段落索引应该是数字，规划器返回了字符串“2”。执行器的参数校验会拦截这种错误，返回错误信息“参数index类型应为number”。规划器看到错误后一般能自我修正。如果反复修正不了，就在提示词里加参数示例，比如“index: 2（数字，不是字符串）”。

5.2 文档操作后界面不更新

这个问题的根源通常是数据模型改了但没触发响应式更新。排查时先看工具函数是否直接修改了对象属性，如果是，React检测不到变化。解决方法是改用不可变更新，每次修改都创建新对象，或者用状态管理库的更新方法。

另一个可能原因是工具函数在异步回调里修改数据，而React的批处理机制导致更新被合并。我的做法是在工具函数里用flushSync强制同步更新，或者把修改操作放在微任务里。实测下来，文档操作这种低频修改用flushSync完全没问题，不会影响性能。

如果界面部分更新部分不更新，那多半是组件拆分粒度问题。比如段落组件用了React.memo，但比较函数没写对，导致应该更新的段落被跳过。检查memo的比较函数，确保它比较了所有影响渲染的字段。

5.3 公式计算结果不对

先检查依赖范围是否正确。比如=SUM(A1:A10)，如果实际数据在A1到A9，A10是空，结果应该一样。但如果A10有文本，SUM会忽略文本，结果还是对的。问题往往出在范围写错，比如写成了A1:A100，把无关单元格也算进去了。

再检查循环引用。如果公式引用了自己所在的单元格，或者间接引用了自己，就会形成环。我的实现里会检测环并标记错误，但有时候环比较隐蔽，比如A1引用B1，B1引用C1，C1又引用A1。排查方法是看错误单元格的依赖链，顺着链找环。

还有一种情况是类型转换不符合预期。比如=A1+B1，A1是文本“3”，B1是数字4，结果是7还是“34”？我的实现是尝试把文本转数字，转成功就做加法，转失败就返回类型错误。这个规则要在文档里写清楚，避免用户困惑。

5.4 智能体任务执行到一半卡住

卡住的原因通常是规划器陷入了循环，反复生成相同的步骤。排查方法是看观察历史，如果连续几步的工具名和参数都一样，就是循环了。我的处理是设置最大步骤数，默认20步，超过就终止并提示用户“任务过于复杂，请拆分成多个指令”。

另一个原因是工具调用超时。比如某个工具函数里有网络请求或大量计算，执行时间过长。我给每个工具调用设了超时时间，默认5秒，超时就返回错误，让规划器决定是否重试。对于确实耗时的操作，比如全文档重算公式，我会把它拆成多个小步骤，每步处理一部分。

还有一种情况是规划器返回了空步骤列表，表示任务已完成，但实际文档没变化。这通常是规划器误判，以为不需要操作。排查时看规划器的推理过程，如果它说“文档已符合要求”，但实际不符合，就是文档摘要没传对。检查摘要生成逻辑，确保它反映了文档的真实状态。

5.5 常见问题速查表

提示：排查智能体问题时，先把规划器的输入输出完整打印出来，包括提示词、模型返回、执行器观察结果。大部分问题看一遍日志就能定位，比盲目改代码高效得多。

6. 扩展方向与个人实操体会

这套东西做完之后，我最大的体会是：智能体的能力上限不取决于模型多强，而取决于工具设计得多好。同样的模型，工具描述清晰、参数约束严格、返回值规范，任务成功率能差出一大截。我试过用同一套模型，只改工具描述，成功率从六成提到八成五。所以如果你也在做类似项目，别急着换模型，先把工具层打磨好。

扩展方向上，我目前想到几个。一是加协作功能，多个智能体分别负责文档、表格、演示，通过消息队列通信，完成跨文档的复杂任务。二是加模板系统，用户保存常用文档结构，智能体根据模板填充内容。三是加版本对比，智能体每次修改后生成diff，用户可以选择性接受或拒绝。这几个方向都不需要改核心架构，在现有分层上叠加即可。

最后分享一个小技巧：调试智能体时，把温度参数调到0，让模型输出尽量确定。等流程跑通了，再适当调高温度增加灵活性。我一开始没注意这个，温度设了0.7，规划器每次生成的步骤都不一样，排查问题特别费劲。调到0之后，同样输入基本同样输出，调试效率高了很多。