v1.32.0

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

bitable 命令组此前在 CLI 侧硬性强制 User Token（未登录直接报错），但底层飞书 base/v3 与 bitable/v1 API 本身一直同时支持 User / Tenant(App) 两种身份。本版按官方 lark-cli 的 --as 模式放开：

• 新增命令组 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（缺失报错）
• 新增 resolveIdentityToken 统一身份解析，替换 9 处咽喉点；客户端层零改动
• 实测在未登录环境用 App Token 读到此前因 token 过期而判定"不可入 cron"的真实多维表格全部 102 条记录

测试与文档

• 新增 cmd/bitable_identity_test.go（bot/user/auto 三态 + flag 继承）
• feishu-cli-bitable 技能补「身份选择 --as」表格 + cron 示例 + 91403 排错
• CLAUDE.md Token 策略三类扩为四类

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

全部变更见 CHANGELOG.md

v1.31.0

新功能 — 妙笔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，走「先建后删、同位置重建」——新块创建成功后才删旧块，中途失败不丢数据，返回 new_block_id
• get：读回块 HTML（--raw 逐字节输出便于存文件/再编辑）
• 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 类实战踩坑）。

测试与质量

7 个单测覆盖 record 编码转义、loadHTMLInput 保原文、<script>/U+2028 payload roundtrip；指针解引用统一 client.StringVal，update 补 len==0 防御，get --raw 空内容告警。

---

完整变更见 CHANGELOG.md。

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

v1.30.0

v1.30.0 — 能力大补齐

本版大量补齐多维表格 / 电子表格的高级能力，并新增视频会议机器人、邮箱签名、Markdown 对比等。向后兼容，无破坏性变更（无 flag 删除/改名/改默认值）。经四轮对抗式 review + 六维度发版门禁评估（go/no-go = GO）。

多维表格 Bitable

• 仪表盘 dashboard：CRUD + 复制 + 服务端智能排版 + 13 种图表块
• 表单 form：CRUD + 表单问题批量管理 + 按分享链接(shr)取详情/匿名提交
• 记录附件：上传 / 下载（原始文件名）/ 移除；记录批量获取 batch-get；批量共享链接
• 角色协作者 role member 增删（含批量）、工作流 workflow CRUD/启停、表本体 重命名 / 高级权限开关
• 全部新命令统一支持 --format/--jq/--dry-run

电子表格 Sheet

• 下拉菜单 get/update/delete（多选 + 选项上色高亮）
• 筛选视图及筛选条件完整 CRUD、浮动图片管理、批量单元格样式 batch-set-style

消息与搜索

• search messages --enrich：把消息 ID 补全成内容/发送者/群名/时间，支持 --format/--jq/--page-all
• msg resource-download 支持用户身份下载 + 大文件自动分片

邮件 / 视频会议

• mail signature 查看邮箱签名
• vc bot 会议机器人入会 / 离会 / 查会议事件

文档转换

• 大表导入提速 25-30x + 文档写入自动 3 QPS 限流（避免触发频控）
• 表格列宽自定义（行内注释 <!-- feishu-colwidth --> 或 --table-column-width）
• markdown diff 对比远端/本地 Markdown（支持 --format/--jq）

云盘 / 通用

• 大文件下载突破 100MB（User Token + Range 分片自动兜底）
• api 透传统一支持 --format json|pretty|table|ndjson|csv + 内置 --jq（gojq，无需外部 jq）

---

安装：curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash
完整变更见 CHANGELOG.md。

v1.29.0

v1.29.0

🌟 亮点

本版本聚焦「云文档操作能力补齐」和「Agent 友好性提升」，新增 8 个 CLI 命令 + 2 份方法论文档，并首次系统性沉淀「飞书埋藏 API」反向工程经验。

⭐ 新增命令

通用底座

• feishu-cli api <method> <path> — 通用 OpenAPI 透传，覆盖 2500+ 未封装端点；自动鉴权 + URL 规范化 + 内置 10+ 业务错误码中文翻译 + --dry-run 预览
• feishu-cli auth token --as user|bot|auto — 导出 Access Token 给 curl/Python/任何 HTTP 工具用，复用 feishu-cli 的 Token 全生命周期管理

云文档

