在 IM 里使用 Mole Agent

Mole Agent 通过通知设置里的连接器在飞书、Slack、钉钉、企业微信、Google Chat 和 Microsoft Teams 里回答。在群里 @ 它，或者私聊它。处理的时候它会表示正在处理：飞书和 Slack 在你的消息上加一个表情，企业微信、Google Chat 和 Teams 先回复一条“正在查”，答好后原地换成答案。答案附上 MoleSignal 里这个会话的链接。 这些会话就是普通的 Mole Agent 会话：在 MoleSignal 里能看到、能接着问，计入组织的每日预算，也和别的回答一样打分。参见质量。

​

怎么收消息

除了 Teams，每个连接器都由一台 MoleSignal 服务器主动连出去收消息，MoleSignal 不需要能被公网访问。Teams 需要一个 https 的公网回调地址，先看完 Teams 的安全措施。每个平台要准备的地址、账号和权限见外部条件。

​

开始之前

• 开启需要 agent.manage，提问的人需要 agent.use。
• 在设置 → 通知 → 连接器里有对应平台的连接器（见上表）：Slack App 要填 Bot Token 和 App-Level Token，Google Chat App 要填 Pub/Sub 订阅。参见通知渠道。
• 要让大家自己绑定账号、让回复带上会话的链接，MoleSignal 要配置对外地址 http.external_url。Teams 还要求它是 https 地址，回调地址就在它下面。参见配置。

​

在平台上设置

​

飞书

如果用的是 Lark，把连接器的 API 基础地址设为 https://open.larksuite.com/open-apis。

​

Slack

​

钉钉

连接器的 Client ID 和 Client Secret 就是应用的凭证。机器人 RobotCode 不单独填时就是 Client ID。

​

企业微信

企业微信用智能机器人回答：它用 API 模式的长连接收消息，回复也走这条连接。

• 一个机器人同一时间只能有一条长连接。别处用同一个 Bot ID 连上时（例如另一套 MoleSignal 或测试环境），MoleSignal 的连接会被挤掉，状态显示连不上及原因。每套环境用各自的机器人。
• 长连接和 URL 回调只能选一种。机器人改成 URL 回调后，长连接就断了。
• 机器人的创建人是企业的超级管理员时，消息里的成员 userid 是明文，否则是加密过的。加密的 userid 不方便管理员手工绑定，请大家用 Mole Agent 发的一次性链接自己绑定。
• 这个连接器不发通知，发通知请用企业微信 App 或企业微信 Webhook 连接器。

​

Google Chat

Google Chat App 把消息发到一个 Cloud Pub/Sub 主题，MoleSignal 从它的订阅里拉取，不需要公网地址。

• 订阅的确认时限保留默认的 10 秒即可：MoleSignal 拉到就确认。
• 在空间和群聊里，只有 @ 应用的消息会发给它，在话题里接着问也要 @ 它。私聊收到每一条。

​

Microsoft Teams

Teams 的消息由 Bot Framework 投到 MoleSignal 的公网回调地址。这是唯一需要从公网访问 MoleSignal 的平台，开启前先按 Teams 的安全措施准备好对外地址。

• 在频道和群聊里，只有 @ Bot 的消息会发给它，在帖子下接着问也要 @ 它。私聊收到每一条。
• 只支持 Azure 公有云的 Bot Framework。

​

Teams 的安全措施

Teams 的回调地址在公网上。MoleSignal 对它做了这些检查：

• 每个请求都验 Bot Framework 的令牌。 这个地址不认 MoleSignal 的登录，只认 Bot Framework 签的 JWT：签名的密钥来自 login.botframework.com 的 OpenID 元数据（缓存 24 小时）；iss 是 https://api.botframework.com；aud 是这个 Bot 的应用 ID；exp 和 nbf 允许 5 分钟误差；签名的密钥要为 Teams 渠道（msteams）背书；令牌里的 serviceUrl 要和消息里的一致。验不过返回 401 或 403，消息不处理。
• 回复只发给 Bot Framework。 MoleSignal 只把 Bot 的令牌发给 Bot Framework 的服务地址（smba.trafficmanager.net、*.botframework.com、*.teams.microsoft.com）或连接器里配的服务地址，消息里的地址不是这些时拒收。
• 只收自己的租户。 连接器的租户填租户 ID（GUID）时，别的租户发来的消息不处理。填域名或 botframework.com 时不限制。
• 地址只对开着的连接器有效。 连接器没在 IM 接入里开启、停用了或删了，回调地址返回 404。地址里只有连接器的 ID，不含密钥。
• 限制正文大小。 超过 256 KiB 的请求直接拒绝。

部署上请再做到：

1. 只把回调路径开放到公网。 用反向代理或网关只转发 POST /api/v1/public/im/teams/，登录页和其他 API 仍只在内网访问。例如 nginx：
   server {
     listen 443 ssl;
     server_name molesignal.example.com;
     # ssl_certificate 与 ssl_certificate_key …
     client_max_body_size 256k;
   
     location /api/v1/public/im/teams/ {
       limit_except POST { deny all; }
       proxy_pass http://molesignal.internal:8080;
       proxy_set_header Host $host;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto https;
     }
   
     location / {
       return 404;
     }
   }
   
   如果员工也通过这个对外地址访问 MoleSignal，就在网关上把其他路径限制在公司网络或 VPN 里，只让回调路径对公网开放。
