[riba2534]

概述

对照飞书官方 CLI（larksuite/cli）做的一次全量对齐。按 11 个领域逐项比对源码与服务端契约，修复了一批"代码自洽、但与服务端实际行为不符"的缺陷，补齐了官方已有、本项目缺失的高价值能力。

本项目比官方更稳妥的设计都原样保留，包括：

• fail-closed 身份解析、host 白名单；
• 本地 Markdown 转换器与画板全家桶；
• 单文档 3 QPS 限流；
• api --page-all 出错即失败。

这次修复的大部分缺陷，gofmt、go vet、go test 都发现不了，每一条都是用编译后的二进制在真实飞书环境里复现、修复再复验的。

发版号为 v1.42.0（按维护者决定继续使用 1.x，模块路径不变，go install ...@latest 照常可用）；9 个 SKILL.md 的 compatibility 已同步为 v1.42.0+。
下文"行为变更"中的条目会改变部分旧用法，CHANGELOG.md 的 [Unreleased] 开头有迁移指南，逐条列出受影响的旧用法和改法；退出码分类保留。

⚠️ 行为变更（合并前请过目）

范围	变化
退出码	0 成功 / 1 一般 / 2 用法 / 3 鉴权或权限 / 4 网络 / 10 需确认 / 130 中断。错误文本不变。判断 == 1 的脚本需要调整
删除类操作	非交互且未带 --yes（或 --force）时 exit 10 且不执行。此前打印"操作已取消"后 exit 0，Agent 会误判为成功
日历 / 任务写命令	默认身份 Bot → --as auto（已登录即本人身份）；calendar event-reply 改为必须 User
多维表格	record list 默认 100 条（原 20 条且无提示）；table/field/view list 返回全量；视图配置 get/set 直接输出数组；role 输出去掉外层 data
电子表格	delete-rows/delete-cols/protect 的 --start/--end 按文档语义换算为接口口径（原来会多删一行 / 保护范围错位）
文档	doc import 部分失败 exit 1；content-update 纯文本选择器改为文本级替换，块级模式多处命中 exit 2
邮件	读取类命令正文默认输出解码后的明文（--raw-body 保留原值）；draft-edit 改为局部修改
会议	vc bot meeting-join/leave 仅支持 Bot；minutes get --with-artifacts 的逐字稿改为写入文件
云盘	下载改为 60s 空闲超时（不再有 5 分钟总时长）；push/pull 遇鉴权、权限或限流错误时终止整批；file delete 改为异步并轮询
IM	话题群 msg history 只返回根消息；user search --query 改走 v3 接口，不再返回 user_id
OKR	cycle list 默认查 v2 用户周期（与 cycle detail 的 ID 一致），旧的租户周期用 --tenant
api	业务错误时 stdout 为空，错误写 stderr（--raw 例外）
搜索文档	search docs 改走 Search v2：每页最多 20 条（原 50），翻页改用 --page-token，--offset 大于 0 时报用法错误
画板	board export-code --output-path 的目标文件已存在时默认报错，覆盖需要加 --overwrite（原来静默覆盖）
本地路径	输出路径或输入文件命中敏感目录、输入文件不存在或是目录时，退出码统一为 2，且在发出任何网络请求之前报错

主要修复

会丢数据或有安全风险的

• drive push --if-exists overwrite 原来是先删后传。现在带 file_token 原地覆盖：token、链接、协作者、评论都保留。实测覆盖后 token 不变；旧版 token 会变。
• sheet delete-rows --start 2 原来会删掉第 2、3 两行。实测现在只删第 3 行。
• doc content-update replace_all "旧"→"新" 原来会覆盖整段。现在是文本级替换，粗体等样式也保留。另外，本地导出的 Markdown 写回时，原来画板会被静默清空；现在先转换，无法转换的直接拒绝。
• 删除表单题目原来会连带删除整列数据，且没有任何提示。现在加了 --keep-field 和确认门禁。
• apps html-publish 原来会把 .git 一起打包发布到公网。
• 输入/输出路径现在拒绝 ~/.ssh、~/.aws、~/.feishu-cli、/etc 等敏感目录。
• 建块、建图在 5xx 时自动重试，原来可能生成重复块或重复图。现在重试复用幂等 token，或先回读确认。

与服务端契约不符的

