AI驱动的智能办公桌面应用：从意图到可审阅变更的办公新范式

1. 项目概述：当AI成为你的办公协作者

如果你和我一样，每天都要和Word、Excel、PPT打交道，那你一定经历过这样的时刻：为了统一一份报告的格式，手动调整几十个标题的样式；为了做一份PPT，在找图、排版、写文案之间反复横跳；或者，面对一份复杂的数据表格，需要花大量时间才能理清头绪。传统的办公软件，本质上是一个“手动操作”的工具，我们得自己点开每一个菜单，执行每一个动作。

最近几年，AI写作助手层出不穷，但它们大多停留在“聊天框”里。你告诉它要写什么，它生成一段文本，然后你得自己复制、粘贴、调整格式。这个过程是割裂的，AI就像一个在黑箱里工作的神秘写手，你无法精确控制它对文档的修改，也无法直观地看到它到底改了哪里。更重要的是，它对你的工作环境——你电脑里那些散落的文件、文件夹——一无所知。

“智启文档”（Word-Cursor）这个项目，正是为了解决这些痛点而生的。它不是一个简单的AI聊天插件，而是一个AI驱动的智能办公桌面应用。它的核心目标，是把类似Cursor编辑器那种“对话式编程”的体验，完整地带入到文档、表格和演示文稿的生产场景中。简单来说，它让你能用自然语言指挥AI，直接在你的真实文件上工作，并且每一步修改都清晰可见、可控可审。

想象一下这个场景：你打开一个文件夹作为工作区，AI能理解这个文件夹里所有文件的内容和关系。你可以选中一段文字，告诉AI“把这段改得更正式一点”，AI的修改会以高亮差异（diff）的形式呈现，你可以逐条接受或拒绝。你可以让AI基于一份文档大纲，直接生成一套风格统一的PPT，并且对不满意的页面说“这一页重做，风格更简洁”。你甚至可以让AI联网搜索最新资料，并把搜索结果整理、引用到你的报告中。这一切，都在一个集成了编辑器、文件管理和AI能力的桌面应用里完成。

这个项目适合所有需要高效处理文档的从业者，无论是经常撰写报告、公文的行政人员，需要制作大量演示材料的产品经理和销售，还是需要进行数据整理和分析的运营人员。它降低了使用AI辅助办公的门槛，将AI从一个“文本生成器”变成了一个“可审阅、可协作的工作流执行器”。接下来，我将为你深入拆解这个项目的设计思路、核心实现以及我踩过的一些坑，希望能为你带来启发。

2. 核心设计思路：从“编辑器”到“工作流执行器”

传统的文档处理流程是线性的、手动的：打开文件 -> 手动编辑 -> 保存。AI的介入，如果只是作为一个外挂的文本生成器，实际上增加了一个“生成->复制->粘贴->调整”的环节，流程反而更复杂了。Word-Cursor的设计哲学，是重新定义人机协作的范式，将AI深度嵌入到工作流中，形成闭环。

2.1 范式升级：意图驱动 vs. 操作驱动

旧范式（操作驱动）：用户思考 -> 用户手动执行UI操作（点击按钮、拖拽、输入）-> 软件响应。在这个范式下，AI是外部的、辅助性的。

新范式（意图驱动）：用户描述意图（自然语言）-> AI理解意图并规划任务 -> AI调用工具（编辑器、文件系统、搜索）执行 -> 结果以可审阅的变更集呈现 -> 用户确认。在这个范式下，AI是内置的、主导工作流的协作者。

Word-Cursor就是这个新范式的实践。它的系统架构清晰地体现了这一点。应用分为两大核心部分：Electron主进程和React渲染进程。渲染进程负责所有用户界面的展示，包括文档编辑器、聊天面板、文件树。而所有需要操作系统底层能力或执行重型、异步任务的操作，如读写本地文件、调用Brave搜索API、执行PPT生成和图片处理，都放在Electron主进程中完成。两者通过Electron IPC（进程间通信）进行数据交换。

注意：这种架构选择至关重要。将文件IO、网络请求等可能阻塞或涉及敏感权限的操作放在主进程，不仅更安全（遵循最小权限原则），也保证了UI的流畅性。浏览器（Web）模式之所以功能受限，正是因为它无法直接访问这些系统级能力。

2.2 “可审阅变更”是信任的基石

直接让AI“黑盒式”地修改你的重要文档，是令人不安的。因此，“可审阅的变更”（Reviewable Changes）成为了整个体验的核心。这不仅仅是技术实现，更是产品设计上的关键决策。

其工作流程如下：

