本轮以「深度 review + 实物验证」为主线，系统校准了 CLI 与飞书官方 API 的契约。
命令面几乎无变化（36 个命令组零增减，新增 3 个子命令），但修掉了一批静默出错的问题。

从不可用恢复为可用

修复数据破坏路径（原实现 exit 0 静默发生）

• doc content-update --mode replace_all：不带 # 的模糊标题选择器同时命中父标题与子标题时，
  外层范围会吞掉未匹配的兄弟章节（实测 7 块文档替换后只剩 2 块）。现 fail-closed 要求明确选择器。
• drive pull --delete-local / push --delete-remote：身份静默降级 Bot 后远端视图更小、差集更大，
  会误删本地文件。现拒绝降级执行。
• event last-consumer 注销：会抹掉窗口期内新 consumer 刚建立的订阅（新 consumer 已 ready 却收不到事件）。
  现注销后复检并幂等补订阅。
• calendar agenda：午夜发生 DST 跳变的时区区间倒挂，静默返回空结果。
• wiki delete：确认提示未提级联范围（--include-children 默认 true）。现按实际范围提示。

安全

• 取 tenant token 曾用裸 http.Post，绕过重定向/凭证策略层——app_secret 可随 3xx 重放且无超时。
  统一改走带 host 校验与凭证剥离的 HTTP client（共 4 处）。
• wiki delete 的 loopback 豁免曾用前缀匹配，127.0.0.evil.com 可绕过 HTTPS 约束。改用 net.ParseIP。
• 分片上传 block_size 守卫在 64 位平台永久失效，畸形值会导致 panic。加合理上限。

新增命令

• markdown patch — 对云盘原生 .md 做局部补丁
• schema status — 查元数据来源与版本（embedded / cache / runtime）
• slides get — 获取演示文稿信息

向前兼容性

命令名、子命令、flag 零删除零改名；api 输出结构未变；stderr 新增的告警不污染 stdout（-o json 管道安全）。

有 4 处「以前静默通过、现在报错」，其中 3 处以前本就拿不到正确结果。唯一需要改脚本的是：

doc content-update --mode replace_all --selection-by-title "模糊词" 若同时命中父子标题，现在报错。
改法：加标题级别（"## 子标题"）或改用 --mode replace_range。

若 token.json 是旧版本（无 app_id），执行一次 feishu-cli auth token --bind-legacy-app --as user。

完整变更见 CHANGELOG.md。

多 Bot 身份支持

把「用哪个目录 / User Token」和「用哪套 App 凭证」拆成两条正交解析链，新增三个全局 flag：

feishu-cli profile list --json                  # 先看能操作哪些 Bot
feishu-cli --profile alert msg send ...         # 单次指定，不改默认指针
feishu-cli --bot-app-id cli_xxx --bot-app-secret xxx auth status -o json   # 单次覆盖 App 凭证，不写盘

• 目录 / User Token：--profile > FEISHU_PROFILE > active-profile 指针 > 旧布局
• App 凭证：--bot-app-id/--bot-app-secret > FEISHU_APP_ID/SECRET > 选中目录的 config.yaml

profile list / profile current 升级为 Bot 清单——即使没执行过 profile add，也会输出环境变量/旧布局正在用的那套（effective），不会让人误判「一个 Bot 都没有」。

凭证告警收窄

此前只要设置了 FEISHU_APP_ID 就对每条命令打印警告，而这正是文档推荐的单应用用法。现在只在真错配时出声：覆盖来的 app_id 与所选目录 config.yaml 不是同一个应用，或两半凭证落在不同层且无法确认同属一个应用。单应用配置完全静默。

身份字段只陈述可离线证明的事实（user_token_override / has_config_user_token / token_from_profile）。CLI 不再断言「本次实际用了哪个 token」——本项目按命令分四类 token helper，--as bot、默认 Bot 身份的写命令、只认 flag 的 vc bot meeting-join、固定读本地文件的 auth status 各有各的解析路径。

健壮性

• 单个 profile 的 config/token/cache 损坏不再让整张清单打不开，按来源分别记录原因并在输出中点名
• auth status / auth logout 在 config.yaml 损坏时降级继续（业务命令保持 fail-fast）
• 表格按显示宽度对齐，正确处理 CJK 与 ZWJ 表情（👨‍💻）
• commandOverride 改用独立 mutex，不再复用保护文件写入的锁

升级说明

JSON 契约完全向后兼容：profile list --json 的 name/path/active/has_config/has_token 与 auth status -o json 的全部既有字段，取值与 v1.38.4 逐一相同，只新增字段；所有命令退出码不变。

两处行为变更：

1. 人类可读输出有调整：profile list 表格列改为 ACTIVE/NAME/APP_ID/TOKEN/USER/SELECT，profile current 扩展为多行，auth status 新增 Profile/App ID 行。解析输出的脚本请改用 --json / -o json。
2. active-profile 指针失效且旧布局仍在时，改为优先旧布局（原为回退到字典序第一个 profile）。指针缺失时优先旧布局本就是既定行为，此改动让两种等价情况保持一致，不会把仍在用 ~/.feishu-cli/ 的用户静默切到另一套 Bot。

安装

curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash

跨文档同步块导出修复（Bug 修复版）

本版修复飞书文档导出时，跨文档引用同步块（ReferenceSynced）被静默导出为空的问题，并同步完成九个领域 Skill 的源码级校正。

修复

• 跨文档同步块完整展开：根据 source_document_id / source_block_id 调用源块 children API，并设置 with_descendants=true，导出源同步块及全部后代内容
• 失败不再静默：权限不足、API 异常、源块缺失或元数据不完整时，Markdown 保留带源标识的 WARNING 占位，stderr 输出明确诊断
• 缓存与循环保护：同一源块的重复引用只请求一次；跨文档递归或循环引用会安全停止并保留诊断
• 源文档媒体上下文：同步块中的图片、视频和画板使用正确的源文档/源块上下文下载
• CommonMark 列表缩进：按父级 marker 实际宽度累计缩进，覆盖无序、有序、多位编号、Todo 与混合多层嵌套

Skill 文档校正

• 对 9 个领域 Skill 完成源码级复核，修正 doc、wiki、file、perm、calendar、OKR、会议、邮件、消息卡片等命令示例和身份说明
• 清理领域合并后的自引用、孤儿参考文件和重复权威说明
• 同步 calendar rsvp 帮助文案为 User Token 必需
• Skill 顶层结构保持 9 个领域，33 个工作流与 499 个可执行命令继续保持唯一归属

验证

• 真实飞书 E2E：通过本机正式构建二进制创建跨文档同步引用，导出后源内容、三级嵌套列表和图片均正确；OpenAPI 回读确认目标为 block_type=50 并指向源 block_type=49
• 自动化覆盖：跨文档成功/失败、重复引用、循环引用、源文档媒体、SDK with_descendants 分页及 CommonMark round-trip
• gofmt -l cmd internal、go test -count=1 ./...、go vet ./...、make check-skills 全部通过
• Dataviz 色板与文档一致性检查通过
• 五个平台构建、tar.gz 结构和 checksums.txt 校验全部通过

安装

curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash

Full Changelog: v1.38.3...v1.38.4

图片显示尺寸绑定加固（Bug 修复版）

在 v1.38.2 之后对「docx 图片块显式宽高绑定」（e76f4c8）做了完整 review，本版一次性修复评审发现的全部问题：

修复

• EXIF 安全回退：JPEG 带 Orientation 5-8（显示时宽高转置的旋转，常见于手机竖拍照片）时不再下发本地解码宽高，退回服务端推断，避免显示框宽高比写反。内置轻量 EXIF 段扫描（只读 SOS 之前的段头，不解码图像数据）
• 格式补全：引入 golang.org/x/image 注册 webp / bmp / tiff 解码器。网络下载图片最常见的 webp 此前无法本地解码、仍会落回服务端推断（1600px 缩略图 bug 的根因路径），现已显式绑定真实像素
• 降级兜底：带宽高的 replace_image 请求被服务端以非临时错误拒绝时，自动降级为 token-only 重绑一次（等价旧行为），避免整个绑定/导入失败
• 告警治理：图片解码失败的 ⚠ 提示改为仅 --verbose 输出（doc add / doc content-update 等静默路径不再刷屏）；表格单元格图片的消息前缀修正为「单元格图片 N」，不再与顶层图片编号混淆

内部改进

• 删除零调用的 ReplaceImage 兼容包装，收敛为唯一入口 ReplaceImage(doc, block, token, ReplaceImageOptions{Width, Height, Align, Caption})；doc media-insert 不再手工构造 replace_image 请求体
• board upload-image 复用共享的头部解码 helper（原先整图解码只为读尺寸），顺带获得 webp/bmp/tiff 支持
• 新增单元测试：解码 helper 全格式/失败路径/EXIF 方向、EXIF 解析器大小端、payload 字段规则

实测验证

• doc import：png 640x360 / webp 550x368 / 表格单元格 png 300x200 均显式落块（API 回读确认）；EXIF Orientation=6 JPEG 正确回退服务端推断
• doc media-insert：webp + --align + --caption 全部经新选项正确落块
• board upload-image --dry-run：webp 正常识别，EXIF 旋转图明确提示改用 --width/--height

安装

curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash

Full Changelog: v1.38.2...v1.38.3

消息媒体 key 兼容性补丁

• 仅存在的普通本地文件优先于 img_ / file_ 资源 key 前缀。
• 目录、FIFO 等非普通文件不再抢占同名飞书资源 key。
• 保留 v1.38.1 对 img_logo.png、file_report.pdf 等真实本地媒体文件的自动上传修复。
• 增加同名前缀目录回归测试。

对应修复：PR #175。

消息媒体路径修复

