# DING 消息 (ding) 命令参考

## 命令总览

### 发送 DING 消息
```
Usage:
  dws ding message send [flags]
Example:
  dws ding message send --robot-code <ROBOT_CODE> --users <USER_ID_1>,<USER_ID_2> --content "请查看"
Flags:
      --content string      消息内容 (必填)
      --robot-code string   机器人 ID (必填, 可从 应用管理→机器人 获取, 或设 DINGTALK_DING_ROBOT_CODE)
      --users string         接收人 userId 列表 (必填)
      --type string         提醒类型: app/sms/call (默认 app)
```

### 撤回 DING 消息
```
Usage:
  dws ding message recall [flags]
Example:
  dws ding message recall --robot-code <ROBOT_CODE> --id <OPEN_DING_ID>
Flags:
      --id string           DING 消息 ID (必填)
      --robot-code string   机器人 ID (必填, 或设 DINGTALK_DING_ROBOT_CODE)
```

### 查询 DING 消息历史
```
Usage:
  dws ding message list [flags]
Example:
  dws ding message list
  dws ding message list --type UNREAD
  dws ding message list --type SEND --cursor 10
Flags:
      --cursor int     分页游标 (首次传 0, 翻页传返回的 nextCursor)
      --type string    消息类型: ALL / UNREAD / SEND / NEW_COMMENT / DELETED (可选, 不传返回全部)
```

### 查看 DING 接收状态
```
Usage:
  dws ding message receiver-status [flags]
Example:
  dws ding message receiver-status --ding-id <OPEN_DING_ID>
  # 查询 dingId: dws ding message list
Flags:
      --ding-id string   DING 消息 openDingId (必填)
```

### 以用户身份发送 DING — 以当前用户身份（非机器人）发送 DING 消息
```
Usage:
  dws ding message send-personal [flags]
Example:
  dws ding message send-personal --users openDingTalkId1,openDingTalkId2 --content "请查看"
  dws ding message send-personal --type call --users openDingTalkId1 --content "紧急告警"
  # 查询 openDingTalkId: dws aisearch person --query "姓名" --dimension name
Flags:
      --users string     接收者 openDingTalkId 列表，逗号分隔 (必填)
      --content string   DING 内容 (必填)
      --type string      提醒类型: app/sms/call (默认 app)
      --uuid string      幂等唯一标识（可选，不传由服务端生成）

注意:
  - 与 `ding message send`（机器人身份）不同：send-personal 以当前用户身份发送，无需 --robot-code
  - 接收者使用 openDingTalkId（非 userId），可通过 `dws aisearch person --query "姓名" --dimension name` 获取
  - sms/call 类型有通信费用，使用前需和用户确认
```

### 以用户身份撤回 DING — 以当前用户身份撤回已发送的 DING 消息
```
Usage:
  dws ding message recall-personal [flags]
Example:
  dws ding message recall-personal --id <openDingId>
  # 查询 openDingId: dws ding message list
Flags:
      --id string   DING 消息 openDingId (必填)

注意:
  - 与 `ding message recall`（机器人身份）不同：recall-personal 以当前用户身份撤回，无需 --robot-code
  - openDingId 可通过 `dws ding message list` 或 `send-personal` 返回值获取
```

### 消息转 DING — 将聊天消息转为 DING 通知发送给指定接收者
```
Usage:
  dws ding message send-by-message [flags]
Example:
  dws ding message send-by-message --group <openConversationId> --message-id <openMessageId> --users id1,id2
  dws ding message send-by-message --group <openConversationId> --message-id <openMessageId> --users id1 --type sms
  # 查询 openDingTalkId: dws aisearch person --query "姓名" --dimension name
  # 查询 openConversationId: dws chat search --keyword "群名"
Flags:
      --group string       原消息所在会话 openConversationId (必填)
      --message-id string  原消息 openMessageId (必填)
      --users string       接收者 openDingTalkId 列表，逗号分隔 (必填)
      --type string        提醒类型: app/sms/call (默认 app)
      --uuid string        幂等唯一标识（可选，不传由服务端生成）

注意:
  - 与 `send-personal` 不同: send-by-message 是将已有聊天消息转发为 DING，需要指定原消息的会话和消息 ID
  - 接收者使用 openDingTalkId，可通过 `dws aisearch person --query "姓名" --dimension name` 获取
  - sms/call 类型有通信费用，使用前需和用户确认
```

## 意图判断

