# はじめに

> コーディング Agent で最初の Office アプリを作成し、組み込みとデプロイの手順を確認します。

- Human documentation: [https://docs.univer.ai/ja-JP/overview/get-started](https://docs.univer.ai/ja-JP/overview/get-started)

- Agent Markdown: [https://docs.univer.ai/ja-JP/overview/get-started.md](https://docs.univer.ai/ja-JP/overview/get-started.md)

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.3.0`

- Source: [get-started.ja-JP.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/get-started.ja-JP.mdx)

---

このガイドでは、表計算との連動、文書の共同編集、Agent 用 CLI の3つの例で Office SDK の使い方を紹介します。例を1つ選び、プロンプトをコーディング Agent に渡してから、アプリへの組み込みとデプロイを進めます。

## 最初に作るものを決める

Office SDK は Sheets、Docs、Slides、Relational Tables、Canvases、PDF に対応します。アプリの目的に合う導入方法を選んでください。

| 目的 | 開始するガイド | 最初の完了条件 |
| --- | --- | --- |
| Office エディターを組み込む | [Web SDK のインストール](https://docs.univer.ai/ja-JP/guides/sheets/getting-started/installation.md) | コンテンツを作成、編集、保存し、再度開ける。 |
| コンテンツと業務画面を連動させる | [Facade API](https://docs.univer.ai/ja-JP/guides/sheets/getting-started/facade.md) | 入力欄とセルが双方向に連動し、実際の計算結果を表示できる。 |
| 共同編集を追加する | [Server SDK 共同編集クイックスタート](https://docs.univer.ai/ja-JP/server/collaboration/quick-start.md) | 独立した2つのセッションで同じ内容を編集し、互いの変更が同期される。 |
| Office ファイルを取り込み、処理し、書き出す | [ファイル変換](https://docs.univer.ai/ja-JP/server/import-export/node.md) | 実際のファイルを取り込み、編集、書き出し、結果を確認できる。 |
| Agent や CLI からコンテンツを操作する | [AI SDK コンテンツ操作](https://docs.univer.ai/ja-JP/ai/content-operations.md) | 読み込み、構造確認、変更を実行し、確定結果や出力を検証できる。 |
| 人と Agent の共通ワークスペースを作る | [Worktree とレビュー](https://docs.univer.ai/ja-JP/ai/worktree.md) | Agent の変更を独立した下書きに保持し、人が比較・レビューしてマージできる。 |

これらの機能は組み合わせられます。[機能一覧](https://docs.univer.ai/ja-JP/overview/features.md)で製品ごとの対応範囲を確認し、以下の3つの例でまず1つの流れを体験してください。

## Agent と開発を始める

要件と [llms.txt](/llms.txt) のドキュメント索引リンクをコーディング Agent に渡します。SDK ドキュメント全体をコピーする必要はありません。以下のテンプレートか、完成した3つの例をそのまま使えます。

### 要件テンプレート

`<…>` を自分の要件に置き換えます。Office システム全体を設計する前に、結果が見える機能を1つ決めましょう。

```text
Univer Office SDK で、ローカルで動作する<アプリ名>を作ってください。
最初に https://docs.univer.ai/ja-JP/llms.txt と関連する完全な例を読み、
SDK パッケージのバージョンを揃えてください。

初期コンテンツ：<すぐ操作できる少量のデータや文章>。
中心となる体験：<ユーザーの操作1つと、直後に見える変化>。
受け入れ条件：<操作して確認できる具体的な結果を2〜3個>。

ネイティブの Univer エディターと実際の SDK 機能で、この流れだけを実装してください。
実際に起動し、ブラウザーで検証してプレビューリンクを提示してください。
必要な設定が不足している場合は、具体的に説明してください。
```

### 例1：表計算との連動

数量の入力欄とセルを双方向に連動させ、数式で計算した見積総額をページに表示します。

```text
Univer Office SDK で、ローカルで動作する単一ページの見積アプリを作ってください。
https://docs.univer.ai/ja-JP/llms.txt と関連する完全な例を読み、
SDK パッケージのバージョンを揃えてください。

基本の Sheets プリセットで編集可能なネイティブシートを組み込みます。
モニター2台×1200、キーボード5個×300、ヘッドセット3個×200を用意し、
各行の金額と合計はシートの数式で計算してください。

横に「モニター数量」の入力欄と「見積合計」のカードを置きます。
入力欄とセルを双方向に連動させ、カードは実際の数式結果を読み取ります。
画面側で金額を再計算せず、ブラウザーへの保存と再読み込みでの復元に対応します。

初期合計4500、数量を3にすると5700になることを確認してください。
セルを直接編集しても入力欄と合計が更新され、保存後の再読み込みで復元されること。
この機能だけを実装し、実際に動作確認してプレビューリンクを提示してください。
```

**試し方：** モニターの数量を2から3に変え、合計が4500から5700になることを確認します。シートを直接編集し、画面が追従することも確認します。保存して再読み込みし、復元を確かめてください。[Web SDK のインストール](https://docs.univer.ai/ja-JP/guides/sheets/getting-started/installation.md)と [Facade API](https://docs.univer.ai/ja-JP/guides/sheets/getting-started/facade.md)も参照できます。

### 例2：文書の共同編集

独立した2つのセッションで同じ文書を編集し、双方の変更がリアルタイムに同期されることを確認します。

```text
Univer Office SDK で、ローカルで動作する2人の文書共同編集デモを作ってください。
https://docs.univer.ai/ja-JP/llms.txt と、次のリポジトリの現行例を参照し、
https://github.com/dream-num/univer-collaboration-examples
フロントエンドとサーバーの SDK バージョンを揃えてください。

Alice と Bob 用のネイティブなモダン文書エディターを左右に置きます。
独立した実行環境とオンラインセッションで実際の Server SDK 共同編集サービスに接続し、
公式例に従ってサーバーが作成した同じ文書を明示的に読み込みます。短い文章を用意します。

左で入力すると右に表示され、右で続けて入力すると左も更新されるようにします。
SDK の共同編集プロトコルを使い、固定のデモユーザー2人とメモリー内ストレージだけを使います。
前後端を1つのローカルサービスで提供し、ログイン、ファイル管理、AI チャットは追加しません。
Pro License は環境変数から読み込み、未設定なら SDK の既定の動作と表示を維持します。

双方向の入力後に内容が一致し、サーバーで更新が確定することを確認してください。
再読み込み後も内容が復元されること、サービスの再起動でメモリー内データが消えることも説明します。
この機能だけを実装し、実際に動作確認してプレビューリンクを提示してください。
```

**試し方：** 左の本文に入力し、次に右で編集を続けます。双方向の同期と再読み込み後の復元を確認してください。デモのメモリー内データはサービス再起動時にリセットされます。デプロイ時は永続化データベースを接続してください。[Server SDK 共同編集クイックスタート](https://docs.univer.ai/ja-JP/server/collaboration/quick-start.md)で導入方法を確認できます。

### 例3：自分の you-cli を作る

現在の Agent が使える独自の Office ツールを作ります。Sheet、Doc、Slide、Relational Table、Canvases に対応し、まず Doc で「生成 → プレビュー → 会話による修正」を体験します。

```text
Univer Office SDK で、このプロジェクト専用の you-cli と Web プレビューを作ってください。
https://docs.univer.ai/ja-JP/llms.txt と、以下の完全な内容操作例を読んでください。
https://github.com/dream-num/univer-cli-examples
前後端と AI SDK のバージョンを揃え、インストール済みの型で API を確認してください。

Sheet、Doc、Slide、Relational Table、Canvases に対応し、まず Doc で実装します。
./you-cli create <type> --name <name>、inspect --unit <id>、
execute --unit <id> --file <path>、open --unit <id>、--help を用意してください。
ツールをこのプロジェクトに置き、現在の Agent が読む説明または Skill を作成してください。
unitId、種類、確定結果、プレビュー URL などを対応する JSON 結果に含めてください。

CLI と Web は同じ実際の共同編集コンテンツを扱い、開いているネイティブエディターを更新します。
書き込みの確定を待って読み戻し、コンテンツと一覧を永続化してください。
open は URL を返し、Agent が宿主のプレビュー機能で開きます。利用可能なら右側に表示します。
自然言語理解は現在の Agent を使い、ライセンスは環境から読み込んで必要な表示を保ってください。

会話で週次レポートを生成して開き、続く会話でリスクと担当者を追加してください。
同じ unitId と開いているプレビューを使い、再読み込み・サービス再起動後も復元してください。
実際に検証し、プレビューと使い方を提示してください。この例のサービスだけを起動してください。
```

#### 会話で使う

上のプロンプトをコーディング Agent に渡します。構築とプロジェクト説明の読み込みが済んだら、同じ会話で次のように依頼します。

```text
you-cli で進捗、リスク、来週の計画を含む週次レポートを作り、Web プレビューを開いてください。
```

結果を見てから、続けて依頼します。

```text
同じレポートに「納期が遅れる可能性がある」というリスクを追加し、担当者を林さんにしてください。
すでに開いているプレビューを更新してください。
```

Agent は元の文書の `unitId` を再利用します。宿主が対応していれば会話の横にプレビューを表示し、それ以外では返されたブラウザーリンクを使います。

#### you-cli コマンド一覧

上のプロンプトで作るプロジェクト専用インターフェースです。`UNIT_ID` を `create` が返す `unitId` に置き換えます。`edit.js` は Agent が Facade API で作成する変更スクリプトです。

| 操作 | コマンド | 結果 |
| --- | --- | --- |
| 作成 | `./you-cli create doc --name "週次レポート"` | 文書を作り `unitId` を返します。`sheet`、`slide`、`base`、`board` も選べます。 |
| 確認 | `./you-cli inspect --unit UNIT_ID` | 実際の内容と現在のリビジョンを読みます。 |
| 変更 | `./you-cli execute --unit UNIT_ID --file edit.js` | 変更を実行し、確定を待って結果を返します。 |
| 表示 | `./you-cli open --unit UNIT_ID` | 同じ文書の Web URL を返し、Agent が開きます。 |

`./you-cli --help` でも確認できます。[AI SDK コンテンツ操作](https://docs.univer.ai/ja-JP/ai/content-operations.md)と完全な [CLI SDK Examples](https://docs.univer.ai/ja-JP/overview/examples/cli-sdk.md)を参照してください。

## アプリに最初の流れを組み込む

Web SDK が共通のコンテンツランタイムを提供します。共有編集や Agent 操作が必要になったら Server SDK と AI SDK を追加します。役割は [Office SDK 概要](https://docs.univer.ai/ja-JP/overview.md)を参照してください。

| 手順 | アプリで接続するもの | 関連ガイド |
| --- | --- | --- |
| エディターの組み込み | プリセットを画面に配置し、Facade API で業務操作を接続。スナップショット保存とインスタンス破棄を実装します。 | [Web SDK 導入](https://docs.univer.ai/ja-JP/guides/sheets/getting-started/installation.md) |
| バックエンドの接続 | 既存の認証・権限を使い、共有文書のデータベースを設定。必要に応じてインポート・エクスポートを追加します。 | [共同編集](https://docs.univer.ai/ja-JP/server/collaboration/quick-start.md)、[ファイル変換](https://docs.univer.ai/ja-JP/server/import-export/node.md) |
| 既存 Agent の接続 | 読み書き、計算、検証をツールや CLI として公開。レビューが必要なら Worktree を追加します。 | [AI SDK コンテンツ操作](https://docs.univer.ai/ja-JP/ai/content-operations.md)、[Worktree](https://docs.univer.ai/ja-JP/ai/worktree.md) |

## アプリケーション構成

既存アプリと Agent は Office コンテンツを共有できます。画面が操作を受け持ち、Agent がツールを呼び出し、業務サービスが認証・権限・ストレージを管理します。

**青いノードは利用者側で用意・管理するシステムです：** アプリ画面、既存 Agent、認証と権限を含む業務 API、データベース、ファイルストレージ。SDK と記したほかのノードは組み込む Univer の機能です。

```mermaid
%%{init: {"themeVariables":{"fontSize":"13px"},"flowchart":{"padding":10,"nodeSpacing":20,"rankSpacing":20}}}%%
flowchart TB
    UI["自分のアプリ画面"]
    UI --> Editor["Web SDK · エディター"]
    Agent["自分の既存 Agent"] --> Tools["AI SDK · Office ツール"]
    Editor <-->|共有編集| App["自分の業務 API · 認証と権限"]
    Tools <-->|コンテンツ操作と確定| App
    App --> Server["Server SDK · 共同編集とファイル変換"]
    Tools --> Runtime["Web SDK · Headless ランタイム"]
    Server --> Runtime
    Server --> Storage[("自分のデータベースとファイル")]
    classDef appOwned fill:#e8f0ff,stroke:#4771c4,color:#163d75,stroke-width:2px
    class UI,Agent,App,Storage appOwned
```

エディターの組み込みだけならローカルのスナップショットから始め、共有編集でバックエンドを接続します。Agent のモデルと処理の流れは既存のものを使い、AI SDK でコンテンツを操作します。変更の分離、比較、レビューには Worktree を組み合わせます。

## Workspace を使ったビルドとデプロイ

[Univer Workspace](https://github.com/dream-num/univer-workspace)は、3つの SDK を組み合わせた Office アプリの参考です。以下のコマンドはリポジトリのルートで実行します。前提条件は [README](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/README.md)を確認してください。

1. **ローカル開発。** 依存関係をインストールし、別々のターミナルで `pnpm workspace:dev:server` と `pnpm workspace:dev:web` を実行します。`http://127.0.0.1:5173` を開きます。Web 開発サーバーが API と WebSocket をバックエンドへ転送します。
2. **ビルドと実行。** Workspace アプリだけをビルドし、本番用エントリーを起動します。

```bash
pnpm --filter @univerjs/univer-workspace build
pnpm workspace:start
```

Web は `dist/public`、Server は `dist/server` に出力され、1つの Node.js プロセスが静的ページと API を提供します。

3. **デプロイの準備。** ライセンス、認証、データディレクトリを設定し、業務データ、共同編集データ、アップロードを永続化します。再起動後の復元も確認します。[Docker デプロイ](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/README.md#docker)と[構成の説明](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/docs/architecture.md)を参照してください。

規模の拡大に応じて [Server SDK デプロイガイド](https://docs.univer.ai/ja-JP/server/deployment.md)を参考にサービスを分離します。

## ほかのオープンソースプロジェクト

- [Univer CLI](https://docs.univer.ai/ja-JP/overview/examples/cli.md)：ローカルで Agent やターミナルから Office コンテンツを作成・編集・検証し、Viewer で変更をレビューします。
- [DeepSeek Harness](https://docs.univer.ai/ja-JP/overview/examples/deepseek-harness.md)：既存の Agent の会話に Office ツール、ライブプレビュー、下書きレビューを追加します。

[すべての例](https://docs.univer.ai/ja-JP/overview/examples.md)でデモとリポジトリのリンクを確認できます。