feishu-bitable

Category: Tools & Productivity | Uploader: Larkin0302 | Downloads: 0 | Version: v1.0（Latest）

飞书多维表格的完整生命周期管理：从零搭建 + 日常 CRUD 操作。 **当以下情况时使用此 Skill**： (1) 用户说"搭建多维表格"、"做一个XX表"、"搭一个XX系统" (2) 用户描述业务需求并希望用多维表格实现 (3) 需要查询、新增、修改、删除多维表格中的记录 (4) 需要管理字段、视图、数据表 (5) 需要批量导入数据或批量更新 (6) 用户提到"多维表格"、"bitable"、"数据表"、"记录"、"字段" --- > **⚠️ 最高优先级指令 — 创建多维表格的唯一方式：** > > 当用户要求「搭建」「做一个」「搭一个」多维表格系统时，**必须按顺序完成以下 3 步**： > > **第 1 步：设计 JSON 配置并调用脚本创建表** > ``` > exec(command='cat > /tmp/bitable_config.json << ...') > exec(command='python3 ~/.openclaw/skills/feishu-bitable/scripts/create_bitable_template.py --config /tmp/bitable_config.json') > ``` > > **第 2 步：用脚本生成的 Markdown 创建配置文档（禁止跳过！禁止自己写内容！）** > ``` > exec(command='cat /tmp/bitable_config_doc.md') ← 读取脚本自动生成的完整 Markdown > feishu_create_doc(title="从 __CONFIG_DOC_TITLE__ 获取", markdown="上面 cat 的完整内容") > ``` > > **第 3 步：向用户汇报** > 告知多维表格链接 + 配置文档链接 + 需手动完善的事项。 > > **禁止使用 feishu_bitable_app 工具创建！禁止让用户手动创建！禁止跳过配置文档！禁止自己编写配置文档内容！** # 飞书多维表格技能你是一个多维表格专家。覆盖**从零搭建**到**日常操作**的完整生命周期。 ## 架构 - **从零搭建** → 调用 Python 脚本（Phase 1-4，确定性执行，无默认字段/空行问题） - **日常操作** → 用飞书插件的 `feishu_bitable_*` 工具（查询、新增、修改、删除、批量操作） - **凭据** → 脚本自动从 OpenClaw 配置读取，与飞书插件共用同一应用 **判断用哪个路径：** - 用户要"搭建"/"做一个"/"搭一个" → Phase 1-4（脚本搭建） - 用户要"查记录"/"加一行"/"改字段"/"导入数据" → 日常 CRUD 操作 --- # 一、从零搭建（Phase 1-4） **⚠️ 禁止手动调用 feishu_bitable_* 工具创建表！必须用脚本！** 飞书 API 创建表时会自动附带默认字段（多行文本、单选、日期、附件）和空行，只有脚本能从源头避免。 ## Phase 1: 需求分析（内部思考，禁止向用户提问） > **⚠️ 铁律：禁止向用户提问！禁止问澄清问题！直接读模式库 → 设计 JSON → 搭建！** > > 用户说"搭建XX系统"时，你必须**立刻开始搭建**，不要问"你需要哪些模块"、"你的业务是什么"等问题。 > 用户可以在搭建完成后通过配置文档的「修改意见区」提出修改。 **内部分析（不输出给用户）**，用六问法快速拆解： | | 问题 | 决定 | |--|------|------| | Q1 | 涉及几类数据？ | 建几张表 | | Q2 | 关联关系？（1:N / N:N） | 单向/双向关联 | | Q3 | 核心指标？ | 公式/汇总 | | Q4 | 数据从哪来？ | 录入方式 | | Q5 | 数据到哪去？ | 输出方式 | | Q6 | 谁在哪个节点消费？ | 视图和权限 | 读取实战模式库（详见 [references/system-patterns.md](references/system-patterns.md)），匹配最接近的模式： - "项目管理"/"任务管理" → 项目管理模式 - "客户"/"销售"/"CRM" → CRM 模式 - "库存"/"进销存" → 进销存模式 - "工单"/"售后" → 工单系统模式 - 其他类型 → 参考最接近的模式，自行设计合理的表结构 **分析完成后立即进入 Phase 2，开始搭建。** --- ## Phase 2: 设计 JSON + 调用脚本搭建 ### 2.1 设计 JSON 配置 ```json { "app_name": "系

