Univer Workspace: デプロイとAIスプレッドシート実践

AI が生成したスプレッドシートの内容がチャットウィンドウに留まるだけでは、その後の編集、コラボレーション、レビューが途切れてしまいます。Univer Workspace は、ドキュメント、スプレッドシート、AI 操作を同じワークスペースにまとめ、Agent が分離された Worktree 内で変更し、私たちがレビューした後にマージできるようにします。今日は一緒にローカルデプロイを完了し、売上スプレッドシートで Agent による集計と数式の生成を試します。

プロジェクト概要

Univer Workspace は、Univer Office SDK をベースに構築され、独立してデプロイできるオープンソースの Office ワークスペースです。解決する中心的な問題は、AI が生成したオフィスコンテンツを手動でエディタに移す必要があり、その後の変更がコラボレーションやレビューを困難にしていることです。

プロジェクトは、Browser、Agent、CLI の3つの入口を同じ Workspace Server に接続し、人間と AI が Sheet、Doc、Slide、Base、Board を共同で処理できるようにします。Agent は分離された Worktree 内で作業し、変更を検証します。私たちが確認したコンテンツだけが共有 trunk にマージされます。Workspace Browser で直接編集することも、Workspace Agent にドキュメントの横で対話してコンテンツを生成させ、コードレビューのようにスプレッドシートの変更をレビューすることもできます。

適用シーンと前提環境

典型的なシーンは売上データ分析です。チームは売上明細スプレッドシートを Workspace に置き、Agent に地域ごとの集計と数式の生成をさせ、私たちはコードレビューのようにスプレッドシートの変更をレビューします。

開始前に必要なもの:

  • ターミナルを操作でき、JavaScript/TypeScript の設定を読めること
  • Git がインストールされていること
  • Node.js 24 以降
  • pnpm 11.24.0
  • Agent との対話に使うモデル API Key
  • スクリーンショットやレイアウト確認を行う場合は Chrome/Chromium

Workspace へのログインとモデル認証情報は別物です。ドキュメントの閲覧にはモデルリクエストは不要で、Agent と対話するときだけモデル認証情報が必要です。

核心依存関係と環境

リポジトリの .npmrc は、@univer-cli、@univerjs、@univerjs-pro、@univerjs-labs を https://insider-npm-registry.univer.work/ に向けています。インストール時には、このプライベート Registry と公共の npm Registry の両方にアクセスする必要があります。

DSH Runtime は packages/dsh-runtime によって @deepseek-ai/[email protected] に固定されています。ソースコードは Apache-2.0 ですが、Univer SDK の利用条件はソースコードのライセンスと完全に同じではありません。内蔵ランタイムの開発用認証情報は90日ごとにローテーションされ、サーバー側の Collaboration/Exchange SDK には license key が必要です。いずれかの値が欠けている場合は無料枠にフォールバックします。

プロジェクト構造ツリー

apps/workspace                 Workspace Browser、Server、HTTP 契约与部署应用
apps/agent                     用于文档对话与 Worktree 审查的 Workspace Agent
apps/cli                       面向 Agent 的远程 Workspace 自动化应用
packages/client-core           私有 Node-hosted Workspace Agent Client 能力
packages/dsh-runtime           固定 DSH 运行时版本与依赖图
scripts                        SDK 版本与发布工具

ステップバイステップ手順

1. 固定バージョンをクローンして依存関係をインストール

まずチュートリアルで使う commit に固定し、後続の変更がコマンドに影響しないようにします。

git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
git checkout c1a5fb3dc9d5951cbf618f76639466feac5da4d7
pnpm install --frozen-lockfile

この手順ではプライベート Registry と公共の npm Registry にアクセスします。ネットワークが制限されている場合は、文末のよくある質問を先に確認してください。

2. モデル接続を設定

Agent を起動する前に、ログインとモデル認証情報の役割分担を理解してください。Workspace へのログインはデータアクセスのみを許可します。Agent と対話するとき、DSH はモデルリクエストを、設定した chat completions エンドポイントに送信します。Agent に売上スプレッドシートを分析させて数式を生成させる場合は、モデルで利用可能な baseURL、API Key、model を事前に用意してください。

