8.5 KiB
8.5 KiB
Chat 低频原子能力索引
返回入口：DingTalk Chat Skill
本文件只用于根 Skill 和精确 task reference 都未覆盖的低频底层能力。普通发送、读取、搜索、 建群、引用回复和查看置顶会话必须回到根 Skill 的 Golden Route，不在这里重新选路。
使用边界
- 先确认任务确实需要 Shortcut 未发布的底层字段、原始响应或运维控制；
- 读取精确原子 leaf Schema/Help，不加载产品级 Catalog 猜参数；
- 自然目标仍必须唯一解析，禁止选择搜索结果第一项；
- 原子写 leaf 的 confirmation 若与对应 Golden Shortcut 不一致，停止并报告交付漂移；
- 后续 ID 只使用当前 profile 的真实返回，不跨组织复用；
- 完成后保留原始结果、partial failure 和可继续编排的稳定 ID。
高频任务返回表
| 用户终点 | 返回入口 |
|---|---|
| 姓名/群名简单发送、文件、Bot、Webhook、复杂 @ | 根 Skill Golden Route |
| 消息读取、条件搜索、@我、Favorite/reaction 查询和批量详情 | message-query |
| 编辑、撤回、引用、转发、reaction/Pin/Top/Favorite 写入 | message-actions |
| 位置、名片、资源下载和特殊媒体 fallback | message-media |
| 群列表、群搜索、成员读取、Bot 列表和邀请链接 | group-discovery |
| 建群、改群、成员写入、管理员、禁言、公告和群设置 | group-admin |
| 跨步骤消息/群组合流程 | 消息任务级流程 |
| Bot 搜索、进群和撤回 | chat-bot |
| 会话置顶、状态和分组 | chat-conversation |
| 话题与话题圈的创建、发布、浏览、回复、互动和整条转发 | thread |
| 相邻低频意图仍需消歧 | intent-guide |
消息底层能力
| 原子命令 | 仅用于 |
|---|---|
chat message send |
+messages-send 尚未发布的位置、名片等真实底层消息类型 |
chat message list |
需要原始响应或显式手工 continuation；普通浏览使用 +chat-messages |
chat message list-all |
指定时间范围的原始全会话分页接口 |
chat message list-by-sender |
需要原始按发送者响应；普通组合搜索使用 +search-msg |
chat message list-mentions / list-focused |
精确的 @我或特别关注原始列表 |
chat message search / search-advanced |
+search-msg 未发布的底层过滤字段或原始响应 |
chat message query-send-status |
使用真实 openTaskId 查询用户消息投递任务 |
chat message recall / edit |
撤回或编辑已知消息 |
chat message read-status |
查询已知消息的已读/未读状态 |
chat message reply |
+messages-reply 未发布的底层引用字段，且安全门禁已对齐 |
chat message forward / combine-forward |
Shortcut 未覆盖的精确转发字段 |
chat message download-media |
Shortcut 无法消费的已知底层 mediaId/fileId 引用 |
消息对象管理：
| 原子命令 | 对象 |
|---|---|
message set-pin-msg / unset-pin-msg / list-pin-msg |
消息 Pin |
message set-top-msg / unset-top-msg |
会话内消息 Top |
message add-favorite / remove-favorite / list-favorites |
当前用户 Favorite |
message add-emoji / remove-emoji |
默认 emoji reaction |
message create-text-emotion / add-text-emotion / update-text-emotion / remove-text-emotion |
文字表情 |
message list-emotion-replies |
批量 reaction/文字回应 |
emotion list / send / favorite |
当前用户个人收藏表情列表、发送和新增 |
Favorite、消息 Pin、消息 Top 与会话 Top 是四种对象，不能互换。
个人收藏表情与消息 reaction/文字回应不同；发送收藏表情使用 chat emotion send，给已有消息贴表情使用 chat message add-emoji 或 chat message add-text-emotion。
群与成员底层能力
| 原子命令 | 用途 |
|---|---|
chat search / search-common |
群管理前解析唯一群、查询共同群 |
chat group get-by-group-id |
数字群号转 openConversationId |
chat group create |
+chat-create 尚未发布的真实底层创建字段；显式群主已由 Shortcut 覆盖 |
chat group members / members list-by-ids |
群成员分页和精确详情 |
chat group members add / remove |
添加/移除已知成员 ID |
chat group members add-bot / remove-bot / group bots |
机器人进群、移除和列表 |
chat group rename / update-icon |
群名和群头像 |
chat group transfer-owner / set-admin |
群主和管理员 |
chat group upgrade-to-external |
普通群升级外部群；不可逆 |
chat group invite-url / share-invite |
群邀请链接及分享 |
chat group update-settings / `user-settings query |
set` |
chat group update-nick / update-alias |
当前用户群昵称和群备注 |
chat group set-history |
新成员历史消息可见范围 |
chat group-mute / group-mute-member |
全员或指定成员禁言 |
| `chat group notice create | edit |
chat group list-my-groups / list-all |
当前用户相关群列表 |
chat group list-join-validations / audit-join-validation |
入群审批 |
chat group-role * |
群身份定义与成员分配 |
退出、解散群、踢人、转让群主、升级外部群、禁言、管理员和公告写入都属于高影响操作； 必须以最终 Runtime gate/Schema 为准确认对象与影响。
Bot 与 Webhook 底层能力
| 原子命令 | 用途 |
|---|---|
chat bot search |
搜索当前用户创建的机器人并取得 robotCode |
chat bot find |
搜索可用机器人并取得机器人 openDingTalkId |
chat message send-by-bot |
+messages-send --as bot 未发布的真实底层字段，包括机器人群聊引用回复的 --reply / --ref-sender |
chat message recall-by-bot |
使用 processQueryKey 撤回机器人消息 |
chat message send-by-webhook |
+messages-send --as webhook 未发布的真实底层字段 |
新发送流程统一使用 +messages-send。不得因看见 bot/webhook 原子命令就绕开统一身份能力矩阵。
会话状态与分组
| 原子命令 | 用途 |
|---|---|
chat conversation-info |
已知稳定用户/群 ID 的会话详情 |
chat list-all-conversations |
全部会话原始分页列表 |
chat list-top-conversations |
需要原始响应时的置顶会话 fallback；普通查看使用 +conversation-list-top |
chat set-top |
设置/取消整个会话置顶 |
chat mute / hide / mute-at-all / mute-red-envelope |
会话通知与可见状态 |
chat mark-unread / mark-read |
会话未读或消息已读状态 |
chat clear-red-point / clear-all-red-point |
清除会话红点 |
chat clear-messages |
清空当前用户视角的会话记录 |
chat category * |
自定义/智能会话分组 |
消息 Top 使用 message set-top-msg，整个会话 Top 使用 chat set-top，查看置顶会话使用
+conversation-list-top。
稳定 ID 传递
| 来源 | 只可用于 |
|---|---|
唯一群解析 / +chat-create |
当前 profile 下的 openConversationId |
| 唯一人员解析 | 当前 profile 下的 userId / openDingTalkId |
+messages-send |
openTaskId 查询投递状态；它不是消息 ID |
+chat-messages / +search-msg / +messages-mget |
回复、转发、撤回、资源操作使用的真实消息/会话/thread ID |
chat bot search |
robotCode；不能当机器人 openDingTalkId |
chat message send-by-bot |
processQueryKey 用于机器人撤回；群聊引用回复还需消息查询返回的 openMessageId 与原发送者 openDingTalkId |
显式稳定 ID 当前不携带可验证的 profile provenance；调用方必须保证来源，不得宣称所有 跨 profile 误用都会在本地写入前被拦截。
故障处理
unknown command/unknown flag：读取精确 leaf Help，最多修正一次；- confirmation 或参数约束不清：读取精确 leaf Schema，以最终 Runtime gate 为准；
- 自然目标零命中/多候选：停止并展示候选，不选择第一项；
- 权限、认证或 profile：按
dingtalk-shared对应 reference 分流； - partial result：保留已完成项、失败 ledger、continuation 和真实错误，不换同义原子命令重试。