Changelog: Source: GitHub https://github.com/Larkin0302/feishu-bitable-skill

Directory Structure

Current level: Root

📁 references/
- 📄 automation-workflow.md 6.9 KB
- 📄 examples.md 16.5 KB
- 📄 field-properties.md 14.1 KB
- 📄 field-type-mapping.md 4.0 KB
- 📄 formula-reference.md 11.3 KB
- 📄 permissions-guide.md 6.1 KB
- 📄 record-values.md 15.3 KB
- 📄 system-patterns.md 7.2 KB
📁 scripts/
- 📄 create_bitable_template.py 92.2 KB
- 📄 feishu_common.py 7.7 KB
📄 .gitignore 29 B
📄 _meta.json 57 B
📄 install.sh 18.5 KB
📄 README.md 3.1 KB
📄 SKILL.md 22.2 KB

SKILL.md

---
name: feishu-bitable
description: |
  飞书多维表格的完整生命周期管理：从零搭建 + 日常 CRUD 操作。
  **当以下情况时使用此 Skill**：
  (1) 用户说"搭建多维表格"、"做一个XX表"、"搭一个XX系统"
  (2) 用户描述业务需求并希望用多维表格实现
  (3) 需要查询、新增、修改、删除多维表格中的记录
  (4) 需要管理字段、视图、数据表
  (5) 需要批量导入数据或批量更新
  (6) 用户提到"多维表格"、"bitable"、"数据表"、"记录"、"字段"
---

> **⚠️ 最高优先级指令 — 创建多维表格的唯一方式：**
>
> 当用户要求「搭建」「做一个」「搭一个」多维表格系统时，**必须按顺序完成以下 3 步**：
>
> **第 1 步：设计 JSON 配置并调用脚本创建表**
> ```
> exec(command='cat > /tmp/bitable_config.json << ...')
> exec(command='python3 ~/.openclaw/skills/feishu-bitable/scripts/create_bitable_template.py --config /tmp/bitable_config.json')
> ```
>
> **第 2 步：用脚本生成的 Markdown 创建配置文档（禁止跳过！禁止自己写内容！）**
> ```
> exec(command='cat /tmp/bitable_config_doc.md')  ← 读取脚本自动生成的完整 Markdown
> feishu_create_doc(title="从 __CONFIG_DOC_TITLE__ 获取", markdown="上面 cat 的完整内容")
> ```
>
> **第 3 步：向用户汇报**
> 告知多维表格链接 + 配置文档链接 + 需手动完善的事项。
>
> **禁止使用 feishu_bitable_app 工具创建！禁止让用户手动创建！禁止跳过配置文档！禁止自己编写配置文档内容！**

# 飞书多维表格技能

你是一个多维表格专家。覆盖**从零搭建**到**日常操作**的完整生命周期。

## 架构

- **从零搭建** → 调用 Python 脚本（Phase 1-4，确定性执行，无默认字段/空行问题）
- **日常操作** → 用飞书插件的 `feishu_bitable_*` 工具（查询、新增、修改、删除、批量操作）
- **凭据** → 脚本自动从 OpenClaw 配置读取，与飞书插件共用同一应用

**判断用哪个路径：**
- 用户要"搭建"/"做一个"/"搭一个" → Phase 1-4（脚本搭建）
- 用户要"查记录"/"加一行"/"改字段"/"导入数据" → 日常 CRUD 操作

---

# 一、从零搭建（Phase 1-4）

**⚠️ 禁止手动调用 feishu_bitable_* 工具创建表！必须用脚本！** 飞书 API 创建表时会自动附带默认字段（多行文本、单选、日期、附件）和空行，只有脚本能从源头避免。

## Phase 1: 需求分析（内部思考，禁止向用户提问）

> **⚠️ 铁律：禁止向用户提问！禁止问澄清问题！直接读模式库 → 设计 JSON → 搭建！**
>
> 用户说"搭建XX系统"时，你必须**立刻开始搭建**，不要问"你需要哪些模块"、"你的业务是什么"等问题。
> 用户可以在搭建完成后通过配置文档的「修改意见区」提出修改。

**内部分析（不输出给用户）**，用六问法快速拆解：

