data-analysis-for-feishu

<div align="center">

<h1>📊 飞书数据可视化分析技能</h1>

<p>

<strong>开源数据可视化技能，专为 OpenClaw 构建，适配飞书生态</strong>

</p>

<p>

<a href="https://github.com/openclaw/skills"><img src="https://img.shields.io/badge/OpenClaw-Skill-blue.svg" alt="OpenClaw Skill"></a>

<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License MIT"></a>

<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.8+-yellow.svg" alt="Python 3.8+"></a>

<img src="https://img.shields.io/badge/Feishu-5.15+-brightgreen.svg" alt="Feishu 5.15+">

</p>

<p>

<a href="#features">✨ 特性</a> •

<a href="#installation">🚀 安装</a> •

<a href="#quick-start">⚡ 快速上手</a> •

<a href="#chart-types">📊 图表类型</a> •

<a href="#data-sources">📥 数据源</a> •

<a href="#examples">📖 示例</a> •

<a href="#faq">❓ 常见问题</a> •

<a href="#contributing">🤝 贡献指南</a>

</p>

</div>

✨ 特性

📊 丰富的图表支持

支持 12 种以上专业图表类型，覆盖 99% 的数据可视化场景：

• 基础图表：折线图、面积图、柱状图、堆叠柱状图、饼图、环形图、仪表图、雷达图
• 高级图表：散点图（相关性分析）、漏斗图（转化率分析）、瀑布图（财务分析）、双轴图（多指标对比）
• 多系列支持：所有图表均支持多数据系列对比
• 可自定义：支持堆叠模式、区域填充、自定义颜色等

🧠 AI 智能分析能力

• 自动图表推荐：上传数据后，AI 自动分析数据特征并推荐最优图表类型
• 自动数据清洗：自动处理空值、异常值，完成日期、百分比格式转换
• 自动生成分析报告：在生成图表的同时，输出自然语言的分析结论（趋势、极值、比例等）
• 自动生成标题：无需手动输入标题，系统根据数据自动创建合适标题

📥 多种数据源支持

无需手动转换数据，支持 6 种以上常见数据源：

• 本地文件：Excel（.xlsx/.xls）、CSV/TSV
• 飞书生态：飞书多维表格（Bitable）、飞书表格（Sheet）
• 文本格式：Markdown 表格、原始 JSON/二维数组、粘贴的表格文本

🖼️ 与飞书完美兼容

• 超高清输出：2x Retina DPI 渲染，默认分辨率 1200x750，文字和线条清晰锐利
• 精准裁剪：自动仅截取图表区域，无多余空白
• 飞书优化显示：在飞书聊天、文档、知识库页面中显示效果良好
• 双模式支持：

- ✅ 截图模式：兼容所有飞书版本，无需权限

- ✅ 交互卡片模式：支持悬停查看数值、切换数据系列（需飞书 ECharts 组件权限）

⚡ 优秀使用体验

• 零配置：开箱即用，首次运行时自动安装依赖
• 快速生成：首次运行约 10 秒（下载浏览器），后续生成仅需 1-3 秒
• 用户友好：错误提示清晰，日志输出完整，便于排查问题
• 可导出：支持将分析结论导出为独立文本文件，方便复制使用

🚀 安装

前置条件

• OpenClaw 实例（版本 ≥ 0.8.0）
• Python 3.8+
• 飞书集成已启用（可选，用于飞书数据源）

安装步骤

1. 下载技能包：

   wget https://github.com/openclaw/skills/releases/download/data-analysis-for-feishu-v1.0.0/data-analysis-for-feishu.skill

1. 在 OpenClaw 中安装：

进入 OpenClaw 管理后台 → 技能管理 → 安装 → 上传 .skill 文件

1. 完成！ 依赖项将在首次使用时自动安装。

手动安装（开发者专用）

cd /path/to/openclaw/skills
git clone https://github.com/openclaw/data-analysis-for-feishu.git
cd data-analysis-for-feishu
pip install -r requirements.txt

⚡ 快速上手

1 分钟测试运行

1 分钟内生成你的第一张图表：

# 进入技能目录
cd skills/data-analysis-for-feishu

# 生成示例漏斗图
python scripts/main.py \
  --type funnel \
  --title "用户转化漏斗" \
  --labels "访问" "注册" "加入购物车" "购买" "复购" \
  --values 10000 4500 2200 1200 500 \
  --output demo_funnel.png

你将获得一张高清漏斗图及自动分析报告。

自动模式（推荐）

让 AI 完成全部工作，只需提供数据：

# 自动分析 Excel 数据，推荐图表类型，生成图表 + 分析报告
python scripts/main.py \
  --excel your_data.xlsx \
  --output result.png \
  --analysis-output analysis.txt

📊 图表类型

📥 数据源

📖 使用示例

