# 钉钉

钉钉接入使用钉钉 Stream 模式，用户可私聊机器人或在群聊中 @ 机器人完成设备查询、控制和协作；当前通道以文本为主，设备智能体会回复到原钉钉会话。

## 使用方式

| 方式 | 触发方式 | 说明 |
| --- | --- | --- |
| 私聊机器人 | 直接向机器人发送文本 | 适合个人远程查询和控制设备。 |
| 群聊 @ 机器人 | 在群里 @ 机器人并输入问题 | 适合组织内多人协作。没有 @ 机器人时，群消息不会触发设备智能体。 |

## 在钉钉后台准备应用

1. 在钉钉开发者后台创建应用。
2. 开启机器人能力。
3. 消息接收模式选择 Stream 模式。
4. 在应用信息中复制 `Client ID` 和 `Client Secret`。
5. 发布应用。
6. 私聊机器人，或把机器人加入群聊；群聊中需要 @ 机器人。

## 在控制台填写配置

打开 **设置 → IM 通道 → 钉钉**，填写以下字段：

| 字段 | `.env` | 说明 |
| --- | --- | --- |
| 启用 | `DINGTALK_ENABLED` | 是否启动钉钉通道 |
| Client ID | `DINGTALK_CLIENT_ID` | 钉钉应用的 `Client ID`，旧称 `AppKey` |
| Client Secret | `DINGTALK_CLIENT_SECRET` | 钉钉应用的 `Client Secret`，旧称 `AppSecret` |
| 白名单 | `DINGTALK_ALLOW_FROM` | 可选，允许访问的员工 ID |

也可以在 `.env` 中配置：

```bash
DINGTALK_ENABLED=true
DINGTALK_CLIENT_ID=dingxxxxxxxxxxxx
DINGTALK_CLIENT_SECRET=xxxxxxxxxxxxxxxx
DINGTALK_ALLOW_FROM=user1,user2
```

保存后重启服务，配置才会生效。

## 验证接入

1. 确认服务已重启。
2. 日志中出现 `DingTalk: enabled` 和 `Channel started (Stream Mode)`。
3. 私聊机器人发送消息，或在群里 @ 机器人。
4. 如果启用了白名单，确认发送者员工 ID 已写入白名单。

设备智能体回复时，会优先使用钉钉回调中的会话地址；如果不可用，会通过钉钉开放接口发送到原会话。

## 常见检查项

- 没有回复：确认应用已发布，机器人已加入会话，并且 Stream 模式已启用。
- 群里无响应：确认消息中 @ 了机器人。
- 白名单后无响应：确认填写的是员工 ID，不是昵称。