Repository navigation
对照官方 CLI(larksuite/cli v1.0.99)逐领域对齐:统一退出码与 --dry-run 语义,内嵌 OpenAPI catalog 改为从官方同步,
并补齐妙搭、多维表格、Slides、会中控制、妙记编辑、条件格式、OKR 等能力。除下方「行为变化」外,已有命令不带新参数时的
默认值、身份、stdout 输出结构与成功路径退出码均保持不变。
行为变化(升级前请阅读)
| 变化 | 影响范围 | 迁移建议 |
|---|---|---|
| 参数/用法错误退出码 1 → 2,错误文本不变 | auth/search/user/config/skills/update、doc/markdown/board/slides、drive/file/media/wiki/comment/perm、msg/chat/mail/event、sheet、bitable、calendar/task/tasklist/approval/attendance/okr、vc/minutes、apps | 按退出码 1 判断「参数写错」的脚本改为判断 2;2 表示不要重试 |
本地参数校验前移到 config.Validate() 与身份解析之前 |
同上 | 「缺凭据且参数错」由 exit 3 变为 2;task create/update --due 非法、search messages 非法参数不再先触发 token 刷新;user search --email 与 --query 冲突不再先解析 User Token |
无凭据 --dry-run 由 exit 3 变为 0(静态预览,不联网) |
doc create/content-update/history revert/resource、markdown 全家桶、board import/update、bitable 全部叶子命令、apps update/access-scope-set/html-publish、mail rule-*/signature/template delete/thread-modify/thread-trash、okr progress update、drive export/import/move/update-title/apply-permission、file delete、comment reply update/react、vc bot meeting-join/leave/events、vc meeting list-active、wiki member add/node-copy/space-create | CI 中可直接用 --dry-run 校验命令构造;去掉 --dry-run 仍为 exit 3。board clone、drive push/pull 的 --dry-run 需要读取远端,仍需凭据 |
离线 catalog(FEISHU_CLI_REMOTE_META=off 或远端不可达)由 12 service / 152 method 变为 15 / 256 |
schema、api、离线 auth login --domain [--recommend] |
审批 7 个已下线的 uat_* 路径修正为当前端点(如 approval.tasks.approve → /tasks/pass),approval.tasks.query 的 topic 枚举去掉 3;移除无引用的陈旧方法 calendar.events.search(官方为 search_event)与 im.chats.list;离线推荐 scope 随之变化(chat/im/task/drive/okr 等域新增,drive 域去掉 docs:event:subscribe),用 auth login --domain <d> --recommend 前可先 auth check 对比 |
sheet read / read-plain 文本模式中富文本单元格渲染为 text(link) |
原先输出 Go map[...] 语法 |
解析文本输出的脚本改用 -o json(JSON 与旧版逐字节一致) |
apps html-publish --wait / apps release create --wait 轮询遇限流或网络错误时指数退避(2s 起、单次 ≤30s)继续查询 |
连续失败 >5 次或超出 --wait-timeout 才失败;发布提交本身不重放 |
无需改动;限流提示改为退避建议,不再追加 app_id / --app-type 参数提示 |
apps update 缺字段错误文本变为「至少提供 --name、--description、--icon-url 或 --icon-file 之一」 |
随新 flag 调整 | 匹配旧文本的脚本需更新 |
mail template delete / mail thread-trash 先解析身份再确认 |
未登录时 exit 3 先于 exit 10 | 非交互脚本先确认已登录再追加 --yes |
board import --engine local 缺 whiteboard-cli 由 exit 1 变为 2(文本不变),检查提前到凭据校验之前 |
— | — |
离线 catalog 补丁层:schema status、auth status、doctor --only catalog 的方法数多出 local_supplements 补回的 task.comments.*(联网模式下如 250 → 255);schema status --format json 与 auth status -o json 的 catalog 新增 supplements 字段 |
只新增 | 精确比对方法数的脚本需更新 |
approval task rollback / add-sign / remind 先校验配置与 User Token 再确认 |
未登录且非交互时 exit 10 → exit 3 | 非交互脚本先确认已登录再追加 --yes |
okr comment create / update / delete 只支持 User |
显式 --as bot 原先被静默忽略,现在 exit 2;--help 中 --as 默认显示为 user |
去掉 --as bot |
非法 --format / --jq 统一为用法错误,gojq 表达式在读配置与凭据之前校验 |
原先部分命令 exit 1,或写命令先执行写入再报错;api --dry-run --jq '-r' 0 → 2 |
修正表达式;event consume 的点路径 --jq 不受影响 |
drive search 单个位置参数作为关键字 |
原先位置参数被静默忽略、返回不相关结果;多于 1 个或与 --query 同用时 exit 2 |
关键字可写成唯一位置参数,或继续用 --query |
本地前置校验:sheet write 显式范围小于数据、sheet dropdown delete --ranges 超过 100、drive preview --type 非法取值、vc bot 非法 --as、task comment 非法 ID |
原先联网后由服务端拒绝(exit 1)或先报缺凭据(exit 3),现在联网前 exit 2 | 服务端本就拒绝这些输入,合法调用不受影响 |
msg history / thread-messages --concise 正文行首的列表、标题、引用、分隔线语法加反斜杠转义 |
只影响显式 --concise 的输出文本 |
解析 concise 文本的脚本注意转义符;默认 JSON 不变 |
| 飞书 SDK 日志不再写 stdout;换取 tenant token 的网络错误归为网络错误 | -o json 管道不再混入 [Warn] 日志;代理/DNS 失败 exit 3 → 4(可重试) |
无需改动 |
slides media-upload 文件类型/大小检查提前到 wiki 链接解析之前;doc read --keyword 正则在导出全文前校验;doc export --engine docs_ai 的 --doc-format/--detail 在 wiki 解析前校验 |
— | 参数错误更早报出,不再先联网 |
新增
平台与认证
- 全局
--error-format text|json(默认 text,输出逐字节不变):json 时 stderr 输出一行{"error":{message,exit_code,kind,code,log_id,missing_scopes,retryable,hint}},code/log_id/missing_scopes 取不到时省略。 api --file [field=]path|-:multipart/form-data 上传,--data顶层键作为表单字段;与--data-file、--page-all互斥,仅 POST/PUT/PATCH/DELETE;路径在首个网络请求前校验,--dry-run只显示文件名与大小。auth login --json的 authorization_complete 与auth status -o json在未下发 refresh_token 时新增no_refresh_token{cause,fix,settings_url}。schema status新增补丁层:远端 overlay 之后按local_supplements白名单从内嵌基线补回公开 meta 缺失的方法(首批task.comments.*),JSON 新增supplements字段;联网模式下schema task.comments.list恢复可用。离线--domain mindnotes可用。
云文档、画板与 Slides
slides history list / revert / revert-status:历史版本与回滚。revert 带确认门禁,--history-version-id须为正整数;--wait按poll_after_ms只轮询不重放,整体 ≤5 分钟,超时仍 running 时 exit 0 并输出wait_timed_out: true。- slides、board 写命令新增
--as bot|user|auto(默认 bot):不传时身份解析与旧版一致,显式--as时 dry-run 预览多一个identity字段。 --dry-run:doc media-insert(多步计划,不读剪贴板)、slides media-upload、board delete(仍无确认门禁,与其他存量删除命令一致,执行前先--dry-run)、board create-notes。- feishu-cli-visual 技能收录官方 Slides 图表示例、XSD 图表节选与 IconPark 常用图标清单。
云盘、知识库与权限
drive preview <file_token|url>(--list-only、--type pdf|pdf_lin|html|text|image|source_file、--version、-o、--overwrite)与drive cover <file_token|url>(--spec default|icon|grid|small|middle|big|square,--list-only本地列出规格)。预览接口返回空内容时报错且不写空文件。drive search新增时间窗--edited-*、--commented-*、--opened-*、--created-*(-since/-until,接受 7d/1m/1y/日期/RFC3339/unix 秒),--mine(所有者为自己)、--created-by-me/--original-creator-ids(原始创建者)。opened 窗口 >90 天只查最近切片并在 stderr 列出全部切片,>365 天 exit 2。不传新 flag 时请求体不变。drive push/pull --dry-run:输出差集计划(create_folder/upload/overwrite/download/skip/conflict/delete_remote/delete_local),不上传、不下载、不删除,不要求--yes;需要凭据只读列举远端。- perm 全家桶
<doc_token>接受文档链接(/wiki/ → wiki,/minutes/ → minutes),显式--doc-type与链接推断的类型冲突时 exit 2;perm add/delete/update --member-kind wiki_space_member|wiki_space_viewer|wiki_space_editor(仅--member-type wikispaceid)。 --dry-run:perm 全家桶;wiki create/delete/delete-space/move/move-docs/move-to-drive/update、wiki member remove;comment add/resolve/unresolve/reply add/reply delete;file copy/mkdir/move/shortcut/upload/version create/delete/revert;drive upload/secure-label set/add-comment;media upload;minutes apply-permission。
消息与事件
msg read-status om_xxx ...:批量查询本人对消息的已读状态(1–50 个,仅 User)。msg history/msg thread-messages --concise:紧凑 Markdown 视图,与-o json互斥。msg forward支持omt_话题 ID;msg forward/msg merge-forward新增--dry-run。event consume新增--param k=v(可重复)、--as user|bot|auto、--dry-run(无凭据预览订阅计划);新 EventKeyminutes.minute.generated_v1、drive.notice.comment_add_v1、task.task.update_user_access_v2、board.whiteboard.updated_v1(必填--param whiteboard_id)、mail.user_mailbox.event.message_received_v1(复用单连接)。event list/schema --json对相关 key 新增params、subscribe_no_body、subscribe_body字段。
邮件
mail share-to-chat:把邮件或线程以卡片分享到 IM 会话(仅 User,--dry-run)。mail send/reply/reply-all/forward/draft-send --send-time <unix 秒>:定时发送(≥5 分钟,须--confirm-send);mail send/reply/reply-all/forward/draft-create --request-receipt:请求已读回执。
电子表格
sheet cond-format list/create/update/delete:条件格式(cellIs / containsText / timePeriod / 空值 / 重复 / 唯一),规则、范围、颜色本地校验,子表名自动换算;update(整条覆盖)与 delete 带确认门禁。--dry-run:sheet write、clear、table-put、unprotect、filter delete、image delete、dropdown delete、filter-view delete、filter-view condition delete。
多维表格
bitable field extension get/update/update-cells(字段 AI 扩展,--config本地严格校验,写命令带确认门禁)、bitable field button-rule bind/get/unbind(按钮字段绑定工作流)。bitable table copy/copy-status(--range schema|all、--wait;提交遇网络错误提示结果未知、不自动重放)。bitable template categories/list/search(模板中心只读)、bitable block create/move/rename/delete(顶层块,delete 带确认门禁)、bitable copy --time-zone。bitable resolve离线解析 BaseApp/app/链接;全部 bitable 叶子命令支持--dry-run,多数命令支持--format/--jq(不传时输出不变)。
日历、任务与 OKR
task create --assignee/--follower/--tasklist-id/--idempotency-key/--data、task update --data、tasklist task-add --section-guid;task/tasklist 全部写命令支持--dry-run。task comment get/update/delete(delete 带确认门禁)。calendar create-event/update-event --description-format text|markdown(markdown 写富文本描述,当前目录内本地图片自动上传)、calendar create-event --meeting-owner-id(仅--as bot);calendar rsvp、calendar attendee add、okr upload-image新增--dry-run。okr weight、okr reorder、okr indicator update、okr objective batch-create(失败回滚)、okr comment get/update/delete(delete 带确认门禁)。
会议与妙记
vc bot meeting-countdown、meeting-message-send(--uuid幂等)、meeting-screenshot(--output在首个网络请求前校验,已存在默认拒绝):--as默认 auto。vc bot meeting-invite(all_suggested/selected)、vc bot meeting-end(确认门禁):仅 Bot。minutes upload --file-token、minutes update --topic、minutes summary、minutes todo、minutes speaker-replace、minutes word-replace:仅 User,支持--dry-run,token 可写妙记链接;覆盖摘要、删除待办、批量替换说话人与词语带确认门禁(非交互未--yesexit 10)。vc note transcript --overwrite:目标已存在且未传时 stderr 告警,默认仍覆盖。
妙搭
apps delete(--confirm-name必填,先比对当前名称再删除,带确认门禁)、apps release create(按分支发布,--wait)、apps features(功能开关只读)、apps list --owner-id、apps update --icon-url/--icon-file、apps access-scope-get --dry-run。
修复
- 未下发 refresh_token 的提示改为归因应用安全设置(未开启「刷新 user_access_token」或开启后未发版),login/status/doctor 给出设置页链接;access_token 过期且从未下发 refresh_token 时给独立文案,退出码仍为 3。
sheet table-get:下拉框单元格(V3 返回#UNSUPPORTED_TYPE)原先读成 null,get→put 往返会清空原值;现按纯文本回填,失败时 stderr 列出单元格地址。sheet read-rich遇到该类型时 stderr 告警并提示改用 read-plain。- perm 命令遇到非 JSON 响应时不再外泄响应头,改为「服务端返回非 JSON 响应(HTTP 404)」与处理提示。
- apps 限流(99991400 / HTTP 429)时提示退避重试,不再给出无关的参数提示。
--error-format json:未知命令与 flag 解析失败时同样输出 JSON 信封;flag 正常解析时不再被其他 flag 取值里的--error-format=json误触发;仍以code=N文本返回的旧错误补回code/log_id。默认文本输出逐字节不变。api --file:含=的本地路径不再被误拆成field=path;响应超过 32MiB 显式报错而非静默截断;真实网络错误 exit 4,host 白名单等本地策略拒绝不再被当成可重试的网络错误。no_refresh_token.settings_url指向签发该 token 的应用;doctor在未下发 refresh_token 时给出与auth status一致的提示(JSON 新增hint)。- 事件订阅:画板事件按
whiteboard_id过滤未命中时遵循 ACK 策略(确认是唯一长连接才 ACK 丢弃,否则交由服务端重投);订阅生命周期按「EventKey + 订阅身份 +--param」计数,旧版 bus.json 条目保守计入,不会误注销他人订阅;IM 等无需订阅的 key 与订阅类 key 同时监听时可以--as user;画板事件体解析失败只告警一次。 msg history / thread-messages --concise:@_user_1不再误伤@_user_10;正文行首的列表、标题、引用、分隔线语法加转义。sheet table-get下拉框回填在两个接口返回的范围起点不一致时告警且不回填,避免错位;sheet write/clear/dropdown delete的--dry-run预览范围与真实请求一致(需要子表列表才能确定时在步骤说明中注明)。- 新增的覆盖 / 删除类命令补齐确认门禁:
minutes summary、minutes todo(含 delete)、minutes speaker-replace/word-replace、sheet cond-format update。 bitable table copy --wait:服务端错误不再误报「--task-id 无效」;任务终态失败时提示可重新提交,不再提示续查;copy-status遇到已清理的任务(800030110)给出处理提示。field extension update-cells、field button-rule的--table-id/--field-id传名称时先解析为 ID(update-cells 传规范 tbl/fld ID 时仍只发一个请求,不新增 scope 依赖)。okr objective batch-create拿不到 objective_id 时,错误说明该目标可能残留、需手动清理,不再声称已全部回滚。calendar --description-format markdown不再上传代码块中的图片语法,支持带标题的图片写法。
开发与测试
- 修复
internal/event竞态测试偶发失败:宿主机端口扫描器的探测请求打进 httptest 端口,测试现在识别并忽略这类请求,并主动注入一次做回归;全量测试中 slice flag 复位串扰同步修复。 - 新增契约门禁
cmd/contract_gate_test.go:静态扫描 RunE,拦截「--dry-run前要求凭据」「--开头参数错误未用clierr.Usagef」「裸 HTTP 客户端」三类回归;存量例外登记在cmd/testdata/contract_gate_allowlist.txt,只减不增。 - 新增
scripts/sync_official_catalog.py:从官方仓库内嵌 catalog 重生成internal/registry/meta_data.json,校验 manifest sha256、输出 method 级 diff,未授权删除时失败;make update-meta OFFICIAL=/path/to/larksuite/cli [ALLOW_REMOVE='--allow-remove a.b.c']调用该脚本。internal/registry/local_supplements.json维护补丁层白名单。 scripts/check_skill_contracts.py:考勤非法日期的离线契约断言随退出码规范改为 exit 2。