lark-workflow-base-analytics

Bitable Intelligent Analysis Workflow

CRITICAL — Before starting, you MUST first use the Read tool to read lark-shared/SKILL.md, which contains authentication, permission handling, and security rules.

Applicable Scenarios

"Help me analyze this table" / "What trends does this Bitable have"
"Make a data report for this Base" / "Analyze the data in this table"
"Is there any anomalous data in this table" / "Bitable data insights"
"Help me look at the distribution of this table" / "Data dashboard"
"Summarize the key metrics of this table" / "Base analytics"

Bitable (Base/Bitable) is Feishu's most core differentiated product relative to competitors. This Skill enables AI to understand table structures, aggregate and analyze data, detect anomalies, and generate insight reports—unlocking the data value accumulated in Base.

Prerequisites

Supports user identity. Before execution, ensure authorization has been granted:

lark-cli auth login --domain base,doc

Workflow

用户指定 Base ──► 解析 base_token / table_id
                       │
                       ▼
              base +field-list（获取表结构）
                       │
                       ▼
              base +data-query（聚合分析）
              base +record-list（取样本数据）
              base +record-search（关键词搜索）
                       │
                       ▼
              AI 分析引擎
              ┌────────┼────────┐
              ▼        ▼        ▼
           趋势分析  异常检测  分布统计
                       │
                       ▼
              结构化分析报告（可选：docs +create / +dashboard-arrange）

Step 1: Parse the data source

Inputs the user may provide:

A. Base link:

https://xxx.feishu.cn/base/<base_token>?table=<table_id>&view=<view_id>

Extract base_token、table_id、view_id。

B. Directly provide base_token + table_id:

Go directly to Step 2.

C. Vague description ("that sales data table"):

Prompt the user to provide a specific link or token.

Step 2: Get the table structure

Refer to lark-base/SKILL.md。

# 列出所有数据表
lark-cli base +table-list --base-token "<base_token>" --format json

# 获取目标表的字段结构
lark-cli base +field-list --base-token "<base_token>" --table-id "<table_id>" --format json

Identify from the field list:

Numeric fields(Number / Currency / Progress) → can be aggregated and analyzed
Date fields(DateTime / CreatedTime / ModifiedTime) → can be used for time trends
Option fields(SingleSelect / MultiSelect) → can be used for distribution statistics
Person fields(User) → can be used for assignee dimension analysis
Formula/Lookup fields(Formula / Lookup) → note that they are read-only

Step 3: Data aggregation analysis

# 使用 data-query 进行聚合（推荐方式）
lark-cli base +data-query --base-token "<base_token>" --table-id "<table_id>" \
  --field-names '["<字段1>","<字段2>"]' \
  --group-by '["<分组字段>"]' \
  --aggregations '[{"field_name":"<数值字段>","type":"sum"}]' \
  --format json

Common aggregation types:

sum — Sum (amount, quantity)
average — Average
max / min — Maximum/minimum value
count — Count
counta — Non-empty count

Note：+data-query supports --filter parameter for conditional filtering. Use --page-size to control the returned amount.

# 获取记录样本（当需要逐行分析时）
lark-cli base +record-list --base-token "<base_token>" --table-id "<table_id>" \
  --page-size 100 --format json

⚠️ Data volume control: Base returns at most 500 records at a time. If the data volume is large, use --page-token pagination to retrieve it, but for analysis scenarios, aggregate queries (+data-query) are usually more efficient.

⚠️ JSON input validation (v1.0.11+): Base shortcut commands now validate JSON input and reject null objects. Ensure that the passed --filter、--aggregations and other JSON parameters are not null but valid JSON objects or arrays; when empty, simply omit the parameter.

Keyword search for anomalous records (v1.0.8+):

# 按关键词搜索记录（适合快速定位异常数据）
lark-cli base +record-search --base-token "<base_token>" --table-id "<table_id>" \
  --query "<关键词>" --format json

Tip：+record-search Suitable for quickly locating records that contain specific text (such as error statuses or abnormal notes), more efficient than +record-list + manual filtering.

Use record field filtering (v1.0.8+):

# 通过字段过滤精确获取特定条件的记录
lark-cli base +record-list --base-token "<base_token>" --table-id "<table_id>" \
  --filter '<过滤条件>' --page-size 100 --format json

Tip: Field filtering can complete data filtering on the server side, greatly reducing the amount of returned data, and is suitable for large-table analysis scenarios.

