Skip to content

Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/dingtalk-skills/dws

【何时用:仅当用户明确指向钉钉/DingTalk(钉钉文档、钉钉日程等)时使用;泛指做文档/表格/待办/审批默认走本地工具,不要误用钉钉】用 dws CLI 管理钉钉:AI表格/AI搜问(找人首选)/目标管理(Agoal)/组织大脑/日历/通讯录/群聊与机器人消息/待办/审批/智能合同/考勤/日志(日报周报)/DING消息/钉钉文档/云盘/Markdown文件/HTML文件/AI听记/邮箱/在线电子表格(axls)/知识库/白板/开放平台文档/个人IM与OA事件订阅。用户要求操作上述钉钉产品时使用。

FileKindSize
LICENSEother9.9 KB
NOTICEother666 B
SKILL.mdskill md38.4 KB
references/best_practices/01-messaging.mdmarkdown3.2 KB
references/best_practices/02-task.mdmarkdown2.8 KB
references/best_practices/03-meeting.mdmarkdown11.6 KB
references/best_practices/04-document.mdmarkdown11.0 KB
references/best_practices/05-reporting.mdmarkdown6.2 KB
references/best_practices/06-data-analytics.mdmarkdown5.4 KB
references/best_practices/07-minutes.mdmarkdown8.3 KB
references/best_practices/08-directory.mdmarkdown8.0 KB
references/best_practices/09-mail.mdmarkdown5.2 KB
references/best_practices/10-minutes-speaker-match.mdmarkdown9.0 KB
references/best_practices/11-minutes-speaker-correct.mdmarkdown4.4 KB
references/best_practices/_common/conventions.mdmarkdown3.4 KB
references/best_practices/_common/recipe-conventions.mdmarkdown1.8 KB
references/best_practices/lite-recipes.mdmarkdown15.7 KB
references/capability-limits.mdmarkdown2.9 KB
references/error-codes.mdmarkdown4.0 KB
references/field-rules.mdmarkdown5.4 KB
references/global-reference.mdmarkdown5.1 KB
references/intent-guide.mdmarkdown47.8 KB
references/products/agoal.mdmarkdown12.1 KB
references/products/aisearch.mdmarkdown14.1 KB
references/products/aitable-record-ops.mdmarkdown4.8 KB
references/products/aitable.mdmarkdown30.1 KB
references/products/aitable/aitable-advperm.mdmarkdown10.2 KB
references/products/aitable/aitable-api-key.mdmarkdown1.7 KB
references/products/aitable/aitable-attachment.mdmarkdown3.5 KB
references/products/aitable/aitable-best-practices.mdmarkdown3.5 KB
references/products/aitable/aitable-cell-value.mdmarkdown9.1 KB
references/products/aitable/aitable-comment.mdmarkdown2.8 KB
references/products/aitable/aitable-dashboard-chart.mdmarkdown4.5 KB
references/products/aitable/aitable-data-analysis-sop.mdmarkdown5.6 KB
references/products/aitable/aitable-error-recovery.mdmarkdown6.9 KB
references/products/aitable/aitable-export-import.mdmarkdown9.8 KB
references/products/aitable/aitable-field-properties.mdmarkdown8.5 KB
references/products/aitable/aitable-field.mdmarkdown6.6 KB
references/products/aitable/aitable-filter-sort.mdmarkdown12.4 KB
references/products/aitable/aitable-form.mdmarkdown15.1 KB
references/products/aitable/aitable-formula-guide.mdmarkdown8.2 KB
references/products/aitable/aitable-primary-doc.mdmarkdown2.3 KB
references/products/aitable/aitable-psql.mdmarkdown14.7 KB
references/products/aitable/aitable-record-create.mdmarkdown2.2 KB
references/products/aitable/aitable-record-delete.mdmarkdown582 B
references/products/aitable/aitable-record-history.mdmarkdown4.0 KB
references/products/aitable/aitable-record-name-key.mdmarkdown2.4 KB
references/products/aitable/aitable-record-query.mdmarkdown15.0 KB
references/products/aitable/aitable-record-share.mdmarkdown1.6 KB
references/products/aitable/aitable-record-stats.mdmarkdown3.8 KB
references/products/aitable/aitable-record-update.mdmarkdown3.2 KB
references/products/aitable/aitable-record-upsert.mdmarkdown3.3 KB
references/products/aitable/aitable-view-config.mdmarkdown11.8 KB
references/products/aitable/aitable-view-extras.mdmarkdown8.0 KB
references/products/aitable/aitable-workflow.mdmarkdown14.4 KB
references/products/attendance-report.mdmarkdown29.9 KB
references/products/attendance-schedule.mdmarkdown27.5 KB
references/products/attendance-vacation.mdmarkdown9.4 KB
references/products/attendance.mdmarkdown102.0 KB
references/products/calendar.mdmarkdown50.3 KB
references/products/chat-emoji-list.mdmarkdown8.4 KB
references/products/chat.mdmarkdown158.3 KB
references/products/chat/a2ui.mdmarkdown4.2 KB
references/products/contact.mdmarkdown30.5 KB
references/products/contract.mdmarkdown15.2 KB
references/products/dev.mdmarkdown14.7 KB
references/products/devdoc.mdmarkdown1.8 KB
references/products/ding.mdmarkdown9.9 KB
references/products/dingtalk-tag/capability.mdmarkdown5.7 KB
references/products/dingtalk-tag/dingtalk-tag-index.mdmarkdown3.9 KB
references/products/dingtalk-tag/manage-and-connect.mdmarkdown8.2 KB
references/products/dingtalk-tag/manage.mdmarkdown9.7 KB
references/products/dingtalk-tag/run.mdmarkdown5.4 KB
references/products/doc.mdmarkdown65.2 KB
references/products/doc/doc-block.mdmarkdown14.6 KB
references/products/doc/doc-comment.mdmarkdown9.9 KB
references/products/doc/doc-create.mdmarkdown6.6 KB
references/products/doc/doc-export.mdmarkdown3.5 KB
references/products/doc/doc-file-ops.mdmarkdown9.4 KB
references/products/doc/doc-import.mdmarkdown2.8 KB
references/products/doc/doc-info.mdmarkdown9.9 KB
references/products/doc/doc-list.mdmarkdown1.3 KB
references/products/doc/doc-media.mdmarkdown4.7 KB
references/products/doc/doc-permission.mdmarkdown4.9 KB
references/products/doc/doc-read.mdmarkdown8.5 KB
references/products/doc/doc-search.mdmarkdown1.4 KB
references/products/doc/doc-update.mdmarkdown15.5 KB
references/products/doc/doc-whiteboard.mdmarkdown3.9 KB
references/products/doc/format/doc-jsonml-cookbook.mdmarkdown25.0 KB
references/products/doc/format/doc-jsonml-schema.jsonconfig16.5 KB
references/products/doc/format/doc-jsonml-schema.mdmarkdown29.1 KB
references/products/doc/style/doc-create-workflow.mdmarkdown23.1 KB
references/products/doc/style/doc-style-guideline.mdmarkdown21.1 KB
references/products/doc/style/doc-update-workflow.mdmarkdown16.4 KB
references/products/drive.mdmarkdown65.4 KB
references/products/drive/drive-export.mdmarkdown2.6 KB
references/products/drive/drive-storage.mdmarkdown2.1 KB
references/products/drive/drive-task.mdmarkdown2.4 KB
references/products/event.mdmarkdown29.7 KB
references/products/hrbrain.mdmarkdown7.5 KB
references/products/html.mdmarkdown6.4 KB
references/products/mail.mdmarkdown88.1 KB
references/products/markdown.mdmarkdown11.4 KB
references/products/minutes.mdmarkdown173.8 KB
references/products/oa-template-write.mdmarkdown8.1 KB
references/products/oa.mdmarkdown61.7 KB
references/products/oa/oa-form-components.mdmarkdown33.7 KB
references/products/oa/oa-goout.mdmarkdown7.5 KB
references/products/oa/oa-leave.mdmarkdown7.2 KB
references/products/oa/oa-overtime.mdmarkdown10.1 KB
references/products/oa/oa-process-nodes.mdmarkdown11.6 KB
references/products/oa/oa-supply.mdmarkdown6.2 KB
references/products/oa/template/components/AddressField.mdmarkdown718 B
references/products/oa/template/components/CalculateField.mdmarkdown2.0 KB
references/products/oa/template/components/CascadeField.mdmarkdown1.1 KB
references/products/oa/template/components/ColumnLayout.mdmarkdown746 B
references/products/oa/template/components/DDAttachment.mdmarkdown586 B
references/products/oa/template/components/DDDateField.mdmarkdown857 B
references/products/oa/template/components/DDDateRangeField.mdmarkdown1.6 KB
references/products/oa/template/components/DDMultiSelectField.mdmarkdown1.3 KB
references/products/oa/template/components/DDPhotoField.mdmarkdown699 B
references/products/oa/template/components/DDSelectField.mdmarkdown1.2 KB
references/products/oa/template/components/DepartmentField.mdmarkdown789 B
references/products/oa/template/components/ExternalContactField.mdmarkdown751 B
references/products/oa/template/components/FormRelateField.mdmarkdown2.1 KB
references/products/oa/template/components/IdCardField.mdmarkdown709 B
references/products/oa/template/components/InnerContactField.mdmarkdown819 B
references/products/oa/template/components/InvoiceField.mdmarkdown1.1 KB
references/products/oa/template/components/MoneyField.mdmarkdown811 B
references/products/oa/template/components/NumberField.mdmarkdown807 B
references/products/oa/template/components/OcrIdCardField.mdmarkdown1.7 KB
references/products/oa/template/components/OcrTextField.mdmarkdown900 B
references/products/oa/template/components/PhoneField.mdmarkdown760 B
references/products/oa/template/components/RecipientAccountField.mdmarkdown746 B
references/products/oa/template/components/RelateField.mdmarkdown804 B
references/products/oa/template/components/SeqNumberField.mdmarkdown1.1 KB
references/products/oa/template/components/SignatureField.mdmarkdown722 B
references/products/oa/template/components/StarRatingField.mdmarkdown774 B
references/products/oa/template/components/TableField.mdmarkdown1.2 KB
references/products/oa/template/components/TextField.mdmarkdown775 B
references/products/oa/template/components/TextNote.mdmarkdown675 B
references/products/oa/template/components/TextareaField.mdmarkdown754 B
references/products/oa/template/components/TimeAndLocationField.mdmarkdown719 B
references/products/oa/template/example/form_components.jsonconfig7.3 KB
references/products/oa/template/example/process_config.jsonconfig22.7 KB
references/products/oa/template/form-components.mdmarkdown11.5 KB
references/products/oa/template/nodes/approver.mdmarkdown3.7 KB
references/products/oa/template/nodes/cc.mdmarkdown2.6 KB
references/products/oa/template/nodes/condition.mdmarkdown10.8 KB
references/products/oa/template/nodes/handler.mdmarkdown2.4 KB
references/products/oa/template/nodes/originator.mdmarkdown941 B
references/products/oa/template/nodes/parallel.mdmarkdown2.7 KB
references/products/oa/template/nodes/payer.mdmarkdown1.6 KB
references/products/oa/template/process-nodes.mdmarkdown8.8 KB
references/products/oa/template/rules/target_approval.mdmarkdown3.3 KB
references/products/oa/template/rules/target_connect_approval.mdmarkdown3.2 KB
references/products/oa/template/rules/target_formcomponent_approval.mdmarkdown1.2 KB
references/products/oa/template/rules/target_formula_managerOfDept.mdmarkdown1.5 KB
references/products/oa/template/rules/target_formula_reportLineManager.mdmarkdown1.5 KB
references/products/oa/template/rules/target_label.mdmarkdown3.9 KB
references/products/oa/template/rules/target_management.mdmarkdown1.3 KB
references/products/oa/template/rules/target_managers_labels.mdmarkdown1.3 KB
references/products/oa/template/rules/target_matrix_approval.mdmarkdown2.4 KB
references/products/oa/template/rules/target_originator.mdmarkdown698 B
references/products/oa/template/rules/target_select.mdmarkdown1.6 KB
references/products/openapi-explorer.mdmarkdown3.9 KB
references/products/pat.mdmarkdown1.8 KB
references/products/report.mdmarkdown29.9 KB
references/products/sheet.mdmarkdown16.2 KB
references/products/sheet/sheet-batch-operations.mdmarkdown7.7 KB
references/products/sheet/sheet-chart.mdmarkdown3.9 KB
references/products/sheet/sheet-comment.mdmarkdown7.9 KB
references/products/sheet/sheet-conditional-format.mdmarkdown4.5 KB
references/products/sheet/sheet-dimension-operations.mdmarkdown3.7 KB
references/products/sheet/sheet-dropdown.mdmarkdown6.7 KB
references/products/sheet/sheet-export.mdmarkdown8.6 KB
references/products/sheet/sheet-filter-view.mdmarkdown3.7 KB
references/products/sheet/sheet-filter.mdmarkdown10.0 KB
references/products/sheet/sheet-formula.mdmarkdown10.0 KB
references/products/sheet/sheet-import.mdmarkdown2.6 KB
references/products/sheet/sheet-media-image.mdmarkdown13.9 KB
references/products/sheet/sheet-pivot-table.mdmarkdown12.6 KB
references/products/sheet/sheet-range-operations.mdmarkdown8.7 KB
references/products/sheet/sheet-read-data.mdmarkdown4.0 KB
references/products/sheet/sheet-revision-changeset.mdmarkdown3.2 KB
references/products/sheet/sheet-search-replace.mdmarkdown6.3 KB
references/products/sheet/sheet-style-format.mdmarkdown4.5 KB
references/products/sheet/sheet-version.mdmarkdown5.0 KB
references/products/sheet/sheet-workbook.mdmarkdown4.3 KB
references/products/sheet/sheet-write-data.mdmarkdown7.8 KB
references/products/simple.mdmarkdown2.6 KB
references/products/todo.mdmarkdown21.0 KB
references/products/whiteboard.mdmarkdown19.7 KB
references/products/whiteboard/compose.mdmarkdown5.7 KB
references/products/whiteboard/diff.mdmarkdown3.7 KB
references/products/whiteboard/open-nodes-v1.mdmarkdown4.0 KB
references/products/whiteboard/open-nodes-v1/01-overview.mdmarkdown3.3 KB
references/products/whiteboard/open-nodes-v1/02-query.mdmarkdown7.3 KB
references/products/whiteboard/open-nodes-v1/03-update.mdmarkdown8.6 KB
references/products/whiteboard/open-nodes-v1/04-text-style.mdmarkdown11.8 KB

references/products/chat.md

View on GitHub
# 会话与群聊 (chat) 命令参考

## 命令总览

## Shortcut 优先路由

常见 Agent 意图优先使用公开 `+` Shortcut;下面的原子命令章节保留给需要特定原始返回结构、兼容参数或 Shortcut 未覆盖字段的场景。执行前用 `dws schema --cli-path "chat +<shortcut>" --compact --format json` 读取最终参数、约束和确认语义。

| 意图 | 首选 |
|---|---|
| 以 current-user / bot / webhook 身份发消息 | `dws chat +messages-send --as <identity> ...`;Bot 多群用 `--groups/--groups-file` |
| 拉取单个群聊或单聊的消息 | `dws chat +chat-messages ...`;全量加 `--page-all`,导出加 `--output` |
| 按关键词、发送者、@对象、会话、类型或时间组合搜索 | `dws chat +search-msg ...` |
| 查询最近 24 小时或指定时间以来有新消息的去重会话摘要 | `dws chat +recent-conversations`;可选 `--start/--end`,自动翻页并返回名称、类型和最新消息时间 |
| 查询 @我的消息 | `dws chat +at-me ...` |
| 根据消息 ID 批量取详情与 reaction | `dws chat +messages-mget ...` |
| 读取已知 thread/topic 的全部回复 | `dws chat +thread-replies ...` |
| 下载单个 mediaId/fileId | `dws chat +messages-resource-download ...` |

- `+messages-send` 只暴露下层真实支持的身份能力:user 支持文本/Markdown、已有 mediaId 图片、本地文件和幂等键;bot 支持群聊、最多 100 个稳定群 ID 的逐项 ledger 或批量单聊文本/Markdown;webhook 的目标由 token 所在群决定。该 Shortcut 的 Bot/Webhook 路由不支持富媒体。
- 需要机器人发送公网图片 URL 或本地文件时,直接使用 `chat message send-by-bot`;它分别支持 `--msg-type image --image-url` 和 `--msg-type file --file-path`。
- `+chat-messages --page-all` 连续读取 typed `nextPage.time`,按消息 ID 去重并受 `--page-limit/--max-results` 约束;`--output` 将同一完整性 ledger 原子写入工作目录内 JSON。
- `+messages-send` 会自动规范化并补齐 @ 占位符。user 使用 `<@id>` / `<@all>`;bot/webhook 使用 `@id` / `@手机号` / `@all`。声明 `--at-*` / `--at-all` 即可,不要为统一 Shortcut 手工拼 `@10`。
- `+search-msg --page-all` 连续翻页并默认按消息 ID 批量富化;任何续页或富化失败都会保留已取得结果并返回逐项失败 ledger。
- `+active-conversations` 保留为隐藏但可执行的兼容入口;新调用使用 `+recent-conversations`。两者共用参数、校验和查询实现,使用旧名不会额外告警。
- `+recent-conversations` 的 `--start` 选填,省略时从有效 `--end` 往前推 24 小时;两个时间参数都省略即查询最近 24 小时,仅传 `--end` 即查询该结束时间之前 24 小时,不是当天零点。显式 `--start` 沿用原解析规则,空值或纯空白仍报错。自动翻页并按 `openConversationId` 去重;`--page-delay` 默认 200ms(0–60000ms,等待可取消)。会话总有 `name` 和 `nameKnown`,未知名称为 `""` / `false`。成功及页数上限结果在 `data`,需检查 `complete` 和 `meta.pagination`;`pageSize` 记录 `--limit`。
- `+recent-conversations` 的 `--start/--end` 仅支持整秒,显式传入非零小数秒会在参数校验时失败。默认 `end` 是本次查询取到的当前时间向下取整秒,不包含当前尚未结束的这一秒,再从有效 `end` 倒推默认 `start`;最终有效区间必须满足 `end > start`。同一 `start/end` 用于所有页请求、结果返回和续查;消息 `latestMessageTime` 仍保留毫秒精度。非首页 `--cursor` 必须显式复用原 `--start/--end`,否则校验失败,不能重新使用默认窗口。
- `+recent-conversations` 后续页失败返回 `partial_failure`(退出码 7):已成功页面摘要在 `data.succeeded[0]`(`id=completed-pages`,`complete=false`),失败项在 `data.failed[0]`(`id=page:N`,其 `error.details.failedPage/failedCursor` 保留失败位置),`meta.pagination.next_token` 指向失败页输入游标;首个请求页失败返回普通 `failure`。先排查错误,不自动重试。`--cursor` 用于手工续查,不能跨次校验查询绑定或检测循环,也不恢复旧聚合;必须保持同一 profile,复用摘要中的 `start/end/pageSize` 作为 `--start/--end/--limit`,前后批次按 `conversationId` 合并并保留最大消息时间。续页自身的 `complete` 始终为 false;只有从首页起无遗漏地接续所有批次、处理完失败页且 endpoint 耗尽,才能报告全量结果。分页耗尽不保证上游索引无延迟或一致性快照。
- `+recent-conversations` 不保存磁盘进度,强制终止后需重新查询;游标过期需从首页重查。`pagesFetched` 仅计本次已验证页面。`--total-timeout` 默认 300 秒(1–3600),每次执行所有页、重试和等待共用预算;全局 `--timeout` 仍约束单次请求。
- `+at-me`、`+chat-messages`、`+messages-mget`、`+search-msg`、`+thread-replies` 可用 `--download-resources` 下载资源。引用、回复、合并转发中的资源使用结果 `resourceRefs` 自带的子消息 `messageId`;仅当子消息缺会话 ID 时继承父消息 `openConversationId`。
- 上述五个查询 Shortcut 与 `+messages-resource-download` 都沿用安全本地下载的 `read/not_required` 契约,不应添加 `--yes` 或触发交互确认。下载只允许工作目录内相对路径、默认不覆盖并原子落盘;需要覆盖时必须由用户显式传 `--overwrite`。
- 下载器仅接受经审查的钉钉与公网 OSS HTTPS 地址并逐跳校验重定向;跨主机时不会转发下层提供的请求头。新官方域名被拒绝时记录错误中的 host 供审查,不要放宽为任意 HTTPS。

### group (群组管理)

#### 创建群 — 当前登录用户自动成为群主
```
Usage:
  dws chat group create [flags]
Example:
  dws chat group create --name "Q1 项目冲刺群" --users userId1,userId2,userId3
Flags:
      --users string    成员 userId 列表,用户本身会自动加入,无需包含,逗号分隔,不超过20个 (必填)
      --name string     群名称 (必填)
```

#### 查看群成员列表 — 分页查询指定群聊的成员
```
Usage:
  dws chat group members [flags]
Example:
  dws chat group members --id <openconversation_id>
Flags:
      --cursor string   分页游标,首次从 0 开始
      --id string       群 ID / openconversation_id (必填)
```