用户说"DING 一下/紧急通知/电话提醒" → `message send`
用户说"以我的名义 DING/个人发 DING/用户身份 DING" → `message send-personal`
用户说"消息转 DING/把这条消息 DING 给某人/转发为 DING" → `message send-by-message`
用户说"撤回 DING" → `message recall`
用户说"以我的名义撤回 DING/个人撤回 DING" → `message recall-personal`
用户说"DING 消息/查 DING/DING 历史/我的 DING" → `message list`
用户说"DING 接收状态/谁收到了 DING/DING 已读" → `message receiver-status`

关键区分:
- `ding message send`（机器人身份，需 --robot-code） vs `ding message send-personal`（用户身份，无需 robot-code） vs `ding message send-by-message`（消息转 DING，需指定原消息）
- `ding message recall`（机器人身份） vs `ding message recall-personal`（用户身份）
- ding(紧急提醒, 支持电话/短信) vs bot(常规群/单聊消息)
- sms/call 类型有通信费用

## 核心工作流

```bash
# 机器人身份: 应用内 DING (免费)
dws ding message send --robot-code <ROBOT_CODE> --type app --users userId1,userId2 --content "请查看" --format json

# 机器人身份: 电话 DING (紧急, 有成本!)
dws ding message send --robot-code <ROBOT_CODE> --type call --users userId1 --content "紧急告警" --format json

# 机器人身份: 撤回
dws ding message recall --robot-code <ROBOT_CODE> --id <OPEN_DING_ID> --format json

# 用户身份: 应用内 DING
dws ding message send-personal --users openDingTalkId1,openDingTalkId2 --content "请查看" --format json

# 用户身份: 电话 DING (紧急, 有成本!)
dws ding message send-personal --type call --users openDingTalkId1 --content "紧急告警" --format json

# 用户身份: 消息转 DING
dws ding message send-by-message --group <openConversationId> --message-id <openMessageId> --users openDingTalkId1,openDingTalkId2 --format json

# 用户身份: 撤回
dws ding message recall-personal --id <OPEN_DING_ID> --format json
```
## 上下文传递表
| 操作 | 提取 | 用于 |
|------|------|------|
| `message send` | `openDingId` | message recall 的 --id |
| `message send-personal` | `openDingId` | message recall-personal 的 --id |
| `message list` | `openDingId` | message receiver-status 的 --ding-id |
| `message send-by-message` | `openDingId` | message recall-personal 的 --id |
## 注意事项
- `--robot-code` 从钉钉开放平台 应用管理 → 机器人 中获取，也可设环境变量 `DINGTALK_DING_ROBOT_CODE`
- `send` / `recall` 是机器人身份，需要 --robot-code；`send-personal` / `recall-personal` / `send-by-message` 是用户身份，无需 robot-code
- `send` 接收者使用 userId；`send-personal` / `send-by-message` 接收者使用 openDingTalkId（可通过 `dws aisearch person --query "姓名" --dimension name` 获取）
- `send-by-message` 是将已有聊天消息转发为 DING，需指定 --group 和 --message-id
- sms/call 类型有通信费用，使用前需和用户确认
- 默认 `--type app` 为应用内 DING（免费）

---

## SKILL 摘要（原 dingtalk-ding/SKILL.md 正文）

<!-- VISIBLE_SHORTCUTS_START -->
## Shortcuts（无专用脚本/recipe 时优先）

以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "ding +<shortcut>" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws ding <shortcut> --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service ding --format json` 批量发现。

| Shortcut | 风险 | 适用场景 |
|---|---|---|
| `dws ding +receiver-status` | read | 查询 DING 消息接收人已读状态 |
<!-- VISIBLE_SHORTCUTS_END -->

## 意图表

| 用户说 | 命令 |
|--------|------|
| "DING 张三" / "应用内紧急通知" | `dws ding message send --type app --users <userId> --content "<内容>"` |
| "短信 DING" | `dws ding message send --type sms --users <userId> --content "<内容>"` |
| "电话 DING" / "电话叫人" | `dws ding message send --type call --users <userId> --content "<内容>"` |
| "撤回 DING" | `dws ding message recall --id <id> --robot-code <robotCode>` |
| "以我的名义发 DING / 个人 DING" | `dws ding message send-personal --users <openDingTalkId> --content "<内容>"` |
| "以我的名义撤回 DING" | `dws ding message recall-personal --id <openDingId>` |
| "DING 历史 / 接收状态" | `dws ding message list` / `dws ding message receiver-status` |

## 跨产品协作

- 接收人是人名 → 先用 `dingtalk-aisearch` 拿 `userId`
- 普通通知（不需必达）→ 切到 `dingtalk-chat`
## 局部意图与 Recipe

- [局部意图消歧](ding-intent-guide.md)；[Lite Recipe](ding-lite-recipes.md)。