feishu-bitable

不碰外部（只输出文字）无严重或高危命中op7418/CodePilot

它会碰到什么

扫了多少4 个文本文件，41 KB

它会碰到什么不碰外部（只输出文字）

命中总数0 处

命中统计严重 0 · 高 0 · 中 0 · 低 0

这一栏是扫描器报的事实，不是结论。命中多不等于有毒（安全工具、规则库、示例脚本本来就会包含危险写法），命中少也不等于干净。它和你手上的凭据、文件、网络有什么关系，需要你自己看。

技能内容

Feishu Bitable (多维表格) SKILL

🚨 执行前必读

✅ 创建数据表：支持两种模式 — ① 明确需求时，在 create 时通过 table.fields 一次性定义字段（减少 API 调用）；② 探索式场景时，使用默认表 + 逐步修改字段（更稳定，易调整）
⚠️ 默认表的空行坑：app.create 自带的默认表中会有空记录（空行）！插入数据前建议先调用 feishu_bitable_app_table_record.list + batch_delete 删除空行，避免数据污染
✅ 写记录前：先调用 feishu_bitable_app_table_field.list 获取字段 type/ui_type
✅ 人员字段：默认 open_id（ou_...），值必须是 [{id:"ou_xxx"}]（数组对象）
✅ 日期字段：毫秒时间戳（例如 1674206443000），不是秒
✅ 单选字段：字符串（例如 "选项1"），不是数组
✅ 多选字段：字符串数组（例如 ["选项1", "选项2"]）
✅ 附件字段：必须先上传到当前多维表格，使用返回的 file_token
✅ 批量上限：单次 ≤ 500 条，超过需分批（批量操作是原子性的）
✅ 并发限制：同一数据表不支持并发写，需串行调用 + 延迟 0.5-1 秒

📋 快速索引：意图 → 工具 → 必填参数

|---------|------|--------|---------|---------|

🎯 核心约束（Schema 未透露的知识）

📚 详细参考文档

当遇到字段配置、记录值格式问题或需要完整示例时，查阅以下文档：

[字段 Property 配置详解](references/field-properties.md) - 每种字段类型创建/更新时需要的 property 参数结构（单选的 options、进度的 min/max、关联的 table_id 等）
[记录值数据结构详解](references/record-values.md) - 每种字段类型在记录中对应的 fields 值格式（人员字段只传 id、日期是毫秒时间戳、附件需先上传等）
[使用场景完整示例](references/examples.md) - 8 个完整场景示例（创建表模式对比、批量导入、筛选查询、附件处理、关联字段等）

何时查阅:

创建/更新字段时收到 125408X 错误码（property 结构错误）→ 查 field-properties.md
写入记录时收到 125406X 错误码（字段值转换失败）→ 查 record-values.md
需要完整的操作流程和参数示例 → 查 examples.md

1. 字段类型与值格式必须严格匹配

Bitable 最大的坑：不同字段类型对 value 的数据结构要求完全不同。

最易错的字段类型（完整列表见 [record-values.md](references/record-values.md)）

|------|---------|----------|---------|-----------|

| 11 | User | 人员 | [{id: "ou_xxx"}] | 传字符串 "ou_xxx" 或 [{name: "张三"}] |

| 5 | DateTime | 日期 | 1674206443000（毫秒） | 传秒时间戳或字符串 |

| 3 | SingleSelect | 单选 | "选项名" | 传数组 ["选项名"] |

| 15 | Url | 超链接 | {link: "...", text: "..."} | 只传字符串 URL |

| 17 | Attachment | 附件 | [{file_token: "..."}] | 传外部 URL 或本地路径 |

强制流程：

先调用 feishu_bitable_app_table_field.list 获取字段的 type 和 ui_type
根据上表或 [record-values.md](references/record-values.md) 构造正确格式
错误码 125406X 或 1254015 → 检查字段值格式

人员字段特别注意：

默认使用 open_id（ou_...），与 calendar/task 一致
格式：[{id: "ou_xxx"}]（数组对象）
只能传 id 字段，不能传 name/email 等