| | 问题 | 决定 |
|--|------|------|
| Q1 | 涉及几类数据？ | 建几张表 |
| Q2 | 关联关系？（1:N / N:N） | 单向/双向关联 |
| Q3 | 核心指标？ | 公式/汇总 |
| Q4 | 数据从哪来？ | 录入方式 |
| Q5 | 数据到哪去？ | 输出方式 |
| Q6 | 谁在哪个节点消费？ | 视图和权限 |

读取实战模式库（详见 [references/system-patterns.md](references/system-patterns.md)），匹配最接近的模式：
- "项目管理"/"任务管理" → 项目管理模式
- "客户"/"销售"/"CRM" → CRM 模式
- "库存"/"进销存" → 进销存模式
- "工单"/"售后" → 工单系统模式
- 其他类型 → 参考最接近的模式，自行设计合理的表结构

**分析完成后立即进入 Phase 2，开始搭建。**

---

## Phase 2: 设计 JSON + 调用脚本搭建

### 2.1 设计 JSON 配置

```json
{
  "app_name": "系统名称",
  "tables": [
    {
      "name": "数据表名",
      "first_field_name": "首字段名",
      "default_view_name": "全部XX",
      "fields": [
        {"field_name": "字段名", "type": 1},
        {"field_name": "状态", "type": 3, "property": {"options": [{"name": "选项1"}, {"name": "选项2"}]}},
        {"field_name": "日期", "type": 5, "property": {"date_formatter": "yyyy/MM/dd"}},
        {"field_name": "金额", "type": 2, "property": {"formatter": "0.00"}}
      ],
      "views": [
        {"view_name": "按状态看板", "view_type": "kanban"}
      ],
      "records": [
        {"首字段名": "示例1", "状态": "选项1", "日期": 1736006400000, "金额": 10000}
      ]
    }
  ]
}
```

**字段类型速查：**

| type | 字段 | property |
|------|------|----------|
| 1 | 文本 | 省略 |
| 2 | 数字 | `formatter:"0.00"` |
| 3 | 单选 | `options:[{name:"选项名"}]` |
| 4 | 多选 | 同单选 |
| 5 | 日期 | `date_formatter:"yyyy/MM/dd"` |
| 7 | 复选框 | 省略 |
| 11 | 人员 | `multiple:bool` |
| 13 | 电话 | 省略 |
| 15 | 超链接 | **property 必须完全省略** |
| 17 | 附件 | 省略 |
| 20 | 公式 | 占位（表达式需手动填写） |
| 99001 | 货币 | `currency_code:"CNY"` |

**视图类型：** `grid`（表格）、`kanban`（看板）、`gallery`（画册）、`gantt`（甘特）。注意：`calendar`（日历）API 不支持创建，脚本会自动跳过并提示用户手动创建。

**记录值：** 字段名作 key，文本=字符串，日期=毫秒时间戳，单选=选项名字符串，数字=数字。

**设计要点：**
- 每张表 3-5 条有意义的示例数据
- 单选字段选项要完整
- 公式字段用 type=20 占位

### 2.2 写入临时文件并执行

```
exec(command='cat > /tmp/bitable_config.json << '"'"'JSONEOF'"'"'
{JSON 内容}
JSONEOF')

exec(command='python3 ~/.openclaw/skills/feishu-bitable/scripts/create_bitable_template.py --config /tmp/bitable_config.json')
```

**可选参数：**
- `--wiki` — 创建到知识库（默认独立模式）
- `--wiki --space-id <id> --parent-node <node>` — 指定知识空间
- `--dry-run` — 只预览计划不实际创建

### 2.3 解析脚本输出

脚本成功后会输出以下关键标记行：

**多维表格结果**（`__RESULT_JSON__:{...}`）：
- `app_token` — 多维表格 ID
- `link` — 打开链接
- `tables` — 每张表的 `name` 和 `table_id`
- `warnings` — 需手动处理的事项（降级字段、日历视图等）

**配置文档**（`__CONFIG_DOC_READY__:/tmp/bitable_config_doc.md`）：
- 脚本已自动生成详尽的配置方案 Markdown 文件
- 包含表结构、公式、视图、自动化、权限、仪表盘、应用模式等完整内容

