diff --git a/skills/lark-doc/SKILL.md b/skills/lark-doc/SKILL.md index 571696cd5..20101067e 100644 --- a/skills/lark-doc/SKILL.md +++ b/skills/lark-doc/SKILL.md @@ -97,31 +97,19 @@ Drive Folder (云空间文件夹) └── file_token (直接使用) ``` -## 重要说明：画板编辑 -> **⚠️ lark-doc skill 不能直接编辑已有画板内容，但 `docs +update` 可以新建空白画板** -### 场景 1：已通过 docs +fetch 获取到文档内容和画板 token -如果用户已经通过 `docs +fetch` 拉取了文档内容，并且文档中已有画板（返回的 markdown 中包含 `` 标签），请引导用户： -1. 记录画板的 token -2. 查看 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md) 了解如何编辑画板内容 -### 场景 2：刚创建画板，需要编辑 -如果用户刚通过 `docs +update` 创建了空白画板，需要编辑时： -**步骤 1：按空白画板语法创建** -- 在 `--markdown` 中直接传 `` -- 需要多个空白画板时，在同一个 `--markdown` 里重复多个 whiteboard 标签 - **步骤 2：从响应中记录 token** -- `docs +update` 成功后，读取响应字段 `data.board_tokens` -- `data.board_tokens` 是新建画板的 token 列表，后续编辑直接使用这里的 token - **步骤 3：引导编辑** -- 记录需要编辑的画板 token -- 查看 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md) 了解如何编辑画板内容 -### 注意事项 -- 已有画板内容无法通过 lark-doc 的 `docs +update` 直接编辑 -- 编辑画板需要使用专门的 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md) - -## 文档可视化建议 -> **💡 在撰写文档时，当需要表达较为复杂的时序、架构层次、逻辑关系、数据流程等内容时，建议使用画板绘制可视化图表以显著提升文档的可阅读性。** -> -> 请参考 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md) 了解如何绘制画板内容。 +## 绘图需求识别与挖掘 + +用户很少主动提"画板"——**默认**使用飞书画板承载图表，命中以下任一信号即触发： +- 用户提到图表类型：架构图、流程图、时序图、组织图、路线图、对比图、鱼骨图、飞轮图、思维导图等 +- 用户表达可视化意图：画一下、梳理关系、画个流程、给我一个图、方便汇报等 +- 文档主题涉及结构关系、流程走向、时间线、数据对比 + +以下场景不加图：用户明确拒绝、合同/法律条款/合规声明等严谨连续文本、原样转录任务。 + +> [!CAUTION] +> 命中后，**MUST** 先读取 [`references/lark-doc-whiteboard.md`](references/lark-doc-whiteboard.md) 并**严格按其流程执行**。 +> +> **绝对禁止**用 `whiteboard-cli` 渲染 PNG 后通过 `docs +media-insert` 插入文档——图表必须通过 `lark-cli whiteboard +update` 写入画板 block，这是唯一合法路径。 ## 快速决策 - 用户说“看一下文档里的图片/附件/素材”“预览素材”，优先用 `lark-cli docs +media-preview`。 @@ -132,45 +120,6 @@ Drive Folder (云空间文件夹) - 拿到 spreadsheet URL / token 后，再切到 `lark-sheets` 做对象内部读取、筛选、写入等操作。 - 用户说“给文档加评论”“查看评论”“回复评论”“给评论加表情 / reaction”“删除评论表情 / reaction”，**不要留在 `lark-doc`**，直接切到 `lark-drive` 处理。 -## 画板需求挖掘（主动识别） - -> **用户很少主动提"画板"。创建文档时应主动识别适合可视化的内容，用画板呈现。** - -### 🔴 关键要求（必须遵守） - -**创建空白画板 ≠ 完成任务**。创建空白画板后，**必须继续使用 lark-whiteboard 技能填充实际内容**。 - -### 语义与画板类型映射 - -创建/编辑文档时，文档主题涉及以下语义，应**主动**创建画板，无需用户指定： - -| 语义 | 画板类型 | 参考指南 | -|---------------|-------|---------------------------------------------------------------------------------------------| -| 架构/分层/技术方案 | 架构图 | [lark-whiteboard-cli/scenes/architecture.md](../lark-whiteboard-cli/scenes/architecture.md) | -| 流程/审批/部署/业务流转 | 流程图 | [lark-whiteboard-cli/scenes/flowchart.md](../lark-whiteboard-cli/scenes/flowchart.md) | -| 组织/层级/汇报关系 | 组织架构图 | [lark-whiteboard-cli/scenes/organization.md](../lark-whiteboard-cli/scenes/organization.md) | -| 时间线/里程碑/版本规划 | 里程碑图 | [lark-whiteboard-cli/scenes/milestone.md](../lark-whiteboard-cli/scenes/milestone.md) | -| 因果/复盘/根因分析 | 鱼骨图 | [lark-whiteboard-cli/scenes/fishbone.md](../lark-whiteboard-cli/scenes/fishbone.md) | -| 方案对比/技术选型 | 对比图 | [lark-whiteboard-cli/scenes/comparison.md](../lark-whiteboard-cli/scenes/comparison.md) | -| 循环/飞轮/闭环 | 飞轮图 | [lark-whiteboard-cli/scenes/flywheel.md](../lark-whiteboard-cli/scenes/flywheel.md) | -| 层级占比/能力模型 | 金字塔图 | [lark-whiteboard-cli/scenes/pyramid.md](../lark-whiteboard-cli/scenes/pyramid.md) | -| 模块依赖/调用关系 | 架构图 | [lark-whiteboard-cli/scenes/architecture.md](../lark-whiteboard-cli/scenes/architecture.md) | -| 分类梳理/知识体系 | 思维导图 | [lark-whiteboard-cli/scenes/mermaid.md](../lark-whiteboard-cli/scenes/mermaid.md) | -| 数据分布/占比 | 饼图 | [lark-whiteboard-cli/scenes/mermaid.md](../lark-whiteboard-cli/scenes/mermaid.md) | - -创建画板前，务必先阅读 [`lark-whiteboard-cli`](../lark-whiteboard-cli/SKILL.md) 和 [`lark-whiteboard`](../lark-whiteboard/SKILL.md) 这两个 Skill，了解画板的创建流程。 - -### 完整执行流程（必须完整执行） - -1. **创建空白画板占位**：创建场景用 `docs +create`、编辑场景用 `docs +update` 插入空白画板 -2. **获取画板 token**：从 `docs +update` 响应的 `data.board_tokens` 获取画板 token 列表 -3. **填充画板内容**：切换到 [`lark-whiteboard-cli`](../lark-whiteboard-cli/SKILL.md) 创建画板内容，并填入画板 -4. **验证完成**：确认所有画板都有实际内容，不是空白 - -**不适用**：纯文字记录（日志/备忘）、数据密集型内容（用表格）、用户明确只要文字。 - -> ⚠️ **警告**：如果只创建空白画板而不填充内容，任务将被视为未完成！ - ## 补充说明 `docs +search` 除了搜索文档 / Wiki，也承担“先定位云空间对象，再切回对应业务 skill 操作”的资源发现入口角色；当用户口头说“表格 / 报表”时，也优先从这里开始。 @@ -186,4 +135,4 @@ Shortcut 是对常用操作的高级封装（`lark-cli docs + [flags]`） | [`+update`](references/lark-doc-update.md) | Update a Lark document | | [`+media-insert`](references/lark-doc-media-insert.md) | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback) | | [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) | -| [`+whiteboard-update`](references/lark-doc-whiteboard-update.md) | Update an existing whiteboard in lark document with whiteboard dsl. Such DSL input from stdin. refer to lark-whiteboard skill for more details. | +| [`+whiteboard-update`](../lark-whiteboard/references/lark-whiteboard-update.md) | Alias of `whiteboard +update`. Update an existing whiteboard with DSL, Mermaid or PlantUML. Prefer `whiteboard +update`; refer to lark-whiteboard skill for details. | diff --git a/skills/lark-doc/references/lark-doc-create.md b/skills/lark-doc/references/lark-doc-create.md index 03f437240..b23326f43 100644 --- a/skills/lark-doc/references/lark-doc-create.md +++ b/skills/lark-doc/references/lark-doc-create.md @@ -57,9 +57,8 @@ lark-cli docs +create --title "学习笔记" --wiki-space my_library --markdown 如果文档中包含空白画板（``），**必须继续以下步骤**： 1. 从返回值的 `data.board_tokens` 字段记录所有新建画板的 token -2. 立即切换到 [`lark-whiteboard`](../lark-whiteboard/SKILL.md) 技能 -3. 使用 `whiteboard +update` 命令为每个画板填充实际内容（Mermaid/PlantUML/DSL） -4. 确认所有画板都有实际内容后，任务才算完成 +2. 读取 `../../lark-whiteboard/SKILL.md`，跳至"渲染 & 写入画板"章节，为每个 board_token 生成并写入实际内容 +3. 确认所有画板都有实际内容后，任务才算完成 **仅创建空白画板是不够的！** 如果只创建空白画板而不填充内容，任务将被视为未完成。 @@ -85,7 +84,7 @@ lark-cli docs +create --title "学习笔记" --wiki-space my_library --markdown - **视觉节奏**：用分割线、分栏、表格打破大段纯文字 - **图文交融**：流程、架构或草图需要可视化时，优先使用图片、表格或空白画板 - **克制留白**：Callout 不过度、加粗只强调核心词 -- **主动画板**：文档涉及架构、流程、组织、时间线、因果等逻辑关系时，主动插入空白画板，后续用 lark-whiteboard 填充；但若用户明确要求仅文本或内容更适合表格，则不插入。详见 [画板需求挖掘](../SKILL.md#画板需求挖掘主动识别) +- **主动画板**：文档涉及架构、流程、组织、时间线、因果等逻辑关系时，**必须**在 markdown 对应章节的文字内容之后插入 `` 占位，每个图表对应一个标签。**禁止**用 `whiteboard-cli` 渲染的 PNG/SVG 图片替代画板。创建完成后从返回值 `data.board_tokens` 取 token，读取 `../../lark-whiteboard/SKILL.md` 的"渲染 & 写入画板"章节为每个 token 写入图表内容。例：文档含"系统整体架构""分层架构""部署架构"各需插入一个画板，"类图"也需插入一个画板（走 Mermaid 路由）。 当用户有明确的样式、风格需求时，应当以用户的需求为准！ @@ -450,7 +449,7 @@ lark-cli docs +create --title "空白画板示例" --markdown '` - 读取时只能获取 token，可通过 media-download 查看内容，无法直接读出画板内部内容 -- 画板编辑：详见 [SKILL.md](../SKILL.md#重要说明画板编辑) +- 画板编辑：详见 [../../lark-whiteboard/SKILL.md](../../lark-whiteboard/SKILL.md) ### 多维表格（Base） diff --git a/skills/lark-doc/references/lark-doc-whiteboard-update.md b/skills/lark-doc/references/lark-doc-whiteboard-update.md deleted file mode 100644 index bfe58dbea..000000000 --- a/skills/lark-doc/references/lark-doc-whiteboard-update.md +++ /dev/null @@ -1,6 +0,0 @@ - -# docs +whiteboard-update（更新飞书画板） - -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 - -本 shortcut 仅为兼容历史调用保留，具体使用方式请参考 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md) \ No newline at end of file diff --git a/skills/lark-doc/references/lark-doc-whiteboard.md b/skills/lark-doc/references/lark-doc-whiteboard.md new file mode 100644 index 000000000..5ef05f17a --- /dev/null +++ b/skills/lark-doc/references/lark-doc-whiteboard.md @@ -0,0 +1,66 @@ +# lark-doc 画板处理指南 + +> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +## 两个 Skill 的职责边界 + +| Skill | 核心职责 | 约束 | +|------|------|------| +| `lark-doc` | 文档内容读取/更新、插入空白画板占位、获取 board_token | 不能直接编辑画板内容；`docs +update` 的画板能力仅限插入空白占位 | +| `lark-whiteboard` | 查询/导出画板（+query）；图表内容生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入画板（+update） | 图表内容生成由此 skill 完整执行，不依赖外部调度 | + +## 文档与画板协同流程 + +### 步骤 1：判断场景 + +| 场景 | 入口 | +|------|------| +| 文档中需要插入新画板 | 继续步骤 2 | +| 已有画板需要更新内容 | 先 `docs +fetch` 获取 `board_token`，跳至步骤 3 | +| 只查看 / 下载已有画板 | 切换至 `lark-whiteboard`，不走本流程 | + +### 步骤 2：在文档中创建空白画板 + +- 创建场景：`docs +create`；编辑场景：`docs +update` +- markdown 中使用 ``（不要转义） +- 多个画板时，在相应的地方插入各自的 whiteboard 标签 +- 从响应的 `data.board_tokens` 中读取 token 列表 + +### 步骤 3：生成并写入画板内容 + +读取 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)，跳至"渲染 & 写入画板"章节，按其完整流程为每个 board_token 生成并写入图表内容。 + +多个画板时依次处理，每个画板完成后再处理下一个。 + +### 步骤 4：完成校验 + +- 确认每个 token 对应的画板都已填充真实内容 +- 不保留空白占位画板；只有空白画板而无内容视为任务未完成 + +--- + +## 语义与画板类型映射 + +| 语义 | 画板类型 | +|------|------| +| 架构/分层/技术方案/模块依赖/调用关系 | 架构图 | +| 流程/审批/部署/业务流转/状态机 | 流程图 | +| 跨角色流程/跨系统交互/端到端链路 | 泳道图 | +| 组织/层级/汇报关系 | 组织架构图 | +| 时间线/里程碑/版本规划 | 里程碑图 | +| 因果/复盘/根因分析 | 鱼骨图 | +| 方案对比/技术选型/功能矩阵 | 对比图 | +| 循环/飞轮/闭环/增长链路 | 飞轮图 | +| 层级占比/能力模型/需求层次 | 金字塔图 | +| 矩形树图/层级面积占比 | 树状图 | +| 转化漏斗/销售漏斗 | 漏斗图 | +| 分类梳理/知识体系/思维导图/时序图/类图 | Mermaid | +| 数据分布/占比/饼图 | Mermaid | +| 柱状图/条形图/数据对比 | 柱状图 | +| 折线图/趋势图/时序数据 | 折线图 | + +--- + +## 关联参考 + +- 画板查询/创作/修改/渲染写入：[`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md) diff --git a/skills/lark-whiteboard-cli/SKILL.md b/skills/lark-whiteboard-cli/SKILL.md deleted file mode 100644 index 736b0018f..000000000 --- a/skills/lark-whiteboard-cli/SKILL.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -name: lark-whiteboard-cli -description: > - 当用户要求或使用飞书画板绘制架构图、流程图、思维导图、时序图或其他可视化图表时使用此 skill，作为使用 whiteboard-cli 设计图表布局的指南 -compatibility: Requires Node.js 18+ -metadata: - requires: - bins: ["lark-cli"] ---- - -> [!NOTE] -> **环境依赖**：绘制画板需要 `@larksuite/whiteboard-cli`（画板 Node.js CLI 工具），以及 `lark-cli`（LarkSuite CLI 工具）。 -> 如果执行失败，手动安装后重试：`npm install -g @larksuite/whiteboard-cli@^0.2.0` - -> [!IMPORTANT] -> 执行 `npm install` 安装新的依赖前，务必征得用户同意！ - - -## Workflow - -> **这是画板，不是网页。** 画板是无限画布上自由放置元素，flex 布局是可选增强。 - -``` -Step 1: 路由 & 读取知识 - - 判断渲染路径（见路由表）：Mermaid 还是 DSL？ - - 读对应 scene 指南 — 了解结构特征和布局策略 - - 确定布局策略（见下方快速判断）和构建方式 - - 读 references/ 核心模块 — 语法、布局、配色、排版、连线 - -Step 2: 生成完整 DSL（含颜色） - - 按 content.md 规划信息量和分组 - - 按 layout.md 选择布局模式和间距 - - 推荐使用图标让图表更直观，运行 `npx -y @larksuite/whiteboard-cli@^0.2.0 --icons` 查看可用图标，选取合适的图标, 但不要过度使用或者所有图表都用图标, 根据图表类型和内容选择是否使用图标 - - 按 style.md 上色（用户没指定时用默认经典色板） - - 按 schema.md 语法输出完整 JSON - - 连线参考 connectors.md，排版参考 typography.md - - 注意：部分图形（鱼骨/飞轮/柱状/折线等）要按 scene 指南的脚本模板写 .js 脚本生成 JSON： - 1. 创建产物目录 ./diagrams/YYYY-MM-DDTHHMMSS/ - 2. 将脚本保存为 diagram.gen.js，执行 node diagram.gen.js 产出 diagram.json - 3. 用产出的 diagram.json 进入 Step 3 - -Step 3: 渲染 & 审查 → 交付 - - 渲染前自查（见下方检查清单） - - 渲染 PNG，检查： - · 信息完整？布局合理？配色协调？ - · 文字无截断？连线无交叉？ - - 有问题 → 按症状表修复 → 重新渲染（最多 2 轮） - - 2 轮后仍有严重问题 → 考虑走 Mermaid 路径兜底 - - 没问题 → 交付： - · 用户要求上传飞书 → 见下方”上传飞书画板”章节中的说明 - · 用户未指定 → 展示 PNG 图片给用户 -``` - -**布局策略快速判断**（详见 `references/layout.md`）： - -先定**主布局**，再定子布局：**结构化信息**优先用 Flex，**关系链路**优先用 Dagre，**灵活定位**用绝对布局。 - -涉及 Dagre / Flex 的具体边界、危险模式、混合布局原则，统一以 `references/layout.md` 为准；scene 文件只描述场景差异，不重复定义通用布局规则。 - -> **构建方式是强约束**：当 scene 指南要求"脚本生成"时，必须先写脚本（.js）并用 `node` 执行来产出 JSON 文件。绝对定位场景（鱼骨图、飞轮图、柱状图、折线图等）的坐标需要数学计算，直接手写 JSON 极易导致节点重叠或连线穿模。 ---- - -## 渲染路径选择（DSL or Mermaid） - -| 图表类型 | 路径 | 理由 | -| ------------ | ----------- | ------------------- | -| 思维导图 | **Mermaid** | 辐射结构自动布局 | -| 时序图 | **Mermaid** | 参与方+消息自动排列 | -| 类图 | **Mermaid** | 类关系自动布局 | -| 饼图 | **Mermaid** | Mermaid 原生支持 | -| 其他所有类型 | **DSL** | 精确控制样式和布局 | - -**路由规则**： -1. **自动 Mermaid**：思维导图、时序图、类图、饼图 → 默认走 Mermaid -2. **显式 Mermaid**：用户输入包含 Mermaid 语法 → 走 Mermaid -3. **DSL 路径**：其他所有类型 → 先读核心模块，再读对应场景指南 - -**Mermaid 路径**：参考 `scenes/mermaid.md` 编写 `.mmd` 文件，跳过 DSL 模块。 -**DSL 路径**：按 Workflow 3 步执行。 - ---- - -## 模块索引 - -### 核心参考（DSL 路径必读） - -| 模块 | 文件 | 说明 | -| -------- | -------------------------- | ------------------------------- | -| DSL 语法 | `references/schema.md` | 节点类型、属性、尺寸值 | -| 内容规划 | `references/content.md` | 信息提取、密度决策、连线预判 | -| 布局系统 | `references/layout.md` | 网格方法论、Flex 映射、间距规则 | -| 排版规则 | `references/typography.md` | 字号层级、对齐、行距 | -| 连线系统 | `references/connectors.md` | 拓扑规划、锚点选择 | -| 配色系统 | `references/style.md` | 多色板、视觉层级 | - - -### 场景指南（按类型选读一个） - -| 图表类型 | 文件 | 适用场景 | -| ----------- | ------------------------ | -------------------------------------- | -| 架构图 | `scenes/architecture.md` | 分层架构、微服务架构 | -| 组织架构图 | `scenes/organization.md` | 公司组织、树形层级 | -| 泳道图 | `scenes/swimlane.md` | 跨角色流程、跨系统交互流程、端到端链路 | -| 对比图 | `scenes/comparison.md` | 方案对比、功能矩阵 | -| 鱼骨图 | `scenes/fishbone.md` | 因果分析、根因分析 | -| 柱状图 | `scenes/bar-chart.md` | 柱状图、条形图 | -| 折线图 | `scenes/line-chart.md` | 折线图、趋势图 | -| 树状图 | `scenes/treemap.md` | 矩形树图、层级占比 | -| 漏斗图 | `scenes/funnel.md` | 转化漏斗、销售漏斗 | -| 金字塔图 | `scenes/pyramid.md` | 层级结构、需求层次 | -| 循环/飞轮图 | `scenes/flywheel.md` | 增长飞轮、闭环链路 | -| 里程碑 | `scenes/milestone.md` | 时间线、版本演进 | -| 流程图 | `scenes/flowchart.md` | 业务流、状态机、带条件判断的链路 | -| Mermaid | `scenes/mermaid.md` | 思维导图、时序图、类图、饼图 | - ---- - -## 文件产物规范 - -每次绘图在 `./diagrams/` 下按当前时间创建子目录（格式 `YYYY-MM-DDTHHMMSS`），目录内文件名固定。用户指定了保存路径时以用户为准。 - -``` -./diagrams/ - 2026-03-27T143000/ ← 自动按时间创建，无需起名 - diagram.json ← DSL（CLI 输入） - diagram.gen.js ← 坐标计算脚本（仅脚本构建方式） - diagram.png ← 最终图片 - diagram.mmd ← Mermaid 源码（仅 Mermaid 路径） -``` - -## CLI 命令 - -**查看可用图标**： -```bash -npx -y @larksuite/whiteboard-cli@^0.2.0 --icons -``` - -**渲染**： -```bash -npx -y @larksuite/whiteboard-cli@^0.2.0 -i ./diagrams/2026-03-27T143000/diagram.json -o ./diagrams/2026-03-27T143000/diagram.png # DSL -npx -y @larksuite/whiteboard-cli@^0.2.0 -i ./diagrams/2026-03-27T143000/diagram.mmd -o ./diagrams/2026-03-27T143000/diagram.png # Mermaid -``` - -**上传飞书画板**： - -> 上传需要飞书认证。遇到认证或权限错误时，阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 了解登录和权限处理。 - -**第一步：获取画板 Token** - -| 用户给了什么 | 怎么获取 Token | -| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 画板 Token（`XXX`） | 直接使用 | -| 文档 URL 或 doc_id，文档中已有画板 | `lark-cli docs +fetch --doc --as user`，从返回的 `` 中提取 token | -| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --doc --mode append --markdown '' --as user`，从响应的 `data.board_tokens[0]` 获取 token | - -关于飞书文档的创建，读取等更多操作，请参考 lark-doc skill [`../lark-doc/SKILL.md`](../lark-doc/SKILL.md)。 - -**第二步：上传** - -> [!CAUTION] -> **MANDATORY PRE-FLIGHT CHECK (上传前强制拦截检查)** -> 当你要向一个**已存在的画板 Token** 写入内容时，**绝对禁止**直接执行上传命令！你必须严格遵守以下两步： -> **强制执行 Dry Run（状态探测）** -> 必须先在命令中添加 `--overwrite --dry-run` 参数来探测画板当前状态。示例命令： -> ```bash -> npx -y @larksuite/whiteboard-cli@^0.2.0 --to openapi -i <输入文件> --format json | lark-cli whiteboard +update --whiteboard-token --source - --overwrite --dry-run --as user -> ``` -> -> **解析结果并拦截** -> - 仔细阅读 Dry Run 的输出日志。 -> - **如果日志包含 `XX whiteboard nodes will be deleted`**：这说明画板**非空**，当前操作会覆盖并摧毁用户的原有图表！ -> - **你必须立即停止操作**，并通过 `AskUserQuestion` 工具（或直接回复）向用户确认：”目标画板当前非空，继续更新将清空原有的 XX 个节点，是否确认覆盖？” -> - 只有在用户明确授权”同意覆盖”后，你才能移除 `--dry-run` 真正执行上传。 -> - 用户可能会要求你不覆盖更新画板内容，在这种情况下，移除 `--overwrite` 和 `--dry-run` 参数再上传。 - -```bash -npx -y @larksuite/whiteboard-cli@^0.2.0 --to openapi -i <输入文件> --format json | lark-cli whiteboard +update --whiteboard-token <画板Token> --source - --yes --as user -``` -> 画板一经上传不可修改。如需应用身份上传，将 `--as user` 替换为 `--as bot`。 -> 如果画板非空，先加 `--overwrite --dry-run` 检查待删除节点数，向用户确认后去掉 `--dry-run` 执行。 - -你也可以将布局输出为原生 OpenAPI json 格式，再通过 lark-cli 导入飞书画板。关于 lark-cli 操作画板的更多方式，请参照 [../lark-whiteboard/SKILL.md](../lark-whiteboard/SKILL.md) - -**症状→修复表**（视觉审查发现问题时参照）： - -| 看到的问题 | 改什么 | -| ------------------ | ----------------------------------- | -| 文字被截断 | height 改为 fit-content | -| 文字溢出容器右侧 | 增大 width，或缩短文字 | -| 节点重叠粘连 | 增大 gap | -| 节点挤成一团 | 增大 padding 和 gap | -| 连线穿过节点 | 调整 fromAnchor/toAnchor 或增大间距 | -| 大面积空白 | 缩小外层 frame 宽度 | -| 文字和背景色太接近 | 调整 fillColor 或 textColor | -| 布局整体偏左/偏右 | 调整绝对定位的 x 坐标使内容居中 | - ---- - -## 渲染前自查 - -生成 DSL 后、渲染前，快速检查： - -- [ ] 不同分组用了不同颜色？同组节点样式完全一致？ -- [ ] 外层浅色背景、内层白色节点？（外重内轻） -- [ ] 所有节点有边框（borderWidth=2）？文字在背景上清晰可读？ -- [ ] 连线用灰色（#BBBFC4），不用彩色？ -- [ ] frame 都写了 layout 属性？gap 和 padding 都显式设置了？ -- [ ] 含文字节点 height 用 fit-content？connector 在顶层 nodes 数组？ - ---- - -## 关键约束速查 - -> 最高频出错的规则，即使不读子模块文件也必须遵守。 - -1. **含文字节点的 height 必须用 `'fit-content'`** — 写死数值会截断文字 -2. **`fill-container` 仅在 flex 父容器中生效** — `layout: 'none'` 下宽度退化为 0 -3. **`layout: 'none'` 的容器必须有固定宽高** — 不要写成 `fit-content` -4. **connector 必须放在顶层 nodes 数组** — 不能嵌套在 frame children 里 -5. **图层顺序** — 数组顺序 = 绘制顺序。后定义的元素层级越高，会覆盖先定义的。重叠/浮层/标注元素务必放在数组末尾。 -6. **flex 容器内的 x/y 会被完全忽略** — 需要自由定位时用 `layout: 'none'` 或放在顶层 nodes -7. **Dagre 子容器默认为不透明节点** — 外层连线无法寻址其内部子节点（引擎会自动重定向至外壳）。需穿透时声明 `layout: "dagre"` + `layoutOptions: { isCluster: true }` - -❌ 致命错误：flex 容器内设 x/y，坐标不生效，节点按顺序排列 -```json -{ "type": "frame", "layout": "vertical", "children": [ - { "type": "rect", "x": 100, "y": 0, "text": "成都" }, - { "type": "rect", "x": 540, "y": 0, "text": "康定" } -]} -``` -✅ 正确：用 `layout: "none"` 或放在顶层 nodes 用 x/y 定位。 - -❌ 致命错误：`layout: "none"` 容器本身写 `width: "fit-content", height: "fit-content"`，再在内部摆绝对坐标节点 - -✅ 正确：绝对定位容器先给固定宽高，再在内部用 x/y 放置子节点。 diff --git a/skills/lark-whiteboard/SKILL.md b/skills/lark-whiteboard/SKILL.md index 944ec4480..2ddc4696a 100644 --- a/skills/lark-whiteboard/SKILL.md +++ b/skills/lark-whiteboard/SKILL.md @@ -2,117 +2,144 @@ name: lark-whiteboard version: 1.0.0 description: > - 飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用 PlantUML/Mermaid 代码或 OpenAPI 原生格式更新画板内容。 - 当用户需要查看画板内容、导出画板图片、或编辑画板，或是需要可视化表达架构、流程、组织关系、时间线、因果、对比等结构化信息时使用此 skill，无论是否提及"画板"。 + 飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用 DSL（转成 OpenAPI 格式）、PlantUML/Mermaid 格式更新画板内容。 + 当用户需要查看画板内容、导出画板图片、编辑画板，或是需要可视化表达架构、流程、组织关系、时间线、因果、对比等结构化信息时使用此 skill，无论是否提及"画板"。 metadata: requires: - bins: [ "lark-cli" ] + bins: ["lark-cli"] cliHelp: "lark-cli whiteboard --help" --- -# whiteboard (v1) +> [!IMPORTANT] +> **执行前检查环境**： +> - 运行 `whiteboard-cli --version`，确认版本为 `0.2.x`；未安装或版本不符 → `npm install -g @larksuite/whiteboard-cli@^0.2.0` +> - 运行 `lark-cli --version`，确认可用。 +> - 执行任何 `npm install` 前，**必须征得用户同意**。 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理** -## 核心概念 +--- -### 画板 Token +## 快速决策 -画板 token 是画板的唯一标识符。飞书画板嵌入在云文档中，可以从云文档的 `docs +fetch` 结果中获取（`` -标签），或从 `docs +update` 新建画板后的 `data.board_tokens` 字段中获取。 +| 用户需求 | 行动 | +|---|---| +| 查看画板内容 / 导出图片 | [`+query --output_as image`](references/lark-whiteboard-query.md) | +| 获取画板的 Mermaid/PlantUML 代码 | [`+query --output_as code`](references/lark-whiteboard-query.md) | +| 检查画板是否由代码绘制 | [`+query --output_as code`](references/lark-whiteboard-query.md) | +| 修改节点文字/颜色（简单改动）| `+query --output_as raw` → 手动改 JSON → `+update --input_format raw` | +| 用户**已提供** Mermaid/PlantUML 代码，或明确指定用该格式 | 自己生成/使用代码 → [`+update --input_format mermaid/plantuml`](references/lark-whiteboard-update.md) | +| 绘制复杂图表（架构/流程/组织等）| → **[§ 创作 Workflow](#创作-workflow)** | +| 修改/重绘已有复杂画板 | → **[§ 修改 Workflow](#修改-workflow)** | -## 快速决策 +> **⚠️ 强制规范（通过 stdin 更新）**： +> 数据来源于本地文件时，**必须**使用 `--source - --input_format <格式>`。 +> 例：`cat chart.mmd | lark-cli whiteboard +update --source - --input_format mermaid` -当需要插入图表时： +## Shortcuts -1. 能否使用飞书画板？ - - 能 → 走画板路径（推荐！可编辑、可协作） - - 不能 → 走图片路径 +| Shortcut | 说明 | +|---|---| +| [`+query`](references/lark-whiteboard-query.md) | 查询画板，导出为预览图片、代码或原始节点结构 | +| [`+update`](references/lark-whiteboard-update.md) | 更新画板，支持 PlantUML、Mermaid 或 OpenAPI 原生格式 | -| 用户需求 | 推荐 Shortcut | -|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| -| "查看这个画板的内容" | [`+query --output_as image`](references/lark-whiteboard-query.md) | -| "导出画板为图片" | [`+query --output_as image`](references/lark-whiteboard-query.md) | -| "获取画板的 PlantUML/Mermaid 代码" | [`+query --output_as code`](references/lark-whiteboard-query.md) | -| "检查画板是否由 PlantUML/Mermaid 代码块组成" | [`+query --output_as code`](references/lark-whiteboard-query.md) | -| "修改画板某个节点的颜色或文字" | [`+query --output_as raw`](references/lark-whiteboard-query.md) 后 [`+update`](references/lark-whiteboard-update.md) | -| "用 PlantUML 绘制画板" | [`+update --input_format plantuml`](references/lark-whiteboard-update.md) | -| "用 Mermaid 绘制画板" | [`+update --input_format mermaid`](references/lark-whiteboard-update.md) | -| "在画板绘制复杂图表" | [`+update --input_format raw`](references/lark-whiteboard-update.md), 需要使用 whiteboard-cli 工具，参见 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) | +--- -## Shortcuts +## 创作 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 --as user`，从返回的 `` 提取 | +| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --doc --mode append --markdown '' --as user`，从响应 `data.board_tokens[0]` 取得（参数详见 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 ← 渲染结果 +``` + +### 写入画板 + +> [!CAUTION] +> **写入前强制 dry-run**：向已有内容的画板写入时，必须先加 `--overwrite --dry-run` 探测。 +> 输出含 `XX whiteboard nodes will be deleted` → 必须向用户确认后才能执行。 + +```bash +# 第一步：dry-run 探测 +npx -y @larksuite/whiteboard-cli@^0.2.0 -i <产物文件> --to openapi --format json \ + | lark-cli whiteboard +update \ + --whiteboard-token \ + --source - --input_format raw \ + --idempotent-token <10+字符唯一串> \ + --overwrite --dry-run --as user + +# 第二步：确认后执行 +npx -y @larksuite/whiteboard-cli@^0.2.0 -i <产物文件> --to openapi --format json \ + | lark-cli whiteboard +update \ + --whiteboard-token \ + --source - --input_format raw \ + --idempotent-token <10+字符唯一串> \ + --overwrite --as user +``` -| Shortcut | 说明 | -|---------------------------------------------------|---------------------------------------------| -| [`+query`](references/lark-whiteboard-query.md) | 查询画板，导出为预览图片、代码或原始节点结构 | -| [`+update`](references/lark-whiteboard-update.md) | 更新画板内容，支持 PlantUML、Mermaid 或 OpenAPI 原生格式输入 | - -## Workflow - -### 场景 1: 创作一个画板 - -1. 确定需要创作的画板 Token（从用户请求或对应的文档中获取）与要创作的内容 -2. 参考 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) 生成画板内容 -3. 使用 [`+update`](references/lark-whiteboard-update.md) shortcut 更新画板内容 - -### 场景 2: 修改或优化一个画板 - -1. 确定要修改的画板 Token （从用户请求或对应的文档中获取） -2. 使用 [`+query --output_as code`](references/lark-whiteboard-query.md) shortcut 导出画板代码，确认画板是否由 Mermaid 或 - PlantUML 绘制 - 1. 如果 +query --output_as code 返回了 Mermaid / PlantUML 代码块，则在这一代码的基础上优化修改 - 2. 如果没有返回代码块，则使用 [`+query --output_as image`](references/lark-whiteboard-query.md) - 获取画板预览图片，根据图片内容参考 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) 重绘优化 - 3. 如果用户只需要简单修改某个节点的文本内容/颜色，可以使用 [ - `+query --output_as raw`](references/lark-whiteboard-query.md) shortcut 导出画板原生 OpenAPI 格式，并在此基础上修改。 - 4. 如果用户有明确要求，则以用户要求优先。 -3. 使用 [`+update`](references/lark-whiteboard-update.md) shortcut 创建新的画板内容。根据用户需求，你可能会需要使用 [ - `docs +update`](../lark-doc/references/lark-doc-update.md) 创建新的画板，或使用 [ - `+update --overwrite`](references/lark-whiteboard-update.md) 在原画板上覆盖式更新。 - -## 与 lark-doc 的配合使用 - -### 场景 1: 从文档中获取画板 token - -1. 使用 `lark-doc` 的 [`+fetch`](../lark-doc/references/lark-doc-fetch.md) 获取文档内容 -2. 从返回的 markdown 中解析 `` 标签，记录画板 token -3. 使用本 skill 的 `+query` 或 `+update` 读取或操作画板 - -### 场景 2: 新建画板并编辑（完整流程） - -这是最常见的使用场景，**必须完整执行以下步骤**： - -1. 使用 `lark-doc` 的 [`+update`](../lark-doc/references/lark-doc-update.md) 创建空白画板 - - 在 markdown 中传入 `` - - **注意这一 XML 标签不要转义** - - 需要多个画板时，重复多个 whiteboard 标签 - -2. 从响应的 `data.board_tokens` 中获取新建画板的 token 列表 - - 记录每个 token 对应的图表类型和位置 - -3. 根据文档主题，为每个画板设计相应的内容 - - 参考下方"常见图表模板与参考指南"选择合适的语法 - - 使用 Mermaid（推荐）、PlantUML 或 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) 生成内容 - -4. **逐个更新画板**：使用本 skill 的 `+update` shortcut 编辑每个画板的内容 - - 不要遗漏任何一个画板 token - - 确保每个画板都有实际内容，不是空白 - -### 常见图表模板与参考指南 - -| 图表类型 | 推荐语法 | 详细参考指南 | -|----------------|--------------------|---------------------------------------------------------------------------------------------| -| 架构图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/architecture.md](../lark-whiteboard-cli/scenes/architecture.md) | -| 流程图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/flowchart.md](../lark-whiteboard-cli/scenes/flowchart.md) | -| 组织架构图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/organization.md](../lark-whiteboard-cli/scenes/organization.md) | -| 里程碑/时间线 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/milestone.md](../lark-whiteboard-cli/scenes/milestone.md) | -| 鱼骨图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/fishbone.md](../lark-whiteboard-cli/scenes/fishbone.md) | -| 对比图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/comparison.md](../lark-whiteboard-cli/scenes/comparison.md) | -| 飞轮图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/flywheel.md](../lark-whiteboard-cli/scenes/flywheel.md) | -| 金字塔图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/pyramid.md](../lark-whiteboard-cli/scenes/pyramid.md) | -| 思维导图/饼图/时序图/类图 | Mermaid | [lark-whiteboard-cli/scenes/mermaid.md](../lark-whiteboard-cli/scenes/mermaid.md) | -| 柱状图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/bar-chart.md](../lark-whiteboard-cli/scenes/bar-chart.md) | -| 折线图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/line-chart.md](../lark-whiteboard-cli/scenes/line-chart.md) | -| 树状图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/treemap.md](../lark-whiteboard-cli/scenes/treemap.md) | -| 漏斗图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/funnel.md](../lark-whiteboard-cli/scenes/funnel.md) | -| 泳道图 | whiteboard-cli DSL | [lark-whiteboard-cli/scenes/swimlane.md](../lark-whiteboard-cli/scenes/swimlane.md) | +> `--idempotent-token` 最少 10 字符，建议用时间戳+标识拼接（如 `1744800000-board-1`），避免重试导致重复写入。 +> 如需应用身份上传，将 `--as user` 替换为 `--as bot`。 diff --git a/skills/lark-whiteboard-cli/references/connectors.md b/skills/lark-whiteboard/references/connectors.md similarity index 100% rename from skills/lark-whiteboard-cli/references/connectors.md rename to skills/lark-whiteboard/references/connectors.md diff --git a/skills/lark-whiteboard-cli/references/content.md b/skills/lark-whiteboard/references/content.md similarity index 100% rename from skills/lark-whiteboard-cli/references/content.md rename to skills/lark-whiteboard/references/content.md diff --git a/skills/lark-whiteboard/references/lark-whiteboard-query.md b/skills/lark-whiteboard/references/lark-whiteboard-query.md index 3ed08fa46..a6d505b9a 100644 --- a/skills/lark-whiteboard/references/lark-whiteboard-query.md +++ b/skills/lark-whiteboard/references/lark-whiteboard-query.md @@ -1,6 +1,6 @@ # whiteboard +query（查询画板） -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 +> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 查询画板内容，支持导出为预览图片、提取 PlantUML/Mermaid 代码，或获取飞书 OpenAPI 原生画板节点格式。 @@ -17,7 +17,7 @@ - `image`：预览图片 - `code`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。 -- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) 。 +- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)。 ## 示例 diff --git a/skills/lark-whiteboard/references/lark-whiteboard-update.md b/skills/lark-whiteboard/references/lark-whiteboard-update.md index 4500185e6..fe7b0dbdc 100644 --- a/skills/lark-whiteboard/references/lark-whiteboard-update.md +++ b/skills/lark-whiteboard/references/lark-whiteboard-update.md @@ -1,6 +1,6 @@ # whiteboard +update（更新画板） -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 +> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 更新画板内容，支持三种输入格式： @@ -26,8 +26,7 @@ 思维导图，时序图，类图，饼图，流程图等图标推荐使用 Mermaid/PlantUML 语法绘制。 -而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) -使用 whiteboard-cli 工具创作。 +而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板) 使用 whiteboard-cli 工具创作。 ## 示例 @@ -69,28 +68,32 @@ lark-cli whiteboard +update \ --overwrite --yes --as user ``` -### 示例 3：使用 whiteboard-cli 直接使用画板 DSL 更新画板 +### 示例 3：使用 whiteboard-cli 生成 OpenAPI 格式并写入画板 -whiteboard-cli 工具的具体用法请参考 [../lark-whiteboard-cli/SKILL.md](../lark-whiteboard-cli/SKILL.md) +whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板) ```bash # 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递 -npx -y @larksuite/whiteboard-cli@^0.1.0 --to openapi -i <画板 DSL> --format json | lark-cli whiteboard +update \ - --whiteboard-token <画板Token> \ - --input_format raw --source -\ - --overwrite --yes --as user +npx -y @larksuite/whiteboard-cli@^0.2.0 -i <产物文件> --to openapi --format json \ + | lark-cli whiteboard +update \ + --whiteboard-token <画板Token> \ + --source - --input_format raw \ + --idempotent-token <10+字符唯一串> \ + --yes --as user ``` -### 示例 4：使用 whiteboard-cli 使用画板 DSL 生成 Raw 格式 Json，并使用其更新画板 +### 示例 4：先生成产物文件，再从文件读取更新 -whiteboard-cli 工具的具体用法请参考 [../lark-whiteboard-cli/SKILL.md](../lark-whiteboard-cli/SKILL.md) +whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板) ```bash -# 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递 -npx -y @larksuite/whiteboard-cli@^0.1.0 --to openapi -i <画板 DSL> -o ./temp.json +# 生成 OpenAPI 格式到文件 +npx -y @larksuite/whiteboard-cli@^0.2.0 -i --to openapi --format json -o ./temp.json +# 从文件读取并更新 lark-cli whiteboard +update \ --whiteboard-token <画板Token> \ + --idempotent-token <10+字符唯一串> \ --input_format raw \ --source @./temp.json \ --overwrite --yes --as user diff --git a/skills/lark-whiteboard-cli/references/layout.md b/skills/lark-whiteboard/references/layout.md similarity index 99% rename from skills/lark-whiteboard-cli/references/layout.md rename to skills/lark-whiteboard/references/layout.md index 8238ce979..8f8c56305 100644 --- a/skills/lark-whiteboard-cli/references/layout.md +++ b/skills/lark-whiteboard/references/layout.md @@ -58,7 +58,7 @@ | ---------------------- | ----------------------------------------------------------------------------- | | 纯 Flex / Dagre | 直接写 JSON | | 混合布局 (Flex包Dagre) | 直接写 JSON（外层先做分区，局部复杂关系交给 Dagre；若被嵌套，默认为不透明节点） | -| 极度依赖几何坐标的图 | 写脚本生成 JSON（node xxx.js） | +| 极度依赖几何坐标的图 | 写脚本生成 JSON（node xxx.cjs） | | 需要精确避让的特殊线 | 脚本 + `--layout` 两阶段 | --- diff --git a/skills/lark-whiteboard-cli/references/schema.md b/skills/lark-whiteboard/references/schema.md similarity index 100% rename from skills/lark-whiteboard-cli/references/schema.md rename to skills/lark-whiteboard/references/schema.md diff --git a/skills/lark-whiteboard-cli/references/style.md b/skills/lark-whiteboard/references/style.md similarity index 100% rename from skills/lark-whiteboard-cli/references/style.md rename to skills/lark-whiteboard/references/style.md diff --git a/skills/lark-whiteboard-cli/references/typography.md b/skills/lark-whiteboard/references/typography.md similarity index 100% rename from skills/lark-whiteboard-cli/references/typography.md rename to skills/lark-whiteboard/references/typography.md diff --git a/skills/lark-whiteboard/routes/dsl.md b/skills/lark-whiteboard/routes/dsl.md new file mode 100644 index 000000000..b3877098e --- /dev/null +++ b/skills/lark-whiteboard/routes/dsl.md @@ -0,0 +1,106 @@ +# DSL 路径 + +> **这是画板，不是网页。** 画板是无限画布上自由放置元素，flex 布局是可选增强。 + +## Workflow + +``` +Step 1: 路由 & 读取知识 + - 读对应 scene 指南 — 了解结构特征和布局策略 + - 确定布局策略（见下方快速判断）和构建方式 + - 读 references/ 核心模块 — 语法、布局、配色、排版、连线 + +Step 2: 生成完整 DSL（含颜色） + - 按 content.md 规划信息量和分组 + - 按 layout.md 选择布局模式和间距 + - 推荐使用图标让图表更直观，运行 `npx -y @larksuite/whiteboard-cli@^0.2.0 --icons` 查看可用图标 + - 按 style.md 上色（用户没指定时用默认经典色板） + - 按 schema.md 语法输出完整 JSON + - 连线参考 connectors.md，排版参考 typography.md + + 注意：部分图形（鱼骨/飞轮/柱状/折线等）要按 scene 指南的脚本模板写 CommonJS 脚本生成 JSON： + 1. 创建产物目录 ./diagrams/YYYY-MM-DDTHHMMSS/ + 2. 将脚本保存为 diagram.gen.cjs（必须 .cjs 后缀，脚本用 require() 写，.js 在 ESM 项目下会崩），执行 node diagram.gen.cjs 产出 diagram.json + 3. 用产出的 diagram.json 进入 Step 3 + +Step 3: 渲染 & 审查 → 交付 + - 渲染前自查（见下方检查清单） + - 渲染 PNG（仅用于预览验证，不是最终产物）：npx -y @larksuite/whiteboard-cli@^0.2.0 -i diagram.json -o diagram.png + - 检查：信息完整？布局合理？配色协调？文字无截断？连线无交叉？ + - 有问题 → 按症状表修复 → 重新渲染（最多 2 轮） + - 2 轮后仍有严重问题 → 考虑走 Mermaid 路径兜底 + - 写入画板：用 whiteboard-cli 将 diagram.json 转换为 OpenAPI 格式并 pipe 给 +update： + npx -y @larksuite/whiteboard-cli@^0.2.0 -i diagram.json --to openapi --format json \ + | lark-cli whiteboard +update --whiteboard-token \ + --source - --input_format raw --idempotent-token <时间戳+标识> --yes --as user + → 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板) + - 交付：向用户报告 board_token 写入成功 +``` + +**布局策略快速判断**（详见 `references/layout.md`）： + +先定**主布局**，再定子布局：**结构化信息**优先用 Flex，**关系链路**优先用 Dagre，**灵活定位**用绝对布局。 + +> **构建方式是强约束**：当 scene 指南要求"脚本生成"时，必须先写脚本（`.cjs`，CommonJS）并用 `node` 执行来产出 JSON 文件。 + +## 模块索引 + +### 核心参考（必读） + +| 模块 | 文件 | 说明 | +| -------- | -------------------------- | ------------------------------- | +| DSL 语法 | `references/schema.md` | 节点类型、属性、尺寸值 | +| 内容规划 | `references/content.md` | 信息提取、密度决策、连线预判 | +| 布局系统 | `references/layout.md` | 网格方法论、Flex 映射、间距规则 | +| 排版规则 | `references/typography.md` | 字号层级、对齐、行距 | +| 连线系统 | `references/connectors.md` | 拓扑规划、锚点选择 | +| 配色系统 | `references/style.md` | 多色板、视觉层级 | + +### 场景指南（按类型选读一个） + +| 图表类型 | 文件 | 适用场景 | +| ----------- | ------------------------ | -------------------------------------- | +| 架构图 | `scenes/architecture.md` | 分层架构、微服务架构 | +| 组织架构图 | `scenes/organization.md` | 公司组织、树形层级 | +| 泳道图 | `scenes/swimlane.md` | 跨角色流程、跨系统交互流程 | +| 对比图 | `scenes/comparison.md` | 方案对比、功能矩阵 | +| 鱼骨图 | `scenes/fishbone.md` | 因果分析、根因分析 | +| 柱状图 | `scenes/bar-chart.md` | 柱状图、条形图 | +| 折线图 | `scenes/line-chart.md` | 折线图、趋势图 | +| 树状图 | `scenes/treemap.md` | 矩形树图、层级占比 | +| 漏斗图 | `scenes/funnel.md` | 转化漏斗、销售漏斗 | +| 金字塔图 | `scenes/pyramid.md` | 层级结构、需求层次 | +| 循环/飞轮图 | `scenes/flywheel.md` | 增长飞轮、闭环链路 | +| 里程碑 | `scenes/milestone.md` | 时间线、版本演进 | +| 流程图 | `scenes/flowchart.md` | 业务流、状态机、带条件判断的链路 | + +## 渲染前自查 + +- [ ] 不同分组用了不同颜色？同组节点样式完全一致？ +- [ ] 外层浅色背景、内层白色节点？ +- [ ] 所有节点有边框（borderWidth=2）？文字在背景上清晰可读？ +- [ ] 连线用灰色（#BBBFC4），不用彩色？ +- [ ] frame 都写了 layout 属性？gap 和 padding 都显式设置了？ +- [ ] 含文字节点 height 用 fit-content？connector 在顶层 nodes 数组？ + +## 症状→修复表 + +| 看到的问题 | 改什么 | +| ------------------ | ----------------------------------- | +| 文字被截断 | height 改为 fit-content | +| 文字溢出容器右侧 | 增大 width，或缩短文字 | +| 节点重叠粘连 | 增大 gap | +| 节点挤成一团 | 增大 padding 和 gap | +| 连线穿过节点 | 调整 fromAnchor/toAnchor 或增大间距 | +| 大面积空白 | 缩小外层 frame 宽度 | +| 文字和背景色太接近 | 调整 fillColor 或 textColor | +| 布局整体偏左/偏右 | 调整绝对定位的 x 坐标使内容居中 | + +## 关键约束速查 + +1. **含文字节点的 height 必须用 `'fit-content'`** — 写死数值会截断文字 +2. **`fill-container` 仅在 flex 父容器中生效** — `layout: 'none'` 下宽度退化为 0 +3. **`layout: 'none'` 的容器必须有固定宽高** — 不要写成 `fit-content` +4. **connector 必须放在顶层 nodes 数组** — 不能嵌套在 frame children 里 +5. **flex 容器内的 x/y 会被完全忽略** — 需要自由定位时用 `layout: 'none'` +6. **Dagre 子容器默认为不透明节点** — 需穿透时声明 `layout: "dagre"` + `layoutOptions: { isCluster: true }` diff --git a/skills/lark-whiteboard/routes/mermaid.md b/skills/lark-whiteboard/routes/mermaid.md new file mode 100644 index 000000000..1dfa4810d --- /dev/null +++ b/skills/lark-whiteboard/routes/mermaid.md @@ -0,0 +1,27 @@ +# Mermaid 路径 + +适用于：思维导图、时序图、类图、饼图、甘特图。 + +## Workflow + +``` +Step 1: 读取知识 + - 读 scenes/mermaid.md — Mermaid 语法和使用方式 + +Step 2: 生成 Mermaid + - 按 mermaid.md 的语法编写 .mmd 文件 + - 只输出纯 Mermaid 语法文本 + +Step 3: 渲染验证 & 写入画板 & 交付 + 1. 创建产物目录 ./diagrams/YYYY-MM-DDTHHMMSS/ + 2. 保存为 diagram.mmd + 3. 渲染（仅用于预览验证，PNG 不是最终产物）： + npx -y @larksuite/whiteboard-cli@^0.2.0 -i diagram.mmd -o diagram.png + 4. 审查 PNG，有问题修改后重新渲染（最多 2 轮） + 5. 写入画板：用 whiteboard-cli 将 diagram.mmd 转换为 OpenAPI 格式并 pipe 给 +update： + npx -y @larksuite/whiteboard-cli@^0.2.0 -i diagram.mmd --to openapi --format json \ + | lark-cli whiteboard +update --whiteboard-token \ + --source - --input_format raw --idempotent-token <时间戳+标识> --yes --as user + → 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板) + 6. 交付：向用户报告 board_token 写入成功 +``` diff --git a/skills/lark-whiteboard/routes/svg.md b/skills/lark-whiteboard/routes/svg.md new file mode 100644 index 000000000..2f3c2b144 --- /dev/null +++ b/skills/lark-whiteboard/routes/svg.md @@ -0,0 +1,53 @@ +# SVG 路径 + +你在设计一张专业的信息图——内容扎实, 美观漂亮, 具有设计感和视觉张力, 不是枯燥的布局和文字堆砌, **不要做的像普通的网页或者千篇一律的模版** +最终交付是**画板跨越重排渲染的节点**(你写 SVG → 画板解析) + +**核心心智纠正 (重要)**： +- 大多数 AI 如果只考虑“绝对不报错/完美映射”, 最终给出的都是全篇纯白底色加单层 `` 的方正卡片网格, 极其死板单调, **这将被视为不及格！** +- **SVG 给你了完全的设计自由**, 请大胆使用你脑内的图标路径 (``), 连接指引 (`流畅的 `), 各种环境氛围点缀, 大胆一点, 充分信任你的品味, 发挥出你的顶级艺术创造力！ + +## Workflow + +### 1. 想清楚要画什么 + +- **核心信息是什么？** 能做到一图胜千言, 绝对不要只生成平平无奇的文字表格, 要有设计感 +- **内容充实度**：如果用户描述稀疏简略, 利用你的领域知识扩展, 保证信息维度和内容充实, 但不要过度堆砌, 淹没重点 +- **视觉层级与隐喻**：这个没有固定的形式, 你自由判断, 比如: 给重要的节点加光环, 加高亮背景；给对比项设计天平或对称结构 + +### 2. 写 SVG + +[!IMPORTANT] 布局, 配色, 信息密度, 装饰物——**全部由你判断**, 打破单调的 `` 牢笼, 严禁通篇用矩形和文字应付用户 + +操作边界约束： +- **语言跟随用户**：图表文字的语言与用户 prompt 保持一致, 技术术语用行业里通用的写法, 不机械翻译 +- 文字用 ``(不是 ``), 容器宽度留够——画板按 CJK ≈ 1em / Latin ≈ 0.6em 重排 +- 连线使用正交折线替代斜直线(`` 带水平/垂直折点)视觉效果更好 +- 可自由使用 `translate`, `rotate`, `scale`但请尽量避免使用 `skewX` / `skewY` / `matrix(...)` 发生空间级扭曲 + +### 3. 渲染审查 + +``` +建目录 ./diagrams/YYYY-MM-DDTHHMMSS/ (例：./diagrams/2026-04-15T143022/) +写文件 /diagram.svg +渲染 npx -y @larksuite/whiteboard-cli@^0.2.0 -i /diagram.svg -o /diagram.png -f svg +检查 npx -y @larksuite/whiteboard-cli@^0.2.0 -i /diagram.svg -f svg --check +导出 npx -y @larksuite/whiteboard-cli@^0.2.0 -i /diagram.svg -f svg --to openapi --format json > /diagram.json +``` + +`npx -y @larksuite/whiteboard-cli@^0.2.0 --check` 检测 `text-overflow` 和 `node-overlap`, 并结合视觉效果(查看 PNG)进行调整 + +## 画板怎么处理 SVG + +画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示), **不需要所有元素都可编辑, 一定要兼顾可编辑和美观漂亮** + +**可识别的元素** + +- 形状：`` / `` / `` / `` +- 连线：`` / `` / ``(自动识别为直线 / 折线 / 曲线) +- 文本：`` / `` 画板硬编码 Noto Sans SC **文字必须用 ``** +- 分组：`` / `` / `` 引用 `` +- 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级 + +**装饰特性** +- `` / `` / `` / `` / `` → 画板通过图片路径保留视觉 (光晕/阴影/纹理/遮罩等效果都在, 元素不可再编辑但不丢视觉) diff --git a/skills/lark-whiteboard-cli/scenes/architecture.md b/skills/lark-whiteboard/scenes/architecture.md similarity index 100% rename from skills/lark-whiteboard-cli/scenes/architecture.md rename to skills/lark-whiteboard/scenes/architecture.md diff --git a/skills/lark-whiteboard-cli/scenes/bar-chart.md b/skills/lark-whiteboard/scenes/bar-chart.md similarity index 95% rename from skills/lark-whiteboard-cli/scenes/bar-chart.md rename to skills/lark-whiteboard/scenes/bar-chart.md index e0bb8ee2c..6bebbc72e 100644 --- a/skills/lark-whiteboard-cli/scenes/bar-chart.md +++ b/skills/lark-whiteboard/scenes/bar-chart.md @@ -8,7 +8,7 @@ ## Layout 选型 -- **脚本生成坐标**（推荐）：用 .js 脚本计算柱体位置和高度，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染 +- **脚本生成坐标**（推荐）：用 .cjs 脚本计算柱体位置和高度，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染 - **绝对定位手写**：简单柱状图（≤ 5 个柱）可手写坐标 ## Layout 规则 @@ -179,3 +179,9 @@ - 柱体间距不均匀（脚本需统一计算 barGap） - Y 轴刻度线和格线误带箭头 - 坐标轴忘记带箭头 + +此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `data` 数组，其余坐标与柱体高度全自动计算。 + +```javascript +const { writeFileSync } = require('fs'); +``` diff --git a/skills/lark-whiteboard-cli/scenes/comparison.md b/skills/lark-whiteboard/scenes/comparison.md similarity index 100% rename from skills/lark-whiteboard-cli/scenes/comparison.md rename to skills/lark-whiteboard/scenes/comparison.md diff --git a/skills/lark-whiteboard-cli/scenes/fishbone.md b/skills/lark-whiteboard/scenes/fishbone.md similarity index 98% rename from skills/lark-whiteboard-cli/scenes/fishbone.md rename to skills/lark-whiteboard/scenes/fishbone.md index 839d7a2c2..3d3b04000 100644 --- a/skills/lark-whiteboard-cli/scenes/fishbone.md +++ b/skills/lark-whiteboard/scenes/fishbone.md @@ -10,7 +10,7 @@ ## Layout 选型 -- **脚本生成坐标**（必须）：用 .js 脚本通过三角函数计算鱼骨坐标，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染 +- **脚本生成坐标**（必须）：用 .cjs 脚本通过三角函数计算鱼骨坐标，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染 ## Layout 规则 diff --git a/skills/lark-whiteboard-cli/scenes/flowchart.md b/skills/lark-whiteboard/scenes/flowchart.md similarity index 100% rename from skills/lark-whiteboard-cli/scenes/flowchart.md rename to skills/lark-whiteboard/scenes/flowchart.md diff --git a/skills/lark-whiteboard-cli/scenes/flywheel.md b/skills/lark-whiteboard/scenes/flywheel.md similarity index 96% rename from skills/lark-whiteboard-cli/scenes/flywheel.md rename to skills/lark-whiteboard/scenes/flywheel.md index 59b4d2d02..14c5ef929 100644 --- a/skills/lark-whiteboard-cli/scenes/flywheel.md +++ b/skills/lark-whiteboard/scenes/flywheel.md @@ -9,7 +9,7 @@ ## Layout 选型 -- **脚本生成坐标**（必须）：用 .js 脚本极坐标计算阶段标签位置、SVG 圆环切割，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染 +- **脚本生成坐标**（必须）：用 .cjs 脚本极坐标计算阶段标签位置、SVG 圆环切割，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染 ## Layout 规则 @@ -51,7 +51,7 @@ nodes 数组中的图层顺序（必须严格遵守）： ## 骨架示例 -此场景必须用 .js 脚本生成。Agent 使用时只需修改 `stages` 数组和 `centerTitle`/`centerSubtitle`，其余坐标全自动计算。 +此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `stages` 数组和 `centerTitle`/`centerSubtitle`，其余坐标全自动计算。 ```javascript const { writeFileSync } = require('fs'); diff --git a/skills/lark-whiteboard-cli/scenes/funnel.md b/skills/lark-whiteboard/scenes/funnel.md similarity index 98% rename from skills/lark-whiteboard-cli/scenes/funnel.md rename to skills/lark-whiteboard/scenes/funnel.md index 2aeaa457d..1f59fe3d3 100644 --- a/skills/lark-whiteboard-cli/scenes/funnel.md +++ b/skills/lark-whiteboard/scenes/funnel.md @@ -26,10 +26,10 @@ ## 脚本构建模板 -必须使用 `node` 运行脚本生成 JSON。 +此场景必须用 .cjs 脚本生成。 ```javascript -import fs from 'fs'; +const fs = require('fs'); // 1. 配置基础参数 const GAP = 4; diff --git a/skills/lark-whiteboard-cli/scenes/line-chart.md b/skills/lark-whiteboard/scenes/line-chart.md similarity index 96% rename from skills/lark-whiteboard-cli/scenes/line-chart.md rename to skills/lark-whiteboard/scenes/line-chart.md index 733dd21c1..ceacfbc41 100644 --- a/skills/lark-whiteboard-cli/scenes/line-chart.md +++ b/skills/lark-whiteboard/scenes/line-chart.md @@ -8,7 +8,7 @@ ## Layout 选型 -- **脚本生成坐标**（推荐）：用 .js 脚本计算数据点坐标和折线路径，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染 +- **脚本生成坐标**（推荐）：用 .cjs 脚本计算数据点坐标和折线路径，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染 ## Layout 规则 @@ -206,3 +206,9 @@ - 数据点太密时标注互相遮挡（超过 10 个点考虑隔一个标注一次） - 折线段忘记设 endArrow: "none"，默认带箭头 - 多系列时折线颜色相近难以区分，应使用对比度高的不同色系 + +此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `data` 数组，其余坐标与折线生成全自动计算。 + +```javascript +const { writeFileSync } = require('fs'); +``` diff --git a/skills/lark-whiteboard-cli/scenes/mermaid.md b/skills/lark-whiteboard/scenes/mermaid.md similarity index 96% rename from skills/lark-whiteboard-cli/scenes/mermaid.md rename to skills/lark-whiteboard/scenes/mermaid.md index be252a8bd..821a841be 100644 --- a/skills/lark-whiteboard-cli/scenes/mermaid.md +++ b/skills/lark-whiteboard/scenes/mermaid.md @@ -16,12 +16,6 @@ - 用户直接粘贴了 Mermaid 语法文本 - 图表类型为思维导图、时序图、类图、饼图（自动路由） -## CLI 用法 - -```bash -npx -y @larksuite/whiteboard-cli@^0.2.0 -i ./diagrams/{name}.mmd -o ./diagrams/{name}.png -``` - ## 思维导图 (Mindmap) ```mermaid diff --git a/skills/lark-whiteboard-cli/scenes/milestone.md b/skills/lark-whiteboard/scenes/milestone.md similarity index 100% rename from skills/lark-whiteboard-cli/scenes/milestone.md rename to skills/lark-whiteboard/scenes/milestone.md diff --git a/skills/lark-whiteboard-cli/scenes/organization.md b/skills/lark-whiteboard/scenes/organization.md similarity index 99% rename from skills/lark-whiteboard-cli/scenes/organization.md rename to skills/lark-whiteboard/scenes/organization.md index c0ca2b457..5e1d0ceca 100644 --- a/skills/lark-whiteboard-cli/scenes/organization.md +++ b/skills/lark-whiteboard/scenes/organization.md @@ -159,9 +159,7 @@ { "type": "connector", "connector": { "from": "child-b", "to": "leaf-b1", "fromAnchor": "bottom", "toAnchor": "top", "lineShape": "rightAngle", "lineWidth": 2 } }, { "type": "connector", "connector": { "from": "child-b", "to": "leaf-b2", "fromAnchor": "bottom", "toAnchor": "top", "lineShape": "rightAngle", "lineWidth": 2 } } ] -}; - -fs.writeFileSync('diagram.json', JSON.stringify(doc, null, 2)); +} ``` ## 陷阱 diff --git a/skills/lark-whiteboard-cli/scenes/pyramid.md b/skills/lark-whiteboard/scenes/pyramid.md similarity index 99% rename from skills/lark-whiteboard-cli/scenes/pyramid.md rename to skills/lark-whiteboard/scenes/pyramid.md index cd0ece18d..906b85c1c 100644 --- a/skills/lark-whiteboard-cli/scenes/pyramid.md +++ b/skills/lark-whiteboard/scenes/pyramid.md @@ -29,7 +29,7 @@ vertical frame + 每层宽度递减。gap 4px 保持紧密。 必须使用 `node` 运行脚本生成 JSON。 ```javascript -import fs from 'fs'; +const fs = require('fs'); // 1. 配置基础参数 const GAP = 4; diff --git a/skills/lark-whiteboard-cli/scenes/swimlane.md b/skills/lark-whiteboard/scenes/swimlane.md similarity index 93% rename from skills/lark-whiteboard-cli/scenes/swimlane.md rename to skills/lark-whiteboard/scenes/swimlane.md index efcebd762..2d8fd75d6 100644 --- a/skills/lark-whiteboard-cli/scenes/swimlane.md +++ b/skills/lark-whiteboard/scenes/swimlane.md @@ -27,9 +27,9 @@ 1. **网格对齐是第一优先级**：跨泳道同一阶段必须严格对齐（水平对齐 x；垂直对齐 y）。对齐通过“共享阶段标尺（stage ruler / stage slots）”实现，不靠肉眼估算，也不靠逐节点随意手写坐标 2. **只生成真实节点**：为保证跨泳道阶段严格对齐，所有阶段统一保留透明的 **stage cell**；仅在真实阶段的 cell 内生成卡片节点，并按阶段索引映射到对应槽位 -3. **泳道容器禁止使用背景色**：每条泳道是一个可见的分组容器，只能使用边框表达分组（建议统一使用浅灰色细虚线 `borderDash: "dashed"`，`borderWidth: 1`，`borderColor: "#DEE0E3"`），**不得使用任何有色背景作为泳道底色**，以降低视觉噪音。必须显式声明 `fillColor: "transparent"`，保持视觉透明 +3. **泳道底色**：为了增强层级感同时保持界面整洁，**强烈建议所有泳道容器统一使用极浅灰色背景**（如 `fillColor: "#F8F9FA"` 或 `"#FCFCFC"`）。边框使用浅灰色细虚线（`borderDash: "dashed"`, `borderWidth: 1`, `borderColor: "#DEE0E3"`）以明确边界。 4. **步骤卡片**：使用 `rect`。为建立清晰的视觉层级，卡片**必须填充浅色背景**（参考 `references/style.md` 中的浅色板，如极浅的主题色），边框使用对应的主题主色（`borderWidth: 1-2`），文字使用深色（如 `#1F2329`）以确保可读性。统一圆角；宽高以可读为先，避免过窄导致换行过多 -5. **间距**：只要存在 connector 连线，卡片之间的主轴间距必须满足 `gap >= 40`；如果连线包含文字（`label`），主轴间距必须 `gap >= 64`，以提供充足的阅读空间。 +5. **间距**：只要存在 connector 连线，卡片之间的主轴间距必须满足 `gap >= 40` ### 子节点对齐 @@ -51,7 +51,7 @@ ### 跨泳道间距（lanesGap） - 根容器承载所有泳道：水平泳道用 `layout: "vertical"`，垂直泳道用 `layout: "horizontal"` -- 固定跨泳道主轴间距 `lanesGap`（建议 `64-80`），更宽的间距能让跨泳道连线（特别是带文字时）有更多留白，降低重叠感 +- 缩减跨泳道主轴间距 `lanesGap`（建议 `16-24`），以保持整体图表的紧凑性。避免 `lanesGap` 设置为 `0` 导致边框重叠变粗，也避免间距过大导致视觉涣散。 - 每条泳道作为根容器的子 frame，内部再使用上述 Flex 栅格的 stage cell 布局 - `lanesGap` 与 `lanePadding/stackGap` 独立；lane 内容增减不应影响跨泳道间距 - 4px 基线对齐：`lanesGap`、`lanePadding`、cell 尺寸建议按 4 的倍数对齐 @@ -72,7 +72,7 @@ - lane body：`layout: "vertical"`，包含完整的阶段 **stage cell** 数组；cell 高度固定为 `slotHeight`，相邻 cell 间 `gap` 统一；空阶段 cell 透明但保留 - 内容居中对齐：stage cell 建议 `alignItems: "center"` + `justifyContent: "center"`，让卡片在每个 cell 内水平/垂直居中；卡片宽度不超过 `slotWidth`（或固定宽度），避免被 `"fill-container"` 拉伸导致“看起来不居中” - 步骤卡片：推荐统一卡片高度或统一 `slotHeight / gap`，保证跨泳道阶段严格 y 对齐 -- 泳道外层容器必须显式写 `fillColor: "transparent"`、`borderDash: "dashed"`、`borderWidth: 1`、`borderColor: "#DEE0E3"`（统一浅灰色），否则会被编译为虚拟 frame 导致不渲染 +- 泳道外层容器必须显式写 `fillColor: "#F8F9FA"`（极浅灰）、`borderDash: "dashed"`、`borderWidth: 1`、`borderColor: "#DEE0E3"`（统一浅灰色），否则会被编译为虚拟 frame 导致不渲染 - 统一高度（Flex 自适应，可选）：根容器使用 `alignItems: "stretch"`，每个泳道外层 frame 使用 `height: "fill-container"`；泳道内部仍保持 lane label + lane body 的结构 示例： @@ -86,7 +86,7 @@ "id": "lanes-root", "x": 40, "y": 40, "layout": "horizontal", - "gap": 64, + "gap": 16, "alignItems": "stretch", "children": [ { @@ -95,7 +95,7 @@ "layout": "vertical", "width": "fit-content", "height": "fill-container", - "fillColor": "transparent", + "fillColor": "#F8F9FA", "borderDash": "dashed", "borderWidth": 1, "borderColor": "#DEE0E3", @@ -106,7 +106,7 @@ "textAlign": "center", "verticalAlign": "middle", "fontSize": 18, "fontWeight": "bold", "textColor": "#5178C6" } ] }, { "type": "frame", "id": "lane-left-body", "layout": "vertical", - "gap": 64, "padding": 16, + "gap": 40, "padding": 16, "children": [ { "type": "frame", "id": "stage-1-cell-left", "layout": "vertical", "width": 220, "height": 80, "alignItems": "center", "justifyContent": "center", "children": [{ "type": "rect", "id": "c-s1", "width": 200, "height": "fit-content", "fillColor": "#E1EAFA", "borderColor": "#5178C6", "borderWidth": 2, "borderRadius": 8 }] }, @@ -120,7 +120,7 @@ "layout": "vertical", "width": "fit-content", "height": "fill-container", - "fillColor": "transparent", + "fillColor": "#F8F9FA", "borderDash": "dashed", "borderWidth": 1, "borderColor": "#DEE0E3", @@ -131,7 +131,7 @@ "textAlign": "center", "verticalAlign": "middle", "fontSize": 18, "fontWeight": "bold", "textColor": "#8569CB" } ] }, { "type": "frame", "id": "lane-right-body", "layout": "vertical", - "gap": 64, "padding": 16, + "gap": 40, "padding": 16, "children": [ { "type": "frame", "id": "stage-1-cell-right", "layout": "vertical", "width": 220, "height": 80, "alignItems": "center", "justifyContent": "center", "children": [] }, { "type": "frame", "id": "stage-2-cell-right", "layout": "vertical", "width": 220, "height": 80, "alignItems": "center", "justifyContent": "center", @@ -142,13 +142,14 @@ ] }, { "type": "connector", "connector": { "from": "c-s1", "to": "d-s2", - "lineShape": "polyline", "lineColor": "#BBBFC4", "lineWidth": 2, "endArrow": "arrow" } } + "lineShape": "polyline", "lineColor": "#BBBFC4", "lineWidth": 2, "endArrow": "arrow" } } ] } ``` ### 泳道配色（默认色板） +- **泳道背景**：所有泳道容器统一使用极浅灰色（如 `fillColor: "#F8F9FA"` 或 `"#FCFCFC"`），以增强物理容器的层级感，并突出内部的彩色卡片。 - **泳道边框**：所有泳道外层容器统一使用浅灰色细虚线（`borderColor: "#DEE0E3"`, `borderWidth: 1`, `borderDash: "dashed"`）。 - **泳道标题**：按 `references/style.md` 经典色板为每条泳道分配不同的主题色，泳道 title 的 `textColor` 使用该主题色。 - **内容节点（rect）**：采用“浅色底 + 主题色边框”策略。`fillColor` 使用与该泳道主题色对应的极浅色（如浅蓝、浅紫等），`borderColor` 使用对应的主题色，文字 `textColor` 统一使用深色 `#1F2329`。 @@ -188,7 +189,7 @@ "x": 40, "y": 40, "layout": "vertical", - "gap": 64, + "gap": 16, "alignItems": "stretch", "padding": 0, "width": "fit-content", @@ -198,11 +199,11 @@ "type": "frame", "id": "lane-a", "layout": "horizontal", - "gap": 64, + "gap": 40, "padding": 16, "width": "fit-content", "height": "fill-container", - "fillColor": "transparent", + "fillColor": "#F8F9FA", "borderDash": "dashed", "borderWidth": 1, "borderColor": "#DEE0E3", @@ -267,11 +268,11 @@ "type": "frame", "id": "lane-b", "layout": "horizontal", - "gap": 64, + "gap": 40, "padding": 16, "width": "fit-content", "height": "fill-container", - "fillColor": "transparent", + "fillColor": "#F8F9FA", "borderDash": "dashed", "borderWidth": 1, "borderColor": "#DEE0E3", diff --git a/skills/lark-whiteboard-cli/scenes/treemap.md b/skills/lark-whiteboard/scenes/treemap.md similarity index 94% rename from skills/lark-whiteboard-cli/scenes/treemap.md rename to skills/lark-whiteboard/scenes/treemap.md index a6d2a76a3..32c98e2a2 100644 --- a/skills/lark-whiteboard-cli/scenes/treemap.md +++ b/skills/lark-whiteboard/scenes/treemap.md @@ -8,7 +8,7 @@ ## Layout 选型 -- **脚本生成坐标**（推荐）：Treemap 需要精确的面积比例计算，用 .js 脚本递归切分矩形，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染 +- **脚本生成坐标**（推荐）：Treemap 需要精确的面积比例计算，用 .cjs 脚本递归切分矩形，脚本输出 JSON 文件后调用 `npx -y @larksuite/whiteboard-cli@^0.2.0` 渲染 - 不适合手动心算坐标 ## Layout 规则 @@ -208,3 +208,9 @@ - **分类标签不可见**：分类标签 text 节点必须在其子矩形 rect 节点之前添加（z-index 靠后的节点在上层） - **面积比例不正确**：必须用脚本预先计算比例，不要心算 - **缺少配色区分**：不同顶层分类必须用不同背景色（从色板选取），所有子节点继承对应色系 + +此场景必须用 .cjs 脚本生成。Agent 使用时只需修改 `data` 树，其余坐标与矩形面积自动递归计算。 + +```javascript +const { writeFileSync } = require('fs'); +```