feishu-bitable

用途

本技能为 AI 大模型提供处理飞书多维表格（Bitable）的完整能力，支持操作数据表、记录、字段和素材。当用户说"飞书多维表格""飞书表格""bitable"，或需要读写表格记录、操作数据表结构、管理字段、上传素材时使用。

主要能力

数据表管理：创建、更新、删除数据表（支持批量操作），列出所有数据表。
记录操作：增删改查记录，支持批量操作（单次最多 1000 条），查询单次最多 500 行并支持分页，批量获取最多 100 条。
字段管理：创建、更新、删除字段，列出所有字段。
素材上传：上传文件、图片、视频等素材，获取临时下载链接（24 小时有效）。

使用方式

所有脚本均使用 --parameter-file-path 参数传递配置，必须通过参数文件方式调用。AI 自动处理临时文件的创建和清理，人类用户只需用自然语言描述需求。

标准流程：

获取访问凭证：运行 get-tenant-access-token.js，参数文件包含 appId 和 appSecret。
解析多维表格 URL：运行 parse-bitable-url.js，从 URL 提取 app_token、table_id、view_id。
执行具体操作：根据需求选择 table/、record/、field/、media/ 目录下的对应脚本。

示例命令：

node scripts/get-tenant-access-token.js --parameter-file-path params.json
node scripts/parse-bitable-url.js --parameter-file-path params.json
node scripts/record/get.js --parameter-file-path "params.json"
node scripts/record/create.js --parameter-file-path "params.json"
node scripts/record/batch-create.js --parameter-file-path "params.json"

AI 调用时需自动管理临时文件：使用 createTempParamsFile 创建临时参数文件（存放在系统临时目录），执行脚本后使用 cleanupTempFile 清理，并用 try...finally 确保即使出错也会清理。临时文件命名格式为 feishu-{operation}-{timestamp}-{random}.json。

触发映射

"查看记录"/"获取记录"/"列出记录" → record/get.js
"添加记录"/"创建记录"/"插入记录" → record/create.js
"修改记录"/"更新记录"/"编辑记录" → record/update.js
"删除记录"/"移除记录" → record/delete.js
"批量添加记录" → record/batch-create.js
"批量修改记录" → record/batch-update.js
"批量删除记录"/"清空记录" → record/batch-delete.js
"查看表格"/"数据表列表" → table/list.js
"创建表格"/"添加数据表" → table/create-single.js
"修改表格名称"/"重命名表格" → table/update.js
"删除表格"/"移除数据表" → table/delete-one.js
"查看字段"/"列信息" → field/list.js
"添加字段"/"新列" → field/create.js
"修改字段"/"修改列" → field/update.js
"删除字段"/"移除列" → field/delete.js
"上传文件"/"上传图片"/"上传附件" → media/upload.js
"获取下载链接"/"获取直链" → media/file-token-to-url.js

核心概念

多维表格 (Bitable)：结合电子表格的灵活性和数据库的结构化特性。
数据表 (Table)：多维表格中的单个表格，类似 Excel 工作表。
记录 (Record)：数据表中的一行数据。
字段 (Field)：数据表中的一列的表头，用于设定该列的数据类型。
素材 (Media)：上传的文件、图片、视频等。

前置要求

有效的 tenant_access_token：所有 API 操作都需要。
app_token：标识要操作的多维表格。
table_id：标识要操作的数据表（部分操作需要）。

输出格式

成功：返回操作结果数据（JSON 格式），包含完整的 API 响应。
失败：返回错误信息，包含错误码和解决建议。

适用场景

用户通过自然语言请求操作飞书多维表格，例如："帮我在飞书表格 https://xxx.feishu.cn/wiki/xxx 里添加一条记录，任务名称是'完成报告'，进度50%"。AI 自动完成凭证检查、URL 解析、临时参数文件创建、记录创建、临时文件清理，并向用户返回结果。用户无需知道临时文件的存在。

限制与注意事项

本技能 scripts/ 目录下的所有 JavaScript 文件已进行代码混淆处理。AI 行为准则：可以执行这些脚本，使用 --parameter-file-path 传递参数；不要读取或分析 scripts/ 目录下的 .js 文件内容。遇到问题时参考 references/ 目录下的文档，查看脚本输出的错误信息和错误码。
批量操作限制：记录单次最多 1000 条，批量获取最多 100 条，查询单次最多 500 行。
临时文件必须创建在系统临时目录（os.tmpdir()），不要创建在技能目录或用户工作目录。
获取直链的临时下载链接 24 小时有效。

常见错误处理

缺少访问凭证（401/403）：运行 get-tenant-access-token.js 获取凭证。
访问凭证过期（错误代码 99991663）：重新获取凭证。
URL 解析失败：检查 URL 格式或手动提供参数。
记录不存在（404）：检查 record_id 或先查询。
字段类型不匹配（400）：运行 field/list.js 查看字段类型。
文本字段格式错误（TextFieldConvFail）：文本字段使用字符串格式，不要用富文本数组格式。
字段更新缺少参数：更新字段时必须提供 type 参数。
文件 token 格式错：使用 file_tokens（数组）而非 file_token（字符串）。
批量操作超限（422）：减少单次操作数量。
网络超时：检查网络连接，稍后重试。

参考文档

references/ 目录下包含：认证与凭证管理指南、获取访问凭证 API、解析飞书 URL 工具、常见错误及解决方案、参数配置示例与最佳实践。