data-analysis

数据分析技能

概述

此技能使用 DuckDB（一款进程内分析型 SQL 引擎）分析用户上传的 Excel/CSV 文件。它通过单个 Python 脚本支持架构检查、基于 SQL 的查询、统计摘要和结果导出。

环境设置

运行分析前，请准备好 Python 环境。使用运行脚本的同一解释器显式安装所需软件包：

python -m pip install duckdb openpyxl

如果缺少任一软件包，脚本会退出并提示如何设置；它不会调用安装程序或修改环境。DuckDB 现有的用于加载文件的空间扩展设置保持不变。

核心功能

• 检查 Excel/CSV 文件结构（工作表、列、类型、行数）
• 对上传的数据执行任意 SQL 查询
• 生成统计摘要（均值、中位数、标准差、百分位数、空值）
• 支持多工作表 Excel 工作簿（每个工作表都会成为一张表）
• 将查询结果导出为 CSV、JSON 或 Markdown
• 借助 DuckDB 的列式引擎高效处理大型文件

工作流

步骤 1：了解需求

用户上传数据文件并请求分析时，请确定：

• 文件位置：/mnt/user-data/uploads/ 下已上传的 Excel/CSV 文件路径
• 分析目标：用户想了解哪些信息（摘要、筛选、聚合、比较等）
• 输出格式：结果应如何呈现（表格、CSV 导出、JSON 等）
• 无需检查 /mnt/user-data 下的文件夹

步骤 2：检查文件结构

首先检查上传的文件以了解其架构：

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/data.xlsx \
  --action inspect

返回内容包括：

• 工作表名称（Excel）或文件名（CSV）
• 列名、数据类型和非空值数量
• 每个工作表/文件的行数
• 示例数据（前 5 行）

步骤 3：执行分析

根据架构构造 SQL 查询，以回答用户的问题。

运行 SQL 查询

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/data.xlsx \
  --action query \
  --sql "SELECT category, COUNT(*) as count, AVG(amount) as avg_amount FROM Sheet1 GROUP BY category ORDER BY count DESC"

生成统计摘要

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/data.xlsx \
  --action summary \
  --table Sheet1

对于每个数值列，返回：count、mean、std、min、25%、50%、75%、max、null_count。 对于字符串列，返回：count、unique、top value、frequency、null_count。

导出结果

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/data.xlsx \
  --action query \
  --sql "SELECT * FROM Sheet1 WHERE amount > 1000" \
  --output-file /mnt/user-data/outputs/filtered-results.csv

支持的输出格式（根据扩展名自动检测）：

• .csv — 逗号分隔值
• .json — JSON 记录数组
• .md — Markdown 表格

相对输出路径以当前工作目录为基准。直接使用 report.csv 这样的文件名会将文件写入当前目录；对于 reports/report.csv 这样的路径，会自动创建缺失的父目录。 如果目标路径上已存在文件，则会直接覆盖，不发出警告。

JSON 结果的列名必须唯一。对于重复的列名，请使用显式 SQL 别名，例如 SELECT a.id AS left_id, b.id AS right_id FROM ...。 重复名称会导致错误，且不会修改任何现有输出文件。错误信息会列出重复名称，方便你直接为这些列指定别名。发生此拒绝时，CLI 会向 stderr 输出简短的 Error: ... 消息，并以非零状态码退出。

JSON 导出也会拒绝非有限数值（NaN、Infinity 和 -Infinity），包括列表或结构体中的值；此检查会在打开输出文件前进行。请在 SQL 中筛选或替换这些值，例如 CASE WHEN isfinite(ratio) THEN ratio ELSE NULL END AS ratio。有限数值、空值以及 'NaN' 这样的文本仍然有效。

参数

参数	必填	描述
--files	是	以空格分隔的 Excel/CSV 文件路径
--action	是	以下选项之一：inspect、query、summary
--sql	用于 query	要执行的 SQL 查询
--table	用于 summary	要汇总的表/工作表名称
--output-file	否	导出结果的路径（CSV/JSON/MD）

说明

请勿读取 Python 文件，只需使用相应参数调用它。

表命名规则

• Excel 文件：每个工作表都会成为一个以工作表命名的表（例如：Sheet1、Sales、Revenue）
• CSV 文件：表名为不带扩展名的文件名（例如：data.csv → data）
• 多个文件：所有文件中的表都可在同一查询上下文中使用，因此可以跨文件联接
• 名称冲突：重复的名称（包括仅大小写不同的名称）会按输入顺序分配唯一的 SQL 名称，例如 report、report_1、report_2。重复的 Excel 工作表名称也适用此规则。查询和摘要中请使用 inspect 显示的 SQL 名称。原始名称的别名不会覆盖较早分配的 SQL 名称。
• 特殊字符：工作表名和文件名会转换为 SQL 名称（例如，sales-2026 → sales_2026）。请使用 inspect 输出的 SQL 名称，或将唯一的原始名称用双引号括起来，例如 SELECT * FROM "sales-2026"。查询会原样执行：字符串字面量、列别名、注释和 CTE 均遵循 DuckDB 的常规语义。名称中包含双引号时，需通过重复双引号进行转义，例如 "net""amount"

