lark-whiteboard

Files (19)

• SKILL.md
• connectors.md · references/
• content.md · references/
• layout.md · references/
• schema.md · references/
• style.md · references/
• typography.md · references/
• architecture.md · scenes/
• bar-chart.md · scenes/
• comparison.md · scenes/
• fishbone.md · scenes/
• flywheel.md · scenes/
• funnel.md · scenes/
• line-chart.md · scenes/
• mermaid.md · scenes/
• milestone.md · scenes/
• organization.md · scenes/
• pyramid.md · scenes/
• treemap.md · scenes/

SKILL.md (first lines)

# Whiteboard Cli Skill

> [!NOTE]
> **环境依赖**：绘制画板需要 `@larksuite/whiteboard-cli`（画板 Node.js CLI 工具），以及 `lark-cli`（LarkSuite CLI 工具）。
> 如果执行失败，手动安装后重试：`npm install -g @larksuite/whiteboard-cli@^0.1.0`

> [!IMPORTANT]
> 执行 `npm install` 安装新的依赖前，务必征得用户同意！


## Workflow

> **这是画板，不是网页。** 画板是无限画布上自由放置元素，flex 布局是可选增强。

```
Step 1: 路由 & 读取知识
  - 判断渲染路径（见路由表）：Mermaid 还是 DSL？
  - 读对应 scene 指南 — 了解结构特征和布局策略
  - 确定布局策略（见下方快速判断）和构建方式
  - 读 references/ 核心模块 — 语法、布局、配色、排版、连线

Step 2: 生成完整 DSL（含颜色）
  - 按 content.md 规划信息量和分组
  - 按 layout.md 选择布局模式和间距
  - 按 style.md 上色（用户没指定时用默认经典色板）
  - 按 schema.md 语法输出完整 JSON
  - 连线参考 connectors.md，排版参考 typography.md

  注意：部分图形（鱼骨/飞轮/柱状/折线等）等, 要按 scene 指南的脚本模板写 .js 脚本生成 JSON：
    - node xxx.js → 产出 JSON 文件
    - 用产出的 JSON 文件进入 Step 3

Step 3: 渲染 & 审查 → 交付
  - 渲染前自查（见下方检查清单）
  - 渲染 PNG，检查：
    · 信息完整？布局合理？配色协调？
    · 文字无截断？连线无交叉？
  - 有问题 → 按症状表修复 → 重新渲染（最多 2 轮）
  - 2 轮后仍有严重问题 → 考虑走 Mermaid 路径兜底
  - 没问题 → 交付：
    · 用户要求上传飞书 → 见下方”上传飞书画板”章节中的说明
    · 用户未指定 → 展示 PNG 图片给用户
```

**布局策略快速判断**（详见 layout.md）：

| 判断条件 | 布局策略 | 构建方式 |
|----------|----------|----------|
| 有明确上下层级（用户层→服务层→数据层） | Flex 分层 | 直接写 JSON |
| 空间位置承载信息（地理、拓扑、角度） | 纯绝对定位 | 写脚本算坐标（node xxx.js） |
| 多个独立模块平级互联 | 混合（岛屿式） | 直接写 JSON + 估高辅助 |
| 不确定 | 默认 Flex（最安全） | 直接写 JSON |

> **构建方式是强约束**：当 scene 指南要求"脚本生成"时，必须先写脚本（.js）并用 `node` 执行来产出 JSON 文件。绝对定位场景（鱼骨图、飞轮图、柱状图、折线图等）的坐标需要数学计算，直接手写 JSON 极易导致节点重叠或连线穿模。

---

## 渲染路径选择（DSL or Mermaid）

| 图表类型 | 路径 | 理由 |
|----------|------|------|
| 思维导图 | **Mermaid** | 辐射结构自动布局 |
| 时序图 | **Mermaid** | 参与方+消息自动排列 |
| 类图 | **Mermaid** | 类关系自动布局 |
| 饼图 | **Mermaid** | Mermaid 原生支持 |
| 流程图 | **Mermaid** | 通过 Mermaid 语法稳定生成结构 |
| 其他所有类型 | **DSL** | 精确控制样式和布局 |

**路由规则**：
1. **自动 Mermaid**：思维导图、时序图、类图、饼图、流程图 → 默认走 Mermaid
2. **显式 Mermaid**：用户输入包含 Mermaid 语法 → 走 Mermaid
3. **DSL 路径**：其他所有类型 → 先读核心模块，再读对应场景指南

**Mermaid 路径**：参考 `scenes/mermaid.md` 编写 `.mmd` 文件，跳过 DSL 模块。
**DSL 路径**：按 Workflow 3 步执行。

---

## 模块索引

### 核心参考（DSL 路径必读）

| 模块 | 文件 | 说明 |
|------|------|------|
| DSL 语法 | `references/schema.md` | 节点类型、属性、尺寸值 |
| 内容规划 | `references/content.md` | 信息提取、密度决策、连线预判 |
| 布局系统 | `references/layout.md` | 网格方法论、Flex 映射、间距规则 |
| 排版规则 | `references/typography.md` | 字号层级、对齐、行距 |
| 连线系统 | `references/connectors.md` | 拓扑规划、锚点选择 |
| 配色系统 | `references/style.md` | 多色板、视觉层级 |


### 场景指南（按类型选读一个）

| 图表类型 | 文件 | 适用场景 |
|----------|------|----------|
| 架构图 | `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` | 时间线、版本演进 |
| Mermaid | `scenes/mermaid.md` | 思维导图、时序图、类图、饼图、流程图 |

---

## CLI 命令

**渲染**：
```bash
npx -y @larksuite/whiteboard-cli@^0.1.0 -i my-diagram.json -o ./images/my-diagram.png        # DSL 路径
npx -y @larksuite/whiteboard-cli@^0.1.0 -i diagram.mmd -o ./images/diagram.png               # Mermaid 路径
npx -y @larksuite/whiteboard-cli@^0.1.0 -i skeleton.json -o ./images/step1.png -l coords.json  # 两阶段（提取坐标）
```

From eastreams/loong, MIT.

More from eastreams/loong