Univer Workspace 배포 실전: AI 공동 편집 오피스 문서

Univer Workspace 배포 실전: AI 공동 편집 오피스 문서

프로젝트 소개

오피스 문서의 공동 편집은 항상 팀 협업의 골칫거리였습니다. 특히 AI 에이전트가 콘텐츠 제작에 참여하기 시작하면서, AI가 문서를 수정하도록 안전하고 통제 가능하게 하는 것이 새로운 문제가 되었습니다. Univer Workspace는 바로 이러한 시나리오를 해결하기 위해 탄생했습니다: 독립적으로 배포할 수 있는 오픈 소스 Office 작업 공간으로, 사용자와 AI 에이전트가 같은 플랫폼에서 Sheet, Doc, Slide, Base, Board를 함께 처리할 수 있습니다.

핵심 설계 사고는 주목할 만합니다. Workspace는 Browser, Server, Agent, CLI 네 부분으로 구성됩니다:

  • Browser는 직접 편집 및 공동 편집 인터페이스를 제공하며, 인간의 조작 진입점입니다.
  • Server는 유일한 권위자로, 신원 인증, 권한 관리, 문서 저장을 담당합니다.
  • Agent는 DSH 기반의 로컬 웹 애플리케이션으로, 대화, 문서 미리보기, 변경 검토를 한곳에 모았습니다.
  • 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 contract 및 배포 애플리케이션
apps/cli                       Agent용 원격 Workspace 자동화 애플리케이션
apps/agent                     문서 대화 및 Worktree 검토용 Workspace Agent 애플리케이션
packages/client-core           프라이빗 Node-hosted Workspace Agent Client 기능
packages/reference-provider    Browser 전용 프라이빗 referenced-Unit policy
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 서비스 시작

백엔드 Server를 시작하면 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가 문서를 처리하도록 하려면 두 개의 독립적인 연결이 필요합니다: 하나는 Workspace 로그인 자격 증명으로, AI가 사용자의 문서에 접근할 수 있게 합니다. 다른 하나는 모델 서비스 자격 증명으로, 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://<your-workspace>/mcp를 Claude, Cursor 또는 VS Code에 구성하면 이 AI 어시스턴트들이 직접 문서를 조작할 수 있습니다.
  • HTML View 미니 애플리케이션: Agent는 보고서 데이터에 바인딩된 웹 앱을 생성할 수 있으며, 지표, 차트, 컨트롤이 셀과 양방향으로 연동되어 의사 결정 대시보드에 적합합니다.
  • Docker 배포: PostgreSQL + S3 저장으로 전환하고 apps/workspace/README.md를 참조하여 컨테이너화 배포를 수행하며, 자동 업그레이드 및 데이터 마이그레이션을 지원합니다.

Workspace를 직접 구축하고 AI가 첫 번째 월간 보고서를 처리하도록 해보세요. Worktree 검토 메커니즘이 주는 통제감을 느낄 수 있을 것입니다.