refactor(whiteboard): introduce lark-doc-whiteboard.md and streamline whiteboard workflow

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 中包含 `<whiteboard token="xxx"/>` 标签），请引导用户：
-1. 记录画板的 token
-2. 查看 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md) 了解如何编辑画板内容
-### 场景 2：刚创建画板，需要编辑
-如果用户刚通过 `docs +update` 创建了空白画板，需要编辑时：
-**步骤 1：按空白画板语法创建**
-- 在 `--markdown` 中直接传 `<whiteboard type="blank"></whiteboard>`
-- 需要多个空白画板时，在同一个 `--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 +<verb> [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. |

skills/lark-doc/references/lark-doc-create.md

@@ -57,9 +57,8 @@ lark-cli docs +create --title "学习笔记" --wiki-space my_library --markdown
 如果文档中包含空白画板（`<whiteboard type="blank"></whiteboard>`），**必须继续以下步骤**：
 
 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 type="blank"></whiteboard>` 占位，每个图表对应一个标签。**禁止**用 `whiteboard-cli` 渲染的 PNG/SVG 图片替代画板。创建完成后从返回值 `data.board_tokens` 取 token，读取 `../../lark-whiteboard/SKILL.md` 的"渲染 & 写入画板"章节为每个 token 写入图表内容。例：文档含"系统整体架构""分层架构""部署架构"各需插入一个画板，"类图"也需插入一个画板（走 Mermaid 路由）。
 
 当用户有明确的样式、风格需求时，应当以用户的需求为准！
 
@@ -450,7 +449,7 @@ lark-cli docs +create --title "空白画板示例" --markdown '<whiteboard type=
 **重要说明**：
 - 创建空白画板时，直接使用 `<whiteboard type="blank"></whiteboard>`
 - 读取时只能获取 token，可通过 media-download 查看内容，无法直接读出画板内部内容
-- 画板编辑：详见 [SKILL.md](../SKILL.md#重要说明画板编辑)
+- 画板编辑：详见 [../../lark-whiteboard/SKILL.md](../../lark-whiteboard/SKILL.md)
 
 ### 多维表格（Base）
 

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 type="blank"></whiteboard>`（不要转义）
+- 多个画板时，在相应的地方插入各自的 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)