1. 為什么“本地優(yōu)先”是 AI 辦公 Agent 的分水嶺1.1 從聊天記錄到真文件一個被忽視的交付斷層過去一年我試過不下二十款 AI 辦公助手絕大多數(shù)都有一個通病聊得天花亂墜最后交付給你的是一段 Markdown 文本或者一個需要你手動復(fù)制粘貼的代碼塊。你讓它“幫我整理一下這個月的報銷單”它給你一段格式建議你讓它“把這份會議紀(jì)要轉(zhuǎn)成周報”它給你一段模板。真正落到磁盤上的.xlsx、.docx、.pptx文件幾乎沒人給你。OpenWorkBuddy 這個項(xiàng)目最吸引我的點(diǎn)就在這里——它的定位是本地優(yōu)先的 AI 辦公 Agent交付真文件而不只是聊天記錄。這句話拆開看有三層含義第一Agent 運(yùn)行在你自己的機(jī)器上文件不出本地第二它的輸出物是真實(shí)可打開、可編輯的辦公文件第三它不是一個對話框而是一個能調(diào)用工具、讀寫文件、執(zhí)行多步任務(wù)的執(zhí)行體。這解決的是什么問題是“最后一公里”的問題。大模型能生成內(nèi)容但內(nèi)容到文件之間隔著一層格式轉(zhuǎn)換、樣式套用、多文件協(xié)同、路徑管理。OpenWorkBuddy 把這層補(bǔ)上了。適合誰來參考我覺得三類人最該看一是想給自己團(tuán)隊搭內(nèi)部辦公自動化工具的后端工程師二是對 AI Agent 架構(gòu)感興趣、想找一個真實(shí)可跑項(xiàng)目練手的人三是被各種“AI 辦公”產(chǎn)品繞暈、想自己掌控數(shù)據(jù)和流程的獨(dú)立開發(fā)者。1.2 本地優(yōu)先不是噱頭是數(shù)據(jù)主權(quán)的底線很多人看到“本地優(yōu)先”第一反應(yīng)是“離線能用嗎”。其實(shí)本地優(yōu)先的核心不是離線而是數(shù)據(jù)不出機(jī)器。辦公場景里流轉(zhuǎn)的東西——合同、財報、人事表、客戶名單——沒有一樣適合上傳到第三方服務(wù)器。OpenWorkBuddy 把 Agent 的運(yùn)行時、文件讀寫、工具調(diào)用全部放在本地模型調(diào)用可以走本地推理也可以走你信任的接口但文件的生成、修改、存儲始終在你自己的文件系統(tǒng)里。我實(shí)測下來這個設(shè)計帶來的直接好處是你可以放心讓它處理真實(shí)業(yè)務(wù)文件而不用先做脫敏。脫敏這件事本身就是巨大的成本一份合同脫敏完上下文就斷了Agent 理解不了業(yè)務(wù)邏輯。本地優(yōu)先把這個問題從根上繞開了。1.3 JavaScript 技術(shù)棧的選擇邏輯項(xiàng)目用 JavaScript 作為主要語言這個選擇值得說道。辦公 Agent 的核心能力之一是操作辦公文件而 JavaScript 生態(tài)里有docx、exceljs、pptxgenjs這些成熟的庫能直接在 Node 環(huán)境里生成和修改 Office 文件不需要依賴 Office 軟件本身。相比之下Python 雖然也有python-docx、openpyxl但在前端集成和跨平臺分發(fā)上JavaScript 的 Electron / Node 組合更順滑。另一個原因是 Agent 的編排層。JavaScript 的異步模型天然適合處理“調(diào)用模型 → 等待返回 → 調(diào)用工具 → 再調(diào)用模型”這種鏈?zhǔn)饺蝿?wù)async/await寫起來比回調(diào)清晰得多。而且如果后續(xù)要做桌面端Electron 直接復(fù)用同一套代碼不用重寫。提示選 JavaScript 不代表不能用其他語言寫工具。OpenWorkBuddy 的架構(gòu)里工具層是可以通過子進(jìn)程或 HTTP 接口擴(kuò)展的你用 Python 寫一個數(shù)據(jù)處理腳本掛上去也完全可行。2. 核心架構(gòu)拆解一個辦公 Agent 到底由什么組成2.1 四層結(jié)構(gòu)模型層、編排層、工具層、文件層我把 OpenWorkBuddy 的架構(gòu)理解成四層這個分層方式也是我自己搭 Agent 時常用的思路。模型層負(fù)責(zé)和 LLM 交互接收自然語言指令輸出結(jié)構(gòu)化的動作意圖。這一層的關(guān)鍵是提示詞設(shè)計和輸出格式約束。Agent 不能隨便說話它必須輸出“我要調(diào)用哪個工具、傳什么參數(shù)”這種機(jī)器能解析的東西。編排層是大腦負(fù)責(zé)維護(hù)任務(wù)狀態(tài)、決定下一步調(diào)用哪個工具、處理工具返回結(jié)果、判斷任務(wù)是否完成。這一層最容易出問題因?yàn)槎嗖饺蝿?wù)里任何一步失敗都可能導(dǎo)致整個流程卡死。工具層是手腳每個工具是一個獨(dú)立函數(shù)比如“讀取 Excel 文件”“生成 Word 文檔”“發(fā)送郵件”“查詢數(shù)據(jù)庫”。工具的設(shè)計原則是單一職責(zé)一個工具只做一件事參數(shù)盡量簡單。文件層是落地層負(fù)責(zé)把工具產(chǎn)出的內(nèi)容寫成真實(shí)文件管理文件路徑、命名、版本。這一層是 OpenWorkBuddy 區(qū)別于普通聊天機(jī)器人的關(guān)鍵。2.2 任務(wù)編排從一句話到多步執(zhí)行舉個具體例子。你說“把 data 目錄下所有 CSV 合并成一個 Excel每個 sheet 對應(yīng)一個文件再加一個匯總頁”。這句話對人來說很清楚對 Agent 來說需要拆成多步掃描data目錄列出所有.csv文件逐個讀取 CSV解析表頭和內(nèi)容創(chuàng)建一個新的 Excel 工作簿為每個 CSV 創(chuàng)建一個 sheet寫入數(shù)據(jù)創(chuàng)建一個匯總 sheet統(tǒng)計每個文件的行數(shù)和列數(shù)保存文件到指定路徑編排層要做的就是把這個任務(wù)拆解成工具調(diào)用序列然后一步步執(zhí)行。每一步的返回結(jié)果作為下一步的輸入。如果中間某一步失敗比如某個 CSV 編碼不對編排層要能捕獲錯誤、決定是跳過還是終止。我踩過的一個坑是早期版本的 Agent 沒有做步驟持久化任務(wù)跑到一半進(jìn)程掛了前面所有工作白費(fèi)。后來加了檢查點(diǎn)機(jī)制每完成一步就把狀態(tài)寫到臨時文件重啟后能從斷點(diǎn)繼續(xù)。2.3 工具調(diào)用的參數(shù)校驗(yàn)別讓模型瞎傳模型輸出工具調(diào)用參數(shù)時經(jīng)常會出現(xiàn)類型錯誤。比如要求傳數(shù)字它傳了字符串要求傳數(shù)組它傳了逗號分隔的字符串。如果不做校驗(yàn)工具函數(shù)直接崩。我的做法是在工具層加一層參數(shù)校驗(yàn)用 JSON Schema 定義每個工具的參數(shù)類型、必填項(xiàng)、取值范圍。模型輸出后先過校驗(yàn)不通過就返回錯誤信息讓模型重新生成。這個重試機(jī)制看起來簡單但能擋掉八成以上的低級錯誤。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] } };注意參數(shù)校驗(yàn)的錯誤信息要寫得具體比如“sourceDir 必須是字符串你傳的是數(shù)字”這樣模型才知道怎么改?；\統(tǒng)地說“參數(shù)錯誤”模型會反復(fù)犯同樣的錯。2.4 文件交付的完整性保障交付真文件這件事難點(diǎn)不在生成而在完整性。一個 Excel 文件生成到一半進(jìn)程被殺留下一個損壞的文件比不生成還糟糕。OpenWorkBuddy 的做法是先生成到臨時文件寫完后再原子性地重命名到目標(biāo)路徑。這樣即使中途失敗目標(biāo)路徑上要么是舊文件要么是新文件不會出現(xiàn)半成品。另一個細(xì)節(jié)是文件鎖。如果多個任務(wù)同時寫同一個文件不加鎖會互相覆蓋。我用的是基于文件系統(tǒng)的鎖在目標(biāo)路徑旁邊創(chuàng)建一個.lock文件寫完再刪掉。簡單但有效。3. 實(shí)操搭建從零跑通一個本地辦公 Agent3.1 環(huán)境準(zhǔn)備與依賴安裝先把基礎(chǔ)環(huán)境搭起來。Node 版本建議 18 以上因?yàn)橐玫皆膄etch和較新的fsAPI。node -v # 確認(rèn) 18 mkdir openworkbuddy cd openworkbuddy npm init -y npm install docx exceljs pptxgenjs npm install openai # 或者你用的模型 SDK目錄結(jié)構(gòu)我習(xí)慣這樣組織openworkbuddy/ ├── src/ │ ├── agent/ # 編排層 │ ├── tools/ # 工具層 │ ├── model/ # 模型層 │ └── utils/ # 文件操作、校驗(yàn)等 ├── workspace/ # Agent 的工作目錄 │ ├── input/ │ └── output/ └── package.jsonworkspace目錄是 Agent 的沙箱所有文件讀寫都限制在這個目錄里。這樣做是為了安全防止模型被誘導(dǎo)去讀寫系統(tǒng)文件。3.2 模型接入與提示詞設(shè)計模型層我建議先用一個簡單的封裝把系統(tǒng)提示詞和用戶輸入拼起來發(fā)給模型。系統(tǒng)提示詞要寫清楚三件事Agent 的角色、可用工具列表、輸出格式要求。你是一個本地辦公助手運(yùn)行在用戶的機(jī)器上。 你可以調(diào)用以下工具 - read_file(path): 讀取文件內(nèi)容 - write_excel(data, path): 生成 Excel 文件 - write_word(content, path): 生成 Word 文檔 - list_dir(path): 列出目錄內(nèi)容 你的輸出必須是 JSON 格式 {action: 工具名, params: {...}, reason: 為什么這么做} 如果任務(wù)完成輸出 {action: done, result: 結(jié)果描述}這個格式約束是關(guān)鍵。沒有它模型會輸出自然語言編排層沒法解析。我試過讓模型輸出 XML、YAML、JSON最后發(fā)現(xiàn) JSON 最穩(wěn)因?yàn)榇蠖鄶?shù)模型對 JSON 的生成質(zhì)量最高。3.3 工具層的實(shí)現(xiàn)要點(diǎn)以生成 Excel 為例用exceljs實(shí)現(xiàn)一個工具函數(shù)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 }; }這里有幾個細(xì)節(jié)一是先寫臨時文件再重命名保證原子性二是返回結(jié)果里帶上文件路徑和 sheet 數(shù)量方便編排層判斷是否成功三是參數(shù)里的data結(jié)構(gòu)要提前和模型約定好不然模型會傳各種奇怪的格式。3.4 編排循環(huán)的實(shí)現(xiàn)編排層是一個循環(huán)調(diào)用模型 → 解析輸出 → 執(zhí)行工具 → 把結(jié)果喂回模型 → 繼續(xù)循環(huán)直到模型輸出done或達(dá)到最大步數(shù)。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(達(dá)到最大步數(shù)任務(wù)未完成); }最大步數(shù)這個限制很重要。我遇到過模型陷入死循環(huán)反復(fù)調(diào)用同一個工具沒有步數(shù)限制的話會一直燒 token。3.5 一個完整的任務(wù)演示假設(shè)workspace/input下有三個 CSV 文件我想合并成一個 Excel。輸入指令把 input 目錄下所有 CSV 合并成 output/merged.xlsx每個文件一個 sheetAgent 的執(zhí)行過程步驟動作參數(shù)結(jié)果1list_dir{path: input}返回三個文件名2read_file{path: input/a.csv}返回 CSV 內(nèi)容3read_file{path: input/b.csv}返回 CSV 內(nèi)容4read_file{path: input/c.csv}返回 CSV 內(nèi)容5write_excel{data: {...}, path: output/merged.xlsx}成功返回路徑6done-任務(wù)完成整個過程不需要人工干預(yù)最后output/merged.xlsx是一個真實(shí)可打開的文件。4. 常見問題與排查技巧實(shí)錄4.1 模型輸出格式錯誤怎么辦這是最高頻的問題。模型有時候會在 JSON 外面包一層 Markdown 代碼塊有時候會加解釋性文字。我的處理方式是寫一個健壯的解析函數(shù)先用正則提取 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}); } }如果連續(xù)三次解析失敗就終止任務(wù)并報錯。不要無限重試模型有時候會卡在同一個錯誤上。4.2 文件路徑安全問題模型可能會生成../../etc/passwd這種路徑。必須在工具層做路徑校驗(yàn)確保所有路徑都在workspace目錄內(nèi)。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; }這個檢查不能省。我見過有人圖省事不做校驗(yàn)結(jié)果模型被誘導(dǎo)去讀系統(tǒng)文件雖然大多數(shù)情況下只是讀但風(fēng)險是實(shí)實(shí)在在的。4.3 大文件處理的內(nèi)存問題處理幾十兆的 Excel 時exceljs默認(rèn)會把整個文件加載到內(nèi)存。如果文件更大進(jìn)程會 OOM。解決方案是用流式 APIconst workbook new ExcelJS.stream.xlsx.WorkbookWriter({ filename: tempPath, useStyles: true });流式寫入的代價是不能隨機(jī)訪問已經(jīng)寫入的單元格但對于“生成新文件”這種場景完全夠用。4.4 常見問題速查表問題現(xiàn)象可能原因解決方法模型不調(diào)用工具直接回答系統(tǒng)提示詞不夠明確在提示詞里強(qiáng)調(diào)“必須輸出 JSON 動作”工具調(diào)用參數(shù)類型錯誤模型對參數(shù)類型理解偏差加 JSON Schema 校驗(yàn)錯誤時重試任務(wù)中途卡死模型陷入循環(huán)設(shè)置最大步數(shù)超限終止生成的文件打不開寫入未完成或格式錯誤用臨時文件 原子重命名路徑越界報錯模型生成了絕對路徑用 safePath 強(qiáng)制限制在 workspace內(nèi)存占用過高大文件全量加載改用流式 API4.5 幾個我踩過的坑第一個坑是編碼問題。CSV 文件有的是 UTF-8有的是 GBK直接讀會亂碼。我的做法是先檢測 BOM沒有 BOM 就嘗試用 UTF-8 讀如果出現(xiàn)亂碼字符再回退到 GBK。這個邏輯寫起來不復(fù)雜但能省掉大量調(diào)試時間。第二個坑是并發(fā)寫文件。早期版本沒有加鎖兩個任務(wù)同時寫同一個文件結(jié)果互相覆蓋。后來加了文件鎖問題解決。文件鎖的實(shí)現(xiàn)很簡單就是創(chuàng)建一個.lock文件存在就等待不存在就創(chuàng)建并繼續(xù)。第三個坑是模型幻覺。模型有時候會“假裝”調(diào)用了工具實(shí)際上只是在文本里描述了調(diào)用過程。這種情況在輸出格式約束不嚴(yán)的時候特別容易出現(xiàn)。解決辦法是強(qiáng)制要求模型輸出結(jié)構(gòu)化的動作 JSON編排層只認(rèn) JSON不認(rèn)自然語言描述。5. 擴(kuò)展方向這個項(xiàng)目還能怎么玩5.1 接入更多辦公文件格式目前主要覆蓋 Excel、Word、PPT實(shí)際上辦公場景里還有 PDF、Markdown、CSV、JSON 等格式。PDF 的生成可以用pdfkit解析可以用pdf-parse。Markdown 轉(zhuǎn) Word 可以用md-to-docx這類庫。每增加一種格式就是增加一個工具函數(shù)架構(gòu)上不需要大改。5.2 定時任務(wù)與批處理把 Agent 包裝成一個定時任務(wù)每天早上自動跑一遍“匯總昨日數(shù)據(jù)生成日報”。用node-cron就能實(shí)現(xiàn)const cron require(node-cron); cron.schedule(0 8 * * *, () { runAgent(匯總 input/daily 下昨天的數(shù)據(jù)生成 output/daily-report.xlsx); });這個用法在數(shù)據(jù)報表場景里特別實(shí)用人還沒到工位報表已經(jīng)生成好了。5.3 多 Agent 協(xié)作單個 Agent 處理復(fù)雜任務(wù)時容易顧此失彼?？梢圆鸪啥鄠€專職 Agent一個負(fù)責(zé)數(shù)據(jù)讀取一個負(fù)責(zé)格式轉(zhuǎn)換一個負(fù)責(zé)質(zhì)量檢查。Agent 之間通過文件或消息隊列通信。這個架構(gòu)復(fù)雜度高但處理大型任務(wù)時更穩(wěn)。5.4 本地模型接入如果對數(shù)據(jù)安全要求極高可以把模型層換成 本地推理?，F(xiàn)在不少開源模型支持本地部署通過兼容接口調(diào)用。這樣整個鏈路——從輸入到模型推理到文件生成——全部在本地完成沒有任何數(shù)據(jù)外流。我在實(shí)際使用中的體會是本地辦公 Agent 的價值不在于它有多智能而在于它能把“智能”落到真實(shí)的文件上。聊天記錄看完就忘了但一個生成好的 Excel 文件會留在你的磁盤上第二天還能打開繼續(xù)用。這個差別用過的人才知道。