• feishu-cli drive apply-permission ⭐ 以用户身份向文档所有者发起协作权限申请（飞书「埋藏 API」，官方文档站未收录但官方 lark-cli 已实现，端到端实测通过）
• feishu-cli drive inspect — 解析任意飞书文档 URL → 输出 type/title/canonical token，自动展开 wiki 节点
• feishu-cli wiki space-create — 创建知识库
• feishu-cli wiki space-list — 列出当前可见所有 wiki space（支持 --page-all 自动翻页）
• feishu-cli wiki node-copy — 复制 wiki 节点（跨 space 或同 space 内）
• feishu-cli bitable record share-link — 批量生成 bitable 记录共享链接

🛠 体验改进

• 外部群操作友好化：chat get/update/delete/link/member 收到 232033/232011/232006 错误时自动打印中文解决方案（含切对外共享 App 的具体命令）；不再让 Agent 误以为"飞书不支持"
• chat member list/add/remove + msg history 全部新增 --as bot|user|auto flag，外部群推荐 --as bot
• msg history 群聊容器自动拉成员名单：顶层新增 chat_members 字段（含群昵称的完整名单）+ chat_members_note 提示；每条 message 注入 sender_name 字段
• feishu-cli api 命令的 detectFeishuBizError 加 232033/232011/232006/232025 分支

📚 文档

• 新增 skills/feishu-cli-chat/references/external-chat.md（飞书外部群完整指南：受影响 API、解锁条件、3 种切 App 方式、错误码速查、sender_id ≠ member_id namespace 隔离的实测证据 + 历史教训）
• 新增 skills/feishu-cli-toolkit/references/embedded-api-discovery.md（「飞书埋藏 API 反向工程方法论」4 步法 + 6 个已知埋藏 API 清单：docs_ai/v1、slides_ai/v1、drive permission apply、drive metas batch_query 等）
• CLAUDE.md 顶层加「通用 API 透传命令（兜底）」+ 「外部群操作（重要）」两段全局规约
• README.md 命令清单 + 详细示例段同步本次 8 个新命令
• 4 个 SKILL.md 同步：feishu-cli-chat / -drive / -bitable / -toolkit

🧪 实测覆盖

命令	实测场景
feishu-cli api	32 个场景 + 30 个单测，含真实 GET/POST/DELETE 调用
feishu-cli auth token	5 场景，含 curl 真实调 user_info 成功
feishu-cli drive apply-permission	真实调用 code:0 Success（端到端 OAuth 补 scope → 调用）
feishu-cli drive inspect	6 场景（含 wiki 展开 / 错误 URL / 无权限）
feishu-cli wiki space-list	真实拉到 178 个 space
feishu-cli wiki node-copy	dry-run + 互斥参数 + 缺参 3 场景
feishu-cli msg history	含外部群 chat_members + sender_name 注入实测

📦 资产

平台	文件
Linux x86_64	feishu-cli_v1.29.0_linux-amd64.tar.gz
Linux ARM64	feishu-cli_v1.29.0_linux-arm64.tar.gz
macOS Intel	feishu-cli_v1.29.0_darwin-amd64.tar.gz
macOS Apple Silicon	feishu-cli_v1.29.0_darwin-arm64.tar.gz
Windows x86_64	feishu-cli_v1.29.0_windows-amd64.tar.gz

🚀 安装

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

🙏 致敬

本版本的「埋藏 API」发现路径，受官方 larksuite/cli 启发。drive_apply_permission 与 drive_inspect 等命令的核心思路移植自官方实现。

v1.28.0 — 兼容性恢复 + msg history 自动展开线程

重要：本版本修复了 v1.27.0 引入的多个静默回归（读类命令 token 策略退化、外部群读取 230002 等），所有 v1.26.0 用户都建议升级。

🔴 重大修复（v1.27.0 → v1.28.0）

Token 策略回归修复

v1.27.0 把约 36 个读类命令的 token 解析从 resolveOptionalUserTokenWithFallback 改成了 resolveOptionalUserToken，破坏了 CLAUDE.md 明确定义的 "User 优先 + Tenant 兜底" 策略。已 auth login 的用户读外部群报 230002 Bot/User can NOT be out of the chat，静默无提示。

