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点击查看免费下载drive list-comments是 larksuite/cli 官方飞书 CLI 中用于分页列出云空间Drive评论的快捷命令shortcut覆盖 doc/docx/sheet/file/slides/base(bitable)/apps 等多类资源并自动处理 URL 解析与 wiki 解包。本文以官方文档 skills/lark-drive/references/lark-drive-list-comments.md 为骨架结合 shortcuts/drive/drive_list_comments.go 等仓库源码完整讲解该命令的参数语义、默认口径、评论卡片模型、统计与排序规则帮助你或 AI Agent在评论查询场景中一次性拿到正确且可复用的结果。前置条件与快速上手在使用任何drive verb快捷命令之前请先阅读 skills/lark-shared/SKILL.md其中包含认证、全局参数和权限处理的完整约定。从源码看list-comments声明了只读风险等级Risk: read需要的权限 scope 是docs:document.comment:read并在输入为 wiki 时按需使用wiki:node:retrieve身份上同时支持user与bot两种类型见 shortcuts/drive/drive_list_comments.go。最基本的两条命令如下# 推荐直接传用户给出的完整 URL。默认只查未解决评论。 lark-cli drive list-comments --url DOCUMENT_URL # 只有用户明确要求包含已解决评论时才传 --solved-status all。 lark-cli drive list-comments --url DOCUMENT_URL --solved-status all官方推荐“优先传用户给出的完整 URL”因为 shortcut 会根据 URL 路径自动识别资源类型apps妙搭类型支持/page/token形态的 URL如果传入的是 wiki URL 或--token wiki_token --type wikishortcut 会先解析到真实文档再查询评论列表。参数详解下表完整列出list-comments的全部参数与官方文档一致并补充了源码中的默认值与校验范围参数必填说明--url与--token二选一推荐入口。支持 doc/docx/sheet/file/slides/base/bitable/apps/wiki URLapps 妙搭 URL 使用/page/tokenwiki URL 会自动解析到真实文档。--token与--url二选一裸 token 或 URL。裸 token 必须搭配--typewiki token 使用--type wiki。--type裸 token 时必填传 token 对应类型doc、docx、sheet、file、slides、bitable、base、apps、wiki。wiki token 使用wiki传base时CLI 会按bitable类型处理。--solved-status否false/true/all默认false。false查未解决评论true查已解决评论all查全部评论。--comment-scope否all/whole/partial默认all。all查全部范围whole查全文评论partial查局部评论。--need-reaction否是否返回评论卡片上的 reaction 数据只有用户明确需要 reaction 时才带。--need-relation否docx 评论定位关系字段仅 docx 生效非 docx 静默忽略。需要定位正文时先读 skills/lark-drive/references/lark-drive-comment-location.md。--page-size否默认 50最大 100。--page-token否分页游标本 shortcut 不自动翻页按返回的page_token继续请求下一页。以上默认值与取值约束在源码中有明确对应driveListCommentsDefaultPageSize 50、driveListCommentsDefaultSolvedStatus false、driveListCommentsDefaultScope all且--page-size必须在 1~100 之间--page-size must be between 1 and 100--solved-status仅接受false/true/all--comment-scope仅接受all/whole/partial越界都会返回ValidationError见 shortcuts/drive/drive_list_comments.go 与 shortcuts/drive/drive_list_comments.go。参数到底如何映射到 OpenAPI 请求--solved-status与--comment-scope会被翻译成底层 Drive 评论接口的布尔参数而不是原样透传--solved-status false→is_solvedfalse默认true→is_solvedtrueall→不携带is_solved无过滤--comment-scope all→不携带is_whole无过滤whole→is_wholetrue全文评论partial→is_wholefalse局部/选区评论--need-reaction true→need_reactiontrue--need-relation true且目标是docx时才追加need_relationtrue非 docx 目标静默忽略见 shortcuts/drive/drive_list_comments.go 的buildDriveListCommentsParams。这一点有单测直接验证默认参数必须显式携带is_solvedfalse但省略is_whole与user_id_type--solved-status all时省略is_solved--comment-scope partial时携带is_wholefalseneed_relation只在docx目标上出现见 shortcuts/drive/drive_list_comments_test.go。输入解析规则--url/--token/--type的组合语义resolveDriveListCommentsInputshortcuts/drive/drive_list_comments.go定义了输入解析的完整规则理解它就能避免大多数“参数报错”--url与--token互斥同时传会报--url and --token are mutually exclusive两者都不传会报specify --url or --token。URL 自动识别类型--url或--token传入完整 URL 时走common.ParseResourceURL解析路径中的类型与 token/wiki/路径解析为wiki类型。妙搭 apps URLhttps://domain/page/token形态的 URL 由parseDriveListCommentsAppsURL专门识别shortcuts/drive/drive_list_comments.go识别为apps类型非/page/路径如/app/token会报错提示应使用 Miaoda/page/tokenURL。裸 token 必须搭配--type未包含://的裸 token 若不提供--type报--type is required when --url/--token is a bare token裸 token 中若残留/?#等字符也会被拒绝。--type与 URL 类型冲突报错如果 URL 路径类型与显式--type不一致例如 wiki URL 配--type docxshortcut 返回 validation error官方建议直接移除--type。base归一化为bitablenormalizeDriveListCommentsType会把base映射为bitable因此传--type base与传--type bitable等价folder等不支持的--type会被拒绝。这些边界在单元测试中有系统覆盖包括“URL 带 query 参数也能正确解析 token”“--token同样接受完整 URL 与妙搭 URL”“URL 与 token 互斥”“裸 token 缺 type”“类型冲突”等 13 组用例见 shortcuts/drive/drive_list_comments_test.go。行为说明URL 原样传递当用户已经给出完整 URL 时原样传给--url不要先提取 token 再重组成其他类型 URL。比如 sheet 保留/sheets/tokenwiki 保留/wiki/token妙搭 apps 保留/page/token。URL 输入时不需要传--type如果 URL 类型和显式--type冲突shortcut 会返回 validation error建议移除--type。wiki 输入会自动解析到真实文档再查询评论列表。JSON 输出不额外返回 wiki token 或 wiki node。Wiki 自动解包两步编排与错误码当目标是 wiki 节点时list-comments实际是两步编排先调用GET /open-apis/wiki/v2/spaces/node_by_token?tokenwiki_token解包取响应中node.obj_type与node.obj_token再对真实文档调用GET /open-apis/drive/v1/files/obj_token/comments见 shortcuts/drive/drive_list_comments.go 的resolveDriveListCommentsTarget。解包结果如果是 wiki 自身obj_typewiki或不受支持的类型如folder会报 validation error 并注明该命令只支持 doc、docx、sheet、file、slides、bitable、apps。Wiki 解包请求的典型错误码映射如下源码中直接处理见 shortcuts/drive/drive_list_comments.go错误码语义映射131012节点不存在not found不可重试131013/131016参数无效131014前置条件不满足dry-run 模式会如实展示这两步请求第一步wiki/v2/spaces/node_by_token第二步以obj_token from step 1为占位的评论列表请求need_relation也以“仅当 obj_type 为 docx 时才发送”的占位形式出现。对应的 e2e 测试在 tests/cli_e2e/drive/drive_list_comments_dryrun_test.go其中还验证了--solved-status all时第二步不携带is_solved。重要默认口径默认只查未解决评论即不额外传--solved-status或显式传--solved-status false。即使用户说“所有评论”“全部评论”“把评论都列出来”只要没有明确提到包含已解决评论仍然按默认口径查询未解决评论。仅当用户明确要求“包含已解决评论”“已解决和未解决都要”“全部历史评论”这类语义时才传--solved-status all。是否还有下一页以输出里的has_more为准page_token只作为has_moretrue时续跑下一页的游标。输出结构list-comments的输出是结构化的 JSON官方文档给出了骨架{ file_token: docx_token, file_type: docx, items: [], has_more: false, page_token: , count: 0 }字段语义items保留评论卡片字段外层补充file_token已解析的真实文件 token、file_type已解析的真实类型、has_more是否还有下一页评论卡片、page_token续跑游标、count当前页返回的评论卡片数。是否继续分页以has_more为准而不是只看page_token是否存在。两个实现细节值得注意items始终是 JSON 数组服务端若省略或返回 nulldriveCommentItems会归一化为[]避免 jq 等消费方对null迭代报错见 shortcuts/drive/drive_comment_common.go对应单测TestDriveListCommentsOmittedItemsNormalizedshortcuts/drive/drive_list_comments_test.go。count由本地计算即len(items)等于当前页评论卡片数见 shortcuts/drive/drive_list_comments.go。评论卡片模型返回的items是评论卡片列表每个item对应用户界面中的一张评论卡片不是平铺的互动消息列表。创建评论时会同时创建该卡片里的第一条 reply真正承载正文的是item.reply_list.replies其中第一条 reply根回复在用户视角下就是这张卡片里的“评论本身”。更新根回复即改写评论正文见 skills/lark-drive/references/lark-drive-update-reply.md删除按 reply 逐条生效卡片在最后一条回复被删时才消失见 skills/lark-drive/references/lark-drive-delete-reply.md。item.has_moretrue表示该评论卡片下还有回复未包含在本次返回中这与外层has_more是否还有下一页评论卡片是两个不同字段。需要完整回复时继续用drive list-replies --comment-id id分页拉全见 skills/lark-drive/references/lark-drive-list-replies.md。统计口径当需要向用户汇报数量时请严格按下述口径计算避免把“评论数”和“回复数”混为一谈统计“评论数”或“评论卡片数”统计items长度全量统计时对所有分页返回的items长度累加。统计“回复数”统计所有item.reply_list.replies长度之和再减去items长度即去掉每张卡片的根回复。统计“总互动数”统计所有item.reply_list.replies长度之和包含每张评论卡片里的首条评论。任一item.has_moretrue时先用drive list-replies --comment-id id把该卡片的回复拉全再做回复数或总互动数统计否则会少算。排序规则只有当用户明确提到“最新评论”“最后评论”“最早评论”时才需要按create_time排序。排序前必须拉完所有评论分页不能只取第一页。“最新评论”/“最后评论”按create_time降序取第一条。“最早评论”按create_time升序取第一条。用户只说“第一条评论”时直接使用返回的第一条不需要额外排序。源码视角命令如何被注册与执行list-comments是 drive 评论家族中的一个 shortcut在 shortcuts/drive/shortcuts.go 的Shortcuts()列表中注册DriveListComments与add-comment、batch-query-comments、resolve-comment、restore-comment、add-reply、list-replies、update-reply、delete-reply、react-reply构成完整的评论操作闭环。其执行流程为解析输入readDriveListCommentsSpec→ 校验validateDriveListCommentsSpec→ 解析目标resolveDriveListCommentsTargetwiki 解包→ 拼装参数buildDriveListCommentsParams→ 调用GET /open-apis/drive/v1/files/{file_token}/comments→ 输出结果见 shortcuts/drive/drive_list_comments.go。在 skills/lark-drive/SKILL.md 的 Shortcuts 表中list-comments的定位是“分页获取评论列表”与其配套的评论类命令都有各自独立的 reference 文档执行前先阅读对应 ref 是官方推荐做法。延伸阅读skills/lark-drive/SKILL.md — 云空间云盘/云存储全部命令与快速决策规则skills/lark-drive/references/lark-drive-list-replies.md — 拉全某张卡片下的回复统计与item.has_more补全skills/lark-drive/references/lark-drive-comment-location.md — 使用need_relation定位 docx 正文skills/lark-drive/references/lark-drive-update-reply.md — 更新回复改写评论正文shortcuts/drive/drive_list_comments.go — 命令核心实现shortcuts/drive/drive_list_comments_test.go — 输入解析、参数映射与执行链路的单元测试tests/cli_e2e/drive/drive_list_comments_dryrun_test.go — dry-run 模式的 e2e 验证赞分享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 drive copy 完全指南飞书云空间文件复制实战lark cli drive copy 完全指南 本指南以官方 CLI 工具 lark cli 的 drive copy 快捷命令为CLIAI 技能Lark CLI drive files list 实战指南用原生 API 精确盘点飞书云空间文件夹树Lark CLI drive files list 实战指南用原生 API 精确盘点飞书云空间文件夹树 drive files list 是 Lark CLICLIAI 技能Lark CLI drive batch-query-comments 实战指南按评论 ID 批量拉取云文档评论卡片Lark CLI drive batch query comments 实战指南按评论 ID 批量拉取云文档评论卡片 适用对象 使用 lark cliLCLIAI 技能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考