github/larksuite-cli
1
0
Fork 0
mirror of https://github.com/larksuite/cli.git synced 2026-07-07 09:11:44 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor(skills): introduce lark-doc-whiteboard.md and streamline whiteboard workflow (#502)

Browse Source 
- add lark-doc/references/lark-doc-whiteboard.md: defines role boundaries
  between lark-doc and lark-whiteboard, step-by-step doc↔whiteboard
  coordination flow, and semantic-to-chart-type mapping table
- lark-doc-create.md: tighten post-create whiteboard flow (step 2 now
  directly references the "渲染 & 写入画板" section); strengthen 主动画板
  guideline with explicit placeholder syntax, prohibition on PNG/SVG
  substitution, and concrete routing examples
- lark-whiteboard/SKILL.md: upgrade to v0.2, rewrite with structured
  quick-decision table, creation/modification workflows, render routing
  table, and dry-run write guard
- extract rendering routes into routes/{dsl,mermaid,svg}.md; add
  per-chart scene guides under scenes/
- remove lark-whiteboard-cli/SKILL.md (absorbed into lark-whiteboard)
This commit is contained in:
zkh-bytedance
2026-04-17 17:51:50 +08:00
committed by GitHub
parent 1ad7cfab5b
commit 830fb3bbe5
31 changed files with 442 additions and 443 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
skills/lark-doc/SKILL.md
View File

@@ -97,31 +97,19 @@ Drive Folder (云空间文件夹)
└── file_token (直接使用)
```
## 重要说明：画板编辑
> **⚠️ lark-doc skill 不能直接编辑已有画板内容，但 `docs +update` 可以新建空白画板**
### 场景 1：已通过 docs +fetch 获取到文档内容和画板 token
如果用户已经通过 `docs +fetch` 拉取了文档内容，并且文档中已有画板（返回的 markdown 中包含 `<whiteboard token="xxx"/>` 标签），请引导用户：
1. 记录画板的 token
2. 查看 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md) 了解如何编辑画板内容
### 场景 2：刚创建画板，需要编辑
如果用户刚通过 `docs +update` 创建了空白画板，需要编辑时：
**步骤 1：按空白画板语法创建**
- 在 `--markdown` 中直接传 `<whiteboard type="blank"></whiteboard>`
- 需要多个空白画板时，在同一个 `--markdown` 里重复多个 whiteboard 标签
**步骤 2：从响应中记录 token**
- `docs +update` 成功后，读取响应字段 `data.board_tokens`
- `data.board_tokens` 是新建画板的 token 列表，后续编辑直接使用这里的 token
**步骤 3：引导编辑**
- 记录需要编辑的画板 token
- 查看 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md) 了解如何编辑画板内容
### 注意事项
- 已有画板内容无法通过 lark-doc 的 `docs +update` 直接编辑
- 编辑画板需要使用专门的 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md)
## 绘图需求识别与挖掘
## 文档可视化建议
> **💡 在撰写文档时，当需要表达较为复杂的时序、架构层次、逻辑关系、数据流程等内容时，建议使用画板绘制可视化图表以显著提升文档的可阅读性。**
>
> 请参考 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md) 了解如何绘制画板内容。
用户很少主动提"画板"——**默认**使用飞书画板承载图表，命中以下任一信号即触发：
- 用户提到图表类型：架构图、流程图、时序图、组织图、路线图、对比图、鱼骨图、飞轮图、思维导图等
- 用户表达可视化意图：画一下、梳理关系、画个流程、给我一个图、方便汇报等
- 文档主题涉及结构关系、流程走向、时间线、数据对比
以下场景不加图：用户明确拒绝、合同/法律条款/合规声明等严谨连续文本、原样转录任务。
> [!CAUTION]
> 命中后，**MUST** 先读取 [`references/lark-doc-whiteboard.md`](references/lark-doc-whiteboard.md) 并**严格按其流程执行**。
>
> **绝对禁止**用 `whiteboard-cli` 渲染 PNG 后通过 `docs +media-insert` 插入文档——图表必须通过 `lark-cli whiteboard +update` 写入画板 block，这是唯一合法路径。
## 快速决策
- 用户说“看一下文档里的图片/附件/素材”“预览素材”，优先用 `lark-cli docs +media-preview`。
@@ -132,45 +120,6 @@ Drive Folder (云空间文件夹)
- 拿到 spreadsheet URL / token 后，再切到 `lark-sheets` 做对象内部读取、筛选、写入等操作。
- 用户说“给文档加评论”“查看评论”“回复评论”“给评论加表情 / reaction”“删除评论表情 / reaction”，**不要留在 `lark-doc`**，直接切到 `lark-drive` 处理。
## 画板需求挖掘（主动识别）
> **用户很少主动提"画板"。创建文档时应主动识别适合可视化的内容，用画板呈现。**
### 🔴 关键要求（必须遵守）
**创建空白画板 ≠ 完成任务**。创建空白画板后，**必须继续使用 lark-whiteboard 技能填充实际内容**。
### 语义与画板类型映射
创建/编辑文档时，文档主题涉及以下语义，应**主动**创建画板，无需用户指定：
| 语义 | 画板类型 | 参考指南 |
|---------------|-------|---------------------------------------------------------------------------------------------|
| 架构/分层/技术方案 | 架构图 | [lark-whiteboard-cli/scenes/architecture.md](../lark-whiteboard-cli/scenes/architecture.md) |
| 流程/审批/部署/业务流转 | 流程图 | [lark-whiteboard-cli/scenes/flowchart.md](../lark-whiteboard-cli/scenes/flowchart.md) |
| 组织/层级/汇报关系 | 组织架构图 | [lark-whiteboard-cli/scenes/organization.md](../lark-whiteboard-cli/scenes/organization.md) |
| 时间线/里程碑/版本规划 | 里程碑图 | [lark-whiteboard-cli/scenes/milestone.md](../lark-whiteboard-cli/scenes/milestone.md) |
| 因果/复盘/根因分析 | 鱼骨图 | [lark-whiteboard-cli/scenes/fishbone.md](../lark-whiteboard-cli/scenes/fishbone.md) |
| 方案对比/技术选型 | 对比图 | [lark-whiteboard-cli/scenes/comparison.md](../lark-whiteboard-cli/scenes/comparison.md) |
| 循环/飞轮/闭环 | 飞轮图 | [lark-whiteboard-cli/scenes/flywheel.md](../lark-whiteboard-cli/scenes/flywheel.md) |
| 层级占比/能力模型 | 金字塔图 | [lark-whiteboard-cli/scenes/pyramid.md](../lark-whiteboard-cli/scenes/pyramid.md) |
| 模块依赖/调用关系 | 架构图 | [lark-whiteboard-cli/scenes/architecture.md](../lark-whiteboard-cli/scenes/architecture.md) |
| 分类梳理/知识体系 | 思维导图 | [lark-whiteboard-cli/scenes/mermaid.md](../lark-whiteboard-cli/scenes/mermaid.md) |
| 数据分布/占比 | 饼图 | [lark-whiteboard-cli/scenes/mermaid.md](../lark-whiteboard-cli/scenes/mermaid.md) |
创建画板前，务必先阅读 [`lark-whiteboard-cli`](../lark-whiteboard-cli/SKILL.md) 和 [`lark-whiteboard`](../lark-whiteboard/SKILL.md) 这两个 Skill，了解画板的创建流程。
### 完整执行流程（必须完整执行）
1. **创建空白画板占位**：创建场景用 `docs +create`、编辑场景用 `docs +update` 插入空白画板
2. **获取画板 token**：从 `docs +update` 响应的 `data.board_tokens` 获取画板 token 列表
3. **填充画板内容**：切换到 [`lark-whiteboard-cli`](../lark-whiteboard-cli/SKILL.md) 创建画板内容，并填入画板
4. **验证完成**：确认所有画板都有实际内容，不是空白
**不适用**：纯文字记录（日志/备忘）、数据密集型内容（用表格）、用户明确只要文字。
> ⚠️ **警告**：如果只创建空白画板而不填充内容，任务将被视为未完成！
## 补充说明
`docs +search` 除了搜索文档 / Wiki，也承担“先定位云空间对象，再切回对应业务 skill 操作”的资源发现入口角色；当用户口头说“表格 / 报表”时，也优先从这里开始。
@@ -186,4 +135,4 @@ Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）
| [`+update`](references/lark-doc-update.md) | Update a Lark document |
| [`+media-insert`](references/lark-doc-media-insert.md) | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback) |
| [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) |
| [`+whiteboard-update`](references/lark-doc-whiteboard-update.md) | Update an existing whiteboard in lark document with whiteboard dsl. Such DSL input from stdin. refer to lark-whiteboard skill for more details. |
| [`+whiteboard-update`](../lark-whiteboard/references/lark-whiteboard-update.md) | Alias of `whiteboard +update`. Update an existing whiteboard with DSL, Mermaid or PlantUML. Prefer `whiteboard +update`; refer to lark-whiteboard skill for details. |

9
skills/lark-doc/references/lark-doc-create.md
View File

@@ -57,9 +57,8 @@ lark-cli docs +create --title "学习笔记" --wiki-space my_library --markdown
如果文档中包含空白画板（`<whiteboard type="blank"></whiteboard>`），**必须继续以下步骤**：
1. 从返回值的 `data.board_tokens` 字段记录所有新建画板的 token
2. 立即切换到 [`lark-whiteboard`](../lark-whiteboard/SKILL.md) 技能
3. 使用 `whiteboard +update` 命令为每个画板填充实际内容（Mermaid/PlantUML/DSL）
4. 确认所有画板都有实际内容后，任务才算完成
2. 读取 `../../lark-whiteboard/SKILL.md`，跳至"渲染 & 写入画板"章节，为每个 board_token 生成并写入实际内容
3. 确认所有画板都有实际内容后，任务才算完成
**仅创建空白画板是不够的！** 如果只创建空白画板而不填充内容，任务将被视为未完成。
@@ -85,7 +84,7 @@ lark-cli docs +create --title "学习笔记" --wiki-space my_library --markdown
- **视觉节奏**：用分割线、分栏、表格打破大段纯文字
- **图文交融**：流程、架构或草图需要可视化时，优先使用图片、表格或空白画板
- **克制留白**：Callout 不过度、加粗只强调核心词
- **主动画板**：文档涉及架构、流程、组织、时间线、因果等逻辑关系时，主动插入空白画板，后续用 lark-whiteboard 填充；但若用户明确要求仅文本或内容更适合表格，则不插入。详见 [画板需求挖掘](../SKILL.md#画板需求挖掘主动识别)
- **主动画板**：文档涉及架构、流程、组织、时间线、因果等逻辑关系时，**必须**在 markdown 对应章节的文字内容之后插入 `<whiteboard type="blank"></whiteboard>` 占位，每个图表对应一个标签。**禁止**用 `whiteboard-cli` 渲染的 PNG/SVG 图片替代画板。创建完成后从返回值 `data.board_tokens` 取 token，读取 `../../lark-whiteboard/SKILL.md` 的"渲染 & 写入画板"章节为每个 token 写入图表内容。例：文档含"系统整体架构""分层架构""部署架构"各需插入一个画板，"类图"也需插入一个画板（走 Mermaid 路由）。
当用户有明确的样式、风格需求时，应当以用户的需求为准！
@@ -450,7 +449,7 @@ lark-cli docs +create --title "空白画板示例" --markdown '<whiteboard type=
**重要说明**：
- 创建空白画板时，直接使用 `<whiteboard type="blank"></whiteboard>`
- 读取时只能获取 token，可通过 media-download 查看内容，无法直接读出画板内部内容
- 画板编辑：详见 [SKILL.md](../SKILL.md#重要说明画板编辑)
- 画板编辑：详见 [../../lark-whiteboard/SKILL.md](../../lark-whiteboard/SKILL.md)
### 多维表格（Base）

6
skills/lark-doc/references/lark-doc-whiteboard-update.md
View File

@@ -1,6 +0,0 @@
# docs +whiteboard-update（更新飞书画板）
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
本 shortcut 仅为兼容历史调用保留，具体使用方式请参考 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)

66
skills/lark-doc/references/lark-doc-whiteboard.md Normal file
View File

@@ -0,0 +1,66 @@
# lark-doc 画板处理指南
> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
## 两个 Skill 的职责边界
| Skill | 核心职责 | 约束 |
|------|------|------|
| `lark-doc` | 文档内容读取/更新、插入空白画板占位、获取 board_token | 不能直接编辑画板内容；`docs +update` 的画板能力仅限插入空白占位 |
| `lark-whiteboard` | 查询/导出画板（+query）；图表内容生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入画板（+update） | 图表内容生成由此 skill 完整执行，不依赖外部调度 |
## 文档与画板协同流程
### 步骤 1：判断场景
| 场景 | 入口 |
|------|------|
| 文档中需要插入新画板 | 继续步骤 2 |
| 已有画板需要更新内容 | 先 `docs +fetch` 获取 `board_token`，跳至步骤 3 |
| 只查看 / 下载已有画板 | 切换至 `lark-whiteboard`，不走本流程 |
### 步骤 2：在文档中创建空白画板
- 创建场景：`docs +create`；编辑场景：`docs +update`
- markdown 中使用 `<whiteboard type="blank"></whiteboard>`（不要转义）
- 多个画板时，在相应的地方插入各自的 whiteboard 标签
- 从响应的 `data.board_tokens` 中读取 token 列表
### 步骤 3：生成并写入画板内容
读取 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)，跳至"渲染 & 写入画板"章节，按其完整流程为每个 board_token 生成并写入图表内容。
多个画板时依次处理，每个画板完成后再处理下一个。
### 步骤 4：完成校验
- 确认每个 token 对应的画板都已填充真实内容
- 不保留空白占位画板；只有空白画板而无内容视为任务未完成
---
## 语义与画板类型映射
| 语义 | 画板类型 |
|------|------|
| 架构/分层/技术方案/模块依赖/调用关系 | 架构图 |
| 流程/审批/部署/业务流转/状态机 | 流程图 |
| 跨角色流程/跨系统交互/端到端链路 | 泳道图 |
| 组织/层级/汇报关系 | 组织架构图 |
| 时间线/里程碑/版本规划 | 里程碑图 |
| 因果/复盘/根因分析 | 鱼骨图 |
| 方案对比/技术选型/功能矩阵 | 对比图 |
| 循环/飞轮/闭环/增长链路 | 飞轮图 |
| 层级占比/能力模型/需求层次 | 金字塔图 |
| 矩形树图/层级面积占比 | 树状图 |
| 转化漏斗/销售漏斗 | 漏斗图 |
| 分类梳理/知识体系/思维导图/时序图/类图 | Mermaid |
| 数据分布/占比/饼图 | Mermaid |
| 柱状图/条形图/数据对比 | 柱状图 |
| 折线图/趋势图/时序数据 | 折线图 |
---
## 关联参考
- 画板查询/创作/修改/渲染写入：[`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)