修复范围：msg、calendar、task、tasklist、file、board、wiki、user、comment（PR #151）等 36+ 命令全部回退到 WithFallback，恢复 "自动加载 ~/.feishu-cli/token.json + 过期 refresh" 行为。

配套修复

• mail_inline.go：resolveCurrentUserOpenID 补 SaveCurrentUserCache，避免每次 mail 命令都打 /authen/v1/user_info（QPS 风险）
• cmd/config_create_app.go：--save 适配 profile，多 App 用户切到 work profile 后能正确写入 ~/.feishu-cli/profiles/work/config.yaml
• internal/event/bus.go：EventsDir() 接 profile，每个 profile 独立 events 目录，daemon 状态不再跨 profile 污染
• internal/converter/markdown_to_block.go：normalizeURL 用 PathUnescape 替代 QueryUnescape，修 URL query 中字面 + 被错解为空格（如 `?q=a+b` → `?q=a b`），与导出方向对称
• cmd/root.go：Long 文本补 auth/dept/tasklist；--config 与 token 路径解耦时打 stderr warning；清理 9 处冗余 SilenceUsage/SilenceErrors（含 schema.go 矛盾的 SilenceErrors: false）

⚡ 新能力（与官方 lark-cli 对齐）

msg history 默认自动展开线程

对话题群（chat_mode=thread）的根消息，一次性拉取每个 thread_id 的回复，与官方 lark-cli +chat-messages-list 行为对齐：

```bash

默认开启：一次拉根 + 所有话题回复（实测 50 根 + 25 话题 = 26 次 API）

feishu-cli msg history --container-id oc_xxx --container-id-type chat -o json

关闭（保持 v1.27 行为）

feishu-cli msg history --container-id oc_xxx --container-id-type chat --expand-threads=false -o json

调规模

feishu-cli msg history --container-id oc_xxx --container-id-type chat \
--threads-per-page 30 --threads-total-limit 300
```

JSON 输出顶层新增 `thread_replies` / `thread_has_more` / `thread_replies_card_texts`。

意外收益：把线程回复一起送入 contact basic_batch 批量查名字，外部商家用户名字解析率从 ~8% 提升到 ~42%，反超官方 lark-cli（35.5%）。

Comment User Token 支持（PR #151 by @zhmushan）

comment list/add/get/resolve/unresolve 5 个命令终于接受 --user-access-token。文档归个人所有 + App 未加协作者时不再 1069303 forbidden。

converter round-trip 回归测试

新增 23 个 markdown → blocks → markdown 端到端测试，覆盖 inline 粗体/斜体/code/link（含 URL + 号）、嵌套列表、代码块、行内/块级公式（验证 \\nu 不被吃）、blockquote、6 色 Callout 等。

📚 文档与技能同步

• 25 个 SKILL.md 全部含完整 frontmatter（name/description/argument-hint/user-invocable/allowed-tools）
• CLAUDE.md token 策略章节重写为三类（读 / 写 / 必须 User），与 cmd/utils.go 三个 helper 对齐
• feishu-cli-doctor / feishu-cli-profile 描述合并到 feishu-cli-auth；feishu-cli-doc-guide 内容搬到 feishu-cli-import/references/
• README 技能清单从 28 收敛到 25
• skills/feishu-cli-chat/scripts/fetch_chat_history.py 显式 --expand-threads=false 避免与新默认行为双拉

📦 安装

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

🙏 致谢

• @zhmushan 贡献 PR #151（comment User Token）
• @Luoqiu1 贡献 PR #150（board 曲线 path 退化避坑文档）

完整变更

```
0dec77a docs(skill/chat): 脱敏 output-quirks.md 中的真实 App ID 和 open_id
1eafccb fix(comment): list/add/get/resolve 支持 User Token (#151)
46861cb fix(skill/chat): fetch_chat_history.py 显式关闭 expand-threads
f984189 feat(msg): history 自动展开线程回复（与官方 lark-cli 对齐）
c298b46 docs(skills): 同步 25 个 skill + CLAUDE.md + README.md 到 v1.27.1 现状
8587c0a fix(converter): normalizeURL 用 PathUnescape 修 round-trip 不等价 + 加回归测试
f00f6a3 fix(cli): root.go Long 补全 + --config warning + 清理冗余 Silence 设置
0a91e6f fix(profile): 修复 config-create-app 与 event daemon 跨 profile 隔离
8fcadd1 fix: 修复 v1.27.0 读类命令 token 策略回归
```