#### 添加群成员 — 向指定群聊添加成员,需传入群 ID 与用户 ID 列表
```
Usage:
  dws chat group members add [flags]
Example:
  dws chat group members add --id <openconversation_id> --users userId1,userId2
Flags:
      --id string      群 ID / openconversation_id (必填)
      --users string   要添加的用户 userId 列表,逗号分隔 (必填)
```

#### 移除群成员 — 从指定群聊中移除成员,需传入群 ID 与待移除的用户 ID 列表
```
Usage:
  dws chat group members remove [flags]
Example:
  dws chat group members remove --id <openconversation_id> --users userId1,userId2
Flags:
      --id string      群 ID / openconversation_id (必填)
      --users string   要移除的用户 userId 列表,逗号分隔 (必填)
```
> 移除对象是群主时 CLI 会拦截并报错,提示先用 `chat group transfer-owner` 转让群主(防止产生无主群);查不到群主时放行。

#### 将机器人添加到群中 — 将自定义机器人添加到当前用户有管理权限的群聊中,如果没有权限则会报错
```
Usage:
  dws chat group members add-bot [flags]
Example:
  dws chat group members add-bot --robot-code <robot-code> --id <openconversation_id>
Flags:
      --id string           群聊 openConversationId (必填)
      --robot-code string   机器人 Code (必填)
```

#### 从群内移除机器人 — 将指定机器人从群聊中移除,需要群管理员或群主权限
```
Usage:
  dws chat group members remove-bot [flags]
Example:
  dws chat group members remove-bot --id <openConversationId> --bot-id <openBotId>
  # 查询群 ID: dws chat search --query "群名"
  # 查询群内机器人: dws chat group bots --group <openConversationId>
Flags:
      --id string       群聊 openConversationId (必填)
      --bot-id string   机器人 openBotId (必填)
```

#### 根据成员 ID 批量查询群成员详情 — 传入成员 openDingTalkId 列表批量查询
```
Usage:
  dws chat group members list-by-ids [flags]
Example:
  dws chat group members list-by-ids --id <openConversationId> --users openDingTalkId1,openDingTalkId2
  # 查询群 ID: dws chat search --query "群名"
  # 查询 openDingTalkId: dws contact user search --query "姓名"
Flags:
      --id string      群 ID / openConversationId (必填)
      --users string   成员 openDingTalkId 列表,逗号分隔 (必填)
```

#### 更新群名称
```
Usage:
  dws chat group rename [flags]
Example:
  dws chat group rename --id <openconversation_id> --name "新群名"
Flags:
      --id string     群 ID / openconversation_id (必填)
      --name string   修改后的群名称 (必填)
```

#### 根据群号获取群聊信息 — 当用户只提供了数字群号而非 openConversationId 时,用此命令转换
```
Usage:
  dws chat group get-by-group-id [flags]
Example:
  dws chat group get-by-group-id --group-id 12345678
  # 群号为数字类型的群ID
Flags:
      --group-id int   群号 (必填,数字类型)
```

#### 转让群主 — 将群主身份转让给群内其他成员
```
Usage:
  dws chat group transfer-owner [flags]
Example:
  dws chat group transfer-owner --group <openConversationId> --new-owner <openDingTalkId>
  dws chat group transfer-owner --group <openConversationId> --user <userId>
  # 查询群 ID: dws chat search --query "群名"
  # 查询人员: dws aisearch person --query "姓名" --dimension name
Flags:
      --group string       群聊 openConversationId (必填)
      --new-owner string   新群主 openDingTalkId
      --user string        新群主 userId
```

#### 将普通群升级为外部群 — 不可逆,仅群主可执行
```
Usage:
  dws chat group upgrade-to-external [flags]
Example:
  dws chat group upgrade-to-external --group <openConversationId> --dry-run
  dws chat group upgrade-to-external --group <openConversationId> --extension '{"source":"dws"}' --dry-run
Flags:
      --group string      待升级普通群的 openConversationId (必填)
      --extension string  预留扩展字段 JSON 对象;对象值必须是字符串 (可选)
      --dry-run           预览操作,不实际升级
      --yes               确认执行不可逆升级
```

仅 `NORMAL_GROUP` 普通群可升级;新建外部群使用 `chat group create --type EXTERNAL`。正式执行前必须确认目标群和影响,再传 `--yes`。

#### 获取群邀请链接 — 获取指定群聊的邀请加入链接

可选 --expires-seconds 指定链接有效期(秒),0 表示永久有效,不传则使用服务端默认值。
```
Usage:
  dws chat group invite-url [flags]
Example:
  dws chat group invite-url --group <openConversationId>
  dws chat group invite-url --group <openConversationId> --expires-seconds 86400
  dws chat group invite-url --group <openConversationId> --expires-seconds 0
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string            群聊 openConversationId (必填)
      --expires-seconds int64   链接有效期(秒),0 表示永久有效,不传使用服务端默认值
```

#### 分享群聊链接到会话 — 将指定群的邀请链接分享到另一个会话或单聊用户

`--target` 和 `--receiver` 二选一:`--target` 指定目标会话,`--receiver` 指定单聊用户。

```
Usage:
  dws chat group share-invite [flags]
Example:
  dws chat group share-invite --source <被分享群openConversationId> --target <目标会话openConversationId>
  dws chat group share-invite --source <被分享群openConversationId> --receiver <接收者openDingTalkId>
  dws chat group share-invite --source <openConversationId> --target <openConversationId> --expires-seconds 86400
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --source string            被分享群的 openConversationId (必填)
      --target string            接收分享消息的会话 openConversationId(与 --receiver 二选一)
      --receiver string          接收分享消息的单聊用户 openDingTalkId(与 --target 二选一)
      --expires-seconds int64    链接有效期(秒),0 表示永久有效,不传使用服务端默认值
      --uuid string              消息幂等键(可选)
```

#### 退出群聊 — 当前用户退出指定群聊
```
Usage:
  dws chat group quit [flags]
Example:
  dws chat group quit --group <openConversationId>
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string   群聊 openConversationId (必填)
```
> ⚠️ 唯一群主 quit 会直接成功,产生无主群,之后对该群做 dismiss / members 等管理操作会报 listRoles null(11056) 无法管理。与 `chat group members remove` 移除群主有本地拦截不同,quit 无此防护。作为唯一群主想退群,应先 `chat group transfer-owner` 转让群主,或 `chat group dismiss` 解散群。

#### 更新群头像 — 更新指定群聊的群头像
```
Usage:
  dws chat group update-icon [flags]
Example:
  dws chat group update-icon --group <openConversationId> --icon-media-id <mediaId>
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string          群聊 openConversationId (必填)
      --icon-media-id string  群头像 mediaId (必填)
```
> `--icon-media-id` 有本地格式校验:必须是 `@` 开头的、由可信上游提供的媒体 ID,非法格式会在本地直接报错。
> ⚠️ 本地格式校验只查前缀。格式合法但不真实存在的 mediaId 服务端仍会静默返回成功,头像并不会真正更新。务必使用真实上游媒体上传能力拿到有效 mediaId;DWS CLI 不提供本地文件到 mediaId 的上传命令。

#### 更新群设置 — 更新指定群聊的设置项

--setting-key 指定设置项,--status 指定值(0=关闭,1=开启)。

支持的 settingKey:
  authority、joinValidation、onlyAdminCanAtAll、searchable、addFriendForbidden、
  toolbarStatus、pluginCustomizeVerify、onlyAdminCanDING、allMembersCanCreateMcsConf、
  onlyAdminCanSetMsgTop、onlyAdminCanPinMsg、onlyAdminCanSendFile、
  allMembersCanCreateCalendar、groupEmailDisabled、groupRedEnvelopeSwitch、
  groupLiveAuthority、groupBillAuthority
```
Usage:
  dws chat group update-settings [flags]
Example:
  dws chat group update-settings --group <openConversationId> --setting-key searchable --status 1
  dws chat group update-settings --group <openConversationId> --setting-key onlyAdminCanAtAll --status 0
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string        群聊 openConversationId (必填)
      --setting-key string  群设置项 key (必填)
      --status int          设置值: 0=关闭, 1=开启 (必填)
```

#### 设置群备注 — 给群设置只有自己可见的备注标题
```
Usage:
  dws chat group update-alias [flags]
Example:
  dws chat group update-alias --group <openConversationId> --alias-title "项目A群"
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string         群聊 openConversationId (必填)
      --alias-title string   群备注标题 (必填)
```

#### 设置或清除我在群内的群昵称
```
Usage:
  dws chat group update-nick [flags]
Example:
  dws chat group update-nick --group <openConversationId> --nick "我的群昵称"
  dws chat group update-nick --group <openConversationId>
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string   群聊 openConversationId (必填)
      --nick string    个人群昵称;不传则清除当前群昵称
```

#### 查看群内所有机器人 — 获取指定群聊中的所有机器人列表
```
Usage:
  dws chat group bots [flags]
Example:
  dws chat group bots --group <openConversationId>
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string   群聊 openConversationId (必填)
```

#### 解散群聊 — 解散指定群聊,操作不可逆,需要群主权限

> **CAUTION:** 解散群聊不可恢复(群聊与全部消息一并消失)。执行前必须向用户确认,同意后追加全局 `--yes` 执行(未加时 CLI 返回确认门禁错误)。

```
Usage:
  dws chat group dismiss [flags]
Example:
  dws chat group dismiss --group <openConversationId>
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string   群聊 openConversationId (必填)
```

#### 设置新成员入群可查看历史消息选项 — 控制新加入成员可见的历史消息范围
```
Usage:
  dws chat group set-history [flags]
Example:
  dws chat group set-history --group <openConversationId> --option RECENT_100
  dws chat group set-history --group <openConversationId> --option FORBIDDEN
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string    群聊 openConversationId (必填)
      --option string   可见范围: FORBIDDEN | RECENT_100 | ALL (必填)

注意:
  - FORBIDDEN:禁止查看历史消息(默认安全策略)
  - RECENT_100:可查看最近 100 条消息(最常用)
  - ALL:可查看全部历史消息(开放性最高)
```

#### 拉取我创建/管理的群 — 查询当前用户作为群主或管理员的群列表

可通过 --role 过滤角色:OWNER 仅群主、ADMIN 仅管理员,不传则返回全部。可通过 --limit 限制返回数量,不传则返回所有符合条件的群。
```
Usage:
  dws chat group list-my-groups [flags]
Example:
  dws chat group list-my-groups
  dws chat group list-my-groups --role OWNER
  dws chat group list-my-groups --role ADMIN --limit 10
Flags:
      --role string    角色过滤: OWNER(仅群主) / ADMIN(仅管理员),不传返回全部
      --limit int      最多返回群数量,不传返回全部

注意:
  - 底层先拉取最近 1000 条会话,剔除单聊和话题圈后筛选出群主/管理员的群
  - 内部群会校验 orgId 归属
  - 不传 --role 时返回群主 + 管理员的所有群
```

### group notice (群公告管理)

#### 发布群公告 — 在指定群聊中发布群公告,支持 Markdown、定时发布

```
Usage:
  dws chat group notice create [flags]
Example:
  dws chat group notice create --group <openConversationId> --content "今晚 22 点系统维护,请提前保存工作内容"
  dws chat group notice create --group <openConversationId> --content "# 重要通知\n请大家查收" --sticky --send-ding
  dws chat group notice create --group <openConversationId> --content "明早九点例会" --run-at "2026-07-03T09:00:00+08:00"
Flags:
      --group string       群聊 openConversationId (必填)
      --content string     公告正文,Markdown 格式 (必填)
      --sticky             是否吊顶置顶(默认 false)
      --send-ding          是否发 DING 提醒(默认 false)
      --run-at string      定时发布时间 ISO-8601(传入则定时发布)
```

#### 修改群公告 — 整体替换指定群公告的内容
```
Usage:
  dws chat group notice edit [flags]
Example:
  dws chat group notice edit --group <openConversationId> --notice-id <dataId> --content "更新后的公告内容"
Flags:
      --group string       群聊 openConversationId (必填)
      --notice-id string   群公告 dataId (必填)
      --content string     公告新正文,Markdown 格式 (必填)
      --sticky             是否吊顶置顶
      --send-ding          是否发 DING 提醒
```

#### 查看群公告详情
```
Usage:
  dws chat group notice get [flags]
Example:
  dws chat group notice get --group <openConversationId> --notice-id <dataId>
Flags:
      --group string       群聊 openConversationId (必填)
      --notice-id string   群公告 dataId (必填)
```

#### 查看群公告列表
```
Usage:
  dws chat group notice list [flags]
Example:
  dws chat group notice list --group <openConversationId>
  dws chat group notice list --group <openConversationId> --limit 20 --cursor <nextPageCursor>
  dws chat group notice list --group <openConversationId> --scheduled
Flags:
      --group string    群聊 openConversationId (必填)
      --limit int       每页返回数量(默认 10,最大 100)
      --cursor string   分页游标
      --scheduled       是否查询定时公告列表
```

### group-role (群身份管理)

#### 查看群身份列表 — 拉取指定群聊的自定义群身份列表
```
Usage:
  dws chat group-role list [flags]
Example:
  dws chat group-role list --group <openConversationId>
Flags:
      --group string   群聊 openConversationId (必填)
```

#### 添加群身份 — 在指定群中创建一个新的自定义群身份
```
Usage:
  dws chat group-role add [flags]
Example:
  dws chat group-role add --group <openConversationId> --name "管理员"
Flags:
      --group string   群聊 openConversationId (必填)
      --name string    群身份名称 (必填)
```

#### 更新群身份名称 — 修改指定群身份的名称
```
Usage:
  dws chat group-role update [flags]
Example:
  dws chat group-role update --group <openConversationId> --role-id <openRoleId> --name "新名称"
Flags:
      --group string     群聊 openConversationId (必填)
      --role-id string   群身份 openRoleId,由 group-role list 返回 (必填)
      --name string      群身份新名称 (必填)
```

#### 删除群身份 — 删除指定群聊中的某个自定义群身份
```
Usage:
  dws chat group-role remove [flags]
Example:
  dws chat group-role remove --group <openConversationId> --role-id <openRoleId>
Flags:
      --group string     群聊 openConversationId (必填)
      --role-id string   群身份 openRoleId,由 group-role list 返回 (必填)
```

#### 设置用户群身份 — 覆盖指定用户在群中的全部群身份
```
Usage:
  dws chat group-role set-user [flags]
Example:
  dws chat group-role set-user --group <openConversationId> --user <userId> --role-id <openRoleId>
  # 查询人员: dws aisearch person --query "姓名" --dimension name
  # 查询 role-id: dws chat group-role list --group <openConversationId>
Flags:
      --group string     群聊 openConversationId (必填)
      --user string      用户 userId(必填)
      --role-id string   群身份 openRoleId,由 group-role list 返回
```

#### 移除用户的指定群身份 — 从用户身上移除指定的群身份(不影响其他群身份)

> ⚠️ 当前不可用:该命令当前调用常失败(服务端返回 1002 系统繁忙),多为服务端侧限制。set-user 会清掉该用户的**全部**身份,无法只移除其中一个。
```
Usage:
  dws chat group-role remove-user [flags]
Example:
  dws chat group-role remove-user --group <openConversationId> --user <userId> --role-ids roleId1,roleId2
Flags:
      --group string      群聊 openConversationId (必填)
      --user string       用户 userId(必填)
      --role-ids string   要移除的群身份 openRoleId 列表,逗号分隔 (必填)
```

#### 查询群成员的群身份 — 查询指定群成员当前持有的所有群身份
```
Usage:
  dws chat group-role query-user [flags]
Example:
  dws chat group-role query-user --group <openConversationId> --user <userId>
Flags:
      --group string   群聊 openConversationId (必填)
      --user string    用户 userId(必填)
```

### search (搜索群聊)

#### 根据关键词搜索群聊 — 分页返回匹配群聊列表

hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。

**注意:**
1. query 不要拆分得太细,应使用群名称中连续的核心词作为关键词(如群名"项目冲刺群"应搜"项目冲刺"而非拆成"项目"+"冲刺"分别搜索)。
2. 当搜索结果返回多个群聊时,应列出候选群让用户确认目标群聊,不要自行假定并直接进行后续操作。

```
Usage:
  dws chat search [flags]
Example:
  dws chat search --query "项目冲刺"
  dws chat search --query "项目冲刺" --limit 20 --cursor 0
Flags:
      --query string   搜索关键词 (必填)
      --limit int        每页返回数量(默认 20)
      --cursor string    分页游标(默认 "0",翻页传 nextCursor)
      --exclude-muted    是否排除已设置免打扰的群聊(默认 false)
```

### data-auth (数据授权)

#### 跨组织数据授权 — 授予 chat 跨组织消息拉取权限

用于跨组织消息拉取等数据访问场景,不用于发送、撤回、群管理等操作。该命令调用 `chat_permission_grant`,固定使用数据授权类别:`scope=chat.data:cross-org`、`grantCategory=data`。

```
Usage:
  dws chat data-auth cross-org [flags]

Example:
  dws chat data-auth cross-org --target-org-id 439446171 --format json
  dws chat data-auth cross-org --target-org-id 439446171 --agentCode wukong --grant-type timed --ttl 24h --format json
  dws chat data-auth cross-org --all --grant-type timed --ttl 24h --format json

Flags:
      --target-org-id string   目标组织 ID(与 --all 二选一)
      --all                    授权所有目标组织
      --agentCode string       Agent 标识,默认 wukong
      --grant-type string      授权策略: once|session|timed|permanent (default "timed")
      --ttl string             timed 授权有效期,如 1h/4h/24h/7d (default "24h")
      --session-id string      session 授权的会话标识

注意:
  - --target-org-id 和 --all 必须且只能指定一个。
  - --grant-type=session 时必须传 --session-id。
  - --grant-type=timed 时必须传 --ttl。
```

### message (会话消息管理)

#### 拉取会话消息内容 — 拉取指定群聊或单聊的会话消息内容

--group 指定群聊,--user 指定单聊用户(通过 userId),--open-dingtalk-id 指定单聊用户(通过 openDingTalkId),三者互斥。用 --direction 控制时间方向:newer=从给定时间往现在拉,older=从给定时间往以前拉。hasMore=true 时用结果中的边界 createTime 作为下次 --time 翻页。引用回复消息会带 `quotedMessage`;被引用的原消息是合并转发或图片时,其类型与内容也会保留在引用上下文中。
```
Usage:
  dws chat message list [flags]
Example:
  dws chat message list --group <openconversation_id> --time "2025-03-01 00:00:00"
  dws chat message list --user <userId> --time "2025-03-01 00:00:00" --limit 50
  dws chat message list --open-dingtalk-id <openDingTalkId> --time "2025-03-01 00:00:00" --limit 50
  dws chat message list --group <openconversation_id> --time "2025-03-01 00:00:00" --direction older
Flags:
      --direction string         时间方向: newer=从给定时间往现在拉,older=从给定时间往以前拉(推荐)
      --group string             群聊 openconversation_id(群聊时必填)
      --limit int                返回数量,不传则不限制
      --time string              开始时间,格式: yyyy-MM-dd HH:mm:ss (必填)
      --user string              单聊用户 userId(单聊时与 --open-dingtalk-id 二选一)
      --open-dingtalk-id string  单聊用户 openDingTalkId(单聊时与 --user 二选一,适用于三方应用等无法获取 userId 的场景)

注意:
  - --group、--user、--open-dingtalk-id 三者互斥,只需指定其一:群聊用 --group,单聊用 --user 或 --open-dingtalk-id
  - --user 和 --open-dingtalk-id 都是发起单聊消息拉取,区别在于用不同格式的用户标识:
    - --user 传 userId(企业内部应用常用)
    - --open-dingtalk-id 传 openDingTalkId(三方应用或跨组织场景常用,无法获取 userId 时使用)
  - --group 的别名: --id, --chat, --conversation-id (均可替代 --group)
  - 翻页:hasMore=true 时,用结果中的边界 createTime 作为下次 --time
  - 自动翻页:显式加 `--page-all` 后 CLI 按边界时间连续拉取全部页并按消息 ID 去重,`--page-limit` 控制最多请求页数(默认 50,范围 1-500),`--max-items` 控制最多输出条数(默认 0 不限制,精确截断并置 `truncatedByResultLimit=true`),`--page-delay` 控制页间等待毫秒数(默认 200,0 表示不等待);只传这些分页控制参数但不传 `--page-all` 时仍保持原单页调用
  - 处理引用回复时读取 quotedMessage,不要只看回复正文;合并转发与图片引用的原消息内容也在该上下文中
  - 话题圈是群会话容器,使用 `openConversationId`;群内一条 Thread 使用 `openConvThreadId`。浏览主话题使用 `dws chat thread list --conversation-id <openConversationId>`;需要逐条查看回复正文或核实具体回复是否仍存在时,使用 `dws chat thread list-replies --conversation-id <openConversationId> --topic-id <openConvThreadId>`。
```

#### 以当前用户身份发送消息 — --group 群聊 / --user 或 --open-dingtalk-id 单聊