• wiki 节点解析从 get_node 迁移到 node_by_token。
• 新增统一的资源 URL 解析器：只看路径前缀，?from=/wiki/ 不会再误导解析。
• 业务错误随 HTTP 400 下发时，先解析业务码再判断：错误信息附带 log_id 和缺失的 scope。99991672 不再提示"重新登录"（重新登录解决不了）。
• api --data 和表格写入中的大整数不再被舍入。
• callout 背景色枚举原来整体错了一位：NOTE 显示成浅紫，修正后为浅蓝。
• Office token 判定修正（原来会误判，导致图片上传后不渲染）。
• 邮件：正文 base64 解码；In-Reply-To 补尖括号；draft-edit 不再丢失回复头和附件。
• 会议与妙记：vc note transcript 按官方协议重写；meeting-events 原来文本模式永远显示 0 条；妙记搜索固定排序后翻页不再漏条。
• 话题群消息重复、群成员列表缺少机器人。
• 事件订阅原来按事件类型各开一条连接，会和同一应用的其他连接争抢事件；现在单进程只开一条连接。
• 认证：scope 支持逗号分隔；auth status --verify 刷新 token 时加锁；刷新失败按错误码分类。
• 集成阶段发现的跨领域问题：
  • SDK 的 token 缓存原来是全局的，同一 app_id 切换 base_url 后仍复用旧 token；现在随客户端实例重建而丢弃。
  • 中文在截断时被切成半个字符（9 处）。
  • Bot 异步删除失败时没有给出原因。
  • table-put 覆盖写入后，数值被存成了文本。

补齐的能力（节选，完整列表见 CHANGELOG）

• 文档：content-update 支持 --block-id 和本地资源；doc read --engine docs_ai --with-ids；doc create --content；doc history。
• Slides：完整的编辑闭环。
• apps html-publish --wait，可拿到访问链接或构建错误。
• 画板：SVG 走服务端解析，生成可编辑节点。
• 日历：重复日程的 --apply-to、分享链接、参会人管理。
• 审批：退回、加签、催办。
• OKR：目标和 KR 的写入与评论。
• 邮件：附件、收信规则、线程整理。
• 会议：vc meeting list-active。
• IM：@file/stdin 统一输入、附件区、msg edit、联系人 v3 搜索。
• 平台与工程：
  • skills install：技能内嵌进二进制，与 CLI 版本严格配套；
  • doctor 检测技能版本漂移；
  • --help 末尾指向相关技能；
  • update 命令、auth scopes；
  • CI、make release-package、make check-privacy。

技能目录 review 与文档实测（本轮追加）

技能目录（9 个领域技能逐条核对；依据是新二进制的 --help、源码和实跑结果）

• 修正过时或错误的说法：身份、默认值、输出字段、退出码，以及示例的参数与取值。

• 新增 Agent 调用契约 feishu-cli-platform/.../auth/references/agent-contract.md，内容包括：

  • 退出码含义；
  • 退出码 10 的确认门禁；
  • stdout/stderr 约定；
  • Bot 建资源后的自动授权；
  • 目标解析。

  各领域 SKILL.md 末尾统一指向它。

• 内容按命令归属迁移：

  • msg、chat 之间互相调整；
  • drive add-comment 迁到 comment；
  • drive apply-permission 和 drive secure-label 迁到 perm；
  • drive search 迁到 platform/search。

• 跨工作流的命令组必须使用显式前缀，命令组的 --help 会列出全部相关工作流。make check-skills 会强制检查这两条。

• 身份表 identity.md 按 --help 逐条核对过。

• 9 个 description 统一改为单行，结构为"能力 → 何时用 → 不用于"。

• 评测数据：

  • trigger-evals.json 替换 17 条，仍是每个领域 8 个正例；
  • trigger-boundary-evals.json 新增 11 条；
  • evals.json 为新增的命令组补了 21 条用例。

• ⚠️ 本次没有运行模型触发评测（按维护者决定）。description 的改动只做了静态核对：72 条正例都能在本领域 description 里找到覆盖短语；72 条近邻负例落在"不用于"或能力边界之外；31 条边界用例的归属一致。这只说明文字覆盖到位，不代表实际触发率。

review 中顺带修复的 Go 缺陷

• msg read-users：已登录时必然失败。改用原始请求，新增 --as。
• file version create：数字 status 解析错误，会把成功误报为失败，导致重复建版本。
• 会议与妙记：
  • 妙记命令接受妙记链接；
  • vc notes 在会议号和日历路径下也会补拉纪要产物；
  • 产物部分失败时非零退出；
  • minutes download 同批同名文件自动改名。
