Skip to content

Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/lark-skills/lark-drive

lark-drive

Verified

【何时用:仅当用户明确指向飞书/Lark(发到飞书、飞书文档等)时使用;泛指做个文档或PPT或表格或方案默认走本地工具,不要误用飞书】飞书云空间:管理 Drive 文件/文件夹,上传下载、复制移动删除、评论、权限、密级标签、版本、改标题,导入 Word/Markdown/Excel/CSV/PPTX/.base 为在线文档;doubao.com 云空间 URL 同走本 skill,不回退 WebFetch。不负责:文档内容编辑(lark-doc)、表格/Base 表内数据(lark-sheets/lark-base)、知识库节点(lark-wiki)。

FileKindSize
SKILL.mdskill md24.3 KB
references/lark-drive-add-comment.mdmarkdown11.9 KB
references/lark-drive-add-reply.mdmarkdown2.5 KB
references/lark-drive-apply-permission.mdmarkdown3.6 KB
references/lark-drive-batch-query-comments.mdmarkdown2.4 KB
references/lark-drive-comment-content.mdmarkdown2.6 KB
references/lark-drive-comment-location.mdmarkdown10.8 KB
references/lark-drive-copy.mdmarkdown3.9 KB
references/lark-drive-cover.mdmarkdown2.4 KB
references/lark-drive-create-folder.mdmarkdown3.7 KB
references/lark-drive-create-shortcut.mdmarkdown4.3 KB
references/lark-drive-delete-reply.mdmarkdown2.4 KB
references/lark-drive-delete.mdmarkdown4.5 KB
references/lark-drive-download.mdmarkdown2.8 KB
references/lark-drive-export-download.mdmarkdown1.5 KB
references/lark-drive-export.mdmarkdown8.2 KB
references/lark-drive-files-list.mdmarkdown10.2 KB
references/lark-drive-import.mdmarkdown11.0 KB
references/lark-drive-inspect.mdmarkdown2.1 KB
references/lark-drive-list-comments.mdmarkdown5.9 KB
references/lark-drive-list-replies.mdmarkdown2.6 KB
references/lark-drive-member-add.mdmarkdown5.1 KB
references/lark-drive-member-list.mdmarkdown3.0 KB
references/lark-drive-member-remove.mdmarkdown2.9 KB
references/lark-drive-move.mdmarkdown5.0 KB
references/lark-drive-permission-get-setting.mdmarkdown1.8 KB
references/lark-drive-permission-guide.mdmarkdown3.7 KB
references/lark-drive-preview.mdmarkdown4.6 KB
references/lark-drive-pull.mdmarkdown9.8 KB
references/lark-drive-push.mdmarkdown18.0 KB
references/lark-drive-react-reply.mdmarkdown2.9 KB
references/lark-drive-reactions.mdmarkdown7.1 KB
references/lark-drive-resolve-comment.mdmarkdown1.7 KB
references/lark-drive-restore-comment.mdmarkdown2.1 KB
references/lark-drive-search.mdmarkdown22.5 KB
references/lark-drive-secure-label.mdmarkdown2.0 KB
references/lark-drive-status.mdmarkdown7.3 KB
references/lark-drive-task-result.mdmarkdown13.4 KB
references/lark-drive-update-reply.mdmarkdown2.4 KB
references/lark-drive-update-title.mdmarkdown3.4 KB
references/lark-drive-upload.mdmarkdown5.4 KB
references/lark-drive-version-delete.mdmarkdown1.0 KB
references/lark-drive-version-get.mdmarkdown2.0 KB
references/lark-drive-version-history.mdmarkdown1.9 KB
references/lark-drive-version-revert.mdmarkdown1.3 KB
references/lark-drive-workflow-knowledge-organize-analysis.mdmarkdown12.6 KB
references/lark-drive-workflow-knowledge-organize-discovery.mdmarkdown18.9 KB
references/lark-drive-workflow-knowledge-organize-execution.mdmarkdown9.4 KB
references/lark-drive-workflow-knowledge-organize-planning.mdmarkdown14.2 KB
references/lark-drive-workflow-knowledge-organize-rollback.mdmarkdown10.8 KB
references/lark-drive-workflow-knowledge-organize.mdmarkdown19.8 KB
references/lark-drive-workflow-permission-governance-commands.mdmarkdown6.4 KB
references/lark-drive-workflow-permission-governance-outputs.mdmarkdown27.7 KB
references/lark-drive-workflow-permission-governance.mdmarkdown25.7 KB
references/lark-drive-workflow-topic-move-collector-execute.mdmarkdown13.5 KB
references/lark-drive-workflow-topic-move-collector-recall.mdmarkdown9.3 KB
references/lark-drive-workflow-topic-move-collector-resolve-verify.mdmarkdown13.6 KB
references/lark-drive-workflow-topic-move-collector-review-plan.mdmarkdown12.5 KB
references/lark-drive-workflow-topic-move-collector-setup.mdmarkdown8.3 KB
references/lark-drive-workflow-topic-move-collector.mdmarkdown15.8 KB
references/lark-drive-workflow.mdmarkdown8.3 KB

