Whiteboard Cli Skill

[!NOTE] Environment Dependencies: Drawing whiteboard requires

@larksuite/whiteboard-cli

(Whiteboard Node.js CLI tool) and

lark-cli

(LarkSuite CLI tool). If execution fails, install manually and retry:

npm install -g @larksuite/whiteboard-cli@^0.1.0

[!IMPORTANT] Be sure to obtain user consent before executing

npm install

to install new dependencies!

Workflow

This is a whiteboard, not a web page. Whiteboard allows free placement of elements on an infinite canvas, and flex layout is an optional enhancement.

Step 1: Routing & Knowledge Reading
  - Determine rendering path (see routing table): Mermaid or DSL?
  - Read corresponding scene guide — understand structural features and layout strategies
  - Confirm layout strategy (see quick judgment below) and construction method
  - Read references/ core modules — syntax, layout, color scheme, typesetting, connections

Step 2: Generate Complete DSL (Including Colors)
  - Plan information volume and grouping according to content.md
  - Select layout mode and spacing according to layout.md
  - Apply colors according to style.md (use default classic color palette if not specified by user)
  - Output complete JSON according to schema.md syntax
  - Refer to connectors.md for connections and typography.md for typesetting

  Note: For some graphics (fishbone/flywheel/bar/line charts, etc.), write .js scripts according to scene guide templates to generate JSON:
    - node xxx.js → output JSON file
    - Use the generated JSON file to proceed to Step 3

Step 3: Rendering & Review → Delivery
  - Self-check before rendering (see checklist below)
  - Render PNG and check:
    · Is information complete? Is layout reasonable? Is color scheme coordinated?
    · Is text not truncated? Are connections not crossing?
  - If there are issues → fix according to symptom table → re-render (max 2 rounds)
  - If serious issues remain after 2 rounds → consider using Mermaid path as fallback
  - If no issues → deliver:
    · If user requests upload to Feishu → follow instructions in "Upload to Feishu Whiteboard" section below
    · If user doesn't specify → display PNG image to user

Construction method is a strong constraint: When the scene guide requires "script generation", you must first write a script (.js) and execute it with

node

to output the JSON file. Coordinates for absolute positioning scenarios (fishbone diagrams, flywheel diagrams, bar charts, line charts, etc.) require mathematical calculation; manually writing JSON can easily lead to node overlap or connection penetration.

Rendering Path Selection (DSL or Mermaid)

1. Automatic Mermaid: Mind map, sequence diagram, class diagram, pie chart, flowchart → default to Mermaid
2. Explicit Mermaid: User input contains Mermaid syntax → use Mermaid
3. DSL Path: All other types → first read core modules, then read corresponding scene guide

scenes/mermaid.md

.mmd

Module Index

Core References (Required for DSL Path)

references/schema.md

references/content.md

references/layout.md

references/typography.md

references/connectors.md

references/style.md

Scene Guides (Read one according to type)

scenes/architecture.md

scenes/organization.md

scenes/comparison.md

scenes/fishbone.md

scenes/bar-chart.md

scenes/line-chart.md

scenes/treemap.md

scenes/funnel.md

scenes/pyramid.md

scenes/flywheel.md

scenes/milestone.md

scenes/mermaid.md

CLI Commands

npx -y @larksuite/whiteboard-cli@^0.1.0 -i my-diagram.json -o ./images/my-diagram.png        # DSL Path
npx -y @larksuite/whiteboard-cli@^0.1.0 -i diagram.mmd -o ./images/diagram.png               # Mermaid Path
npx -y @larksuite/whiteboard-cli@^0.1.0 -i skeleton.json -o ./images/step1.png -l coords.json  # Two-stage (extract coordinates)

Upload requires Feishu authentication. When encountering authentication or permission errors, read

../lark-shared/SKILL.md

to learn about login and permission handling.

XXX

lark-cli docs +fetch --doc <URL> --as user

<whiteboard token=”XXX”/>

lark-cli docs +update --doc <doc_id> --mode append --markdown '<whiteboard type=”blank”></whiteboard>' --as user

data.board_tokens[0]

../lark-doc/SKILL.md

[!CAUTION] MANDATORY PRE-FLIGHT CHECK When you want to write content to an existing whiteboard Token, never execute the upload command directly! You must strictly follow these two steps: Enforce Dry Run (Status Detection) You must first add

--overwrite --dry-run

parameters to the command to detect the current state of the whiteboard. Example command:

bash

npx -y @larksuite/whiteboard-cli@^0.1.0 --to openapi -i <input file> --format json | lark-cli docs +whiteboard-update --whiteboard-token <Token> --overwrite --dry-run --as user

Parse Results and Intercept

• Carefully read the Dry Run output logs.
• If the log contains

  XX whiteboard nodes will be deleted

  : This means the whiteboard is not empty, and the current operation will overwrite and destroy the user's original chart!
• You must stop the operation immediately, and confirm with the user via the

  AskUserQuestion

  tool (or directly reply): "The target whiteboard is currently not empty. Continuing the update will clear the original XX nodes. Are you sure you want to overwrite?"
• Only after the user explicitly authorizes "agree to overwrite" can you remove

  --dry-run

  and execute the upload.
• The user may request you to update the whiteboard content without overwriting; in this case, remove the

  --overwrite

  and

  --dry-run

  parameters before uploading.

npx -y @larksuite/whiteboard-cli@^0.1.0 --to openapi -i <input file> --format json | lark-cli docs +whiteboard-update --whiteboard-token <Whiteboard Token> --yes --as user

Once uploaded, the whiteboard cannot be modified. To upload as an application identity, replace

--as user

with

--as bot

. If the whiteboard is not empty, first add

--overwrite --dry-run

to check the number of nodes to be deleted, confirm with the user, then remove

--dry-run

to execute.

Pre-Rendering Self-Check

• Different groups use different colors? Nodes in the same group have exactly the same style?
• Light outer background, white inner nodes? (Heavy outer, light inner)
• All nodes have borders (borderWidth=2)? Text is clearly readable on the background?
• Connections use gray (#BBBFC4), not colored?
• All frames have layout attribute? gap and padding are explicitly set?
• Height of text-containing nodes uses fit-content? connector is in top-level nodes array?

Key Constraint Quick Reference

Most frequently violated rules that must be followed even without reading sub-module files.

1. Height of text-containing nodes must use

   'fit-content'

   — hardcoding values will truncate text

2. fill-container

   only takes effect in flex parent containers — width degenerates to 0 under

   layout: 'none'

3. connector must be placed in the top-level nodes array — cannot be nested in frame children
4. Layer order — array order = drawing order. Later-defined elements have higher layers and will cover earlier-defined ones. Overlapping/floating/annotation elements must be placed at the end of the array.
5. x/y in flex containers are completely ignored — use

   layout: 'none'

   or place in top-level nodes for free positioning

{ "type": "frame", "layout": "vertical", "children": [
  { "type": "rect", "x": 100, "y": 0, "text": "Chengdu" },
  { "type": "rect", "x": 540, "y": 0, "text": "Kangding" }
]}

layout: "none"