Agent と自動化

AI SDK は Univer のモデル、Facade、共同編集を、Agent が呼び出せる TypeScript 機能として提供します。既存の Agent から内容の理解、編集、検証、レビューへの引き渡しを行えます。モデルとツールのプロトコル、タスク制御はアプリケーションが選びます。

既存の Agent に接続する

機能パッケージは構造化された結果を返し、ツール、サービス、CLI に組み込めます。任意の -command パッケージは Commander コマンドを提供します。Agent は Web エディターと同じ内容モデルとコマンド系を操作します。

Runtime が編集可能な状態を復元する仕組み

Collaboration Runtime は生存期間を通して一つの Unit に結び付きます。アプリケーションの backend を開き、UnitData または Snapshot checkpoint と changeset を読み、リモート先端まで連続した revision を再生します。数式モジュールがあれば最新計算結果の適用も待ちます。

fetch() は変更を取得・検証するだけです。pull() は OT でリモート変更と pending/awaiting を調整し、モデルへ適用します。baseRevision、knownHeadRevision、pendingMutationCount、awaitingChangeset で状態を追跡できます。

対象を特定して Facade を実行する

overview で構造を把握し、安定した ID や明確なセレクターで対象を読みます。Snapshot 全体をモデルへ送る必要はありません。Sheet 範囲、Doc 段落、Slide ページ、Relational Table 構造概要、Canvases オブジェクトに対応します。Relational Table 概要はフィールド設定を含みますが、レコード値や View projection は必要に応じ Facade で読みます。

prepareContentExecutionProgram() は Unit ID でルート Facade を取得し、画面上の選択に依存しません。注入変数の再宣言は拒否されます。read モードは永続化する業務操作を実行前に阻止し、write は対象 Unit の mutation を取得します。Unit の作成・破棄は別のライフサイクル操作です。

不明な API は find() で候補を探し、show() で正確な宣言と関連型を確認します。同梱索引はエンジン起動やオンライン文書を必要としません。内容操作とパッケージ概要を参照してください。

実行と送信確認を区別する

execute({ mode: 'write' }) は live Unit を変更して pending を蓄積します。サーバーへの保存完了ではありません。 commit() は識別可能な changeset を送り、ACK の識別子、内容、revision を検証して確定します。

結果不明でも sid + reqId を保持し、backend の冪等な確認により重複編集を防ぎます。backend はこの契約を満たす必要があります。コード途中の例外でも実行済み mutation が残る場合があるため、pending を確認して復旧します。execute() は自動ロールバックするトランザクションではありません。

例は読み込み済み Sheet Runtime を受け取り、実行結果と送信状態を返します。呼び出し側は上表に従って対応し、所有者の終了時に Runtime を閉じます。

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 を再利用する

Worker pool はアプリケーションの key ごとに Runtime を排他的に貸し出します。同じ key の生成は single-flight、lease は FIFO 待ち行列となり、異なる key は別 Worker で処理できます。release() は返却、TTL/LRU は未使用資源の回収、invalidate() は信頼できないインスタンスの破棄を表します。

Key は backend、Unit、Worktree を区別します。Pool は init の意味的な互換性を検証しません。Daemon で pool を保持すれば短い CLI 呼び出しをまたいで再利用できますが、同期と送信確認は必要です。起動時間、常駐メモリー、Worker 数の判断は Runtime 再利用と Daemonを参照してください。

自動化から人によるレビューへ

レポート作成、データ整理、テンプレート入力、コンテンツ生成を構成できます。対象を特定して Facade で書き込み、必要な計算を待ち、値・文字・属性を読み戻して、必要なら視覚検証を追加します。

承認が必要なら Worktree を対象にし、Agent が反復編集・検証して Ready にし、人がレビューして Merge を判断します。複数 Unit の結果は個別に追跡します。複数 Runtime は文書横断の原子的トランザクションになりません。

認証、認可、モデル接続、タスク管理はアプリケーションが担当します。read/write 制限は業務操作の境界であり、信頼できない JavaScript のプロセス分離とファイル・ネットワーク権限もアプリ側で設定します。クイックスタートと Univer CLI の例で体験できます。

機能一覧に戻る