数据分析仪表板开发

技能文档

---
name: develop-data-analysis-dashboard
title: 数据分析仪表板开发
category: 办公效率
description: 数据分析仪表板（数据大屏）开发技能。当用户需要开发数据看板、创建或编辑 Dashboard 项目、搭建数据大屏、或进行仪表板数据清洗时触发。涵盖仪表板项目创建、卡片规划、数据清洗、卡片管理工具（创建、更新、删除、查询卡片）、地图下载工具、仪表板开发与验证。触发词：数据看板、仪表板、数据大屏、Dashboard 开发、数据可视化看板。
---

# 数据分析仪表板开发技能

提供完整的数据分析仪表板（数据大屏）开发能力——项目创建、卡片规划、数据清洗、仪表板开发、验证与交付，作为一站式端到端工作流。数据清洗是仪表板开发的重要环节。

---

## 代码执行方式

本技能中的工具调用必须通过代码执行函数传递，将工具调用代码作为参数传入运行。

当技能代码片段通过 SDK 调用工具时，始终使用 `result.ok` 判断成功与否，从 `result.content` 读取失败详情。不要读取或调用 `result.error`，因为 SDK `Result` 将失败文本存储在 `content` 中。

---

## 快速入门

**重要**：详细规则在本文档后续章节内联说明；执行步骤时，请参阅「技能工作流」「项目创建」「仪表板开发」和「数据清洗指南」章节。

**运行时基础文件**：不要修改、覆盖或删除 `index.html`、`dashboard.js` 或 `index.css`；违规操作将导致数据仪表板不可用。

**新建仪表板的默认卡片数量——除非用户明确要求缩减规模，否则必须遵守：**

| 卡片类型 | 要求数量 | 说明 |
|----------|----------|------|
| metric | **≥ 6** | 关键 KPI 概览卡片 |
| echarts | **26 – 30** | 仪表板核心；用同类型图表覆盖不同维度来凑足数量 |
| table | **2 – 3** | 至少 1 个必须是明细级表格 |
| markdown | 0 | 除非用户要求添加备注/注释，否则省略 |
| **合计** | **34 – 39** | 交付前自查 |

**强制执行规则（不可协商）：**

- 调用 `create_dashboard_project` 之前**必须**在 `cards_plan` 中列出所有卡片；不得将卡片推迟到后续步骤。
- `cards_plan` 中的 `card_id` 必须与后续 `create_dashboard_cards` 调用中使用的 `id` 完全匹配。
- 如果 echarts 数量不足，添加覆盖不同维度或时间范围的同类型图表——**不得**降低下限。
- 交付前调用 `query_dashboard_cards` 按 `type` 计数；如果任何类型低于要求数量，先创建缺少的卡片再继续。
- **仅当**用户明确要求更小的仪表板时，才覆盖这些数量。

---

## 技能工作流

### 步骤1：路径判断

- **新建仪表板**：规划准备（头脑风暴 + 阅读数据源） → 创建仪表板项目 → 数据清洗 → 仪表板开发 → 验证 → 完成交付
- **编辑仪表板**：项目定位 → 数据清洗（按需） → 仪表板编辑与卡片工具维护 → 验证 → 完成交付

### 步骤2：项目定位（编辑场景）

理解用户需求，定位目标项目。

### 步骤3：规划准备（新建场景）

在 `create_dashboard_project` 之前：
1. 头脑风暴问题和角度
2. **深入阅读数据源**（字段、粒度、定义、时间、分布、缺失值、可比维度）
3. 严格按照**快速入门中的强制数量**编写 `cards_plan`（metric ≥6, echarts 26–30, table 2–3, 合计 34–39）
4. **每张卡片必须在项目创建之前列出**——不接受少量代表性图表

### 步骤4：创建项目

必须调用 `create_dashboard_project` 并在同一调用中提供所需的 `cards_plan`；工具从中生成 `cards_plan.md`；规划卡片标识必须与后续 `create_dashboard_cards` 中的 `id` 匹配。

**返回（`result`）**：成功时 `result.ok` 为 true，`result.content` 包含创建路径和相关信息；失败时 `result.ok` 为 false，`result.content` 包含错误信息。

### 步骤5：数据清洗

