1. 为什么“本地优先”是 AI 办公 Agent 的分水岭1.1 从聊天记录到真文件一个被忽视的交付断层过去一年我试过不下二十款 AI 办公助手绝大多数都有一个通病聊得天花乱坠最后交付给你的是一段 Markdown 文本或者一个需要你手动复制粘贴的代码块。你让它“帮我整理一下这个月的报销单”它给你一段格式建议你让它“把这份会议纪要转成周报”它给你一段模板。真正落到磁盘上的.xlsx、.docx、.pptx文件几乎没人给你。OpenWorkBuddy 这个项目最吸引我的点就在这里——它的定位是本地优先的 AI 办公 Agent交付真文件而不只是聊天记录。这句话拆开看有三层含义第一Agent 运行在你自己的机器上文件不出本地第二它的输出物是真实可打开、可编辑的办公文件第三它不是一个对话框而是一个能调用工具、读写文件、执行多步任务的执行体。这解决的是什么问题是“最后一公里”的问题。大模型能生成内容但内容到文件之间隔着一层格式转换、样式套用、多文件协同、路径管理。OpenWorkBuddy 把这层补上了。适合谁来参考我觉得三类人最该看一是想给自己团队搭内部办公自动化工具的后端工程师二是对 AI Agent 架构感兴趣、想找一个真实可跑项目练手的人三是被各种“AI 办公”产品绕晕、想自己掌控数据和流程的独立开发者。1.2 本地优先不是噱头是数据主权的底线很多人看到“本地优先”第一反应是“离线能用吗”。其实本地优先的核心不是离线而是数据不出机器。办公场景里流转的东西——合同、财报、人事表、客户名单——没有一样适合上传到第三方服务器。OpenWorkBuddy 把 Agent 的运行时、文件读写、工具调用全部放在本地模型调用可以走本地推理也可以走你信任的接口但文件的生成、修改、存储始终在你自己的文件系统里。我实测下来这个设计带来的直接好处是你可以放心让它处理真实业务文件而不用先做脱敏。脱敏这件事本身就是巨大的成本一份合同脱敏完上下文就断了Agent 理解不了业务逻辑。本地优先把这个问题从根上绕开了。1.3 JavaScript 技术栈的选择逻辑项目用 JavaScript 作为主要语言这个选择值得说道。办公 Agent 的核心能力之一是操作办公文件而 JavaScript 生态里有docx、exceljs、pptxgenjs这些成熟的库能直接在 Node 环境里生成和修改 Office 文件不需要依赖 Office 软件本身。相比之下Python 虽然也有python-docx、openpyxl但在前端集成和跨平台分发上JavaScript 的 Electron / Node 组合更顺滑。另一个原因是 Agent 的编排层。JavaScript 的异步模型天然适合处理“调用模型 → 等待返回 → 调用工具 → 再调用模型”这种链式任务async/await写起来比回调清晰得多。而且如果后续要做桌面端Electron 直接复用同一套代码不用重写。提示选 JavaScript 不代表不能用其他语言写工具。OpenWorkBuddy 的架构里工具层是可以通过子进程或 HTTP 接口扩展的你用 Python 写一个数据处理脚本挂上去也完全可行。2. 核心架构拆解一个办公 Agent 到底由什么组成2.1 四层结构模型层、编排层、工具层、文件层我把 OpenWorkBuddy 的架构理解成四层这个分层方式也是我自己搭 Agent 时常用的思路。模型层负责和 LLM 交互接收自然语言指令输出结构化的动作意图。这一层的关键是提示词设计和输出格式约束。Agent 不能随便说话它必须输出“我要调用哪个工具、传什么参数”这种机器能解析的东西。编排层是大脑负责维护任务状态、决定下一步调用哪个工具、处理工具返回结果、判断任务是否完成。这一层最容易出问题因为多步任务里任何一步失败都可能导致整个流程卡死。工具层是手脚每个工具是一个独立函数比如“读取 Excel 文件”“生成 Word 文档”“发送邮件”“查询数据库”。工具的设计原则是单一职责一个工具只做一件事参数尽量简单。文件层是落地层负责把工具产出的内容写成真实文件管理文件路径、命名、版本。这一层是 OpenWorkBuddy 区别于普通聊天机器人的关键。2.2 任务编排从一句话到多步执行举个具体例子。你说“把 data 目录下所有 CSV 合并成一个 Excel每个 sheet 对应一个文件再加一个汇总页”。这句话对人来说很清楚对 Agent 来说需要拆成多步扫描data目录列出所有.csv文件逐个读取 CSV解析表头和内容创建一个新的 Excel 工作簿为每个 CSV 创建一个 sheet写入数据创建一个汇总 sheet统计每个文件的行数和列数保存文件到指定路径编排层要做的就是把这个任务拆解成工具调用序列然后一步步执行。每一步的返回结果作为下一步的输入。如果中间某一步失败比如某个 CSV 编码不对编排层要能捕获错误、决定是跳过还是终止。我踩过的一个坑是早期版本的 Agent 没有做步骤持久化任务跑到一半进程挂了前面所有工作白费。后来加了检查点机制每完成一步就把状态写到临时文件重启后能从断点继续。2.3 工具调用的参数校验别让模型瞎传模型输出工具调用参数时经常会出现类型错误。比如要求传数字它传了字符串要求传数组它传了逗号分隔的字符串。如果不做校验工具函数直接崩。我的做法是在工具层加一层参数校验用 JSON Schema 定义每个工具的参数类型、必填项、取值范围。模型输出后先过校验不通过就返回错误信息让模型重新生成。这个重试机制看起来简单但能挡掉八成以上的低级错误。const toolSchema { name: merge_csv_to_excel, parameters: { type: object, properties: { sourceDir: { type: string }, outputPath: { type: string }, includeSummary: { type: boolean, default: true } }, required: [sourceDir, outputPath] } };注意参数校验的错误信息要写得具体比如“sourceDir 必须是字符串你传的是数字”这样模型才知道怎么改。笼统地说“参数错误”模型会反复犯同样的错。2.4 文件交付的完整性保障交付真文件这件事难点不在生成而在完整性。一个 Excel 文件生成到一半进程被杀留下一个损坏的文件比不生成还糟糕。OpenWorkBuddy 的做法是先生成到临时文件写完后再原子性地重命名到目标路径。这样即使中途失败目标路径上要么是旧文件要么是新文件不会出现半成品。另一个细节是文件锁。如果多个任务同时写同一个文件不加锁会互相覆盖。我用的是基于文件系统的锁在目标路径旁边创建一个.lock文件写完再删掉。简单但有效。3. 实操搭建从零跑通一个本地办公 Agent3.1 环境准备与依赖安装先把基础环境搭起来。Node 版本建议 18 以上因为要用到原生的fetch和较新的fsAPI。node -v # 确认 18 mkdir openworkbuddy cd openworkbuddy npm init -y npm install docx exceljs pptxgenjs npm install openai # 或者你用的模型 SDK目录结构我习惯这样组织openworkbuddy/ ├── src/ │ ├── agent/ # 编排层 │ ├── tools/ # 工具层 │ ├── model/ # 模型层 │ └── utils/ # 文件操作、校验等 ├── workspace/ # Agent 的工作目录 │ ├── input/ │ └── output/ └── package.jsonworkspace目录是 Agent 的沙箱所有文件读写都限制在这个目录里。这样做是为了安全防止模型被诱导去读写系统文件。3.2 模型接入与提示词设计模型层我建议先用一个简单的封装把系统提示词和用户输入拼起来发给模型。系统提示词要写清楚三件事Agent 的角色、可用工具列表、输出格式要求。你是一个本地办公助手运行在用户的机器上。 你可以调用以下工具 - read_file(path): 读取文件内容 - write_excel(data, path): 生成 Excel 文件 - write_word(content, path): 生成 Word 文档 - list_dir(path): 列出目录内容 你的输出必须是 JSON 格式 {action: 工具名, params: {...}, reason: 为什么这么做} 如果任务完成输出 {action: done, result: 结果描述}这个格式约束是关键。没有它模型会输出自然语言编排层没法解析。我试过让模型输出 XML、YAML、JSON最后发现 JSON 最稳因为大多数模型对 JSON 的生成质量最高。3.3 工具层的实现要点以生成 Excel 为例用exceljs实现一个工具函数const ExcelJS require(exceljs); async function writeExcel(params) { const { data, path } params; const workbook new ExcelJS.Workbook(); for (const sheet of data.sheets) { const worksheet workbook.addWorksheet(sheet.name); worksheet.addRow(sheet.headers); sheet.rows.forEach(row worksheet.addRow(row)); } const tempPath path .tmp; await workbook.xlsx.writeFile(tempPath); await fs.rename(tempPath, path); return { success: true, path, sheets: data.sheets.length }; }这里有几个细节一是先写临时文件再重命名保证原子性二是返回结果里带上文件路径和 sheet 数量方便编排层判断是否成功三是参数里的data结构要提前和模型约定好不然模型会传各种奇怪的格式。3.4 编排循环的实现编排层是一个循环调用模型 → 解析输出 → 执行工具 → 把结果喂回模型 → 继续循环直到模型输出done或达到最大步数。async function runAgent(userInput, maxSteps 20) { const messages [ { role: system, content: SYSTEM_PROMPT }, { role: user, content: userInput } ]; for (let step 0; step maxSteps; step) { const response await callModel(messages); const action parseAction(response); if (action.action done) { return action.result; } const toolResult await executeTool(action.action, action.params); messages.push({ role: assistant, content: response }); messages.push({ role: user, content: JSON.stringify(toolResult) }); } throw new Error(达到最大步数任务未完成); }最大步数这个限制很重要。我遇到过模型陷入死循环反复调用同一个工具没有步数限制的话会一直烧 token。3.5 一个完整的任务演示假设workspace/input下有三个 CSV 文件我想合并成一个 Excel。输入指令把 input 目录下所有 CSV 合并成 output/merged.xlsx每个文件一个 sheetAgent 的执行过程步骤动作参数结果1list_dir{path: input}返回三个文件名2read_file{path: input/a.csv}返回 CSV 内容3read_file{path: input/b.csv}返回 CSV 内容4read_file{path: input/c.csv}返回 CSV 内容5write_excel{data: {...}, path: output/merged.xlsx}成功返回路径6done-任务完成整个过程不需要人工干预最后output/merged.xlsx是一个真实可打开的文件。4. 常见问题与排查技巧实录4.1 模型输出格式错误怎么办这是最高频的问题。模型有时候会在 JSON 外面包一层 Markdown 代码块有时候会加解释性文字。我的处理方式是写一个健壮的解析函数先用正则提取 JSON 部分再尝试解析。如果解析失败把错误信息返回给模型让它重新输出。function parseAction(text) { const jsonMatch text.match(/\{[\s\S]*\}/); if (!jsonMatch) throw new Error(未找到 JSON); try { return JSON.parse(jsonMatch[0]); } catch (e) { throw new Error(JSON 解析失败: ${e.message}); } }如果连续三次解析失败就终止任务并报错。不要无限重试模型有时候会卡在同一个错误上。4.2 文件路径安全问题模型可能会生成../../etc/passwd这种路径。必须在工具层做路径校验确保所有路径都在workspace目录内。const path require(path); const WORKSPACE path.resolve(./workspace); function safePath(userPath) { const resolved path.resolve(WORKSPACE, userPath); if (!resolved.startsWith(WORKSPACE)) { throw new Error(路径越界); } return resolved; }这个检查不能省。我见过有人图省事不做校验结果模型被诱导去读系统文件虽然大多数情况下只是读但风险是实实在在的。4.3 大文件处理的内存问题处理几十兆的 Excel 时exceljs默认会把整个文件加载到内存。如果文件更大进程会 OOM。解决方案是用流式 APIconst workbook new ExcelJS.stream.xlsx.WorkbookWriter({ filename: tempPath, useStyles: true });流式写入的代价是不能随机访问已经写入的单元格但对于“生成新文件”这种场景完全够用。4.4 常见问题速查表问题现象可能原因解决方法模型不调用工具直接回答系统提示词不够明确在提示词里强调“必须输出 JSON 动作”工具调用参数类型错误模型对参数类型理解偏差加 JSON Schema 校验错误时重试任务中途卡死模型陷入循环设置最大步数超限终止生成的文件打不开写入未完成或格式错误用临时文件 原子重命名路径越界报错模型生成了绝对路径用 safePath 强制限制在 workspace内存占用过高大文件全量加载改用流式 API4.5 几个我踩过的坑第一个坑是编码问题。CSV 文件有的是 UTF-8有的是 GBK直接读会乱码。我的做法是先检测 BOM没有 BOM 就尝试用 UTF-8 读如果出现乱码字符再回退到 GBK。这个逻辑写起来不复杂但能省掉大量调试时间。第二个坑是并发写文件。早期版本没有加锁两个任务同时写同一个文件结果互相覆盖。后来加了文件锁问题解决。文件锁的实现很简单就是创建一个.lock文件存在就等待不存在就创建并继续。第三个坑是模型幻觉。模型有时候会“假装”调用了工具实际上只是在文本里描述了调用过程。这种情况在输出格式约束不严的时候特别容易出现。解决办法是强制要求模型输出结构化的动作 JSON编排层只认 JSON不认自然语言描述。5. 扩展方向这个项目还能怎么玩5.1 接入更多办公文件格式目前主要覆盖 Excel、Word、PPT实际上办公场景里还有 PDF、Markdown、CSV、JSON 等格式。PDF 的生成可以用pdfkit解析可以用pdf-parse。Markdown 转 Word 可以用md-to-docx这类库。每增加一种格式就是增加一个工具函数架构上不需要大改。5.2 定时任务与批处理把 Agent 包装成一个定时任务每天早上自动跑一遍“汇总昨日数据生成日报”。用node-cron就能实现const cron require(node-cron); cron.schedule(0 8 * * *, () { runAgent(汇总 input/daily 下昨天的数据生成 output/daily-report.xlsx); });这个用法在数据报表场景里特别实用人还没到工位报表已经生成好了。5.3 多 Agent 协作单个 Agent 处理复杂任务时容易顾此失彼。可以拆成多个专职 Agent一个负责数据读取一个负责格式转换一个负责质量检查。Agent 之间通过文件或消息队列通信。这个架构复杂度高但处理大型任务时更稳。5.4 本地模型接入如果对数据安全要求极高可以把模型层换成 本地推理。现在不少开源模型支持本地部署通过兼容接口调用。这样整个链路——从输入到模型推理到文件生成——全部在本地完成没有任何数据外流。我在实际使用中的体会是本地办公 Agent 的价值不在于它有多智能而在于它能把“智能”落到真实的文件上。聊天记录看完就忘了但一个生成好的 Excel 文件会留在你的磁盘上第二天还能打开继续用。这个差别用过的人才知道。