飞书表格导出与数据分析

核心功能

一、导出功能

从飞书多维表格/电子表格导出数据为CSV或Excel
自动识别URL类型（wiki/base/sheets）
支持多表/多工作表一次性导出
富文本单元格自动提取纯文本

二、数据分析功能

基于 DuckDB 引擎的高效数据分析：

数据探索：表结构、数值统计、分类统计、日期统计、数据质量
SQL查询：智能SQL生成、自动重试、SQL校正（语法/列名/引号）
数据抽样：支持按比例抽样验证查询逻辑
结果导出：支持CSV/Excel/JSON/Parquet格式

三、生成分析报告

根据分析结果，由 AI 直接生成 Markdown 格式分析报告。

报告结构：

# {标题}

**数据来源**: {源文件}  
**生成时间**: {时间}  

---

## 洞察结论
- {关键发现1}
- {关键发现2}
- {业务建议}

## 关键指标
| 指标 | 数值 | 说明 |
|------|------|------|
| {指标1} | {值} | {说明} |
| {指标2} | {值} | {说明} |

## 数据概览
- **数据行数**: {行数}
- **数据列数**: {列数}
- **字段列表**: {字段1}, {字段2}, ...

## 分析查询
### 查询 1
```sql
{SELECT语句}

结果: {结果表格或摘要}

报告由 feishu-table-analytics 技能生成


将报告保存为 `{文件名}_report.md`。

### 四、可视化报告功能（可选）
基于 Chart.js 生成自包含 HTML 可视化报告：
- **KPI卡片**：顶部关键指标展示
- **多图表**：柱状图、折线图、饼图、雷达图等
- **洞察结论**：数据趋势、关键发现、业务建议
- **数据表格**：明细数据展示

## 使用方式

### 第一步：导出飞书表格

#### 导出多维表格
```bash
python scripts/main.py \
  --url "https://xxx.feishu.cn/base/xxx" \
  --table-name "员工列表" \
  --output employees.csv

导出电子表格

python scripts/main.py \
  --url "https://xxx.feishu.cn/sheets/xxx" \
  --output data.xlsx \
  --format excel

第二步：数据分析

数据探索

# 完整统计（推荐）
python scripts/duckdb_analyzer.py --file_path ./employees.csv --mode describe

# 简单模式
python scripts/duckdb_analyzer.py --file_path ./employees.csv --mode describe --simple

# 导出分析报告
python scripts/duckdb_analyzer.py --file_path ./employees.csv --mode describe --output report.json

SQL查询

# 基础查询
python scripts/duckdb_analyzer.py --file_path ./employees.csv --mode query \
  --sql "SELECT * FROM data LIMIT 10"

# 聚合分析
python scripts/duckdb_analyzer.py --file_path ./employees.csv --mode query \
  --sql "SELECT department, COUNT(*) as count FROM data GROUP BY department"

# 抽样验证
python scripts/duckdb_analyzer.py --file_path ./employees.csv --mode query \
  --sql "SELECT * FROM data WHERE salary > 10000" --sample_fraction 0.1

# 导出结果
python scripts/duckdb_analyzer.py --file_path ./employees.csv --mode query \
  --sql "SELECT * FROM data" --output result.xlsx

第三步：生成分析报告

3.1 AI 生成报告基础结构

根据分析结果，由 AI 生成 Markdown 报告（洞察、指标、概览、查询摘要），保存为 {源文件名}_report.md。

报告结构：

# {标题}

**数据来源**: {源文件}  
**生成时间**: {时间}  

---

## 洞察结论
- {关键发现1}
- {关键发现2}
- {业务建议}

## 关键指标
| 指标 | 数值 | 说明 |
|------|------|------|
| {指标1} | {值} | {说明} |

## 数据概览
- **数据行数**: {行数}
- **数据列数**: {列数}
- **字段列表**: {字段1}, {字段2}, ...

## 分析查询
### 查询 1
```sql
{SELECT语句}

结果: {结果摘要}

报告由 feishu-table-analytics 技能生成


**3.2 追加完整数据明细**

将分析结果中的完整表格数据追加到报告末尾：

```bash
python scripts/append_data_to_report.py \
  --report analysis_report.md \
  --data analysis_result.json \
  --section "数据明细"

脚本会自动读取 JSON 数据，生成 Markdown 表格追加到报告（最多显示100行）。

第四步：生成可视化报告（可选）

当用户明确要求"生成报告"、"可视化"、"出图"或"制作图表"时执行此步骤。

步骤 4.1：构造可视化配置

根据分析结果构造 JSON 配置：

KPI 卡片（顶部关键指标）：

[
  {"label": "总营收", "value": "¥1,755,905", "sub": "全年累计", "color": "green"},
  {"label": "订单数", "value": "200", "sub": "5 品类", "color": "blue"}
]

图表配置：

占比/构成：doughnut 或 pie
趋势/时间序列：line（fill: true 显示面积）
分类对比（≤8 项）：bar（垂直）
分类对比（>8 项）：horizontalBar（水平）
多指标对比：分组 bar
排名 Top N：水平 bar
多维度对比：radar

洞察结论（insights）：

文本格式：每行一条洞察
内容建议：数据趋势、关键发现、业务建议

数据表格（tables）：