1. 用户发起指令：通过聊天输入或快捷键（Ctrl+K）对选中文本发出指令。
2. AI规划与执行：AI（大语言模型）理解指令，规划出需要对文档进行的操作序列（如：替换某段文字、调整某个标题格式、插入一个表格）。
3. 生成变更集：AI通过调用编辑器工具，计算出执行这些操作后文档的“新状态”，并与“旧状态”进行比对，生成一个结构化的变更集（Diff）。这个变更集不仅包含文本的增删改，在高级模式下还能包含格式变更。
4. 可视化呈现：变更集在UI上被渲染为高亮显示（通常删除线标红表示删除，背景标绿表示新增）。同时，一个“待确认修改”面板会列出所有变更。
5. 用户决策：用户可以逐一查看每条变更，理解AI的修改意图（有时AI会附带简短的修改理由），然后选择“接受”或“拒绝”。也可以一键“接受全部”或“拒绝全部”。

这个机制将控制权完全交给了用户，AI从“自作主张的执行者”变成了“提出建议的协作者”，极大地降低了心理门槛和使用风险。在我自己的使用中，这个功能让我敢于对更长的文档、更复杂的指令放手让AI尝试，因为我知道我有最终的否决权。

2.3 以“工作区”为中心的上下文管理

大多数AI助手缺乏“上下文”。它们通常只关注当前聊天窗口里的内容。Word-Cursor引入了“工作区”（Workspace）的概念。你可以打开本地任意一个文件夹作为工作区，应用左侧会显示文件树。

这样做的好处是革命性的：

• 文件感知：AI在为你工作时，可以引用工作区内其他文件的内容。例如，你可以说“参考市场分析.docx里的数据，更新当前报告中的Q3预测部分”。
• 跨文档操作：你可以让AI总结工作区内所有.txt文件的内容，或者将多个Excel表格的数据合并分析。
• 拖拽即上下文：你可以直接将工作区里的文件拖拽到聊天输入框，AI会自动读取其内容作为补充上下文，无需你手动复制粘贴。

这模拟了真实的工作场景——我们的工作成果很少是孤立的单个文件，而是一组相互关联的项目文件。工作区概念让AI真正融入了你的生产环境。

3. 核心模块深度解析与实操要点

3.1 文档编辑：不止于富文本

Word-Cursor的文档编辑器基于Tiptap（构建在ProseMirror之上），这是一个功能强大且扩展性强的富文本编辑器框架。但它的目标不仅仅是做一个网页版Word，而是要成为AI驱动的编辑平台。

3.1.1 打印布局与格式保留为了让编辑体验更贴近最终输出（如打印或生成PDF），编辑器实现了打印布局（A4）预览模式。这不仅仅是加一个白色背景，它模拟了页边距、分页，并支持Ctrl+滚轮缩放。这对于撰写正式报告、论文等对排版有要求的文档非常实用。

一个关键挑战是格式保留。当用户选中一段已有格式（如加粗、红色、特定字体）的文字，并要求AI修改时，AI的回复通常是纯文本。如何让AI的修改“继承”原有格式？这里的实现策略是：

1. 获取选区时，同时捕获该选区对应的HTML片段及其样式信息。
2. 将用户指令和这段带样式的HTML（或一个简化表示）一同发送给AI，并在指令中明确要求“尽量保留原格式”。
3. AI返回修改后的内容。系统会尝试将新内容“套用”回原有的HTML结构，或进行智能的样式匹配。对于无法自动匹配的情况，变更集会包含格式调整建议，由用户在审阅时确认。

3.1.2 文档审查（/审查命令）这是一个极具价值的“杀手级”功能。输入/审查，AI会通读全文，从五个维度进行诊断：

1. 语法语病：错别字、病句、标点误用。
2. 逻辑连贯：段落衔接是否生硬，论述是否前后矛盾。
3. 措辞专业性：用词是否准确、得体，是否符合文体（如公文、学术、商务）。
4. 格式规范：标题层级是否清晰，列表、引用等格式是否统一。
5. 事实核查（基础版）：对文中提及的明显可验证的事实（如日期、数字矛盾）提出疑问。

审查结果会以分类徽章（如[语法]、[逻辑]）的形式呈现在修订面板中，每条建议都附带原因。这比普通的语法检查器更深入，因为它结合了语义理解。例如，它可能指出“此处使用‘综上所述’略显突兀，因为上文并未进行充分的总结性论述”，这是纯规则检查做不到的。

实操心得：对于重要文档，我习惯先让AI自由创作或我自己撰写初稿，然后使用/审查命令进行一遍深度“体检”。接受那些显而易见的语法和错别字修改，对于逻辑和措辞建议，则结合自己的判断进行选择性采纳。这个过程能极大提升文档的最终质量。

