Univer Workspace: 배포와 AI 스프레드시트 실전
AI가 생성한 스프레드시트 내용이 채팅 창에만 머물면 이후 수정, 협업, 검토가 모두 끊깁니다. Univer Workspace는 문서, 스프레드시트, AI 작업을 하나의 워크스페이스에 넣어 Agent가 격리된 Worktree에서 수정하고, 우리가 검토한 후 병합할 수 있게 합니다. 오늘은 함께 로컬 배포를 완료하고, 판매 스프레드시트로 Agent가 요약과 수식을 생성하도록 실행해 보겠습니다.
프로젝트 소개
Univer Workspace는 Univer Office SDK 기반으로 구축된, 독립적으로 배포할 수 있는 오픈소스 Office 워크스페이스입니다. 핵심 문제는 AI가 생성한 오피스 콘텐츠를 수동으로 편집기로 옮겨야 하고, 이후 수정 시 협업과 검토가 어렵다는 점입니다.
이 프로젝트는 Browser, Agent, CLI 세 가지 진입점을 동일한 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/로 지정합니다. 설치 시 이 프라이빗 레지스트리와 공개 npm 레지스트리에 모두 접근해야 합니다.
DSH Runtime은 packages/dsh-runtime에서 @deepseek-ai/[email protected]로 고정됩니다. 소스 코드는 Apache-2.0을 사용하지만 Univer SDK 사용 조건이 소스 코드 라이선스와 완전히 같지는 않습니다. 내장 런타임 개발 자격 증명은 90일마다 교체되며, 서버 측 Collaboration/Exchange SDK는 라이선스 키가 필요하고, 둘 중 하나라도 없으면 무료 할당량으로 강등됩니다.
프로젝트 구조 트리
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. 고정 버전 클론 및 의존성 설치
튜토리얼에서 사용하는 커밋으로 고정하여 이후 변경이 명령에 영향을 주지 않도록 합니다.
git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
git checkout c1a5fb3dc9d5951cbf618f76639466feac5da4d7
pnpm install --frozen-lockfile
이 단계에서는 프라이빗 레지스트리와 공개 npm 레지스트리에 접근합니다. 네트워크가 제한된 경우 문서 끝의 자주 묻는 질문을 먼저 확인하세요.
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 베이스 주소로 지정하면 됩니다.
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를 편집하여 주석 처리되지 않은 한 줄 구성을 추가하세요:
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 배열에 추가하고, 구성 항목은 항상 하나만 유지하세요.
4. Workspace Server 및 Browser 시작
첫 번째 터미널에서 Server를 시작합니다:
pnpm workspace:dev:server
두 번째 터미널에서 Browser 개발 서버를 시작합니다:
pnpm workspace:dev:web
http://127.0.0.1:5173을 열고 로컬 Workspace 계정을 등록하거나 기존 계정으로 로그인하세요. 로컬 등록에는 GitHub/Discord OAuth가 필요하지 않습니다. 두 프로세스를 계속 실행해 두세요.
5. DSH Runtime 및 Agent Profile 빌드, 로컬 Agent 시작
Agent는 로컬 웹 애플리케이션이므로 먼저 소스에서 DSH 런타임을 조립해야 합니다. 아래 명령은 client-core와 세 개의 bundle을 빌드하고 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 쿠키를 설정하고 루트 주소로 리디렉션합니다.
# 复制启动器输出的完整地址,例如:
# 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 프라이빗 레지스트리 접근 실패
설치 시 프라이빗 레지스트리와 공개 npm 레지스트리 모두 접근해야 하며, 둘 다 필요합니다. 멈추거나 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을 먼저 열지 않으면 브라우저에 세션 쿠키가 없습니다. 런처가 출력한 dsh web: 주소를 다시 열어 교환을 완료한 뒤, 이후에는 매개변수 없는 루트 주소를 사용할 수 있습니다. 일회용 토큰은 재사용하지 마세요.
5. Workspace 로그인은 성공했지만 모델 메시지 실패
Workspace OAuth는 데이터 접근만 승인하며 모델 자격 증명은 별도로 구성해야 합니다. DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL, 모델 ID를 확인하세요. Defapi를 사용할 때 baseURL은 콘솔에서 제공하는 chat completions 베이스 주소를 입력하고 /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를 기준으로 작성되었으며 이후 버전은 공식 문서를 기준으로 합니다.