Starlight_Lancher/.agents/skills/lark-drive/references/lark-drive-list-comments.md

drive +list-comments

前置条件： 先阅读 ../lark-shared/SKILL.md 了解认证、全局参数和权限处理。

列出 doc/docx/sheet/file/slides/base(bitable)/apps 的评论卡片。优先传用户给出的完整 URL，shortcut 会自动识别类型；apps 为妙搭类型，支持 /page/<token> URL；如果传 wiki URL 或 --token <wiki_token> --type wiki，会先解析到真实文档。

重要默认口径

• 默认只查未解决评论，即不额外传 --solved-status 或显式传 --solved-status false。即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确提到包含已解决评论，仍然按默认口径查询未解决评论。
• 仅当用户明确要求“包含已解决评论”“已解决和未解决都要”“全部历史评论”这类语义时，才传 --solved-status all。
• 是否还有下一页以输出里的 has_more 为准；page_token 只作为 has_more=true 时续跑下一页的游标。

命令

# 推荐：直接传用户给出的完整 URL。默认只查未解决评论。
lark-cli drive +list-comments \
  --url "<DOCUMENT_URL>"

# 只有用户明确要求包含已解决评论时，才查询已解决和未解决的全部评论。
lark-cli drive +list-comments \
  --url "<DOCUMENT_URL>" \
  --solved-status all

# 查询已解决评论。
lark-cli drive +list-comments \
  --url "<DOCUMENT_URL>" \
  --solved-status true

# 只查全文评论或局部评论。
lark-cli drive +list-comments \
  --url "<DOCUMENT_URL>" \
  --comment-scope whole

lark-cli drive +list-comments \
  --url "<DOCUMENT_URL>" \
  --comment-scope partial

# 电子表格 URL 保留 /sheets/ 路径，直接原样传入；不要把 sheet token 拼成 /docx/<token>。
lark-cli drive +list-comments \
  --url "https://example.larksuite.com/sheets/<SHEET_TOKEN>"

# 妙搭 apps URL 使用 /page/<token>，shortcut 会识别为 file_type=apps。
lark-cli drive +list-comments \
  --url "https://example.feishu.cn/page/<APPS_TOKEN>/"

# wiki URL 会自动解包。
lark-cli drive +list-comments \
  --url "https://example.larksuite.com/wiki/<WIKI_TOKEN>"

# 裸 wiki token 也支持，但必须显式声明 --type wiki。
lark-cli drive +list-comments \
  --token "<WIKI_TOKEN>" \
  --type wiki

# 裸 token 需要声明 token 对应类型；不要默认当作 docx。这里以 sheet 为例。
lark-cli drive +list-comments \
  --token "<DOCUMENT_TOKEN>" \
  --type sheet \
  --page-size 100

# 妙搭裸 apps token 需要显式声明 --type apps。
lark-cli drive +list-comments \
  --token "<APPS_TOKEN>" \
  --type apps

# docx 需要评论定位关系时再带 need-relation；非 docx 会静默忽略。
lark-cli drive +list-comments \
  --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" \
  --need-relation

# 分页续跑。
# 先看上一页输出的 has_more；只有 has_more=true 时，才用返回的 page_token 继续。
lark-cli drive +list-comments \
  --url "<DOCUMENT_URL>" \
  --page-size 100 \
  --page-token "<NEXT_PAGE_TOKEN>"

# 预览请求链路，不发真实请求。
lark-cli drive +list-comments \
  --url "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
  --dry-run

参数

参数	必填	说明
--url	与 --token 二选一	推荐入口。支持 doc/docx/sheet/file/slides/base/bitable/apps/wiki URL；apps 妙搭 URL 使用 /page/<token>；wiki URL 会自动解析到真实文档。
--token	与 --url 二选一	裸 token 或 URL。裸 token 必须搭配 --type；wiki 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 静默忽略。需要定位正文时先读 lark-drive-comment-location.md。
--page-size	否	默认 50，最大 100。
--page-token	否	分页游标；本 shortcut 不自动翻页，按返回的 page_token 继续请求下一页。

行为说明

• --comment-scope all 查全部范围；whole 查全文评论；partial 查局部/选区评论。
• 当用户已经给出完整 URL 时，原样传给 --url；不要先提取 token 再重组成其他类型 URL。比如 sheet 保留 /sheets/<token>，wiki 保留 /wiki/<token>，妙搭 apps 保留 /page/<token>。
• URL 输入时不需要传 --type；如果 URL 类型和显式 --type 冲突，shortcut 会返回 validation error，建议移除 --type。
• wiki 输入会自动解析到真实文档，再查询评论列表。JSON 输出不额外返回 wiki token 或 wiki node。
• 输出中的 items 保留评论卡片字段，外层补充 file_token、file_type、has_more、page_token、count；count 是当前页返回的评论卡片数。是否继续分页以 has_more 为准，而不是只看 page_token 是否存在。
• 如果需要批量按评论 ID 查询、获取更多回复、创建/编辑/删除回复，继续使用原生 drive file.comments batch_query 或 drive file.comment.replys.*。

输出

{
  "file_token": "docx_token",
  "file_type": "docx",
  "items": [],
  "has_more": false,
  "page_token": "",
  "count": 0
}

参考

• lark-drive -- 云空间（云盘/云存储）全部命令
• lark-drive-comments-guide -- 评论统计、回复限制和原生 API 说明
• lark-drive-comment-location -- 使用 need_relation 定位 docx 正文