钉钉集成
将钉钉 Stream 机器人连接到 Mopheus，在钉钉中与智能体协作并接收工单更新。
钉钉集成可将钉钉 Stream 机器人连接到 Mopheus 中的智能体或小队。私聊消息会直接处理；群聊中必须 @机器人。消息、图片、工单状态变更和普通工单评论都会回推到来源钉钉会话。
前置条件
在钉钉开放平台完成以下配置：
-
在 应用开发 中创建应用，并记录应用的 AppKey 和 AppSecret。
-
进入应用详情，在添加应用能力中选择机器人。
-
进入机器人配置，启用 Stream 模式/Stream 事件投递，配置机器人消息事件，并授予机器人发送消息、接收消息和发送媒体消息所需的权限。若机器人需要处理图片或文件，也要启用对应的媒体权限。
在权限管理中开通机器人发送、接收消息以及图片/文件媒体所需的权限(正常选机器人,权限即满足要求,无需额外添加)。
在事件订阅中选择
Stream模式推送，点击已完成接入，验证连接通道，再点击保存。
-
确认应用的可用范围包含需要使用机器人的成员和群聊。
完成以上配置后，进入版本管理与发布，点击创建新版本，填写版本信息后点击发布。机器人配置和事件订阅通常要在已发布版本中才会生效。
Mopheus 通过 Stream 主动连接钉钉，因此不需要公网 Webhook 地址、HTTP 回调地址、额外部署密钥或环境开关。app_url 是 Mopheus 的账号绑定链接地址，与钉钉 Stream 连接不是同一个配置。
权限与事件检查
| 配置 | 用途 |
|---|---|
| 机器人接收消息事件 | 接收私聊和群聊中的机器人消息 |
| 机器人发送消息权限 | 回传智能体回复、绑定提示和工单通知 |
| 图片/文件媒体权限 | 下载并处理消息中的图片或文件 |
| 应用可用范围 | 决定哪些成员和群聊可以使用机器人 |
修改权限或事件订阅后保存机器人配置，并确认已连接的机器人使用最新配置。
配置 Mopheus
在 设置 → 系统配置 中设置：
| 配置项 | 值 |
|---|---|
启用渠道 (channel_enabled) | true |
启用钉钉 (dingtalk_enabled) | true |
钉钉密钥 (dingtalk_secret_key) | 用于加密已安装 AppSecret 的 Base64 编码 32 字节密钥 |
应用 URL (app_url) | Mopheus Web 应用的公网地址，例如 https://app.example.com |
应用 URL 用于一次性账号关联链接。它必须指向提供 /dingtalk/bind 的 Web 应用，不能是不可访问的本地开发端口或 API 地址。
在系统配置中通过 dingtalk_secret_key 旁的 生成 或 轮换 操作管理密钥。轮换会先重新加密全部已安装钉钉应用的 AppSecret，再保存新密钥。已有安装时不要手动替换该值。
连接机器人
打开智能体或小队，在集成区域选择 连接钉钉应用。表单只接收两项：
| 字段 | 钉钉值 |
|---|---|
| AppKey | 应用 AppKey |
| AppSecret | 应用 AppSecret |
Mopheus 会在保存前验证凭据，并对 AppSecret 进行静态加密。数据库事务提交后，渠道监督器会重新协调连接；两个启用开关均开启时将启动该机器人。
关联账号
未关联的发送者首次发消息时会收到一个指向 /dingtalk/bind 的私聊 Markdown 链接。登录 Mopheus 后打开链接，即可把钉钉身份关联到当前 Mopheus 账号。令牌只能使用一次，15 分钟后过期。
即使原消息来自群聊，关联链接也只会私聊发送，以避免其他群成员关联他人的钉钉身份。
消息与媒体
- 私聊会路由到选定智能体，或选定小队的负责人。
- 群聊只有 @机器人时才会路由。
- 钉钉图片以及富文本内嵌图片会立即下载、校验为图片内容、保存为 Mopheus 附件，并提供给智能体任务。
- 文件下载使用受限客户端：本地、私有、回环地址和不安全重定向都会被拒绝。
- 超长智能体回复会拆分为有效的钉钉 Markdown 消息；访问令牌会缓存，并在钉钉拒绝过期令牌时自动刷新重试一次。
工单通知
智能体从钉钉会话创建工单时，Mopheus 会在创建阶段将不可变的来源会话和来源消息写入工单 metadata。后续状态变更和普通评论会推送回原始会话。没有来源消息锚点的旧工单会回退到会话路由。
排障
| 现象 | 检查项 |
|---|---|
| 安装已保存但没有 Stream 日志 | 确认 channel_enabled 与 dingtalk_enabled 都是 true。安装只会在数据库事务提交成功后重新协调监督器。 |
| 账号关联页面失败 | 确认 app_url 是可访问的前端 URL，并先登录后再打开链接。修正旧 URL 后请重新生成链接。 |
| 机器人忽略群消息 | 在群里 @机器人，并确认安装状态为启用。 |
| 机器人无法读取图片 | 检查机器人媒体权限，并确认图片未超过入站大小限制。 |
| 修改密钥后已有机器人失效 | 使用系统配置中的轮换操作；手动替换 dingtalk_secret_key 无法解密旧 AppSecret。 |