# 시작하기

> 코딩 Agent로 첫 Office 앱을 만들고 통합 및 배포 방법을 알아봅니다.

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

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.3.0`

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

---

이 가이드는 스프레드시트 연동, 문서 공동 편집, Agent용 CLI의 세 가지 예시로 Office SDK 사용법을 소개합니다. 예시 하나를 골라 프롬프트를 코딩 Agent에 전달한 다음 앱 통합과 배포를 진행하세요.

## 먼저 만들 앱 정하기

Office SDK는 Sheets, Docs, Slides, Relational Tables, Canvases, PDF를 지원합니다. 앱 목표에 맞는 연동 경로를 선택하세요.

| 목표 | 시작할 가이드 | 첫 완료 기준 |
| --- | --- | --- |
| Office 편집기 삽입 | [Web SDK 설치](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/installation.md) | 콘텐츠를 만들고 편집·저장한 뒤 다시 엽니다. |
| 콘텐츠와 업무 화면 연동 | [Facade API](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/facade.md) | 입력란과 셀을 양방향으로 연결하고 실제 계산 결과를 표시합니다. |
| 공동 편집 추가 | [Server SDK 협업 빠른 시작](https://docs.univer.ai/ko-KR/server/collaboration/quick-start.md) | 독립된 두 세션에서 같은 내용을 편집하고 서로의 변경을 동기화합니다. |
| Office 파일 가져오기·처리·내보내기 | [파일 변환](https://docs.univer.ai/ko-KR/server/import-export/node.md) | 실제 파일을 가져와 수정하고 내보낸 결과를 확인합니다. |
| Agent나 CLI로 콘텐츠 조작 | [AI SDK 콘텐츠 조작](https://docs.univer.ai/ko-KR/ai/content-operations.md) | 콘텐츠를 불러와 구조를 검사하고 수정한 뒤 커밋이나 출력을 검증합니다. |
| 사람과 Agent가 공유하는 작업 공간 구축 | [Worktree와 검토](https://docs.univer.ai/ko-KR/ai/worktree.md) | Agent 변경을 독립된 초안에 보관하고 사람이 비교·검토한 뒤 병합합니다. |

이 기능들은 함께 사용할 수 있습니다. [기능 목록](https://docs.univer.ai/ko-KR/overview/features.md)에서 제품별 지원 범위를 확인하고 아래 세 예시로 먼저 하나의 흐름을 체험하세요.

## Agent와 시작하기

코딩 Agent에게 요구 사항과 [llms.txt](/llms.txt) 문서 색인 링크를 전달하면 됩니다. 전체 SDK 문서를 복사할 필요는 없습니다. 아래 템플릿을 수정하거나 세 완성 예시 중 하나를 그대로 붙여 넣으세요.

### 요구 사항 템플릿

`<…>`를 원하는 내용으로 바꾸세요. 전체 오피스 시스템을 계획하기 전에 결과를 확인할 수 있는 기능 하나를 정합니다.

```text
Univer Office SDK로 로컬에서 실행할 수 있는 <앱 이름>을 만들어 주세요.
https://docs.univer.ai/ko-KR/llms.txt와 관련 전체 예제를 먼저 읽고
SDK 패키지 버전을 동일하게 맞춰 주세요.

초기 콘텐츠: <바로 조작할 수 있는 소량의 데이터나 문서>.
핵심 경험: <사용자의 한 가지 조작과 즉시 보이는 변화>.
검증 조건: <조작으로 확인할 수 있는 구체적인 결과 2~3개>.

기본 Univer 편집기와 실제 SDK 기능으로 이 최소 흐름만 구현하세요.
직접 실행하고 브라우저에서 검증한 후 미리보기 링크를 주세요.
필수 설정이 빠졌다면 무엇이 필요한지 구체적으로 알려 주세요.
```

### 예시 1: 스프레드시트 연동

수량 입력란과 셀을 양방향으로 연결하고 수식으로 계산한 견적 합계를 페이지에 표시합니다.

```text
Univer Office SDK로 로컬에서 실행하는 단일 페이지 견적 작업대를 만들어 주세요.
https://docs.univer.ai/ko-KR/llms.txt와 관련 전체 예제를 먼저 읽고
SDK 패키지 버전을 동일하게 맞춰 주세요.

기본 Sheets 프리셋으로 편집 가능한 기본 스프레드시트를 삽입하세요.
모니터 2대×1200, 키보드 5개×300, 헤드셋 3개×200을 준비하고
각 항목 금액과 합계는 시트 수식으로 계산하세요.

옆에 모니터 수량 입력란과 견적 합계 카드를 배치하세요.
입력란과 셀을 양방향으로 연결하고 카드는 실제 수식 결과를 읽게 하세요.
페이지에서 견적을 다시 계산하지 마세요. 브라우저에 저장하고 새로 고침 시 복원하세요.

