feat：移除了弹窗，服务器添加sls
This commit is contained in:
48
.claude/skills/lark-whiteboard/SKILL.md
Normal file
48
.claude/skills/lark-whiteboard/SKILL.md
Normal file
@ -0,0 +1,48 @@
|
||||
---
|
||||
name: lark-whiteboard
|
||||
version: 1.0.0
|
||||
description: >
|
||||
飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用多种格式更新画板内容。
|
||||
当用户需要查看画板内容、导出画板图片、编辑画板时使用此 skill。不负责：飞书云文档内容编辑（lark-doc）、文档内嵌电子表格/Base（lark-sheets / lark-base）。
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli whiteboard --help"
|
||||
---
|
||||
|
||||
> [!IMPORTANT]
|
||||
> - 运行 `lark-cli --version`，确认可用，无需询问用户。
|
||||
> - 运行 `npx -y @larksuite/whiteboard-cli@^0.2.13 -v`，确认可用，无需询问用户。
|
||||
|
||||
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
|
||||
|
||||
---
|
||||
|
||||
## 快速决策
|
||||
|
||||
**身份**：画板操作默认使用 `--as user`。仅当需要以应用身份上传时使用 `--as bot`。
|
||||
|
||||
| 用户需求 | 行动 |
|
||||
|-----------------------------------------|---------------------------------------------------------------------------------------------------|
|
||||
| 查看画板内容 / 导出图片 | [`+export --output-type preview`](references/lark-whiteboard-export.md) |
|
||||
| 导出 SVG 矢量图 | [`+export --output-type svg`](references/lark-whiteboard-export.md) |
|
||||
| 获取画板的 Mermaid/PlantUML 代码 | [`+export --output-type source`](references/lark-whiteboard-export.md) |
|
||||
| 检查画板是否由代码绘制 | [`+export --output-type source`](references/lark-whiteboard-export.md) |
|
||||
| 仅微调节点文字/颜色 | `+export --output-type raw` → 手动改 JSON → `+update --input_format raw` |
|
||||
| 用户**已提供** Mermaid/PlantUML/SVG 代码，或明确指定用该格式 | 自己生成/使用代码 → [`+update --input_format mermaid/plantuml/svg`](references/lark-whiteboard-update.md) |
|
||||
| 新建/创作复杂图表（架构/流程/组织等） | → **[§ 创作 Workflow](references/lark-whiteboard-workflow.md#创作-workflow)** |
|
||||
| 修改/重绘已有画板 | → **[§ 修改 Workflow](references/lark-whiteboard-workflow.md#修改-workflow)** |
|
||||
|
||||
## Shortcuts
|
||||
|
||||
| Shortcut | 说明 |
|
||||
|---------------------------------------------------|---|
|
||||
| [`+export`](references/lark-whiteboard-export.md) | 导出画板为预览图片、SVG 矢量图、代码或原始节点结构。 |
|
||||
| [`+update`](references/lark-whiteboard-update.md) | 更新画板，支持 PlantUML、Mermaid、SVG 或 OpenAPI 原生格式 |
|
||||
|
||||
---
|
||||
|
||||
## 不在本 skill 范围
|
||||
- 文档内容编辑 → lark-doc [lark-doc](../lark-doc/SKILL.md)
|
||||
- 在文档中创建画板 → [lark-doc-whiteboard.md](../lark-doc/references/lark-doc-whiteboard.md)
|
||||
- 表格 / Base 操作 → [lark-sheets](../lark-sheets/SKILL.md) / [lark-base](../lark-base/SKILL.md)
|
||||
102
.claude/skills/lark-whiteboard/elements/connectors.md
Normal file
102
.claude/skills/lark-whiteboard/elements/connectors.md
Normal file
@ -0,0 +1,102 @@
|
||||
# 连线系统
|
||||
|
||||
## 连线策略
|
||||
|
||||
| 连线数 | 策略 |
|
||||
|--------|------|
|
||||
| ≤8 | 逐条画 |
|
||||
| 9-15 | 代表性连线（每层选 1-2 个节点连到下一层）|
|
||||
| >15 | 层到层连线，或回退精简分组 |
|
||||
|
||||
一个节点有 3+ 条连线时：入线从 top，出线从 bottom，同侧多条线用不同方向分散。
|
||||
|
||||
---
|
||||
|
||||
## connector 必须放根 nodes 数组
|
||||
|
||||
```typescript
|
||||
// 错误：connector 放在 frame children 里
|
||||
{ type: 'frame', children: [
|
||||
{ type: 'connector', ... } // 会导致 Schema 报错或无法连线！
|
||||
]}
|
||||
|
||||
// 正确：connector 放在根 nodes 数组
|
||||
const doc: WBDocument = {
|
||||
version: 2,
|
||||
nodes: [
|
||||
{ type: 'frame', id: 'box', ... },
|
||||
{ type: 'connector', ... }, // 必须和顶层 frame 平级
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 箭头默认值
|
||||
|
||||
- `endArrow` 省略时默认为 `'arrow'`（即连线末端默认带箭头）。
|
||||
- `startArrow` 省略时默认为 `'none'`（即连线起始端默认无箭头）。
|
||||
|
||||
---
|
||||
|
||||
## 连线技巧
|
||||
|
||||
```typescript
|
||||
// 自动绕线（推荐）：仅需指定节点 id（引擎可自动推断最优出线方向），并使用 polyline 或 rightAngle 形状
|
||||
// 只要不传 waypoints，引擎会尝试自动避开障碍物并生成折线。
|
||||
{ type: 'connector', connector: {
|
||||
from: 'a', to: 'b', // fromAnchor 和 toAnchor 也可以省略，让引擎自己找最短路径
|
||||
lineShape: 'polyline', lineColor: '#000000', lineWidth: 2, endArrow: 'arrow' }}
|
||||
|
||||
// 精确坐标（做注解箭头）
|
||||
{ type: 'connector', connector: {
|
||||
from: { x: 150, y: 200 }, to: 'b', toAnchor: 'left',
|
||||
lineShape: 'curve', lineColor: '#BBBFC4', lineWidth: 2,
|
||||
lineStyle: 'dashed', endArrow: 'triangle' }}
|
||||
|
||||
// 手动控制路径点 waypoints（仅在需要强制固定路线、或者自动路由不符合预期时使用）
|
||||
// 注意：一旦提供了 waypoints，引擎将严格尊重这些点，不再进行自动避障。
|
||||
{ type: 'connector', connector: {
|
||||
from: { x: 300, y: 140 }, to: { x: 300, y: 340 },
|
||||
waypoints: [{ x: 350, y: 140 }, { x: 350, y: 340 }],
|
||||
lineShape: 'polyline', lineColor: '#000000', lineWidth: 2, endArrow: 'arrow' }}
|
||||
|
||||
// 绘制坐标轴/数轴（必须使用 straight，防止刻度文字触发自动避障导致线条弯曲）
|
||||
{ type: 'connector', connector: {
|
||||
from: { x: 100, y: 400 }, to: { x: 600, y: 400 },
|
||||
lineShape: 'straight', lineColor: '#000000', lineWidth: 2, endArrow: 'arrow' }}
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **1. 形状选用要求（核心）**，需明确 `lineShape` 类型：
|
||||
> - **`'polyline'`（圆角折线）**：**默认首选**。适用于流程图、架构图等绝大多数场景。支持引擎的**自动绕线与避障**功能（只需指定 `from` 和 `to`）。
|
||||
> - **`'rightAngle'`（直角折线）**：适用于明确要求“总线/直角规约”、树状层级严格对齐的场景，同样支持**自动绕线与避障**。
|
||||
> - **`'straight'`（直线）**：不受自动避障机制的影响，适用于**坐标轴、数轴、几何图形边框、直接指向关系**等要求线条绝对笔直、不允许出现任何绕行或弯曲的场景。
|
||||
> - **`'curve'`（曲线）**：适用于优雅的跨层连线（S型弯）、自由发散的脑图分支、或做注解箭头时。
|
||||
> - **注意**：你需要根据当前绘制的图表类型和上下文语境，选择最合适的 `lineShape`。不要盲目全部使用 `polyline`，例如在绘制坐标系时必须主动切换为 `straight`。
|
||||
> **2. 间距要求**：有 connector 连线的卡片间 gap 需 ≥ 40，否则箭头挤在缝里看不清。
|
||||
> **3. 顶层约束**：`connector` 必须直接放在 `WBDocument.nodes`，**严禁**嵌套在 `children` 内。建议在数据末尾统一声明连线。
|
||||
>
|
||||
> [!TIP]
|
||||
> **自动绕线 vs 手动控制**
|
||||
> - **优先依赖自动绕线**：对于 `'polyline'` 和 `'rightAngle'`，引擎会自动规划路径并尝试避开障碍物（`fromAnchor` 和 `toAnchor` 也可省略，引擎会自动推断最优出线方向），这是最推荐的方式。
|
||||
> - **何时手动算 waypoints**：**仅在必要时**（例如自动路由不符合预期，或者必须强制走特定形状绕开特定元素时），才需要通过 `waypoints` 手动接管坐标序列。
|
||||
>
|
||||
> **连线标签**
|
||||
> - **连线文字说明**：需要文字说明时，可用 `label` 标注。
|
||||
|
||||
---
|
||||
|
||||
## 锚点方向规则
|
||||
|
||||
锚点（top/right/bottom/left）表示连线从节点的哪个边出发，方向含义与 CSS border 四边相同。
|
||||
|
||||
**注意：由于目前自动绕线功能支持省略锚点让引擎自动推断，以下规则主要适用于你想强制控制出线方向，或者使用直线/曲线时的场景。**
|
||||
|
||||
选择锚点时根据两个节点的相对位置：目标在下方用 `fromAnchor: 'bottom'` + `toAnchor: 'top'`，目标在右侧用 `fromAnchor: 'right'` + `toAnchor: 'left'`。如果手动指定了锚点，必须与节点的实际相对位置匹配，否则可能导致连线反向绕行。
|
||||
|
||||
**锚点绑定的常见范式**：
|
||||
- **同层横向推进**（目标在正右）：`fromAnchor: "right"` -> `toAnchor: "left"`
|
||||
- **垂直下沉推进**（目标在正下）：`fromAnchor: "bottom"` -> `toAnchor: "top"`
|
||||
- **跨层斜切推进**（目标在左下或右下）：首选 **`fromAnchor: "bottom"` -> `toAnchor: "top"`**。由于线段自身带有重力倾向，从底部出线再弯曲进入下一层顶部，完美契合流水线的 S 型大弯，能画出最优雅顺滑的跨层曲线。**避免**使用左右锚点互相跨接。
|
||||
- **逆流回捞**（底部发散回指顶部原点）：首选 **`fromAnchor: "top"` -> `toAnchor: "bottom"`** 配合 `lineStyle: "dashed"`。
|
||||
40
.claude/skills/lark-whiteboard/elements/content.md
Normal file
40
.claude/skills/lark-whiteboard/elements/content.md
Normal file
@ -0,0 +1,40 @@
|
||||
# 内容规划
|
||||
|
||||
核心原则：**信息量匹配用户需求的详细程度。** 用户说"画一个简单架构图"就画简单的，说"画一个完整的微服务架构"才画复杂的。不要自作主张**过度展开**。
|
||||
|
||||
**用户 prompt 简短/模糊时**（如"画个漏斗图"、"画个架构图"），不要只输出字面内容。应适当补充该领域合理的内容
|
||||
|
||||
## 信息量参考
|
||||
|
||||
| 用户需求 | 合理的信息量 |
|
||||
|---------|------------|
|
||||
| "画一个简单的 XX 架构图" | 3 层，每层 2-3 节点，无侧边栏 |
|
||||
| "画一个 XX 架构图"（普通请求） | 3-4 层，每层 3-4 节点 |
|
||||
| "画一个完整/详细的 XX 架构图" | 4-5 层，每层 4-6 节点，可加侧边栏（侧边栏最多 2-3 项）|
|
||||
| 流程图 | 6-10 步骤 + 1-2 个条件分支 |
|
||||
| 对比表 | 4-6 个维度，每格 1-2 行说明 |
|
||||
| 组织架构 | 3-4 层，每个父节点下 2-4 个子节点 |
|
||||
|
||||
**节点文字**：标题 + 简短说明（如"用户服务\n注册登录和权限管理"），不要写长段落。说明 12 字以内为佳。
|
||||
|
||||
## 分组
|
||||
|
||||
每组 2-5 个节点。超过 5 个拆成子组。
|
||||
|
||||
## 连线预判
|
||||
|
||||
| 连线数 | 策略 |
|
||||
|--------|------|
|
||||
| ≤8 | 逐条画 |
|
||||
| 9-15 | 代表性连线 |
|
||||
| >15 | 层到层，或回退精简 |
|
||||
|
||||
## 精简触发条件
|
||||
|
||||
布局放不下时才精简：
|
||||
|
||||
| 问题 | 精简方式 |
|
||||
|------|---------|
|
||||
| 节点文字放不下 | 缩短描述文字 |
|
||||
| 一行节点超过 5 个 | 拆成两排或合并同类 |
|
||||
| 连线交叉 | 减少连线数量 |
|
||||
80
.claude/skills/lark-whiteboard/elements/image.md
Normal file
80
.claude/skills/lark-whiteboard/elements/image.md
Normal file
@ -0,0 +1,80 @@
|
||||
# 图片准备 (Image Preparation)
|
||||
|
||||
> 本文件说明如何在画板 DSL 中使用图片节点。进入任何含图片的场景前，必须先完成图片准备流程。
|
||||
|
||||
## 概述
|
||||
|
||||
画板 DSL 支持 `type: 'image'` 节点，但图片不能直接使用 URL 或其他域的 token，**必须先上传到目标画板获取 `whiteboard` 域 media token**，然后在 DSL 中引用。
|
||||
|
||||
**核心规则**：不管图片从哪来（本地文件、URL、文档中的 `docx_image` token、其他域的 Drive token），都必须通过 `docs +media-upload --parent-type whiteboard --parent-node <目标画板token>` 上传，拿到画板专属的 media token 后才能在 DSL 中使用。直接使用非 `whiteboard` 域的 token 会导致画板 API 报 500（错误码 2891001）或图片在文档中消失。
|
||||
|
||||
## Step 0：图片准备流程
|
||||
|
||||
### 1. 获取图片到本地
|
||||
|
||||
根据图片来源选择对应方式：
|
||||
|
||||
| 图片来源 | 获取方式 |
|
||||
|---------|---------|
|
||||
| 本地文件 | 直接使用 |
|
||||
| 网络 URL | `curl -L -o photo.jpg "<URL>"` |
|
||||
| 文档中的图片 token | `lark-cli docs +media-download --token <token> --output ./photo.png` |
|
||||
| 其他域的 Drive token | `lark-cli docs +media-download --token <token> --output ./photo.png` |
|
||||
|
||||
**图片源选择（需要搜索图片时）**：
|
||||
|
||||
| 图片源类型 | 说明 |
|
||||
|-------|------|
|
||||
| 免费版权图库 | 支持按关键词搜索，图片无版权风险（CC0 或类似协议），图库种类丰富（人物/动物/风景/美食/建筑等），关键词能精准匹配图片内容 |
|
||||
| 直接 URL | 用户提供或已知的图片链接，最可靠 |
|
||||
|
||||
**选择图库的必要条件**：
|
||||
- **版权合规**：图片必须无版权纠纷风险，避免使用需要付费授权或有使用限制的图库
|
||||
- **关键词搜索**：支持按关键词搜索并返回相关图片，确保图片内容与主题匹配
|
||||
- **内容丰富**：图库图片种类多、数量大，能覆盖常见主题（宠物、美食、景点、产品等）
|
||||
|
||||
**严禁使用随机占位图服务**：某些图库仅提供随机占位图，URL 中的关键词参数不会影响返回的图片内容，下载的图片与主题完全无关。
|
||||
|
||||
### 2. 校验图片
|
||||
|
||||
```bash
|
||||
ls -l *.jpg # 确认每张文件大小不同；若大小相同则内容可能重复，需重新下载
|
||||
```
|
||||
|
||||
**图片内容审查（必须执行）**：
|
||||
- 下载完成后，确认文件是真实图片而非 HTML 错误页：若某张图片大小 < 1KB，很可能是下载失败返回了 HTML 错误页，需重新下载
|
||||
- **图片内容正确性只能在渲染后验证**：生成 DSL 并本地渲染 PNG 后，必须查看渲染结果，确认每张图片内容与主题相关（如宠物主题的图片确实是宠物，而非建筑/风景等不相关内容）
|
||||
- 若发现图片内容与主题不符，必须用更精确的关键词重新下载并重新上传
|
||||
|
||||
### 3. 上传到目标画板
|
||||
|
||||
**必须**使用 `docs +media-upload --parent-type whiteboard` 上传：
|
||||
|
||||
```bash
|
||||
lark-cli docs +media-upload --file ./photo1.jpg --parent-type whiteboard --parent-node <whiteboard_token>
|
||||
# 响应: { "file_token": "<media_token>", ... }
|
||||
```
|
||||
|
||||
逐张上传，收集每个 media token：
|
||||
|
||||
```bash
|
||||
lark-cli docs +media-upload --file ./photo1.jpg --parent-type whiteboard --parent-node <whiteboard_token> # → <media_token_1>
|
||||
lark-cli docs +media-upload --file ./photo2.jpg --parent-type whiteboard --parent-node <whiteboard_token> # → <media_token_2>
|
||||
lark-cli docs +media-upload --file ./photo3.jpg --parent-type whiteboard --parent-node <whiteboard_token> # → <media_token_3>
|
||||
```
|
||||
|
||||
### 4. 在 DSL 中引用
|
||||
|
||||
```json
|
||||
{ "type": "image", "id": "img-1", "width": 240, "height": 160, "image": { "src": "<media_token_1>" } }
|
||||
```
|
||||
|
||||
## 常见错误
|
||||
|
||||
| 错误现象 | 原因 | 解决 |
|
||||
|---------|------|------|
|
||||
| 画板 API 返回 500（2891001） | 使用了非 `whiteboard` 域 token（如 `docx_image`、Drive file token） | 下载图片后用 `docs +media-upload --parent-type whiteboard` 重新上传 |
|
||||
| 画板 API 返回 500 | 图片上传到了其他画板 | 重新上传到目标画板 |
|
||||
| 画板在文档中图片消失 | 图片 token 的资源域与画板不匹配 | 确保图片通过 `--parent-type whiteboard --parent-node <画板token>` 上传 |
|
||||
| 图片裂开/无法显示 | token 无效或已过期 | 重新上传获取新 token |
|
||||
| 图片内容与主题无关 | 使用了随机占位图服务 | 改用免费版权图库服务 |
|
||||
374
.claude/skills/lark-whiteboard/elements/layout.md
Normal file
374
.claude/skills/lark-whiteboard/elements/layout.md
Normal file
@ -0,0 +1,374 @@
|
||||
# 布局系统
|
||||
|
||||
## 布局决策
|
||||
|
||||
> 不要靠关键词猜布局。先分析信息结构，再决定布局策略。
|
||||
> 本文件负责说明通用布局原则与骨架模板；字段语义看 `elements/schema.md`，完整场景范式看各 `scenes/*.md`。
|
||||
|
||||
总原则：**先定主布局，再定子布局。**
|
||||
|
||||
**快速判断**：
|
||||
- **Flex**：按层分、按区排
|
||||
- **Dagre**：关系网密、流程链主导
|
||||
- **绝对定位**：空间位置承载信息（地理方位、拓扑坐标、物理面板等），用脚本计算坐标
|
||||
- **默认选择**：拿不准时优先用 **Flex**
|
||||
|
||||
|
||||
**Dagre 版式统一原则**：
|
||||
1. Dagre 解决的是**拓扑关系**，不是自动把画布铺满。
|
||||
2. Dagre 作为子容器嵌套时，默认是不透明节点（Opaque Node），先根据内部拓扑计算自身包围盒，再作为原子节点参与父层布局。若需连线穿透边界，须声明 `layout: "dagre"` + `layoutOptions: { isCluster: true }`。
|
||||
3. 混合布局时，Flex 更适合负责分区与层次，Dagre 更适合负责局部复杂关系；但如果 Dagre 本身就是主布局，也完全可以直接承担整张图的主体拓扑。
|
||||
4. 选用 Dagre 前先看三件事：**最长链路方向、分支是否对称、是否有长回边/重试回路**。哪一项失衡，哪一项就会把包围盒撑歪。
|
||||
5. 长回边、失败重试、跨层返回等关系，优先收敛到局部；必要时拆成局部流程区或旁路说明，不要让一条边把整个 Dagre 宽度拉爆。
|
||||
6. 若 Dagre 产物在父容器中出现明显单侧留白、宽高失衡或内容只占很小一部分，必须调整 `rankdir`、重构拓扑，或在父层补充对称信息区，不能原样交付。
|
||||
|
||||
**读代码画架构图**：扫目录结构（按层分 → Flex；按功能模块分 → 看依赖方向）→ grep import（单向→Flex；网状→ Dagre 或 Flex + Dagre）→ 拿不准 → 默认 Flex。
|
||||
|
||||
> **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"`（绝对定位）的容器必须有明确的固定宽高！**
|
||||
|
||||
❌ 致命错误：
|
||||
```json
|
||||
{ "type": "frame", "layout": "none", "width": "fit-content", "height": "fit-content", "children": [
|
||||
{ "type": "rect", "x": 0, "y": 0, "text": "区域A" },
|
||||
{ "type": "rect", "x": 500, "y": 0, "text": "区域B" }
|
||||
]}
|
||||
```
|
||||
✅ 正确：必须给绝对定位容器明确的固定宽高：
|
||||
```json
|
||||
{ "type": "frame", "layout": "none", "width": 1064, "height": 680, "children": [
|
||||
{ "type": "rect", "x": 0, "y": 0, "text": "区域A" },
|
||||
{ "type": "rect", "x": 554, "y": 0, "text": "区域B" }
|
||||
]}
|
||||
```
|
||||
|
||||
**构建方式**：
|
||||
|
||||
| 布局类型 | 做法 |
|
||||
| ---------------------- | ----------------------------------------------------------------------------- |
|
||||
| 纯 Flex / Dagre | 直接写 JSON |
|
||||
| 混合布局 (Flex包Dagre) | 直接写 JSON（外层先做分区，局部复杂关系交给 Dagre；若被嵌套，默认为不透明节点） |
|
||||
| 极度依赖几何坐标的图 | 写脚本生成 JSON（node xxx.cjs） |
|
||||
| 需要精确避让的特殊线 | 脚本 + `--layout` 两阶段 |
|
||||
|
||||
---
|
||||
|
||||
## 网格方法论
|
||||
|
||||
核心理念：**先画网格，再填内容**。
|
||||
|
||||
先回答三个问题：
|
||||
1. **信息分几行几列？** 每组一行或一列
|
||||
2. **每格多大？** 等宽还是有主次？
|
||||
3. **行列间距多大？** 分区间 24-32px，同区内 12-16px
|
||||
|
||||
---
|
||||
|
||||
## 布局模式选择
|
||||
|
||||
| 模式 | 适用场景 | DSL 映射 |
|
||||
| ---- | ---------------------------- | -------------------------------------------------------- |
|
||||
| grid | 架构图、对比表、卡片墙、看板 | vertical frame 嵌套 horizontal frame |
|
||||
| flow | 复杂流程图、微服务交互 | `layout: "dagre"`，由引擎自动计算网状连线排版 |
|
||||
| tree | 组织架构、模块依赖 | `layout: "dagre"` 配 `rankdir: "TB"` 或根节点居中的 Flex |
|
||||
| free | 地理位置布局、物理面板还原 | `layout: "none"` + x/y |
|
||||
|
||||
大多数图表用 grid 或 flow 模式。只有节点坐标本身有强语义（如地图）时才用 free。
|
||||
|
||||
> 以上都是布局策略名称，DSL 的 `layout` 属性值只支持 `'horizontal'`、`'vertical'`、`'none'`、`'dagre'` 四种。
|
||||
|
||||
---
|
||||
|
||||
## DSL 与 CSS Flexbox 属性映射
|
||||
|
||||
| DSL 属性 | 对应的 CSS 心智模型 | 限制 |
|
||||
| -------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| `layout: 'horizontal'` | `flex-direction: row` | 不写 layout = 绝对定位 |
|
||||
| `layout: 'vertical'` | `flex-direction: column` | 同上 |
|
||||
| `layout: 'none'` | `position: absolute`（子节点用 x/y） | 子节点不能用 `fill-container`；容器必须有固定宽高 |
|
||||
| `layout: 'dagre'` | 类似 Mermaid / DOT 的有向图布局 | 宽高只支持 `fit-content`；先按拓扑算包围盒再参与父层布局；嵌套时默认为不透明节点 |
|
||||
| `width/height: 'fill-container'` | `flex: 1`（主轴）/ `align-self: stretch`（交叉轴） | 祖先必须有确定尺寸 |
|
||||
| `width/height: 'fit-content'` | `width/height: auto` | — |
|
||||
| `alignItems` | 同 CSS `align-items` | 仅 `'start'`/`'center'`/`'end'`/`'stretch'`（无 flex- 前缀） |
|
||||
| `justifyContent` | 同 CSS `justify-content` | 仅 `'start'`/`'center'`/`'end'`/`'space-between'`/`'space-around'` |
|
||||
| `gap` | 同 CSS `gap` | 必须显式写（不写节点会粘连） |
|
||||
| `padding` | 同 CSS `padding` | 必须显式写。支持 `number` / `[v,h]` / `[t,r,b,l]` |
|
||||
|
||||
`alignItems` 默认值为 `'start'`（CSS Flexbox 默认 `stretch`）。需要等高卡片时必须显式写 `alignItems: 'stretch'`。
|
||||
DSL 的语法是严格白名单，不能写原生 CSS 属性（不支持 `alignSelf`、`flexWrap`、`margin` 等）。
|
||||
|
||||
---
|
||||
|
||||
## DSL 注意事项
|
||||
|
||||
1. **frame 必须写 layout 属性**，不写时子节点全堆在左上角。
|
||||
|
||||
2. **fill-container 死锁陷阱**：使用 `fill-container` 时，祖先链中必须有固定宽度（或高度），否则和 `fit-content` 形成死锁，尺寸退化为 0。
|
||||
错误示例：
|
||||
```json
|
||||
{ "type": "frame", "layout": "horizontal", "width": "fit-content", "children": [
|
||||
{ "type": "rect", "width": "fill-container" }
|
||||
]}
|
||||
```
|
||||
正确示例：
|
||||
```json
|
||||
{ "type": "frame", "layout": "horizontal", "width": 1200, "children": [
|
||||
{ "type": "rect", "width": "fill-container" }
|
||||
]}
|
||||
```
|
||||
3. **不要给 Dagre 套固定宽高的外框**：Dagre 产物尺寸由拓扑决定，无法提前预知。父容器应使用 `fit-content` 自适应，或直接让 Dagre 作为顶层容器，不要用固定像素框住它。
|
||||
4. **`layout: 'none'` 的容器必须有固定宽高**，不要写成 `fit-content`，否则子节点绝对定位容易错乱。
|
||||
5. **含文字节点高度用 fit-content**，引擎不支持 overflow，写死高度会截断文字。
|
||||
6. **Shape 节点有内边距**：rect/ellipse/diamond/triangle 各边 12px；cylinder 垂直 +42px。
|
||||
7. **不支持 flex-wrap**，需要换行时用嵌套 frame 模拟。
|
||||
8. **图层顺序**：数组中越靠后的节点层级越高。需要叠加标注时放在数组最后。
|
||||
|
||||
---
|
||||
|
||||
## 布局选择指南
|
||||
|
||||
| 你要表达的关系 | 怎么排 | DSL 写法 |
|
||||
| -------------------------- | ------------------------ | ---------------------------------------------------------------------------- |
|
||||
| 先后顺序、层级从上到下 | 纵向堆叠 | `layout: 'vertical'` |
|
||||
| 并列、同等重要、可对比 | 横向等分 | `layout: 'horizontal'` + `alignItems: 'stretch'` + `width: 'fill-container'` |
|
||||
| 区域有名称，名称在侧边 | 侧标签 + 内容并排 | 横向 frame: [text(标签), frame(内容)] |
|
||||
| 多个大分区，各自独立 | 分区纵向排列 | 纵向 frame 包多个彩色 frame |
|
||||
| 一行放不下，需要换行 | 嵌套横向 frame 模拟换行 | 纵向 frame 包多个横向 frame |
|
||||
| 复杂的网状关系、拓扑图 | **Dagre 有向图自动布局** | `layout: 'dagre'` + `layoutOptions.edges` |
|
||||
| 节点位置本身有含义（地图） | 绝对定位 | `layout: 'none'` + x/y |
|
||||
|
||||
这些可以自由嵌套组合。比如：纵向堆叠(标题) + 分区纵向排列(多个层) + 每个层内横向等分(节点)。
|
||||
|
||||
---
|
||||
|
||||
## 布局示例
|
||||
|
||||
### 纵向堆叠（标题 + 内容）
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "layout": "vertical", "gap": 28, "padding": 32,
|
||||
"width": 1200, "height": "fit-content",
|
||||
"children": [
|
||||
{ "type": "text", "width": "fill-container", "height": "fit-content",
|
||||
"text": "图表标题", "fontSize": 24, "textAlign": "center" },
|
||||
...内容...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 横向等分（并列元素）
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "layout": "horizontal", "gap": 16, "padding": 0,
|
||||
"width": "fill-container", "height": "fit-content",
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{ "type": "rect", "width": "fill-container", "height": "fit-content",
|
||||
"textAlign": "center", "verticalAlign": "middle", "text": "A" },
|
||||
{ "type": "rect", "width": "fill-container", "height": "fit-content",
|
||||
"textAlign": "center", "verticalAlign": "middle", "text": "B" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`alignItems: 'stretch'` + `width: 'fill-container'` = 等宽等高。
|
||||
|
||||
### 侧标签 + 内容
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "layout": "horizontal", "gap": 24, "padding": 0,
|
||||
"width": "fill-container", "height": "fit-content",
|
||||
"alignItems": "center",
|
||||
"children": [
|
||||
{ "type": "text", "width": 160, "height": "fit-content",
|
||||
"text": "区域名称", "fontSize": 20, "textColor": "#1F2329", "textAlign": "right" },
|
||||
{ "type": "frame", "width": "fill-container", "height": "fit-content",
|
||||
...区域内容...
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
不要用 frame 的 `title` 属性做标签——渲染为极小标题栏，不可读。
|
||||
|
||||
### 分区纵向排列
|
||||
|
||||
把内容划分为几个大区域，每个区域用不同颜色区分（颜色从 style 文件的色板选取）：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "layout": "vertical", "gap": 28, "padding": 0,
|
||||
"width": "fill-container", "height": "fit-content",
|
||||
"children": [
|
||||
{ "type": "frame", "borderRadius": 8,
|
||||
"layout": "horizontal", "gap": 16, "padding": 20, ...区域1... },
|
||||
{ "type": "frame", "borderRadius": 8,
|
||||
"layout": "horizontal", "gap": 16, "padding": 20, ...区域2... }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 模拟换行
|
||||
|
||||
一行放不下时，拆成多个横向 frame：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "layout": "vertical", "gap": 8, "padding": 0,
|
||||
"children": [
|
||||
{ "type": "frame", "layout": "horizontal", "gap": 8, "padding": 0,
|
||||
"children": [item1, item2, item3, item4] },
|
||||
{ "type": "frame", "layout": "horizontal", "gap": 8, "padding": 0,
|
||||
"children": [item5, item6] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 复杂拓扑混合布局 (Dagre + Flex)
|
||||
|
||||
当你在处理**连线众多、关系杂乱的拓扑图 / 链路流程图 / 复杂架构图**时，不用手动去算每个节点坐标，优先考虑 **Flex + Dagre 的混合布局策略**。这主要包含两种维度的嵌套：
|
||||
|
||||
* **外层 Dagre + 内层 Flex（复杂节点）**：**这是最推荐的复杂架构画法**。整图拓扑交由 `layout: "dagre"` 自动计算并顺滑布线，而图中的节点不再只是单调的矩形，可以是一个用 Flex 自由拼装的复杂 `frame` 卡片（包含图标、主次标题、状态等），让节点承载更丰富的信息。
|
||||
* **外层 Flex + 内层 Dagre（局部流程）**：外层用 Flex 或绝对定位划分大的业务区域，而某个特定区域内部放入 `layout: "dagre"` 容器负责处理局部的业务流。
|
||||
* **嵌套前先做宽度预判**：Dagre 会根据拓扑尽情往两侧撑出包围盒。如果可能横跨导致溢出，优先改 `rankdir` 为 `TB`、缩短文案、调小 `nodesep/ranksep`，必要时将超长的链路拆成分步区。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "id": "arch_root",
|
||||
"layout": "dagre", "padding": 40,
|
||||
"width": "fit-content", "height": "fit-content",
|
||||
"layoutOptions": {
|
||||
"rankdir": "LR", "nodesep": 60, "ranksep": 100,
|
||||
"edges": [
|
||||
["client", "auth_svc", "request"],
|
||||
["auth_svc", "order_svc"],
|
||||
["order_svc", "order_db"]
|
||||
]
|
||||
},
|
||||
"children": [
|
||||
{
|
||||
"type": "frame", "id": "client",
|
||||
"layout": "vertical", "gap": 6, "padding": [12, 16],
|
||||
"alignItems": "center",
|
||||
"fillColor": "#F8FAFC", "borderColor": "#CBD5E1", "borderWidth": 2, "borderRadius": 10,
|
||||
"children": [
|
||||
{ "type": "text", "text": "Client App", "fontSize": 14, "textColor": "#0F172A" },
|
||||
{ "type": "text", "text": "React 18", "fontSize": 10, "textColor": "#64748B" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame", "id": "cluster_gateway",
|
||||
"layout": "dagre", "layoutOptions": { "isCluster": true, "clusterTitle": "Gateway Tier", "clusterTitleColor": "#15803D" },
|
||||
"fillColor": "#F0FDF4", "borderColor": "#86EFAC",
|
||||
"borderWidth": 2, "borderDash": "dashed", "borderRadius": 16,
|
||||
"children": [
|
||||
{ "type": "rect", "id": "auth_svc", "width": 120, "height": 40, "text": "Auth Service", "fillColor": "#DCFCE7", "borderColor": "#86EFAC", "borderWidth": 1, "borderRadius": 6, "fontSize": 12 },
|
||||
{ "type": "rect", "id": "order_svc", "width": 120, "height": 40, "text": "Order Service", "fillColor": "#DCFCE7", "borderColor": "#86EFAC", "borderWidth": 1, "borderRadius": 6, "fontSize": 12 }
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame", "id": "order_db",
|
||||
"layout": "vertical", "gap": 4, "padding": [10, 14],
|
||||
"alignItems": "center",
|
||||
"fillColor": "#FFFFFF", "borderColor": "#FECACA", "borderWidth": 2, "borderRadius": 10,
|
||||
"children": [
|
||||
{ "type": "cylinder", "width": 50, "height": 36, "fillColor": "#FCA5A5", "borderColor": "#DC2626", "borderWidth": 1 },
|
||||
{ "type": "text", "text": "Order DB", "fontSize": 12, "textColor": "#7F1D1D" }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**示例要点**：
|
||||
- `client` 和 `order_db` 是 **Flex 复合节点**（不透明节点），内部用 vertical 布局组合多行信息，对外层 Dagre 是固定宽高的原子。
|
||||
- `cluster_gateway` 是 **透明子图**（`layout: "dagre"` + `isCluster: true`），外部连线可穿越边界直达 `auth_svc` 和 `order_svc`。
|
||||
- 所有 `edges` 统一写在最外层根 Dagre 的 `layoutOptions` 中。
|
||||
|
||||
**Dagre 嵌套排版规则**：
|
||||
|
||||
1. **不透明节点（Opaque Node）**：Dagre 内的子容器，无论其内部 layout 是 flex、absolute 还是 dagre，只要未声明 isCluster: true，对外层 Dagre 就是具有确定宽高的不透明原子节点。外层连线无法寻址其内部子节点。
|
||||
2. **连线兜底重定向（Edge Redirect Fallback）**：当 edges 引用了某不透明节点内部的子节点 ID 时，引擎自动将该连线端点重定向至其最近的不透明祖先节点。不报错，不产生悬空连线。
|
||||
3. **透明子图（Compound Cluster）**：子容器同时声明 `layout: "dagre"` 与 `layoutOptions: { isCluster: true }` 时，成为外层 Dagre 的复合子图。其内部子节点直接参与外层拓扑运算，连线可穿越子图边界。子图自身不执行独立排版，尺寸由外层 Dagre 根据内部节点包围盒自动撑开。
|
||||
|
||||
---
|
||||
|
||||
## 绝对定位
|
||||
|
||||
当节点位置本身有含义（拓扑图、地图、时间线轴）时用绝对定位。大多数图表优先用 Flex。
|
||||
|
||||
### 混合布局
|
||||
|
||||
模块内部用 Flex 自动排版，模块之间用绝对定位自由摆放。注意：承载这些模块的 `layout: "none"` 父容器必须先给出**固定宽高**，再在里面摆放子模块。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "layout": "none", "width": 1200, "height": 800,
|
||||
"children": [
|
||||
{
|
||||
"type": "frame", "id": "module-a", "x": 100, "y": 100,
|
||||
"width": 300, "height": "fit-content",
|
||||
"layout": "vertical", "gap": 8, "padding": 16,
|
||||
"children": [
|
||||
{ "type": "rect", "width": "fill-container", "height": "fit-content", "text": "内容1" },
|
||||
{ "type": "rect", "width": "fill-container", "height": "fit-content", "text": "内容2" }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 两阶段绘图
|
||||
|
||||
先出骨架图导出坐标，再基于坐标补充连线和注解：
|
||||
|
||||
```bash
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.13 -i skeleton.json -o step1.png -l coords.json
|
||||
```
|
||||
|
||||
`coords.json` 包含每个带 id 节点的精确坐标（absX, absY, width, height）。
|
||||
|
||||
---
|
||||
|
||||
## 常用间距和尺寸
|
||||
|
||||
| 参数 | 常用范围 | 说明 |
|
||||
| ---------------- | ----------- | ------------ |
|
||||
| 整图宽度 | 1000-1400px | — |
|
||||
| 分区之间间距 | 24-32px | — |
|
||||
| 同分区内节点间距 | 12-16px | — |
|
||||
| 有连线的节点间距 | >= 40px | 给箭头留空间 |
|
||||
| 分区内边距 | 16-24px | — |
|
||||
| 侧标签宽度 | 120-180px | — |
|
||||
|
||||
---
|
||||
|
||||
## 等大卡片
|
||||
|
||||
一排卡片需要等宽等高时，不要写固定像素：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "layout": "horizontal", "gap": 16, "padding": 0,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{ "type": "rect", "width": "fill-container", "height": "fit-content", "text": "A" },
|
||||
{ "type": "rect", "width": "fill-container", "height": "fit-content", "text": "B" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`alignItems: 'stretch'` + `width: 'fill-container'` = 等宽等高。
|
||||
357
.claude/skills/lark-whiteboard/elements/schema.md
Normal file
357
.claude/skills/lark-whiteboard/elements/schema.md
Normal file
@ -0,0 +1,357 @@
|
||||
# DSL Schema
|
||||
|
||||
> 本文件只说明 **DSL 里能写什么**：节点类型、字段、枚举值、硬约束。布局策略、组合方法、Dagre/Flex 心智模型统一放在 `elements/layout.md`。
|
||||
> `?` 表示该字段在 schema 层是 optional；若需要稳定产出，再参考对应 scene 或 layout 文件中的最佳实践。
|
||||
|
||||
**📝 布局引擎核心法则**：
|
||||
- **基本行为与 Flexbox 等同**：Frame 布局基于 Yoga 引擎。`layout: 'horizontal'` = `flex-direction: row`，`fill-container` = `flex: 1`，`fit-content` = `width: auto`，`gap` / `padding` / `alignItems` / `justifyContent` 语义相同。
|
||||
- **枚举值无 flex- 前缀**：一律使用 `'start'` / `'end'` 而非原生 CSS 的 `'flex-start'` / `'flex-end'`。
|
||||
- **默认对齐的差异**：`alignItems` 的默认值是 `'start'`（原生 CSS 默认是 `stretch`）。所以同排卡片需要等高时，**必须显式声名** `alignItems: 'stretch'`。
|
||||
- **Dagre 引擎的特殊性**：`layout: 'dagre'` 作为专属拓扑连线引擎，自身不支持 `fill-container` 宽高，对其父容器而言，它是一个自适应（打包裹）的黑盒。
|
||||
|
||||
## WBDocument
|
||||
|
||||
```typescript
|
||||
interface WBDocument {
|
||||
version: 2;
|
||||
nodes: WBNode[]; // 顶层节点。connector 必须放在这里，不能嵌套在 children 中
|
||||
}
|
||||
```
|
||||
|
||||
## 节点类型
|
||||
|
||||
### Frame（容器）
|
||||
|
||||
唯一可以包含子节点的类型。用于分组、布局、背景。
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'frame';
|
||||
id?: string;
|
||||
x?: number; y?: number; // Flex 子节点不需要 x/y
|
||||
width: WBSizeValue;
|
||||
height: WBSizeValue;
|
||||
layout: 'horizontal' | 'vertical' | 'none' | 'dagre'; // 布局模式
|
||||
gap: number; // 必须显式写（不写节点会粘连，容易出 bug）
|
||||
padding: number | [number, number] | [number, number, number, number]; // 必须显式写（不写内容贴边）
|
||||
justifyContent?: 'start' | 'center' | 'end' | 'space-between' | 'space-around';
|
||||
alignItems?: 'start' | 'center' | 'end' | 'stretch';
|
||||
layoutOptions?: { // 仅当 layout 为 'dagre' 时生效
|
||||
rankdir?: 'TB' | 'BT' | 'LR' | 'RL';
|
||||
nodesep?: number;
|
||||
edgesep?: number;
|
||||
ranksep?: number;
|
||||
edges?: Array<[string, string] | [string, string, string]>; // [fromId, toId, label?] 引擎自动排版子节点并生成贝塞尔曲线连线
|
||||
isCluster?: boolean; // 透明子图。为 true 时子节点参与父级 Dagre 拓扑运算，连线可穿越边界
|
||||
clusterTitle?: string; // 子图悬浮标题（自动吸附左上角）
|
||||
clusterTitleColor?: string; // 标题颜色 (HEX格式，如 "#8B5CF6")
|
||||
};
|
||||
fillColor?: string;
|
||||
borderColor?: string;
|
||||
borderWidth?: number;
|
||||
borderDash?: 'solid' | 'dashed' | 'dotted';
|
||||
borderRadius?: number;
|
||||
children?: WBNode[]; // 不能包含 connector
|
||||
}
|
||||
```
|
||||
|
||||
**Dagre 嵌套排版规则**：
|
||||
|
||||
1. **不透明节点（Opaque Node）**：Dagre 内的子容器，无论 `layout` 是 `flex`、`absolute` 还是 `dagre`，只要未声明 `isCluster: true`，对外层 Dagre 就是具有确定宽高的不透明原子节点。外层连线无法寻址其内部子节点。
|
||||
2. **连线兜底重定向（Edge Redirect Fallback）**：当 `edges` 引用了某不透明节点内部的子节点 ID 时，引擎自动将该连线端点重定向至其最近的不透明祖先节点。不报错，不产生悬空连线。
|
||||
3. **透明子图（Compound Cluster）**：子容器同时声明 `layout: "dagre"` 与 `layoutOptions: { isCluster: true }` 时，成为外层 Dagre 的复合子图。其内部子节点直接参与外层拓扑运算，连线可穿越子图边界。子图自身不执行独立排版，尺寸由外层 Dagre 根据内部节点包围盒自动撑开。
|
||||
|
||||
**isCluster 最小用法**：
|
||||
```json
|
||||
{
|
||||
"type": "frame", "id": "cluster_a",
|
||||
"layout": "dagre", "layoutOptions": { "isCluster": true },
|
||||
"fillColor": "#F0FDF4", "borderColor": "#86EFAC", "borderWidth": 2, "borderDash": "dashed", "borderRadius": 16,
|
||||
"children": [
|
||||
{ "type": "text", "text": "区域标题", "fontSize": 11, "textColor": "#15803D" },
|
||||
{ "type": "rect", "id": "node_inside", "width": 120, "height": 40, "text": "内部节点" }
|
||||
]
|
||||
}
|
||||
```
|
||||
> 注意：`edges` 必须写在**最外层的根 Dagre** 的 `layoutOptions` 中，不要写在 cluster 内部。
|
||||
**其他约束**：
|
||||
- `layout / gap / padding` 在 schema 层是 optional，但实际生成时推荐显式写出，避免依赖默认行为。
|
||||
- `layoutOptions` 仅在 `layout: 'dagre'` 时生效。
|
||||
- `children` 里不能出现 `connector`。
|
||||
|
||||
> **虚拟 frame 陷阱**：没有 `fillColor`、`borderColor`、`borderWidth` 的 frame 在编译时可能被当作纯布局容器跳过（子节点直接提升到父级）。如果给这种 frame 设了 `id` 并让外部 connector 连接它，编译后 frame 消失，connector 引用会失效。需要保留这个 frame 时，请给它加上不会被优化掉的外观属性。
|
||||
|
||||
### 基础图形
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'rect' | 'ellipse' | 'cylinder' | 'diamond' | 'triangle' | 'trapezoid';
|
||||
id?: string;
|
||||
x?: number; y?: number;
|
||||
opacity?: number; // 0-1，仅影响 fillColor 的透明度（对 frame/text/stickyNote 无效）
|
||||
vFlip?: boolean;
|
||||
hFlip?: boolean;
|
||||
width: WBSizeValue;
|
||||
height: WBSizeValue;
|
||||
fillColor?: string;
|
||||
borderColor?: string;
|
||||
borderWidth?: number;
|
||||
borderDash?: 'solid' | 'dashed' | 'dotted';
|
||||
borderRadius?: number;
|
||||
topWidth?: number; // 仅对 triangle / trapezoid 有效，梯形顶边宽度或三角形顶角截断宽度
|
||||
text?: string | WBTextRun[]; // 纯文本或富文本
|
||||
fontSize?: number;
|
||||
textColor?: string;
|
||||
textAlign?: 'left' | 'center' | 'right'; // Shape 默认 'center'（与 CSS 不同）
|
||||
verticalAlign?: 'top' | 'middle' | 'bottom'; // Shape 默认 'middle'（与 CSS 不同）
|
||||
}
|
||||
```
|
||||
|
||||
> **cylinder 约束**：cylinder 的弧度固定 16px，不随宽度缩放。宽度过大会变成扁椭圆。禁止 `width: "fill-container"`，必须用固定宽度 + `height: "fit-content"`。宽度根据文字长度选择，通常 120-200px。
|
||||
|
||||
> **Shape 内边距（TEXT_INSET）**：Shape 节点有强制内边距，fit-content 会自动补偿。
|
||||
> - rect / ellipse / diamond / triangle：上下左右各 12px
|
||||
> - cylinder：顶部弧形 32px + 底部弧形 10px（垂直 +42px），水平各 7px
|
||||
>
|
||||
> 需要手算固定尺寸时：`实际文字宽/高 + 对应 inset`。
|
||||
> 例：rect 内 14px 字号两行文字高 ~32px → `height >= 32 + 24 = 56px`
|
||||
|
||||
### Image（图片节点）
|
||||
|
||||
图片节点用于在画板中展示图片。图片不能直接使用 URL，必须先上传到飞书获取 media token。
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'image';
|
||||
id?: string;
|
||||
x?: number; y?: number;
|
||||
width: WBSizeValue; // 固定宽度，推荐 240 或 200
|
||||
height: WBSizeValue; // 固定高度，推荐按 3:2 比例（如 240×160 或 200×133）
|
||||
image: {
|
||||
src: string; // media token（通过 docs +media-upload --parent-type whiteboard 上传获取）
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
> **关键约束**：
|
||||
> - `image.src` 必须是通过 `docs +media-upload --parent-type whiteboard --parent-node <画板token>` 上传后返回的 **media token**，不能是 URL 或 Drive file token
|
||||
> - 图片必须上传到**目标画板**，跨画板的 token 不可用
|
||||
> - 同一画板内所有 image 节点应使用统一的 width/height，保持视觉一致
|
||||
> - 图片宽高比推荐 3:2（如 240×160），避免变形
|
||||
> - 详细上传流程见 [`elements/image.md`](../elements/image.md)
|
||||
|
||||
### Text（纯文本节点）
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'text';
|
||||
id?: string;
|
||||
x?: number; y?: number;
|
||||
width: WBSizeValue;
|
||||
height: WBSizeValue;
|
||||
text?: string | WBTextRun[];
|
||||
fontSize?: number;
|
||||
textColor?: string;
|
||||
textAlign?: 'left' | 'center' | 'right';
|
||||
verticalAlign?: 'top' | 'middle' | 'bottom';
|
||||
}
|
||||
```
|
||||
|
||||
### StickyNote（便签）
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'stickyNote';
|
||||
id?: string;
|
||||
x?: number; y?: number;
|
||||
width: WBSizeValue;
|
||||
height: WBSizeValue;
|
||||
fillColor?: '#FEF1CE' | '#F5D1A7' | '#DFF5E5' | '#CDF7CC' | '#C9E8EF' | '#D6DCF3' | '#D3CCEE' | '#F1C5E7' | '#F6C8C8'; // 便签底色（仅支持这 9 种）
|
||||
text?: string | WBTextRun[];
|
||||
fontSize?: number;
|
||||
textColor?: string;
|
||||
textAlign?: 'left' | 'center' | 'right';
|
||||
verticalAlign?: 'top' | 'middle' | 'bottom';
|
||||
}
|
||||
```
|
||||
|
||||
### Connector（连线）
|
||||
|
||||
必须放在顶层 `nodes` 数组中，不能嵌套在 frame 的 `children` 里。
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'connector';
|
||||
id?: string;
|
||||
connector: {
|
||||
from: string | { x: number; y: number }; // 节点 id 或坐标
|
||||
to: string | { x: number; y: number };
|
||||
fromAnchor?: 'top' | 'right' | 'bottom' | 'left';
|
||||
toAnchor?: 'top' | 'right' | 'bottom' | 'left';
|
||||
lineShape?: 'straight' | 'polyline' | 'curve' | 'rightAngle'; // 直线、圆角折线、曲线、直角折线
|
||||
lineColor?: string;
|
||||
lineWidth?: number;
|
||||
lineStyle?: 'solid' | 'dashed' | 'dotted';
|
||||
startArrow?: 'none' | 'arrow' | 'triangle' | 'circle' | 'diamond';
|
||||
endArrow?: 'none' | 'arrow' | 'triangle' | 'circle' | 'diamond';
|
||||
waypoints?: { x: number; y: number }[]; // polyline 途经点
|
||||
label?: string; // 连线中间的标签文字
|
||||
labelPosition?: number; // 标签位置，0-1，默认 0.5（中点）
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### SVG
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'svg';
|
||||
id?: string;
|
||||
x?: number; y?: number;
|
||||
opacity?: number;
|
||||
width: WBSizeValue;
|
||||
height: WBSizeValue;
|
||||
svg: { code: string }; // SVG 代码字符串
|
||||
}
|
||||
```
|
||||
|
||||
#### 渲染规范
|
||||
|
||||
SVG 通过 `image/svg+xml` Blob 加载到画布，**不在 HTML DOM 中**，因此存在严格限制：
|
||||
|
||||
**必须**：
|
||||
- 包含 `viewBox` 属性（如 `viewBox="0 0 24 24"`），引擎依赖它确定坐标系
|
||||
- 包含 `xmlns="http://www.w3.org/2000/svg"`（SVG 作为独立 `image/svg+xml` 解析时，XML 规范要求声明命名空间）
|
||||
|
||||
**允许的元素**（纯几何绘制）：
|
||||
- 基本图形：`<rect>` `<circle>` `<ellipse>` `<line>` `<polyline>` `<polygon>` `<path>`
|
||||
- 渐变/滤镜：`<defs>` `<linearGradient>` `<radialGradient>` `<filter>` `<feGaussianBlur>` `<feMerge>`
|
||||
- 结构：`<g>` `<clipPath>` `<mask>` `<use>`
|
||||
|
||||
**禁止的元素**（字体和外部资源在 Blob 沙箱中无法加载）：
|
||||
- `<text>` `<tspan>`（用同层 DSL rect 节点 + text 属性替代）
|
||||
- `<image>`（用同层 DSL image 节点替代）
|
||||
- `<foreignObject>`
|
||||
- 任何引用外部 URL 的属性（`xlink:href` 指向远程资源等）
|
||||
|
||||
#### 两种典型用法
|
||||
|
||||
**1. 背景装饰 SVG**（大尺寸，与 frame 同大小）
|
||||
|
||||
用于绘制连线、曲线、发光效果等几何背景。文字信息通过同一 frame 内的 rect 节点叠加：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "width": 1400, "height": 680, "layout": "none",
|
||||
"children": [
|
||||
{ "type": "svg", "x": 0, "y": 0, "width": 1400, "height": 680,
|
||||
"svg": { "code": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1400 680\" ...>...</svg>" } },
|
||||
{ "type": "rect", "x": 100, "y": 50, "width": 200, "height": 40,
|
||||
"text": "Label", "fillColor": "transparent" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**2. 内联图标 SVG**（24-48px，Feather/Lucide 风格）
|
||||
|
||||
用于卡片/按钮中的小图标，纯 stroke 线条：
|
||||
|
||||
```json
|
||||
{ "type": "svg", "width": 32, "height": 32,
|
||||
"svg": { "code": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"#3B82F6\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"12\" cy=\"12\" r=\"10\"/><polyline points=\"12 6 12 12 16 14\"/></svg>" } }
|
||||
```
|
||||
|
||||
### Icon（内置图标）
|
||||
|
||||
引用画板内置图标库的图标。比手写 SVG 更简单——只需指定 `name`。
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: 'icon';
|
||||
id?: string;
|
||||
x?: number; y?: number;
|
||||
width?: WBSizeValue; // 默认 48
|
||||
height?: WBSizeValue; // 默认 48，保持正方形
|
||||
name: string; // 图标名称，从 npx -y @larksuite/whiteboard-cli@^0.2.13 --icons 输出中选取
|
||||
color?: string; // 可选颜色覆盖，hex 格式如 '#FF6600'
|
||||
}
|
||||
```
|
||||
|
||||
**获取可用图标**：规划好内容和布局后，运行以下命令查看所有可用图标名，从中选取：
|
||||
```bash
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.13 --icons
|
||||
```
|
||||
|
||||
用法：
|
||||
```json
|
||||
{ "type": "icon", "id": "db", "name": "database", "width": 48, "height": 48 }
|
||||
```
|
||||
|
||||
**使用建议**：
|
||||
- 当图表中的节点代表具体事物（服务器、用户、数据库等）时，用图标比纯文字方块更直观
|
||||
- 一张图 3-8 个图标为宜，为关键组件配图标，次要节点用普通形状
|
||||
- 用 `color` 为图标指定合适的颜色, 比如与所在容器的配色一致
|
||||
- 图标可放在 frame 子元素中参与 flex 布局，连线可通过 id 连接到图标
|
||||
- 图标+文字组合：frame(vertical) 中放 icon + text，形成富组件
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "layout": "vertical", "gap": 8, "padding": 12,
|
||||
"alignItems": "center", "fillColor": "#F0F5FF", "borderColor": "#ADC6FF",
|
||||
"children": [
|
||||
{ "type": "icon", "id": "db-icon", "name": "database", "width": 36, "height": 36 },
|
||||
{ "type": "text", "text": "PostgreSQL", "fontSize": 12, "width": "fit-content", "height": "fit-content" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 富文本 WBTextRun
|
||||
|
||||
`text` 字段可以是纯字符串或 `WBTextRun[]` 数组。类似 HTML 内联样式：bold 对应 `<b>`，italic 对应 `<i>`，listType 对应 `<ol>/<ul>`。每个 run 是一段带样式的文字：
|
||||
|
||||
```typescript
|
||||
interface WBTextRun {
|
||||
content: string; // 文字内容，可含 \n 换行
|
||||
bold?: boolean;
|
||||
italic?: boolean;
|
||||
underline?: boolean;
|
||||
strikeThrough?: boolean;
|
||||
fontSize?: number;
|
||||
color?: string; // 文字颜色
|
||||
backgroundColor?: string; // 文字高亮背景
|
||||
hyperlink?: string;
|
||||
listType?: 'none' | 'ordered' | 'unordered';
|
||||
indent?: number; // 缩进级数
|
||||
quote?: boolean; // 引用块
|
||||
}
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"text": [
|
||||
{ "content": "标题文字\n", "bold": true, "fontSize": 16 },
|
||||
{ "content": "正文内容，", "fontSize": 14 },
|
||||
{ "content": "高亮部分", "backgroundColor": "#FEF1CE", "fontSize": 14 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`text` 和 `content` 中出现的双引号必须写成 `\"`，这是 JSON 规范要求。换行用 `\n`（JSON 中写为 `"第一行\n第二行"`，不要双重转义为 `\\n`）。
|
||||
|
||||
---
|
||||
|
||||
## 尺寸值 WBSizeValue
|
||||
|
||||
| 值 | 含义 | 注意 |
|
||||
| --------------------- | --------------------------- | -------------------------------------- |
|
||||
| `number` | 固定像素 | 任何场景 |
|
||||
| `'fit-content'` | 由内容决定大小 | 父级需要 Flex 布局 |
|
||||
| `'fit-content(N)'` | 同上，无内容时 fallback N | 同上 |
|
||||
| `'fill-container'` | 填满父级剩余空间 | 父级需要 Flex 布局，且祖先链有固定宽度 |
|
||||
| `'fill-container(N)'` | 同上，无 Flex 时 fallback N | — |
|
||||
|
||||
`fill-container` 在 `layout: 'none'`（绝对定位）下无效。`fit-content` 仍可用于含文字节点（引擎通过 Yoga measureFunc 测量文字尺寸）。
|
||||
318
.claude/skills/lark-whiteboard/elements/style.md
Normal file
318
.claude/skills/lark-whiteboard/elements/style.md
Normal file
@ -0,0 +1,318 @@
|
||||
# 配色系统
|
||||
|
||||
## 怎么上色（最重要）
|
||||
|
||||
上色步骤：
|
||||
|
||||
1. **找出图中有几个分组**（层级、分支、类别、阶段...）
|
||||
2. **为每个分组选一种不同颜色**（从色板中选 2-4 种颜色）
|
||||
3. **分组容器**用浅色填充 — 告诉读者"这块是一个整体"
|
||||
4. **分组内节点**用白色填充 + 该分组的深色 borderColor — 告诉读者"这些属于这个分组"
|
||||
|
||||
具体映射（经典色板）：
|
||||
|
||||
| 分组 | 层容器 fillColor | 层容器 borderColor | 内部节点 borderColor |
|
||||
|------|----------------|-------------------|---------------------|
|
||||
| 第 1 组 | #F0F4FC（浅蓝） | #5178C6 | #5178C6 |
|
||||
| 第 2 组 | #EAE2FE（浅紫） | #8569CB | #8569CB |
|
||||
| 第 3 组 | #DFF5E5（浅绿） | #509863 | #509863 |
|
||||
| 第 4 组 | #FEF1CE（浅黄） | #D4B45B | #D4B45B |
|
||||
| 第 5 组 | #FEE3E2（浅红） | #D25D5A | #D25D5A |
|
||||
| 内部节点 | #FFFFFF | 跟随所属分组 | — |
|
||||
|
||||
**各类图表怎么上色**：
|
||||
- 架构图有 3 层 → 每层一种颜色，层背景浅色填充，层内节点白色+深色边框
|
||||
- 对比表有 3 列 → 每列表头一种颜色，该列数据单元格用同色边框
|
||||
- 组织架构有 4 个部门 → 每个部门一种颜色，子部门白色+同色边框
|
||||
- 流程图 → 起止节点一种颜色，判断节点一种颜色，步骤节点白色
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **用户配色优先。** 用户指定了色值/风格时以用户为准。用户只给 1-2 个色值时，推导完整色板：主色→浅底→深边框→灰调连线色。
|
||||
> 用户**未指定**配色时，必须从上方色板表中选取颜色，不要使用表中没有的自创色值（如 `#E8F3FF`、`#1664FF`、`#14C9C9` 等都不在色板中）。
|
||||
|
||||
---
|
||||
|
||||
## 结构规则
|
||||
|
||||
### 分组 — 不同层/分组必须用不同颜色
|
||||
|
||||
选 2-4 种颜色，每种代表一个分组。同组节点视觉完全一致（fillColor、borderColor 相同）。
|
||||
|
||||
### 分层 — 外重内轻
|
||||
|
||||
- 外层（大分区）：浅色填充背景
|
||||
- 内层（具体节点）：白色填充 + 分组色边框
|
||||
|
||||
### 清晰
|
||||
|
||||
- 所有节点有边框（borderWidth=2）
|
||||
- 间距不粘连（gap >= 8，有连线时 >= 40）
|
||||
- 文字在背景上清晰可读（fontSize >= 14）。文字与背景色对比度应足够（参考 WCAG 2.1：正文至少 4.5:1，标题至少 3:1）
|
||||
- 不要仅靠颜色区分信息——同时使用边框、形状或文字标签辅助，确保色觉障碍用户也能理解
|
||||
- 连线用灰色（#BBBFC4），不抢节点注意力
|
||||
|
||||
### 统一参数
|
||||
|
||||
| 参数 | 值 | 为什么 |
|
||||
|------|---|--------|
|
||||
| borderWidth | 2 | 让边框清晰可见 |
|
||||
| borderRadius | 8 | 统一的圆角，整洁 |
|
||||
| gap（最小值） | 8 | 元素不粘连 |
|
||||
| padding（最小值） | 8 | 内容不贴边 |
|
||||
| gap（有连线时） | 40 | 给箭头留空间 |
|
||||
| fontSize（正文） | >= 14 | 可读 |
|
||||
| fontSize（标题） | >= 24 | 醒目 |
|
||||
| fontSize（辅助） | >= 13 | 不费眼 |
|
||||
|
||||
---
|
||||
|
||||
## 色板选择指南
|
||||
|
||||
根据用户需求的关键词或场景选择合适的色板。未指定时默认使用"经典"色板。
|
||||
|
||||
| 色板 | 适用场景 | 关键词 |
|
||||
|------|---------|-------|
|
||||
| 经典 | 通用图表、说明文档 | 默认、通用 |
|
||||
| 商务 | 汇报、企业架构、正式文档 | 专业、正式、给老板看 |
|
||||
| 科技 | 技术架构、DevOps、监控 | 技术、炫酷、暗色 |
|
||||
| 清新 | 流程图、用户旅程、教程 | 清新、自然、轻松 |
|
||||
| 极简 | 论文配图、学术报告 | 学术、极简、黑白 |
|
||||
|
||||
---
|
||||
|
||||
## 预设色板
|
||||
|
||||
每套色板定义 7 个角色的颜色。**连线色是色板的一部分**，不同色板的连线色不同。
|
||||
|
||||
### 经典
|
||||
|
||||
| 角色 | fillColor | borderColor | textColor |
|
||||
|------|-----------|-------------|-----------|
|
||||
| 分区背景 | #F0F4FC | #5178C6 | #1F2329 |
|
||||
| 分组标题 | #EAE2FE | #8569CB | #1F2329 |
|
||||
| 内容节点 | #FFFFFF | #5178C6 | #1F2329 |
|
||||
| 第二分组 | #DFF5E5 | #509863 | #1F2329 |
|
||||
| 第三分组 | #FEF1CE | #D4B45B | #1F2329 |
|
||||
| 第四分组 | #FEE3E2 | #D25D5A | #1F2329 |
|
||||
| 强调/表头 | #1F2329 | #1F2329 | #FFFFFF |
|
||||
| 连线 | -- | -- | #BBBFC4 |
|
||||
|
||||
### 商务
|
||||
|
||||
| 角色 | fillColor | borderColor | textColor |
|
||||
|------|-----------|-------------|-----------|
|
||||
| 分区背景 | #EDF2F7 | #4A6FA5 | #1A202C |
|
||||
| 分组标题 | #D4E0ED | #4A6FA5 | #1A202C |
|
||||
| 内容节点 | #FFFFFF | #718BAE | #1A202C |
|
||||
| 第二分组 | #E8EDF3 | #5A7B9A | #1A202C |
|
||||
| 第三分组 | #F0F0F0 | #8895A7 | #1A202C |
|
||||
| 强调/表头 | #2D4A7A | #2D4A7A | #FFFFFF |
|
||||
| 连线 | -- | -- | #718BAE |
|
||||
|
||||
### 科技
|
||||
|
||||
| 角色 | fillColor | borderColor | textColor |
|
||||
|------|-----------|-------------|-----------|
|
||||
| 画布/分区背景 | #0F172A | #1E293B | #E2E8F0 |
|
||||
| 分组标题 | #1E293B | #3B82F6 | #E2E8F0 |
|
||||
| 内容节点 | #1E293B | #334155 | #E2E8F0 |
|
||||
| 第二分组 | #1E293B | #8B5CF6 | #E2E8F0 |
|
||||
| 第三分组 | #1E293B | #10B981 | #E2E8F0 |
|
||||
| 强调 | #2563EB | #3B82F6 | #FFFFFF |
|
||||
| 连线 | -- | -- | #475569 |
|
||||
|
||||
### 清新
|
||||
|
||||
| 角色 | fillColor | borderColor | textColor |
|
||||
|------|-----------|-------------|-----------|
|
||||
| 分区背景 | #F0FDF4 | #86EFAC | #14532D |
|
||||
| 分组标题 | #DCFCE7 | #4ADE80 | #14532D |
|
||||
| 内容节点 | #FFFFFF | #86EFAC | #14532D |
|
||||
| 第二分组 | #ECFDF5 | #6EE7B7 | #14532D |
|
||||
| 第三分组 | #F0FDFA | #5EEAD4 | #134E4A |
|
||||
| 强调 | #16A34A | #16A34A | #FFFFFF |
|
||||
| 连线 | -- | -- | #86EFAC |
|
||||
|
||||
### 极简
|
||||
|
||||
| 角色 | fillColor | borderColor | textColor |
|
||||
|------|-----------|-------------|-----------|
|
||||
| 分区背景 | #F8F9FA | #DEE2E6 | #212529 |
|
||||
| 分组标题 | #E9ECEF | #ADB5BD | #212529 |
|
||||
| 内容节点 | #FFFFFF | #CED4DA | #212529 |
|
||||
| 第二分组 | #F1F3F5 | #868E96 | #212529 |
|
||||
| 第三分组 | #F8F9FA | #ADB5BD | #212529 |
|
||||
| 强调/表头 | #495057 | #495057 | #FFFFFF |
|
||||
| 连线 | -- | -- | #ADB5BD |
|
||||
|
||||
---
|
||||
|
||||
## 各元素怎么画
|
||||
|
||||
> 以下示例使用经典色板。如果选了其他色板，替换对应颜色即可，结构保持不变。
|
||||
|
||||
### 图表标题
|
||||
|
||||
告诉读者"这张图讲什么"。大号深色文字，居中。
|
||||
|
||||
```json
|
||||
{ "type": "text", "fontSize": 24, "textColor": "#1F2329", "textAlign": "center" }
|
||||
```
|
||||
|
||||
### 分区背景
|
||||
|
||||
把相关的内容圈在一起，告诉读者"这些属于同一个大类"。浅色做 fillColor，对应深色做 borderColor。内部放白色节点。
|
||||
|
||||
```json
|
||||
{ "fillColor": "#F0F4FC", "borderColor": "#5178C6", "borderWidth": 2, "borderRadius": 8, "padding": 20 }
|
||||
```
|
||||
|
||||
### 分区标签
|
||||
|
||||
给分区一个名字。用独立 text 节点，不要用 frame 的 `title` 属性（会被渲染为极小标题栏）。
|
||||
|
||||
**所有分区标签统一用深色文字 `#1F2329`**，不要给每个标签用不同颜色——颜色区分通过层容器背景和边框体现，标签文字颜色保持一致。
|
||||
|
||||
```json
|
||||
{ "type": "text", "width": 180, "height": "fit-content", "text": "Access layer", "fontSize": 20, "textColor": "#1F2329", "textAlign": "right" }
|
||||
```
|
||||
|
||||
### 分组标题
|
||||
|
||||
告诉读者"这个子分组叫什么"。色板色填充 + 同色系深色边框。
|
||||
|
||||
```json
|
||||
{ "fillColor": "#EAE2FE", "borderColor": "#8569CB", "borderWidth": 2, "borderRadius": 8, "fontSize": 14, "textColor": "#1F2329" }
|
||||
```
|
||||
|
||||
### 内容节点
|
||||
|
||||
具体的信息项。白色填充，边框颜色跟随所属分组。
|
||||
|
||||
```json
|
||||
{ "fillColor": "#FFFFFF", "borderColor": "#5178C6", "borderWidth": 2, "borderRadius": 8, "fontSize": 14, "textColor": "#1F2329" }
|
||||
```
|
||||
|
||||
白色节点的 borderColor 取决于它所属的分组：
|
||||
```
|
||||
属于蓝色分组: fillColor="#FFFFFF" borderColor="#5178C6" borderWidth=2
|
||||
属于紫色分组: fillColor="#FFFFFF" borderColor="#8569CB" borderWidth=2
|
||||
独立节点: fillColor="#FFFFFF" borderColor="#DEE0E3" borderWidth=2
|
||||
```
|
||||
（注：以上为经典色板的值，其他色板替换对应的 borderColor）
|
||||
|
||||
### 表头
|
||||
|
||||
告诉读者"这一列/行是什么维度"。深色填充 + 白色文字。
|
||||
|
||||
```json
|
||||
{ "fillColor": "#1F2329", "borderColor": "#1F2329", "borderWidth": 2, "borderRadius": 0, "fontSize": 15, "textColor": "#FFFFFF", "textAlign": "center" }
|
||||
```
|
||||
|
||||
### 图标组件
|
||||
|
||||
icon + text 的组合卡片。icon 的 `color` 跟随所属分组的 borderColor，与其他节点视觉一致。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "layout": "vertical", "gap": 4, "padding": 12,
|
||||
"alignItems": "center", "fillColor": "#FFFFFF", "borderColor": "#5178C6", "borderWidth": 2, "borderRadius": 8,
|
||||
"children": [
|
||||
{ "type": "icon", "name": "server", "width": 36, "height": 36, "color": "#5178C6" },
|
||||
{ "type": "text", "width": "fit-content", "height": "fit-content", "text": "应用服务器", "fontSize": 12 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
icon color 需要结合上下文选择合适的颜色, 比如: 使用所属分组的borderColor
|
||||
|
||||
### textColor 规则
|
||||
|
||||
```
|
||||
- 正文：#1F2329（深色，在白底/浅色底上清晰）
|
||||
- 辅助说明：#646A73（弱化，不抢注意力）
|
||||
- 深色底上：#FFFFFF（反色，清晰可读）
|
||||
（以上为经典色板的值，其他色板参考对应 textColor 列）
|
||||
```
|
||||
|
||||
### 辅助说明
|
||||
|
||||
补充信息，不抢主角的注意力。灰色小字。
|
||||
|
||||
```json
|
||||
{ "fontSize": 13, "textColor": "#646A73" }
|
||||
```
|
||||
|
||||
### 连线
|
||||
|
||||
表达元素之间的关系或流向。使用色板中的连线色。
|
||||
|
||||
```json
|
||||
{ "lineColor": "#BBBFC4", "lineWidth": 2 }
|
||||
```
|
||||
|
||||
### 布局容器
|
||||
|
||||
纯粹用来排版的 frame，读者看不见它。不设 fillColor、borderColor。
|
||||
|
||||
```json
|
||||
{ "type": "frame", "layout": "vertical", "gap": 28, "padding": 32 }
|
||||
```
|
||||
|
||||
### 分组容器
|
||||
|
||||
用虚线框圈定一组节点，比分区背景更轻量。
|
||||
|
||||
```json
|
||||
{ "borderColor": "#DEE0E3", "borderWidth": 2, "borderDash": "dashed", "borderRadius": 8 }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见错误
|
||||
|
||||
错误：每个节点一种颜色 -> 读者分不清谁和谁是一组
|
||||
```json
|
||||
{ "fillColor": "#8569CB" }, { "fillColor": "#5178C6" }, { "fillColor": "#509863" }
|
||||
```
|
||||
正确：同组节点视觉一致 -> 读者一眼看出关系
|
||||
```json
|
||||
{ "fillColor": "#FFFFFF", "borderColor": "#8569CB" }, { "fillColor": "#FFFFFF", "borderColor": "#8569CB" }
|
||||
```
|
||||
|
||||
错误：内外层都用重色 -> 读者不知道先看哪里
|
||||
```json
|
||||
{ "type": "frame", "fillColor": "#5178C6", "children": [{ "fillColor": "#8569CB" }] }
|
||||
```
|
||||
正确：外层浅色内层白色 -> 读者先看结构再看细节
|
||||
```json
|
||||
{ "type": "frame", "fillColor": "#F0F4FC", "children": [{ "fillColor": "#FFFFFF", "borderColor": "#5178C6" }] }
|
||||
```
|
||||
|
||||
错误：连线用和节点一样的彩色 -> 和节点颜色抢注意力
|
||||
```json
|
||||
{ "connector": { "lineColor": "#5178C6" } }
|
||||
```
|
||||
正确：连线用色板中的连线色 -> 衬托节点
|
||||
```json
|
||||
{ "connector": { "lineColor": "#BBBFC4" } }
|
||||
```
|
||||
|
||||
错误：节点没边框 -> 和背景融为一体，看不清边界
|
||||
```json
|
||||
{ "fillColor": "#FFFFFF" }
|
||||
```
|
||||
正确：节点有边框 -> 边界清晰
|
||||
```json
|
||||
{ "fillColor": "#FFFFFF", "borderColor": "#DEE0E3", "borderWidth": 2 }
|
||||
```
|
||||
|
||||
错误：全图黑白灰，没有颜色区分 -> 读者无法快速识别分组
|
||||
```json
|
||||
{ "fillColor": "#FFFFFF", "borderColor": "#DEE0E3" }
|
||||
```
|
||||
正确：不同分组用不同颜色 -> 一眼看出结构（蓝色分组 + 紫色分组）
|
||||
```json
|
||||
{ "fillColor": "#F0F4FC", "borderColor": "#5178C6" }
|
||||
{ "fillColor": "#EAE2FE", "borderColor": "#8569CB" }
|
||||
```
|
||||
73
.claude/skills/lark-whiteboard/elements/typography.md
Normal file
73
.claude/skills/lark-whiteboard/elements/typography.md
Normal file
@ -0,0 +1,73 @@
|
||||
# 排版规则
|
||||
|
||||
## 字号层级表
|
||||
|
||||
| 层级 | 字号 | 用途 | 对齐 |
|
||||
|------|------|------|------|
|
||||
| H1 | 24-28 | 图表标题（每图一个） | center |
|
||||
| H2 | 18-20 | 分区/层标签 | right（侧标签）或 center（顶部标签） |
|
||||
| H3 | 15-16 | 分组标题、卡片标题 | center 或 left |
|
||||
| Body | 14 | 正文、节点文字 | center（短标签）或 left（长文本） |
|
||||
| Caption | 13 | 辅助说明、注解 | left |
|
||||
|
||||
规则：
|
||||
- 同张图不超过 3 个字号层级
|
||||
- 同级节点 fontSize 必须完全相同
|
||||
- 相邻层级字号差 >= 4px
|
||||
|
||||
---
|
||||
|
||||
## 对齐规则
|
||||
|
||||
Shape 节点默认 `textAlign: 'center'` + `verticalAlign: 'middle'`（与 CSS 相反）。如需左对齐须显式声明。
|
||||
|
||||
| 内容类型 | 对齐方式 |
|
||||
|---------|---------|
|
||||
| 短文本（<=15 字） | center |
|
||||
| 长文本（>15 字） | left |
|
||||
| 侧标签（层名、分区名） | right |
|
||||
| 图表标题 | center |
|
||||
| 多行描述/段落 | left |
|
||||
|
||||
---
|
||||
|
||||
## 图表标题
|
||||
|
||||
用独立 text 节点，不要用 frame 的 `title` 属性。
|
||||
|
||||
- Flex 布局：放在最外层 frame 的第一个 child，`width: "fill-container"`
|
||||
- 绝对定位：width 设为图表整体宽度，`textAlign: "center"`
|
||||
|
||||
---
|
||||
|
||||
## 标题和描述拆成两个节点
|
||||
|
||||
一个卡片内展示名称和描述时，用 frame 包两个 text 节点，不要塞进同一个 shape：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "frame", "layout": "vertical", "gap": 4, "padding": 12,
|
||||
"width": "fill-container", "height": "fit-content",
|
||||
"borderWidth": 2, "borderRadius": 8,
|
||||
"children": [
|
||||
{ "type": "text", "width": "fill-container", "height": "fit-content",
|
||||
"text": "用户服务", "fontSize": 16 },
|
||||
{ "type": "text", "width": "fill-container", "height": "fit-content",
|
||||
"text": "处理注册登录和个人信息管理", "fontSize": 13 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 图标+文字组合
|
||||
|
||||
icon + text 纵向排列时：icon 宽高 36-48px，下方文字 fontSize 12-13，外层 frame gap 4-8。icon 比文字大 2-3 倍时视觉比例最佳。
|
||||
|
||||
---
|
||||
|
||||
## 尺寸规则
|
||||
|
||||
含文字节点 `height` 必须用 `'fit-content'`。写死高度会截断文字。
|
||||
|
||||
所有节点必须显式声明 `width` 和 `height`。
|
||||
@ -0,0 +1,60 @@
|
||||
# whiteboard +export（导出画板）
|
||||
|
||||
> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
导出画板内容，支持导出为预览图片、SVG 矢量图、提取 PlantUML/Mermaid 代码，或获取飞书 OpenAPI 原生画板节点格式。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|----------------------|----|------------------------------------------------------------------------|
|
||||
| `--whiteboard-token` | 是 | 画板 token，需要拥有画板的读权限 |
|
||||
| `--output-type` | 是 | 输出格式：`preview`（预览图片）、`svg`（SVG 矢量图）、`source`（PlantUML/Mermaid 代码）、`raw`（OpenAPI 原生画板节点格式） |
|
||||
| `--output` | 否 | 输出路径。当 `--output-type preview` 时必填，推荐传入无后缀文件路径（如 `./preview`）；当 `--output-type svg/source/raw` 时可选，不填则直接输出到终端 |
|
||||
| `--overwrite` | 否 | 覆盖已存在的文件，默认为 false |
|
||||
|
||||
## 输出格式
|
||||
|
||||
- `preview`：预览图片。推荐 `--output ./preview` 这类无后缀文件路径，CLI 会按实际图片类型保存为 `./preview.png` 或 `./preview.jpg`。如果 `--output` 是目录，会保存为该目录下的 `whiteboard_<whiteboard-token>.png/.jpg`；如果显式写了后缀，需要和实际图片类型匹配。`--overwrite` 检查的是补齐后缀后的最终路径，例如返回 PNG 时 `--output ./preview` 对应覆盖 `./preview.png`。
|
||||
- `svg`：导出画板为标准 SVG 矢量图。可用于 SVG 编辑后回写画板（见 [`routes/svg-edit.md`](../routes/svg-edit.md)）。注意：导出为纯视觉快照，思维导图层级、表格结构、连接器绑定等语义信息会丢失。
|
||||
- `source`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。
|
||||
- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)。
|
||||
|
||||
## 示例
|
||||
|
||||
### 示例 1：导出画板为预览图片
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +export \
|
||||
--whiteboard-token "wbcnxxxxxxxx" \
|
||||
--output-type preview \
|
||||
--output ./preview
|
||||
```
|
||||
|
||||
### 示例 2：提取画板中的代码并直接输出
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +export \
|
||||
--whiteboard-token "wbcnxxxxxxxx" \
|
||||
--output-type source
|
||||
```
|
||||
|
||||
### 示例 3：导出画板为 SVG 矢量图
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +export \
|
||||
--whiteboard-token "wbcnxxxxxxxx" \
|
||||
--output-type svg \
|
||||
--output ./whiteboard.svg \
|
||||
--as user
|
||||
```
|
||||
|
||||
### 示例 4：导出画板原始节点结构到文件
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +export \
|
||||
--whiteboard-token "wbcnxxxxxxxx" \
|
||||
--output-type raw \
|
||||
--output ./nodes.json \
|
||||
--overwrite
|
||||
```
|
||||
@ -0,0 +1,122 @@
|
||||
# whiteboard +update（更新画板）
|
||||
|
||||
> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
更新画板内容，支持四种输入格式：
|
||||
|
||||
- `raw`：飞书 OpenAPI 原生画板节点格式，不推荐直接编辑。
|
||||
- `plantuml`：PlantUML 代码
|
||||
- `mermaid`：Mermaid 代码
|
||||
- `svg`：SVG 文本
|
||||
|
||||
输入内容可以通过管道从 stdin 读取，或通过 `--source` 指定文件。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|----------------------|----|--------------------------------------------|
|
||||
| `--whiteboard-token` | 是 | 画板 token，需要拥有画板的编辑权限 |
|
||||
| `--idempotent-token` | 否 | 幂等 token，确保更新操作幂等；最少 10 个字符，建议使用时间戳 + 场景标识拼接（如 `1744800000-board-1`）。同一次逻辑更新只生成一次该 token，重试时须原样复用；切勿在每次重试时重新生成时间戳或幂等 key，否则会重复写入 |
|
||||
| `--overwrite` | 否 | 覆盖更新，在更新前删除所有现有内容，默认为 false |
|
||||
| `--source` | 是 | 输入画板内容，支持使用 `@path` 从文件读取，或 `-` 从 stdin 读取 |
|
||||
| `--input_format` | 否 | 输入格式：`raw`、`plantuml`、`mermaid`、`svg`，默认为 `raw` |
|
||||
|
||||
### 以 raw (OpenAPI 原生画板节点格式) 创作
|
||||
|
||||
**不要以直接生成 json 语法的方式创作 raw 格式的飞书 OpenAPI 原生画板节点参数**
|
||||
|
||||
思维导图，时序图，类图，饼图，流程图等图表推荐使用 Mermaid/PlantUML 语法绘制。
|
||||
|
||||
而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板) 使用 whiteboard-cli 工具创作。
|
||||
|
||||
## 示例
|
||||
|
||||
### 示例 1：使用 PlantUML 代码更新画板（从 stdin 读取）
|
||||
|
||||
```bash
|
||||
# 编写 PlantUML 代码
|
||||
cat > diagram.puml << 'EOF'
|
||||
@startuml
|
||||
Alice -> Bob: Hello
|
||||
Bob -> Alice: Hi
|
||||
@enduml
|
||||
EOF
|
||||
|
||||
# 通过管道传递给命令
|
||||
cat diagram.puml | lark-cli whiteboard +update \
|
||||
--whiteboard-token <画板Token> \
|
||||
--input_format plantuml --source -\
|
||||
--overwrite --as user
|
||||
```
|
||||
|
||||
### 示例 2：使用 Mermaid 代码更新画板（从文件读取）
|
||||
|
||||
```bash
|
||||
# 编写 Mermaid 代码
|
||||
cat > diagram.mmd << 'EOF'
|
||||
graph TD
|
||||
A[开始] --> B{判断}
|
||||
B -->|是| C[处理]
|
||||
B -->|否| D[结束]
|
||||
C --> D
|
||||
EOF
|
||||
|
||||
# 从文件读取并更新
|
||||
lark-cli whiteboard +update \
|
||||
--whiteboard-token <画板Token> \
|
||||
--input_format mermaid \
|
||||
--source @./diagram.mmd \
|
||||
--overwrite --as user
|
||||
```
|
||||
|
||||
### 示例 3：使用 whiteboard-cli 生成 OpenAPI 格式并写入画板
|
||||
|
||||
whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
|
||||
|
||||
```bash
|
||||
# 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.13 -i <产物文件> --to openapi --format json \
|
||||
| lark-cli whiteboard +update \
|
||||
--whiteboard-token <画板Token> \
|
||||
--source - --input_format raw \
|
||||
--idempotent-token <10+字符唯一串> \
|
||||
--as user
|
||||
```
|
||||
|
||||
### 示例 4：先生成产物文件，再从文件读取更新
|
||||
|
||||
whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
|
||||
|
||||
```bash
|
||||
# 生成 OpenAPI 格式到文件
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.13 -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 --as user
|
||||
```
|
||||
|
||||
### 示例 5：使用 SVG 写入画板（从文件读取）
|
||||
|
||||
适用于从零创建（直接写入 SVG）和编辑现有画板（编辑工作流详见 [`../routes/svg-edit.md`](../routes/svg-edit.md)）。
|
||||
|
||||
```bash
|
||||
# 编写或导出 SVG 文件
|
||||
cat > diagram.svg << 'EOF'
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100">
|
||||
<rect x="10" y="10" width="80" height="40" fill="#4A90E2"/>
|
||||
<text x="50" y="35" text-anchor="middle" fill="#fff">Hello</text>
|
||||
</svg>
|
||||
EOF
|
||||
|
||||
# 从文件读取并更新
|
||||
lark-cli whiteboard +update \
|
||||
--whiteboard-token <画板Token> \
|
||||
--input_format svg \
|
||||
--source @./diagram.svg \
|
||||
--overwrite --as user
|
||||
```
|
||||
@ -0,0 +1,87 @@
|
||||
# 画板创作/修改工作流
|
||||
|
||||
## 创作 Workflow
|
||||
|
||||
> 此 workflow 用于**独立创作一个画板**。
|
||||
> 需要在文档中批量创建多个画板时，由 lark-doc 负责调度，见 `lark-doc` 技能的 `references/lark-doc-whiteboard.md`。
|
||||
|
||||
**Step 1：获取 board_token**
|
||||
|
||||
| 用户给了什么 | 怎么获取 |
|
||||
|---|---|
|
||||
| 直接给了 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> --command append --content '<whiteboard type="blank"></whiteboard>' --as user`，从响应 `data.new_blocks[0].block_token` 取得（`block_type == "whiteboard"` 的那条；参数详见 lark-doc SKILL.md）|
|
||||
|
||||
**Step 2：渲染 & 写入**
|
||||
|
||||
→ 进入 **[§ 渲染 & 写入画板](#渲染--写入画板)** 章节，按流程完成后直接返回结果给用户。
|
||||
|
||||
---
|
||||
|
||||
## 修改 Workflow
|
||||
|
||||
**Step 1：获取 board_token**（同创作 Workflow Step 1）
|
||||
|
||||
**Step 2：判断修改策略**
|
||||
|
||||
```
|
||||
+export --output-type source
|
||||
├─ 返回 Mermaid/PlantUML 代码
|
||||
│ → 在原代码上修改 → +update --input_format mermaid/plantuml
|
||||
├─ 无代码（SVG/DSL 或其他方式绘制的画板）
|
||||
│ ├─ 需纯新增（思维导图、流程图、时序图、类图、饼图、甘特图）图表节点
|
||||
│ │ → +export --output-type preview → 看图 → +export --output-type raw → 确定新节点坐标和层级 → [§ 渲染 & 写入画板]
|
||||
│ └─ 其他改动（几何变动/增删元素/结构调整/混合编辑等）
|
||||
│ → [`../routes/svg-edit.md`](../routes/svg-edit.md)（视觉高保真还原，大部分场景适用）
|
||||
└─ 用户有明确要求 → 以用户要求优先
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 渲染 & 写入画板
|
||||
|
||||
### 渲染路由
|
||||
|
||||
**先自报身份**：按训练来源，你属于哪一家？`Claude` / `Gemini` / `GPT` / `GLM` / `Doubao 或 Seed` / `Other`。身份决定 SVG / DSL 分流（不同家族对这两种表达语言的能力不均衡），不要跳过这一步。
|
||||
|
||||
**然后按图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
|
||||
|
||||
按上到下匹配, 命中即停:
|
||||
|
||||
| 图表类型 | 身份 | 路径 |
|
||||
|--------------------|-------------------------------------|------------------------------------------------|
|
||||
| 思维导图、时序图、类图、饼图、甘特图 | 任何身份 | [`../routes/mermaid.md`](../routes/mermaid.md) |
|
||||
| 鱼骨图、金字塔图、流程图 | `Doubao` / `Seed` | [`../routes/dsl.md`](../routes/dsl.md) |
|
||||
| 其他图表 | `Claude` / `Gemini` / `GPT` / `GLM` / `Doubao` / `Seed` | [`../routes/svg.md`](../routes/svg.md) |
|
||||
| 其他图表 | `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 ← 渲染结果
|
||||
```
|
||||
|
||||
### 写入画板
|
||||
|
||||
写入画板时按最终产物类型选择 `+update --input_format`：
|
||||
|
||||
- Mermaid / PlantUML / SVG 产物直接用对应的 `mermaid` / `plantuml` / `svg` 写入。
|
||||
- 只有 DSL 产物或已明确需要 OpenAPI 原生节点格式时，才先用 `npx -y @larksuite/whiteboard-cli@^0.2.13 --to openapi --format json` 转换，再用 `raw` 写入。
|
||||
|
||||
具体命令示例、`--overwrite`、`--idempotent-token` 和 `--as user/bot` 的使用方式，统一参考 [`whiteboard +update`](./lark-whiteboard-update.md)。
|
||||
107
.claude/skills/lark-whiteboard/routes/dsl.md
Normal file
107
.claude/skills/lark-whiteboard/routes/dsl.md
Normal file
@ -0,0 +1,107 @@
|
||||
# DSL 路径
|
||||
|
||||
> **这是画板，不是网页。** 画板是无限画布上自由放置元素，flex 布局是可选增强。
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
Step 1: 路由 & 读取知识
|
||||
- 读对应 scene 指南 — 了解结构特征和布局策略
|
||||
- 确定布局策略（见下方快速判断）和构建方式
|
||||
- 读 elements/ 核心模块 — 语法、布局、配色、排版、连线
|
||||
|
||||
Step 2: 生成完整 DSL（含颜色）
|
||||
- 按 content.md 规划信息量和分组
|
||||
- 按 layout.md 选择布局模式和间距
|
||||
- 推荐使用图标让图表更直观，运行 `npx -y @larksuite/whiteboard-cli@^0.2.13 --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.13 -i diagram.json -o diagram.png
|
||||
- 检查：信息完整？布局合理？配色协调？文字无截断？连线无交叉？
|
||||
- 有问题 → 按症状表修复 → 重新渲染（最多 2 轮）
|
||||
- 2 轮后仍有严重问题 → 考虑走 Mermaid 路径兜底
|
||||
- 写入画板：用 whiteboard-cli 将 diagram.json 转换为 OpenAPI 格式并 pipe 给 +update：
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.13 -i diagram.json --to openapi --format json \
|
||||
| lark-cli whiteboard +update --whiteboard-token <board_token> \
|
||||
--source - --input_format raw --idempotent-token <时间戳+标识> --as user
|
||||
→ 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)
|
||||
- 交付：向用户报告 board_token 写入成功
|
||||
```
|
||||
|
||||
**布局策略快速判断**（详见 `elements/layout.md`）：
|
||||
|
||||
先定**主布局**，再定子布局：**结构化信息**优先用 Flex，**关系链路**优先用 Dagre，**灵活定位**用绝对布局。
|
||||
|
||||
> **构建方式是强约束**：当 scene 指南要求"脚本生成"时，必须先写脚本（`.cjs`，CommonJS）并用 `node` 执行来产出 JSON 文件。
|
||||
|
||||
## 模块索引
|
||||
|
||||
### 核心参考（必读）
|
||||
|
||||
| 模块 | 文件 | 说明 |
|
||||
| -------- |----------------------------| ------------------------------- |
|
||||
| DSL 语法 | `elements/schema.md` | 节点类型、属性、尺寸值 |
|
||||
| 内容规划 | `elements/content.md` | 信息提取、密度决策、连线预判 |
|
||||
| 布局系统 | `elements/layout.md` | 网格方法论、Flex 映射、间距规则 |
|
||||
| 排版规则 | `elements/typography.md` | 字号层级、对齐、行距 |
|
||||
| 连线系统 | `elements/connectors.md` | 拓扑规划、锚点选择 |
|
||||
| 配色系统 | `elements/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` | 业务流、状态机、带条件判断的链路 |
|
||||
| 图片展示 | `scenes/photo-showcase.md` | 用户显式要求图片/配图/插图时（需先完成 `elements/image.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
.claude/skills/lark-whiteboard/routes/mermaid.md
Normal file
27
.claude/skills/lark-whiteboard/routes/mermaid.md
Normal 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.13 -i diagram.mmd -o diagram.png
|
||||
4. 审查 PNG，有问题修改后重新渲染（最多 2 轮）
|
||||
5. 写入画板：用 whiteboard-cli 将 diagram.mmd 转换为 OpenAPI 格式并 pipe 给 +update：
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.13 -i diagram.mmd --to openapi --format json \
|
||||
| lark-cli whiteboard +update --whiteboard-token <board_token> \
|
||||
--source - --input_format raw --idempotent-token <时间戳+标识> --as user
|
||||
→ 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)
|
||||
6. 交付：向用户报告 board_token 写入成功
|
||||
```
|
||||
85
.claude/skills/lark-whiteboard/routes/svg-edit.md
Normal file
85
.claude/skills/lark-whiteboard/routes/svg-edit.md
Normal file
@ -0,0 +1,85 @@
|
||||
# SVG 编辑路径
|
||||
|
||||
通过导出画板的 SVG → 编辑 SVG → 回写画板，实现对已有画板的可视化编辑。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 有损性警告
|
||||
|
||||
SVG 导出是**纯视觉快照**，再次导入后画板语义（思维导图层级/表格结构/连线绑定/容器类型/mention/节点 ID/锁定/评论）会丢失。
|
||||
|
||||
**保留的信息**：形状几何（位置/大小/路径）、文本内容与基本格式（字号/粗体/斜体/对齐）、填充色/描边色/透明度（线性渐变降级为第一个 stop-color 纯色）、连接器路径形状与箭头样式、`<g>` 嵌套的基本分组关系（≥2 子元素时重建为 DirectFocusGroup）。
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### 0. 用户确认（强制）
|
||||
|
||||
在执行任何编辑前，**必须**向用户说明：
|
||||
|
||||
> SVG 编辑只保证视觉层面对齐，画板语义（层级/节点类型/思维导图结构/表格结构/连线绑定/容器类型/mention 等）将不可恢复，是否继续？
|
||||
|
||||
**用户未确认前不得执行后续步骤。**
|
||||
|
||||
### 1. 导出当前画板 SVG
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +export \
|
||||
--whiteboard-token <TOKEN> \
|
||||
--output-type svg \
|
||||
--output <dir>/original.svg \
|
||||
--as user
|
||||
```
|
||||
|
||||
### 2. 编辑 SVG
|
||||
|
||||
在导出的 SVG 上进行修改。参考 [`svg.md` § 画板怎么处理 SVG](./svg.md#画板怎么处理-svg) 了解可识别元素与不支持的装饰特性。
|
||||
|
||||
**技术约束**：
|
||||
- 新增文字必须用 `<text>`（不是 `<path>`），容器宽度留够（CJK ≈ 1em / Latin ≈ 0.6em）
|
||||
- 避免 `skewX` / `skewY` / `matrix(...)` 变换
|
||||
- 禁止使用 `<radialGradient>` / `<filter>` / `<pattern>` / `<clipPath>` / `<mask>`
|
||||
|
||||
**编辑原则**（区别于从零创作）：
|
||||
|
||||
- **风格一致**：新增/修改元素应匹配导出 SVG 中已有的配色、字号、线宽、间距风格，不引入突兀的视觉差异
|
||||
- **最小改动**：只修改用户要求的部分，不主动"优化"或重排无关区域
|
||||
- **结构稳定**：尽量保留原有 `<g>` 层级结构，避免不必要的重组导致分组关系变化
|
||||
- **连线协调**：连接器端点绑定已丢失，若移动了形状，必须手动同步调整视觉上连接到该形状的 connector path 端点坐标，否则连线会"断开"
|
||||
- **内部引用完整性**：不要随意删改 `<defs>` 中被 `url(#id)` 引用的元素（`<marker>`/`<linearGradient>` 等）或修改其 `id`，否则引用方会失效
|
||||
|
||||
### 3. 渲染审查
|
||||
|
||||
```bash
|
||||
# 渲染 PNG 预览
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.13 -i <dir>/edited.svg -o <dir>/edited.png -f svg
|
||||
|
||||
# 几何检查（text-overflow / node-overlap）
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.13 -i <dir>/edited.svg -f svg --check
|
||||
```
|
||||
|
||||
结合 PNG 视觉效果和 `--check` 报告进行调整，有问题则修改 SVG 后重新渲染（最多 2 轮）。
|
||||
- SVG 本地渲染预览时，画板中的图片因 session 原因无法正常显示，属于预期内的行为。
|
||||
|
||||
### 4. 写回画板
|
||||
|
||||
`--overwrite` 会清空原画板内容，确认后再执行
|
||||
|
||||
```bash
|
||||
# dry-run 探测
|
||||
lark-cli whiteboard +update \
|
||||
--whiteboard-token <TOKEN> \
|
||||
--source @<dir>/edited.svg \
|
||||
--input_format svg \
|
||||
--idempotent-token <10+字符唯一串> \
|
||||
--overwrite --dry-run --as user
|
||||
|
||||
# 用户确认后执行
|
||||
lark-cli whiteboard +update \
|
||||
--whiteboard-token <TOKEN> \
|
||||
--source @<dir>/edited.svg \
|
||||
--input_format svg \
|
||||
--idempotent-token <10+字符唯一串> \
|
||||
--overwrite --as user
|
||||
```
|
||||
59
.claude/skills/lark-whiteboard/routes/svg.md
Normal file
59
.claude/skills/lark-whiteboard/routes/svg.md
Normal file
@ -0,0 +1,59 @@
|
||||
# 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.13 -i <dir>/diagram.svg -o <dir>/diagram.png -f svg
|
||||
检查 npx -y @larksuite/whiteboard-cli@^0.2.13 -i <dir>/diagram.svg -f svg --check
|
||||
导出 npx -y @larksuite/whiteboard-cli@^0.2.13 -i <dir>/diagram.svg -f svg --to openapi --format json > <dir>/diagram.json
|
||||
```
|
||||
|
||||
`npx -y @larksuite/whiteboard-cli@^0.2.13 --check` 检测 `text-overflow` 和 `node-overlap`, 并结合视觉效果(查看 PNG)进行调整
|
||||
|
||||
## 画板怎么处理 SVG
|
||||
|
||||
画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但非阴影用途的 `<filter>` / `<clipPath>` 等装饰特性画板不支持（见下方⚠️）
|
||||
**不需要所有元素都可编辑, 但必须避免使用不支持的装饰特性, 且要兼顾可编辑和美观漂亮**
|
||||
|
||||
**可识别的元素**
|
||||
|
||||
- 形状：`<rect>` / `<circle>` / `<ellipse>` / `<polygon>`
|
||||
- 连线：`<line>` / `<polyline>` / `<path>`(自动识别为直线 / 折线 / 曲线)
|
||||
- 文本：`<text>` / `<tspan>` 画板硬编码 Noto Sans SC **文字必须用 `<text>`**
|
||||
- 分组：`<g>` / `<a>` / `<use>` 引用 `<symbol>`
|
||||
- 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级
|
||||
- 阴影：`<filter>` 里放 `<feDropShadow>` 或标准 drop/inner primitive 链 (`<feGaussianBlur in="SourceAlpha">` + `<feOffset>` + `<feFlood>` + `<feComposite>` + `<feMerge>`), 会被识别成节点阴影, drop 至多 1 个, inner 至多 1 个; 其余 filter 效果不识别
|
||||
- 渐变：`<linearGradient>` / `<radialGradient>` 在 `<defs>` 中定义, 通过 `fill="url(#id)"` 引用 (载体限 `<rect>` / `<circle>` / `<ellipse>` / `<polygon>` / `<path>`), 需要至少 2 个 `<stop>`, `gradientUnits` 只支持默认的 `objectBoundingBox` (不写即可);
|
||||
|
||||
**⚠️ [!IMPORTANT] 不支持的装饰特性**
|
||||
- `<pattern>` / `<clipPath>` / `<mask>` / 非阴影用途的 `<filter>` (blur / hue-rotate / 复合合成 / `flood-color=url(...)` / 多个 `<feDropShadow>` 等) → 画板不支持，**请避免使用，否则会导致画板渲染问题**
|
||||
- 渐变边界：`gradientUnits="userSpaceOnUse"` / `spreadMethod="reflect|repeat"` / stops 少于 2 个 / 复杂 `gradientTransform` 会变成不可编辑图片, 视觉正确但失去可编辑性, 若无必要请沿用默认 `objectBoundingBox`
|
||||
433
.claude/skills/lark-whiteboard/scenes/architecture.md
Normal file
433
.claude/skills/lark-whiteboard/scenes/architecture.md
Normal file
@ -0,0 +1,433 @@
|
||||
# 系统架构图
|
||||
|
||||
适用于：分层架构图、微服务架构图、前后端架构图等有明确模块划分的场景。
|
||||
|
||||
## Content 约束
|
||||
|
||||
- **充分展开**：用户说"IM 架构"，要展开到接入层（Web/iOS/Android/桌面）、网关层（接入/路由/安全）、服务层（核心服务+支撑服务两个子区域）、存储层（MySQL/Redis/MongoDB + 括号说明用途）
|
||||
- 每层节点 3-6 个。超过 6 个分两排或拆为子区域（如"核心服务"和"支撑服务"各一个子 frame）
|
||||
- 层标签简短（2-4 字），如"接入层""网关层"
|
||||
- 每个节点有标题 + 简短说明（如"用户服务\n注册登录和权限管理"）
|
||||
- 技术组件加括号注明技术栈（如"消息队列\n(Kafka)"）
|
||||
- 存储节点必须用 `cylinder` 类型（弧度固定 16px，禁止 `fill-container` 宽度，用 120-200 固定宽度）。每行最多 4 个 cylinder（超过 4 个换行或合并同类项，如多个 MySQL 合并为"关系数据库\n(MySQL)"）
|
||||
- 侧边栏（如运维监控、基础设施）只在用户明确要求时才加，最多 2-3 项。不要自作主张添加侧边栏
|
||||
- 可使用 icon+text 组合更直观的进行内容展示和增强辨识度
|
||||
- **连线：非必要不画。** 架构图的分层结构本身已表达了调用方向（上层调下层），不需要每对节点都连线。只在需要强调特定调用关系时才画，且总数不超过 3-5 条
|
||||
|
||||
## Layout 选型
|
||||
|
||||
| 模式 | 适用条件 | 特征 |
|
||||
| -------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| **grid（分层条带）** | 有明确上下层级关系（接入→网关→服务→存储） | 行=层级，每行 horizontal frame 等分节点。左侧 text 标签 + 右侧层 frame（Label-Outside 模式） |
|
||||
| **grid（网格矩阵）** | 多模块平级，无明确层级 | N×M 网格等分，每格一个模块 |
|
||||
| **混合（岛屿式）** | 模块间网状互联，无清晰分层 | 宏观 `layout: "none"` + x/y 定位各模块岛屿，微观每个岛屿内部用 flex 布局 |
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- **根节点**：固定宽度（1200），`height: "fit-content"`，`layout: "vertical"`，`gap: 20`，`padding: 24`
|
||||
- **主体双栏**（有侧边栏时）：horizontal frame，`alignItems: "stretch"`，`gap: 16`
|
||||
- 左侧 layers-container：`width: "fill-container"`，vertical，`gap: 16`
|
||||
- 右侧 sidebar：固定宽度 160-180，`height: "fill-container"`，`justifyContent: "space-between"`
|
||||
- **单层（Label-Outside）**：horizontal frame，左侧 text 标签（`width: 80`，`textAlign: "right"`），右侧层 frame（`fill-container`，带 borderWidth/borderRadius，`padding: 24`，`gap: 16`）。**为什么用 Label-Outside**：标签放在 frame 外部更简洁，避免在 frame 内部嵌套窄 rect 导致竖排文字和对齐问题。
|
||||
- **子区域**：在层 frame 内嵌套 horizontal wrapper（`alignItems: "stretch"` 保证同行等高），内含多个 vertical frame（各子区域），每个子区域有自己的标题 text + 内容行。行内组件 `width: "fill-container"` 自动均分。
|
||||
- **侧边栏**：拆成独立的逻辑块 frame（如"运维监控"和"基础设施"分开），各块 `height: "fill-container"`。外层 `justifyContent: "space-between"` 保证与左侧对齐，内部可设 `justifyContent: "center"` 使内容居中。
|
||||
- **行内标签**：层内如有贯穿多列的特殊组件（如中间件），可采用"左侧小标签 + 右侧组件组"的横向布局
|
||||
|
||||
## 骨架示例
|
||||
|
||||
### 分层条带（Label-Outside + 侧边栏）
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "root",
|
||||
"x": 0, "y": 0,
|
||||
"width": 1200,
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 20,
|
||||
"padding": 24,
|
||||
"children": [
|
||||
{
|
||||
"type": "text",
|
||||
"id": "title",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"text": "[图表标题]",
|
||||
"fontSize": 24,
|
||||
"textAlign": "center",
|
||||
"verticalAlign": "middle"
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "main-container",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"alignItems": "stretch",
|
||||
"gap": 16,
|
||||
"padding": 0,
|
||||
"children": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "layers-container",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"alignItems": "stretch",
|
||||
"gap": 16,
|
||||
"padding": 0,
|
||||
"children": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "row-layer-1",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 24,
|
||||
"padding": 0,
|
||||
"alignItems": "center",
|
||||
"children": [
|
||||
{
|
||||
"type": "text",
|
||||
"id": "label-1",
|
||||
"width": 80,
|
||||
"height": "fit-content",
|
||||
"text": "[层标签]",
|
||||
"fontSize": 20,
|
||||
"textAlign": "right"
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "layer-1",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"borderWidth": 2,
|
||||
"borderRadius": 8,
|
||||
"layout": "horizontal",
|
||||
"gap": 16,
|
||||
"padding": 24,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{ "type": "rect", "id": "n-1-1", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "n-1-2", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "n-1-3", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "row-layer-2",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 24,
|
||||
"padding": 0,
|
||||
"alignItems": "center",
|
||||
"children": [
|
||||
{
|
||||
"type": "text",
|
||||
"id": "label-2",
|
||||
"width": 80,
|
||||
"height": "fit-content",
|
||||
"text": "[层标签]",
|
||||
"fontSize": 20,
|
||||
"textAlign": "right"
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "layer-2",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"borderWidth": 2,
|
||||
"borderRadius": 8,
|
||||
"layout": "vertical",
|
||||
"gap": 16,
|
||||
"padding": 24,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "subareas-wrapper",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"alignItems": "stretch",
|
||||
"gap": 16,
|
||||
"padding": 0,
|
||||
"children": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "subarea-a",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 8,
|
||||
"padding": 12,
|
||||
"borderRadius": 8,
|
||||
"borderWidth": 2,
|
||||
"children": [
|
||||
{ "type": "text", "id": "title-a", "width": "fill-container", "height": "fit-content", "text": "[子区域名]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "row-a-1",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"children": [
|
||||
{ "type": "rect", "id": "sa-1", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "sa-2", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "subarea-b",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 8,
|
||||
"padding": 12,
|
||||
"borderRadius": 8,
|
||||
"borderWidth": 2,
|
||||
"children": [
|
||||
{ "type": "text", "id": "title-b", "width": "fill-container", "height": "fit-content", "text": "[子区域名]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "row-b-1",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"children": [
|
||||
{ "type": "rect", "id": "sb-1", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "sb-2", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "row-layer-3",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 24,
|
||||
"padding": 0,
|
||||
"alignItems": "center",
|
||||
"children": [
|
||||
{
|
||||
"type": "text",
|
||||
"id": "label-3",
|
||||
"width": 80,
|
||||
"height": "fit-content",
|
||||
"text": "[层标签]",
|
||||
"fontSize": 20,
|
||||
"textAlign": "right"
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "layer-3",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"borderWidth": 2,
|
||||
"borderRadius": 8,
|
||||
"layout": "horizontal",
|
||||
"gap": 0,
|
||||
"padding": 24,
|
||||
"justifyContent": "space-around",
|
||||
"children": [
|
||||
{ "type": "cylinder", "id": "db-1", "width": 140, "height": "fit-content", "text": "[存储名]", "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "cylinder", "id": "db-2", "width": 140, "height": "fit-content", "text": "[存储名]", "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "right-sidebar-wrapper",
|
||||
"width": 180,
|
||||
"height": "fill-container",
|
||||
"layout": "vertical",
|
||||
"alignItems": "stretch",
|
||||
"justifyContent": "space-between",
|
||||
"gap": 16,
|
||||
"padding": 0,
|
||||
"children": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "side-block-1",
|
||||
"width": "fill-container",
|
||||
"height": "fill-container",
|
||||
"layout": "vertical",
|
||||
"alignItems": "stretch",
|
||||
"justifyContent": "center",
|
||||
"gap": 12,
|
||||
"padding": 16,
|
||||
"borderRadius": 8,
|
||||
"borderWidth": 2,
|
||||
"children": [
|
||||
{ "type": "text", "id": "side-title-1", "width": "fill-container", "height": "fit-content", "text": "[侧边栏模块名]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "side-items-1",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"children": [
|
||||
{ "type": "rect", "id": "s-1", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "s-2", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "side-block-2",
|
||||
"width": "fill-container",
|
||||
"height": "fill-container",
|
||||
"layout": "vertical",
|
||||
"alignItems": "stretch",
|
||||
"justifyContent": "center",
|
||||
"gap": 12,
|
||||
"padding": 16,
|
||||
"borderRadius": 8,
|
||||
"borderWidth": 2,
|
||||
"children": [
|
||||
{ "type": "text", "id": "side-title-2", "width": "fill-container", "height": "fit-content", "text": "[侧边栏模块名]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "side-items-2",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"children": [
|
||||
{ "type": "rect", "id": "s-3", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "s-4", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 岛屿式（网状互联）
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "root",
|
||||
"x": 0, "y": 0,
|
||||
"width": 1200,
|
||||
"height": 800,
|
||||
"layout": "none",
|
||||
"padding": 24,
|
||||
"children": [
|
||||
{
|
||||
"type": "text",
|
||||
"id": "title",
|
||||
"x": 0, "y": 0,
|
||||
"width": 1152,
|
||||
"height": "fit-content",
|
||||
"text": "[图表标题]",
|
||||
"fontSize": 24,
|
||||
"textAlign": "center",
|
||||
"verticalAlign": "middle"
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "island-a",
|
||||
"x": 40, "y": 60,
|
||||
"width": 320,
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 12,
|
||||
"padding": 20,
|
||||
"borderWidth": 2,
|
||||
"borderRadius": 8,
|
||||
"children": [
|
||||
{ "type": "text", "id": "island-a-title", "width": "fill-container", "height": "fit-content", "text": "[模块名]", "fontSize": 16, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "ia-1", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "ia-2", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "island-b",
|
||||
"x": 440, "y": 60,
|
||||
"width": 320,
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 12,
|
||||
"padding": 20,
|
||||
"borderWidth": 2,
|
||||
"borderRadius": 8,
|
||||
"children": [
|
||||
{ "type": "text", "id": "island-b-title", "width": "fill-container", "height": "fit-content", "text": "[模块名]", "fontSize": 16, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "ib-1", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "ib-2", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "island-c",
|
||||
"x": 240, "y": 340,
|
||||
"width": 320,
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 12,
|
||||
"padding": 20,
|
||||
"borderWidth": 2,
|
||||
"borderRadius": 8,
|
||||
"children": [
|
||||
{ "type": "text", "id": "island-c-title", "width": "fill-container", "height": "fit-content", "text": "[模块名]", "fontSize": 16, "textAlign": "center", "verticalAlign": "middle" },
|
||||
{ "type": "rect", "id": "ic-1", "width": "fill-container", "height": "fit-content", "text": "[节点名]", "borderRadius": 8, "borderWidth": 2, "fontSize": 14, "textAlign": "center", "verticalAlign": "middle" }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{ "type": "connector", "connector": { "from": "ia-1", "to": "ib-1", "fromAnchor": "right", "toAnchor": "left", "lineShape": "straight", "lineWidth": 2, "endArrow": "arrow" } },
|
||||
{ "type": "connector", "connector": { "from": "island-a", "to": "ic-1", "fromAnchor": "bottom", "toAnchor": "top", "lineShape": "rightAngle", "lineWidth": 2, "endArrow": "arrow" } },
|
||||
{ "type": "connector", "connector": { "from": "island-b", "to": "ic-1", "fromAnchor": "bottom", "toAnchor": "top", "lineShape": "rightAngle", "lineWidth": 2, "endArrow": "arrow" } }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 陷阱
|
||||
|
||||
- **所有架构图都用分层条带**：多模块平级网状互联时应选岛屿式；无明确层级时应选网格矩阵。先判断信息结构再选布局。
|
||||
- **连线过多导致交叉**：架构图非必要不画连线。分层结构本身已表达调用方向，不需要每对节点连线。如果一定要画，最多 3-5 条关键路径。
|
||||
- **层标签用 frame title（不可读）**：层标签必须用独立的 text 节点放在 frame 外侧（Label-Outside 模式），不要嵌入 frame 内部。
|
||||
- **cylinder 用 fill-container 宽度**：cylinder 弧度固定 16px 不随宽度缩放，必须用固定宽度（120-200）。
|
||||
- **侧边栏逻辑混合**："运维监控"和"基础设施"必须是独立 frame，不可合并成一个长条。
|
||||
- **根节点没有固定宽度**：根 frame 必须有明确宽度（如 1200），否则子节点的 `fill-container` 无法计算。
|
||||
187
.claude/skills/lark-whiteboard/scenes/bar-chart.md
Normal file
187
.claude/skills/lark-whiteboard/scenes/bar-chart.md
Normal file
@ -0,0 +1,187 @@
|
||||
# 柱状图
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 数据点 ≤ 12
|
||||
- 同一数据系列用同一颜色（不要每个柱不同色）
|
||||
- Y 轴必须有单位标注（如 "万元"、"人次"）
|
||||
|
||||
## Layout 选型
|
||||
|
||||
- **脚本生成坐标**（推荐）：用 .cjs 脚本计算柱体位置和高度，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.13` 渲染
|
||||
- **绝对定位手写**：简单柱状图（≤ 5 个柱）可手写坐标
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- 白板坐标系 Y 轴向下为正，图表"底部原点"拥有最大 Y 值，柱体向上生长时 Y 减小
|
||||
- 柱体等宽等间距，底部对齐 X 轴
|
||||
- 柱体高度：`height = (value / maxValue) * chartHeight`
|
||||
- 柱体 Y 坐标：`y = originY - height`
|
||||
- 坐标轴用 connector 直线，末端带箭头（endArrow: "arrow"）
|
||||
- 格线用虚线 connector（lineStyle: "dashed"，endArrow: "none"）
|
||||
- 刻度线短横线 connector（endArrow: "none"）
|
||||
- 数值标注放在柱体顶部上方
|
||||
- 类别标签放在 X 轴下方，居中对齐柱体
|
||||
|
||||
## 坐标与尺寸计算指南
|
||||
|
||||
白板坐标系中，**X 轴向右为正，Y 轴向下为正**。因此图表的"底部原点"实际上拥有最大的 Y 坐标，图形向上生长时 Y 坐标在不断减小。
|
||||
|
||||
1. **确定图表区域**：
|
||||
- 设定图表区高度 `chartHeight` 和宽度 `chartWidth`
|
||||
- 设定左下角坐标原点 `(originX, originY)`
|
||||
- 示例：originX=80, originY=480, chartWidth=1000, chartHeight=400
|
||||
2. **Y 轴映射（计算高度）**：
|
||||
- 找出数据的最大值 `maxValue`
|
||||
- 将 maxValue 向上取整到"整数刻度"（如数据最大 190 → maxValue 取 200）
|
||||
- 柱子高度：`height = (value / maxValue) * chartHeight`
|
||||
- 柱子 Y 坐标：`y = originY - height`
|
||||
3. **X 轴映射（计算宽度与 X 坐标）**：
|
||||
- 将 chartWidth 按数据个数均分：`slotWidth = chartWidth / barCount`
|
||||
- 设定柱子间距 `barGap`（推荐 slotWidth 的 25%-30%）
|
||||
- 柱子宽度：`barWidth = slotWidth - barGap`
|
||||
- 第 i 根柱子 X 坐标：`x = originX + i * slotWidth + barGap / 2`
|
||||
4. **Y 轴刻度计算**：
|
||||
- 将 0 到 maxValue 等分为 4-6 个刻度
|
||||
- 每个刻度的 Y 坐标：`gridY = originY - (tickValue / maxValue) * chartHeight`
|
||||
- 刻度线：从 (originX-10, gridY) 到 (originX, gridY) 的短横线
|
||||
- 网格线：从 (originX, gridY) 到 (originX+chartWidth, gridY) 的虚线
|
||||
|
||||
## 完整 JSON 示例
|
||||
|
||||
以下示例：3 根柱子，数据 [120, 200, 150]，maxValue=200，originX=80, originY=480, chartWidth=900, chartHeight=400。
|
||||
|
||||
- slotWidth = 900 / 3 = 300
|
||||
- barGap = 80, barWidth = 220
|
||||
- 刻度：0, 50, 100, 150, 200（每 50 一格，gridInterval = 80px）
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{ "type": "rect", "x": 0, "y": 0, "width": 1100, "height": 580 },
|
||||
|
||||
{ "type": "text", "x": 80, "y": 10, "width": 900, "height": "fit-content",
|
||||
"text": "季度销售额对比", "fontSize": 24, "textAlign": "center" },
|
||||
|
||||
{ "type": "text", "x": 10, "y": 40, "width": 60, "height": "fit-content",
|
||||
"text": "万元", "fontSize": 12, "textAlign": "center" },
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 480 }, "to": { "x": 80, "y": 55 },
|
||||
"lineShape": "straight", "lineWidth": 2, "endArrow": "arrow"
|
||||
}},
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 480 }, "to": { "x": 1000, "y": 480 },
|
||||
"lineShape": "straight", "lineWidth": 2, "endArrow": "arrow"
|
||||
}},
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 70, "y": 480 }, "to": { "x": 80, "y": 480 },
|
||||
"lineShape": "straight", "lineWidth": 1,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "text", "x": 20, "y": 470, "width": 50, "height": 20,
|
||||
"text": "0", "fontSize": 12, "textAlign": "right" },
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 70, "y": 400 }, "to": { "x": 80, "y": 400 },
|
||||
"lineShape": "straight", "lineWidth": 1,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "text", "x": 20, "y": 390, "width": 50, "height": 20,
|
||||
"text": "50", "fontSize": 12, "textAlign": "right" },
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 400 }, "to": { "x": 980, "y": 400 },
|
||||
"lineShape": "straight", "lineWidth": 1, "lineStyle": "dashed",
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 70, "y": 320 }, "to": { "x": 80, "y": 320 },
|
||||
"lineShape": "straight", "lineWidth": 1,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "text", "x": 20, "y": 310, "width": 50, "height": 20,
|
||||
"text": "100", "fontSize": 12, "textAlign": "right" },
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 320 }, "to": { "x": 980, "y": 320 },
|
||||
"lineShape": "straight", "lineWidth": 1, "lineStyle": "dashed",
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 70, "y": 240 }, "to": { "x": 80, "y": 240 },
|
||||
"lineShape": "straight", "lineWidth": 1,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "text", "x": 20, "y": 230, "width": 50, "height": 20,
|
||||
"text": "150", "fontSize": 12, "textAlign": "right" },
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 240 }, "to": { "x": 980, "y": 240 },
|
||||
"lineShape": "straight", "lineWidth": 1, "lineStyle": "dashed",
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 70, "y": 160 }, "to": { "x": 80, "y": 160 },
|
||||
"lineShape": "straight", "lineWidth": 1,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "text", "x": 20, "y": 150, "width": 50, "height": 20,
|
||||
"text": "200", "fontSize": 12, "textAlign": "right" },
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 160 }, "to": { "x": 980, "y": 160 },
|
||||
"lineShape": "straight", "lineWidth": 1, "lineStyle": "dashed",
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
|
||||
{ "type": "rect", "id": "bar-0", "x": 120, "y": 240,
|
||||
"width": 220, "height": 240, "borderRadius": 4 },
|
||||
{ "type": "text", "x": 120, "y": 215,
|
||||
"width": 220, "height": 20,
|
||||
"text": "120", "fontSize": 14, "textAlign": "center" },
|
||||
{ "type": "text", "x": 120, "y": 490,
|
||||
"width": 220, "height": 30,
|
||||
"text": "Q1", "fontSize": 14, "textAlign": "center" },
|
||||
|
||||
{ "type": "rect", "id": "bar-1", "x": 420, "y": 80,
|
||||
"width": 220, "height": 400, "borderRadius": 4 },
|
||||
{ "type": "text", "x": 420, "y": 55,
|
||||
"width": 220, "height": 20,
|
||||
"text": "200", "fontSize": 14, "textAlign": "center" },
|
||||
{ "type": "text", "x": 420, "y": 490,
|
||||
"width": 220, "height": 30,
|
||||
"text": "Q2", "fontSize": 14, "textAlign": "center" },
|
||||
|
||||
{ "type": "rect", "id": "bar-2", "x": 720, "y": 180,
|
||||
"width": 220, "height": 300, "borderRadius": 4 },
|
||||
{ "type": "text", "x": 720, "y": 155,
|
||||
"width": 220, "height": 20,
|
||||
"text": "150", "fontSize": 14, "textAlign": "center" },
|
||||
{ "type": "text", "x": 720, "y": 490,
|
||||
"width": 220, "height": 30,
|
||||
"text": "Q3", "fontSize": 14, "textAlign": "center" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
坐标推导验证：
|
||||
- bar-0 (120): height = (120/200)*400 = 240, y = 480-240 = 240
|
||||
- bar-1 (200): height = (200/200)*400 = 400, y = 480-400 = 80
|
||||
- bar-2 (150): height = (150/200)*400 = 300, y = 480-300 = 180
|
||||
- bar-0 x = 80 + 0*300 + 80/2 = 120, bar-1 x = 80 + 1*300 + 40 = 420, bar-2 x = 80 + 2*300 + 40 = 720
|
||||
|
||||
## 陷阱
|
||||
|
||||
- 单系列用多色（不专业）：同一数据系列所有柱体应使用同一颜色
|
||||
- 缺 Y 轴单位标注，读者无法理解数值含义
|
||||
- 柱体间距不均匀（脚本需统一计算 barGap）
|
||||
- Y 轴刻度线和格线误带箭头
|
||||
- 坐标轴忘记带箭头
|
||||
|
||||
此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `data` 数组，其余坐标与柱体高度全自动计算。
|
||||
|
||||
```javascript
|
||||
const { writeFileSync } = require('fs');
|
||||
```
|
||||
135
.claude/skills/lark-whiteboard/scenes/comparison.md
Normal file
135
.claude/skills/lark-whiteboard/scenes/comparison.md
Normal file
@ -0,0 +1,135 @@
|
||||
# 对比图 / 矩阵图
|
||||
|
||||
适用于：方案对比、功能矩阵、技术选型等多选项按多维度比较的场景。
|
||||
|
||||
## Content 约束
|
||||
|
||||
- **每格内容要充实**：不要只写一个关键词，给出具体说明（如"MVCC 多版本并发控制，支持行级锁"而非仅"支持"）
|
||||
- 单格内容不同格子允许不同长度，但每格不超过 5 行
|
||||
- 长文本（超过 15 字）用 `textAlign: "left"`（不要居中）
|
||||
- 第一行是标题行（对象名称），第一列是维度标签列
|
||||
- 维度数量至少 4 个，充分展开对比维度
|
||||
|
||||
## Layout 选型
|
||||
|
||||
| 模式 | 适用条件 | 特征 |
|
||||
|------|---------|------|
|
||||
| **严格 grid（默认）** | 所有对比场景 | 表头行 + 数据行，每行 horizontal frame，行内 rect 等分 |
|
||||
| **卡片式对比（替代）** | 维度较少（2-3 个） | 每个对象做一张独立卡片，卡片内纵向列出各维度。卡片横向等分：外层 `layout: "horizontal"`，每张卡片 `width: "fill-container"` |
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- 最外层 frame：`layout: "vertical"`，固定 `width`（如 1000），`height: "fit-content"`
|
||||
- 每行：horizontal frame，`width: "fill-container"`，`alignItems: "stretch"`
|
||||
- 行内单元格全部 `width: "fill-container"` 等分列宽
|
||||
- 行间 `gap >= 12`（不要 8，太紧）
|
||||
- 行内列间 `gap: 8-12`
|
||||
- 标题行：深色底白字（由 style 控制具体颜色）
|
||||
- 每列同色边框保持视觉一致性
|
||||
- 单元格 `height: "fit-content"`，不要写固定 height
|
||||
|
||||
## 骨架示例
|
||||
|
||||
### 3 列 4 行表格
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "frame",
|
||||
"width": 1000,
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 12,
|
||||
"padding": 0,
|
||||
"children": [
|
||||
{
|
||||
"type": "text",
|
||||
"id": "title",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"text": "[对比图标题]",
|
||||
"fontSize": 24,
|
||||
"textAlign": "center",
|
||||
"verticalAlign": "middle"
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "header-row",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{ "type": "rect", "id": "h-dim", "width": "fill-container", "height": "fit-content", "text": "[维度]", "fontSize": 15, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 0, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "h-col-1", "width": "fill-container", "height": "fit-content", "text": "[对象A]", "fontSize": 15, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "h-col-2", "width": "fill-container", "height": "fit-content", "text": "[对象B]", "fontSize": 15, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "h-col-3", "width": "fill-container", "height": "fit-content", "text": "[对象C]", "fontSize": 15, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 }
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "data-row-1",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{ "type": "rect", "id": "d1-dim", "width": "fill-container", "height": "fit-content", "text": "[维度1]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "d1-c1", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "d1-c2", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "d1-c3", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 }
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "data-row-2",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{ "type": "rect", "id": "d2-dim", "width": "fill-container", "height": "fit-content", "text": "[维度2]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "d2-c1", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "d2-c2", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "d2-c3", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 }
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "data-row-3",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{ "type": "rect", "id": "d3-dim", "width": "fill-container", "height": "fit-content", "text": "[维度3]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "d3-c1", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "d3-c2", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 },
|
||||
{ "type": "rect", "id": "d3-c3", "width": "fill-container", "height": "fit-content", "text": "[...]", "fontSize": 14, "textAlign": "center", "verticalAlign": "middle", "borderRadius": 8, "borderWidth": 2 }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 陷阱
|
||||
|
||||
- **行间距 8px 太紧**：行间 gap 至少 12，8 会让行与行视觉粘连。
|
||||
- **长文本居中对齐**：超过一行的文本应改为 `textAlign: "left"`，居中多行文本可读性差。
|
||||
- **列数太多导致每列太窄**：对比对象建议 ≤ 5 列（含维度列），超过时合并维度或拆分为多张表。
|
||||
- **列宽不等**：所有数据列必须用 `width: "fill-container"` 等分，不要给某列写固定宽度。
|
||||
- **行高不等**：每行 frame 必须 `alignItems: "stretch"`，否则同行单元格因文字行数不同高矮不齐。
|
||||
- **忘记维度标签列**：第一列放维度名称，标题行（维度列）用与数据列不同的视觉处理。
|
||||
- **单元格用固定 height**：单元格必须 `height: "fit-content"`，固定高度会导致文字截断。
|
||||
238
.claude/skills/lark-whiteboard/scenes/fishbone.md
Normal file
238
.claude/skills/lark-whiteboard/scenes/fishbone.md
Normal file
@ -0,0 +1,238 @@
|
||||
# 鱼骨图（因果图）
|
||||
|
||||
> **必须写脚本生成 JSON。** 鱼骨图的分支角度、原因小骨坐标需要三角函数计算，直接手写 JSON 极易导致节点重叠和连线穿模。请用下方脚本模板。
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 分类 4-6 个
|
||||
- 每个分类的原因 ≤ 4
|
||||
- 总原因 ≤ 20（超过必须合并分类）
|
||||
|
||||
## Layout 选型
|
||||
|
||||
- **脚本生成坐标**（必须）：用 .cjs 脚本通过三角函数计算鱼骨坐标，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.13` 渲染
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- 主干水平居中，从左向右延伸
|
||||
- 分类节点按 spineX 从左到右排列，奇数（第 1、3、5...）在上方，偶数（第 2、4...）在下方
|
||||
- 每个分类的原因沿斜线（分支骨）等距排列
|
||||
- 鱼头（中心问题）在右侧，用 ellipse
|
||||
- 主干连线带箭头指向鱼头，分支骨和原因小骨连线 endArrow: "none"
|
||||
- 原因小骨水平延伸到原因框右侧，Y 坐标精准对齐
|
||||
|
||||
## 骨架示例
|
||||
|
||||
**上下交替**：分类标签按 spineX 从左到右排列，奇数（第1、3、5...）在上方，偶数（第2、4...）在下方。
|
||||
|
||||
**视觉同色系**：同一个分支的分类标签、连线及其下的所有原因节点，必须使用同一个色系（如相同的背景色与边框色组合），以保持图形风格统一和逻辑连贯。可以预定义一组颜色数组，按分支轮询使用。
|
||||
|
||||
### 坐标计算脚本模板（必须严格参照此算法生成）
|
||||
|
||||
以下 Node.js 脚本模板包含了完整的动态布局算法，能够自动适配任意数量的分类和原因，生成完美不重叠的鱼骨图：
|
||||
|
||||
```javascript
|
||||
const fs = require('fs');
|
||||
|
||||
const nodes = [];
|
||||
|
||||
// 1. 数据定义 (根据用户需求填充)
|
||||
const categories = [
|
||||
{ id: "c0", text: "前端代码", reasons: ["未压缩资源", "冗余请求", "超大图片未懒加载"] },
|
||||
{ id: "c1", text: "后端服务", reasons: ["数据库慢查询", "缓存失效", "并发量过大"] },
|
||||
{ id: "c2", text: "网络环境", reasons: ["CDN配置错误", "DNS解析缓慢", "带宽限制", "网络抖动"] }
|
||||
];
|
||||
|
||||
// 2. 动态布局计算
|
||||
const catWidth = 120;
|
||||
const catHeight = 40;
|
||||
const reasonWidth = 140; // 调整原因框宽度以适应长文本
|
||||
const reasonHeight = 32;
|
||||
const lineLength = 20; // 原因小骨连线的水平延伸长度
|
||||
const paddingX = 40; // 同侧节点间的水平安全间距
|
||||
|
||||
// 预置的分支色系数组（分支骨分类和具体原因保持同一色系）
|
||||
const branchColors = [
|
||||
{ fill: "#E8F3FF", stroke: "#1664FF" }, // 蓝色系
|
||||
{ fill: "#E6FFED", stroke: "#00B42A" }, // 绿色系
|
||||
{ fill: "#FFF7E8", stroke: "#FF7D00" }, // 橙色系
|
||||
{ fill: "#FFECE8", stroke: "#F5319D" }, // 粉色系
|
||||
{ fill: "#F2E8FF", stroke: "#722ED1" }, // 紫色系
|
||||
{ fill: "#E8FFFF", stroke: "#14C9C9" } // 青色系
|
||||
];
|
||||
|
||||
let maxSpineY_up = 0;
|
||||
let maxSpineY_down = 0;
|
||||
|
||||
// 第一步：计算每个 category 的内部尺寸和相对包围盒
|
||||
categories.forEach((cat, index) => {
|
||||
const isTop = index % 2 === 0;
|
||||
const numReasons = cat.reasons.length;
|
||||
|
||||
// 动态计算分支高度，确保原因小骨不会垂直重叠
|
||||
// 每个原因需要 reasonHeight + 上下间距(约 16)
|
||||
const requiredY = (numReasons + 1) * (reasonHeight + 16);
|
||||
const branchDY = Math.max(160, requiredY);
|
||||
const branchDX = -branchDY * 0.7; // 保持固定的倾斜角度向左延伸
|
||||
|
||||
cat.isTop = isTop;
|
||||
cat.branchDX = branchDX;
|
||||
cat.branchDY = branchDY;
|
||||
|
||||
// 记录最大分支高度，用于计算背景高度和主骨 Y 坐标
|
||||
if (isTop) maxSpineY_up = Math.max(maxSpineY_up, branchDY + catHeight + 40);
|
||||
else maxSpineY_down = Math.max(maxSpineY_down, branchDY + catHeight + 40);
|
||||
|
||||
// 计算该分类的相对包围盒的极值（相对于 spineX 锚点）
|
||||
// 最左侧可能由分类框或原因框决定
|
||||
cat.minX = Math.min(branchDX - catWidth / 2, branchDX - lineLength - reasonWidth);
|
||||
// 最右侧为主骨挂载点 0 或 分类框右侧
|
||||
cat.maxX = Math.max(0, branchDX + catWidth / 2);
|
||||
});
|
||||
|
||||
// 第二步：计算每个 category 在主骨上的绝对 X 坐标 (spineX)
|
||||
let currentSpineX = 100; // 初始偏移
|
||||
for (let i = 0; i < categories.length; i++) {
|
||||
const cat = categories[i];
|
||||
let startX = currentSpineX;
|
||||
|
||||
// 需要和上一个同侧的 category 保持距离，防止水平重叠
|
||||
if (i >= 2) {
|
||||
const prevSameSideCat = categories[i - 2];
|
||||
const requiredX = prevSameSideCat.spineX + prevSameSideCat.maxX - cat.minX + paddingX;
|
||||
startX = Math.max(startX, requiredX);
|
||||
}
|
||||
|
||||
// 确保左侧最长分支不会超出画布左边界
|
||||
if (startX + cat.minX < 50) {
|
||||
startX = 50 - cat.minX;
|
||||
}
|
||||
|
||||
cat.spineX = startX;
|
||||
// 每次略微向前推进，确保异侧节点也能稍微错开
|
||||
currentSpineX = startX + 80;
|
||||
}
|
||||
|
||||
// 第三步：计算全局画布尺寸
|
||||
const lastCat = categories[categories.length - 1];
|
||||
const spineY = maxSpineY_up + 50; // 动态推导主骨 Y 坐标
|
||||
const totalWidth = lastCat.spineX + 350; // 右侧留出鱼头的空间
|
||||
const totalHeight = spineY + maxSpineY_down + 50;
|
||||
|
||||
// 4. 生成节点数据
|
||||
// 背景
|
||||
nodes.push({ type: "rect", x: 0, y: 0, width: totalWidth, height: totalHeight, fillColor: "#FFFFFF", borderWidth: 0 });
|
||||
|
||||
// 鱼头
|
||||
const headWidth = 180;
|
||||
const headHeight = 80;
|
||||
const headX = totalWidth - headWidth - 40;
|
||||
const headY = spineY - headHeight / 2;
|
||||
nodes.push({ type: "ellipse", id: "head", x: headX, y: headY, width: headWidth, height: headHeight, text: "核心问题" });
|
||||
|
||||
// 主骨连线
|
||||
const firstSpineX = categories[0].spineX + categories[0].minX;
|
||||
nodes.push({
|
||||
type: "connector",
|
||||
connector: { from: { x: firstSpineX, y: spineY }, to: "head", toAnchor: "left", lineShape: "straight", endArrow: "arrow" }
|
||||
});
|
||||
|
||||
// 遍历生成分类和原因小骨
|
||||
categories.forEach((cat, index) => {
|
||||
const isTop = cat.isTop;
|
||||
const branchDY = cat.branchDY;
|
||||
const branchDX = cat.branchDX;
|
||||
const color = branchColors[index % branchColors.length];
|
||||
|
||||
// 分类标签
|
||||
const catX = cat.spineX + branchDX - catWidth / 2;
|
||||
const catY = spineY + (isTop ? -branchDY - catHeight : branchDY);
|
||||
|
||||
nodes.push({
|
||||
type: "rect", id: cat.id, x: catX, y: catY, width: catWidth, height: catHeight, text: cat.text,
|
||||
fillColor: color.fill, strokeColor: color.stroke
|
||||
});
|
||||
// 分支骨连线
|
||||
nodes.push({
|
||||
type: "connector",
|
||||
connector: { from: { x: cat.spineX, y: spineY }, to: cat.id, toAnchor: isTop ? "bottom" : "top", lineShape: "straight", endArrow: "none", lineColor: color.stroke }
|
||||
});
|
||||
|
||||
// 原因小骨
|
||||
cat.reasons.forEach((reason, rIndex) => {
|
||||
// 线性插值，均匀分布在分支骨上
|
||||
const t = (rIndex + 1) / (cat.reasons.length + 1);
|
||||
const attachX = cat.spineX + branchDX * t;
|
||||
const attachY = spineY + (isTop ? -branchDY : branchDY) * t;
|
||||
|
||||
// 关键对齐：确保原因盒子完全在连线左侧，并且 Y 坐标中心精准对齐
|
||||
const boxX = attachX - lineLength - reasonWidth;
|
||||
const boxY = attachY - reasonHeight / 2;
|
||||
|
||||
const rId = `${cat.id}-r${rIndex}`;
|
||||
nodes.push({
|
||||
type: "rect", id: rId, x: boxX, y: boxY, width: reasonWidth, height: reasonHeight, text: reason,
|
||||
fillColor: color.fill, strokeColor: color.stroke
|
||||
});
|
||||
// 原因小骨连线
|
||||
nodes.push({
|
||||
type: "connector",
|
||||
connector: { from: { x: attachX, y: attachY }, to: rId, toAnchor: "right", lineShape: "straight", endArrow: "none", lineColor: color.stroke }
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
fs.writeFileSync('diagram.json', JSON.stringify({ version: 2, nodes }, null, 2));
|
||||
```
|
||||
|
||||
## 连线格式与注意点
|
||||
|
||||
所有 connector 都用 `{ "type": "connector", "connector": { ... } }` 格式。
|
||||
**注意：除了主骨外，其他所有连线（分支骨、原因小骨）都必须设置 `"endArrow": "none"`，否则会默认带箭头，导致方向混乱。**
|
||||
|
||||
分支骨：从主骨上的绝对坐标点 → 分类标签节点：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{ "type": "rect", "x": 0, "y": 0, "width": "__totalWidth__", "height": "__totalHeight__" },
|
||||
|
||||
{ "type": "ellipse", "id": "head", "x": "__headX__", "y": "__headY__",
|
||||
"width": 180, "height": 80, "text": "[中心问题]" },
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": "__spineStartX__", "y": "__spineY__" },
|
||||
"to": "head", "toAnchor": "left",
|
||||
"lineShape": "straight", "endArrow": "arrow"
|
||||
}},
|
||||
|
||||
{ "type": "rect", "id": "c0", "x": "__catX__", "y": "__catY__",
|
||||
"width": 120, "height": 40, "text": "[分类A]" },
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": "__spineX0__", "y": "__spineY__" },
|
||||
"to": "c0", "toAnchor": "bottom",
|
||||
"lineShape": "straight", "endArrow": "none"
|
||||
}},
|
||||
|
||||
{ "type": "rect", "id": "c0-r0", "x": "__reasonX__", "y": "__reasonY__",
|
||||
"width": 140, "height": 32, "text": "[原因1]" },
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": "__attachX__", "y": "__attachY__" },
|
||||
"to": "c0-r0", "toAnchor": "right",
|
||||
"lineShape": "straight", "endArrow": "none"
|
||||
}}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
上述骨架展示一个分类（上方）+ 一条原因的模式。完整鱼骨图重复此模式，上下交替。每个分类下可有多条原因，均匀插值分布在分支骨上。
|
||||
|
||||
## 陷阱
|
||||
|
||||
- **代码生成**：必须使用带有动态防重叠算法的脚本来计算坐标并输出 JSON。
|
||||
- **分支骨防重叠**：同一侧的相邻分支骨和原因框必须没有任何交叉。
|
||||
- **自适应高度**：原因数量较多时，分支骨自动拉长以容纳所有小骨。
|
||||
- **原因小骨水平**：原因框右侧的附着点必须与连线起点 Y 坐标一致。
|
||||
- **无箭头**：所有分类的分支连线、小骨连线均必须关闭箭头。
|
||||
- **同色系**：同一个分支骨、分类标签节点以及原因小骨节点和连线，必须使用同色系的颜色以保持视觉连贯性。
|
||||
185
.claude/skills/lark-whiteboard/scenes/flowchart.md
Normal file
185
.claude/skills/lark-whiteboard/scenes/flowchart.md
Normal file
@ -0,0 +1,185 @@
|
||||
# 流程图 (Flowchart)
|
||||
|
||||
适用于：各种业务流转图、决策树、审批流、时序控制逻辑、带条件判断的链路、系统架构拓扑等。
|
||||
|
||||
通用字段语义详见 `elements/schema.md`，通用布局原则详见 `elements/layout.md`；本文件只描述流程图场景下的选型边界与范式。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **流程图必须走 DSL 路径，不再使用 Mermaid！**
|
||||
> 复杂分支、判断、回路、跳级关系优先使用 `layout: "dagre"` 计算拓扑；如果只是规整的单线流水线，且卡片强对齐比自动拓扑更重要，也可以使用 Flex + 顶层 `connector` 组合实现。
|
||||
|
||||
## 美学规范
|
||||
|
||||
- **摒弃简陋节点，推崇全卡片化**：核心业务节点不要只用一个纯文本 `rect`。**应优先采用 Flex 组合卡片**（如：在 `vertical` frame 内上下组合【Emoji 标题项】和【补充说明项】），使得节点信息结构化、层级分明。
|
||||
- **语义化色彩编排**：节点底色严禁随机分配。必须按状态语义映射：常规链路用浅蓝/浅紫、核心风控/检查用预警黄、成功通过用生命绿、失败熔断用危险红。边框颜色可同色系加深，以凸显卡片边缘。
|
||||
- **统一判定逻辑**：条件分支必须使用 `diamond` 菱形节点，并且**严禁漏掉** `layoutOptions.edges` 边定义里的第三个标签参数（必须清晰写明"是/否"、"通过/拒绝"）。
|
||||
- **形状多样化**：合理搭配不同形状来表达语义 —— `ellipse` 用于外部实体/起终点、`diamond` 用于判断路由、`rect` 用于业务处理节点、`cylinder` 用于持久化存储。
|
||||
|
||||
## Layout 选型
|
||||
|
||||
| 模式 | 适用条件 | 核心配置 |
|
||||
| ---------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| **主体用 Dagre** | 有判断、分支、回路、回退、跳级关系的标准流程图 | 主体 frame 设定 `layout: "dagre"`，按需配置 `rankdir: "TB"` 或 `rankdir: "LR"`。 |
|
||||
| **局部复合节点** | 流程中的某一步本身是一个小型 UI 组合体 | 外层仍用 `dagre`，复合步骤内部改用 `layout: "vertical"` / `"horizontal"`。此类节点为**不透明节点**，外层连线只能连到外壳。 |
|
||||
| **透明子图** | 需按业务区域分组，且连线穿越区域边界 | 子容器声明 `layout: "dagre"` + `layoutOptions: { isCluster: true }`，成为透明子图。内部节点直接参与外层拓扑运算。 |
|
||||
| **规整流水线** | 基本是单线 A → B → C → D，且卡片对齐要求极高 | 主体可用 Flex 排版，连线改用顶层 `connector`；不要为了"自动"而硬上 Dagre。 |
|
||||
|
||||
## 核心属性
|
||||
|
||||
- **`rankdir`**: `TB`（上下）或 `LR`（左右）。**强烈推荐优先使用 `LR`**，充分利用宽屏横向空间。
|
||||
- **`edges`**: 在根 Dagre 的 `layoutOptions.edges` 中按 `[fromId, toId, "标签"]` 声明。**支持反向连接**实现闭环。所有 edges 统一写在**最外层根 Dagre**，不要写在 cluster 内部。
|
||||
- **`ranksep` 与边文本**: 若边上标注了说明文字，**必须根据字数调大间距**：`ranksep = max(60, 字数 × 16)`。
|
||||
- **自适应尺寸**: dagre 容器**必须**设定 `width: "fit-content"` 和 `height: "fit-content"`。
|
||||
- **`clusterTitle`**: 透明子图可通过 `clusterTitle` 声明悬浮标题（自动吸附左上角、加粗 14px），搭配 `clusterTitleColor` 指定标题颜色。
|
||||
|
||||
## 两种嵌套模式
|
||||
|
||||
### 不透明节点（Opaque Node）
|
||||
Dagre 内的子容器，只要未声明 `isCluster: true`，对外层 Dagre 就是具有确定宽高的原子节点。外层连线无法寻址其内部子节点。适合封装复杂的组合卡片（如带图标、版本号、多行描述的业务模块）。
|
||||
|
||||
### 透明子图（Compound Cluster）
|
||||
子容器同时声明 `layout: "dagre"` 与 `layoutOptions: { isCluster: true }` 时，成为外层 Dagre 的复合子图。其内部子节点直接参与外层拓扑运算，连线可穿越子图边界。适合划分网络区域、功能层级、命名空间等边界容器。推荐搭配 `borderDash: "dashed"` 虚线边框 + 淡色背景。
|
||||
|
||||
## 骨架示例（推荐范本）
|
||||
|
||||
以下是一个混合架构拓扑的完整示例。它同时展示了**透明子图**（Kubernetes Zone，连线可穿透）和**不透明复合节点**（DB 集群、AI 引擎，连线只能连外壳）的标准写法，以及多种形状（ellipse / diamond / rect / cylinder）和语义化配色规范。
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "root",
|
||||
"x": 20, "y": 20,
|
||||
"layout": "dagre",
|
||||
"width": "fit-content", "height": "fit-content",
|
||||
"padding": 60,
|
||||
"fillColor": "#F8FAFC",
|
||||
"borderColor": "#CBD5E1",
|
||||
"borderWidth": 1,
|
||||
"borderRadius": 16,
|
||||
"layoutOptions": {
|
||||
"rankdir": "LR",
|
||||
"nodesep": 60,
|
||||
"ranksep": 120,
|
||||
"edges": [
|
||||
["user", "k8s_ingress", "HTTPS request"],
|
||||
["k8s_ingress", "web_pod", "Route UI"],
|
||||
["k8s_ingress", "api_pod", "Route API"],
|
||||
["web_pod", "api_pod", "Internal REST"],
|
||||
["api_pod", "db_cluster", "SQL Query"],
|
||||
["api_pod", "ai_service", "gRPC Stream"]
|
||||
]
|
||||
},
|
||||
"children": [
|
||||
{
|
||||
"type": "ellipse", "id": "user", "text": "Global Users",
|
||||
"width": 110, "height": 60,
|
||||
"fillColor": "#E2E8F0", "borderColor": "#64748B", "borderWidth": 1,
|
||||
"fontSize": 14, "textColor": "#334155"
|
||||
},
|
||||
{
|
||||
"type": "frame", "id": "zone_k8s",
|
||||
"layout": "dagre",
|
||||
"layoutOptions": {
|
||||
"isCluster": true,
|
||||
"clusterTitle": "☸️ Kubernetes Zone (isCluster)",
|
||||
"clusterTitleColor": "#2563EB"
|
||||
},
|
||||
"fillColor": "#EFF6FF", "borderColor": "#60A5FA",
|
||||
"borderWidth": 2, "borderDash": "dashed", "borderRadius": 24,
|
||||
"children": [
|
||||
{
|
||||
"type": "diamond", "id": "k8s_ingress", "text": "Nginx Ingress",
|
||||
"width": 130, "height": 70,
|
||||
"fillColor": "#DBEAFE", "borderColor": "#3B82F6", "borderWidth": 2,
|
||||
"textColor": "#1E40AF"
|
||||
},
|
||||
{
|
||||
"type": "rect", "id": "web_pod", "text": "Next.js SSR Pod",
|
||||
"width": 140, "height": 48,
|
||||
"fillColor": "#BFDBFE", "borderColor": "#2563EB", "borderWidth": 2,
|
||||
"borderRadius": 8, "textColor": "#1E3A8A"
|
||||
},
|
||||
{
|
||||
"type": "rect", "id": "api_pod", "text": "Go Lang API Pod",
|
||||
"width": 140, "height": 48,
|
||||
"fillColor": "#BFDBFE", "borderColor": "#2563EB", "borderWidth": 2,
|
||||
"borderRadius": 8, "textColor": "#1E3A8A"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame", "id": "db_cluster",
|
||||
"layout": "vertical", "gap": 16, "padding": [20, 24],
|
||||
"alignItems": "center",
|
||||
"fillColor": "#F0FDF4", "borderColor": "#22C55E",
|
||||
"borderWidth": 2, "borderRadius": 16,
|
||||
"children": [
|
||||
{
|
||||
"type": "text", "id": "db_title",
|
||||
"text": "🗄️ Highly Available DB (不透明)", "fontSize": 14, "textColor": "#14532D"
|
||||
},
|
||||
{
|
||||
"type": "frame", "id": "db_row", "layout": "horizontal", "gap": 20,
|
||||
"children": [
|
||||
{
|
||||
"type": "cylinder", "id": "db_master", "text": "Master",
|
||||
"width": 80, "height": 50,
|
||||
"fillColor": "#DCFCE7", "borderColor": "#16A34A", "borderWidth": 1,
|
||||
"textColor": "#166534"
|
||||
},
|
||||
{
|
||||
"type": "cylinder", "id": "db_replica", "text": "Replica",
|
||||
"width": 80, "height": 50,
|
||||
"fillColor": "#DCFCE7", "borderColor": "#16A34A", "borderWidth": 1,
|
||||
"textColor": "#166534"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame", "id": "ai_service",
|
||||
"layout": "vertical", "gap": 10, "padding": [16, 20],
|
||||
"alignItems": "center",
|
||||
"fillColor": "#FAF5FF", "borderColor": "#A855F7",
|
||||
"borderWidth": 2, "borderRadius": 12,
|
||||
"children": [
|
||||
{
|
||||
"type": "text", "id": "ai_title",
|
||||
"text": "🧠 Multi-Modal Engine (不透明)", "fontSize": 14, "textColor": "#6B21A8"
|
||||
},
|
||||
{
|
||||
"type": "rect", "id": "ai_version",
|
||||
"text": "v4.2.1-beta", "width": 90, "height": 22,
|
||||
"fillColor": "#E9D5FF", "borderColor": "#C084FC", "borderWidth": 1,
|
||||
"borderRadius": 4, "fontSize": 11, "textColor": "#581C87"
|
||||
},
|
||||
{
|
||||
"type": "text", "id": "ai_desc",
|
||||
"text": "Includes Vector Store\n& Transformer Blocks",
|
||||
"fontSize": 12, "textColor": "#7E22CE", "textAlign": "center"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**范本要点**：
|
||||
- `zone_k8s` 是**透明子图**（`isCluster: true` + `clusterTitle`），外部连线穿越虚线边界直达 `k8s_ingress`、`web_pod`、`api_pod`。
|
||||
- `db_cluster` 和 `ai_service` 是**不透明节点**（`layout: "vertical"`），内部用 Flex 组合了多行结构化信息，对外层 Dagre 是固定宽高的原子。连线只能连到外壳 ID。
|
||||
- 所有 `edges` 统一写在最外层根 Dagre 的 `layoutOptions` 中。
|
||||
- 本范本中用到了 `ellipse`（外部实体）、`diamond`（路由判断）、`rect`（业务节点）、`cylinder`（数据库存储）四种形状。
|
||||
|
||||
## 陷阱与常见报错防范
|
||||
|
||||
- **误用 Mermaid**：只要用户没有带 `mermaid` 具体语法代码，哪怕描述明确是"流程图"，也**强制使用 DSL 框架下的 Dagre 模式**。
|
||||
- **重复画线**：`dagre` 里的所有子节点关系通过 `edges` 定义，引擎会自动生成连线。**绝对不要再去外层用 `connector` 节点重复连一次**。
|
||||
- **穿透黑盒**：普通子容器是不透明节点，外部连线无法直接寻址其内部子节点（引擎会自动重定向至外壳）。若需穿透，必须声明 `layout: "dagre"` 与 `layoutOptions: { isCluster: true }`。
|
||||
- **`id` 缺失**：只要是在 `edges` 里出现的标识符，`children` 里一定能找到同名 `id` 的节点对应，拼写必须完全一致。
|
||||
- **宽度灾难**：Dagre 内容器禁止子框使用 `fill-container`，因为 dagre 父容器本身是被内容撑开的。
|
||||
195
.claude/skills/lark-whiteboard/scenes/flywheel.md
Normal file
195
.claude/skills/lark-whiteboard/scenes/flywheel.md
Normal file
@ -0,0 +1,195 @@
|
||||
# 增长飞轮图 (Flywheel)
|
||||
|
||||
> **必须写脚本生成 JSON。** 飞轮图需要极坐标计算阶段标签位置和 SVG 圆环切割，直接手写 JSON 无法正确实现同心圆环结构。请用下方脚本模板。
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 阶段 4-6 个，每阶段短标签（title + 可选 subtitle/desc）
|
||||
- 中心放置飞轮主题标题
|
||||
|
||||
## Layout 选型
|
||||
|
||||
- **脚本生成坐标**（必须）：用 .cjs 脚本极坐标计算阶段标签位置、SVG 圆环切割，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.13` 渲染
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- 同心圆遮挡法构建圆环：大圆（底色）+ 小圆（白色遮罩）+ 中心文字
|
||||
- nodes 数组顺序决定 z-index：先大圆 -> 小圆 -> 中心文字 -> SVG 切割 -> 外围卡片
|
||||
- 阶段标签均匀分布在圆环外围，每个标签到圆心距离相等
|
||||
- SVG polyline 切割圆环形成分段 + 箭头方向感
|
||||
- 阶段数多时需动态放大半径、缩小箭头折角、收紧文字容器
|
||||
|
||||
### 同心圆遮挡法详解
|
||||
|
||||
画一个大圆（作为飞轮的底层颜色），然后在它正中心画一个小圆（填充为白色 `#FFFFFF`）。大圆和小圆都设置 `borderWidth: 0`，通过叠加遮挡形成圆环。
|
||||
|
||||
nodes 数组中的图层顺序（必须严格遵守）：
|
||||
|
||||
1. **底层大圆** (`type: 'ellipse'`, 填色, `borderWidth: 0`)
|
||||
2. **遮罩小圆** (`type: 'ellipse'`, 白色填色, `borderWidth: 0`)
|
||||
3. **中心文字** — 必须在两个圆之后添加，否则被白色小圆盖住
|
||||
4. **SVG 切割箭头** — 覆盖在圆环上，用白色粗线 polyline 切出分段
|
||||
5. **外围阶段卡片** — 极坐标计算位置
|
||||
|
||||
### SVG 箭头线切割分段
|
||||
|
||||
通过插入一个铺满大圆区域的 `svg` 节点，利用极坐标计算每个分段交界处的坐标，使用 `<polyline>` 画与背景色相同的粗线条（白色、20px+ 宽度）。线条从内圆边缘穿过大圆边缘，并在穿过时产生一定角度的偏转（`da` 参数），在视觉上"切断"圆环并形成箭头方向感。
|
||||
|
||||
### 外围文字环绕布局
|
||||
|
||||
- 利用极坐标 `x = cx + R * cos(θ)` 计算每个分段的中心角度
|
||||
- 在计算出的坐标点放置 `frame` 容器（`layout: 'vertical'`）
|
||||
- 外围文字容器内部的 `text` 节点不能用 `width: 'fill-container'`，必须指定固定 width 配合 `height: 'fit-content'`
|
||||
|
||||
### 动态缩放优化（阶段数 >= 8 时必须）
|
||||
|
||||
当阶段数量较多（8 个、12 个或 16 个以上）时，必须动态调整：
|
||||
|
||||
- **放大画布与圆环半径**：节点越多，需要越长的圆周容纳外围文字。适当调大 `rOut` 和 `rIn`（如 16 阶段时 `rOut` 可设为 400+），同步放大 `cx`/`cy` 避免超出边界
|
||||
- **缩小箭头切割角度**：段数增多时每段夹角变小，保持默认折角会导致缝隙过大。应减小 `da`（如 `da = 4`）
|
||||
- **收紧外围文字容器**：缩窄 `boxWidth`，减小文字字号，确保相邻文本框不互相覆盖
|
||||
|
||||
## 骨架示例
|
||||
|
||||
此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `stages` 数组和 `centerTitle`/`centerSubtitle`，其余坐标全自动计算。
|
||||
|
||||
```javascript
|
||||
const { writeFileSync } = require('fs');
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// 只需修改这里 -- 填入用户要求的阶段数据和中心标题
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
const centerTitle = '{{CENTER_TITLE}}';
|
||||
const centerSubtitle = '{{CENTER_SUBTITLE}}'; // 可选，不需要就留空字符串
|
||||
|
||||
const stages = [
|
||||
{ title: '{{STAGE_1}}', subtitle: '{{SUB_1}}', desc: '{{DESC_1}}' },
|
||||
{ title: '{{STAGE_2}}', subtitle: '{{SUB_2}}', desc: '{{DESC_2}}' },
|
||||
{ title: '{{STAGE_3}}', subtitle: '{{SUB_3}}', desc: '{{DESC_3}}' },
|
||||
{ title: '{{STAGE_4}}', subtitle: '{{SUB_4}}', desc: '{{DESC_4}}' },
|
||||
];
|
||||
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
// 以下是自动计算逻辑，不需要修改
|
||||
// ══════════════════════════════════════════════════════════════
|
||||
|
||||
// --- 布局参数 ---
|
||||
const numSegments = stages.length;
|
||||
const cx = 600, cy = 450; // 画布中心
|
||||
const rOut = 240, rIn = 160; // 内外圆半径
|
||||
const textDist = rOut + 40; // 文字离圆心距离
|
||||
const boxWidth = 220; // 外围文字卡片宽度
|
||||
const boxHeight = 80; // 估算高度（用于偏移计算）
|
||||
const da = 8; // 箭头折角
|
||||
|
||||
const nodes = [];
|
||||
|
||||
// --- 图层 1：底层大圆（圆环底色） ---
|
||||
nodes.push({
|
||||
type: 'ellipse',
|
||||
x: cx - rOut, y: cy - rOut,
|
||||
width: rOut * 2, height: rOut * 2,
|
||||
borderWidth: 0,
|
||||
});
|
||||
|
||||
// --- 图层 2：遮罩小圆（白色） ---
|
||||
nodes.push({
|
||||
type: 'ellipse',
|
||||
x: cx - rIn, y: cy - rIn,
|
||||
width: rIn * 2, height: rIn * 2,
|
||||
borderWidth: 0,
|
||||
});
|
||||
|
||||
// --- 图层 3：中心文字（必须在两个圆之后） ---
|
||||
nodes.push({
|
||||
type: 'text',
|
||||
x: cx - rIn, y: cy - (centerSubtitle ? 30 : 20),
|
||||
width: rIn * 2, height: 'fit-content',
|
||||
text: [{ content: centerTitle, bold: true, fontSize: 32 }],
|
||||
textAlign: 'center',
|
||||
});
|
||||
if (centerSubtitle) {
|
||||
nodes.push({
|
||||
type: 'text',
|
||||
x: cx - rIn, y: cy + 20,
|
||||
width: rIn * 2, height: 'fit-content',
|
||||
text: [{ content: centerSubtitle, fontSize: 18 }],
|
||||
textAlign: 'center',
|
||||
});
|
||||
}
|
||||
|
||||
// --- 图层 4：SVG 切割箭头 ---
|
||||
let svg = `<svg viewBox="0 0 ${rOut * 2} ${rOut * 2}" xmlns="http://www.w3.org/2000/svg">`;
|
||||
for (let i = 0; i < numSegments; i++) {
|
||||
const a = -90 + i * (360 / numSegments);
|
||||
const rad = (a * Math.PI) / 180;
|
||||
const radMid = ((a + da) * Math.PI) / 180;
|
||||
const R1 = rIn - 5, R2 = rOut + 5, Rm = (rIn + rOut) / 2;
|
||||
const x1 = rOut + R1 * Math.cos(rad), y1 = rOut + R1 * Math.sin(rad);
|
||||
const x2 = rOut + Rm * Math.cos(radMid), y2 = rOut + Rm * Math.sin(radMid);
|
||||
const x3 = rOut + R2 * Math.cos(rad), y3 = rOut + R2 * Math.sin(rad);
|
||||
svg += `<polyline points="${x1},${y1} ${x2},${y2} ${x3},${y3}" stroke="#FFFFFF" stroke-width="20" fill="none" stroke-linejoin="round" stroke-linecap="round" />`;
|
||||
}
|
||||
svg += `</svg>`;
|
||||
nodes.push({
|
||||
type: 'svg',
|
||||
x: cx - rOut, y: cy - rOut,
|
||||
width: rOut * 2, height: rOut * 2,
|
||||
svg: { code: svg },
|
||||
});
|
||||
|
||||
// --- 图层 5：外围阶段卡片（极坐标计算位置） ---
|
||||
for (let i = 0; i < numSegments; i++) {
|
||||
const stage = stages[i];
|
||||
const a = -90 + (360 / numSegments) / 2 + i * (360 / numSegments);
|
||||
const rad = (a * Math.PI) / 180;
|
||||
const tx = cx + textDist * Math.cos(rad);
|
||||
const ty = cy + textDist * Math.sin(rad);
|
||||
|
||||
// 动态偏移：根据角度将文本框向外推
|
||||
let offsetX = 0, offsetY = 0;
|
||||
if (Math.cos(rad) > 0.1) offsetX = 0;
|
||||
else if (Math.cos(rad) < -0.1) offsetX = -boxWidth;
|
||||
else offsetX = -boxWidth / 2;
|
||||
if (Math.sin(rad) > 0.1) offsetY = 0;
|
||||
else if (Math.sin(rad) < -0.1) offsetY = -boxHeight;
|
||||
else offsetY = -boxHeight / 2;
|
||||
|
||||
const textW = boxWidth - 24; // 卡片 padding 12 * 2
|
||||
nodes.push({
|
||||
type: 'frame',
|
||||
x: tx + offsetX, y: ty + offsetY,
|
||||
width: boxWidth, height: 'fit-content',
|
||||
layout: 'vertical', gap: 8, padding: 12,
|
||||
alignItems: 'start',
|
||||
borderWidth: 2, borderRadius: 8,
|
||||
children: [
|
||||
{ type: 'text', width: textW, height: 'fit-content',
|
||||
text: [{ content: stage.title, bold: true, fontSize: 18 }], textAlign: 'left' },
|
||||
{ type: 'text', width: textW, height: 'fit-content',
|
||||
text: [{ content: stage.subtitle, fontSize: 14 }], textAlign: 'left' },
|
||||
{ type: 'text', width: textW, height: 'fit-content',
|
||||
text: [{ content: stage.desc, fontSize: 12 }], textAlign: 'left' },
|
||||
],
|
||||
});
|
||||
}
|
||||
|
||||
// --- 图表标题 ---
|
||||
nodes.push({
|
||||
type: 'text',
|
||||
x: cx - rOut - 100, y: 30,
|
||||
width: (rOut + 100) * 2, height: 'fit-content',
|
||||
text: [{ content: centerTitle, bold: true, fontSize: 24 }],
|
||||
textAlign: 'center',
|
||||
});
|
||||
|
||||
writeFileSync('diagram.json', JSON.stringify({ version: 2, nodes }, null, 2));
|
||||
```
|
||||
|
||||
## 陷阱
|
||||
|
||||
- **中心文字被 SVG 遮挡**：中心文字节点必须在大圆和小圆之后、SVG 之前添加，确保 z-index 正确
|
||||
- **缺方向指示箭头**：SVG polyline 切割线必须带角度偏转（da 参数），形成顺时针/逆时针箭头感
|
||||
- **标签位置不对称**：外围卡片必须用极坐标公式 `x = cx + R * cos(θ)` 均匀分布，不可手动摆放
|
||||
- **外围文字容器死锁**：`layout: 'vertical'` 的 frame 内部 text 节点不能用 `width: 'fill-container'`，必须指定固定 width
|
||||
101
.claude/skills/lark-whiteboard/scenes/funnel.md
Normal file
101
.claude/skills/lark-whiteboard/scenes/funnel.md
Normal file
@ -0,0 +1,101 @@
|
||||
# 漏斗图 (Funnel)
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 阶段 3-6 个
|
||||
- 每阶段一行标签 + 数值（如 "{{STAGE_NAME}} ({{PERCENTAGE}})"）
|
||||
- 文案尽量简短；长文案外置到漏斗旁边，图形内仅保留核心短文案
|
||||
|
||||
## Layout 选型
|
||||
|
||||
绝对定位。用 `trapezoid` / `triangle` 节点从宽到窄排列，height 用 `fit-content`。
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- 外层 frame 使用 `layout: "vertical"` + `alignItems: "center"` 居中对齐
|
||||
- 所有层必须使用脚本计算宽度，以保证**绝对完美的等斜率（直线边缘）**。切勿手写拍脑袋的宽度！
|
||||
- 每层间 gap 0-8px（紧密堆叠视觉效果好），从上到下宽度递减。注意 children 数组第一个元素是最顶层（最宽）
|
||||
- 所有图形节点必须设置 `"vFlip": false`（引擎默认朝上翻转，漏斗需要朝下）
|
||||
- 注意：因为 `vFlip: false` 且是倒金字塔结构，所以 `topWidth` 实际控制的是漏斗各层的**底部较窄边缘**。底层可用 `triangle`（`topWidth: 0`）收窄为尖角，或继续用 `trapezoid` 保持平底。
|
||||
|
||||
> **严格的斜率算法（必须在脚本中实现）**：
|
||||
> 要让漏斗的侧边形成一条完美的直线，**宽度的递减必须与高度和 gap 严格挂钩**。
|
||||
> 1. 设定整体宽度收缩系数 `angleK`（建议值 1.5 到 2.5，表示高度每增加1px，总宽度减少的像素数）。
|
||||
> 2. 因为从上往下变窄，所以公式是减法：`bottomWidth(即 topWidth 属性) = currentWidth - (height * angleK)`
|
||||
> 3. 下一层的顶宽公式（必须考虑 gap 带来的额外内收）：`nextLayerWidth = bottomWidth - (gap * angleK)`
|
||||
|
||||
## 脚本构建模板
|
||||
|
||||
此场景必须用 .cjs 脚本生成。
|
||||
|
||||
```javascript
|
||||
const fs = require('fs');
|
||||
|
||||
// 1. 配置基础参数
|
||||
const GAP = 4;
|
||||
const ANGLE_K = 2; // 斜率系数：高度每下降1px，宽度减少2px
|
||||
const LAYER_HEIGHT = 80;
|
||||
|
||||
const data = [
|
||||
{ text: "展现 (100%)", fillColor: "#F0F4FC", textColor: "#1F2329" },
|
||||
{ text: "点击 (50%)", fillColor: "#EAE2FE", textColor: "#1F2329" },
|
||||
{ text: "加购 (20%)", fillColor: "#DFF5E5", textColor: "#1F2329" },
|
||||
{ text: "成交 (5%)", fillColor: "#1F2329", textColor: "#FFFFFF" }
|
||||
];
|
||||
|
||||
// 计算第一层的初始宽度 (保证最底层缩到0或平底)
|
||||
// 倒推公式：startWidth = 最后一层底宽 + 所有高度消耗 + 所有gap消耗
|
||||
const totalHeightLoss = data.length * LAYER_HEIGHT * ANGLE_K;
|
||||
const totalGapLoss = (data.length - 1) * GAP * ANGLE_K;
|
||||
// 设定最底层为一个尖角 (底宽为0)
|
||||
let currentWidth = 0 + totalHeightLoss + totalGapLoss;
|
||||
|
||||
const children = data.map((layer, index) => {
|
||||
// 2. 根据公式计算当前层的底宽 (对应节点的 topWidth 属性)
|
||||
const currentBottomWidth = currentWidth - (LAYER_HEIGHT * ANGLE_K);
|
||||
|
||||
const node = {
|
||||
type: currentBottomWidth <= 0 ? "triangle" : "trapezoid",
|
||||
width: currentWidth,
|
||||
// 注意：漏斗中 topWidth 表示的是下方的窄边！如果 <=0 就用 triangle
|
||||
topWidth: Math.max(0, currentBottomWidth),
|
||||
height: LAYER_HEIGHT,
|
||||
vFlip: false, // 必须为 false
|
||||
text: layer.text,
|
||||
textAlign: "center",
|
||||
fillColor: layer.fillColor,
|
||||
borderColor: layer.fillColor,
|
||||
borderWidth: 2,
|
||||
fontSize: 16,
|
||||
textColor: layer.textColor
|
||||
};
|
||||
|
||||
// 3. 关键：计算下一层的顶宽。必须减去 gap 的向内收缩量！
|
||||
currentWidth = currentBottomWidth - (GAP * ANGLE_K);
|
||||
|
||||
return node;
|
||||
});
|
||||
|
||||
const output = {
|
||||
version: 2,
|
||||
nodes: [
|
||||
{
|
||||
type: "frame",
|
||||
layout: "vertical",
|
||||
alignItems: "center",
|
||||
gap: GAP,
|
||||
padding: 40,
|
||||
children: children
|
||||
}
|
||||
]
|
||||
};
|
||||
|
||||
fs.writeFileSync('diagram.json', JSON.stringify(output, null, 2));
|
||||
```
|
||||
|
||||
## 陷阱
|
||||
|
||||
- **不要手写随意递减的宽度**：这会导致漏斗侧边变成折线，不直。必须严格使用上述 `angleK` 公式计算。
|
||||
- **忘记计算 gap 带来的收缩**：如果下一层的 `width` 只是简单等于上一层的 `topWidth`，在有 gap 的情况下，衔接处会产生锯齿折角。必须减去 `gap * angleK`。
|
||||
- **vFlip 未设置**：忘记 `"vFlip": false` 会导致梯形朝上翻转，漏斗形状错误
|
||||
- **文字溢出底层**：底层越窄空间越小，短文案用 `\n` 换行，长文案外置到漏斗旁边（外层套 `layout: "horizontal"` 的 frame，漏斗一侧，说明文字另一侧）
|
||||
214
.claude/skills/lark-whiteboard/scenes/line-chart.md
Normal file
214
.claude/skills/lark-whiteboard/scenes/line-chart.md
Normal file
@ -0,0 +1,214 @@
|
||||
# 折线图
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 数据点 ≤ 15
|
||||
- Y 轴必须有单位标注（如 "万元"、"%"）
|
||||
- 折线系列 ≤ 3（超过太密看不清）
|
||||
|
||||
## Layout 选型
|
||||
|
||||
- **脚本生成坐标**（推荐）：用 .cjs 脚本计算数据点坐标和折线路径，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.13` 渲染
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- 白板坐标系 Y 轴向下为正，图表"底部原点"拥有最大 Y 值，数据点向上分布时 Y 减小
|
||||
- 数据点用小 ellipse 标记（width: 12, height: 12）
|
||||
- 折线用 connector straight 连接相邻数据点，endArrow: "none"
|
||||
- 坐标轴用 connector 直线，末端带箭头（endArrow: "arrow"）
|
||||
- 格线用虚线 connector（lineStyle: "dashed"，endArrow: "none"）
|
||||
- 刻度线短横线 connector（endArrow: "none"）
|
||||
- 数值标注放在数据点上方
|
||||
- 类别标签放在 X 轴下方，居中对齐数据点
|
||||
|
||||
## 坐标与尺寸计算指南
|
||||
|
||||
白板坐标系中，**X 轴向右为正，Y 轴向下为正**。图表的"底部原点"拥有最大的 Y 坐标，数据点向上分布时 Y 坐标减小。
|
||||
|
||||
1. **确定图表区域**：
|
||||
- 设定图表区高度 `chartHeight` 和宽度 `chartWidth`
|
||||
- 设定左下角坐标原点 `(originX, originY)`
|
||||
- 示例：originX=80, originY=480, chartWidth=900, chartHeight=400
|
||||
2. **Y 轴范围自适应**：
|
||||
- 找出数据最小值 `dataMin` 和最大值 `dataMax`
|
||||
- yMin 不一定为 0：若数据集中在 80-120，Y 轴从 0 开始会让折线挤在顶部一小段区域
|
||||
- 推荐：yMin = 向下取整到合适刻度（如 dataMin=82 → yMin=80），yMax = 向上取整（如 dataMax=118 → yMax=120）
|
||||
- 当数据波动极小时（如 98-102），适当扩大范围避免折线过于平坦
|
||||
3. **数据点坐标计算**：
|
||||
- X 坐标：在可用宽度内均匀分布。`pointX = originX + (i / (pointCount - 1)) * chartWidth`
|
||||
- Y 坐标：按比例映射到高度。`pointY = originY - ((value - yMin) / (yMax - yMin)) * chartHeight`
|
||||
- ellipse 定位：`ellipseX = pointX - 6, ellipseY = pointY - 6`（圆心对齐数据点）
|
||||
4. **连线逻辑**：
|
||||
- 用 connector straight 将相邻数据点连接
|
||||
- `from` = 点[i] 的 (pointX, pointY)，`to` = 点[i+1] 的 (pointX, pointY)
|
||||
- startArrow: "none", endArrow: "none"
|
||||
5. **Y 轴刻度计算**：
|
||||
- 将 yMin 到 yMax 等分为 4-5 个刻度
|
||||
- 每个刻度的 Y 坐标：`gridY = originY - ((tickValue - yMin) / (yMax - yMin)) * chartHeight`
|
||||
|
||||
## 完整 JSON 示例
|
||||
|
||||
以下示例：4 个数据点，数据 [120, 200, 150, 180]，yMin=100, yMax=220，originX=80, originY=480, chartWidth=900, chartHeight=400。
|
||||
|
||||
- 刻度：100, 130, 160, 190, 220（每 30 一格）
|
||||
- 点0 (120): pointX=80, pointY=480-((120-100)/120)*400=480-66.7=413
|
||||
- 点1 (200): pointX=80+300=380, pointY=480-((200-100)/120)*400=480-333.3=147
|
||||
- 点2 (150): pointX=80+600=680, pointY=480-((150-100)/120)*400=480-166.7=313
|
||||
- 点3 (180): pointX=80+900=980, pointY=480-((180-100)/120)*400=480-266.7=213
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{ "type": "rect", "x": 0, "y": 0, "width": 1100, "height": 580 },
|
||||
|
||||
{ "type": "text", "x": 80, "y": 10, "width": 900, "height": "fit-content",
|
||||
"text": "季度销售额趋势", "fontSize": 24, "textAlign": "center" },
|
||||
|
||||
{ "type": "text", "x": 10, "y": 40, "width": 60, "height": "fit-content",
|
||||
"text": "万元", "fontSize": 12, "textAlign": "center" },
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 480 }, "to": { "x": 80, "y": 55 },
|
||||
"lineShape": "straight", "lineWidth": 2, "endArrow": "arrow"
|
||||
}},
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 480 }, "to": { "x": 1000, "y": 480 },
|
||||
"lineShape": "straight", "lineWidth": 2, "endArrow": "arrow"
|
||||
}},
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 70, "y": 480 }, "to": { "x": 80, "y": 480 },
|
||||
"lineShape": "straight", "lineWidth": 1,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "text", "x": 20, "y": 470, "width": 50, "height": 20,
|
||||
"text": "100", "fontSize": 12, "textAlign": "right" },
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 70, "y": 380 }, "to": { "x": 80, "y": 380 },
|
||||
"lineShape": "straight", "lineWidth": 1,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "text", "x": 20, "y": 370, "width": 50, "height": 20,
|
||||
"text": "130", "fontSize": 12, "textAlign": "right" },
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 380 }, "to": { "x": 980, "y": 380 },
|
||||
"lineShape": "straight", "lineWidth": 1, "lineStyle": "dashed",
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 70, "y": 280 }, "to": { "x": 80, "y": 280 },
|
||||
"lineShape": "straight", "lineWidth": 1,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "text", "x": 20, "y": 270, "width": 50, "height": 20,
|
||||
"text": "160", "fontSize": 12, "textAlign": "right" },
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 280 }, "to": { "x": 980, "y": 280 },
|
||||
"lineShape": "straight", "lineWidth": 1, "lineStyle": "dashed",
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 70, "y": 180 }, "to": { "x": 80, "y": 180 },
|
||||
"lineShape": "straight", "lineWidth": 1,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "text", "x": 20, "y": 170, "width": 50, "height": 20,
|
||||
"text": "190", "fontSize": 12, "textAlign": "right" },
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 180 }, "to": { "x": 980, "y": 180 },
|
||||
"lineShape": "straight", "lineWidth": 1, "lineStyle": "dashed",
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 70, "y": 80 }, "to": { "x": 80, "y": 80 },
|
||||
"lineShape": "straight", "lineWidth": 1,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "text", "x": 20, "y": 70, "width": 50, "height": 20,
|
||||
"text": "220", "fontSize": 12, "textAlign": "right" },
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 80 }, "to": { "x": 980, "y": 80 },
|
||||
"lineShape": "straight", "lineWidth": 1, "lineStyle": "dashed",
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 80, "y": 413 }, "to": { "x": 380, "y": 147 },
|
||||
"lineShape": "straight", "lineWidth": 3,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 380, "y": 147 }, "to": { "x": 680, "y": 313 },
|
||||
"lineShape": "straight", "lineWidth": 3,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
{ "type": "connector", "connector": {
|
||||
"from": { "x": 680, "y": 313 }, "to": { "x": 980, "y": 213 },
|
||||
"lineShape": "straight", "lineWidth": 3,
|
||||
"startArrow": "none", "endArrow": "none"
|
||||
}},
|
||||
|
||||
{ "type": "ellipse", "id": "pt-0", "x": 74, "y": 407,
|
||||
"width": 12, "height": 12 },
|
||||
{ "type": "text", "x": 55, "y": 383,
|
||||
"width": 50, "height": 20,
|
||||
"text": "120", "fontSize": 14, "textAlign": "center" },
|
||||
{ "type": "text", "x": 50, "y": 490,
|
||||
"width": 60, "height": 30,
|
||||
"text": "Q1", "fontSize": 14, "textAlign": "center" },
|
||||
|
||||
{ "type": "ellipse", "id": "pt-1", "x": 374, "y": 141,
|
||||
"width": 12, "height": 12 },
|
||||
{ "type": "text", "x": 355, "y": 117,
|
||||
"width": 50, "height": 20,
|
||||
"text": "200", "fontSize": 14, "textAlign": "center" },
|
||||
{ "type": "text", "x": 350, "y": 490,
|
||||
"width": 60, "height": 30,
|
||||
"text": "Q2", "fontSize": 14, "textAlign": "center" },
|
||||
|
||||
{ "type": "ellipse", "id": "pt-2", "x": 674, "y": 307,
|
||||
"width": 12, "height": 12 },
|
||||
{ "type": "text", "x": 655, "y": 283,
|
||||
"width": 50, "height": 20,
|
||||
"text": "150", "fontSize": 14, "textAlign": "center" },
|
||||
{ "type": "text", "x": 650, "y": 490,
|
||||
"width": 60, "height": 30,
|
||||
"text": "Q3", "fontSize": 14, "textAlign": "center" },
|
||||
|
||||
{ "type": "ellipse", "id": "pt-3", "x": 974, "y": 207,
|
||||
"width": 12, "height": 12 },
|
||||
{ "type": "text", "x": 955, "y": 183,
|
||||
"width": 50, "height": 20,
|
||||
"text": "180", "fontSize": 14, "textAlign": "center" },
|
||||
{ "type": "text", "x": 950, "y": 490,
|
||||
"width": 60, "height": 30,
|
||||
"text": "Q4", "fontSize": 14, "textAlign": "center" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
坐标推导验证：
|
||||
- 点0 (Q1, 120): pointX = 80 + (0/3)*900 = 80, pointY = 480 - ((120-100)/120)*400 = 413
|
||||
- 点1 (Q2, 200): pointX = 80 + (1/3)*900 = 380, pointY = 480 - ((200-100)/120)*400 = 147
|
||||
- 点2 (Q3, 150): pointX = 80 + (2/3)*900 = 680, pointY = 480 - ((150-100)/120)*400 = 313
|
||||
- 点3 (Q4, 180): pointX = 80 + (3/3)*900 = 980, pointY = 480 - ((180-100)/120)*400 = 213
|
||||
- ellipse 定位：ellipseX = pointX - 6, ellipseY = pointY - 6
|
||||
|
||||
## 陷阱
|
||||
|
||||
- Y 轴范围不合理：若数据集中在 80-120，Y 轴从 0 到 120 会让折线挤在顶部一小段区域，应设 yMin 接近数据最小值
|
||||
- 缺 Y 轴单位标注，读者无法理解数值含义
|
||||
- 数据点太密时标注互相遮挡（超过 10 个点考虑隔一个标注一次）
|
||||
- 折线段忘记设 endArrow: "none"，默认带箭头
|
||||
- 多系列时折线颜色相近难以区分，应使用对比度高的不同色系
|
||||
|
||||
此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `data` 数组，其余坐标与折线生成全自动计算。
|
||||
|
||||
```javascript
|
||||
const { writeFileSync } = require('fs');
|
||||
```
|
||||
130
.claude/skills/lark-whiteboard/scenes/mermaid.md
Normal file
130
.claude/skills/lark-whiteboard/scenes/mermaid.md
Normal file
@ -0,0 +1,130 @@
|
||||
# Mermaid 图表路径
|
||||
|
||||
本场景与 DSL 路径互斥。
|
||||
|
||||
| | DSL 路径 | Mermaid 路径 |
|
||||
|---|---|---|
|
||||
| 中间格式 | JSON（WBDocument） | Mermaid 文本（.mmd 文件） |
|
||||
| 布局控制 | 精确控制（x/y 坐标、Flex） | 由 parser-kit 自动布局 |
|
||||
| 视觉定制 | 完全可控（颜色、字号、圆角等） | 有限（Mermaid 语法） |
|
||||
| 参考模块 | elements/ + 对应 scene | 仅本文件 |
|
||||
|
||||
## 适用条件
|
||||
|
||||
满足以下任一条件时使用：
|
||||
- 用户明确要求 "用 Mermaid" 或 "输出 Mermaid"
|
||||
- 用户直接粘贴了 Mermaid 语法文本
|
||||
- 图表类型为思维导图、时序图、类图、饼图（自动路由）
|
||||
|
||||
## 思维导图 (Mindmap)
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
root((主题))
|
||||
分支A
|
||||
子项A1
|
||||
子项A2
|
||||
分支B
|
||||
子项B1
|
||||
分支C
|
||||
```
|
||||
|
||||
## 时序图 (Sequence Diagram)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant A as 浏览器
|
||||
participant B as 服务器
|
||||
participant C as 数据库
|
||||
A->>B: 请求数据
|
||||
B->>C: 查询
|
||||
C-->>B: 返回结果
|
||||
B-->>A: 响应数据
|
||||
```
|
||||
|
||||
消息类型：
|
||||
- `->>` 实线箭头（同步请求）
|
||||
- `-->>` 虚线箭头（响应/异步）
|
||||
- `-x` 带 x 箭头（失败）
|
||||
|
||||
## 类图 (Class Diagram)
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Animal {
|
||||
+String name
|
||||
+int age
|
||||
+makeSound()
|
||||
}
|
||||
class Dog {
|
||||
+fetch()
|
||||
}
|
||||
Animal <|-- Dog
|
||||
```
|
||||
|
||||
## 饼图 (Pie Chart)
|
||||
|
||||
```mermaid
|
||||
pie title 分布
|
||||
"类别A" : 40
|
||||
"类别B" : 30
|
||||
"类别C" : 20
|
||||
"类别D" : 10
|
||||
```
|
||||
|
||||
## 流程图 (Flowchart)
|
||||
|
||||
> [!WARNING]
|
||||
> **流程图不推荐使用 Mermaid 路径！**
|
||||
> 带复杂分支、复合节点、高保真卡片样式的流程图应优先走 **DSL 路径**（参见 `scenes/flowchart.md`）。只有用户明确给出 Mermaid 代码，或场景本身就是极简文字流程时，才走此路径。
|
||||
|
||||
适用于：极简的文字节点判断业务流。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([开始]) --> B{条件判断}
|
||||
B -->|是| C[处理步骤]
|
||||
B -->|否| D[另一步骤]
|
||||
C --> E([结束])
|
||||
D --> E
|
||||
```
|
||||
|
||||
### 约束与规范
|
||||
|
||||
- **节点文字 ≤ 8 字**（超过必须缩写，必要时加图例说明）
|
||||
- 判断节点（菱形）只写条件关键词，不写长描述
|
||||
- 步骤数 ≤ 12（超过需合并步骤或拆分为子流程）
|
||||
- 遵循标准流程图符号：开始/结束用体育场形状或圆形 `A([开始])`，判断用菱形 `B{判断}`，步骤用矩形 `C[步骤]`
|
||||
|
||||
### 语法参考
|
||||
|
||||
方向：`TD`（上到下）、`LR`（左到右）、`BT`（下到上）、`RL`（右到左）
|
||||
|
||||
节点形状：`A[矩形]`、`A(圆角)`、`A{菱形}`、`A((圆形))`、`A([体育场])`、`A[[子程序]]`
|
||||
|
||||
连线：`-->`（实线）、`-.->`（虚线）、`==>`（粗线）、`-->|标签|`（带标签）
|
||||
|
||||
## State Diagram
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Idle
|
||||
Idle --> Processing : 收到请求
|
||||
Processing --> Success : 处理成功
|
||||
Processing --> Failed : 处理失败
|
||||
Success --> [*]
|
||||
Failed --> Idle : 重试
|
||||
```
|
||||
|
||||
## 其他支持的图表类型
|
||||
|
||||
- **甘特图**：`gantt`
|
||||
- **ER 图**：`erDiagram`
|
||||
- **Git 分支图**：`gitGraph`
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 输出纯 Mermaid 文本，不是 JSON，不要混用 DSL
|
||||
- 节点文字含特殊字符时用双引号包裹：`A["包含(括号)的文字"]`
|
||||
- `subgraph` 用于逻辑分组
|
||||
- Mermaid 的流程图样式较基础，也无法在节点内部嵌套复杂排版；复杂流程优先走 DSL（见 `scenes/flowchart.md`），极简文字流程或用户显式给 Mermaid 代码时再使用 Mermaid。
|
||||
139
.claude/skills/lark-whiteboard/scenes/milestone.md
Normal file
139
.claude/skills/lark-whiteboard/scenes/milestone.md
Normal file
@ -0,0 +1,139 @@
|
||||
# 里程碑时间线 (Milestone)
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 节点 4-8 个
|
||||
- 每节点：标题 + 日期 + 可选描述
|
||||
- 时间从左到右递增
|
||||
|
||||
## Layout 选型
|
||||
|
||||
两种方案按需选择：
|
||||
|
||||
1. **横向时间线**：horizontal frame，节点等分
|
||||
2. **交替上下**：绝对定位，节点交替在时间轴上下方（节点多时更紧凑）
|
||||
|
||||
## 结构特征
|
||||
|
||||
- **标题居中**：顶部放置图表标题
|
||||
- **年份/时间轴条**：箭头形色块承载年份，按时间从左到右递增
|
||||
- **里程碑卡片**：下方虚线圆角卡片承载标题与描述
|
||||
- **严格对齐**：年份条与对应卡片等宽，左右对齐
|
||||
- **文字层级**：标题加粗在上，描述文字更小更浅在下，居中对齐
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- 绝对定位为主（`layout: "none"`），节点位置承载时间序列含义
|
||||
- 先确定里程碑数量，计算等距的 x 坐标序列
|
||||
- 时间轴用 connector 贯穿所有节点
|
||||
- 节点与时间轴用短竖线连接
|
||||
- 节点间水平间距一致
|
||||
- 年份条宽度 = 卡片宽度，垂直间距统一
|
||||
- 标题与年份区域保留足够留白
|
||||
|
||||
## 骨架示例
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "frame",
|
||||
"x": 0, "y": 0,
|
||||
"width": 1200, "height": 360,
|
||||
"layout": "none",
|
||||
"children": [
|
||||
{
|
||||
"type": "text",
|
||||
"x": 300, "y": 12,
|
||||
"width": 600, "height": "fit-content",
|
||||
"text": [{ "content": "{{CHART_TITLE}}", "bold": true, "fontSize": 24 }],
|
||||
"textAlign": "center"
|
||||
},
|
||||
|
||||
{
|
||||
"type": "svg",
|
||||
"x": 50, "y": 56,
|
||||
"width": 190, "height": 36,
|
||||
"svg": {
|
||||
"code": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 190 36\"><polygon points=\"0,0 170,0 190,18 170,36 0,36\"/></svg>"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 50, "y": 64,
|
||||
"width": 190, "height": "fit-content",
|
||||
"text": "{{DATE_1}}",
|
||||
"textAlign": "center"
|
||||
},
|
||||
{
|
||||
"type": "rect",
|
||||
"x": 50, "y": 132,
|
||||
"width": 190, "height": 120,
|
||||
"borderDash": "dashed",
|
||||
"borderRadius": 8
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 50, "y": 150,
|
||||
"width": 190, "height": "fit-content",
|
||||
"text": [{ "content": "{{MILESTONE_1_TITLE}}", "bold": true, "fontSize": 16 }],
|
||||
"textAlign": "center"
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 50, "y": 180,
|
||||
"width": 190, "height": "fit-content",
|
||||
"text": "{{MILESTONE_1_DESC}}",
|
||||
"fontSize": 13,
|
||||
"textAlign": "center"
|
||||
},
|
||||
|
||||
{
|
||||
"type": "svg",
|
||||
"x": 290, "y": 56,
|
||||
"width": 190, "height": 36,
|
||||
"svg": {
|
||||
"code": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 190 36\"><polygon points=\"0,0 170,0 190,18 170,36 0,36\"/></svg>"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 290, "y": 64,
|
||||
"width": 190, "height": "fit-content",
|
||||
"text": "{{DATE_2}}",
|
||||
"textAlign": "center"
|
||||
},
|
||||
{
|
||||
"type": "rect",
|
||||
"x": 290, "y": 132,
|
||||
"width": 190, "height": 120,
|
||||
"borderDash": "dashed",
|
||||
"borderRadius": 8
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 290, "y": 150,
|
||||
"width": 190, "height": "fit-content",
|
||||
"text": [{ "content": "{{MILESTONE_2_TITLE}}", "bold": true, "fontSize": 16 }],
|
||||
"textAlign": "center"
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 290, "y": 180,
|
||||
"width": 190, "height": "fit-content",
|
||||
"text": "{{MILESTONE_2_DESC}}",
|
||||
"fontSize": 13,
|
||||
"textAlign": "center"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 陷阱
|
||||
|
||||
- **节点太多时太拥挤**：超过 6 个节点时考虑交替上下布局或增大画布宽度
|
||||
- **右侧节点与时间轴末端重叠**：最后一个节点的 x + width 不要超出画布边界
|
||||
- **年份条与卡片不对齐**：年份条和卡片的 x、width 必须完全一致
|
||||
173
.claude/skills/lark-whiteboard/scenes/organization.md
Normal file
173
.claude/skills/lark-whiteboard/scenes/organization.md
Normal file
@ -0,0 +1,173 @@
|
||||
# 组织架构图
|
||||
|
||||
适用于：公司组织架构、模块依赖树、分类层级树等树形层级结构的场景。
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 层级 ≤ 4
|
||||
- 每个父节点下 ≤ 5 个子节点
|
||||
- 叶节点有意义（不要只为凑数添加空节点）
|
||||
- 长文本用 `\n` 手动换行（如"研发负责人\n(CTO)"）
|
||||
|
||||
## Layout 选型
|
||||
|
||||
| 模式 | 适用条件 | 特征 |
|
||||
|------|---------|------|
|
||||
| **tree（居中展开）** | 有明确从属关系的层级结构 | 根节点居中，子节点横向排列，逐层展开。每个"父+子"用 vertical frame 包裹（子树模块） |
|
||||
| **grid（矩阵式）** | 多部门平级，每部门内部有细分 | 横向等分各部门，每部门内部 vertical 列表 |
|
||||
|
||||
## Layout 规则
|
||||
|
||||
以下规则违反会导致连线错乱或排版崩溃：
|
||||
|
||||
1. **子树包裹模式（关键）**：每个父节点和它的子节点群用一个 `layout: "vertical"` + `alignItems: "center"` 的 frame 包裹。**不要**把所有父节点放一层、所有子节点放另一层。*违反后果：父节点与子节点群中心偏移，正交连线无法合并，分裂成两条平行线。*
|
||||
2. **同层节点建议等高**：同层节点统一 `height`（如 60-70），保证连线横向主轴平直。如果文字长度差异大可用 `fit-content`，但要确保同层文字行数接近。*违反后果：同层节点高低不平，rightAngle 连线横向弯折错乱。*
|
||||
3. **垂直间距 >= 60**：父子间纵向 `gap: 60`。*违反后果：连线引擎没有足够空间折弯与合并，导致连线穿模或提前分叉。*
|
||||
4. **叶子容器偶数宽度**：包含叶子节点的横向 frame，宽度应手动计算（子节点宽度之和 + gap × (n-1)），如 2 个 120px 节点 + 20px gap = `width: 260`。或用 `fill-container` 自动等分。*违反后果：父节点中心与子节点群中心有像素级偏差。*
|
||||
5. **同层兄弟间横向 gap: 20-40**
|
||||
6. 最小字号 14px
|
||||
7. 连线：所有父子连线必须 `lineShape: "rightAngle"`（总线风格），`fromAnchor: "bottom"`, `toAnchor: "top"`。*违反后果：失去组织架构图专属的总线视觉效果。*
|
||||
8. 根 frame 宽度要足够（如 1200-1600），避免叶节点被挤压重叠
|
||||
9. 不同层级在 fontSize、borderWidth、颜色上递进区分（如 Root 深灰 → L1 浅蓝 → L2 浅绿 → L3 浅紫）
|
||||
10. 长文本用 `\n` 主动换行（如 "基础架构部\n(包含云原生)"），确保节点高度足够容纳
|
||||
|
||||
## 骨架示例
|
||||
|
||||
### 树形展开（子树包裹模式）
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "frame",
|
||||
"width": 1200,
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 48,
|
||||
"padding": 40,
|
||||
"alignItems": "center",
|
||||
"children": [
|
||||
{
|
||||
"type": "text",
|
||||
"id": "title",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"text": "[图表标题]",
|
||||
"fontSize": 24,
|
||||
"textAlign": "center",
|
||||
"verticalAlign": "middle"
|
||||
},
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "root-node",
|
||||
"width": 240,
|
||||
"height": "fit-content",
|
||||
"borderWidth": 3,
|
||||
"borderRadius": 8,
|
||||
"text": "[根节点名]",
|
||||
"fontSize": 18,
|
||||
"padding": 12
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 40,
|
||||
"padding": 0,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{
|
||||
"type": "frame",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 48,
|
||||
"padding": 0,
|
||||
"alignItems": "center",
|
||||
"children": [
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "child-a",
|
||||
"width": 200,
|
||||
"height": "fit-content",
|
||||
"borderWidth": 2,
|
||||
"borderRadius": 8,
|
||||
"text": "[子节点名]",
|
||||
"fontSize": 16,
|
||||
"padding": 10
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 40,
|
||||
"padding": 0,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{ "type": "rect", "id": "leaf-a1", "width": "fill-container", "height": "fit-content", "borderWidth": 1, "borderRadius": 8, "text": "[叶节点名]", "fontSize": 14, "padding": 8 },
|
||||
{ "type": "rect", "id": "leaf-a2", "width": "fill-container", "height": "fit-content", "borderWidth": 1, "borderRadius": 8, "text": "[叶节点名]", "fontSize": 14, "padding": 8 }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "vertical",
|
||||
"gap": 48,
|
||||
"padding": 0,
|
||||
"alignItems": "center",
|
||||
"children": [
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "child-b",
|
||||
"width": 200,
|
||||
"height": "fit-content",
|
||||
"borderWidth": 2,
|
||||
"borderRadius": 8,
|
||||
"text": "[子节点名]",
|
||||
"fontSize": 16,
|
||||
"padding": 10
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"layout": "horizontal",
|
||||
"gap": 40,
|
||||
"padding": 0,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{ "type": "rect", "id": "leaf-b1", "width": "fill-container", "height": "fit-content", "borderWidth": 1, "borderRadius": 8, "text": "[叶节点名]", "fontSize": 14, "padding": 8 },
|
||||
{ "type": "rect", "id": "leaf-b2", "width": "fill-container", "height": "fit-content", "borderWidth": 1, "borderRadius": 8, "text": "[叶节点名]", "fontSize": 14, "padding": 8 }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{ "type": "connector", "connector": { "from": "root-node", "to": "child-a", "fromAnchor": "bottom", "toAnchor": "top", "lineShape": "rightAngle", "lineWidth": 2 } },
|
||||
{ "type": "connector", "connector": { "from": "root-node", "to": "child-b", "fromAnchor": "bottom", "toAnchor": "top", "lineShape": "rightAngle", "lineWidth": 2 } },
|
||||
{ "type": "connector", "connector": { "from": "child-a", "to": "leaf-a1", "fromAnchor": "bottom", "toAnchor": "top", "lineShape": "rightAngle", "lineWidth": 2 } },
|
||||
{ "type": "connector", "connector": { "from": "child-a", "to": "leaf-a2", "fromAnchor": "bottom", "toAnchor": "top", "lineShape": "rightAngle", "lineWidth": 2 } },
|
||||
{ "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 } }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 陷阱
|
||||
|
||||
- **分离父子层级（致命错误）**：不要把所有同级父节点放一个 horizontal frame、所有子节点放另一个。必须用 `alignItems: "center"` 的 vertical frame 把每个父节点和它的子节点包裹在一起。
|
||||
- **同层节点高低不平**：同层节点高度应一致（或文字行数接近），否则 rightAngle 连线横向弯折错乱。
|
||||
- **垂直间距不足**：父子间 gap 必须 >= 60。不够时连线引擎无法折弯合并。也不要用 80，3-4 层会纵向拉伸过度。
|
||||
- **做成线性链而非树形展开**：每个父节点的子节点必须横向展开，不要做单链。
|
||||
- **连线混用 straight**：所有父子连线必须 `lineShape: "rightAngle"`，`fromAnchor: "bottom"`，`toAnchor: "top"`。
|
||||
- **叶节点字号 12px 看不清**：最小字号 14px。
|
||||
- **所有节点同一大小和样式**：不同层级必须在 fontSize、borderWidth、颜色上有区分（根>子>叶）。
|
||||
126
.claude/skills/lark-whiteboard/scenes/photo-showcase.md
Normal file
126
.claude/skills/lark-whiteboard/scenes/photo-showcase.md
Normal file
@ -0,0 +1,126 @@
|
||||
# 图片展示 (Photo Showcase)
|
||||
|
||||
适用于：用户**显式要求使用图片/配图/插图**的场景（如"画一个带配图的旅行路线"、"做一个有图片的产品展示"）。
|
||||
|
||||
> **注意**：仅当用户明确说了「图片/配图/插图/照片」等词时才进入本场景。单纯说"旅行路线图"、"产品展示"等不触发。
|
||||
|
||||
> **前置条件**：进入本场景前，必须已完成 [`elements/image.md`](../elements/image.md) 的 Step 0（图片准备），拿到所有 media token。
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 图片 3-6 张，每张配标题（必需）+ 简短描述（可选，15字内）
|
||||
- **每张图必须是不同的真实图片**（不同 media token），下载时用不同关键词/URL
|
||||
- 下载后用 `ls -l` 比较文件大小确保每张图不重复
|
||||
- 文字仅作辅助说明，图片是信息主体
|
||||
|
||||
## Layout 选型
|
||||
|
||||
| 模式 | 适用条件 | 特征 |
|
||||
|------|---------|------|
|
||||
| **卡片网格（默认）** | 多图平级展示（产品墙、团队介绍、美食推荐） | horizontal frame 内放等尺寸图文卡片 |
|
||||
| **路线时间线** | 有先后顺序（旅行路线、团建路线、项目演进） | 图文卡片 + connector 串联 |
|
||||
| **中心辐射** | 有一个核心主题 + 周围子项 | 中心标题 + 周围图文卡片 |
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- **图文卡片结构**：vertical frame（图上文下），image 宽度 = 卡片宽度，height 按 3:2 比例
|
||||
- **卡片统一尺寸**：所有卡片宽高一致（推荐 240×280 或 200×250）
|
||||
- **图片统一尺寸**：所有 image 节点用相同 width/height（推荐 240×160 或 200×133）
|
||||
- **卡片间距**：gap: 24（比纯文字图表间距更大，让图片呼吸）
|
||||
- **卡片样式**：白色底 + 圆角 12 + 细边框，image 无圆角（紧贴卡片顶部）
|
||||
- **有序路线时**：卡片间用 connector 连接，connector 放顶层 nodes 数组
|
||||
|
||||
## 骨架示例
|
||||
|
||||
### 卡片网格（产品展示/团队介绍/美食推荐）
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "frame", "id": "grid", "layout": "vertical", "gap": 24, "padding": 32,
|
||||
"width": 840, "height": "fit-content",
|
||||
"children": [
|
||||
{ "type": "text", "id": "title", "width": 776, "height": 36,
|
||||
"text": "图表标题", "fontSize": 24, "textAlign": "center" },
|
||||
{
|
||||
"type": "frame", "id": "row", "layout": "horizontal", "gap": 24, "padding": 0,
|
||||
"width": "fit-content", "height": "fit-content",
|
||||
"children": [
|
||||
{
|
||||
"type": "frame", "id": "card-1", "layout": "vertical", "gap": 8, "padding": [0, 0, 12, 0],
|
||||
"width": 240, "height": "fit-content",
|
||||
"fillColor": "#FFFFFF", "borderWidth": 1, "borderColor": "#E0E0E0", "borderRadius": 12,
|
||||
"children": [
|
||||
{ "type": "image", "id": "img-1", "width": 240, "height": 160, "image": { "src": "<token_1>" } },
|
||||
{ "type": "text", "id": "t-1", "text": "标题", "fontSize": 14, "width": 216, "height": 20 },
|
||||
{ "type": "text", "id": "d-1", "text": "简短描述", "fontSize": 11, "textColor": "#666666", "width": 216, "height": 16 }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
每张图文卡片结构相同，复制并替换 `<token_N>`、标题和描述即可。3 张卡片一行，超过 3 张换行（嵌套第二个 horizontal frame）。
|
||||
|
||||
### 路线时间线（旅行路线/团建路线）
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "frame", "id": "route", "layout": "vertical", "gap": 24, "padding": 32,
|
||||
"width": 1100, "height": "fit-content",
|
||||
"children": [
|
||||
{ "type": "text", "id": "title", "width": 1036, "height": 36,
|
||||
"text": "路线标题", "fontSize": 24, "textAlign": "center" },
|
||||
{
|
||||
"type": "frame", "id": "stops", "layout": "horizontal", "gap": 32, "padding": 0,
|
||||
"width": "fit-content", "height": "fit-content",
|
||||
"children": [
|
||||
{
|
||||
"type": "frame", "id": "stop-1", "layout": "vertical", "gap": 8, "padding": [0, 0, 12, 0],
|
||||
"width": 240, "height": "fit-content",
|
||||
"fillColor": "#FFFFFF", "borderWidth": 1, "borderColor": "#E0E0E0", "borderRadius": 12,
|
||||
"children": [
|
||||
{ "type": "image", "id": "img-1", "width": 240, "height": 160, "image": { "src": "<token_1>" } },
|
||||
{ "type": "text", "id": "t-1", "text": "第1站：地点名", "fontSize": 14, "width": 216, "height": 20 }
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame", "id": "stop-2", "layout": "vertical", "gap": 8, "padding": [0, 0, 12, 0],
|
||||
"width": 240, "height": "fit-content",
|
||||
"fillColor": "#FFFFFF", "borderWidth": 1, "borderColor": "#E0E0E0", "borderRadius": 12,
|
||||
"children": [
|
||||
{ "type": "image", "id": "img-2", "width": 240, "height": 160, "image": { "src": "<token_2>" } },
|
||||
{ "type": "text", "id": "t-2", "text": "第2站：地点名", "fontSize": 14, "width": 216, "height": 20 }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{ "type": "connector", "id": "c1", "connector": { "from": "stop-1", "to": "stop-2", "fromAnchor": "right", "toAnchor": "left" } }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
注意：connector 必须放在**顶层 nodes 数组**，不能嵌套在 frame.children 内。connector 的属性须包裹在 `connector` 字段中。
|
||||
|
||||
## 图片准备检查清单
|
||||
|
||||
生成 DSL 前确认：
|
||||
|
||||
- [ ] 所有 image 节点的 `image.src` 都是通过 `docs +media-upload --parent-type whiteboard` 上传的 media token（非 URL、非 Drive file token）
|
||||
- [ ] 所有图片已上传到目标画板（`--parent-node` 设为目标画板 token）
|
||||
- [ ] 每个 media token 不同（对应不同的真实图片）
|
||||
- [ ] 所有图片尺寸一致（同一画板内统一 width×height）
|
||||
- [ ] 图片宽高比合理（推荐 3:2，即 240×160）
|
||||
- [ ] 渲染 PNG 后查看图片内容，确认每张图片与主题相关
|
||||
- [ ] 未使用随机占位图服务（关键词参数不影响返回内容的图库）
|
||||
99
.claude/skills/lark-whiteboard/scenes/pyramid.md
Normal file
99
.claude/skills/lark-whiteboard/scenes/pyramid.md
Normal file
@ -0,0 +1,99 @@
|
||||
# 金字塔图 (Pyramid)
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 层级 3-6 个，从底到顶宽度递减
|
||||
- 每层一个短标签（如关键词或短语）
|
||||
- 长文案外置到金字塔旁边，图形内仅保留核心短文案
|
||||
|
||||
## Layout 选型
|
||||
|
||||
vertical frame + 每层宽度递减。gap 4px 保持紧密。
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- 外层 frame 使用 `layout: "vertical"` + `alignItems: "center"`
|
||||
- 所有层必须使用脚本计算宽度，以保证**绝对完美的等斜率（直线边缘）**。切勿手写拍脑袋的宽度！
|
||||
- children 数组中第一个元素是顶层（最窄），最后一个是底层（最宽）。
|
||||
- 顶层通常用 `triangle`（`topWidth: 0`），中间和底层用 `trapezoid`。
|
||||
- gap 通常设为 4px 保持紧密的金字塔感。
|
||||
|
||||
> **严格的斜率算法（必须在脚本中实现）**：
|
||||
> 要让金字塔的侧边形成一条完美的直线，**宽度的增量必须与高度和 gap 严格挂钩**。
|
||||
> 1. 设定整体宽度扩张系数 `angleK`（建议值 1.5 到 2.5，表示高度每增加1px，总宽度增加的像素数）。
|
||||
> 2. 当前层的底宽公式：`width = topWidth + (height * angleK)`
|
||||
> 3. 下一层的顶宽公式（必须考虑 gap 带来的额外外扩）：`nextTopWidth = width + (gap * angleK)`
|
||||
|
||||
## 脚本构建模板
|
||||
|
||||
必须使用 `node` 运行脚本生成 JSON。
|
||||
|
||||
```javascript
|
||||
const fs = require('fs');
|
||||
|
||||
// 1. 配置基础参数
|
||||
const GAP = 4;
|
||||
const ANGLE_K = 2; // 斜率系数：高度每增加1px，宽度增加2px
|
||||
const LAYER_HEIGHT = 80;
|
||||
|
||||
const data = [
|
||||
{ text: "顶层核心", fillColor: "#1F2329", textColor: "#FFFFFF" },
|
||||
{ text: "中间层 B", fillColor: "#DFF5E5", textColor: "#1F2329" },
|
||||
{ text: "中间层 A", fillColor: "#EAE2FE", textColor: "#1F2329" },
|
||||
{ text: "最底层基础", fillColor: "#F0F4FC", textColor: "#1F2329" }
|
||||
];
|
||||
|
||||
let currentTopWidth = 0; // 顶层如果是尖角，初始为 0
|
||||
const children = data.map((layer, index) => {
|
||||
// 2. 根据公式计算当前层的底宽
|
||||
const currentBottomWidth = currentTopWidth + (LAYER_HEIGHT * ANGLE_K);
|
||||
|
||||
const node = {
|
||||
type: currentTopWidth === 0 ? "triangle" : "trapezoid",
|
||||
width: currentBottomWidth,
|
||||
topWidth: currentTopWidth,
|
||||
height: LAYER_HEIGHT,
|
||||
text: layer.text,
|
||||
textAlign: "center",
|
||||
fillColor: layer.fillColor,
|
||||
borderColor: layer.fillColor,
|
||||
borderWidth: 2,
|
||||
fontSize: 16,
|
||||
textColor: layer.textColor
|
||||
};
|
||||
|
||||
// 3. 关键：计算下一层的顶宽。必须把 gap 的延伸也算进去！
|
||||
currentTopWidth = currentBottomWidth + (GAP * ANGLE_K);
|
||||
|
||||
return node;
|
||||
});
|
||||
|
||||
const output = {
|
||||
version: 2,
|
||||
nodes: [
|
||||
{
|
||||
type: "frame",
|
||||
layout: "vertical",
|
||||
alignItems: "center",
|
||||
gap: GAP,
|
||||
padding: 40,
|
||||
children: children
|
||||
}
|
||||
]
|
||||
};
|
||||
|
||||
fs.writeFileSync('diagram.json', JSON.stringify(output, null, 2));
|
||||
```
|
||||
|
||||
## 陷阱
|
||||
|
||||
- **不要手写随意递增的宽度**：这会导致金字塔侧边变成折线，不直。必须严格使用上述 `angleK` 公式计算。
|
||||
- **忘记计算 gap 带来的扩展**：如果下一层的 `topWidth` 只是简单等于上一层的 `width`，在有 gap 的情况下，衔接处会产生锯齿折角。必须加上 `gap * angleK`。
|
||||
- **从上到下排列错误**：children 数组第一个是顶层（最窄），最后一个是底层（最宽），宽度依次递增。
|
||||
- **文字溢出顶层三角形**：顶层三角形内部可用空间极小。短文案用 `\n` 手动换行；长文案外置到金字塔旁边（外层套 horizontal frame，金字塔左侧，说明文字右侧）
|
||||
- **倒金字塔误用**：如果用户要求"倒金字塔"、"漏斗图"或"自上而下递减的结构"，**不要**使用本文件，切换到 `scenes/funnel.md`
|
||||
|
||||
## 扩展
|
||||
|
||||
- **辅助说明**：需要在旁边添加文字说明时，在最外层套一个 `layout: "horizontal"` 的 frame，金字塔放左侧，说明文字（vertical 排列的 text 节点）放右侧
|
||||
- **配色**：各层颜色应从色板中选取不同颜色以示区分（如蓝→紫→绿→黄递进）
|
||||
371
.claude/skills/lark-whiteboard/scenes/swimlane.md
Normal file
371
.claude/skills/lark-whiteboard/scenes/swimlane.md
Normal file
@ -0,0 +1,371 @@
|
||||
# 泳道图（Swimlane）
|
||||
|
||||
适用于：跨角色/跨系统的端到端流程（用户/网关/服务/存储/回调）、多泳道协作流程、系统交互链路图。
|
||||
|
||||
支持两种方向：
|
||||
- **水平泳道**：泳道为横向条带（自上而下排列），流程从左到右推进
|
||||
- **垂直泳道**：泳道为纵向列（自左向右排列），流程从上到下推进
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 泳道数（lanes）建议 3-7，超过 7 会显著降低可读性；如必须更多泳道，优先合并同类或拆成两张图
|
||||
- 阶段数（stages）建议 4-8；超过 8 优先合并相邻阶段或改成“代表性阶段”
|
||||
- 每个阶段在每条泳道中最多放 1 个“主步骤卡片”；如同一阶段需要多个步骤，放在同一格内做纵向堆叠（2-3 个为上限）
|
||||
- 节点文本 1-2 行为主；长文本用 `\n` 手动换行，避免单行超长导致卡片过宽
|
||||
- 仅画必要连线：泳道图的结构已经表达了“属于哪个角色/系统 + 发生顺序”，连线只用于表达跨泳道交互、关键因果关系或异步事件流
|
||||
|
||||
## Layout 选型
|
||||
|
||||
| 模式 | 适用条件 | 特征 |
|
||||
|------|---------|------|
|
||||
| **水平泳道** | 默认推荐；流程天然左→右推进 | lanes=行，stages=列；跨泳道同一阶段严格 x 对齐 |
|
||||
| **垂直泳道** | 用户明确要求竖版、或画布更适合纵向滚动阅读 | lanes=列，stages=行；跨泳道同一阶段严格 y 对齐 |
|
||||
|
||||
## Layout 规则
|
||||
|
||||
### 通用规则（两种方向都适用）
|
||||
|
||||
1. **网格对齐是第一优先级**：跨泳道同一阶段必须严格对齐（水平对齐 x；垂直对齐 y）。对齐通过“共享阶段标尺（stage ruler / stage slots）”实现，不靠肉眼估算，也不靠逐节点随意手写坐标
|
||||
2. **只生成真实节点**：为保证跨泳道阶段严格对齐，所有阶段统一保留透明的 **stage cell**；仅在真实阶段的 cell 内生成卡片节点，并按阶段索引映射到对应槽位
|
||||
3. **泳道底色**：为了增强层级感同时保持界面整洁，**强烈建议所有泳道容器统一使用极浅灰色背景**（如 `fillColor: "#F8F9FA"` 或 `"#FCFCFC"`）。边框使用浅灰色细虚线（`borderDash: "dashed"`, `borderWidth: 1`, `borderColor: "#DEE0E3"`）以明确边界。
|
||||
4. **步骤卡片**：使用 `rect`。为建立清晰的视觉层级，卡片**必须填充浅色背景**（参考 `elements/style.md` 中的浅色板，如极浅的主题色），边框使用对应的主题主色（`borderWidth: 1-2`），文字使用深色（如 `#1F2329`）以确保可读性。统一圆角；宽高以可读为先，避免过窄导致换行过多
|
||||
5. **间距**：只要存在 connector 连线，卡片之间的主轴间距必须满足 `gap >= 40`
|
||||
|
||||
### 子节点对齐
|
||||
|
||||
- **同一阶段必须严格对齐**：所有泳道复用同一套 stage slots；不允许靠卡片自身宽度或肉眼估算来对齐
|
||||
- **卡片宽度一致**：同一泳道中的步骤卡片应保持统一宽度；推荐使用统一固定宽度，或严格复用同一槽位宽度
|
||||
- **统一使用 stack 容器**：有内容的阶段统一使用 `layout: "vertical"` 的 stack frame（纵向堆叠 1-3 张卡片）；空阶段不生成 stack/卡片，但保留透明 cell 保证对齐
|
||||
- **垂直居中但不影响对齐**：stage cell 默认 `alignItems: "stretch"`，可用 `justifyContent: "center"` 让卡片在 cell 内居中，以确保左右边界严格对齐
|
||||
- **不靠底色区分行/列**：阶段网格默认不需要背景色；如需“轻微”的行/列边界提示，优先给 stage cell 加 1px 细边框（`fillColor: "transparent"` 仍保持视觉透明）
|
||||
|
||||
### Flex 栅格模式（默认）
|
||||
|
||||
- lane body 使用 Flex 布局：水平泳道用 `layout: "horizontal"`，垂直泳道用 `layout: "vertical"`
|
||||
- 为每个阶段生成一个 **stage cell**（占位单元格）；空阶段的 cell 透明但保留；cell 内用 `layout: "vertical"` 的 stack 承载 1-3 张卡片
|
||||
- 统一参数：`slotWidth: 180-220`（水平泳道 cell 宽度）、`slotHeight: 64-104`（垂直泳道 cell 高度建议档）、`gap: 40-56`（有连线时必须 ≥40）、`stackGap: 8`、`lanePadding: 16`
|
||||
- 对齐规则：所有泳道复用同一组 `slotWidth/slotHeight/gap`；同一阶段在各泳道上使用相同的 cell 索引保证严格对齐
|
||||
- 尺寸语义：lane body `width/height` 用 `"fit-content"`（Yoga 自适应）；卡片 `height: "fit-content"`；Flex 容器内不写子节点 `x/y`
|
||||
- 内容密度：卡片文字 1-2 行；同阶段堆叠上限 2-3；超过上限优先拆分到相邻阶段或缩短文本
|
||||
|
||||
### 跨泳道间距（lanesGap）
|
||||
|
||||
- 根容器承载所有泳道：水平泳道用 `layout: "vertical"`，垂直泳道用 `layout: "horizontal"`
|
||||
- 缩减跨泳道主轴间距 `lanesGap`（建议 `16-24`），以保持整体图表的紧凑性。避免 `lanesGap` 设置为 `0` 导致边框重叠变粗，也避免间距过大导致视觉涣散。
|
||||
- 每条泳道作为根容器的子 frame，内部再使用上述 Flex 栅格的 stage cell 布局
|
||||
- `lanesGap` 与 `lanePadding/stackGap` 独立；lane 内容增减不应影响跨泳道间距
|
||||
- 4px 基线对齐：`lanesGap`、`lanePadding`、cell 尺寸建议按 4 的倍数对齐
|
||||
|
||||
### 水平泳道（lanes=行，stages=列）
|
||||
|
||||
- 根容器：`layout: "vertical"`，`gap: lanesGap` 固定；`alignItems: "stretch"`，标题在最上方
|
||||
- 每条泳道：一个可见 frame（分组容器），内部用 `layout: "horizontal"` 分成两块：
|
||||
- 左侧 lane label：固定宽度 text（如 100-140），垂直居中；左对齐（`textAlign: "left"`）；title 需要比步骤卡片更醒目，优先通过 `fontSize: 18-20` + `fontWeight: "bold"` + 与泳道边框一致的 `textColor` 实现
|
||||
- 右侧 lane body：`layout: "horizontal"`，包含完整的阶段 **stage cell** 数组；cell 宽度固定为 `slotWidth`，相邻 cell 间 `gap` 统一；空阶段 cell 透明但保留
|
||||
- 步骤卡片：推荐统一卡片宽度（如 160-220），并在所有泳道复用同一组 `slotWidth / gap`，保证跨泳道阶段严格 x 对齐
|
||||
|
||||
### 垂直泳道（lanes=列，stages=行）
|
||||
|
||||
- 根容器：`layout: "horizontal"`，`gap: lanesGap` 固定；`alignItems: "stretch"`，标题在最上方
|
||||
- 每条泳道：一个可见 frame（分组容器），内部 `layout: "vertical"`：
|
||||
- 顶部 lane label：必须放在单独的 `lane label frame` 中，label frame 使用 `width: "fill-container"`、`alignItems: "center"`、`justifyContent: "center"`，并通过 `paddingTop` 留出与泳道上边的 gap（推荐 `12-16`，按 4px 基线取值，如 `padding: [12, 8, 8, 8]`）；内部 text 使用 `width: "fill-container"` + `textAlign: "center"`，确保 title 在整条泳道顶部**水平居中**
|
||||
- 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: "#F8F9FA"`（极浅灰）、`borderDash: "dashed"`、`borderWidth: 1`、`borderColor: "#DEE0E3"`（统一浅灰色），否则会被编译为虚拟 frame 导致不渲染
|
||||
- 统一高度（Flex 自适应，可选）：根容器使用 `alignItems: "stretch"`，每个泳道外层 frame 使用 `height: "fill-container"`；泳道内部仍保持 lane label + lane body 的结构
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "lanes-root",
|
||||
"x": 40, "y": 40,
|
||||
"layout": "horizontal",
|
||||
"gap": 16,
|
||||
"alignItems": "stretch",
|
||||
"children": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "lane-left",
|
||||
"layout": "vertical",
|
||||
"width": "fit-content",
|
||||
"height": "fill-container",
|
||||
"fillColor": "#F8F9FA",
|
||||
"borderDash": "dashed",
|
||||
"borderWidth": 1,
|
||||
"borderColor": "#DEE0E3",
|
||||
"children": [
|
||||
{ "type": "frame", "id": "lane-left-label-wrap", "layout": "vertical", "width": "fill-container", "height": "fit-content",
|
||||
"alignItems": "center", "justifyContent": "center", "padding": [12, 8, 8, 8], "children": [
|
||||
{ "type": "text", "id": "lane-left-label", "text": "Lane Left", "width": "fill-container", "height": "fit-content",
|
||||
"textAlign": "center", "verticalAlign": "middle", "fontSize": 18, "fontWeight": "bold", "textColor": "#5178C6" }
|
||||
] },
|
||||
{ "type": "frame", "id": "lane-left-body", "layout": "vertical",
|
||||
"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 }] },
|
||||
{ "type": "frame", "id": "stage-2-cell-left", "layout": "vertical", "width": 220, "height": 80, "alignItems": "center", "justifyContent": "center", "children": [] }
|
||||
] }
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "lane-right",
|
||||
"layout": "vertical",
|
||||
"width": "fit-content",
|
||||
"height": "fill-container",
|
||||
"fillColor": "#F8F9FA",
|
||||
"borderDash": "dashed",
|
||||
"borderWidth": 1,
|
||||
"borderColor": "#DEE0E3",
|
||||
"children": [
|
||||
{ "type": "frame", "id": "lane-right-label-wrap", "layout": "vertical", "width": "fill-container", "height": "fit-content",
|
||||
"alignItems": "center", "justifyContent": "center", "padding": [12, 8, 8, 8], "children": [
|
||||
{ "type": "text", "id": "lane-right-label", "text": "Lane Right", "width": "fill-container", "height": "fit-content",
|
||||
"textAlign": "center", "verticalAlign": "middle", "fontSize": 18, "fontWeight": "bold", "textColor": "#8569CB" }
|
||||
] },
|
||||
{ "type": "frame", "id": "lane-right-body", "layout": "vertical",
|
||||
"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",
|
||||
"children": [{ "type": "rect", "id": "d-s2", "width": 200, "height": "fit-content", "fillColor": "#EAE6F3", "borderColor": "#8569CB", "borderWidth": 2, "borderRadius": 8 }] }
|
||||
] }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{ "type": "connector", "connector": { "from": "c-s1", "to": "d-s2",
|
||||
"lineShape": "polyline", "lineColor": "#BBBFC4", "lineWidth": 2, "endArrow": "arrow" } }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 泳道配色（默认色板）
|
||||
|
||||
- **泳道背景**：所有泳道容器统一使用极浅灰色（如 `fillColor: "#F8F9FA"` 或 `"#FCFCFC"`），以增强物理容器的层级感，并突出内部的彩色卡片。
|
||||
- **泳道边框**：所有泳道外层容器统一使用浅灰色细虚线（`borderColor: "#DEE0E3"`, `borderWidth: 1`, `borderDash: "dashed"`）。
|
||||
- **泳道标题**：按 `elements/style.md` 经典色板为每条泳道分配不同的主题色，泳道 title 的 `textColor` 使用该主题色。
|
||||
- **内容节点（rect）**：采用“浅色底 + 主题色边框”策略。`fillColor` 使用与该泳道主题色对应的极浅色（如浅蓝、浅紫等），`borderColor` 使用对应的主题色，文字 `textColor` 统一使用深色 `#1F2329`。
|
||||
- **连线（connector）**：连线颜色固定为灰色 `#BBBFC4`，不随泳道颜色变化。当连线带有文字（`label`）时，为防止文字压在边框上难以阅读，必须为连线文字设置纯白背景（`labelFillColor: "#FFFFFF"`）遮挡底纹。
|
||||
|
||||
提醒：避免创建“虚拟 frame”（见 `elements/schema.md` 的说明）。lane 外层必须具有可见属性以避免在编译时被跳过。
|
||||
|
||||
|
||||
## 连线规则（强制参考 connectors.md）
|
||||
|
||||
泳道图中所有连线的选择与写法必须严格遵循 `elements/connectors.md`，尤其是：
|
||||
- `connector` 必须放在 `WBDocument.nodes` 顶层，不能嵌套在 `children`
|
||||
- 默认优先使用自动绕线：`lineShape: "polyline"` / `"rightAngle"`，且不写 `waypoints`
|
||||
- 未指定 `lineShape` 时默认使用 `"rightAngle"`
|
||||
- 只有在必要时才强制锚点方向；锚点选择必须与节点相对位置一致
|
||||
- 有连线时卡片间距必须满足 `gap >= 40`；如果连线包含文字（`label`），主轴间距必须 `gap >= 64`
|
||||
- 带文字的连线必须设置 `labelFillColor: "#FFFFFF"` 遮挡底纹
|
||||
|
||||
泳道图语境下的落地约束：
|
||||
- **默认不写锚点**，交给引擎自动推断；只有需要强制“左→右推进 / 上→下推进”时才写
|
||||
- 需要表达“异步/事件流/推送”（如 SSE/Chunk）时：使用 `lineStyle: "dashed"` 并配合 `label` 说明语义；其他参数仍按 connectors.md
|
||||
- 避免连接“仅用于布局且可能被优化掉的虚拟 frame”，尽量连接具体步骤卡片的节点 id（参考 `elements/schema.md` 的虚拟 frame 陷阱）
|
||||
|
||||
## 骨架示例
|
||||
|
||||
> 示例展示布局的结构与对齐方法；实际节点的样式满足当前布局规则的前提下参考 `elements/style.md`
|
||||
|
||||
- 水平泳道示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "lanes-root",
|
||||
"x": 40,
|
||||
"y": 40,
|
||||
"layout": "vertical",
|
||||
"gap": 16,
|
||||
"alignItems": "stretch",
|
||||
"padding": 0,
|
||||
"width": "fit-content",
|
||||
"height": "fit-content",
|
||||
"children": [
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "lane-a",
|
||||
"layout": "horizontal",
|
||||
"gap": 40,
|
||||
"padding": 16,
|
||||
"width": "fit-content",
|
||||
"height": "fill-container",
|
||||
"fillColor": "#F8F9FA",
|
||||
"borderDash": "dashed",
|
||||
"borderWidth": 1,
|
||||
"borderColor": "#DEE0E3",
|
||||
"children": [
|
||||
{
|
||||
"type": "text",
|
||||
"id": "lane-a-label",
|
||||
"text": "Lane A",
|
||||
"width": 120,
|
||||
"height": "fit-content",
|
||||
"textAlign": "left",
|
||||
"verticalAlign": "middle",
|
||||
"fontSize": 18,
|
||||
"fontWeight": "bold",
|
||||
"textColor": "#5178C6"
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "stage-1-cell-a",
|
||||
"layout": "vertical",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"width": 200,
|
||||
"height": "fit-content",
|
||||
"fillColor": "transparent",
|
||||
"alignItems": "stretch",
|
||||
"justifyContent": "center",
|
||||
"children": [
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "a-s1",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"fillColor": "#E1EAFA",
|
||||
"borderColor": "#5178C6",
|
||||
"borderWidth": 2,
|
||||
"borderRadius": 8,
|
||||
"text": "[阶段 1 节点]",
|
||||
"fontSize": 14,
|
||||
"textColor": "#1F2329",
|
||||
"textAlign": "center",
|
||||
"verticalAlign": "middle"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "stage-2-cell-a",
|
||||
"layout": "vertical",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"width": 200,
|
||||
"height": "fit-content",
|
||||
"fillColor": "transparent",
|
||||
"alignItems": "stretch",
|
||||
"justifyContent": "center",
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "lane-b",
|
||||
"layout": "horizontal",
|
||||
"gap": 40,
|
||||
"padding": 16,
|
||||
"width": "fit-content",
|
||||
"height": "fill-container",
|
||||
"fillColor": "#F8F9FA",
|
||||
"borderDash": "dashed",
|
||||
"borderWidth": 1,
|
||||
"borderColor": "#DEE0E3",
|
||||
"children": [
|
||||
{
|
||||
"type": "text",
|
||||
"id": "lane-b-label",
|
||||
"text": "Lane B",
|
||||
"width": 120,
|
||||
"height": "fit-content",
|
||||
"textAlign": "left",
|
||||
"verticalAlign": "middle",
|
||||
"fontSize": 18,
|
||||
"fontWeight": "bold",
|
||||
"textColor": "#8569CB"
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "stage-1-cell-b",
|
||||
"layout": "vertical",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"width": 200,
|
||||
"height": "fit-content",
|
||||
"fillColor": "transparent",
|
||||
"alignItems": "stretch",
|
||||
"justifyContent": "center",
|
||||
"children": []
|
||||
},
|
||||
{
|
||||
"type": "frame",
|
||||
"id": "stage-2-cell-b",
|
||||
"layout": "vertical",
|
||||
"gap": 8,
|
||||
"padding": 0,
|
||||
"width": 200,
|
||||
"height": "fit-content",
|
||||
"fillColor": "transparent",
|
||||
"alignItems": "stretch",
|
||||
"justifyContent": "center",
|
||||
"children": [
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "b-s2",
|
||||
"width": "fill-container",
|
||||
"height": "fit-content",
|
||||
"fillColor": "#EAE6F3",
|
||||
"borderColor": "#8569CB",
|
||||
"borderWidth": 2,
|
||||
"borderRadius": 8,
|
||||
"text": "[阶段 2 节点]",
|
||||
"fontSize": 14,
|
||||
"textColor": "#1F2329",
|
||||
"textAlign": "center",
|
||||
"verticalAlign": "middle"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "connector",
|
||||
"connector": {
|
||||
"from": "a-s1",
|
||||
"to": "b-s2",
|
||||
"lineShape": "polyline",
|
||||
"lineColor": "#BBBFC4",
|
||||
"lineWidth": 2,
|
||||
"endArrow": "arrow",
|
||||
"label": "[跨泳道交互]",
|
||||
"labelFillColor": "#FFFFFF"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- 垂直泳道示例：见上文“垂直泳道”
|
||||
|
||||
- 全泳道统一 `slotWidth/slotHeight/gap`，并为每个阶段生成占位 **stage cell**（空阶段 cell 透明但保留）
|
||||
- Flex 容器内不写子节点 `x/y`；对齐通过 cell 索引与统一尺寸实现
|
||||
- 只有真实阶段才在对应 cell 内生成卡片；空阶段不生成卡片但保留 cell 保证网格完整
|
||||
- 连线必须放在 `nodes` 顶层，并连接具体步骤卡片 id，不要连接 `lane-*-body` 这类布局容器
|
||||
- **水平泳道**：根容器用 `layout: "vertical"` 固定 `lanesGap`；lane body 用 `layout: "horizontal"`；cell 固定宽度 `slotWidth`；主轴 `gap` 统一
|
||||
- **垂直泳道**：根容器用 `layout: "horizontal"` 固定 `lanesGap`；lane body 用 `layout: "vertical"`；cell 固定高度 `slotHeight`；主轴 `gap` 统一
|
||||
- **泳道 title**：title 比步骤卡片更醒目，但仍只用字号、字重、文字色强调；不要给泳道 title 额外加背景条
|
||||
|
||||
## 陷阱
|
||||
|
||||
- **各泳道复用的 stage slots 不一致**：会导致同阶段错位；`slotWidth / slotHeight / gap` 必须全泳道统一
|
||||
- **把 connector 放进 children**：会导致 schema 报错或无法连线（见 connectors.md）
|
||||
- **把辅助容器画成可见元素**：lane body 或其他支撑 frame 必须保持 `fillColor: "transparent"`，除泳道分组容器外不要额外加边框
|
||||
- **手写 waypoints 过早**：先让引擎自动绕线；只有在必要时才通过 waypoints 接管
|
||||
- **连线过多**：按 connectors.md 的连线数量策略降采样，否则跨泳道线会互相遮挡导致不可读
|
||||
216
.claude/skills/lark-whiteboard/scenes/treemap.md
Normal file
216
.claude/skills/lark-whiteboard/scenes/treemap.md
Normal file
@ -0,0 +1,216 @@
|
||||
# 矩形树图 (Treemap)
|
||||
|
||||
## Content 约束
|
||||
|
||||
- 分类 3-5 个，每个分类下子项 2-4 个
|
||||
- 总面积比例需预先计算：每个矩形面积 = 父矩形面积 * (本项数值 / 同级总数值)
|
||||
- 每个叶子节点标签必须包含数值（如 "{{LABEL}} ({{VALUE}})"）
|
||||
|
||||
## Layout 选型
|
||||
|
||||
- **脚本生成坐标**（推荐）：Treemap 需要精确的面积比例计算，用 .cjs 脚本递归切分矩形，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.13` 渲染
|
||||
- 不适合手动心算坐标
|
||||
|
||||
## Layout 规则
|
||||
|
||||
- 使用交替切分法（Slice-and-Dice）：奇数层水平切分 width，偶数层垂直切分 height
|
||||
- 父矩形内必须为标题预留 30-40px 顶部空间，子矩形从 y + 35 开始放置
|
||||
- 子节点必须完全落在父矩形范围内
|
||||
- 水平切分时：子 width = 父 width * (子数值 / 父总数值)，子 x 依次累加
|
||||
- 垂直切分时：子 height = (父 height - 35) * (子数值 / 父总数值)，子 y 依次累加（注意扣除父标签预留的 35px）
|
||||
|
||||
### 面积比例计算规则
|
||||
|
||||
1. **面积与数值严格成正比**：任何层级的节点，其矩形面积 `width * height` 必须与数值成比例
|
||||
2. **奇数层水平切分**（如第一层分类）：
|
||||
- 父矩形的 `height` 和 `y` 坐标传给所有子节点（扣除标签预留空间后）
|
||||
- 按子节点数值占父节点的比例切分父矩形的 `width`：`子width = 父width * (子数值 / 父总数值)`
|
||||
- 子节点的 `x` 坐标依次向右累加
|
||||
3. **偶数层垂直切分**（如第二层子项）：
|
||||
- 父矩形的 `width` 和 `x` 坐标传给所有子节点
|
||||
- 按子节点数值占父节点的比例切分父矩形的 `height`：`子height = 父height * (子数值 / 父总数值)`
|
||||
- 子节点的 `y` 坐标依次向下累加
|
||||
4. **层层递归**：不断交替水平和垂直切分方向，直到所有叶子节点都被分配了精确的坐标和宽高
|
||||
|
||||
### 父标签预留空间
|
||||
|
||||
每个非叶子节点的矩形，顶部必须预留 30-40px 放置分类标签。子矩形从父矩形的 `y + 35` 开始放置，可用高度为 `父height - 35`。
|
||||
|
||||
示例：父矩形 `{ x: 40, y: 40, height: 700 }`，则：
|
||||
- 父标签放在 `y: 46`（留 6px 上边距）
|
||||
- 子矩形从 `y: 75` 开始放置（40 + 35）
|
||||
- 子矩形可用高度为 `700 - 35 = 665`
|
||||
|
||||
## 骨架示例
|
||||
|
||||
2 层 treemap：3 个分类（硬件 40、软件 35、服务 25），各含 2 个子项。
|
||||
|
||||
根矩形 1100x700，第一层水平切分 width，第二层垂直切分 height。
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"nodes": [
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "root",
|
||||
"x": 40, "y": 40,
|
||||
"width": 1100, "height": 700,
|
||||
"borderWidth": 2, "borderRadius": 6
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 48, "y": 46,
|
||||
"width": 1084, "height": 24,
|
||||
"text": "{{ROOT_TITLE}}",
|
||||
"fontSize": 14
|
||||
},
|
||||
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "cat-A",
|
||||
"x": 40, "y": 75,
|
||||
"width": 440, "height": 665,
|
||||
"borderWidth": 2, "borderRadius": 6
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 48, "y": 81,
|
||||
"width": 424, "height": 24,
|
||||
"text": "{{CAT_A}}",
|
||||
"fontSize": 14
|
||||
},
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "cat-A-item-1",
|
||||
"x": 40, "y": 110,
|
||||
"width": 440, "height": 380,
|
||||
"borderRadius": 4
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 48, "y": 116,
|
||||
"width": 424, "height": 24,
|
||||
"text": "{{ITEM_A1}} (24)",
|
||||
"fontSize": 14
|
||||
},
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "cat-A-item-2",
|
||||
"x": 40, "y": 490,
|
||||
"width": 440, "height": 250,
|
||||
"borderRadius": 4
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 48, "y": 496,
|
||||
"width": 424, "height": 24,
|
||||
"text": "{{ITEM_A2}} (16)",
|
||||
"fontSize": 14
|
||||
},
|
||||
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "cat-B",
|
||||
"x": 480, "y": 75,
|
||||
"width": 385, "height": 665,
|
||||
"borderWidth": 2, "borderRadius": 6
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 488, "y": 81,
|
||||
"width": 369, "height": 24,
|
||||
"text": "{{CAT_B}}",
|
||||
"fontSize": 14
|
||||
},
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "cat-B-item-1",
|
||||
"x": 480, "y": 110,
|
||||
"width": 385, "height": 380,
|
||||
"borderRadius": 4
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 488, "y": 116,
|
||||
"width": 369, "height": 24,
|
||||
"text": "{{ITEM_B1}} (20)",
|
||||
"fontSize": 14
|
||||
},
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "cat-B-item-2",
|
||||
"x": 480, "y": 490,
|
||||
"width": 385, "height": 285,
|
||||
"borderRadius": 4
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 488, "y": 496,
|
||||
"width": 369, "height": 24,
|
||||
"text": "{{ITEM_B2}} (15)",
|
||||
"fontSize": 14
|
||||
},
|
||||
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "cat-C",
|
||||
"x": 865, "y": 75,
|
||||
"width": 275, "height": 665,
|
||||
"borderWidth": 2, "borderRadius": 6
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 873, "y": 81,
|
||||
"width": 259, "height": 24,
|
||||
"text": "{{CAT_C}}",
|
||||
"fontSize": 14
|
||||
},
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "cat-C-item-1",
|
||||
"x": 865, "y": 110,
|
||||
"width": 275, "height": 399,
|
||||
"borderRadius": 4
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 873, "y": 116,
|
||||
"width": 259, "height": 24,
|
||||
"text": "{{ITEM_C1}} (15)",
|
||||
"fontSize": 14
|
||||
},
|
||||
{
|
||||
"type": "rect",
|
||||
"id": "cat-C-item-2",
|
||||
"x": 865, "y": 509,
|
||||
"width": 275, "height": 231,
|
||||
"borderRadius": 4
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"x": 873, "y": 515,
|
||||
"width": 259, "height": 24,
|
||||
"text": "{{ITEM_C2}} (10)",
|
||||
"fontSize": 14
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
面积比例验证（第一层水平切分 width）：
|
||||
- 硬件 40/100 * 1100 = 440，软件 35/100 * 1100 = 385，服务 25/100 * 1100 = 275
|
||||
- 子矩形从 y=75 开始，可用高度 665
|
||||
|
||||
## 陷阱
|
||||
|
||||
- **父标签被子矩形遮挡**（最严重）：子矩形必须从 y + 35（相对父矩形顶部）开始放置，为父分类标签留出空间
|
||||
- **分类标签不可见**：分类标签 text 节点必须在其子矩形 rect 节点之前添加（z-index 靠后的节点在上层）
|
||||
- **面积比例不正确**：必须用脚本预先计算比例，不要心算
|
||||
- **缺少配色区分**：不同顶层分类必须用不同背景色（从色板选取），所有子节点继承对应色系
|
||||
|
||||
此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `data` 树，其余坐标与矩形面积自动递归计算。
|
||||
|
||||
```javascript
|
||||
const { writeFileSync } = require('fs');
|
||||
```
|
||||
Reference in New Issue
Block a user