236
skills/lark-whiteboard-cli/SKILL.md
View File

@@ -1,236 +0,0 @@
---
name: lark-whiteboard-cli
description: >
当用户要求或使用飞书画板绘制架构图、流程图、思维导图、时序图或其他可视化图表时使用此 skill，作为使用 whiteboard-cli 设计图表布局的指南
compatibility: Requires Node.js 18+
metadata:
requires:
bins: ["lark-cli"]
---
> [!NOTE]
> **环境依赖**：绘制画板需要 `@larksuite/whiteboard-cli`（画板 Node.js CLI 工具），以及 `lark-cli`（LarkSuite CLI 工具）。
> 如果执行失败，手动安装后重试：`npm install -g @larksuite/whiteboard-cli@^0.2.0`
> [!IMPORTANT]
> 执行 `npm install` 安装新的依赖前，务必征得用户同意！
## Workflow
> **这是画板，不是网页。** 画板是无限画布上自由放置元素，flex 布局是可选增强。
```
Step 1: 路由 & 读取知识
- 判断渲染路径（见路由表）：Mermaid 还是 DSL？
- 读对应 scene 指南 — 了解结构特征和布局策略
- 确定布局策略（见下方快速判断）和构建方式
- 读 references/ 核心模块 — 语法、布局、配色、排版、连线
Step 2: 生成完整 DSL（含颜色）
- 按 content.md 规划信息量和分组
- 按 layout.md 选择布局模式和间距
- 推荐使用图标让图表更直观，运行 `npx -y @larksuite/whiteboard-cli@^0.2.0 --icons` 查看可用图标，选取合适的图标, 但不要过度使用或者所有图表都用图标, 根据图表类型和内容选择是否使用图标
- 按 style.md 上色（用户没指定时用默认经典色板）
- 按 schema.md 语法输出完整 JSON
- 连线参考 connectors.md，排版参考 typography.md
注意：部分图形（鱼骨/飞轮/柱状/折线等）要按 scene 指南的脚本模板写 .js 脚本生成 JSON：
1. 创建产物目录 ./diagrams/YYYY-MM-DDTHHMMSS/
2. 将脚本保存为 diagram.gen.js，执行 node diagram.gen.js 产出 diagram.json
3. 用产出的 diagram.json 进入 Step 3
Step 3: 渲染 & 审查 → 交付
- 渲染前自查（见下方检查清单）
- 渲染 PNG，检查：
· 信息完整？布局合理？配色协调？
· 文字无截断？连线无交叉？
- 有问题 → 按症状表修复 → 重新渲染（最多 2 轮）
- 2 轮后仍有严重问题 → 考虑走 Mermaid 路径兜底
- 没问题 → 交付：
· 用户要求上传飞书 → 见下方”上传飞书画板”章节中的说明
· 用户未指定 → 展示 PNG 图片给用户
```
**布局策略快速判断**（详见 `references/layout.md`）：
先定**主布局**，再定子布局：**结构化信息**优先用 Flex，**关系链路**优先用 Dagre，**灵活定位**用绝对布局。
涉及 Dagre / Flex 的具体边界、危险模式、混合布局原则，统一以 `references/layout.md` 为准；scene 文件只描述场景差异，不重复定义通用布局规则。
> **构建方式是强约束**：当 scene 指南要求"脚本生成"时，必须先写脚本（.js）并用 `node` 执行来产出 JSON 文件。绝对定位场景（鱼骨图、飞轮图、柱状图、折线图等）的坐标需要数学计算，直接手写 JSON 极易导致节点重叠或连线穿模。
---
## 渲染路径选择（DSL or 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/swimlane.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/flowchart.md` | 业务流、状态机、带条件判断的链路 |
| Mermaid | `scenes/mermaid.md` | 思维导图、时序图、类图、饼图 |
---
## 文件产物规范
每次绘图在 `./diagrams/` 下按当前时间创建子目录（格式 `YYYY-MM-DDTHHMMSS`），目录内文件名固定。用户指定了保存路径时以用户为准。
```
./diagrams/
2026-03-27T143000/ ← 自动按时间创建，无需起名
diagram.json ← DSL（CLI 输入）
diagram.gen.js ← 坐标计算脚本（仅脚本构建方式）
diagram.png ← 最终图片
diagram.mmd ← Mermaid 源码（仅 Mermaid 路径）
```
## CLI 命令
**查看可用图标**：
```bash
npx -y @larksuite/whiteboard-cli@^0.2.0 --icons
```
**渲染**：
```bash
npx -y @larksuite/whiteboard-cli@^0.2.0 -i ./diagrams/2026-03-27T143000/diagram.json -o ./diagrams/2026-03-27T143000/diagram.png # DSL
npx -y @larksuite/whiteboard-cli@^0.2.0 -i ./diagrams/2026-03-27T143000/diagram.mmd -o ./diagrams/2026-03-27T143000/diagram.png # Mermaid
```
**上传飞书画板**：
> 上传需要飞书认证。遇到认证或权限错误时，阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 了解登录和权限处理。
**第一步：获取画板 Token**
| 用户给了什么 | 怎么获取 Token |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 画板 Token（`XXX`） | 直接使用 |
| 文档 URL 或 doc_id，文档中已有画板 | `lark-cli docs +fetch --doc <URL> --as user`，从返回的 `<whiteboard token=”XXX”/>` 中提取 token |
| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --doc <doc_id> --mode append --markdown '<whiteboard type=”blank”></whiteboard>' --as user`，从响应的 `data.board_tokens[0]` 获取 token |
关于飞书文档的创建，读取等更多操作，请参考 lark-doc skill [`../lark-doc/SKILL.md`](../lark-doc/SKILL.md)。
**第二步：上传**
> [!CAUTION]
> **MANDATORY PRE-FLIGHT CHECK (上传前强制拦截检查)**
> 当你要向一个**已存在的画板 Token** 写入内容时，**绝对禁止**直接执行上传命令！你必须严格遵守以下两步：
> **强制执行 Dry Run（状态探测）**
> 必须先在命令中添加 `--overwrite --dry-run` 参数来探测画板当前状态。示例命令：
> ```bash
> npx -y @larksuite/whiteboard-cli@^0.2.0 --to openapi -i <输入文件> --format json | lark-cli whiteboard +update --whiteboard-token <Token> --source - --overwrite --dry-run --as user
> ```
>
> **解析结果并拦截**
> - 仔细阅读 Dry Run 的输出日志。
> - **如果日志包含 `XX whiteboard nodes will be deleted`**：这说明画板**非空**，当前操作会覆盖并摧毁用户的原有图表！
> - **你必须立即停止操作**，并通过 `AskUserQuestion` 工具（或直接回复）向用户确认：”目标画板当前非空，继续更新将清空原有的 XX 个节点，是否确认覆盖？”
> - 只有在用户明确授权”同意覆盖”后，你才能移除 `--dry-run` 真正执行上传。
> - 用户可能会要求你不覆盖更新画板内容，在这种情况下，移除 `--overwrite` 和 `--dry-run` 参数再上传。
```bash
npx -y @larksuite/whiteboard-cli@^0.2.0 --to openapi -i <输入文件> --format json | lark-cli whiteboard +update --whiteboard-token <画板Token> --source - --yes --as user
```
> 画板一经上传不可修改。如需应用身份上传，将 `--as user` 替换为 `--as bot`。
> 如果画板非空，先加 `--overwrite --dry-run` 检查待删除节点数，向用户确认后去掉 `--dry-run` 执行。
你也可以将布局输出为原生 OpenAPI json 格式，再通过 lark-cli 导入飞书画板。关于 lark-cli 操作画板的更多方式，请参照 [../lark-whiteboard/SKILL.md](../lark-whiteboard/SKILL.md)
**症状→修复表**（视觉审查发现问题时参照）：
| 看到的问题 | 改什么 |
| ------------------ | ----------------------------------- |
| 文字被截断 | height 改为 fit-content |
| 文字溢出容器右侧 | 增大 width，或缩短文字 |
| 节点重叠粘连 | 增大 gap |
| 节点挤成一团 | 增大 padding 和 gap |
| 连线穿过节点 | 调整 fromAnchor/toAnchor 或增大间距 |
| 大面积空白 | 缩小外层 frame 宽度 |
| 文字和背景色太接近 | 调整 fillColor 或 textColor |
| 布局整体偏左/偏右 | 调整绝对定位的 x 坐标使内容居中 |
---
## 渲染前自查
生成 DSL 后、渲染前，快速检查：
- [ ] 不同分组用了不同颜色？同组节点样式完全一致？
- [ ] 外层浅色背景、内层白色节点？（外重内轻）
- [ ] 所有节点有边框（borderWidth=2）？文字在背景上清晰可读？
- [ ] 连线用灰色（#BBBFC4），不用彩色？
- [ ] frame 都写了 layout 属性？gap 和 padding 都显式设置了？
- [ ] 含文字节点 height 用 fit-content？connector 在顶层 nodes 数组？
---
## 关键约束速查
> 最高频出错的规则，即使不读子模块文件也必须遵守。
1. **含文字节点的 height 必须用 `'fit-content'`** — 写死数值会截断文字
2. **`fill-container` 仅在 flex 父容器中生效** — `layout: 'none'` 下宽度退化为 0
3. **`layout: 'none'` 的容器必须有固定宽高** — 不要写成 `fit-content`
4. **connector 必须放在顶层 nodes 数组** — 不能嵌套在 frame children 里
5. **图层顺序** — 数组顺序 = 绘制顺序。后定义的元素层级越高，会覆盖先定义的。重叠/浮层/标注元素务必放在数组末尾。
6. **flex 容器内的 x/y 会被完全忽略** — 需要自由定位时用 `layout: 'none'` 或放在顶层 nodes
7. **Dagre 子容器默认为不透明节点** — 外层连线无法寻址其内部子节点（引擎会自动重定向至外壳）。需穿透时声明 `layout: "dagre"` + `layoutOptions: { isCluster: true }`
❌ 致命错误：flex 容器内设 x/y，坐标不生效，节点按顺序排列
```json
{ "type": "frame", "layout": "vertical", "children": [
{ "type": "rect", "x": 100, "y": 0, "text": "成都" },
{ "type": "rect", "x": 540, "y": 0, "text": "康定" }
]}
```
✅ 正确：用 `layout: "none"` 或放在顶层 nodes 用 x/y 定位。
❌ 致命错误：`layout: "none"` 容器本身写 `width: "fit-content", height: "fit-content"`，再在内部摆绝对坐标节点
✅ 正确：绝对定位容器先给固定宽高，再在内部用 x/y 放置子节点。

193
skills/lark-whiteboard/SKILL.md
View File

@@ -2,117 +2,144 @@
name: lark-whiteboard
version: 1.0.0
description: >
飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用 PlantUML/Mermaid 代码或 OpenAPI 原生格式更新画板内容。
当用户需要查看画板内容、导出画板图片、或编辑画板，或是需要可视化表达架构、流程、组织关系、时间线、因果、对比等结构化信息时使用此 skill，无论是否提及"画板"。
飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用 DSL（转成 OpenAPI 格式）、PlantUML/Mermaid 格式更新画板内容。
当用户需要查看画板内容、导出画板图片、编辑画板，或是需要可视化表达架构、流程、组织关系、时间线、因果、对比等结构化信息时使用此 skill，无论是否提及"画板"。
metadata:
requires:
bins: [ "lark-cli" ]
bins: ["lark-cli"]
cliHelp: "lark-cli whiteboard --help"
---
# whiteboard (v1)
> [!IMPORTANT]
> **执行前检查环境**：
> - 运行 `whiteboard-cli --version`，确认版本为 `0.2.x`；未安装或版本不符 → `npm install -g @larksuite/whiteboard-cli@^0.2.0`
> - 运行 `lark-cli --version`，确认可用。
> - 执行任何 `npm install` 前，**必须征得用户同意**。
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
## 核心概念
### 画板 Token
画板 token 是画板的唯一标识符。飞书画板嵌入在云文档中，可以从云文档的 `docs +fetch` 结果中获取（`<whiteboard token="xxx"/>`
标签），或从 `docs +update` 新建画板后的 `data.board_tokens` 字段中获取。
---
## 快速决策
当需要插入图表时：
| 用户需求 | 行动 |
|---|---|
| 查看画板内容 / 导出图片 | [`+query --output_as image`](references/lark-whiteboard-query.md) |
| 获取画板的 Mermaid/PlantUML 代码 | [`+query --output_as code`](references/lark-whiteboard-query.md) |
| 检查画板是否由代码绘制 | [`+query --output_as code`](references/lark-whiteboard-query.md) |
| 修改节点文字/颜色（简单改动）| `+query --output_as raw` → 手动改 JSON → `+update --input_format raw` |
| 用户**已提供** Mermaid/PlantUML 代码，或明确指定用该格式 | 自己生成/使用代码 → [`+update --input_format mermaid/plantuml`](references/lark-whiteboard-update.md) |
| 绘制复杂图表（架构/流程/组织等）| → **[§ 创作 Workflow](#创作-workflow)** |
| 修改/重绘已有复杂画板 | → **[§ 修改 Workflow](#修改-workflow)** |
1. 能否使用飞书画板？
- 能 → 走画板路径（推荐！可编辑、可协作）
- 不能 → 走图片路径
| 用户需求 | 推荐 Shortcut |
|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| "查看这个画板的内容" | [`+query --output_as image`](references/lark-whiteboard-query.md) |
| "导出画板为图片" | [`+query --output_as image`](references/lark-whiteboard-query.md) |
| "获取画板的 PlantUML/Mermaid 代码" | [`+query --output_as code`](references/lark-whiteboard-query.md) |
| "检查画板是否由 PlantUML/Mermaid 代码块组成" | [`+query --output_as code`](references/lark-whiteboard-query.md) |
| "修改画板某个节点的颜色或文字" | [`+query --output_as raw`](references/lark-whiteboard-query.md) 后 [`+update`](references/lark-whiteboard-update.md) |
| "用 PlantUML 绘制画板" | [`+update --input_format plantuml`](references/lark-whiteboard-update.md) |
| "用 Mermaid 绘制画板" | [`+update --input_format mermaid`](references/lark-whiteboard-update.md) |
| "在画板绘制复杂图表" | [`+update --input_format raw`](references/lark-whiteboard-update.md), 需要使用 whiteboard-cli 工具，参见 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) |
> **⚠️ 强制规范（通过 stdin 更新）**：
> 数据来源于本地文件时，**必须**使用 `--source - --input_format <格式>`。
> 例：`cat chart.mmd | lark-cli whiteboard +update <token> --source - --input_format mermaid`
## Shortcuts
| Shortcut | 说明 |
|---------------------------------------------------|---------------------------------------------|
| [`+query`](references/lark-whiteboard-query.md) | 查询画板，导出为预览图片、代码或原始节点结构 |
| [`+update`](references/lark-whiteboard-update.md) | 更新画板内容，支持 PlantUML、Mermaid 或 OpenAPI 原生格式输入 |
| Shortcut | 说明 |
|---|---|
| [`+query`](references/lark-whiteboard-query.md) | 查询画板，导出为预览图片、代码或原始节点结构 |
| [`+update`](references/lark-whiteboard-update.md) | 更新画板，支持 PlantUML、Mermaid 或 OpenAPI 原生格式 |
## Workflow
---
### 场景 1: 创作一个画板
## 创作 Workflow
1. 确定需要创作的画板 Token（从用户请求或对应的文档中获取）与要创作的内容
2. 参考 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) 生成画板内容
3. 使用 [`+update`](references/lark-whiteboard-update.md) shortcut 更新画板内容
> 此 workflow 用于**独立创作一个画板**。
> 需要在文档中批量创建多个画板时，由 lark-doc 负责调度，见 `lark-doc` 技能的 `references/lark-doc-whiteboard.md`。
### 场景 2: 修改或优化一个画板
**Step 1：获取 board_token**
1. 确定要修改的画板 Token （从用户请求或对应的文档中获取）
2. 使用 [`+query --output_as code`](references/lark-whiteboard-query.md) shortcut 导出画板代码，确认画板是否由 Mermaid 或
PlantUML 绘制
1. 如果 +query --output_as code 返回了 Mermaid / PlantUML 代码块，则在这一代码的基础上优化修改
2. 如果没有返回代码块，则使用 [`+query --output_as image`](references/lark-whiteboard-query.md)
获取画板预览图片，根据图片内容参考 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) 重绘优化
3. 如果用户只需要简单修改某个节点的文本内容/颜色，可以使用 [
`+query --output_as raw`](references/lark-whiteboard-query.md) shortcut 导出画板原生 OpenAPI 格式，并在此基础上修改。
4. 如果用户有明确要求，则以用户要求优先。
3. 使用 [`+update`](references/lark-whiteboard-update.md) shortcut 创建新的画板内容。根据用户需求，你可能会需要使用 [
`docs +update`](../lark-doc/references/lark-doc-update.md) 创建新的画板，或使用 [
`+update --overwrite`](references/lark-whiteboard-update.md) 在原画板上覆盖式更新。
| 用户给了什么 | 怎么获取 |
|---|---|
| 直接给了 whiteboard token（`wbcnXXX`）| 直接使用 |
| 文档 URL 或 doc_id，文档中已有画板 | `lark-cli docs +fetch --doc <URL> --as user`，从返回的 `<whiteboard token="xxx"/>` 提取 |
| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --doc <doc_id> --mode append --markdown '<whiteboard type="blank"></whiteboard>' --as user`，从响应 `data.board_tokens[0]` 取得（参数详见 lark-doc SKILL.md）|
## 与 lark-doc 的配合使用
**Step 2：渲染 & 写入**
### 场景 1: 从文档中获取画板 token
→ 进入 **[§ 渲染 & 写入画板](#渲染--写入画板)** 章节，按流程完成后直接返回结果给用户。
1. 使用 `lark-doc` 的 [`+fetch`](../lark-doc/references/lark-doc-fetch.md) 获取文档内容
2. 从返回的 markdown 中解析 `<whiteboard token="xxx"/>` 标签，记录画板 token
3. 使用本 skill 的 `+query` 或 `+update` 读取或操作画板
---
### 场景 2: 新建画板并编辑（完整流程）
## 修改 Workflow
这是最常见的使用场景，**必须完整执行以下步骤**：
**Step 1：获取 board_token**（同创作 Workflow Step 1）
1. 使用 `lark-doc` 的 [`+update`](../lark-doc/references/lark-doc-update.md) 创建空白画板
- 在 markdown 中传入 `<whiteboard type="blank"></whiteboard>`
- **注意这一 XML 标签不要转义**
- 需要多个画板时，重复多个 whiteboard 标签
**Step 2：判断修改策略**
2. 从响应的 `data.board_tokens` 中获取新建画板的 token 列表
- 记录每个 token 对应的图表类型和位置
```
+query --output_as code
├─ 返回 Mermaid/PlantUML 代码
│ → 在原代码上修改 → +update --input_format mermaid/plantuml
├─ 无代码（DSL 或其他方式绘制的画板）
│ ├─ 只改文字/颜色 → +query --output_as raw → 手动改 JSON → +update --input_format raw
│ └─ 重绘/结构调整 → +query --output_as image → 看图后进入 [§ 渲染 & 写入画板]
└─ 用户有明确要求 → 以用户要求优先
```
3. 根据文档主题，为每个画板设计相应的内容
- 参考下方"常见图表模板与参考指南"选择合适的语法
- 使用 Mermaid（推荐）、PlantUML 或 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) 生成内容
---
4. **逐个更新画板**：使用本 skill 的 `+update` shortcut 编辑每个画板的内容
- 不要遗漏任何一个画板 token
- 确保每个画板都有实际内容，不是空白
## 渲染 & 写入画板
### 常见图表模板与参考指南
### 渲染路由
| 图表类型 | 推荐语法 | 详细参考指南 |
|----------------|--------------------|---------------------------------------------------------------------------------------------|
| 架构图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/architecture.md](../lark-whiteboard-cli/scenes/architecture.md) |
| 流程图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/flowchart.md](../lark-whiteboard-cli/scenes/flowchart.md) |
| 组织架构图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/organization.md](../lark-whiteboard-cli/scenes/organization.md) |
| 里程碑/时间线 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/milestone.md](../lark-whiteboard-cli/scenes/milestone.md) |
| 鱼骨图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/fishbone.md](../lark-whiteboard-cli/scenes/fishbone.md) |
| 对比图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/comparison.md](../lark-whiteboard-cli/scenes/comparison.md) |
| 飞轮图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/flywheel.md](../lark-whiteboard-cli/scenes/flywheel.md) |
| 金字塔图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/pyramid.md](../lark-whiteboard-cli/scenes/pyramid.md) |
| 思维导图/饼图/时序图/类图 | Mermaid | [lark-whiteboard-cli/scenes/mermaid.md](../lark-whiteboard-cli/scenes/mermaid.md) |
| 柱状图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/bar-chart.md](../lark-whiteboard-cli/scenes/bar-chart.md) |
| 折线图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/line-chart.md](../lark-whiteboard-cli/scenes/line-chart.md) |
| 树状图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/treemap.md](../lark-whiteboard-cli/scenes/treemap.md) |
| 漏斗图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/funnel.md](../lark-whiteboard-cli/scenes/funnel.md) |
| 泳道图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/swimlane.md](../lark-whiteboard-cli/scenes/swimlane.md) |
**先自报身份**：按训练来源，你属于哪一家？`Claude` / `Gemini` / `GPT` / `GLM` / `Doubao 或 Seed` / `Other`。身份决定 SVG / DSL 分流（不同家族对这两种表达语言的能力不均衡），不要跳过这一步。
**然后按图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
| 图表类型 | 身份 | 路径 |
|---|---|---|
| 思维导图、时序图、类图、饼图、甘特图 | 任何身份 | [`routes/mermaid.md`](routes/mermaid.md) |
| 其他图表 | `Claude` / `Gemini` / `GPT` / `GLM` | [`routes/svg.md`](routes/svg.md) |
| 其他图表 | `Doubao` / `Seed` / `Other` | [`routes/dsl.md`](routes/dsl.md) |
> **⚠️ SVG 路径失败回退**：走 `routes/svg.md` 时，碰到以下情况之一 → **丢弃当前 SVG，改读 `routes/dsl.md` 从零重画，不要逐行修补**：
> - 渲染命令直接报错（语法级崩溃，不是 `--check` 的 warn/error）
> - 两轮改写仍无法消除 `--check` 的 `text-overflow` error
> - 目测 PNG 视觉严重错乱（文字大面积溢出、元素重叠压住关键信息、布局整体崩溃）
>
> SVG 源码修补常常引入新 bug，换 DSL 从零重画往往更稳。这是 SVG 路径自由发挥的硬兜底，不要侵入 `routes/svg.md` 的创作流程。
### 产物规范
产物目录：`./diagrams/YYYY-MM-DDTHHMMSS/`（本地时间，不含冒号和时区后缀）。如用户指定路径，以用户为准。
目录内固定文件名：
```
diagram.svg ← SVG 源码（SVG 路径）
diagram.mmd ← Mermaid 源码（Mermaid 路径）
diagram.json ← DSL 源文件（DSL 路径） / OpenAPI JSON（SVG 路径从 diagram.svg 导出）
diagram.gen.cjs ← 坐标计算脚本（仅 DSL 脚本构建方式）
diagram.png ← 渲染结果
```
### 写入画板
> [!CAUTION]
> **写入前强制 dry-run**：向已有内容的画板写入时，必须先加 `--overwrite --dry-run` 探测。
> 输出含 `XX whiteboard nodes will be deleted` → 必须向用户确认后才能执行。
```bash
# 第一步：dry-run 探测
npx -y @larksuite/whiteboard-cli@^0.2.0 -i <产物文件> --to openapi --format json \
| lark-cli whiteboard +update \
--whiteboard-token <Token> \
--source - --input_format raw \
--idempotent-token <10+字符唯一串> \
--overwrite --dry-run --as user
# 第二步：确认后执行
npx -y @larksuite/whiteboard-cli@^0.2.0 -i <产物文件> --to openapi --format json \
| lark-cli whiteboard +update \
--whiteboard-token <Token> \
--source - --input_format raw \
--idempotent-token <10+字符唯一串> \
--overwrite --as user
```
> `--idempotent-token` 最少 10 字符，建议用时间戳+标识拼接（如 `1744800000-board-1`），避免重试导致重复写入。
> 如需应用身份上传，将 `--as user` 替换为 `--as bot`。