• 邮件：
  • 内联图片在 home 为软链接时被误拒；
  • --format 只接受服务端支持的取值；
  • thread-modify 的错误提示改为指向 thread-trash。
• search docs 迁移到官方使用的 Search v2 端点：每页最多 20 条，翻页用 --page-token。
• 其他：
  • okr comment create --select-all 配 --content-json 时选区为空；
  • board export-code 原来静默覆盖已有文件，现在需要 --overwrite；
  • slides 和 mail 的授权域补齐 scope；
  • 一批用法错误的退出码统一为 2。

文档转换器（这些都是全块类型往返实测时发现的）

• doc export 导出的 <image/file token>、<whiteboard token>、视频重新导入时，原来整篇报 1770001 失败。现在下载原素材重新上传，画板按源码重建或复制节点。
• 嵌套引用（原 1770030）、分栏（原 1770028，列内有空行时内容会被截断）。
• 列表项的多个段落原来会被合并成一段。
• 表格单元格里的公式没有转换。
• 被服务端拒绝的单个块现在隔离跳过，建块阶段失败也会输出 JSON。
• --download-images 时资源路径改为相对输出文件。
• doc 子命令接受文档链接。
• 建块按"每批最多 5 个画板"切分。实测单次请求出现第 6 个画板就报 1770035；此前含多个画板的导出文件重新导入会在第二批中止，doc add 则直接失败。
• doc read --keyword 能命中导出时被转义的词。

本地路径安全（E2E 实测发现的 P0，已系统性修复）

• 实测 doc export <文档> -o ~/.ssh/x.md 会真实写入 ~/.ssh。markdown fetch、doc export-file、drive export 等十余个命令也有问题：要么先发请求或先建导出任务再处理路径，要么不经校验直接写文件；doc import、doc add 读取本地文件时也不校验路径。
• 修复分三层：
  • 原子写入口默认拒绝敏感目录，CLI 自管路径改用 Trusted 变体；
  • 所有用户指定的输出路径或目录，都在第一次网络请求之前校验；
  • 本地输入文件统一校验：命中敏感目录、文件不存在、是目录或无权限读取，一律返回退出码 2。
• 审计了 27 个写入点、47 个读取点，逐条标注了归属。
• 用 strace 复验了 13 个用例，包括真实文档 doc export -o 到敏感目录、--assets-dir、markdown fetch、export-file、drive export、board image、api -o、drive pull --local-dir，以及输入文件不存在或是目录：
  • 全部退出码 2；
  • AF_INET 连接数为 0，仅有查询本机 nscd 的 AF_UNIX 连接（对照组有 19 次 AF_INET）；
  • 没有生成任何文件。
• 正常路径回归通过：导出并下载图片、api -o、auth status、skills install。

飞书文档 / 画板 E2E 实测（两条独立 lane，只用新建的 fp-test-* 资源，测完已删除并确认 1770003 resource deleted）

• 文档往返：78 项。往返矩阵覆盖：

  • H1–H6；
  • 行内样式、三层嵌套列表、多段落列表项、任务列表、代码块、三层嵌套引用、6 种 Callout；
  • 表格：含公式、样式、图片单元格，大于 9 行和大于 9 列；
  • 列宽注释、图片、公式；
  • 11 种 Mermaid、journey 降级、PlantUML、SVG；
  • 含空列的分栏；
  • content-update 全部 10 种模式、doc history、原生 Markdown 文件、PDF/DOCX 导出。

  二次往返除 token 外一致。实测中发现的 8 个问题已全部修复并复测，包括上面的 1770035、关键词搜索和本地路径安全。

• 画板：43/43 通过，覆盖：

  • 服务端与本地两种 Mermaid 引擎、PlantUML、服务端 SVG 解析；
  • svg-import、upload-image、nodes、image、lint、export-code（含 --overwrite）；
  • update --overwrite --snapshot、clone（connector 重映射）、delete；
  • svg_to_board.py 五步管道（21 个节点，lint 0.90）；
  • doc htmlbox 全生命周期。

• 技能和 CLAUDE.md 里关于 Mermaid 的旧禁令已删除：字面花括号、方括号内冒号、par...and...end、11 个参与者的时序图，以及带 skinparam、缩进、可见性标记的 PlantUML。删除依据是 doc import 实测，这些写法全部一次渲染成画板。

• 会议与妙记只做了一项只读调用：用维护者指定的妙记取逐字稿。其余领域按维护者的分工只做静态核对（对齐官方 CLI 的底层 API），没有实际调用。

