快速開始
透過編程 Agent 建立第一個 Office 應用,再了解如何整合和部署。
本文透過試算表連動、文件協作和 CLI 三個實例介紹 Office SDK 的用法。選擇一個實例,將對應的 Prompt 交給編程 Agent,再依後續步驟整合應用並部署。
先確定你要建立什麼
Office SDK 支援試算表、文件、簡報、關聯式表格、畫布與 PDF。依應用目標找到對應的接入方式。
| 你的目標 | 從哪裡開始 | 第一個完成標準 |
|---|---|---|
| 在應用中嵌入 Office 編輯器 | Web SDK 安裝與基礎用法 | 建立內容,完成編輯、儲存與重新開啟。 |
| 讓 Office 內容與業務介面連動 | Facade API | 頁面輸入與儲存格雙向同步,介面讀取真實計算結果。 |
| 為編輯器加入多人協作 | Server SDK 協作快速開始 | 兩個獨立工作階段編輯同一份內容,修改互相同步。 |
| 匯入、處理並匯出 Office 檔案 | 檔案轉換 | 使用真實檔案完成匯入、修改、匯出並檢查結果。 |
| 讓 Agent 或 CLI 讀寫內容 | AI SDK 內容操作 | 載入內容、檢查結構、執行修改並驗證提交或輸出。 |
| 建立人類與 Agent 共用的工作空間 | Worktree 與審閱流程 | Agent 修改保留於獨立草稿,經人類比較、審閱後合併。 |
這些能力可以組合使用。查看功能總覽確認產品支援範圍;下方三個實例協助你先體驗一段完整流程。
讓 Agent 協助你開始
將需求和 llms.txt 文件索引連結交給程式設計 Agent 即可,不必複製完整 SDK 文件。以下提供一個可重複使用的範本,以及三個可以直接貼上使用的完整實例。
一個需求範本
將 <…> 替換為你的需求。不必先規劃整個辦公系統,先描述一個看得見結果的功能。
請用 Univer Office SDK 建立可在本機執行的<應用程式名稱>。先閱讀 https://docs.univer.ai/zh-TW/llms.txt 和相關完整範例,SDK 套件使用相同版本。初始內容:<少量可以直接操作的資料或文字>。核心體驗:<使用者做一個動作,立即看到什麼變化>。驗收條件:<兩到三個具體、可以操作驗證的結果>。只完成這個最小流程,使用原生 Univer 編輯器與真實 SDK 能力。完成後實際啟動,在瀏覽器中驗證,並提供預覽連結。若缺少必要設定,請說明具體缺少什麼。實例一:試算表連動
將頁面上的數量輸入欄位與試算表儲存格雙向綁定,並在頁面中顯示公式計算的報價總額。
請用 Univer Office SDK 製作可在本機執行的單頁報價工作台。先閱讀 https://docs.univer.ai/zh-TW/llms.txt 和相關完整範例,SDK 套件使用相同版本。使用基礎 Sheets 預設,嵌入可編輯的原生試算表,預設三項商品:顯示器 2 台 × 1200 元,鍵盤 5 個 × 300 元,耳機 3 個 × 200 元。每項金額與合計都使用試算表公式計算。旁邊放「顯示器數量」輸入框與「報價總額」卡片。輸入框與對應儲存格雙向同步,卡片讀取真實公式結果;頁面不要重複計算報價。支援儲存至瀏覽器,重新整理後還原。實際驗證:初始合計 4500 元,數量改為 3 後為 5700 元;直接在試算表修改數量,輸入框與總額也更新;儲存後重新整理仍保留修改。只完成這些功能,實際執行驗證後提供預覽連結。體驗方式: 將顯示器數量從 2 改為 3,看到合計從 4500 變為 5700;再直接編輯試算表,觀察頁面跟隨變化。儲存並重新整理,確認資料還原。接入方式見 Web SDK 安裝與基礎用法與 Facade API。
實例二:文件協作
使用兩個獨立工作階段編輯同一份文件,驗證兩側的修改能否即時同步。
請用 Univer Office SDK 製作可在本機執行的雙人文件協作展示。先閱讀 https://docs.univer.ai/zh-TW/llms.txt,並參考https://github.com/dream-num/univer-collaboration-examples的目前版本範例,前後端 SDK 套件保持相同版本。左右各放一個原生 Univer 現代文件編輯器,代表「小林」和「小陳」。兩側使用獨立執行環境與線上工作階段,連接真實的 Server SDK 協作服務,依官方範例明確載入伺服器建立的同一份文件,預設幾句簡短文字。左側輸入一句話,右側即時出現;右側繼續輸入,左側也更新。透過 SDK 協作協定同步。只使用固定的兩位展示使用者與記憶體儲存,前後端共用一個本機服務,不加入登入、檔案管理或 AI 對話。Pro License 從環境變數讀取;未設定時保留 SDK 預設行為與提示。實際驗證:雙向輸入後內容一致,伺服器確實提交更新,重新整理後可讀回內容。說明服務重新啟動後記憶體資料會重設。只完成這些功能,實際執行驗證後提供預覽連結。體驗方式: 在左側正文輸入一句話,再在右側繼續編輯,觀察雙向同步;重新整理後確認文字保留。此展示使用記憶體儲存,服務重新啟動會重設;部署應用時須接入持久化資料庫。接入方式見 Server SDK 協作快速開始。
實例三:建立自己的 you-cli
讓目前的 Agent 使用你自己的 Office 工具。支援 Sheet、Doc、Slide、Relational Table 與 Canvases,先用一份 Doc 體驗「產生 → 預覽 → 繼續對話修改」。
請用 Univer Office SDK,在目前專案建立自己的 you-cli 與 Web 預覽。先閱讀 https://docs.univer.ai/zh-TW/llms.txt,並參考https://github.com/dream-num/univer-cli-examples 的完整內容操作範例。前後端與 AI SDK 套件使用相容的相同版本,API 以安裝套件型別為準。支援 Sheet、Doc、Slide、Relational Table、Canvases,先用 Doc 完成流程。約定命令:./you-cli create <type> --name <name>、inspect --unit <id>、execute --unit <id> --file <path>、open --unit <id>,並提供 --help。工具放在目前專案,提供使用說明或 Skill,讓目前 Agent 讀取後呼叫。回傳 JSON,包含對應的 unitId、類型、提交結果與預覽 URL。CLI 與 Web 連接同一份真實協作內容,提交後更新已開啟的原生編輯器。寫入後等待提交確認並讀回驗證,內容與清單使用持久化儲存。open 回傳 URL,由 Agent 透過宿主預覽能力開啟;支援時在右側顯示。模型與自然語言理解沿用目前 Agent;授權從環境讀取並保留必要提示。驗收:對話產生專案週報並開啟預覽;接著增加風險與負責人,沿用同一 unitId,預覽自動更新;重新整理與服務重啟後內容仍保留。實際執行驗證,提供預覽連結與用法;僅啟動本例需要的服務。透過對話使用
先把上方 Prompt 交給程式設計 Agent。建立工具並讀取專案說明後,在同一個對話中說:
用 you-cli 建立專案週報,包含本週進展、風險與下週計畫,開啟 Web 預覽。看到內容後繼續說:
在剛才那份週報增加一項風險:交付可能延遲,負責人小林。更新已開啟的預覽。Agent 會沿用原文件的 unitId。支援預覽面板的宿主可在右側顯示,其他環境使用回傳的瀏覽器連結。
you-cli 命令參考
以下為上方 Prompt 約定的專案內命令。將 UNIT_ID 替換為 create 回傳的 unitId;edit.js 由 Agent 依 Facade API 編寫。
| 操作 | 命令 | 結果 |
|---|---|---|
| 建立 | ./you-cli create doc --name "專案週報" | 建立文件並回傳 unitId;也可選 sheet、slide、base、board。 |
| 檢查 | ./you-cli inspect --unit UNIT_ID | 讀取真實內容與目前版本。 |
| 修改 | ./you-cli execute --unit UNIT_ID --file edit.js | 執行修改,等待提交並回傳結果。 |
| 預覽 | ./you-cli open --unit UNIT_ID | 回傳同一份文件的 Web URL,由 Agent 開啟。 |
也可執行 ./you-cli --help。操作流程見 AI SDK 內容操作,完整程式碼見 CLI SDK Examples。
將第一個流程接入你的應用
Web SDK 提供共同的內容執行環境。需要共享編輯或 Agent 操作時,在此基礎上接入 Server SDK 與 AI SDK。具體分工見 Office SDK 總覽。
| 接入步驟 | 在應用中完成什麼 | 繼續閱讀 |
|---|---|---|
| 掛載編輯器 | 將預設掛載至頁面,以 Facade API 連接業務互動;處理快照儲存與實例銷毀。 | Web SDK 接入 |
| 連接後端 | 沿用身分與權限,為共享文件設定資料庫;按需加入檔案匯入匯出。 | 協作接入、檔案轉換 |
| 連接既有 Agent | 將內容讀寫、計算與驗證封裝為工具或 CLI;需要審閱時再接入 Worktree。 | AI SDK 內容操作、Worktree |
應用架構
既有應用與 Agent 可以共用 Office 內容。介面負責互動,Agent 透過工具執行操作,業務服務沿用你的身分、權限與儲存。
藍色節點由你提供與管理: 應用介面、既有 Agent、業務 API(含身分與權限)、資料庫與檔案儲存。其餘標有 SDK 的節點代表整合至應用的 Univer 能力。
僅嵌入編輯器時可從本機快照開始,共享編輯再連接後端。Agent 繼續使用既有模型與任務編排,透過 AI SDK 操作內容;需要隔離修改、比較與審閱時,再組合 Worktree。
以 Workspace 為例建置與部署
Univer Workspace展示如何將三個 SDK 組成完整的辦公空間。以下指令在 Workspace 儲存庫根目錄執行,環境準備以 README為準。
- 本機開發。 安裝相依套件後,在兩個終端機分別執行
pnpm workspace:dev:server與pnpm workspace:dev:web,開啟http://127.0.0.1:5173。Web 開發服務將 API 與 WebSocket 請求轉送至後端。 - 建置並執行。 僅建置 Workspace 應用,再啟動正式入口:
pnpm --filter @univerjs/univer-workspace buildpnpm workspace:startWeb 產物位於 dist/public,Server 產物位於 dist/server,由一個 Node.js 程序提供靜態頁面與 API。
規模擴大後,再參考 Server SDK 部署指引拆分服務。
繼續探索開源專案
- Univer CLI:在本機工作區透過 Agent 或終端機建立、編輯與檢查 Office 內容,並透過 Viewer 審閱修改。
- DeepSeek Harness:在既有 Agent 對話接入 Office 工具、即時預覽與草稿審閱。
查看全部範例,取得各專案的展示與儲存庫連結。
你覺得這篇文檔如何?