0
skills/lark-whiteboard-cli/references/connectors.md → skills/lark-whiteboard/references/connectors.md
View File

0
skills/lark-whiteboard-cli/references/content.md → skills/lark-whiteboard/references/content.md
View File

4
skills/lark-whiteboard/references/lark-whiteboard-query.md
View File

@@ -1,6 +1,6 @@
# whiteboard +query（查询画板）
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
查询画板内容，支持导出为预览图片、提取 PlantUML/Mermaid 代码，或获取飞书 OpenAPI 原生画板节点格式。
@@ -17,7 +17,7 @@
- `image`：预览图片
- `code`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。
- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) 。
- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)。
## 示例

29
skills/lark-whiteboard/references/lark-whiteboard-update.md
View File

@@ -1,6 +1,6 @@
# whiteboard +update（更新画板）
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
更新画板内容，支持三种输入格式：
@@ -26,8 +26,7 @@
思维导图，时序图，类图，饼图，流程图等图标推荐使用 Mermaid/PlantUML 语法绘制。
而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md)
使用 whiteboard-cli 工具创作。
而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板) 使用 whiteboard-cli 工具创作。
## 示例
@@ -69,28 +68,32 @@ lark-cli whiteboard +update \
--overwrite --yes --as user
```
### 示例 3：使用 whiteboard-cli 直接使用画板 DSL 更新画板
### 示例 3：使用 whiteboard-cli 生成 OpenAPI 格式并写入画板
whiteboard-cli 工具的具体用法请参考 [../lark-whiteboard-cli/SKILL.md](../lark-whiteboard-cli/SKILL.md)
whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
```bash
# 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
npx -y @larksuite/whiteboard-cli@^0.1.0 --to openapi -i <画板 DSL> --format json | lark-cli whiteboard +update \
--whiteboard-token <画板Token> \
--input_format raw --source -\
--overwrite --yes --as user
npx -y @larksuite/whiteboard-cli@^0.2.0 -i <产物文件> --to openapi --format json \
| lark-cli whiteboard +update \
--whiteboard-token <画板Token> \
--source - --input_format raw \
--idempotent-token <10+字符唯一串> \
--yes --as user
```
### 示例 4：使用 whiteboard-cli 使用画板 DSL 生成 Raw 格式 Json，并使用其更新画板
### 示例 4：先生成产物文件，再从文件读取更新
whiteboard-cli 工具的具体用法请参考 [../lark-whiteboard-cli/SKILL.md](../lark-whiteboard-cli/SKILL.md)
whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
```bash
# 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
npx -y @larksuite/whiteboard-cli@^0.1.0 --to openapi -i <画板 DSL> -o ./temp.json
# 生成 OpenAPI 格式到文件
npx -y @larksuite/whiteboard-cli@^0.2.0 -i <DSL 文件> --to openapi --format json -o ./temp.json
# 从文件读取并更新
lark-cli whiteboard +update \
--whiteboard-token <画板Token> \
--idempotent-token <10+字符唯一串> \
--input_format raw \
--source @./temp.json \
--overwrite --yes --as user

