快速開始

透過編程 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 中。可以從下面的可複用模板開始,也可以直接貼上三個完整例項中的一個。

一個需求範本

將 <…> 替換為你的需求。先描述一個可見的結果,再規劃整套辦公系統。

text
請用 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 在應用中的接入方式。

Bash
npx skills add dream-num/skills --skill build-with-univer

在 Agent 當前開啟的專案中執行該命令。用 npx skills list 確認安裝完成,然後使用上面的模板或下面的例項。以當前文件和專案實際使用的 SDK 版本為準。

實例一:試算表連動

將數量輸入框繫結到表格單元格,並在頁面上顯示公式計算的結果。

text
請用 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。

實例二:文件協作

使用兩個獨立會話編輯同一份文件,確認兩側的修改能夠互相同步。

text
請用 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 完成“生成 → 預覽 → 對話中修改”的完整流程。

text
請用 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 讀取專案說明後,在同一個對話中傳送以下內容:

text
用 you-cli 建立專案週報,包含本週進展、風險與下週計畫,開啟 Web 預覽。

檢視結果後,繼續傳送:

text
在剛才那份週報增加一項風險:交付可能延遲,負責人小林。更新已開啟的預覽。

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 能力。

100%

僅嵌入編輯器時,本地快照即可滿足需求;共享編輯需要後端。Agent 的模型和任務編排保持不變,內容操作交由 AI SDK 處理;需要隔離修改、對比和審閱時再加入 Worktree。

以 Workspace 為例建置與部署

Univer Workspace 將三個 SDK 組成一個完整的辦公空間。以下命令在 Workspace 倉庫根目錄執行,前置條件參見其 README。

  1. 本地開發。 安裝依賴,然後在兩個終端中分別執行 pnpm workspace:dev:server 和 pnpm workspace:dev:web,並開啟 http://127.0.0.1:5173。Web 開發服務會將 API 和 WebSocket 請求轉發到後端。
  2. 建置並執行。 僅建置 Workspace 應用,然後啟動其生產入口:
Bash
pnpm --filter @univerjs/univer-workspace buildpnpm workspace:start

Web 產物位於 dist/public,Server 程式碼位於 dist/server,由同一個 Node.js 程序同時提供靜態頁面和 API。

  1. 準備部署。 配置許可證、身分和資料目錄,持久化業務資料、協同資料和上傳資源,然後重啟服務並確認資料恢復。容器化執行參見 Docker 部署,模組劃分參見 架構說明。

單程序無法滿足需求時,可按照 Server SDK 部署指引 拆分服務。

繼續探索開源專案

  • Univer CLI:在本地工作區中透過 Agent 或終端建立、編輯和檢查 Office 內容,再到 Viewer 中審閱修改。
  • DeepSeek Harness:為已有的 Agent 對話加入 Office 工具、即時預覽和草稿審閱。

全部範例 彙總了各專案的演示和倉庫連結。

你覺得這篇文檔如何?

© 2026 DreamNum Co., Ltd.