示例 1：多系列面积图

python scripts/main.py \
  --type area \
  --title "2023 vs 2024 销售趋势" \
  --excel sales_comparison.xlsx \
  --x-axis-field "Month" \
  --y-axis-field "2023 销售,2024 销售" \
  --series-names "2023,2024" \
  --output sales_trend.png

示例 2：双轴图（销售额 + 增长率）

python scripts/main.py \
  --type dual_axis \
  --title "月度绩效表现" \
  --x-axis "Jan" "Feb" "Mar" "Apr" "May" "Jun" \
  --y1-axis 120 150 135 180 210 240 \
  --y1-name "销售额 (千)" \
  --y2-axis 0 25 -10 33.3 16.7 14.3 \
  --y2-name "增长率 (%)" \
  --output performance.png

示例 3：瀑布图用于财务分析

python scripts/main.py \
  --type waterfall \
  --title "月度利润分解" \
  --x-axis "初始收入" "商品成本" "运营费用" "税费" "净利润" \
  --y-axis 1000 -300 -200 -150 350 \
  --y-name "金额 (千)" \
  --output profit_waterfall.png

示例 4：从 Markdown 表格生成图表

python scripts/main.py \
  --type bar \
  --title "季度收入" \
  --markdown-table "| 季度 | 收入 | 利润 |\n|----|----|----|\n| Q1 | 1200 | 240 |\n| Q2 | 1500 | 375 |\n| Q3 | 1350 | 297 |\n| Q4 | 1800 | 540 |" \
  --x-axis-field "季度" \
  --y-axis-field "收入,利润" \
  --output quarterly.png

🔧 配置选项

自定义颜色方案

在 scripts/generate_echarts_screenshot.py 中修改 DEFAULT_COLORS 以使用品牌色：

DEFAULT_COLORS = ["#YOUR_COLOR1", "#YOUR_COLOR2", ...]

自定义默认分辨率

在 scripts/main.py 中修改默认的 width/height 参数，调整输出图像尺寸。

启用交互式卡片模式

若您已获得飞书 ECharts 组件权限，可使用以下命令生成交互式卡片数据：

python scripts/generate_echarts_card.py --type line --title "演示" --x-axis "A" "B" --y-axis 1 2 --output card.json

将生成的 JSON 文件作为飞书卡片发送。

❓ 常见问题

问：首次运行时图片空白怎么办？

答：首次运行会自动下载 Chromium 浏览器（约 180MB），请耐心等待。后续运行速度极快。

问：能否不使用飞书？

答：可以！本工具支持生成本地 PNG 图片，适用于任何场景，飞书集成为可选功能。

问：如何申请飞书 ECharts 组件权限？

答：前往飞书开放平台 → 您的应用 → 权限管理 → 搜索“消息卡片 - 使用 ECharts 图表组件” → 提交申请。该权限免费，通常 1 个工作日内审核通过。

问：是否支持中文数据？

答：完全支持！所有组件均采用 UTF-8 编码，中文标签、标题及分析报告均可正常显示。

问：能否添加自定义图表类型？

答：可以！只需在 scripts/generate_echarts_screenshot.py 中按现有格式添加新的图表配置即可。

🤝 贡献指南

欢迎贡献！您可以通过以下方式参与：

• 🐛 报告问题与缺陷
• ✨ 提出新功能建议
• 📝 改进文档内容
• 🔧 添加新图表类型或数据源
• 🌐 增加多语言支持

开发环境搭建

# 克隆仓库
git clone https://github.com/your-username/data-analysis-for-feishu.git
cd data-analysis-for-feishu

# 安装依赖
pip install -r requirements.txt

# 运行测试
python scripts/main.py --type funnel --title "测试" --labels "A" "B" "C" --values 100 50 20 --output test.png

提交 Pull Request 步骤

1. Fork 项目仓库
2. 创建特性分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送至分支（git push origin feature/AmazingFeature）
5. 打开 Pull Request

📄 许可证

本项目采用 MIT 许可证发布。详情请参阅 LICENSE 文件。

🙏 致谢

• [ECharts](https://echarts.apache.org/) - 强大的开源图表库
• [Pyppeteer](https://pyppeteer.github.io/pyppeteer/) - Python 无头浏览器工具
• [OpenClaw](https://openclaw.ai/) - 可扩展的 AI 代理平台
• [飞书开放平台](https://open.feishu.cn/) - 飞书 API 与文档支持

<div align="center">

<strong>如果此技能对您有帮助，请在 GitHub 上给它一颗星 ⭐！</strong>

<br>

<a href="https://github.com/openclaw/data-analysis-for-feishu/stargazers"><img src="https://img.shields.io/github/stars/openclaw/data-analysis-for-feishu.svg?style=social" alt="GitHub stars"></a>

</div>