npm package: @loobayn/n8n-nodes-feishu-bitable
Description: n8n community node for Feishu/Lark Bitable - Read, write and manage Feishu Bitable data with simple text filter syntax
Author: loobayn
Latest version: 0.1.0

# n8n-nodes-feishu-bitable

n8n 飞书多维表格节点 - 读取、写入和管理飞书多维表格数据，支持简单的文本语法筛选。

## 功能特性

| 操作类型 | 功能说明 | 适用场景 |
|----------|----------|----------|
| **读取记录** | 从飞书多维表格获取数据 | 数据同步、报表生成、数据分析 |
| **写入记录** | 向飞书多维表格写入文本数据 | 数据更新、批量导入、状态变更 |
| **上传附件** | 上传文件到附件字段 | 图片存储、文档归档、资源管理 |

## 安装说明

### 方式一：通过 n8n 社区节点安装（推荐）

| 步骤 | 操作位置 | 具体操作 |
|------|----------|----------|
| 1 | n8n 主界面 | 点击左下角 **Settings** 图标 |
| 2 | Settings 页面 | 选择左侧菜单 **Community Nodes** |
| 3 | Community Nodes 页面 | 点击 **Install a community node** 按钮 |
| 4 | 安装对话框 | 输入 `n8n-nodes-feishu-bitable` |
| 5 | 安装对话框 | 点击 **Install** 按钮 |
| 6 | 等待安装完成 | 安装成功后节点会出现在节点列表中 |

### 方式二：手动安装（Docker 环境）

```bash
# 进入 n8n 自定义节点目录
cd ~/.n8n/custom

# 使用 npm 安装
npm install n8n-nodes-feishu-bitable

# 重启 n8n 服务
docker restart n8n
```

### 方式三：本地开发安装

```bash
# 克隆仓库
git clone https://github.com/your-repo/n8n-nodes-feishu-bitable.git

# 进入项目目录
cd n8n-nodes-feishu-bitable

# 安装依赖
npm install

# 构建项目
npm run build

# 链接到 n8n
npm link

# 在 n8n 自定义节点目录中链接
cd ~/.n8n/custom
npm link n8n-nodes-feishu-bitable
```

## 凭证配置

### 步骤 1：创建飞书应用

