lark-whiteboard

[!IMPORTANT]

• Run lark-cli --version to confirm availability, no need to ask the user.
• Run npx -y @larksuite/whiteboard-cli@^0.2.11 -v to confirm availability, no need to ask the user.

CRITICAL, Before starting, you MUST use the Read tool to read ../lark-shared/SKILL.md, which contains authentication and permission handling.

---

Quick Decision

Shortcuts

---

Creation Workflow

This workflow is used for creating a whiteboard independently. When creating multiple whiteboards in batches within a document, lark-doc is responsible for scheduling. See references/lark-doc-whiteboard.md in the lark-doc skill.

Step 1: Get board_token

Step 2: Render & Write

→ Proceed to the § Render & Write Whiteboard section, and return the result to the user directly after completing the process.

---

Modification Workflow

Step 1: Get board_token (Same as Creation Workflow Step 1)

Step 2: Determine modification strategy

+query --output_as code
  ├─ Returns Mermaid/PlantUML code
  │   → Modify the original code → +update --input_format mermaid/plantuml
  ├─ No code (Whiteboard drawn via DSL or other methods)
  │   ├─ Only change text/color → +query --output_as raw → Manually edit JSON → +update --input_format raw
  │   └─ Redraw/Structural adjustment → +query --output_as image → View image then proceed to [§ Render & Write Whiteboard]
  └─ User has explicit requirements → Prioritize user requirements

---

Render & Write Whiteboard

Rendering Routing

State your identity first: Based on the training source, which family do you belong to? Claude / Gemini / GPT / GLM / Doubao or Seed / Other. Your identity determines the SVG / DSL routing (different families have uneven capabilities for these two expression languages), do not skip this step.

Then select the path based on chart type × identity, read the corresponding file and execute according to its complete workflow (including reading scene guides, generating content, rendering review, and delivery):

⚠️ SVG path failure fallback: When following routes/svg.md, if one of the following occurs → Discard current SVG, switch to reading routes/dsl.md and redraw from scratch, do not patch line by line:

• Rendering command throws an error directly (syntax-level crash, not a --check warn/error)
• Two rounds of rewriting still fail to eliminate the --check text-overflow error
• Visual inspection shows severe PNG distortion (large areas of text overflow, elements overlapping and obscuring key information, overall layout collapse)

SVG source patching often introduces new bugs, switching to DSL and redrawing from scratch is usually more stable. This is a hard fallback for SVG path freedom, do not intrude into the creation process of routes/svg.md.

Artifact Specifications

Artifact directory: ./diagrams/YYYY-MM-DDTHHMMSS/ (local time, without colons or timezone suffix). If the user specifies a path, follow the user's preference.

Fixed filenames within the directory:

diagram.svg           ← SVG source (SVG path)
diagram.mmd           ← Mermaid source (Mermaid path)
diagram.json          ← DSL source file (DSL path) / OpenAPI JSON (exported from diagram.svg for SVG path)
diagram.gen.cjs       ← Coordinate calculation script (only for DSL script construction method)
diagram.png           ← Rendering result

Write to Whiteboard

Regarding --overwrite In the whiteboard update command, if the --overwrite flag is not included, it performs an incremental update. If the whiteboard already contains content, the new content might overlap with existing content, causing issues. Therefore, if you need to update the entire whiteboard content, you must include the --overwrite flag for an overwrite update.

npx -y @larksuite/whiteboard-cli@^0.2.11 -i <artifact file> --to openapi --format json \
  | lark-cli whiteboard +update \
    --whiteboard-token <Token> \
    --source - --input_format raw \
    --idempotent-token <10+ character unique string> \
    --as user \
    --overwrite

--idempotent-token must be at least 10 characters. It is recommended to use a timestamp + identifier (e.g., 1744800000-board-1) to avoid duplicate writes due to retries. If you need to upload with bot identity, replace --as user with --as bot.