3.2 PPT端到端生成与编辑：从想法到幻灯片

这是项目中最复杂、也最体现AI集成深度的功能。它不是一个简单的“文本转PPT”工具，而是一个完整的、可干预的生成流水线。

3.2.1 生成流水线拆解

1. 大纲结构化：用户用自然语言描述PPT需求（如“做一个关于新能源汽车市场趋势的PPT，共10页，风格现代科技感”）。AI首先将其转化为一个结构化的JSON大纲，明确每一页的类型（封面、目录、内容、总结）、标题、要点和布局意图。
2. 视觉提示词生成：系统将每一页的结构化信息（标题、要点）发送给Gemini（通过OpenRouter API），由Gemini生成针对该页内容的、详细的图像生成提示词（Image Prompt）。这个提示词会描述画面风格、构图、元素、色调等。例如，对于“市场趋势”页，可能生成“A clean, futuristic dashboard chart showing upward trend lines against a dark blue gradient background, with minimalistic icons representing technology and growth.”
3. 图像生成与后处理：上一步生成的提示词被发送给**通义万相（DashScope）**的图像生成模型（如qwen-image-plus）。生成的原始图片会经过后处理（使用sharp库），进行尺寸统一、去除黑边、优化压缩等操作，以适应PPT幻灯片。
4. PPTX打包：使用pptxgenjs库，将处理好的图片和对应的文本（标题、要点）按照预设的版式布局，组装成真正的.pptx文件。文本的字体、颜色、位置都根据选择的风格主题（如“Midnight Pro”、“Swiss International”）进行配置。
5. 文件保存：最终生成的.pptx文件通过Electron主进程保存到用户指定的工作区位置。

3.2.2 “整页重做”与“局部编辑”生成结果不满意怎么办？Word-Cursor提供了两种精修方式：

• 整页重做：告诉AI“第5页重做，风格更简洁，文字更突出”。系统会重新执行该页的提示词生成->生图->打包流程。这适用于整体都不满意的情况。
• 局部编辑：在PPT预览界面，按住Ctrl键拖拽鼠标，框选幻灯片上某个特定区域（如一个图标、一块图表）。然后在聊天框输入指令，如“把框选的图标换成扁平化设计，颜色改为蓝色”。系统会调用DashScope的图像编辑模型，仅对框选区域进行重绘，并将结果无缝替换回原幻灯片。这实现了像素级的精准控制。

避坑指南：PPT生成最常遇到的问题是“生图失败”或“风格不一致”。首先，确保你的OpenRouter和DashScope的API Key有效且额度充足。其次，在给AI的初始指令中，尽可能明确风格，例如直接说“使用Swiss International风格，信息密度中等”。如果某页反复失败，尝试简化该页的文字内容，过于复杂或密集的文字描述可能会超出图像模型的理解能力。最后，批量生成多页PPT时，网络超时或API限流可能导致部分页失败，此时可以针对失败的单页使用“整页重做”。

3.3 Excel预览与AI辅助分析

当前版本的Excel能力定位是“预览与AI辅助分析”，而非完全替代Excel。其核心价值在于，让AI能“看见”并理解你表格中的数据。

3.3.1 技术实现使用exceljs库在渲染进程中读取.xlsx或.xls文件，将工作表数据（单元格值、公式、部分格式）解析为JSON结构，并在前端用类似表格的UI渲染出来。这个“预览”是只读的，但数据已经加载到内存中。

3.3.2 典型工作流

1. 打开表格：在工作区打开一个Excel文件，AI会自动感知到文件内容（可以设置为自动发送文件摘要到聊天上下文）。
2. 提问与分析：你可以直接向AI提问：“这个表格第三列数据的平均值是多少？”、“找出销售额超过10万的所有行，并总结一下他们的共同特点。”、“根据B列和C列的数据，生成一个简要的趋势分析报告。”
3. 数据提取与格式化：你可以指令AI：“把‘状态’为‘已完成’的所有项目名称和负责人提取出来，整理成Markdown列表。”AI会解析数据，并返回结构化的结果。
4. 生成解释与建议：对于复杂的表格，你可以让AI解释其结构：“这个表格看起来是财务报表，请解释‘流动资产’和‘非流动资产’下面这些子项分别代表什么。”或者“基于这个数据，你觉得用哪种图表展示最合适？”

注意事项：由于是预览模式，AI无法直接修改原始Excel文件。但它生成的分析结论、提取的数据文本，你可以轻松复制，或通过对话让它将结果插入到一个新的Word文档中。对于简单的数据清洗或转换需求，你可以描述规则，让AI生成处理步骤说明甚至伪代码，指导你手动操作或后续自动化。

3.4 联网搜索与信息整合

项目内置了Brave Search MCP Server，这是一个强大的功能。MCP（Model Context Protocol）是一种让AI模型安全、结构化地使用外部工具（如搜索、计算器、数据库）的协议。内置意味着搜索能力被深度集成，无需你额外启动一个服务。

3.4.1 工作流程

1. 用户在对话中提出需要联网查询的需求，例如“搜索2024年人工智能在医疗领域的最新突破”。
2. AI识别该意图，通过IPC调用主进程中的Brave Search工具。
3. 主进程使用配置的Brave Search API Key发起搜索请求。
4. 搜索结果以结构化的形式（包含网页标题、URL、摘要、有时还有新闻、视频、FAQ分类）返回给AI。
5. AI综合这些信息，生成一个带有引用来源的总结性回答。
6. 用户可以进一步要求AI将这些信息整理并写入正在编辑的文档中。

3.4.2 与普通搜索插件的区别普通搜索插件可能只是把搜索结果罗列出来。而在这里，搜索是工作流的一部分。AI不仅获取信息，还会理解、筛选、整合，并最终作用于你的产出物（文档）。例如，你可以说：“搜索关于‘远程办公效率’的近期研究，找出三个核心观点和对应的论文来源，然后以‘参考文献’的形式添加到我的报告末尾。”AI会完成从搜索、分析到格式化的全过程。

安全提示：联网搜索引入了外部不可信内容。项目的最佳实践是，不要让AI直接“阅读”整个网页的原始HTML（可能包含恶意脚本或无关噪音），而是基于Brave Search返回的结构化摘要进行工作。这既提高了效率，也降低了提示词注入（Prompt Injection）或引入不相关内容的风险。在设置中，务必使用自己的Brave Search API Key，并注意用量。

4. 从零开始的部署、配置与深度使用指南

4.1 环境准备与两种运行模式

首先，确保你的开发环境符合要求：Node.js >= 18，npm >= 9。克隆项目后，npm install安装依赖。

这里你必须理解两种运行模式的本质区别，这决定了你能用什么功能：

• 桌面端模式 (npm run dev:electron)：这是完整功能模式。它启动了Electron应用，包含了主进程和渲染进程。只有在这个模式下，你才能使用：

  • 本地文件系统操作（工作区、打开/保存文件）。
  • 内置的Brave搜索（MCP Server在主进程运行）。
  • PPT的端到端生成、编辑和打包。
  • ONLYOFFICE编辑器集成。
  • 完整的本地补全（Tab键续写）体验。
  • 结论：为了体验所有功能，务必使用此模式。

• Web模式 (npm run dev)：这仅启动Vite开发服务器和React前端。它主要用于UI和交互逻辑的开发调试。在此模式下，所有依赖Electron主进程的功能都将失效或回退。例如，点击“打开工作区”会无反应，PPT生成会报错。如果你只想修改前端界面样式或组件逻辑，可以用此模式加快热重载速度。

4.2 核心配置详解：避开第一个大坑

配置是项目运行的前提，错误配置是新手最常见的问题。所有配置都在应用右上角的设置面板中完成，它会自动保存到本地。你也可以使用根目录下的.env文件（参考.env.example）进行配置，但UI设置的优先级更高。

4.2.1 主模型配置（必需）这是驱动所有AI对话和文档编辑能力的引擎。

• API Key & Base URL：项目兼容任何提供OpenAI格式API的服务。这意味着你可以使用：
  • 官方OpenAI API。
  • Azure OpenAI。
  • 各类第三方代理网关（如你提供的链接）。
  • 本地部署的Ollama、LM Studio等（需其服务端提供兼容OpenAI的接口）。
• 如何配置：在“主模型”设置栏，填入你的API Key。在“Base URL”中填入对应的接口地址，例如第三方网关可能是https://api.xxx.com/v1，本地Ollama则是http://127.0.0.1:11434/v1。最后，在“Model”中填入模型名称，如gpt-4o、claude-3-5-sonnet或本地模型名。

4.2.2 PPT生成配置（强烈建议）PPT生成依赖两个外部服务：

1. OpenRouter API Key：用于调用Gemini模型，将每页PPT的文字内容转化为富有想象力的视觉描述提示词。没有它，AI就无法生成高质量的图片提示。
2. DashScope (阿里云百炼) API Key：用于调用通义万相模型，根据上一步的视觉提示词生成图片，并进行局部编辑。没有它，PPT生成流程会中断。

4.2.3 Brave搜索配置（可选但推荐）在设置中找到“联网搜索”项，填入你的Brave Search API Key。获取后，你就能在对话中直接使用联网能力。这是区别于其他纯本地文档工具的核心优势之一。

4.2.4 本地补全配置（可选）如果你有本地运行的大模型服务（如Ollama运行了qwen2.5:7b），并开启了其兼容OpenAI的API，可以在这里启用“本地补全”。设置好服务地址（如http://127.0.0.1:11434/v1）和模型名后，在编辑文档时按Tab键，就会尝试用本地模型进行低延迟的续写。这适合对隐私要求高、或需要快速简单补全的场景。

配置避坑清单：

1. 主模型必配：不配置主模型，整个AI功能都无法使用。
2. PPT生成需双Key：只想用Word和Excel，可以不配OpenRouter和DashScope。但要用PPT，两者缺一不可。
3. Key的安全存放：切勿将填有真实Key的.env文件上传至Git等公开仓库。使用.env.example模板，并将其加入.gitignore。
4. 网络问题：如果使用海外API（如OpenAI官方），确保网络通畅。使用国内网关或本地模型可避免此问题。

4.3 典型工作流实战演练

理解了配置，我们来模拟几个真实的工作流，看看如何最大化利用这个工具。

工作流A：撰写一份可交付的项目复盘报告

1. 启动与准备：运行npm run dev:electron，打开一个专门的项目文件夹作为工作区。
2. 新建文档：在文件树右键，新建项目复盘报告.docx。
3. 构思大纲：在聊天框输入：“我需要撰写一份关于‘智慧园区物联网平台’项目的季度复盘报告。请先为我生成一个包含8-10个小节的详细目录大纲，每小节列出3-5个核心要点。要求结构严谨，涵盖项目回顾、成果数据、问题分析、经验总结、下一步计划。”
4. 审阅与确认：AI生成大纲后，你可以在“待确认修改”面板中浏览。如果整体满意，点击“接受全部”，大纲就会插入文档。
5. 分步扩写：对AI说：“现在，请根据这个大纲，首先详细扩写‘一、项目概述与目标回顾’这一节。保持正式、客观的商务报告文风，数据部分用占位符[待补充]标注。” AI写完一节，你审阅并接受。
6. 迭代与精修：重复步骤5，直到所有章节完成。过程中可以随时指令：“将第三节‘成本分析’中的‘超支’一词，替换为更中性的‘超出预算’，并分析主要原因。”
7. 最终格式化：全文完成后，输入：“请将整份报告统一格式：一级标题黑体三号居中，二级标题黑体四号左对齐，正文宋体小四，1.5倍行距。并生成一份300字的执行摘要，置于文档开头。”
8. 最终审查：输入/审查命令，让AI进行最终校对，处理可能遗留的语法、逻辑和格式问题。

工作流B：从零生成一套产品发布会PPT

1. 准备内容：可以先在Word里写好发布会演讲的核心要点，或直接向AI描述。
2. 生成大纲：输入：“基于以下核心信息，生成一份12页的产品发布会PPT大纲，风格要求‘Midnight Pro’（暗夜高级质感），信息密度适中。核心信息：[你的产品介绍、亮点、数据、愿景]”。让AI输出严格的JSON大纲。
3. 确认与调整：仔细审查AI生成的每页标题和要点，确保逻辑连贯。如果对某一页不满意，可以指令调整：“将第4页‘技术架构’的布局意图改为‘图文左右分栏’，左边放架构图描述，右边放核心优势列表。”
4. 开始生成：确认大纲后，对AI说：“好的，请根据这个大纲和‘Midnight Pro’风格，开始生成PPT。” 此时，系统会开始调用Gemini和DashScope API，依次生成每一页的图片并打包。这个过程可能需要几分钟，请耐心等待。
5. 精修与编辑：生成完成后，在PPT预览器中浏览。如果发现第7页的配图与内容不符，可以框选该图片区域，然后输入：“将框选的图片替换为更能体现‘数据流通’概念的抽象科技感图片，保持暗色调。”
6. 导出与备用：满意的PPT可以直接从应用内保存到工作区。为了兼容性，你也可以在生成后，用Microsoft PowerPoint或WPS打开进行最后的微调。

工作流C：快速处理与分析调研数据表格

1. 打开表格：在工作区打开收集到的用户调研反馈.xlsx。
2. 初步探索：问AI：“这个表格有哪些列？大致描述一下前5行的数据内容。” AI会解析表头和数据样例。
3. 数据清洗：指令：“查看‘满意度评分’这一列，找出所有评分低于3的数据行，并将这些行的‘用户ID’和‘反馈摘要’列提取出来，整理成一个新的Markdown表格。”
4. 洞察分析：指令：“根据‘年龄段’和‘产品功能’这两列，分析不同年龄段的用户最关注哪些功能，用文字描述主要发现。”
5. 生成报告片段：最后，让AI将上述分析和提取的关键问题，整理成一段文字，你可以直接插入到最终的调研报告文档中。

4.4 高级技巧与快捷命令

除了常规对话，系统内置了一些快捷命令（以/开头），能快速触发特定工作流：

• /审查//校对：如前所述，进行深度文档审查。
• /润色：优化文档表达，使其更流畅、专业。
• /精简：删除冗余内容，保留核心信息。
• /翻译 [目标语言]：例如/翻译 英文，将选中内容或全文翻译成指定语言。
• /格式化：快速将杂乱格式统一为默认或指定格式。
• /编号：为文档中的所有标题自动添加多级编号（如1., 1.1, 1.1.1）。
• /公文：将文档调整为公文体裁（用语、格式）。
• /会议纪要：将零散的要点整理成结构化的会议纪要格式。

高效使用心法：

1. 意图具体化：给AI的指令越具体，结果越可控。不要说“改一下”，而要说“将语气调整为面向高层汇报的正式口吻，并突出项目风险部分”。
2. 善用选区：先选中一段文字再按Ctrl+K或右键，AI会默认针对这段选区操作，上下文更清晰。
3. 分步进行：对于复杂任务，拆解成“生成大纲->确认->扩写第一节->审阅->...”的步骤，比一次性要求AI写万字长文更容易控制质量。
4. 审阅是关键：不要盲目接受所有修改。养成审阅的习惯，尤其是对关键数据和重要结论的修改。

5. 架构设计与技术栈深度剖析

要真正理解这个项目，甚至进行二次开发，我们需要深入其技术架构。它不是一个简单的“前端+API”应用，而是一个精心设计的、分层清晰的桌面AI应用。

5.1 前后端分离的Electron架构

项目采用了经典的Electron架构：一个主进程（Main Process）和多个渲染进程（Renderer Process）。但它的设计亮点在于对职责的清晰划分和模块化。

5.1.1 主进程：系统服务与重型任务枢纽主进程（electron/目录）是应用的后台引擎，负责所有需要系统权限或计算密集型的操作。它被进一步拆分为多个服务模块，这是一种高内聚、低耦合的优秀实践：

• services/files：文件系统操作（读写、监听、工作区管理）。
• services/excel/services/ppt：专门处理Excel和PPT文件的解析、生成、编辑逻辑。
• services/ai-proxy：作为AI API调用的代理层，统一处理请求、错误和日志。
• services/web-search：封装Brave Search MCP Server的调用。
• services/memory：管理工作区上下文、对话历史等记忆功能。
• ipc/：定义了主进程与渲染进程之间所有的IPC通信通道（window.electronAPI.*）。这种集中管理的方式让通信协议清晰可维护。

5.1.2 渲染进程：用户交互与状态管理渲染进程（src/目录）基于React + TypeScript + Vite构建，负责所有用户界面。

• 编辑器核心：使用Tiptap构建富文本编辑器。Tiptap基于ProseMirror，提供了强大的文档模型和变更追踪能力，这正是实现“可审阅diff”的基础。通过其扩展系统，实现了标题、列表、表格、图片等所有富文本功能，以及打印布局等自定义渲染。
• 状态管理：复杂的应用状态（如当前文档内容、聊天历史、工作区文件树、AI设置、待确认的修改列表）需要统一管理。项目可能使用了Context API、Zustand或类似的状态管理库来保持UI同步。
• 组件化：将聊天面板、文件树、编辑器、设置面板、修订面板等拆分为独立组件，通过清晰的Props和事件进行通信。

5.1.3 IPC通信：进程间的桥梁所有从UI发起的、需要主进程能力的操作，都通过IPC进行。例如：

• 前端点击“打开工作区” -> 调用window.electronAPI.openDirectory-> 主进程打开系统文件夹选择对话框 -> 返回路径 -> 前端更新文件树。
• 前端请求生成PPT -> 发送大纲数据到主进程 -> 主进程调用AI服务、生图、打包 -> 返回生成的文件路径或进度。 这种设计确保了UI的响应性，即使AI生成图片或搜索网络需要较长时间，UI也不会卡死。

5.2 Agent运行时与工具调用

src/agent/目录是项目的“大脑”，它实现了AI Agent的运行时逻辑。这不是一个简单的API调用封装，而是一个完整的工具调用（Tool Calling）框架。

