@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/lark-tools/cli-skills/lark-vc/references/lark-vc-search.md

@@ -0,0 +1,159 @@
+
+# vc +search
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+搜索已结束的历史会议记录，支持关键词、时间范围、组织者、参与者以及会议室等多条件过滤。只读操作，不修改任何会议数据。
+
+本 skill 对应 shortcut：`lark-cli vc +search`（调用 `POST /open-apis/vc/v1/meetings/search`）。
+
+## 典型触发表达
+
+以下说法通常应优先使用 `vc +search`：
+
+- 今天开过的会
+- 今天开了哪些会
+- 最近参加过哪些会
+- 我这周开过的会
+- 已结束的会议
+- 历史会议记录
+
+## 命令
+
+```bash
+# 关键词搜索
+lark-cli vc +search --query "周会"
+
+# 查询某一天开过的会（单日查询时，start 和 end 必须填写同一天）
+lark-cli vc +search --start 2026-03-10 --end 2026-03-10
+
+# 按时间范围搜索
+lark-cli vc +search --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
+lark-cli vc +search --start 2026-03-10 --end 2026-03-17
+
+# 关键词 + 时间范围
+lark-cli vc +search --query "周会" --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
+lark-cli vc +search --query "周会" --start "2026-03-10T00:00+08:00"
+lark-cli vc +search --query "周会" --end "2026-03-17T00:00+08:00"
+
+# 按组织者过滤（open_id，逗号分隔）
+lark-cli vc +search --organizer-ids "ou_a,ou_b"
+
+# 按参与者过滤（open_id，逗号分隔）
+lark-cli vc +search --participant-ids "ou_x,ou_y"
+
+# 按会议室过滤
+lark-cli vc +search --room-ids "123,456"
+
+# 多条件组合查询
+lark-cli vc +search --organizer-ids "ou_a" --room-ids "123" --start "2026-03-10T00:00+08:00"
+
+# 分页查询
+lark-cli vc +search --query "周会" --page-size 15
+lark-cli vc +search --query "周会" --page-token "next_page_token"
+
+# 输出为表格/可读格式
+lark-cli vc +search --query "周会" --format json
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--query <text>` | 否 | 搜索关键词 |
+| `--start <time>` | 否 | 开始时间（ISO 8601 或仅日期） |
+| `--end <time>` | 否 | 结束时间（ISO 8601 或仅日期） |
+| `--organizer-ids <ids>` | 否 | 组织者 open_id 列表，逗号分隔 |
+| `--participant-ids <ids>` | 否 | 参与者 open_id 列表，逗号分隔 |
+| `--room-ids <ids>` | 否 | 会议室 ID 列表，逗号分隔 |
+| `--page-size <n>` | 否 | 每页数量，默认 `15`，最大 `30` |
+| `--page-token <token>` | 否 | 翻页标记，用于获取下一页 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 至少提供一个过滤条件
+
+所有参数均可选，但必须至少提供一个过滤条件：`--query`、`--start`、`--end`、`--organizer-ids`、`--participant-ids` 或 `--room-ids`。
+
+### 2. 仅搜索历史会议
+
+`vc +search` 只能搜索已结束的历史会议记录，不用于查询未来日程。查询未来会议安排请使用 [lark-calendar](../../lark-calendar/SKILL.md)。
+
+### 3. 仅支持 user 身份
+
+该接口仅支持 `user` 身份，使用前需完成 `lark-cli auth login` 并具备 `vc:meeting.search:read` 权限。
+
+### 4. 支持分页
+
+当返回 `has_more=true` 时，使用响应中的 `page_token` 配合 `--page-token` 获取下一页结果。
+
+### 5. 日期型 `--end` 包含当天整天
+
+当 `--end` 传入的是仅日期格式（如 `2026-03-10`）时，CLI 会将它解释为当天 `23:59:59`，而不是当天 `00:00:00`。
+
+这意味着：
+
+- `--start 2026-03-10 --end 2026-03-10` 表示只查 `2026-03-10` 当天
+- `--start 2026-03-10 --end 2026-03-11` 表示查询 `2026-03-10` 和 `2026-03-11` 两天
+
+如果用户说“昨天开过的会”“今天开过的会”“某一天开过的会”，应把 `--start` 和 `--end` 都设置为同一天，而不是把 `--end` 设成下一天。
+
+## 时间格式
+
+`--start` 和 `--end` 支持以下时间格式：
+
+| 格式 | 示例 | 说明 |
+|------|------|------|
+| ISO 8601（带时区） | `2026-03-10T14:00:00+08:00` | 推荐 |
+| ISO 8601（不带时区） | `2026-03-10T14:00:00` | 按本地时区解析 |
+| 仅日期 | `2026-03-10` | 按天粒度解析；若用于 `--end`，表示当天 `23:59:59` |
+
+## 输出结果
+
+- 默认输出 JSON，包含 `items`、`total`、`has_more` 和 `page_token`。
+
+## Pagination (`has_more` / `page_token`)
+
+- 当结果中返回 `has_more=true` 时，说明还有更多页可继续获取。
+- 继续翻页时，使用响应中的 `page_token` 搭配 `--page-token` 发起下一次查询。
+- 不要假设调大 `--page-size` 就能拿全结果；分页遍历时应以 `has_more` 和 `page_token` 为准。
+- `total` 数量小于 50 时，自动分页获取所有结果；`total` 数量大于 50 时，向用户确认是否获取全部结果。
+
+```bash
+# First page
+lark-cli vc +search --query "周会" --page-size 15
+
+# Next page
+lark-cli vc +search --query "周会" --page-size 15 --page-token "<PAGE_TOKEN>"
+```
+
+## 搜索结果中的下一步
+
+搜索结果中的 `meeting_id` 可直接用于继续查询会议纪要：
+
+```bash
+# 根据 meeting_id 获取会议纪要
+lark-cli vc +notes --meeting-ids <MEETING_ID>
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| 命令直接报错，要求提供过滤条件 | 没有传入 `--query`、时间范围或任何过滤 ID | 至少补充一个过滤条件后重试 |
+| 时间参数校验失败 | `--start` 或 `--end` 格式不合法 | 改用 ISO 8601 或 `YYYY-MM-DD` |
+| 搜不到未来会议 | `vc +search` 只查历史会议 | 改用 [lark-calendar](../../lark-calendar/SKILL.md) 查询未来日程 |
+| 权限不足 | 未授权 `vc:meeting.search:read` | 使用 `auth login` 完成授权 |
+
+## 提示
+- 必须使用 `--format json` 输出，你更佳擅长解析 JSON 数据。
+- 排查参数与请求结构时优先使用 `--dry-run`。
+- 搜索的时间范围最大为 1 个月，如果需要搜索更长时间范围的会议，需要拆分为多次时间范围为一个月查询。
+- 不要使用 `yesterday`、`today` 这类相对时间字面量；请先转换成明确日期，例如 `2026-03-10`。
+
+## 参考
+
+- [lark-vc](../SKILL.md) -- 视频会议全部命令
+- [lark-vc-notes](lark-vc-notes.md) -- 获取会议纪要
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-whiteboard/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: lark-whiteboard
+version: 1.0.0
+description: >
+  飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用 PlantUML/Mermaid 代码或 OpenAPI 原生格式更新画板内容。
+  当用户需要查看画板内容、导出画板图片、或编辑画板，或是需要可视化表达架构、流程、组织关系、时间线、因果、对比等结构化信息时使用此 skill，无论是否提及"画板"。
+metadata:
+  requires:
+    bins: [ "lark-cli" ]
+  cliHelp: "lark-cli whiteboard --help"
+---
+
+# whiteboard (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+## 核心概念
+
+### 画板 Token
+
+画板 token 是画板的唯一标识符。飞书画板嵌入在云文档中，可以从云文档的 `docs +fetch` 结果中获取（`<whiteboard token="xxx"/>`
+标签），或从 `docs +update` 新建画板后的 `data.board_tokens` 字段中获取。
+
+## 快速决策
+
+当需要插入图表时：
+
+1. 能否使用飞书画板？
+    - 能 → 走画板路径（推荐！可编辑、可协作）
+    - 不能 → 走图片路径
+
+| 用户需求                             | 推荐 Shortcut                                                                                                                                            |
+|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| "查看这个画板的内容"                      | [`+query --output_as image`](references/lark-whiteboard-query.md)                                                                                      |
+| "导出画板为图片"                        | [`+query --output_as image`](references/lark-whiteboard-query.md)                                                                                      |
+| "获取画板的 PlantUML/Mermaid 代码"      | [`+query --output_as code`](references/lark-whiteboard-query.md)                                                                                       |
+| "检查画板是否由 PlantUML/Mermaid 代码块组成" | [`+query --output_as code`](references/lark-whiteboard-query.md)                                                                                       |
+| "修改画板某个节点的颜色或文字"                 | [`+query --output_as raw`](references/lark-whiteboard-query.md) 后 [`+update`](references/lark-whiteboard-update.md)                                    |
+| "用 PlantUML 绘制画板"                | [`+update --input_format plantuml`](references/lark-whiteboard-update.md)                                                                              |
+| "用 Mermaid 绘制画板"                 | [`+update --input_format mermaid`](references/lark-whiteboard-update.md)                                                                               |
+| "在画板绘制复杂图表"                      | [`+update --input_format raw`](references/lark-whiteboard-update.md), 需要使用 whiteboard-cli 工具，参见 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) |
+
+## Shortcuts
+
+| 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 中解析 `<whiteboard token="xxx"/>` 标签，记录画板 token
+3. 使用本 skill 的 `+query` 或 `+update` 读取或操作画板
+
+### 场景 2: 新建画板并编辑（完整流程）
+
+这是最常见的使用场景，**必须完整执行以下步骤**：
+
+1. 使用 `lark-doc` 的 [`+update`](../lark-doc/references/lark-doc-update.md) 创建空白画板
+    - 在 markdown 中传入 `<whiteboard type="blank"></whiteboard>`
+    - **注意这一 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)         |

package/server/assets/skills/lark-tools/cli-skills/lark-whiteboard/references/lark-whiteboard-query.md

@@ -0,0 +1,49 @@
+# whiteboard +query（查询画板）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询画板内容，支持导出为预览图片、提取 PlantUML/Mermaid 代码，或获取飞书 OpenAPI 原生画板节点格式。
+
+## 参数
+
+| 参数                   | 必填 | 说明                                                                     |
+|----------------------|----|------------------------------------------------------------------------|
+| `--whiteboard-token` | 是  | 画板 token，需要拥有画板的读权限                                                    |
+| `--output_as`        | 是  | 输出格式：`image`（预览图片）、`code`（PlantUML/Mermaid 代码）、`raw`（OpenAPI 原生画板节点格式） |
+| `--output`           | 否  | 输出路径。当 `--output_as image` 时必填；当 `--output_as code/raw` 时可选，不填则直接输出到终端 |
+| `--overwrite`        | 否  | 覆盖已存在的文件，默认为 false                                                     |
+
+## 输出格式
+
+- `image`：预览图片
+- `code`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。
+- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [lark-whiteboard-cli](../lark-whiteboard-cli/SKILL.md) 。
+
+## 示例
+
+### 示例 1：导出画板为预览图片
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as image \
+  --output ./preview.png
+```
+
+### 示例 2：提取画板中的代码并直接输出
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as code
+```
+
+### 示例 3：导出画板原始节点结构到文件
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as raw \
+  --output ./nodes.json \
+  --overwrite
+```

