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点击查看免费下载本文围绕飞书知识库Wiki的官方 CLI 工具 lark-cli 中wiki node-copy快捷命令展开讲解如何把一个 Wiki 节点及其正文内容复制到目标知识空间或目标父节点下并深入剖析其高危写确认--yes、目标参数互斥校验、锁竞争错误码 131009指数退避重试等源码级实现。读完本文你将掌握该命令的完整参数语义、可复制的实战命令、输出字段含义以及复制与移动wiki move的选型边界。一、命令定位复制什么、不复制什么wiki node-copy是 skills/lark-wiki 技能集中推荐优先使用的 Wiki 快捷命令Shortcut之一。它的语义非常明确复制一个 Wiki 节点并包含该节点的正文内容复制到「目标知识空间」或「目标父节点之下」非递归复制只复制被指定的那一个节点及其内容后代节点descendant nodes不会被复制需要逐个另行复制保留源节点复制不会删除或移动源节点源节点与副本同时存在。这一「仅当前节点、不递归」的语义同时被命令的 Tips 与测试用例双重固定在 shortcuts/wiki/wiki_node_copy.go 的 Tips 中明确写着 “This shortcut copies the current node only; descendant nodes are not copied”而测试TestWikiNodeCopyDeclaresNodeOnlySemantics也断言了这两条提示必须存在见 shortcuts/wiki/wiki_list_copy_test.go。因此若你的目标是复制整棵子树父节点加全部子孙请先列出子树结构再对每个节点逐一执行node-copy若目标是移动而非复制不保留源节点则应改用wiki move详见下文对比。二、高危写操作与--yes确认机制上游复制 API 被标记为danger: true因此node-copy被归类为high-risk-write高危写。在源码 shortcuts/wiki/wiki_node_copy.go 中可以看到var WikiNodeCopy common.Shortcut{ Service: wiki, Command: node-copy, Description: Copy a wiki node to a target space or parent node, Risk: high-risk-write, Scopes: []string{wiki:node:copy}, AuthTypes: []string{user, bot}, HasFormat: true, ... }Risk: high-risk-write意味着必须显式追加--yes才能发出请求。如果遗漏--yesCLI 会返回confirmation_required类型的错误提示语为 “requires confirmation”并附带恢复提示add --yes to confirm底层 API 请求根本不会发出复制操作不会执行。该确认机制在命令框架层实现internal/cmdutil/confirm.go中的RequireConfirmation构造一个携带errs.RiskHighRiskWrite风险级别的ConfirmationRequiredError见 internal/cmdutil/confirm.go。测试TestWikiNodeCopyDeclaredHighRiskWriteshortcuts/wiki/wiki_list_copy_test.go刻意不注册任何 HTTP stub并断言未带--yes时命令必然以confirmation_required失败——若确认门禁失效导致请求外泄httpmock 会以 “no stub” 报错让回归一目了然。这从测试设计上锁死了「无--yes绝不发请求」的契约。三、完整用法与参数详解基本命令lark-cli wiki node-copy \ --space-id source_space_id \ --node-token source_node_token \ (--target-space-id target_space_id | --target-parent-node-token token) \ [--title new_title] \ --yes \ [--as user|bot]参数表Flag必填说明--space-id是源知识空间 IDWiki 空间 ID 为数字字符串可通过wiki space-list获取--node-token是待复制的源节点 token--target-space-id条件必填目标知识空间 ID当未提供--target-parent-node-token时必须提供--target-parent-node-token条件必填目标父节点 token当未提供--target-space-id时必须提供--title否复制后节点的新标题省略则沿用原标题--yes是确认高危写操作缺少该标志命令拒绝发送 API 请求--format否输出格式json默认/pretty/table/csv/ndjson--as否身份user/bot默认auto知识库以用户为中心建议显式传--as user硬性约束--target-space-id与--target-parent-node-token必须且只能提供其中一个二者不可同时为空也不可同时给出详见下一节。三个典型场景场景一复制到另一个知识空间的根目录lark-cli wiki node-copy \ --space-id 7211568716812369922 \ --node-token wikcn_SOURCE_TOKEN \ --target-space-id 7352712345678901234 \ --yes \ --as user场景二复制到同/异空间下某个父节点内并重命名副本lark-cli wiki node-copy \ --space-id 7211568716812369922 \ --node-token wikcn_SOURCE_TOKEN \ --target-parent-node-token wikcn_PARENT_TOKEN \ --title Getting Started (Copy) \ --yes \ --as user场景三先预览将要发出的请求dry-runShortcut 实现了 DryRun 预览逻辑common.NewDryRunAPI会展示待发送的POST /open-apis/wiki/v2/spaces/{space_id}/nodes/{node_token}/copy请求及其请求体适合在真正执行前核对目标与标题参数。四、目标校验二选一且互斥--target-space-id与--target-parent-node-token的约束在命令的Validate钩子中实现shortcuts/wiki/wiki_node_copy.go共三条规则至少提供一个目标参数两者均为空时返回ValidationErrorinvalid_argument并同时指出两个参数 “provide --target-space-id or --target-parent-node-token”两者互斥同时给出时同样返回校验错误提示 “mutually exclusive; provide only one”——这一设计也保证了请求体永远不会出现歧义的「双目标」形态参数格式校验space-id、node-token、两个目标参数都会经过资源名格式校验validateOptionalResourceName防止把 URL、路径或不合法字符直接塞进 token 字段。对应的测试TestWikiNodeCopyRequiresTargetSpaceOrParent与TestWikiNodeCopyRejectsBothTargetFlagsshortcuts/wiki/wiki_list_copy_test.go分别验证了这两种失败路径并断言错误中同时携带了两个问题参数的定位信息。五、底层 API 与请求体构造node-copy最终调用的是飞书开放平台 Wiki v2 的复制接口POST /open-apis/wiki/v2/spaces/{space_id}/nodes/{node_token}/copy其中{space_id}对应--space-id{node_token}对应--node-token均经过validate.EncodePathSegment进行路径段编码。请求体由buildNodeCopyBody构造shortcuts/wiki/wiki_node_copy.go--target-space-id非空 → 写入target_space_id--target-parent-node-token非空 → 写入target_parent_token--title非空 → 写入title省略时整个title字段不进入请求体服务端会沿用原标题。这条字段映射被测试TestWikiNodeCopyCopiesNodeToTargetSpace和TestWikiNodeCopyCopiesNodeToTargetParentshortcuts/wiki/wiki_list_copy_test.go通过捕获请求体CapturedBody逐一验证复制到空间时请求体含target_space_id与title复制到父节点时请求体含target_parent_token且未提供--title时请求体中不存在title字段。六、输出字段解读命令执行成功后默认输出 JSON完整示例如下{ space_id: target_space_id, node_token: wikcn_EXAMPLE_TOKEN, obj_token: doccn_EXAMPLE_TOKEN, obj_type: docx, node_type: origin, title: Getting Started (Copy), parent_node_token: , has_child: false }各字段含义字段说明space_id副本所在的知识空间 IDnode_token副本的 Wiki 节点 tokenwikcn...前缀obj_token副本对应的底层文档对象 token如doccn...obj_type底层对象类型如docx/sheet/bitable/slides/file等node_type节点类型常见为origin原始节点副本对应快捷方式时为shortcuttitle副本标题未指定--title时沿用原标题parent_node_token副本的父节点 token复制到空间根目录时为空字符串has_child副本是否含子节点复制本身非递归通常为false除此之外源码在输出时还会尝试补充url字段shortcuts/wiki/wiki_node_copy.go优先取上游响应中携带的真实url缺失时回退为按品牌brand合成的资源链接见wikiNodeURL实现 shortcuts/wiki/wiki_helpers.go。该行为同样有测试断言TestWikiNodeCopyCopiesNodeToTargetSpace中校验url必须取响应中的真实链接。使用--format pretty时命令会以可读的多行形式渲染title、node_token、space_id、obj_type、obj_token并在有值时追加parent_node_token与urlshortcuts/wiki/wiki_node_copy.go。七、锁竞争131009自动重试指数退避实现Wiki 服务在并发写入同一目标父节点时可能返回131009 lock contentioninternal/output/lark_errors.go中常量LarkErrWikiLockContention 131009见 internal/output/lark_errors.go。node-copy对这一错误做了有界指数退避自动重试实现在runWikiNodeCopyWithRetryshortcuts/wiki/wiki_node_copy.go常量wikiNodeCopyMaxRetries 2、wikiNodeCopyRetryBaseDelay 250 * time.Millisecond退避策略第 n 次重试前等待baseDelay (n-1)即250ms → 500ms共 3 次尝试1 次初始 2 次重试只对锁竞争重试isWikiNodeLockContention判断为 131009 时才进入下一次尝试其余错误如权限类、参数类立即返回、不重试重试窗口内若上下文被取消Ctrl-C 或超时返回带network_transport/network_timeout分类的上下文错误并保留原始 cause重试耗尽后仍失败时会为原始错误追加提示wiki node copy failed after 2 retries due to lock contention; try again later or reduce concurrent writes under the same target parent见wrapWikiNodeCopyRetryError。相关测试覆盖了全部关键路径shortcuts/wiki/wiki_list_copy_test.goTestRunWikiNodeCopyRetriesLockContentionThenSucceeds第一次 131009、第二次成功断言恰好调用 2 次TestRunWikiNodeCopyDoesNotRetryOtherErrors权限错误不重试且错误分类与 cause 被完整保留TestRunWikiNodeCopyBackoffCancellationPreservesErrorContract退避期间取消 / 超时的错误契约TestRunWikiNodeCopyRetryExhaustionPreservesErrorContract重试耗尽后仍保留 131009 的retryable属性并追加重试耗尽提示。实操建议若连续重试后仍遇 131009请先等待片刻再重试并避免在同一目标父节点下并发执行多个复制/写入操作。八、权限与身份必需 Scopewiki:node:copy。框架的 preflight 会对 scope 做精确匹配相关测试TestWikiListShortcutsDeclareNarrowScopes论证了窄 scope 的必要性因此授权时应确保应用/用户具备该精确 scope。身份选择命令支持--as user与--as bot。但知识空间与节点本质是用户个人资源--as默认值为auto不带时常常被解析成bot列出/操作的是应用所属空间而非用户的。策略上应显式使用--as user仅当用户明确要求「应用 / bot 视角」时才用--as bot依据 skills/lark-wiki/SKILL.md 的「身份选择优先使用 user 身份」一节。权限错误提示若遇到 Wiki 服务返回的 131006空间/节点 ACL 拒绝命令层会给出稳定的恢复提示这是资源访问权限问题而非应用 scope 授权问题不应重试同一请求或反复切换身份试错应向资源所有者 / 知识库管理员申请读权限见wikiPermissionDeniedHintshortcuts/wiki/wiki_helpers.go。九、实战流程复制前先用wiki node-get确认复制属于写操作且源与目标涉及两处资源推荐在执行前先做一次「我要动什么」的确认解析并确认源节点wiki node-get支持直接传入 wiki URL / node_token / obj_token通过node_by_token解析出space_id、obj_type、parent_node_token、has_child等关键信息实现见 shortcuts/wiki/wiki_node_get.go。它被设计为move/node-copy/delete-space之前的核对步骤。确认目标空间或父节点用wiki space-list --as user拿目标数字space_id若目标是某父节点用wiki node-list --space-id space_id找到对应node_token不要把 wiki URL、doc token 直接当--space-id/--target-parent-node-token使用。执行复制并带上--yes。核对输出重点检查返回的space_id/parent_node_token是否符合预期必要时用wiki node-get回读副本确认。十、与wiki move的选型对比维度wiki node-copywiki move语义复制节点及内容保留源节点移动节点源不保留目标表达--target-space-id或--target-parent-node-token二选一互斥支持--target-parent-token、--target-space-id另有 Drive 文档迁入知识库的docs_to_wiki模式--obj-type--obj-token递归非递归仅当前节点单节点移动风险等级high-risk-write需--yeswrite所需 Scopewiki:node:copywiki:node:move、wiki:node:read、wiki:space:read适用场景模板复用、归档副本、跨空间克隆整理/迁移节点位置、Drive 文档入知识库原文档明确建议要移动已有 Wiki 节点且不保留源时用wiki move而不是「复制再删除」。move的完整说明见 skills/lark-wiki/references/lark-wiki-move.md其实现位于 shortcuts/wiki/wiki_move.go。十一、常见错误与排障速查现象原因处理方式confirmation_required提示requires confirmation未带--yes追加--yes后重发高危写确认是刻意设计勿去掉该保护invalid_argument--target-space-id/--target-parent-node-token均为空未提供任何目标参数提供两者之一invalid_argument两者互斥同时提供了两个目标参数只保留一个目标参数错误码 131009lock contention且重试后仍失败同一目标父节点下并发写入冲突稍等再试避免同目标并发写错误码 131006permission denied对源/目标空间或节点无资源访问权限不重试、不切换身份试错向知识库管理员申请资源读权限复制后副本无子节点复制本身非递归对需要的每个后代节点分别执行node-copy十二、相关资源本命令参考文档skills/lark-wiki/references/lark-wiki-node-copy.md技能总览与身份/成员约束skills/lark-wiki/SKILL.md命令实现shortcuts/wiki/wiki_node_copy.go测试用例确认门禁、目标校验、重试、请求体断言shortcuts/wiki/wiki_list_copy_test.go节点解析与复制前核对shortcuts/wiki/wiki_node_get.go移动命令对比shortcuts/wiki/wiki_move.go、skills/lark-wiki/references/lark-wiki-move.md高危写确认机制internal/cmdutil/confirm.go锁竞争错误码定义internal/output/lark_errors.go赞分享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 CLI 知识库Wiki端到端测试 100% 覆盖解析节点工作流与 space-list / node-list / node-copy 快捷命令验证Lark CLI 知识库Wiki端到端测试 100% 覆盖解析节点工作流与 space list / node list / node copy 快CLIAI 技能Lark CLI 知识整理工作流 Rollback云盘/知识库移动失败后的安全恢复与清理机制Lark CLI 知识整理工作流 Rollback云盘/知识库移动失败后的安全恢复与清理机制 导读 knowledge_organize 知识整理是 LaCLIAI 技能飞书云空间文件复制实战lark-cli drive copy 完全指南飞书云空间文件复制实战lark cli drive copy 完全指南 本指南以官方 CLI 工具 lark cli 的 drive copy 快捷命令为CLIAI 技能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