2. 用 https。 http.external_url 要是 https 地址，Teams 不往 http 投；TLS 可以在代理上终止，证书要是公共 CA 签发的。
3. 可选：按来源限制。 可以在防火墙或网关上只允许 Azure 服务标记 AzureBotService 里的地址访问回调路径。这些地址会变，要跟着 Azure 公布的列表更新；令牌的验证仍然是主要的防线。
4. 保管好客户端密码。 它随连接器加密保存，接口不会返回。定期轮换，换了之后在连接器里更新；Bot 的应用注册只授予它需要的权限。
5. 留意异常。 回调请求和令牌验证失败会记在 MoleSignal 的日志与追踪里；IM 接入里能看到每个连接器最近一次收到消息的时间。

​

外部条件

每个平台在 MoleSignal 外面要准备好的东西：

• 防火墙或出站代理要放行上表里的出站地址。WebSocket 长连接（飞书、Slack、钉钉、企业微信）直接连到平台，不经过 HTTP 代理。
• Teams 的入站要有：公网 DNS、公共 CA 签发的证书、只转发回调路径的反向代理，见 Teams 的安全措施。
• 自己绑定账号、回复里的会话链接都要配置 http.external_url。

​

开启

打开 Mole Agent → 设置 → IM 接入，这里列出所有能在 IM 里回答的连接器： 在 IM 里回答的连接器要先在这里关掉，才能在通知设置里删除。

​

绑定账号

Mole Agent 按 IM 账号所属的 MoleSignal 用户回答，用这个用户的权限。它靠同一个连接器上启用、已验证的通知方式认出账号： 一个账号属于不止一个用户时，Mole Agent 不回答。

• 自己绑定：还没绑定的人提问时，Mole Agent 私下给他发一个一次性链接：私聊里直接发，Slack 里发一条只有他看得到的消息。他登录 MoleSignal 后打开链接，选择绑定，这个账号就成了他的一种通知方式，并且已经验证。链接只能用一次，15 分钟内有效。企业微信和 Google Chat 只能私下发给私聊过机器人的人，Teams 只能发给装了这个 Bot 的人；发不出去时，Mole Agent 在原处请对方先私聊，再在私聊里给链接。
• 管理员绑定：在设置 → 通知 → 用户路由里给成员绑定这个账号并验证。参见通知渠道。

​

提问

在群里 @ 机器人；私聊时直接写。私聊在 /new 之前一直是同一个会话。 其他命令，例如 /rca INC-12 或某个技能，和在 MoleSignal 里一样用。

​

话题是谁的会话

个人会话只有开始它的人能接着问；团队会话是这个团队的成员都能接着问。群里新开的话题，提问人在连接器设置的团队里时记成这个团队的会话，否则是他的个人会话。/scope 会把话题换到一个新会话，之前的消息留在原来的会话里。

​

回答的时候

• 在 IM 里没有人能回答 Mole Agent 的问题或确认改动。它会做合理的假设并说明，跳过需要有人确认的步骤，回复里会说明跳过了。要继续这些步骤，从链接打开 MoleSignal 里的会话。
• 一次回答最多 15 分钟。企业微信的“正在查”是一条流式消息，10 分钟内要结束：超过 9 分钟才好的回答另发一条。
• 回复是带各部分的回答，例如可能原因、证据和下一步，用提问人的界面语言。
• 在群里，群里所有人都能看到回复，但它是按提问人的权限查出来的。不想让别人看到的，请私聊提问。
• 组织今天的预算用完时，Mole Agent 会说明，不再回答。

​

告警卡片

这一节说的是告警通知，不是和 Mole Agent 的对话：经飞书 App 或 Slack App 连接器发出的告警通知，在这个连接器开了 IM 接入以后，是一张带按钮的卡片，在卡片上就能确认、解决告警，不用打开 MoleSignal。钉钉、企业微信、Google Chat 和 Teams 发出的告警通知仍是文字。

• 卡片带哪些按钮，看告警发出时的状态：等待确认的有确认和解决，已确认的只有解决，恢复的通知不带按钮。
• 点按钮按 IM 账号绑定的 MoleSignal 用户执行，这个用户要有 alerts.acknowledge。还没绑定的账号会私下收到一次性绑定链接，和提问时一样，见绑定账号。账号对上不止一个用户时不执行。
• 点完以后，卡片换成告警现在的样子：内容按发出它的通知策略的模板重写，写明谁确认或解决了告警，只留下还能点的按钮。群里所有人看到的是同一张卡片。
• 飞书给点按钮的人弹出提示，说明做成了没有；Slack 里没做成时，发一条只有点按钮的人看得到的消息说明原因。
• 按钮上的字用收通知的人的界面语言；发到群里的卡片用组织的默认语言。

​

限制

• Mole Agent 读文字消息和富文本消息里的文字，企业微信还读语音转成的文字。图片和文件会被忽略。
• 连着连接器的服务器停了，另一台服务器大约一分钟内接手。这一分钟里的提问，只有平台重新投递时才会在连上后得到回答。Teams 不受影响：哪台服务器收到回调都能处理。
• 企业微信的回复只能从连着机器人的那台服务器发出。别的服务器上结束的回答交给它发，通常几秒内送到。
• 企业微信限制每个会话每分钟 30 条、每小时 1000 条消息。
• 在 MoleSignal 里或另一张卡片上确认、解决告警以后，已经发出的告警卡片不会跟着变。再点其中的按钮，会说明告警已经确认或解决，并把卡片换成现在的样子。