lark-whiteboard（云雀白板）

whiteboard (v1)

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理

核心概念

画板 Token

画板 token 是画板的唯一标识符。飞书画板嵌入在云文档中，可以从云文档的 docs +fetch 结果中获取（<whiteboard token="xxx"/> 标签），或从 docs +update 新建画板后的 data.board_tokens 字段中获取。

快速决策

当需要插入图表时：

1. 能否使用飞书画板？

- 能 → 走画板路径（推荐！可编辑、可协作） - 不能 → 走图片路径

Shortcuts

Workflow

场景 1: 创作一个画板

1. 确定需要创作的画板 Token（从用户请求或对应的文档中获取）与要创作的内容
2. 参考 lark-whiteboard-cli 生成画板内容
3. 使用 +update shortcut 更新画板内容

场景 2: 修改或优化一个画板

1. 确定要修改的画板 Token （从用户请求或对应的文档中获取）
2. 使用 +query --output_as code shortcut 导出画板代码，确认画板是否由 Mermaid 或 PlantUML 绘制

1. 如果 +query --output_as code 返回了 Mermaid / PlantUML 代码块，则在这一代码的基础上优化修改 2. 如果没有返回代码块，则使用 +query --output_as image 获取画板预览图片，根据图片内容参考 lark-whiteboard-cli 重绘优化 3. 如果用户只需要简单修改某个节点的文本内容/颜色，可以使用 +query --output_as raw shortcut 导出画板原生 OpenAPI 格式，并在此基础上修改。 4. 如果用户有明确要求，则以用户要求优先。

1. 使用 +update shortcut 创建新的画板内容。根据用户需求，你可能会需要使用 docs +update 创建新的画板，或使用 +update --overwrite 在原画板上覆盖式更新。

与 lark-doc 的配合使用

场景 1: 从文档中获取画板 token

1. 使用 lark-doc 的 +fetch 获取文档内容
2. 从返回的 markdown 中解析 <whiteboard token="xxx"/> 标签，记录画板 token
3. 使用本 skill 的 +query 或 +update 读取或操作画板

场景 2: 新建画板并编辑（完整流程）

这是最常见的使用场景，必须完整执行以下步骤：

1. 使用 lark-doc 的 +update 创建空白画板

- 在 markdown 中传入 <whiteboard type="blank"></whiteboard> - 注意这一 XML 标签不要转义 - 需要多个画板时，重复多个 whiteboard 标签

1. 从响应的 data.board_tokens 中获取新建画板的 token 列表

- 记录每个 token 对应的图表类型和位置

1. 根据文档主题，为每个画板设计相应的内容

- 参考下方"常见图表模板与参考指南"选择合适的语法 - 使用 Mermaid（推荐）、PlantUML 或 lark-whiteboard-cli 生成内容

1. 逐个更新画板：使用本 skill 的 +update shortcut 编辑每个画板的内容

- 不要遗漏任何一个画板 token - 确保每个画板都有实际内容，不是空白

常见图表模板与参考指南