• 修复 img_logo.png、file_report.pdf 等本地相对文件因 img_ / file_ 前缀被误判为飞书资源 key 的问题。
• 本地存在的媒体路径现在优先于资源 key 前缀；不存在同名路径时仍保持 key 直传兼容性。
• 同步覆盖 msg send、msg reply 与 --upload-images，包括图片、文件、Opus、MP4 和视频封面。
• 更新 feishu-cli-messaging Skill，并补充完整回归测试。

对应修复：PR #174。

消息发送与话题回复

• msg send / msg reply 统一支持文本、Markdown、post/card、图片、文件、Opus 音频与 MP4 视频内容模型。
• msg reply 新增本地媒体上传、--upload-images、--idempotency-key 和 JSON 输出。
• 修正话题语义：msg send 不再错误接受 thread_id；回复既有话题使用 msg reply <om_xxx>。
• 加强上传与发送的成功判定，MP4/Opus 作为附件时自动使用正确消息类型。
• 同步 README 与 feishu-cli-messaging Skill。

兼容性提示

原 msg send --thread-id 会在本地返回明确错误；请改用 msg reply <话题根消息 om_xxx> ...。

修复

• doc content-update / doc add 表格填充接入 batch_update 批量加速（#172）：此前这两条路径的单元格填充全部走逐 cell 慢路径（每 cell 1 读 + 1 写、写受单文档 3 QPS 节流），批量填充优化仅在 doc import 生效。现在填充函数内部按表格局部补建 cellID→textBlockID 映射，content-update 全部 6 种加内容 mode 与 doc add 均走 batch_update（每批 ≤30 cell）。
  • 真实文档实测：88 cell（12×6 大表 + 4×4 小表）--mode overwrite 从 62.3s → 6.1s
  • 顺带修复 doc import 追加行（>9 行表格 insert_table_row 产生的新 cell）此前不走批量的遗留问题
  • 失败自动降级为逐 cell 路径，行为不劣于此前版本

文档

• CLAUDE.md 与 docs 技能的 write/import 工作流同步表格填充性能现状

安装 / 升级

curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash

修复

• board image 画板缩略图扩展名：download_as_image 端点实际返回 JPEG，此前硬编码 .png 落盘导致下游按 PNG 解析报错。现按响应 Content-Type（缺失时按文件头嗅探）决定扩展名：目录与无扩展名路径自动补 .jpg/.png（推荐传无扩展名路径）；doc export 画板资产与 Markdown 引用、doc media-download 输出路径同步修正。
  • ⚠️ 行为变化：显式传 .png 而服务端实际返回 JPEG 时现在会报错（此前会静默写出内容与扩展名不符的文件），请改用 .jpg 或省略扩展名。

新功能

• bitable 记录字段投影：record list / search / batch-get 新增可重复 --field-id（字段名或字段 ID），只返回指定字段，读大表时控制输出体积。上限 list/batch-get 100 个、search 50 个。
• base/v3 错误提示增强：不再丢弃服务端 data.error.hint/path——如 select 写入未知选项时会直接列出可用选项与出错字段路径。

文档（均经真实 API 实测）

• bitable：batch-create 推荐 create_records 行式；select 未知选项行为按端点分化（单条端点自动创建、批量端点拒绝）；auto_number 改规则语义（存量记录不重排、新记录用新格式）；修正 field create 示例的 v3 形状
• htmlbox：HTML 总长上限约 500KB、正文可用宽度约 820px、height-mode 合法值仅 auto/viewport
• 卡片：新增 14 个合法彩色图标 token 枚举表（禁止按名称规律拼接）
• OKR：新增创建 O/KR 与量化指标 indicators 的 api 透传配方
• 日历：新增 Bot 建日程后自加参会人的配方

安装 / 升级

curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash

本版为一次全域能力补齐：29 项新能力 + 深度修复，全部经真实 API 验证。

亮点

• 消息发送者名字服务端回填：msg history/get/mget 读消息时 Bot 与外部租户用户的名字直接解析（此前 Bot 恒为空），内部群解析率实测 ~100%
• CLI 交互守卫：错拼子命令/flag 不再静默成功——报错 + 拼写建议 + 非 0 退出码，AI Agent 与脚本不再误判
• 多维表格结构化过滤：bitable record list --filter-json/--sort-json（tuple DSL，操作符与各字段类型值写法完整文档化，无需关键词）
• 电子表格类型保真闭环：新增 sheet table-get，数字/日期/布尔 dtype 自动推断，与 table-put 对称支持 get→改→put round-trip
• 大文档选择性读取：doc read --outline/--heading/--keyword，先看结构再取所需章节，不必整篇导出
• 交互式 Bot 闭环：事件系统新增 card.action.trigger 卡片回调与审批 v4 事件（自动注册服务端订阅，fail-closed）
• OKR 全量接线：cycle detail、progress get/update/delete、upload-image + --as 身份切换

新增命令

doc read、sheet table-get、chat list、task search、vc detail、vc note detail/transcript、minutes search/apply-permission、mail message-modify/message-trash/draft-send、wiki move-to-drive、drive secure-label list/set、file version revert、okr cycle detail、okr progress get/update/delete、okr upload-image

新增 flag / 增强

msg send --idempotency-key（幂等防重发）、calendar create-event/update-event --rrule（重复日程）、drive upload --file-token（原地覆盖）、chat member list --page-all（截断告警）、minutes get --wait-ready、task search --enrich=false、bitable record batch-update 逐记录差异化形态、doctor 身份就绪诊断、auth logout 服务端吊销、install.sh sha256 校验

修复

• 未完成任务 completed_at="0" 误显示为 1970 年
• drive push 命中 1062507（目录子节点超 1500）按父目录隔离，不再放弃未满目录
• --due-before 纯日期对齐当天 23:59:59；幂等键按字符（50）而非字节校验
• 错误码判定统一为词边界安全匹配，避免 log_id 同数字串误判

完整变更见 CHANGELOG。

安装

curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash

v1.35.0 新增统一可视化设计系统、HTMLBox 编排动画生成器和多维表格记录搜索便捷模式，并修复 Wiki 导出、评论回复身份和安装脚本的已知问题。

新增

• feishu-cli-dataviz：提供图表形式选择、明暗主题色板、反模式清单和多载体配色规范。新的校验器覆盖 9 组定稿色板、重复色、环形首尾区分度和 3/4/6/8 位 CSS hex 文档门禁。
• HTMLBox Agent 编排动画：animate_diagram.py 将结构化 JSON 转为自包含 SVG 动画 HTML，支持播放、暂停、步骤导航和 prefers-reduced-motion。
• bitable record search 便捷参数：新增 --keyword、可重复 --search-field、--filter-json、--sort-json、--view-id、--offset 和 --limit；保留 --config / --config-file 完整请求体逃生舱。

修复

• Wiki 树导出：每篇文档使用独立素材目录，并正确改写 Quote、Callout、表格图片和 video 的相对路径；同时保留代码、普通链接和未下载素材。
• 评论回复身份：comment reply add/delete 默认统一使用当前 App/Bot；显式提供 User Token 时才切换为用户身份。comment delete 改为返回飞书 API 真实支持的替代操作。
• 安装脚本：过程日志改写 stderr，避免 GitHub API fallback 污染版本号和下载 URL；新增版本号格式校验。

验证

• go test -count=1 ./...、go vet ./...、gofmt、Dataviz 九组色板门禁和 HTMLBox 5 个 Python 回归测试全部通过。
• Bitable/Comment 最终二进制本地 mock 和真实只读 Wiki 导出通过。
• Linux amd64/arm64、macOS amd64/arm64 和 Windows amd64 产物均显式注入 v1.35.0。

安装

curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash

Full Changelog: v1.34.0...v1.35.0

新增 5 项能力 + 1 项修复，全部经真实飞书 API round-trip 验证。

新增 — 电子表格按列类型保真写入（sheet table-put）

把 pandas DataFrame 形状的 JSON（to_json(orient="split")）按列 dtype 写入电子表格，让数字/日期/文本列不被误判类型。

• 日期列写 Excel 序列号 + 给该列设日期 formatter（yyyy/MM/dd），飞书识别为「真日期」（可排序/可透视/ISNUMBER=TRUE），而非文本
• 数字列保数值精度（大整数不退化为科学计数法）；文本列用 @ formatter 防止 ID/邮编等数字串被识别为数字（前导零保真，如 007）
• dtype 映射：int*/uint*/float*/complex*→number（interval* 除外，按文本）、bool/boolean→bool、datetime*→date、其他→string
• 空值（null/NaN）写空文本元素；单批 ≤ 5000 单元格自动按行分批
• ⚠️ 当前为写侧实现：就地覆盖 A1 起的矩形区域、不清除区域外旧行、不自动扩容（写入前用 sheet add-rows 预扩容）；仅支持单 sheet；读侧 round-trip（table-get）与 auto-grow 待后续

新增 — 画板服务端 SVG 导出（board svg-export）

POST /board/v1/whiteboards/{id}/export（export_type=svg），由服务端整板渲染为 SVG（base64 解码）。

• 与 board export-code 的区别：export-code 仅拼接 svg 节点的 svg_code，对 mermaid/plantuml/原生节点无效；svg-export 对任意画板有效，产出可二次编辑的完整 SVG
• 配合 board import / svg_to_board.py 实现「导出 → 编辑 → 回写」闭环
• 读类命令，登录后自动用 User Token，未登录回落 App Token

新增 — 审批实例指定节点审批人/抄送人（approval instance create）

• --node-approver / --node-approver-file、--node-cc / --node-cc-file：发起审批时按节点指定审批人/抄送人，格式 [{"node_id":"n1","value":["ou_xxx"]}]
• 新增 skills/feishu-cli-approval/references/form-control-values.md：14 类表单控件 value 结构速查 + 不支持清单 + 取值来源

新增 — schema pretty 输出渲染枚举值

schema <service>.<resource>.<method> 的 pretty 模式现在渲染字段的枚举取值（来自飞书归一化端点的 options/enum，含枚举描述），此前白白丢弃。数字型枚举值也正确渲染。

