develop-data-analysis-dashboard

数据分析仪表板开发技能

提供完整的数据分析仪表板（仪表盘）开发能力，涵盖项目创建、卡片规划、数据清洗、仪表板开发、验证和交付，形成端到端工作流。数据清洗是仪表板开发的重要环节。

---

代码执行方式

本技能中通过 from sdk.tool import tool 发起的所有工具调用，都必须通过将代码传递给 run_sdk_snippet 的 python_code 参数来执行。

当技能片段通过 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 统计数量；如果任何类型未达到要求数量，必须先创建缺少的卡片，再继续后续步骤。
• 仅当用户明确表示希望使用更小的仪表板时，才可覆盖这些数量要求。

工作流概述

路径概览

• 新建仪表板：规划准备（头脑风暴 + 阅读资料）→ 创建仪表板项目 → 数据清理 → 仪表板开发 → 验证 → 完成交付
• 编辑仪表板：识别项目 → 数据清理（按需）→ 编辑仪表板并维护卡片工具 → 验证 → 完成交付

步骤详情

• 识别项目：了解用户需求并确定目标项目（编辑场景）
• 规划准备（新建仪表板）：在调用 create_dashboard_project 前，围绕问题和角度进行头脑风暴；深入阅读资料（字段、粒度、定义、时间、分布、缺失情况、可比较维度），然后严格按照 Quick Start 中的强制数量编写 cards_plan（指标 ≥6、echarts 26–30、表格 2–3、总计 34–39）——必须在创建项目之前列出每张卡片；只列出少数代表性图表不可接受
• 创建项目：必须在同一次调用中使用必需的 cards_plan 调用 create_dashboard_project；该工具会据此写入 cards_plan.md；计划中的卡片标识符必须与之后 create_dashboard_cards 中的 id 相匹配
• 数据清理：根据 cards_plan.md 和数据目标，在项目中创建并运行 data_cleaning.py，为仪表板提供数据
• 仪表板编辑：按需更改允许修改的文件（例如 data_cleaning.py、cleaned_data/、config.js；绝不修改或删除 index.html、dashboard.js、index.css）（编辑场景）
• 仪表板开发：根据 cards_plan.md，使用卡片工具（create_dashboard_cards、update_dashboard_cards、delete_dashboard_cards、query_dashboard_cards）创建或维护卡片
• 验证仪表板：调用 validate_dashboard(project_path="PROJECT_NAME")；修复错误并重新运行，直到通过（不要为了通过验证而删除卡片）
• 完成交付：总结项目和分析结果，然后结束任务

核心原则

按顺序执行各步骤；交付前必须通过验证，否则页面无法正常工作。 绝不修改、覆盖或删除 index.html、dashboard.js 或 index.css，否则数据仪表板将无法使用（仅通过卡片工具及其他允许的路径维护 data.js 等允许修改的文件）。

偏好

• 新建仪表板：先进行规划准备，再编写 cards_plan；严格遵循 Quick Start 中的强制卡片数量表——指标 ≥6、echarts 26–30、表格 2–3、总计 34–39；交付前使用 query_dashboard_cards 自检
• 卡片优先设置 title（如果会与指标 label 重复，则指标卡片除外）
• 优先使用 ECharts；图表较多时，在不同维度使用相同类型的图表
• 卡片标准尺寸示例（24 列网格）：指标 {w:4,h:3}，图表 {w:8,h:8}，表格 {w:12,h:8}，Markdown {w:12,h:(calculate height based on content)}

---

决策树

新建还是编辑仪表板？ ├─ 新建 → 规划准备（头脑风暴、阅读资料）→ 编写 cards_plan [指标 ≥6、echarts 26–30、表格 2–3、总计 34–39，列出所有卡片] → create_dashboard_project → 数据清理 → 仪表板开发 → 验证 → 完成交付 └─ 编辑 → 识别现有仪表板项目 → 数据清理（按需）→ 仪表板开发/编辑 → 验证 → 完成交付

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

交付前检查卡片数量？ ├─ 调用 query_dashboard_cards → 按类型统计 ├─ 指标 < 6 或 echarts < 26 或表格 < 2 → 先创建缺少的卡片 └─ 数量达标 → 继续验证

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

---

核心工具

create_dashboard_project — 创建仪表盘项目

参数	必填	类型	描述
name	是	string	项目名称；仪表盘将在工作区中以此名称创建目录
cards_plan	是	array	卡片计划列表（至少包含一项）；工具会据此生成 cards_plan.md；字段定义及如何编写条目请参见下方的工具用法示例

完成规划准备后，再编写 cards_plan。对于新建的仪表盘，各类型的强制数量定义见快速入门中的新建仪表盘的默认卡片数量（metric ≥6，echarts 26–30，table 2–3，总计 34–39）。**调用此工具前，必须在 cards_plan 中列出每张卡片，不允许只提供部分计划。**仅当用户明确要求缩减仪表盘时，才可低于这些数量；否则必须预先列出所有卡片。创建项目后，可以分批调用 create_dashboard_cards。此工具不会验证数量，确保符合要求是你的责任。

返回值（result）：成功时，result.ok 为 true，且 result.content 包含创建的路径及相关信息；失败时，result.ok 为 false，且 result.content 包含错误（例如“Directory already exists”）。

validate_dashboard — 验证仪表盘

参数	必填	类型	描述
project_path	是	string	仪表盘项目目录路径，相对于工作区根目录

返回值（result）：成功时，result.ok 为 true，且没有错误；失败时，result.ok 为 false，且 result.content 包含验证失败原因。交付前必须通过验证，否则页面将无法访问。

卡片管理工具

必须使用卡片管理工具处理 data.js；严格禁止直接编辑。卡片字段和 CardData 定义见下文的 Card Data DSL；布局工作流和验证见 Dashboard Development。

工具	描述
create_dashboard_cards	批量创建；每次调用的 cards 最好不超过 6 个；auto_layout（可省略 layout）
update_dashboard_cards	批量更新；每次调用 1–10 个 updates，最好不超过 6 个；支持编辑单个字段
delete_dashboard_cards	批量删除；card_ids 为 1–20 个；删除后自动压缩布局
query_dashboard_cards	查询所有卡片或按 ID 查询；可选用 fields 筛选返回的属性

create_dashboard_cards

auto_layout（默认值为 false）：设为 true 时，省略每张卡片的 layout；工具会按类型顺序生成无间隙布局，以减少验证工作量。建议在新建仪表板时使用 auto_layout=true。条件允许时，每次调用的 cards 最好不超过 6 个（非硬性限制）。

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

update_dashboard_cards

每项更新必须包含 id 和至少一个要更改的其他字段（type、source、title、titleAlign、layout、getCardData 等）。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 的子集

---

工具使用示例

# Create dashboard project (see structure below)
# Abbreviated example: shows one cards_plan row shape; real new dashboards must list the full per-type plan per the skill.
result = tool.call('create_dashboard_project', {
    "name": "Sales Data Dashboard",
    "cards_plan": [
        {
            "display_name": "Total Sales",
            "card_id": "total_sales",
            "type": "metric",
            "data_detail": "Sum of sales amount",
        },
        {
            "display_name": "Monthly Sales Trend",
            "card_id": "monthly_trend",
            "type": "echarts",
            "data_detail": "Sales by month",
        },
    ],
})

if result.ok:
    # Read project path and other info from result.content
    pass
else:
    # result.content explains failure, e.g. "Directory already exists"
    pass

# create_dashboard_cards: auto_layout=True; prefer ≤6 cards/call
result = tool.call('create_dashboard_cards', {
    "project_path": "Sales Data Dashboard",
    "auto_layout": True,
    "cards": [...]
})

# query_dashboard_cards: omit card_ids for all cards; optional fields, card_ids (1–20)
result = tool.call('query_dashboard_cards', {
    "project_path": "Sales Data Dashboard",
})

# update_dashboard_cards: each update needs id and ≥1 other field; prefer ≤6 updates/call
result = tool.call('update_dashboard_cards', {
    "project_path": "Sales Data Dashboard",
    "updates": [...]
})

# delete_dashboard_cards: card_ids 1–20; do not delete to pass validation
result = tool.call('delete_dashboard_cards', {
    "project_path": "Sales Data Dashboard",
    "card_ids": [...]
})

# validate_dashboard: delivery requires result.ok with no errors
result = tool.call('validate_dashboard', {"project_path": "Sales Data Dashboard"})
if not result.ok:
    # Fix issues from result.content, then validate again
    pass

# download_dashboard_maps (when needed)
result = tool.call('download_dashboard_maps', {
    "project_path": "Sales Data Dashboard",
    "area_names": ["China", "Guangdong", "Shenzhen"]
})

---

文件命名规则

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

• 用户偏好的语言为中文：“销售数据仪表板”（中文）、“sales_data.csv”（中文）
• 用户偏好的语言为英语：“Sales Data Dashboard”、“Sales Data.csv”

---

关键约束

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

---

数据源

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

数据源识别与验证：

1. 理解请求；识别源类型和内容。
2. 如果数据来自网络或 MCP 工具，则在分析前将其保存到 JSON 文件。
3. 检查源文件——如果符合以下任一情况，请立即进入异常处理流程：源文件无法读取；格式不受支持；空模板；仅有表头；没有有效业务数据；数据质量差到无法接受。
4. 异常处理流程：告知用户原因并结束任务。

---

项目结构、文件和编辑规则

此树与表格相对应：每项的路径、用途和编辑规则。

Project Directory/
├── geo/                    # Map GeoJSON data
├── cleaned_data/           # Cleaned data (CSV)
├── data_cleaning.py        # Data cleaning script
├── data.js                 # Card config (DASHBOARD_CARDS)
├── config.js               # Global config (colors, themes, etc.)
├── index.html              # Page markup (system-managed; do not modify or delete)
├── index.css               # Styles (system-managed; do not modify or delete)
├── dashboard.js            # Dashboard runtime (system-managed; do not modify or delete)
└── magic.project.js        # Project configuration file

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

---

卡片数据 DSL

卡片基本结构：

• id：String，卡片唯一标识符（必填）
• type：卡片类型，必须严格遵循 CardType 类型（必填）
• source：String，数据源路径，例如 "./cleaned_data/filename.csv"（必填）
• layout：react-grid-layout 布局对象，包含 {x: integer, y: integer, w: integer, h: integer}（必填）
• getCardData：异步函数，用于加载数据并处理卡片数据，返回 CardData（必填）
• title：可选字符串，卡片标题
• titleAlign：可选字符串，标题对齐方式（"left"|"center"|"right"）

CardType 卡片类型：

• metric：单指标卡片，显示指标值
• table：数据表格卡片，显示结构化数据
• markdown：Markdown 文档卡片
• echarts：ECharts 图表卡片

CardData 数据结构规范：

• MetricCard（指标卡片）：
  • label：String，指标名称（必填）
  • value：String 或 number，指标值（必填）
  • change：可选字符串，变化值或百分比
  • unit：可选字符串，单位
  • icon：可选字符串，使用 tabler-icon 中的图标名称，例如 "ti-chart-bar"
  • iconColor：可选字符串，图标颜色；设置 icon 时必填
• TableCard（表格卡片）：
  • columns：列配置数组，每个项目包含：
    • title：String，列标题
    • dataIndex：String，数据字段名称
    • dataType：可选，数据类型（"string"|"number"|"date"|"time"），默认值为 "string"
    • width：可选，列宽（字符串或数字）
    • formatter：可选，列格式化函数，用于自定义单元格的显示方式；参数 value 是当前单元格的字符串值；返回值必须为字符串；仅限纯文本
    • sortable：可选，布尔值，是否启用排序
    • filterable：可选，布尔值，是否启用筛选
  • data：数据数组，每个项目是一个包含各列数据的对象（尽可能使用原始数据，再通过 formatter 函数格式化）
• MarkdownCard（Markdown 卡片）：
  • content：String，Markdown 格式的文本内容（必填）
• echarts（图表卡片）：ECharts Options 配置（版本：v6.0.0）

getCardData 数据加载函数：

• 异步函数，参数为 csv 对象，返回符合 CardData 规范的数据
• 核心方法：
  • csv.load("filename") 加载 cleaned_data 目录中的 CSV 文件（不包含 .csv 扩展名）
  • 返回：{data: row array, fields: column name array, name: filename, url: path}
• 关键规范：
  • 字段访问：使用 row["field_name"]，避免特殊字符问题
  • 数据转换：parseFloat(row["field_name"]) 将字符串转换为数字；CSV 数据默认是字符串
  • 数值处理：避免浮点精度问题，必要时使用 Math.round() 或 .toFixed()；百分比使用 .toFixed(2)，金额使用 .toLocaleString()
  • 主题配置访问：使用 window.DASHBOARD_CONFIG 前，先阅读 config.js，确认实际键名和值类型；例如：window.DASHBOARD_CONFIG.COLORS_PRIMARY

示例

// MetricCard example
getCardData: async (csv) => {
  const result = await csv.load("sales_data");
  const totalSales = result.data.reduce((sum, row) => {
    return sum + parseFloat(row["sales_amount"]);
  }, 0);
  return {
    label: "Total Sales",
    value: totalSales,
    unit: "USD",
    icon: "ti-currency-dollar",
  };
};

// TableCard example
getCardData: async (csv) => {
  const result = await csv.load("sales_data");
  return {
    columns: [
      {
        title: "Region",
        dataIndex: "region",
        dataType: "string",
        sortable: false,
        filterable: false,
      },
      {
        title: "Sales",
        dataIndex: "sales",
        dataType: "number",
        sortable: true,
        filterable: false,
        formatter: (value) => `$${parseFloat(value).toLocaleString()}`,
      },
      {
        title: "Customers",
        dataIndex: "customers",
        dataType: "number",
        sortable: true,
        filterable: false,
      },
    ],
    data: result.data,
  };
};

// ECharts chart example
getCardData: async (csv) => {
  const result = await csv.load("sales_data");
  return {
    grid: { left: 0, right: 0, top: 0, bottom: 0, containLabel: false },
    tooltip: {
      trigger: "axis",
      formatter: function (params) {
        return (
          params[0].name + ": " + params[0].value.toLocaleString() + " USD"
        );
      },
    },
    xAxis: {
      type: "category",
      data: result.data.map((row) => row["region"]),
    },
    yAxis: {
      type: "value",
      axisLabel: { formatter: (value) => value.toLocaleString() },
    },
    series: [
      {
        type: "bar",
        data: result.data.map((row) => parseFloat(row["sales"])),
        label: {
          show: true,
          formatter: (params) => params.value.toLocaleString(),
        },
      },
    ],
  };
};

// MarkdownCard example
getCardData: async (csv) => {
  const salesData = await csv.load("sales_base_data");
  const productData = await csv.load("product_sales_ranking");
  const totalSales = salesData.data.reduce(
    (sum, row) => sum + parseFloat(row["sales_amount"]),
    0,
  );
  const topProduct = productData.data.sort(
    (a, b) => parseFloat(b["sales_amount"]) - parseFloat(a["sales_amount"]),
  )[0];
  return {
    content: `### Sales Analysis Report\n\n**Total Sales**: ${totalSales.toLocaleString()} USD\n**Top Product**: ${topProduct["product_name"]}`,
  };
};

数据处理示例（与上方英文示例中的 CSV 结构相同）：

// CSV file: sales_data.csv
// Example content:
// region,sales,customers
// East,120000,150
// South,95000,120

const parsedData = [
  { region: "East", sales: "120000", customers: "150" },
  { region: "South", sales: "95000", customers: "120" },
];
const parsedFields = ["region", "sales", "customers"];

---

外观与布局

卡片实际尺寸计算逻辑：

• 宽度：根据 config.js 中的 GRID_COLS 列网格系统计算
• 高度：卡片高度 = 卡片行数 × 卡片行高（config.js 中的 GRID_DEFAULT_ROW_HEIGHT）

UI 主题自定义（仅当用户明确要求时）：config.js（全局主题）。

卡片布局：

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

---

ECharts v6.0.0 配置

仅用于仪表板开发

ECharts v6.0.0 关键设置：

• 地图：series.map 使用 GeoJSON 中的中文区域名称，例如 "China"、"Guangdong"、"Shenzhen"（传入下载的 GeoJSON 中的准确名称）；series.nameProperty 为 "fullname"
• grid：
  • 必需配置：{ left: 0, right: 0, top: 0, bottom: 0, containLabel: false }，在 v6.0.0 中，此配置已支持坐标轴及其标签完整地贴边显示，因此无需为 XY 轴标签或轴标题预留任何空间
  • outerBounds：
    • 使用场景：为图例、visualMap 组件预留空间
    • 使用条件：仅在配置了图例、visualMap 组件时设置
    • 核心原则：outerBounds 的方向必须与组件的位置方向一致
    • 配置示例：
      • 底部水平图例：{ grid: { left: 0, right: 0, top: 0, bottom: 0, containLabel: false, outerBounds: { bottom: 30 } }, legend: { type: "scroll", bottom: 0 } }
      • 左侧垂直图例：{ grid: { left: 0, right: 0, top: 0, bottom: 0, containLabel: false, outerBounds: { left: 50 } }, legend: { type: "scroll", orient: "vertical", left: 0 } }
      • 底部水平 visualMap：{ grid: { left: 0, right: 0, top: 0, bottom: 0, containLabel: false, outerBounds: { bottom: 50 } }, visualMap: { orient: "horizontal", bottom: 0, left: "center" } }
      • 左下方垂直 visualMap：{ grid: { left: 0, right: 0, top: 0, bottom: 0, containLabel: false, outerBounds: { left: 50 } }, visualMap: { orient: "vertical", left: 0, bottom: 0 } }
    • 错误示例：
      • outerBounds: { right: 120 }, legend: { orient: "vertical", right: 0 }（图例应位于左侧）
      • outerBounds: { left: 60 }，但未配置左侧组件（预留空间没有意义）
      • outerBounds: { top: 30 }，但组件位于底部（方向不匹配）
• legend：
  • 使用条件：仅在多系列图表或饼图需要图例时配置；单系列图表不需要图例
  • 推荐配置：水平图例使用 { bottom: 0, type: "scroll" }，垂直图例使用 { left: 0, orient: "vertical", type: "scroll" }
  • 避免使用 right、top 位置，优先使用 bottom、left 位置
• visualMap：
  • visualMap 推荐配置：水平使用 { orient: "horizontal", bottom: 0, left: "center" }，垂直使用 { orient: "vertical", left: 0, bottom: 0 }
  • 地图 visualMap 建议使用垂直方向：{ orient: "vertical", left: 0, bottom: 0 } + outerBounds: { left: 50 }
• tooltip：在有帮助的每个图形/系列上配置 tooltip
• dataZoom：严格禁止配置 dataZoom；ECharts dataZoom 的视觉效果较差，不建议在此处使用
• label：label.formatter 接收 params 对象；使用 params.value 获取数值；在需要时设置 labelLayout.hideOverlap: true 以减少重叠；可考虑使用字体描边以提高可读性
• title：不要在选项中设置 ECharts title（这会与卡片标题重复）
• axis：数值轴优先设置 name；类目轴避免设置 name。优先采用垂直布局模式：Y = 数值轴，X = 类目轴
• 充分利用图表区域；避免不必要的空白边距
• 格式化函数参数：label.formatter 和 tooltip.formatter 接收 params；axisLabel.formatter 接收 value
• 保持主题与 config.js 一致；使用 window.DASHBOARD_CONFIG 前，先阅读 config.js 以确认键名和数值类型

---

卡片管理工具 — 快速参考

参数表、auto_layout 和批处理上限，请参阅上文的核心工具、卡片管理工具。典型用法（按需选择）：

• 创建：create_dashboard_cards；每次调用 ≤6 个，auto_layout=True
• 编辑：update_dashboard_cards；每次调用 ≤6 项更新；可只提供部分字段（例如标题、layout.y）
• 删除：delete_dashboard_cards；不要为了通过验证而删除
• 浏览：使用 query_dashboard_cards，不带 card_ids（可选 fields），快速查看完整摘要
• 查看详情：使用同一工具并提供 card_ids，查看完整配置，包括 getCardData
• 精简负载：使用 query_dashboard_cards 并提供 fields（例如仅包含 id、type、layout）

---

仪表板数据清洗指南

• 脚本文件：data_cleaning.py
• 脚本示例：

import os
import pandas as pd

# Required statements (strictly follow this format)
PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
OUTPUT_DIR = os.path.join(PROJECT_ROOT, "cleaned_data")
os.makedirs(OUTPUT_DIR, exist_ok=True)

# Data source definition (if file data sources exist)
FILE_DATA_SOURCES = {
  'main_data': os.path.join(PROJECT_ROOT, "..", "data_source.csv"),
  'additional_data': os.path.join(PROJECT_ROOT, "..", "additional_data.csv")
}

def main():
    # 1. Data loading
    df = pd.read_csv(FILE_DATA_SOURCES['main_data'])

    # 2. Data cleaning: Handle missing values, remove duplicates, type conversion, outlier treatment

    # 3. Data splitting: Split into multiple thematic files by business logic, time dimension, geographic region, etc.

    # 4. Metric calculation: Descriptive statistics, group aggregation, derived metrics, advanced analysis

    # 5. Data output: CSV format to cleaned_data directory
    df.to_csv(os.path.join(OUTPUT_DIR, "cleaned_data.csv"), index=False, encoding='utf-8')

if __name__ == "__main__":
    main()

数据清洗核心原则：

• 只能通过执行 data_cleaning.py 脚本将 CSV 写入 cleaned_data
• 对完整数据集进行清洗
• 不得修改或覆盖用户上传的源文件；仅限只读访问
• 所有输出文件必须使用 UTF-8 编码和 CSV 格式
• 明确处理缺失值（根据情况进行填充、删除或标记）
• 按需转换数据类型（例如将字符串转换为数值、解析日期）
• 输出前删除重复行
• 在适用时，根据业务逻辑将数据拆分为多个主题文件；每个文件服务于一张或多张卡片
• 派生指标（比率、增长率、排名）应在此脚本中计算