Univer Workspace導入実践:AIによるオフィス文書の共同編集
Univer Workspace導入実践:AIによるオフィス文書の共同編集
プロジェクト概要
オフィス文書の共同編集は常にチームコラボレーションの悩みの種です。特にAIエージェントがコンテンツ作成に参加し始めてから、AIに文書を安全かつ制御可能な方法で変更させる方法が新たな問題となっています。Univer Workspaceはまさにこのシナリオを解決するために誕生しました。独立してデプロイ可能なオープンソースのOfficeワークスペースであり、あなたとAIエージェントが同じプラットフォーム上でSheet、Doc、Slide、Base、Boardを共同で処理できます。
その中核となる設計思想は注目に値します。WorkspaceはBrowser、Server、Agent、CLIの4つの部分で構成されています:
- Browser は直接編集と共同編集のインターフェースを提供し、人間の操作エントリです。
- Server は唯一の権威であり、認証、権限管理、文書ストレージを担当します。
- Agent はDSHベースのローカルWebアプリケーションで、対話、文書プレビュー、変更レビューを一箇所にまとめます。
- CLI はAIエージェントに構造化された自動化エントリを提供し、ターミナルで文書の読み込み、変更、検証を完了できます。
最も優れたメカニズムは Worktree です。Agentが何かを変更する前に、システムはまず分離されたワークツリーを作成し、Agentはその中で自由に編集・検証し、ドラフトが準備できたら人間にレビューを依頼し、承認が得られて初めてメインブランチにマージされます。これにより、途中で生成される変更は共有コンテンツを汚染せず、人間が常に最終決定権を持ちます。
中核となる依存関係と環境
始める前に、コンピュータに以下の基本環境が整っていることを確認してください:
- Node.js 24+:WorkspaceのサーバーとフロントエンドはモダンなJavaScriptに基づいており、Node 24以降が必要です。
- pnpm 11:リポジトリはpnpmを使用して依存関係を管理しており、バージョンは11.xが要求されます。
corepack enableを使用して有効化することをお勧めします。 - Docker:コンテナデプロイメントの場合は、データベースとファイルストレージサービスを実行するためにDockerが必要です。ローカルでのクイック体験には、デフォルトのSQLiteを先に使用できます。
- モデルサービス認証情報:AIエージェントに言語モデルを設定する際、モデルサービスのAPIアドレスとキーが必要です。例:DeepSeekの
DEEPSEEK_API_KEY。 - Workspaceアカウント:Workspaceへのアクセスにはログインが必要で、デフォルトでパスワードによる登録が有効です。
プロジェクト構造ツリー
リポジトリをクローンすると、次のようなディレクトリレイアウトが表示されます:
apps/workspace Workspace Browser、Server、HTTP契約、およびデプロイアプリケーション
apps/cli Agent向けのリモートWorkspace自動化アプリケーション
apps/agent 文書対話とWorktreeレビューのためのWorkspace Agentアプリケーション
packages/client-core プライベートなNodeホスト型Workspace Agent Client機能
packages/reference-provider Browserのみで使用されるプライベートなreferenced-Unitポリシー
packages/dsh-univer-workspace-plugin Workspace AgentのWorkspace機能とブラウザUI
packages/dsh-univer-workspace-skin-plugin Workspace AgentのWorkspaceビジュアルスキン
scripts SDKバージョンとCLIローカル公開ツール
apps/workspace が中核であり、Browserフロントエンド、Serverバックエンド、API契約を含みます。apps/cli はAIエージェント用のコマンドラインツールで、apps/agent はデスクトップレベルの対話インターフェースです。
ステップバイステップの手順
1. ソースコードと環境の準備
まずリポジトリをローカルにクローンし、依存関係をインストールして、環境変数の例をコピーします:
git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
pnpm install
cp apps/workspace/.env.example apps/workspace/.env
デフォルト設定ではSQLiteとローカルファイルストレージが使用され、すぐに利用できます。本番環境にデプロイする場合は、apps/workspace/.env のデータベースとストレージ設定を必要に応じて変更します。
2. Workspaceサービスの起動
バックエンドサーバーを起動します。これは http://127.0.0.1:3020 で動作します:
pnpm workspace:dev:server
別のターミナルでフロントエンドのBrowser開発サーバーを起動します:
pnpm workspace:dev:web
次に http://127.0.0.1:5173 を開くと、ViteはAPIとWebSocketトラフィックを3020ポートのServerに自動的にプロキシします。パスワードでアカウントを登録し、ログインすると、編集可能なWorkspaceが利用できるようになります。
3. AIアシスタントとモデルサービスの接続
AIに文書処理をさせるには、2つの独立した接続が必要です:1つは Workspaceログイン認証情報 で、AIが文書にアクセスできるようにします。もう1つは モデルサービス認証情報 で、AIに「頭脳」を与えて考えることができるようにします。
まずモデルサービスについて。 Workspace Agentのモデル設定はローカルマシンの状態であり、Workspaceユーザーにバインドされません。環境変数で直接注入できます。Agentを起動する前に次を実行します:
export DEEPSEEK_API_KEY=<your-api-key>
モデルサービスの選択肢を増やしたり、より柔軟な価格を希望する場合は、Defapi をチェックしてください。Defapiは集約モデルゲートウェイであり、公式の半額のモデルサービスを提供し、v1/chat/completions、v1/messages、v1beta/models/ などの主要なプロトコルと互換性があります。プラットフォームからAPIルートアドレスとモデルIDを取得したら、同じ環境変数の方法で注入します。これは外部クライアント設定であり、Workspaceの組み込み機能ではないことに注意してください。
次にOAuthコールバックを登録します。 Workspace AgentはブラウザOAuthログインを使用する必要があり、公式ドキュメントでは apps/agent/README.md にインストール手順があるとされています。Agentをインストールする際、ローカルランチャーが完全なトークンURLを出力するため、アプリケーションの登録とコールバック設定を完了する必要があります。
4. Workspace Agentのインストールと起動
AgentはDSHベースのローカルWebアプリケーションであり、インストール手順は apps/agent/README.md を参照してください。インストールが完了したら、Agentを起動すると、Workspaceサービスを選択または起動するように案内され、OAuthコールバックを登録し、ログインページが開きます。
ログイン後、Agentの対話インターフェースで @ を使用してWorkspace内のファイルを参照できます。Agentはファイルの内容を読み取り、変更を加えます。
5. オフィス文書タスクの実行
次にAgentにスプレッドシートを変更させます。対話で次のように入力します:
請查看 @銷售數據 這個 Sheet,把 2024 年每個季度的銷售額匯總成一個新的 Sheet,標註增長率。
Agentは新しいWorktreeを作成し、その中で読み取り、計算、書き込み操作を実行します。このプロセスはメインブランチ上の元のデータに影響を与えません。
6. 結果の確認とマージのレビュー
Agentの変更が完了すると、WorktreeはReady状態になります。BrowserまたはAgentのレビューインターフェースに戻ると、次のものが表示されます:
- Agentドラフトとメインブランチの比較ビュー
- 変更されたセル、新しいSheet
データを注意深く確認し、問題がなければ マージ をクリックします。この時点で初めて変更がメインブランチに反映され、すべてのコラボレーターが更新を確認できます。問題が見つかった場合は、再オープン をマークして、Agentに引き続き修正させることができます。
ここにCLIを使用する代替ルートを提供します。Claude Codeを例にすると、実行環境に univer-workspace-cli がインストールされている場合、次のように操作できます:
npm install --global univer-workspace-cli@latest
npx skills add dream-num/univer-workspace --skill univer-workspace-cli -g
uvw config set workspace.origin http://127.0.0.1:3020
uvw auth login # ブラウザで確認後
uvw auth login --complete
uvw pr list -R <owner>/<slug>
CLIはWorktreeをPRとして管理します。uvw pr view <n> -R <owner>/<slug> --json id で返されるWorktree IDをコピーして、コンテンツコマンドで確認できます。
一般的な問題のトラブルシューティング
起動時にNode.jsのバージョンが低すぎるというメッセージが出る
WorkspaceにはNode.js 24+が必要です。node -v でバージョンを確認してください。バージョンが不十分な場合は、nvmを使用してLTSバージョンをインストールしてください。
pnpm install がハングする、またはエラーが発生する
リポジトリはpnpm 11.24.0を固定で使用しています。corepack enable を実行してからインストールを実行してください。ネットワークの問題で失敗する場合は、ミラーソースを設定して再試行してください。
ブラウザで5173ポートを開いてもコンテンツが表示されない
両方のターミナルがまだ実行されていることを確認してください:pnpm workspace:dev:server と pnpm workspace:dev:web。ViteのプロキシではServerが先に正常に起動している必要があります。
OAuthログイン時にコールバックアドレスが一致しないと表示される
Agent設定のコールバックアドレスがWorkspaceの承認済みコールバックリストと一致しているか確認してください。ローカル開発では、コールバックは通常 http://127.0.0.1:<agent-port>/oauth/callback です。
Agentの対話でモデル認証情報が見つからないというメッセージが出る
モデル認証情報はローカル状態であり、Workspaceユーザーには追従しません。Agentを起動する前に DEEPSEEK_API_KEY をエクスポートしたか、DSH Modelsページでモデルを設定したか確認してください。Agentプロセスごとに個別に設定する必要があります。
マージ時に権限がないというメッセージが出る
Worktreeのマージには文書編集権限が必要です。Browserで現在のアカウントが対応するフォルダーやファイルに対して書き込み権限があるか確認してください。文書がチームのSpaceにある場合は、OwnerまたはAdminが権限を割り当てる必要があります。
追加リーディング / 高度な方向性
Univer Workspaceをさらに深く使用したい場合、以下の方向性は探求する価値があります:
- CLIの高度な使用法:
apps/cli/README.mdを読んで、uvw executeでカスタムスクリプトを実行する方法、uvw inspectで文書構造を検査する方法、uvw screenshotでレイアウトを検証するためのスクリーンショットをレンダリングする方法を学びます。 - MCPサービスの統合:WorkspaceはリモートMCPサービスを提供します。
https://<あなたのworkspace>/mcpをClaude、Cursor、VS Codeに設定すると、これらのAIアシスタントが直接あなたの文書を操作できるようになります。 - HTML Viewミニアプリ:Agentはレポートデータにバインドされたウェブアプリケーションを生成でき、指標、チャート、コントロールがセルと双方向に連携します。意思決定ダッシュボードに適しています。
- Dockerデプロイメント:PostgreSQL + S3ストレージに切り替え、
apps/workspace/README.mdを参照してコンテナ化デプロイを実行します。自動アップグレードとデータ移行をサポートします。
手を動かしてWorkspaceを構築し、AIに最初の月次レポートを処理させると、Worktreeのレビューメカニズムがもたらすコントロール感を実感できます。