飞书多维表格操作

技能文档

---
name: bitable-crud-ops
description: 飞书多维表格CRUD操作技能，支持自动解析Wiki链接获取真实app_token，正确处理记录创建、读取、更新和删除操作。
title: 飞书多维表格操作
category: 办公效率
---

# 飞书多维表格 CRUD 操作

你是一位飞书多维表格操作专家，帮助用户通过 API 高效管理多维表格数据。

## 核心能力

### 关键特性：Wiki 链接自动解析

飞书文档链接分为两种类型，需要正确区分：
- **Wiki 链接**：`https://xxx.feishu.cn/wiki/xxxx`（node_token）
- **多维表格链接**：`https://xxx.feishu.cn/base/xxxx`（app_token）

Wiki 链接中的 token 是 `node_token`，不能直接用于多维表格 API。必须先解析获取真实的 `app_token`。

**解析方法**：
```bash
# 通过飞书 API 解析 Wiki node_token 获取真实 app_token
curl -X GET "https://open.feishu.cn/open-apis/wiki/v2/spaces/get_node?token=<node_token>" \
  -H "Authorization: Bearer <tenant_access_token>"

# 返回结果中的 obj_token 即为真实的 app_token
{
  "data": {
    "node": {
      "obj_token": "真实的多维表格 app_token",
      "obj_type": "bitable"
    }
  }
}
```

### 1. 创建记录

```bash
# 向多维表格添加新记录
curl -X POST "https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables/<table_id>/records" \
  -H "Authorization: Bearer <tenant_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "名称": "示例记录",
      "状态": "进行中",
      "负责人": [{"id": "ou_xxxxx"}],
      "截止日期": 1700000000000,
      "金额": 10000.00,
      "标签": ["重要", "紧急"],
      "附件": [{"file_token": "boxcnXXXXXX"}]
    }
  }'
```

### 2. 读取记录

```bash
# 查询单条记录
curl -X GET "https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables/<table_id>/records/<record_id>" \
  -H "Authorization: Bearer <tenant_access_token>"

# 批量查询记录（支持过滤和排序）
curl -X POST "https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables/<table_id>/records/search" \
  -H "Authorization: Bearer <tenant_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "conjunction": "and",
      "conditions": [
        {"field_name": "状态", "operator": "is", "value": ["进行中"]},
        {"field_name": "金额", "operator": "isGreater", "value": ["5000"]}
      ]
    },
    "sort": [
      {"field_name": "截止日期", "order": "asc"}
    ],
    "page_size": 20
  }'
```

### 3. 更新记录

```bash
# 更新单条记录
curl -X PUT "https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables/<table_id>/records/<record_id>" \
  -H "Authorization: Bearer <tenant_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "状态": "已完成",
      "完成日期": 1700100000000
    }
  }'

# 批量更新记录
curl -X POST "https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables/<table_id>/records/batch_update" \
  -H "Authorization: Bearer <tenant_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {"record_id": "recXXXXX1", "fields": {"状态": "已完成"}},
      {"record_id": "recXXXXX2", "fields": {"状态": "已取消"}}
    ]
  }'
```

### 4. 删除记录

```bash
# 删除单条记录
curl -X DELETE "https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables/<table_id>/records/<record_id>" \
  -H "Authorization: Bearer <tenant_access_token>"

# 批量删除记录
curl -X POST "https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables/<table_id>/records/batch_delete" \
  -H "Authorization: Bearer <tenant_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": ["recXXXXX1", "recXXXXX2", "recXXXXX3"]
  }'
```

## 字段类型参考

| 字段类型 | API 值格式 | 示例 |
|----------|-----------|------|
| 文本 | 字符串 | `"项目名称"` |
| 数字 | 数字 | `100.5` |
| 单选 | 字符串 | `"进行中"` |
| 多选 | 字符串数组 | `["标签1", "标签2"]` |
| 日期 | 毫秒时间戳 | `1700000000000` |
| 复选框 | 布尔值 | `true` |
| 人员 | 对象数组 | `[{"id": "ou_xxx"}]` |
| 附件 | 对象数组 | `[{"file_token": "boxcnXXX"}]` |
| 链接 | 对象 | `{"text": "显示文本", "link": "https://..."}` |
| 公式 | 只读 | 自动计算 |

## 认证配置

需要以下环境变量：
- `FEISHU_APP_ID`：飞书应用 ID
- `FEISHU_APP_SECRET`：飞书应用密钥
- `FEISHU_USER_OPEN_ID`：用户 Open ID（可选）

获取 tenant_access_token：
```bash
curl -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d '{"app_id": "<APP_ID>", "app_secret": "<APP_SECRET>"}'
```

## 输出格式

操作结果应包含：
1. **操作类型**：创建/读取/更新/删除
2. **操作结果**：成功/失败
3. **数据详情**：返回的记录内容
4. **分页信息**：如有分页，提供下一页的 page_token

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。