• Provider适配层：抽象了不同AI服务提供商（OpenAI兼容接口、Azure等）的差异，提供统一的调用接口。
• 工具注册与执行器：所有AI可以调用的“工具”（如edit_document,search_web,generate_ppt_slide）在这里注册。当AI模型决定要调用某个工具时，执行器会解析参数，调用对应的实际函数（这些函数可能在前端，也可能通过IPC调用主进程服务）。
• 技能与子代理：将复杂任务分解为“技能”（Skills），例如“文档审查”可能由“语法检查”、“逻辑分析”、“格式校验”等多个子技能组合而成。子代理（Subagents）可以专门处理特定类型的任务。
• 上下文管理与压缩：AI模型有上下文长度限制。Transcript/Replay存储模块负责管理冗长的对话历史和文档上下文，并可能采用智能的压缩策略（如总结之前的对话、只保留相关片段）来节省Token，降低成本并提升效率。

5.3 文档处理与格式转换

办公文档的核心是格式。项目需要处理.docx,.xlsx,.pptx三种主流格式。

• DOCX处理：使用mammoth.js将.docx文件转换为HTML，以便在Tiptap编辑器中渲染和编辑。反过来，当需要保存时，需要将编辑器中的HTML（或ProseMirror JSON）再转换回.docx。这个过程涉及样式映射（如CSS样式到Word样式）、图片嵌入等复杂问题。docx库用于程序化生成和修改DOCX文件。
• PPTX生成：如前所述，使用pptxgenjs。挑战在于将AI生成的视觉概念和文本内容，动态地、美观地布局到每一页幻灯片上，并保持整体风格一致。这需要一套预设的版式模板和灵活的布局算法。
• Excel预览：使用exceljs读取文件。挑战在于高效地解析可能包含大量数据的工作表，并在前端以可滚动、性能良好的方式渲染。目前项目侧重于数据读取和展示，为AI提供分析上下文。

5.4 可选集成：ONLYOFFICE与Scrapeless MCP

为了提供更强大的扩展性，项目设计了可选的集成路径。

• ONLYOFFICE Document Server：这是一个开源的、功能强大的在线文档编辑器套件，几乎完全兼容MS Office。当用户需要处理极其复杂的排版、公式、或需要接近原生Office的协作体验时，可以切换到ONLYOFFICE编辑器模式。这需要用户在本地通过Docker运行一个ONLYOFFICE服务。项目通过iframe或API的方式集成该编辑器，实现了“重型编辑”能力的按需加载。
• Scrapeless MCP Server：这是一个独立的、遵循MCP协议的服务，专注于网页自动化和抓取。它可以处理JavaScript渲染的动态页面，执行点击、滚动、表单填写等操作，并将结果（HTML、Markdown、截图）返回。虽然Word-Cursor主程序内置了Brave搜索，但Scrapeless提供了更强大的、可编程的网页交互能力。你可以将其作为一个独立的MCP Server运行，并与Cursor、Claude Desktop等其他AI客户端连接，为AI提供更丰富的“手和眼睛”。

6. 常见问题排查与实战经验

即使按照指南操作，在实际部署和使用中仍可能遇到问题。以下是我在深度使用和测试中总结的常见问题及解决方案。

6.1 启动与运行故障

问题：运行npm run dev:electron后白屏或功能无响应。

• 排查步骤：
  1. 检查Node版本：在终端输入node -v，确保版本≥18。
  2. 检查依赖：尝试删除node_modules文件夹和package-lock.json文件，然后重新运行npm install。网络不佳时，这个步骤可能失败或部分失败。
  3. 查看主进程日志：Electron启动时会打开两个窗口，一个是应用本身，另一个是主进程的控制台（通常是一个命令行窗口）。主进程控制台是排查问题的关键，任何API Key错误、服务连接失败、文件权限问题都会在这里打印。如果看不到这个窗口，可能是被隐藏了，检查任务栏或系统托盘。
  4. 简化环境：首次运行时，不要打开一个包含成千上万文件或深层次嵌套的文件夹作为工作区。先新建一个空文件夹测试，排除文件系统读取的潜在问题。
  5. 端口冲突：开发服务器默认占用某个端口（如5173），如果被其他程序占用会导致失败。可以尝试修改vite.config.ts中的端口配置。

问题：Web模式(npm run dev)可以运行，但Electron模式不行。

• 原因：这几乎可以肯定问题出在Electron主进程的代码或环境上。可能是某个原生模块（Native Module）编译失败，或者主进程代码中有语法错误。
• 解决：仔细查看主进程控制台的错误信息。常见于Windows环境，可能需要安装Windows Build Tools（npm install --global windows-build-tools）来编译原生依赖。

6.2 AI功能相关故障

问题：对话正常，但AI无法修改文档，或修改不显示diff。

