飞书多维表格（Bitable）操作

feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。

前置条件

• 认证：需要有效的 App Access Token（环境变量 FEISHU_APP_ID + FEISHU_APP_SECRET，或 ~/.feishu-cli/config.yaml）
• 权限：应用需开通 bitable:app（多维表格读写）
• 验证：feishu-cli auth status 确认认证状态正常

核心概念

bitable ≠ sheet：feishu-cli bitable 操作多维表格（Base），feishu-cli sheet 操作电子表格（Sheets），两者是完全不同的产品和 API。

命令速查

# === 多维表格 ===
feishu-cli bitable create --name "项目管理"
feishu-cli bitable create --name "数据库" --folder FOLDER_TOKEN
feishu-cli bitable get <app_token>

# === 数据表 ===
feishu-cli bitable tables <app_token>
feishu-cli bitable create-table <app_token> --name "任务表"
feishu-cli bitable rename-table <app_token> <table_id> --name "新表名"
feishu-cli bitable delete-table <app_token> <table_id>

# === 字段管理 ===
feishu-cli bitable fields <app_token> <table_id>
feishu-cli bitable fields <app_token> <table_id> -o json    # JSON 输出（含完整 property）
feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"状态","type":3,"property":{"options":[{"name":"进行中"},{"name":"已完成"}]}}'
feishu-cli bitable update-field <app_token> <table_id> <field_id> --field '{"field_name":"新名称","type":1}'
feishu-cli bitable delete-field <app_token> <table_id> <field_id>

# === 记录操作 ===
feishu-cli bitable records <app_token> <table_id>
feishu-cli bitable records <app_token> <table_id> --page-size 100
feishu-cli bitable records <app_token> <table_id> --filter '{"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":["进行中"]}]}'
feishu-cli bitable records <app_token> <table_id> --sort '[{"field_name":"创建时间","desc":true}]'
feishu-cli bitable records <app_token> <table_id> --field-names "名称,状态,金额"
feishu-cli bitable get-record <app_token> <table_id> <record_id>
feishu-cli bitable add-record <app_token> <table_id> --fields '{"名称":"测试","金额":100,"状态":"进行中"}'
feishu-cli bitable add-records <app_token> <table_id> --data '[{"名称":"A","金额":100},{"名称":"B","金额":200}]'
feishu-cli bitable add-records <app_token> <table_id> --data-file records.json
feishu-cli bitable update-record <app_token> <table_id> <record_id> --fields '{"状态":"已完成"}'
feishu-cli bitable delete-records <app_token> <table_id> --record-ids "recXXX,recYYY"

# === 视图管理 ===
feishu-cli bitable views <app_token> <table_id>
feishu-cli bitable create-view <app_token> <table_id> --name "看板" --type kanban
feishu-cli bitable delete-view <app_token> <table_id> <view_id>

# === 多维表格复制 ===
feishu-cli bitable copy <app_token>
feishu-cli bitable copy <app_token> --name "副本" --folder-token FOLDER_TOKEN --without-content

# === 附件上传 ===
feishu-cli bitable record-upload-attachment <app_token> <table_id> <record_id> --field "附件" --file /path/to/file.pdf
# 自动追加到现有附件，不覆盖

# === 数据聚合查询 ===
feishu-cli bitable data-query <app_token> <table_id> --data '{"filter":{"conjunction":"and","conditions":[...]},"sort":[...],"field_names":["名称","金额"],"page_size":100}'
feishu-cli bitable data-query <app_token> <table_id> --data-file query.json

# === 仪表盘管理 ===
feishu-cli bitable dashboard list <app_token>
feishu-cli bitable dashboard get <app_token> <dashboard_id>
feishu-cli bitable dashboard create <app_token> --source-block-id <dashboard_id>   # 通过复制创建
feishu-cli bitable dashboard update <app_token> <dashboard_id>                     # API 限制
feishu-cli bitable dashboard delete <app_token> <dashboard_id>                     # API 限制

# === 仪表盘 Block 管理 ===
feishu-cli bitable dashboard-block list <app_token> <dashboard_id>
feishu-cli bitable dashboard-block get <app_token> <dashboard_id> <block_id>
feishu-cli bitable dashboard-block create <app_token> <dashboard_id>
feishu-cli bitable dashboard-block update <app_token> <dashboard_id> <block_id>
feishu-cli bitable dashboard-block delete <app_token> <dashboard_id> <block_id>

# === 视图高级配置 ===
feishu-cli bitable view-filter get <app_token> <table_id> <view_id>
feishu-cli bitable view-filter set <app_token> <table_id> <view_id> --config '{"conjunction":"and","conditions":[...]}'
feishu-cli bitable view-filter set <app_token> <table_id> <view_id> --config-file filter.json
feishu-cli bitable view-sort get <app_token> <table_id> <view_id>
feishu-cli bitable view-sort set <app_token> <table_id> <view_id> --config '[{"field_name":"创建时间","desc":true}]'
feishu-cli bitable view-sort set <app_token> <table_id> <view_id> --config-file sort.json
feishu-cli bitable view-group get <app_token> <table_id> <view_id>
feishu-cli bitable view-group set <app_token> <table_id> <view_id> --config '[{"field_name":"状态","desc":false}]'
feishu-cli bitable view-group set <app_token> <table_id> <view_id> --config-file group.json