根据 `cards_plan.md` 和数据目标，在项目中创建并运行 `data_cleaning.py`，为仪表板提供数据。详见 [数据清洗指南](references/data-cleaning-guide.md)。

### 步骤6：仪表板开发/编辑

按 `cards_plan.md` 使用卡片工具（create_dashboard_cards、update_dashboard_cards、delete_dashboard_cards、query_dashboard_cards）创建或维护卡片。

可修改的文件：`data_cleaning.py`、`cleaned_data/`、`config.js`
禁止修改的文件：`index.html`、`dashboard.js`、`index.css`

### 步骤7：验证仪表板

调用 `validate_dashboard(project_path="PROJECT_NAME")`；修复错误并重新运行直到通过（不得通过删除卡片来通过验证）。

### 步骤8：完成交付

总结项目和分析结果，关闭任务。

---

## 决策树

```
新建还是编辑仪表板？
├─ 新建 → 规划准备（头脑风暴，阅读数据源） → 编写 cards_plan [metric ≥6, echarts 26–30, table 2–3, 合计 34–39, 列出所有卡片] → create_dashboard_project → 数据清洗 → 仪表板开发 → 验证 → 完成交付
└─ 编辑 → 定位现有仪表板项目 → 数据清洗（按需） → 仪表板开发/编辑 → 验证 → 完成交付

需要数据清洗？
├─ 新建仪表板 → 必须执行 data_cleaning.py
├─ 编辑仪表板且数据/需求有变更 → 按需执行
└─ 编辑仪表板且无变更 → 可跳过

交付前卡片数量检查？
├─ 调用 query_dashboard_cards → 按类型计数
├─ metric < 6 或 echarts < 26 或 table < 2 → 先创建缺少的卡片
└─ 数量达标 → 进入验证

验证失败？ → 修复问题并重新运行 validate_dashboard 直到 result.ok 且无错误
```

---

## 核心工具

### create_dashboard_project — 创建仪表板项目

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `name` | 是 | string | 项目名称；仪表板在工作区的该目录下创建 |
| `cards_plan` | 是 | array | 卡片规划列表（至少一项）；工具从中生成 `cards_plan.md` |

完成**规划准备**后编写 `cards_plan`。新建仪表板的强制数量见快速入门。**必须在调用此工具前在 `cards_plan` 中列出所有卡片——不允许部分规划。** 仅当用户明确要求缩减仪表板时才可低于这些数量。

### validate_dashboard — 验证仪表板

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `project_path` | 是 | string | 仪表板项目目录路径，相对于工作区根目录 |

**交付前必须通过验证；否则页面无法访问。**

### 卡片管理工具

必须使用卡片管理工具操作 `data.js`；严禁直接编辑。卡片字段和 CardData 定义详见 [卡片数据 DSL 规范](references/card-data-dsl.md)。

| 工具 | 说明 |
|------|------|
| create_dashboard_cards | 批量创建；建议每次 ≤6 张卡片；`auto_layout`（可省略 `layout`） |
| update_dashboard_cards | 批量更新；每次 1–10 个更新，建议 ≤6；支持单字段编辑 |
| delete_dashboard_cards | 批量删除；`card_ids` 1–20；删除后自动压缩布局 |
| query_dashboard_cards | 查询全部或按 id 查询；可选 `fields` 过滤返回属性 |

**create_dashboard_cards**

`auto_layout`（默认 false）：为 true 时省略每张卡片的 `layout`，工具按类型顺序生成无间隙布局。新建仪表板建议使用 `auto_layout=true`。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `project_path` | 是 | string | 仪表板项目路径 |
| `cards` | 是 | List | 卡片列表；每项含 id、type、source、getCardData；auto_layout=true 时可省略 `layout` |
| `auto_layout` | 否 | boolean | 为 true 时省略 `layout`，由工具填充网格 |

**update_dashboard_cards**

每次更新必须包含 `id` 和至少一个其他要更改的字段。`layout` 接受部分对象（如仅 `y`）。

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `project_path` | 是 | string | 仪表板项目路径 |
| `updates` | 是 | List | 更新对象，1–10 项；建议每次 ≤6 |

