Provides complete data analysis dashboard development capabilities, including dashboard project creation, card planning, data cleaning, dashboard development, validation delivery, and full development workflow. Data cleaning is an important part of dashboard development. Data source marking uses the magic.project.js sources array.
How to Use This Document
This document provides quick guidance and core tool descriptions. For details, refer to the following reference documents:
- Project setup → references/project-setup.md (data sources, card planning, project structure, template tools)
- Dashboard development → references/dashboard-development.md (card DSL, appearance, ECharts v6, card management tools)
- Data cleaning → references/dashboard-data-cleaning.md
- Full workflow → references/dashboard-workflow.md
Code Execution Method
All tool calls via from sdk.tool import tool in this skill must be executed by passing code to run_skills_snippet's python_code parameter.
Quick Start
Important: Before executing the following steps, it's recommended to read the corresponding reference documents to understand detailed specifications:
- Before starting dashboard development → Read
reference/dashboard-workflow.mdfor complete workflow - After creating project → Read
reference/project-setup.mdfor project structure, data sources, card planning - When cleaning data → Read
reference/dashboard-data-cleaning.mdfor data cleaning specifications - When developing cards → Read
reference/dashboard-development.mdfor card DSL, appearance, ECharts v6, card management tools
Create Dashboard Project
from sdk.tool import tool
result = tool.call('create_dashboard_project', {
"name": "销售数据分析看板",
"sources": [{"type": "file", "name": "sales.csv", "url": "../sales.csv"}]
})
if result.ok:
# 后续在该项目目录内进行卡片规划、数据清洗、看板开发
# sources 参数会自动写入 magic.project.js 的 sources 数组
pass
Validate Dashboard
from sdk.tool import tool
result = tool.call('validate_dashboard', {
"project_path": "销售数据分析看板"
})
if result.ok:
# 无错误和警告方可交付
pass
Core Tools
create_dashboard_project - Create Dashboard Project
| Parameter | Required | Type | Description |
|---|---|---|---|
name |
Yes | string | Project name; the dashboard will be created in this directory under the workspace |
sources |
No | List[Dict[str, str]] | List of raw data source configurations, which will be automatically written to the sources array of magic.project.js. Each item must contain type, name, url. Example: [{"type": "file", "name": "sales.csv", "url": "../sales.csv"}] |
Return (result): on success, result.ok is true,result.content contains information such as the creation path; on failure, result.ok is false,result.error contains the error message (e.g., the directory already exists).
Data source marking: when creating a project, pass it in via the sources parameter, and it will be automatically written to the sources array of magic.project.js; when editing an existing project, you need to manually update the sources array in magic.project.js.
validate_dashboard - Validate Dashboard
| Parameter | Required | Type | Description |
|---|---|---|---|
project_path |
Yes | string | Dashboard project directory path, relative to the workspace root directory |
Return (result): on success, result.ok is true, with no errors or warnings; on failure, result.ok is false,result.error contains the reason for validation failure.Validation must pass before delivery; otherwise, the page cannot be accessed normally.
update_dashboard_template - Update Template Files
| Parameter | Required | Type | Description |
|---|---|---|---|
target_project |
Yes | string | Name of the dashboard project directory to update |
update_dashboard_js |
No | boolean | Whether to update dashboard.js, default false |
update_index_css |
No | boolean | Whether to update index.css, default false |
update_index_html |
No | boolean | Whether to update index.html, default false |
update_config_js |
No | boolean | Whether to update config.js, default false |
Return (result): on success, result.ok is true; on failure, result.error contains the error message.
backup_dashboard_template - Restore Template Backup
| Parameter | Required | Type | Description |
|---|---|---|---|
target_project |
Yes | string | Name of the dashboard project directory whose backup is to be restored |
restore_dashboard_js |
No | boolean | Whether to restore the dashboard.js backup |
restore_index_css |
No | boolean | Whether to restore the index.css backup |
restore_index_html |
No | boolean | Whether to restore the index.html backup |
restore_config_js |
No | boolean | Whether to restore the config.js backup |
Return (result): on success, result.ok is true; on failure, result.error contains error information.
download_dashboard_maps - Manually download map data
Manual download Dashboard map GeoJSON tool. Usually no need to download manually, as maps are auto-downloaded by create_dashboard_cards, update_dashboard_cards, and validate_dashboard.
When to use: Before creating map cards, or when validate_dashboard didn't download needed maps.
| Parameter | Required | Type | Description |
|---|---|---|---|
project_path |
Yes | string | Dashboard project path, relative to the workspace root directory |
area_names |
Yes | List[str] | List of region names to download (1-10), supports: 中国, provinces (e.g., 广东省, 北京市), major_city (e.g., 深圳市, 广州市). Precise names are required |
Return (result): on success, result.ok is true,result.extra_info contains download statistics; on failure, result.ok is false,result.error contains error information.
卡片管理工具 / Card Management Tools
Must use card management tools to operate data.js, strictly prohibited to edit directly. See reference/dashboard-development.md for details.
| Tool | Description |
|---|---|
| create_dashboard_cards | Batch create cards, supports the auto_layout parameter to automatically generate a full layout (layout can be omitted) |
| update_dashboard_cards | Batch update cards, supports single-field editing |
| delete_dashboard_cards | Batch delete cards, automatically compacts the layout |
| query_dashboard_cards | Query card information, supports querying all/specified cards, supports field filtering |
create_dashboard_cards - Create cards
auto_layout parameter (default false): When true, omit layout per card; the tool auto-generates gap-free layout by type order to avoid repeated validate failures. Recommend auto_layout=true when creating new dashboards.
| Parameter | Required | Type | Description |
|---|---|---|---|
project_path |
Yes | string | Dashboard project path |
cards |
Yes | List | Card list, each item contains id, type, source, getCardData; layout can be omitted when auto_layout=true |
auto_layout |
No | boolean | Whether to automatically calculate the layout, default false; when true, layout is omitted and filled by the tool |
工具使用示例 / Tool Usage Example
# 创建项目后检查 result.ok
# 识别数据源后传入 sources 参数，会自动写入 magic.project.js
result = tool.call('create_dashboard_project', {
"name": "销售数据分析看板",
"sources": [{"type": "file", "name": "sales.csv", "url": "../sales.csv"}]
})
if result.ok:
# 在 result.content 中可获取项目路径等信息
# sources 已自动写入 magic.project.js
pass
else:
# result.error 含失败原因，如 "Directory already exists"
pass
# 创建卡片：建议 auto_layout=True 省略 layout，由工具自动铺满
result = tool.call('create_dashboard_cards', {
"project_path": "销售数据分析看板",
"auto_layout": True,
"cards": [...]
})
# 校验看板：必须 result.ok 且无错误无警告才能交付
result = tool.call('validate_dashboard', {"project_path": "销售数据分析看板"})
if not result.ok:
# 根据 result.error 修复问题后重新校验
pass
# 手动下载地图（如需要）
result = tool.call('download_dashboard_maps', {
"project_path": "销售数据分析看板",
"area_names": ["中国", "广东省", "深圳市"]
})
决策树 / Decision Tree
New or edit dashboard? ├─ New → create_dashboard_project(sources=[...]) → Card planning → Data cleaning → Dashboard development → Validate → Complete delivery (data source auto-marked) └─ Edit → Identify existing dashboard project → Data cleaning (as needed) → Dashboard development/editing → Validate → Mark data source (as needed) → Complete delivery
Need data cleaning? ├─ New dashboard → Must execute data_cleaning.py ├─ Edit dashboard with data/requirement changes → Execute as needed └─ Edit dashboard without changes → Can skip
Validation failed? → Fix issues and re-run validate_dashboard until result.ok with no errors or warnings
Data source marking? ├─ When creating project → Pass via create_dashboard_project sources param, auto-written to magic.project.js └─ When editing project → Manually update sources array in magic.project.js
文件命名规范 / File Naming Rules
File and directory naming intelligently determined based on file content, business domain, and user preferred language, e.g.:
- User preferred language is Chinese: "销售数据分析看板", "销售数据.csv"
- User preferred language is English: "Sales Data Dashboard", "Sales Data.csv"
关键约束 / Key Constraints
- Strictly prohibited to generate any images through Python scripts (matplotlib, seaborn, plotly, etc.), all charts must use ECharts
- Data source files strictly prohibited to modify, only allow reading
- When creating project, pass sources via create_dashboard_project param (auto-written to magic.project.js); when editing existing project, manually update sources array in magic.project.js
- Must use card management tools (create_dashboard_cards, update_dashboard_cards, delete_dashboard_cards) to perform operations
- Temporary files start with temp_, must delete before task end
- File naming determined by content, business domain, user preferred language
工作流程概要 / Workflow Summary
New dashboard: Create dashboard project (pass sources param, auto-mark data source) → Card planning → Data cleaning → Dashboard development → Validate → Complete delivery Edit dashboard: Identify dashboard project → Data cleaning (as needed) → Dashboard development/editing → Validate → Mark data source (as needed) → Complete delivery