飞书表格导出与数据分析

核心功能

一、导出功能

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

二、数据分析功能

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

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

三、生成分析报告

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

报告结构：

# {标题}

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

---

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

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

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

## 分析查询
### 查询 1

{SELECT语句}

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

---

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

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

四、可视化报告功能（可选）

基于 Chart.js 生成自包含 HTML 可视化报告：

• KPI卡片：顶部关键指标展示
• 多图表：柱状图、折线图、饼图、雷达图等
• 洞察结论：数据趋势、关键发现、业务建议
• 数据表格：明细数据展示

使用方式

第一步：导出飞书表格

导出多维表格

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

{SELECT语句}

**结果**: {结果摘要}

---

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

3.2 追加完整数据明细

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

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

典型工作流

完整分析流程：

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

输出产物：

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

参数说明

导出参数（main.py）

分析参数（duckdb_analyzer.py）

数据追加参数（append_data_to_report.py）

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

依赖要求

• 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校正功能

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

可视化图表类型

最佳实践

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