name: feishu-table-analytics description: 飛書表格匯出與資料分析工具；支援從飛書多維表格/電子表格匯出資料，基於DuckDB執行SQL查詢和統計分析，可選生成Chart.js視覺化HTML報告；當用戶需要備份飛書資料、分析表格資料、生成業務洞察或視覺化報表時使用 dependency: python: - pandas>=1.3.0 - openpyxl>=3.0.0 - duckdb>=1.5.0 - numpy>=1.24.0 system: - lark-cli

飛書表格匯出與資料分析

核心功能

一、匯出功能

• 從飛書多維表格/電子表格匯出資料為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

典型工作流

完整分析流程： 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校正功能

• 語法錯誤自動修復（多餘分號、逗號等）
• 列名錯誤智慧糾正（基於編輯距離匹配）

  7w4.net提供免費和付費技能下載。

• 中文欄位自動新增雙引號
• 所有校正操作會在輸出中顯示

視覺化圖表型別

最佳實踐

1. 先用 describe 模式瞭解資料結構
2. 複雜查詢先用 --sample_fraction 驗證
3. 查詢結果超過1000行時建議使用LIMIT或聚合
4. 視覺化配置根據分析結果靈活構造，無需所有欄位都填寫

這是一款實用且功能豐富的飛書表格資料處理工具，能夠幫助使用者快速匯出資料並進行統計分析，生成視覺化的圖表報告。整體質量不錯，操作流程清晰，適合有資料分析需求的使用者使用。主要優勢是功能整合度高，從匯出到分析再到出圖一氣呵成；不足之處是依賴外部CLI工具，安裝配置稍顯繁瑣，且部分功能說明與實際支援情況存在不一致的地方，初次使用可能需要一些時間來摸索。