飞书多维表格使用场景完整示例（base）

本文档提供基于 lark-cli base ... 的完整示例，覆盖 unified Shortcut 与当前 base/v3 原生 API 的常见组合方式。

返回: SKILL.md | 参考: shortcut 字段 JSON 规范 · shortcut 记录值规范

场景 1：用 unified Shortcut 快速建表

适合已经明确字段结构、希望一次性完成建表的场景。

lark-cli base +table-create \
  --base-token bascnXXXXXXXX \
  --name "客户管理表" \
  --fields '[
    {"name":"客户名称","type":"text"},
    {"name":"负责人","type":"user","property":{"multiple":false}},
    {"name":"签约日期","type":"datetime"},
    {"name":"状态","type":"single_select","property":{"options":["进行中","已完成"]}}
  ]'

场景 2：使用原生 API 创建数据表并查看字段

适合需要精确观察 base/v3 请求参数和响应结构的场景。原生 API 直接使用 base service。

步骤 1：在已有 Base 中创建数据表

lark-cli base tables create \
  --params '{"base_token":"bascnXXXXXXXX"}' \
  --data '{"name":"客户管理表"}'

步骤 2：列出字段

lark-cli base table.fields list \
  --params '{"base_token":"bascnXXXXXXXX","table_id":"tblXXXXXXXX","limit":100}'

提示：当前 base/v3 不再使用旧的 app_token / app.table.* 路径，统一改为 base_token + tables / table.fields / table.records。

场景 3：创建、读取、更新单条记录

新增记录

lark-cli base table.records create \
  --params '{"base_token":"bascnXXXXXXXX","table_id":"tblXXXXXXXX"}' \
  --data '{
    "客户名称":"字节跳动",
    "负责人":[{"id":"ou_xxx"}],
    "状态":"进行中"
  }'

列出记录

lark-cli base table.records list \
  --params '{"base_token":"bascnXXXXXXXX","table_id":"tblXXXXXXXX","limit":100}'

更新记录

lark-cli base table.records patch \
  --params '{"base_token":"bascnXXXXXXXX","table_id":"tblXXXXXXXX","record_id":"recXXXXXXXX"}' \
  --data '{
    "状态":"已完成"
  }'

删除记录

lark-cli base table.records delete \
  --params '{"base_token":"bascnXXXXXXXX","table_id":"tblXXXXXXXX","record_id":"recXXXXXXXX"}'

场景 4：配置视图筛选后按视图读取记录

当前 base/v3 原生 spec 没有独立 search 方法。需要筛选查询时，推荐先写视图筛选，再通过 view_id 读取记录。

更新视图筛选条件

lark-cli base view.filter update \
  --params '{"base_token":"bascnXXXXXXXX","table_id":"tblXXXXXXXX","view_id":"vewXXXXXXXX"}' \
  --data '{
    "logic":"and",
    "conditions":[
      {
        "field_name":"状态",
        "operator":"is",
        "value":["进行中"]
      }
    ]
  }'

按视图读取记录

lark-cli base table.records list \
  --params '{"base_token":"bascnXXXXXXXX","table_id":"tblXXXXXXXX","view_id":"vewXXXXXXXX","limit":100}'

场景 5：什么时候优先用 Shortcut

需要一次性建表并附带字段、视图时，优先 lark-cli base +table-create
需要按业务字段名做 upsert 时，优先 lark-cli base +record-upsert
需要配置筛选视图时，优先 lark-cli base +view-set-filter
需要记录历史时，优先 lark-cli base +record-history-list

原生 API 更适合两类场景：

需要逐步核对 schema base.<resource>.<method> 的请求参数
需要精确控制单次表 / 字段 / 记录 / 视图操作

examples.md 3.6 KB History Raw