165 lines
4.8 KiB
Markdown
165 lines
4.8 KiB
Markdown
---
|
||
name: bitable-reader
|
||
version: 1.0.0
|
||
description: "通用飞书多维表格结构读取技能。读取任意多维表格的表结构、字段定义、记录数据，自动处理分页和JSON字段解析。适用于内容发现、配置提取、数据分析等场景。"
|
||
metadata:
|
||
requires:
|
||
permissions: ["bitable:app:readonly", "wiki:node:retrieve"]
|
||
triggers:
|
||
- "用户提供多维表格链接（wiki/bitable）要求查看内容"
|
||
- "需要从多维表格提取配置数据做分析"
|
||
- "需要了解某个多维表格的字3段结构和数据格式"
|
||
---
|
||
|
||
# bitable-reader — 多维表格通用读取技能
|
||
|
||
## 身份规则
|
||
- 所有读取操作**永远使用 Bot 身份**（`--as bot` / Bot tenant_access_token）
|
||
- 禁止触发用户授权弹窗
|
||
- 只读操作，绝不写入或删除
|
||
|
||
## 执行链路
|
||
|
||
### 步骤 0：获取 Bot 凭据
|
||
|
||
```bash
|
||
TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"app_id":"cli_a931175d41799cc7","app_secret":"Iw2vEfbjT6GtV0GhbxbZqfQ4nAPtbR14"}' \
|
||
| python3 -c "import sys,json; print(json.load(sys.stdin)['tenant_access_token'])")
|
||
```
|
||
|
||
Token 有效期 2 小时，同一会话复用即可。
|
||
|
||
### 步骤 1：定位多维表格
|
||
|
||
#### 1a. 从 wiki 链接进入
|
||
```
|
||
链接：https://xxx.feishu.cn/wiki/XXXXXX
|
||
↓
|
||
提取 wiki_token = "XXXXXX"
|
||
↓
|
||
lark-cli wiki spaces get_node --params '{"token":"XXXXXX"}' --as bot
|
||
```
|
||
|
||
若返回 `has_child: true` 且非 bitable，遍历子节点（步骤 1b）。
|
||
|
||
#### 1b. 遍历 wiki 子目录
|
||
```bash
|
||
curl -s -X GET \
|
||
"https://open.feishu.cn/open-apis/wiki/v2/spaces/<space_id>/nodes?parent_node_token=<node_token>" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
分页用 `page_token` 参数。
|
||
|
||
#### 1c. 确认目标为 bitable
|
||
Node 的 `obj_type` 为 `"bitable"` 时，`obj_token` 即为 `app_token`。
|
||
|
||
#### 1d. 直接提供 app_token 时
|
||
跳过上述步骤，直接进入步骤 2。
|
||
|
||
### 步骤 2：列出所有数据表
|
||
|
||
```bash
|
||
curl -s -X GET \
|
||
"https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
返回结构：
|
||
```json
|
||
{
|
||
"data": {
|
||
"has_more": false,
|
||
"items": [
|
||
{"name": "S0", "revision": 1445, "table_id": "tblXXXXXX"},
|
||
{"name": "S1", "revision": 3150, "table_id": "tblYYYYYY"}
|
||
],
|
||
"page_token": "...",
|
||
"total": 7
|
||
}
|
||
}
|
||
```
|
||
|
||
### 步骤 3：获取表字段结构
|
||
|
||
```bash
|
||
curl -s -X GET \
|
||
"https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables/<table_id>/fields" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
返回每个字段的 `field_name` 和 `type`（类型代码对照表见附录）。
|
||
|
||
### 步骤 4：读取记录数据
|
||
|
||
#### 4a. 全量分页读取
|
||
```bash
|
||
curl -s -X GET \
|
||
"https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables/<table_id>/records?page_size=100" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
用返回的 `has_more` + `page_token` 循环翻页。
|
||
|
||
#### 4b. 按 ID 精读单条
|
||
```bash
|
||
curl -s -X GET \
|
||
"https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables/<table_id>/records/<record_id>" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
### 步骤 5：解析输出
|
||
|
||
每条记录返回：
|
||
```json
|
||
{
|
||
"record_id": "recXXXXXX",
|
||
"fields": {
|
||
"ID": "0000001",
|
||
"taskData": "{...JSON string...}",
|
||
"textData": "{...JSON string...}",
|
||
...
|
||
}
|
||
}
|
||
```
|
||
|
||
**重要：** 长文本/JSON 字段在多维表格中以 **字符串** 形式存储，需用 `json.loads()` 反序列化后再分析内部结构。
|
||
|
||
## 常见字段类型说明
|
||
|
||
| type | 含义 | 读取形式 |
|
||
|------|------|---------|
|
||
| 1 | 文本 | 字符串 |
|
||
| 2 | 数字 | 数字 |
|
||
| 3 | 单选 | 字符串 |
|
||
| 4 | 多选 | 字符串数组 |
|
||
| 5 | 日期 | Unix 毫秒时间戳 |
|
||
| 7 | 复选框 | 布尔 |
|
||
| 17 | 文本（长） | 字符串（含 JSON） |
|
||
| 20 | URL | 对象 `{link, text}` |
|
||
| 21 | 附件 | 对象数组 `[{file_token, name, ...}]` |
|
||
|
||
## 典型使用模式
|
||
|
||
### 模式 A：探索未知表结构
|
||
1. 列出所有表 → 展示表名/revision
|
||
2. 用户选择目标表 → 读取字段结构
|
||
3. 采样 2–3 条记录 → 分析 JSON 字段结构
|
||
4. 归纳输出字段含义和内容模式
|
||
|
||
### 模式 B：批量导出特定字段
|
||
1. 已知 table_id 和目标字段名
|
||
2. 全量分页读取
|
||
3. 提取目标字段 → 解析 JSON → 汇总
|
||
|
||
### 模式 C：按条件检索
|
||
1. 已知 ID 范围或关键词
|
||
2. 全量读取后本地过滤（bitable API 筛选较受限）
|
||
|
||
## 注意事项
|
||
- 含 JSON 的字段（如 `taskData`, `learningData`）读取后为普通字符串，需显式 `json.loads()`
|
||
- 部分表格可能包含内嵌 Sheet（`<sheet token="..."/>`），需用 `feishu-embedded-sheet` 技能处理
|
||
- 读取大表（revision > 5000）时注意 API 限流，建议逐页 `sleep 0.3s`
|
||
- 若返回 `99991663` 错误，重新获取 token 后重试
|