package/server/assets/skills/lark-tools/cli-skills/lark-whiteboard/references/lark-whiteboard-update.md

@@ -0,0 +1,97 @@
+# whiteboard +update（更新画板）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新画板内容，支持三种输入格式：
+
+- `raw`：飞书 OpenAPI 原生画板节点格式，不推荐直接编辑。
+- `plantuml`：PlantUML 代码
+- `mermaid`：Mermaid 代码
+
+输入内容可以通过管道从 stdin 读取，或通过 `--source` 指定文件。
+
+## 参数
+
+| 参数                   | 必填 | 说明                                         |
+|----------------------|----|--------------------------------------------|
+| `--whiteboard-token` | 是  | 画板 token，需要拥有画板的编辑权限                       |
+| `--idempotent-token` | 否  | 幂等 token，确保更新操作幂等，最小长度 10 个字符              |
+| `--overwrite`        | 否  | 覆盖更新，在更新前删除所有现有内容，默认为 false                |
+| `--source`           | 是  | 输入画板内容，支持使用 `@path` 从文件读取，或 `-` 从 stdin 读取 |
+| `--input_format`     | 否  | 输入格式：`raw`、`plantuml`、`mermaid`，默认为 `raw`  |
+
+### 以 raw (OpenAPI 原生画板节点格式) 创作
+
+**不要以直接生成 json 语法的方式创作 raw 格式的飞书 OpenAPI 原生画板节点参数**
+
+思维导图，时序图，类图，饼图，流程图等图标推荐使用 Mermaid/PlantUML 语法绘制。
+
+而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [lark-whiteboard-cli](../lark-whiteboard-cli/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 --yes --as user
+```
+
+### 示例 2：使用 Mermaid 代码更新画板（从文件读取）
+
+```bash
+# 编写 Mermaid 代码
+cat > diagram.mmd << 'EOF'
+graph TD
+    A[开始] --&gt; B{判断}
+    B --&gt;|是| C[处理]
+    B --&gt;|否| D[结束]
+    C --&gt; D
+EOF
+
+# 从文件读取并更新
+lark-cli whiteboard +update \
+  --whiteboard-token <画板Token> \
+  --input_format mermaid \
+  --source @./diagram.mmd \
+  --overwrite --yes --as user
+```
+
+### 示例 3：使用 whiteboard-cli 直接使用画板 DSL 更新画板
+
+whiteboard-cli 工具的具体用法请参考 [../lark-whiteboard-cli/SKILL.md](../lark-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
+```
+
+### 示例 4：使用 whiteboard-cli 使用画板 DSL 生成 Raw 格式 Json，并使用其更新画板
+
+whiteboard-cli 工具的具体用法请参考 [../lark-whiteboard-cli/SKILL.md](../lark-whiteboard-cli/SKILL.md)
+
+```bash
+# 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
+npx -y @larksuite/whiteboard-cli@^0.1.0 --to openapi -i <画板 DSL> -o ./temp.json
+
+lark-cli whiteboard +update \
+  --whiteboard-token <画板Token> \
+  --input_format raw \
+  --source @./temp.json \
+  --overwrite --yes --as user
+```

package/server/assets/skills/lark-tools/cli-skills/lark-whiteboard-cli/SKILL.md

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