钉钉集成
将钉钉 Stream 机器人连接到 Mopheus，在钉钉中与智能体协作并接收工单更新。
钉钉集成
钉钉集成可将钉钉 Stream 机器人连接到 Mopheus 中的智能体或小队。私聊消息会直接处理；群聊中必须 @机器人。消息、图片、工单状态变更和普通工单评论都会回推到来源钉钉会话。
前置条件
在钉钉开放平台创建企业内部机器人应用，启用 Stream 事件投递，配置机器人消息事件，并授予收发消息所需权限。记录应用的 AppKey 和 AppSecret。
Mopheus 通过 Stream 连接钉钉，不需要公网 Webhook 地址、额外部署密钥或环境开关。
配置 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。 |