# QQ 渠道（SnowLuma / OneBot v11）

伙伴作为客户端连接 SnowLuma 的 **正向 Universal WebSocket**。同一条连接接收消息并调用 OneBot API，无需额外填写 HTTP API，也无需反向连接或开放 DSH 回调端口。

1. 在 SnowLuma 登录 QQ，启用正向 WebSocket（角色 `Universal`）。
2. 打开「伙伴 → 渠道 → QQ → 配置」。
3. 填写地址（同一 Docker 网络例如 `ws://snowluma:3001`）和该 **WS 服务**的 Access Token。HTTP 与 WS 的 Token 可能不同。跨公网连接应使用 `wss://`。
4. 测试连接、保存并启用。令牌仅存入 DSH 凭据库。
5. 群聊：开启群聊回复并选择接入群；加入自主回复白名单的群放行所有成员，其他已接入群需要审批发言账号。私聊：需要时单独开启，再核对好友的配对码并批准；只使用群聊时关闭私聊回复。

默认自动发现好友私聊；高级设置可限制为一个联系人 QQ 号。群聊默认关闭，可在分层设置中开启；群临时私聊、非好友私聊、匿名群消息和自身消息不触发伙伴。安装腾讯官方 `dsh-qqbot` 插件不是此渠道的前置条件，两者各自配置、独立连接。

渠道直接复用伙伴的身份、人格卡、记忆、工具、提问和通知路由；角色分段文字和表情包按原顺序发送。QQ 无法原地编辑普通消息，所以不伪造进度卡或额外发送“正在思考”。

支持普通文本、QQ 系统表情的文字说明、图片/表情图片发送、文件发送，以及带受支持 QQ 媒体下载地址的入站附件。附件接收限制沿用每批最多 8 个、总计 64 MB；缺少可用下载地址、超限或无法下载时会提示失败，不会悄悄忽略附件后执行文字。模型输出的 CQ 字符串按普通文字发送。

连接中断后自动退避重连，API 请求按 echo 匹配回执，发送接口不会在连接层自动重放。OneBot WS 是实时事件流，不能保证补回断线期间的消息；如发生掉线，请重发尚未收到回复的消息。处理失败后沿用伙伴的暂停/投递恢复机制，已开始执行的消息不会再次执行工具。

官方参考：https://snowluma.github.io/zh/docs/guide/connect-bot

## 分层配置

首页只显示账号状态和分类入口，详细设置在下一层，返回保留未保存的草稿，关闭时提示保存状态。

- **连接与账号**：测试/更新 WS 地址及令牌、启停、重连；移除渠道放在折叠项中。留空令牌保留原凭据，更新时核对同一 QQ 账号。
- **私聊回复**：默认开启，只有批准后的好友才能触发伙伴。
- **群聊回复 → 选择群组**：默认关闭，从已加入的群选择（最多 100 个）；默认仅真正 @ 机器人时回复，可改为回复群内每条消息。可控制回复时是否 @ 发言人。
- **表情与图片**：分别控制原生 QQ 系统表情和图片/人格表情包发送。
- **访问权限**：填写多个归属账号；私聊核对配对码后批准。白名单群成员无需逐人批准，其他已接入群需要审批发言账号；已有记录可单独屏蔽。
- **发送消息**：从已授权的接收人选择好友或群成员，发送文字或原生 QQ 表情。表情目录支持分类、搜索、预览和加载更多；点击最终发送按钮才会发送。群成员接收项表示发送到对应群，不是私聊该成员。

默认每个群、每位私聊联系人使用独立会话，以群名或联系人名命名。「会话与记忆」中可选择哪些私聊用户、群聊使用本地主会话；未选择的对象继续独立。保存后对后续消息生效，取消勾选可接回原独立会话。启用记忆时，各会话共享该伙伴已整理的长期记忆，升级合并旧群记忆，不拼接原始聊天、不删除旧会话文件。群消息标注群号和发言人；群内任务的通知仍固定返回来源群。私聊的“最近联系人”自动路由不会选择群成员。身份、人格和已有工具权限仍沿用该伙伴的配置，共用工作目录；如需独立资料和身份，可使用单独伙伴。

群回复开启并选中群后，白名单群成员无需逐人配对；非白名单群需要审批发言账号。私聊与各群的账号审批分别记录，不互相继承。若连接创建时限制了固定私聊联系人，则仍只监听该联系人；要启用群聊需使用未限制联系人的连接。

