1.1 Python SDK vs 手机快捷指令#

• Python SDK（封装视角）：通过 lark-oapi 库，只需填入 APP_ID 和 APP_SECRET，SDK 在底层自动完成鉴权换 Token、缓存与请求头装配。
• 手机端/原生 HTTP（底层视角）：没有 SDK 支持，必须由快捷指令手动按顺序发起 2 步（文字版） 或 3 步（图片版） 标准 HTTP 请求。

1.2 数据流向图解#

2.1 必备的 4 个核心标识符#

在开发或配置时，准备好以下 4 项参数：

2.2 两层权限（缺一不可）#

1. 应用 API 权限（开发者后台）：
   • 申请 查看、评论、编辑和管理多维表格 (bitable:app)
   • 申请 查看、评论、编辑和管理云空间中所有文件 (drive:drive)
   • 关键：勾选后必须进入「版本管理与发布」创建并发布新版本，权限才会生效。
2. 多维表格文档协作者权限（多维表格前端）：
   • 打开目标多维表格，点击右上角「…」→「添加文档应用」；
   • 搜索并选择刚才创建的自建应用，赋予编辑权限。

2.3 多维表格字段配置#

在多维表格中建好以下字段（名称需与脚本/快捷指令完全一致）：

接口 1：获取租户访问凭证 (tenant_access_token)#

• 请求方式：POST
• 请求 URL：https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
• 请求头 (Headers)：

  Content-Type: application/json; charset=utf-8
  

• 请求体 (Body - JSON)：

  {
    "app_id": "你的_APP_ID",
    "app_secret": "你的_APP_SECRET"
  }
  

• 返回示例：

  {
    "code": 0,
    "msg": "ok",
    "tenant_access_token": "t-g1049b1xxxxxxxxxxxx",
    "expire": 7140
  }
  

• 解析字段：提取 tenant_access_token（有效期 2 小时）。

接口 2：上传图片素材 (upload_all)#

• 请求方式：POST
• 请求 URL：https://open.feishu.cn/open-apis/drive/v1/medias/upload_all
• 请求头 (Headers)：

  Authorization: Bearer <获取到的_tenant_access_token>
  

• 请求体格式：multipart/form-data（表单提交）
• 表单字段 (Form Data)：

• 返回示例：

  {
    "code": 0,
    "msg": "success",
    "data": {
      "file_token": "boxcnABC123XYZ456"
    }
  }
  

• 解析字段：提取 data.file_token。

接口 3：多维表格新增记录 (records/create)#

• 请求方式：POST

• 请求 URL：https://open.feishu.cn/open-apis/bitable/v1/apps/{APP_TOKEN}/tables/{TABLE_ID}/records

• 请求头 (Headers)：

  Authorization: Bearer <获取到的_tenant_access_token>
  Content-Type: application/json; charset=utf-8
  

• 请求体 (Body - JSON)：

  情况 A：纯文字记账

  {
    "fields": {
      "货币": -43.98,
      "备注": "盖饭"
    }
  }
  

  情况 B：带图片凭证记账（注意：图片字段是包含对象的数组）

  {
    "fields": {
      "货币": -43.98,
      "备注": "盖饭",
      "图片": [
        {
          "file_token": "boxcnABC123XYZ456"
        }
      ]
    }
  }
  

• 返回示例：

  {
    "code": 0,
    "msg": "success",
    "data": {
      "record": {
        "record_id": "recuz789xxxx"
      }
    }
  }
  

4.1 复刻版本一：极速文字记账#

4.2 复刻版本二：图文结合记账（带小票/截图）#

