# Matrix 与 Mattermost 渠道

渠道配置支持账号密码与 Access Token 两种认证方式。账号密码仅发送到指定服务器换取令牌，持久化凭据只包含令牌，不向伙伴模型提供密码。建议使用 HTTPS；HTTP 会明文传输凭据。

测试登录成功后，服务端在内存中暂存令牌 5 分钟；相同账号配置的重复测试和保存复用这次登录。未保存的临时会话到期尝试退出；保存的令牌不会退出。服务器返回 429 时读取等待时长，并在等待期间拒绝重复认证，不再误报密码错误。

同一伙伴的本地与所有渠道共用一条主对话，不要求关联联系人。已有本地主对话优先；没有本地会话时可继续最新可用的渠道对话。旧的多份对话记录不会被拼接或删除。各渠道仍保留投递路由与配对授权，回复回消息来源；所有获准联系人会共享这条主对话的上下文，适用于用户明确要求的共享模式。不同伙伴仍隔离。

渠道状态和配对列表使用共享轻量轮询，页面可见时约 3 秒刷新一次，后台页暂停；不重复加载记忆和对话正文。新请求在已打开的配置弹窗中直接出现，不强行弹出另一层窗口。

房间 / DM ID 现在可选，默认留空自动发现私聊。保存后启用渠道，再向机器人发送消息。Matrix 可邀请机器人加入明确标记为私聊的未加密双人房间；邀请状态不足以确认安全时不会自动加入，请先手动加入。机器人返回配对码，在「渠道 → 配置」核对同一代码及联系人身份后批准。配对码用于核对请求，不是登录密码，也不会自动授予权限。批准后请重新发送消息，首次配对消息不会执行。

高级配置可固定一个会话 ID，兼容原有配置。自动模式下每位联系人绑定收到配对消息的房间，其他房间不会继承该授权。群聊和加密房间均不会交给伙伴处理。

- Matrix：填写 homeserver URL、账号密码和已加入的双人房间 ID。当前仅支持未加密房间；加密房间、群组会拒绝连接。仅支持 SSO 的账号请使用 Token。
- Mattermost：填写服务器 URL、账号密码和双人 DM ID。开启 MFA 时填写当前验证码，也可使用 Token。当前以约 10 秒间隔轮询消息。
- 未保存的测试会话到期尝试退出，不会撤销用户自行填写的 Token。服务器不可达时，退出可能失败，需要在服务器会话管理中手动撤销。
- 保存后渠道默认关闭；审核联系人授权，再启用渠道。首次连接跳过已有历史消息。

回复始终回到消息来源会话。主动通知可指定同一伙伴下的已授权投递目标；未指定时选择最近发来消息的渠道，不要求联系人关联标识。目标被停用或撤销授权时不会静默换渠道投递。

Matrix / Mattermost 跟随 DSH 的 `ui-conversation.busyEnter` 配置：`steer` 在伙伴忙碌时插入补充，未在执行时正常开启一轮；`queue` 等前面的执行和回复完成后按顺序处理。插话成功发送简短确认，不创建第二个进度消息。配置在接收新消息时读取，已经排队的消息不回溯改序。

收消息与模型回复分离，执行期间持续轮询；Mattermost 有待处理任务时缩短轮询间隔。附件先按原规则合并和下载，再交给插话/排队接口。后台待处理最多 100 组，超过上限暂停并提示重连；排队未执行的消息不提前记执行回执，存在待处理任务时不推进持久同步游标。交互提问的答案优先处理，不被模型执行队列阻塞。

支持文字、图片、文件、音频和视频的私聊收发。图片通过现有附件接口交给模型；其他附件保存到当前会话的 `inbound/` 目录，并向伙伴提供真实路径与 MIME 类型。音频/视频可作为文件交付，不代表自动转写或视频理解；需要伙伴另行使用可用工具处理。

单条入站消息最多 8 个附件，合计不超过 64 MB；单个出站附件不超过 64 MB。服务器自身可能有更小的上传限制。Mattermost 带附件消息保留附带文字；Matrix 支持 `m.image`、`m.file`、`m.audio`、`m.video`，保留与文件名不同的标准 caption。

部分客户端会把一次发送的文字与附件拆成多个事件。连接器收到消息后额外收集约 1 秒，并合并同一联系人、同一房间中时间跨度不超过 2 秒且包含附件的相邻事件；纯文字消息不会合并。整组附件下载完成后再一次性交给伙伴，文件路径显示在用户文字前，下载失败不会只执行文字。合并后仍执行 8 个附件/合计 64 MB 的限制，并记录所有原始事件回执，避免重连重复执行。

这不是客户端上传完成信号：缺少关联元数据时，超过收集窗口才到达的附件不能保证与先前文字合并；时间跨度过大、不同房间/联系人或缺少时间戳的消息保持独立，避免把不同请求错误拼接。收集阶段不提前提交同步游标，重启会从未提交位置重新读取。

附件只在配对批准后下载。Matrix 使用 homeserver 的认证媒体下载接口（`/_matrix/client/v1/media/download/…`，需要支持该接口的服务端），不直接访问消息中的 HTTP URL；Mattermost 校验文件属于当前消息。下载和上传不跟随重定向，传输中限制实际字节数，上传完成后再次检查身份才发送附件消息。图片类型通过文件头识别；其他内容作为文件，不自动执行。

显式附件工具按当前用户消息来源选择渠道，本地发起只显示在 DSH；多个渠道共用会话不会采用列表中的第一个渠道。新交付记录保存原始路由，重试必须回到同一渠道。旧版未记录目标的交付不猜测目标，请用原文件 path 重新提交。

交互提问按实际消息来源返回。仍不支持群聊、Matrix E2EE/加密附件或 Mattermost 线程。入站附件失败会告知发送人且不执行该条请求，需重新发送；其他消息可继续处理。回复发送失败时保留原有停止连接行为，避免自动重放消息重复执行工具；此行为不等于可靠消息队列或恰好一次投递保证。显式 `partner_send_attachment` 交付沿用已有 `deliveryId` 重试机制。

当前已有模拟服务器回归测试和部署页面验收；真实账号完整收发仍需联调。升级前备份状态与凭据；加入新渠道后不要直接降级到仅识别微信的旧版。
# Matrix 消息缺口恢复

增量同步返回 `timeline.limited` 时，不清空或跳过旧游标，而是使用房间
`/messages?dir=f&from=<旧同步游标>&to=<本次同步游标>` 分页补拉。
同一批按事件 ID 去重，空页但分页游标继续推进时仍继续读取。
补拉后再次核验双人会话及成员身份；加密房间仍不支持，不因补拉绕过授权。
首次连接只建立水位，不自动执行此前的历史对话。

补拉失败、分页游标循环或响应无效时，不返回成功批次，不推进持久游标。
单房间补拉最多100页、10000个事件、16MiB；超过限制保留原游标并明确报错。
Matrix 积压超过100组输入时等待执行队列空位，不再直接因队列已满停掉渠道。
网络超时、连接失败、HTTP 408/429/5xx 持续退避重连；认证失败和投递异常仍保留原有停机保护。
这些恢复策略只应用于 Matrix，不修改 Mattermost 的服务器地址、DNS 或凭据。