飞书知识库空间盘点：lark-cli 的 wiki +space-list 命令使用与分页机制全解

飞书知识库空间盘点lark-cli 的 wiki space-list 命令使用与分页机制全解【免费下载链接】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 space-list是 Lark/飞书 CLIlark-cli提供的知识库Wiki核心只读命令用于列出调用方当前可访问的所有知识空间Wiki Space并内置了与 CLI 其余 list 类快捷命令一致的单页默认策略与完整的分页游标机制。本文以 lark-wiki-space-list.md 为骨架结合仓库源码wiki_space_list.go与端到端测试wiki_shortcut_workflow_test.go逐项展开读完本文你将掌握该命令的全部参数语义、JSON/pretty 等输出格式、游标续页与--page-all的取舍策略、my_library个人知识库的边界以及如何用返回的space_id衔接node-list/node-copy等下游命令。命令概览一条命令盘点全部知识空间在 lark-wiki 技能包的 Shortcuts 体系中space-list被定义为“List wiki spaces accessible to the caller”列出调用方可访问的知识空间风险等级为read支持user与bot两种身份并声明了最窄权限范围wiki:space:retrieve源码见 wiki_space_list.go。默认行为与 CLI 其他 list 类快捷命令保持一致默认只抓取一页每页最多--page-size条。要遍历全部空间必须显式传入--page-all并受--page-limit默认 10 页上限约束。这一默认策略在源码注释中有明确说明Default fetches a single page (matches other list shortcuts in this CLI)。使用方式与典型场景最简用法单页查看# 默认单页最多 --page-size 条 lark-cli wiki space-list # 显式指定身份为 user知识空间是用户中心资源见下文“身份选择” lark-cli wiki space-list --as user遍历全部空间# 遍历每一页受 --page-limit 上限约束默认 10 页 lark-cli wiki space-list --page-all # 遍历每一页且不设上限空间很多时慎用 lark-cli wiki space-list --page-all --page-limit 0从游标续页# 从指定游标续页无论是否带 --page-all都按单页获取 lark-cli wiki space-list --page-token TOKEN不同输出格式lark-cli wiki space-list --format pretty lark-cli wiki space-list --format table lark-cli wiki space-list --format csv lark-cli wiki space-list --format ndjson参数详解FlagsFlag类型默认值说明--page-sizeint50每页条数取值范围 1–50--page-tokenstring—分页游标一旦指定即视为单页获取不自动翻页--page-allboolfalse自动翻页拉取所有页受--page-limit上限约束--page-limitint10--page-all模式下最多拉取页数0 表示不设上限--formatenumjsonjson/pretty/table/csv/ndjson--asenumauto身份user/bot知识空间是用户中心资源建议显式传--as user源码级佐证这些 flag 的定义与默认值直接声明在 wiki_space_list.go 的common.Shortcut.Flags中其中page-size的默认值来自常量wikiSpaceListDefaultPageSize 50取值范围上限来自wikiSpaceListMaxPageSize 50。校验逻辑非法参数直接拦截命令内置了参数预校验validateWikiListPaginationwiki_space_list.go在任何网络请求发出之前就会拒绝非法输入--page-size必须落在1 ~ 50之间否则报--page-size must be between 1 and 50错误子类型SubtypeInvalidArgument--page-limit必须是非负整数否则报--page-limit must be a non-negative integer。该校验函数同时被space-list与node-list共享注释中明确说明shared by space-list and node-list确保两个 list 命令的分页语义完全一致。输出结构解析默认 JSON 输出采用 CLI 统一的外层信封结构okdatameta{ ok: true, data: { spaces: [ { space_id: 6946843325487912356, name: Engineering Wiki, description: ..., space_type: team, visibility: private, open_sharing: closed } ], has_more: false, page_token: }, meta: { count: 1 } }字段语义字段说明data.spaces[]空间列表每项含space_id、name、description、space_type、visibility、open_sharing六个字段data.has_more上游是否还有更多页data.page_token下一页游标无更多页时为空字符串meta.count本次返回的空间数量稳定信封契约有端到端测试保证在 wiki_shortcut_workflow_test.go 中QA-P1 用例对space-list的输出做了严格断言data.spaces必须始终存在且是数组——即使为空也是[]而不是null源码中fetchWikiSpaces返回的切片始终非 nil注释明确写道The returned slice is always non-nil so json output stays as [] instead of null见 wiki_space_list.godata.has_more与data.page_token必须始终存在绝不省略以便下游 Agent 无论是否触发翻页上限都能据此续页meta.count必须等于len(data.spaces)count 为 0 时该字段被omitempty省略这是信封框架的既有行为测试注释对此有说明。续页信号当默认单页获取或--page-all被--page-limit截断未能耗尽上游游标时返回has_moretrue且page_tokencursor调用方可以用--page-token cursor继续拉取或调大--page-limit重新--page-all。pretty 格式的行为细节--format pretty走独立渲染器renderWikiSpacesPrettywiki_space_list.go有几处值得注意的细节空结果时输出No wiki spaces found.若“当前页为空但服务端报告还有更多页”即has_moretrue且page_token非空会输出Current page is empty but the server reports more pages.并提示使用--page-all或--page-token续页——这是对“这页真没有 vs 还没翻完”两种情况的刻意区分避免调用方在翻页未完时误判为无数据每项按[序号] 名称展示随后缩进列出space_id、space_type、visibility、open_sharing与可选的description缺失字段统一以-占位valueOrDash列表末尾若还有下一页会打印Next page token: cursor。底层实现分页循环如何工作fetchWikiSpaceswiki_space_list.go是命令的核心执行逻辑它把四个分页 flag 组合成三种行为模式默认无--page-all、无--page-token从起点抓取一页即返回--page-token X从游标 X 开始抓取一页自动翻页被禁用--page-all持续抓取后续页面直到has_morefalse、游标耗尽、或达到--page-limit默认 10 页0 表示不设上限。每次请求都打到飞书开放平台GET /open-apis/wiki/v2/spaces常量wikiSpacesAPIPath携带page_size以及需要时的page_token参数通过runtime.CallAPITyped发起。循环结束后返回最后一个页面的has_more/page_token作为信封字段保证调用方总能拿到真实的续页信号。两个防御性设计--page-token优先wikiListShouldAutoPaginatewiki_space_list.go明确规定——只要显式传了--page-token就绝不自动翻页--page-all被忽略。因为调用方已经给出了明确的游标自动翻页反而可能打乱续页语义冲突提示warnIfConflictingPagingFlagswiki_space_list.go在同时传--page-token与--page-all时向 stderr 打印警告--page-token is set, so --page-all is ignored避免调用方误以为两个 flag 会叠加生效。Dry-run 支持DryRun实现wiki_space_list.go会构造出将要发出的 GET 请求含page_size/page_token参数并显式标注“Auto-paginates through all pages (capped by --page-limit when 0)”来提示调用方翻页循环是否会触发——方便在不实际请求的情况下验证分页行为。身份选择为什么建议显式传 --as user知识空间与节点本质上是用户的个人资源。CLI 的--as默认值是auto不带--as时常被解析为bot此时列出的是应用tenant_access_token所属的空间而不是用户的空间。因此 lark-wiki/SKILL.md 的策略明确要求知识库相关操作优先显式使用--as user仅在用户明确要求“应用 / bot 视角”时才用--as bot。这一点同样贯穿到下游node-list的--space-id my_library别名只对--as user有效bot 身份下会被提前拒绝并给出明确提示源码见 wiki_node_list.go。与 my_library 的边界列表 API 永远不返回个人知识库一个容易踩坑的事实底层列表 API 永远不会返回my_library个人知识库。调用方可访问的空间列表里不会有它。需要个人知识库时必须通过 get 类操作显式解析lark-cli wiki spaces get --params {space_id:my_library}该别名在源码中以常量wikiMyLibrarySpaceID my_library定义wiki_node_create.go并通过resolveMyLibrarySpaceIDwiki_node_create.go调用GET /open-apis/wiki/v2/spaces/my_library解析出用户真实的数字space_id供node-create、node-list等接受该别名的快捷命令共享使用——这也是为什么space-list的结果中看不到它它属于用户个人库不属于可枚举的空间集合。下游衔接把 space_id 用起来space-list的输出价值在于产出真实的数字space_id它是后续 Wiki 操作的核心入参# 1. 盘点空间拿到 space_id lark-cli wiki space-list --as user # 2. 列出某空间根节点默认单页 lark-cli wiki node-list --space-id 6946843325487912356 # 3. 把节点复制到目标空间--space-id 指目标空间 lark-cli wiki node-copy --space-id 6946843325487912356 --node-token NODE_TOKEN ...对应关系在文档与源码中都有明确约定space-list的 Notes 部分指出“Usespace_idfrom the output as--space-idfornode-listornode-copy”wiki_node_list.go 的校验逻辑更是硬性要求--space-id必须是数字形式的 wikispace_id——传入 URL、节点 token、文档 token 或标题都会被拒绝并提示先运行lark-cli wiki space-list --as user获取正确的 ID。权限要求调用该命令需要以下权限范围项值Required Scopewiki:space:retrieve源码中对该范围的选择有一处值得注意的设计考量wiki_space_list.go 的注释上游 API 实际接受wiki:wiki/wiki:wiki:readonly/wiki:space:retrieve三种范围中的任意一种但由于框架的 preflight 做的是精确字符串匹配见 internal/auth/scope.go如果声明更宽的只读形式反而会错误拒绝那些只携带窄范围wiki:space:retrieve的 token并给出误导性的“缺权限”提示。因此命令故意声明最窄范围以与真实携带的 token 精确对齐。结语wiki space-list虽然是一条只读的“盘点”命令但它的分页策略、信封契约与身份语义是整个 Wiki 快捷命令体系的样板理解它就等于理解了node-list、member-list等兄弟命令的通用行为模式。实际使用时记住三条核心心法即可默认单页要全量就--page-all并随时用--page-limit或--page-token控制节奏显式--as user因为知识空间是用户中心资源auto常被解析成 bot 而看不到用户的空间space_id是硬通货——从本命令的输出中取数字space_id再喂给node-list/node-copy/node-create不要传 URL 或名称。【免费下载链接】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），仅供参考