EP-Hub-Skill/.agents/skills/dingtalk-chat/references/chat/chat-conversation.md

chat-conversation：会话状态、红点、置顶与分组

返回入口：chat.md

适用场景

用于获取会话基础信息、全部会话/置顶会话列表、会话置顶、免打扰、隐藏、红点、已读未读、清空聊天记录、自定义会话分组和智能会话分组。

• 查看置顶会话默认使用 `dws chat +conversation-list-top`； 原子 list-top-conversations 只在需要原始响应时作为 fallback。
• 取得目标会话后读取或导出消息记录，默认使用 `dws chat +chat-messages`； 可附带非必填的 --sender-query 解析姓名：唯一解析成功后按 senderId 筛选同一次读取结果； 解析失败、不完整或存在歧义时抑制未过滤消息并返回 sender_resolution_failed。不要回到原子 message list，也不要补跑 +search-msg。直接条件检索优先使用 +search-msg。

必读约束

• 会话状态类命令通常需要 openConversationId。群聊只用 +chat-search --query 获取唯一候选，单聊可由 chat conversation-info --user/--open-dingtalk-id 获取。
• set-top 是会话置顶；message set-top-msg 是会话内消息置顶，二者不能混用。
• clear-messages 只清空当前用户视角的消息，不影响其他成员。
• 智能分组规则中的成员使用 openDingTalkId；如果用户只给姓名，先用 aisearch person --dimension name 获取。

命令明细

会话基础信息

dws chat conversation-info --group <openConversationId> --format json
dws chat conversation-info --user <userId> --format json
dws chat conversation-info --open-dingtalk-id <openDingTalkId> --format json

--group、--user、--open-dingtalk-id 互斥且必须指定一个。文件/音视频发送不再依赖调用方读取 spaceId；直接用 message send --msg-type file|audio|video --file。

会话列表与红点

命令	用途	参数
+conversation-list	获取当前用户会话	要求“全部”时加 --page-all；检查 complete / failures
+chat-list	列出当前用户会话（默认群聊，可选单聊）	默认只返回群聊；--types group,p2p 可包含单聊；要求全部时加 --page-all，合并去重后再过滤类型
+chat-list-all	获取当前用户加入的全部群	要求全部时加 --page-all；沿数字 nextCursor 去重聚合
+my-groups	获取并投影当前用户加入的群	要求全部时加 --page-all；读完后再应用 --type 本地过滤
+conversation-list-top	获取置顶会话列表	可选 --limit --cursor --exclude-muted；使用稳定 conversations[]
message list-unread-conversations	获取未读会话列表	可选 --count --exclude-muted
clear-red-point	清除指定会话红点	--conversation-id，别名 --id / --chat
clear-all-red-point	清除所有会话红点，一键全部已读	无参数

翻页时，hasMore=true 用返回的 nextCursor 作为下次 --cursor。Shortcut 全量读取应检查 complete、stopReason 和 failures；达到 --page-limit 时会保留可继续的 nextCursor。

会话置顶与通知

命令	用途	必填参数
set-top	设置/取消会话置顶	--conversation-id；默认置顶，--off 取消
mute	开启/关闭会话免打扰	--conversation-id；默认开启，--off 关闭
hide	隐藏会话	--conversation-id
mute-at-all	关闭/恢复 @所有人通知	--conversation-id；默认关闭，--off 恢复；必须先开启会话总免打扰
mute-red-envelope	关闭/恢复红包通知	--conversation-id；默认关闭，--off 恢复；必须先开启会话总免打扰

若连续操作两个子开关，优先操作红包通知；恢复 @所有人通知后，平台可能清除子开关所需的 总免打扰状态，此时要先重新开启总免打扰，再操作红包通知。

dws chat set-top --conversation-id <openConversationId>
dws chat set-top --conversation-id <openConversationId> --off
dws chat mute --conversation-id <openConversationId>
dws chat mute --conversation-id <openConversationId> --off
dws chat hide --conversation-id <openConversationId>

已读未读与清理

命令	用途	必填参数
mark-unread	标记指定会话为未读	--conversation-id
mark-read	将指定消息及之前消息标记为已读	--conversation-id --message-id
clear-messages	清空当前用户指定会话的消息	--conversation-id

dws chat mark-unread --conversation-id <openConversationId>
dws chat mark-read --conversation-id <openConversationId> --message-id <openMessageId>
dws chat clear-messages --conversation-id <openConversationId>

会话分组

命令	用途	必填参数
category list	获取用户自定义会话分组	无
category list-conversations	拉取指定分组下会话	--category-id，可选 --exclude-muted
category list-by-conv	拉取指定会话所属的用户自定义会话分组	--group
category batch-info	批量拉取用户自定义会话分组信息	--category-ids
category create	创建会话分组	--title
category create-smart	创建智能会话分组，可按群名称关键词和群内成员匹配	--name，可选 --keywords --members
category delete	删除会话分组	--category-id
category rename	修改分组名称	--category-id --title
category add-conv	将会话加入分组	--group --category-ids
category remove-conv	将会话移出分组	--group --category-ids

dws chat category list
dws chat category list-by-conv --group <openConversationId>
dws chat category batch-info --category-ids 123,456
dws chat category create --title "工作群"
dws chat category create-smart --name "重点群" --keywords "重点,项目" --members openDingTalkId1,openDingTalkId2
dws chat category add-conv --group <openConversationId> --category-ids 123,456

create-smart 中 --keywords 是群名称关键词列表，--members 是群内成员 openDingTalkId 列表；两者可单独使用，也可组合使用。

常见工作流

获取单聊会话 ID 后置顶

dws aisearch person --query "张三" --dimension name --format json
dws chat conversation-info --user <userId> --format json
dws chat set-top --conversation-id <openConversationId> --format json

查看置顶会话并拉消息

dws chat +conversation-list-top --limit 100 --format json
dws chat +chat-messages --group <openConversationId> --time "2026-03-10 00:00:00" --direction older --format json

会话分组

dws chat category create --title "重点项目" --format json
dws chat category add-conv --group <openConversationId> --category-ids <categoryId> --format json
dws chat category list-by-conv --group <openConversationId> --format json
dws chat category batch-info --category-ids <categoryId> --format json
dws chat category list-conversations --category-id <categoryId> --format json

智能会话分组

dws aisearch person --query "张三" --dimension name --format json
dws chat category create-smart --name "项目组" --keywords "项目,开发" --format json
dws chat category create-smart --name "团队群" --members openDingTalkId1,openDingTalkId2 --format json
dws chat category create-smart --name "重点群" --keywords "重点" --members openDingTalkId1 --format json

常见错误与回退

• 用户说“置顶消息”：用 message set-top-msg，不是 chat set-top。
• 用户说“置顶会话”：设置/取消用 chat set-top，查看列表用 +conversation-list-top。
• 单聊没有会话 ID：先 conversation-info --user 或 --open-dingtalk-id。
• 清空聊天记录前必须确认目标会话；该操作只影响当前用户视角。
• 智能分组没有匹配条件：至少确认分组名称；关键词和成员规则不明确时先向用户确认，不要自行猜成员。