DSH の deepseek-official アダプターは baseURL + /chat/completions にリクエストを送信するため、baseURL は /v1 の階層まで指定し、パスを重ねて連結しないでください。

モデルコストを抑えたい場合は、Defapi のような OpenAI 互換ゲートウェイを利用できます。Defapi は統一されたモデル接続を提供し、公式の約半額の課金が特徴です。具体的なモデルと価格はコンソールを基準にしてください。公式サイト https://defapi.org に明確な入り口があります。基本的に v1/chat/completions、v1/messages、v1beta/models/ プロトコルと互換性があります。設定時は baseURL を Defapi コンソールが表示する chat completions ベース URL に指定すればよいです。

export DEEPSEEK_API_KEY="<Defapi 控制台创建的 API Key>"
export DEEPSEEK_BASE_URL="<Defapi 控制台显示的 chat completions 基址,例如 https://xxx/v1>"
export UWH_MODEL_SETTINGS_ENABLED=true

モデル ID はコンソールで実際に利用できる一覧に従います。DSH のデフォルトモデル ID が Defapi コンソールと一致しない場合は、DSH Models ページのモデル一覧でコンソールで利用できる ID に変更できます。本番環境ではデフォルトで Models ページが非表示になります。UWH_MODEL_SETTINGS_ENABLED=true を設定すると表示されます。ローカルで NODE_ENV=production を設定していない場合、ネイティブ DSH Models ページを直接開くことができます。

3. Workspace 環境設定を作成し、Agent OAuth クライアントを登録

Workspace はデフォルトでは Agent OAuth クライアントを登録しません。.env.example をコピーするだけでは不十分です。

cp apps/workspace/.env.example apps/workspace/.env

次に apps/workspace/.env を編集し、コメントアウトされていない1行の設定を追加します。

OAUTH_CLIENTS_JSON={"clients":[{"clientId":"univer-workspace-harness","clientType":"public","requiresConsent":true,"redirectUris":["http://127.0.0.1:3101/auth/oauth/callback"],"scopes":["identity","session"]}]}

すでに OAUTH_CLIENTS_JSON がある場合は、上記のクライアントを clients 配列に追加し、設定項目は常に1つだけを保持してください。

4. Workspace Server と Browser を起動

1つ目のターミナルで Server を起動します:

pnpm workspace:dev:server

2つ目のターミナルで Browser 開発サーバーを起動します:

pnpm workspace:dev:web

http://127.0.0.1:5173 を開き、ローカル Workspace アカウントを登録するか、既存アカウントでログインします。ローカル登録には GitHub/Discord OAuth は不要です。2つのプロセスを起動したままにしてください。

5. DSH Runtime と Agent Profile をビルドし、ローカル Agent を起動

Agent はローカル Web アプリです。まずソースコードから DSH ランタイムを組み立てる必要があります。次のコマンドは client-core と3つのバンドルをビルドし、Profile を隔離ディレクトリにインストールします。

export UWH_LOCAL_ROOT="${XDG_CACHE_HOME:-$HOME/.cache}/univer-workspace-harness"
export UWH_DSH_BOOTSTRAP="$UWH_LOCAL_ROOT/dsh-cli"
export DSH_HOME="$UWH_LOCAL_ROOT/install"
export UWH_DSH_DATA_HOME="$UWH_LOCAL_ROOT/data"
mkdir -p "$UWH_DSH_BOOTSTRAP" "$DSH_HOME/internal-packages"
export UWA_PACKAGES="$(mktemp -d "$DSH_HOME/internal-packages/build.XXXXXX")"

pnpm --dir packages/dsh-runtime install --frozen-lockfile
pnpm --dir packages/dsh-runtime deploy --legacy \
  --filter @univerjs/univer-workspace-dsh-runtime \
  --prod --config.node-linker=hoisted "$UWH_DSH_BOOTSTRAP"
