feat: support file comment reply reactions (#380)

Change-Id: Ib75a35c438dc1c1aac32077ccc04a0de2ffef145
2026-07-07 09:11:44 +08:00 · 2026-04-10 18:22:30 +08:00
parent 344ff88701
commit 51d07be18a
5 changed files with 142 additions and 4 deletions
--- a/skill-template/domains/doc.md
+++ b/skill-template/domains/doc.md
@@ -106,9 +106,13 @@ Drive Folder (云空间文件夹)
 - 编辑画板需要使用专门的 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md)

 ## 快速决策
+- 用户说“看一下文档里的图片/附件/素材”“预览素材”，优先用 `lark-cli docs +media-preview`。
+- 用户明确说“下载素材”，再用 `lark-cli docs +media-download`。
+- 如果目标明确是画板 / whiteboard / 画板缩略图，只能用 `lark-cli docs +media-download --type whiteboard`，不要用 `+media-preview`。
 - 用户说“找一个表格”“按名称搜电子表格”“找报表”“最近打开的表格”，先用 `lark-cli docs +search` 做资源发现。
 - `docs +search` 不是只搜文档 / Wiki；结果里会直接返回 `SHEET` 等云空间对象。
 - 拿到 spreadsheet URL / token 后，再切到 `lark-sheets` 做对象内部读取、筛选、写入等操作。
+- 用户说“给文档加评论”“查看评论”“回复评论”“给评论加表情 / reaction”“删除评论表情 / reaction”，**不要留在 `lark-doc`**，直接切到 `lark-drive` 处理。

 ## 补充说明 
 `docs +search` 除了搜索文档 / Wiki，也承担“先定位云空间对象，再切回对应业务 skill 操作”的资源发现入口角色；当用户口头说“表格 / 报表”时，也优先从这里开始。
--- a/skill-template/domains/drive.md
+++ b/skill-template/domains/drive.md
@@ -1,8 +1,15 @@

-## 核心概念
-
 > **导入分流规则：** 如果用户要把本地 Excel / CSV 导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。

+## 快速决策
+
+- 用户要把本地 `.xlsx` / `.csv` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
+- 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
+- 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
+- `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
+
+## 核心概念
+
 ### 文档类型与 Token

 飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的 `file_token`。
@@ -136,6 +143,9 @@ Drive Folder (云空间文件夹)
 - 使用 `drive file.comments batch_query` 是**已知评论 ID 后**的批量查询，需要传入具体的评论 ID 列表。
 - 使用 `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论，或获取"最新/最后 N 条评论"等场景。

+#### Reaction / 表情场景
+- 遇到评论 / 回复上的 reaction（表情、各表情数量、谁点了什么、添加/删除表情）相关问题时，**先阅读 [lark-drive-reactions.md](../../skills/lark-drive/references/lark-drive-reactions.md) 了解如何使用**。
+
 ### 典型错误与解决方案

 | 错误信息 | 原因 | 解决方案 |
--- a/skills/lark-doc/SKILL.md
+++ b/skills/lark-doc/SKILL.md
@@ -119,12 +119,13 @@ Drive Folder (云空间文件夹)
 - 编辑画板需要使用专门的 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md)

 ## 快速决策
- 用户说“找一个表格”“按名称搜电子表格”“找报表”“最近打开的表格”，先用 `lark-cli docs +search` 做资源发现。
 - 用户说“看一下文档里的图片/附件/素材”“预览素材”，优先用 `lark-cli docs +media-preview`。
 - 用户明确说“下载素材”，再用 `lark-cli docs +media-download`。
 - 如果目标明确是画板 / whiteboard / 画板缩略图，只能用 `lark-cli docs +media-download --type whiteboard`，不要用 `+media-preview`。
+- 用户说“找一个表格”“按名称搜电子表格”“找报表”“最近打开的表格”，先用 `lark-cli docs +search` 做资源发现。
 - `docs +search` 不是只搜文档 / Wiki；结果里会直接返回 `SHEET` 等云空间对象。
 - 拿到 spreadsheet URL / token 后，再切到 `lark-sheets` 做对象内部读取、筛选、写入等操作。
+- 用户说“给文档加评论”“查看评论”“回复评论”“给评论加表情 / reaction”“删除评论表情 / reaction”，**不要留在 `lark-doc`**，直接切到 `lark-drive` 处理。

 ## 补充说明 
 `docs +search` 除了搜索文档 / Wiki，也承担“先定位云空间对象，再切回对应业务 skill 操作”的资源发现入口角色；当用户口头说“表格 / 报表”时，也优先从这里开始。
--- a/skills/lark-drive/SKILL.md
+++ b/skills/lark-drive/SKILL.md
@@ -12,6 +12,8 @@ metadata:

 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**