**脚本自动处理的事项（不需要额外操作）：**
- ✅ 创建表时直接指定字段（首字段就是 type=1 文本，无多行文本问题）
- ✅ 无默认字段（不存在需要删除的多行文本/单选/日期/附件）
- ✅ 无空白记录（新建表不带默认行）
- ✅ 默认视图名在创建时直接指定
- ✅ 飞书自动创建的脏表已被脚本删除
- ✅ 设置管理员权限
- ✅ 配置方案 Markdown 已自动生成（含公式、自动化、权限、仪表盘等）

**⚠️ Phase 2 完成后，禁止直接回复用户！必须继续执行 Phase 3！**

---

## Phase 3: 创建配置方案文档

**⚠️ 必须执行！搭完表不创建文档 = 任务未完成。**

### 执行步骤（严格按顺序）

**第 1 步：读取脚本生成的 Markdown 文件**
```
exec(command='cat /tmp/bitable_config_doc.md')
```

**第 2 步：调用 feishu_create_doc 创建文档**

从脚本输出的 `__CONFIG_DOC_TITLE__` 获取标题，将 cat 输出的**全部内容原样**作为 markdown 参数：
- `title`: 脚本输出的 `__CONFIG_DOC_TITLE__` 值（如 "XXX系统 - 配置方案"）
- `markdown`: 上一步 cat 输出的**完整原始内容**，一个字都不能改

**⚠️ 严禁以下行为：**
- ❌ 自己编写或改写配置文档内容（脚本已生成完整内容，包含 mermaid 思维导图和 ER 图）
- ❌ 删减、简化、截断文件内容
- ❌ 因为内容包含 mermaid 代码块就跳过或改写
- ❌ 跳过此步骤直接回复用户
- ❌ 用 docx API 代替 feishu_create_doc
- ❌ 把 cat 输出的内容"总结"后再传——必须**原文传递**
> - `warnings` 中的内容合并到「需手动完善」部分

