Mattermost 机器人

Mattermost 机器人用于把艾维斯能力接入自托管 Mattermost 协作环境。上线前应把它当作受控消息入口来配置：只接收已批准团队、频道或命令触发的请求，只返回当前用户或频道允许访问的知识和工具结果，并保留可审计的请求记录。

适用场景

场景	建议
公开频道问答	使用 Outgoing Webhook，把触发词限制在一个或几个已批准公开频道。
私有频道或私聊问答	使用自定义 Slash Command。Mattermost 官方文档说明 Slash Command 可用于公开频道、私有频道和 Direct Message。
固定机器人身份发帖	创建 Bot Account，并使用机器人访问令牌调用 Mattermost REST API。
生产 ChatOps	使用独立 Mattermost 机器人账号、独立 webhook 或 command，并绑定独立艾维斯工作区和访问范围。
敏感知识问答	先验证 Mattermost 来源频道、用户和艾维斯访问群组，不把机器人配置成绕过权限的共享代理。

接入方式选择

Mattermost 能力	适合用途	注意事项
Outgoing Webhook	监听公开频道消息或触发词，并把消息 POST 到艾维斯回调地址。	官方文档说明 Outgoing Webhook 支持公开频道；如果留空频道或触发词，触发范围会变宽。
Custom Slash Command	用户输入 `/aivis 问题` 后把请求发送到艾维斯。	可用于私有频道和私聊，并支持命令自动补全。
Bot Account + Personal Access Token	艾维斯需要主动调用 Mattermost REST API 发帖、回帖或访问频道信息时使用。	使用非管理员 bot 账号，不复用 System Admin 或个人账号 token。

通常建议先使用 Custom Slash Command 做最小闭环：触发范围清晰、用户意图明确，也更适合私有频道和 Direct Message。只有需要监听公开频道自然语言消息时，再使用 Outgoing Webhook。

管理边界

项目	建议
入口	只绑定已批准的 Mattermost 站点、团队、频道、Slash Command 或 Outgoing Webhook。
身份	使用专用 Bot Account 或专用集成账号，不复用管理员个人令牌。
响应	根据 Mattermost 来源、艾维斯用户/群组、Agent、知识库和工具权限控制可返回内容。
回调	回调 URL 应使用 HTTPS；如果部署在内网，按 Mattermost 官方要求配置可信内部连接。
运维	记录 Mattermost Site URL、team/channel、command/webhook token、bot token、网络策略、负责人和轮换时间。

配置前检查

已确认 Mattermost Server 版本和部署方式，且当前账号有权限进入 Product menu > Integrations 或系统管理员可代为配置。
已确认服务器已启用所需集成能力：Outgoing Webhooks、Custom Slash Commands、Personal Access Tokens 或 Bot Accounts。
已准备可供 Mattermost 访问的艾维斯 HTTPS 回调 URL。
已明确机器人允许服务的团队、频道、用户范围、默认 Agent、知识范围和工具范围。
已决定使用 Outgoing Webhook、Custom Slash Command，还是额外使用 Bot Account / Personal Access Token。
所有 token 只保存到受保护配置中，不写入公开文档、Agent 指令、工单、截图或聊天记录。

配置数据获取入口

配置数据	获取方式
Mattermost Site URL	使用 Mattermost 站点根地址，例如 `https://mattermost.example.com`。艾维斯后端需要能访问该地址，用户浏览器也应能打开来源链接。
Outgoing Webhook Token	在 Mattermost 打开 Product menu > Integrations > Outgoing Webhooks，创建 webhook 后复制 Token。可参考 Mattermost Developers：Outgoing webhooks。
Slash Command Token	在 Product menu > Integrations > Slash Commands 创建自定义命令后复制生成的 token。可参考 Mattermost Developers：Custom slash commands。
Bot Account Token	在 System Console > Integrations > Bot Accounts 启用 bot 账号创建，再从 Integrations > Bot Accounts 创建专用机器人并复制生成 token。可参考 Mattermost Developers：Bot accounts。
Personal Access Token	若使用普通集成账号，先在系统控制台启用 Personal Access Tokens，再在该账号 Profile > Security > Personal Access Tokens 创建。可参考 Mattermost Developers：Personal access tokens。
Team / Channel ID	从 Mattermost 频道链接、API 返回值或系统管理信息中确认；上线前记录 team、channel、channel display name 和 owner，避免只凭频道显示名配置。
集成开关	在 System Console > Integrations > Integration Management 检查 Outgoing Webhooks、Custom Slash Commands 和 Personal Access Tokens；Bot Accounts 在 System Console > Integrations > Bot Accounts 中检查。可参考 Mattermost 管理文档：Integrations configuration settings。

配置 Outgoing Webhook

如果希望机器人监听公开频道中的触发词，可在 Mattermost 创建 Outgoing Webhook：