原生表情目录来自 SnowLuma `fetch_sys_faces`，发送使用 `face` 消息段；经典预览使用目录的 `em_code` 对应 QQ 图片 CDN，无法加载的表情显示名称和编号。模型文本中的 CQ 字符串仍按文字发送，不强制每轮发表情。

## 自主回复白名单

「群聊回复 → 自主回复白名单」从已选群组中勾选。白名单群无需 @，普通消息进入有界的话题观察窗口；所有未屏蔽成员的发言均进入本地对话归属判断，连续聊天优先接续；可选本地语义分类辅助判断新话题，不另发远程大模型判断请求。真正回复使用所配置的独立或主会话，以及伙伴的角色和记忆；归属账号附加关系设定与既有授权工具，其他成员只提供当前会话回复工具。无需先 @ 或配对，群内聊天许可不授予私有能力。

每个群最多保留最近 16 条背景，每条最多 1200 字；判断至少间隔 15 秒，自主回复后至少间隔 45 秒，伙伴正在处理任务时不插入自主消息。明确 @ 不受自主判断影响。没有每日回复次数上限。

## 渠道表情适配器

`StickerAdapters` 默认委托伙伴的 `StickerLibrary`，渠道通过 `register(platform, factory)` 提供 `list` 和 `resolve`，工具按实际消息来源选择适配器，本地聊天或未知来源始终使用默认库。

QQ 的「表情与图片 → 聊天表情来源」默认选择 QQ 收藏与系统表情，也可明确切换默认库。QQ 目录优先提供 `fetch_custom_face_detail` 的收藏和 `fetch_sys_faces` 的系统表情；模型通过 `partner_stickers` 查找、查看并用 `partner_chat_reply` 发送。QQ 模式只返回和接受 QQ 收藏及系统表情 ID，不混入内置库；默认库模式按原 ID 使用图片，不做关键词替换。目录缓存最多五分钟，更新渠道配置会失效。

系统表情走 `face` 消息段，收藏表情走 `send_custom_face`，两者保留发送顺序、来源账号和渠道绑定。查询没有匹配时可去掉 query 浏览收藏，仍没有合适结果就只发文字，不回退默认库；发送结果未知时不再补发默认图片，避免重复消息。QQ 当前无收藏时仍可使用系统表情。原生表情的页面展示使用宿主正常正文元素。

## 私有能力

在「QQ 设置 → 私有能力」启用总开关，再按分类选择单项能力，保存后生效。仅归属账号及系统自主执行可在已有授权范围内调用。关闭总开关不会影响已开启的文字、表情与当前会话语音回复；后者在「聊天回复 → 语音回复」独立设置。伙伴通过 `partner_qq` 先查目录，再查参数，最后调用；无需向每次对话注入全部 API 参数。

- **QQ 空间**：可浏览动态、发表说说、点赞、评论和管理自己的说说；默认发表范围为好友可见，可调整。空间访问范围由当前 QQ 账号决定。
- **语音**：本地音频文件发送到已授权私聊或已选群；QQ AI 音色生成及发送用于群。点击「读取 QQ 音色」选择默认音色，也可让伙伴选择。
- **其他分类**：聊天互动、记录、账号与好友资料、群资料、公告待办、群管理、文件及群相册。管理与删除操作独立开启，且受 QQ 实际权限约束。

未实现和凭据类接口不对伙伴开放。文件上传只读取伙伴工作目录内的非隐藏普通文件，不支持任意 URL 或远程容器路径。结果未知的对外操作不会自动重发；可在「最近操作记录」确认状态，再核对 QQ 实际结果。

自主接话判断与后台记忆整理独立；面板的「当前任务」显示记忆、归档、初始化或运行中的会话，最近判断显示接续、语义判断、降级放行或旁听原因。连续消息逐条进入本地判断，不会因接话冷却或伙伴忙碌直接跳过；判断可自主选择不回复。群白名单的所有未屏蔽成员都可进入接话判断；其他已接入群按发言账号审批，私聊由独立开关和配对控制。

AI 仅注册一个 `partner_qq` 入口。`list` 默认返回已开启的分类与数量，带 `category` / `query` 时最多返回 20 项操作概要（`offset` 翻页），`describe` 才返回单项参数。完整 89 项 API schema 不进入每轮工具定义。

## 归属账号