2
skills/lark-whiteboard-cli/references/layout.md → skills/lark-whiteboard/references/layout.md
View File

@@ -58,7 +58,7 @@
| ---------------------- | ----------------------------------------------------------------------------- |
| 纯 Flex / Dagre | 直接写 JSON |
| 混合布局 (Flex包Dagre) | 直接写 JSON（外层先做分区，局部复杂关系交给 Dagre；若被嵌套，默认为不透明节点） |
| 极度依赖几何坐标的图 | 写脚本生成 JSON（node xxx.js） |
| 极度依赖几何坐标的图 | 写脚本生成 JSON（node xxx.cjs） |
| 需要精确避让的特殊线 | 脚本 + `--layout` 两阶段 |
---

0
skills/lark-whiteboard-cli/references/schema.md → skills/lark-whiteboard/references/schema.md
View File

0
skills/lark-whiteboard-cli/references/style.md → skills/lark-whiteboard/references/style.md
View File

0
skills/lark-whiteboard-cli/references/typography.md → skills/lark-whiteboard/references/typography.md
View File

106
skills/lark-whiteboard/routes/dsl.md Normal file
View File

@@ -0,0 +1,106 @@
# DSL 路径
> **这是画板，不是网页。** 画板是无限画布上自由放置元素，flex 布局是可选增强。
## Workflow
```
Step 1: 路由 & 读取知识
- 读对应 scene 指南 — 了解结构特征和布局策略
- 确定布局策略（见下方快速判断）和构建方式
- 读 references/ 核心模块 — 语法、布局、配色、排版、连线
Step 2: 生成完整 DSL（含颜色）
- 按 content.md 规划信息量和分组
- 按 layout.md 选择布局模式和间距
- 推荐使用图标让图表更直观，运行 `npx -y @larksuite/whiteboard-cli@^0.2.0 --icons` 查看可用图标
- 按 style.md 上色（用户没指定时用默认经典色板）
- 按 schema.md 语法输出完整 JSON
- 连线参考 connectors.md，排版参考 typography.md
注意：部分图形（鱼骨/飞轮/柱状/折线等）要按 scene 指南的脚本模板写 CommonJS 脚本生成 JSON：
1. 创建产物目录 ./diagrams/YYYY-MM-DDTHHMMSS/
2. 将脚本保存为 diagram.gen.cjs（必须 .cjs 后缀，脚本用 require() 写，.js 在 ESM 项目下会崩），执行 node diagram.gen.cjs 产出 diagram.json
3. 用产出的 diagram.json 进入 Step 3
Step 3: 渲染 & 审查 → 交付
- 渲染前自查（见下方检查清单）
- 渲染 PNG（仅用于预览验证，不是最终产物）：npx -y @larksuite/whiteboard-cli@^0.2.0 -i diagram.json -o diagram.png
- 检查：信息完整？布局合理？配色协调？文字无截断？连线无交叉？
- 有问题 → 按症状表修复 → 重新渲染（最多 2 轮）
- 2 轮后仍有严重问题 → 考虑走 Mermaid 路径兜底
- 写入画板：用 whiteboard-cli 将 diagram.json 转换为 OpenAPI 格式并 pipe 给 +update：
npx -y @larksuite/whiteboard-cli@^0.2.0 -i diagram.json --to openapi --format json \
| lark-cli whiteboard +update --whiteboard-token <board_token> \
--source - --input_format raw --idempotent-token <时间戳+标识> --yes --as user
→ 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)
- 交付：向用户报告 board_token 写入成功
```
**布局策略快速判断**（详见 `references/layout.md`）：
先定**主布局**，再定子布局：**结构化信息**优先用 Flex，**关系链路**优先用 Dagre，**灵活定位**用绝对布局。
> **构建方式是强约束**：当 scene 指南要求"脚本生成"时，必须先写脚本（`.cjs`，CommonJS）并用 `node` 执行来产出 JSON 文件。
## 模块索引
### 核心参考（必读）
| 模块 | 文件 | 说明 |
| -------- | -------------------------- | ------------------------------- |
| 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/swimlane.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/flowchart.md` | 业务流、状态机、带条件判断的链路 |
## 渲染前自查
- [ ] 不同分组用了不同颜色？同组节点样式完全一致？
- [ ] 外层浅色背景、内层白色节点？
- [ ] 所有节点有边框（borderWidth=2）？文字在背景上清晰可读？
- [ ] 连线用灰色（#BBBFC4），不用彩色？
- [ ] frame 都写了 layout 属性？gap 和 padding 都显式设置了？
- [ ] 含文字节点 height 用 fit-content？connector 在顶层 nodes 数组？
## 症状→修复表
| 看到的问题 | 改什么 |
| ------------------ | ----------------------------------- |
| 文字被截断 | height 改为 fit-content |
| 文字溢出容器右侧 | 增大 width，或缩短文字 |
| 节点重叠粘连 | 增大 gap |
| 节点挤成一团 | 增大 padding 和 gap |
| 连线穿过节点 | 调整 fromAnchor/toAnchor 或增大间距 |
| 大面积空白 | 缩小外层 frame 宽度 |
| 文字和背景色太接近 | 调整 fillColor 或 textColor |
| 布局整体偏左/偏右 | 调整绝对定位的 x 坐标使内容居中 |
## 关键约束速查
1. **含文字节点的 height 必须用 `'fit-content'`** — 写死数值会截断文字
2. **`fill-container` 仅在 flex 父容器中生效** — `layout: 'none'` 下宽度退化为 0
3. **`layout: 'none'` 的容器必须有固定宽高** — 不要写成 `fit-content`
4. **connector 必须放在顶层 nodes 数组** — 不能嵌套在 frame children 里
5. **flex 容器内的 x/y 会被完全忽略** — 需要自由定位时用 `layout: 'none'`
6. **Dagre 子容器默认为不透明节点** — 需穿透时声明 `layout: "dagre"` + `layoutOptions: { isCluster: true }`

27
skills/lark-whiteboard/routes/mermaid.md Normal file
View File

@@ -0,0 +1,27 @@
# Mermaid 路径
适用于：思维导图、时序图、类图、饼图、甘特图。
## Workflow
```
Step 1: 读取知识
- 读 scenes/mermaid.md — Mermaid 语法和使用方式
Step 2: 生成 Mermaid
- 按 mermaid.md 的语法编写 .mmd 文件
- 只输出纯 Mermaid 语法文本
Step 3: 渲染验证 & 写入画板 & 交付
1. 创建产物目录 ./diagrams/YYYY-MM-DDTHHMMSS/
2. 保存为 diagram.mmd
3. 渲染（仅用于预览验证，PNG 不是最终产物）：
npx -y @larksuite/whiteboard-cli@^0.2.0 -i diagram.mmd -o diagram.png
4. 审查 PNG，有问题修改后重新渲染（最多 2 轮）
5. 写入画板：用 whiteboard-cli 将 diagram.mmd 转换为 OpenAPI 格式并 pipe 给 +update：
npx -y @larksuite/whiteboard-cli@^0.2.0 -i diagram.mmd --to openapi --format json \
| lark-cli whiteboard +update --whiteboard-token <board_token> \
--source - --input_format raw --idempotent-token <时间戳+标识> --yes --as user
→ 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)
6. 交付：向用户报告 board_token 写入成功
```

53
skills/lark-whiteboard/routes/svg.md Normal file
View File

@@ -0,0 +1,53 @@
# SVG 路径
你在设计一张专业的信息图——内容扎实, 美观漂亮, 具有设计感和视觉张力, 不是枯燥的布局和文字堆砌, **不要做的像普通的网页或者千篇一律的模版**
最终交付是**画板跨越重排渲染的节点**(你写 SVG → 画板解析)
**核心心智纠正 (重要)**：
- 大多数 AI 如果只考虑“绝对不报错/完美映射”, 最终给出的都是全篇纯白底色加单层 `<rect>` 的方正卡片网格, 极其死板单调, **这将被视为不及格！**
- **SVG 给你了完全的设计自由**, 请大胆使用你脑内的图标路径 (`<path>`), 连接指引 (`流畅的 <path>`), 各种环境氛围点缀, 大胆一点, 充分信任你的品味, 发挥出你的顶级艺术创造力！
## Workflow
### 1. 想清楚要画什么
- **核心信息是什么？** 能做到一图胜千言, 绝对不要只生成平平无奇的文字表格, 要有设计感
- **内容充实度**：如果用户描述稀疏简略, 利用你的领域知识扩展, 保证信息维度和内容充实, 但不要过度堆砌, 淹没重点
- **视觉层级与隐喻**：这个没有固定的形式, 你自由判断, 比如: 给重要的节点加光环, 加高亮背景；给对比项设计天平或对称结构
### 2. 写 SVG
[!IMPORTANT] 布局, 配色, 信息密度, 装饰物——**全部由你判断**, 打破单调的 `<rect>` 牢笼, 严禁通篇用矩形和文字应付用户
操作边界约束：
- **语言跟随用户**：图表文字的语言与用户 prompt 保持一致, 技术术语用行业里通用的写法, 不机械翻译
- 文字用 `<text>`(不是 `<path>`), 容器宽度留够——画板按 CJK ≈ 1em / Latin ≈ 0.6em 重排
- 连线使用正交折线替代斜直线(`<polyline>` 带水平/垂直折点)视觉效果更好
- 可自由使用 `translate`, `rotate`, `scale`但请尽量避免使用 `skewX` / `skewY` / `matrix(...)` 发生空间级扭曲
### 3. 渲染审查
```
建目录 ./diagrams/YYYY-MM-DDTHHMMSS/ (例：./diagrams/2026-04-15T143022/)
写文件 <dir>/diagram.svg
渲染 npx -y @larksuite/whiteboard-cli@^0.2.0 -i <dir>/diagram.svg -o <dir>/diagram.png -f svg
检查 npx -y @larksuite/whiteboard-cli@^0.2.0 -i <dir>/diagram.svg -f svg --check
导出 npx -y @larksuite/whiteboard-cli@^0.2.0 -i <dir>/diagram.svg -f svg --to openapi --format json > <dir>/diagram.json
```
`npx -y @larksuite/whiteboard-cli@^0.2.0 --check` 检测 `text-overflow` 和 `node-overlap`, 并结合视觉效果(查看 PNG)进行调整
## 画板怎么处理 SVG
画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示), **不需要所有元素都可编辑, 一定要兼顾可编辑和美观漂亮**
**可识别的元素**
- 形状：`<rect>` / `<circle>` / `<ellipse>` / `<polygon>`
- 连线：`<line>` / `<polyline>` / `<path>`(自动识别为直线 / 折线 / 曲线)
- 文本：`<text>` / `<tspan>` 画板硬编码 Noto Sans SC **文字必须用 `<text>`**
- 分组：`<g>` / `<a>` / `<use>` 引用 `<symbol>`
- 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级
**装饰特性**
- `<radialGradient>` / `<filter>` / `<pattern>` / `<clipPath>` / `<mask>` → 画板通过图片路径保留视觉 (光晕/阴影/纹理/遮罩等效果都在, 元素不可再编辑但不丢视觉)

0
skills/lark-whiteboard-cli/scenes/architecture.md → skills/lark-whiteboard/scenes/architecture.md
View File

8
skills/lark-whiteboard-cli/scenes/bar-chart.md → skills/lark-whiteboard/scenes/bar-chart.md
View File

@@ -8,7 +8,7 @@
## Layout 选型
- **脚本生成坐标**（推荐）：用 .js 脚本计算柱体位置和高度，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
- **脚本生成坐标**（推荐）：用 .cjs 脚本计算柱体位置和高度，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
- **绝对定位手写**：简单柱状图（≤ 5 个柱）可手写坐标
## Layout 规则
@@ -179,3 +179,9 @@
- 柱体间距不均匀（脚本需统一计算 barGap）
- Y 轴刻度线和格线误带箭头
- 坐标轴忘记带箭头
此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `data` 数组，其余坐标与柱体高度全自动计算。
```javascript
const { writeFileSync } = require('fs');
```

0
skills/lark-whiteboard-cli/scenes/comparison.md → skills/lark-whiteboard/scenes/comparison.md
View File

2
skills/lark-whiteboard-cli/scenes/fishbone.md → skills/lark-whiteboard/scenes/fishbone.md
View File

@@ -10,7 +10,7 @@
## Layout 选型
- **脚本生成坐标**（必须）：用 .js 脚本通过三角函数计算鱼骨坐标，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
- **脚本生成坐标**（必须）：用 .cjs 脚本通过三角函数计算鱼骨坐标，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
## Layout 规则

0
skills/lark-whiteboard-cli/scenes/flowchart.md → skills/lark-whiteboard/scenes/flowchart.md
View File

4
skills/lark-whiteboard-cli/scenes/flywheel.md → skills/lark-whiteboard/scenes/flywheel.md
View File

@@ -9,7 +9,7 @@
## Layout 选型
- **脚本生成坐标**（必须）：用 .js 脚本极坐标计算阶段标签位置、SVG 圆环切割，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
- **脚本生成坐标**（必须）：用 .cjs 脚本极坐标计算阶段标签位置、SVG 圆环切割，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
## Layout 规则
@@ -51,7 +51,7 @@ nodes 数组中的图层顺序（必须严格遵守）：
## 骨架示例
此场景必须用 .js 脚本生成。Agent 使用时只需修改 `stages` 数组和 `centerTitle`/`centerSubtitle`，其余坐标全自动计算。
此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `stages` 数组和 `centerTitle`/`centerSubtitle`，其余坐标全自动计算。
```javascript
const { writeFileSync } = require('fs');

