---
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 后重试