# CLI

> 為各種 Agent 接入本機 Office 能力：安裝、打開樣例，再建立可以計算、編輯和審閱的成果。

- Human documentation: [https://docs.univer.ai/zh-TW/overview/examples/cli](https://docs.univer.ai/zh-TW/overview/examples/cli)

- Agent Markdown: [https://docs.univer.ai/zh-TW/overview/examples/cli.md](https://docs.univer.ai/zh-TW/overview/examples/cli.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.3.0`

- Source: [examples/cli.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/examples/cli.zh-TW.mdx)

---

**Univer CLI** 是基於 **[Univer Office SDK](https://docs.univer.ai/zh-TW/overview.md)** 建置的本機 Office 自動化應用，為你正在使用的 Agent 提供內容操作命令和 Skills。它可以處理已有 Excel、Word、PowerPoint 文件，也能建立試算表、文件、簡報、關聯式表格和畫布，結果保存在本機。

**CLI（Command-Line Interface，命令列介面）是目前操作 Univer 的主要方式**，取代先前以 MCP 為主的 Agent 接入方式。Univer CLI 提供 `univer` 命令與 Skills，讓 Agent 在自己的命令執行環境中完成內容編輯、檢查與交付，再透過本機 Viewer 預覽和審閱成果。

[安裝與體驗](#quick-start) · [Skills 運作方式](#skills) · [Skills 目錄](#skills-catalog)

## 適配你正在使用的 Agent

可以在以下 Agent 中使用 Univer CLI：

**OpenCode** · **Claude Code** · **OpenClaw** · **Hermes** · **Codex** · **WorkBuddy** · **Kimi Work**

共同入口是 `univer` 命令和隨版本提供的操作指導。支援 Agent Skills 的宿主可以加載官方 Skill；具備命令執行能力的 Agent 也可以透過自己的工具層調用。對話內預覽卡片等宿主體驗，可參考對應的[集成專案](https://univer.ai/ecosystem)。

## 先看到第一個成果

準備 Node.js 24 或更新版本，並在 Agent 使用的環境中安裝：

```bash
npm install --global univer-cli@latest
npx skills add dream-num/skills -s univer-cli -g
univer doctor
```

`univer doctor` 用於檢查本機執行環境；Skill 幫助 Agent 發現命令、加載對應產品的操作指導，並完成內容檢查與交付。

### 打開官方樣例

在一個新的空目錄中，把下面這段話發給你的 Agent：

```text
使用 Univer CLI 體驗官方樣例。
把 https://univer.ai/cli-assets/hello.univer 下載到目前目錄的 hello.univer，
列出文件中的內容，然後給我本機 Viewer 連結，並介紹我可以體驗哪些功能。
```

先打開已有內容，就能直接體驗原生編輯器。接著可以讓 Agent 修改其中的內容，或嘗試下面的新建任務。

## Skills：Agent 的操作指南

Skills 將內容模型、操作步驟、Facade API 查詢與驗證要求整理成 Agent 可讀取的指引，讓它依任務找到所需能力，完成從編輯到審閱交付的流程。

**探索入口：** 安裝給 Agent 的 [`univer-cli` Skill](https://github.com/dream-num/skills/blob/main/skills/univer-cli/SKILL.md) 協助辨識 Office 任務，再從本機 CLI 載入完整指引。

**執行階段 Skills：** 隨 CLI 一起發佈，與已安裝版本的指令和 Facade API 配套。先載入 `core`，再載入目標產品；涉及嵌入或跨內容公式時，再補充對應主題。

### 依任務載入

通常由 Agent 完成以下讀取；開發者也可以直接查看：

```bash
univer skills list
univer skills get core
univer skills get sheet
univer skills path sheet
```

`list` 列出已安裝的 Skills，`get` 讀取指引，`path` 回傳本機目錄。需要參考資料與範本時，使用 `univer skills get core --full`；特定 API 可透過 `univer api find` 和 `univer api show` 按需查詢。

### Skills 目錄

點擊名稱瀏覽原始碼中的指引。實際執行任務時，以本機 `univer skills get <name>` 回傳的版本為準。

| Skill | 何時使用 |
| --- | --- |
| [`core`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/core/SKILL.md) | 共同流程：理解 Unit 與 Worktree，定位內容、操作、驗證並交付審閱。 |
| [`sheet`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/sheet/SKILL.md) | 試算表（Sheet）：資料、公式、格式、圖表與結果檢查。 |
| [`doc`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/doc/SKILL.md) | 文件（Doc）：段落、豐富文字、表格、圖表與頁面配置。 |
| [`slide`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/slide/SKILL.md) | 簡報（Slide）：頁面、形狀、文字、圖片與視覺檢查。 |
| [`base`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/base/SKILL.md) | 關聯式表格（Relational Table）：表格、欄位、記錄與檢視。 |
| [`board`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/board/SKILL.md) | 畫布（Canvases）：畫布元素、圖表與配置檢查。 |
| [`embed`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/embed/SKILL.md) | 嵌入內容：將一個 Unit 的內容嵌入另一個 Unit，並連接圖表資料來源。 |
| [`cross-unit-formula`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/cross-unit-formula/SKILL.md) | 跨內容公式：從 Sheet 範圍或 Relational Table 欄位取值，在 Sheet 儲存格或公式驅動的形狀中計算。 |

例如，在文件中嵌入試算表，載入順序為 `core → doc + sheet → embed`；讓 Sheet 儲存格或形狀參照其他內容的資料時，再載入 `cross-unit-formula`。不必一開始載入所有指引。更新 CLI 後，應重新載入 `core` 與相關產品、主題 Skills。

## 你可以用它做什麼

- **從資料到成品：** 清洗表格、編寫公式、產生圖表與樞紐分析表；編排帶頁首與頁尾的報告，或根據提綱製作簡報。
- **多種內容保持關聯：** 一個 `.univer` 檔案可以容納多種內容，並透過公式、圖表引用和嵌入連接資料與表達。
- **產生後驗證：** 透過 Facade 讀回實際內容模型，再結合截圖和簡報版面配置檢查，發現文字溢出、重疊和越界等問題。
- **先審閱，再交付：** Agent 在隔離的 Worktree 草稿中工作，返回本機 Viewer 連結；你可以查看差異、要求修改、合併或捨棄，並匯出支援的 Office 格式。畫布目前不提供檔案匯入匯出。

## 試試這樣一個任務

> 用 Univer CLI 建立一個月度開銷表，包含日期、類別、金額和 5 條示例資料，添加總額公式及按類別匯總的圖表。檢查資料與顯示結果後給我 Viewer 連結，在我審閱前不要合併。

## Office SDK 如何支撐

Office SDK 提供 Headless 內容執行環境、Facade API、計算、渲染、版本和 Worktree 能力。CLI 將這些能力組織為終端命令和隨版本提供的 Skills，並負責本機 `.univer` 儲存、Gateway 與 Viewer。Agent 修改的內容可以直接進入編輯器預覽和標準檔案交付流程。

## 體驗與原始碼

[快速體驗指南](https://github.com/dream-num/univer-cli#quick-start) · [原始碼儲存庫](https://github.com/dream-num/univer-cli)

## 繼續瞭解

- [無頭與伺服器端計算](https://docs.univer.ai/zh-TW/overview/features/shared/server-calculation.md)
- [文件載入與內容操作](https://docs.univer.ai/zh-TW/ai/content-operations.md)
- [Worktree](https://docs.univer.ai/zh-TW/overview/features/shared/worktree.md)

[全部示例](https://docs.univer.ai/zh-TW/overview/examples.md)