4
skills/lark-whiteboard-cli/scenes/funnel.md → skills/lark-whiteboard/scenes/funnel.md
View File

@@ -26,10 +26,10 @@
## 脚本构建模板
必须使用 `node` 运行脚本生成 JSON。
此场景必须用 .cjs 脚本生成。
```javascript
import fs from 'fs';
const fs = require('fs');
// 1. 配置基础参数
const GAP = 4;

8
skills/lark-whiteboard-cli/scenes/line-chart.md → skills/lark-whiteboard/scenes/line-chart.md
View File

@@ -8,7 +8,7 @@
## Layout 选型
- **脚本生成坐标**（推荐）：用 .js 脚本计算数据点坐标和折线路径，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
- **脚本生成坐标**（推荐）：用 .cjs 脚本计算数据点坐标和折线路径，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
## Layout 规则
@@ -206,3 +206,9 @@
- 数据点太密时标注互相遮挡（超过 10 个点考虑隔一个标注一次）
- 折线段忘记设 endArrow: "none"，默认带箭头
- 多系列时折线颜色相近难以区分，应使用对比度高的不同色系
此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `data` 数组，其余坐标与折线生成全自动计算。
```javascript
const { writeFileSync } = require('fs');
```

6
skills/lark-whiteboard-cli/scenes/mermaid.md → skills/lark-whiteboard/scenes/mermaid.md
View File

@@ -16,12 +16,6 @@
- 用户直接粘贴了 Mermaid 语法文本
- 图表类型为思维导图、时序图、类图、饼图（自动路由）
## CLI 用法
```bash
npx -y @larksuite/whiteboard-cli@^0.2.0 -i ./diagrams/{name}.mmd -o ./diagrams/{name}.png
```
## 思维导图 (Mindmap)
```mermaid

