ai_member_only/ai_member_xiaoyan

Fork 0

ai_member_only f013d6f6ef auto backup: 2026-05-13 08:10:01

2026-05-13 08:10:01 +08:00

4.8 KiB

Raw Blame History

name

version

description

metadata

bitable-reader

1.0.0

通用飞书多维表格结构读取技能。读取任意多维表格的表结构、字段定义、记录数据，自动处理分页和JSON字段解析。适用于内容发现、配置提取、数据分析等场景。

requires

triggers

permissions

bitable:app:readonly

wiki:node:retrieve

用户提供多维表格链接（wiki/bitable）要求查看内容

需要从多维表格提取配置数据做分析

需要了解某个多维表格的字3段结构和数据格式

bitable-reader — 多维表格通用读取技能

身份规则

所有读取操作永远使用 Bot 身份（--as bot / Bot tenant_access_token）
禁止触发用户授权弹窗
只读操作，绝不写入或删除

执行链路

步骤 0：获取 Bot 凭据

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 子目录

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：列出所有数据表

curl -s -X GET \
  "https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables" \
  -H "Authorization: Bearer $TOKEN"

返回结构：

{
  "data": {
    "has_more": false,
    "items": [
      {"name": "S0", "revision": 1445, "table_id": "tblXXXXXX"},
      {"name": "S1", "revision": 3150, "table_id": "tblYYYYYY"}
    ],
    "page_token": "...",
    "total": 7
  }
}

步骤 3：获取表字段结构

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. 全量分页读取

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 精读单条

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：解析输出

每条记录返回：

{
  "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：探索未知表结构

列出所有表 → 展示表名/revision
用户选择目标表 → 读取字段结构
采样 2–3 条记录 → 分析 JSON 字段结构
归纳输出字段含义和内容模式

模式 B：批量导出特定字段

已知 table_id 和目标字段名
全量分页读取
提取目标字段 → 解析 JSON → 汇总

模式 C：按条件检索

已知 ID 范围或关键词
全量读取后本地过滤（bitable API 筛选较受限）

注意事项

含 JSON 的字段（如 taskData, learningData）读取后为普通字符串，需显式 json.loads()
部分表格可能包含内嵌 Sheet（<sheet token="..."/>），需用 feishu-embedded-sheet 技能处理
读取大表（revision > 5000）时注意 API 限流，建议逐页 sleep 0.3s
若返回 99991663 错误，重新获取 token 后重试

4.8 KiB Raw Blame History Unescape Escape