概述

该技能通过素材上传流程，将文件上传至飞书（Lark）Bitable 的附件字段：

1. 获取源文件（本地副本、URL 下载或飞书消息附件下载）
2. 调用 Bitable 上传端点，以 parent_type=bitable_file 参数上传
3. 从上传响应中提取 file_token
4. 创建或更新记录，并在附件字段中填入该 file_token

核心设计：这是一个通用型技能，适用于您的应用可访问的任意 Bitable。所有配置均未硬编码。

验证状态

本地测试通过

• 所有 Python 模块通过语法检查（py_compile）
• 所有自定义异常类均已正确导入
• 文件未找到时抛出 SkillFileNotFoundError（而非 NameError）
• 输入校验失败时对缺失参数抛出 SkillInputError
• 所有 payload 示例文件均为合法 JSON
• main.py --help 可成功执行

需真实环境验证

• Bitable 记录创建/更新接口的响应格式
• 表格/字段列表 API 的响应结构
• 记录搜索 API 的筛选器语法

若在您的环境中任意 API 调用失败，请查阅 references/feishu-api-notes.md 中标注的可扩展性接入点。

支持的源类型

目标解析机制

本技能支持灵活的目标指定方式，适配任意 Bitable：

表格指定（优先级：table_id > table_name）

• 直接提供 table_id，解析最快
• 或提供 table_name，自动执行查找（调用 API 列出全部表格并按名称匹配）

字段指定（优先级：field_id > field_name）

• 直接提供 field_id，解析最快
• 或提供 field_name，自动执行查找（调用 API 列出全部字段并按名称匹配）

记录指定

• 提供 record_id：更新已有记录
• 提供 lookup：根据字段值搜索目标记录
• 两者均不提供：创建新记录

输入 JSON 结构

{
  "target": {
    "app_token": "bascxxxxxxxxxxxxx",
    "table_id": "tblxxxxxxxxxx",
    "table_name": "",
    "record_id": "recxxxxxxxxxx",
    "field_id": "fldxxxxxxxxxx",
    "field_name": "附件",
    "lookup": {
      "field_name": "合同编号",
      "field_id": "",
      "value": "HT-2026-001"
    },
    "allow_create_if_lookup_missing": false
  },
  "source": {
    "type": "local",
    "ref": "/path/to/file.pdf"
  },
  "append": true
}

Target 参数

Lookup 配置

"lookup": {
  "field_name": "合同编号",
  "field_id": "",
  "value": "HT-2026-001"
}

Source 参数

追加模式（Append Mode）

上传流程

小文件（≤20MB）

直接上传至素材上传端点：

POST /open-apis/drive/v1/upload
multipart/form-data 字段：
  - file: <文件内容>
  - file_name: 文件名
  - size: 文件大小（字节）
  - parent_type: bitable_file
  - parent_node: {app_token}
  - extra: {"drive_route_token": "{app_token}"}

大文件（>20MB）

以 5MB 分片进行分块上传：

1. POST /open-apis/drive/v1/chunked_upload/prepare → 获取 upload_id
2. POST /open-apis/drive/v1/chunked_upload（每片调用一次）→ 获取 etag
3. POST /open-apis/drive/v1/chunked_upload/finish → 获取 file_token

环境变量

运行前请设置以下环境变量：

export FEISHU_APP_ID=your_app_id
export FEISHU_APP_SECRET=your_app_secret
export FEISHU_BASE_URL=https://open.feishu.cn  # 可选

使用示例

已知 record_id 的本地文件

python scripts/main.py --input payload.local.json

URL 下载 + 替换模式

python scripts/main.py --input payload.url.json

飞书消息附件

python scripts/main.py --input payload.feishu_message.json

通过表名自动解析表格

python scripts/main.py --input payload.table_name.json

通过字段值查找记录

python scripts/main.py --input payload.lookup.json

创建带附件的新记录

python scripts/main.py --input payload.create_record.json

基础验证

使用前请先执行语法检查：

python -m py_compile scripts/*.py

该命令验证以下内容：

• 所有 Python 模块语法合法
• 无未定义变量或非法导入

输出

成功

{
  "ok": true,
  "file_token": "vobxxxxxxxxxx",
  "app_token": "bascxxxxxxxxxx",
  "table_id": "tblxxxxxxxxxx",
  "table_name": "合同归档",
  "record_id": "recxxxxxxxxxx",
  "field_name": "附件",
  "field_id": "fldxxxxxxxxxx",
  "upload_type": "direct",
  "attachment_count": 3,
  "mode": "append",
  "message": "Successfully uploaded 'report.pdf'..."
}

错误

{
  "ok": false,
  "error": "Table 'xxx' not found. Available tables: 表 1, 表 2",
  "error_type": "resolve_error"
}

常见错误

为何本技能可适配任意 Bitable

本技能未对任何特定 Bitable 进行硬编码：

1. 动态 app_token：从输入中读取，非硬编码
2. 动态表格解析：支持 table_id（直连）或 table_name（API 查询）
3. 动态字段解析：支持 field_id（直连）或 field_name（API 查询）
4. 动态记录解析：支持 record_id、lookup 搜索或新建模式

参考文档

详见 references/feishu-api-notes.md，其中包含：

• 为何来自 IM/Drive 的 file_token 不可直接复用于 Bitable 附件
• 为何必须上传至 bitable_file 专用上传端点
• API 实现细节与可扩展性接入点
• 已知不确定性项（可能需在具体环境中验证）