Agent 与自动化

把内容检查、编辑和验证组合为工具,让已有 Agent 操作 Office 内容。

AI SDK 将 Univer 的内容模型、Facade 和协同能力封装为一组可组合的 TypeScript 能力。已有的 Agent 可以读取并修改内容,检查结果,然后交付人工审阅。模型选择、工具协议和任务编排均由应用决定。

把内容能力接到现有 Agent

能力包返回结构化结果,应用可以将其接入自己的工具、服务或 CLI。可选的 -command 包将同一批能力封装为原生 Commander 命令。无论采用哪种接入方式,Agent 操作的都是与 Web 编辑器共用的内容模型和命令系统。

能力实际职责
Inspection读取结构、区域、段落和对象细节,以缩小任务范围。
API Reference离线查询随包分发的 Facade 声明、重载、类型和示例。
Content Execution将 workbook、doc、presentation、base 或 board 绑定到指定的 Unit,并生成待执行的代码。
Collaboration Runtime加载内容、捕获 mutation、协调远端变更,并显式提交 changeset。

Runtime 如何还原可编辑状态

一个 Collaboration Runtime 从创建到销毁只绑定一个 Unit。加载时,它先打开应用提供的 backend,读取 UnitData 或 Snapshot checkpoint,并在此基础上重放 changeset,随后将 revision 连续补齐到远端 head。如果安装了公式模块,它还会等待最新计算结果应用完成。

100%

fetch() 负责取回变更并对其进行校验。pull() 通过 OT 协调远端变更与本地的 pending、awaiting 状态,然后应用协调结果。Runtime 还维护 baseRevision、knownHeadRevision、pendingMutationCount 和 awaitingChangeset,应用可据此判断进度。

先定位内容,再执行 Facade

先向模型提供一份 overview,再按稳定 ID 或精确选择器查询目标,而不是直接发送整份 Snapshot。Inspection 覆盖 Sheet 区域、Doc 段落、Slide 页面、Relational Table 的结构概览和 Canvases 对象。Relational Table 的概览包含字段配置,但不包含记录值和 View projection;需要时应通过 Facade 读取这些内容。

prepareContentExecutionProgram() 通过 Unit ID 取得根 Facade,不依赖浏览器当前选中的文档,并会拒绝重复声明同一个注入变量。read 模式下,Runtime 会在执行前拦截任何会产生持久化的业务操作;write 模式则捕获目标 Unit 的 mutation。创建和销毁 Unit 属于独立的生命周期操作,不在这个只处理单个 Unit 的执行入口范围内。

遇到不熟悉的 API 时,find() 列出候选,show() 输出准确的声明及相关类型。这份索引随 SDK 一起分发,既不需要内容引擎,也不依赖在线文档。接入细节见内容操作与 Package 概览。

执行成功与提交确认是两件事

execute({ mode: 'write' }) 会修改 live Unit,并将 mutation 累积为 pending。这不表示服务端已经保存变更。 commit() 将 mutation 组成一个附带提交身份的 changeset;返回的 ACK 必须与身份、内容和 revision 一致,提交才算确认。

提交状态应用应如何处理
confirmed / nothing-to-commit变更已确认,或者没有需要提交的内容。
pull-required远端 revision 已前进。先调用 pull() 协调,再重新调用 commit()。
retry / unknown在同一个 Runtime 中保留 awaiting 状态并重试 commit(),不要重新执行编辑代码。
conflict停止写入,由应用决定恢复方式或重新加载。

提交结果不确定时,Runtime 会保留 sid + reqId,backend 可据此以幂等方式确认同一个 changeset,避免重复写入编辑内容。backend 必须实现这套幂等约定。代码执行中途抛出异常时,此前已产生的 mutation 可能仍然保留,因此需要检查 pending 状态再决定如何恢复。execute() 不是会自动回滚的事务。

下面的示例接收一个已加载的 Sheet Runtime,同时返回执行结果和提交结果。调用方按上面的状态表处理后续动作,并在持有期结束时关闭 Runtime。

TypeScript
import { prepareContentExecutionProgram } from '@univer-cli/content-execution'import type { UniverCollaborationRuntime } from '@univer-cli/univer-collaboration-runtime'async function updateSales(runtime: UniverCollaborationRuntime) {  const pulled = await runtime.pull()  if (pulled.status === 'conflict') return pulled  const code = prepareContentExecutionProgram({    unitId: runtime.unitId,    unitType: 'sheet',    code: `      const sheet = workbook.getSheetByName('Data');      if (!sheet) throw new Error('Worksheet Data not found');      sheet.getRange('A2:B2').setValues([        [{ v: 'East', t: 1 }, { v: 128000, t: 2 }]      ]);      return sheet.getRange('A2:B2').getRawValues();    `,  })  const execution = await runtime.execute({ mode: 'write', code })  const commit = await runtime.commit()  return { execution, commit }}

高频任务如何复用 Runtime

高频任务可以按应用定义的 key,从 Worker Runtime 池中独占租用一个实例。同一个 key 的冷创建是 single-flight 的,lease 按 FIFO 顺序排队,不同的 key 可以分配到不同的 Worker。release() 归还实例,TTL/LRU 回收空闲资源,invalidate() 淘汰已不可信的实例。

key 应能区分 backend、Unit 和所在的 Worktree。池不会验证两次初始化输入在语义上是否兼容。Daemon 可以跨多次短 CLI 调用持续持有这个池,但复用的 Runtime 仍然需要同步并确认提交。启动成本、常驻内存和 Worker 数量需要权衡,详见 Runtime 复用与 Daemon。

从自动化任务到人类审阅

将这些能力组合起来,可以用于生成报表、整理业务数据、填充模板或生成内容。流程依次为:定位目标,通过 Facade 写入,等待结果所依赖的计算完成,回读数值、文本和对象属性;需要查看渲染效果时,再加入截图与视觉检查。

需要人工确认时,Agent 在 Worktree 中修改内容。它分多轮进行编辑和自检,内容进入 Ready 状态后由人审阅,决定是否 Merge。跨 Unit 的任务需要按 Unit 分别追踪执行和提交结果,因为多个 Runtime 合起来并不构成跨文档的原子事务。

身份、授权、模型接入和任务生命周期仍由应用负责。read/write 限制约束的是业务操作的边界;不可信 JavaScript 的进程隔离、文件和网络权限仍需由应用配置。完整流程可从快速开始和 Univer CLI 示例开始。

通过 Skills 生成与编辑内容

如需让现有 Agent 直接处理 Office 内容,可按文件所在位置选择对应的应用:

  • CLI Skills:创建、编辑和检查本地 Office 文件,再打开 Viewer 审阅。
  • Workspace Skills:处理已连接 Space 中的文件,生成 Office 内容和 Web App,并将改动交付协作与审阅。

返回功能总览

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.