打开 Product menu > Integrations > Outgoing Webhooks。
点击 Add Outgoing Webhook，填写名称和描述。
选择请求内容类型。建议使用 application/json，便于艾维斯按结构化请求解析。
选择一个明确的公开频道，或设置一个清晰的触发词，例如 aivis。
在 Callback URLs 中填写艾维斯提供的回调 URL 并保存。
复制 Mattermost 生成的 Token，回到艾维斯机器人配置页填写。

Outgoing Webhook 的频道或触发词不要留得过宽。官方文档说明，如果频道为空，触发词会在团队的全部公开频道生效；如果触发词为空，则会响应所选公开频道的全部消息。

配置 Slash Command

如果希望用户明确通过 /aivis 调用机器人，或需要支持私有频道和私聊，建议创建自定义 Slash Command：

打开 Product menu > Integrations > Slash Commands。
点击 Add Slash Command。
设置命令标题、描述和唯一触发词，例如 aivis。触发词不要包含 / 或空格。
将 Request URL 设置为艾维斯回调 URL。
将请求方法设置为 POST。
按需开启 autocomplete，并填写参数提示，例如 [问题]。
保存后复制生成的 token，回到艾维斯机器人配置页填写。

配置 Bot Account

只有在艾维斯需要主动调用 Mattermost REST API 发帖、回帖、发私信或查询频道信息时，才需要 Bot Account 或 Personal Access Token。

在系统控制台确认已启用 Bot Accounts 和必要的 Personal Access Tokens。
创建专用 Bot Account，例如 aivis-bot，不要授予 System Admin，除非经过单独安全评审。
把 bot 加入允许服务的 team 和 channel。
复制生成的 bot access token，并填入艾维斯受保护凭据。
在测试频道发送一条由 bot 发出的最小回复，确认身份、频道和权限符合预期。

在艾维斯中配置

在艾维斯管理后台打开 Mattermost 机器人配置页，按所选接入方式填写：

艾维斯字段	Mattermost 来源	说明
Mattermost 站点地址	Mattermost Site URL	用于生成来源链接或调用 Mattermost API。
回调 URL	艾维斯生成	复制到 Outgoing Webhook 的 Callback URLs 或 Slash Command 的 Request URL。
Webhook / Command Token	Mattermost Outgoing Webhook 或 Slash Command 生成	用于校验请求确实来自 Mattermost。
Bot Access Token	Bot Account 或 Personal Access Token	仅在需要主动调用 Mattermost REST API 时填写。
允许的 Team / Channel	Mattermost team、channel 或内部审批记录	限定机器人可以响应的来源。
默认 Agent / 知识范围	艾维斯配置	决定机器人默认调用哪些知识和工具。

保存后，确认机器人开关为已启用，并记录回调 URL、Mattermost 集成名称、token owner 和负责人。

验证

在测试频道或私聊中发送一条普通问题，确认机器人能回复。
如果使用 Outgoing Webhook，测试触发词和非触发词，确认只有预期消息会触发。
如果使用 Slash Command，测试 /aivis 问题、空参数和异常参数。
使用未授权频道、未授权用户或未绑定 Agent 的问题测试拒绝路径。
在艾维斯追踪中确认 Mattermost 来源、team、channel、user、触发方式、响应结果和错误信息可审计。
轮换 webhook token、command token 或 bot token 后，重新保存艾维斯配置并重复测试。

常见问题排查

现象	优先检查项
Mattermost 中没有 Integrations 菜单	系统管理员是否启用了对应集成能力，或当前用户是否被允许创建集成。
Outgoing Webhook 没有触发	频道是否为公开频道，触发词是否匹配，频道或触发词是否被配置得过窄。
Slash Command 无响应	Request URL 是否为艾维斯回调 URL，请求方法是否为 `POST`，Mattermost 服务端是否能访问该地址。
艾维斯收到请求但校验失败	Webhook / Command Token 是否填错，是否复制了 token ID 而不是真实 token，是否包含多余空格。
Bot 无法发帖	Bot 是否已加入目标 team/channel，token 是否有效，是否具备向目标频道发帖的权限。
私有频道或 DM 不可用	不要用 Outgoing Webhook；改用 Slash Command 或 Bot Account + REST API。
搜索结果包含不该看到的内容	调整艾维斯访问群组、默认 Agent、知识范围或 Mattermost 来源白名单。

安全与维护建议

为生产、测试和演示环境使用不同 Mattermost 集成和 token。
不使用 System Admin 个人 token 作为机器人凭据。
Outgoing Webhook、Slash Command 和 Bot Account token 都应定期轮换，并记录 token owner。
关闭长期不用的 webhook、command 或 bot account 后，再停用艾维斯侧机器人。
频道、团队、owner 或访问范围变更后，重新验证拒绝路径和追踪记录。