快速開始
透過編程 Agent 建立第一個 Office 應用,再了解如何整合和部署。
本文透過三個例項介紹表格聯動、文件協同與供 Agent 使用的 CLI。選擇一個例項,將其 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 文件複製到 Prompt 中。可以從下面的可複用模板開始,也可以直接貼上三個完整例項中的一個。
一個需求範本
將 <…> 替換為你的需求。先描述一個可見的結果,再規劃整套辦公系統。
請用 Univer Office SDK 建立可在本機執行的<應用程式名稱>。先閱讀 https://docs.univer.ai/zh-TW/llms.txt 和相關完整範例,SDK 套件使用相同版本。初始內容:<少量可以直接操作的資料或文字>。核心體驗:<使用者做一個動作,立即看到什麼變化>。驗收條件:<兩到三個具體、可以操作驗證的結果>。只完成這個最小流程,使用原生 Univer 編輯器與真實 SDK 能力。完成後實際啟動,在瀏覽器中驗證,並提供預覽連結。若缺少必要設定,請說明具體缺少什麼。可選:安裝應用建置 Skill
如果程式設計 Agent 支援 Skills,可以安裝 build-with-univer,使其能夠自行查閱 SDK 文件,並理清 Web SDK、Server SDK 和 AI SDK 在應用中的接入方式。
npx skills add dream-num/skills --skill build-with-univer在 Agent 當前開啟的專案中執行該命令。用 npx skills list 確認安裝完成,然後使用上面的模板或下面的例項。以當前文件和專案實際使用的 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。待工具建置完成且 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 可以檢視完整介面。底層 API 見 AI SDK 內容操作,完整程式碼見 CLI SDK Examples。
將第一個流程接入你的應用
Web SDK 提供共用的內容執行時。需要多人共同編輯時加入 Server SDK,需要 Agent 操作內容時加入 AI SDK。各 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 工具、即時預覽和草稿審閱。
全部範例 彙總了各專案的演示和倉庫連結。
你覺得這篇文檔如何?