Univer Workspace: Implantação e Planilhas de IA na Prática
Se o conteúdo de planilha gerado por IA ficar apenas na janela de chat, a edição, colaboração e revisão posteriores serão interrompidas. O Univer Workspace coloca documentos, planilhas e operações de IA no mesmo espaço de trabalho, permitindo que o Agent modifique em uma Worktree isolada e que nós revisemos antes da mesclagem. Hoje vamos concluir a implantação local e usar uma planilha de vendas para o Agent gerar resumos e fórmulas.
Visão geral do projeto
O Univer Workspace é um espaço de trabalho Office open source, construído sobre o Univer Office SDK e implantável de forma independente. O problema central que ele resolve é: o conteúdo de escritório gerado por IA precisa ser transportado manualmente para o editor, o que dificulta a colaboração e a revisão de alterações posteriores.
O projeto conecta três entradas — Browser, Agent e CLI — ao mesmo Workspace Server, permitindo que humanos e IA trabalhem juntos em Sheet, Doc, Slide, Base e Board. O Agent trabalha em uma Worktree isolada e valida as alterações; somente o conteúdo que confirmamos é mesclado ao trunk compartilhado. Você pode editar diretamente no Workspace Browser ou deixar o Workspace Agent conversar ao lado do documento e gerar conteúdo, para depois revisar as mudanças na planilha como quem revisa código.
Cenário de uso e pré-requisitos
Um cenário típico é a análise de dados de vendas. A equipe coloca a tabela de detalhes de vendas no Workspace, faz o Agent resumir por região e gerar fórmulas, e nós revisamos as alterações na planilha como revisaríamos código.
Antes de começar, prepare:
- saber operar o terminal e ler configurações de JavaScript/TypeScript
- Git instalado
- Node.js 24 ou superior
- pnpm 11.24.0
- uma API Key de modelo para conversar com o Agent
- Chrome/Chromium para executar capturas de tela ou verificação de layout
O login do Workspace e as credenciais do modelo são coisas diferentes: navegar pelos documentos não exige requisições de modelo; apenas conversar com o Agent exige credenciais de modelo.
Dependências principais e ambiente
O .npmrc do repositório aponta @univer-cli, @univerjs, @univerjs-pro e @univerjs-labs para https://insider-npm-registry.univer.work/. A instalação exige acesso a esse Registry privado e também ao Registry público do npm.
O DSH Runtime é fixado por packages/dsh-runtime em @deepseek-ai/[email protected]. O código-fonte usa Apache-2.0, mas as condições de uso do Univer SDK não são exatamente iguais à licença do código-fonte: as credenciais de desenvolvimento do runtime embutido são rotacionadas a cada 90 dias, o Collaboration/Exchange SDK do servidor exige license key e, se algum valor estiver ausente, há degradação para a cota gratuita.
Árvore de estrutura do projeto
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 版本与发布工具
Passo a passo
1. Clonar a versão fixada e instalar dependências
Primeiro, fixe o commit usado neste tutorial para que alterações futuras não afetem os comandos.
git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
git checkout c1a5fb3dc9d5951cbf618f76639466feac5da4d7
pnpm install --frozen-lockfile
Este passo acessa o Registry privado e o Registry público do npm. Se a rede for restrita, consulte as perguntas frequentes no final.
2. Configurar a integração do modelo
Antes de iniciar o Agent, entenda a divisão entre login e credenciais de modelo. O login do Workspace autoriza apenas o acesso a dados; ao conversar com o Agent, o DSH envia as requisições de modelo para o endpoint de chat completions configurado. Se você planeja fazer o Agent analisar a planilha de vendas e gerar fórmulas, prepare o baseURL, a API Key e o model disponíveis.
O adaptador deepseek-official do DSH envia requisições para baseURL + /chat/completions; portanto, o baseURL deve ser preenchido até o nível /v1, sem repetir o caminho.
Se quiser controlar o custo do modelo, você pode usar um gateway compatível com OpenAI, como o Defapi. O Defapi oferece integração unificada de modelos, com cobrança em torno de metade do preço oficial; os modelos e preços exatos dependem do console. O site oficial https://defapi.org tem uma entrada clara e é basicamente compatível com os protocolos v1/chat/completions, v1/messages e v1beta/models/. Na configuração, basta apontar o baseURL para a base de chat completions fornecida pelo console do Defapi.
export DEEPSEEK_API_KEY="<Defapi 控制台创建的 API Key>"
export DEEPSEEK_BASE_URL="<Defapi 控制台显示的 chat completions 基址,例如 https://xxx/v1>"
export UWH_MODEL_SETTINGS_ENABLED=true
O ID do modelo segue o catálogo realmente disponível no console. Se o ID de modelo padrão do DSH for diferente do console do Defapi, você pode alterá-lo na lista de modelos da página DSH Models para um ID disponível no console. Em produção, a página Models fica oculta por padrão e só é exibida com UWH_MODEL_SETTINGS_ENABLED=true; localmente, sem NODE_ENV=production, a página nativa DSH Models pode ser aberta diretamente.
3. Criar a configuração de ambiente do Workspace e registrar o cliente OAuth do Agent
Por padrão, o Workspace não registra o cliente OAuth do Agent; apenas copiar .env.example não é suficiente.
cp apps/workspace/.env.example apps/workspace/.env
Em seguida, edite apps/workspace/.env e adicione a configuração de linha única sem comentário:
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"]}]}
Se já existir OAUTH_CLIENTS_JSON, acrescente o cliente acima ao array clients; mantenha sempre apenas uma entrada de configuração.
4. Iniciar o Workspace Server e o Browser
No primeiro terminal, inicie o Server:
pnpm workspace:dev:server
No segundo terminal, inicie o servidor de desenvolvimento do Browser:
pnpm workspace:dev:web
Abra http://127.0.0.1:5173 e registre uma conta local do Workspace ou entre com uma conta existente. O registro local não precisa de OAuth do GitHub/Discord. Mantenha os dois processos em execução.
5. Compilar o DSH Runtime e o Agent Profile e iniciar o Agent local
O Agent é um aplicativo web local; primeiro é necessário montar o runtime DSH a partir do código-fonte. Os comandos abaixo compilam o client-core, três bundles e instalam o Profile em um diretório isolado.
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
O comando fica em primeiro plano em start-local.mjs; isso é normal. Quando aparecer no stderr uma linha começando com dsh web:, copie a URL inteira dessa linha.
Se a porta 3101 estiver ocupada, use outra porta explícita e ajuste os redirectUris do passo 3 de acordo.
6. Conectar o Workspace e concluir o OAuth
No navegador, abra a URL completa impressa por dsh web:; ela contém um ?token=... de uso único. O DSH define um Cookie HttpOnly e redireciona para o endereço raiz.
# 复制启动器输出的完整地址,例如:
# http://127.0.0.1:3101/?token=<one-time-token>
Em seguida, na interface do Agent, acesse Configurações → Workspace e preencha o endereço do serviço local:
http://127.0.0.1:5173
Clique em Sign in to Workspace e aprove o acesso na página de autorização do Workspace. O Workspace redireciona para o callback do Agent local, e o Agent troca o código de autorização via PKCE. Após voltar, a barra lateral deve mostrar a conta e o Space pessoal.
Se a página de conexão ficar esperando, clique em Check again e mantenha o start-local.mjs em execução.
7. Criar a planilha de vendas de exemplo e fazer o Agent gerar resumos e fórmulas
Na barra lateral, abra Arquivos, escolha um Space pessoal ou de equipe, crie uma nova planilha e preencha os detalhes de vendas:
日期,区域,销售额
2025-01-05,华东,12800
2025-01-06,华南,9600
2025-01-07,华东,15100
2025-01-08,华南,14200
Volte a Conversas, crie uma nova conversa, digite @ no campo de entrada para selecionar a planilha recém-criada e envie:
@销售明细 请按区域汇总销售额,并在表格中新增一列计算每个区域的平均销售额。
Após o envio, o Agent valida as referências com base no Workspace atual e grava as alterações na Worktree, sem modificar diretamente o trunk compartilhado.
8. Ver as diferenças da Worktree e mesclar ou descartar
Abra a aba Worktree e encontre a tarefa em andamento. A visualização de revisão mostra “Efeito das alterações” por padrão; você pode alternar para “Diferenças” para ver os documentos adicionados, modificados e excluídos. Depois de confirmar que o resultado está correto, clique em “Mesclar”; se não estiver satisfeito, pode converter em rascunho ou descartar. O trunk compartilhado só é atualizado após o merge.
创建 Worktree
→ Agent 编辑并验证隔离草稿
→ Ready
→ 人工审阅
→ Merge 或 Reopen
→ trunk
Se o Agent executou univer_lint ou univer_screenshot, é necessário ter uma página de renderização estática de versão compatível e Chrome/Chromium. Se faltarem UWH_RENDER_PAGE_ROOT ou um navegador, a ferramenta reportará claramente um erro de pré-condição e não marcará a verificação visual como aprovada.
Solução de problemas comuns
1. Falha ao acessar o Registry privado no pnpm install
A instalação exige acesso ao Registry privado e também ao Registry público do npm; ambos são necessários. Se ficar travado ou retornar 401, primeiro confirme se a rede consegue acessar https://insider-npm-registry.univer.work/ e depois confirme as versões do Node e do pnpm. Não remova as linhas de registry no .npmrc.
2. Aparece OAUTH_CLIENT_UNAVAILABLE
O servidor do Workspace não carregou o cliente OAuth do Agent. Verifique se OAUTH_CLIENTS_JSON em apps/workspace/.env inclui univer-workspace-harness; depois de alterar, reinicie o Server. Apenas copiar .env.example não registra esse cliente.
3. Aparece INVALID_REDIRECT_URI
O endereço de callback deve corresponder exatamente. localhost e 127.0.0.1 são registros diferentes. Se o Agent mudar de porta, ajuste os redirectUris de acordo e reinicie o backend do Workspace. Esse registro controla o callback OAuth; não é uma liberação genérica de CORS para a porta 3101.
4. Abrir o endereço raiz retorna 401
Se você não abrir primeiro a URL completa com token, o navegador não terá o cookie de sessão. Reabra o endereço dsh web: impresso pelo iniciador para concluir a troca; depois, pode usar o endereço raiz sem parâmetros. Não reutilize o token de uso único.
5. Login no Workspace bem-sucedido, mas mensagens do modelo falham
O OAuth do Workspace autoriza apenas o acesso a dados; as credenciais do modelo precisam ser configuradas separadamente. Verifique DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL e o ID do modelo. Ao usar o Defapi, preencha o baseURL com a base de chat completions fornecida pelo console e não acrescente /chat/completions novamente.
6. A página de conexão do Agent fica esperando
Mantenha o start-local.mjs em execução. Após a mudança do estado de conexão, é feita uma verificação de prontidão; se o serviço de conta falhar ao carregar, veja os logs do iniciador. Se a solicitação de autorização expirar, faça login novamente em Configurações → Workspace. Esse fluxo usa OAuth no navegador e não exige a inserção de código de dispositivo.
7. Captura de tela/verificação de layout reporta erro de pré-condição
univer_lint e univer_screenshot exigem que UWH_RENDER_PAGE_ROOT aponte para a página de renderização estática e que UWH_RENDER_BROWSER aponte para um Chrome/Chromium compatível. Se não houver navegador, atribua o caminho do executável a UWH_RENDER_BROWSER e inicie o Agent.
Leitura complementar / Próximos passos
- Implantação com Docker: o Workspace oferece um aplicativo de implantação independente; você pode criar uma imagem seguindo o guia oficial do aplicativo e colocar Server, Browser e armazenamento em um servidor.
- Automação via CLI: instale
univer-workspace-cli, integre-o a ambientes de Agent existentes, como Claude, Codex e Kimi Work, e use a CLI para lidar com documentos e Worktrees. - Integração MCP: o Workspace expõe um serviço MCP remoto com suporte a Streamable HTTP e OAuth; clientes como Cursor, VS Code e Claude Desktop podem se conectar diretamente.
- Documentação oficial e versão fixada: documentação do Univer Web SDK, documentação do Server SDK e documentação de configuração do Workspace. Este tutorial foi escrito com base em
c1a5fb3dc9d5951cbf618f76639466feac5da4d7; para versões futuras, prevalece a documentação oficial.