v1.27.0

Highlights

• 新增 WebSocket 实时事件订阅能力：event list/schema/consume/status/stop，支持 NDJSON 输出、ready marker、进程状态管理和安全输出目录。
• 补齐审批主路径并对齐官方 CLI 当前可执行 schema：approval instance get、approval task transfer，以及 cancel/cc/approve/reject 的 uat_* 用户态接口。
• 增强消息书签、邮件、Markdown、日历、表格、Slides、profile 等命令的参数校验和技能说明覆盖。
• 更新 release 级测试覆盖、registry 元数据、README、CHANGELOG 和 skills/ 文档。

Verification

• go test ./...
• go vet ./...
• gofmt -l cmd internal
• git diff --check
• sensitive information scan
• make build-all
• release tarball structure validation for linux/darwin/windows assets

v1.26.0

Highlights

• Added Markdown export for Sheets with /sheets/<token> URL support.
• Hardened sheet import-md parsing so fenced and indented code blocks are not imported as tables.
• Improved Doc/Wiki Markdown export with safer embedded Sheet expansion and --expand-sheets=false fallback for Wiki exports.
• Fixed Markdown image upload handling for nested imported blocks and kept JSON stdout clean for doc import --output json.
• Made wiki export-tree safer for full-tree exports, including unlimited depth by default, per-document assets directories, pagination checks, and non-zero exit on partial failures.
• Made board export-code compatible with both array and map node payloads.
• Synced README and feishu-cli skills with real CLI flags and examples.

Validation

• go test -count=1 ./...
• go vet ./...
• git diff --check
• gofmt -l cmd internal
• python3 -m py_compile skills/feishu-cli-board/scripts/svg_to_board.py
• make build-all
• Real CLI smoke tests for doc import, sheet import-md, and sheet export --format markdown.

v1.25.0 — 飞书画板 SVG → 原生节点完整路径

⭐ 核心：SVG → 飞书原生节点完整路径

让 AI 画的任意 SVG（飞轮 / 鱼骨 / Dashboard / 插画 / 周期表 / 赛博朋克城市等）都能落到飞书画板，每个矢量元素都是可单独点击编辑的飞书原生节点——不是不可拆的整体贴图。

实战验证：14 张图 / 3949 节点（v3）+ 20 张图 / 8720 节点（v5）端到端跑通。

新增 5 个 board 子命令

命令	用途
`board svg-import`	单 svg 节点导入（适合 < 2KB 装饰元素）
`board clone`	克隆画板（GET → sanitize → 分批 POST，含 connector ID 重映射）
`board upload-image`	本地图片转 image 节点（自动推断像素尺寸）
`board lint`	几何质检（重叠 / 字号一致性 / 容量 / 综合 0-1 评分）
`board export-code`	反向导出 SVG（按 z_index 排序，支持 --merge 合并）

升级现有命令

• board import：新增 `--engine local`（whiteboard-cli 翻译，每节点可编辑）+ `--dry-run` + Mermaid 复杂度警告（par/10+ participant/30+ 长标签）
• board update：新增 `--snapshot` 旧节点快照（增强 overwrite 原子性）
• doc import：Markdown 识别 ```svg fence，与 ```mermaid / ```plantuml 完全对称（三阶段并发管道）

新增基础设施

• `internal/client/whiteboard_cli_bridge.go`：`@larksuite/whiteboard-cli` 桥接，把 SVG/Mermaid 在本地翻译为飞书 OpenAPI 节点 JSON

Skill 大重构：feishu-cli-board

5 路径决策树替代原单层文档：

• A Mermaid 服务端（整图展示）
• B Mermaid 本地引擎（whiteboard-cli，节点可编辑）
• C ⭐ SVG → 原生节点（一键脚本 5 步管道）
• D SVG 单节点装饰（< 2KB 小元素）
• E 精排架构图（手写节点 JSON）

新增 4 篇 references：

• `svg-workflow.md` — 5 步管道详解 + SVG 元素翻译映射表
• `mermaid-engines.md` — server vs local 选型矩阵
• `pitfalls.md` — z_index 错乱 / viewBox 溢出 / 节点翻倍三大致命陷阱及修复
• `examples-real.md` — 14 张实战图档案 + 设计模式索引

新增一键脚本：

• `scripts/svg_to_board.py` — SVG → 飞书画板 5 步管道（翻译 → 修 z_index → 修剪 viewBox → 分批上传 → 验证），三大陷阱全部内置修复

安装

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

使用

```bash