新增 — apps html-publish 单 .html 文件 10MB 上限

对齐妙搭服务端「单个 .html 文件 ≤ 10MB」硬约束，客户端提前拦截并点名超限文件。

• 实跑超限直接拒绝；--dry-run 回填 oversize_html 详情，并新增统一的 would_block / block_reasons 字段，便于脚本/Agent 单字段判断是否可发布

修复 — 电子表格图片上传适配 office 导入表格

UploadSheetImageMedia 的 parent_type 此前固定 sheet_image，对从 .xlsx 等导入的 office 表格（token 以 fake_office_ 开头）会上传失败。现按 token 前缀自动选择 office_sheet_file / sheet_image。

新增 — 妙搭（Miaoda）应用：HTML 秒搭一键部署（apps）

新增 apps 命令组，把妙搭（Miaoda）低代码应用平台的「一份 HTML 秒级发布成可分享的飞书应用」能力搬进 feishu-cli。全部走 User 身份（user_access_token），需要 spark scope。

• apps create —— 创建 HTML 妙搭应用（POST /open-apis/spark/v1/apps），返回 app.app_id（CLI 已剥掉飞书响应的 data 外层，jq 用 .app.app_id）
• apps html-publish —— 把 --path（单 HTML 文件或整目录）打包成 tar.gz，单次 multipart POST 上传并发布（/apps/{id}/upload_and_release_html_code），返回 url（jq 用 .url，一键部署）。客户端侧：要求根目录有 index.html、未压缩 ≤ 200MB / 打包后 tar.gz ≤ 20MB、默认拦截凭证文件（.env / .npmrc / .netrc / .git-credentials / .aws/credentials / .docker/config.json / .kube/config，--allow-sensitive 放行）
• apps update —— 部分更新名称/描述（PATCH /apps/{id}）
• apps access-scope-get / apps access-scope-set —— 查看/设置访问范围（specific / public / tenant，映射后端 Range / All / Tenant）
• apps list —— 列出当前用户的应用（隐藏命令，游标分页）
• 统一支持 --format json|pretty|table|ndjson|csv + --jq；写命令支持 --dry-run
• 权限：spark:app:write（create/update/html-publish/access-scope-set）、spark:app:read（list/access-scope-get）。⚠️ feishu-cli 的 auth login --scope 是「替换」不是「合并」，请把 spark scope 并入完整 scope 串一起登录，避免丢失已有权限

改进 — Markdown 表格单元格图片真嵌入（#164）

Markdown 表格单元格内的本地/网络图片此前在转换阶段被静默丢弃（带 alt 只剩 alt 文本、无 alt 整格变空）。现在 doc import 会在表格填充完成后（阶段 2.5）真正嵌入为单元格内的 Image 子块。

• 新增 ConvertOptions.EmbedTableImages 开关，仅 doc import 启用真嵌入；非导入场景（doc add/content-update）单元格图片降级为 [图片: 说明] 占位文本，杜绝任何路径的静默丢失。
• 导入 JSON 输出新增 cell_image_total/success/failed 统计字段。

修复 — 发版前 code review 收尾

