1. 為什么“AI Agent 辦公應(yīng)用”這個(gè)組合值得單獨(dú)聊AI Agent 這個(gè)詞在過(guò)去一年多里被反復(fù)提及但真正落到“能干活”的場(chǎng)景其實(shí)并不多。大部分演示停留在問(wèn)答、檢索、寫(xiě)幾段文案一旦讓它去操作一個(gè)真實(shí)的電子表格、改一份文檔、生成一張帶格式的報(bào)表立刻就露怯了。原因不復(fù)雜Agent 需要一個(gè)能被程序化操控的“工作臺(tái)”而傳統(tǒng)辦公軟件要么是封閉的桌面程序要么是面向人類交互設(shè)計(jì)的 Web 界面根本沒(méi)有給 Agent 留出穩(wěn)定的操作接口。Univer 這個(gè)項(xiàng)目切入的正是這個(gè)縫隙。它把自己定位成“面向 AI Agent 的開(kāi)源辦公應(yīng)用 SDK”說(shuō)白了就是提供一套可編程的表格、文檔、幻燈片內(nèi)核讓開(kāi)發(fā)者能在自己的產(chǎn)品里嵌入辦公能力同時(shí)讓 AI Agent 通過(guò) API 直接讀寫(xiě)單元格、樣式、公式、批注這些結(jié)構(gòu)化對(duì)象而不是靠模擬鼠標(biāo)點(diǎn)擊去“猜”界面。這個(gè)定位很關(guān)鍵因?yàn)樗鼪Q定了 Univer 不是又一個(gè)在線 Excel 的克隆品而是一層基礎(chǔ)設(shè)施。我第一次接觸這類需求是在做一個(gè)內(nèi)部數(shù)據(jù)填報(bào)工具的時(shí)候。業(yè)務(wù)方希望用戶能在網(wǎng)頁(yè)里編輯表格同時(shí)后臺(tái)的自動(dòng)化流程要能直接改某些單元格的值并觸發(fā)重算。當(dāng)時(shí)試過(guò)幾種方案用現(xiàn)成的在線表格組件API 能力弱改個(gè)公式得繞一大圈自己用 canvas 畫(huà)表格光是公式引擎和協(xié)同沖突處理就能拖垮整個(gè)排期。Univer 這類項(xiàng)目的價(jià)值就在于它把公式引擎、渲染、協(xié)同、插件體系這些臟活累活都封裝好了你只需要關(guān)心業(yè)務(wù)邏輯和 Agent 的接入方式。這篇文章適合幾類人看一是正在做 AI Agent 產(chǎn)品、需要給 Agent 配一個(gè)“辦公操作面板”的開(kāi)發(fā)者二是想在自己的 SaaS 里嵌入表格或文檔編輯能力、又不想從零造輪子的團(tuán)隊(duì)三是對(duì)開(kāi)源辦公內(nèi)核感興趣、想研究公式引擎和協(xié)同架構(gòu)的技術(shù)人。我會(huì)從整體設(shè)計(jì)思路、核心模塊拆解、實(shí)操接入步驟、常見(jiàn)坑這幾個(gè)角度展開(kāi)盡量把“為什么這么設(shè)計(jì)”講清楚而不是只羅列 API。2. Univer 的整體設(shè)計(jì)與架構(gòu)思路拆解2.1 它到底解決的是哪一層問(wèn)題要理解 Univer 的定位先得把“辦公應(yīng)用”拆成幾層。最底層是數(shù)據(jù)模型比如一個(gè)表格由工作表、行、列、單元格、樣式、公式、批注等對(duì)象組成往上是計(jì)算引擎負(fù)責(zé)公式解析、依賴圖、重算再往上是渲染層把數(shù)據(jù)畫(huà)到 canvas 或 DOM 上最上面是交互層處理選區(qū)、拖拽、快捷鍵、菜單。傳統(tǒng)辦公軟件把這四層揉在一起對(duì)外只暴露一個(gè)給人用的界面。Univer 的做法是把它們拆開(kāi)每一層都可以被程序調(diào)用。這個(gè)拆分對(duì) AI Agent 特別友好。Agent 不需要去理解“用戶點(diǎn)了哪個(gè)按鈕”它只需要調(diào)用類似setCellValue(sheetId, row, col, value)或者setFormula(...)這樣的方法然后觸發(fā)一次重算再讀取結(jié)果。整個(gè)過(guò)程是確定性的、可測(cè)試的不會(huì)因?yàn)榻缑娓陌婢褪?。這也是為什么 Univer 強(qiáng)調(diào)自己是 SDK 而不是應(yīng)用——它把“辦公能力”變成了一組可組合的模塊。從架構(gòu)上看Univer 采用了插件化 分層依賴的設(shè)計(jì)。核心包提供基礎(chǔ)的數(shù)據(jù)結(jié)構(gòu)和事件總線公式、渲染、協(xié)同、UI 這些都以插件形式掛載。這樣做的好處是體積可控如果你只需要一個(gè)只讀的表格展示可以不引入編輯相關(guān)的插件如果你要做協(xié)同編輯再按需加載協(xié)同模塊。對(duì) Agent 場(chǎng)景來(lái)說(shuō)你甚至可以只引入數(shù)據(jù)層和公式層完全不要 UI把它當(dāng)成一個(gè)純計(jì)算服務(wù)來(lái)用。2.2 為什么選擇 Canvas 渲染而不是 DOMUniver 的表格渲染走的是 Canvas 路線這一點(diǎn)和很多輕量表格組件不同。DOM 渲染的優(yōu)點(diǎn)是天然支持無(wú)障礙、文本選擇和 CSS 樣式但缺點(diǎn)也很明顯當(dāng)單元格數(shù)量上萬(wàn)時(shí)DOM 節(jié)點(diǎn)數(shù)量會(huì)爆炸滾動(dòng)和重算都會(huì)卡。Canvas 把整個(gè)表格畫(huà)成一張位圖節(jié)點(diǎn)數(shù)量恒定性能上限高得多。代價(jià)是你要自己實(shí)現(xiàn)文本測(cè)量、選區(qū)繪制、滾動(dòng)虛擬化、輸入法處理這些細(xì)節(jié)。Univer 在這方面做了不少工作比如它維護(hù)了一套自己的文本排版邏輯支持富文本、換行、對(duì)齊還處理了 Canvas 上的光標(biāo)和輸入框疊加。對(duì) Agent 來(lái)說(shuō)Canvas 渲染其實(shí)是個(gè)加分項(xiàng)因?yàn)?Agent 不關(guān)心視覺(jué)細(xì)節(jié)它關(guān)心的是數(shù)據(jù)操作是否高效。Canvas 方案讓大規(guī)模數(shù)據(jù)的批量修改和重算變得更快Agent 一次改幾千個(gè)單元格也不會(huì)把頁(yè)面拖死。不過(guò)這里有個(gè)實(shí)操注意點(diǎn)如果你要在 Canvas 表格上做自動(dòng)化測(cè)試傳統(tǒng)的 DOM 選擇器是抓不到單元格的。你需要通過(guò) Univer 暴露的 API 去讀取數(shù)據(jù)或者用它的測(cè)試工具來(lái)斷言。這一點(diǎn)在寫(xiě) Agent 的回歸測(cè)試時(shí)要提前規(guī)劃好否則會(huì)走彎路。2.3 公式引擎的獨(dú)立性設(shè)計(jì)公式是辦公表格的靈魂也是 Agent 最容易出錯(cuò)的環(huán)節(jié)。Univer 把公式引擎做成了相對(duì)獨(dú)立的模塊支持常見(jiàn)的數(shù)學(xué)、統(tǒng)計(jì)、文本、日期函數(shù)并且維護(hù)了一張依賴圖。當(dāng)你修改某個(gè)單元格時(shí)引擎會(huì)根據(jù)依賴圖找出所有受影響的單元格按拓?fù)漤樞蛑厮愣皇侨碇厮恪＿@個(gè)設(shè)計(jì)對(duì) Agent 很重要。假設(shè) Agent 要在一個(gè)預(yù)算表里改一個(gè)稅率它只需要改那一個(gè)單元格引擎會(huì)自動(dòng)把相關(guān)的合計(jì)、稅額、凈額都更新掉。如果引擎是全表重算大表上每次操作都要幾秒Agent 的多步操作就會(huì)變得不可接受。依賴圖的存在讓增量重算成為可能這是 Agent 高頻操作場(chǎng)景下的性能基礎(chǔ)。另外公式引擎和渲染是解耦的。這意味著你可以在沒(méi)有界面的環(huán)境里跑公式計(jì)算比如在服務(wù)端用 Node.js 加載 Univer 的數(shù)據(jù)層和公式層對(duì)上傳的表格做批量計(jì)算。這個(gè)能力在做數(shù)據(jù)導(dǎo)入導(dǎo)出、報(bào)表生成的時(shí)候非常實(shí)用也是很多純前端表格組件做不到的。2.4 協(xié)同能力的預(yù)留雖然標(biāo)題里沒(méi)提協(xié)同但 Univer 的架構(gòu)里給協(xié)同留了位置。它的數(shù)據(jù)變更走的是命令模式每次修改都會(huì)產(chǎn)生一個(gè)可序列化的操作記錄。這個(gè)設(shè)計(jì)本來(lái)是為了撤銷重做但同樣適合做協(xié)同同步——把操作記錄廣播出去其他端按順序應(yīng)用即可。對(duì) AI Agent 來(lái)說(shuō)這個(gè)特性有個(gè)隱含價(jià)值A(chǔ)gent 的每一次修改都可以被記錄、回放、審計(jì)。在需要合規(guī)或者需要人工復(fù)核的場(chǎng)景里你可以把 Agent 的操作日志拿出來(lái)逐步檢查它改了什么。這比“Agent 直接改了數(shù)據(jù)庫(kù)但沒(méi)留痕”要可控得多。我在做自動(dòng)化流程的時(shí)候特別看重這一點(diǎn)因?yàn)橐坏?Agent 改錯(cuò)了數(shù)據(jù)沒(méi)有操作記錄就很難定位問(wèn)題。3. 核心模塊與實(shí)操接入要點(diǎn)3.1 環(huán)境準(zhǔn)備與依賴安裝Univer 是 TypeScript 項(xiàng)目主流的接入方式是通過(guò) npm 安裝。核心包通常包括univerjs/core、univerjs/sheets、univerjs/sheets-ui、univerjs/sheets-formula這幾個(gè)。如果你要做文檔或幻燈片還有對(duì)應(yīng)的包。安裝的時(shí)候要注意版本對(duì)齊Univer 的包之間版本號(hào)是聯(lián)動(dòng)的混用不同小版本可能會(huì)遇到類型不匹配或者運(yùn)行時(shí)錯(cuò)誤。npm install univerjs/core univerjs/sheets univerjs/sheets-ui univerjs/sheets-formula安裝完之后你需要?jiǎng)?chuàng)建一個(gè) Univer 實(shí)例注冊(cè)需要的插件然后把它掛載到一個(gè)容器元素上。下面是一個(gè)最小化的表格初始化示例import { Univer, LocaleType, merge } from univerjs/core; import { UniverSheetsPlugin } from univerjs/sheets; import { UniverSheetsUIPlugin } from univerjs/sheets-ui; import { UniverSheetsFormulaPlugin } from univerjs/sheets-formula; const univer new Univer({ locale: LocaleType.ZH_CN, theme: defaultTheme, }); univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverSheetsUIPlugin); univer.registerPlugin(UniverSheetsFormulaPlugin); univer.createUnit(UniverInstanceType.UNIVER_SHEET, { id: agent-sheet, sheetOrder: [sheet-01], sheets: { sheet-01: { id: sheet-01, name: 數(shù)據(jù)表, rowCount: 1000, columnCount: 26, cellData: {}, }, }, });這段代碼做了三件事創(chuàng)建實(shí)例、注冊(cè)插件、創(chuàng)建一張工作表。注意rowCount和columnCount決定了表格的初始規(guī)模Agent 如果要處理大數(shù)據(jù)量可以把這個(gè)值調(diào)大但也要考慮內(nèi)存占用。實(shí)測(cè)下來(lái)一萬(wàn)行乘五十列的空白表在瀏覽器里初始化大概幾百毫秒屬于可接受范圍。提示Univer 的包更新比較快接入前建議先看官方倉(cāng)庫(kù)的 release notes確認(rèn)當(dāng)前穩(wěn)定版本。不要盲目追最新版尤其是生產(chǎn)環(huán)境。3.2 用 API 操作單元格Agent 的核心動(dòng)作Agent 操作表格歸根結(jié)底就是讀和寫(xiě)。Univer 提供了基于命令的寫(xiě)入方式和基于 Facade 的讀寫(xiě)方式。命令方式更底層適合需要撤銷重做的場(chǎng)景Facade 方式更直觀適合快速開(kāi)發(fā)。對(duì) Agent 來(lái)說(shuō)我推薦用 Facade因?yàn)樗恼Z(yǔ)義更接近“設(shè)置某個(gè)單元格的值”這種自然語(yǔ)言描述。const sheet univer.getActiveSheet(); const facade sheet.getFacade(); // 寫(xiě)入一個(gè)值 facade.setCellValue(0, 0, 產(chǎn)品名稱); facade.setCellValue(0, 1, 銷量); // 寫(xiě)入公式 facade.setCellFormula(1, 1, SUM(B2:B10)); // 讀取值 const value facade.getCellValue(1, 1);這里有個(gè)細(xì)節(jié)要注意行列索引是從 0 開(kāi)始的而公式里的引用是從 1 開(kāi)始的。Agent 在生成公式的時(shí)候如果它內(nèi)部用的是 0 基索引就很容易差一位。我在做 Agent 的時(shí)候就踩過(guò)這個(gè)坑Agent 說(shuō)“把第二行第一列設(shè)為合計(jì)”結(jié)果寫(xiě)到了第三行。解決辦法是在 Agent 的工具層做一次統(tǒng)一的索引轉(zhuǎn)換不要讓 Agent 直接接觸底層索引。批量寫(xiě)入的時(shí)候逐條調(diào)用setCellValue會(huì)有性能問(wèn)題因?yàn)槊看握{(diào)用都可能觸發(fā)一次重算。更好的做法是用batch或者直接構(gòu)造命令數(shù)組一次性提交。Univer 的命令系統(tǒng)支持批量執(zhí)行這樣依賴圖只會(huì)更新一次重算也只跑一遍。const commands []; for (let i 0; i 100; i) { commands.push({ id: sheet.command.set-range-values, params: { range: { startRow: i, startColumn: 0, endRow: i, endColumn: 0 }, values: [[i * 2]], }, }); } univer.executeCommand(commands);批量提交在 Agent 場(chǎng)景里非常關(guān)鍵。Agent 經(jīng)常需要一次性填充幾百行數(shù)據(jù)如果逐條寫(xiě)頁(yè)面會(huì)卡到無(wú)法交互。我實(shí)測(cè)過(guò)一千條逐條寫(xiě)入大概要兩三秒批量提交能壓到兩百毫秒以內(nèi)差距很明顯。3.3 公式與依賴圖的實(shí)操細(xì)節(jié)公式是 Agent 最容易出錯(cuò)的地方因?yàn)楣缴婕耙?、范圍、函?shù)簽名這些結(jié)構(gòu)化信息。Univer 的公式引擎支持大部分常用函數(shù)但不同版本支持的范圍會(huì)有差異。接入前最好先確認(rèn)你要用的函數(shù)在不在支持列表里尤其是財(cái)務(wù)函數(shù)和數(shù)組函數(shù)。寫(xiě)公式的時(shí)候范圍引用要用 A1 表示法比如SUM(A1:A10)。如果你用 API 設(shè)置公式字符串里不要帶等號(hào)以外的多余空格否則解析可能失敗。下面是一個(gè)設(shè)置公式并讀取計(jì)算結(jié)果的例子facade.setCellFormula(9, 1, SUM(B2:B10)); // 等待重算完成 await univer.getActiveSheet().getFormulaEngine().calculate(); const result facade.getCellValue(9, 1);注意重算可能是異步的尤其是在大數(shù)據(jù)量下。Agent 在寫(xiě)完公式后如果立刻讀值可能讀到的是舊值或者空值。穩(wěn)妥的做法是監(jiān)聽(tīng)重算完成事件或者在 API 層做一次顯式的 calculate 并等待。我在做自動(dòng)化報(bào)表的時(shí)候就遇到過(guò)這個(gè)問(wèn)題Agent 寫(xiě)完公式馬上讀結(jié)果拿到的是 undefined排查了半天才發(fā)現(xiàn)是時(shí)序問(wèn)題。依賴圖還有一個(gè)特性循環(huán)引用會(huì)被檢測(cè)出來(lái)并報(bào)錯(cuò)。Agent 如果生成了循環(huán)引用比如 A1 引用 B1、B1 又引用 A1引擎會(huì)標(biāo)記錯(cuò)誤。這時(shí)候 Agent 需要能讀懂錯(cuò)誤信息并修正。建議在 Agent 的工具層把公式錯(cuò)誤映射成自然語(yǔ)言比如“檢測(cè)到循環(huán)引用請(qǐng)檢查 A1 和 B1 的公式”這樣 Agent 更容易自我糾正。3.4 樣式與格式的編程化控制Agent 生成的表格如果只有數(shù)據(jù)沒(méi)有格式可讀性會(huì)很差。Univer 支持通過(guò) API 設(shè)置字體、顏色、邊框、對(duì)齊、數(shù)字格式這些樣式。樣式對(duì)象的結(jié)構(gòu)和常見(jiàn)的表格庫(kù)類似但字段名有自己的約定接入時(shí)要查文檔確認(rèn)。facade.setCellStyle(0, 0, { fontFamily: Arial, fontSize: 12, bold: true, backgroundColor: #f0f0f0, horizontalAlign: center, });數(shù)字格式是個(gè)容易被忽略的點(diǎn)。Agent 寫(xiě)入的如果是金額默認(rèn)可能顯示成1234.5但業(yè)務(wù)上希望顯示成￥1,234.50。Univer 支持通過(guò) number format 來(lái)控制顯示你需要設(shè)置對(duì)應(yīng)的格式字符串。這個(gè)格式只影響顯示不影響底層值所以 Agent 讀到的還是原始數(shù)字不會(huì)因?yàn)楦袷交鴣G失精度。邊框和合并單元格也是 Agent 常用操作。合并單元格要注意合并后只有左上角的單元格保留值其他單元格的值會(huì)被清空。Agent 如果在合并前沒(méi)保存數(shù)據(jù)就會(huì)丟數(shù)據(jù)。建議在 Agent 的工具層把“合并單元格”實(shí)現(xiàn)成“先讀取所有值、合并、再把值寫(xiě)回左上角”的復(fù)合操作避免數(shù)據(jù)丟失。4. 完整實(shí)操流程從零接入一個(gè) Agent 可操作的表格4.1 項(xiàng)目初始化與目錄結(jié)構(gòu)假設(shè)我們要做一個(gè)最小的 Agent 辦公面板前端用 React后端用 Node.js 跑 Agent 邏輯。目錄結(jié)構(gòu)大概是這樣agent-office/ packages/ web/ # 前端嵌入 Univer agent/ # Agent 邏輯調(diào)用 Univer API shared/ # 共享類型和工具函數(shù)前端負(fù)責(zé)渲染表格和接收用戶輸入Agent 邏輯可以跑在前端也可以跑在后端。如果 Agent 需要調(diào)用外部模型建議放后端避免密鑰泄露。前端通過(guò) WebSocket 或者 HTTP 和后端通信后端把 Agent 的指令轉(zhuǎn)成 Univer 的命令再同步回前端。這里有個(gè)架構(gòu)選擇Agent 是直接操作前端的 Univer 實(shí)例還是操作服務(wù)端的一份數(shù)據(jù)副本兩種都可以。直接操作前端實(shí)例的延遲低但 Agent 邏輯必須跑在瀏覽器里操作服務(wù)端副本更安全但需要做雙向同步。我傾向于后者因?yàn)?Agent 的邏輯往往涉及模型調(diào)用和敏感數(shù)據(jù)放服務(wù)端更可控。同步可以用 Univer 的命令流把服務(wù)端的命令廣播到前端應(yīng)用。4.2 定義 Agent 可用的工具集Agent 要操作表格需要一組明確的工具。工具的定義要盡量原子化一個(gè)工具做一件事參數(shù)要少而清晰。下面是我常用的一組工具定義工具名功能關(guān)鍵參數(shù)read_range讀取指定范圍的值sheetId, rangewrite_range寫(xiě)入一批值sheetId, range, valuesset_formula設(shè)置公式sheetId, row, col, formulaapply_style應(yīng)用樣式sheetId, range, styleinsert_rows插入行sheetId, index, countmerge_cells合并單元格sheetId, rangeget_sheet_info獲取表結(jié)構(gòu)sheetId工具的參數(shù)設(shè)計(jì)要避免讓 Agent 去猜索引。比如read_range的 range 可以用 A1 表示法Agent 更容易理解“讀取 A1:C10”而不是“讀取第 0 行到第 9 行、第 0 列到第 2 列”。在工具內(nèi)部再做一次轉(zhuǎn)換把 A1 表示法解析成行列索引。這樣 Agent 的提示詞可以寫(xiě)得更自然出錯(cuò)率也低。工具的返回值也要結(jié)構(gòu)化。不要返回一大段自然語(yǔ)言而是返回 JSON讓 Agent 能解析。比如read_range返回{ values: [[...]], formulas: [[...]] }Agent 拿到后可以自己決定下一步。如果返回的是“A1 的值是 100”Agent 還得再做一次文本解析容易出錯(cuò)。4.3 處理 Agent 的多步操作與事務(wù)Agent 做復(fù)雜任務(wù)時(shí)往往是多步的比如“先讀取銷售數(shù)據(jù)按地區(qū)匯總再生成一張新表”。這中間任何一步失敗都可能留下半成品。Univer 的命令系統(tǒng)支持撤銷但 Agent 不一定知道怎么撤銷。更好的做法是在工具層做事務(wù)封裝把一組操作打包成一個(gè)事務(wù)要么全成功要么全回滾。實(shí)現(xiàn)方式可以是在執(zhí)行前記錄一個(gè)快照失敗時(shí)恢復(fù)到快照。Univer 的數(shù)據(jù)層支持序列化你可以把當(dāng)前工作表的狀態(tài)存下來(lái)出錯(cuò)時(shí)反序列化回去。這個(gè)快照不需要很深只存受影響的范圍即可避免大表上快照開(kāi)銷過(guò)大。另一個(gè)細(xì)節(jié)是并發(fā)。如果多個(gè) Agent 同時(shí)操作同一張表或者 Agent 和用戶同時(shí)操作就可能沖突。Univer 的命令流是有序的但如果你在服務(wù)端和前端各有一份狀態(tài)就要保證命令的應(yīng)用順序一致。我的做法是給每個(gè)命令帶一個(gè)遞增的序號(hào)接收方按序號(hào)應(yīng)用亂序的緩存起來(lái)等前序到達(dá)。這個(gè)機(jī)制和協(xié)同編輯里的 OT 或 CRDT 思路類似但實(shí)現(xiàn)可以簡(jiǎn)化很多因?yàn)?Agent 場(chǎng)景下并發(fā)度通常不高。4.4 前端渲染與交互的銜接前端嵌入 Univer 后用戶和 Agent 操作的是同一張表。用戶手動(dòng)改了一個(gè)單元格Agent 應(yīng)該能感知到Agent 改了數(shù)據(jù)用戶界面也要實(shí)時(shí)更新。Univer 的事件總線可以監(jiān)聽(tīng)數(shù)據(jù)變更把變更同步給 Agent 的上下文。univer.getActiveSheet().onCellChanged((event) { // 把變更推送給 Agent 的上下文 agentContext.updateCell(event.row, event.col, event.value); });這里要注意事件風(fēng)暴。用戶快速輸入時(shí)會(huì)產(chǎn)生大量變更事件如果每個(gè)事件都推給 AgentAgent 的上下文會(huì)被刷爆。建議做一層節(jié)流比如 200 毫秒合并一次只推送最終狀態(tài)。Agent 不需要知道用戶按了哪些鍵它只需要知道最終的數(shù)據(jù)是什么。還有一個(gè)體驗(yàn)問(wèn)題Agent 操作表格時(shí)用戶應(yīng)該能看到過(guò)程。如果 Agent 一次性改了五百個(gè)單元格界面直接跳到最終狀態(tài)用戶會(huì)一臉懵。可以在 Agent 的工具層加一個(gè)“逐步應(yīng)用”的選項(xiàng)每批操作之間留一點(diǎn)間隔讓用戶看到變化。這個(gè)間隔不用太長(zhǎng)50 到 100 毫秒就夠既能看到過(guò)程又不至于太慢。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 公式不重算或重算結(jié)果不對(duì)這是接入初期最常見(jiàn)的問(wèn)題。表現(xiàn)是設(shè)置了公式但單元格顯示的還是舊值或者顯示#ERROR。排查順序是這樣的先確認(rèn)公式字符串本身是否合法有沒(méi)有多余空格、括號(hào)是否匹配、函數(shù)名是否拼錯(cuò)再確認(rèn)依賴的單元格是否有值如果依賴的是空單元格某些函數(shù)會(huì)返回 0 而不是報(bào)錯(cuò)最后確認(rèn)重算是否被觸發(fā)Univer 的公式引擎在數(shù)據(jù)變更后會(huì)自動(dòng)標(biāo)記臟區(qū)但如果你直接改了底層數(shù)據(jù)而沒(méi)走命令可能不會(huì)觸發(fā)重算。解決辦法是統(tǒng)一走 Facade 或命令 API不要直接改數(shù)據(jù)對(duì)象。如果確實(shí)需要直接改改完后手動(dòng)調(diào)用一次calculate()。另外公式里的范圍引用如果超出了表格的實(shí)際行列數(shù)也可能導(dǎo)致計(jì)算異常。建議在 Agent 生成公式后做一次范圍校驗(yàn)確保引用在有效范圍內(nèi)。5.2 大數(shù)據(jù)量下的性能瓶頸當(dāng)表格行數(shù)超過(guò)五千、或者 Agent 頻繁批量寫(xiě)入時(shí)可能會(huì)遇到卡頓。瓶頸通常出現(xiàn)在三個(gè)地方渲染、重算、事件通知。渲染方面Canvas 雖然比 DOM 快但如果每次變更都全量重繪依然會(huì)卡。Univer 內(nèi)部有臟區(qū)重繪機(jī)制但如果你繞過(guò)了它直接操作就會(huì)觸發(fā)全量重繪。重算方面依賴圖越大單次重算越慢尤其是跨表引用多的時(shí)候。事件通知方面如果每個(gè)單元格變更都觸發(fā)一次事件監(jiān)聽(tīng)方處理不過(guò)來(lái)就會(huì)堆積。優(yōu)化手段包括批量提交命令、限制單次操作的范圍、關(guān)閉不必要的事件監(jiān)聽(tīng)、對(duì)大數(shù)據(jù)表做分頁(yè)或虛擬滾動(dòng)。我實(shí)測(cè)過(guò)一個(gè)一萬(wàn)行乘二十列的表批量寫(xiě)入一千行數(shù)據(jù)如果不做優(yōu)化大概要三到四秒做了批量提交和關(guān)閉中間事件后能壓到一秒以內(nèi)。對(duì)于 Agent 場(chǎng)景還可以考慮把重計(jì)算放到 Web Worker 里避免阻塞主線程。5.3 Agent 生成的公式引用錯(cuò)位前面提過(guò)索引問(wèn)題這里再展開(kāi)一下。Agent 通常用自然語(yǔ)言描述位置比如“第二行第三列”模型在轉(zhuǎn)成代碼時(shí)可能把“第二行”理解成索引 2 而不是索引 1。如果 Agent 直接生成 A1 表示法比如C2出錯(cuò)概率會(huì)低一些因?yàn)?A1 表示法和人類的行列描述更接近。建議在工具層強(qiáng)制使用 A1 表示法內(nèi)部再做轉(zhuǎn)換。還有一個(gè)相關(guān)問(wèn)題是相對(duì)引用和絕對(duì)引用的混淆。Agent 如果生成A1B1然后往下拖拽相對(duì)引用會(huì)變成A2B2這可能是它想要的也可能不是。如果 Agent 想固定引用某一行應(yīng)該用$A$1。在工具層可以提供一個(gè)“填充公式”的工具讓 Agent 指定源公式和目標(biāo)范圍由工具來(lái)處理相對(duì)引用的偏移而不是讓 Agent 自己算。5.4 樣式設(shè)置不生效樣式不生效的原因通常有幾個(gè)一是樣式對(duì)象字段名寫(xiě)錯(cuò)Univer 的樣式字段和 CSS 不完全一樣比如背景色是backgroundColor而不是background二是樣式被后設(shè)置的樣式覆蓋比如你先設(shè)了紅色又設(shè)了默認(rèn)樣式結(jié)果紅色沒(méi)了三是樣式應(yīng)用到了錯(cuò)誤的范圍比如行列索引差一位。排查的時(shí)候可以先把樣式設(shè)到一個(gè)單元格上確認(rèn)生效后再擴(kuò)展到范圍。如果范圍樣式不生效檢查范圍的起止行列是否正確。另外合并單元格的樣式要設(shè)在左上角單元格上設(shè)在其他被合并的單元格上不會(huì)顯示。這個(gè)細(xì)節(jié)在文檔里不一定顯眼但實(shí)際用的時(shí)候很容易踩。5.5 常見(jiàn)問(wèn)題速查表現(xiàn)象可能原因排查方向公式顯示 #ERROR公式語(yǔ)法錯(cuò)誤或引用無(wú)效檢查函數(shù)名、括號(hào)、范圍寫(xiě)入后讀不到值異步重算未完成等待 calculate 完成再讀批量寫(xiě)入卡頓逐條提交觸發(fā)多次重算改用批量命令提交樣式不顯示字段名錯(cuò)誤或范圍錯(cuò)誤單單元格測(cè)試后擴(kuò)展Agent 改錯(cuò)位置索引基準(zhǔn)不一致統(tǒng)一用 A1 表示法合并后數(shù)據(jù)丟失合并清空非左上角值合并前先保存值事件重復(fù)觸發(fā)未做節(jié)流合并高頻事件6. 我對(duì)這類項(xiàng)目的一點(diǎn)實(shí)際體會(huì)接入 Univer 做 Agent 辦公能力最深的體會(huì)是“接口的穩(wěn)定性比功能的豐富度更重要”。Agent 不像人類它不會(huì)因?yàn)榻缑婧每淳腿萑?API 的反復(fù)無(wú)常。一個(gè)字段名改了、一個(gè)索引基準(zhǔn)變了Agent 的整條鏈路就可能崩掉。所以在選型的時(shí)候我會(huì)優(yōu)先看這個(gè)項(xiàng)目的 API 是否穩(wěn)定、是否有版本化的文檔、是否有測(cè)試覆蓋。Univer 在這方面做得還算扎實(shí)但快速迭代期難免有 breaking change生產(chǎn)環(huán)境一定要鎖版本。另一個(gè)體會(huì)是Agent 操作辦公軟件本質(zhì)上是在做“結(jié)構(gòu)化數(shù)據(jù)的增刪改查”而不是“模擬人類操作界面”。凡是讓 Agent 去點(diǎn)按鈕、拖滾動(dòng)條、識(shí)別截圖的方案長(zhǎng)期看都不靠譜因?yàn)榻缑嬉蛔兙腿珡U。Univer 這種提供編程接口的思路才是正路。如果你正在設(shè)計(jì) Agent 產(chǎn)品建議盡早把“操作層”和“展示層”分開(kāi)讓 Agent 只依賴操作層的 API展示層怎么改都不影響 Agent。最后分享一個(gè)小技巧在 Agent 的工具層加一個(gè)“dry run”模式讓 Agent 可以先模擬執(zhí)行一遍看看會(huì)產(chǎn)生什么變更確認(rèn)無(wú)誤后再真正提交。這個(gè)模式在調(diào)試階段特別有用能避免 Agent 把測(cè)試數(shù)據(jù)寫(xiě)進(jìn)生產(chǎn)表。實(shí)現(xiàn)上就是在執(zhí)行命令前攔截把命令記錄下來(lái)但不應(yīng)用返回一個(gè)預(yù)覽結(jié)果給 Agent。等 Agent 確認(rèn)后再真正執(zhí)行。這個(gè)機(jī)制花不了多少代碼但能省下很多排查數(shù)據(jù)問(wèn)題的時(shí)間。