**delete_dashboard_cards**

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `project_path` | 是 | string | 仪表板项目路径 |
| `card_ids` | 是 | List[str] | 要删除的 ID，1–20 项，不重复 |

**query_dashboard_cards**

| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `project_path` | 是 | string | 仪表板项目路径 |
| `card_ids` | 否 | List[str] | 省略则查询所有卡片；如设置则 1–20 个 ID |
| `fields` | 否 | List[str] | 省略则返回所有字段；否则为 id、type、title、source、layout、titleAlign、getCardData 的子集 |

---

## 工具调用示例

```python
# 创建仪表板项目
result = tool.call('create_dashboard_project', {
    "name": "销售数据仪表板",
    "cards_plan": [
        {
            "display_name": "总销售额",
            "card_id": "total_sales",
            "type": "metric",
            "data_detail": "销售金额总和",
        },
        {
            "display_name": "月度销售趋势",
            "card_id": "monthly_trend",
            "type": "echarts",
            "data_detail": "按月的销售额",
        },
    ],
})

if result.ok:
    pass  # 从 result.content 读取项目路径等信息
else:
    pass  # result.content 包含失败原因

# create_dashboard_cards：auto_layout=True；建议每次 ≤6 张卡片
result = tool.call('create_dashboard_cards', {
    "project_path": "销售数据仪表板",
    "auto_layout": True,
    "cards": [...]
})

# query_dashboard_cards：省略 card_ids 查询所有卡片
result = tool.call('query_dashboard_cards', {
    "project_path": "销售数据仪表板",
})

# update_dashboard_cards：每次更新需含 id 和 ≥1 个其他字段
result = tool.call('update_dashboard_cards', {
    "project_path": "销售数据仪表板",
    "updates": [...]
})

# delete_dashboard_cards：card_ids 1–20；不得通过删除卡片来通过验证
result = tool.call('delete_dashboard_cards', {
    "project_path": "销售数据仪表板",
    "card_ids": [...]
})

# validate_dashboard：交付需要 result.ok 且无错误
result = tool.call('validate_dashboard', {"project_path": "销售数据仪表板"})

# download_dashboard_maps（按需使用）
result = tool.call('download_dashboard_maps', {
    "project_path": "销售数据仪表板",
    "area_names": ["中国", "广东省", "深圳市"]
})
```

---

## 文件命名规则

文件和目录名称根据文件内容、业务领域和用户偏好语言智能确定，例如：

- 用户偏好中文：「销售数据分析看板」「销售数据.csv」
- 用户偏好英文：「Sales Data Dashboard」「Sales Data.csv」

---

## 关键约束

- 不要用 Python 脚本生成任何图像（matplotlib、seaborn、plotly 等）；所有图表用 ECharts 实现
- 不修改数据源文件；仅只读访问
- 必须使用卡片管理工具执行相关操作
- 临时文件以 temp_ 开头，必须在任务结束前删除
- 文件命名由内容、业务领域、用户偏好语言决定
- `data.js` 只能通过卡片工具维护；严禁直接编辑或覆盖 `data.js`
- 永远不要修改、覆盖或删除 `index.html`、`dashboard.js` 或 `index.css`；任何更改或删除都会导致数据仪表板不可用

---

## 数据来源

数据来源角色：为数据分析仪表板开发提供基础数据支持。
支持的类型示例：Excel、CSV、JSON、纯文本、PDF、网络数据、MCP 工具数据。
操作规则：不更改用户上传的源文件；仅只读。

数据来源识别与验证：

1. 理解请求；确定来源类型和内容。
2. 如果数据来自网络或 MCP 工具，先将其持久化到 JSON 文件再分析。
3. 数据源检查——如果出现以下任何情况，立即进入异常处理流程：无法读取的源；不支持的格式；空模板；仅有表头；无有效业务数据；数据质量不可接受地差。
4. 异常处理流程：告知用户原因并结束任务。

---

## 项目结构与编辑规则

```
项目目录/
├── geo/                    # 地图 GeoJSON 数据
├── cleaned_data/           # 清洗后的数据（CSV）
├── data_cleaning.py        # 数据清洗脚本
├── data.js                 # 卡片配置（DASHBOARD_CARDS）
├── config.js               # 全局配置（颜色、主题等）
├── index.html              # 页面结构（系统管理；不要修改或删除）
├── index.css               # 样式（系统管理；不要修改或删除）
├── dashboard.js            # 仪表板运行时（系统管理；不要修改或删除）
└── magic.project.js        # 项目配置文件
```