초기 합계 4500, 수량을 3으로 바꾸면 5700이 되는지 확인하세요.
셀을 직접 편집해도 입력란과 합계가 갱신되고 저장 후 새로 고침하면 복원되어야 합니다.
이 기능만 구현하고 실제 실행을 검증한 후 미리보기 링크를 주세요.
```

**체험 방법:** 모니터 수량을 2에서 3으로 바꾸고 합계가 4500에서 5700이 되는지 확인하세요. 시트를 직접 편집해 페이지가 따라오는지도 확인합니다. 저장하고 새로 고침해 복원 여부를 확인하세요. [Web SDK 설치](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/installation.md)와 [Facade API](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/facade.md)를 참고할 수 있습니다.

### 예시 2: 문서 협업

독립된 두 세션에서 같은 문서를 편집하고 양쪽의 변경 사항이 실시간으로 동기화되는지 확인합니다.

```text
Univer Office SDK로 로컬에서 실행하는 두 사용자 문서 협업 데모를 만들어 주세요.
https://docs.univer.ai/ko-KR/llms.txt와 아래 저장소의 현재 예제를 참고하고
https://github.com/dream-num/univer-collaboration-examples
프런트엔드와 서버 SDK 버전을 동일하게 맞춰 주세요.

Alice와 Bob의 기본 Univer 모던 문서 편집기를 좌우에 배치하세요.
독립된 실행 환경과 온라인 세션으로 실제 Server SDK 협업 서비스에 연결하고,
공식 예제에 따라 서버가 만든 같은 문서를 명시적으로 불러오세요. 짧은 문장을 준비하세요.

왼쪽 입력은 오른쪽에, 오른쪽 입력은 왼쪽에 실시간으로 나타나게 하세요.
SDK 협업 프로토콜을 사용하고, 고정된 데모 사용자 두 명과 메모리 저장소만 사용하세요.
프런트엔드와 백엔드는 로컬 서비스 하나로 제공하며 로그인, 파일 관리, AI 채팅은 제외하세요.
Pro License는 환경 변수로 읽고, 없으면 SDK 기본 동작과 안내를 유지하세요.

양방향 입력 후 내용이 같고 서버에서 갱신이 커밋되는지 확인하세요.
새로 고침 후 내용이 복원되어야 하며 서비스 재시작 시 메모리 데이터가 초기화됨을 설명하세요.
이 기능만 구현하고 실제 실행을 검증한 후 미리보기 링크를 주세요.
```

**체험 방법:** 왼쪽 본문에 입력한 후 오른쪽에서 이어서 편집하세요. 양방향 동기화와 새로 고침 후 복원을 확인합니다. 데모의 메모리 데이터는 서비스 재시작 시 초기화됩니다. 배포 시에는 영속 데이터베이스를 연결하세요. [Server SDK 협업 빠른 시작](https://docs.univer.ai/ko-KR/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/ko-KR/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를 제공하세요.
현재 프로젝트에 도구와 사용 설명 또는 Skill을 만들고 현재 Agent가 읽게 하세요.
각 JSON 결과에 해당하는 unitId, 유형, 커밋 결과, 미리보기 URL을 포함하세요.

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/ko-KR/ai/content-operations.md)과 전체 [CLI SDK Examples](https://docs.univer.ai/ko-KR/overview/examples/cli-sdk.md)를 참고하세요.

## 첫 흐름을 앱에 연결하기

Web SDK는 공통 콘텐츠 런타임을 제공합니다. 공유 편집이나 Agent 조작이 필요할 때 Server SDK와 AI SDK를 연결합니다. 각 역할은 [Office SDK 개요](https://docs.univer.ai/ko-KR/overview.md)를 참고하세요.

| 단계 | 앱에서 연결할 내용 | 자세히 보기 |
| --- | --- | --- |
| 편집기 삽입 | 프리셋을 화면에 넣고 Facade API로 업무 동작을 연결합니다. 스냅샷 저장과 인스턴스 해제를 처리합니다. | [Web SDK 연동](https://docs.univer.ai/ko-KR/guides/sheets/getting-started/installation.md) |
| 백엔드 연결 | 기존 사용자와 권한을 연결하고 공유 문서 데이터베이스를 설정합니다. 필요에 따라 파일 가져오기와 내보내기를 추가합니다. | [협업](https://docs.univer.ai/ko-KR/server/collaboration/quick-start.md), [파일 변환](https://docs.univer.ai/ko-KR/server/import-export/node.md) |
| 기존 Agent 연결 | 콘텐츠 읽기·쓰기, 계산, 검증을 도구나 CLI로 제공합니다. 검토가 필요할 때 Worktree를 추가합니다. | [AI SDK 콘텐츠 조작](https://docs.univer.ai/ko-KR/ai/content-operations.md), [Worktree](https://docs.univer.ai/ko-KR/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)는 세 SDK를 완전한 오피스 앱으로 조합한 예입니다. 다음 명령은 Workspace 저장소 루트에서 실행합니다. 사전 준비는 [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`로 빌드되며 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/ko-KR/server/deployment.md)에 따라 서비스를 분리하세요.

## 더 많은 오픈 소스 프로젝트

- [Univer CLI](https://docs.univer.ai/ko-KR/overview/examples/cli.md): 로컬에서 Agent나 터미널로 Office 콘텐츠를 만들고 편집·검사한 다음 Viewer에서 변경을 검토합니다.
- [DeepSeek Harness](https://docs.univer.ai/ko-KR/overview/examples/deepseek-harness.md): 기존 Agent 대화에 Office 도구, 실시간 미리보기, 초안 검토를 추가합니다.

[전체 예제](https://docs.univer.ai/ko-KR/overview/examples.md)에서 데모와 저장소 링크를 확인하세요.