---
name: feishu-bitable
description: 飞书多维表格操作。用于记录增删改查、批量操作、筛选排序、数据同步。当需要操作飞书多维表格时使用。
---

# 飞书多维表格 (Bitable)

## URL 结构

```
https://xxx.feishu.cn/base/BascXXX?table=tblXXX&view=vewXXX
                          └── app_token  └── table_id
```

## 核心操作

### 列出记录

```python
def list_records(app_token, table_id, filter_str=None, page_size=100):
    url = f"https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records"
    params = {"page_size": page_size}
    if filter_str:
        params["filter"] = filter_str
    response = requests.get(url, headers=headers, params=params)
    return response.json()["data"]["items"]
```

### 创建记录

```python
def create_record(app_token, table_id, fields):
    url = f"https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records"
    response = requests.post(url, headers=headers, json={"fields": fields})
    return response.json()["data"]["record"]

# 示例
create_record("BascXXX", "tblXXX", {"任务名称": "完成开发", "状态": "进行中"})
```

### 批量创建 (最多 500 条)

```python
url = f".../records/batch_create"
requests.post(url, headers=headers, json={"records": [{"fields": {...}}, ...]})
```

### 更新记录

```python
def update_record(app_token, table_id, record_id, fields):
    url = f".../records/{record_id}"
    response = requests.put(url, headers=headers, json={"fields": fields})
    return response.json()["data"]["record"]
```

### 删除记录

```python
def delete_record(app_token, table_id, record_id):
    url = f".../records/{record_id}"
    return requests.delete(url, headers=headers).json()
```

## 筛选条件

```python
# 等于
'CurrentValue.[状态]="进行中"'

# 包含
'CurrentValue.[标题].contains("任务")'

# 大于（数字/日期）
'CurrentValue.[优先级]>2'

# 组合
'AND(CurrentValue.[状态]="进行中", CurrentValue.[优先级]>2)'
'OR(CurrentValue.[状态]="完成", CurrentValue.[状态]="归档")'

# 空值
'CurrentValue.[截止日期]=BLANK()'
```

## 排序

```python
params = {
    "sort": '[{"field_name":"优先级","desc":true}]'
}
```

## 字段类型

| 类型 | 值格式 |
|------|--------|
| 文本 | `"字符串"` |
| 数字 | `123` |
| 单选 | `"选项值"` |
| 多选 | `["选项1", "选项2"]` |
| 日期 | `1706400000000` (毫秒时间戳) |
| 人员 | `[{"id": "ou_xxx"}]` |
| 复选框 | `true/false` |
| 链接 | `{"link": "https://...", "text": "显示文本"}` |

## 完整工具类

见 `~/.claude/skills/feishu/feishu_bitable.py`

```python
from feishu_bitable import FeishuBitable

bitable = FeishuBitable()
records = bitable.list_records("BascXXX", "tblXXX")
bitable.create_record("BascXXX", "tblXXX", {"名称": "测试"})
bitable.batch_create("BascXXX", "tblXXX", [{"名称": "1"}, {"名称": "2"}])
```

## 常见场景

```python
# 获取待处理任务
tasks = bitable.list_records("BascXXX", "tblXXX",
    filter_str='CurrentValue.[状态]="待处理"')

# 批量更新状态
for task in tasks:
    bitable.update_record("BascXXX", "tblXXX",
        task["record_id"], {"状态": "已完成"})
```