lark-cli 飞书知识库 node-create 命令实战自动空间解析的知识库节点创建指南【免费下载链接】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 node-createshortcut 展开它是飞书知识库Wiki中创建节点的推荐入口——相比原生wiki.nodes.create它支持从父节点或个人知识库自动解析目标空间、内置参数组合校验与 bot 自动授权。读完本文你将掌握该命令的全部参数语义、空间解析优先级、节点/对象类型组合约束、返回值契约与错误处理策略并了解其底层 OpenAPI 调用链与源码实现。一、命令定位为什么要用 shortcut 而不是原生 APIwiki node-create是 lark-cli 对原生wiki.nodes.create封装出的 shortcut高级命令定义在 shortcuts/wiki/wiki_node_create.go。从源码看它的核心定位是自动解析目标知识空间// shortcuts/wiki/wiki_node_create.go var WikiNodeCreate common.Shortcut{ Service: wiki, Command: node-create, Description: Create a wiki node with automatic space resolution, Risk: write, Scopes: []string{wiki:node:create, wiki:node:read, wiki:space:read}, AuthTypes: []string{user, bot}, ... }该 shortcut 声明需要三个 scopewiki:node:create、wiki:node:read、wiki:space:read同时支持user与bot两种身份风险等级为write写入操作。相比原生 API 必须手动解析空间 IDshortcut 提供了三层便利可直接指定space_id也可以只给父节点由命令自动反查所属空间user身份下如果--space-id与--parent-node-token都省略会自动回退到个人知识库my_library内置参数组合校验从源头拦截shortcut 缺--origin-node-token实体节点配file对象等非法组合避免把错误抛给上游 API。二、快速上手七个典型用法# 1. 在个人知识库根目录下创建一个 docx 节点user 身份默认回退到 my_library lark-cli wiki node-create \ --title 项目计划 # 2. 在指定知识空间中创建一个 docx 节点 lark-cli wiki node-create \ --space-id SPACE_ID \ --title 项目计划 # 3. 在指定父节点下创建一个子节点 lark-cli wiki node-create \ --parent-node-token PARENT_NODE_TOKEN \ --title 迭代记录 # 4. 显式指定创建到个人知识库仅 user 身份bot 不支持 --space-id my_library lark-cli wiki node-create \ --space-id my_library \ --title 学习笔记 # 5. 创建一个快捷方式节点shortcut lark-cli wiki node-create \ --parent-node-token PARENT_NODE_TOKEN \ --node-type shortcut \ --origin-node-token ORIGIN_NODE_TOKEN \ --title 原文档快捷方式 # 6. 创建非 docx 类型节点例如多维表格/电子表格 lark-cli wiki node-create \ --space-id SPACE_ID \ --obj-type sheet \ --title 周报数据 # 7. 预览底层调用链推荐写入前先执行 lark-cli wiki node-create \ --title Roadmap \ --dry-run[!CAUTION]wiki node-create是写入操作执行前必须确认用户意图建议先用--dry-run预览将触发的调用链。三、参数详解语义、默认值与组合约束参数必填说明--space-id否目标知识空间 IDuser身份可传特殊值my_library表示个人知识库bot身份不支持该值--parent-node-token否父知识库节点 token 或文档 obj_token在解析出的 Wiki 节点下创建新节点--title否节点标题--node-type否节点类型默认origin可选值origin、shortcut--obj-type否节点对应对象类型默认docx可选值sheet、mindnote、bitable、file、docx、slides。file仅支持shortcut节点--origin-node-token否当--node-typeshortcut时必填表示快捷方式指向的源节点 token源码视角的补充说明参数读取在 wiki_node_create.go 的readWikiNodeCreateSpec中完成所有字符串参数都会被TrimSpacenode-type与obj-type额外做ToLower归一化因此大小写混写也能正确匹配枚举。--obj-type的合法枚举在源码中定义为wikiObjectTypes [sheet, mindnote, bitable, file, docx, slides]见 wiki_node_create.go与文档一致。校验逻辑validateWikiNodeCreateSpecwiki_node_create.go除了检查参数格式外还内置了三条组合规则--node-typeshortcut但未传--origin-node-token→ 报错提示必须提供源节点 token--node-typeorigin却传了--origin-node-token→ 报错该参数仅用于快捷方式节点--node-typeorigin搭配--obj-typefile→ 报错file对象类型仅支持 shortcut 节点并给出恢复提示use --node-type shortcut --obj-type file --origin-node-token TOKEN。校验失败的报错会携带结构化的Params标注具体是哪个 flag 的问题与恢复 HintAgent 或脚本可以直接依据这些字段修正参数无需解析散文式报错文案。四、空间解析规则三条路径与优先级命令的空间解析严格遵循如下优先级源码见resolveWikiNodeCreateSpacewiki_node_create.go优先级--space-id--parent-node-tokenmy_library场景解析行为显式传--space-id直接使用该空间若值为my_library则仅user身份可用并先调用GET /open-apis/wiki/v2/spaces/my_library解析成真实space_id未传--space-id但传--parent-node-token先调用GET /open-apis/wiki/v2/spaces/node_by_token获取父节点再读取其space_iduser身份且两者都未传自动解析my_library个人知识库bot身份且两者都未传直接校验失败——bot 没有个人知识库回退语义必须显式提供--space-id或--parent-node-token父节点类型的兼容性--parent-node-token接受 Wikinode_token或已挂载到 Wiki 的文档obj_token创建时统一使用查询返回的node_token。显式传空间时也会查询父节点并校验父节点所属空间。bot 身份限制bot身份既没有个人知识库回退语义也不支持显式传--space-id my_library请改用真实space_id或--parent-node-token。这条限制在参数校验阶段而非 API 调用阶段就被拦截wiki_node_create.go报错会同时标注--space-id与--parent-node-token两个参数提示 bot 身份必须提供其一。上述三种解析路径在 wiki_node_create_test.go 中均有对应测试覆盖例如TestResolveWikiNodeCreateSpaceUsesParentNode、TestResolveWikiNodeCreateSpaceUsesMyLibraryFallback、TestResolveWikiNodeCreateSpaceRejectsBotWithoutLocation验证了优先级与身份限制的正确性。五、节点类型与对象类型组合矩阵与约束创建请求体中的node_type与obj_type存在强约束关系node_type支持的obj_typeoriginsheet、mindnote、bitable、docx、slidesshortcutsheet、mindnote、bitable、file、docx、slides要点--node-typeshortcut时必须同时提供--origin-node-token--node-typeorigin时不能传--origin-node-token--obj-typefile仅支持--node-typeshortcut实体节点不支持创建file类型shortcut节点只是知识库中的快捷方式入口真正被引用的节点由--origin-node-token指定如果node-create因上述组合返回参数校验错误禁止改用 rawwiki nodes create或直接调用 OpenAPI 绕过校验应修正node_type、obj_type或origin_node_token。指向文件的快捷方式节点示例lark-cli wiki node-create \ --space-id SPACE_ID \ --node-type shortcut \ --obj-type file \ --origin-node-token ORIGIN_NODE_TOKEN请求体的构造见wikiNodeCreateSpec.RequestBodywiki_node_create.go只有node_type与obj_type始终写入title、parent_node_token、origin_node_token仅在非空时写入。六、一致性校验空间与父节点必须匹配如果同时传了--space-id和--parent-node-token命令会校验父节点所属空间是否与--space-id一致wiki_node_create.go两者解析出的空间不一致时直接返回验证错误--space-id %q does not match parent node space %q不会继续创建对于my_libraryuser身份下也会先解析出真实space_id后再做这层校验。对应的测试为TestResolveWikiNodeCreateSpaceRejectsSpaceMismatch用space_other与父节点所在space_parent的不匹配场景验证了该拦截逻辑。七、返回值输出契约详解成功后会返回一个 JSON 对象常见字段包括字段含义resolved_space_id最终用于创建的真实知识空间 IDresolved_by空间解析来源取值explicit_space_id/parent_node_token/my_librarynode_token新建知识库节点 tokenobj_token节点关联对象 tokenobj_type节点关联对象类型node_type节点类型title节点标题permission_grant可选仅--as bot时返回说明是否已自动为当前 CLI 用户授予可管理权限从源码wikiNodeCreateOutputwiki_node_create.go看完整输出还包括space_id、parent_node_token、origin_node_token、has_child等字段便于 Agent 在创建后继续编排如移动到子节点、复制、授权等。此外augmentWikiNodeCreateOutput还会在可能时追加url字段优先使用 OpenAPI 响应中返回的真实链接缺失时按品牌域名用node_token合成见 wiki_helpers.go。[!IMPORTANT] 如果节点是以应用身份bot创建的如lark-cli wiki node-create --as bot创建成功后 CLI 会尝试为当前 CLI 用户自动授予该知识库节点的full_access可管理权限。以应用身份创建时结果里会额外返回permission_grant字段明确说明授权结果status granted当前 CLI 用户已获得该知识库节点的可管理权限status skipped本地没有可用的当前用户open_id因此不会自动授权可提示用户先完成lark-cli auth login再让 AI / agent 继续使用应用身份bot授予当前用户权限status failed节点已创建成功但自动授权用户失败会带上失败原因并提示稍后重试或继续使用 bot 身份处理该节点。permission_grant.perm full_access表示该资源已授予可管理权限。不要擅自执行 owner 转移。如果用户需要把 owner 转给自己必须单独确认。自动授权的底层实现走POST /open-apis/drive/v1/permissions/{token}/members请求体为member_typeopenid、member_id当前用户 open_id、permfull_access、typeuser、perm_typecontainer——这一请求结构在测试TestWikiNodeCreateBotAutoGrantSuccesswiki_node_create_test.go中被断言验证granted/skipped/failed三种状态也分别有对应测试覆盖。八、dry-run 编排预览调用链--dry-run会按输入参数展示实际将触发的 OpenAPI 调用链源码见buildWikiNodeCreateDryRunwiki_node_create.go仅传--title展示my_library解析 创建节点两步调用仅传--parent-node-token展示查询父节点 - 创建节点两步调用同时需要my_library和父节点如--space-id my_library --parent-node-token ...展示三步调用链解析 my_library → 解析父节点 → 创建节点显式传真实--space-id且无父节点展示单步创建请求。dry-run 输出中真实空间 ID 会原样展示需要运行时解析的占位符会以resolved_space_id、resolved_parent_node_token形式呈现。dry-run 编排与文档描述一致且由TestWikiNodeCreateDryRunShowsMyLibraryLookup等一组测试逐条断言了不同参数组合下的步骤数与 URL见 wiki_node_create_test.go。九、错误处理可重试与不可重试的边界node-create对两类典型错误做了差异化处理1. 结构限制错误码131003——不可重试返回131003表示触发了知识空间总节点数、目录深度或单个父节点直属子节点数等结构限制。这不是瞬时错误禁止使用相同参数重试。正确做法是根据上游错误信息选择更浅或其他父节点、重新组织现有节点或清理/改用其他知识空间不要在无法确认具体限制时盲目增加中间层级。源码中该限制被显式标记为Retryable false并追加恢复 Hint见 wiki_node_create.go测试TestRunWikiNodeCreateClassifiesStructuralLimitAsNonRetryable验证了即使上游标记可重试也会被强制改为不可重试的行为。2. 写锁竞争错误码131009——带退避自动重试当多个并发创建同时命中同一父节点时API 可能返回写锁竞争错误code131009。命令会以指数退避自动重试初始延迟 250ms之后翻倍250ms、500ms最多重试 2 次总计最多 3 次请求见 wiki_node_create.go。重试耗尽后错误 hint 会说明try again later or reduce concurrent node creations under the same parent。除锁竞争外的其他错误如限流rate_limit不会触发此重试路径。十、推荐场景用户说在我的知识库里新建一篇页面时优先用lark-cli wiki node-create --title ...用户已经给出父页面链接或parent_node_token时优先传--parent-node-token让 shortcut 自动推导空间需要创建知识库快捷方式时使用--node-type shortcut --origin-node-token token需要把已有 Wiki 节点移出知识库、移动到 Drive 时请改用wiki move-to-drive批量整理知识库结构请遵循 lark-wiki SKILL 的快速决策 中的工作流指引。[!IMPORTANT] 前置条件先阅读 lark-shared/SKILL.md 了解认证、全局参数和安全规则——包括--as user/--as bot身份语义、写入操作前的用户确认要求、--dry-run预览约定以及退出码 10 高风险确认门禁的处理方式。参考lark-wiki/SKILL.md —— 知识库全部命令与 shortcut 总览shortcuts/wiki/wiki_node_create.go ——node-create核心实现参数校验、空间解析、重试、输出构造shortcuts/wiki/wiki_node_create_test.go —— 覆盖校验、解析、dry-run、自动授权、重试等场景的测试shortcuts/wiki/wiki_helpers.go —— 节点 URL 合成与通用错误提示lark-shared/SKILL.md —— 认证和全局参数【免费下载链接】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），仅供参考