# === 工作流管理 ===
feishu-cli bitable workflow list <app_token>
feishu-cli bitable workflow get <app_token> <workflow_id>
feishu-cli bitable workflow enable <app_token> <workflow_id>
feishu-cli bitable workflow disable <app_token> <workflow_id>

# === 表单管理 ===
feishu-cli bitable form list <app_token> <table_id>
feishu-cli bitable form get <app_token> <table_id> <form_id>
feishu-cli bitable form patch <app_token> <table_id> <form_id> --name "表单名称" --description "表单描述"

# === 角色管理 ===
feishu-cli bitable role list <app_token>
feishu-cli bitable role create <app_token> --name "编辑者" --config '{"table_roles":[...]}'
feishu-cli bitable role delete <app_token> <role_id>

# === 高级权限 ===
feishu-cli bitable advperm enable <app_token>     # 启用高级权限
feishu-cli bitable advperm disable <app_token>    # 禁用高级权限

别名：feishu-cli base 等同于 feishu-cli bitable。

字段类型速查

不支持 API 写入：公式、查找引用、创建时间、修改人、自动编号。

过滤运算符

踩坑必读

1. PUT fields 更新描述会清空单选选项

使用 update-field 更新单选（type=3）字段时，必须带上完整的 property（含 options 列表），否则选项被清空，所有记录中该字段的值丢失。

正确做法：先用 fields -o json 获取当前字段定义，合并修改后再更新：

# 1. 获取当前字段定义
feishu-cli bitable fields <app_token> <table_id> -o json

# 2. 更新时带上完整 property
feishu-cli bitable update-field <app_token> <table_id> <field_id> \
  --field '{"field_name":"状态","type":3,"property":{"options":[{"name":"待处理"},{"name":"进行中"},{"name":"已完成"}]},"description":{"text":"任务状态"}}'

2. 创建 Base 默认表有空行

bitable create 创建多维表格时自动创建一张默认表，里面有空记录（约 10 行）。写入数据前建议先清理：

# 1. 列出所有记录
feishu-cli bitable records <app_token> <table_id> -o json

# 2. 找出空行的 record_id，批量删除
feishu-cli bitable delete-records <app_token> <table_id> --record-ids "rec1,rec2,rec3"

3. 不要用复选框（Checkbox），用单选替代

复选框在 GUI 上容易误触。改用单选（type=3）配置"是/否"选项：

feishu-cli bitable create-field <app_token> <table_id> \
  --field '{"field_name":"必填","type":3,"property":{"options":[{"name":"是"},{"name":"否"}]}}'

4. 主索引列重命名需带 type

重命名 is_primary=true 的字段时必须带 type 字段，否则报 99992402：

# 错误：缺少 type
feishu-cli bitable update-field ... --field '{"field_name":"新名称"}'

# 正确：带上 type
feishu-cli bitable update-field ... --field '{"field_name":"新名称","type":1}'

5. API 创建的表格默认不可见

通过 API 创建的多维表格默认只有机器人能看到。创建后必须立即添加权限：

邮箱来源：~/.feishu-cli/config.yaml 中的 owner_email，或环境变量 FEISHU_OWNER_EMAIL。

# 添加 full_access 权限
feishu-cli perm add <app_token> --doc-type bitable --member-type email --member-id <owner_email> --perm full_access --notification

如果配置了 transfer_ownership: true，还需转移所有权：

feishu-cli perm transfer-owner <app_token> --doc-type bitable --member-type email --member-id <owner_email>

6. 关联字段的局限

关联字段是"一列关联一张表"的设计，无法让不同行关联到不同子表。如果主表的不同记录需要对应到不同子表，直接靠命名约定（如工具名称 → 同名子表）更实用。

7. 数据格式注意

• 数值不要传字符串：100 而非 "100"
• 日期必须是 13 位毫秒时间戳：1770508800000
• 批量操作最多 500 条：超出需要分批处理

典型工作流

创建项目管理表

# 1. 创建多维表格
feishu-cli bitable create --name "项目管理" -o json
# → app_token

# 2. 查看默认表
feishu-cli bitable tables <app_token>
# → table_id

# 3. 添加字段
feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"负责人","type":1}'
feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"状态","type":3,"property":{"options":[{"name":"待处理"},{"name":"进行中"},{"name":"已完成"}]}}'
feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"优先级","type":3,"property":{"options":[{"name":"P0"},{"name":"P1"},{"name":"P2"}]}}'
feishu-cli bitable create-field <app_token> <table_id> --field '{"field_name":"截止日期","type":5}'

# 4. 清理默认空行
feishu-cli bitable records <app_token> <table_id> -o json
feishu-cli bitable delete-records <app_token> <table_id> --record-ids "..."

# 5. 批量写入数据
feishu-cli bitable add-records <app_token> <table_id> --data '[
  {"标题":"完成需求文档","负责人":"张三","状态":"进行中","优先级":"P0"},
  {"标题":"代码审查","负责人":"李四","状态":"待处理","优先级":"P1"}
]'

# 6. 添加权限
feishu-cli perm add <app_token> --doc-type bitable --member-type email --member-id user@example.com --perm full_access --notification

# 7. 创建看板视图
feishu-cli bitable create-view <app_token> <table_id> --name "状态看板" --type kanban

API 限制

权限要求