0
skills/lark-whiteboard-cli/scenes/milestone.md → skills/lark-whiteboard/scenes/milestone.md
View File

4
skills/lark-whiteboard-cli/scenes/organization.md → skills/lark-whiteboard/scenes/organization.md
View File

@@ -159,9 +159,7 @@
{ "type": "connector", "connector": { "from": "child-b", "to": "leaf-b1", "fromAnchor": "bottom", "toAnchor": "top", "lineShape": "rightAngle", "lineWidth": 2 } },
{ "type": "connector", "connector": { "from": "child-b", "to": "leaf-b2", "fromAnchor": "bottom", "toAnchor": "top", "lineShape": "rightAngle", "lineWidth": 2 } }
]
};
fs.writeFileSync('diagram.json', JSON.stringify(doc, null, 2));
}
```
## 陷阱

2
skills/lark-whiteboard-cli/scenes/pyramid.md → skills/lark-whiteboard/scenes/pyramid.md
View File

@@ -29,7 +29,7 @@ vertical frame + 每层宽度递减。gap 4px 保持紧密。
必须使用 `node` 运行脚本生成 JSON。
```javascript
import fs from 'fs';
const fs = require('fs');
// 1. 配置基础参数
const GAP = 4;

31
skills/lark-whiteboard-cli/scenes/swimlane.md → skills/lark-whiteboard/scenes/swimlane.md
View File