验证

项	结果
gofmt -l cmd internal	无输出
go vet ./...	通过
go test ./...	19 个包全部 ok（含技能 review、转换器、路径安全新增的测试）
go test -race ./...	19 个包全部 ok，无 DATA RACE
make check-skills	通过：584 个命令都有唯一的技能归属，跨工作流命令组都用了显式前缀，1158 条示例参数检查通过，离线契约 9/9
make check-privacy	通过（扫描 1303 个文件）
make release-package VERSION=v1.42.0-rc	5 个平台包 + checksums.txt，结构自检和宿主平台实跑通过（产物已删除）
每个 P0 修复	都有单元测试，并做了反向验证：回退修复后新测试失败，恢复后通过。画板分批、关键词搜索还另外用修复前的二进制复现了缺陷作对照
真实二进制回归	11 个领域分别回归，集成后再做跨领域回归，README 新增的示例逐条实跑。证据摘要见下
模型触发评测	本次未运行（维护者决定）。description 的改动做了静态覆盖核对，见上文"技能目录 review"

集成分支真实回归摘要（写操作只针对新建的 fp-test-* 资源，验证后已删除）

• 基础设施
  • 未知命令、拼错子命令：exit 2，并给出拼写建议。
  • 非交互删除不带 --yes：exit 10，未执行。
  • -o ~/.ssh/x：exit 2，文件未创建。
  • Bot 调用应用未开通权限的接口：exit 3，提示到开放平台开通，附 log_id。
  • 网络不可达：exit 4。
• 文档：全块类型导入，permission_grant=granted；replace_all 文本级替换，段落其余文字和样式保留；NOTE callout 为浅蓝；带画板占位的导出写回被拒绝，并列出行号。
• 电子表格：Sheet1! 前缀可用；delete-rows --start 2 只删第 3 行；1000000 与 15 位整数原值回读；table-put 时分秒往返一致。
• 多维表格：150 条记录时默认返回 100 条并带 next_offset，--page-all 拿到 150 条、无重复；批量删除 120 条成功；resolve 判型正确。
• 云盘：push 覆盖后 file_token 不变；pull/status 正常；分页提示带续翻 token；异步删除轮询到 success。
• 日历 / 任务 / 审批：freebusy 默认查本人；以 auto 身份创建并删除日程；task complete 幂等；审批稀疏分页给出续翻提示。
• 邮件 / 妙记：triage 用 inbox 文件夹名可用；正文已解码；妙记按创建时间严格倒序。
• Slides / 画板：创建、加页、按页读取、截图、删页门禁；SVG 解析为 4 个可编辑节点。
• IM
  • 话题群 history：旧版返回 19 条（只有 9 条根消息、6 条重复）；新版 13 条，全部是根消息，无重复。
  • 群成员：旧版 0 个 bot，新版 26 个 bot。
  • event consume：加了 timeout 后，stdin EOF 不再导致提前退出。
  • 发消息只由 Bot 发给本人，验证后全部撤回：--markdown @file 样式归一、--attachment、msg edit、Bot 身份 reaction、资源下载用服务端文件名、stdin 输入。

未能真实验证的部分（只有单测覆盖）

项	原因
OKR、考勤、妙搭的真实数据	当前应用或用户缺少相应 scope，只验证了端点与错误路径
Slides lint 拦截（4000153）	本租户服务端没有拦截
统一逐字稿成功路径	找不到 unified 类型的纪要样本
妙搭真实发布、机器人入会/离会、真正发出邮件、审批写操作	对外可见，按约定只做了 dry-run

按默认方案处理的决策点（如需调整请告知）

• 不接入未公开的 sheet_ai 端点。图表、条件格式、透视表依赖它，列为后续。
• docs_ai 作为可选引擎，与本地转换器并存：--engine docs_ai、doc create --content。
• 妙搭只补发布闭环（get / release / --wait），db/file/env 等约 90 个命令暂不做。
• 原本没有确认的删除命令，不新增确认门禁，避免破坏 cron 脚本。唯一例外是"删除表单题目会连带删除整列数据"。

合并后需要人工处理的一项

回归时留下了一个无法自动删除的测试日程：fp-test-att，2026-11-30 07:00–07:30。它的组织者被转给了应用机器人，而应用没有租户级的日历删除权限。这个日程只出现在本人和机器人的日历上，请在飞书客户端手动删除。