Feishu Bitable · Research Ingestion Piece

这是为 Activepieces 研究数据入库设计的飞书多维表格 Piece。npm 包名为 @tangm6666/piece-feishu-readonly。

能力

• 用自建应用 app_id / app_secret 获取 tenant_access_token；
• 分页读取指定 Base 的数据表元数据；
• 读取指定测试表的前 10 条记录、全表分页扫描，以及按文本定位任务记录；
• 读取目标表字段架构；写前按真实字段类型校验日期、超链接、系统字段与关联字段；
• 按唯一字段生成安全的新增/更新计划，默认只演算不写入；
• 在明确关闭 dry run 后，批量新增/更新并回读受影响记录；
• 更新单条任务汇总记录，默认只演算不写入。
• 以视频 ID 创建或复用受控的飞书云盘交付目录：原视频 / 抽帧 / 文案与报告 / 收口快照；默认仅演算。
• 将流程生成的 Markdown、文本或 JSON 交付件上传到已授权的飞书云盘目录；默认仅演算，不读取任意主机文件。
• 将流程生成的 Markdown、文本或 JSON 交付件写入 Activepieces 已有持久化卷中的固定目录，并在同一步回读核账；默认仅演算。
• 将一条表2视频的封面附件作为受限的图像 data URL 交给紧随其后的多模态模型步骤；仅读取，单张上限 4 MB，不向日志输出图片。

安全边界

• 凭据通过 CustomAuth Connection 输入，动作输出不包含凭据或 Token；
• 仅允许访问 https://open.feishu.cn/open-apis 中代码写死的 Token、table-list 与 record-list 路径；
• 所有入库动作都有 Dry run only 开关，默认开启；
• 连接校验会真实获取 Token，因此只有在获准只读联调后才点击保存/测试连接；
• 使用专用测试应用和测试 Base，禁止生产凭据。
• 云盘写入只允许发生在用户明确共享给应用身份的根目录之下；根目录 token 必须由 Flow 显式传入。

构建与安装状态

当前本地草稿版本为 0.7.1：除字段架构读取与 schema-aware 入库外，加入受控的三处落盘目录规划、生成文本交付件上传与本地快照写入。封面证据读取可选绑定当前 Table record_id，避免历史重复视频ID误取素材。

官方文档说明私有 Piece 文件上传属于付费版本。社区版后续需要在以下路径中选择一个：

1. 将 Piece 作为公开社区包发布到 npm；
2. 在 Activepieces 官方源码仓库/私有 fork 中本地构建包含该 Piece 的镜像；
3. 若现有实例具备付费许可，从 Platform Admin → Setup → Pieces 上传构建后的 .tgz。

任何安装路径都属于下一道施工门禁，执行前须确认版本、许可和回滚方式。