mirror of
https://github.com/larksuite/cli.git
synced 2026-07-03 14:02:43 +08:00
docs(whiteboard): optimize whiteboard skill (#1371)
* docs(whiteboard): optimize whiteboard skill Change-Id: Iabcbe9f4e309ae9f467ceec265320cea6cdfa81b * fix: PR issue Change-Id: I96d99037b3ba74a3ea9964991b67cdf15fb985be
This commit is contained in:
syh-cpdsss
@@ -2,9 +2,8 @@
|
||||
name: lark-whiteboard
|
||||
version: 1.0.0
|
||||
description: >
|
||||
飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用 DSL（转成 OpenAPI 格式）、PlantUML/Mermaid 格式更新画板内容。
|
||||
当用户需要查看画板内容、导出画板图片、编辑画板，或是需要可视化表达架构、流程、组织关系、时间线、因果、对比等结构化信息时使用此 skill，无论是否提及"画板"。
|
||||
⚠️ 原 `lark-whiteboard-cli` skill 已合并至本 skill，若 skill 列表中同时存在 `lark-whiteboard-cli`，请忽略它，统一使用本 skill（`lark-whiteboard`），并提示用户运行 `npx skills remove lark-whiteboard-cli -g` 删除旧 skill。
|
||||
飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用多种格式更新画板内容。
|
||||
当用户需要查看画板内容、导出画板图片、编辑画板时使用此 skill。不负责：飞书云文档内容编辑（lark-doc）、文档内嵌电子表格/Base（lark-sheets / lark-base）。
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
@@ -21,15 +20,17 @@ metadata:
|
||||
|
||||
## 快速决策
|
||||
|
||||
| 用户需求 | 行动 |
|
||||
|---|---|
|
||||
| 查看画板内容 / 导出图片 | [`+query --output_as image`](references/lark-whiteboard-query.md) |
|
||||
| 获取画板的 Mermaid/PlantUML 代码 | [`+query --output_as code`](references/lark-whiteboard-query.md) |
|
||||
| 检查画板是否由代码绘制 | [`+query --output_as code`](references/lark-whiteboard-query.md) |
|
||||
| 修改节点文字/颜色（简单改动）| `+query --output_as raw` → 手动改 JSON → `+update --input_format raw` |
|
||||
**身份**：画板操作默认使用 `--as user`。仅当需要以应用身份上传时使用 `--as bot`。
|
||||
|
||||
| 用户需求 | 行动 |
|
||||
|-----------------------------------------|-----------------------------------------------------------------------------------------------|
|
||||
| 查看画板内容 / 导出图片 | [`+query --output_as image`](references/lark-whiteboard-query.md) |
|
||||
| 获取画板的 Mermaid/PlantUML 代码 | [`+query --output_as code`](references/lark-whiteboard-query.md) |
|
||||
| 检查画板是否由代码绘制 | [`+query --output_as code`](references/lark-whiteboard-query.md) |
|
||||
| 修改节点文字/颜色（简单改动） | `+query --output_as raw` → 手动改 JSON → `+update --input_format raw` |
|
||||
| 用户**已提供** Mermaid/PlantUML 代码，或明确指定用该格式 | 自己生成/使用代码 → [`+update --input_format mermaid/plantuml`](references/lark-whiteboard-update.md) |
|
||||
| 绘制复杂图表（架构/流程/组织等）| → **[§ 创作 Workflow](#创作-workflow)** |
|
||||
| 修改/重绘已有复杂画板 | → **[§ 修改 Workflow](#修改-workflow)** |
|
||||
| 新建/创作复杂图表（架构/流程/组织等） | → **[§ 创作 Workflow](references/lark-whiteboard-workflow.md#创作-workflow)** |
|
||||
| 修改/重绘已有画板 | → **[§ 修改 Workflow](references/lark-whiteboard-workflow.md#修改-workflow)** |
|
||||
|
||||
## Shortcuts
|
||||
|
||||
@@ -40,93 +41,7 @@ metadata:
|
||||
|
||||
---
|
||||
|
||||
## 创作 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 --api-version v2 --doc <URL> --as user`，从返回的 `<whiteboard token="xxx"/>` 提取 |
|
||||
| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --api-version v2 --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：判断修改策略**
|
||||
|
||||
```
|
||||
+query --output_as code
|
||||
├─ 返回 Mermaid/PlantUML 代码
|
||||
│ → 在原代码上修改 → +update --input_format mermaid/plantuml
|
||||
├─ 无代码（DSL 或其他方式绘制的画板）
|
||||
│ ├─ 只改文字/颜色 → +query --output_as raw → 手动改 JSON → +update --input_format raw
|
||||
│ └─ 重绘/结构调整 → +query --output_as image → 看图后进入 [§ 渲染 & 写入画板]
|
||||
└─ 用户有明确要求 → 以用户要求优先
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 渲染 & 写入画板
|
||||
|
||||
### 渲染路由
|
||||
|
||||
**先自报身份**：按训练来源，你属于哪一家？`Claude` / `Gemini` / `GPT` / `GLM` / `Doubao 或 Seed` / `Other`。身份决定 SVG / DSL 分流（不同家族对这两种表达语言的能力不均衡），不要跳过这一步。
|
||||
|
||||
**然后按图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
|
||||
|
||||
| 图表类型 | 身份 | 路径 |
|
||||
|------------------------|-------------------------------------|------------------------------------------|
|
||||
| 思维导图、流程图、时序图、类图、饼图、甘特图 | 任何身份 | [`routes/mermaid.md`](routes/mermaid.md) |
|
||||
| 其他图表 | `Claude` / `Gemini` / `GPT` / `GLM` | [`routes/svg.md`](routes/svg.md) |
|
||||
| 其他图表 | `Doubao` / `Seed` / `Other` | [`routes/dsl.md`](routes/dsl.md) |
|
||||
|
||||
> **⚠️ SVG 路径失败回退**：走 `routes/svg.md` 时，碰到以下情况之一 → **丢弃当前 SVG，改读 `routes/dsl.md` 从零重画，不要逐行修补**：
|
||||
> - 渲染命令直接报错（语法级崩溃，不是 `--check` 的 warn/error）
|
||||
> - 两轮改写仍无法消除 `--check` 的 `text-overflow` error
|
||||
> - 目测 PNG 视觉严重错乱（文字大面积溢出、元素重叠压住关键信息、布局整体崩溃）
|
||||
>
|
||||
> SVG 源码修补常常引入新 bug，换 DSL 从零重画往往更稳。这是 SVG 路径自由发挥的硬兜底，不要侵入 `routes/svg.md` 的创作流程。
|
||||
|
||||
### 产物规范
|
||||
|
||||
产物目录：`./diagrams/YYYY-MM-DDTHHMMSS/`（本地时间，不含冒号和时区后缀）。如用户指定路径，以用户为准。
|
||||
|
||||
目录内固定文件名：
|
||||
|
||||
```
|
||||
diagram.svg ← SVG 源码（SVG 路径）
|
||||
diagram.mmd ← Mermaid 源码（Mermaid 路径）
|
||||
diagram.json ← DSL 源文件（DSL 路径） / OpenAPI JSON（SVG 路径从 diagram.svg 导出）
|
||||
diagram.gen.cjs ← 坐标计算脚本（仅 DSL 脚本构建方式）
|
||||
diagram.png ← 渲染结果
|
||||
```
|
||||
|
||||
### 写入画板
|
||||
|
||||
> 关于 --overwrite
|
||||
> 画板更新命令中，若不携带 --overwrite flag，则是增量更新画板内容，若画板内已有内容的话，新增内容可能会和已有内容重叠，导致问题。
|
||||
> 因此，若需要整体更新画板内容，需携带 --overwrite flag 覆盖式更新。
|
||||
|
||||
```bash
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.11 -i <产物文件> --to openapi --format json \
|
||||
| lark-cli whiteboard +update \
|
||||
--whiteboard-token <Token> \
|
||||
--source - --input_format raw \
|
||||
--idempotent-token <10+字符唯一串> \
|
||||
--as user \
|
||||
--overwrite
|
||||
```
|
||||
|
||||
> `--idempotent-token` 最少 10 字符，建议用时间戳+标识拼接（如 `1744800000-board-1`），避免重试导致重复写入。
|
||||
> 如需应用身份上传，将 `--as user` 替换为 `--as bot`。
|
||||
## 不在本 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)
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
## 布局决策
|
||||
|
||||
> 不要靠关键词猜布局。先分析信息结构，再决定布局策略。
|
||||
> 本文件负责说明通用布局原则与骨架模板；字段语义看 `references/schema.md`，完整场景范式看各 `scenes/*.md`。
|
||||
> 本文件负责说明通用布局原则与骨架模板；字段语义看 `elements/schema.md`，完整场景范式看各 `scenes/*.md`。
|
||||
|
||||
总原则：**先定主布局，再定子布局。**
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# DSL Schema
|
||||
|
||||
> 本文件只说明 **DSL 里能写什么**：节点类型、字段、枚举值、硬约束。布局策略、组合方法、Dagre/Flex 心智模型统一放在 `references/layout.md`。
|
||||
> 本文件只说明 **DSL 里能写什么**：节点类型、字段、枚举值、硬约束。布局策略、组合方法、Dagre/Flex 心智模型统一放在 `elements/layout.md`。
|
||||
> `?` 表示该字段在 schema 层是 optional；若需要稳定产出，再参考对应 scene 或 layout 文件中的最佳实践。
|
||||
|
||||
**📝 布局引擎核心法则**：
|
||||
@@ -138,7 +138,7 @@ interface WBDocument {
|
||||
> - 图片必须上传到**目标画板**，跨画板的 token 不可用
|
||||
> - 同一画板内所有 image 节点应使用统一的 width/height，保持视觉一致
|
||||
> - 图片宽高比推荐 3:2（如 240×160），避免变形
|
||||
> - 详细上传流程见 [`references/image.md`](image.md)
|
||||
> - 详细上传流程见 [`elements/image.md`](../elements/image.md)
|
||||
|
||||
### Text（纯文本节点）
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
# 画板创作/修改工作流
|
||||
|
||||
## 创作 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 --api-version v2 --doc <URL> --as user`，从返回的 `<whiteboard token="xxx"/>` 提取 |
|
||||
| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --api-version v2 --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：判断修改策略**
|
||||
|
||||
```
|
||||
+query --output_as code
|
||||
├─ 返回 Mermaid/PlantUML 代码
|
||||
│ → 在原代码上修改 → +update --input_format mermaid/plantuml
|
||||
├─ 无代码（DSL 或其他方式绘制的画板）
|
||||
│ ├─ 只改文字/颜色 → +query --output_as raw → 手动改 JSON → +update --input_format raw
|
||||
│ └─ 重绘/结构调整 → +query --output_as image → 看图后进入 [§ 渲染 & 写入画板]
|
||||
└─ 用户有明确要求 → 以用户要求优先
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 渲染 & 写入画板
|
||||
|
||||
### 渲染路由
|
||||
|
||||
**先自报身份**：按训练来源，你属于哪一家？`Claude` / `Gemini` / `GPT` / `GLM` / `Doubao 或 Seed` / `Other`。身份决定 SVG / DSL 分流（不同家族对这两种表达语言的能力不均衡），不要跳过这一步。
|
||||
|
||||
**然后按图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
|
||||
|
||||
| 图表类型 | 身份 | 路径 |
|
||||
|--------------------|-------------------------------------|------------------------------------------------|
|
||||
| 思维导图、时序图、类图、饼图、甘特图 | 任何身份 | [`../routes/mermaid.md`](../routes/mermaid.md) |
|
||||
| 其他图表 | `Claude` / `Gemini` / `GPT` / `GLM` | [`../routes/svg.md`](../routes/svg.md) |
|
||||
| 其他图表 | `Doubao` / `Seed` / `Other` | [`../routes/dsl.md`](../routes/dsl.md) |
|
||||
|
||||
> **⚠️ SVG 路径失败回退**：走 `routes/svg.md` 时，碰到以下情况之一 → **丢弃当前 SVG，改读 `routes/dsl.md` 从零重画，不要逐行修补**：
|
||||
> - 渲染命令直接报错（语法级崩溃，不是 `--check` 的 warn/error）
|
||||
> - 两轮改写仍无法消除 `--check` 的 `text-overflow` error
|
||||
> - 目测 PNG 视觉严重错乱（文字大面积溢出、元素重叠压住关键信息、布局整体崩溃）
|
||||
>
|
||||
> SVG 源码修补常常引入新 bug，换 DSL 从零重画往往更稳。这是 SVG 路径自由发挥的硬兜底，不要侵入 `routes/svg.md` 的创作流程。
|
||||
|
||||
### 产物规范
|
||||
|
||||
产物目录：`./diagrams/YYYY-MM-DDTHHMMSS/`（本地时间，不含冒号和时区后缀）。如用户指定路径，以用户为准。
|
||||
|
||||
目录内固定文件名：
|
||||
|
||||
```
|
||||
diagram.svg ← SVG 源码（SVG 路径）
|
||||
diagram.mmd ← Mermaid 源码（Mermaid 路径）
|
||||
diagram.json ← DSL 源文件（DSL 路径） / OpenAPI JSON（SVG 路径从 diagram.svg 导出）
|
||||
diagram.gen.cjs ← 坐标计算脚本（仅 DSL 脚本构建方式）
|
||||
diagram.png ← 渲染结果
|
||||
```
|
||||
|
||||
### 写入画板
|
||||
|
||||
> 关于 --overwrite
|
||||
> 画板更新命令中，若不携带 --overwrite flag，则是增量更新画板内容，若画板内已有内容的话，新增内容可能会和已有内容重叠，导致问题。
|
||||
> 因此，若需要整体更新画板内容，需携带 --overwrite flag 覆盖式更新。
|
||||
|
||||
```bash
|
||||
npx -y @larksuite/whiteboard-cli@^0.2.11 -i <产物文件> --to openapi --format json \
|
||||
| lark-cli whiteboard +update \
|
||||
--whiteboard-token <Token> \
|
||||
--source - --input_format raw \
|
||||
--idempotent-token <10+字符唯一串> \
|
||||
--as user \
|
||||
--overwrite
|
||||
```
|
||||
|
||||
> `--idempotent-token` 最少 10 字符，建议用时间戳+标识拼接（如 `1744800000-board-1`），避免重试导致重复写入。
|
||||
> 如需应用身份上传，将 `--as user` 替换为 `--as bot`。
|
||||
@@ -8,7 +8,7 @@
|
||||
Step 1: 路由 & 读取知识
|
||||
- 读对应 scene 指南 — 了解结构特征和布局策略
|
||||
- 确定布局策略（见下方快速判断）和构建方式
|
||||
- 读 references/ 核心模块 — 语法、布局、配色、排版、连线
|
||||
- 读 elements/ 核心模块 — 语法、布局、配色、排版、连线
|
||||
|
||||
Step 2: 生成完整 DSL（含颜色）
|
||||
- 按 content.md 规划信息量和分组
|
||||
@@ -37,7 +37,7 @@ Step 3: 渲染 & 审查 → 交付
|
||||
- 交付：向用户报告 board_token 写入成功
|
||||
```
|
||||
|
||||
**布局策略快速判断**（详见 `references/layout.md`）：
|
||||
**布局策略快速判断**（详见 `elements/layout.md`）：
|
||||
|
||||
先定**主布局**，再定子布局：**结构化信息**优先用 Flex，**关系链路**优先用 Dagre，**灵活定位**用绝对布局。
|
||||
|
||||
@@ -47,14 +47,14 @@ Step 3: 渲染 & 审查 → 交付
|
||||
|
||||
### 核心参考（必读）
|
||||
|
||||
| 模块 | 文件 | 说明 |
|
||||
| -------- | -------------------------- | ------------------------------- |
|
||||
| DSL 语法 | `references/schema.md` | 节点类型、属性、尺寸值 |
|
||||
| 内容规划 | `references/content.md` | 信息提取、密度决策、连线预判 |
|
||||
| 布局系统 | `references/layout.md` | 网格方法论、Flex 映射、间距规则 |
|
||||
| 排版规则 | `references/typography.md` | 字号层级、对齐、行距 |
|
||||
| 连线系统 | `references/connectors.md` | 拓扑规划、锚点选择 |
|
||||
| 配色系统 | `references/style.md` | 多色板、视觉层级 |
|
||||
| 模块 | 文件 | 说明 |
|
||||
| -------- |----------------------------| ------------------------------- |
|
||||
| DSL 语法 | `elements/schema.md` | 节点类型、属性、尺寸值 |
|
||||
| 内容规划 | `elements/content.md` | 信息提取、密度决策、连线预判 |
|
||||
| 布局系统 | `elements/layout.md` | 网格方法论、Flex 映射、间距规则 |
|
||||
| 排版规则 | `elements/typography.md` | 字号层级、对齐、行距 |
|
||||
| 连线系统 | `elements/connectors.md` | 拓扑规划、锚点选择 |
|
||||
| 配色系统 | `elements/style.md` | 多色板、视觉层级 |
|
||||
|
||||
### 场景指南（按类型选读一个）
|
||||
|
||||
@@ -73,7 +73,7 @@ Step 3: 渲染 & 审查 → 交付
|
||||
| 循环/飞轮图 | `scenes/flywheel.md` | 增长飞轮、闭环链路 |
|
||||
| 里程碑 | `scenes/milestone.md` | 时间线、版本演进 |
|
||||
| 流程图 | `scenes/flowchart.md` | 业务流、状态机、带条件判断的链路 |
|
||||
| 图片展示 | `scenes/photo-showcase.md` | 用户显式要求图片/配图/插图时（需先完成 `references/image.md` 的图片准备） |
|
||||
| 图片展示 | `scenes/photo-showcase.md` | 用户显式要求图片/配图/插图时（需先完成 `elements/image.md` 的图片准备） |
|
||||
|
||||
## 渲染前自查
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
适用于：各种业务流转图、决策树、审批流、时序控制逻辑、带条件判断的链路、系统架构拓扑等。
|
||||
|
||||
通用字段语义详见 `references/schema.md`，通用布局原则详见 `references/layout.md`；本文件只描述流程图场景下的选型边界与范式。
|
||||
通用字段语义详见 `elements/schema.md`，通用布局原则详见 `elements/layout.md`；本文件只描述流程图场景下的选型边界与范式。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **流程图必须走 DSL 路径，不再使用 Mermaid！**
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
| 中间格式 | JSON（WBDocument） | Mermaid 文本（.mmd 文件） |
|
||||
| 布局控制 | 精确控制（x/y 坐标、Flex） | 由 parser-kit 自动布局 |
|
||||
| 视觉定制 | 完全可控（颜色、字号、圆角等） | 有限（Mermaid 语法） |
|
||||
| 参考模块 | references/ + 对应 scene | 仅本文件 |
|
||||
| 参考模块 | elements/ + 对应 scene | 仅本文件 |
|
||||
|
||||
## 适用条件
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
> **注意**：仅当用户明确说了「图片/配图/插图/照片」等词时才进入本场景。单纯说"旅行路线图"、"产品展示"等不触发。
|
||||
|
||||
> **前置条件**：进入本场景前，必须已完成 [`references/image.md`](../references/image.md) 的 Step 0（图片准备），拿到所有 media token。
|
||||
> **前置条件**：进入本场景前，必须已完成 [`elements/image.md`](../elements/image.md) 的 Step 0（图片准备），拿到所有 media token。
|
||||
|
||||
## Content 约束
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@
|
||||
1. **网格对齐是第一优先级**：跨泳道同一阶段必须严格对齐（水平对齐 x；垂直对齐 y）。对齐通过“共享阶段标尺（stage ruler / stage slots）”实现，不靠肉眼估算，也不靠逐节点随意手写坐标
|
||||
2. **只生成真实节点**：为保证跨泳道阶段严格对齐，所有阶段统一保留透明的 **stage cell**；仅在真实阶段的 cell 内生成卡片节点，并按阶段索引映射到对应槽位
|
||||
3. **泳道底色**：为了增强层级感同时保持界面整洁，**强烈建议所有泳道容器统一使用极浅灰色背景**（如 `fillColor: "#F8F9FA"` 或 `"#FCFCFC"`）。边框使用浅灰色细虚线（`borderDash: "dashed"`, `borderWidth: 1`, `borderColor: "#DEE0E3"`）以明确边界。
|
||||
4. **步骤卡片**：使用 `rect`。为建立清晰的视觉层级，卡片**必须填充浅色背景**（参考 `references/style.md` 中的浅色板，如极浅的主题色），边框使用对应的主题主色（`borderWidth: 1-2`），文字使用深色（如 `#1F2329`）以确保可读性。统一圆角；宽高以可读为先，避免过窄导致换行过多
|
||||
4. **步骤卡片**：使用 `rect`。为建立清晰的视觉层级，卡片**必须填充浅色背景**（参考 `elements/style.md` 中的浅色板，如极浅的主题色），边框使用对应的主题主色（`borderWidth: 1-2`），文字使用深色（如 `#1F2329`）以确保可读性。统一圆角；宽高以可读为先，避免过窄导致换行过多
|
||||
5. **间距**：只要存在 connector 连线，卡片之间的主轴间距必须满足 `gap >= 40`
|
||||
|
||||
### 子节点对齐
|
||||
@@ -151,16 +151,16 @@
|
||||
|
||||
- **泳道背景**：所有泳道容器统一使用极浅灰色（如 `fillColor: "#F8F9FA"` 或 `"#FCFCFC"`），以增强物理容器的层级感，并突出内部的彩色卡片。
|
||||
- **泳道边框**：所有泳道外层容器统一使用浅灰色细虚线（`borderColor: "#DEE0E3"`, `borderWidth: 1`, `borderDash: "dashed"`）。
|
||||
- **泳道标题**：按 `references/style.md` 经典色板为每条泳道分配不同的主题色，泳道 title 的 `textColor` 使用该主题色。
|
||||
- **泳道标题**：按 `elements/style.md` 经典色板为每条泳道分配不同的主题色，泳道 title 的 `textColor` 使用该主题色。
|
||||
- **内容节点（rect）**：采用“浅色底 + 主题色边框”策略。`fillColor` 使用与该泳道主题色对应的极浅色（如浅蓝、浅紫等），`borderColor` 使用对应的主题色，文字 `textColor` 统一使用深色 `#1F2329`。
|
||||
- **连线（connector）**：连线颜色固定为灰色 `#BBBFC4`，不随泳道颜色变化。当连线带有文字（`label`）时，为防止文字压在边框上难以阅读，必须为连线文字设置纯白背景（`labelFillColor: "#FFFFFF"`）遮挡底纹。
|
||||
|
||||
提醒：避免创建“虚拟 frame”（见 `references/schema.md` 的说明）。lane 外层必须具有可见属性以避免在编译时被跳过。
|
||||
提醒：避免创建“虚拟 frame”（见 `elements/schema.md` 的说明）。lane 外层必须具有可见属性以避免在编译时被跳过。
|
||||
|
||||
|
||||
## 连线规则（强制参考 connectors.md）
|
||||
|
||||
泳道图中所有连线的选择与写法必须严格遵循 `references/connectors.md`，尤其是：
|
||||
泳道图中所有连线的选择与写法必须严格遵循 `elements/connectors.md`，尤其是：
|
||||
- `connector` 必须放在 `WBDocument.nodes` 顶层，不能嵌套在 `children`
|
||||
- 默认优先使用自动绕线：`lineShape: "polyline"` / `"rightAngle"`，且不写 `waypoints`
|
||||
- 未指定 `lineShape` 时默认使用 `"rightAngle"`
|
||||
@@ -171,11 +171,11 @@
|
||||
泳道图语境下的落地约束：
|
||||
- **默认不写锚点**，交给引擎自动推断；只有需要强制“左→右推进 / 上→下推进”时才写
|
||||
- 需要表达“异步/事件流/推送”（如 SSE/Chunk）时：使用 `lineStyle: "dashed"` 并配合 `label` 说明语义；其他参数仍按 connectors.md
|
||||
- 避免连接“仅用于布局且可能被优化掉的虚拟 frame”，尽量连接具体步骤卡片的节点 id（参考 `references/schema.md` 的虚拟 frame 陷阱）
|
||||
- 避免连接“仅用于布局且可能被优化掉的虚拟 frame”，尽量连接具体步骤卡片的节点 id（参考 `elements/schema.md` 的虚拟 frame 陷阱）
|
||||
|
||||
## 骨架示例
|
||||
|
||||
> 示例展示布局的结构与对齐方法；实际节点的样式满足当前布局规则的前提下参考 `references/style.md`
|
||||
> 示例展示布局的结构与对齐方法；实际节点的样式满足当前布局规则的前提下参考 `elements/style.md`
|
||||
|
||||
- 水平泳道示例：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user