@@ -27,9 +27,9 @@
1. **网格对齐是第一优先级**：跨泳道同一阶段必须严格对齐（水平对齐 x；垂直对齐 y）。对齐通过“共享阶段标尺（stage ruler / stage slots）”实现，不靠肉眼估算，也不靠逐节点随意手写坐标
2. **只生成真实节点**：为保证跨泳道阶段严格对齐，所有阶段统一保留透明的 **stage cell**；仅在真实阶段的 cell 内生成卡片节点，并按阶段索引映射到对应槽位
3. **泳道容器禁止使用背景色**：每条泳道是一个可见的分组容器，只能使用边框表达分组（建议统一使用浅灰色细虚线 `borderDash: "dashed"`，`borderWidth: 1`，`borderColor: "#DEE0E3"`），**不得使用任何有色背景作为泳道底色**，以降低视觉噪音。必须显式声明 `fillColor: "transparent"`，保持视觉透明
3. **泳道底色**：为了增强层级感同时保持界面整洁，**强烈建议所有泳道容器统一使用极浅灰色背景**（如 `fillColor: "#F8F9FA"` 或 `"#FCFCFC"`）。边框使用浅灰色细虚线（`borderDash: "dashed"`, `borderWidth: 1`, `borderColor: "#DEE0E3"`）以明确边界。
4. **步骤卡片**：使用 `rect`。为建立清晰的视觉层级，卡片**必须填充浅色背景**（参考 `references/style.md` 中的浅色板，如极浅的主题色），边框使用对应的主题主色（`borderWidth: 1-2`），文字使用深色（如 `#1F2329`）以确保可读性。统一圆角；宽高以可读为先，避免过窄导致换行过多
5. **间距**：只要存在 connector 连线，卡片之间的主轴间距必须满足 `gap >= 40`；如果连线包含文字（`label`），主轴间距必须 `gap >= 64`，以提供充足的阅读空间。
5. **间距**：只要存在 connector 连线，卡片之间的主轴间距必须满足 `gap >= 40`
### 子节点对齐
@@ -51,7 +51,7 @@
### 跨泳道间距（lanesGap）
- 根容器承载所有泳道：水平泳道用 `layout: "vertical"`，垂直泳道用 `layout: "horizontal"`
- 固定跨泳道主轴间距 `lanesGap`（建议 `64-80`），更宽的间距能让跨泳道连线（特别是带文字时）有更多留白，降低重叠感
- 缩减跨泳道主轴间距 `lanesGap`（建议 `16-24`），以保持整体图表的紧凑性。避免 `lanesGap` 设置为 `0` 导致边框重叠变粗，也避免间距过大导致视觉涣散。
- 每条泳道作为根容器的子 frame，内部再使用上述 Flex 栅格的 stage cell 布局
- `lanesGap` 与 `lanePadding/stackGap` 独立；lane 内容增减不应影响跨泳道间距
- 4px 基线对齐：`lanesGap`、`lanePadding`、cell 尺寸建议按 4 的倍数对齐
@@ -72,7 +72,7 @@
- lane body：`layout: "vertical"`，包含完整的阶段 **stage cell** 数组；cell 高度固定为 `slotHeight`，相邻 cell 间 `gap` 统一；空阶段 cell 透明但保留
- 内容居中对齐：stage cell 建议 `alignItems: "center"` + `justifyContent: "center"`，让卡片在每个 cell 内水平/垂直居中；卡片宽度不超过 `slotWidth`（或固定宽度），避免被 `"fill-container"` 拉伸导致“看起来不居中”
- 步骤卡片：推荐统一卡片高度或统一 `slotHeight / gap`，保证跨泳道阶段严格 y 对齐
- 泳道外层容器必须显式写 `fillColor: "transparent"`、`borderDash: "dashed"`、`borderWidth: 1`、`borderColor: "#DEE0E3"`（统一浅灰色），否则会被编译为虚拟 frame 导致不渲染
- 泳道外层容器必须显式写 `fillColor: "#F8F9FA"`（极浅灰）、`borderDash: "dashed"`、`borderWidth: 1`、`borderColor: "#DEE0E3"`（统一浅灰色），否则会被编译为虚拟 frame 导致不渲染
- 统一高度（Flex 自适应，可选）：根容器使用 `alignItems: "stretch"`，每个泳道外层 frame 使用 `height: "fill-container"`；泳道内部仍保持 lane label + lane body 的结构
示例：
@@ -86,7 +86,7 @@
"id": "lanes-root",
"x": 40, "y": 40,
"layout": "horizontal",
"gap": 64,
"gap": 16,
"alignItems": "stretch",
"children": [
{
@@ -95,7 +95,7 @@
"layout": "vertical",
"width": "fit-content",
"height": "fill-container",
"fillColor": "transparent",
"fillColor": "#F8F9FA",
"borderDash": "dashed",
"borderWidth": 1,
"borderColor": "#DEE0E3",
@@ -106,7 +106,7 @@
"textAlign": "center", "verticalAlign": "middle", "fontSize": 18, "fontWeight": "bold", "textColor": "#5178C6" }
] },
{ "type": "frame", "id": "lane-left-body", "layout": "vertical",
"gap": 64, "padding": 16,
"gap": 40, "padding": 16,
"children": [
{ "type": "frame", "id": "stage-1-cell-left", "layout": "vertical", "width": 220, "height": 80, "alignItems": "center", "justifyContent": "center",
"children": [{ "type": "rect", "id": "c-s1", "width": 200, "height": "fit-content", "fillColor": "#E1EAFA", "borderColor": "#5178C6", "borderWidth": 2, "borderRadius": 8 }] },
@@ -120,7 +120,7 @@
"layout": "vertical",
"width": "fit-content",
"height": "fill-container",
"fillColor": "transparent",
"fillColor": "#F8F9FA",
"borderDash": "dashed",
"borderWidth": 1,
"borderColor": "#DEE0E3",
@@ -131,7 +131,7 @@
"textAlign": "center", "verticalAlign": "middle", "fontSize": 18, "fontWeight": "bold", "textColor": "#8569CB" }
] },
{ "type": "frame", "id": "lane-right-body", "layout": "vertical",
"gap": 64, "padding": 16,
"gap": 40, "padding": 16,
"children": [
{ "type": "frame", "id": "stage-1-cell-right", "layout": "vertical", "width": 220, "height": 80, "alignItems": "center", "justifyContent": "center", "children": [] },
{ "type": "frame", "id": "stage-2-cell-right", "layout": "vertical", "width": 220, "height": 80, "alignItems": "center", "justifyContent": "center",
@@ -142,13 +142,14 @@
]
},
{ "type": "connector", "connector": { "from": "c-s1", "to": "d-s2",
"lineShape": "polyline", "lineColor": "#BBBFC4", "lineWidth": 2, "endArrow": "arrow" } }
"lineShape": "polyline", "lineColor": "#BBBFC4", "lineWidth": 2, "endArrow": "arrow" } }
]
}
```
### 泳道配色（默认色板）
- **泳道背景**：所有泳道容器统一使用极浅灰色（如 `fillColor: "#F8F9FA"` 或 `"#FCFCFC"`），以增强物理容器的层级感，并突出内部的彩色卡片。
- **泳道边框**：所有泳道外层容器统一使用浅灰色细虚线（`borderColor: "#DEE0E3"`, `borderWidth: 1`, `borderDash: "dashed"`）。
- **泳道标题**：按 `references/style.md` 经典色板为每条泳道分配不同的主题色，泳道 title 的 `textColor` 使用该主题色。
- **内容节点（rect）**：采用“浅色底 + 主题色边框”策略。`fillColor` 使用与该泳道主题色对应的极浅色（如浅蓝、浅紫等），`borderColor` 使用对应的主题色，文字 `textColor` 统一使用深色 `#1F2329`。
@@ -188,7 +189,7 @@
"x": 40,
"y": 40,
"layout": "vertical",
"gap": 64,
"gap": 16,
"alignItems": "stretch",
"padding": 0,
"width": "fit-content",
@@ -198,11 +199,11 @@
"type": "frame",
"id": "lane-a",
"layout": "horizontal",
"gap": 64,
"gap": 40,
"padding": 16,
"width": "fit-content",
"height": "fill-container",
"fillColor": "transparent",
"fillColor": "#F8F9FA",
"borderDash": "dashed",
"borderWidth": 1,
"borderColor": "#DEE0E3",
@@ -267,11 +268,11 @@
"type": "frame",
"id": "lane-b",
"layout": "horizontal",
"gap": 64,
"gap": 40,
"padding": 16,
"width": "fit-content",
"height": "fill-container",
"fillColor": "transparent",
"fillColor": "#F8F9FA",
"borderDash": "dashed",
"borderWidth": 1,
"borderColor": "#DEE0E3",

8
skills/lark-whiteboard-cli/scenes/treemap.md → skills/lark-whiteboard/scenes/treemap.md
View File

@@ -8,7 +8,7 @@
## Layout 选型
- **脚本生成坐标**（推荐）：Treemap 需要精确的面积比例计算，用 .js 脚本递归切分矩形，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
- **脚本生成坐标**（推荐）：Treemap 需要精确的面积比例计算，用 .cjs 脚本递归切分矩形，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染
- 不适合手动心算坐标
## Layout 规则
@@ -208,3 +208,9 @@
- **分类标签不可见**：分类标签 text 节点必须在其子矩形 rect 节点之前添加（z-index 靠后的节点在上层）
- **面积比例不正确**：必须用脚本预先计算比例，不要心算
- **缺少配色区分**：不同顶层分类必须用不同背景色（从色板选取），所有子节点继承对应色系
此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `data` 树，其余坐标与矩形面积自动递归计算。
```javascript
const { writeFileSync } = require('fs');
```