分析模式

基本探索

-- Row count
SELECT COUNT(*) FROM Sheet1

-- Distinct values in a column
SELECT DISTINCT category FROM Sheet1

-- Value distribution
SELECT category, COUNT(*) as cnt FROM Sheet1 GROUP BY category ORDER BY cnt DESC

-- Date range
SELECT MIN(date_col), MAX(date_col) FROM Sheet1

聚合与分组

-- Revenue by category and month
SELECT category, DATE_TRUNC('month', order_date) as month,
       SUM(revenue) as total_revenue
FROM Sales
GROUP BY category, month
ORDER BY month, total_revenue DESC

-- Top 10 customers by spend
SELECT customer_name, SUM(amount) as total_spend
FROM Orders GROUP BY customer_name
ORDER BY total_spend DESC LIMIT 10

跨文件联接

-- Join sales with customer info from different files
SELECT s.order_id, s.amount, c.customer_name, c.region
FROM sales s
JOIN customers c ON s.customer_id = c.id
WHERE s.amount > 500

窗口函数

-- Running total and rank
SELECT order_date, amount,
       SUM(amount) OVER (ORDER BY order_date) as running_total,
       RANK() OVER (ORDER BY amount DESC) as amount_rank
FROM Sales

透视分析

-- Pivot: monthly revenue by category
SELECT category,
       SUM(CASE WHEN MONTH(date) = 1 THEN revenue END) as Jan,
       SUM(CASE WHEN MONTH(date) = 2 THEN revenue END) as Feb,
       SUM(CASE WHEN MONTH(date) = 3 THEN revenue END) as Mar
FROM Sales
GROUP BY category

完整示例

用户上传了 sales_2024.xlsx（包含工作表：Orders、Products、Customers），并提出请求：“分析我的销售数据——展示收入最高的产品和月度趋势。”

步骤 1：检查文件

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/sales_2024.xlsx \
  --action inspect

步骤 2：按收入列出热门产品

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/sales_2024.xlsx \
  --action query \
  --sql "SELECT p.product_name, SUM(o.quantity * o.unit_price) as total_revenue, SUM(o.quantity) as total_units FROM Orders o JOIN Products p ON o.product_id = p.id GROUP BY p.product_name ORDER BY total_revenue DESC LIMIT 10"

步骤 3：查看月度收入趋势

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/sales_2024.xlsx \
  --action query \
  --sql "SELECT DATE_TRUNC('month', order_date) as month, SUM(quantity * unit_price) as revenue FROM Orders GROUP BY month ORDER BY month" \
  --output-file /mnt/user-data/outputs/monthly-trends.csv

步骤 4：统计摘要

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/sales_2024.xlsx \
  --action summary \
  --table Orders

向用户清晰地说明发现、趋势和可行的见解，并展示结果。

多文件示例

用户上传了 orders.csv 和 customers.xlsx，并提出请求：“哪个地区的平均订单金额最高？”

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/orders.csv /mnt/user-data/uploads/customers.xlsx \
  --action query \
  --sql "SELECT c.region, AVG(o.amount) as avg_order_value, COUNT(*) as order_count FROM orders o JOIN Customers c ON o.customer_id = c.id GROUP BY c.region ORDER BY avg_order_value DESC"

输出处理

分析完成后：

• 在对话中将查询结果直接呈现为格式化表格
• 对于较大的结果，导出到文件，并通过 present_files 工具分享
• 始终用通俗语言解释发现和关键要点
• 如果发现有趣的规律，请建议后续分析
• 如果用户想保留结果，可提供导出选项

缓存

该脚本会自动缓存已加载的数据，避免每次调用时都重新解析文件：

• 首次加载时，文件会被解析并存储在系统临时目录（.data-analysis-cache/）下的持久化 DuckDB 数据库中
• 缓存键由按顺序排列的输入文件名，以及每个文件各自的 SHA256 摘要生成。重命名、调整顺序或更改输入文件都会创建新的缓存；将名称相同且内容未变的输入文件移至其他目录，则可以继续使用原有缓存。更新后的键命名空间会忽略旧版缓存表映射，并在首次使用时重新构建
• 后续使用相同文件的调用会直接使用缓存数据库（几乎可瞬时启动）
• 缓存过程透明，无需额外参数

当需要对同一组数据文件执行多次查询时（检查 → 查询 → 摘要），缓存尤其有用。

注意事项

• DuckDB 支持完整的 SQL，包括窗口函数、CTE、子查询和高级聚合
• Excel 日期列会自动解析；请使用 DuckDB 日期函数（DATE_TRUNC、EXTRACT 等）
• 对于非常大的文件（100MB 及以上），DuckDB 能够高效处理，无需将所有内容加载到内存中
• 列名包含空格时，可使用双引号访问："Column Name"