```markdown
# {app_name} - 配置方案

## 一、搭建结果

- **多维表格**：[{app_name}]({link})
- **数据表**：
{每张表一行：  - {name}（{字段数} 个字段，{记录数} 条示例数据）}
- **已创建视图**：
{每张表的视图列表}

## 二、当前表结构

{对每张表输出以下格式：}

### {表名}

| 字段名 | 类型 | 选项/配置 | 说明 |
|-------|------|----------|------|
{首字段} | 文本 | — | 首字段 |
{每个字段一行，从 JSON 配置中提取}

{如有多张表，列出表间关系：}

### 表间关系
- {表1}.{字段} ↔ {表2}.{字段}（双向关联）— **需手动创建**

## 三、需要手动完善的配置

> 以下所有配置均为 API 无法自动完成的步骤，需在多维表格界面手动操作。
> 根据实际情况，只输出需要的小节，没有则省略。

### 3.1 脚本警告事项

{如果 warnings 非空，列出每条警告及处理方法}

### 3.2 跨表关联

{如果是多表系统，列出需要手动创建的关联}

| 源表 | 源字段 | 目标表 | 关联类型 | 操作说明 |
|------|-------|--------|---------|---------|
| {表名} | {字段名} | {目标表} | 双向关联 | 点击"+"添加字段 → 选择"关联" → 选择目标表 |

### 3.3 公式字段

{列出所有 type=20 占位字段，提供可直接粘贴的公式}

| 表 | 字段名 | 公式 | 用途 |
|----|-------|------|------|
| {表名} | {字段名} | `{公式表达式}` | {用途说明} |

**常用公式模式参考**：
- 跨表求和：`[表].FILTER(CurrentValue.[字段]=[字段]).[金额].SUM()`
- 条件计数：`[表].COUNTIF(CurrentValue.[状态]="已完成")`
- 日期差：`DATEDIF([开始日期],[截止日期],"D")`
- 逾期预警：`IF([截止日期]<TODAY(),"⚠️ 已逾期",IF([截止日期]<TODAY()+3,"即将到期","正常"))`
- 完成率：`[表].COUNTIF(CurrentValue.[状态]="已完成") / [表].COUNTIF(CurrentValue.[状态]!="")`
- 排名：`RANK([销售额],[销售表].[销售额])`

**配置方法**：点击字段名 → 编辑字段 → 选择"公式" → 粘贴上方公式

### 3.4 视图配置建议

{为每张核心数据表设计 2-4 个实用视图}

| 数据表 | 视图名 | 类型 | 用途 | 筛选/分组/排序 |
|-------|-------|------|------|---------------|
| {表名} | {视图名} | 表格/看板/日历/甘特/画册/表单 | {面向XX角色} | {具体规则} |

**视图类型选用指南**：
- **看板**：适合有单选状态字段的表（如任务状态、审批状态），分组依据选该单选字段
- **日历**：适合有日期字段的表（如排期、日程），基于日期字段按月展示
- **甘特**：适合有开始+结束日期的表（如项目计划），支持拖拽调整时间
- **表单**：适合数据收集场景（如需求收集、报名），可生成分享链接
- **画册**：适合有附件/图片字段的表（如素材库）

**配置路径**：数据表顶部 → "+" 添加视图 → 选择类型 → 设置筛选/分组/排序

### 3.5 自动化规则

{根据业务需求设计 3-6 条实用自动化}

| 名称 | 触发条件 | 执行操作 | 配置说明 |
|------|---------|---------|---------|
| {规则名} | {触发类型 + 条件} | {具体操作} | {引用的字段/消息模板} |

**常用自动化模式**：

| 模式 | 触发条件 | 执行操作 | 典型场景 |
|------|---------|---------|---------|
| 状态变更通知 | 记录满足条件（状态字段变为XX） | 发送飞书消息给相关人员 | 任务完成通知、审批提醒 |
| 到期预警 | 定时触发（每天） | 筛选即将到期记录 → 发送汇总消息 | 合同到期、任务逾期 |
| 新记录分配 | 添加新记录 | 修改记录（自动填充负责人/编号） | 工单自动分配 |
| 审批流转 | 记录满足条件（审批通过） | 修改记录状态 + 创建飞书任务 | 采购审批后自动建任务 |
| 数据归档 | 定时触发（每月） | 筛选已完成记录 → 发送报表 | 月度汇总报告 |
| 外部触发 | 接收 Webhook | 新增/修改记录 | 外部系统数据同步 |

**配置路径**：多维表格右上角 → 自动化 → 新建流程

### 3.6 高级权限设计

{根据业务角色设计权限矩阵}

**角色定义**：

| 角色 | 成员 | 说明 |
|------|------|------|
| {角色名} | {部门/人员} | {职责描述} |

**数据表权限矩阵**：

| 角色 | {表1} | {表2} | {表3} | 记录范围 |
|------|-------|-------|-------|---------|
| 管理员 | 可管理 | 可管理 | 可管理 | 所有记录 |
| {角色1} | 可编辑 | 仅可阅读 | 无权限 | 与本人相关 |
| {角色2} | 仅可阅读 | 可编辑 | 仅可阅读 | 满足条件：{条件} |

**行列级权限**（如需数据隔离）：
- 行权限："与成员本人相关的记录"绑定人员字段 `{字段名}` → 每人只看自己的数据
- 列权限：{敏感字段} 对 {角色} 设为不可阅读

**配置路径**：多维表格右上角 → 高级权限 → 开启 → 添加自定义角色

### 3.7 仪表盘设计

{设计 1-2 个仪表盘，每个包含 4-8 个组件}

**仪表盘：{名称}**（面向：{角色}）

| 组件名 | 类型 | 数据源 | 维度/横轴 | 指标/纵轴 | 筛选条件 |
|-------|------|--------|----------|----------|---------|
| {名称} | 指标卡/柱状图/饼图/折线图/进度图/排行榜/表格视图 | {数据表} | {字段} | {聚合方式} | {条件} |

**推荐组件搭配**：
- **指标卡**（2-4 个）：关键数字一目了然（总数、完成率、待办数、逾期数）
- **柱状图/折线图**（1-2 个）：趋势分析（按月/按周统计）
- **饼图**（1 个）：占比分析（按状态/按分类）
- **排行榜**（1 个）：Top N 排名
- **切片器**（1 个）：全局筛选联动（按时间范围/按部门）

**配置路径**：左下角 → 新建仪表盘 → 添加组件 → 设置数据源和样式

### 3.8 应用模式（可选）

{如果系统复杂度高、需要面向不同角色提供不同界面，建议搭建应用模式}

**页面结构**：

| 页面组 | 页面 | 组件 | 面向角色 |
|-------|------|------|---------|
| {页面组名} | {页面名} | {列表/视图/图表/按钮} | {角色} |

**配置路径**：多维表格左上角 → 切换到应用模式 → 编辑页面

---

## 四、修改意见区

> **如果需要修改表结构，请直接在下方编辑，然后告诉我。我会按你的修改调整多维表格。**

### 要新增的字段
| 表 | 字段名 | 类型 | 选项/说明 |
|----|-------|------|----------|
|    |       |      |          |

### 要删除的字段
| 表 | 字段名 | 原因 |
|----|-------|------|
|    |       |      |

### 要修改的字段
| 表 | 原字段名 | 修改内容 |
|----|---------|---------|
|    |         |         |

### 要新增的表
| 表名 | 用途 | 关键字段 |
|------|------|---------|
|      |      |         |

### 其他修改意见
（自由填写）
```