Step 4: AI analysis engine

Based on the table structure and aggregation results, AI performs the following analysis:

4.1 Trend analysis (when there is a date field):

Aggregate numeric fields by day/week/month
Identify growth/decline trends
Calculate period-over-period/year-over-year change rates

4.2 Distribution analysis (when there are option fields):

Quantity and proportion of each option value
Identify concentration (whether it is severely skewed)

4.3 Anomaly detection:

Extreme values in numeric fields (>3σ)
Proportion of missing values
Data consistency check (such as whether date fields contain future dates)

4.4 Correlation analysis (when there are multiple numeric fields):

Inference of correlation between fields
Cross-group comparison

Step 5: Generate analysis report

## 📊 多维表格分析报告

### 数据概览
- **表名**：{表名}
- **字段数**：{N} 个（{M} 个数值字段，{P} 个选项字段）
- **记录总数**：{count} 条
- **时间跨度**：{最早日期} ~ {最晚日期}

### 📈 关键指标
| 指标 | 值 | 趋势 |
|------|---|------|
| {数值字段1} 总计 | ¥1,234,567 | 📈 +12.3% 环比 |
| {数值字段2} 平均 | 85.6 | 📉 -3.2% 环比 |
| 记录增长 | 本月 +45 条 | 📈 |

### 📊 分布分析
**{选项字段名} 分布：**
| 值 | 数量 | 占比 | 可视化 |
|----|------|------|--------|
| 进行中 | 45 | 38% | ████████░░ |
| 已完成 | 52 | 44% | █████████░ |
| 已取消 | 21 | 18% | ████░░░░░░ |

### 📈 时间趋势
**{数值字段} 月度趋势：**
| 月份 | 值 | 环比变化 |
|------|---|---------|
| 1月 | 120,000 | — |
| 2月 | 135,000 | +12.5% |
| 3月 | 128,000 | -5.2% |

### ⚠️ 异常与问题
- ⚠️ "{字段X}" 有 {N} 条空值（占比 {P}%）
- ⚠️ 记录 #{id} 的 "{字段Y}" 值异常偏高（{值}，是平均值的 {倍数} 倍）
- ⚠️ 最近 7 天无新增记录

### 💡 洞察与建议
1. **{洞察 1}**：基于趋势数据推导的结论
2. **{洞察 2}**：基于分布数据推导的建议
3. **{洞察 3}**：基于异常检测的告警或建议行动

Step 6: Write back to document (optional, when requested by the user)

Refer to lark-doc/SKILL.md。

lark-cli docs +create --title "数据分析报告：{表名} (<date>)" --markdown "<报告内容>"

Step 7: Generate dashboard (optional, v1.0.8+)

When the user needs to display analysis results directly within Base, you can use +dashboard-arrange to automatically arrange the dashboard:

# 在 Base 仪表盘中添加 Markdown 文本块并自动排列
lark-cli base +dashboard-arrange --base-token "<base_token>" \
  --dashboard-id "<dashboard_id>" --format json

Tip: v1.0.8 newly adds text block type supports Markdown content, allowing the analysis summary to be embedded directly into the dashboard.

Fault tolerance mechanism

Abnormal scenario	Handling method
Table has no numeric fields	Only perform distribution analysis and record statistics, do not perform trend analysis
Table has no date field	Skip time trend analysis, mark "no time dimension"
Data volume >500 records	Use `+data-query` aggregate queries, do not fetch row by row
Table is empty (0 records)	Prompt "this table currently has no data"
Field type cannot be aggregated	Skip this field and analyze other aggregatable fields
base_token has no permission	Prompt the user to check Base sharing permissions

Permission table

Step	Command	Required scope	Required?
Table structure	`base +table-list` / `+field-list`	`bitable:bitable:readonly`	✅ Required
Data aggregation	`base +data-query`	`bitable:bitable:readonly`	✅ Required
Record list	`base +record-list`	`bitable:bitable:readonly`	Optional (when analyzing row by row)
Keyword search	`base +record-search`	`bitable:bitable:readonly`	Optional (when locating anomalies)
Generate report	`docs +create`	`docx:document:write`	Optional (when writing back)
Dashboard arrangement	`base +dashboard-arrange`	`bitable:bitable`	Optional (when dashboarding)

Reference

lark-shared — Authentication, permissions (must read)
lark-base — +field-list、+data-query、+record-list detailed usage
lark-doc — +create detailed usage