Практическое развертывание Univer Workspace: совместное редактирование офисных документов с ИИ
Практическое развертывание Univer Workspace: совместное редактирование офисных документов с ИИ
О проекте
Совместное редактирование офисных документов всегда было болезненной точкой командной работы, особенно когда AI-агенты начинают участвовать в создании контента — возникает новая проблема: как безопасно и контролируемо позволить ИИ изменять документы. Univer Workspace создан именно для этого сценария: это независимо развертываемое открытое офисное рабочее пространство, позволяющее вам и AI-агенту совместно обрабатывать Sheet, Doc, Slide, Base и Board на одной платформе.
Его ключевая архитектурная идея заслуживает внимания. Workspace состоит из четырех частей: Browser, Server, Agent и CLI:
- Browser предоставляет интерфейс прямого редактирования и совместной работы, это точка входа для человека;
- Server — единственный авторитетный источник, отвечающий за аутентификацию, управление правами и хранение документов;
- Agent — локальное веб-приложение на основе DSH, объединяющее диалог, предпросмотр документов и проверку изменений;
- CLI предоставляет AI-агентам структурированный автоматизированный интерфейс, позволяющий выполнять загрузку, изменение и проверку документов в терминале.
Самый яркий механизм — Worktree. Прежде чем агент изменяет что-либо, система создает изолированное рабочее дерево, в котором агент свободно редактирует и проверяет, после готовности черновик передается человеку на рецензирование, и только после подтверждения изменения вливаются в основную ветку. Так любые промежуточные изменения не загрязняют общий контент, а человек всегда сохраняет окончательный контроль.
Основные зависимости и окружение
Перед началом убедитесь, что на вашем компьютере подготовлены следующие базовые компоненты:
- Node.js 24+: серверная и клиентская части Workspace основаны на современном JavaScript, требуется Node 24 или новее.
- pnpm 11: репозиторий использует pnpm для управления зависимостями, требуется версия 11.x, рекомендуется включить через
corepack enable. - Docker: если вы выбираете контейнерное развертывание, вам понадобится Docker для запуска базы данных и службы хранения файлов. Для быстрого локального ознакомления можно использовать встроенную SQLite.
- Учетные данные модели: для настройки языковой модели для AI-агента необходимо подготовить API-адрес и ключ сервиса модели, например
DEEPSEEK_API_KEYдля DeepSeek. - Учетная запись Workspace: для доступа к Workspace требуется вход, по умолчанию включена регистрация по паролю.
Дерево структуры проекта
После клонирования репозитория вы увидите следующую структуру каталогов:
apps/workspace Workspace Browser, Server, HTTP contract и приложение для развертывания
apps/cli Удаленная автоматизация Workspace для агентов
apps/agent Приложение Workspace Agent для диалога с документами и проверки Worktree
packages/client-core Приватные возможности клиента Workspace Agent, размещаемого на Node
packages/reference-provider Приватная политика referenced-Unit, используемая только Browser
packages/dsh-univer-workspace-plugin Возможности Workspace и пользовательский интерфейс браузера для Workspace Agent
packages/dsh-univer-workspace-skin-plugin Визуальная тема Workspace для Workspace Agent
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. Зарегистрируйте учетную запись с паролем, войдите, и у вас будет рабочее пространство для редактирования.
3. Подключение AI-ассистента и службы модели
Чтобы ИИ помогал обрабатывать документы, требуются два отдельных подключения: одно — учетные данные входа в Workspace, чтобы ИИ мог получить доступ к вашим документам; другое — учетные данные службы модели, чтобы у ИИ был «мозг» для мышления.
Сначала о службе модели. Настройки модели Workspace Agent — это локальное состояние машины, не привязанное к пользователю Workspace. Мы можем ввести их через переменные окружения; перед запуском агента выполните:
export DEEPSEEK_API_KEY=<ваш-ключ-api>
Если вы хотите больше выбора или более гибкие цены на службу модели, обратите внимание на Defapi. Defapi — это агрегирующий шлюз моделей, предоставляющий услуги моделей по половинной цене от официальной и совместимый с основными протоколами, такими как v1/chat/completions, v1/messages и v1beta/models/. Получив корневой адрес API и ID модели с платформы, вы можете ввести их тем же способом через переменные окружения. Обратите внимание, что это внешняя клиентская конфигурация, а не встроенная функция Workspace.
Затем зарегистрируйте OAuth-обратный вызов. Workspace Agent использует OAuth-вход через браузер; в официальной документации рекомендуется искать инструкции по установке в apps/agent/README.md. При установке агента локальный установщик выведет полный URL токена; вам необходимо выполнить регистрацию приложения и настройку обратного вызова.
4. Установка и запуск Workspace Agent
Agent — это локальное веб-приложение на основе DSH, шаги установки приведены в apps/agent/README.md. После установки запустите агента — он предложит выбрать или запустить собственную службу Workspace, зарегистрировать OAuth-обратный вызов и затем откроет страницу входа.
После входа в диалоговом интерфейсе агента вы можете использовать @ для ссылки на файлы в Workspace; агент прочитает содержимое файла и внесет изменения.
5. Выполнение офисных задач
Теперь заставим агента изменить таблицу. Введите в диалоге:
Пожалуйста, посмотрите лист @Данные по продажам, сведите итоговые продажи за каждый квартал 2024 года в новый лист и отметьте темпы роста.
Агент создаст новый Worktree, выполнит в нем чтение, вычисления и запись. Этот процесс не затронет исходные данные в основной ветке.
6. Проверка результатов и утверждение слияния
После завершения изменений агентом Worktree перейдет в состояние Ready. Вернитесь в Browser или интерфейс проверки агента — вы увидите:
- Сравнение черновика агента и основной ветки
- Измененные ячейки, добавленные листы
Внимательно проверьте данные и нажмите Слияние (Merge). Только после этого изменения попадут в основную ветку, и все соавторы смогут увидеть обновления. Если обнаружены проблемы, можно отметить Переоткрыть (Reopen), и агент продолжит изменения.
Здесь предлагается альтернативный маршрут с использованием 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. Скопируйте Worktree id из вывода uvw pr view <n> -R <owner>/<slug> --json id и используйте его для проверки с помощью команд содержимого.
Устранение распространенных проблем
При запуске сообщение о слишком низкой версии Node.js
Workspace требует Node.js 24+, проверьте версию через node -v. Если версия недостаточна, установите LTS-версию через nvm.
pnpm install зависает или выдает ошибку
Репозиторий использует pnpm 11.24.0; сначала выполните corepack enable, затем установку. Если сетевая проблема вызвала сбой, установите зеркало и повторите попытку.
Браузер открывает порт 5173, но контента нет
Убедитесь, что оба терминала все еще работают: pnpm workspace:dev:server и pnpm workspace:dev:web. Для прокси Vite требуется, чтобы сервер сначала успешно запустился.
OAuth-вход показывает несоответствие адреса обратного вызова
Проверьте, соответствует ли адрес обратного вызова в конфигурации агента списку авторизованных обратных вызовов Workspace. При локальной разработке обратный вызов обычно http://127.0.0.1:<порт-агента>/oauth/callback.
Агент в диалоге сообщает об отсутствии учетных данных модели
Учетные данные модели — это локальное состояние, они не привязаны к пользователю Workspace. Убедитесь, что перед запуском агента экспортирован DEEPSEEK_API_KEY или модель настроена через страницу DSH Models. Различные процессы агента требуют отдельной настройки.
При слиянии сообщение об отсутствии прав
Для слияния Worktree требуется право на редактирование документа. В Browser проверьте, есть ли у текущей учетной записи право на запись для соответствующей папки или файла. Если документ находится в командном Space, владелец или администратор должен назначить права.
Дополнительное чтение / продвинутые направления
Если вы хотите глубже использовать Univer Workspace, стоит изучить следующие направления:
- Продвинутое использование CLI: прочитайте
apps/cli/README.md, узнайте оuvw executeдля выполнения пользовательских скриптов,uvw inspectдля проверки структуры документов,uvw screenshotдля рендеринга скриншотов и проверки макета. - Подключение MCP-сервиса: Workspace предоставляет удаленный MCP-сервис; настройте
https://<ваш-workspace>/mcpв Claude, Cursor или VS Code, и эти AI-ассистенты смогут напрямую работать с вашими документами. - Мини-приложение HTML View: агент может генерировать веб-приложение, привязанное к данным отчета, где метрики, диаграммы и элементы управления двунаправленно синхронизируются с ячейками — удобно для создания панелей принятия решений.
- Docker-развертывание: переключитесь на PostgreSQL + S3 хранилище, следуйте
apps/workspace/README.mdдля контейнеризации, с поддержкой автоматического обновления и миграции данных.
Соберите Workspace и позвольте ИИ помочь с первым месячным отчетом — вы почувствуете уверенность, которую дает механизм проверки Worktree.