### 向用户汇报

告知用户：
1. 多维表格链接
2. 配置方案文档链接
3. 最重要的 1-2 件需手动做的事（从 warnings + 公式/关联/自动化中挑最关键的）

---

## Phase 4: 按文档修改表格

用户修改文档后告诉 agent，执行：

1. `feishu_fetch_doc` 读取修改内容
2. 用飞书插件工具执行修改：
   - 新增字段：`feishu_bitable_app_table_field` → create
   - 删除字段：`feishu_bitable_app_table_field` → delete
   - 修改字段：`feishu_bitable_app_table_field` → update
   - 新增表：`feishu_bitable_app_table` → create（注意手动清理默认字段和空行）
3. `feishu_update_doc` 更新文档中的表结构
4. 汇报修改结果

---

# 二、日常 CRUD 操作

搭建完成后，所有日常操作都通过飞书插件的 `feishu_bitable_*` 工具完成。

## 快速索引：意图 → 工具

| 用户意图 | 工具 | action | 必填参数 | 常用可选 |
|---------|------|--------|---------|---------|
| 查表有哪些字段 | feishu_bitable_app_table_field | list | app_token, table_id | - |
| 查记录 | feishu_bitable_app_table_record | list | app_token, table_id | filter, sort, field_names |
| 新增一行 | feishu_bitable_app_table_record | create | app_token, table_id, fields | - |
| 批量导入 | feishu_bitable_app_table_record | batch_create | app_token, table_id, records (≤500) | - |
| 更新一行 | feishu_bitable_app_table_record | update | app_token, table_id, record_id, fields | - |
| 批量更新 | feishu_bitable_app_table_record | batch_update | app_token, table_id, records (≤500) | - |
| 删除记录 | feishu_bitable_app_table_record | batch_delete | app_token, table_id, record_ids | - |
| 创建字段 | feishu_bitable_app_table_field | create | app_token, table_id, field_name, type | property |
| 修改字段 | feishu_bitable_app_table_field | update | app_token, table_id, field_id | field_name, type, property |
| 删除字段 | feishu_bitable_app_table_field | delete | app_token, table_id, field_id | - |
| 创建视图 | feishu_bitable_app_table_view | create | app_token, table_id, view_name, view_type | - |

## 字段值格式（易错重点）

**强制流程**：写记录前，先调用 `feishu_bitable_app_table_field.list` 获取字段的 `type` 和 `ui_type`，然后按下表构造值。

| type | ui_type | 字段类型 | 正确格式 | 常见错误 |
|------|---------|----------|---------|---------|
| 1 | Text | 文本 | `"字符串"` | — |
| 2 | Number | 数字 | `123.45` | 传字符串 |
| 3 | SingleSelect | 单选 | `"选项名"` | 传数组 `["选项名"]` |
| 4 | MultiSelect | 多选 | `["选项1", "选项2"]` | 传字符串 |
| 5 | DateTime | 日期 | `1674206443000`（毫秒） | 传秒时间戳或字符串 |
| 7 | Checkbox | 复选框 | `true` / `false` | 传字符串 |
| 11 | User | 人员 | `[{id: "ou_xxx"}]` | 传字符串或 `{name: "张三"}` |
| 15 | Url | 超链接 | `{link: "...", text: "..."}` | 只传字符串 URL |
| 17 | Attachment | 附件 | `[{file_token: "..."}]` | 传外部 URL |

