From 008bdda861219ad90ca837b58370903aaea48790 Mon Sep 17 00:00:00 2001 From: syh-cpdsss Date: Fri, 12 Jun 2026 17:46:55 +0800 Subject: [PATCH] docs(whiteboard): optimize whiteboard skill (#1371) * docs(whiteboard): optimize whiteboard skill Change-Id: Iabcbe9f4e309ae9f467ceec265320cea6cdfa81b * fix: PR issue Change-Id: I96d99037b3ba74a3ea9964991b67cdf15fb985be --- skills/lark-whiteboard/SKILL.md | 117 +++--------------- .../{references => elements}/connectors.md | 0 .../{references => elements}/content.md | 0 .../{references => elements}/image.md | 0 .../{references => elements}/layout.md | 2 +- .../{references => elements}/schema.md | 4 +- .../{references => elements}/style.md | 0 .../{references => elements}/typography.md | 0 .../references/lark-whiteboard-workflow.md | 92 ++++++++++++++ skills/lark-whiteboard/routes/dsl.md | 22 ++-- skills/lark-whiteboard/scenes/flowchart.md | 2 +- skills/lark-whiteboard/scenes/mermaid.md | 2 +- .../lark-whiteboard/scenes/photo-showcase.md | 2 +- skills/lark-whiteboard/scenes/swimlane.md | 12 +- 14 files changed, 131 insertions(+), 124 deletions(-) rename skills/lark-whiteboard/{references => elements}/connectors.md (100%) rename skills/lark-whiteboard/{references => elements}/content.md (100%) rename skills/lark-whiteboard/{references => elements}/image.md (100%) rename skills/lark-whiteboard/{references => elements}/layout.md (99%) rename skills/lark-whiteboard/{references => elements}/schema.md (99%) rename skills/lark-whiteboard/{references => elements}/style.md (100%) rename skills/lark-whiteboard/{references => elements}/typography.md (100%) create mode 100644 skills/lark-whiteboard/references/lark-whiteboard-workflow.md diff --git a/skills/lark-whiteboard/SKILL.md b/skills/lark-whiteboard/SKILL.md index 51673014..d20563d1 100644 --- a/skills/lark-whiteboard/SKILL.md +++ b/skills/lark-whiteboard/SKILL.md @@ -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 --as user`，从返回的 `` 提取 | -| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --api-version v2 --doc --command append --content '' --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 \ - --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) diff --git a/skills/lark-whiteboard/references/connectors.md b/skills/lark-whiteboard/elements/connectors.md similarity index 100% rename from skills/lark-whiteboard/references/connectors.md rename to skills/lark-whiteboard/elements/connectors.md diff --git a/skills/lark-whiteboard/references/content.md b/skills/lark-whiteboard/elements/content.md similarity index 100% rename from skills/lark-whiteboard/references/content.md rename to skills/lark-whiteboard/elements/content.md diff --git a/skills/lark-whiteboard/references/image.md b/skills/lark-whiteboard/elements/image.md similarity index 100% rename from skills/lark-whiteboard/references/image.md rename to skills/lark-whiteboard/elements/image.md diff --git a/skills/lark-whiteboard/references/layout.md b/skills/lark-whiteboard/elements/layout.md similarity index 99% rename from skills/lark-whiteboard/references/layout.md rename to skills/lark-whiteboard/elements/layout.md index 537bedb2..50fe940f 100644 --- a/skills/lark-whiteboard/references/layout.md +++ b/skills/lark-whiteboard/elements/layout.md @@ -3,7 +3,7 @@ ## 布局决策 > 不要靠关键词猜布局。先分析信息结构，再决定布局策略。 -> 本文件负责说明通用布局原则与骨架模板；字段语义看 `references/schema.md`，完整场景范式看各 `scenes/*.md`。 +> 本文件负责说明通用布局原则与骨架模板；字段语义看 `elements/schema.md`，完整场景范式看各 `scenes/*.md`。 总原则：**先定主布局，再定子布局。** diff --git a/skills/lark-whiteboard/references/schema.md b/skills/lark-whiteboard/elements/schema.md similarity index 99% rename from skills/lark-whiteboard/references/schema.md rename to skills/lark-whiteboard/elements/schema.md index 2d289e23..ea9cbf61 100644 --- a/skills/lark-whiteboard/references/schema.md +++ b/skills/lark-whiteboard/elements/schema.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（纯文本节点） diff --git a/skills/lark-whiteboard/references/style.md b/skills/lark-whiteboard/elements/style.md similarity index 100% rename from skills/lark-whiteboard/references/style.md rename to skills/lark-whiteboard/elements/style.md diff --git a/skills/lark-whiteboard/references/typography.md b/skills/lark-whiteboard/elements/typography.md similarity index 100% rename from skills/lark-whiteboard/references/typography.md rename to skills/lark-whiteboard/elements/typography.md diff --git a/skills/lark-whiteboard/references/lark-whiteboard-workflow.md b/skills/lark-whiteboard/references/lark-whiteboard-workflow.md new file mode 100644 index 00000000..59d4cda9 --- /dev/null +++ b/skills/lark-whiteboard/references/lark-whiteboard-workflow.md @@ -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 --as user`，从返回的 `` 提取 | +| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --api-version v2 --doc --command append --content '' --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 \ + --source - --input_format raw \ + --idempotent-token <10+字符唯一串> \ + --as user \ + --overwrite +``` + +> `--idempotent-token` 最少 10 字符，建议用时间戳+标识拼接（如 `1744800000-board-1`），避免重试导致重复写入。 +> 如需应用身份上传，将 `--as user` 替换为 `--as bot`。 diff --git a/skills/lark-whiteboard/routes/dsl.md b/skills/lark-whiteboard/routes/dsl.md index 792475ca..1b9977a2 100644 --- a/skills/lark-whiteboard/routes/dsl.md +++ b/skills/lark-whiteboard/routes/dsl.md @@ -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` 的图片准备） | ## 渲染前自查 diff --git a/skills/lark-whiteboard/scenes/flowchart.md b/skills/lark-whiteboard/scenes/flowchart.md index 16522493..c5c3a5fd 100644 --- a/skills/lark-whiteboard/scenes/flowchart.md +++ b/skills/lark-whiteboard/scenes/flowchart.md @@ -2,7 +2,7 @@ 适用于：各种业务流转图、决策树、审批流、时序控制逻辑、带条件判断的链路、系统架构拓扑等。 -通用字段语义详见 `references/schema.md`，通用布局原则详见 `references/layout.md`；本文件只描述流程图场景下的选型边界与范式。 +通用字段语义详见 `elements/schema.md`，通用布局原则详见 `elements/layout.md`；本文件只描述流程图场景下的选型边界与范式。 > [!IMPORTANT] > **流程图必须走 DSL 路径，不再使用 Mermaid！** diff --git a/skills/lark-whiteboard/scenes/mermaid.md b/skills/lark-whiteboard/scenes/mermaid.md index 821a841b..9d6795a1 100644 --- a/skills/lark-whiteboard/scenes/mermaid.md +++ b/skills/lark-whiteboard/scenes/mermaid.md @@ -7,7 +7,7 @@ | 中间格式 | JSON（WBDocument） | Mermaid 文本（.mmd 文件） | | 布局控制 | 精确控制（x/y 坐标、Flex） | 由 parser-kit 自动布局 | | 视觉定制 | 完全可控（颜色、字号、圆角等） | 有限（Mermaid 语法） | -| 参考模块 | references/ + 对应 scene | 仅本文件 | +| 参考模块 | elements/ + 对应 scene | 仅本文件 | ## 适用条件 diff --git a/skills/lark-whiteboard/scenes/photo-showcase.md b/skills/lark-whiteboard/scenes/photo-showcase.md index 2e139a58..84d7a424 100644 --- a/skills/lark-whiteboard/scenes/photo-showcase.md +++ b/skills/lark-whiteboard/scenes/photo-showcase.md @@ -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 约束 diff --git a/skills/lark-whiteboard/scenes/swimlane.md b/skills/lark-whiteboard/scenes/swimlane.md index 2d8fd75d..302e48c9 100644 --- a/skills/lark-whiteboard/scenes/swimlane.md +++ b/skills/lark-whiteboard/scenes/swimlane.md @@ -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` - 水平泳道示例：