references/lark-drive-add-comment.md

View on GitHub

# drive +add-comment

> **前置条件:** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

给文档、受支持的 Drive 普通文件、电子表格、飞书幻灯片或 Base 添加评论。未指定位置时创建全文评论,但仅适用于 doc/docx、白名单 Drive file,以及解析为这些类型的 wiki;sheet、slides、Base(bitable) 必须指定 `--block-id`。不同类型的 `--block-id` 格式见下文。支持直接传 docx URL/token、旧版 doc URL(仅全文评论)、Drive file URL/token(**仅支持白名单扩展名,且只支持全文评论**)、sheet URL、slides URL、base/bitable URL,也支持传最终可解析为 doc/docx/file/sheet/slides/base(bitable) 的 wiki URL。

## 命令

```bash
# 默认:未指定位置时添加全文评论
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
  --content '[{"type":"text","text":"请补充发布说明"}]'

# 也可以显式指定为全文评论;旧版 doc URL 仅支持全文评论
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/doc/<DOC_ID>" \
  --full-comment \
  --content '[{"type":"text","text":"请补充旧版文档的背景信息"}]'

# wiki 链接也可以,shortcut 会先解析到真实 doc/docx token
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
  --content '[{"type":"text","text":"这里需要一段全文评论"}]'

# 给受支持的 Drive 普通文件添加全文评论
# 注意:CLI 会先查询 drive metas,只有白名单扩展名才允许评论
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/file/<FILE_TOKEN>" \
  --content '[{"type":"text","text":"请补充文件说明"}]'

# 裸 token 也支持,但必须显式声明 --type file
lark-cli drive +add-comment \
  --doc "<FILE_TOKEN>" --type file \
  --content '[{"type":"text","text":"请补充目录说明"}]'

# 给 docx 文档的指定 block 添加局部评论(block_id 可通过 docs +fetch --detail with-ids 获取)
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
  --block-id "<BLOCK_ID>" \
  --content '[{"type":"text","text":"请补充流程说明"}]'

# wiki 链接也支持局部评论;解析结果可以是 docx/sheet/slides,block-id 格式按目标类型传
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
  --block-id "<BLOCK_ID>" \
  --content '[{"type":"text","text":"请补充更细的开发步骤"}]'

# 组合文本、@用户、链接元素
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
  --block-id "<BLOCK_ID>" \
  --content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 处理,参考 "},{"type":"link","text":"https://example.com"}]'

# 给电子表格单元格添加评论(--block-id 格式为 <sheetId>!<cell>)
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/sheets/<SHEET_TOKEN>" \
  --block-id "<SHEET_ID>!D6" \
  --content '[{"type":"text","text":"请检查此单元格数据"}]'

# wiki 链接指向的 sheet 也支持
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
  --block-id "<SHEET_ID>!A1" \
  --content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 确认"}]'

# 给幻灯片元素添加评论(--block-id 格式为 <slide-block-type>!<xml-id>)
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
  --block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>" \
  --content '[{"type":"text","text":"请调整这个元素的位置"}]'

# 例如:给整页 slide 添加评论
# <slide id="pkk"> ... </slide>  =>  --block-id slide!pkk
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
  --block-id "slide!pkk" \
  --content '[{"type":"text","text":"这一页需要补充过渡说明"}]'

# 例如:给图片元素添加评论
# <img id="bPk" ... />  =>  --block-id img!bPk
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
  --block-id "img!bPk" \
  --content '[{"type":"text","text":"这张图片建议换成更清晰的版本"}]'

# 例如:给文本 shape 添加评论
# <shape type="text" id="bPq"> ... </shape>  =>  --block-id shape!bPq
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
  --block-id "shape!bPq" \
  --content '[{"type":"text","text":"这段文案可以再精简"}]'

# wiki 链接指向的 slides 也支持
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
  --block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>" \
  --content '[{"type":"text","text":"这里需要补充说明"}]'

# 传裸 token 时需要 --type 指定文档类型
lark-cli drive +add-comment \
  --doc "<SHEET_TOKEN>" --type sheet \
  --block-id "<SHEET_ID>!D6" \
  --content '[{"type":"text","text":"请检查"}]'

lark-cli drive +add-comment \
  --doc "<DOCX_TOKEN>" --type docx \
  --content '[{"type":"text","text":"全文评论"}]'

# 裸 token + 已知 block_id 的局部评论
lark-cli drive +add-comment \
  --doc "<PRESENTATION_ID>" --type slides \
  --block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>" \
  --content '[{"type":"text","text":"slide block comment"}]'

# 裸 token + 已知 block_id 的局部评论
lark-cli drive +add-comment \
  --doc "<DOCX_TOKEN>" --type docx \
  --block-id "<BLOCK_ID>" \
  --content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 处理,参考 "},{"type":"link","text":"https://example.com"}]'

# 如果需要更底层的原生 API,也可以直接调用 V2 协议
lark-cli schema drive.file.comments.create_v2

lark-cli drive file.comments create_v2 \
  --params '{"file_token":"<DOC_TOKEN>"}' \
  --data '{"file_type":"docx","reply_elements":[{"type":"text","text":"全文评论内容"}]}'

# Base 记录局部评论;原生 file_type 传 bitable。
lark-cli drive +add-comment \
  --doc "<BASE_TOKEN>" --type bitable \
  --block-id "<TABLE_ID>!<RECORD_ID>!<VIEW_ID>" \
  --content '[{"type":"text","text":"Base record-local comment"}]'

# `base` 也可作为裸 token 类型别名;/base/ 与 /bitable/ URL 都会自动识别为 Base。
lark-cli drive +add-comment \
  --doc "<BASE_TOKEN>" --type base \
  --block-id "<TABLE_ID>!<RECORD_ID>!<VIEW_ID>" \
  --content '[{"type":"text","text":"Base alias comment"}]'

# 预览底层调用链
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
  --block-id "<BLOCK_ID>" \
  --content '[{"type":"text","text":"请补充流程说明"}]' \
  --dry-run
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `--doc` | 是 | 文档 URL / token、file / sheet / slides / base / bitable URL,或可解析到 `doc`/`docx`/`file`/`sheet`/`slides`/`base(bitable)` 的 wiki URL |
| `--type` | 裸 token 时必填 | 文档类型:`doc`、`docx`、`file`、`sheet`、`slides`、`bitable`、`base`;评论 Base 文档推荐传 `bitable`,`base` 仅作为兼容别名兜底。URL 输入时自动识别,无需传 |
| `--content` | 是 | `reply_elements` JSON 数组字符串。示例:`'[{"type":"text","text":"文本"},{"type":"mention_user","text":"ou_xxx"},{"type":"link","text":"https://example.com"}]'` |
| `--full-comment` | 否 | 显式指定创建全文评论;未传 `--block-id` 时也会默认走全文评论(仅适用于 doc/docx、白名单 Drive file,以及解析为这些类型的 wiki;不适用于 sheet、slides、Base / bitable) |
| `--block-id` | 局部评论时必填 | 目标块 ID,可通过 `docs +fetch --detail with-ids` 获取;sheet 用 `<sheetId>!<cell>`,slides 用 `<slide-block-type>!<xml-id>`,Base 用 `<table-id>!<record-id>!<view-id>` |

## 行为说明

- **不支持妙搭 apps**:妙搭不支持新增评论,`--doc` 传 `/page/<token>` URL 或 `--type apps` 都不可用。其余评论管理命令(列表、批量查询、回复、解决/恢复、reaction)都支持 apps。
- **局部评论需要先获取 block ID**:先调用 `docs +fetch --doc <TOKEN> --detail with-ids` 获取带有 block ID 的文档内容,然后使用 `--block-id` 指定目标块。
- **Review 场景优先局部评论**:审阅、校对、逐条指出问题时,必须先尝试定位到具体 block / 单元格 / slide 元素,并逐问题创建局部评论;不要把所有问题合并成一条全文评论。
- 未传 `--block-id` 时,shortcut 默认创建**全文评论**;也可以显式传 `--full-comment`。全文评论支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file,以及最终可解析为 `doc`/`docx`/`file` 的 wiki URL。
- **Drive file 评论**:仅支持白名单扩展名的普通文件。当前支持:`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。
- **Drive file 暂不支持**:`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件会被 CLI 拒绝,并提示“当前还不支持这种类型的评论”。这些类型虽然可能接受 OpenAPI 请求,但在页面评论展示上存在问题。
- **Drive file 只支持全文评论**:file 目标不支持局部评论,不允许传 `--block-id`。
- 传 `--block-id` 时,shortcut 创建**局部评论(划词评论)**;该模式支持 `docx`、`sheet`、`slides`、Base / bitable,以及最终可解析为这些类型的 wiki URL。
- **Sheet 评论**:当 `--doc` 为 sheet URL 或 wiki 解析为 sheet 时,使用 `--block-id "<sheetId>!<cell>"` 指定单元格(如 `a281f9!D6`);sheet 没有全文评论,`--full-comment` 不可用。
- **Slide 评论**:当 `--doc` 为 slides URL、`--type slides`,或 wiki 解析为 slides 时,必须传 `--block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>"`。此时 `--full-comment` 不可用。
- **Base 记录局部评论**:Base 不支持全局评论,所有评论都挂在记录上;裸 token 可传 `--type bitable` 或 `--type base`,推荐 `bitable`。定位信息必须是 file token(base token)+ `--block-id "<table-id>!<record-id>!<view-id>"`,其中 table/record/view ID 通常分别以 `tbl`/`rec`/`vew` 开头;view_id 只决定被提及时点击通知打开哪个视图,不影响评论挂载点,但必须传。ID 获取参考 [`lark-base`](../../lark-base/SKILL.md)。
- **Slide 参数映射示例**:`--block-id` 由 PPT XML 元素类型和元素 `id` 组成。例如:
    - `<slide id="pkk">` 对应 `--block-id slide!pkk`,表示给整页评论。
    - `<img id="bPk" ... />` 对应 `--block-id img!bPk`,表示给图片元素评论。
    - `<shape type="text" id="bPq">...</shape>` 对应 `--block-id shape!bPq`,表示给文本 shape 评论。

- `--content` 是结构化评论元素数组(`text` / `mention_user` / `link`),完整格式见 [`lark-drive-comment-content.md`](lark-drive-comment-content.md);上方示例已覆盖常见写法。
- 写入评论前会自动生成符合 OpenAPI 定义的请求体;shortcut 用户只需要传 `--doc`、`--content`,局部评论再传对应格式的 `--block-id`。
- `--dry-run` 仅预览调用链和请求体,不会实际写入。
- 如果需要更底层的控制,仍可改用 `lark-cli schema drive.file.comments.create_v2` + `lark-cli drive file.comments create_v2`。
- 直接调用原生 `drive.file.comments.create_v2` 时,全文评论省略 `anchor`;docx/sheet/slides 局部评论传 `anchor.block_id`,Base 记录局部评论传 `anchor.block_id`(table_id)、`anchor.base_record_id`、`anchor.base_view_id`。
- 直接调用原生 `drive.file.comments.*` / `drive.file.comment.replys.*` 评论 Base 文档时,`file_type` 填 `bitable`,不要填 `base`。

> [!CAUTION]
> 这是**写入操作** —— 执行前必须确认用户意图。

## 参考

- [lark-drive](../SKILL.md) -- 云空间(云盘/云存储)全部命令
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall