dsh-univer-workspace-plugin

dsh-univer-workspace-plugin

The Node host defers loading the document runtime pool, Office conversion and API reference until their first operation. The build ships these lazy chunks beside the worker bootstrap in lib/; closing an unused runtime manager does not load document engines. Account switching also joins pending pool initialization before closing it. These are internal packaging and lifecycle choices, not new exports.

The Univer capability plugin for DSH. It gives an agent the ability to operate remote Univer Workspace Units (documents) in the Spaces the authorizing User can access. Documents are Units managed and persisted by the Univer Workspace backend; local paths are used only for task assets and import/export, not as document identities.

The distributed host, worker and browser entries bundle their JavaScript SDK dependencies without source maps. Desktop packaging stages a reduced installation manifest containing external native bindings and ws; binding versions come from the installed SDK wrappers. The source manifest retains its SDK dependencies. DSH peers remain host-provided. Moving a dependency across this boundary requires checking the emitted bundle and running the isolated desktop runtime checks.

Screenshot and layout-lint tools receive the same resolved Univer license as the headless document runtime, including the bundled development default. Local rendering still requires a built render page and Chrome/Chromium; see the Agent render setup.

Why run in a dedicated DSH profile?

This plugin is part of the Workspace Agent application composition. The supported setup installs it into the dedicated univer-workspace-harness profile alongside the Agent core, skin, and version-matched DSH web bundle. Follow the Agent installation guide instead of adding this capability bundle alone to an existing general-purpose web profile.

A DSH profile selects an installed bundle set and its composition patches. A separate profile matters here for four reasons:

• Required services and lifecycle. The plugin consumes the Agent core's workspaceAuth and workspaceRuntime services. They supply the authorized Workspace connection and account-owned runtime directory. Installing the tools alone does not establish OAuth, Space bindings, or account switching.
• Application-wide UI composition. Agent replaces the native sidebar and reference discovery, and configures the webserver, connection handling, settings, and credentials. The native and replacement sidebar cannot both declare the same child slots. Applying these patches to a user's ordinary profile would also change that profile's interface and behavior.
• Tool and document semantics. Other Univer plugins may use overlapping tool names for local .univer files. Here documents are remote, database-backed Workspace Units with Resource identities and Worktree review. Mixing both toolsets in one composition can introduce name collisions and contradictory instructions about where content lives.
• Reproducible dependencies. The profile is a separate pnpm project under $DSH_HOME/profiles/ . The profile builder installs the pinned DSH web bundle first, then the three repository bundles, reusing its peer versions. This keeps Agent's supported bundle set separate from another profile's plugin choices. The DSH CLI is also installed outside the repository workspace to keep its React 18 graph separate from Workspace Browser's React 19 graph; choosing a profile alone does not provide that dependency isolation.

Profile isolation is not account isolation

Boundary	What owns it
Installed plugins and composition patches	The dedicated DSH profile, assembled by build-profile.sh
Workspace connection, login, and account switching	Agent core; one active connection per running instance
Account-specific Sessions, indexes, attachments, and local Space directories	Runtime directories selected by Workspace origin and user ID under UWH_DSH_DATA_HOME
Shared local model settings and browser-session signing state	Agent's shared settings and credentials paths
Remote document access and mutation permissions	Workspace server

Use the same profile when switching Workspace accounts; the application switches account-owned services and data directories without reinstalling plugins or restarting the HTTP listener. All tabs connected to that Agent instance share its current Workspace identity. A profile is not an OS sandbox and does not restrict the agent's local filesystem permissions.

The default profile name remains univer-workspace-harness after the application rename. Keep the builder and launcher on the same DSH_PROFILE if choosing a custom name. See the Agent storage guide for installation paths, shared state, and account data; do not use a profile name as a substitute for those explicit storage boundaries.

Delivered so far

• Workspace sign-in onboarding: a first-run step before model setup offers the Workspace service URL and a primary sign-in action. Connected accounts skip the step; users who defer it retain a sign-in button in the sidebar. Expanding or collapsing the sidebar preserves the settings owner and its deferred onboarding state. Workspace authorization and model credentials remain separate.

• Explicit Space registration: listing remote Spaces is read-only. A new device/account starts with an empty session list; a Space is bound to a local dsh workspace directory only when the user selects it in the add/picker flow. Removing its local registration does not cause browsing to add it back. A durable shadow table (space-links storage domain) maps a dsh workspace id back to { userId, spaceId }. Selecting a Space in DSH selects one of the User's accessible Spaces; the directory is never surfaced to the User.

• Discovery tool: univer_spaces lists the User's Spaces through the harness workspaceAuth service, resolving the calling agent from its session working directory.

• Document tools: univer_documents, univer_open, and univer_create list, open, and create Univer documents through the Workspace product API.

• Editing: univer_edit executes Facade API code in a headless collaboration runtime (read against trunk/draft, write only in Worktree scope with a committed changeset), managed by a forked worker pool.

• Review: univer_worktree drives the Worktree lifecycle (create/ready/merge/discard) with merge and discard forced through the tools/pre-execute approval waterfall.

• Worktree-local Unit: univer_unit implements the Workspace product's source=worktree create contract with the calling Space as its enforced scope, stable idempotency, pending-Operation polling, and complete Unit response validation. action=remove marks a Unit for deletion at merge; action=restore undoes that draft intent. Existing documents enter Trash only after merge, while canceled new Units never become published documents.

• Execution sources and path safety: univer_execute accepts exactly one inline code or session-relative codeFile; both import/export paths use canonical realpath containment checks, including symlink escapes.

• Import/export: univer_import and univer_export use the pinned @univerjs-pro/exchange-node SDK locally. Import converts the session file into JSON-safe UnitData and creates a Worktree-local Unit (so it can be reviewed, discarded, or merged); export synchronizes a trunk or Worktree Unit and writes .xlsx/.csv/.tsv/.docx/.pptx bytes back to the session workspace. The product trunk exchange task is intentionally not used because it would bypass Worktree review semantics.

• Structured inspection: univer_inspect uses the pinned @univer-cli/content-inspection contract for workbook/document/ presentation overviews and Sheet ranges; it never executes caller-provided write code.

• SDK reference and assets: univer_api uses the pinned @univer-cli/api-reference; univer_resources uses the pinned resource library and a build-time copied @univerjs-pro/cli-assets manifest. The latter is a static visual-asset catalog, not the Workspace product's Resource/ACL model.

• Skill references: the native DSH skill loader returns the main instructions and lists reference-reading calls. Use univer_skill_resource with the listed skill and path to read one document. Reading is limited to references and templates bundled with the selected Skill.

• Worktree parity: univer_worktree exposes the review lifecycle used by the browser (create → ready → merge/discard). The underlying transition adapter may retain compatibility with older server actions, but the plugin exposes reopen for returning a ready Worktree to draft.

• Browser Space picker: this plugin owns the Workspace Space picker and injects it into the stock DSH hero/sidebar slots. DSH still owns its native mechanical workspace list and session persistence; selecting a Space registers that Space and hands its directory to the native DSH picker/adoption flow.

• Browser file workspace: the sidebar replaces the shell root with native DSH session and Workspace file tabs. The file tab browses the authenticated Space/Node/Resource tree, creates items in permitted folders, renames and trashes nodes, and exposes a capability-gated trash view with restore and permanent removal. Univer Resources open in the embedded Viewer; Blob Resources use the native DSH Sidecar for read-only image, video, audio, PDF, and text previews, while unsupported media remains download-only. .univer.html files use the private shared HTML viewer with live Sheet subscriptions and permission-checked trunk writes. Other Blob previews are read-only. HTML source access is independently authorized through the current account; publishing its template does not edit Sheets. Native tab close retains the HTML runtime until save confirms; failed saves keep a recovery surface with a save-and-close action. See the HTML integration guide.

• Blob tools: univer_blob exposes get/download/upload/replace through the existing Workspace service/provider and authenticated HTTP client. Get reads metadata only. Upload creates a new Blob from a session file in the current Space by default, with optional spaceId, parentNodeId, and name. Download into the session workspace, edit locally, then replace with the exact downloaded ETag. Uploads and replacements publish immediately, without Worktree review. Both writes require an idempotencyKey; retry with the same key and unchanged input to resume the same operation instead of creating a duplicate. Stale ETags require downloading and reconciling current content; file paths use the same session containment checks as import/export.

• Native Sidecar preview: file and Worktree opens update one Workspace preview tab in the current session's native right sidebar. DSH owns tab closing, resizing, splitting and fullscreen; Workspace renders the content inside it. With no selected session, the native flow reuses or creates a blank session in an already-added Space. If none has been added, the UI asks the user to add one first. Other native tab types remain available.

• Capability HTTP routes: /api/uwh/me, /api/uwh/template-fork, Space rename, the same-origin Space/Node tree, and trash actions are registered by this plugin. The Workspace Agent only supplies the authenticated workspaceAuth service they consume.

• Bundled skill: univer teaches the model the Space/document model and the Worktree review rules.

• Conversation change summaries: turn cards list the documents touched by that Turn. Clicking a row opens its Worktree in Sidecar and locates the document; conversation cards do not mount document runtimes or offer preview accordions.

• Floating task list: one compact session list shows each Worktree's status and counts of added, modified and deleted documents. Rows open Sidecar. The list is portaled to the document and can be dragged across the entire viewport, independently of conversation and Sidecar layout.

Not yet delivered (tracked as follow-up stages)

• The remaining Office-only gateway/file capabilities that do not have a Workspace product equivalent yet.

Document creation and review

For agent tasks, create an empty draft with univer_worktree (action: "create", no resourceId), then create a document with univer_unit (action: "create") or import one with univer_import. New Units stay in the Worktree until merge activates their reserved Resource and Node identities in the target Space. Existing documents enter a new Worktree by passing their resourceId to univer_worktree. Verify the content, mark the draft ready, and let the user review it before merge.

univer_new and univer_create create documents directly in trunk and are for explicit requests to publish immediately. Worktree changes support new, modified, and deleted documents. Use univer_unit with action: "remove" to mark a document for deletion and action: "restore" to undo that intent while the Worktree is a draft. Merging moves existing documents to Trash and cancels unpublished new Units. Discarding a Worktree leaves existing documents unchanged.

dsh-univer-office tool audit

The office plugin operates local .univer files, while this plugin operates remote Workspace Resources. The shared operations are deliberately mapped to the remote contract rather than accepting a local file path that the server cannot authorize:

dsh-univer-office	Workspace plugin	Boundary
univer_new	univer_new / univer_create	Resource creation is a Workspace API operation; the result is opened to resolve unitId.
univer_unit	univer_unit (create, remove, restore)	Create draft Units or update their deletion intent through the Workspace product API; merge approval remains a separate Worktree action.
univer_status	univer_status + univer_spaces, univer_documents, univer_open	Status returns the selected trunk Resource or Worktree Unit/file-state; Space, Node and Unit identity remain separate remote resources.
univer_execute	univer_execute (or univer_edit mode=write)	Writes are Worktree-scoped and commit a collaboration changeset; exactly one inline code/safe session codeFile is accepted.
univer_inspect	univer_inspect	Uses the public content-inspection SDK over the same headless collaboration runtime; range selectors are validated before execution.
univer_worktree