K0nd1us / QQ-agent

# QQ Agent（桌面端）
一个跑在你自己电脑上的 QQ 群聊机器人：装完双击启动，扫码登录，填个模型 Key 就能用。
事件驱动 + 无状态会话架构，每次处理的 token 成本恒定可控；所有操作都在图形控制台里完成，不用碰命令行。
从 Derpyu520/qq-bridge 彻底改造而来的独立 QQ agent 应用。
## 能实现什么
- **像真人一样混群**：被 @ 或被叫到时回话，平时看心情插嘴；会发文字、表情包、戳一戳，会引用、会 @ 人，知道什么时候该闭嘴
- **记住每个群友**：双向长期记忆——它记得谁是什么风格、爱什么梗、雷点是什么，下次聊天自然带上；记忆页随时可查看、手动编辑
- **看得懂图、上得了网**：视觉模型直接看消息里的图片；内置 6 家搜索服务（含免 Key 的 Bing 网页解析），还能自己加任意兼容搜索服务
- **花多少看多少**：每次调用的 token 和成本精确记录，按天 / 按会话 / 按模型三个维度统计，缓存命中率、峰谷分时计价、图片计费口径全标清楚
- **零编程门槛**：所有配置都在控制台点选——白名单从 QQ 里直接勾选群，模型从模型目录里点选切换，不用查群号、不用写配置
## 技术架构
**事件驱动 + 无状态会话（成本控制的核心）**
1. 群聊消息持续写入本地 JSON 存档（每条带时间与已读状态）
2. 每次有新消息（或主动机会），**新开一个独立会话**：提示词 = 静态系统提示（人设/规则/策略）+ 存档摘要 + 本次新消息
3. 会话结束即弃置，LLM 层面零历史——一次处理的成本是恒定小份，不随聊天量膨胀
4. 处理期间新来的消息只写存档；本次结束后发现未读 → 自动再开新会话，直到清空
5. 长期信息走记忆工具持久化，跨运行生效
**整体组成**
- **协议端**：通过 OneBot v11 正向 WebSocket 接 QQ（默认配 SnowLuma，任何兼容协议端均可换）
- **大脑**：任意 OpenAI 兼容 API——官方 / 中转站 / 本地网关均可，模型在设置里自选
- **桌面壳**：Electron，托盘常驻、开机自启、关窗不退出、端口被占自动让位
- **控制台**：零框架原生 HTML/CSS/JS，明暗双主题 + 跟随系统，带完整设计 token 体系
- **安全边界**：工具天然绑定会话（模型无法把消息发到别的群）、发送白名单 + 限频、联网抓取带完整 SSRF 防护（DNS 校验 / IP 固定 / 手动跟重定向）、图片地址禁内网
## 设置项都能做什么
**模型 API**
- 多提供商模型目录：填 Base URL + Key，点「获取列表」自动拉模型，选中即切换；中转站返回几百个模型时内置搜索 + 厂商/模型双栏
- 一键测试：发个 ping 立刻验证地址/Key/模型通不通，显示延迟
- 成本核算：内置 140 个模型的官方价格表自动匹配；走中转站可关掉官方价自填单价，支持「渠道：模型」两级定价、峰谷分时、图片计费规则提示
- 视觉开关：模型不支持图片时关掉，看图工具自动从提示词移除
**聊天设置**
- **响应档位滑条**（省 token 核心）：0~100 无级调节——1 档仅 @ 响应、2 档 +关键词、3 档按概率随机响应（滑条位置线性决定概率）、4 档全响应；没命中的消息直接标已读，零 token 消耗。触发原因决定上下文条数：被 @ 时永远带最多上下文
- **表情包积极程度** 0~3 档：不鼓励 / 偶尔 / 较积极 / 表情包爱好者（提示词层面引导，不强制）
- 人设系统：内置「小鲸鱼」角色卡开箱即用，多套模板一键填充可改；参与度风格（安静/普通/活跃）可调
- 关键词、每群独立开关、私聊开关、屏蔽名单（被屏蔽者不存档、不触发、不进提示词）
**记忆**
- 自动记录对群友的长期印象；可手动触发整理（合并重复、删过时），或对单个群友「更新记忆」
**搜索服务**
- 6 家内置（Bing 免 Key / DeepSeek / 智谱 / 博查 / 百度千帆 / 秘塔）+ 自定义添加任意兼容服务，可加多个
**白名单**
- 从 QQ 账号拉群列表/好友列表直接勾选；机器人只对名单内的会话工作
**桌面端**
- 托盘常驻 / 开机自启 / 关窗不退出；明暗主题；版本更新检查（发现新版本时直接提示）
**OneBot**
- 协议端地址可改，适配任何 OneBot v11 实现
## 界面一览
- **会话**：每次处理一个会话卡片，完整留档——提示词、思考、工具调用与结果、实际发出的每条消息、用量；运行中实时刷新
- **存档**：每个群/好友的消息库，未读标记一目了然；可手动唤醒一次处理或全部标已读
- **记忆**：每个群友一份档案，可编辑、删除、单独更新
- **用量**：三维度统计 + 下钻明细 + 调用次数明细（内置 28 种工具按类别分组的趣味统计，启用 Skill 后还会更多）
- **设置**：以上所有
## 扩展（两型：插件 / Skill）
扩展分**两型**，按"什么时候该运行"来选，放进对应目录即生效：
| 类型 | 放哪 | 靠什么生效 | 谁决定何时执行 |
|---|---|---|---|
| **确定性型（插件）** | `plugins/ /` | 能力 `providers` / 钩子 `hooks` | **核心代码**：满足条件必然执行，不经过 LLM |
| **LLM 型（Skill）** | `skills/ /` | 工具 `registerTool` + 提示词片段 | **模型**：看工具说明自己判断 |
 [code] 
判据一句话：**规则能写死 → 插件（`plugins/`）；要理解人话 → 技能（`skills/`）**。
（完整的定义与三问判断法见两份开发文档的 §0。）
选错类型的后果是**功能静默失效**（不报错、不崩、就是没反应），所以两份开发文档请先读：
- **确定性型** → doc/extend_development/plugin-development.md
- **LLM 型** → doc/extend_development/skill-development.md
- 共同机制完整参考 → doc/extend_development/skill-reference.md
其它约定：
- **开关只有一处**：`config.skills[id].enabled`。关掉一个扩展，它注册的工具、
 提供的能力、提示词片段、请求改写会**同时**失效 —— 不会出现"界面关了但还在偷偷工作"。
- **按能力依赖，不按名字**：核心模块问"谁提供 `llm.request-params`"，
 不 import 具体扩展，所以换实现不用改核心代码。
- **不可能覆盖安全规则**：扩展的提示词片段优先级被强制压在核心规则之下。
- **状态可解释**：控制台的「技能」与「插件」两个页签各自直接告诉你为什么某项没生效
 （未启用 / 依赖缺失 / 加载失败 / 模型不