在 QQ 配置的“访问权限”中填写一个或多个归属 QQ 号，保存即可；留空关闭。只填写账号，不另写哥哥、弟弟等关系，不区分私聊或群聊。角色设定描述角色本身；具体关系、称呼和相处方式沿用身份中的独立「关系设定」，修改身份后同步使用新设定。

识别依据是渠道真实发言账号，昵称、自称和引用不改变归属。其他人按人物性格与各自交往相处。绑定决定是否附加关系以及能否使用既有授权的私有工具，不绕过私聊开关、群白名单或主会话选择。本地对话保持原设定。

## 工具入口与耗时诊断

启用“统一伙伴工具入口”后，partner_tools 按分类查询、describe 查看参数、call 调用真实能力；partner_channel_access 默认只返回实时权限与分类摘要，指定 category、query 或 offset 后每页最多返回 12 项。基础回忆、聊天回复、前置回应，以及已授权的独立工作入口直接提供，避免为了接话或开始调查先遍历目录；其他能力仍通过统一入口调用。QQ 普通成员可使用公开聊天、表情、语音和本会话回忆，工作入口仅向具备对应权限的来源提供。不接受自报 QQ 号，调用时再次检查当前权限；工具注册保持稳定，实际暴露范围可随核验来源变化，既有审批、取消和记忆边界不变。

群消息逐条通过会话归属与本地语义判断，不再使用独立远程模型门控。`channels/status` 的 `qqLatency` 保留最近 20 条消息的处理耗时；`beforeHandleMs` 包括前置队列与身份核验，`decisionMs` 是本地接话判断，`decisionMethod` 为 `local`、`decisionScore` 为规则结果或语义分类分值（不是接话抽签概率），`agent` 区分伙伴队列、输入准备、模型与空闲等待、回合结束后的等待、状态提交和出站准备。`sendMs` 包括投递记账、渠道校验、发送确认与完成记账，不能直接视为网络延迟。追加到运行中回合的消息标记 `steered`，不额外发送技术提示。

### 会话归属与本地语义（2.21.3）

已替换 2.21.2 的逐条评分抽签：明确呼唤、引用伙伴消息与正在进行的对话优先接续；按群和发言人保留五分钟成功回复窗口，换人插话不会清空。新话题由可选本地语义分类器辅助判断；低置信度或故障时交给正式回复模型，后者可以选择旁听而不发送消息。详情、资源占用与测试限制见 [QQ 接话设计](qq-attention.md)。

### 自主收藏与整理（2.23.0）

在 QQ「表情与图片」中开启收藏管理的具体操作后，伙伴可用 `partner_qq` 的 `stickers` 分类查询、收藏、备注、排序与删除表情。收到的图片使用伙伴工作目录中已落盘的附件路径；只接收 PNG/JPEG/GIF/WebP，最大 2 MB。收藏前读取至多 200 项检查相同 MD5，收藏成功后建议用简短名称和情绪词备注，再通过 `partner_stickers` 检索并以 `partner_chat_reply` 发送。超过查询范围的旧收藏不能保证去重。

整理可作为自主活动，无需每次发消息汇报；删除用于明确重复或不再需要的项，不批量清空。普通非归属 QQ 账号也可使用当前渠道已开启的收藏管理能力。表情能力与自主活动设置继续由用户控制。

### 公开聊天中的收藏与语音（2.23.4）

「表情与图片」下的查看、收藏、备注、置顶和删除开关面向当前渠道已获聊天许可的普通联系人及群成员；关闭私有能力总开关不影响这些已开启的操作。收藏管理由 AI 按人格和实际需要自行决定；空间、账号管理仍属于私有能力。普通账号的 `partner_qq` 查询仅显示当前渠道公开操作，执行时再次验证来源、联系人许可与单项开关，不能指定其他渠道。

当前会话文字转语音仍通过 `partner_qq_reply` 使用独立的语音开关，不依赖归属账号和私有能力；仅发送到当前会话。角色可以按场景自行选择，不要求用户先点名索要。

### 公开聊天互动（2.23.18）

在「聊天回复 → 聊天互动」配置消息表情回应、回应查询、群基本信息、群成员信息与列表。各项开关保持用户原设置，不受私有能力总开关控制。普通联系人只能回应当前私聊消息；群成员只能查询当前群、回应当前群消息，不能跨到另一个已接入群。账号资料修改、空间、群管理等保持私有授权。轻量表情回应不要求额外前置文字；表情收藏与语音沿用既有入口。