AI 自由作图首选（适合复杂图）

python3 skills/feishu-cli-board/scripts/svg_to_board.py drawing.svg $BOARD_ID

单 svg 装饰

feishu-cli board svg-import $BOARD_ID icon.svg --x 100 --y 100

本地引擎 Mermaid（复杂图）

feishu-cli board import $BOARD_ID complex.mmd --syntax mermaid --engine local

克隆画板

feishu-cli board clone --batch-size 10
```

v1.24.0

✨ 新功能

合并转发消息子内容自动展开（merge_forward）

飞书"合并转发"消息（msg_type=merge_forward）的 body.content 此前固定为占位符 "Merged and Forwarded Message"，子消息（文本/卡片/图片等）完全拿不到。本版本对所有 msg 读取命令默认自动展开：

命令	输出新增字段	说明
msg get	sub_messages 数组	平铺递归展开（深度上限 10 层），含 upper_message_id 可重建嵌套树
msg list / msg history / msg mget	merge_forward_sub_messages map	容器 message_id → 平铺子消息；list 内最多 5 并发展开

核心特性：

• ✅ 递归到底，深度上限 10 层防呆
• ✅ 平铺保留 upper_message_id，可重建嵌套树
• ✅ sender_names 自动合并所有嵌套子消息发送者
• ✅ 单容器失败不阻断主流程，stderr 提示
• ✅ 逃生开关：FEISHU_DISABLE_MERGE_FORWARD_EXPAND=1 全局禁用

顺手修复

• msg list JSON 输出补齐 sender_names 字段（与 msg history / msg get / msg mget 对齐）

技术实现

参考官方 lark cli convert_lib/merge.go，复用飞书未文档化的 card_msg_content_type=raw_card_content query 参数触发 API 返回 data.items[] 完整子消息列表。

详细输出形态、字段说明、性能特性见 feishu-cli-chat SKILL.md。

验证

• 单元测试 10 个 case 全覆盖（平铺 / 递归 / 深度限制 / cycle / API 错误 / auto retry / 并发 / 部分失败 / 逃生开关 / list 集成）
• 真实 e2e 在 SEA AM 测试群验证通过

Breaking changes

无。新增字段对原有 caller 完全向后兼容。

v1.23.0

改进

性能与稳定性

• drive status 大文件 OOM 修复：HashRemoteFile 改用 SDK 流式下载 + io.Copy(h, resp.File)，1GB+ 远端文件计算 SHA-256 时内存峰值从 O(filesize) 降至 O(64KB)
• drive pull / drive status 加 --workers flag（默认 4）：并发下载 / 哈希计算，100 文件镜像约 4× 加速
• BatchGetMessages 5 路并发：保持入参顺序的 errgroup 风格实现，msg mget / 历史消息回退路径直接受益

代码清理

• 删除 splitAndTrimNonEmpty（与 splitAndTrim 等价）
• drive_push 的 pushParentRel / ensureRemoteFolder 改用标准库 path.Dir / path.Base
• 清理 drive_status.go 残留的 _ = filepath.ToSlash 占位代码

文档同步

• feishu-cli-auth：补 auth refresh 子命令完整段落 + v1.22+ stale flag/env token 自动刷新策略
• feishu-cli-import：HTML 标签扩展语法表加 <video> 行 + 视频导入并发说明
• feishu-cli-export：修正"大表格自动拆分"过时描述、<sheet> 改为 v1.22+ token+id 拆分格式、加 <video> 导出行
• feishu-cli-doc-guide：Block 类型映射表补 <video> (type 23) 与 <sheet token+id> (type 30) 两行

兼容性

对外 CLI 行为完全向后兼容，新增 --workers flag 默认值为保守的 4。

安装

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