Univer Workspace

Univer Workspace is a deployable knowledge and collaboration workspace built on the Univer Office SDK. It brings Sheets, Docs, Slides, relational tables, canvases, and more into one shared runtime, with data and references staying connected across artifacts as the workspace changes.

Choose the Workspace Browser for direct editing, Workspace Agent for document conversations and change review, or the CLI for automation. All three connect to the Workspace Server, which owns document storage and permissions. Agents work in isolated Worktrees, verify their changes, and hand the result to a person for review. Humans can continue editing and stay in control of what gets merged.

Why Univer Workspace

Spreadsheet-based mini-apps · Watch the demo

• Agents can generate spreadsheet-based mini-apps, such as decision-making dashboards, interactive reports, and business dashboards.
• Metrics, charts, and controls on the web page are bound to cells, supporting data reads, writes, and collaborative updates.
• See the HTML View showcase for ten page styles, live editing, and public sharing with visitor trials.

Choose your entry point

Workspace Agent is a local web application built on DSH (DeepSeek Harness). Its local file references point to the machine running Agent; Workspace documents remain on the connected service. Both Agent and CLI can connect to your existing Workspace deployment or one you start locally.

Connect an AI assistant (MCP)

Workspace runs a remote MCP server. An assistant connected to it can find your files, open a pull request, edit Sheets, Docs, and Slides, read the result back, and mark the pull request ready for you to review in the browser. Nothing is installed on your machine.

A client that cannot run OAuth can send a personal access token as Authorization: Bearer <token>. Create one from Access tokens in the Workspace account menu. On space.univer.ai, editing tools (execute, inspect, import, and export) are currently enabled only for invited accounts; every account can browse, search, and manage issues and pull requests.

claude mcp add --transport http univer-workspace https://space.univer.ai/mcp

codex mcp add univer-workspace --url https://space.univer.ai/mcp
codex mcp login univer-workspace

[mcp_servers.univer-workspace]
url = "https://space.univer.ai/mcp"

{
  "mcpServers": {
    "univer-workspace": { "url": "https://space.univer.ai/mcp" }
  }
}

code --add-mcp '{"name":"univer-workspace","type":"http","url":"https://space.univer.ai/mcp"}'

gemini mcp add --transport http --scope user univer-workspace https://space.univer.ai/mcp

opencode mcp add univer-workspace --url https://space.univer.ai/mcp --global
opencode mcp auth univer-workspace

{
  "mcpServers": {
    "univer-workspace": { "serverUrl": "https://space.univer.ai/mcp" }
  }
}

{
  "mcpServers": {
    "univer-workspace": { "type": "streamableHttp", "url": "https://space.univer.ai/mcp" }
  }
}

If a client keeps asking you to sign in, sign out of the server in that client (for example claude mcp logout univer-workspace, opencode mcp logout univer-workspace, or /mcp auth in Gemini CLI) and sign in again. If a tool you expect is missing, check the ?toolsets= part of the URL.

Space Preview

Space is a proof-of-concept plugin for Univer Workspace that you install in official DeepSeek Harness (DSH). It connects to your Workspace service so you can browse files, edit Univer Docs and Sheets, and chat with an AI alongside an open document.

See the Space plugin guide for the package, installation steps, and known limitations. Space is optional and does not replace Workspace Agent. Use non-critical documents while evaluating this preview.

How it works

flowchart LR
    Human([Human]) --> Browser[Workspace Browser]
    Agent([AI agent]) --> CLI[Workspace CLI]
    Human --> AgentApp[Workspace Agent: local conversation and review]
    AgentApp --> Server
    Browser --> Server[Workspace Server]
    CLI --> Server
    Server --> Product[(Product data)]
    Server --> Collaboration[(Collaboration data)]
    Server --> Blobs[(Blob and asset bytes)]

The Browser is the direct editing and collaboration surface. Workspace Agent combines a conversation with document previews and Worktree review. The CLI gives agents a structured way to load, understand, edit, validate, and render the same content. The Server resolves authoritative identity and permissions, owns Workspace product workflows, and composes the Univer Collaboration SDK.

Worktree turns agent editing into an explicit review workflow:

create Worktree
→ agent edits and verifies an isolated draft
→ Ready
→ human reviews in the Browser or Workspace Agent
→ Merge or Reopen
→ trunk

