lark-cli `wiki +move-to-drive` 完全指南：将飞书 Wiki 节点移入 Drive 文件夹的异步移动协议与续跑实践

lark-cliwiki move-to-drive完全指南将飞书 Wiki 节点移入 Drive 文件夹的异步移动协议与续跑实践【免费下载链接】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-cli飞书官方 CLI的wiki move-to-driveshortcut 为研究对象完整讲解「把已有 Wiki 节点移出知识库、放入指定 Drive 文件夹或『我的空间』根目录」这一写操作的命令用法、异步任务轮询协议、超时续跑机制、权限影响与底层源码实现。读完本文你将能正确区分wiki move、wiki move-to-drive与drive move的适用场景理解move_wiki_to_docs异步协议的数值状态语义并能在轮询超时后用drive task_result --scenario wiki_move_to_drive安全续跑任务。功能概述wiki move-to-drive是 lark-cli 中用于将已有 Wiki 节点移出知识库Wiki 空间放入 Drive 文件夹或当前调用身份的「我的空间」根目录的快捷命令shortcut。它是会改变文档归属与权限继承的写入操作且该操作始终创建异步任务——shortcut 会按固定窗口自动轮询窗口内未完成时返回可续跑命令交由调用方继续查询。命令定义见 shortcuts/wiki/wiki_move_to_drive.go其在 shortcut 注册表中声明为var WikiMoveToDrive common.Shortcut{ Service: wiki, Command: move-to-drive, Description: Move a wiki node to a Drive folder, polling the async task until it finishes, Risk: write, Scopes: []string{space:document:move, wiki:space:read}, AuthTypes: []string{user, bot}, // ... }前置条件使用前先阅读 skills/lark-shared/SKILL.md了解认证方式、--as user|bot身份模型、JSON 输出契约与高风险操作安全规则。何时使用四类移动场景的取舍移动文档存在四条路径选择依据是源对象类型与目标位置源对象目标位置命令Wiki 节点Wiki 空间或 Wiki 父节点wiki moveDrive 文档Wiki 空间或 Wiki 父节点wiki moveWiki 节点Drive 文件夹或「我的空间」根目录wiki move-to-driveDrive 文件 / 文件夹Drive 文件夹或根目录drive move判断口诀源对象已是 Wiki 节点、目标是 Wiki 空间/父节点 →wiki movenode 模式源对象还是 Drive 文档、目标是「迁入知识库 / 挂到某个 Wiki 页面下」→wiki movedocs_to_wiki 模式源对象是 Wiki 节点、目标是 Drive 文件夹或根目录 →wiki move-to-drive本文主题源对象已是 Drive 文件/文件夹、目标也是 Drive 文件夹 →drive move。完整的场景决策树见 skills/lark-wiki/references/lark-wiki-move.md 与 skills/lark-wiki/SKILL.md 中的「快速决策」一节其中明确要求用户要把已有 Wiki 节点移出知识库时必须使用wiki move-to-drive不要使用wiki move或drive move。关键前置--node-token必须是 Wiki 节点 token--node-token必须是 Wiki 节点 token形如wikcnXXX不是底层文档的obj_token形如doxcnXXX。无法判断时先执行解析命令确认lark-cli wiki node-get --node-token URL_OR_TOKENwiki node-get会统一解析 node_token / obj_token / 飞书 URL返回data.space_id、node_token、obj_token、obj_type等字段作为后续移动的输入依据。这一点在 skills/lark-wiki/SKILL.md 中有强约束「获取或解析 Wiki 节点统一使用wiki node-get包括只为获取space_id、node_token、obj_token或obj_type的中间步骤」。命令用法与参数详解基本命令# 移到指定 Drive 文件夹 lark-cli wiki move-to-drive \ --node-token WIKI_NODE_TOKEN \ --folder-token TARGET_FOLDER_TOKEN \ --as user # 移到当前调用身份的「我的空间」根目录 lark-cli wiki move-to-drive \ --node-token WIKI_NODE_TOKEN \ --as user # 预览提交任务和轮询任务两步请求 lark-cli wiki move-to-drive \ --node-token WIKI_NODE_TOKEN \ --folder-token TARGET_FOLDER_TOKEN \ --dry-run参数表参数必填说明--node-token是要移出知识库的 Wiki 节点 token--folder-token否目标 Drive 文件夹 token省略时移动到当前调用身份的「我的空间」根目录参数校验的源码实现从 shortcuts/wiki/wiki_move_to_drive.go 的validateWikiMoveToDriveSpec可以看到--node-token缺失直接返回--node-token is required的校验错误SubtypeInvalidArgumentnode-token 与 folder-token 都会经过validateOptionalResourceName做资源名合法性校验如拒绝../folder这类路径注入写法。对应测试 shortcuts/wiki/wiki_move_to_drive_test.go 中TestValidateWikiMoveToDriveSpec覆盖了「必须传 node-token」「拒绝不安全 folder-token」「允许省略 folder-token」三种情形。另外请求体的构造逻辑wikiMoveToDriveSpec.RequestBody是仅当--folder-token非空时才写入folder_token字段省略时请求体为空表示移动到「我的空间」根目录。TestWikiMoveToDriveRequestBodyOmitsEmptyFolder精确验证了这一行为。异步协议与轮询行为wiki move-to-drive的移动请求永远创建异步任务shortcut 按以下两步协议执行提交移动任务POST /open-apis/wiki/v2/nodes/{node_token}/move_wiki_to_docs响应中取得完整、不可拆分的task_id。若响应缺失task_idCLI 会以SubtypeInvalidResponse内部错误拒绝见TestWikiMoveToDriveExecuteRejectsMissingTaskID。轮询任务状态GET /open-apis/wiki/v2/tasks/{task_id}?task_typemove_wiki_to_docs读取data.task.move_wiki_to_docs_result。数值状态语义轮询结果的状态码是数值类型语义固定状态值含义status1处理中processingstatus0成功successstatus-1失败failure源码中以常量固化见 shortcuts/wiki/wiki_move_to_drive.gowikiMoveToDriveTaskType move_wiki_to_docs wikiMoveToDriveResult move_wiki_to_docs_result wikiMoveToDriveStatusSuccess 0 wikiMoveToDriveStatusProcessing 1 wikiMoveToDriveStatusFailure -1任务查询必须使用task_typemove_wiki_to_docs、字段move_wiki_to_docs_result和数值状态不要回退到其他 task type、result 字段或字符串状态。解析器parseWikiMoveToDriveTaskStatus对「缺字段」「status 缺失」「status 为字符串、小数或未知数值」都会直接判定为非法响应——测试TestParseWikiMoveToDriveTaskStatus用null、processing字符串、0.5、2四类反例验证了这种严格性。有限轮询窗口最多轮询 30 次每次间隔 2 秒对应wikiMoveToDrivePollAttempts 30、wikiMoveToDrivePollInterval 2 * time.Second总窗口约 60 秒轮询窗口内成功时返回readytrue并尽可能返回obj_token、obj_type和url仍在处理中时返回readyfalse、timed_outtrue、完整task_id和next_command超时不代表任务失败任务进入失败态时返回结构化错误SubtypeServerError消息形如wiki move-to-drive task %s failed: %s若任务已创建但每次状态查询都失败返回带 hint 的错误并在 hint 中给出续跑查询命令轮询期间的上下文取消如context.Canceled/DeadlineExceeded会被包装为网络层错误SubtypeNetworkTransport/SubtypeNetworkTimeout同样附上续跑 hint避免吞掉取消语义。pollWikiMoveToDriveTask的健壮性由 shortcuts/wiki/wiki_move_to_drive_test.go 中的多个用例保障TestPollWikiMoveToDriveContinuesFromProcessingToSuccessprocessing→success 连续轮询、TestPollWikiMoveToDriveRecoversFromTransientError瞬时网络错误后恢复、TestPollWikiMoveToDriveDoesNotSwallowFinalCancellation保留取消错误、TestRunWikiMoveToDriveFailureIsTypedAPIError失败态返回类型化 API 错误。task_id的处理纪律task_id是服务端签名的 opaque ID可能包含多个连字符必须原样保存不能自行切分、截断或解析。即使任务查询响应省略了task.task_idCLI 也会回退为请求时使用的完整 IDparseWikiMoveToDriveTaskStatus中的回退逻辑确保续跑不丢 ID。典型返回成功{ node_token: wikcnXXX, folder_token: fldcnXXX, task_id: OPAQUE_TASK_ID, ready: true, failed: false, status: 0, status_msg: success, obj_token: doxcnXXX, obj_type: docx, url: https://example.feishu.cn/docx/doxcnXXX }成功时readytrueobj_token/obj_type/url指向移入 Drive 后的新文档资源可直接供下游命令使用。轮询窗口超时{ node_token: wikcnXXX, folder_token: , task_id: OPAQUE_TASK_ID, ready: false, failed: false, status: 1, status_msg: processing, timed_out: true, next_command: lark-cli drive task_result --scenario wiki_move_to_drive --task-id OPAQUE_TASK_ID --as user }超时返回的next_command是带完整续跑上下文的命令直接复制执行即可见下节。超时续跑drive task_result当轮询窗口结束任务仍在处理时使用drive task_result续跑lark-cli drive task_result \ --scenario wiki_move_to_drive \ --task-id COMPLETE_TASK_ID \ --as user身份与 profile 必须保持一致续跑必须保持和初始移动相同的--profile与--as user|bot身份否则可能收到权限错误。shortcut 返回的next_command会保留两者——wikiMoveToDriveTaskResultCommand在构造续跑命令时会读取当前 runtime 的 identity--as与ProfileName--profile并拼入命令测试TestRunWikiMoveToDriveTimeoutReturnsResumeCommand验证了--profile secondary与--as bot都被正确保留。续跑场景的底层映射drive task_result通过--scenario区分不同异步任务wiki_move_to_drive场景对应查询GET /open-apis/wiki/v2/tasks/{task_id}?task_typemove_wiki_to_docs该场景的返回契约见 skills/lark-drive/references/lark-drive-task-result.md{ scenario: wiki_move_to_drive, task_id: OPAQUE_TASK_ID, ready: true, failed: false, status: 0, status_msg: success, obj_token: doxcnXXX, obj_type: docx, url: https://example.feishu.cn/docx/doxcnXXX }字段语义readymove_wiki_to_docs_result.status0时为truefailedstatus0时为truestatus1表示仍在处理status/status_msg协议返回的数值状态与可读消息不要把字符串状态当作成功值解析obj_token/obj_type/url成功后新 Drive 文档的资源信息task_id签名后的 opaque ID可能包含多个连字符服务端响应省略task.task_id时回退为请求中的完整 ID。场景分发逻辑见 shortcuts/drive/drive_task_result.gowiki_move_to_drive是--scenario支持值之一另有import、export、task_check、wiki_move、wiki_delete_space、wiki_delete_node同一 shortcut 统一了所有异步任务的续跑查询接口。--dry-run时该场景展示一步查询请求。权限要求与影响本地 scope 预检查CLI 在发起命令前会做本地 scope 预检查。wiki move-to-drive声明的权限组合为用途scope移动写操作预检查space:document:move任务轮询读操作wiki:space:readShortcut.Scopes是全量必选ALL-required的预检模型若本地 token 已记录 scopes 且缺失任一权限命令会提示重新执行lark-cli auth login --scope ...。测试TestWikiMoveToDriveDeclaredContract对 scopes 与Riskwrite做了契约级断言。实现细节移动端点的权限集合wiki:wiki/wiki:node:move/space:document:move是 OR 语义而 shortcut 的Scopes是全量预检源码注释说明因此取注册表中最高优先级的space:document:move加上任务状态端点所需的wiki:space:read。权限模型变化重要影响调用方必须能移动源 Wiki 节点并能写入目标 Drive 文件夹成功后源节点会从 Wiki 树中消失目标文档改用 Drive 目标位置的权限模型原 Wiki 层级继承权限不再保留省略--folder-token时「根目录」属于当前--as身份user 与 bot 的可见资源范围可能不同bot 只能访问应用自己的资源查用户资源会返回空成功而非报错参见 skills/lark-shared/SKILL.md 的身份准则。高风险写入警示[!CAUTION] 这是会改变文档归属和权限继承的写入操作。执行前必须确认源 Wiki 节点、目标 Drive 位置和调用身份。Risk: write意味着这不是可逆的「挪个位置」移动后文档脱离 Wiki 的层级权限体系改用 Drive 文件夹的权限模型原 Wiki 继承权限随之失效。执行前务必通过wiki node-get确认源节点、通过drive侧命令确认目标文件夹并用--dry-run预览两步请求。dry-run两步请求编排--dry-run会展示完整的底层调用链不发起真实请求参见 skills/lark-shared/SKILL.md 安全规则第 3 条「目标命令支持--dry-run时用--dry-run预览危险请求」POST /open-apis/wiki/v2/nodes/{node_token}/move_wiki_to_docsBody 含可选的folder_token——提交移动任务GET /open-apis/wiki/v2/tasks/:task_id?task_typemove_wiki_to_docs——轮询任务结果。两步编排的 dry-run 实现在buildWikiMoveToDriveDryRun测试TestBuildWikiMoveToDriveDryRun断言了 POST URL、请求体folder_token与 GET 参数task_type均正确。常见问题与排查路径现象排查方向传入的 token 报错 / 移动了错误的文档确认--node-token是 Wiki 节点 tokenwikcn*而非底层obj_tokendoxcn*先用wiki node-get解析轮询超时timed_outtrue不是失败复制输出中的next_command续跑或手动执行drive task_result --scenario wiki_move_to_drive --task-id 完整ID续跑报权限错误检查续跑命令的--profile与--as是否与初始移动完全一致移动成功后找不到文档 / 权限异常移动后文档脱离 Wiki 层级权限改属 Drive 目标文件夹权限模型确认目标文件夹与调用身份user/bot 可见范围不同本地预检提示缺 scope缺失space:document:move或wiki:space:read时按提示重新执行lark-cli auth login --scope ...关联阅读skills/lark-wiki/SKILL.md —— 知识库全部命令与快速决策skills/lark-wiki/references/lark-wiki-move.md —— Wiki 内移动与 Drive 文档迁入 Wikiwiki moveskills/lark-drive/references/lark-drive-task-result.md —— 超时后的任务续跑drive task_result全场景说明skills/lark-shared/SKILL.md —— 认证、身份与全局参数源码移动实现 shortcuts/wiki/wiki_move_to_drive.go、契约测试 shortcuts/wiki/wiki_move_to_drive_test.go、续跑场景 shortcuts/drive/drive_task_result.go【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考