• 表格单元格图片（#164）：纯图片单元格若带 alt（如 ![架构图](./a.png)），alt 文本不再经填充兜底路径泄漏成单元格里多余的标题；嵌入阶段改用 GetTableCellIDs（block.Table.Cells，与填充/导出同源）定位单元格，不再依赖 list-blocks 是否为表格块填充 children；单元格数与图片索引不一致或获取失败时，被跳过的图片计入失败统计而非静默丢弃；单元格图片上传失败时删除孤儿空 Image 块并补占位文本
• apps dry-run：--dry-run 预览现在同样尊重 --format/--jq（此前固定 JSON，与 help 列出的 flag 不符）
• apps html-publish 凭证扫描：目录形态下不再因根的「父目录」恰好叫 .aws/.docker/.kube 而把根下普通 credentials/config 文件误判为凭证
• 文档：apps 输出 jq 路径勘误（data.app.app_id → .app.app_id、data.url → .url，CLI 已剥掉 data 外层）
• 一致性：内联图片占位统一为中文「[图片: …]」前缀（此前本地路径分支用英文 [Image: 且直出原始路径）；apps html-publish 打包错误信息改为中文

新功能 — 多维表格支持 --as bot|user|auto 身份切换

bitable 命令组此前在 CLI 侧硬性强制 User Token（未登录直接报错），但底层飞书 base/v3 与 bitable/v1 API 本身一直同时支持 User / Tenant(App) 两种身份（client 早已声明 SupportedAccessTokenTypes:[User, Tenant]，瓶颈纯在命令封装层）。本版按 --as bot|user|auto 身份模式放开：

• 新增命令组 persistent flag --as bot|user|auto（默认 auto），所有 bitable 子命令通用：
  • auto（默认）：User 优先、Tenant 兜底——已登录用 User Token，未登录/过期自动回落 App Token
  • bot（= tenant/app）：强制 App Token，无需 auth login、永不过期，适合 cron / 无人值守 / 脚本自动抓取多维表格
  • user：强制 User Token（缺失报错，提示可改用 --as bot）
• 新增 resolveIdentityToken（cmd/utils.go）统一身份解析，替换 9 处咽喉点的 resolveRequiredUserToken/requireUserToken（bitable_base/field/form_crud/output/record_attachment）。客户端层零改动
• 修复后实测：在未登录环境用 App Token 读到此前因 token 过期而判定"不可入 cron"的真实多维表格全部 102 条记录

测试与文档

• 新增 cmd/bitable_identity_test.go：覆盖 bot/tenant/app 三别名（含大小写/空白）、显式 user token、非法 --as 报错、persistent flag 注册与子命令继承
• feishu-cli-bitable 技能 SKILL.md 补「身份选择 --as」表格 + cron 示例 + 91403 协作者排错；description 补 cron / App Token 触发词
• CLAUDE.md Token 策略由「三类」扩为「四类」，新增 resolveIdentityToken 身份可选类目

新功能 — 妙笔BOX（htmlbox）HTML 小组件命令

飞书文档里唯一能跑动画、可交互内容的载体落地为正式命令。妙笔BOX 是 AddOns HTML 小组件块（block_type=40），把一整页 HTML 存进 add_ons.record，飞书在 iframe 沙箱里真实执行 CSS/JS——CSS 动画、ECharts、Three.js、Canvas、真实地图、3D 图表都能动（区别于画板的 SVG 节点会被服务端栅格化成静态图）。

新增命令 feishu-cli doc htmlbox {create|update|get|delete}：

• create：往文档插入妙笔BOX 块（--html / --html-file / stdin 三选一，--index / --parent-id 控制位置）
• update：更新块 HTML。飞书 API 不支持原地改 add_ons（PATCH 返回 1770001），改走「先建后删、同位置重建」——新块在原位置创建成功后才删旧块，中途失败不丢数据，返回 new_block_id
• get：读回块 HTML（--raw 逐字节输出便于存文件/再编辑，默认输出含 html 字段的结构）
• delete：删除妙笔BOX 块（仅限 block_type=40，防误删其他块）
• 统一接入 --format / --jq / --dry-run；默认 Bot 身份（操作自建文档无需登录）

配套 feishu-cli-htmlbox 技能：SKILL.md + 3 个 references——mechanism.md（块机制 / iframe 沙箱边界 / 与画板的 trade-off）、html-recipes.md（CSS 动画 / ECharts / Canvas / Dashboard 自包含范例）、pitfalls.md（真实创建大批量图沉淀的 9 类实战踩坑：JS 报错白屏不报错、CDN 加载时序、真实地图 registerMap、record 双重编码、批量追加限流等）。

测试与质量

• 新增 7 个单测：record JSON 编码转义、loadHTMLInput（含「不 TrimSpace 保原文」这一 get --raw 还原保证）、<script> / HTML 注释 / U+2028 payload roundtrip、unicode/emoji roundtrip
• 指针解引用统一用 client.StringVal，update 补 len==0 防御，get --raw 空内容时 stderr 告警

性能与功能 — 表格批量填充提速 25-30x，列宽可自定义

① 表格填充 batch_update 优化（issue #159）

doc import / doc add / doc content-update 三个入口的 Markdown 表格填充重写：

• 阶段二开始预热文档级 cellID → textBlockID 映射（一次 GetAllBlocks 替代 N 次 GetBlockChildren）
• single-group cell（占绝大多数）走 batch_update API，每批 ≤30 个一次写入；多块 cell（含 <br/>）保留原 update-first-empty 路径作为兜底
• 整批失败自动降级 per-cell，避免一颗坏 cell 污染整张表
• 新增文档级 3 QPS 写限流器（docWriteLimiter），下沉到 CreateBlock/UpdateBlock/DeleteBlocks/BatchUpdateBlocks 4 个底层写函数，所有间接调用者（InsertTableRow/AppendTableRows/ReplaceImage 等）自动受限，避免触发 99991400

典型场景：4 张 6×8 表（共 ~120 cells）从 ~70s 降到 ~3s（25-30x），与 issue #159 实测数据吻合。BatchUpdateBlocks 改为返回 (*BatchUpdateBlocksResult, http.Header, error)，让 retry 层拿到 x-ogw-ratelimit-reset 做精确退避。

② 表格列宽自定义（issue #156）

之前列宽完全由内容启发式计算（中文 14px / 英文 8px），用户无法干预。现在两种方式可覆盖：

• 紧邻表格上方注释（推荐，单表精控）：

  <!-- feishu-colwidth: 80,200,120,* -->
  | 列1 | 列2 | 列3 | 列4 |
  |-----|-----|-----|-----|
  

  单位支持 px 整数、30% 百分比（按 700px 文档宽度换算）、* 或空（该列走 auto）。注释独占一行才生效；中间夹任何块（heading/段落/列表/代码块/link-ref-def）会清空注释，避免悬浮注释污染下游表格。

• CLI flag 全局覆盖：--table-column-width=auto|fixed|N1,N2,...

  • auto（默认）：保留启发式
  • fixed：所有列等分文档宽度
  • 像素列表（如 80,200,*,120）：显式声明每列宽度，* 表示该列走 auto

优先级：注释 > CLI flag explicit > flag fixed > auto。所有路径最终都会过 [80, 400] 像素 clamp。注释/flag 列宽数量与表实际列数不一致时，stderr 打印警告（多写截断、少写补 auto）。

新增 — 消息搜索 enrich / 多维表格补全 / 输出工程化（jq + 表格/CSV）

补齐三类此前未覆盖的场景。

① 消息搜索 enrich（search messages）

新增 --enrich opt-in 富化：在消息 ID 基础上补全 内容 / 发送者 / 群名 / 时间（对齐 lark +messages-search）。默认行为保持原 ID 输出，完全向后兼容：

• 默认（无 --enrich）：仅返回消息 ID，-o json / --format json 返回旧 schema {MessageIDs,HasMore,PageToken}，与升级前一致
• --enrich：search → 消息 ID → BatchGetMessages 取详情 → 解析发送者名/群名 → 人类可读视图；-o json / --format json 返回 []{message_id,msg_type,chat_id,chat_name,sender_id,sender_name,create_time,time,text} 数组
• --format json|pretty|table|ndjson|csv + --jq 结构化输出对两种模式均生效；--page-all/--page-limit 自动翻页

② 多维表格补全（bitable）

补齐 base/v3 + bitable/v1 公开 API 支持、此前缺失的命令：

• bitable dashboard list|copy（仪表盘）
• bitable form get|patch + bitable form field list|patch（表单及表单问题）
• bitable role member list|create|delete|batch-create|batch-delete（角色协作者）
• bitable workflow enable|disable（工作流启停）
• bitable update（多维表格本体重命名 / 高级权限开关）
• bitable record batch-get（批量获取记录）
• 新增 internal/client/bitable_v1.go：dashboard copy / role member / app update / workflow 启停 base/v3 无对应端点，走 bitable/v1（无需 X-App-Id header）。新命令经统一执行器 bitableRun + 请求描述符 bitableReq 路由 base/v3 与 bitable/v1，写命令支持 --dry-run 预览

注：dashboard block / form submit 已在后续一轮补齐（见下方「④ 多维表格 / 表格 / vc / mail / markdown 再补全」）。lark-base 的 view 独立 filter-sort 端点走飞书私有扩展 API（base-api.feishu.cn），公开 OpenAPI 无对应，未做专用命令——可用 feishu-cli api 裸调兜底。

③ 输出工程化（internal/output）

新增统一输出包，并接入 api 与新命令：

• --format json|pretty|table|ndjson|csv（api / search messages / bitable 新增命令）
• --jq <expr>（内置 gojq v0.12.17，纯 Go，无需外部 jq；保持 go 1.21 兼容）
• api 命令新增 --format/--jq（显式指定时走内置渲染，否则保持原 pretty/raw 行为）
• 大整数精度：渲染链路用 json.Number（飞书 19 位 message_id/chat_id 不被 float64 截断）
• table/csv 渲染 CJK 宽度对齐、单元格换行净化

新增依赖：github.com/itchyny/gojq v0.12.17（pin 该版本保持 go 1.21 兼容，未抬升 go directive）。

新增 — ④ 多维表格 / 表格 / vc / mail / markdown 再补全

补齐上一轮仍缺的仪表盘 / 表单 / 工作流 / 附件 / 浮图 / 筛选视图 / 下拉 / 会议机器人 / 邮箱签名 / Markdown diff。

多维表格（bitable）

• bitable dashboard create|get|update|delete|arrange（仪表盘 CRUD + 服务端智能排版，原有 list|copy）；create|update 支持便捷字段 --name/--theme-style 或 --config/--config-file 完整请求体二选一
• bitable dashboard block create|get|list|update|delete（仪表盘块 CRUD）；create 支持 --type（column/bar/line/pie/ring/area/combo/scatter/funnel/wordCloud/radar/statistics/text）+ --data-config 便捷字段
• bitable form create|delete|detail|submit（表单 CRUD + 按分享 token 取详情/提交，原有 get|patch）；detail/submit 走 share-token（shr 前缀）无需 base_token；submit 不处理附件上传
• bitable form field create|delete（表单问题批量增删，单次 ≤ 10，别名 questions，原有 list|patch）；create 用 --questions 数组，delete 用 --question-ids
• bitable workflow create|get|update（工作流 CRUD，update 为整体替换 PUT，原有 enable|disable|list）
• bitable record upload-attachment|download-attachment|remove-attachment（记录附件上传 / 下载 / 移除；upload/download 为 2 步编排，单次 ≤ 50 附件）

表格（sheet）

• sheet image get|update|media-upload|write-image（浮图获取 / 更新锚点尺寸偏移 / 上传素材取 file_token / 本地图片写入单元格，原有 add|list|delete）
• sheet filter-view get|update（筛选视图获取 / 更新名称范围，原有 create|list|delete）
• sheet filter-view condition create|get|update|delete|list（筛选条件 CRUD，按列字母定位）
• sheet dropdown get|update|delete（下拉菜单数据验证获取 / 更新 / 删除，原有 set）；update 支持多范围 / 多选 --multiple / 高亮 --colors
• sheet batch-set-style（批量为多范围设置单元格样式，--data 传 {ranges,style} 数组）

会议（vc）

• vc bot meeting-join|meeting-leave|meeting-events（会议机器人按会议号入会 / 离会 / 查会议事件，对应 /open-apis/vc/v1/bots/{join,leave,events}）

邮件（mail）

• mail signature（列出 / 查看邮箱签名，--detail <签名ID> 取单个详情）

Markdown（markdown）

• markdown diff（下载远端 Markdown 在本地算 unified diff，不改远端；三模式：远端最新 vs 本地 / 远端某版本 vs 最新 / 版本 A vs 版本 B）；输出支持 --format/--jq（-o json 作兼容别名），默认仍打印 unified diff 文本

云盘下载（drive / file / msg）

• drive download / file download 支持 User Token 直连下载 + 大文件自动 HTTP Range 分片兜底（突破单次下载大小限制；Bot/Tenant 路径仍保留 100MB 客户端上限）
• msg resource-download 支持 --user-access-token 用户身份下载消息图片/文件（可取 Bot 不可见的历史资源），大文件同样自动分片

新增 — event 模块（WebSocket 实时事件订阅 + daemon 进程管理）

新增 feishu-cli event 命令族（list / schema / consume / status / stop）， 通过飞书 WebSocket 长连接接收应用事件并以 NDJSON 输出到 stdout。

背景：feishu-cli 之前完全没有事件订阅能力，AI Agent 想做 bot 实时响应只能自写 WebSocket 客户端。本 PR 在 feishu-cli 代码风格下重新实现，让单工具栈即可完成消息接收、群成员变更监听、审批 事件订阅等长连接场景。

新增子命令：

• event list [--json] — 列出所有支持的 EventKey（按 domain 分组：im / contact / calendar / drive / approval / vc 共 22+ 个）
• event schema <key> [--json] — 查看某个 EventKey 的 EventType / scope / payload schema 示例
• event consume <key> — 启动 WebSocket 长连接订阅（阻塞，事件流→stdout NDJSON）
• event status [--json] — 查看本机所有 consume 进程（PID/EventKey/启动时间/uptime）
• event stop {--pid N | --event-key K | --all} [--force] [--json] — 停止 consume 进程

Consume 关键 flag：

• --max-events N — 接收 N 条事件后退出（0=不限制）
• --timeout 30s — 运行时长上限（0=不限制）
• --jq .event.message — 极简点路径过滤（只接受 .a.b.c，不支持完整 jq 语法，用 pipe 接外部 jq）
• --output-dir ./events — 每条事件 dump 为 <event_id>.json 落盘（只接受安全相对路径）
• --quiet — 抑制 stderr 诊断（不影响 stdout 事件流；ready marker 仍会输出，便于父进程判断就绪）

Daemon / 进程模型：

• 每个 event consume 进程 = 一个独立 OS 进程 + 一个 WebSocket 长连接（一个 EventKey）
• 状态文件 ~/.feishu-cli/events/<app_id>/bus.json（每个 AppID 一个目录）：consume 启动写入 PID/EventKey/启动时间，退出时移除
• 跨进程互斥 ~/.feishu-cli/events/<app_id>/bus.lock（flock 文件锁，fd 关闭自动释放）
• 原子写：tmp + os.Rename 防止半写
• 进程探活：signal(0) 检测 PID 存活，status 命令自动清理僵尸条目
• 重连策略：复用 oapi-sdk-go v3 ws.Client.WithAutoReconnect(true)，断线无限重试（间隔 2 分钟 + 首次随机抖动）
• 架构取舍：不跑独立 daemon + Unix socket 做事件 fan-out；feishu-cli 简化为每个 consume 直连 WebSocket， 不做事件分发——足够覆盖 AI Agent 单 EventKey 订阅的主线场景，省去 IPC 复杂度

Subprocess 协议（兼容 AI Agent 子进程调度）：

• 启动后 stderr 立即输出 [event] ready event_key=<key>，父进程应阻塞 stderr 等该行出现后再读 stdout
• 非 TTY 模式下 stdin EOF = shutdown 信号（适配 < /dev/null / nohup 等场景）
• 退出码 0：正常退出（达到 --max-events / --timeout / SIGTERM / Ctrl-C），非 0：startup 失败或 ws 不可恢复错误

Scope 要求：默认 App Token；具体 scope 因 EventKey 而异（event schema <key> 查看）。已加入 --domain event --recommend 推荐列表，覆盖 IM/联系人/日历/云盘/审批/VC 常用 scope 并集。

代码影响范围：

• 新增 cmd/event.go（顶层命令）+ cmd/event_{list,schema,consume,status,stop}.go（5 个子命令）
• 新增 internal/event/{keys,bus,runtime}.go（EventKey 注册表 + bus.json 状态管理 + WebSocket runtime）
• 新增 cmd/event_test.go + internal/event/{keys,bus,runtime}_test.go（mock 单测）
• 新增 cmd/event_smoke_test.go（//go:build smoke 本地真实 WebSocket 端到端测试）
• 修改 internal/registry/domain_alias.go：新增 event domain scope 推荐列表
• 修改 go.sum：补全 larksuite/oapi-sdk-go/v3/ws 子包的传递依赖（gorilla/websocket、gogo/protobuf；均为 indirect，无新顶层依赖）

新增 — attendance 考勤查询模块

新增 attendance 顶层命令组（别名 att），覆盖飞书考勤 OpenAPI 两类查询：

• feishu-cli attendance user-task query —— 按日期范围查询用户上下班打卡记录 （POST /open-apis/attendance/v1/user_tasks/query，单次最多 50 用户）
• feishu-cli attendance user-stats query —— 查询日度 / 月度考勤统计 （POST /open-apis/attendance/v1/user_stats_datas/query，单次最多 200 用户， 起止跨度 ≤ 31 天）

特性：

• 日期参数同时接受 YYYY-MM-DD 与 YYYYMMDD，自动转换为 API 所需的 yyyyMMdd 整数
• 输出双模：默认 text 人类可读（打卡时间 / 结果 / 加班标记 / 统计字段标题）， -o json 直出归一化结构体，便于 AI Agent 与脚本消费
• 同时打印 invalid_user_ids / unauthorized_user_ids，提示无效或无权限用户
• user-task ≤ 50、user-stats ≤ 200 用户数本地预校验，避免无谓远程请求
• user-stats 起止跨度 > 31 天本地预校验，避免触发 OpenAPI 报错
• 全部命令走 tenant_access_token（即应用身份）：larksuite/oapi-sdk-go v3.5.3 中 Attendance.UserTask.Query / Attendance.UserStatsData.Query 的 SupportedAccessTokenTypes 仅含 Tenant，传入 user token 会被 SDK 拒绝

权限要求：应用需在飞书开放平台「应用权限管理」页面获得 attendance:task:readonly 权限（tenant 级），无需 auth login。

新增 — msg flag：消息书签（收藏 / 列表 / 取消）

新增 feishu-cli msg flag {create,list,cancel} 三个子命令，对应飞书 OpenAPI /im/v1/flags， 覆盖消息书签的完整生命周期。

支持的两层书签模型：

其余组合服务端会拒绝，CLI 默认值为 default + message 即可覆盖 90% 用例。

实现说明：飞书 Open SDK v3 当前未封装 flag 接口，使用通用 HTTP client（client.Post / client.Get）直接调用，与 comment reply add 同套路。

权限要求：User Token；list 需要 im:feed.flag:read，create/cancel 需要 im:feed.flag:write

新增 — okr 模块：OKR 周期和进展记录

新增 feishu-cli okr 命令组，覆盖 OKR 最高频的 3 个操作：

• okr cycle list — 获取当前租户的所有 OKR 周期（/open-apis/okr/v1/periods，租户级全局列表，自动分页）
• okr progress list --objective-id 7xxx | --key-result-id 7xxx — 列出某个目标 / 关键结果下的所有进展记录
• okr progress create --objective-id 7xxx | --key-result-id 7xxx --content "..." — 创建一条进展记录， 支持纯文本（--content，自动包装为 ContentBlock）或原始富文本（--content-json）； 可附带 --progress-percent + --progress-status 标记进度； --source-url 飞书侧必填，CLI 默认填 https://www.feishu.cn/okr/progress placeholder，可显式覆盖

实现要点：

• progress create 走飞书 Open SDK v3.5.3 的 Okr.ProgressRecord.Create； cycle list 走通用 HTTP client 直调 /open-apis/okr/v1/periods（v1/periods 是租户级，不按用户过滤）； progress list 走通用 HTTP client 直调 /open-apis/okr/v2/...
• 所有命令默认使用 User Token，会自动读取 ~/.feishu-cli/token.json； 也可以通过 --user-access-token 或 FEISHU_USER_ACCESS_TOKEN 显式覆盖
• 时间戳统一格式化为本地时区 YYYY-MM-DD HH:MM:SS，方便人眼阅读

权限要求（User Token scope）：

使用示例：

feishu-cli auth login --domain event --recommend

# 列出所有 EventKey
feishu-cli event list

# 查看 IM 接收消息事件的字段
feishu-cli event schema im.message.receive_v1

# 订阅（Ctrl-C 退出）
feishu-cli event consume im.message.receive_v1

# 调试：抓 5 条事件后自动退出
feishu-cli event consume im.message.receive_v1 --max-events 5 --timeout 60s

# 并发订阅多个 EventKey（每个进程一个 EventKey）
feishu-cli event consume im.message.receive_v1 > receive.ndjson 2> receive.log &
feishu-cli event consume im.chat.member.user.added_v1 > member.ndjson 2> member.log &
feishu-cli event status                       # 查看活跃进程
feishu-cli event stop --all                   # 一键停止

新增 — doctor 命令（健康检查 / 配置 / 认证 / 网络 / 依赖一把验）

新增 feishu-cli doctor 命令，跑一组本地诊断快速验证 CLI 状态。

6 项检查：

• config_file — app_id / app_secret 是否就位
• user_token — token.json 状态（valid / needs_refresh / expired）
• endpoint_open — open.feishu.cn HTTPS 可达性 + RTT
• endpoint_larksuite — open.larksuite.com HTTPS 可达性 + RTT
• proxy — HTTPS_PROXY 与 NO_PROXY 配置（缺飞书域 warn）
• dependencies — Go 版本 + larksuite/oapi-sdk-go 版本

flag：--json 机器可读输出 / --offline 跳过网络检查 / --only user_token,proxy 仅运行指定项。

退出码：0 = 全 pass / 1 = 任一 fail。

使用示例：

feishu-cli doctor                              # pretty 输出全检查
feishu-cli doctor --json                       # JSON 输出（AI agent 自检友好）
feishu-cli doctor --offline                    # 跳过网络
feishu-cli doctor --only user_token,proxy      # 仅跑指定项

代码影响范围：新增 cmd/doctor.go（6 项检查 + pretty/JSON 输出）和 cmd/doctor_test.go（parseOnly / shouldRun / proxy / dependencies 单测）；不引入新依赖。

新增 — slides 模块：Slides 演示文稿创建与媒体上传

新增 feishu-cli slides 顶层命令，提供两个子命令支撑 Slides 演示文稿的最小可用工作流：

• slides create [--title <name>] [--width <px>] [--height <px>] [--output json] 调用 POST /open-apis/slides_ai/v1/xml_presentations 创建空白演示文稿，返回 xml_presentation_id / revision_id / title。默认尺寸 960x540。
• slides media-upload --file <path> --presentation-token <xml_presentation_id> [--output json] 本地图片走 /open-apis/drive/v1/medias/upload_all 上传到指定演示文稿，返回 file_token 可直接作为 slide XML 中 <img src="..."> 引用。

关键实现细节：

• 上传 parent_type 固定为 slide_file（实测：slide_image / slides_image / slides_file 都会被拒）；parent_node 必须为目标 xml_presentation_id
• 单文件上限 20 MB（多分片 upload_prepare 不接受 parent_type=slide_file）
• 共用 internal/client/drive.go::UploadMediaWithExtra 上传链路

权限要求：

• 创建：slides:presentation:create 或 slides:presentation:write_only
• 上传：docs:document.media:upload

新增 — mail 高级能力：CID 内联图片 + 邮件模板（MVP）

为 mail 模块补齐两块进阶能力：直接发送与邮件模板。

1. mail send --inline-images-auto-scan（CID 内联图片）

HTML body 中所有 <img src="本地相对/绝对路径"> 会被自动扫描：

1. 跳过已经是 cid: / http(s): / data: / // scheme 的引用
2. 同一本地路径只上传一次（去重）
3. 每张图独立生成 20-hex CID
4. 走 drive/v1/medias/upload_all（parent_type=email，parent_node = 当前登录用户 open_id）
5. EML 走 multipart/related：HTML 段 + 每张图一个 Content-ID: <cid>、Content-Disposition: inline 的 part
6. 改写 src 为 cid:<cid> 后回写到 body

依赖 ~/.feishu-cli/user_profile.json 中缓存的 open_id（auth login 后自动写入）。

2. mail template create / mail template list（邮件模板 MVP）

• mail template create --name xxx --subject xxx --body xxx [--to ... --cc ... --bcc ... --plain-text] 调用 POST /open-apis/mail/v1/user_mailboxes/{id}/templates
• mail template list [--mailbox me] 调用 GET /open-apis/mail/v1/user_mailboxes/{id}/templates（接口不分页，一次返回所有 id+name）

底层 client 也实现了 GetMailTemplate / UpdateMailTemplate / DeleteMailTemplate，但 CLI 层目前只暴露 create/list（MVP）。

权限要求：

• User Access Token
• mail:user_mailbox:readonly / mail:user_mailbox.message:modify / mail:user_mailbox.message:send
• 模板相关 scope：mail:user_mailbox:readonly、mail:user_mailbox.message:modify

⚠️ 模板接口依赖邮箱读写相关权限 —— 命令本身实现完整、参数校验完整、EML/JSON payload 正确；如果调用模板 API 时返回 scope 校验失败（401/permission denied），请补开邮箱读写权限后重试。 CID 内联图片功能不依赖此 scope，已可正常使用。

新增 — profile：多配置（profile）管理

新增 feishu-cli profile 顶层命令，让一台机器在多个飞书账号 / 应用之间快速切换。 解决长期痛点：原 ~/.feishu-cli/{config.yaml,token.json} 单实例布局，切账号必须手动备份/恢复 或者来回 mv，对同时需要 work / personal、或者 feishu.cn / larksuite.com 双端的用户极不友好。

子命令：

• profile add <name> [--app-id ... --app-secret ... --base-url ... --use] 新建 profile
• profile list (alias ls) 列出所有 profile，标注 active 列；--json 适合脚本/AI Agent
• profile use <name> (alias switch/checkout) 切换 active；use - 切回上一个
• profile current 显示当前 active profile 名 + 目录
• profile rename <old> <new> (alias mv) 重命名，自动同步指针
• profile remove <name> (alias rm/delete) 删除 profile；--force 跳过二次确认
• profile migrate [--name default] [--force] 把旧布局 ~/.feishu-cli/{config,token}.json 拷到 profiles/<name>/（原文件保留，让用户确认无误后手动清理）

目录布局：

~/.feishu-cli/
  config.yaml                # 旧布局，profile 系统未启用时仍读这里（无感升级）
  token.json
  active-profile             # 一行文本：当前 profile 名
  previous-profile           # 一行文本：上一个 profile 名（支持 use -）
  profiles/
    work/
      config.yaml
      token.json
      user_profile.json
    personal/
      ...

向后兼容设计：

• 没有任何 profile 时，internal/config 和 internal/auth 仍走旧路径，老用户零感知升级
• profile add 不会 自动迁移旧文件——避免静默丢数据；要迁就显式 profile migrate
• FEISHU_PROFILE=<name> 环境变量临时覆盖（不写指针文件），适合 CI / 一次性切换

安全：

• profile 名仅允许 [A-Za-z0-9_-]{1,64}，禁止 ./../路径分隔符等注入字符
• 保留名 profiles / cache 不可作为 profile 名
• 写入操作通过进程内 mutex 串行化；指针文件原子写（.tmp + rename）
• 所有 profile 目录默认 0700 权限，含 token.json 等敏感文件

测试：internal/profile/store_test.go 21 个测试，全部用 t.TempDir() 隔离，覆盖 ValidateName / List 字典序 / Create / Remove / Rename / Use 含 - 切换 / MigrateLegacy 含 --force 覆盖 / FEISHU_PROFILE 环境变量优先级 / ActiveDir 新旧布局切换。

示例：

# 创建一个标题为 "Q2 OKR" 的演示文稿
feishu-cli slides create --title "Q2 OKR" --output json

# 把封面图上传到该演示文稿
feishu-cli slides media-upload --file ./cover.png \
    --presentation-token <xml_presentation_id>

新增 — schema 命令：本地浏览飞书 OpenAPI 方法（path / 参数 / scope）

新增 feishu-cli schema [service.resource.method] 子命令，无需 token、纯本地查询飞书 开放平台 OpenAPI 方法的 HTTP path / 动词 / 参数 / 请求体 / 响应体 / scope / 文档链接。 便于 AI Agent 和脚本作者快速查找参数。

用法：

feishu-cli schema                                # 列出所有可用 service（12 个）
feishu-cli schema im                             # 列出 im 域下所有 resource.method
feishu-cli schema im.messages                    # 列出 messages 资源下所有 method
feishu-cli schema im.messages.delete             # 查看具体 method 详情
feishu-cli schema im.messages.delete --format json   # JSON 输出（AI Agent 推荐）
feishu-cli schema list --service drive           # 等价于 schema drive，支持 --format json

数据源：internal/registry/meta_data.json（编译期 embed），与认证模块复用同一份元数据。 当前覆盖 12 个 service：approval / attendance / calendar / drive / im / mail / minutes / sheets / slides / task / vc / wiki。

输出含：HTTP verb + 完整 path、parameters（含 path / query / required 标记）、 requestBody（嵌套字段）、responseBody、accessTokens（user / tenant）、scopes、docUrl。

查询本人最近一周打卡

feishu-cli attendance user-task query
--employee-type open_id
--user-ids ou_xxxxxxxxx
--start 2026-05-01 --end 2026-05-18

查询本月日度统计（JSON 输出）

feishu-cli attendance user-stats query
--employee-type open_id
--user-ids ou_xxxxxxxxx --current-user-id ou_xxxxxxxxx
--stats-type daily --start 2026-05-01 --end 2026-05-31 -o json

收藏消息（消息层）

feishu-cli msg flag create om_xxx

feed 层书签（自动识别 thread/msg_thread）

feishu-cli msg flag create om_xxx --flag-type feed

列出当前用户所有书签

feishu-cli msg flag list --page-size 50

取消书签（默认尽量取消消息层 + feed 层）

feishu-cli msg flag cancel om_xxx

feed 层书签（普通群线程）

feishu-cli msg flag create om_xxx --item-type msg_thread --flag-type feed

feishu-cli auth login --scope "okr:okr"
feishu-cli okr cycle list
feishu-cli okr progress list --objective-id 7xxx
feishu-cli okr progress create --key-result-id 7xxx --content "本周完成核心模块联调"

MVP 范围说明：本次只覆盖最常用的 3 个动词，progress update / delete / get 和图片上传暂不暴露 为命令行（client 层已有实现，后续按需补 CLI）。

新增 — approval 流程：实例详情 / 发起 / 撤回 / 抄送 / 通过 / 拒绝 / 转交

补齐审批模块的核心能力，原本只有 approval get（定义查询）和 approval task query（任务列表查询）两条只读命令，现在可以覆盖官方当前可执行的实例/任务主路径：

• feishu-cli approval instance get — 获取单个审批实例详情，对齐官方 instances/uat_get
• feishu-cli approval instance create — 发起一条审批实例，--form 或 --form-file 传表单 JSON
• feishu-cli approval instance cancel — 撤回（取消）已发起的审批实例
• feishu-cli approval instance cc — 把审批实例抄送给一个或多个用户（--cc-user-ids ou_a,ou_b）
• feishu-cli approval task approve — 通过指定审批任务，可附 --comment
• feishu-cli approval task reject — 拒绝指定审批任务，建议在 --comment 中填写原因
• feishu-cli approval task transfer — 转交审批任务给其他用户，对齐官方 tasks/uat_transfer

权限要求：instance get、task query、instance cancel/cc、task approve/reject/transfer 使用 User Token，分别需要 approval:instance:read、approval:task:read、approval:instance:write、approval:task:write；instance create 是本项目额外应用态能力，使用 tenant_access_token，需要 approval:approval。

底层 API：

• GET /open-apis/approval/v4/instances/uat_get
• POST /open-apis/approval/v4/instances
• POST /open-apis/approval/v4/instances/uat_cancel
• POST /open-apis/approval/v4/instances/uat_cc
• POST /open-apis/approval/v4/tasks/uat_approval
• POST /open-apis/approval/v4/tasks/uat_reject
• POST /open-apis/approval/v4/tasks/uat_transfer

官方 skill 文案中提到但当前官方可执行 schema 未开放的能力仍不在本次范围：tasks/rollback（退回）、tasks/add_sign（加签）、tasks/remind（催办）。

代码影响范围：

• internal/client/approval.go：新增审批实例详情、实例写、任务写/转交 client 函数 + 对应 Options 结构 + 共享请求 helper
• cmd/approval_instance.go：新增 approval instance 父命令
• cmd/approval_instance_{get,create,cancel,cc}.go：4 条实例侧子命令
• cmd/approval_task_{approve,reject,transfer}.go：3 条任务侧子命令

新增 — sheet filter-view + sheet dropdown：筛选视图与下拉菜单

补齐两块电子表格高级能力：

• 筛选视图 CRUD（V3 API）：用 SDK SpreadsheetSheetFilterView 实现
  • feishu-cli sheet filter-view create --token <t> --sheet-id <s> --range "<sheetId>!A1:H14" [--name 视图名 --filter-view-id 自定义ID]
  • feishu-cli sheet filter-view list --token <t> --sheet-id <s>
  • feishu-cli sheet filter-view delete --token <t> --sheet-id <s> --filter-view-id <fv>
  • --range 不带 sheetId 前缀时自动补全为 <sheet-id>!<range>
• 下拉菜单（V2 dataValidation API）：list 类型数据验证
  • feishu-cli sheet dropdown set --token <t> --range "<sheetId>!A1:A100" --options "待办,处理中,已完成" [--multiple --colors "#FF4D4F,#FAAD14,#52C41A"]
  • --options-json '["a, b","c"]'：选项内含逗号时绕过 CSV 解析
  • 传 --colors 自动开启 highlightValidData，颜色数量需与选项一致

权限：sheets:spreadsheet（User Token 或 App Token 均可），命令默认 resolveOptionalUserTokenWithFallback 自动读取登录态。

代码影响范围：

• internal/client/sheets.go：新增 CreateFilterView / ListFilterViews / DeleteFilterView / SetDropdown
• cmd/sheet_filter_view.go、cmd/sheet_dropdown.go：CLI 入口

新增 — markdown {create,fetch,overwrite}：Drive 原生 .md 文件 CRUD

新增 feishu-cli markdown 顶层命令，把 Drive 上的 .md 当作普通文件整体读写， 保留原始 Markdown 格式（不做 Markdown ↔ 飞书 docx 块的转换）。

与 doc import / doc export 的区别：

适合 AI agent 把生成的 Markdown 直接落盘到飞书 Drive、下次读回时仍是原汁原味 Markdown 源码的场景。

子命令：

• markdown create --name xxx.md --content "..." | --content-file path.md | --file path.md [--folder-token fldxxx] 从字符串或本地文件创建 .md；强制 .md 后缀；空内容报错；底层走 client.UploadFileWithToken（≤ 20MB 单次上传，> 20MB 复用现成分片管线）。

• markdown fetch --file-token boxcnxxx [--output-path path] [-o json] 缺省 --output-path 时直接打印到 stdout； 指定路径则落盘，目录会拼 fileToken.md，--overwrite 防误覆。

• markdown overwrite --file-token boxcnxxx --name existing.md --content "..." | --content-file path.md | --file path.md [--name renamed.md] 覆盖现有 .md 的内容，file_token 保持不变；--content 时 --name 必填，--content-file 缺省使用本地 basename。 实现细节：飞书 Go SDK v3.5.3 的 UploadAllFileReqBody 没有暴露 file_token 字段，因此本命令用 client.Post + *larkcore.Formdata 自己拼 multipart， endpoint 仍是官方的 POST /open-apis/drive/v1/files/upload_all， shortcuts/markdown/helpers.go 的写法。

权限：User Access Token + drive:file:upload / drive:file:download （或 drive:drive）。

内联图片

feishu-cli mail send --to user@example.com --subject "周报"
--body '<p>看附图</p><img src="./screenshot.png">'
--inline-images-auto-scan --confirm-send

模板创建+列表

feishu-cli mail template create --name "周报" --subject "本周进度" --body "<p>模板</p>" feishu-cli mail template list

新增 — calendar 智能化三件套（suggestion / room-find / rsvp）

针对 AI Agent 自动排会场景，补齐三条飞书日历开放能力，使整条「选时段 → 选会议室 → 答复邀请」 流水线全部可在 CLI 完成。

• calendar suggestion：智能时段建议。直调 POST /open-apis/calendar/v4/freebusy/suggestion， 按 --attendee-ids ou_xxx,oc_yyy + --duration 30m/1h30m/90 推荐可用时段；支持 --start/--end 搜索窗口（默认当天）、--exclude start~end,... 排除午休/已占用时段、 --event-rrule 周期性规则、--timezone。返回带「推荐理由」+「AI 行动指引」。
• calendar room-find：会议室查找。直调 POST /open-apis/calendar/v4/freebusy/room_find， 支持多个 --slot start~end 并发查询（worker=10），可按 --city/--building/--floor/ --room-name（逗号分隔多个）/--min-capacity/--max-capacity 多维度过滤；可选 --attendee-ids 让服务端结合参与者位置筛选。
• calendar rsvp：答复日程邀请。走 SDK Reply 接口，--calendar-id（可省略，默认主日历）+ --event-id + --action accept|decline|tentative。与既有的 calendar event-reply 位置参数风格互为补充——rsvp 全 flag 风格、calendar-id 可省，更适合 AI Agent 调度。

SDK 现状：v3.5.3 暴露 Reply 但未暴露 freebusy/suggestion 和 freebusy/room_find， 故 suggestion / room-find 走 client.Post 通用 HTTP 直调 OpenAPI；新增 client 函数集中在 internal/client/calendar_smart.go，包括 SuggestFreebusy、FindMeetingRoom、 FindMeetingRoomBatch（并发+排序）、SplitAttendeeIDs（按 ou_/oc_ 前缀分流）。

权限要求：

• suggestion / room-find：calendar:calendar.free_busy:read（User Token 或 App Token 均可）
• rsvp：calendar:calendar.event:reply（推荐 User Token，以本人身份答复）

典型用法：

# 1. 先让飞书推荐可用时段
feishu-cli calendar suggestion --attendee-ids ou_aaa,ou_bbb --duration 30m

# 2. 锁定时段后查会议室
feishu-cli calendar room-find \
  --slot 2024-01-22T09:00:00+08:00~2024-01-22T09:30:00+08:00 \
  --building "飞书大厦" --min-capacity 6

# 3. 收到邀请后答复
feishu-cli calendar rsvp --event-id EVENT_xxx --action accept
# 从旧布局开始（已有 config.yaml 和 token.json）
feishu-cli profile migrate                              # → profiles/default/，指针指 default
feishu-cli profile add personal --use --app-id cli_yyy  # 新建 personal 并切过去
feishu-cli profile list                                 # 看哪个 active
feishu-cli profile use -                                # 切回 default
FEISHU_PROFILE=personal feishu-cli msg send ...         # 一次性临时切换

新增 — comment reply add：为已有评论添加回复

新增命令 feishu-cli comment reply add <file_token> <comment_id> --text "..."，补齐评论回复 生命周期的最后一块拼图（此前只有 list / delete）。

背景：飞书 Open SDK v3.5.3 的 fileCommentReply 只暴露 List/Delete/Update，没有 Create 方法，而 Open API 本身是支持的（POST /drive/v1/files/:token/comments/:comment_id/replies）。 此 PR 不依赖 SDK 升级，用通用 HTTP client（client.Post）直接调用 API 实现。

同时改进：

• comment reply add / delete / list 全部加上 --user-access-token 参数支持，并走 resolveOptionalUserTokenWithFallback 自动读取登录态，和 msg/chat/doc export 等模块保持一致
• 重要修复：comment reply delete 在 App Token（Bot 身份）下调用飞书侧会返回 1069303 forbidden——飞书只允许回复作者本人删除。现在命令默认优先使用 User Token（如果已登录）， 行为才符合用户预期。命令帮助中也显式说明了这个权限模型
• comment reply add 默认也走 User Token fallback，回复会以用户身份发布（而非显示为 Bot）， 且该回复能被后续 reply delete 正常删除

权限要求：docs:document.comment:create（User Token）

使用示例：

feishu-cli auth login                       # 确保有 User Token
feishu-cli comment reply add <file_token> <comment_id> --text "已处理"
feishu-cli comment reply delete <file_token> <comment_id> <reply_id>  # 自动用 User Token

代码影响范围：

• internal/client/comment.go：新增 CreateCommentReply（HTTP client 直调）， ListCommentReplies / DeleteCommentReply 签名增加 userAccessToken 参数
• cmd/comment_reply.go：新增 addReplyCmd，三个子命令统一加 --user-access-token flag
• cmd/comment.go：Long help 中补充 reply add 示例

Features — 新增 wiki move-docs 命令（移动云空间文档至知识空间）

新增 feishu-cli wiki move-docs <obj_token> --space-id <id> 命令，对应飞书 OpenAPI POST /open-apis/wiki/v2/spaces/{space_id}/nodes/move_docs_to_wiki。

解决的问题：之前要把"我的空间 / 共享空间"里已存在的 docx / sheet / mindnote / bitable / file 挂到知识库下，只有两条路——(1) 飞书客户端手动点"添加到知识库"；(2) 走 wiki create 新建空文档再重写内容。前者不能自动化，后者丢原文档权限和历史。新命令一步到位。

用法：

# 把 drive docx 移入知识空间根目录
feishu-cli wiki move-docs doccnXXXXXX --space-id 7012345678901234567

# 移入指定父节点
feishu-cli wiki move-docs doccnXXXXXX --space-id 7012345678901234567 --parent-node wikcnYYYYYY

# 移动电子表格
feishu-cli wiki move-docs shtcnXXXXXX --space-id 7012345678901234567 --obj-type sheet

# 无 move 权限时提交迁入申请
feishu-cli wiki move-docs doccnXXXXXX --space-id 7012345678901234567 --apply

# 用用户身份调用（企业版 wiki 空间不接受 app 成员，必须 user token）
feishu-cli wiki move-docs doccnXXXXXX --space-id 7012345678901234567 --user-access-token u-xxx

返回三种情况：wiki_token（立即完成）/ task_id（异步任务）/ applied=true（权限不足已提交申请）。

Scope 要求：wiki:node:move 或 wiki:wiki，已加入 --domain wiki --recommend 推荐列表。

代码影响范围：

• 新增 cmd/move_docs_to_wiki.go（命令）和 internal/client/wiki.go 的 MoveDocsToWiki 函数
• internal/registry/domain_alias.go 的 wiki domain 补上 wiki:node:move
• README 知识库操作段落补一行命令

Breaking Changes — 移除 config add-scopes 命令

feishu-cli config add-scopes 子命令及其 --domain / --scopes / --print-only flag 全部删除。

删除理由：

1. 命令几乎不可用 — 硬编码的 scopeDomains 字典里多数 scope 名已过时（docx:document / sheets:spreadsheet / bitable:app / im:chat:readonly / drive:export:readonly / vc:room:readonly 等都是飞书不支持的粗粒度名称），生成的申请链接里多数 scope 会被后台拒绝
2. 权限开通不适合自动化 — 飞书开放平台的权限申请通常需要 tenant 管理员审批，scope 选择也是业务决策而非技术"默认值"。CLI 自动化只会造成"看起来装好了但后台还没批"的幻觉
3. 有更简单的替代 — 飞书开放平台的应用权限管理页面支持"导入权限 JSON"入口，复制 README 权限要求 章节里的完整权限清单一次性粘贴即可开通 400+ 个 scope

迁移指引：

旧：

feishu-cli config add-scopes --domain all

新：

1. 打开飞书开放平台 → 你的应用 → 权限管理页面
2. 复制 README 的完整权限 JSON（tenant + user 两套 400+ scope）
3. 粘贴到"导入权限"入口，一键开通全部
4. 等待 tenant 管理员审批（如果需要）

代码影响范围：

• 删除 cmd/config_add_scopes.go 整个文件
• cmd/auth_check.go 的 suggestion 文案改为引导用户去开放平台开通（不再推荐 config add-scopes）
• README / CLAUDE.md / AGENTS.md / 6 个 skill 的 config add-scopes 引用全部更新为"去开放平台开通"
• 保留 config create-app --save（Device Flow 创建应用）不变

Breaking Changes — 多维表格（bitable）切换到 base/v3 API

旧实现：bitable 模块全部调用 /open-apis/bitable/v1/apps/{app_token}/... 老 API，覆盖 ~30 个基础 CRUD 命令。 新实现：全面切换到 /open-apis/base/v3/bases/{base_token}/... 新 API，覆盖 48 个命令，支持深度能力（视图完整配置读写、记录 upsert、修改历史、角色 CRUD、高级权限、数据聚合、工作流查询）。

命令名迁移表

新增能力

• 视图配置完整写入：view-sort-set / view-group-set / view-visible-fields-set / view-timebar-set / view-card-set（老 v1 只能写 filter）
• 记录修改历史：bitable record history-list --record-id xxx
• 角色 CRUD：bitable role create/update/delete（老 v1 只有 list）
• 字段选项搜索：bitable field search-options
• Base create 支持时区：--time-zone Asia/Shanghai

Flag 变化

• 删除 --app-token 别名：只保留 --base-token（与 base/v3 API 命名一致，不再做兼容别名）
• bitable create 的 --description 被删除（base/v3 不支持），新增 --time-zone
• bitable data-query 的 --table-id 被删除（v3 端点挂在 base 下）

删除的文件

• internal/client/bitable.go / bitable_test.go（v1 实现）
• cmd/bitable_create.go / bitable_get.go / bitable_copy.go / bitable_advperm.go / bitable_dashboard.go / bitable_data_query.go / bitable_form.go / bitable_record_upload_attachment.go / bitable_role.go / bitable_view_config.go / bitable_workflow.go

新增的文件

• internal/client/base.go（BaseV3Call + BaseV3Path helper + X-App-Id header 自动注入）
• cmd/bitable_base.go / bitable_misc.go（所有 base/v3 命令的注册）
• cmd/bitable_table.go / bitable_field.go / bitable_record.go / bitable_view.go 全部重写

Breaking Changes — VC（视频会议）改造升级

• vc search：底层 API 从 GET /meeting_list 切换到 POST /meetings/search。
  • 新增 flag：--query / --organizer-ids / --participant-ids / --room-ids
  • 删除 flag：--meeting-no / --meeting-status
  • 必须指定至少一个过滤条件
• vc notes：
  • flag 从 --meeting-id / --minute-token（单数）改为 --meeting-ids / --minute-tokens（复数，支持 CSV 批量最多 50）
  • 新增第三路径 --calendar-event-ids：从日历事件自动反查会议 / 妙记
  • 新增开关 --with-artifacts（获取 AI 产物）/ --download-transcript --output-dir（下载逐字稿）
• 所有 vc / minutes 命令默认 User Access Token，未登录时统一报错提示 feishu-cli auth login

新增命令

• vc recording --meeting-ids/-calendar-event-ids：查询会议录制并自动提取 minute_token
• minutes download --minute-tokens x,y,z --output ./dir：批量下载妙记音视频媒体（SSRF 防护 / 重定向校验 / Content-Disposition 解析 / 文件名去重 / 5 req/s 速率限制 / --url-only 预览链接）
• minutes get <token> --with-artifacts：新增 AI 产物合并输出

Added — drive 云盘命令组（8 个命令）

新增独立的 drive 子命令组，与现有 file / media / doc media-* 命令并存，提供增强能力：

保留不动：file list / delete / mkdir / copy / shortcut / quota / meta / stats / version + media upload / download + doc media-download / media-insert + comment list / resolve / delete / reply

Added — mail 飞书邮箱模块（10 个命令，从零新建）

全新命令组。首期不支持附件和 CID 内联图片，仅支持纯文本和 HTML body。所有命令默认 User Access Token。

关键技术点：

• RFC 5322 EML 构建 + base64 URL-safe 编码，POST /drafts body {"raw":"..."}
• HTML 自动检测（<html>/<div>/<b>/<br> 等标签），可用 --plain-text / --html 强制
• 发件人地址默认从 /user_mailboxes/{mailbox}/profile 读取
• 地址格式支持 "Name <email>" 和 "email"
• Subject 去重：reply 自动避免 Re: Re:，forward 自动避免 Fwd: Fwd:

Fixed

• mail reply 引用块缺日期占位符：之前的 quote header 模板第一个 %s 传空字符串，会输出 "在 ，xxx 写道:"，已修正为 "{email} 写道:"
• 分片上传 fd 泄漏：uploadFileMultipart 之前每片每次重试都 os.Open + Seek，现改为外层打开一次 + io.NewSectionReader，大文件不稳定网络下重试时节省 N×syscall
• mail reply 重复 GetMailboxProfile 调用：之前在 runMailReply 里调用 2 次（一次取 selfEmail 一次取 from/fromName），现合并为 1 次，省 1 个 API RTT
• drive import 上传端点错误：之前走 /files/upload_all 会在用户云盘留下中间文件，现改为官方的 /medias/upload_all + parent_type=ccm_import_open + extra
• mail triage --query 静默失效：之前把 query 当 list 端点的查询参数，飞书会忽略；现改走专用的 POST /search 端点

Refactor（内部代码清理，用户感知较小）

• 新增 requireUserToken(cmd, cmdName) helper，统一所有新命令的 "需要 User Access Token" 错误信息格式
• 删除重复的 GetWikiNodeByToken（58 行），改用已有的 GetWikiNode
• 删除 internal/client/mail.go 的 joinPath，用 strings.Join
• dedupStrings 从 vc_recording.go 移到 vc_common.go
• runBaseV3WithJSON 重构，抽出 runBaseV3WithBody 让命令层直接传已构造的 body
• bitable view create/rename 去掉 cmd.Flags().Set("config", ...) + MarkHidden 的 hack 模式
• 删除 runBaseV3Simple / addBaseTokenFlag / exactlyOneNonEmpty 三处死参数/死变量
• 所有文件统一 gofmt

Breaking Changes — OAuth 认证全面切换到 Device Flow

彻底删除 Authorization Code Flow，只保留 Device Flow（RFC 8628）。本地桌面、SSH 远程、容器、CI 全环境统一使用同一条命令，无需任何重定向 URL 白名单配置。

删除的 flag

auth login 命令删除以下 flag：

• --manual — SSH 远程手动粘贴回调模式（Device Flow 下 SSH 和本地一视同仁）
• --no-manual — 强制本地回调模式（本地回调 HTTP server 已移除）
• --port — 本地回调端口（不再需要）
• --print-url — 非交互两步式第一步（改用 --no-wait + --device-code）
• --method — 授权方式选择（Device Flow 是唯一方式）
• --scopes — 请求 OAuth scope（飞书 token v2 端点实际忽略此参数，返回应用预配置的全部 scope）

删除的子命令

• auth callback <url> --state <state> — Authorization Code Flow 换 token 专用，整体删除

删除的代码

• internal/auth/oauth.go：Login / loginLocal / loginManual / buildAuthURL / GenerateAuthURL / ParseCallbackURL / ExchangeToken 等函数
• internal/auth/browser.go：isLocalEnvironment() 函数（曾在 macOS 上无条件返回 true 导致 SSH 远程 Darwin bug）
• cmd/auth_callback.go：整个文件

修复的 bug

• Issue #95：飞书错误码 20029（重定向 URL 有误）。根因是 Authorization Code Flow 需要用户在飞书开放平台配置 http://127.0.0.1:9768/callback 白名单，Device Flow 直接绕过此要求
• Darwin SSH bug：isLocalEnvironment() 在 macOS 上无条件返回 true，SSH 到 Mac 服务器时错误走本地回调模式会 2 分钟超时失败。已通过删除该函数消除

新增 — auth login 的 JSON 事件流模式

• auth login --json：阻塞轮询 + JSON 事件流输出到 stdout。AI Agent 推荐配合 Claude Code 的 run_in_background=true 使用

  • 首次输出：{"event":"device_authorization","verification_uri":"...","verification_uri_complete":"...","user_code":"...","device_code":"...","expires_in":240,"interval":5}
  • 成功输出：{"event":"authorization_success","expires_at":"...","refresh_expires_at":"...","scope":"..."}

• auth login --no-wait --json：两步模式第一步。只请求 device_code 并立即输出 JSON，不启动轮询。适合 AI Agent 希望把"请求"和"轮询"拆到两次独立 Bash 调用的场景

• auth login --device-code <code> --json：两步模式第二步。用已有的 device_code 继续轮询直到授权完成

新增 — auth check 子命令

预检当前 Token 是否包含指定 scope，专为 AI Agent 在执行业务命令前做前置判断而设计：

feishu-cli auth check --scope "search:docs:read"
feishu-cli auth check --scope "search:docs:read im:message:readonly"

输出 JSON：

{
  "ok": true,
  "granted": ["search:docs:read"],
  "missing": null
}

或失败情况：

{
  "ok": false,
  "error": "not_logged_in",
  "missing": ["search:docs:read"],
  "suggestion": "feishu-cli auth login"
}

退出码 0 = 满足，非 0 = 缺少或未登录，AI Agent 可直接分支。

不变

• Token 存储格式：~/.feishu-cli/token.json 仍是明文 JSON，数据结构完全兼容。升级后不需要重新登录
• Token 自动刷新：ResolveUserAccessToken() 路径和 RefreshAccessToken() 逻辑保持不动，access_token 过期时用 refresh_token 自动刷新
• config create-app 命令完全不变（它本来就用 Device Flow）
• auth status / auth logout 行为不变
• 所有业务命令（doc/msg/search/wiki/task/calendar/...）行为不变

迁移指引

人类用户

无需任何迁移。一条命令通吃所有场景：

feishu-cli auth login

本地桌面会自动开浏览器，SSH 远程需要手动复制 stderr 里的链接在本机浏览器打开，一模一样的命令。

AI Agent / 脚本用户

旧的两步式：

feishu-cli auth login --print-url --scopes "..."
feishu-cli auth callback "<回调URL>" --state "<state>"

迁移为以下任一方案：

方案 A（推荐）：阻塞 + 后台运行：

# run_in_background=true
feishu-cli auth login --json
# 读 stdout 第一行拿 verification_uri_complete，展示给用户
# 等后台进程退出，读第二行 stdout 拿 authorization_success

方案 B：两步模式：

# 第一步
feishu-cli auth login --no-wait --json  # → device_code JSON
# 把链接展示给用户等待授权
# 第二步
feishu-cli auth login --device-code <code> --json  # → authorization_success

CI / 无头脚本

Authorization Code Flow 本来就无法无头完成（需要浏览器授权），Device Flow 同样需要人类介入一次。如果 CI 需要 User Token，应该预先在本地通过 auth login 拿到 token.json 然后把它作为 secret 部署到 CI 环境，不需要任何迁移。

详细对比

更早的版本请参考 GitHub Releases。