OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add riba2534/feishu-cli --skill feishu-cli-bitable
飞书多维表格（Bitable/Base）操作。底层使用 base/v3 新 API，支持视图完整配置写入、 记录 upsert、记录批量获取、记录附件上传下载、记录修改历史、角色 CRUD + 协作者增删、 多维表格本体重命名/高级权限开关、数据聚合查询、 仪表盘 + 仪表盘块 CRUD、表单 + 表单问题 CRUD、工作流 CRUD 等。 当用户请求"创建多维表格"、"操作数据表"、"添加记录"、"查询记录"、"管理字段"、 "多维表格"、"base"、"bitable"、"数据表"、"视图排序"、"视图过滤"、"视图分组"、 "角色"、"role"、"高级权限"、"advperm"、"数据聚合"、"data query"、 "仪表盘"、"dashboard"、"表单"、"form"、"工作流"、"workflow"、"记录附件"、 "复制多维表格"时使用。 支持 --as bot|user|auto 身份切换：默认 auto（User 优先、Tenant 兜底）， --as bot 用 App Token 操作多维表格，无需 auth login、永不过期， 适合 cron / 无人值守 / 脚本自动抓取多维表格内容。 凡涉及"App Token 读写 bitable"、"不登录抓多维表格"、"cron 定时同步多维表格"、 "bitable 报需要 User Token / 91403 没权限"时也应使用本技能。
npx skills add riba2534/feishu-cli --skill feishu-cli-bitable
通过 base/v3 API 操作飞书多维表格。bitable 也支持 base 别名。
API 切换：此技能已从旧的
bitable/v1切换到新的base/v3。字段名app_token和base_token在飞书文档里是同一个值的两种叫法（老 v1 叫 app_token，新 v3 叫 base_token），CLI 只认--base-token（--app-token已删除）。从多维表格 URL 里/base/<token>或/bitable/<token>片段里取 token 即可。
--as bot|user|auto 身份切换（详见下方「身份选择」），默认 auto（User 优先、Tenant 兜底）。已登录用 User Token，未登录自动回落 App Token；要稳定用 App Token 跑（cron）显式加 --as botX-App-Id header，自动注入）。--as bot / auto 回落 Tenant 时只靠 App 凭证，无需 auth login--as（命令组 persistent flag，所有子命令通用）飞书 base/v3 与 bitable/v1 API 本身同时支持 User 和 Tenant(App) 两种身份，本技能据此提供三档：
--as | 身份 | 何时用 | 是否需 auth login |
|---|---|---|---|
auto（默认） | User 优先、Tenant 兜底 | 交互式日常使用 | 否（未登录自动用 App Token） |
bot（= tenant/app） | 强制 App Token | cron / 无人值守 / 脚本自动抓取，永不过期 | 否 |
user | 强制 User Token | 必须以本人身份操作（个人 base、协作者权限） | 是（缺失报错） |
--as bot报91403 you don't have permission：不是 token 问题，是 Bot 还不是这张多维表格的协作者。把 Bot 加为协作者（feishu-cli perm add <base_token> --doc-type bitable --member-type open_id --member-id <bot_open_id> --perm full_access）或把文档可见性调到组织可见即可。Bot 自己创建的 base 默认就有权限。 历史背景：旧版本 bitable 命令在 CLI 侧硬性强制 User Token（未登录直接报错），其实底层 API 一直支持 Tenant Token——现已按官方lark-cli的--as模式放开。
update走bitable/v1（PUT apps/{app_token}，base/v3 无更新本体端点；app_token 即 base_token），仅支持云空间文件夹内的多维表格。--is-advanced true/false等价于advperm enable/disable的高级权限开关。
附件文件名：
download-attachment用附件原始文件名保存（不再用 file_token 命名）；目标已存在会直接报错，加--overwrite覆盖。三个附件命令均支持--dry-run（写前预览请求体）；upload/remove-attachment支持--format/--jq，download-attachment不支持（仅打印 JSON）。
视图配置自动包装规则（减少用户样板）：
view-sort-set可直接传[{...}]数组，自动包成{"sort_config":[...]}view-group-set可直接传[{...}]数组，自动包成{"group_config":[...]}- 其他配置（filter/visible-fields/timebar/card）必须传完整对象
视图配置 JSON Schema 速查：
把用户/群/部门加入或移出某个角色（走 bitable/v1 协作者端点 apps/{app_token}/roles/{role_id}/members）。
--member-id-type默认open_id，可选open_id|union_id|user_id|chat_id|department_id|open_department_id（与--member-id/--member-ids的 ID 类型对应）。member 写命令（create/delete/batch-create/batch-delete）均支持--dry-run/--format/--jq。 scope 不同：role member 走协作者端点，所需 scope 是bitable:app/bitable:app:readonly/base:collaborator:read，不是base:role——只申请base:role会撞 99991679。
⚠️ base/v3 的 data-query 端点挂在 base 级（不是 table 级），所以不需要 --table-id。
底层调用：POST /open-apis/base/v3/bases/{base_token}/data/query
查询 body 示例（LiteQuery DSL：dimensions / measures / filters，与上面 --config 一致）：
update是 PUT 整体替换，未提供的字段不保留；workflow_id为wkf前缀。 私有端点：公开 OpenAPI 仅文档化workflow list（只读），create/get/update/enable/disable走 base/v3 私有扩展端点（如撞限制可用feishu-cli api裸调兜底）。写命令（create/update/enable/disable）均支持--dry-run/--format/--jq。
block
--type取值：column|bar|line|pie|ring|area|combo|scatter|funnel|wordCloud|radar|statistics|text；图表块--data-config传table_name/series|count_all/group_by/filter，文本块传text。--data-config的内部结构由飞书图表 schema 定义、本地无离线校验（--dry-run也不校验内部字段），建议用block get先取一个已有图表块的结构作模板再改。--theme-style写入theme.theme_style，合法取值由飞书仪表盘主题 schema 定义（CLI 不做枚举校验）；不确定时省略此字段用默认主题，或dashboard get一个已配好主题的看板看其真实取值。 dashboard / block 全部写命令（create/update/delete/copy/arrange）均支持--dry-run预览请求体；全部命令支持--format json|pretty|table|ndjson|csv与--jq。
表单问题字段：
title(必填)/type(text/number/select/datetime/user/attachment/location)/description/required/multiple/options等；submit如需附件先用record upload-attachment思路拿 file_token 再写进--content。 form patch 走bitable/v1（不同于其它 form 命令的 base/v3）：因--shared/--shared-limit/--submit-limit-once是 bitable/v1 字段，整体路由到 bitable/v1 让分享相关字段一次生效。--shared-limit取值：off | tenant_editable | anyone_editable；仅显式设置的便捷字段才提交，复杂场景可用--config/--config-file裸传完整请求体。 form submit 的--content是裸字段 map（如{"评分":5}），不要外包{"fields":{...}}——CLI 不再自动解包，多套一层会丢数据。 form/field 全部写命令（create/patch/delete、field create/patch/delete、detail/submit）支持--dry-run预览；全部 form 命令支持--format/--jq；form create/patch、field create/delete均支持--config/--config-file裸传完整请求体作为便捷字段的逃生通道。
| 命令 | 所需 scope |
|---|---|
| 读操作（list/get/search/history） | base:app:readonly、base:table:readonly、base:record:readonly、base:field:readonly、base:view:readonly |
| 写操作（create/update/delete/batch） | base:app、base:table、base:record、base:field、base:view |
| 角色管理 | base:role:readonly / base:role |
| 角色协作者（role member） | bitable:app:readonly / bitable:app / base:collaborator:read（走 bitable/v1 协作者端点，不是 base:role） |
| 高级权限 | base:app_permission |
| 工作流 | 读 base:workflow:readonly / 写 base:workflow |
| 仪表盘 / 表单 | 读 base:dashboard:readonly / base:form:readonly，写 base:dashboard / base:form |
--base-token（--app-token 已删除）--dry-run 只在本轮新增的写命令上可用——dashboard/block 写、form/form field 写、workflow create/update/enable/disable、role member 写、record upload/download/remove-attachment、bitable update。旧写命令不支持（record batch-create/batch-update/upsert/delete、table/field/view/role create·update·delete、advperm enable/disable、bitable create/copy 等传 --dry-run 会报 unknown flag）。新命令的 dry-run 也尊重 --format/--jq（download-attachment 的 dry-run 始终打 stdout，不写 --output）。--format json|pretty|table|ndjson|csv（默认 json）+ --jq（内置 gojq）的主要是本轮新增命令（record batch-get、bitable update、dashboard/form/role member/workflow 各命令等），可 --jq '.items[].name' 提取或 --format table 表格化。大量旧命令不支持：record list/get/search/批量写、table/field/view/role list·CRUD、view-*-get/set、bitable create/copy/data-query/advperm、record download-attachment 等——这些直接打印 JSON（部分用旧式 -o json），需要过滤时改用 feishu-cli api ... --jq 或外部 jq。record batch-create / batch-update 由飞书后端限制，建议单批 ≤500 条view create --view-type 可选值：grid / kanban / gallery / gantt / calendarmedias/upload_all + append_attachments，download 走 get_attachments + medias/{ft}/download，单次 ≤50 个detail/submit 用 share-token（shr 前缀，从分享链接提取）无需 base_tokenfeishu-cli api 裸调兜底）：view 独立 filter-sort 端点（base-api.feishu.cn）# 创建多维表格
feishu-cli bitable create --name "项目管理" --time-zone Asia/Shanghai
feishu-cli bitable create --name "销售" --folder-token fldxxx
# 获取多维表格信息
feishu-cli bitable get --base-token bscnxxxx
# 复制多维表格
feishu-cli bitable copy --base-token bscnxxxx --name "副本"
feishu-cli bitable copy --base-token bscnxxxx --name "空白副本" --without-content
# 更新多维表格本体：重命名 / 开关高级权限（仅显式设置的字段才提交）
feishu-cli bitable update --base-token bscnxxxx --name "新表名"
feishu-cli bitable update --base-token bscnxxxx --is-advanced true # 开启高级权限feishu-cli bitable table list --base-token bscnxxxx
feishu-cli bitable table get --base-token bscnxxxx --table-id tblxxx
feishu-cli bitable table create --base-token bscnxxxx --name "任务表"
feishu-cli bitable table create --base-token bscnxxxx --config-file table.json
feishu-cli bitable table update --base-token bscnxxxx --table-id tblxxx --name "新名字"
feishu-cli bitable table delete --base-token bscnxxxx --table-id tblxxxfeishu-cli bitable field list --base-token xxx --table-id tblxxx
feishu-cli bitable field get --base-token xxx --table-id tblxxx --field-id fldxxx
feishu-cli bitable field create --base-token xxx --table-id tblxxx --config-file field.json
feishu-cli bitable field update --base-token xxx --table-id tblxxx --field-id fldxxx --config '...'
feishu-cli bitable field delete --base-token xxx --table-id tblxxx --field-id fldxxx
feishu-cli bitable field search-options --base-token xxx --table-id tblxxx --field-id fldxxx --query "关键词"feishu-cli bitable record list --base-token xxx --table-id tblxxx --view-id viewxxx --limit 100
feishu-cli bitable record get --base-token xxx --table-id tblxxx --record-id recxxx
feishu-cli bitable record batch-get --base-token xxx --table-id tblxxx --record-ids recxxx,recyyy
# batch-get 可选 flag：返回分享链接 / 自动计算字段 / 指定用户字段 ID 类型
feishu-cli bitable record batch-get --base-token xxx --table-id tblxxx --record-ids recxxx,recyyy \
--with-shared-url --automatic-fields --user-id-type open_id # user-id-type: open_id|union_id|user_id
feishu-cli bitable record search --base-token xxx --table-id tblxxx --config-file search.json
# upsert：不传 --record-id 则 POST 创建；传 --record-id 则 PATCH 更新（官方无专用 upsert 端点）
feishu-cli bitable record upsert --base-token xxx --table-id tblxxx --config '{"fields":{"名称":"测试"}}'
feishu-cli bitable record upsert --base-token xxx --table-id tblxxx --record-id recxxx --config '{"fields":{"状态":"完成"}}'
feishu-cli bitable record batch-create --base-token xxx --table-id tblxxx --config-file records.json
feishu-cli bitable record batch-update --base-token xxx --table-id tblxxx --config-file records.json
feishu-cli bitable record delete --base-token xxx --table-id tblxxx --record-id recxxx
# batch-delete：POST /records/batch_delete，单次最多 500 条；--record-ids CSV 或 --from-file 任选其一
feishu-cli bitable record batch-delete --base-token xxx --table-id tblxxx --record-ids rec_1,rec_2,rec_3
feishu-cli bitable record batch-delete --base-token xxx --table-id tblxxx --from-file ids.txt # 每行一个 record_id
# share-link：批量生成记录共享链接（v1.29+ 新增），单次最多 100 条
feishu-cli bitable record share-link --base-token xxx --table-id tblxxx --record-ids rec_1,rec_2,rec_3
# history-list：GET + query params（不是 POST body），--record-id 必填
feishu-cli bitable record history-list --base-token xxx --table-id tblxxx --record-id recxxx
feishu-cli bitable record history-list --base-token xxx --table-id tblxxx --record-id recxxx --page-size 50 --max-version 20
# 附件：upload/download 为 2 步编排（medias/upload_all + append/get_attachments），单次 ≤50 个
feishu-cli bitable record upload-attachment --base-token xxx --table-id tblxxx \
--record-id recxxx --field-id fldxxx --file ./report.pdf --file ./shot.png # --file 可重复
feishu-cli bitable record download-attachment --base-token xxx --table-id tblxxx \
--record-id recxxx --output ./downloads/ # 省略 --file-token 下全部
feishu-cli bitable record download-attachment --base-token xxx --table-id tblxxx \
--record-id recxxx --file-token boxcnxxxx --output ./a.pdf --overwrite # 指定单个附件，已存在则覆盖
feishu-cli bitable record remove-attachment --base-token xxx --table-id tblxxx \
--record-id recxxx --field-id fldxxx --file-token boxcnxxxx # --file-token 可重复# 基础 CRUD
feishu-cli bitable view list --base-token xxx --table-id tblxxx
feishu-cli bitable view get --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view create --base-token xxx --table-id tblxxx --name "看板视图" --view-type kanban
feishu-cli bitable view delete --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view rename --base-token xxx --table-id tblxxx --view-id viewxxx --name "新名字"
# 视图配置 get/set（6 种 × 2 = 12 命令）— set 方法是 PUT（全量替换）
feishu-cli bitable view view-filter-get --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view view-filter-set --base-token xxx --table-id tblxxx --view-id viewxxx \
--config '{"filter_info":{"conjunction":"and","conditions":[{"field_id":"fld1","operator":"is","value":["进行中"]}]}}'
feishu-cli bitable view view-sort-get --base-token xxx --table-id tblxxx --view-id viewxxx
# sort/group 的 --config 可传数组，自动包装为 {"sort_config":[...]} / {"group_config":[...]}
feishu-cli bitable view view-sort-set --base-token xxx --table-id tblxxx --view-id viewxxx \
--config '[{"field_id":"fld1","desc":false}]'
feishu-cli bitable view view-group-get --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view view-group-set --base-token xxx --table-id tblxxx --view-id viewxxx \
--config '[{"field_id":"fld1"}]'
feishu-cli bitable view view-visible-fields-get --base-token xxx --table-id tblxxx --view-id viewxxx
# visible-fields 必须传完整对象（不会自动包装）
feishu-cli bitable view view-visible-fields-set --base-token xxx --table-id tblxxx --view-id viewxxx \
--config '{"view_field":[{"field_id":"fld1","visible":true},{"field_id":"fld2","visible":true}]}'
feishu-cli bitable view view-timebar-get --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view view-timebar-set --base-token xxx --table-id tblxxx --view-id viewxxx \
--config '{"timebar":{"start_field_id":"fld_start","end_field_id":"fld_end","title_field_id":"fld_title"}}'
feishu-cli bitable view view-card-get --base-token xxx --table-id tblxxx --view-id viewxxx
feishu-cli bitable view view-card-set --base-token xxx --table-id tblxxx --view-id viewxxx \
--config '{"card":{"cover_field_id":"fld1","display_fields":["fld2","fld3"]}}'// view-filter（过滤条件）
{
"filter_info": {
"conjunction": "and",
"conditions": [
{"field_id": "fldxxx", "operator": "is", "value": ["进行中"]}
]
}
}
// view-sort（排序）
{
"sort_config": [
{"field_id": "fldxxx", "desc": false}
]
}
// view-group（分组）
{
"group_config": [{"field_id": "fldxxx"}]
}
// view-visible-fields（可见字段）
{
"view_field": [{"field_id": "fld1", "visible": true}, {"field_id": "fld2", "visible": false}]
}
// view-timebar（甘特图时间轴）
{"timebar": {"start_field_id": "fld1", "end_field_id": "fld2", "title_field_id": "fld3"}}
// view-card（卡片/画册视图）
{"card": {"cover_field_id": "fld1", "display_fields": ["fld2", "fld3"]}}feishu-cli bitable role list --base-token xxx
feishu-cli bitable role get --base-token xxx --role-id roxxx
feishu-cli bitable role create --base-token xxx --config-file role.json
feishu-cli bitable role update --base-token xxx --role-id roxxx --config '...'
feishu-cli bitable role delete --base-token xxx --role-id roxxxfeishu-cli bitable role member list --base-token xxx --role-id roxxx # 支持 --page-size(≤100)/--page-token
feishu-cli bitable role member create --base-token xxx --role-id roxxx --member-id ou_xxx
feishu-cli bitable role member delete --base-token xxx --role-id roxxx --member-id ou_xxx
# 批量增删：--member-ids 逗号分隔，单次 ≤100
feishu-cli bitable role member batch-create --base-token xxx --role-id roxxx --member-ids ou_a,ou_b,ou_c
feishu-cli bitable role member batch-delete --base-token xxx --role-id roxxx --member-ids ou_a,ou_bfeishu-cli bitable advperm enable --base-token xxx
feishu-cli bitable advperm disable --base-token xxxfeishu-cli bitable data-query --base-token xxx --config-file query.json
feishu-cli bitable data-query --base-token xxx --config '{"dimensions":[{"field_id":"fld_cat"}],"measures":[{"field_id":"fld_amt","type":"sum"}]}'{
"dimensions": [{"field_id": "fld_category"}],
"measures": [{"field_id": "fld_amount", "type": "sum"}]
}feishu-cli bitable workflow list --base-token xxx --page-size 50 --status enabled
feishu-cli bitable workflow list --base-token xxx --page-token TOKEN
feishu-cli bitable workflow get --base-token xxx --workflow-id wkfxxxx # 含 steps
feishu-cli bitable workflow create --base-token xxx --config '{"title":"My Workflow","steps":[...]}'
feishu-cli bitable workflow update --base-token xxx --workflow-id wkfxxxx --config-file wf.json # PUT 整体替换
feishu-cli bitable workflow enable --base-token xxx --workflow-id wkfxxxx
feishu-cli bitable workflow disable --base-token xxx --workflow-id wkfxxxx# 仪表盘 CRUD（原有 list/copy）；create/update 支持便捷字段 --name/--theme-style 或 --config/--config-file
feishu-cli bitable dashboard list --base-token xxx
feishu-cli bitable dashboard copy --base-token xxx --dashboard-id dsbxxxx --name "副本"
feishu-cli bitable dashboard create --base-token xxx --name "运营看板"
feishu-cli bitable dashboard get --base-token xxx --dashboard-id dsbxxxx
feishu-cli bitable dashboard update --base-token xxx --dashboard-id dsbxxxx --name "新名字"
feishu-cli bitable dashboard delete --base-token xxx --dashboard-id dsbxxxx
feishu-cli bitable dashboard arrange --base-token xxx --dashboard-id dsbxxxx # 服务端智能排版，无 body
# 仪表盘块 block CRUD；create --type 取值见下
feishu-cli bitable dashboard block create --base-token xxx --dashboard-id dsbxxxx \
--type column --name "按月统计" --data-config '{"table_name":"任务","group_by":[{"field_id":"fld_month"}]}'
feishu-cli bitable dashboard block list --base-token xxx --dashboard-id dsbxxxx
feishu-cli bitable dashboard block get --base-token xxx --dashboard-id dsbxxxx --block-id blkxxxx
feishu-cli bitable dashboard block update --base-token xxx --dashboard-id dsbxxxx --block-id blkxxxx --name "新块名"
feishu-cli bitable dashboard block delete --base-token xxx --dashboard-id dsbxxxx --block-id blkxxxx# 表单 CRUD（原有 get/patch）
feishu-cli bitable form create --base-token xxx --table-id tblxxx --name "报名表" --description "活动报名"
feishu-cli bitable form list --base-token xxx --table-id tblxxx # 列出表下所有表单，支持 --page-size(≤100)/--page-token
feishu-cli bitable form get --base-token xxx --table-id tblxxx --form-id vewxxx
feishu-cli bitable form patch --base-token xxx --table-id tblxxx --form-id vewxxx --name "新名字"
# patch 一键开启共享（走 bitable/v1，shared 系字段才生效）
feishu-cli bitable form patch --base-token xxx --table-id tblxxx --form-id vewxxx \
--shared true --shared-limit anyone_editable --submit-limit-once true
feishu-cli bitable form delete --base-token xxx --table-id tblxxx --form-id vewxxx # form_id 即表单视图 view_id
# 按分享 token（shr 前缀）取详情 / 提交，无需 base_token
feishu-cli bitable form detail --share-token shrcnxxxx
feishu-cli bitable form submit --share-token shrcnxxxx --content '{"评分":5,"评价":"很好"}' # 不处理附件
# 表单问题 field（别名 questions）：list/patch + 批量 create/delete（单次 ≤10）
feishu-cli bitable form field list --base-token xxx --table-id tblxxx --form-id vewxxx
feishu-cli bitable form field create --base-token xxx --table-id tblxxx --form-id vewxxx \
--questions '[{"type":"text","title":"你的名字","required":true}]'
feishu-cli bitable form field patch --base-token xxx --table-id tblxxx --form-id vewxxx --config-file q.json
feishu-cli bitable form field delete --base-token xxx --table-id tblxxx --form-id vewxxx --question-ids fld001,fld002# 1. 创建多维表格
BASE_TOKEN=$(feishu-cli bitable create --name "任务跟踪" -o json | jq -r '.base.base_token')
# 2. 创建数据表
TABLE_ID=$(feishu-cli bitable table create --base-token $BASE_TOKEN --name "待办" | jq -r '.table.table_id')
# 3. 添加字段
feishu-cli bitable field create --base-token $BASE_TOKEN --table-id $TABLE_ID --config '{
"field": {"name": "状态", "type": "select", "property": {"options": [{"name": "待办"}, {"name": "进行中"}, {"name": "完成"}]}}
}'
# 4. 批量写入记录
feishu-cli bitable record batch-create --base-token $BASE_TOKEN --table-id $TABLE_ID --config-file records.json
# 5. 创建自定义视图
VIEW_ID=$(feishu-cli bitable view create --base-token $BASE_TOKEN --table-id $TABLE_ID --name "进行中" --view-type grid | jq -r '.view.view_id')
# 6. 配置视图过滤
feishu-cli bitable view view-filter-set --base-token $BASE_TOKEN --table-id $TABLE_ID --view-id $VIEW_ID --config '{
"filter_info": {
"conjunction": "and",
"conditions": [{"field_id": "fld_status", "operator": "is", "value": ["进行中"]}]
}
}'
# 7. 配置排序（按创建时间降序）
feishu-cli bitable view view-sort-set --base-token $BASE_TOKEN --table-id $TABLE_ID --view-id $VIEW_ID --config '{
"sort_config": [{"field_id": "fld_create_time", "desc": true}]
}'