Univer Workspace: развертывание и практическая работа с AI-таблицами
Если содержимое таблиц, сгенерированное ИИ, остаётся только в окне чата, последующие правки, совместная работа и ревью обрываются. Univer Workspace объединяет документы, таблицы и действия ИИ в одном рабочем пространстве: агент вносит изменения в изолированном Worktree, а мы ревьюируем и только затем вливаем. Сегодня развернём его локально и прогоним агента на таблице продаж, чтобы он сгенерировал сводку и формулы.
О проекте
Univer Workspace — это независимо разворачиваемое открытое рабочее пространство Office, построенное на Univer Office SDK. Ключевая проблема, которую оно решает: офисное содержимое, созданное ИИ, приходится вручную переносить в редактор, а дальнейшие правки усложняют совместную работу и ревью.
Проект подключает три входа — Browser, Agent, CLI — к одному Workspace Server, позволяя человеку и ИИ совместно работать с Sheet, Doc, Slide, Base и Board. Агент работает в изолированном Worktree и проверяет изменения: только подтверждённое нами содержимое попадает в общий trunk. Можно редактировать напрямую в Workspace Browser или позволить Workspace Agent общаться рядом с документом и генерировать контент, а затем ревьюить изменения таблицы, как ревьюят код.
Сценарии использования и подготовка
Типовой сценарий — анализ данных о продажах. Команда кладёт таблицу с продажами в Workspace, просит агента собрать сводку по регионам и сгенерировать формулы, а затем ревьюит изменения таблицы, как код.
Перед началом подготовьте:
- Умение работать с терминалом и понимание конфигурации JavaScript/TypeScript
- Установленный Git
- Node.js 24 или новее
- pnpm 11.24.0
- API-ключ модели для диалогов с агентом
- Chrome/Chromium, если нужно запускать скриншоты или проверку макета
Вход в Workspace и учётные данные модели — разные вещи: для просмотра документов запросы к модели не нужны, они нужны только для диалога с агентом.
Ключевые зависимости и окружение
В .npmrc репозитория @univer-cli, @univerjs, @univerjs-pro, @univerjs-labs указывают на https://insider-npm-registry.univer.work/. При установке нужен доступ и к этому приватному Registry, и к публичному npm Registry.
DSH Runtime в packages/dsh-runtime зафиксирован на @deepseek-ai/[email protected]. Исходный код распространяется под Apache-2.0, но условия использования Univer SDK не сводятся к лицензии исходников: встроенные учётные данные runtime для разработки ротируются каждые 90 дней, серверный SDK Collaboration/Exchange требует license key, а при отсутствии любого из значений действует бесплатный лимит.
Структура проекта
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
На этом шаге нужен доступ к приватному Registry и публичному npm Registry. Если сеть ограничена, сначала посмотрите раздел с частыми проблемами в конце.
2. Настройка подключения модели
Перед запуском агента разберёмся в разделении ролей между входом и учётными данными модели. Вход в Workspace даёт доступ только к данным; при диалоге с агентом DSH отправляет запросы к модели на настроенную конечную точку chat completions. Если планируете, чтобы агент анализировал таблицу продаж и генерировал формулы, сначала подготовьте доступные для модели baseURL, API Key и model.
Адаптер deepseek-official в DSH отправляет запросы на baseURL + /chat/completions, поэтому baseURL нужно указать до уровня /v1, не добавляя путь повторно.
Чтобы контролировать расходы на модель, можно подключить OpenAI-совместимый шлюз вроде Defapi. 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 не совпадает с консолью Defapi, в списке моделей на странице DSH Models его можно заменить на доступный ID. В production страница Models по умолчанию скрыта; чтобы она появилась, нужно установить UWH_MODEL_SETTINGS_ENABLED=true. Локально, без NODE_ENV=production, собственная страница DSH Models открывается напрямую.
3. Создайте конфигурацию окружения Workspace и зарегистрируйте OAuth-клиент агента
По умолчанию Workspace не регистрирует 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
Во втором терминале запустите dev-сервер Browser:
pnpm workspace:dev:web
Откройте http://127.0.0.1:5173, зарегистрируйте локальную учётную запись Workspace или войдите в существующую. Для локальной регистрации GitHub/Discord OAuth не нужен. Держите оба процесса запущенными.
5. Соберите DSH Runtime и Agent Profile, запустите локального агента
Агент — это локальное веб-приложение, поэтому сначала нужно собрать DSH runtime из исходников. Приведённые ниже команды собирают 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
Команда останется в foreground на start-local.mjs — это нормально. Дождитесь в stderr строки, начинающейся с dsh web:, и скопируйте весь URL из этой строки.
Если порт 3101 занят, выберите другой свободный порт и соответственно обновите redirectUris на шаге 3.
6. Подключите Workspace и завершите OAuth
Откройте в браузере полный URL, который вывел dsh web:; внутри есть одноразовый ?token=.... DSH установит HttpOnly Cookie и перенаправит на корневой адрес.
# 复制启动器输出的完整地址,例如:
# http://127.0.0.1:3101/?token=<one-time-token>
Затем в интерфейсе агента откройте Настройки → Workspace и укажите адрес локального сервиса:
http://127.0.0.1:5173
Нажмите Sign in to Workspace и разрешите доступ на странице авторизации Workspace. Workspace перенаправит на локальный callback агента, агент обменяет код авторизации по PKCE. После возврата в боковой панели должны появиться аккаунт и личное Space.
Если страница подключения всё ещё ждёт, нажмите Check again и держите start-local.mjs запущенным.
7. Создайте пример таблицы продаж и попросите агента сгенерировать сводку и формулы
В боковой панели откройте Файлы, выберите личное или командное Space, создайте новую таблицу и заполните данные о продажах:
日期,区域,销售额
2025-01-05,华东,12800
2025-01-06,华南,9600
2025-01-07,华东,15100
2025-01-08,华南,14200
Вернитесь к Чатам, создайте новый чат, в поле ввода наберите @ и выберите только что созданную таблицу, затем отправьте:
@销售明细 请按区域汇总销售额,并在表格中新增一列计算每个区域的平均销售额。
После отправки агент проверит ссылки в текущем Workspace и запишет изменения в Worktree, не трогая напрямую общий trunk.
8. Просмотрите изменения в Worktree, влейте или отклоните их
Откройте вкладку Worktree и найдите выполняющуюся задачу. В представлении ревью по умолчанию показывается «результат изменений»; можно переключиться на «различия», чтобы увидеть добавленные, изменённые и удалённые документы. Если результат верный, нажмите «Влить»; если нет — можно перевести в черновик или отклонить. Только после вливания обновляется общий trunk.
创建 Worktree
→ Agent 编辑并验证隔离草稿
→ Ready
→ 人工审阅
→ Merge 或 Reopen
→ trunk
Если агент выполнял univer_lint или univer_screenshot, нужны совместимая по версии статическая страница рендеринга и Chrome/Chromium. Если UWH_RENDER_PAGE_ROOT или браузер отсутствуют, инструмент явно сообщит об ошибке предусловий и не отметит визуальную проверку как пройденную.
Устранение частых проблем
1. pnpm install не может достучаться до приватного Registry
При установке требуется доступ и к приватному Registry, и к публичному npm Registry — оба обязательны. Если всё зависло или появился 401, сначала убедитесь, что сеть может достучаться до https://insider-npm-registry.univer.work/, затем проверьте версии Node и pnpm. Не удаляйте строку registry в .npmrc.
2. Появляется OAUTH_CLIENT_UNAVAILABLE
Сервер Workspace не загрузил OAuth-клиент агента. Проверьте, что в apps/workspace/.env параметр OAUTH_CLIENTS_JSON содержит univer-workspace-harness, затем перезапустите Server. Простое копирование .env.example не регистрирует этого клиента.
3. Появляется INVALID_REDIRECT_URI
Адрес callback должен совпадать точно. localhost и 127.0.0.1 — это разные регистрации. Если агент переехал на другой порт, синхронно обновите redirectUris и перезапустите бэкенд Workspace. Эта регистрация управляет OAuth-callback, а не общим CORS-доступом к порту 3101.
4. Открытие корневого адреса возвращает 401
Если сначала не открыть полный URL с токеном, у браузера не будет сессионного Cookie. Снова откройте адрес dsh web:, выведенный лаунчером, чтобы выполнить обмен; после этого можно использовать корневой адрес без параметров. Одноразовый токен повторно не используйте.
5. Вход в Workspace успешен, но сообщения модели не работают
OAuth Workspace даёт доступ только к данным; учётные данные модели нужно настраивать отдельно. Проверьте DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL и ID модели. При использовании Defapi указывайте в baseURL базовый адрес chat completions из консоли и не добавляйте /chat/completions повторно.
6. Страница подключения агента всё время ждёт
Держите start-local.mjs запущенным. После изменения состояния подключения выполняется проверка готовности; если сервис учётных записей не загрузился, посмотрите логи лаунчера. Если запрос авторизации истёк, войдите заново через Настройки → Workspace. Этот процесс использует браузерный OAuth и не требует ввода кода устройства.
7. Скриншот/проверка макета сообщает об ошибке предусловий
univer_lint и univer_screenshot требуют, чтобы UWH_RENDER_PAGE_ROOT указывал на статическую страницу рендеринга, а UWH_RENDER_BROWSER — на совместимый Chrome/Chromium. Если браузера нет, присвойте путь к исполняемому файлу переменной UWH_RENDER_BROWSER и затем запустите агента.
Дополнительное чтение / Следующие шаги
- Деплой через Docker: Workspace — это отдельно разворачиваемое приложение; по официальному руководству приложения можно собрать образ и разместить Server, Browser и хранилище на сервере.
- Автоматизация через CLI: установите
univer-workspace-cliи подключите его к существующим агентным средам вроде Claude, Codex, Kimi Work; используйте CLI для работы с документами и Worktree. - Подключение через MCP: Workspace предоставляет удалённый MCP-сервис с поддержкой Streamable HTTP и OAuth; клиенты вроде Cursor, VS Code, Claude Desktop могут подключаться напрямую.
- Официальная документация и зафиксированная версия: документация Univer Web SDK, документация Server SDK, документация по конфигурации Workspace. Это руководство написано по коммиту
c1a5fb3dc9d5951cbf618f76639466feac5da4d7; для последующих версий ориентируйтесь на официальную документацию.