开源Agent直接编辑Word/PDF/Excel：SurfSense设计解析

开源Agent新玩法：不聊天，直接产出可编辑文件

大多数AI助手停留在对话层面，而SurfSense选择了一条更硬核的路：你给它一个任务，它去检索你的文档、写出真实的Word、PDF、PPT和Excel文件，甚至能直接编辑你已有的文件。这个项目采用Apache-2.0协议，支持Windows、macOS和Linux，由维护者在Reddit上主动求反馈。

SurfSense在Reddit上的发布帖

据维护者描述，SurfSense的定位是“带Agent的NotebookLM”：模型可选本地模型、任何OpenAI兼容API，或者直接复用你的ChatGPT/Claude订阅计划。

Agent核心能力：检索、引用、写文件、改文件

从检索到成稿的闭环

Agent会先搜索并阅读你指定的资料源，在输出中标注引用了哪些段落。随后它直接生成Word文档、PDF、幻灯片、电子表格或网页，也能以你上传的.docx或.pptx为模板起步。

编辑原有文件，且不覆盖原件

更实用的能力是编辑你自己的文件：Word编辑以“修订模式+批注”返回，Excel会更新公式，PDF可填充表单。所有改动都作为新副本交付，原始文件永远不会被写入。这个设计对需要留痕的办公场景很关键。

通过MCP接入外部工具

Agent支持MCP插件，例如Notion、DeepWiki，或任何你通过URL添加的服务器。这让它能跨越本地文件的边界，调用外部知识源。

MCP（Model Context Protocol）是Anthropic于2024年11月提出的开放协议，用于标准化大模型应用与外部数据源、工具之间的连接方式。它采用客户端-服务器架构：宿主应用（如SurfSense）作为客户端，连接到提供特定能力的MCP服务器，服务器再暴露资源（resources）、工具（tools）和提示模板（prompts）三类原语。与传统的函数调用相比，MCP的关键价值在于互操作性——同一个MCP服务器可以被任意兼容的客户端复用，开发者无需为每个应用单独编写集成代码。协议基于JSON-RPC 2.0传输，支持本地stdio和远程HTTP/SSE两种连接方式，通过URL添加服务器正是后者的典型用法。

架构拆解：两个引擎、无Shell、文档即脚本

双引擎但同规则

SurfSense用opencode为所有模型驱动Agent；如果你使用Claude计划，则由你自己的Claude Code接管执行。两条路径共享同一套工具和规则。

opencode是近年兴起的开源终端AI编程Agent，主打“模型无关”的Agent运行时：它将工具调用、文件操作、会话管理等能力封装为统一接口，底层可切换任意支持工具调用的模型。Claude Code则是Anthropic官方推出的Agentic编程工具，深度绑定Claude模型并复用用户的订阅额度。SurfSense让二者共存的意义在于解耦：Agent的行为规则（可用工具集、审批策略、文档处理流程）定义在应用层，而执行引擎可以按用户已有的模型订阅灵活替换，从而避免被单一供应商锁定，也降低了用户的额外API成本。

刻意关闭Shell与代码执行

出于安全考虑，shell、代码执行、子Agent和网页访问都被关闭。Agent只能使用固定工具集：搜索、文档工具和PDF工具。这是一种用能力换可控性的取舍。

“文档即脚本”与自检循环

这是该项目最值得讨论的设计：Agent把每份文档写成一个脚本，SurfSense在独立进程中运行它，保留每个版本，并把页面预览回传给Agent，让它检查自己的输出并修正。

版本管理在此处指的是SurfSense为Agent生成的每一版文档脚本保留独立快照，而非依赖Git等外部工具。这种设计使Agent的每次修改都可追溯、可回滚，配合页面预览形成“生成—渲染—观察—修正”的闭环，本质上是一种视觉反馈驱动的自我纠错机制（self-refinement）。相较之下，让模型直接编辑二进制文档（如.docx）时，模型无法“看到”修改后的排版效果，错误往往难以自查。脚本化的代价是需要维护一套文档生成DSL及其运行时，且对复杂格式的还原度依赖该DSL的表达能力。

每个任务独立文件夹

每个对话拥有自己的文件夹，存放你所选资料源的文本，Agent可以直接读取和grep，而不只依赖搜索接口。

审批与模型门槛

你可以指定哪些插件工具可自由使用、哪些需要先询问。Agent模式要求模型支持工具调用且上下文至少32K；更小的模型仍可用于普通问答。

工具调用（tool calling / function calling）要求模型在生成文本之外，能输出结构化的函数名与参数，并理解工具返回结果后继续推理。这通常需要模型经过专门的指令微调，较小的模型往往不支持或表现不稳定。32K上下文门槛则与Agent的工作方式有关：检索到的资料文本、多轮工具调用历史、文档脚本和页面预览反馈都会占用上下文窗口，窗口过小会导致Agent“遗忘”早期信息或无法容纳完整资料源。因此SurfSense将Agent模式与普通问答模式分层，是对模型能力差异的务实处理。

维护者抛出的两个开放问题

维护者在帖子中明确希望得到对Agent设计的诚实反馈，核心疑问有两个：

“文档即带版本管理的脚本、配合预览自检”是否是正确的模式，还是应该让模型直接编辑文件？
如何决定哪些工具应当请求审批？

这两个问题触及Agent工程的核心张力：直接编辑文件更贴近人类工作流，但脚本化+版本+预览的组合提供了可回滚与可验证性；审批粒度过粗会打断流程，过细则形同虚设。SurfSense目前的选择偏向可控与可审计。

适用人群与上手方式

如果你需要AI在办公文档上产出可交付物，而不是停留在聊天窗口，这个项目值得一试。下载地址为surfsense.com/downloads，源码在GitHub的MODSetter/SurfSense仓库。

常见问题

SurfSense支持哪些文件格式？ Word、PDF、幻灯片、电子表格和网页，也可基于.docx或.pptx模板生成。

会覆盖我的原始文件吗？ 不会。所有编辑以新副本形式返回，Word改动带修订和批注。

必须用云端模型吗？ 不必须。支持本地模型、OpenAI兼容API，或ChatGPT/Claude订阅计划。