Intermediate changes remain isolated from shared content until a person accepts them. See the CLI guide for the complete product workflow.

Quick start

These commands start the Workspace service and Browser. To add the conversation interface, follow the Workspace Agent guide.

Requirements

• Node.js 24 or newer
• pnpm 11

Install dependencies and prepare the application configuration:

pnpm install
cp apps/workspace/.env.example apps/workspace/.env

Start the Server:

pnpm workspace:dev:server

In another terminal, start the Browser development server:

pnpm workspace:dev:web

Open http://127.0.0.1:5173. Vite provides hot module replacement and proxies API and WebSocket traffic to the Server at http://127.0.0.1:3020.

The Server can also serve the latest built Browser from port 3020 when apps/workspace/dist/public exists. Its product API is available at http://127.0.0.1:3020/api-docs and http://127.0.0.1:3020/openapi.yaml.

Configuration, authentication, storage, Docker, and database migration details live in the Workspace application guide.

One-Click Deploy

Use Workspace Agent

Workspace Agent is a desktop app built on DSH for Univer Workspace. Reference Workspace files with @, create and edit documents through conversation, then review changes and choose whether to merge or discard them.

The Agent guide includes a prompt you can give a coding agent before cloning the repository, as well as manual setup and usage instructions. It walks through choosing or starting your own Workspace service, registering the OAuth callback, configuring model credentials, and opening the complete token URL printed by the local launcher.

Desktop Agent packaging and manual CI are described in the desktop guide. Downloads use GitHub Releases; Agent release tags never trigger automatic publication.

Use the Workspace CLI

To use Workspace with an existing agent such as Claude, Codex, or Kimi Work, install the CLI and Workspace CLI Skill in the environment where the agent runs:

npm install --global univer-workspace-cli@latest
npx skills add dream-num/univer-workspace --skill univer-workspace-cli -g

Point the CLI at your own Workspace deployment, then begin browser-approved login:

uvw config set workspace.origin <origin>
uvw auth login

After the user approves the displayed URL and verification code, complete the one-time exchange:

uvw auth login --complete

The installed package includes version-matched Skills, structured JSON output, Facade API discovery, content inspection, PNG/PDF rendering, Office exchange, and Worktree workflows. See the CLI guide for the complete usage and login contract.

Repository layout

apps/workspace                 Workspace Browser, Server, HTTP contract, and deployment app
apps/cli                       Agent-ready remote Workspace automation application
apps/mcp                       Private MCP gateway, Stage A local development authentication
apps/agent                     Workspace Agent application for document conversations and review
packages/client-core           Private Node-hosted Workspace Agent Client capabilities
packages/reference-provider   Private Browser-only referenced-Unit policy
packages/workspace-html-viewer Private shared HTML View sandbox and binding host
packages/workspace-markdown-viewer Private shared read-only Markdown preview
packages/dsh-univer-workspace-plugin        Workspace Agent Workspace capabilities and browser UI
packages/dsh-univer-workspace-skin-plugin   Workspace Agent Workspace visual skin
scripts                       SDK version and local CLI release tooling

This repository is the product composition root, not a replacement for the upstream SDKs. Univer Runtime owns the Unit model, rendering, Facade APIs, and Office content capabilities. Univer Collaboration SDK owns snapshots, revisions, OT, realtime collaboration, and Worktree protocol contracts. Univer CLI SDK owns the reusable headless runtime, execution, inspection, and rendering capabilities.

Workspace owns product identity, Spaces, hierarchy, ACLs, sharing, Trash, Recent, Blob storage policy, remote workflows, and deployment. Client Core shares storage-neutral authentication, Workspace workflows, local Node-hosted Blob/Asset transfer, and the worker-backed content runtime between repository applications, including Node-hosted Office exchange, Markdown compile/create/native-readback/update, Typst compile/materialize/apply, render Unit assembly, screenshots, PNG/PDF output, Slide layout lint, the render-page source, and the SVG compile/measure/apply workflow; the reference-provider package remains Browser-only. Both are private implementation modules, not additional public applications or SDKs.

Architecture principles