[开始]
  │
  ├─> 1. 判断是否有图片输入（快捷指令输入 / 相册选择 / 拍照）
  │      ├─ 有图片：设为变量 [原始图片]
  │      └─ 无图片：变量 [原始图片] 为空
  │
  ├─> 2. 要求输入 [金额] (转负数) 和 [备注]
  │
  ├─> 3. 调用接口 1 获取 tenant_access_token ──> 得到变量 [Token]
  │
  ├─> 4. 如果 [原始图片] 有值：
  │      ├─ a. 动作 [转换图像]：将图片转为 JPEG 格式（压缩质量 75%）
  │      ├─ b. 动作 [获取文件详细信息]：获取图片 "文件大小"（字节数）
  │      ├─ c. 动作 [获取当前日期]：格式化为 yyyy-MM-dd.jpg
  │      ├─ d. 动作 [获取 URL 内容]（调用接口 2 upload_all）：
  │      │       URL: https://open.feishu.cn/open-apis/drive/v1/medias/upload_all
  │      │       标头: Authorization: Bearer [Token]
  │      │       请求体: 表单 (Form)
  │      │         - file_name = [日期文件名]
  │      │         - parent_type = bitable_image
  │      │         - parent_node = [你的 APP_TOKEN]
  │      │         - size = [文件大小]
  │      │         - file = [处理后的图片]
  │      ├─ e. 提取返回中的 $.data.file_token ──> 得到变量 [file_token]
  │      └─ f. 用文本拼接带附件的 JSON（见 4.3 节技巧）
  │
  ├─> 5. 否则（无图）：
  │      └─ 用文本拼接纯文字 JSON
  │
  ├─> 6. 调用接口 3 写入记录
  │
  └─> 7. 弹出通知与震动提示完成

4.3 快捷指令进阶技巧：用「文本」模板拼接 JSON#

在 iOS 快捷指令中手动配置多层嵌套 JSON 容易出错。推荐做法：使用一个「文本」动作写好模板，把变量直接插入其中，再把文本传给请求体：

带图 JSON 文本模板：

{
  "fields": {
    "货币": 最终金额,
    "备注": "备注",
    "图片": [
      {
        "file_token": "file_token"
      }
    ]
  }
}

(在快捷指令编辑器中，将 最终金额、备注、file_token 替换为对应的魔术变量。在「获取 URL 内容」中，请求体选择「文件」，并将该文本作为输入即可)

5.1 环境安装#

python -m pip install lark-oapi Pillow

5.2 脚本配置#

打开 记账.py 或 记账-图片版.py，填写配置区域：

APP_ID = "cli_xxxxxxxxxxxxxxxx"
APP_SECRET = "your_app_secret"

APP_TOKEN = "bascnxxxxxxxxxxxxxxx"
TABLE_ID = "tblxxxxxxxxxxxxxxx"

AMOUNT_FIELD = "货币"
REMARK_FIELD = "备注"
IMAGE_FIELD = "图片"      # 图片版专用
EXPENSE_AS_NEGATIVE = True # 支出强制记负数

5.3 运行命令#

# 普通文字版
python 记账.py 43.98 盖饭

# 图片版（不带图）
python 记账-图片版.py 43.98 盖饭

# 图片版（带同目录图片）
python 记账-图片版.py 43.98 盖饭 1.png

# 图片版（带绝对路径图片）
python 记账-图片版.py 43.98 盖饭 "D:\账单\1.png"

5.4 图片版的关键优化#

1. 自动纠正方向：通过 ImageOps.exif_transpose() 读取手机拍摄的 EXIF 方向，避免小票倒置。
2. 透明图层铺白底：将带有透明通道的 PNG/WebP 转为纯白背景 RGB。
3. 内存无损压缩：在 BytesIO 内存流中直接压缩为 JPEG（Quality 75），不产生本地临时垃圾文件。
4. 智能参数解析：脚本自动检测最后一个参数是否为有效图片路径；若是则上传图片，其余参数合并为备注。

参考资料#

• 飞书开放平台：新增多维表格记录
• 飞书开放平台：上传素材
• 飞书开放平台：获取 tenant_access_token
• 飞书开放平台：申请 API 权限