Univer Board Units
Load univer first. Use an explicit draft worktree for writes and retain the Board unitId returned by univer_unit. The Board is a remote Workspace Unit; Resource and Node IDs are not content Unit IDs.
Use native editable Board elements to express the user's intent. Choose shape types, layout, spacing, colors, and emphasis for the actual content; examples are not templates that every Board must follow.
Start with the task
- Inspect an existing Board before editing; preserve unrelated content and deliberate manual layout.
- For a new relationship-heavy diagram, draft a compact BoardSpec to preserve meaning before choosing geometry. Translate it through Facade APIs; it is not an SDK input or another persisted model.
- Direct edits, standalone charts, images, sticky notes, and freehand work can call their dedicated APIs without a spec. Do not invent graph relations just to use one.
- Read only the relevant reference below through
univer_skill_resource, withskill: "univer-board"and its listedpath(for examplereferences/board-spec.md). These are bundled resource identifiers, not session or installation paths; no Shell/file-reading tool is needed.
| Task | Read when needed |
|---|---|
| Relationship planning, semantic IDs and nesting | BoardSpec |
| Flowcharts, activity lanes, fork/join, composite states | Flow and state |
| Lifelines, activation bars, messages and fragments | Sequence |
| Class/ER compartments, relation ends and cardinalities | Class and ER |
| Use cases, component interfaces, deployment/package nesting | Structural UML |
| Mind maps, trees, timelines and family selection | Mind maps |
| Tables, charts, images, sticky notes, resources, embeds and Ink | Content selection |
| Endpoint selection, routing diagnostics or animation | Connector routing |
| Multiple texts, label sizing, wrapping or placement | Connector labels |
| Explicit multi-profile coverage or UI regression testing | Diagram review |
The profile narrows the search, not the design. Mix native primitives where the intent warrants it; no fixed node size, layout direction, color palette, or animation count is required.
Work through the installed API
Create a Board with univer_unit only when a new Unit is needed. Use univer_inspect with its unitId and unitType: "board"
for a read-only overview. For selected elements, use univer_edit with mode: "read" and
board.describeElements() or board.getElements(); this inspect tool has no elementIds parameter.
Discover existing IDs before editing.
Use univer_api with find / show to query only the Facade methods/types needed for the next operation.
univer_execute predefines univerAPI, api, and the selected FBoard as board; do not redeclare them. The installed
SDK is authoritative: before a large batch, probe selected runtime methods/enums in a read-only call if their
availability is uncertain. An indexed type alone does not establish runtime support. Do not invent parameters or
upgrade dependencies to match a reference; report unavailable capabilities or explain a semantics-preserving fallback.
Run this code through univer_execute with unitType: "board", the Board unitId, and its draft worktreeId:
const shape = board.insertShape({
shapeType: api.Enum.ShapeTypeEnum.RoundRect,
transform: { left: 80, top: 80, width: 180, height: 100 },
});
if (!shape) throw new Error("Cannot insert Board shape");
shape.getText().setText("Review");
return { shapeId: shape.getId(), elements: board.describeElements() };
insertShape takes geometry in transform, visual properties in shapeData, and text through the returned
live handle—not top-level id, coordinates, or text. Retain generated IDs and map semantic IDs to them.
Await asynchronous operations according to their installed signatures before dependent calls or readback.
Ordinary shapes keep a fixed stroke width when resized. Use the stock outline for native symbols.
Set strokeReferenceSize only when an authored icon needs a proportional outline. See
shape outline scaling for the Facade fields.
Create and arrange nodes before their connectors. Use element-bound endpoints; for ordinary automatic connections,
start with fromElementId / toElementId and omit sides/routing overrides. Introduce explicit ports or routes for
diagram semantics or a diagnosed layout problem, not guessed pixel endpoints. Native map branches belong to their
layout owner. Sequence messages need the lifeline/activation rules in their reference.
Create known parents before children. Direct insertion into a parent uses parent-local coordinates;
insertShapeAtPoint() resolves a Board-world top-left point. Read back parentId, laneId and world bounds:
a shape drawn inside a box is not necessarily its child.
Choose an explicit layout plan
Check the installed tool schema for univer_lint.layoutPlan and the installed API reference for
FBoard.planLayout and FBoard.applyLayoutPlan. For example, call univer_lint with the draft Unit and Worktree,
unitType: "board", mode: "rendered", and layoutPlan: { mode: "routes", connectorIds: ["edge-a", "edge-b"] }.
Use graph for a new ordinary diagram whose nodes may move. Use routes to coordinate paths while keeping frames
and ports, ports for automatic endpoint positions, labels for caption placement, or text for measured frame
growth. Pass generated IDs for the active page. Human editing uses individual routes. Native structured layout
owners and authored geometry remain authoritative.
Read analyses[].plan from the lint report, including the report attached to a lint failure. The plan is read-only
and needs a render runtime with fonts ready. Apply a ready, non-empty plan in the draft through
board.applyLayoutPlan(plan) after checking the page ID. If the call returns false, obtain a fresh plan.
For an incomplete plan, resolve the reported IDs, ownership, resource or spacing constraint before retrying.
Capture a fresh screenshot and lint again. If the installed tool lacks the option, use its documented supported
planning capabilities and report any mode that is unavailable.
Verify in proportion to the change
For a generated diagram, follow intent → spec when useful → layout decisions → Facade calls → check → targeted repair:
- Read back persisted elements/text, ownership and bindings with
describeElements(),getElements(), oruniver_editwithmode: "read". Check the requested meaning, not only counts. - Run
univer_lintwithunitType: "board"andmode: "model"for a browser-free model check; finish withmode: "both"(the default) and a fulluniver_screenshot. Inspect the report'sstatus,coverage, rawanalyses, the image and each image'smetadata.layoutAnalysis.incompleteis a blocker to claiming clean layout; model checks cannot establish final font metrics or automatic routes. - Repair implicated elements and recapture. Use routing or label guidance for their diagnostics. Never silently discard semantics to pass.
- Hand off an overview and any needed readable details. Distinguish clean results, visually reviewed diagnostic exceptions, and blockers; command success alone is not visual verification.
For automatic crossings, excessive detours or distant automatic captions, inspect the installed univer_lint
schema for includePortPlan. When supported,
request includePortPlan: true with unitType: "board" and mode: "both" on the intended Worktree.
Read analyses[].portPlan and the unchanged original findings. Apply only one ready non-empty plan through
FBoard.applyLayoutPlan on the same current page; then lint a fresh snapshot before requesting label repairs.
For a distance finding, also request maximumAutomaticLabelDistance: 12 when supported. An empty plan does not
resolve the finding; report ineligible ownership or missing support rather than forcing ports to automatic.
Missing/incomplete planning remains incomplete. Preserve authored ports/routes, node frames and native ownership.
See port and label repair and review arrowheads in screenshots.
For new ordinary generated shapes, inspect the installed univer_lint tool schema first. Only when it
exposes textPlanElementIds, request that explicit generated selection in rendered/both mode, retain
analyses[].textPlan, and apply a ready current plan through the Facade. Report missing support instead of
sending unsupported arguments or guessing ordinary shape heights. Replan, fit and remeasure; preserve
all text, fonts and authored/native ownership. See the native text sizing procedure.
If the installed schema also exposes textPlanMaximumWidthGrowth, use it with textPlanElementIds to bound
horizontal growth from 1 to 2; 1 keeps the original width. For long or bilingual generated text, start with 1.25
and adjust using complete coverage and screenshots. Preserve complete text, fonts and incomplete findings;
never send the option to an unsupported version or fall back to guessed dimensions.
For a localized edit, inspect the changed region and affected relationships; do not regenerate the Board or run an unrelated profile matrix. Full drag/menu/Undo/Redo testing belongs to explicit interaction or coverage requests, not every authoring task. A static screenshot does not prove UI behavior.
For an explicit automatic-label proximity check, call univer_lint with unitType: "board",
mode: "rendered" or "both", and maximumAutomaticLabelDistance: 12. The opt-in value must be finite and
non-negative; zero is valid. Missing native support or unresolved distance makes coverage incomplete, and
exceeded limits are errors. Preserve fixed/authored and endpoint-role labels. Read native receipt/status and
screenshots; this sampled, marker-trimmed stroke-centerline metric is not raster ink and never repairs labels.
For measured label repair, call univer_lint with unitType: "board", mode: "both" and
includeLabelPlan: true. The check remains read-only. An empty patches array needs no write.
For a non-empty plan, check that analyses[].labelPlan is ready and
plan.pageId === board.getData().activePageId, then pass that exact plan to board.applyLayoutPlan(plan)
through univer_execute on the same Worktree/Unit/current page. Report other-page plans as unapplied; use only an
installed, supported page-selection API if one is available. Check the boolean result. A stale rejection requires a fresh lint; an incomplete or
unavailable plan requires resolving its diagnostics. Lint and screenshot again after application.
For endpoint constraints or label-layout/no-free-position, follow the label spacing repair:
keep the same selection, fixed elements and direction, increase graph layerGap for movable nodes with automatic
endpoints, then obtain a fresh rendered label plan. Preserve manual/native constraints and report any remaining incomplete result.
Call univer_screenshot with unitType: "board", the selected unitId, worktreeId, and an authorized workspace output
directory. Use the DSH live Board preview for requested interaction or animation checks. Follow the
univer ready/status handoff; merge and discard remain user-authorized. Board Office export is unsupported.