| 步骤 | 操作位置 | 具体操作 |
|------|----------|----------|
| 1 | 浏览器 | 访问 [飞书开放平台](https://open.feishu.cn) |
| 2 | 开放平台首页 | 点击右上角 **登录** 并完成登录 |
| 3 | 开发者后台 | 点击 **创建企业自建应用** |
| 4 | 创建应用页面 | 填写应用名称（如：n8n 数据同步） |
| 5 | 创建应用页面 | 填写应用描述 |
| 6 | 创建应用页面 | 点击 **创建** 按钮 |

### 步骤 2：获取应用凭证

| 字段名 | 获取位置 | 说明 |
|--------|----------|------|
| **App ID** | 应用详情 → 凭证与基础信息 | 格式如 `cli_xxxxxxxxxx` |
| **App Secret** | 应用详情 → 凭证与基础信息 | 点击"显示"查看，格式为 32 位字符串 |

### 步骤 3：配置应用权限

在飞书开放平台的应用详情页，进入 **权限管理** → **API 权限**，开启以下权限：

| 权限名称 | 权限标识 | 用途 |
|----------|----------|------|
| 查看、评论、编辑和管理多维表格 | `bitable:app` | 读取和写入表格数据 |
| 上传、下载文件 | `drive:drive` | 上传附件文件 |

### 步骤 4：在 n8n 中配置凭证

| 步骤 | 操作位置 | 具体操作 |
|------|----------|----------|
| 1 | n8n 主界面 | 点击左侧 **Credentials** |
| 2 | Credentials 页面 | 点击 **Add Credential** |
| 3 | 选择凭证类型 | 搜索并选择 **Feishu Bitable API** |
| 4 | 凭证配置页面 | 填写 App ID |
| 5 | 凭证配置页面 | 填写 App Secret |
| 6 | 凭证配置页面 | 点击 **Save** 保存 |

## 节点配置说明

### 通用字段

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| **凭证** | 下拉选择 | ✅ | 选择已配置的 Feishu Bitable API 凭证 |
| **操作类型** | 下拉选择 | ✅ | 选择：读取记录 / 写入记录 / 上传附件 |
| **表格链接** | 文本 | ✅ | 粘贴飞书多维表格的完整链接 |

### 表格链接格式

支持以下链接格式：

```
# 标准格式
https://xxx.feishu.cn/base/{app_token}?table={table_id}

# 带视图参数（视图参数会被忽略）
https://xxx.feishu.cn/base/{app_token}?table={table_id}&view={view_id}

# 示例
https://example.feishu.cn/base/bascnXXXXXXXXXX?table=tblXXXXXXXXXX
```

### 读取记录操作

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| **输出列** | 多行文本 | ❌ | 每行一个列名，留空返回所有列 |
| **筛选条件** | 多行文本 | ❌ | 每行一条筛选规则，语法见下文 |
| **最大行数** | 数字 | ❌ | 限制返回的最大记录数，默认无限制 |

### 写入记录操作

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| **目标列** | 文本 | ✅ | 要写入数据的列名 |
| **写入内容** | 文本 | ✅ | 要写入的内容，支持表达式 |
| **筛选条件** | 多行文本 | ❌ | 筛选要更新的记录 |
| **新增行** | 开关 | ❌ | 开启后创建新记录而非更新 |
| **新增行数** | 数字 | ❌ | 新增行模式下要创建的行数（1-100） |

### 上传附件操作

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| **目标列** | 文本 | ✅ | 附件字段的列名 |
| **二进制属性** | 文本 | ✅ | 包含文件数据的二进制属性名 |
| **筛选条件** | 多行文本 | ❌ | 筛选要添加附件的记录 |
| **新增行** | 开关 | ❌ | 开启后创建新记录并添加附件 |

## 筛选条件语法

本节点支持简单的文本语法来筛选表格记录，无需编写复杂的 JSON 配置。

### 基本语法

| 语法格式 | 功能说明 | 示例 |
|----------|----------|------|
| `列名+关键词` | 仅包含该列包含关键词的行 | `状态+进行中` |
| `列名-关键词` | 排除该列包含关键词的行 | `状态-已完成` |
| `列名+空值` | 仅包含该列为空的行 | `备注+空值` |
| `列名-空值` | 排除该列为空的行 | `备注-空值` |
| `列名+非空值` | 仅包含该列非空的行 | `备注+非空值` |
| `列名-非空值` | 排除该列非空的行 | `备注-非空值` |

### 多条件组合规则

| 条件类型 | 组合逻辑 | 说明 |
|----------|----------|------|
| 包含条件（+） | AND | 记录必须同时满足所有包含条件 |
| 排除条件（-） | OR | 记录只要满足任一排除条件就会被排除 |

### 匹配规则

| 规则 | 说明 |
|------|------|
| 大小写不敏感 | `状态+进行中` 会匹配 "进行中"、"JINXINGZHONG" 等 |
| 包含匹配 | `标题+报告` 会匹配 "月度报告"、"报告总结" 等 |
| 列表字段 | 对于多选字段，任一选项匹配即可 |

### 筛选示例

```
# 示例 1：筛选状态为"进行中"且优先级为"高"的记录
状态+进行中
优先级+高

# 示例 2：筛选有负责人的记录
负责人+非空值

# 示例 3：排除已完成和已取消的记录
状态-已完成
状态-已取消

# 示例 4：筛选标题包含"报告"且备注不为空的记录
标题+报告
备注-空值
```

## 使用示例

### 示例 1：读取表格数据

**场景**：从飞书多维表格读取所有"进行中"的任务

**节点配置**：

| 字段 | 值 |
|------|-----|
| 操作类型 | 读取记录 |
| 表格链接 | `https://example.feishu.cn/base/bascnXXX?table=tblXXX` |
| 输出列 | `标题`<br>`状态`<br>`负责人`<br>`截止日期` |
| 筛选条件 | `状态+进行中` |

### 示例 2：更新记录状态

**场景**：将所有"待处理"的任务状态更新为"进行中"

**节点配置**：

| 字段 | 值 |
|------|-----|
| 操作类型 | 写入记录 |
| 表格链接 | `https://example.feishu.cn/base/bascnXXX?table=tblXXX` |
| 目标列 | `状态` |
| 写入内容 | `进行中` |
| 筛选条件 | `状态+待处理` |

### 示例 3：批量新增记录

**场景**：批量创建 5 条新任务记录

**节点配置**：

| 字段 | 值 |
|------|-----|
| 操作类型 | 写入记录 |
| 表格链接 | `https://example.feishu.cn/base/bascnXXX?table=tblXXX` |
| 目标列 | `标题` |
| 写入内容 | `{{ $json.taskName }}` |
| 新增行 | ✅ 开启 |
| 新增行数 | `5` |

### 示例 4：上传图片附件

**场景**：将工作流中的图片上传到表格的附件字段

**节点配置**：

| 字段 | 值 |
|------|-----|
| 操作类型 | 上传附件 |
| 表格链接 | `https://example.feishu.cn/base/bascnXXX?table=tblXXX` |
| 目标列 | `附件` |
| 二进制属性 | `data` |
| 筛选条件 | `任务ID+{{ $json.taskId }}` |

## 输出格式

### 读取操作输出

```json
{
  "records": [
    {
      "record_id": "recXXXXXXXX",
      "标题": "任务标题",
      "状态": "进行中",
      "负责人": [
        {
          "id": "ou_xxxxx",
          "name": "张三"
        }
      ],
      "截止日期": 1703980800000,
      "备注": null
    }
  ],
  "status": "success",
  "affectedCount": 1,
  "message": "成功读取 1 条记录"
}
```

### 写入操作输出

```json
{
  "status": "success",
  "affectedCount": 5,
  "message": "成功更新 5 条记录"
}
```

### 附件上传输出

```json
{
  "status": "success",
  "affectedCount": 1,
  "message": "成功上传附件到 1 条记录",
  "fileToken": "boxcnXXXXXXXX"
}
```

## 测试验证

### 验证凭证配置

在 n8n 凭证配置页面点击 **Test** 按钮，预期结果：

| 结果 | 说明 |
|------|------|
| ✅ Connection tested successfully | 凭证配置正确 |
| ❌ Invalid credentials | App ID 或 App Secret 错误 |

### 验证节点功能

1. 创建一个简单的工作流
2. 添加 **Manual Trigger** 节点
3. 添加 **Feishu Bitable** 节点
4. 配置读取操作，不设置筛选条件
5. 执行工作流，检查是否能获取到表格数据

### 验证检查项

| 检查项 | 预期结果 |
|--------|----------|
| 节点出现在节点列表 | 搜索"飞书"或"Feishu"可找到 |
| 凭证测试通过 | 显示连接成功 |
| 读取操作正常 | 返回表格记录数据 |
| 筛选条件生效 | 返回符合条件的记录 |
| 写入操作正常 | 表格数据被更新 |

## 问题排查

| 问题现象 | 检查项 | 解决方法 |
|----------|--------|----------|
| 凭证测试失败 | App ID 和 App Secret 是否正确 | 重新从飞书开放平台复制凭证 |
| 无法访问表格 | 应用是否有表格权限 | 在飞书开放平台开启 `bitable:app` 权限 |
| 无法访问表格 | 表格是否授权给应用 | 在表格设置中添加应用为协作者 |
| 链接解析失败 | 链接格式是否正确 | 确保链接包含 `base/` 和 `table=` |
| 筛选无结果 | 列名是否正确 | 检查列名是否与表格中完全一致 |
| 筛选无结果 | 关键词是否存在 | 检查表格中是否有匹配的数据 |
| 写入失败 | 目标列是否存在 | 检查列名是否正确 |
| 写入失败 | 字段类型是否匹配 | 确保写入内容与字段类型兼容 |
| 附件上传失败 | 是否有云盘权限 | 开启 `drive:drive` 权限 |
| 附件上传失败 | 目标列是否为附件类型 | 确保目标列是附件字段 |
| 请求超时 | 网络是否正常 | 检查网络连接，稍后重试 |
| 请求过于频繁 | 是否触发限流 | 等待一段时间后重试 |

## 配置清单

### 飞书开放平台配置

| 配置项 | 位置 | 值 |
|--------|------|-----|
| 应用类型 | 创建应用时选择 | 企业自建应用 |
| API 权限 - 多维表格 | 权限管理 → API 权限 | `bitable:app` |
| API 权限 - 云盘 | 权限管理 → API 权限 | `drive:drive` |

### n8n 凭证配置

| 字段 | 来源 | 格式 |
|------|------|------|
| App ID | 飞书开放平台 → 应用详情 → 凭证与基础信息 | `cli_xxxxxxxxxx` |
| App Secret | 飞书开放平台 → 应用详情 → 凭证与基础信息 | 32 位字符串 |

### 表格授权配置

| 配置项 | 位置 | 操作 |
|--------|------|------|
| 添加应用为协作者 | 表格右上角 → 分享 → 添加协作者 | 搜索并添加应用 |
| 设置权限级别 | 添加协作者时选择 | 选择"可编辑"或"可管理" |

## 开发指南

### 环境要求

| 依赖 | 版本要求 |
|------|----------|
| Node.js | >= 18.10 |
| npm | >= 9.0 |

### 开发命令

```bash
# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

# 运行测试（监听模式）
npm run test:watch

# 代码检查
npm run lint

# 代码格式化
npm run format
```

### 项目结构

```
n8n-nodes-feishu-bitable/
├── credentials/
│   └── FeishuBitableApi.credentials.ts  # 凭证定义
├── nodes/
│   └── FeishuBitable/
│       ├── FeishuBitable.node.ts        # 节点主体
│       ├── FeishuApiClient.ts           # API 客户端
│       ├── FilterParser.ts              # 筛选条件解析器
│       ├── UrlParser.ts                 # 链接解析器
│       └── feishu.svg                   # 节点图标
├── dist/                                # 构建输出
├── package.json
├── tsconfig.json
└── README.md
```

## 许可证

MIT License

## 相关链接

- [Docker 本地测试部署指南](./docs/DOCKER_DEPLOYMENT.md)
- [飞书开放平台](https://open.feishu.cn)
- [飞书多维表格 API 文档](https://open.feishu.cn/document/server-docs/docs/bitable-v1/bitable-overview)
- [n8n 官方文档](https://docs.n8n.io)
- [n8n 社区节点开发指南](https://docs.n8n.io/integrations/creating-nodes/)