Univer Workspace documents
Use the structured univer_* tools whenever the task creates, reads, changes, converts, or reviews office content. Do not wait for the user to name a tool. Do not invoke a global univer CLI, access backend document storage directly, or substitute openpyxl, python-pptx, python-docx, ZIP manipulation, or another writer.
Start immediately
- Existing document: discover it with
univer_documents and open its resourceId with univer_open; call univer_status with that identity before selecting a Unit or continuing a worktree.
- New Modern Doc: create an empty draft Worktree, load
univer-doc, then call
univer_compile_markdown with a session Markdown file. It creates the Doc Unit; no placeholder
is needed. Use univer_export_markdown before editing selected current native blocks.
- Other new document: call
univer_worktree with action: "create" and no resourceId, then univer_unit with action: "create", the returned worktreeId, name, and unitType. The target spaceId defaults to the session's linked Space; set it and parentNodeId explicitly when needed.
- Office source (
.xlsx, .csv, .tsv, .docx, .pptx): create an empty draft worktree, then call univer_import in that worktree. Import creates the new Unit; no placeholder document is needed.
univer_new and univer_create create a document directly in the Space's trunk. Use them only when the user explicitly requests immediate creation outside the review workflow.
- Before authoring content, load the matching Unit skill:
univer-sheet, univer-doc, univer-slide, univer-base, or univer-board.
- For an Embed or a Chart backed by another Unit's data, also load
univer-embed. For formulas that read another Unit, also load univer-cross-unit-formula.
Mental model
- A document is a Sheet, Doc, Slide, Base, or Board Unit managed by the Univer Workspace backend. Its content is persisted by backend services in databases, not in a local document file.
resourceId identifies the product resource, unitId identifies its document content, and nodeId identifies its location in a Space. A Worktree can group multiple Units; it is an isolated review scope, not a storage file.
- A new Worktree-local Unit has reserved identities and a target Space/folder. It appears in the formal Space directory only after merge activates it; discard does not publish it.
- Sheet names, pages, paragraphs, tables, ranges, shapes, fields, records, and views live inside a Unit; none substitutes for
unitId.
trunk is the reviewed main line. A worktree is an isolated scope for agent changes. There is no implicit current worktree.
- Every content write requires the complete address: draft
worktreeId and unitId (plus unitType where required by the tool).
univer_execute persists only when Facade mutations occurred. A read-only execution produces no revision.
ready rejects writes until reopen. merged and discarded are terminal; never reuse them.
- Tool success is not correctness evidence. Read the changed model back and verify task-specific assertions.
SVG resources
When a Unit needs icons, logos, emoji, or illustrations, use the bundled resource library instead of inventing placeholders:
- Call
univer_resources with action: "registries" when registry choice matters.
- Call
univer_resources with action: "find" and one or more semantic queries; retain the exact returned handles.
- Call it with
action: "export", those handles, and an explicit workspace output directory.
- Reference the exported SVG files from Slide SVG, or read one handle with
action: "read" when inline SVG text is required.
Only colorEditable: true resources may follow an authored color. Fixed logos, color emoji, and illustrations keep their intrinsic colors. Reuse the exported file; do not copy partial path data from it.
Facade API lookup
- No relevant class or API label is known: use
find with API-name keywords or identifier fragments.
- A class is known: use
show on the class to inspect its APIs.
- A type or exact
Class.member API label is known: use show on that label for signatures, documentation, and examples.
find is case-insensitive. Each query is searched independently and returns its own matches; queries are not combined as AND, and find does not interpret intent. Pass a useful returned label to show instead of searching that label again.
Work from an Issue
An Issue is a request recorded by the user's team in a Team Space, addressed by Space and number (#12). When the user says "work on #12" or points at an Issue, the Issue is the brief: do not ask them to restate it.
- Call
univer_issue with action: "get" and the number (add spaceId when the session is not linked to that Team Space). Read the body and the whole discussion; later comments can change or narrow the request. univer_issue with action: "list" and scope: "mine", assignee: "me" shows what is assigned to the user.
references lists the files the Issue points at. Open each available Univer file with univer_open using its resourceId, and pass that resourceId to univer_worktree create. An entry with available: false was trashed or became unreadable; say so instead of guessing which file was meant. A reference with kind: "blob" is an original file: pass its resourceId to univer_blob. A reference with kind: null is a folder: browse it with univer_documents using its nodeId.
- Follow the required workflow below in a new Worktree named
#12 <Issue title>. The Worktree does not link to the Issue itself, so the name is what ties them together for reviewers.
- When the Worktree is
ready, report back on the Issue with univer_issue comment: say what changed and name the Worktree. End the comment with "(Posted by an agent on the user's behalf.)" because the comment appears under the user's name.
- Leave the Issue open. Closing it (
action: "close") is the user's decision, as is merging; do neither unless they ask.
Issue writes are not idempotent. If a create or comment fails with an unknown result, get the Issue before repeating it, or the discussion may end up with a duplicate. Labels, assignees and linked files need triage rights; if univer_issue reports access denied, tell the user rather than working around it. Use create to record follow-up work you found but were not asked to do. Issues exist only in Team Spaces: ISSUES_TEAM_SPACE_ONLY means the session's Space is personal, so pass a Team Space spaceId.
Required workflow
For document deletion, use univer_unit with action: "remove", worktreeId, and unitId. This only records draft intent; use action: "restore" to undo it before Ready. Existing documents enter Trash after an approved merge, and canceled new draft Units are never published. Do not use permanent deletion or filesystem operations for this workflow.
- Discover existing documents through
univer_spaces, univer_documents, and univer_open. For an existing scope, call univer_status with resourceId or worktreeId; it is not an unscoped listing tool.
- Use one Worktree for the ongoing task, including follow-up requests that add another document type. For example, adding a presentation based on a draft spreadsheet belongs in the same Worktree. Check the existing task Worktree with
univer_status; reuse it if draft, or call univer_worktree with action: "reopen" if ready. Create a new Worktree only for an independent task or after the previous one was merged or discarded. For new documents, omit resourceId; for an existing document, supply its resourceId when creating the worktree. Continue an existing worktree only after confirming its state.
- For a new Modern Doc, let
univer_compile_markdown create the Unit. For other new documents,
use univer_unit or univer_import. For an existing document, use its returned Unit identity;
do not create a duplicate.
- Load the matching Unit skill before writing Facade code.
- Resolve unfamiliar Facade usage with
univer_api following the lookup rules above. Never guess an unfamiliar signature, parameter type, or enum.
- For Modern Docs, use
univer_compile_markdown; export selected current blocks with
univer_export_markdown before partial updates. Use univer_compile_svg for generated
Slide page content, or univer_execute for direct Facade operations.
- Read the changed scope with
univer_inspect; use a fresh read-only univer_execute when inspection omits a required model field.
- For every changed Slide page, call
univer_lint and resolve or explicitly justify each finding.
- For visually relevant changes, call
univer_screenshot with an explicit workspace output directory and the narrowest useful Unit-specific target. Inspect every returned image; screenshots complement rather than replace structural readback or Slide lint.
- Export with
univer_export only when requested and only from the verified scope.
- Mark the worktree
ready and confirm it with univer_status.
univer_screenshot returns model-visible PNG evidence and writes the same PNGs under its explicit output directory. It requires an image-capable current model route. The DSH client also renders live worktree content and the ready review panel from tool results; that preview remains the user-facing handoff surface because there is no model-facing show/open tool. Claim visual verification only for images actually inspected in the current result.
Merge or discard only when the user explicitly requests that outcome. Both operations change review state and are not routine completion steps.
Rework after feedback
Continue in the same worktree only for changes to the same task and only after univer_status confirms that it is still ready or draft.
- If it is
ready, call univer_worktree with action: "reopen".
- If it is already
draft, continue directly.
- Make the remaining changes and repeat the complete readback and Unit-specific verification.
- Mark it
ready again and confirm the final status.
Never reopen or reuse a merged or discarded worktree; create a new worktree instead.
Tool map
| Stage |
Tool |
Use |
| Discover |
univer_spaces, univer_documents, univer_open |
Discover remote documents and resolve their identities. |
| Direct creation |
univer_new, univer_create |
Create a typed document immediately in trunk; prefer Worktree-local creation for agent tasks. |
| Start |
univer_status |
Inspect a document or Worktree using an explicit identity. |
| Start |
univer_issue |
list, get, create, update, comment, close, or reopen Team Space Issues. get before working on one. |
| Start |
univer_worktree |
create, ready, reopen, merge, or discard. |
| Start |
univer_unit |
Create a draft Unit, mark one for deletion with remove, or undo its deletion intent with restore. |
| Start |
univer_import |
Import local xlsx, csv, tsv, docx, or pptx as a new Unit. |
| Write |
univer_execute |
Run version-matched Facade JavaScript against one Unit in a draft worktree. |
| Write |
univer_compile_markdown |
Create native Modern Docs or replace selected explicit blocks from session Markdown. |
| Read for editing |
univer_export_markdown |
Export selected current native Doc blocks, assets, map, and revision. |
| Write |
univer_compile_svg |
Compile workspace SVG into one explicit Slide page with browser text metrics. |
| Verify |
univer_inspect |
Read structured Unit content from trunk or one worktree. |
| Verify |
univer_lint |
Check Slide text off-page, container escape, and text overlap. |
| Verify |
univer_screenshot |
Render Sheet, Doc, Slide, Base, or Board PNG evidence and return it to an image-capable model. |
| Reference |
univer_api |
Find an unknown name, or show a known class, API, or type. |
| Reference |
univer_resources |
List/find/read/export bundled SVG resources or clear their download cache. |
| Deliver |
univer_export |
Export Sheet/Base to xlsx/csv/tsv, Doc to docx, or Slide to pptx. |
Facade execution
univer_execute injects univerAPI, api (the same object), and one Unit-specific handle:
- Sheet:
workbook
- Doc:
doc
- Slide:
presentation
- Board:
board
Do not redeclare injected variables. Use code only for a small snippet. For multi-line or reusable Facade logic, write a workspace JavaScript body file and pass it as codeFile; provide exactly one of code or codeFile.
Execution is Node ESM: require is unavailable, while dynamic import() and Buffer are available. For an explicit local workspace image, generate its data URI inside the execution instead of putting Base64 in the conversation:
const { readFile } = await import("node:fs/promises");
const bytes = await readFile("/absolute/session/workspace/image.png");
const imageDataUri = `data:image/png;base64,${Buffer.from(bytes).toString("base64")}`;
Read only task assets inside the session workspace. Do not print or return the data URI. Resolve exact Facade methods with univer_api, check boolean/null returns, and retain stable IDs needed by later operations.
Import and export
- Import accepts workspace files only; URL import is unavailable.
- Export Sheet or Base to
.xlsx, .csv, or .tsv; Doc to .docx; Slide to .pptx.
- Board export is unsupported.
- Export uses an explicit Unit and an explicit trunk or worktree scope. Recalculate formulas and finish readback before exporting.
Unsupported CLI-only capabilities
Do not invent equivalents for CLI maintenance, daemon/configuration, compile-typst, optimization, or shell command help. Use the bundled DSH tools for resources and screenshots; if the task requires another missing capability, report that exact gap.
Failure recovery
Tool failures use Error [CODE]: message. Route recovery by the code, not free text.
- For
GATEWAY_UNAVAILABLE or GATEWAY_REQUEST_TIMEOUT, retry one univer_status read. After a write timeout, inspect status and content before continuing.
- For
FILE_PERMISSION_DENIED or SESSION_SCOPE_DENIED, use an accessible in-workspace path or ask the user to correct access; do not retry the same path.
- For worktree or Unit state errors, refresh with
univer_status; reopen ready worktrees and replace terminal ones.
1---2name: univer3description: Create, inspect, edit, import, export, and hand off remote Univer Workspace documents (Units) through DSH tools and isolated worktrees. Use proactively for any task involving Workspace documents, spreadsheets or .xlsx/.csv/.tsv data, presentations or .pptx slides, .docx documents, Base databases, Board canvases, cross-Unit content, or exact Univer Facade API authoring; load this before the matching Unit skill.4metadata:5 source: https://skillmd.com/skills/dream-num/univer6---78# Univer Workspace documents910Use the structured `univer_*` tools whenever the task creates, reads, changes, converts, or reviews office content. Do not wait for the user to name a tool. Do not invoke a global `univer` CLI, access backend document storage directly, or substitute openpyxl, python-pptx, python-docx, ZIP manipulation, or another writer.1112## Start immediately1314- Existing document: discover it with `univer_documents` and open its `resourceId` with `univer_open`; call `univer_status` with that identity before selecting a Unit or continuing a worktree.15- New Modern Doc: create an empty draft Worktree, load `univer-doc`, then call16 `univer_compile_markdown` with a session Markdown file. It creates the Doc Unit; no placeholder17 is needed. Use `univer_export_markdown` before editing selected current native blocks.18- Other new document: call `univer_worktree` with `action: "create"` and no `resourceId`, then `univer_unit` with `action: "create"`, the returned `worktreeId`, `name`, and `unitType`. The target `spaceId` defaults to the session's linked Space; set it and `parentNodeId` explicitly when needed.19- Office source (`.xlsx`, `.csv`, `.tsv`, `.docx`, `.pptx`): create an empty draft worktree, then call `univer_import` in that worktree. Import creates the new Unit; no placeholder document is needed.20- `univer_new` and `univer_create` create a document directly in the Space's trunk. Use them only when the user explicitly requests immediate creation outside the review workflow.21- Before authoring content, load the matching Unit skill: `univer-sheet`, `univer-doc`, `univer-slide`, `univer-base`, or `univer-board`.22- For an Embed or a Chart backed by another Unit's data, also load `univer-embed`. For formulas that read another Unit, also load `univer-cross-unit-formula`.2324## Mental model2526- A document is a Sheet, Doc, Slide, Base, or Board Unit managed by the Univer Workspace backend. Its content is persisted by backend services in databases, not in a local document file.27- `resourceId` identifies the product resource, `unitId` identifies its document content, and `nodeId` identifies its location in a Space. A Worktree can group multiple Units; it is an isolated review scope, not a storage file.28- A new Worktree-local Unit has reserved identities and a target Space/folder. It appears in the formal Space directory only after merge activates it; discard does not publish it.29- Sheet names, pages, paragraphs, tables, ranges, shapes, fields, records, and views live inside a Unit; none substitutes for `unitId`.30- `trunk` is the reviewed main line. A worktree is an isolated scope for agent changes. There is no implicit current worktree.31- Every content write requires the complete address: draft `worktreeId` and `unitId` (plus `unitType` where required by the tool).32- `univer_execute` persists only when Facade mutations occurred. A read-only execution produces no revision.33- `ready` rejects writes until `reopen`. `merged` and `discarded` are terminal; never reuse them.34- Tool success is not correctness evidence. Read the changed model back and verify task-specific assertions.3536## SVG resources3738When a Unit needs icons, logos, emoji, or illustrations, use the bundled resource library instead of inventing placeholders:39401. Call `univer_resources` with `action: "registries"` when registry choice matters.412. Call `univer_resources` with `action: "find"` and one or more semantic `queries`; retain the exact returned handles.423. Call it with `action: "export"`, those `handles`, and an explicit workspace `output` directory.434. Reference the exported SVG files from Slide SVG, or read one handle with `action: "read"` when inline SVG text is required.4445Only `colorEditable: true` resources may follow an authored color. Fixed logos, color emoji, and illustrations keep their intrinsic colors. Reuse the exported file; do not copy partial path data from it.4647## Facade API lookup4849- No relevant class or API label is known: use `find` with API-name keywords or identifier fragments.50- A class is known: use `show` on the class to inspect its APIs.51- A type or exact `Class.member` API label is known: use `show` on that label for signatures, documentation, and examples.5253`find` is case-insensitive. Each query is searched independently and returns its own matches; queries are not combined as AND, and `find` does not interpret intent. Pass a useful returned label to `show` instead of searching that label again.5455## Work from an Issue5657An Issue is a request recorded by the user's team in a Team Space, addressed by Space and number (`#12`). When the user says "work on #12" or points at an Issue, the Issue is the brief: do not ask them to restate it.58591. Call `univer_issue` with `action: "get"` and the `number` (add `spaceId` when the session is not linked to that Team Space). Read the body and the whole discussion; later comments can change or narrow the request. `univer_issue` with `action: "list"` and `scope: "mine"`, `assignee: "me"` shows what is assigned to the user.602. `references` lists the files the Issue points at. Open each available Univer file with `univer_open` using its `resourceId`, and pass that `resourceId` to `univer_worktree` `create`. An entry with `available: false` was trashed or became unreadable; say so instead of guessing which file was meant. A reference with `kind: "blob"` is an original file: pass its `resourceId` to `univer_blob`. A reference with `kind: null` is a folder: browse it with `univer_documents` using its `nodeId`.613. Follow the required workflow below in a **new** Worktree named `#12 <Issue title>`. The Worktree does not link to the Issue itself, so the name is what ties them together for reviewers.624. When the Worktree is `ready`, report back on the Issue with `univer_issue` `comment`: say what changed and name the Worktree. End the comment with "(Posted by an agent on the user's behalf.)" because the comment appears under the user's name.635. Leave the Issue open. Closing it (`action: "close"`) is the user's decision, as is merging; do neither unless they ask.6465Issue writes are not idempotent. If a `create` or `comment` fails with an unknown result, `get` the Issue before repeating it, or the discussion may end up with a duplicate. Labels, assignees and linked files need triage rights; if `univer_issue` reports access denied, tell the user rather than working around it. Use `create` to record follow-up work you found but were not asked to do. Issues exist only in Team Spaces: `ISSUES_TEAM_SPACE_ONLY` means the session's Space is personal, so pass a Team Space `spaceId`.6667## Required workflow6869For document deletion, use `univer_unit` with `action: "remove"`, `worktreeId`, and `unitId`. This only records draft intent; use `action: "restore"` to undo it before Ready. Existing documents enter Trash after an approved merge, and canceled new draft Units are never published. Do not use permanent deletion or filesystem operations for this workflow.70711. Discover existing documents through `univer_spaces`, `univer_documents`, and `univer_open`. For an existing scope, call `univer_status` with `resourceId` or `worktreeId`; it is not an unscoped listing tool.722. Use one Worktree for the ongoing task, including follow-up requests that add another document type. For example, adding a presentation based on a draft spreadsheet belongs in the same Worktree. Check the existing task Worktree with `univer_status`; reuse it if draft, or call `univer_worktree` with `action: "reopen"` if ready. Create a new Worktree only for an independent task or after the previous one was merged or discarded. For new documents, omit `resourceId`; for an existing document, supply its `resourceId` when creating the worktree. Continue an existing worktree only after confirming its state.733. For a new Modern Doc, let `univer_compile_markdown` create the Unit. For other new documents,74 use `univer_unit` or `univer_import`. For an existing document, use its returned Unit identity;75 do not create a duplicate.764. Load the matching Unit skill before writing Facade code.775. Resolve unfamiliar Facade usage with `univer_api` following the lookup rules above. Never guess an unfamiliar signature, parameter type, or enum.786. For Modern Docs, use `univer_compile_markdown`; export selected current blocks with79 `univer_export_markdown` before partial updates. Use `univer_compile_svg` for generated80 Slide page content, or `univer_execute` for direct Facade operations.817. Read the changed scope with `univer_inspect`; use a fresh read-only `univer_execute` when inspection omits a required model field.828. For every changed Slide page, call `univer_lint` and resolve or explicitly justify each finding.839. For visually relevant changes, call `univer_screenshot` with an explicit workspace output directory and the narrowest useful Unit-specific target. Inspect every returned image; screenshots complement rather than replace structural readback or Slide lint.8410. Export with `univer_export` only when requested and only from the verified scope.8511. Mark the worktree `ready` and confirm it with `univer_status`.8687`univer_screenshot` returns model-visible PNG evidence and writes the same PNGs under its explicit `output` directory. It requires an image-capable current model route. The DSH client also renders live worktree content and the ready review panel from tool results; that preview remains the user-facing handoff surface because there is no model-facing show/open tool. Claim visual verification only for images actually inspected in the current result.8889Merge or discard only when the user explicitly requests that outcome. Both operations change review state and are not routine completion steps.9091## Rework after feedback9293Continue in the same worktree only for changes to the same task and only after `univer_status` confirms that it is still `ready` or `draft`.94951. If it is `ready`, call `univer_worktree` with `action: "reopen"`.962. If it is already `draft`, continue directly.973. Make the remaining changes and repeat the complete readback and Unit-specific verification.984. Mark it `ready` again and confirm the final status.99100Never reopen or reuse a merged or discarded worktree; create a new worktree instead.101102## Tool map103104| Stage | Tool | Use |105| ---------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |106| Discover | `univer_spaces`, `univer_documents`, `univer_open` | Discover remote documents and resolve their identities. |107| Direct creation | `univer_new`, `univer_create` | Create a typed document immediately in trunk; prefer Worktree-local creation for agent tasks. |108| Start | `univer_status` | Inspect a document or Worktree using an explicit identity. |109| Start | `univer_issue` | `list`, `get`, `create`, `update`, `comment`, `close`, or `reopen` Team Space Issues. `get` before working on one. |110| Start | `univer_worktree` | `create`, `ready`, `reopen`, `merge`, or `discard`. |111| Start | `univer_unit` | Create a draft Unit, mark one for deletion with `remove`, or undo its deletion intent with `restore`. |112| Start | `univer_import` | Import local xlsx, csv, tsv, docx, or pptx as a new Unit. |113| Write | `univer_execute` | Run version-matched Facade JavaScript against one Unit in a draft worktree. |114| Write | `univer_compile_markdown` | Create native Modern Docs or replace selected explicit blocks from session Markdown. |115| Read for editing | `univer_export_markdown` | Export selected current native Doc blocks, assets, map, and revision. |116| Write | `univer_compile_svg` | Compile workspace SVG into one explicit Slide page with browser text metrics. |117| Verify | `univer_inspect` | Read structured Unit content from trunk or one worktree. |118| Verify | `univer_lint` | Check Slide text off-page, container escape, and text overlap. |119| Verify | `univer_screenshot` | Render Sheet, Doc, Slide, Base, or Board PNG evidence and return it to an image-capable model. |120| Reference | `univer_api` | Find an unknown name, or show a known class, API, or type. |121| Reference | `univer_resources` | List/find/read/export bundled SVG resources or clear their download cache. |122| Deliver | `univer_export` | Export Sheet/Base to xlsx/csv/tsv, Doc to docx, or Slide to pptx. |123124## Facade execution125126`univer_execute` injects `univerAPI`, `api` (the same object), and one Unit-specific handle:127128- Sheet: `workbook`129- Doc: `doc`130- Slide: `presentation`131- Board: `board`132133Do not redeclare injected variables. Use `code` only for a small snippet. For multi-line or reusable Facade logic, write a workspace JavaScript body file and pass it as `codeFile`; provide exactly one of `code` or `codeFile`.134135Execution is Node ESM: `require` is unavailable, while dynamic `import()` and `Buffer` are available. For an explicit local workspace image, generate its data URI inside the execution instead of putting Base64 in the conversation:136137```js138const { readFile } = await import("node:fs/promises");139const bytes = await readFile("/absolute/session/workspace/image.png");140const imageDataUri = `data:image/png;base64,${Buffer.from(bytes).toString("base64")}`;141```142143Read only task assets inside the session workspace. Do not print or return the data URI. Resolve exact Facade methods with `univer_api`, check boolean/null returns, and retain stable IDs needed by later operations.144145## Import and export146147- Import accepts workspace files only; URL import is unavailable.148- Export Sheet or Base to `.xlsx`, `.csv`, or `.tsv`; Doc to `.docx`; Slide to `.pptx`.149- Board export is unsupported.150- Export uses an explicit Unit and an explicit trunk or worktree scope. Recalculate formulas and finish readback before exporting.151152## Unsupported CLI-only capabilities153154Do not invent equivalents for CLI maintenance, daemon/configuration, `compile-typst`, optimization, or shell command help. Use the bundled DSH tools for resources and screenshots; if the task requires another missing capability, report that exact gap.155156## Failure recovery157158Tool failures use `Error [CODE]: message`. Route recovery by the code, not free text.159160- For `GATEWAY_UNAVAILABLE` or `GATEWAY_REQUEST_TIMEOUT`, retry one `univer_status` read. After a write timeout, inspect status and content before continuing.161- For `FILE_PERMISSION_DENIED` or `SESSION_SCOPE_DENIED`, use an accessible in-workspace path or ask the user to correct access; do not retry the same path.162- For worktree or Unit state errors, refresh with `univer_status`; reopen `ready` worktrees and replace terminal ones.