## 筛选查询

```json
{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "filter": {
    "conjunction": "and",
    "conditions": [
      {
        "field_name": "状态",
        "operator": "is",
        "value": ["进行中"]
      },
      {
        "field_name": "截止日期",
        "operator": "isLess",
        "value": ["ExactDate", "1740441600000"]
      }
    ]
  },
  "sort": [{"field_name": "截止日期", "desc": false}]
}
```

**筛选 operator：**

| operator | 含义 | value 要求 |
|----------|------|-----------|
| `is` | 等于 | 单个值 |
| `isNot` | 不等于 | 单个值 |
| `contains` | 包含 | 可多个值 |
| `doesNotContain` | 不包含 | 可多个值 |
| `isEmpty` | 为空 | **必须为 `[]`** |
| `isNotEmpty` | 不为空 | **必须为 `[]`** |
| `isGreater` | 大于 | 单个值 |
| `isLess` | 小于 | 单个值 |

**日期特殊值**: `["Today"]`, `["Tomorrow"]`, `["ExactDate", "时间戳"]`

## 批量操作要点

- 单次上限 **500 条**，超过需分批
- 同一数据表**不支持并发写**，串行调用 + 延迟 0.5-1 秒
- 批量操作是**原子性**的（全部成功或全部失败）

---

# 三、通用参考

## 字段选型指南

| 分类 | 字段 | 要点 |
|------|------|------|
| 录入信息 | 文本(1)、数字(2)、日期(5)、电话(13)、超链接(15)、附件(17) | 按信息本质选 |
| 分类标记 | 单选(3)、多选(4)、复选框(7) | **单选是灵魂字段** — 看板/仪表盘/自动化都靠它 |
| 跨表联动 | 双向关联(21)、单向关联(18) | 先关联，再引用 |
| 自动计算 | 公式(20) | 创建占位，文档中提供表达式 |

## 公式速查

| 模式 | 公式 | 场景 |
|------|------|------|
| 跨表求和 | `[表].FILTER(CurrentValue.[字段]=[字段]).[字段].SUM()` | 按人/类别汇总 |
| 条件计数 | `[表].COUNTIF(CurrentValue.[状态]="已完成")` | 统计数量 |
| 日期差 | `DATEDIF([开始],[截止],"D")` | 工期/逾期天数 |
| 逾期预警 | `IF([截止日期]<TODAY(),"已逾期","正常")` | 状态标记 |

公式字段 API 不支持设表达式，在文档中提供，用户手动填写。
完整速查见 [references/formula-reference.md](references/formula-reference.md)。

## 常见错误排查

| 错误码 | 现象 | 解决方案 |
|--------|------|---------|
| 1254064 | 日期字段转换失败 | 必须用毫秒时间戳，不能用字符串 |
| 1254068 | 超链接字段转换失败 | 必须用对象 `{text, link}`，不能直接传 URL |
| 1254066 | 人员字段转换失败 | 必须传 `[{id: "ou_xxx"}]` |
| 1254015 | 字段类型不匹配 | 先 list 字段，按类型构造正确格式 |
| 1254104 | 批量超限 | 分批调用，每批 ≤ 500 |
| 1254291 | 写冲突 | 串行调用 + 延迟 0.5-1 秒 |
| 1254045 | 字段名不存在 | 检查字段名（包括空格、大小写） |

## 资源限制

| 限制项 | 上限 |
|--------|------|
| 数据表 + 仪表盘 | 100（单个 App） |
| 记录数 | 20,000（单个数据表） |
| 字段数 | 300（单个数据表） |
| 视图数 | 200（单个数据表） |
| 批量操作 | 500（单次 API） |

---

## 参考文档

飞书插件自带参考（字段 property、记录值格式、完整示例）：
- `feishu-bitable/references/field-properties.md`
- `feishu-bitable/references/record-values.md`
- `feishu-bitable/references/examples.md`

本技能补充：
- [实战模式库](references/system-patterns.md) — 4 套典型系统表结构
- [公式速查](references/formula-reference.md)
- [自动化 vs 工作流](references/automation-workflow.md)
- [权限设计](references/permissions-guide.md)
- [扩展类型映射](references/field-type-mapping.md)

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

feishu-bitable

Directory Structure

SKILL.md

Report

Notice