+> **导入分流规则：** 如果用户要把本地 Excel / CSV 导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。
+
 ## 快速决策

 - 用户要把本地 `.xlsx` / `.csv` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
@@ -154,6 +156,9 @@ Drive Folder (云空间文件夹)
 - 使用 `drive file.comments batch_query` 是**已知评论 ID 后**的批量查询，需要传入具体的评论 ID 列表。
 - 使用 `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论，或获取"最新/最后 N 条评论"等场景。

+#### Reaction 场景
+- 遇到评论 / 回复上的 reaction（表情、各表情数量、谁点了什么、添加/删除表情）相关问题时，**先阅读 [lark-drive-reactions.md](../../skills/lark-drive/references/lark-drive-reactions.md) 了解如何使用**。
+
 ### 典型错误与解决方案

 | 错误信息 | 原因 | 解决方案 |
@@ -201,7 +206,7 @@ lark-cli drive <resource> <method> [flags] # 调用 API

 ### file.comment.replys

-  - `create` — 
+  - `create` — 添加回复
  - `delete` — 删除回复
  - `list` — 获取回复
  - `update` — 更新回复
@@ -230,6 +235,10 @@ lark-cli drive <resource> <method> [flags] # 调用 API

  - `list` — 获取文档的访问者记录

+### file.comment.reply.reactions
+
+  - `update_reaction` — 添加/删除 reaction
+
 ## 权限表

 | 方法 | 所需 scope |
@@ -254,3 +263,4 @@ lark-cli drive <resource> <method> [flags] # 调用 API
 | `user.subscription_status` | `docs:event:subscribe` |
 | `file.statistics.get` | `drive:drive.metadata:readonly` |
 | `file.view_records.list` | `drive:file:view_record:readonly` |
+| `file.comment.reply.reactions.update_reaction` | `docs:document.comment:create` |
--- a/skills/lark-drive/references/lark-drive-reactions.md
+++ b/skills/lark-drive/references/lark-drive-reactions.md
@@ -0,0 +1,113 @@
+# drive reactions
+
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 评论卡片模型、评论数/回复数统计口径、`file_token` / `file_type` 规则；再阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+处理文档评论 / 回复上的 reaction（点赞、表情、各表情数量、谁点了什么、添加/删除表情）。这个场景不常见，但规则比较集中：查询时只有在用户明确需要 reaction 信息时才带 `need_reaction=true`；写入时统一使用 `drive file.comment.reply.reactions update_reaction`，操作对象始终是 `reply_id`。
+
+> [!IMPORTANT]
+> **`reaction_type` 只能使用本文下方“完整 `reaction_type` 列表”中定义的枚举值。**
+> 不要自由填写、不要根据自然语言临时编造、也不要把列表里的 mixed-case 值改写成别的大小写形式。需要写入时，只能从下方枚举中原样选择并传参。
+
+## 何时使用
+
+- 用户明确要求查看评论 / 回复上的 reaction（表情）。
+- 用户要统计某条评论卡片有哪些表情、各表情数量，或要看谁点了什么。
+- 用户要给评论或回复添加 / 删除 reaction。
+
+## 查询规则
+
+- `drive file.comments list`、`drive file.comments batch_query`、`drive file.comment.replys list` 都支持通过指定`need_reaction`查询reaction信息。
+- `need_reaction` 只在用户明确需要 reaction 信息时再带；如果用户只关心评论正文、回复正文、评论数 / 回复数，默认不要加。
+- 遍历评论卡片并顺带拿 reaction：使用 `drive file.comments list`。
+- 已知评论 ID，批量查看 reaction：使用 `drive file.comments batch_query`，并在请求体里带 `need_reaction=true`。
+- 某张评论卡片下继续翻页拉 reply reaction：使用 `drive file.comment.replys list`。
+- 如果 `drive file.comments list` 返回的某个 `item.has_more=true`，且用户要完整的 reply reaction 数据，后续每一页 `drive file.comment.replys list` 都要持续带 `need_reaction=true`。
+
+## 查询示例
+
+```bash
+# 遍历评论卡片，并把 reaction 一起拿回来
+lark-cli drive file.comments list \
+  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx","need_reaction":true}'
+
+# 已知 comment_id，批量查询评论卡片 reaction
+lark-cli drive file.comments batch_query \
+  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
+  --data '{"comment_ids":["<COMMENT_ID>"],"need_reaction":true}'
+
+# 继续翻某张评论卡片下的 replies，并把 reaction 一起拿回来
+lark-cli drive file.comment.replys list \
+  --params '{"file_token":"<DOC_TOKEN>","comment_id":"<COMMENT_ID>","file_type":"docx","need_reaction":true}'
+```
+
+## 写入规则
+
+- 添加 / 删除 reaction 时，使用 `drive file.comment.reply.reactions update_reaction`。
+- 请求里必须带正确的 `file_type`，并在 body 中传 `action=add|delete`、`reply_id`、`reaction_type`。
+- `update_reaction` 的操作对象是 `reply_id`，不是 `comment_id`。
+- 如果用户说要给“这条评论”加 / 删 reaction，通常需要定位到该评论卡片首条 reply 的 `reply_id` 再操作。
+
+## 写入示例
+
+```bash
+# 给某条 reply 添加一个点赞 reaction
+lark-cli drive file.comment.reply.reactions update_reaction \
+  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
+  --data '{"action":"add","reply_id":"<REPLY_ID>","reaction_type":"THUMBSUP"}'
+
+# 删除某条 reply 上已有的 DONE reaction
+lark-cli drive file.comment.reply.reactions update_reaction \
+  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
+  --data '{"action":"delete","reply_id":"<REPLY_ID>","reaction_type":"DONE"}'
+```
+
+> [!CAUTION]
+> `update_reaction` 是写入操作。执行前必须确认用户意图，不要默认替用户点表情。
+
+## `reaction_type` 使用规则
+
+- `reaction_type` 必须传平台定义的枚举字符串，大小写敏感。
+- 不要擅自把 mixed-case 值改成全大写，例如 `Yes`、`No`、`Get`、`EatingFood`、`CheckMark`、`CrossMark` 都要按原值传。
+- **不要编造列表外的 `reaction_type`，也不要把自然语言描述臆造成平台未定义的新枚举**。
+- 如果用户给的是自然语言语义（如“点赞”“在处理中”“确认一下”），可以在下方枚举列表内选择语义最接近的现有值；如果是近似映射，应在执行时明确告知用户。
+
+## 常见语义联想
+
+- `Yes`：确认 / 同意 / 批准。
+- `No`：拒绝 / 不同意 / 否定。
+- `DONE`：已完成 / 已处理。
+- `Typing`：正在输入 / 正在处理中 / 正在跟进（近似语义）。
+- `OK`：好的 / 收到 / 确认一下。
+- `THUMBSUP`：点赞 / 认可。
+- `LGTM`：看起来没问题 / 可以继续。
+
+## 完整 `reaction_type` 列表
+
+以下枚举按当前 Drive 评论 reaction 指引维护，使用时请保持原样：
+
+```text
+ANGRY, APPLAUSE, ATTENTION, AWESOME, BEAR, BEER, BETRAYED, BIGKISS
+BLACKFACE, BLUBBER, BLUSH, BOMB, CAKE, CHUCKLE, CLAP, CLEAVER
+COMFORT, CRAZY, CRY, CUCUMBER, DETERGENT, DIZZY, DONE, DONNOTGO
+DROOL, DROWSY, DULL, DULLSTARE, EATING, EMBARRASSED, ENOUGH, ERROR
+EYESCLOSED, FACEPALM, FINGERHEART, FISTBUMP, FOLLOWME, FROWN, GIFT, GLANCE
+GOODJOB, HAMMER, HAUGHTY, HEADSET, HEART, HEARTBROKEN, HIGHFIVE, HUG
+HUSKY, INNOCENTSMILE, JIAYI, JOYFUL, KISS, LAUGH, LIPS, LOL
+LOOKDOWN, LOVE, MONEY, MUSCLE, NOSEPICK, OBSESSED, OK, PARTY
+PETRIFIED, POOP, PRAISE, PROUD, PUKE, RAINBOWPUKE, ROSE, SALUTE
+SCOWL, SHAKE, SHHH, SHOCKED, SHOWOFF, SHY, SICK, SILENT
+SKULL, SLAP, SLEEP, SLIGHT, SMART, SMILE, SMIRK, SMOOCH
+SMUG, SOB, SPEECHLESS, SPITBLOOD, STRIVE, SWEAT, TEARS, TEASE
+TERROR, THANKS, THINKING, THUMBSUP, TOASTED, TONGUE, TRICK, UPPERLEFT
+WAIL, WAVE, WELLDONE, WHAT, WHIMPER, WINK, WITTY, WOW
+WRONGED, XBLUSH, YAWN, YEAH, FIREWORKS, BULL, CALF, AWESOMEN
+2021, CANDIEDHAWS, REDPACKET, FORTUNE, LUCK, FIRECRACKER, Yes, No
+Get, LGTM, Lemon, EatingFood, Hundred, MinusOne, ThumbsDown, Fire
+OKR, Drumstick, BubbleTea, Loudspeaker, Pin, Coffee, Alarm, Trophy
+Music, Typing, Pepper, CheckMark, CrossMark
+```
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数