{
  "title": "销售明细",
  "columns": ["category", "total_sales", "order_count"],
  "data": [
    {"category": "Electronics", "total_sales": 42938.24, "order_count": 120}
  ]
}

步骤 3.2：生成可视化报告

python scripts/generate_report.py \
  --title "数据分析报告" \
  --subtitle "数据来源：employees.csv" \
  --data '{"kpis": [...], "charts": [...], "insights": "...", "tables": [...]}' \
  --output report.html

典型工作流

完整分析流程：

导出飞书表格到本地文件
使用 duckdb_analyzer.py --mode describe 了解数据结构
使用 SQL 查询执行数据分析
根据分析结果生成 MD 分析报告（含洞察、SQL、结果）
根据需要决定是否生成可视化 HTML 报告

输出产物：

导出的数据文件（CSV/Excel）
分析报告（MD）：洞察结论 + SQL查询 + 结果数据
可视化报告（HTML，可选）：图表展示

参数说明

导出参数（main.py）

| 参数 | 必填 | 说明 | |------|------|------| | --url | 是 | 飞书表格URL | | --table-name | 多维表格必填 | 数据表名称 | | --output | 是 | 输出文件路径 | | --format | 否 | 导出格式：csv或excel | | --no-record-id | 否 | 不包含record_id字段 |

分析参数（duckdb_analyzer.py）

| 参数 | 必填 | 说明 | |------|------|------| | --file_path | 是 | 数据文件路径 | | --mode | 是 | describe/query | | --sql | query模式必填 | SQL查询语句 | | --sample_fraction | 否 | 抽样比例（0-1） | | --output | 否 | 结果导出路径 | | --excel_sheet | 否 | Excel工作表名称 |

数据追加参数（append_data_to_report.py）

| 参数 | 必填 | 说明 | |------|------|------| | --report | 是 | MD 报告文件路径 | | --data | 是 | 分析结果 JSON 文件路径 | | --section | 否 | 章节标题，默认"数据明细" |

可视化参数（generate_report.py）（第四步，可选）

| 参数 | 必填 | 说明 | |------|------|------| | --title | 是 | 报告标题 | | --data | 是 | JSON字符串，含kpis/charts/tables/insights | | --subtitle | 否 | 副标题 | | --output | 否 | 输出HTML文件路径，默认report.html | | --footer | 否 | 页脚文字 |

依赖要求

Python环境已安装 pandas、openpyxl、duckdb、numpy
已正确配置飞书CLI（lark-cli）

飞书CLI安装

npm install -g @larksuite/cli
lark-cli config init --new

约束说明

强制执行规则

数据导出：必须通过 scripts/main.py 执行（内部封装了lark-cli调用）
数据分析：必须通过 scripts/duckdb_analyzer.py 执行，禁止手动编写 Python 代码处理数据
数据追加：必须通过 scripts/append_data_to_report.py 将完整数据追加到报告
分析报告：AI 生成报告基础结构（洞察、指标、概览、查询摘要）
可视化报告：必须通过 scripts/generate_report.py 执行（可选）
所有输入输出：必须通过脚本参数传递，禁止在对话中直接处理数据内容

智能体职责

解析用户需求，确定参数
调用对应脚本执行操作
解析脚本输出，生成分析结论
根据分析结果生成 MD 分析报告
根据分析结果构造可视化配置（可选）

禁止行为

禁止绕过 main.py 直接调用 lark-cli 命令
禁止使用 pandas/openpyxl 直接读写文件
禁止在分析报告中直接粘贴数据内容

资源索引

导出脚本：scripts/main.py（飞书表格导出入口）
分析脚本：scripts/duckdb_analyzer.py（数据分析核心，支持SQL查询、数据探索、抽样）
数据追加脚本：scripts/append_data_to_report.py（将分析结果JSON追加到MD报告）
可视化脚本：scripts/generate_report.py（Chart.js HTML报告生成，可选）
数据格式参考：references/data-formats.md（支持的文件格式说明）
导出核心模块：scripts/core/
- exporter.py：多维表格/电子表格导出
- parser.py：URL解析
- saver.py：文件保存
- converter.py：格式转换

注意事项

SQL校正功能

语法错误自动修复（多余分号、逗号等）
列名错误智能纠正（基于编辑距离匹配）
中文字段自动添加双引号
所有校正操作会在输出中显示

可视化图表类型

| 类型 | 用途 | 配置示例 | |------|------|----------| | bar | 柱状图（分类对比） | {"type": "bar", "labels": [...], "datasets": [{"data": [...]}]} | | horizontalBar | 水平柱状图（排名） | {"type": "horizontalBar", "labels": [...], "datasets": [{"data": [...]}]} | | line | 折线图（趋势） | {"type": "line", "labels": [...], "datasets": [{"data": [...]}]} | | doughnut/pie | 环形/饼图（占比） | {"type": "doughnut", "labels": [...], "datasets": [{"data": [...]}]} | | radar | 雷达图（多维度） | {"type": "radar", "labels": [...], "datasets": [{"data": [...]}]} |

最佳实践

先用 describe 模式了解数据结构
复杂查询先用 --sample_fraction 验证
查询结果超过1000行时建议使用LIMIT或聚合
可视化配置根据分析结果灵活构造，无需所有字段都填写