📌 核心使用场景

> 完整示例: 查阅 [examples.md](references/examples.md) 了解更多场景（创建表模式对比、空行处理、附件上传、关联字段等）

场景 1: 查字段类型（必做第一步）

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl..."
}

返回：包含每个字段的 field_id、field_name、type、ui_type、property

场景 2: 批量导入客户数据

{
  "action": "batch_create",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "records": [
    {
      "fields": {
        "客户名称": "字节跳动",
        "负责人": [{"id": "ou_xxx"}],
        "签约日期": 1674206443000,
        "状态": "进行中"
      }
    },
    {
      "fields": {
        "客户名称": "飞书",
        "负责人": [{"id": "ou_yyy"}],
        "签约日期": 1675416243000,
        "状态": "已完成"
      }
    }
  ]
}

字段值格式：

人员：[{id: "ou_xxx"}]（数组对象）
日期：毫秒时间戳
单选：字符串
多选：字符串数组

限制: 最多 500 条记录

场景 3: 筛选查询（高级筛选）

{
  "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
    }
  ]
}

filter 说明：

支持 10 种 operator（is/isNot/contains/isEmpty 等，见附录 C）
⚠️ isEmpty/isNotEmpty 必须传 value: []（虽然逻辑上不需要值，但 API 要求必须传空数组）
日期筛选可使用 ["Today"]、["ExactDate", "时间戳"] 等
sort 可指定多个排序字段

🔍 常见错误与排查

|--------|---------|---------|---------|

| 1254068 | URLFieldConvFail | 超链接字段格式错误 | 必须用对象 {text: "显示文本", link: "URL"}，不能直接传字符串 URL |

| 1254066 | UserFieldConvFail | 人员字段格式错误或 ID 类型不匹配 | 必须传 [{id: "ou_xxx"}]，确认 user_id_type |

📚 附录：背景知识

A. 资源层级关系

App (多维表格应用)
 ├── Table (数据表) ×100
 │    ├── Record (记录/行) ×20,000
 │    ├── Field (字段/列) ×300
 │    └── View (视图) ×200
 └── Dashboard (仪表盘)

B. 筛选条件 operator 列表

|----------|------|----------|-----------|

| is | 等于 | 所有 | 单个值 |

| isNot | 不等于 | 除日期外 | 单个值 |

| isEmpty | 为空 | 所有 | 必须为 [] |

| isNotEmpty | 不为空 | 所有 | 必须为 [] |

| isGreater | 大于 | 数字、日期 | 单个值 |

| isLess | 小于 | 数字、日期 | 单个值 |

日期字段特殊值: ["Today"], ["Tomorrow"], ["ExactDate", "时间戳"] 等（完整列表见 [examples.md](references/examples.md#场景-3-筛选查询高级筛选)）

C. 使用限制

| 限制项 | 上限 |

|--------|------|

| 数据表 + 仪表盘 | 100（单个 App） |

| 记录数 | 20,000（单个数据表） |

| 字段数 | 300（单个数据表） |

| 视图数 | 200（单个数据表） |

| 批量创建/更新/删除 | 500（单次 API 调用） |

| 单元格文本 | 10 万字符 |

| 单选/多选选项 | 20,000（单个字段） |

| 单元格附件 | 100 |

| 单元格人员 | 1,000 |

D. 其他约束

从其他数据源同步的数据表，不支持增删改记录
公式字段、查看引用字段是只读的
删除操作无法恢复
视图筛选条件使用 field_id，需先调用 field.list 获取

想直接用这个技能？

本站把开放许可（MIT / Apache 等）的技能按仓库打包整理到网盘，点一下转存到你自己的网盘，不用一个个从 GitHub 拉。许可未声明的技能只给原始仓库链接，不打包。

去原始仓库

它属于哪个仓库

仓库op7418/CodePilot

星标★ 6,461

本站分层T1

该仓技能数9

原文件路径资料/feishu-openclaw-plugin/package/skills/feishu-bitable/SKILL.md

同一个仓库里的其他技能

看这个仓库的全部 9 个技能