• One authoritative Server. Client-provided users, roles, Resources, Units, Worktrees, and revisions are never trusted as authority.
• Separate storage boundaries. Product data, collaboration state, and Blob bytes have distinct owners and are coordinated through durable, idempotent operations.
• Published SDK contracts only. The repository consumes public package exports and never depends on adjacent source checkouts.
• One exact SDK baseline. Version-coupled @univer-cli/*, @univerjs/*, and @univerjs-pro/* packages always move together.
• Contract-first HTTP. OpenAPI source, generated types, Server routes, Browser, and CLI must describe the same behavior.

Read the technical architecture, application design, and data model before changing these boundaries.

Development and verification

Run the smallest relevant check while iterating. Before opening a PR, run the same verification entry used by CI on Linux or macOS:

pnpm verify
pnpm verify --stage test-mcp

The six stages are static, test-workspace, test-cli, test-mcp, test-rest and package. They include HTTP contract generation verification, typechecks, SDK dependency and type-identity checks against installed published packages, all workspace tests, builds, an isolated installation of the actual CLI tarball, and Workspace production import/migration checks. pnpm check remains the shorter typecheck/test loop.

An existing installation can hide dependency-resolution problems. To verify a committed change with a fresh dependency graph and build state, use Node 24 and the pinned pnpm version in a separate worktree:

git worktree add --detach ../univer-ci-check HEAD
cd ../univer-ci-check
node scripts/verify.mjs --install

--install records pnpm install --frozen-lockfile before verification. CI uses this entry in its fresh checkout. The worktree recipe checks HEAD; uncommitted changes in the original directory are not included. A normal local run records whether its source tree is dirty and does not claim a clean installation.

Reports live in .verification/. Each invocation keeps separate command logs, process exit codes/signals, structured Vitest and node:test results, and a summary with commit, attempt, stage, file and test. A failed process remains a failure even if its test report is missing. CI uploads each stage under a distinct run/attempt artifact name for 30 days, including failed runs. Rerunning does not overwrite the first attempt. Setup failures before the verification entry and forcibly terminated runners may have incomplete artifacts; their workflow status still counts.

With gh authenticated, inspect recent first-attempt outcomes and recurring failures:

pnpm ci:reliability --limit 20

The first-pass denominator excludes cancelled and unfinished first attempts. Signature analysis covers failed first attempts. Its coverage is reported separately because older or expired artifacts cannot identify individual failing tests. Reports can contain test fixture data; keep them within the repository's existing access boundary.

Update every version-coupled Univer dependency and the lockfile with the repository script rather than editing individual manifests:

pnpm update:univer-sdk --sdk_version <exact-sdk-version>

Delivery model

The CLI and Workspace deployment are delivered independently from the same source:

• Manually dispatch the CLI release workflow on a stable vX.Y.Z tag contained in main and explicitly set dry_run=false to publish univer-workspace-cli@X.Y.Z. Creating or pushing tags never triggers CI or publication.
• Workspace deployment is a separate manual workflow. It builds either an existing stable tag or an exact commit as sha-<commit>. Pushing a release tag does not deploy the Server.

Stable CLI releases validate the repository-wide SDK baseline and test the actual package artifact before publication.

Documentation

Contributing

Issues and pull requests are welcome. Before changing code, read AGENTS.md and the README or design document closest to the target. Preserve unrelated changes, do not edit generated files by hand, and include the verification required by the affected boundary.

Runtime development license

The Browser, Workspace server, CLI and DSH plugin contain synchronized copies of the approved runtime development credential for local use. It rotates every 90 days and is not the repository software license. The server-side Collaboration and Exchange SDKs also verify it with a license key; without both they fall back to the free tier. Set VITE_UNIVER_LICENSE for Browser builds, or UNIVER_LICENSE together with UNIVER_LICENSE_KEY for the server and CLI, to override it. Rotate every copy at once with the generated-file script:

pnpm update:univer-license --license <license.txt> --license-key <licenseKey.txt>

License

Univer Workspace is licensed under Apache-2.0.

Space 和原 Workspace Agent 共用 packages/workspace-agent-runtime 的既有 Headless Facade / Worktree changeset 实现。它只负责内容 worker，不提供另一个 DSH Runtime。先运行 pnpm --filter @univerjs/univer-workspace-agent-runtime build，再构建相应消费者；Space 将该公开入口与 worker 内联/复制到自己的安装包，不把 file: 开发依赖带入 Host。