| 路径 | 用途 | 编辑规则 |
|------|------|----------|
| geo/ | 地图 GeoJSON | 系统管理；不要编辑 |
| cleaned_data/ | 清洗后的 CSV 数据源 | 可编辑：添加或修改文件 |
| data_cleaning.py | 原始数据 → cleaned_data/ | 可编辑：按需调整清洗逻辑 |
| data.js | DASHBOARD_CARDS 定义 | 仅工具操作：create/update/delete_dashboard_cards；禁止直接编辑文件 |
| config.js | 全局颜色、主题、字体等 | 受限：仅修改字段值；不要添加、删除、重命名字段或更改结构 |
| index.html | 页面 HTML | 系统管理；不要编辑、删除或覆盖，否则仪表板不可用 |
| index.css | 视觉样式 | 系统管理；不要编辑、删除或覆盖，否则仪表板不可用 |
| dashboard.js | 渲染、加载、图表 | 系统管理；不要编辑、删除或覆盖，否则仪表板不可用 |
| magic.project.js | 项目元数据 | 禁止：系统管理 |

---

## 卡片管理工具速查

参数表、`auto_layout` 和批量限制见上方「核心工具 > 卡片管理工具」。典型用法（按需选用）：

- 创建：`create_dashboard_cards`；每次 ≤6 张，`auto_layout=True`
- 编辑：`update_dashboard_cards`；每次 ≤6 个更新；部分字段即可（如 title、`layout.y`）
- 删除：`delete_dashboard_cards`；不得通过删除来通过验证
- 浏览：`query_dashboard_cards` 不带 `card_ids`（及可选 `fields`）获取全部概览
- 详情：同一工具带 `card_ids` 获取含 getCardData 的完整配置
- 精简负载：`query_dashboard_cards` 带 `fields`（如仅 id、type、layout）

---

## 外观与布局

卡片实际尺寸计算逻辑：

- 宽度：基于 config.js 中的 GRID_COLS 列网格系统
- 高度：卡片高度 = 卡片行数 × 卡片行高（config.js 中的 GRID_DEFAULT_ROW_HEIGHT）

UI 主题定制（仅当用户明确要求时）：修改 `config.js`（全局主题）。

卡片布局：

- 层次排列：指标卡片（顶部概览） → 图表卡片（核心分析） → 表格卡片（详细数据） → Markdown 卡片（备注）
- 布局原则：必须充分利用 config.js 中的 GRID_COLS 列网格系统，横向纵向互补填充，紧凑连续无间隙，宽高比协调

卡片标准尺寸示例（24 列网格）：metric `{w:4,h:3}`，chart `{w:8,h:8}`，table `{w:12,h:8}`，Markdown `{w:12,h:(根据内容计算高度)}`

---

## 参考资料

- [卡片数据 DSL 规范](references/card-data-dsl.md) — 卡片结构、CardType、CardData 定义与 getCardData 示例
- [ECharts v6.0.0 配置参考](references/echarts-config.md) — 图表配置要点与常见模式
- [数据清洗指南](references/data-cleaning-guide.md) — data_cleaning.py 编写规范与核心原则

使用说明

# 数据分析仪表板开发

一站式数据看板开发技能，覆盖项目创建、卡片规划、数据清洗、仪表板开发、验证与交付全流程。

## 使用

对话中直接描述需求即可触发：

```
帮我创建一个销售数据分析仪表板，数据文件是 sales.csv
```

```
编辑现有的仪表板项目，增加一个区域对比图表
```

## 工作原理

1. 根据数据源和需求，自动规划卡片方案（指标卡、图表卡、表格卡）
2. 执行数据清洗脚本，将原始数据处理为仪表板可用的结构化数据
3. 通过卡片管理工具创建、配置每张卡片，使用 ECharts 渲染所有图表
4. 自动验证仪表板完整性，确保交付即可用

新建仪表板默认包含 34–39 张卡片（6+ 指标卡、26–30 图表卡、2–3 表格卡），支持地图可视化。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。