CLI SDK 概览
了解 Univer CLI SDK 如何为 Univer 应用增加 Node.js CLI 与 Agent 操作入口。
Univer CLI SDK 是一套用于构建 Office CLI 的 TypeScript SDK。它为 Agent 和自动化程序提供 Node.js 入口，用于加载、理解、修改和检查 Univer Unit。
CLI SDK 是可组合能力，不是固定形态的产品 CLI。业务应用决定命令名称、参数、目标、身份权限、输出和部署方式。
推荐的应用形态
本文以 CLI + Web + Server 为主线：
- CLI 是 Agent 或用户操作 Unit 的入口；
- Web 展示实际页面，支持交互式编辑和人类审阅；
- Server 保存 CLI 与 Web 共享的 Unit、revision 和协同状态。
CLI、Web 与 Server 可以分别部署，也可以全部运行在本地。先使用 Collaboration SDK 构建 Web + Server， 再增加 CLI 入口，是推荐的学习路径，不是部署限制。
使用 Commander 组织 CLI
CLI SDK 的基础功能包提供结构化 TypeScript API，预设命令包把常用能力转换成原生 Commander Command。
业务应用始终拥有根程序：
import { Command } from "commander";
const program = new Command("my-cli");
program.addCommand(presetCommand);
program.addCommand(applicationCommand);
await program.parseAsync();- 预设命令提供默认参数、help、文本或 JSON 输出；
- 应用级命令组合 Runtime、业务 target、身份、提交或文件策略；
- 两者都是普通 Commander
Command，可以在同一个根程序中混合使用。
后续每个主题都会先介绍基础功能 API，再说明如何接入 Commander。
按能力逐步构建
CLI SDK 文档从最核心的 Unit 内容操作开始，再逐步增加文件、视觉、协作和进程能力：
加载与读写 Unit
→ Office 文件导入导出
→ 视觉检查
→ Worktree 隔离编辑与审阅
→ Runtime 复用与 Daemon1. 加载与读写 Unit
首先建立 Agent 操作 Unit 的最小闭环：使用 Collaboration Runtime 加载 Unit，通过 Inspection 理解内容， 执行 Univer Facade 代码，并在需要时查询 Facade API。
2. 连接 Office 文件边界
使用 Univer Pro Exchange 在 Office 文件与 UnitData 之间转换。导入后的 Unit 继续由 Collaboration Server 保存；导出先通过 Collaboration Runtime 取得最新 UnitData。
3. 增加视觉检查
结构化结果无法完整表达页面布局。Screenshot 为 Agent 提供渲染后的图像，Layout Lint 提供结构化布局诊断。
4. 使用 Worktree 隔离修改
Agent 可以在 Worktree draft 中多轮编辑和检查。完成后标记 Ready，由人类在 Web 中审阅并选择 Merge 或 Reopen。
5. 复用昂贵的 Runtime
从短生命周期 Runtime 开始；当启动成本、并发或跨 CLI 进程复用成为问题时，再增加 pool、worker 或 daemon。