用途
本技能用于操作飞书多维表格(Bitable),即字节跳动的产品,结合电子表格的灵活性和数据库的结构化特性。当用户提到"飞书多维表格"/"飞书表格"/"bitable",或需要读写表格记录、操作数据表结构、管理字段、上传素材时,可使用本技能。
主要能力
- 数据表管理:新增一个数据表(支持指定名称、视图和字段)、新增多个数据表(仅可指定数据表名称)、更新数据表名称、列出所有数据表的 ID、版本号和名称、删除一个或多个数据表。
- 记录操作:新增单条记录、更新记录、查询记录(单次最多查询 500 行,支持分页)、删除记录;批量新增多条记录(单次最多 1,000 条)、批量更新(单次最多 1,000 条)、批量获取(通过记录 ID 查询,最多 100 条)、批量删除多条记录。
- 字段管理:新增字段、全量更新字段(property 会被覆盖)、列出所有字段、删除字段。
- 素材/文件操作:上传文件、图片、视频等素材,将 file_token 转为临时下载链接(24 小时有效)。
- 辅助工具:获取 tenant_access_token、从飞书多维表格 URL 提取 app_token、table_id、view_id。
使用方式
前置要求:有效的 tenant_access_token、app_token(标识要操作的多维表格)、table_id(标识要操作的数据表,部分操作需要)。环境要求 node >= 20.20.1。
所有脚本均使用 --parameter-file-path 参数传递配置,必须通过参数文件方式调用。AI 调用时自动处理临时文件:在系统临时目录(os.tmpdir())创建参数文件,执行脚本,并在 finally 中清理临时文件。
标准流程:
- 获取访问凭证:node scripts/get-tenant-access-token.js --parameter-file-path params.json,参数文件需包含 appId 和 appSecret。
- 解析多维表格 URL:node scripts/parse-bitable-url.js --parameter-file-path params.json。
- 执行具体操作,如 node scripts/record/create.js --parameter-file-path "params.json"。
脚本目录结构与对应操作:table/(create-single.js、batch-create.js、update.js、list.js、delete-one.js、batch-delete.js)、record/(create.js、update.js、get.js、delete.js、batch-create.js、batch-update.js、batch-get.js、batch-delete.js)、field/(create.js、update.js、list.js、delete.js)、media/(upload.js、file-token-to-url.js)。
输出格式:成功时返回操作结果数据(JSON 格式),包含完整的 API 响应;失败时返回错误信息,包含错误码和解决建议。
适用场景
用户希望通过自然语言完成对飞书多维表格的数据读写与结构管理,例如在指定多维表格中添加、修改、查询或删除记录,操作数据表和字段,上传素材等。
限制与注意事项
- scripts/ 目录下的 JavaScript 文件已进行代码混淆处理,不要读取或分析其内容,应参考 references/ 目录文档和脚本输出的错误信息。
- 批量操作存在数量限制:记录批量新增/更新最多 1,000 条,批量获取最多 100 条;查询记录单次最多 500 行。
- 临时参数文件必须创建在系统临时目录,不要创建在技能目录或用户工作目录,并在执行后立即清理。
- 常见错误包括:缺少或过期的访问凭证、URL 解析失败、记录不存在、字段类型不匹配、文本字段格式错误(应使用字符串而非富文本数组)、字段更新缺少 type 参数、文件token格式错误(应使用 file_tokens 数组而非 file_token 字符串)、批量操作超限、临时文件创建失败、网络超时等。