export DSH_BIN="$UWH_DSH_BOOTSTRAP/node_modules/@deepseek-ai/dsh/lib/bin.js"

pnpm --filter @univerjs/univer-workspace-client-core build
pnpm --filter @univerjs/workspace-agent build
pnpm --filter dsh-univer-workspace-plugin build
pnpm --filter dsh-univer-workspace-skin-plugin build
pnpm --filter @univerjs/workspace-agent pack \
  --pack-destination "$UWA_PACKAGES"
pnpm --filter dsh-univer-workspace-plugin pack \
  --pack-destination "$UWA_PACKAGES"
pnpm --filter dsh-univer-workspace-skin-plugin pack \
  --pack-destination "$UWA_PACKAGES"

export DSH_PLUGINS="file:$UWA_PACKAGES/univerjs-workspace-agent-0.1.0.tgz file:$UWA_PACKAGES/dsh-univer-workspace-plugin-0.1.0.tgz file:$UWA_PACKAGES/dsh-univer-workspace-skin-plugin-0.1.0.tgz"
NPM_CONFIG_USERCONFIG="$PWD/.npmrc" ./apps/agent/scripts/build-profile.sh

export UWH_RENDER_PAGE_ROOT="$PWD/packages/client-core/dist/render-runtime"
export UWH_RENDER_BROWSER="${UWH_RENDER_BROWSER:-$(command -v google-chrome || command -v chromium || true)}"

node apps/agent/scripts/start-local.mjs --port 3101 \
  --no-open --trusted-host 127.0.0.1

コマンドは start-local.mjs のフォアグラウンドで停止しますが、正常です。stderr に dsh web: で始まる行が現れるまで待ち、その行の URL 全体をコピーしてください。

3101 が使用中の場合は、別の明確なポートに変更し、第3ステップの redirectUris も合わせて修正してください。

6. Workspace に接続して OAuth を完了する

ブラウザで dsh web: が出力した完全な URL を開きます。そこには使い捨ての ?token=... が含まれています。DSH は HttpOnly Cookie を設定し、ルートアドレスにリダイレクトします。

# 复制启动器输出的完整地址,例如:
# http://127.0.0.1:3101/?token=<one-time-token>

次に Agent 画面で 設定 → Workspace に進み、ローカルサービスのアドレスを入力します:

http://127.0.0.1:5173

Sign in to Workspace をクリックし、Workspace の承認ページでアクセスを承認します。Workspace はローカル Agent のコールバックにリダイレクトし、Agent は PKCE で認可コードを交換します。戻ると、サイドバーにアカウントと個人 Space が表示されます。

接続ページが待機し続ける場合は、Check again をクリックし、start-local.mjs を実行したままにしてください。

7. サンプル売上スプレッドシートを作成し、Agent に集計と数式を生成させる

サイドバーで ファイル を開き、個人またはチームの Space を選択して、新しいスプレッドシートを作成し、売上明細を入力します:

日期,区域,销售额
2025-01-05,华东,12800
2025-01-06,华南,9600
2025-01-07,华东,15100
2025-01-08,华南,14200

セッション に戻り、新しいセッションを作成し、入力欄に @ を入力して作成したばかりのスプレッドシートを選択し、送信します:

@销售明细 请按区域汇总销售额,并在表格中新增一列计算每个区域的平均销售额。

送信後、Agent は現在の Workspace に基づいて参照を検証し、変更を Worktree に書き込みます。共有 trunk を直接変更することはありません。

8. Worktree の差分を確認し、マージまたは破棄する

Worktree タブを開き、進行中のタスクを見つけます。レビュー画面はデフォルトで「変更効果」を表示します。「差分」に切り替えると、追加・変更・削除されたドキュメントを確認できます。結果が正しいことを確認したら「マージ」をクリックします。不満があれば下書きに戻すか破棄できます。マージして初めて共有 trunk が更新されます。

创建 Worktree
→ Agent 编辑并验证隔离草稿
→ Ready
→ 人工审阅
→ Merge 或 Reopen
→ trunk