• 排查：
  1. 检查编辑器状态：确认文档已成功加载，并且编辑器处于可编辑状态（不是只读预览）。
  2. 检查AI指令：指令是否明确？例如“修改这段文字”比“优化一下”更好。尝试一个最简单的指令，如“将‘你好’改为‘您好’”。
  3. 查看网络请求：打开开发者工具（Electron中按F12或Ctrl+Shift+I），切换到Network（网络）标签页。发起一个AI修改指令，观察是否有向你的AI服务商发起的请求，以及请求的响应是什么。如果请求失败，可能是API Key错误、余额不足、网络不通或服务端错误。
  4. 检查工具调用：在开发者工具的Console（控制台）中，查看是否有来自Agent运行时的错误日志，例如“Tool X not found”或“Invalid parameters”。

问题：PPT生成失败，提示“缺少API Key”或“生成超时”。

• 排查：
  1. 确认双Key：确保在设置中正确配置了OpenRouter和DashScope的API Key，并且都有可用额度。
  2. 查看详细错误：主进程控制台会打印PPT生成每一步的日志。查看是在“生成提示词”（Gemini调用）阶段失败，还是在“生图”（DashScope调用）阶段失败。
  3. 生图内容安全：图像生成模型有严格的内容安全策略。如果你的PPT大纲中包含可能被识别为敏感、暴力、侵权的内容，生图请求会被拒绝。尝试调整描述词，使其更中性、更抽象。
  4. 网络与超时：生成多页PPT时，连续调用API可能触发限流或遭遇网络波动。尝试先生成1-2页测试。项目代码中应考虑增加重试机制和更友好的超时提示。

问题：Brave搜索返回空结果或错误。

• 排查：
  1. Key有效性：在Brave搜索API官网验证你的Key是否有效、未过期。
  2. 查询语句：搜索查询最好使用英文关键词，并且尽可能具体。尝试一个简单的测试，如“latest news about NASA”。
  3. 网络代理：如果你身处网络受限环境，可能需要为Electron主进程配置代理才能访问Brave搜索API。这通常需要在代码中或系统环境变量中设置。

6.3 性能与体验优化

问题：编辑大型文档（超过50页）时，界面卡顿。

• 原因：Tiptap编辑器需要维护整个文档的ProseMirror状态树，非常大的文档会占用较多内存和计算资源。同时，实时渲染复杂的格式和差异高亮也会带来压力。
• 优化建议：
  • 虚拟滚动：考虑为编辑器实现虚拟滚动，只渲染视口内的文档部分。
  • 分块加载/处理：对于AI审查等操作，可以设计为分块进行，而不是一次性处理整个文档。
  • 简化Diff渲染：在文档极大时，可以暂时关闭或简化实时的高亮渲染，仅在用户需要查看时计算并显示差异。

问题：PPT生成速度慢。

• 分析：慢主要来自两方面：一是调用外部API（Gemini, DashScope）的网络延迟；二是图片后处理和PPTX打包的本地计算。
• 优化建议：
  • 并行化：如果API允许，可以尝试将多页PPT的提示词生成或图片生成请求并行发送，而不是串行等待。
  • 缓存：对于相同的提示词或相似的图片内容，可以考虑在本地进行缓存，避免重复生成。
  • 进度反馈：在UI上提供明确的进度指示（如“正在生成第3/10页...”），提升用户等待时的体验。

6.4 扩展与自定义开发建议

如果你希望基于此项目进行二次开发，这里有一些方向：

1. 接入更多AI模型：在src/agent/providers/下添加新的Provider，可以轻松接入国内外的其他大模型，如DeepSeek、智谱GLM、月之暗面Kimi等。
2. 增加新的工具：在工具注册表中添加新的工具函数。例如，添加一个search_internal_wiki工具，让AI可以查询你公司内部的知识库。
3. 支持更多文件格式：目前核心是Office三件套。可以扩展支持Markdown、PDF（解析）、图片（OCR后分析）等。
4. 强化工作区智能：实现更智能的工作区索引和记忆，让AI能基于你过往的所有文件进行学习和回答，打造真正的个人知识库AI助手。
5. 开发插件系统：设计一个插件架构，允许社区贡献新的AI技能、编辑器扩展或第三方服务集成。

这个项目为我们展示了一个未来办公软件的强大雏形：一个以意图驱动、以工作区为上下文、以可审阅变更建立信任的智能协作环境。它不仅仅是技术的堆砌，更是对生产力工具范式的重新思考。虽然它在处理极端复杂的专业排版或大型数据计算时仍有局限，但其展现出的方向和潜力，足以让我们对AI如何重塑日常办公充满期待。