**重要:该接口会真实发送消息到目标会话,不可用于测试或试探性调用。调用前必须确认消息内容和接收对象无误。**

--group 指定群聊 openConversationId 发群消息;--user 指定用户 userId 发单聊;--open-dingtalk-id 指定用户 openDingTalkId 发单聊。三者只能选其一,不能同时指定。纯文本/Markdown 单聊传 --user 时直接走 userId 发送能力,不需要先手动查询 openDingTalkId。推荐使用 --content flag 传递消息内容(也支持位置参数)。可选 --title 作为消息标题。
图文混排 Markdown 中,公网图片 URL 需要写成 `![图片标题](https://example.com/image.png)` 才会以内联图片展示;省略开头的 `!` 时会按链接/URL 展示,不会渲染为图片。
若用户只提供了数字群号而非 openConversationId,需先调用 `chat group get-by-group-id` 将群号转为 openConversationId,再传入 --group。
--群聊时可选 --at-all @所有人,或 --at-open-dingtalk-ids 指定成员(仅群聊时生效)。
--本地图片、文件、音频或视频统一用 --msg-type file --file;图片会作为可下载的文件附件发送。--msg-type image --media-id 仅用于上游已经提供有效 mediaId 的场景。
```
Usage:
  dws chat message send [flags] [<content>]

富媒体消息路由:
  场景                                     → msgType → 发送参数
  本地图片/文件/音频/视频                   → file    → --file <本地路径>
  上游已提供有效 mediaId 的内联图片          → image   → --media-id <mediaId>

  注意:本地 .png/.jpg 也按 file 发送,接收方看到的是可下载附件;DWS CLI 不能把本地文件转换成 mediaId。

Example:
  dws chat message send --conversation-id <openconversation_id> --content "hello"
  dws chat message send --user <userId> --content "请查收"
  dws chat message send --open-dingtalk-id <openDingTalkId> --content "请查收"
  dws chat message send --conversation-id <openconversation_id> "hello"
  dws chat message send --conversation-id <openconversation_id> --title "周报提醒" --content "请大家本周五前提交周报"
  # 图文混排 Markdown:公网图片 URL 需要写成 ![图片标题](URL) 才会以内联图片展示
  dws chat message send --conversation-id <openconversation_id> --content $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)'
  # 幂等发送(24h 内相同 idempotency key 不重复投递)
  dws chat message send --conversation-id <openconversation_id> --content "hello" --idempotency-key "unique-id-123"
  dws chat message send --conversation-id <openconversation_id> --at-all "<@all> 请大家注意"
  dws chat message send --conversation-id <openconversation_id> --at-open-dingtalk-ids openDingTalkId1,openDingTalkId2 "<@openDingTalkId1> <@openDingTalkId2> 请查收"
  # 本地图片/文件/音频/视频统一作为 file 附件发送
  dws chat message send --conversation-id <openconversation_id> --msg-type file --file ./screenshot.png
  dws chat message send --conversation-id <openconversation_id> --msg-type file --file ./report.pdf
  dws chat message send --conversation-id <openconversation_id> --msg-type file --file ./recording.mp3
  dws chat message send --conversation-id <openconversation_id> --msg-type file --file ./demo.mp4
  # 仅当上游已有有效 mediaId 时发送内联图片
  dws chat message send --conversation-id <openconversation_id> --msg-type image --media-id <mediaId>
Flags:
      --content string           消息内容(推荐使用,也可用位置参数)
      --conversation-id string   群聊 openconversation_id(群聊时必填)
      --group string             --conversation-id 的兼容别名
      --user string              单聊接收人 userId(单聊时与 --open-dingtalk-id 二选一)
      --open-dingtalk-id string  单聊接收人 openDingTalkId(单聊时与 --user 二选一)
      --title string             消息标题(可选,默认「消息」)
      --at-all                   @所有人(仅群聊时生效,可选,默认 false)
      --at-open-dingtalk-ids string  @指定成员的 openDingTalkId 列表,逗号分隔(仅群聊时生效,可选)
      --media-id string          上游提供的有效图片 mediaId(仅 msgType=image)
      --msg-type string          消息类型: image/file/audio/video(本地文件统一使用 file;image 仅配合已有 mediaId)
      --dentry-id int64          已有钉盘文件 dentryId(兼容参数,非本地文件发送的默认路径)
      --space-id int64           已有钉盘文件空间 ID(元数据兼容模式)
      --file-name string         已有钉盘文件名(元数据兼容模式)
      --file-type string         已有钉盘文件类型/扩展名(元数据兼容模式)
      --file string              本地文件路径(本地图片/文件/音视频配合 msgType=file 使用)
      --file-size int64          已有钉盘文件大小,单位字节(元数据兼容模式)
      --idempotency-key string   幂等键,相同 key 在 24h 内不会重复发送(可选)
      --ai-tag                   消息是否带 AI 发送角标(可选,默认 true)

注意:
  - --content 和位置参数二选一,--content 优先
  - --conversation-id、--user、--open-dingtalk-id 三者互斥,只需指定其一:群聊用 --conversation-id,单聊用 --user 或 --open-dingtalk-id
  - 纯文本/Markdown 单聊发送时 `--user` 和 `--open-dingtalk-id` 都可用;传 `--user` 时直接走 userId 发送能力
  - --conversation-id 的兼容别名: --group, --id, --chat
  - --at-all 和 --at-open-dingtalk-ids 仅在 --conversation-id 群聊时生效,单聊时无效;当设置--at-all时,消息内容中一定要包含对应的占位符<@all>;当设置--at-open-dingtalk-ids openDingTalkId1,openDingTalkId2时,消息内容中一定要包含对应格式的占位符<@openDingTalkId1> <@openDingTalkId2>
  - **换行符**:消息内容按 Markdown 渲染,换行有两层要求,缺一不可:
    1. 必须使用**真实换行符**(Unicode `U+000A`),而非字面量字符串 `\n`(反斜杠 + 字母 n)。程序或大模型构造参数时,须确保已正确反转义;否则全部内容会渲染在同一行
    2. Markdown 规范下**单个换行不产生换行效果**。需要换行时请使用:段落分隔(连续两个真实换行符 `\n\n`)、行尾两个空格 + 真实换行符(硬换行 `<br>`),或直接写 HTML 的 `<br>` 标签
  - **图文混排**:公网图片 URL 需要写成 `![图片标题](https://example.com/image.png)` 才会以内联图片展示;如果省略开头的 `!`,例如 `[图片标题](https://example.com/image.png)`,将按链接/URL 展示,不会渲染为图片
  - 本地图片、文档、压缩包、音频和视频统一使用 `--msg-type file --file <本地路径>`;图片会成为可下载的 file 附件,不会内联渲染,也不会生成 mediaId
  - `--msg-type image --media-id` 仅接受上游已经提供的有效 mediaId;DWS CLI 不提供本地文件到 mediaId 的上传或转换能力
  - audio/video 仍是兼容的 file 语义别名,但本地文件的推荐路径保持为 `--msg-type file --file`
  - dentryId/spaceId 等参数仅用于调用方已经持有钉盘文件元数据的兼容场景,不是发送本地文件的前置步骤
  - --idempotency-key 用于幂等发送,传入相同 key 在 24h 内不会重复投递消息;旧参数 --uuid 保留兼容(可选,群聊和单聊均支持)
  - 富媒体消息的单聊优先使用 `--open-dingtalk-id`;传 `--user` 时 CLI 会尝试解析成 openDingTalkId 后发送
  - 发送文字 + 文件时,先发送 `--msg-type file --file` 文件消息,再补一条文本或 Markdown 说明;这是两条独立消息
```

### conversation-file(会话文件空间上传)

#### chat conversation-file upload

把工作目录内的本地文件上传到指定群聊或单聊的会话文件空间,只返回文件标识,不发送聊天消息:
```
dws chat conversation-file upload --conversation-id <openConversationId> --file ./report.pdf --format json
dws chat conversation-file upload --open-dingtalk-id <openDingTalkId> --file ./report.pdf --format json
```

成功结果返回 `dentryId`、`spaceId`、`fileName`、`fileType` 和 `fileSize`,可供后续需要会话文件标识的操作使用。

注意:
  - URL 文件代传不受支持;先把文件下载到工作目录,再传相对路径
  - 需要真正发送文件消息时,使用 `chat message send --msg-type file --file <本地路径>` 或 `chat +messages-send --file <本地路径>`
  - `--conversation-id`、`--user`、`--open-dingtalk-id` 必须且只能指定一个
  - 历史 `chat file upload` 仍保持隐藏下线,不要用于新调用

#### 查询消息发送状态 — 查询以当前用户身份发送的消息的发送状态

查询以当前用户身份发送的消息的发送状态。需要传入发送消息时返回的 openTaskId。

发送成功时返回 openMessageId 和 openConversationId,可直接用于后续编辑或撤回。
```
Usage:
  dws chat message query-send-status [flags]
Example:
  dws chat message query-send-status --open-task-id <openTaskId>
  # openTaskId 由 dws chat message send 返回
Flags:
      --open-task-id string   消息发送任务 ID (必填)

注意:
  - openTaskId 由 `dws chat message send` 发送消息成功后返回
  - 用于确认消息是否已成功发送或获取发送失败的原因
  - 返回结果中含发送成功消息的 openMessageId,可用于后续 recall(撤回)、read-status(查已读)等命令
  - 返回结果同时含 openConversationId;与 openMessageId 组合后可直接用于 edit(编辑)或 recall(撤回)
```

发送后编辑/撤回时,优先使用下列 ID 链,无需按消息内容反查:

```bash
# 1. 发送后保留 openTaskId
dws chat message send --conversation-id <openConversationId> --content "原始内容"
# 2. 查询得到 openMessageId 和 openConversationId
dws chat message query-send-status --open-task-id <openTaskId>
# 3. 编辑消息
dws chat message edit --conversation-id <openConversationId> --msg-id <openMessageId> --text "更新后的内容"

# 发送后撤回使用同一 ID 链
dws chat message send --conversation-id <openConversationId> --content "待撤回的内容"
dws chat message query-send-status --open-task-id <openTaskId>
dws chat message recall --conversation-id <openConversationId> --msg-id <openMessageId>
```

#### 撤回消息 — 撤回当前用户自己发出的消息

撤回当前用户以个人身份发送的消息。需要指定会话 ID(openConversationId)和消息 ID(openMessageId)。与 `recall-by-bot` 的区别:本命令通过 IM 接口撤回用户自己发出的消息,`recall-by-bot` 通过机器人接口撤回机器人发出的消息(需要 robot-code + processQueryKey)。
```
Usage:
  dws chat message recall [flags]
Example:
  dws chat message recall --conversation-id <openConversationId> --msg-id <openMessageId>
Flags:
      --conversation-id string   会话 openConversationId (必填,支持单聊/群聊,别名: --group / --id / --chat)
      --msg-id string            消息 openMessageId (必填)

注意:
  - --conversation-id 的别名: --group, --id, --chat (均可替代 --conversation-id)
  - 刚由 `chat message send` 发出的消息,使用 `query-send-status` 返回的 openConversationId 和 openMessageId;只有历史消息或已丢失 openTaskId 时才通过消息拉取/搜索获取 ID
  - 仅支持撤回当前用户以个人身份发出的消息,不能撤回他人发送的消息,也不能撤回机器人发出的消息
  - 与 `recall-by-bot` 的区别:本命令通过 IM 接口撤回用户自己发出的消息(需要 openConversationId + openMessageId),`recall-by-bot` 通过机器人接口撤回机器人发出的消息(需要 robot-code + processQueryKey)
```

#### 编辑已发送消息

指定会话和消息后编辑 Markdown 消息内容。推荐使用 `--text`,CLI 会生成完整 content JSON;高级场景可直接传 `--content`,两者必须二选一且互斥。

```
Usage:
  dws chat message edit [flags]
Example:
  dws chat message edit --conversation-id <openConversationId> --msg-id <openMessageId> --text "更新后的内容"
  dws chat message edit --group <openConversationId> --msg-id <openMessageId> --title "标题" --text "更新后的内容"
  dws chat message edit --group <openConversationId> --msg-id <openMessageId> --text "<@all> 请查看" --at-all
  dws chat message edit --group <openConversationId> --msg-id <openMessageId> --content '{"title":"标题","text":"更新后的内容"}'
Flags:
      --conversation-id string       会话 openConversationId (必填;别名 --group / --id / --chat)
      --msg-id string                消息 openMessageId (必填)
      --text string                  编辑后的 Markdown 正文;与 --content 二选一
      --title string                 消息标题;仅配合 --text,省略时从正文生成
      --content string               完整 Markdown content JSON;与 --text 二选一
      --at-all                       @所有人;正文缺少 <@all> 时自动补齐
      --at-open-dingtalk-ids string  @成员的 openDingTalkId 列表,逗号分隔
```

`--at-open-dingtalk-ids` 对应正文中的 `<@openDingTalkId>` 占位符;裸 `@openDingTalkId` 会规范化为尖括号格式。

#### 机器人发送消息(--group 群聊 / --users 单聊)

**重要:该接口会真实发送消息到目标会话,不可用于测试或试探性调用。调用前必须确认消息内容和接收对象无误。**

群聊传 --conversation-id;单聊可传 --users、--open-dingtalk-ids 或两者组合。--conversation-id 不能与单聊目标同时指定。默认发送 Markdown,普通发送必须同时使用 --title 和 --text;公网图片 URL 使用 --msg-type image --image-url <图片 URL>;本地图片和其他本地文件一样使用 --msg-type file --file-path <本地路径>,CLI 会完成上传并按文件附件发送。群聊时可选 --at-user-ids 或 --at-open-dingtalk-ids @指定成员。机器人群聊 Markdown 引用回复同时传 --reply <openMessageId> 和 --ref-sender <senderOpenDingTalkId>,可省略 --title 由 CLI 从正文生成;单聊、图片和文件不支持引用回复。
如果用户明确要求"用机器人/机器人身份/robot"发送,必须使用本命令,严禁改用 `chat message send` 以当前用户身份发送。

**重要**:机器人发群消息前,必须确认该机器人已在目标群中。若机器人不在群内会报错"机器人不存在",需先执行 `dws chat group members add-bot --id <openConversationId> --robot-code <robot-code>` 将机器人加入群聊后再发送。
```
Usage:
  dws chat message send-by-bot [flags]
Example:
  dws chat message send-by-bot --robot-code <robot-code> --conversation-id <openconversation_id> --title "日报" --text "## 今日完成..."
  dws chat message send-by-bot --robot-code <robot-code> --conversation-id <openconversation_id> --reply <openMessageId> --ref-sender <senderOpenDingTalkId> --text "收到"
  dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> --msg-type image --image-url "https://example.com/image.png"
  dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> --msg-type file --file-path ./report.pdf
  dws chat message send-by-bot --robot-code <robot-code> --users userId1,userId2 --title "提醒" --text "请提交周报"
  dws chat message send-by-bot --robot-code <robot-code> --open-dingtalk-ids openDingtalkId1,openDingtalkId2 --title "提醒" --text "请提交周报"
  dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> --at-user-ids userId1,userId2 --title "提醒" --text "@userId1 @userId2 请查收本周报告"
  dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> --at-open-dingtalk-ids openDingtalkId1,openDingtalkId2 --title "提醒" --text "@openDingtalkId1 @openDingtalkId2 请查收本周报告"
  dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> --at-all --title "通知" --text "请所有人注意"
Flags:
      --conversation-id string       群聊 openConversationId(群聊时必填;兼容别名 --group)
      --robot-code string            机器人 Code (必填)
      --msg-type string              消息类型:markdown、image 或 file;省略时为 markdown;公网图片使用 image --image-url;本地图片和文件使用 file --file-path
      --title string                 Markdown 消息标题(普通 Markdown 必填;引用回复省略时从正文生成)
      --text string                  Markdown 消息内容(Markdown 时必填)
      --image-url string             公网图片 URL(msgType=image 时必填)
      --file-path string             本地图片或文件路径(msgType=file 时上传并按文件附件发送)
      --users string                 用户 userId 列表,逗号分隔,最多20个(单聊时必填)
      --open-dingtalk-ids string     用户 openDingtalkId 列表,逗号分隔(单聊时可替代 --users,可选)
      --at-user-ids string           @指定成员的 userId 列表,逗号分隔(仅群聊时生效,可选)
      --at-open-dingtalk-ids string  @指定成员的 openDingtalkId 列表,逗号分隔(仅群聊时生效,可选)
      --at-all                        @所有人(可选),服务端接收字符串 true/false
      --reply string                 被引用消息的 openMessageId(仅群聊 Markdown;必须与 --ref-sender 同时使用)
      --ref-sender string            被引用消息发送者的 openDingTalkId(仅群聊 Markdown;必须与 --reply 同时使用)

注意:
  - 用户明确要求机器人发送时,必须使用 `chat message send-by-bot`;严禁使用 `chat message send` 以用户身份代发
  - --group 与任一单聊目标互斥;单聊可同时提供 --users 和 --open-dingtalk-ids,但发送文件时只能指定一个收件人
  - --msg-type 决定发送类型:Markdown 必须同时指定 --title 和 --text;公网图片传 --image-url,本地图片和文件传 --file-path
  - --group 的别名: --id, --chat, --conversation-id (均可替代 --group)
  - --at-user-ids 仅在 --group 群聊时生效,单聊时无效;设置时 --text 中需包含 @userId 对应文本
  - --at-open-dingtalk-ids 仅在 --group 群聊时生效,单聊时无效;设置时 --text 中需包含 @openDingtalkId 对应文本
  - --at-all @所有人,仅群聊时生效;只需带上 --at-all flag 即可,服务端会自动处理
  - --reply 与 --ref-sender 必须成对使用;CLI 在普通群消息参数顶层透传 referenceOpenMessageId 与 srcMsgSendOpenDingTalkId,不设置 msgType=reply
  - userId 获取方式:`dws contact user search --query "姓名"` 搜人获取 userId
  - **换行符**:--text 按 Markdown 渲染,换行规则同 `chat message send`:
    1. 必须使用**真实换行符**(`U+000A`),而非字面量 `\n`,否则全部内容会渲染在同一行
    2. 单个换行不产生换行效果,需用空行(`\n\n`)做段落分隔,或行尾两空格 + 换行/`<br>` 做硬换行
```

#### 机器人撤回消息(--group 群聊 / 不传为单聊)

群聊:传 --group 与 --keys;单聊:仅传 --keys。--keys 为发送时返回的 processQueryKey 列表,逗号分隔。
```
Usage:
  dws chat message recall-by-bot [flags]
Example:
  dws chat message recall-by-bot --robot-code <robot-code> --group <openconversation_id> --keys <process-query-key>
  dws chat message recall-by-bot --robot-code <robot-code> --keys key1,key2
Flags:
      --group string         群聊 openConversationId(群聊撤回时必填)
      --keys string         消息 processQueryKey 列表,逗号分隔 (必填)
      --robot-code string   机器人 Code (必填)
```

#### 自定义机器人 Webhook 发送群消息

@ 人时需在 --content 中包含 @userId 或 @手机号,否则 @ 不生效;@所有人时需在 --content 中包含 @10 并带上 --at-all。
```
Usage:
  dws chat message send-by-webhook [flags]
Example:
  dws chat message send-by-webhook --token <webhook-token> --title "告警" --content "CPU 超 90% @10" --at-all
  dws chat message send-by-webhook --token <webhook-token> --title "test" --content "hi @118785" --at-users 118785
Flags:
      --at-all              @ 所有人(需在 --content 中包含 @10)
      --at-mobiles string   @ 指定手机号,逗号分隔
      --at-users string     @ 指定用户,逗号分隔(需在 content 中包含 @userId)
      --content string      消息内容 (必填)
      --title string        消息标题 (必填)
      --token string        Webhook Token (必填)

注意:
  - **换行符**:--content 按 Markdown 渲染,换行规则同 `chat message send`:
    1. 必须使用**真实换行符**(`U+000A`),而非字面量 `\n`,否则全部内容会渲染在同一行
    2. 单个换行不产生换行效果,需用空行(`\n\n`)做段落分隔,或行尾两空格 + 换行/`<br>` 做硬换行
```

#### 拉取话题回复消息列表

分页查询指定话题的回复,每次返回一页。`conversation-id` 指定父会话,`topic-id` 指定 `openConvThreadId`;需要自动读取全部页面时使用现有的 `dws chat +thread-replies --page-all`。

用户需要逐条查看、列出或概括具体回复内容时,使用本命令;只浏览话题主消息时使用 `thread list`。需要自动读取全部页面、排序或下载资源时,使用 `chat +thread-replies --page-all`。
```
Usage:
  dws chat thread list-replies [flags]
Example:
  dws chat thread list-replies --conversation-id <openConversationId> --topic-id <openConvThreadId>
  dws chat thread list-replies --conversation-id <openConversationId> --topic-id <openConvThreadId> --time "2025-03-01 00:00:00" --limit 20
Flags:
      --conversation-id string  父会话 openConversationId (必填)
      --topic-id string         Thread openConvThreadId (必填)
      --time string             开始时间,格式: yyyy-MM-dd HH:mm:ss(可选)
      --limit int               返回数量(默认 50)
      --direction string        时间方向: newer/older
```

#### 拉取指定时间范围内当前用户的所有会话消息 — 分页拉取当前登录用户在指定时间范围内的所有会话消息

--start 和 --end 限定时间范围,--limit 指定每页数量,--cursor 传分页游标(首页传 "0",后续从响应中的 nextCursor 获取)。服务端按 cursor 分页返回,hasMore=true 时用返回的 nextCursor 值作为下次 --cursor 继续翻页。若当前账号没有消息搜索权益,CLI 会透传服务端的友好提示与开通入口。

需要自动遍历全部分页时显式加 `--page-all`。`--page-limit` 控制最多请求页数(默认 50,范围 1-500),`--max-items` 控制最多输出条数(默认 0 不限制,精确截断并输出 `paging.truncated=true`),`--page-delay` 控制页间等待毫秒数(默认 200,0 表示不等待)。只传这些分页控制参数但不传 `--page-all` 时仍保持原单页调用。
```
Usage:
  dws chat message list-all [flags]
Example:
  dws chat message list-all --start "2025-03-01 00:00:00" --end "2025-03-31 23:59:59" --limit 50
  dws chat message list-all --start "2025-03-01 00:00:00" --end "2025-03-31 23:59:59" --limit 50 --cursor "abc123token"
Flags:
      --start string         起始时间,格式: yyyy-MM-dd HH:mm:ss (必填)
      --end string           结束时间,格式: yyyy-MM-dd HH:mm:ss (必填)
      --limit int            每页返回数量(默认 50)
      --cursor string       分页游标(首页传 "0",后续从响应中的 nextCursor 获取)
      --page-all             自动按 nextCursor 拉取所有分页
      --page-limit int       自动翻页最多请求页数(默认 50,范围 1-500)
      --max-items int        自动翻页最多返回条数(默认 0 表示不限制)
      --page-delay int       自动翻页每页之间等待毫秒数(默认 200;0 表示不等待)

注意:
  - 四个参数每次请求都会传递给服务端,cursor 首页传 "0"
  - 与 chat message list 的区别:list 拉取指定单个会话(群聊或单聊)的消息,list-all 拉取当前用户所有会话的消息
  - 翻页:hasMore=true 时,用响应中的 nextCursor 值作为下次 --cursor 参数继续翻页
  - 自动翻页:`--page-all` 会保留并合并 `result.conversationMessagesList`,同一会话跨页合并 messages,并在顶层输出 `paging` 元数据;shortcut 命令不属于本 typed fallback 小节
  - 时间格式统一为 yyyy-MM-dd HH:mm:ss
  - 权限/权益错误不是空结果;应把返回的 friendly_hint 与 action_url 展示给用户,不要继续盲目翻页
```

#### 拉取指定发送者的消息 — 搜索特定人发送给我的消息(包含单聊和群聊)

> 推荐优先使用 `chat message search-advanced --user/--users`(userId)或 `--sender-ids`(openDingTalkId),它还能叠加关键词/群/at 等过滤条件。本命令保留给需要旧 list-by-sender 返回结构的场景。

搜索特定人发送给我的消息,返回结果包含单聊和群聊标识。--sender-user-id 指定发送者 userId,--sender-open-dingtalk-id 指定发送者 openDingTalkId,二者互斥。分页参数 --limit(默认 50)和 --cursor(默认 "0")始终传递;hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。

自动翻页同样使用 `--page-all` 触发,复用发送者、时间范围和 limit 条件,只替换每页 `cursor`;输出保留并合并 `result.conversationMessagesList`,控制参数为 `--page-limit`、`--max-items`、`--page-delay`。
```
Usage:
  dws chat message list-by-sender [flags]
Example:
  dws chat message list-by-sender --sender-user-id <userId> --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0
  dws chat message list-by-sender --sender-open-dingtalk-id <openDingTalkId> --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0
  dws chat message list-by-sender --sender-user-id <userId> --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T23:59:59+08:00" --limit 20 --cursor 0
  dws chat message list-by-sender --sender-open-dingtalk-id <openDingTalkId> --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor <nextCursor>
Flags:
      --sender-user-id string                发送者 userId(与 --sender-open-dingtalk-id 二选一)
      --sender-open-dingtalk-id string        发送者 openDingTalkId(与 --sender-user-id 二选一);该路径当前返回 result:{}、success:null(疑似服务端问题),优先用 --sender-user-id
      --start string                          开始时间,ISO-8601 格式 (必填)
      --end string                            结束时间,ISO-8601 格式 (必填)
      --limit int                             每页返回数量(默认 50)
      --cursor string                         分页游标(默认 "0",翻页传 nextCursor)
      --page-all                              自动按 nextCursor 拉取所有分页
      --page-limit int                        自动翻页最多请求页数(默认 50,范围 1-500)
      --max-items int                         自动翻页最多返回条数(默认 0 表示不限制)
      --page-delay int                        自动翻页每页之间等待毫秒数(默认 200;0 表示不等待)

注意:
  - --sender-user-id 和 --sender-open-dingtalk-id 二者互斥,必须且只能指定其一:
    - --sender-user-id 传 userId(企业内部应用常用,当前唯一可用路径)
    - --sender-open-dingtalk-id 传 openDingTalkId(当前返回 result:{}、success:null(疑似服务端问题);即使只有 openDingTalkId,也建议先用 contact 换取 userId 后走 --sender-user-id)
  - openDingTalkId 获取方式见下方「openDingTalkId 获取方式」小节
  - 不需要指定单聊/群聊,返回结果自带会话类型标识
  - 时间支持多种 ISO-8601 格式,如 "2026-03-10T00:00:00+08:00"、"2026-03-10 14:00:00"、"2026-03-10" 等
  - 翻页:hasMore=true 时,用返回的 nextCursor 作为下次 --cursor
```

#### 拉取 @我 的消息 — 搜索时间范围内 @我 的消息

> 推荐使用 `chat message search-advanced --at-me`,它还能叠加关键词/群/发送者等过滤条件。本命令适用于仅需拉取 @我 消息的简单场景。

搜索时间范围内 @我 的消息,可选指定群聊。返回结果包含单聊和群聊标识。分页参数 --limit(默认 50)和 --cursor(默认 "0")始终传递;hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。

自动翻页同样使用 `--page-all` 触发,复用时间范围和 group 过滤条件,只替换每页 `cursor`;输出保留并合并 `result.conversationMessagesList`,控制参数为 `--page-limit`、`--max-items`、`--page-delay`。
```
Usage:
  dws chat message list-mentions [flags]
Example:
  dws chat message list-mentions --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0
  dws chat message list-mentions --start "2026-04-01T00:00:00+08:00" --end "2026-04-14T00:00:00+08:00" --limit 20 --cursor 0
  dws chat message list-mentions --group <openconversation_id> --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor 0
  dws chat message list-mentions --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00" --limit 50 --cursor <nextCursor>
Flags:
      --group string    群聊 openconversation_id(可选,不传则查全部)
      --start string    开始时间,ISO-8601 格式 (必填)
      --end string      结束时间,ISO-8601 格式 (必填)
      --limit int       每页返回数量(默认 50)
      --cursor string   分页游标(默认 "0",翻页传 nextCursor)
      --page-all        自动按 nextCursor 拉取所有分页
      --page-limit int  自动翻页最多请求页数(默认 50,范围 1-500)
      --max-items int   自动翻页最多返回条数(默认 0 表示不限制)
      --page-delay int  自动翻页每页之间等待毫秒数(默认 200;0 表示不等待)

注意:
  - --group 可选,不传则查询所有会话中 @我 的消息;传入则只查指定群聊
  - --group 的别名: --id, --chat, --conversation-id (均可替代 --group)
  - 时间支持多种 ISO-8601 格式,如 "2026-03-10T00:00:00+08:00"、"2026-03-10 14:00:00"、"2026-03-10" 等
  - 翻页:hasMore=true 时,用返回的 nextCursor 作为下次 --cursor
```

#### 拉取特别关注人的消息

拉取当前用户特别关注人的消息。分页参数 --limit 指定每页数量,--cursor 传分页游标(首次不传或传 0)。返回结果中 hasMore=true 时用 nextCursor 作为下次 --cursor 继续翻页。

自动翻页使用 `--page-all` 触发,按 int64 cursor 注入下一页游标并聚合 `result.messages`;控制参数为 `--page-limit`、`--max-items`、`--page-delay`。
```
Usage:
  dws chat message list-focused [flags]
Example:
  dws chat message list-focused --limit 50
  dws chat message list-focused --limit 20 --cursor <nextCursor>
Flags:
      --limit int       每页返回数量(默认 50)
      --cursor int64    分页游标(首次不传或传 0,翻页传 nextCursor)
      --page-all        自动按 nextCursor 拉取所有分页
      --page-limit int  自动翻页最多请求页数(默认 50,范围 1-500)
      --max-items int   自动翻页最多返回条数(默认 0 表示不限制)
      --page-delay int  自动翻页每页之间等待毫秒数(默认 200;0 表示不等待)

注意:
  - 首次调用不传 --cursor 或传 0,后续翻页传 nextCursor
```

#### 获取未读会话列表

获取当前用户有未读消息的会话信息。可选通过 `--count` 限制返回条数,不传则使用服务端默认值。
```
Usage:
  dws chat message list-unread-conversations [flags]
Example:
  dws chat message list-unread-conversations
  dws chat message list-unread-conversations --count 20
  dws chat message list-unread-conversations --exclude-muted
Flags:
      --count int       返回未读会话条数(可选)
      --exclude-muted   是否排除已设置免打扰的会话(默认 false)
```

#### 查询消息的已读/未读状态

查询指定会话中消息的已读/未读状态(仅消息发送者可查询自己发出的消息)。--conversation-id 指定会话 openConversationId(群聊或单聊均可),--message-id 指定消息 ID(由 dws chat message list 返回的 openMessageId,必须是当前用户发送的消息)。目标用户 userId 使用 --user/--users;目标用户 openDingTalkId 使用 --target-open-dingtalk-ids;不传目标用户则返回所有接收者的状态。
```
Usage:
  dws chat message read-status [flags]
Example:
  dws chat message read-status --conversation-id <openConversationId> --message-id <openMessageId>
  dws chat message read-status --conversation-id <openConversationId> --message-id <openMessageId> --user userId1,userId2
  dws chat message read-status --conversation-id <openConversationId> --message-id <openMessageId> --users userId1,userId2
  dws chat message read-status --conversation-id <openConversationId> --message-id <openMessageId> --target-open-dingtalk-ids openDingTalkId1,openDingTalkId2
Flags:
      --conversation-id string              会话 openConversationId (必填,群聊或单聊均可)
      --message-id string                   消息 openMessageId,由 chat message list 返回 (必填,必须是当前用户发送的消息)
      --user string                         目标用户 userId,支持逗号分隔(可选,不传则查所有接收者)
      --users string                        目标用户 userId 列表,逗号分隔(可选,不传则查所有接收者)
      --target-open-dingtalk-ids string     目标用户 openDingTalkId 列表,逗号分隔(可选,不传则查所有接收者)

注意:
  - 仅消息发送者可查询自己发出的消息的已读/未读状态,查询他人发的消息会报错
  - --conversation-id 的别名: --group, --id, --chat (均可替代 --conversation-id)
  - --message-id 从 dws chat message list 返回的消息列表中获取(字段名 openMessageId)
  - --user / --users 传目标用户 userId
  - --target-open-dingtalk-ids 不传时返回该消息所有接收者的已读状态;传入则只返回指定 openDingTalkId 用户的状态
```

#### 按关键词搜索消息 — 在当前用户的会话中按关键词搜索消息

> 推荐优先使用 `chat message search-advanced`,它是本命令的严格超集:query 可选(非必填)、支持多个会话(非单个)、还能叠加发送者/at 等维度过滤。

按关键词搜索消息内容。--query 指定搜索关键词(必填)。可选 --group 限定搜索某个会话,不传则搜索所有会话。时间参数 --start/--end(ISO-8601)限定搜索时间范围。分页参数 --limit(默认 100)和 --cursor(默认 "0")始终传递;hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。

自动翻页同样使用 `--page-all` 触发,复用 query、时间范围和 group 条件,只替换每页 `cursor`;输出保留并合并 `result.conversationMessagesList`,控制参数为 `--page-limit`、`--max-items`、`--page-delay`。
```
Usage:
  dws chat message search [flags]
Example:
  dws chat message search --query "changefree" --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 50 --cursor 0
  dws chat message search --query "codereview" --group <openconversation_id> --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00" --limit 100 --cursor 0
  dws chat message search --query "链接" --start "2026-04-15T00:00:00+08:00" --end "2026-04-16T00:00:00+08:00" --limit 100 --cursor <nextCursor>
Flags:
      --query string   搜索关键词 (必填)
      --group string     群聊 openconversation_id(可选,不传则搜索所有会话)
      --start string     开始时间,ISO-8601 格式 (必填)
      --end string       结束时间,ISO-8601 格式 (必填)
      --limit int        每页返回数量(默认 100)
      --cursor string    分页游标(默认 "0",翻页传 nextCursor)
      --page-all         自动按 nextCursor 拉取所有分页
      --page-limit int   自动翻页最多请求页数(默认 50,范围 1-500)
      --max-items int    自动翻页最多返回条数(默认 0 表示不限制)
      --page-delay int   自动翻页每页之间等待毫秒数(默认 200;0 表示不等待)

注意:
  - --group 可选,不传则搜索所有会话中的消息;传入则只搜索指定会话
  - --group 的别名: --id, --chat, --conversation-id (均可替代 --group)
  - 时间支持多种 ISO-8601 格式,如 "2026-03-10T00:00:00+08:00"、"2026-03-10 14:00:00"、"2026-03-10" 等
  - 翻页:hasMore=true 时,用返回的 nextCursor 作为下次 --cursor
```

#### 多维度搜索消息(推荐首选) — 支持按关键词、发送者、@我、@指定人、指定会话、时间范围等多维度搜索

> 推荐:这是消息搜索的首选接口。它可以完全替代 `chat message search`(query 可选 vs 必填,支持多个会话 vs 单个),大部分替代 `chat message list-by-sender`(通过 --user/--users 按 userId 搜索发送者,或通过 --sender-ids 按 openDingTalkId 搜索)和 `chat message list-mentions`(通过 --at-me 搜索@我的消息)。仅在拉取「特别关注人」消息时需要退回 `list-focused`。

支持按关键词、发送者、@我、@指定人、指定会话、时间范围等多维度搜索消息。发送者 userId 使用 --user/--users;发送者或 @ 人的 openDingTalkId 使用 --sender-ids/--at-ids。所有参数均为可选,至少指定一个搜索条件。

自动翻页使用 `--page-all` 触发,复用所有高级过滤参数,只替换每页 `cursor`,保留并合并 `result.conversationMessagesList`;控制参数为 `--page-limit`、`--max-items`、`--page-delay`。
```
Usage:
  dws chat message search-advanced [flags]
Example:
  dws chat message search-advanced --query "周报" --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00"
  dws chat message search-advanced --user <userId> --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00"
  dws chat message search-advanced --users <userId1>,<userId2> --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00"
  dws chat message search-advanced --sender-ids <openDingTalkId1>,<openDingTalkId2> --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00"
  dws chat message search-advanced --at-me --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00"
  dws chat message search-advanced --at-ids <openDingTalkId1>,<openDingTalkId2> --conversation-ids <openConversationId1>,<openConversationId2> --limit 50 --cursor 0
  dws chat message search-advanced --conversation-ids <单聊openConversationId> --query "合同" --start "2026-04-01T00:00:00+08:00" --end "2026-04-15T00:00:00+08:00"
  # 查询群 ID: dws chat search --query "群名"
  # 查询单聊会话 ID: dws chat conversation-info --user <userId>
  # 查询人员: dws aisearch person --query "姓名" --dimension name
Flags:
      --query string              搜索关键词(可选)
      --user string                 发送者 userId,支持逗号分隔(可选)
      --users string                发送者 userId 列表,逗号分隔(可选)
      --sender-ids string           发送者 openDingTalkId 列表,逗号分隔(可选)
      --at-me                       只搜索 @我 的消息(可选,默认 false)
      --at-ids string               @指定人的 openDingTalkId 列表,逗号分隔(可选)
      --conversation-ids string     会话 openConversationId 列表,逗号分隔(可选,群聊或单聊均可,不传则搜索所有会话)
      --start string                开始时间,ISO-8601 格式(可选)
      --end string                  结束时间,ISO-8601 格式(可选)
      --cursor string               分页游标(默认 "0")
      --limit int                   每页返回数量(默认 100)
      --page-all                    自动按 nextCursor 拉取所有分页
      --page-limit int              自动翻页最多请求页数(默认 50,范围 1-500)
      --max-items int               自动翻页最多返回条数(默认 0 表示不限制)
      --page-delay int              自动翻页每页之间等待毫秒数(默认 200;0 表示不等待)
      --conversation-ids 的别名: --groups

注意:
  - 所有参数均为可选,但至少需要指定一个搜索条件
  - --user / --users 传发送者 userId
  - --sender-ids 和 --at-ids 传 openDingTalkId
  - --conversation-ids 可指定多个会话 ID(群聊或单聊均可),逗号分隔,不传则搜索所有会话
  - 群聊 openConversationId 通过 `dws chat search --query "群名"` 获取
  - 单聊 openConversationId 通过 `dws chat conversation-info --user <userId>` 或 `--open-dingtalk-id <openDingTalkId>` 获取
  - 时间支持多种 ISO-8601 格式,如 "2026-03-10T00:00:00+08:00"、"2026-03-10 14:00:00"、"2026-03-10" 等
  - 翻页:hasMore=true 时,用返回的 nextCursor 作为下次 --cursor
  - 替代关系:完全替代 search(严格超集);大部分替代 list-by-sender(--user 覆盖按 userId 搜索发送者,--sender-ids 覆盖按 openDingTalkId 搜索)和 list-mentions(--at-me 覆盖核心功能);不能替代 list-focused(「特别关注」是独立维度)
```

#### 根据消息 ID 批量查询消息
```
Usage:
  dws chat message list-by-ids [flags]
Example:
  dws chat message list-by-ids --msg-ids msgId1,msgId2,msgId3
  # 最多传 50 条消息 ID
Flags:
      --msg-ids string   消息 ID 列表,逗号分隔,最多 50 条 (必填)
```

#### 表情回应选择策略

> 贴表情时,优先查 [chat-emoji-list.md](chat-emoji-list.md) 中的默认表情名称(共 199 个,如「赞」「鼓掌」「感谢」等):
> - 命中 → 使用 `add-emoji --emoji <name>`(直接贴 emoji)
> - 未命中 → 先 `create-text-emotion` 创建文字表情获取 emotionId,再 `add-text-emotion` 贴文字表情

#### 对消息添加 emoji 表情回应
```
Usage:
  dws chat message add-emoji [flags]
Example:
  dws chat message add-emoji --conversation-id <openConversationId> --msg-id <openMsgId> --emoji "赞"
  dws chat message add-emoji --conversation-id <openConversationId> --msg-id <openMsgId> --emoji "鼓掌"
  # --emoji 的值必须是 chat-emoji-list.md 中的 name(中文名),如:赞、鼓掌、感谢、微笑 等
  # 查询会话 ID: dws chat search --query "群名"
Flags:
      --conversation-id string   会话 openConversationId (必填,支持单聊/群聊,别名: --group / --id / --chat)
      --msg-id string   消息 openMsgId (必填)
      --emoji string    emoji 表情名称,必须是默认表情列表中的 name 值 (必填,参见 chat-emoji-list.md)
```

#### 移除消息的 emoji 表情回应
```
Usage:
  dws chat message remove-emoji [flags]
Example:
  dws chat message remove-emoji --conversation-id <openConversationId> --msg-id <openMsgId> --emoji "赞"
  # 查询会话 ID: dws chat search --query "群名"
Flags:
      --conversation-id string   会话 openConversationId (必填,支持单聊/群聊,别名: --group / --id / --chat)
      --msg-id string   消息 openMsgId (必填)
      --emoji string    emoji 表情名称,必须是默认表情列表中的 name 值 (必填,参见 chat-emoji-list.md)
```

#### 对消息添加文字表情回应(当默认表情列表中没有所需表情时使用)
```
Usage:
  dws chat message add-text-emotion [flags]
Example:
  dws chat message add-text-emotion --conversation-id <openConversationId> --msg-id <openMsgId> --emotion-id <emotionId> --emotion-name "赞" --text "nice" --background-id im_bg_5
Flags:
      --conversation-id string   会话 openConversationId (必填,支持单聊/群聊,别名: --group / --id / --chat)
      --msg-id string          消息 openMsgId (必填)
      --emotion-id string      表情 ID (必填,通过 create-text-emotion 或已知表情获取)
      --emotion-name string    表情名称 (必填)
      --text string            文字内容 (必填)
      --background-id string   背景 ID (必填)
```

#### 原地更新消息的文字表情回应
```
Usage:
  dws chat message update-text-emotion [flags]
Example:
  dws chat message update-text-emotion --conversation-id <openConversationId> --msg-id <openMsgId> --old-emotion-id <oldEmotionId> --emotion-id <emotionId> --emotion-name "处理中" --text "处理中 2 分钟" --background-id im_bg_5
Flags:
      --conversation-id string   会话 openConversationId (必填,支持单聊/群聊,别名: --group / --id / --chat)
      --msg-id string            消息 openMsgId (必填)
      --old-emotion-id string    待替换的原表情 ID (必填)
      --emotion-id string        新表情 ID (必填,通过 create-text-emotion 获取)
      --emotion-name string      新表情名称 (必填)
      --text string              新文字内容 (必填)
      --background-id string     新背景 ID (必填)
```

#### 移除消息的文字表情回应
```
Usage:
  dws chat message remove-text-emotion [flags]
Example:
  dws chat message remove-text-emotion --conversation-id <openConversationId> --msg-id <openMsgId> --emotion-id <emotionId> --emotion-name "赞" --text "nice" --background-id <backgroundId>
Flags:
      --conversation-id string   会话 openConversationId (必填,支持单聊/群聊,别名: --group / --id / --chat)
      --msg-id string          消息 openMsgId (必填)
      --emotion-id string      表情 ID (必填)
      --emotion-name string    表情名称 (必填)
      --text string            文字内容 (必填)
      --background-id string   背景 ID (必填)
```

#### 创建文字表情(获取 emotionId)— 当 chat-emoji-list.md 中没有所需表情时,先创建再贴
```
Usage:
  dws chat message create-text-emotion [flags]
Example:
  dws chat message create-text-emotion --emotion-name "赞" --text "nice"
  dws chat message create-text-emotion --emotion-name "感谢" --text "感谢" --background-id im_bg_5
Flags:
      --emotion-name string    表情名称 (必填)
      --text string            文字内容 (必填)
      --background-id string   背景 ID(可选,不传则由服务端默认分配)

注意:
  - 创建后返回 emotionId,可用于 add-text-emotion 命令
  - 如果已有合适的表情,无需创建新的
```

#### 批量拉取消息的表情回复和文字回复

根据消息 ID 列表批量查询消息的表情回复和文字回复信息。

```
Usage:
  dws chat message list-emotion-replies [flags]
Example:
  dws chat message list-emotion-replies --msg-ids msgId1,msgId2,msgId3
  # 消息 ID 可通过 dws chat message list 获取
Flags:
      --msg-ids string   消息 ID 列表,逗号分隔 (必填)
```

### emotion (个人收藏表情)

#### 列出个人收藏表情
```
Usage:
  dws chat emotion list [flags]
Example:
  dws chat emotion list --format json
```
当前用户身份由 MCP server 注入,无业务参数。

#### 发送个人收藏表情
```
Usage:
  dws chat emotion send [flags]
Example:
  dws chat emotion send --media-id <mediaId> --group <openConversationId>
  dws chat emotion send --media-id <mediaId> --emotion-id <emotionId> --user <userId>
  dws chat emotion send --media-id <mediaId> --open-dingtalk-id <openDingTalkId> --uuid <idempotencyKey>
Flags:
      --media-id string            表情媒体 ID (必填)
      --emotion-id string          表情 ID (可选)
      --conversation-id string     群聊 openConversationId(与 --group 等价)
      --group string               群聊 openConversationId
      --user string                单聊接收人 userId,CLI 会解析为 openDingTalkId
      --open-dingtalk-id string    单聊接收人 openDingTalkId
      --uuid string                幂等键
      --idempotency-key string     幂等键(--uuid 等价)
```
目标参数 `--conversation-id/--group`、`--user`、`--open-dingtalk-id` 三选一。该命令会真实发送表情,执行前必须确认目标和 mediaId。

#### 新增个人收藏表情
```
Usage:
  dws chat emotion favorite [flags]
Example:
  dws chat emotion favorite --media-id <mediaId> --name "赞"
  dws chat emotion favorite --media-id <mediaId> --source-conversation-id <cid> --source-message-id <mid>
  dws chat emotion favorite --file-path ./sticker.png --name "本地表情"
Flags:
      --file-path string                 本地图片路径 (jpg/jpeg/png/gif/webp/bmp,≤10MB);与 --media-id 二选一必填
      --media-id string                  待收藏 mediaId;与 --file-path 二选一必填
      --name string                      表情名称
      --source-conversation-id string    来源会话 ID,需与 --source-message-id 成对指定
      --source-message-id string         来源消息 ID,需与 --source-conversation-id 成对指定
```
`--media-id` 与 `--file-path` 二选一必填,同时传会被互斥拦截。传 `--file-path` 时 CLI 先做本地校验(文件存在、非目录、大小 ≤10MB、扩展名为 jpg/jpeg/png/gif/webp/bmp,大小写不敏感),再经 `dingtalk-file/upload_media`(bizType=chat_emoticon)上传取得 mediaId(优先 mediaIdV1,缺失时用 mediaIdV2)后走与 `--media-id` 完全相同的收藏链路;上传成功但收藏失败时会提示已上传的 mediaId,可用 `--media-id` 重试而无需重新上传。大图(接近 10MB)上传耗时较长,建议追加 `--timeout 120` 以上。

### list-top-conversations (置顶会话)

#### 拉取置顶会话列表

拉取当前用户的置顶会话列表。分页参数 --limit 指定每页数量,--cursor 传分页游标(首次不传或传 0)。返回结果中 hasMore=true 时用 nextCursor 作为下次 --cursor 继续翻页。
```
Usage:
  dws chat list-top-conversations [flags]
Example:
  dws chat list-top-conversations --limit 1000
  dws chat list-top-conversations --limit 1000 --cursor <nextCursor>
Flags:
      --limit int        每页返回数量(默认 1000)
      --cursor int64     分页游标(首次不传或传 0,翻页传 nextCursor)
      --exclude-muted    是否排除已设置免打扰的会话(默认 false)

注意:
  - 用户询问"置顶会话"时,直接调用此命令返回置顶会话列表即可
  - 用户询问"置顶消息"时,需两步:先调用此命令拉取置顶会话列表获取各会话的 openConversationId,再用 `chat message list --group <openConversationId>` 分别拉取每个会话内的消息
  - 翻页:hasMore=true 时,用返回的 nextCursor 作为下次 --cursor
```

### download-media (下载消息资源)

#### 下载消息中的资源(图片/视频/语音等)到本地

下载聊天消息中的图片、视频、语音等资源到本地文件。流程:先获取下载 URL,再 HTTP GET 下载。
```
Usage:
  dws chat message download-media [flags]
Example:
  dws chat message download-media --type mediaId --resource-id <mediaId> --message-id <openMessageId> --open-conversation-id <openConversationId> --output ./photo.jpg
  dws chat message download-media --type mediaId --resource-id <mediaId> --message-id <openMessageId> --open-conversation-id <openConversationId> --output ./downloads/photo.jpg
Flags:
      --type string                  资源类型: mediaId (必填)
      --resource-id string           资源 ID,mediaId 类型时为消息中的 mediaId 值 (必填)
      --message-id string            消息 openMessageId (必填)
      --open-conversation-id string  会话 openConversationId (必填)
      --output string                本地保存路径 (必填),建议传完整文件路径(含文件名)

注意:
  - resource-id 从 `dws chat message list` 返回的消息内容中获取 mediaId
  - message-id 从 `dws chat message list` 返回的 openMessageId
  - open-conversation-id 从 `dws chat search` 获取 openConversationId
  - --output 建议传完整文件路径(含扩展名,如 ./photo.jpg);只传目录(如 ./downloads/)在旧版本会下载失败,请显式带上文件名
```

### search-common (搜索共同群)

#### 搜索共同群 — 查询指定人共同所在的群聊

根据昵称列表搜索共同群聊。--nicks 指定要搜索的人员昵称(逗号分隔,必填)。--match-mode 控制匹配模式:AND 表示所有人都在群里,OR 表示任一人在群里(默认 AND)。分页参数 --limit(默认 20)和 --cursor(默认 "0")始终传递;hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。
```
Usage:
  dws chat search-common [flags]
Example:
  dws chat search-common --nicks "风雷,山乔" --limit 20 --cursor 0
  dws chat search-common --nicks "天鸡,乐函" --match-mode OR --limit 20 --cursor 0
  dws chat search-common --nicks "风雷,山乔,天鸡" --limit 10 --cursor <nextCursor>
Flags:
      --nicks string        要搜索的昵称列表,逗号分隔 (必填)
      --match-mode string   匹配模式:AND=所有人都在群里,OR=任一人在群里(默认 AND)
      --limit int           每页返回数量(默认 20)
      --cursor string       分页游标(默认 "0",翻页传 nextCursor)
      --exclude-muted       是否排除已设置免打扰的群聊(默认 false)

注意:
  - --nicks 传人员昵称(花名),逗号分隔,如 "风雷,山乔"
  - --match-mode AND 表示群里必须包含所有指定的人;OR 表示包含任意一人即可
  - 翻页:hasMore=true 时,用返回的 nextCursor 作为下次 --cursor
```

### conversation-info (获取会话基础信息)

#### 获取会话基础信息 — 含会话关联的钉盘共享空间 ID

获取指定会话的基础信息,包含会话关联的钉盘共享空间 ID (newCSpaceIdIM)。该 ID 可用于独立的钉盘存储操作;发送本地图片或文件到聊天不需要先调用本命令,直接使用 `chat message send --msg-type file --file`。
```
Usage:
  dws chat conversation-info [flags]
Example:
  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
Flags:
      --group string              群聊 openConversationId(群聊时使用)
      --user string               单聊对方 userId(单聊时使用)
      --open-dingtalk-id string   单聊对方 openDingTalkId(单聊时使用)

注意:
  - --group、--user、--open-dingtalk-id 互斥,必须且只能指定其一
  - --group 的别名: --id, --chat, --conversation-id (均可替代 --group)
  - 返回值中的 newCSpaceIdIM 为会话共享空间 ID,可用于调用方明确需要的钉盘存储流程
  - 该 ID 不是发送本地聊天附件的前置条件;本地附件直接走 `chat message send --msg-type file --file`
```

#### 引用回复消息 — 引用某条消息并回复文字(单聊/群聊均可)
```
Usage:
  dws chat message reply [flags]
Example:
  dws chat message reply --group <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --content "收到,马上处理"
  dws chat message reply --group <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --content "请看一下" --at-open-dingtalk-ids <mentionedOpenDingTalkId>
  # 被引用消息的 openMessageId、发送者 openDingTalkId 通过 dws chat message list 获取
Flags:
      --at-all                   @所有人(仅群聊时生效;正文缺少 <@all> 时自动补齐)
      --at-open-dingtalk-ids string  @指定成员的 openDingTalkId 列表,逗号分隔(仅群聊时生效;正文缺少对应 <@id> 时自动补齐)
      --group string             会话 openConversationId (必填,支持单聊/群聊)
      --ref-msg-id string        被引用的消息 openMessageId (必填)
      --ref-sender string        被引用消息的发送者 openDingTalkId (必填)
      --content string           回复内容 (必填)
      --ai-tag                   消息是否带 AI 发送角标(可选,默认 true)
      --uuid string              幂等键(可选)

注意:
  - 以当前用户身份引用回复,语义同 chat message send;目前回复类型仅支持 text
  - 群聊 @指定成员时,正文缺少对应 <@openDingTalkId> 会自动补齐,已有裸 @openDingTalkId 会规范化;--at-all 会自动补齐 <@all>
```

#### 转发单条消息 — 将一条消息从源会话转发到目标会话(源/目标均支持单聊/群聊)
```
Usage:
  dws chat message forward [flags]
Example:
  dws chat message forward --src-conversation-id <srcOpenCid> --msg-id <openMessageId> --dest-conversation-id <destOpenCid>
Flags:
      --src-conversation-id string    源会话 openConversationId (必填)
      --msg-id string                 源消息 openMessageId (必填)
      --dest-conversation-id string   目标会话 openConversationId (必填)
      --uuid string                   幂等键(可选)

注意:
  - 与 combine-forward 区别: forward 转单条,combine-forward 合并多条为一条转发
```

#### 转发话题消息 — 将一条话题消息转发到目标会话
```
Usage:
  dws chat thread forward [flags]
Example:
  dws chat thread forward --src-msg-id <openMessageId> --src-conversation-id <openConversationId> --src-thread-id <openConvThreadId> --dest-conversation-id <openConversationId>
Flags:
      --src-msg-id string             源 Thread 主消息 messageId (必填)
      --src-conversation-id string    源父会话 openConversationId (必填)
      --src-thread-id string          源 Thread openConvThreadId (必填)
      --dest-conversation-id string   目标会话 openConversationId (必填)
```

#### 置顶消息 — 将指定消息置顶到会话顶部
```
Usage:
  dws chat message set-top-msg [flags]
Example:
  dws chat message set-top-msg --open-conversation-id <openConversationId> --msg-id <openMessageId>
Flags:
      --open-conversation-id string   会话 openConversationId (必填,支持群聊/单聊)
      --msg-id string                 消息 openMessageId (必填)
```

#### 取消置顶消息 — 取消会话顶部的置顶消息
```
Usage:
  dws chat message unset-top-msg [flags]
Example:
  dws chat message unset-top-msg --open-conversation-id <openConversationId> --msg-id <openMessageId>
Flags:
      --open-conversation-id string   会话 openConversationId (必填,支持群聊/单聊)
      --msg-id string                 消息 openMessageId (必填)
```

#### 合并转发多条消息 — 将多条消息合并后转发到目标会话(源/目标会话均支持单聊/群聊)
```
Usage:
  dws chat message combine-forward [flags]
Example:
  dws chat message combine-forward --src-conversation-id <srcOpenCid> --msg-ids <id1>,<id2>,<id3> --dest-conversation-id <destOpenCid>
  dws chat message combine-forward --src-conversation-id <srcOpenCid> --msg-ids <id1>,<id2> --dest-conversation-id <destOpenCid> --uuid <idempotencyKey>
Flags:
      --src-conversation-id string    源会话 openConversationId (必填)
      --msg-ids string                源消息 openMessageId 列表,逗号分隔 (必填)
      --dest-conversation-id string   目标会话 openConversationId (必填)
      --uuid string                   幂等键(可选)

注意:
  - 与 chat message forward 区别: forward 转单条,combine-forward 合并多条为一条转发
  - --msg-ids 多个消息 ID 用逗号分隔,无顺序要求
```

#### 钉住某条消息(Pin) — 将指定消息设置为钉住状态
```
Usage:
  dws chat message set-pin-msg [flags]
Example:
  dws chat message set-pin-msg --open-conversation-id <openConversationId> --msg-id <openMessageId>
Flags:
      --open-conversation-id string    (必填)会话 openConversationId(支持群聊/单聊)
      --msg-id string                  (必填)消息 openMessageId

注意:
  - 钉住消息后,会话成员均可在会话中看到被钉住的消息
```

#### 取消钉住某条消息(Unpin) — 取消指定消息的钉住状态
```
Usage:
  dws chat message unset-pin-msg [flags]
Example:
  dws chat message unset-pin-msg --open-conversation-id <openConversationId> --msg-id <openMessageId>
Flags:
      --open-conversation-id string    (必填)会话 openConversationId(支持群聊/单聊)
      --msg-id string                  (必填)消息 openMessageId

注意:
  - 取消钉住后消息仍保留在会话中,只是不再被标记为钉住状态
```

#### 拉取某个会话中钉住的消息列表 — 拉取指定会话中被钉住的消息列表
```
Usage:
  dws chat message list-pin-msg [flags]
Example:
  dws chat message list-pin-msg --open-conversation-id <openConversationId>
  dws chat message list-pin-msg --open-conversation-id <openConversationId> --size 50
  dws chat message list-pin-msg --open-conversation-id <openConversationId> --cursor <nextCursor> --size 20
Flags:
      --open-conversation-id string    (必填)会话 openConversationId(支持群聊/单聊)
      --cursor string   (选填)分页游标,首次不传,翻页时传上次返回的 nextCursor
      --size int        (选填)一次拉取的消息数量(默认 20,最大 100)

注意:
  - 与 `chat message list` 区别: list-pin-msg 只返回被钉住的消息;list 拉取全部消息
  - 分页: hasMore=true 时,用返回的 nextCursor 作为下次 --cursor 继续翻页
```

#### 收藏消息 — 为当前用户收藏指定会话中的一条消息
```
Usage:
  dws chat message add-favorite [flags]
Example:
  dws chat message add-favorite --open-message-id <openMessageId> --open-conversation-id <openConversationId>
Flags:
      --open-message-id string        消息 openMessageId (必填)
      --open-conversation-id string   消息所在会话 openConversationId (必填)
```

#### 取消收藏消息 — 移除当前用户的收藏标记,不删除原消息
```
Usage:
  dws chat message remove-favorite [flags]
Example:
  dws chat message remove-favorite --open-message-id <openMessageId> --open-conversation-id <openConversationId>
Flags:
      --open-message-id string        消息 openMessageId (必填)
      --open-conversation-id string   消息所在会话 openConversationId (必填)
```

#### 查询收藏消息 — 分页查询当前用户收藏的消息

自动翻页使用 `--page-all` 触发,按 int64 cursor 注入下一页游标并聚合 `result.items`(不是 `result.messages`)。`--size` 仍保持 1-30 的 Open 服务范围;`--page-limit` 只控制最多请求页数。
```
Usage:
  dws chat message list-favorites [flags]
Example:
  dws chat message list-favorites
  dws chat message list-favorites --size 30
  dws chat message list-favorites --cursor 20 --size 20
Flags:
      --cursor int   数字分页游标,默认 0;翻页时传上次返回的 nextCursor
      --size int     一次拉取的收藏数量,默认 20,范围 1-30
      --page-all     自动按 nextCursor 拉取所有分页
      --page-limit int  自动翻页最多请求页数(默认 50,范围 1-500)
      --max-items int   自动翻页最多返回条数(默认 0 表示不限制)
      --page-delay int  自动翻页每页之间等待毫秒数(默认 200;0 表示不等待)

注意:
  - 首次请求可省略分页参数,CLI 会自动向 Open 服务传入 cursor=0、size="20"
  - hasMore=true 时,将 nextCursor 作为下一次的 --cursor
  - 自动翻页输出顶层 `paging` 元数据,达到 `--page-limit` 或 `--max-items` 时 `truncated=true`
```

### bot (机器人管理)

#### 搜索【我创建的】机器人 — 仅返回当前用户自己创建的机器人

范围: 仅限当前登录用户自己创建的机器人(不含他人创建、官方机器人)。
返回字段: 没有 openDingTalkId,如果需要给机器人发单聊消息请用 find。
典型触发词: "我创建的机器人""我的机器人""我自己的机器人""我做的机器人""查看我的机器人"。

```
Usage:
  dws chat bot search [flags]
Example:
  dws chat bot search --page 1
  dws chat bot search --page 1 --size 10 --name "日报"
Flags:
      --name string   按名称搜索
      --page int      页码,从1开始 (默认 1)
      --size int      每页条数 (默认 50),别名: --limit
```

#### 搜索【全部可用】机器人 — 含他人创建/官方机器人,额外返回机器人 openDingTalkId

范围: 当前用户可用的全部机器人(含他人创建、官方机器人)。
返回字段: 结果在 `result.bots[]` 中,每项含 `botOpenDingTalkId`(机器人的 openDingTalkId,用于给机器人发单聊消息)和 `name`。注意字段名是 `botOpenDingTalkId`,不是 `openDingTalkId`;search 没有此字段。
典型触发词: "搜索机器人""找一个机器人""帮我找 XXX 机器人""所有可用机器人""查机器人"。

```
Usage:
  dws chat bot find [flags]
Example:
  dws chat bot find --query "日报"
  dws chat bot find --query "日报" --limit 20
  dws chat bot find --query "日报" --limit 20 --cursor <上次返回的 nextCursor>
Flags:
      --query string   搜索关键词 (必填)
      --limit int        每页返回数量(默认 20)
      --cursor string    分页游标(首次调用不传,翻页时传上次返回的 nextCursor)

注意:
  - cursor 必须用上次返回的 nextCursor 字符串原值,不要传 "0" 或其他数字字面量
    (服务端 String 类型,但网关会把数字字符串 auto-coerce 回 Integer 导致 PARAM_ERROR)
```

search 与 find 选择指南:

| 维度 | `chat bot search` | `chat bot find` |
|------|-------------------|-----------------|
| 范围 | 仅我创建的机器人 | 全部可用机器人(含他人/官方) |
| 额外返回机器人 openDingTalkId | 无 | 有,字段名 `botOpenDingTalkId`(可用于给机器人发单聊消息) |
| 触发词 | "我创建的""我的""我自己的" | "搜索机器人""找机器人""查机器人" |

### category (会话分组管理)

#### 获取用户自定义会话分组
```
Usage:
  dws chat category list
Example:
  dws chat category list
  # 返回当前用户的所有自定义会话分组
```

#### 查看指定会话所属分组
```
Usage:
  dws chat category list-by-conv [flags]
Example:
  dws chat category list-by-conv --group <openConversationId>
Flags:
      --group string  会话 openConversationId (必填;别名 --conversation-id / --id)
```

#### 批量查询会话分组信息
```
Usage:
  dws chat category batch-info [flags]
Example:
  dws chat category batch-info --category-ids 123,456
Flags:
      --category-ids string  分组 ID 列表,逗号分隔 (必填)
```

分组 ID 可通过 `chat category list` 或 `list-by-conv` 获取。

#### 拉取指定分组下的会话列表
```
Usage:
  dws chat category list-conversations [flags]
Example:
  dws chat category list-conversations --category-id <分组ID>
  dws chat category list-conversations --category-id <分组ID> --exclude-muted
  # 分组ID 可通过 dws chat category list 获取
Flags:
      --category-id int   会话分组 ID (必填)
      --exclude-muted     是否排除已设置免打扰的会话(默认 false)
```

#### 创建会话分组
```
Usage:
  dws chat category create [flags]
Example:
  dws chat category create --title "工作群"
Flags:
      --title string   分组名称 (必填)
```

#### 创建智能会话分组 — 可指定群名称关键词和群内成员作为匹配规则
```
Usage:
  dws chat category create-smart [flags]
Example:
  dws chat category create-smart --name "工作群"
  dws chat category create-smart --name "项目组" --keywords "项目,开发"
  dws chat category create-smart --name "团队群" --members openDingTalkId1,openDingTalkId2
  dws chat category create-smart --name "重点群" --keywords "重点" --members openDingTalkId1
Flags:
      --name string       分组名称 (必填)
      --keywords string   群名称关键词列表,逗号分隔(可选)
      --members string    群内成员 openDingTalkId 列表,逗号分隔(可选)
```

#### 删除会话分组
```
Usage:
  dws chat category delete [flags]
Example:
  dws chat category delete --category-id <分组ID>
  # 分组ID 可通过 dws chat category list 获取
Flags:
      --category-id int   会话分组 ID (必填)
```

#### 重命名会话分组
```
Usage:
  dws chat category rename [flags]
Example:
  dws chat category rename --category-id <分组ID> --title "新名称"
  # 分组ID 可通过 dws chat category list 获取
Flags:
      --category-id int   会话分组 ID (必填)
      --title string      新的分组名称 (必填)
```

#### 将会话加入分组
```
Usage:
  dws chat category add-conv [flags]
Example:
  dws chat category add-conv --group <openConversationId> --category-ids 123,456
  # 分组ID 可通过 dws chat category list 获取
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string          会话 openConversationId (必填)
      --category-ids string   目标分组 ID 列表,逗号分隔 (必填)
```

#### 将会话移出分组
```
Usage:
  dws chat category remove-conv [flags]
Example:
  dws chat category remove-conv --group <openConversationId> --category-ids 123,456
  # 分组ID 可通过 dws chat category list 获取
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --group string          会话 openConversationId (必填)
      --category-ids string   目标分组 ID 列表,逗号分隔 (必填)
```

### text (文本内容处理)

#### 翻译文本内容
```
Usage:
  dws chat text translate [flags]
Example:
  dws chat text translate --query "你好世界" --to en_US
  dws chat text translate --query "Hello World" --to zh_CN
  dws chat text translate --query "Bonjour" --to ja_JP
Flags:
      --query string   待翻译的文本内容 (必填)
      --to string      目标语言代码 (必填)
```

支持的目标语言代码:`en_US`, `zh_CN`, `zh_TW`, `zh_HK`, `ja_JP`, `ko_KR`, `vi_VN`, `th_TH`, `id_ID`, `ms_MY`, `es_419`, `fr_FR`, `pt_BR`, `tr_TR`, `ru_RU`, `de_DE`, `hi_IN`, `hu_HU`, `pl_PL`, `sv_SE`, `fi_FI`, `cs_CZ`, `ar_SA`, `tl_PH`, `he_IL`, `nl_NL`, `lo_LA`, `it_IT`。

### mute (会话免打扰)

#### 会话消息免打扰 — 开启或关闭会话消息免打扰(支持单聊和群聊)
```
Usage:
  dws chat mute [flags]
Example:
  dws chat mute --conversation-id <openConversationId>
  dws chat mute --conversation-id <openConversationId> --off
  # 查询群 ID: dws chat search --query "群名"
  # 查询单聊会话 ID: dws chat conversation-info --user <userId>
Flags:
      --conversation-id string   会话 openConversationId (必填,支持单聊/群聊)
      --id string                --conversation-id 的别名
      --chat string              --conversation-id 的别名
      --off                      关闭免打扰(不传则开启免打扰)

注意:
  - 默认行为是开启免打扰,传 --off 则关闭免打扰
  - 支持单聊和群聊,openConversationId 可通过 chat search(群聊)或 chat conversation-info(单聊)获取
```

### hide (隐藏会话)

#### 隐藏会话 — 在会话列表中隐藏指定会话(支持单聊/群聊),收到新消息时会重新出现
```
Usage:
  dws chat hide [flags]
Example:
  dws chat hide --conversation-id <openConversationId>
  dws chat hide --id <openConversationId>
  # 查询群 ID: dws chat search --query "群名"
  # 查询单聊会话 ID: dws chat conversation-info --user <userId>
Flags:
      --conversation-id string   会话 openConversationId (必填,支持单聊/群聊)
      --id string                --conversation-id 的别名
      --chat string              --conversation-id 的别名

注意:
  - 隐藏后会话不再显示在列表中,收到新消息时会重新出现
  - 支持单聊和群聊,openConversationId 可通过 chat search(群聊)或 chat conversation-info(单聊)获取
```

### mute-at-all (关闭@所有人通知)

#### 关闭/开启 @所有人消息提醒 — 关闭或开启会话中 @所有人的消息通知

> 前置条件:先为会话开启总免打扰(`dws chat mute --conversation-id <openConversationId>`),否则平台返回 `NotificationOffNotEnabled`。
```
Usage:
  dws chat mute-at-all [flags]
Example:
  dws chat mute-at-all --conversation-id <openConversationId>
  dws chat mute-at-all --conversation-id <openConversationId> --off
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --conversation-id string   会话 openConversationId (必填,支持单聊/群聊)
      --id string                --conversation-id 的别名
      --chat string              --conversation-id 的别名
      --off                      恢复接收 @所有人通知(不传则关闭通知)

注意:
  - 默认行为是关闭 @所有人通知,传 --off 则恢复接收通知
  - 该子开关依赖总免打扰;恢复 @所有人通知后,再修改红包子开关前应重新开启总免打扰
  - 支持单聊和群聊,openConversationId 可通过 chat search(群聊)或 chat conversation-info(单聊)获取
```

### mute-red-envelope (关闭红包通知)

#### 关闭/开启红包消息提醒 — 关闭或开启会话中的红包消息通知

> 前置条件:先为会话开启总免打扰(`dws chat mute --conversation-id <openConversationId>`),否则平台返回 `NotificationOffNotEnabled`。
```
Usage:
  dws chat mute-red-envelope [flags]
Example:
  dws chat mute-red-envelope --conversation-id <openConversationId>
  dws chat mute-red-envelope --conversation-id <openConversationId> --off
  # 查询群 ID: dws chat search --query "群名"
Flags:
      --conversation-id string   会话 openConversationId (必填,支持单聊/群聊)
      --id string                --conversation-id 的别名
      --chat string              --conversation-id 的别名
      --off                      恢复接收红包通知(不传则关闭通知)

注意:
  - 默认行为是关闭红包通知,传 --off 则恢复接收通知
  - 若刚恢复了 @所有人通知,应先重新开启总免打扰,再修改红包通知
  - 支持单聊和群聊,openConversationId 可通过 chat search(群聊)或 chat conversation-info(单聊)获取
```

### mark-unread (标记会话为未读)

#### 标记会话为未读 — 将指定会话标记为未读状态
```
Usage:
  dws chat mark-unread [flags]
Example:
  dws chat mark-unread --conversation-id <openConversationId>
  dws chat mark-unread --id <openConversationId>
Flags:
      --conversation-id string   会话 openConversationId (必填,支持群聊/单聊)
      --id string                --conversation-id 的别名
      --chat string              --conversation-id 的别名

注意:
  - 支持群聊和单聊,openConversationId 可通过 chat search(群聊)或 chat conversation-info(单聊)获取
  - API 返回成功,但该未读状态在 API 侧观察不到:`list-all-conversations` 返回的 unreadPoint 不会随之变化,只有钉钉客户端 UI 上能看到未读标记
```

### clear-red-point (清除会话红点)

#### 清除会话红点 — 清除指定会话的未读红点
```
Usage:
  dws chat clear-red-point [flags]
Example:
  dws chat clear-red-point --conversation-id <openConversationId>
  dws chat clear-red-point --id <openConversationId>
Flags:
      --conversation-id string   会话 openConversationId (必填,支持群聊/单聊)
      --id string                --conversation-id 的别名
      --chat string              --conversation-id 的别名

注意:
  - 支持群聊和单聊,openConversationId 可通过 chat search(群聊)或 chat conversation-info(单聊)获取
  - 清除红点后该会话不再显示未读标记
```

### clear-all-red-point (红点清零)

#### 清除所有会话红点 — 一键全部已读
```
Usage:
  dws chat clear-all-red-point
Example:
  dws chat clear-all-red-point

注意:
  - 无需任何参数,直接清除当前用户所有会话的未读红点
  - 等效于"全部已读"操作
```

### list-all-conversations (全部会话列表)

#### 分页获取全部会话列表 — 获取当前用户的所有会话
```
Usage:
  dws chat list-all-conversations [flags]
Example:
  dws chat list-all-conversations
  dws chat list-all-conversations --limit 50
  dws chat list-all-conversations --limit 100 --cursor <nextCursor>
  dws chat list-all-conversations --exclude-muted
Flags:
      --limit int        每页数量(1-100,默认 100);传 >100 会被明确拒绝
      --cursor int       分页游标(首次不传或传 0,翻页传 nextCursor)
      --exclude-muted    是否排除已免打扰会话(默认 false)

注意:
  - 返回结果包含单聊和群聊,不区分会话类型
  - --limit 范围 1-100,默认 100,上限 100;传入 >100 会报错拒绝,不会静默截断
  - 分页当前不可用:当前 hasMore 恒为 false、nextCursor 恒为 null,本命令最多返回 100 条会话,无法用 --cursor 继续翻页取更多
  - 与 list-top-conversations 的区别: 本命令返回全部会话(单聊+群聊),list-top-conversations 仅返回置顶会话
```

### clear-messages (清空会话聊天记录)

#### 清空会话聊天记录 — 清空当前用户指定会话的消息

> **CAUTION:** 清空后本侧消息不可恢复。执行前必须向用户确认,同意后追加全局 `--yes` 执行。

```
Usage:
  dws chat clear-messages [flags]
Example:
  dws chat clear-messages --conversation-id <openConversationId>
  dws chat clear-messages --id <openConversationId>
Flags:
      --conversation-id string   会话 openConversationId (必填,支持群聊/单聊)
      --id string                --conversation-id 的别名
      --chat string              --conversation-id 的别名

注意:
  - 仅清空当前用户视角的消息,不影响其他成员
  - openConversationId 可通过 chat search(群聊)或 chat conversation-info(单聊)获取
```

### mark-read (标记消息已读)

#### 标记消息已读 — 将指定消息及之前的消息标记为已读
```
Usage:
  dws chat mark-read [flags]
Example:
  dws chat mark-read --conversation-id <openConversationId> --message-id <openMessageId>
  dws chat mark-read --id <openConversationId> --message-id <openMessageId>
Flags:
      --conversation-id string   会话 openConversationId (必填,支持群聊/单聊)
      --id string                --conversation-id 的别名
      --chat string              --conversation-id 的别名
      --message-id string        消息 openMessageId (必填)

注意:
  - 标记该消息及之前的所有消息为已读
  - openConversationId 可通过 chat search(群聊)或 chat conversation-info(单聊)获取
  - openMessageId 可通过 chat message list 获取
```

### group list-all (分页拉取所有群)

#### 分页拉取我所有群列表 — 获取当前用户加入的所有群聊
```
Usage:
  dws chat group list-all [flags]
Example:
  dws chat group list-all
  dws chat group list-all --limit 50
  dws chat group list-all --limit 100 --cursor <nextCursor>
Flags:
      --limit int       每页返回数量(默认 100,最大 200)
      --cursor string   分页游标(首次不传,翻页传返回的 nextCursor)

注意:
  - 与 `chat group list-my-groups` 区别: list-all 返回用户加入的所有群;list-my-groups 仅返回用户作为群主/管理员的群
  - 分页: hasMore=true 时用返回的 nextCursor 作为下次 --cursor
  - ⚠️ 存在同步盲区:新建群后较长时间(实测 15 分钟后全量翻页仍查不到)内不会出现在 list-all 里;而 `chat group list-my-groups` / `chat search` 能立即查到。要确认刚建的群,用 list-my-groups 或 search,别依赖 list-all
```

### group list-join-validations (分页拉取入群验证记录)

#### 分页拉取入群验证记录 — 获取当前用户的所有入群验证记录

包括自己被拒绝的记录以及作为审批者的记录。

```
Usage:
  dws chat group list-join-validations [flags]
Example:
  dws chat group list-join-validations
  dws chat group list-join-validations --limit 30
  dws chat group list-join-validations --limit 20 --cursor <nextCursor>
Flags:
      --limit int       单页数量(默认 20,最大 50)
      --cursor string   分页游标(首次不传,翻页传返回的 nextCursor)

注意:
  - 分页: hasMore=true 时用返回的 nextCursor 作为下次 --cursor
  - cursor 首次拉取不传或传 null 时从当前时间开始拉
```

### group audit-join-validation (审批入群验证)

#### 审批入群验证 — 通过、删除单个审核

当前仅 AuditApprove(通过)和 AuditDelete(删除)两个动作可用。

```
Usage:
  dws chat group audit-join-validation [flags]
Example:
  dws chat group audit-join-validation --group <openConversationId> --record-id 123456 --applicant <openDingTalkId> --inviter <openDingTalkId> --status AuditApprove
  dws chat group audit-join-validation --group <openConversationId> --record-id 123456 --applicant <openDingTalkId> --inviter <openDingTalkId> --status AuditDelete
  # 查询入群验证记录: dws chat group list-join-validations
Flags:
      --group string        群 openConversationId (必填)
      --record-id string    申请记录 ID (必填)
      --applicant string    申请人 openDingTalkId (必填)
      --inviter string      邀请人 openDingTalkId (必填)
      --status string       审批动作: AuditApprove(通过) / AuditDelete(删除) (必填)
      --description string  审批说明(可选)

注意:
  - status 仅支持 AuditApprove(通过) 和 AuditDelete(删除);AuditIgnore(忽略)、AuditRefuse(拒绝)、AuditBlock(拒绝且拉黑) 会被服务端拒绝报 unsupported audit status,属服务端限制
  - record-id、applicant、inviter 可通过 dws chat group list-join-validations 查询获得
```

### toolbar (快捷栏管理)

快捷栏(toolbar)是会话级快捷入口管理能力,支持查询、添加、隐藏、排序及自定义入口 CRUD。与 `internal/shortcut/` 下的智能快捷方式框架是两套独立能力。

#### 查询快捷栏入口列表
```
Usage:
  dws chat toolbar list [flags]
Example:
  dws chat toolbar list --conversation-id <cid>
Flags:
      --conversation-id string  会话 openConversationId (必填)
```

#### 将入口添加到快捷栏可见区
```
Usage:
  dws chat toolbar add [flags]
Example:
  dws chat toolbar add --conversation-id <cid> --shortcut-ids 101,102
Flags:
      --conversation-id string  会话 openConversationId (必填)
      --shortcut-ids string     入口 ID 列表,逗号分隔 (必填)
```

#### 将入口从快捷栏可见区隐藏
```
Usage:
  dws chat toolbar hide [flags]
Example:
  dws chat toolbar hide --conversation-id <cid> --shortcut-ids 101,102
Flags:
      --conversation-id string  会话 openConversationId (必填)
      --shortcut-ids string     入口 ID 列表,逗号分隔 (必填)
```

#### 排序快捷栏入口
```
Usage:
  dws chat toolbar sort [flags]
Example:
  dws chat toolbar sort --conversation-id <cid> --sorted-ids 101,102,103
  dws chat toolbar sort --conversation-id <cid> --sorted-ids 101,102 --unsorted-ids 103,104
Flags:
      --conversation-id string  会话 openConversationId (必填)
      --sorted-ids string       排序后的入口 ID 列表,逗号分隔 (必填)
      --unsorted-ids string     不参与排序放在末尾的入口 ID 列表,逗号分隔
```
注意:`--sorted-ids` 与 `--unsorted-ids` 不能有交集。

#### 创建自定义快捷栏入口
```
Usage:
  dws chat toolbar create-custom [flags]
Example:
  dws chat toolbar create-custom --conversation-id <cid> --title "周报" --url "https://example.com" --icon-url "https://example.com/icon.png" --pc-url "https://example.com"
Flags:
      --conversation-id string  会话 openConversationId (必填)
      --title string            入口标题 (必填)
      --url string              入口跳转链接 (必填)
      --icon-url string         入口图标 URL (必填)
      --pc-url string           PC 端跳转链接 (必填)
      --extension stringArray   扩展信息,格式 key=value,可重复使用
      --desc string             入口描述(为空时使用 --title)
      --tag string              入口标签
      --sort-index int          排序权重
```

#### 删除自定义快捷栏入口
```
Usage:
  dws chat toolbar remove-custom [flags]
Example:
  dws chat toolbar remove-custom --conversation-id <cid> --shortcut-id 123
Flags:
      --conversation-id string  会话 openConversationId (必填)
      --shortcut-id int         自定义入口 ID (必填)
      --yes                     确认执行删除操作
```
注意:删除操作不可逆,必须先获得用户确认后加 `--yes` 执行。

#### 更新自定义快捷栏入口
```
Usage:
  dws chat toolbar update-custom [flags]
Example:
  dws chat toolbar update-custom --conversation-id <cid> --shortcut-id 123 --title "周报" --url "https://example.com" --icon-url "https://example.com/icon.png" --pc-url "https://example.com"
Flags:
      --conversation-id string  会话 openConversationId (必填)
      --shortcut-id int         自定义入口 ID (必填)
      --title string            入口标题 (必填)
      --url string              入口跳转链接 (必填)
      --icon-url string         入口图标 URL (必填)
      --pc-url string           PC 端跳转链接 (必填)
      --extension stringArray   扩展信息,格式 key=value,可重复使用
      --desc string             入口描述
      --tag string              入口标签
      --sort-index int          排序权重
```

入口 ID 可通过 `dws chat toolbar list --conversation-id <cid>` 获取。

## 意图判断

用户说"我特别关注的人最近发了什么消息/关注的人最近聊了啥/星标联系人最近的动态" → `chat message list-focused`(零参数一行命令)
用户说"某人发给我的消息/指定发送者的消息/某人最近的消息" → `chat message list-by-sender --sender-user-id <userId>` 或 `--sender-open-dingtalk-id <openDingTalkId>`(跨单聊+群聊)
用户说"和某人的单聊聊天记录/拉某人单聊历史" → `chat message list --user <userId>` 或 `--open-dingtalk-id <openDingTalkId>`
用户说"某个群的聊天记录" → `chat message list --group <openConversationId>`
用户说"最近 24 小时或指定时间以来哪些单聊或群聊有新消息/最近活跃会话" → `chat +recent-conversations`;仅指定时间范围时传 `--start/--end`
用户说"我最近所有消息正文/我今天的消息正文" → `chat message list-all --start <ISO> --end <ISO>`
用户说"@我的消息/提及我的" → `chat message list-mentions --start <ISO> --end <ISO>`
用户说"搜索消息里的关键词/包含XX的消息" → `chat message search-advanced --query "<关键词>"`(首选,严格超集)
用户说"我和某人的共同群" → `chat search-common --nicks "<昵称1>,<昵称2>"`
用户说"未读会话列表" → `chat message list-unread-conversations`
用户说"群里某条话题的回复/逐条列出当前回复/撤回后看看具体还剩哪些回复" → `chat thread list-replies --conversation-id <openConversationId> --topic-id <openConvThreadId>`
用户说"置顶会话/置顶消息" → `chat list-top-conversations` 列会话 → 再 `chat message list --group <id>` 拉消息(两步)

用户说"建群/创建群聊" → `chat group create`
用户说"搜索群/找群" → `chat search`
用户说"我创建的群/我管理的群/我是群主的群/我当管理员的群" → `chat group list-my-groups`
用户说"群成员/看群里有谁" → `chat group members`
用户说"拉人进群/加群成员" → `chat group members add`
用户说"踢人/移除群成员" → `chat group members remove`
用户说"加机器人到群" → `chat group members add-bot`
用户说"改群名" → `chat group rename`
用户说"设置群备注/给群加备注" → `chat group update-alias`
用户说"改我在群里的昵称/设置群昵称" → `chat group update-nick --nick`
用户说"清除/取消群昵称" → `chat group update-nick --group <openConversationId>`(不传 `--nick`)
用户说"把普通群升级为外部群/保留原群并支持外部联系人" → `chat group upgrade-to-external`(不可逆,仅群主;确认后 `--yes`)
用户说"批量查群成员信息/按ID查群成员" → `chat group members list-by-ids`
用户说"聊天记录/会话消息/拉取会话" → `chat message list`
用户说"某人发给我的消息/指定发送者/某人的消息" → `chat message list-by-sender`(用户未明确说"单聊"时优先使用,跨单聊/群聊)
用户说"拉取和某人的单聊记录/单聊消息" → `chat message list --user`(用户明确说"单聊"时使用)
用户说"@我的消息/at我的/提及我的" → `chat message list-mentions`
用户说"未读消息会话/未读会话列表/我的未读会话" → `chat message list-unread-conversations`
用户说"发群消息(以个人身份)" → `chat message send --conversation-id`
用户说"发单聊消息(以个人身份)" → `chat message send --user`(有 userId 时)或 `chat message send --open-dingtalk-id`(有 openDingTalkId 时)
用户说"机器人发消息/机器人群发" → `chat message send-by-bot`
用户说"撤回我发的消息/撤回消息" → `chat message recall`(通过 IM 接口撤回当前用户自己发出的消息,需要 openConversationId + openMessageId)
用户说"编辑/修改已发送消息" → `chat message edit`(`--text` / `--content` 二选一)
用户说"撤回机器人发的消息/机器人撤回消息" → `chat message recall-by-bot`(通过机器人接口撤回机器人发出的消息,需要 robot-code + processQueryKey)
用户说"Webhook 发消息/告警消息" → `chat message send-by-webhook`
用户说"回复话题" → `chat thread reply --conversation-id <openConvThreadId>`
用户说"查看话题回复/拉取话题回复/列出每条回复内容/核实某条回复是否还在" → `chat thread list-replies`
用户说"指定时间以来有消息的会话/最近活跃会话/哪些单聊群聊有新消息" → `chat +recent-conversations`
用户说"所有消息/全部会话消息/拉取全部消息/时间范围内消息正文/我的消息正文/我今天的消息正文/查我的钉钉消息正文" → `chat message list-all`
用户说"特别关注人的消息/关注的人的消息/星标联系人的消息" → `chat message list-focused`
用户说"消息已读未读/谁看了消息/查读状态/消息读取状态" → `chat message read-status`
用户说"查看我的机器人" → `chat bot search`
用户说"搜索消息/查找关键词/搜一下消息里的XX" → 优先使用 `chat message search-advanced`(推荐首选,严格超集);仅在简单关键词搜索且无其他维度需求时可用 `chat message search`
用户说"多维度搜索/按发送者搜索/按人搜消息/指定多个群搜索/@我的消息搜索" → `chat message search-advanced`(推荐首选,支持多维度组合搜索)
用户说"查询消息发送状态/消息发没发成功/消息状态" → `chat message query-send-status`
用户说"我和XX的共同群/我们都在哪些群/查共同群" → `chat search-common`
用户说"置顶会话/置顶消息/我的置顶/查看置顶" → `chat list-top-conversations`
用户说"查看会话分组/自定义分组" → `chat category list`
用户说"这个会话属于哪些分组" → `chat category list-by-conv`
用户说"按多个分组 ID 批量查分组信息" → `chat category batch-info`
用户说"某个分组下的会话/分组会话列表" → `chat category list-conversations`
用户说"新建会话分组/创建分组" → `chat category create`
用户说"创建智能分组/新建智能会话分组" → `chat category create-smart`
用户说"删除会话分组" → `chat category delete`
用户说"重命名分组/改分组名" → `chat category rename`
用户说"把会话加入分组/会话归类到分组" → `chat category add-conv`
用户说"把会话移出分组/从分组移除会话" → `chat category remove-conv`
用户说"根据群号查群信息/群号查群/群号转openConversationId" → `chat group get-by-group-id`(当用户发消息时只提供了群号,用此工具将群号转为 openConversationId,再调用发消息接口)
用户说"查看群身份/群的自定义身份列表" → `chat group-role list`
用户说"创建/添加群身份" → `chat group-role add`
用户说"修改/更新群身份名称" → `chat group-role update`
用户说"删除群身份" → `chat group-role remove`
用户说"给某人设置群身份/设定用户的群身份" → `chat group-role set-user`
用户说"移除某人的群身份/撤销群身份" → `chat group-role remove-user`
用户说"查询某人的群身份/某人在群里有什么身份" → `chat group-role query-user`
用户说"转让群主/换群主/群主转让" → `chat group transfer-owner`
用户说"群邀请链接/入群链接/加群链接" → `chat group invite-url`
用户说"分享群链接/把群分享给某人/群链接发到某群" → `chat group share-invite`
用户说"群公告/发布公告/修改公告/查看公告/定时公告" → `chat group notice create/edit/get/list`
用户说"批量查消息/按ID查消息/根据消息ID查" → `chat message list-by-ids`
用户说"批量查消息回复/表情回复/文字回复/消息回应列表" → `chat message list-emotion-replies`
用户说"查看个人收藏表情/列出我的收藏表情" → `chat emotion list`
用户说"发送个人收藏表情/发表情包" → `chat emotion send`
用户说"收藏表情/新增个人收藏表情/把本地图片收藏为表情/上传图片做表情" → `chat emotion favorite`
用户说"emoji回应/表情回应/给消息加表情" → `chat message add-emoji`
用户说"取消emoji回应/移除表情回应" → `chat message remove-emoji`
用户说"文字表情回应/添加文字表情" → `chat message add-text-emotion`
用户说"修改文字表情回应/更新消息状态文字" → `chat message update-text-emotion`
用户说"取消文字表情回应/移除文字表情" → `chat message remove-text-emotion`
用户说"创建文字表情/新建文字表情" → `chat message create-text-emotion`
用户说"免打扰/消息免打扰/静音/开启免打扰/关闭免打扰" → `chat mute`
用户说"隐藏会话/隐藏群聊/隐藏对话" → `chat hide`
用户说"关闭@所有人通知/屏蔽@所有人/不接收@all" → `chat mute-at-all`
用户说"开启@所有人通知/恢复@所有人提醒" → `chat mute-at-all --off`
用户说"关闭红包通知/屏蔽红包/不接收红包提醒" → `chat mute-red-envelope`
用户说"开启红包通知/恢复红包提醒" → `chat mute-red-envelope --off`
用户说"标记会话未读/标为未读" → `chat mark-unread`
用户说"标记已读/把消息标成已读" → `chat mark-read`
用户说"清除红点/去掉某个会话的未读红点" → `chat clear-red-point`
用户说"全部已读/一键清除红点/红点清零" → `chat clear-all-red-point`
用户说"我的所有会话/全部会话列表" → `chat list-all-conversations`
用户说"清空聊天记录/清空会话消息" → `chat clear-messages`
用户说"我加入的所有群/我的全部群列表" → `chat group list-all`
用户说"入群验证记录/谁申请进群" → `chat group list-join-validations`
用户说"审批入群/通过入群申请/拒绝入群申请" → `chat group audit-join-validation`
用户说"引用回复/回复消息/引用消息回复" → `chat message reply`
用户说"机器人引用回复/让机器人回复这条群消息" → `chat message send-by-bot --conversation-id <openConversationId> --reply <openMessageId> --ref-sender <senderOpenDingTalkId> --text <内容>`
用户说"转发消息/转发一条消息/把消息转发到另一个群" → `chat message forward`
用户说"合并转发/批量转发/合并转发多条消息" → `chat message combine-forward`
用户说"转发话题/转发话题消息" → `chat thread forward`
用户说"置顶消息/把消息置顶" → `chat message set-top-msg`
用户说"取消置顶消息/撤销消息置顶" → `chat message unset-top-msg`
用户说"发送/上传本地图片或媒体到聊天" → `chat message send --msg-type file --file <本地路径>`
用户明确要求机器人发送公网图片 URL → `chat message send-by-bot --msg-type image --image-url <图片 URL>`
用户明确要求机器人发送本地图片或文件 → `chat message send-by-bot --msg-type file --file-path <本地路径>`,按文件附件发送
用户明确只要 mediaId → DWS CLI 当前不提供本地上传入口;仅在上游已有有效 mediaId 时使用 `chat message send --msg-type image --media-id`
用户说"群机器人列表/群里有哪些机器人/查看群机器人" → `chat group bots`
用户说"从群里移除机器人/踢出机器人" → `chat group members remove-bot`
用户说"搜索机器人/找机器人/查机器人/帮我找XXX机器人" → `chat bot find`(全部可用机器人,额外返回 botOpenDingTalkId 可发单聊)
用户说"给机器人发单聊/给机器人发消息/跟机器人聊天" → 必须先 `chat bot find`(拿 openDingTalkId)→ 再 `chat message send --open-dingtalk-id`(search 没有 openDingTalkId,无法发单聊)
用户说"我创建的机器人/我的机器人/我自己的机器人/查看我的机器人" → `chat bot search`(仅我创建的机器人,无 openDingTalkId)
用户说"解散群/解散群聊" → `chat group dismiss`
用户说"设置历史消息/新成员看历史/新成员可见消息" → `chat group set-history`
用户说"置顶会话/取消置顶/会话置顶" → `chat set-top`(设置/取消置顶),`chat list-top-conversations`(查看置顶列表)
用户说"全员禁言/群禁言/解除禁言" → `chat group-mute`
用户说"禁言某人/指定成员禁言/解除某人禁言" → `chat group-mute-member`
用户说"设管理员/取消管理员/设置群管理员" → `chat group set-admin`
用户说"翻译文本/把这段话翻译成英文/翻译成中文" → `chat text translate`

关键区分:
- `chat search` — 搜**群/会话名**返回 `openConversationId`,**不**搜消息内容;要搜消息内容请用 `chat message search-advanced`(首选)/ `chat message search` / `list-by-sender` / `list-all`,**勿混淆**
- `chat message list` — 拉取指定会话的消息(需指定 --group 或 --user),按时间点 + 方向翻页
- `chat message list --user` — list 的单聊模式,拉取与指定用户的单聊记录(用户明确说"单聊""私聊"时使用)
- `chat message list-by-sender` — 搜索指定发送者发给我的消息,跨所有会话(单聊+群聊均包含,用户只说"某人发的消息"时优先使用)
- `chat message list-mentions` — 拉取 @我 的消息(跨单聊/群聊,可选指定群)
- `chat message list-unread-conversations` — 拉取当前用户存在未读消息的会话列表(可选 `--count`)
- `chat message read-status` — 查询指定消息的已读/未读状态(仅消息发送者可查询自己发的消息,需指定 --group 和 --message-id,可选 --target-open-dingtalk-ids 查特定人)
- `chat message list-all` — 拉取当前用户所有会话的消息,按时间范围 + cursor 分页。只要用户没有指定某个具体的会话(如某个群名、某个人名),即使提到"单聊消息""群聊消息"等笼统范围,也应路由到此命令
- `chat thread list-replies` — 使用父会话 `openConversationId` 与 Thread `openConvThreadId` 拉取回复;只有需要按主消息自动解析、全量翻页、排序或下载资源时才使用现有的 `chat +thread-replies`
- `chat message list-focused` — 拉取特别关注人的消息,cursor 分页
- `chat list-top-conversations` — 拉取置顶会话列表(用户询问"置顶会话"或"置顶消息"时路由到此),cursor 分页
- `chat conversation-file upload` — 只把工作目录内的本地文件上传到指定会话文件空间,返回 `dentryId`/`spaceId`,不发送消息;URL 代传不受支持
- `chat message send` — 以当前用户身份发消息(群聊或单聊),正文可用 `--content` 或位置参数;本地图片/文件/音视频统一用 `--msg-type file --file`,其中图片显示为可下载附件而非内联图片;`--msg-type image --media-id` 只用于上游已经提供有效 mediaId 的场景,DWS CLI 不能从本地文件生成 mediaId
- `chat message search` — 按关键词搜索消息内容(跨所有会话,可选指定群)
- `chat search-common` — 搜索共同群,查询指定人共同所在的群聊(AND=所有人都在,OR=任一人在)
- `chat message send-by-bot` — 以**机器人**身份发消息(群聊或单聊);Markdown 使用 `--text`,公网图片使用 `--msg-type image --image-url`,本地图片和文件使用 `--msg-type file --file-path`;群聊 Markdown 引用回复成对使用 `--reply` / `--ref-sender`
- `chat message send-by-webhook` — 通过**自定义机器人 Webhook** 发群消息
- `chat message recall-by-bot` — 通过**机器人接口**撤回机器人发出的消息,需要 `--robot-code` + `--keys`(发送时返回的 processQueryKey);传 `--group` 为群聊撤回,不传为单聊撤回
- `chat message recall` — 通过 **IM 接口**撤回当前用户自己发出的消息,需要 `--conversation-id`(openConversationId)+ `--msg-id`(openMessageId,可通过 `chat message list` 获取);群聊单聊均通过 `--conversation-id` 区分
- `chat message query-send-status` — 查询个人发送的消息的发送状态(需 send 返回的 openTaskId)
- `chat message search-advanced` — 多维度搜索消息(支持关键词、发送者、@我、@指定人、多个会话等维度组合,与 `search` 的区别:`search` 仅支持关键词且必填,`search-advanced` 所有参数均可选)
- `chat message list-by-ids` — 根据消息 ID 批量查询消息(最多 50 条)
- `chat message add-emoji` / `remove-emoji` — 对消息添加/移除 emoji 表情回应
- `chat message list-emotion-replies` — 批量拉取消息的表情回复和文字回复
- `chat message add-text-emotion` / `update-text-emotion` / `remove-text-emotion` — 对消息添加、原地更新或移除文字表情回应
- `chat message create-text-emotion` — 创建文字表情模板,返回 emotionId 供 add-text-emotion 使用
- `chat emotion list` / `send` / `favorite` — 当前用户个人收藏表情列表、发送和新增;不同于消息 reaction/文字回应
- `chat category list` — 获取用户自定义会话分组列表
- `chat category list-conversations` — 拉取指定分组下的会话列表
- `chat category create-smart` — 创建智能会话分组(可指定群名称关键词和成员作为匹配规则)
- `chat category list-by-conv` / `chat category batch-info` — 查询会话所属分组 / 批量查询分组信息
- `chat mute` — 开启/关闭会话消息免打扰(默认开启,--off 关闭)
- `chat hide` — 在会话列表中隐藏会话(支持单聊/群聊,收到新消息时重新出现)
- `chat mute-at-all` — 关闭/开启 @所有人消息提醒(默认关闭,--off 恢复;需先开启总免打扰)
- `chat mute-red-envelope` — 关闭/开启红包消息提醒(默认关闭,--off 恢复;需先开启总免打扰)
- `chat mark-unread` / `chat mark-read` — 标记会话未读 / 标记指定消息及之前的消息已读
- `chat clear-red-point` / `chat clear-all-red-point` — 清除单个会话红点 / 一键清除所有会话红点(全部已读)
- `chat list-all-conversations` — 分页拉取当前用户全部会话列表(单聊+群聊,与 list-top-conversations 的区别是不限置顶)
- `chat clear-messages` — 清空当前用户视角下指定会话的聊天记录(不影响其他成员)
- `chat group list-all` — 分页拉取当前用户加入的所有群(list-my-groups 仅返回群主/管理员的群)
- `chat group list-join-validations` / `chat group audit-join-validation` — 拉取入群验证记录 / 审批入群验证(通过/拒绝/删除/忽略/拉黑)
- `chat file upload` — 已下线;不要调用 `chat/upload_conversation_file_by_url`,只上传本地文件改用 `chat conversation-file upload`
- `chat group transfer-owner` — 转让群主
- `chat group upgrade-to-external` — 将普通群不可逆升级为外部群(仅群主,需确认)
- `chat group update-nick` — 设置群昵称;省略 `--nick` 时清除
- `chat group invite-url` — 获取群邀请链接
- `chat group share-invite` — 分享群聊链接到会话
- `chat group notice create/edit/get/list` — 群公告发布、修改、详情、列表
- `chat message reply` — 引用回复消息(在群聊中引用某条消息并回复文字)
- `chat message edit` — 编辑已发送 Markdown 消息(支持 @成员 / @所有人)
- `chat message forward` — 转发单条消息(将一条消息从源会话转发到目标会话)
- `chat set-top` — 设置/取消会话置顶(默认置顶,--off 取消)
- `chat group-mute` — 全员禁言/取消全员禁言(默认禁言,--off 取消)
- `chat group-mute-member` — 指定群成员禁言/取消禁言(需指定 --users 和 --mute-time)
- `chat group set-admin` — 设置/取消群管理员(默认设为管理员,--off 取消)

## openDingTalkId 获取方式

多个命令参数需要 openDingTalkId(如 --open-dingtalk-id、--at-open-dingtalk-ids、--sender-open-dingtalk-id),统一获取方式如下:

1. 若知道姓名:`dws contact user search --query "姓名"` → 直接从结果中获取 openDingTalkId
2. 若只有 userId:先 `dws contact user get --ids <userId>` 获取姓名 → 再 `dws contact user search --query "姓名"` 获取 openDingTalkId

openDingTalkId 为当前用户视角下的目标用户唯一标识,不可跨用户共享。

## 核心工作流

```bash
# 1. 搜索群 — 提取 openconversation_id
dws chat search --query "项目冲刺" --format json

# 2. 拉取群消息
dws chat message list --group <openconversation_id> --time "2025-03-01 00:00:00" --format json

# 2b. 拉取未读会话列表
dws chat message list-unread-conversations --count 20 --format json

# 3. 以个人身份发送群消息
dws chat message send --conversation-id <openconversation_id> --title "周报提醒" "请大家本周五前提交周报" --format json

# 4. 以个人身份单聊(通过 userId)
dws chat message send --user <userId> "你好" --format json

# 4b. 以个人身份单聊(通过 openDingTalkId,三方应用等无法获取 userId 时使用)
dws chat message send --open-dingtalk-id <openDingTalkId> "你好" --format json

# 5. 机器人发群消息(Markdown)
dws chat message send-by-bot --robot-code <robot-code> \
  --group <openconversation_id> --title "日报" --text "## 今日完成..." --format json

# 6. 机器人单聊发消息
dws chat message send-by-bot --robot-code <robot-code> \
  --users userId1,userId2 --title "提醒" --text "请提交周报" --format json

# 7. Webhook 发告警
dws chat message send-by-webhook --token <webhook-token> \
  --title "告警" --content "CPU 超 90% @10" --at-all --format json
```

## 复合工作流

### 机器人发消息后撤回(完整流程)

`recall-by-bot` 通过机器人接口撤回机器人发出的消息(需要 `--robot-code` + `--keys`)。`chat message recall` 通过 IM 接口撤回当前用户自己发出的消息(需要 `--conversation-id` + `--msg-id`)。

```bash
# Step 1: 查我的机器人 — 提取 robot-code
dws chat bot search --format json

# Step 2: 用机器人发消息 — 提取返回中的 processQueryKey
dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> \
  --title "通知" --text "内容" --format json

# Step 3: 用同一个 robot-code + processQueryKey 撤回
dws chat message recall-by-bot --robot-code <robot-code> --group <openconversation_id> \
  --keys <processQueryKey> --format json
```

### 机器人发群消息(含机器人不在群内的处理)

机器人通过 `send-by-bot --group` 发群消息时,如果返回"机器人不存在"错误,说明该机器人尚未加入目标群,需先邀请进群再发送。

```bash
# Step 1: 查我的机器人 — 提取 robot-code
dws chat bot search --format json

# Step 2: 尝试发送,若报"机器人不存在"则执行 Step 3
dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> \
  --title "通知" --text "内容" --format json

# Step 3: 邀请机器人进群
dws chat group members add-bot --group <openconversation_id> --robot-code <robot-code>

# Step 4: 重新发送
dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> \
  --title "通知" --text "内容" --format json
```

### 给机器人发单聊消息(必须先用 find 拿 openDingTalkId)

给机器人发单聊消息时,必须先用 `chat bot find` 搜索机器人拿到 `openDingTalkId`,再用 `chat message send --open-dingtalk-id` 发送。不能用 `chat bot search`,因为 search 不返回 `openDingTalkId`。

```bash
# Step 1: 搜索机器人 — 提取 openDingTalkId(必须用 find,search 没有此字段)
dws chat bot find --query "玉澜" --format json

# Step 2: 用 openDingTalkId 发单聊消息
dws chat message send --open-dingtalk-id <openDingTalkId> --content "你好" --format json
```

### 机器人 @指定人发群消息

通过 `--at-user-ids` 传入 userId 列表或 `--at-open-dingtalk-ids` 传入 openDingtalkId 列表来 @指定成员,多个用逗号分隔。`--content` 中需包含 `@userId` 或 `@openDingtalkId` 文本(不要用尖括号,不要用姓名)。通过 `--at-all` @所有人。

```bash
# Step 1: 搜人获取 userId
dws contact user search --query "张三" --format json

# Step 2: 用 userId 发送并 @(注意 text 中 @userId)
dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> \
  --at-user-ids userId1,userId2 \
  --title "提醒" --text "@userId1 @userId2 请查收本周报告" --format json

# 或者用 openDingtalkId 发送并 @
dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> \
  --at-open-dingtalk-ids openDingtalkId1,openDingtalkId2 \
  --title "提醒" --text "@openDingtalkId1 @openDingtalkId2 请查收本周报告" --format json

# @所有人
dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> \
  --at-all --title "通知" --text "请所有人注意" --format json
```


### 发送文件 + 文字说明(两条消息)

本地图片和文件先用 `--msg-type file --file` 发送,再补一条文本消息说明;这是两条独立消息,不需要媒体上传或钉盘前置步骤。图片会显示为可下载的文件附件,不会内联渲染。
如果用户明确要求机器人身份,两条消息都必须改用 `chat message send-by-bot`,不得降级为个人身份发送。

```bash
dws chat message send --conversation-id <openconversation_id> --msg-type file --file ./screenshot.png --format json
dws chat message send --conversation-id <openconversation_id> --content "这是本周的数据汇总" --format json
```

机器人身份发送文件及说明:

```bash
dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> --msg-type file --file-path ./report.pdf --format json
dws chat message send-by-bot --robot-code <robot-code> --group <openconversation_id> --text "这是本周的数据汇总" --format json
```

如果调用方已经从上游取得有效 mediaId,可以先用 `--msg-type image --media-id` 发送内联图片,再补一条文本消息;DWS CLI 本身不能把本地图片转换成 mediaId。

### 发送图片或文件

公网图片 URL 使用 `--msg-type image --image-url`,按图片消息发送。本地图片和其他本地文件一样使用 `--msg-type file --file-path`,由 CLI 上传并按文件附件发送。明确要求机器人身份时使用 `dws chat message send-by-bot`,不得降级为个人身份。

```bash
# 机器人发送图片
dws chat message send-by-bot --robot-code <robot-code> --group <openConversationId> --msg-type image --image-url "https://example.com/image.png" --format json

# 当前用户发送文件
dws chat message send --conversation-id <openConversationId> --msg-type file --file ./report.pdf --format json

# 机器人发送文件
dws chat message send-by-bot --robot-code <robot-code> --group <openConversationId> --msg-type file --file-path ./report.pdf --format json
```

**带文字说明**:在上一步发完文件后,再补一条文本消息即可。不要尝试把文字塞进 `--msg-type file` 命令(该命令不读 `--content`)。

```bash
dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file ./report.pdf --format json
dws chat message send --open-dingtalk-id <openDingTalkId> --content "这是本周数据汇总" --format json
```

**已有 mediaId(仅当上游已经提供有效 mediaId 时才用)**:

```bash
dws chat message send --conversation-id <openConversationId> --msg-type image --media-id "@lQLPD4JNnliqBq3NBQDNA8Cw" --format json
```

#### 创建并推送卡片 — streaming 与 A2UI 独立命令

`send-card` 创建 streaming 卡片,群聊传 --conversation-id,单聊传 --open-dingtalk-id,二者互斥。群聊创建时可通过 --at-open-dingtalk-ids @指定成员,或通过 --at-all @所有人。

**注意:send-card 必须和 update-card 搭配使用。** 创建卡片时无需传入内容,后续通过 update-card 更新内容,最后一次更新必须将 --flow-status 设为 3(finish),否则卡片会一直处于"生成中"的加载状态。

`send-a2ui-card` 调用 `im.create_and_send_a2ui_card`,必须传 `--content` JSON 字符串数组(元素为 A2UI 协议 JSON)。生成内容时可参考 [A2UI 展示卡片指南](chat/a2ui.md),使用完整的 `createSurface`、组件定义和数据绑定创建卡片。CLI 会解析为 `a2uiMessages`,并用换行拼接为 `summary`,单聊传 userId 时自动解析为 openDingTalkId。创建时默认 `flowStatus=PROCESSING`。可选 `--a2ui-annotations` 接受 JSON 对象数组并透传为 `a2uiAnnotations`,支持 `[]`;省略时创建请求不携带该字段。
```
Usage:
  dws chat message send-card [flags]
Example:
  dws chat message send-card --conversation-id <openConversationId>
  dws chat message send-card --conversation-id <openConversationId> --at-open-dingtalk-ids <openDingTalkId>
  dws chat message send-card --conversation-id <openConversationId> --at-all
  dws chat message send-card --open-dingtalk-id <openDingTalkId>
  # 查询群 ID: dws chat search --query "群名"
  # 查询人员: dws aisearch person --query "姓名" --dimension name
Flags:
      --at-all                           群聊创建卡片时 @ 所有人(仅与 --conversation-id 一起使用)
      --at-open-dingtalk-ids string      群聊创建卡片时 @ 的 openDingTalkId 列表,逗号分隔(仅与 --conversation-id 一起使用)
      --conversation-id string           群聊 openConversationId
      --open-dingtalk-id string          单聊接收者 openDingTalkId
```

#### 更新卡片内容 — streaming 与 A2UI 独立命令

`update-card` 通过 `im.update_streaming_card` 更新 streaming 卡片。`--flow-status` 的 CLI 类型为 string,仍只接受兼容数字 1-5,并向 RPC 发送 integer。
`update-a2ui-card` 通过 `im.update_a2ui_card` 更新 A2UI 卡片,`--content` 必须是 JSON 字符串数组并发送为 `a2uiMessages`,可通过 `--a2ui-annotations` 传入 JSON 对象数组,省略时发送 `a2uiAnnotations: []`。A2UI `--flow-status` 接受 PROCESSING、INPUTTING、FINISH、EXECUTING、ERROR、ABORTED、TIMEOUT、CONFIRMING、CONFIRMED,也兼容数字 1-9 并映射为对应枚举字符串。

**最后一次更新必须将 --flow-status 设为 3(finish),否则卡片会一直处于"生成中"的加载状态。**
更新结果不确定时不要再次执行更新;保留返回结果并告知用户。
```
Usage:
  dws chat message update-card [flags]
Example:
  dws chat message update-card --biz-id <bizId> --content "更新的卡片内容" --flow-status 2
  dws chat message update-card --biz-id <bizId> --content "最终内容" --flow-status 3
  dws chat message update-a2ui-card --biz-id <bizId> --content '["{\"version\":\"v1.0\",\"updateDataModel\":{\"surfaceId\":\"surface\",\"path\":\"/status\",\"value\":\"finished\"}}"]' --flow-status CONFIRMED
Flags:
      --biz-id string    卡片业务 ID (必填)
      --content string   卡片消息内容 (必填)
      --flow-status string 流式状态 (必填)
```

## 上下文传递表

| 操作 | 从返回中提取 | 用于 |
|------|-------------|------|
| `chat search` | `openConversationId` | message send/list、group members 等的 --group |
| `chat group create` | `openConversationId` | 同上 |
| `chat message list-all` | `nextCursor` | 下次 list-all 的 --cursor |
| `aisearch person` | `userId` | message send 的 --user、send-by-bot 的 --users、send-by-bot 的 --at-user-ids、list-by-sender 的 --sender-user-id |
| `aisearch person` → `contact user get` | `openDingTalkId` | message send 的 --at-open-dingtalk-ids、--open-dingtalk-id、send-by-bot 的 --open-dingtalk-ids、send-by-bot 的 --at-open-dingtalk-ids、list-by-sender 的 --sender-open-dingtalk-id、message list 的 --open-dingtalk-id |
| `chat bot search` | `robotCode` | send-by-bot / recall-by-bot 的 --robot-code(仅我创建的机器人,无 openDingTalkId) |
| `chat bot find` | `botOpenDingTalkId` | 给机器人发单聊消息(send --open-dingtalk-id;字段名是 botOpenDingTalkId,非 openDingTalkId) |
| `chat message send-by-bot` | `processQueryKey` | recall-by-bot 的 --keys |
| `chat message send` | `openTaskId` | query-send-status 的 --open-task-id |
| `chat message query-send-status` | `openMessageId` + `openConversationId` | 刚发送消息的 edit / recall |
| `chat message list` | `openMessageId` | 历史消息或已丢失 openTaskId 时的 recall |
| `chat message search` | `nextCursor` | 下次 message search 的 --cursor |
| `chat message search-advanced` | `nextCursor` | 下次 message search-advanced 的 --cursor |
| `chat search-common` | `openConversationId` | message send/list 等的 --group |
| `chat conversation-info` | `newCSpaceIdIM` | 独立钉盘存储流程的共享空间 ID;不是发送本地聊天附件的前置条件 |
| `chat conversation-file upload` | `dentryId` + `spaceId` | 后续需要引用已上传的会话文件标识;该命令本身不发送消息 |
| `chat file upload` | 无(已下线) | 不要调用;只上传本地文件改用 `chat conversation-file upload`,发文件消息用 `chat message send --msg-type file --file` |
| `chat message list` | `openMsgId` | message read-status 的 --message-id |
| `chat group-role list` | `openRoleId` | group-role update/remove/set-user 的 --role-id;remove-user 的 --role-ids |
| `chat message create-text-emotion` | `emotionId` | add-text-emotion 的 --emotion-id |
| `chat category list` | `categoryId` | category list-conversations 的 --category-id |
| `chat group get-by-group-id` | `openConversationId` | 同 chat search,将群号转为 openConversationId |
| `chat message send-card` | `bizId` | update-card 的 --biz-id |
| `chat message list` | `openMessageId` | message reply 的 --ref-msg-id、send-by-bot 机器人群聊引用回复的 --reply、message forward 的 --msg-id |
| `chat search` | `openConversationId` | set-top 的 --conversation-id、group-mute / group-mute-member 的 --group |

## 注意事项

- **发消息前参数审查(必须执行)**:
  - 发消息(`chat message send`、`send-by-bot`、`send-by-webhook`、`send-card`、`send-a2ui-card`、`reply`、`forward`)是严肃操作,一旦发错人/发错群会导致严重问题,因此在执行发送之前,agent 必须对所有参数进行内部审查
  - 审查方式:将即将发送的**全部参数**(收件人/群、消息内容或 A2UI 内容、@对象、消息类型等)与用户的**原始需求**逐一对比,确认每个参数都能从原始需求中找到明确依据
  - 如果存在任何不明确、有歧义或原始需求中未提及的参数(例如:用户没说发给谁、没说发到哪个群、消息内容与用户意图有出入、不确定是否需要 @某人等),**必须先向用户确认**,严禁自行假设或补全
  - 典型需要确认的场景:用户只说了"发个消息"但没指定群/人;用户的描述可匹配多个群或多个联系人;消息文本由 agent 组织而非用户原文提供时需确认措辞
- idempotency key 幂等参数(发消息最佳实践):
  - 发消息时建议始终带上 `--idempotency-key` 参数,传入用户自行生成的唯一标识(如 UUID v4),用于幂等控制
  - 如果发送失败需要重试,重试时 `--idempotency-key` 必须与首次发送保持一致,服务端据此去重,避免重复发消息
  - 如果不传 `--idempotency-key`,每次调用都视为新消息,重试可能导致消息重复发送
  - 此参数适用于 `chat message send`(群聊和单聊均支持)
- `--group` 为群聊会话 ID (openconversation_id),可从群搜索或群聊信息中获取
- `chat message send` 的正文可用 `--content` 或位置参数(恰好 1 个);群聊用 `--conversation-id`,单聊用 `--user`(userId)或 `--open-dingtalk-id`(openDingTalkId),三者互斥;纯文本/Markdown 单聊传 `--user` 时直接走 userId 发送能力;`--at-all`、`--at-open-dingtalk-ids` 仅在 `--conversation-id` 群聊时生效;本地图片/文件/音视频统一用 `--msg-type file --file`,其中图片是可下载附件;`--msg-type image --media-id` 仅用于上游已经提供有效 mediaId 的内联图片
- `chat message list-all` 的四个参数(--start、--end、--limit、--cursor)每次请求都必须传递;翻页时用响应中的 nextCursor 值作为下次 --cursor
- `chat message list` 的 `--group`、`--user`、`--open-dingtalk-id` 三者互斥,必须且只能指定其一
- `chat message list-by-sender` 不需要指定单聊/群聊,返回结果自带会话类型标识;`--sender-user-id`(userId)与 `--sender-open-dingtalk-id`(openDingTalkId)二选一;时间用 `--start`/`--end`(ISO-8601),分页用 `--limit`/`--cursor`
- `chat message list-mentions` 可选 `--group` 指定群聊,不传则查全部;时间用 `--start`/`--end`(ISO-8601),分页用 `--limit`/`--cursor`
- `chat message list-unread-conversations` 获取当前用户未读会话列表,可选 `--count` 指定返回条数
- `chat message search` 按关键词搜索消息内容,`--query` 必填,可选 `--group` 限定搜索某个会话;时间用 `--start`/`--end`(ISO-8601),分页用 `--limit`(默认 100)/`--cursor`
- `chat message read-status` 查询指定消息的已读/未读状态,仅消息发送者可查询自己发出的消息;`--group`、`--message-id` 必填;目标用户 userId 用 `--user`/`--users`,openDingTalkId 用 `--target-open-dingtalk-ids`,不传则查所有接收者
- `chat search-common` 搜索共同群,`--nicks` 传人员昵称(逗号分隔),`--match-mode` AND/OR 控制匹配逻辑,分页用 `--limit`(默认 20)/`--cursor`
- `chat list-top-conversations` 拉取置顶会话列表,分页用 `--limit`(默认 1000)/`--cursor`;用户询问"置顶会话"或"置顶消息"时均路由到此命令
- `--user` 和 `--open-dingtalk-id` 本质上都是发起单聊操作,只是用户标识格式不同:userId 为企业内部应用常用标识,openDingTalkId 为三方应用或跨组织场景下的用户标识,服务端对两种 ID 的解析逻辑不同
- `--time` 格式: `yyyy-MM-dd HH:mm:ss`,为拉取消息的起始时间点;`--direction` 控制方向(newer=从给定时间往现在拉,older=从给定时间往以前拉),`--limit` 控制数量
- `chat search` 挂在 `chat` 下(非 `chat group` 下),路径为 `dws chat search`
- `send-by-bot` 群聊传 `--conversation-id`,单聊传 `--users` 或 `--open-dingtalk-ids`,与群目标互斥且必选其一;机器人群聊 Markdown 引用回复必须同时传 `--reply <openMessageId>` 与 `--ref-sender <senderOpenDingTalkId>`,单聊、图片和文件不支持引用回复;群聊时可选 `--at-user-ids` @指定成员(传 userId 列表)或 `--at-open-dingtalk-ids` @指定成员(传 openDingTalkId 列表),content 中需包含对应 @标识;`--at-all` @所有人;群聊场景如果返回"机器人不存在"错误,需先通过 `chat group members add-bot --conversation-id <openConversationId> --robot-code <robot-code>` 将机器人邀请进群后再发送
- `recall-by-bot` 群聊传 `--group` + `--keys`,单聊仅传 `--keys`(不传 `--group` 即为单聊撤回)
- `send-by-webhook` 支持 `--at-all`、`--at-mobiles`、`--at-users` 进行 @ 操作,但需在 `--content` 中包含 `@userId` 或 `@手机号` 才能生效;`--at-all` @所有人时需在 `--content` 中包含 `@10`
- `chat group-role` 系列命令用于管理群的自定义身份标签:`list` 查列表,`add` 创建,`update` 改名,`remove` 删除;`set-user` 用单个 `--role-id` 覆盖某人全部身份(不支持传空值清除),`remove-user` 仅移除指定身份,`query-user` 查询某人当前身份;用户用 `--user <userId>`
- 消息**换行符**(`send` / `send-by-webhook` 使用 `--content`,`send-by-bot` 使用 `--text`)有两层要求:(1) 必须是**真实换行符** `U+000A`,不是字面量 `\n`;(2) Markdown 规范下单换行不生效,需用空行 `\n\n`(段落分隔)或行尾两空格 + 换行 / `<br>`(硬换行)
- `chat group transfer-owner` 转让群主,需传 --group(openConversationId);新群主 userId 用 `--user`,openDingTalkId 用 `--new-owner`
- `chat group invite-url` 获取群邀请链接,需传 --group(openConversationId),可选 --expires-seconds 指定有效期(秒,0=永久)
- `chat group quit` 退出群聊,需传 --group(openConversationId)
- `chat group update-icon` 更新群头像,需传 --group(openConversationId)和由可信上游提供的有效 --icon-media-id(mediaId);DWS CLI 不能从本地图片生成该 ID
- `chat group update-settings` 更新群设置,需传 --group(openConversationId)、--setting-key(设置项 key)、--status(0=关闭 1=开启)
- `chat message send-card` 创建并推送 streaming 卡片;`chat message send-a2ui-card` 创建并推送 A2UI 卡片,必须传 JSON 字符串数组 `--content`
- `chat message update-card` 流式更新卡片内容;`chat message update-a2ui-card` 更新 A2UI 卡片,content 必须是 JSON 字符串数组,flowStatus 接受枚举名和兼容数字 1-9
- `chat message list-by-ids` 根据消息 ID 批量查询,--msg-ids 逗号分隔,最多 50 条
- `chat message add-emoji` / `remove-emoji` 需传 --group(openConversationId)、--msg-id(openMsgId)、--emoji(表情名称)
- `chat message add-text-emotion` / `remove-text-emotion` 需传 --group、--msg-id、--emotion-id、--emotion-name、--text、--background-id,六个参数全部必填
- `chat message create-text-emotion` 创建文字表情模板,返回 emotionId;--background-id 可选,不传由服务端默认分配
- `chat category list` 无需参数;`category list-conversations` 需传 --category-id(通过 category list 获取)
- `chat mute` 默认开启免打扰,传 --off 关闭;--conversation-id / --id / --chat 三个别名均可用于传入会话 ID
- `chat hide` 隐藏会话,需传 --conversation-id(openConversationId,支持单聊/群聊),隐藏后不显示在列表中,收到新消息时重新出现
- `chat mute-at-all` 关闭/开启 @所有人消息提醒,需传 --conversation-id(openConversationId),默认关闭通知,传 --off 恢复接收;调用前需先开启总免打扰
- `chat mute-red-envelope` 关闭/开启红包消息提醒,需传 --conversation-id(openConversationId),默认关闭通知,传 --off 恢复接收;调用前需先开启总免打扰
- `chat message reply` 引用回复消息(**单聊/群聊均可**),需传 --group(openConversationId,单聊与群聊使用同一字段)、--ref-msg-id(被引用消息 openMessageId)、--ref-sender(被引用消息发送者 openDingTalkId)、--content(回复内容);目前回复类型仅支持 text
- `chat message forward` 转发单条消息(**源/目标会话均支持单聊/群聊**,常见组合:群→群、群→单、单→群、单→单),需传 --src-conversation-id(源会话 openConversationId)、--msg-id(源消息 openMessageId)、--dest-conversation-id(目标会话 openConversationId)
- `chat set-top` 设置/取消会话置顶(**单聊/群聊均可**),需传 --conversation-id(openConversationId,单聊与群聊使用同一字段),默认置顶,传 --off 取消
- `chat message reply` 以当前用户身份引用回复,与 `chat message send` 的用户身份发送语义一致
- **如何获取 openConversationId**(如果上层已有则直接使用,不必再查):
  - 群聊:`dws chat search --query "群名"`
  - 单聊:`dws chat conversation-info --user <userId>` 或 `dws chat conversation-info --open-dingtalk-id <openDingTalkId>`(人员信息可通过 `dws aisearch person --query "姓名" --dimension name` 获取)
- `chat group-mute` 全员禁言/取消全员禁言,需传 --group(openConversationId),默认禁言,传 --off 取消
- `chat group-mute-member` 指定群成员禁言,需传 --group、--user/--users(userId,逗号分隔)、--mute-time(毫秒,仅禁言时必填,支持 300000/3600000/86400000/604800000/2592000000),传 --off 解除禁言;CLI 会自动把 userId 解析成 openDingTalkId 再调用,直接传 userId 即可;禁言群主会被服务端拒绝
- `chat group set-admin` 设置/取消群管理员,需传 --group(openConversationId)、--user/--users(userId,逗号分隔),默认设为管理员,传 --off 取消

## Runtime 替代旧 Chat 脚本

- 群聊/单聊全量导出:`dws chat +chat-messages --page-all --output <相对.json>`;目标可用稳定 ID 或唯一自然查询。
- Bot 多群广播:`dws chat +messages-send --as bot --groups ...` 或 `--groups-file ...`;输出 `im.batch-write.v1` 逐项 ledger。
- 旧 Chat 导出与广播脚本已停止发布,不能在执行计划中引用。

## 相关产品

- [contact](./contact.md) — 搜索同事/好友,获取 userId 用于 --user、send-by-bot --users、send-by-bot --at-user-ids、list-by-sender --sender-user-id;获取 openDingTalkId 用于 message send 的 --at-open-dingtalk-ids、--open-dingtalk-id、send-by-bot --open-dingtalk-ids、send-by-bot --at-open-dingtalk-ids、list-by-sender 的 --sender-open-dingtalk-id
- [drive](./drive.md) — 钉盘文件存储与下载;不是发送本地聊天图片/文件的前置步骤
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall