# CLI

> 为各种 Agent 接入本地 Office 能力：安装、打开样例，再创建可以计算、编辑和审阅的成果。

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.3.0`

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

---

**Univer CLI** 是基于 **[Univer Office SDK](https://docs.univer.ai/zh-CN/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-CN/overview/features/shared/server-calculation.md)
- [文档内容加载与读写](https://docs.univer.ai/zh-CN/ai/content-operations.md)
- [Worktree](https://docs.univer.ai/zh-CN/overview/features/shared/worktree.md)

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