refactor(dashboard): restructure docs for AI-friendly navigation

shortcuts/base/dashboard_block_create.go

@@ -23,7 +23,7 @@ var BaseDashboardBlockCreate = common.Shortcut{
 		baseTokenFlag(true),
 		dashboardIDFlag(true),
 		{Name: "name", Desc: "block name", Required: true},
-		{Name: "type", Desc: "block type: column / bar / line / pie / ring / area / combo / scatter / funnel / wordCloud / radar / statistics", Required: true},
+		{Name: "type", Desc: "block type: column(柱状图)|bar(条形图)|line(折线图)|pie(饼图)|ring(环形图)|area(面积图)|combo(组合图)|scatter(散点图)|funnel(漏斗图)|wordCloud(词云)|radar(雷达图)|statistics(指标卡). Read dashboard-block-data-config.md before creating.", Required: true},
 		{Name: "data-config", Desc: "data config JSON object (table_name, series, count_all, group_by, filter, etc.)"},
 		{Name: "user-id-type", Desc: "user ID type: open_id / union_id / user_id"},
 		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation"},

shortcuts/base/dashboard_block_update.go

@@ -24,7 +24,7 @@ var BaseDashboardBlockUpdate = common.Shortcut{
 		dashboardIDFlag(true),
 		blockIDFlag(true),
 		{Name: "name", Desc: "new block name"},
-		{Name: "data-config", Desc: "data config JSON object (table_name, series, count_all, group_by, filter, etc.)"},
+		{Name: "data-config", Desc: "data config JSON: table_name, series|count_all (mutually exclusive), group_by, filter. See dashboard-block-data-config.md for details."},
 		{Name: "user-id-type", Desc: "user ID type: open_id / union_id / user_id"},
 		{Name: "no-validate", Type: "bool", Desc: "skip local data_config validation"},
 	},

skills/lark-base/SKILL.md

@@ -96,6 +96,9 @@ metadata:
    - 先通过 `+table-list` / `+field-list` 获取真实的表名、字段名
    - 禁止凭自然语言猜测表名/字段名填入 workflow 配置
 
+## Dashboard（仪表盘/数据看板）模块
+**当用户提到 "仪表盘、dashboard、数据看板、图表、可视化、block、组件、添加组件、创建图表" 等仪表盘相关的关键词时，必须阅读** [lark-base-dashboard.md](references/lark-base-dashboard.md) 这个指引文档，了解仪表盘模块的命令和能力后再进行后续操作。
+
 ## 核心规则
 
 1. **只使用原子命令** — 使用 `+table-list / +table-get / +field-create / +record-upsert / +view-set-filter / +record-history-list / +base-get` 这类一命令一动作的写法，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace`
@@ -145,10 +148,7 @@ metadata:
 | 列表 / 获取表单 | `lark-cli base +form-list` / `+form-get` | 原子命令 |
 | 创建 / 更新 / 删除表单 | `lark-cli base +form-create` / `+form-update` / `+form-delete` | 一命令一动作 |
 | 列表 / 创建 / 更新 / 删除表单问题 | `lark-cli base +form-questions-list` / `+form-questions-create` / `+form-questions-update` / `+form-questions-delete` | 一命令一动作 |
-| 列表 / 获取仪表盘 | `lark-cli base +dashboard-list` / `+dashboard-get` | 原子命令 |
-| 创建 / 更新 / 删除仪表盘 | `lark-cli base +dashboard-create` / `+dashboard-update` / `+dashboard-delete` | 一命令一动作 |
-| 列表 / 获取仪表盘 Block | `lark-cli base +dashboard-block-list` / `+dashboard-block-get` | 原子命令 |
-| 创建 / 更新 / 删除仪表盘 Block | `lark-cli base +dashboard-block-create` / `+dashboard-block-update` / `+dashboard-block-delete` | 一命令一动作 |
+| 创建/管理仪表盘及图表 | `+dashboard-* / +dashboard-block-*` | **必须先读** [lark-base-dashboard.md](references/lark-base-dashboard.md) |
 
 
 ## 操作注意事项
@@ -166,7 +166,6 @@ metadata:
 - **`+base-create / +base-copy` 结果返回规范**：创建或复制成功后，回复中必须主动返回新 Base 的标识信息。若返回结果里带可访问链接（如 `base.url`），要一并返回
 - **`+base-create / +base-copy` 友好性规则**：`--folder-token`、`--time-zone`、复制时的 `--name` 都是可选项。用户没有特别要求时，不要为了这些可选参数额外打断；能直接创建/复制就直接执行
 - **`+base-create / +base-copy` 权限处理（bot 创建）**：若 Base 由应用身份（bot）创建，创建或复制成功后默认继续使用 bot 身份为当前可用 user（指当前 CLI 中 auth 模块已登录且可用的用户身份）添加 `full_access`（管理员）权限，并在回复中明确授权结果（成功 / 无可用 user / 授权失败及原因）。若授权未完成，要继续给出后续引导（稍后重试授权或继续用 bot）；owner 转移必须单独确认，禁止擅自执行
-- **dashboard 使用方式**：`+dashboard-create` 创建后返回 `dashboard_id`；Block 的 `data_config` 通过 JSON 字符串传入，支持 `@file.json` 读取文件
 - **advperm 使用方式**：`+advperm-enable` 启用高级权限后才能管理角色（`+role-*`）；`+advperm-disable` 是高风险操作，停用后已有自定义角色全部失效；操作用户必须为 Base 管理员；先读 [lark-base-advperm-enable.md](references/lark-base-advperm-enable.md) / [lark-base-advperm-disable.md](references/lark-base-advperm-disable.md)
 - **role 使用方式**：`+role-create` 仅支持 `custom_role`；`+role-update` 采用 Delta Merge（`role_name` 和 `role_type` 必须始终提供）；`+role-delete` 不可逆且仅支持自定义角色；角色配置支持 `base_rule_map`（Base 级复制/下载）、`table_rule_map`（表级权限含记录/字段粒度）、`dashboard_rule_map`（仪表盘权限）、`docx_rule_map`（文档权限）；写角色前先读 [role-config.md](references/role-config.md)
 - **表单 form-id**：通过 `+form-list` 获取；`+form-create` 返回的 `id` 即 `form-id`，可用于 `+form-questions-*` 操作
@@ -279,8 +278,7 @@ https://{domain}/base/{base-token}?table={table-id}&view={view-id}
 - [lark-base-role-create.md](references/lark-base-role-create.md) — `+role-create` 创建角色
 - [lark-base-role-update.md](references/lark-base-role-update.md) — `+role-update` 更新角色
 - [lark-base-role-delete.md](references/lark-base-role-delete.md) — `+role-delete` 删除角色
-- [lark-base-dashboard.md](references/lark-base-dashboard.md) — dashboard 命令索引（每个命令已拆到独立文档）
-- [lark-base-dashboard-block.md](references/lark-base-dashboard-block.md) — dashboard block 命令索引（每个命令已拆到独立文档）
+- [lark-base-dashboard.md](references/lark-base-dashboard.md) — dashboard 模块工作流指引
 - [dashboard-block-data-config.md](references/dashboard-block-data-config.md) — Block data_config 结构、图表类型、filter 规则
 - [lark-base-workflow.md](references/lark-base-workflow.md) — workflow 命令索引
 - [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md) — `+workflow-create/+workflow-update` JSON body 数据结构详解，包含触发器及各类节点的配置规则（强烈推荐）
@@ -305,5 +303,4 @@ https://{domain}/base/{base-token}?table={table-id}&view={view-id}
 | [`form commands`](references/lark-base-form-create.md) | `+form-list / +form-get / +form-create / +form-update / +form-delete` |
 | [`form questions commands`](references/lark-base-form-questions-create.md) | `+form-questions-list / +form-questions-create / +form-questions-update / +form-questions-delete` |
 | [`workflow commands`](references/lark-base-workflow.md) | `+workflow-list / +workflow-get / +workflow-create / +workflow-update / +workflow-enable / +workflow-disable` |
-| [`dashboard commands`](references/lark-base-dashboard.md) | `+dashboard-list / +dashboard-get / +dashboard-create / +dashboard-update / +dashboard-delete` |
-| [`dashboard block commands`](references/lark-base-dashboard-block.md) | `+dashboard-block-list / +dashboard-block-get / +dashboard-block-create / +dashboard-block-update / +dashboard-block-delete` |
+| [`dashboard / dashboard-block commands`](references/lark-base-dashboard.md) | `+dashboard-list / +dashboard-get / +dashboard-create / +dashboard-update / +dashboard-delete / +dashboard-block-list / +dashboard-block-get / +dashboard-block-create / +dashboard-block-update / +dashboard-block-delete` |

skills/lark-base/references/dashboard-block-data-config.md

@@ -19,18 +19,63 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档描述所有
 | `radar` | 雷达图 |
 | `statistics` | 指标卡 |
 
+## 字段类型与操作符速查（AI 决策用）
+
+> `+field-list` 返回的 `type` 字段映射：number（数字）、text（文本）、select（单选）、multi_select（多选）、datetime（日期时间）、checkbox（复选框）、user（人员）
+
+```
+文本/电话/URL/邮箱:  is, isNot, contains, doesNotContain, isEmpty, isNotEmpty
+数字/货币/进度:      is, isNot, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty
+单选:               is, isNot, isEmpty, isNotEmpty
+多选:               is, isNot, contains, doesNotContain, isEmpty, isNotEmpty
+日期/时间:          is, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty
+复选框:             is (value: true/false)
+人员/创建人/修改人:  is, isNot, isEmpty, isNotEmpty
+```
+
 ## data_config 通用结构
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `table_name` | string | 关联数据表名称 |
 | `series` | `[{ "field_name": "xxx", "rollup": "SUM" }]` | 指标/Y 轴（与 `count_all` 二选一）。rollup 支持 `SUM` / `MAX` / `MIN` / `AVERAGE` |
 | `count_all` | boolean | COUNTA 聚合，统计所有记录数（与 `series` 二选一） |
-| `group_by` | `[{ "field_name": "xxx", "mode": "integrated" }]` | X 轴分组维度 |
+| `group_by` | `[{ "field_name": "xxx", "mode": "integrated", "sort": {...} }]` | X 轴分组维度。`mode` 必填，`sort` 可选，见下方说明 |
 | `filter` | object | 筛选条件 |
 | `filter.conjunction` | `"and"` / `"or"` | 筛选逻辑 |
 | `filter.conditions` | `[{ "field_name", "operator", "value" }]` | 筛选条件数组，value 类型因字段类型而异（见下方 filter 格式规则） |
 
+## group_by 详细说明
+
+### mode 枚举
+
+| mode | 含义 | 适用场景 |
+|------|------|----------|
+| `integrated` | 聚合分组（默认） | 绝大部分场景，按字段值分组统计 |
+| `enumerated` | 多值拆分统计 | 多选、人员等多值字段，将每个选项/人员拆开独立统计 |
+
+> 多选、人员等多值字段默认用 `enumerated`；其他字段默认用 `integrated`。
+
+### sort 排序
+
+| sort.type | 含义 | 典型场景 |
+|-----------|------|----------|
+| `group` | 按横轴值排序 | 按月份升序、按品类名字母序 |
+| `value` | 按纵轴值排序 | 按销售额从大到小 |
+| `view` | 按数据源记录顺序 | 保持原表行序（不常用） |
+
+`sort.order`：`asc`（升序）/ `desc`（降序）
+
+示例 — 柱状图按销售额降序：
+
+```json
+{
+  "table_name": "订单表",
+  "series": [{ "field_name": "金额", "rollup": "SUM" }],
+  "group_by": [{ "field_name": "类别", "mode": "integrated", "sort": {"type": "value", "order": "desc"} }]
+}
+```
+
 ## filter 格式规则
 
 **基本结构：**
@@ -46,6 +91,20 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档描述所有
 }
 ```
 
+**多条件示例（and/or）：**
+
+```json
+{
+  "filter": {
+    "conjunction": "and",
+    "conditions": [
+      { "field_name": "状态", "operator": "is", "value": "已完成" },
+      { "field_name": "金额", "operator": "isGreater", "value": 1000 }
+    ]
+  }
+}
+```
+
 **操作符：**
 
 | 操作符 | 含义 | 是否需要 value |
@@ -68,10 +127,10 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档描述所有
 | 文本 / 电话 / URL | string | is, isNot, contains, doesNotContain, isEmpty, isNotEmpty | `{"field_name":"姓名","operator":"contains","value":"张"}` |
 | 数字 | number | is, isNot, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty | `{"field_name":"金额","operator":"isGreater","value":0}` |
 | 单选 | string（选项名） | is, isNot, isEmpty, isNotEmpty | `{"field_name":"状态","operator":"is","value":"已完成"}` |
-| 多选 | string 或 string[] | is, isNot, contains, doesNotContain, isEmpty, isNotEmpty | `{"field_name":"标签","operator":"contains","value":["紧急","重要"]}` |
-| 日期时间 / 创建时间 / 修改时间 | number（毫秒时间戳） | is, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty | `{"field_name":"创建日期","operator":"isGreater","value":1711209600000}` |
+| 多选 | string[]（选多个）/ string（选单个） | is, isNot, contains, doesNotContain, isEmpty, isNotEmpty | 多选传数组如 `["标签1","标签2"]`；单选传单个字符串 |
+| 日期时间 / 创建时间 / 修改时间 | number（Unix 毫秒时间戳，13位） | is, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty | `{"field_name":"创建日期","operator":"isGreater","value":1704038400000}` |
 | 复选框 | boolean | is | `{"field_name":"已审核","operator":"is","value":true}` |
-| 人员 / 创建人 / 修改人 | string 或 string[]（用户 ID） | is, isNot, isEmpty, isNotEmpty | `{"field_name":"负责人","operator":"is","value":"user_id_xxx"}` |
+| 人员 / 创建人 / 修改人 | string 或 string[]（用户 ID，格式 `ou_xxx`） | is, isNot, isEmpty, isNotEmpty | `{"field_name":"负责人","operator":"is","value":"ou_xxxxxxxxxxxxxxxx"}` |
 | 所有类型（为空/不为空） | 不需要 value | isEmpty, isNotEmpty | `{"field_name":"备注","operator":"isEmpty"}` |
 
 > `value` 类型为 `string | number | boolean | string[]`，需根据字段类型匹配正确格式
@@ -93,6 +152,16 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档描述所有
 
 ## 可复制模板
 
+**按意图选择模板：**
+- 比较不同类别数值 → 柱状图 / 条形图
+- 看趋势变化 → 折线图 / 面积图
+- 看占比分布 → 饼图 / 环形图 / 词云
+- 多指标对比 → 组合图
+- 看两变量关系 → 散点图
+- 看流程转化 → 漏斗图
+- 看多维度评分 → 雷达图
+- 显示单个指标 → 指标卡（统计数字或记录数）
+
 最小柱状图：
 
 ```json
@@ -103,7 +172,7 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档描述所有
 }
 ```
 
-最小饼/环图（按分类计数）：
+最小饼图/环形图（按分类字段统计行数占比）：
 
 ```json
 {
@@ -123,27 +192,84 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档描述所有
 }
 ```
 
-## 常见错误与修复
+条形图（横向柱状图）：
 
-- 同时存在 `series` 与 `count_all`
-  - 现象：后端/本地校验报互斥错误
-  - 修复：仅保留其一；统计字段用 `series`，统计条数用 `count_all:true`
-- 缺少 `table_name`
-  - 现象：本地校验缺少必填字段
-  - 修复：指定数据源表名（使用表名，非表 ID）
-- `series[].rollup` 大小写/取值不合法
-  - 现象：本地校验提示枚举不支持
-  - 修复：改为 `SUM|MAX|MIN|AVERAGE` 中之一（不区分大小写，CLI 会统一为大写；计数请使用 `count_all:true`）
-- `group_by` 超出 2 个或字段名为空
-  - 修复：保留前 2 个，或补齐 `field_name`
-- 排序枚举不合法
-  - 修复：`group_by.sort.type` 仅能为 `group|value|view`；`order` 为 `asc|desc`
-- filter 写法不规范
-  - 修复：`conjunction` 取 `and|or`；`conditions[].operator` 必须在本页表格列举的范围内；除 `isEmpty/isNotEmpty` 外需提供 `value`
+```json
+{
+  "table_name": "表名",
+  "series": [{ "field_name": "数值字段", "rollup": "SUM" }],
+  "group_by": [{ "field_name": "分组字段", "mode": "integrated" }]
+}
+```
 
-## 指标卡（statistics）data_config 示例
+面积图（趋势填充）：
 
-统计数字字段求和：
+```json
+{
+  "table_name": "表名",
+  "series": [{ "field_name": "数值字段", "rollup": "SUM" }],
+  "group_by": [{ "field_name": "时间字段", "mode": "integrated", "sort": {"type":"group","order":"asc"} }]
+}
+```
+
+组合图（柱+线等多指标对比）：
+
+```json
+{
+  "table_name": "表名",
+  "series": [
+    { "field_name": "指标1", "rollup": "SUM" },
+    { "field_name": "指标2", "rollup": "SUM" }
+  ],
+  "group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
+}
+```
+
+散点图（两变量相关性）：
+
+```json
+{
+  "table_name": "表名",
+  "series": [{ "field_name": "Y轴字段（数值/指标）", "rollup": "SUM" }],
+  "group_by": [{ "field_name": "X轴字段（分类/维度）", "mode": "integrated" }]
+}
+```
+
+漏斗图（流程转化）：
+
+```json
+{
+  "table_name": "表名",
+  "series": [{ "field_name": "数值字段", "rollup": "SUM" }],
+  "group_by": [{ "field_name": "阶段字段", "mode": "integrated" }]
+}
+```
+
+词云（文本频率）：
+
+```json
+{
+  "table_name": "表名",
+  "count_all": true,
+  "group_by": [{ "field_name": "文本字段", "mode": "integrated" }]
+}
+```
+
+雷达图（多维度评分）：
+
+```json
+{
+  "table_name": "表名",
+  "series": [
+    { "field_name": "维度1", "rollup": "SUM" },
+    { "field_name": "维度2", "rollup": "SUM" },
+    { "field_name": "维度3", "rollup": "SUM" }
+  ],
+  "group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
+}
+```
+
+指标卡（统计数字）：
 
 ```json
 {
@@ -152,7 +278,7 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档描述所有
 }
 ```
 
-统计记录行数：
+指标卡（统计记录数）：
 
 ```json
 {
@@ -161,10 +287,27 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档描述所有
 }
 ```
 
-> `series` 与 `count_all` 二选一，不能同时使用。
+## 常见错误与修复
+
+- 同时存在 `series` 与 `count_all`
+  - 现象：后端/本地校验报互斥错误
+  - 修复：见「关键约束」章节的二选一规则
+- 缺少 `table_name`
+  - 现象：本地校验缺少必填字段
+  - 修复：指定数据源表名（使用表名，非表 ID）
+- `series[].rollup` 大小写/取值不合法
+  - 现象：本地校验提示枚举不支持
+  - 修复：改为 `SUM|MAX|MIN|AVERAGE` 中之一（不区分大小写，CLI 会统一为大写；计数请使用 `count_all:true`）
+- `group_by` 超出 2 个或字段名为空
+  - 修复：保留前 2 个，或补齐 `field_name`
+- 排序枚举不合法
+  - 修复：`group_by.sort.type` 仅能为 `group|value|view`；`order` 为 `asc|desc`
+- filter 写法不规范
+  - 修复：`conjunction` 取 `and|or`；`conditions[].operator` 必须在本页表格列举的范围内；除 `isEmpty/isNotEmpty` 外需提供 `value`
 
 ## 坑点
 
 - **`count_all` 与 `series` 二选一** — 两者不能同时使用
 - **filter `value` 类型因字段而异** — 文本/单选为 string，数字为 number，日期为毫秒时间戳，多选/人员可为 string[]，复选框为 boolean；`isEmpty`/`isNotEmpty` 不需要 value
 - **`data_config` 结构随 `type` 变化** — 不同组件类型的字段不同，创建前务必确认类型对应的字段
+- **表名用 name，不是 ID** — `table_name` 对应的是表名称（如「订单表」），不是 `table_id`