QQ 接入总览¶

QQ 接入需要一个独立安装并登录的协议端，以及月璃随附的对应适配器。 协议端提供正向 WebSocket 服务，适配器主动建立连接并向主体转交消息。 安装月璃不会自动安装或登录协议端。

适配器选择¶

已有可用协议端时，选择对应插件即可；两者不能同时启用。 文本、引用、贴表情、合并转发、群历史和成员信息均有能力声明。 NapCat 的戳一戳还依赖连接后的能力探测；SnowLuma 插件把戳一戳列为静态能力。 能力声明不等于账号、协议端版本与实际投递都已验证。 戳一戳动作不可用时，应检查功能开关与协议端能力；普通消息收发须单独验证。

config/adapter.toml 的 plugin 写插件目录名。 连接信息位于该插件目录下的 config.toml，段名必须与上表一致。 具体文件关系与只读自检见适配器配置。 两个协议端都必须上报数组消息段；各自设置字段见对应接入篇。

QQ 账号的职责¶

self_qq 是协议端当前登录的机器人号，owner.qq 是用户本人的号。 两个号必须是不同的数字 QQ 号；模板中的占位值不能原样启用。 适配器连接后会核对实际登录号；连错账号会报告身份不匹配。 本人在私聊名单里自动放行，不用重复加入 [private].list。

私聊与群聊名单¶

私聊可以使用白名单或黑名单，默认白名单。 只允许指定朋友时，将对方数字 QQ 号填到 [private].list。 群聊只支持白名单，填的是数字群号：

[group]
mode = "whitelist"
list = [123456789]

该片段对应插件连接文件中的已有段，示例群号须替换为实际测试群号。 空列表表示不接入任何群。 即使本人在名单外群里发言，也不能豁免群白名单。 名单外群的消息在适配器侧被挡下，不交给主体创建人物、保存会话或请求回复模型。 白名单群消息进入对应群的会话历史，但接收上下文不代表逐条回复。

点名与自然接话¶

QQ 协议 @ 与正文名称提及属于不同信号。 名字或别名来自 bot.toml 的 [bot]，支持不区分大小写的包含匹配。 包含 @ 字符的普通文本不一定构成协议提及。

[bot]
name = "月璃"
aliases = ["小璃"]

[group_chat]
at_mention_must_reply = true
name_mention_probability = 1.0
presence_decay_strength = 3.0
persona_weight = 0.05
reply_window_minutes = 10
max_replies_in_window = 3

该片段用于修改已有字段，应保留模板中的其他群聊选项。 必回 @ 优先于睡眠和回复次数窗口；它仍以消息已进入允许群为前提。 名字、别名、非必回 @ 等直接信号可越过次数上限，但不越过睡眠，也不保证最终发言。 当前还有自然接话窗口和话题延续候选，不能把「未点名」一概写成永不回复。 这类无人点名的参与仍受次数窗口限制。

基础概率还会结合当前发言占比衰减，因此设为 1 不代表每个候选都必回。 persona_weight 只折算群聊人格变化，不决定回复机会。 减少主动参与时，应调整窗口、发言占比策略和行动模式，无需清除会话上下文。 当前次数上限应保持正数；模板的「0 表示不限」与运行时不一致，0 会触发运行错误。

行动模式与动作开关¶

bot.toml 的 [conversation_agent] 初始配置为开启（mode = "enabled"）。 启用后可由信号、发言频率或必要性评分产生候选，再决定回复、等待或沉默。 只对指定会话启用时，其他会话保持原有触发方式。 模式与调用成本见 bot.toml 配置。

reactions_enabled 允许贴表情，pokes_enabled 允许主动戳人；初始配置里前者关闭、后者开启。 self_started_topics 允许行动核心在合适候选里自发起话题，不新增发言额度。 接收戳一戳事件与允许机器人主动戳人属于不同控制项。

屏幕情境与群聊¶

features.toml 的视觉开关控制采集，感知出口控制情境可以进入哪个会话。 默认只允许 desktop；direct 也只对本人开放，不扩大到私聊白名单全部联系人。 group 不属于合法感知出口，配置时会被拒绝。 私聊事实能否进入群聊另由 private_facts_in_group 决定，默认关闭。 完整关系见功能配置。

接入验收应依次核对协议端登录、适配器握手、本人私聊收发及白名单群协议 @ 收发。 每层成功只证明该层；遇到问题保留具体错误和发生时间。 实现边界见开发手册：平台与适配器。