Agent が univer_lint または univer_screenshot を実行した場合、バージョンが一致する静的レンダリングページと Chrome/Chromium が必要です。UWH_RENDER_PAGE_ROOT またはブラウザがない場合、ツールは前提条件エラーを明確に報告し、視覚検証を通過としてマークしません。

よくある問題のトラブルシューティング

1. pnpm install がプライベート Registry にアクセスできない

インストール時にはプライベート Registry と公共の npm Registry の両方にアクセスする必要があり、どちらも欠かせません。止まったままになるか401が発生する場合は、まずネットワークから https://insider-npm-registry.univer.work/ にアクセスできることを確認し、その上で Node と pnpm のバージョンを確認してください。.npmrc の registry 行は削除しないでください。

2. OAUTH_CLIENT_UNAVAILABLE が表示される

Workspace サーバーが Agent OAuth クライアントを読み込んでいません。apps/workspace/.env の OAUTH_CLIENTS_JSON に univer-workspace-harness が含まれているか確認し、変更後に Server を再起動してください。.env.example をコピーするだけでは、このクライアントは登録されません。

3. INVALID_REDIRECT_URI が表示される

コールバックアドレスは正確に一致する必要があります。localhost と 127.0.0.1 は異なる登録になります。Agent のポートを変更した場合は、redirectUris も合わせて修正し、Workspace バックエンドを再起動してください。この登録が制御するのは OAuth コールバックであり、3101 ポートへの一般的な CORS 許可ではありません。

4. ルートアドレスを開くと401が返る

トークン付きの完全な URL を最初に開いていない場合、ブラウザにセッション Cookie がありません。ランチャーが出力した dsh web: アドレスを再度開いて交換を完了し、その後はパラメータなしのルートアドレスを使用できます。使い捨てトークンは再利用しないでください。

5. Workspace のログインは成功するがモデルメッセージが失敗する

Workspace OAuth はデータアクセスのみを許可し、モデルの認証情報は別途設定する必要があります。DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL、モデル ID を確認してください。Defapi を使用する場合、baseURL はコンソールが表示する chat completions ベース URL を指定し、/chat/completions を重ねて連結しないでください。

6. Agent の接続ページが待機し続ける

start-local.mjs を実行したままにしてください。接続状態の変化後、準備完了チェックが行われます。アカウントサービスの読み込みに失敗した場合は、ランチャーのログを確認してください。認可リクエストの期限が切れた場合は、設定 → Workspace から再ログインします。このフローはブラウザ OAuth を使用するため、デバイスコードの入力は不要です。

7. スクリーンショット/レイアウト確認で前提条件エラーが発生する

univer_lint と univer_screenshot は、UWH_RENDER_PAGE_ROOT が静的レンダリングページを指し、UWH_RENDER_BROWSER が互換性のある Chrome/Chromium を指す必要があります。ブラウザがない場合は、実行可能ファイルのパスを UWH_RENDER_BROWSER に設定してから Agent を起動してください。

参考情報 / 次のステップ

  • Docker デプロイ: Workspace は独立してデプロイできるアプリを提供しています。公式アプリガイドに従ってイメージをビルドし、Server、Browser、ストレージをサーバーに配置できます。
  • CLI 自動化: univer-workspace-cli をインストールし、Claude、Codex、Kimi Work などの既存 Agent 環境に接続して、CLI でドキュメントと Worktree を処理できます。
  • MCP 接続: Workspace はリモート MCP サービスを公開しており、Streamable HTTP と OAuth をサポートしています。Cursor、VS Code、Claude Desktop などのクライアントから直接接続できます。
  • 公式ドキュメントと固定バージョン: Univer Web SDK ドキュメント、Server SDK ドキュメント、Workspace 設定ドキュメント。本チュートリアルは c1a5fb3dc9d5951cbf618f76639466feac5da4d7 に基づいて作成されています。以降のバージョンは公式ドキュメントを基準にしてください。