CLIAI 技能【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址https://gitcode.com/gh_mirrors/cli414/cli点击查看免费下载本指南围绕官方 Lark/飞书 CLIlark-cli的 Slides 历史版本能力展开讲解如何使用slides history-list列出 Slides XML 演示文稿的历史版本、通过history-revert按history_version_id发起回滚以及用history-revert-status轮询异步任务状态。读完本文你将掌握一套可安全落地的版本回滚流程从候选版本筛选、跨页补拉、候选确认到异步轮询边界与回滚后的内容验证并能直接照着命令与参数在真实演示文稿上执行。背景为什么回滚需要一套专门流程Slides 演示文稿在飞书/Lark 侧以 XML 形式存储每一次编辑都会产生新的历史版本。与普通文档的直接恢复不同CLI 的回滚是异步任务history-revert提交后立即返回task_id真正的回滚在服务端后台执行。因此整个流程天然分为三个阶段定位版本通过分页接口history-list找到目标版本拿到回滚所需的history_version_id发起回滚history-revert提交异步任务拿到task_id与建议轮询间隔poll_after_ms轮询确认history-revert-status持续查询任务状态直到done/partial_failed/failed再做回滚后验证。其中有一个关键概念需要先澄清回滚接口只接受history_version_id不要直接把revision_id传给history-revert。这一约束在 skills/lark-slides/SKILL.md 中被标记为 CRITICAL 级别history_version_id对应服务端minor_history.version是回滚接口需要的 ID而revision_id是文档修订号同一revision_id可能对应多条历史记录不能作为回滚依据。三个命令与底层实现总览三个命令均在 shortcuts/slides/slides_history.go 中注册统一走/open-apis/slides_ai/v1/xml_presentations/{xml_presentation_id}/...这一组 Slides AI OpenAPI 端点| 命令 | 底层端点 | HTTP 方法 | 风险等级 | 必填参数 | |-|-|-|-|-| |history-list|.../histories| GET | read |--presentation| |history-revert|.../history/revert| POST | write |--presentation、--history-version-id| |history-revert-status|.../history/revert_status| GET | read |--presentation、--task-id|权限声明源码中Scopes/ConditionalScopes字段也值得注意history-list与history-revert-status需要slides:presentation:readhistory-revert属于写操作需要slides:presentation:update与slides:presentation:write_only三个命令都声明了条件权限wiki:node:read——只有当--presentation传入的是 wiki URL 时才需要额外解析三者均支持user与bot两种身份AuthTypes。--presentation的取值支持三种形态requiredPresentationRefFlag定义xml_presentation_id、Slides URL或可解析为 Slides 的 wiki URL。当传入 wiki URL 时执行期会先调用 wiki 节点解析接口/open-apis/wiki/v2/spaces/node_by_token把 wiki 节点解析为真实的 slides token再拼接上述端点——这一点在单元测试 TestSlidesHistoryExecuteResolvesWikiPresentation 中通过 mock 验证先返回obj_type: slides与obj_token随后才发起histories请求。安全流程七步完成一次可信回滚为了不让回滚这个高风险操作出现误判、误回滚或重复提交CLI 定义了一条标准安全流程先用分页接口history-list找到目标版本的history_version_id。history-list是分页接口返回has_more与page_token需要继续翻页时再传--page-token。如果用户指定的是revision_id不要假设它唯一也不要把revision_id直接传给history-revert。先拉一页并在entries[]中筛选revision_id相同的候选如果未匹配到且has_moretrue继续用page_token翻页如果已匹配到候选最多额外再拉一页补齐可能跨页的相邻候选。最终优先根据用户目标时间与edit_time的接近程度选择最合适的一条取同一条的history_version_id如果没有目标时间、或多个候选无法可靠区分则向用户展示候选版本并确认后回滚。如果用户指定的是某一时刻但没有指定revision_id按entries[].edit_time匹配优先选择不晚于目标时刻的最近一条历史记录无法明确匹配时先向用户确认候选版本。使用history-revert发起回滚接口立即返回task_id回滚任务在服务端异步执行。如果返回status: running保存task_id按照返回的poll_after_ms等待后调用history-revert-status。任务创建成功后不得因为状态查询失败而重新发起回滚。停止条件状态变为done、partial_failed或failed后停止轮询达到整体轮询上限时也停止轮询并向用户返回task_id和当前状态。回滚完成后验证用slides xml-get读取演示文稿内容确认。这条流程把定位→确认→提交→轮询→验证串成闭环每一步都避免了对服务端状态的猜测是 Agent 与人类用户共用同一套命令时的可靠基线。按 revision_id 或时间点回滚的智能匹配策略当用户表达回滚到 revision_id42恢复到昨天下午 3 点的版本这类需求时Agent 应当执行如下细化流程执行slides history-list --presentation presentation获取第一页历史记录只有has_moretrue且还需要更多候选时才继续传--page-token翻页。用户给出revision_id时先筛选当前页中entries[].revision_id 用户给出的 revision_id未命中且has_moretrue继续拉下一页已命中候选最多额外再拉一页补齐同一个revision_id可能跨页出现的相邻history_version_id若用户同时给出目标时间在候选里选择edit_time与目标时间最接近的一条若未给目标时间但候选只有一条可直接使用若多个候选无法可靠区分不要自行取第一条向用户展示候选并确认。用户只给出时间时用entries[].edit_time匹配选择目标时刻之前最近的一条如果用户表达的是最接近某时刻则选择绝对时间差最小的一条。从最终匹配条目读取history_version_id对应服务端minor_history.version。执行slides history-revert --presentation presentation --history-version-id history_version_id。候选确认时使用类似格式让用户能一眼区分同一个 revision_id 命中多个历史版本请确认要回滚哪一条 - history_version_id11 revision_id42 edit_time2026-06-22T12:24:45Z name... - history_version_id12 revision_id42 edit_time2026-06-22T12:25:14Z name...这里有一个时间格式约定必须遵守entries[].edit_time是UTC RFC3339 时间字符串例如2026-06-22T12:24:45Z。按时间匹配时先将其解析为时间值再比较先后关系或时间差不要做字符串比较。命令与参数速查# 列出历史版本 lark-cli slides history-list --presentation slides_url_or_token --page-size 20 # 翻页 lark-cli slides history-list --presentation slides_url_or_token --page-size 20 --page-token page_token # 发起回滚任务立即返回 task_id lark-cli slides history-revert --presentation slides_url_or_token --history-version-id 42 # 查询回滚任务状态 lark-cli slides history-revert-status --presentation slides_url_or_token --task-id task_id完整参数说明如下与源码 Flag 定义一致| 命令 | 参数 | 必填 | 说明 | |-|-|-|-| |history-list|--presentation| 是 |xml_presentation_id、Slides URL或可解析为 Slides 的 wiki URL | |history-list|--page-size| 否 | 返回条数范围1-20默认20| |history-list|--page-token| 否 | 上一页返回的page_token| |history-revert|--presentation| 是 | 同一个演示文稿 | |history-revert|--history-version-id| 是 |history-list返回的history_version_id必须大于 0 | |history-revert-status|--presentation| 是 | 同一个演示文稿 | |history-revert-status|--task-id| 是 |history-revert返回的task_id|参数校验在源码层面对齐了文档约束见 shortcuts/slides/slides_history.go 中的validateSlidesHistoryPageSize与validateSlidesHistoryVersionID--page-size必须落在1-20越界报ValidationError--history-version-id必须是正整数字符串strconv.ParseInt失败或 0均拒绝错误信息明确提示必须是slides history-list返回的正整数--task-id不允许为空。对应地TestSlidesHistoryValidation 覆盖了page-size 传 0history-version-id 传 abc / 0task-id 传空串等边界用例断言错误均带正确的参数名--page-size、--history-version-id、--task-id。异步轮询策略边界条件与失败语义由于回滚是异步任务轮询策略决定了流程的健壮性。标准策略如下history-revert返回task_id后认为回滚任务已经成功创建。如果status不是running不再调用状态接口任务可能已同步完成。如果status是running等待响应中的poll_after_ms后调用history-revert-statuspoll_after_ms缺失、为0或非法时默认等待 10 秒。状态查询返回running时继续轮询返回done、partial_failed或failed时停止。除非用户另有要求默认最多轮询5 分钟。达到上限后停止轮询向用户说明任务仍在运行并返回task_id不得将其描述为回滚失败。状态查询出现临时错误时按相同间隔最多连续重试 3 次只重试history-revert-status不得重新调用history-revert避免重复回滚。done后读取当前演示文稿内容进行验证。partial_failed或failed时展示failed_block_tokens除非用户明确确认不得自动再次发起回滚。这条策略的关键点可以浓缩为三条底线任务创建后不重复提交、轮询超时不等于失败、失败后的再次回滚必须经用户确认。返回值要点history-list返回分页结构{ entries: [ { revision_id: 42, history_version_id: 11, edit_time: 2026-06-22T12:24:45Z, type: 1, name: 版本名, description: 版本说明, editor_ids: [ou_xxx] } ], has_more: true, page_token: page_token }history-revert返回异步任务创建确认{ task_id: task_xxx, status: running, history_version_id: 11, poll_after_ms: 10000 }history-revert-status返回{ status: partial_failed, history_version_id: 11, failed_block_tokens: [blk_xxx] }status可能的取值为running、done、partial_failed、failed。当状态是partial_failed或failed时优先检查failed_block_tokens——它列出了回滚失败的块block标识是向用户说明失败范围的关键依据。回滚后验证回滚成功后必须读取一次当前内容确认这也是安全流程的最后一步lark-cli slides xml-get --presentation slides_url_or_token --output ./presentation.xmlxml-get的实现见 shortcuts/slides/slides_xml_get.go--output指定本地 XML 输出路径现有文件会被覆盖也可省略--output让 XML 以 JSON envelope 形式返回或用--raw直接打印原始 XML 到 stdout--revision-id默认-1表示最新版本。回滚验证时读取最新内容确认目标版本内容已生效。从源码与测试看实现保障参数与请求构造三个命令的请求构造非常规整history-listGETQuery 参数page_size、page_tokenslidesHistoryListParams中仅在非空时才带上page_tokenhistory-revertPOST请求体为{history_version_id: ...}slidesHistoryRevertBody且不包含wait_timeout_ms这类等待参数——TestSlidesHistoryDryRun 与 TestSlidesHistoryDryRunE2E 都专门断言了 revert 请求体不得出现wait_timeout_ms说明回滚被刻意设计为纯异步提交不依赖同步等待history-revert-statusGETQuery 参数task_id。Dry-run 与两步编排history-list等命令支持--dry-run预演。对普通 token 只需一步GET /open-apis/slides_ai/v1/xml_presentations/{id}/histories对 wiki URL 则是两步编排先GET /open-apis/wiki/v2/spaces/node_by_token解析 wiki 节点再发起历史版本请求dry-run 中占位为resolved_slides_token。TestSlidesHistoryDryRunWithWikiPresentation 断言两步调用依次出现TestSlidesHistoryDryRunE2E 在真实 CLI 进程上验证了三个命令 dry-run 的端点、方法与参数。E2E 工作流测试最完整的证据来自端到端工作流测试 TestSlidesHistoryWorkflow通过设置环境变量LARK_SLIDES_HISTORY_E2E1并携带 user token 开启。它完整走了一遍真实回滚链路slides create创建演示文稿记录原始内容 marker 与revision_idslides update-slide写入更新 marker确认revision_id增大轮询history-list在entries[]中按revision_id匹配出原始版本的history_version_idhistory-revert发起回滚若status running则用task_id轮询history-revert-status直到非running断言最终状态为done再读取整篇 XML 确认内容恢复为原始 marker。这个测试同时验证了文档中反复强调的两点按revision_id在历史记录中定位history_version_id的可行性以及回滚后必须读回内容做验证的必要性。常见场景速记| 用户诉求 | 推荐动作 | |-|-| | 回滚到 revision_id42 | 翻页筛选revision_id 42的候选必要时补拉一页确认后取history_version_id回滚 | | 恢复到昨天下午 3 点 | 按edit_time匹配目标时刻之前最近的记录 | | 最接近某时刻的版本 | 按edit_time与目标时刻的绝对时间差取最小 | | 回滚后想看结果 |xml-get读取当前 XML 确认内容 | | 任务一直 running | 按poll_after_ms默认 10s轮询整体上限默认 5 分钟超时返回task_id而非报失败 |结合 skills/lark-slides/references/cli/lark-slides-history.md 原文档、skills/lark-slides/SKILL.md 的技能约束以及 shortcuts/slides/slides_history.go 的实现这套定位版本 → 确认候选 → 异步回滚 → 轮询状态 → 读回验证的闭环已经足够支撑人类用户与 AI Agent 在飞书/Lark 幻灯片上安全、可审计地完成任意历史版本回滚。赞分享CLIAI 技能【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址https://gitcode.com/gh_mirrors/cli414/cli点击查看免费下载相关推荐飞书 CLIlark-cliDocx 历史版本管理history-list / history-revert / history-revert-status 回滚实战指南飞书 CLIlark cliDocx 历史版本管理history list / history revert / history revert stCLIAI 技能lark-cli Base 记录变更历史查询record-history-list 命令实战与实现原理lark cli Base 记录变更历史查询 record history list 命令实战与实现原理 导读 record history list 是CLIAI 技能飞书 CLI slides 领域命令全景指南从 lark-slides 技能体系到幻灯片创建、编辑与回滚实战飞书 CLI slides 领域命令全景指南从 lark slides 技能体系到幻灯片创建、编辑与回滚实战 本文基于当前仓库中 affordance/sliCLIAI 技能上一篇RimSort终极指南三分钟掌握《环世界》模组管理告别游戏崩溃烦恼下一篇5分钟搞定虚拟显示器ParsecVDD终极指南解锁4K游戏串流新境界创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
