陌城qqbot框架 更新日志
========================================

v2.0.1-update3-fix1
----------------------------------------
【修复】aiohttp 版本兼容性
  - Python 3.9/3.10 不兼容 aiohttp 3.12+,启动时报 TypeError: unhashable type: 'list'
  - requirements.txt 按 Python 版本区分约束:<3.11 限定 <3.12.0,>=3.11 不限
  - start.bat/start.sh 依赖安装后增加兼容性检查,Python<3.11 强制降级 aiohttp<3.12.0

【优化】移除默认适配器自动创建
  - 不再自动从旧 onebot 字段生成 default-onebot 适配器
  - 首次启动 adapters 为空,框架正常启动 WebUI 等待用户添加适配器
  - 避免新用户首次启动因无协议端而持续重连报错

【优化】UI 架构精简
  - 删除「连接配置」页面(与「适配器管理」功能重叠)
  - 服务器配置/机器人配置/全局并发配置 迁移到「系统配置」页
  - 「适配器管理」成为适配器配置唯一入口


v2.0.1-beta-update-3
----------------------------------------
【新增】多适配器架构
  - 框架支持同时接入多个 bot 适配器,WebUI 后台可视化管理
  - 适配器类型:OneBot v11(NapCat/Lagrange 等)与 QQ 官方机器人接口
  - core/adapters/ 新增适配器抽象基类与具体实现
  - AdapterManager 全局单例,统一管理多适配器的创建、启动、停止、重载
  - 启动时并行启动所有 enabled 适配器,互不阻塞

【新增】QQ 官方机器人适配器
  - 实现 QQ 开放平台(https://q.qq.com)官方机器人接口接入
  - 鉴权:AppID + AppSecret 换取 access_token,按实际 expires_in 缓存(留 60 秒余量自动刷新)
  - WebSocket 事件接收:完整实现 IDENTIFY(op=2)/Hello(op=10)/心跳(op=1/11)/
    Reconnect(op=7)/Invalid Session(op=9)/Resume(op=6) 协议
  - 事件转换:支持 GROUP_AT_MESSAGE_CREATE(群@机器人)、
    GROUP_MESSAGE_CREATE(群全量消息,需白名单)、AT_MESSAGE_CREATE(频道@机器人)、
    C2C_MESSAGE_CREATE(私聊)、GROUP_ADD/DEL_ROBOT、FRIEND_ADD/DEL
  - 消息发送:bot.send_group_msg 转译为官方 /v2/groups/{group_openid}/messages
  - 消息段格式转换:OneBot MessageSegment ↔ 官方 msg_type/content/image
  - msg_type 自动判定:纯文本=0、Markdown=2、Ark=3、图片(media)=7
  - msg_seq 防重复:被动回复时为每个 msg_id 递增 msg_seq
  - @机器人标签剥离:自动移除 content 中的 <qqbotuser> 标签

【新增】适配器隔离机制
  - 根据 bot.adapter_type 严格路由 API 调用
  - OneBot 适配器只调 OneBot WS API,官方适配器只调官方 HTTPS API
  - 官方适配器不支持的 API 抛 NotImplementedError,不会误调 OneBot

【新增】WebUI 适配器管理页
  - 侧边栏「连接配置」新增「适配器管理」入口
  - 支持列表/新增/编辑/删除/启停/测试连接
  - 根据适配器类型动态渲染配置表单
  - 测试连接:OneBot 调 get_login_info,官方调 /users/@me

【新增】配置向后兼容
  - 旧配置(仅有 onebot 字段)启动时自动迁移为 adapters 数组
  - 保留 get_onebot_config 等 API,Connection 页面继续工作

【变更】启动流程
  - BotApp.run() 委托 AdapterManager 全局单例启动所有适配器
  - lifecycle._bots 按 (self_id, adapter_type) 索引,支持同 self_id 跨适配器
  - 启动横幅遍历 adapters 列表输出每个适配器的连接信息

【变更】权限系统
  - QQ 官方适配器不支持 get_group_member_info,无法查询群成员角色
  - GROUP_ADMIN/GROUP_OWNER 权限在官方适配器下回退到 SUPERUSER 检查
  - 使用官方适配器需将 member_openid 加入 superusers 配置

【修复】QQ 官方适配器 API 路径
  - 修正 getAppAccessToken 调用路径
  - get_app_info 从 /v2/app 改为 /users/@me(官方基础接口用根路径)
  - 获取 WebSocket 网关从 /v2/gateway 改为 /gateway

【修复】WebSocket 事件接收
  - 修正 OpCode 处理:op=0 分发事件、op=10 启动心跳+IDENTIFY、
    op=11 心跳ACK、op=7 Reconnect、op=9 Invalid Session
  - 修正 intents 订阅:GROUP_AND_C2C_EVENT(1<<25) 而非 PUBLIC_GUILD_MESSAGES(1<<30)
  - 修正事件类型字段名:从 payload.type 改为 payload.t
  - 新增 READY 事件处理(提取 session_id)、RESUMED 事件处理
  - 新增 Resume 机制:断线重连时优先用 op=6 恢复会话

【修复】事件转换
  - 修正 attachments 字段名:从 type 改为 content_type
  - 新增 @机器人标签剥离(_strip_bot_mention)
  - 正确字段映射:群消息用 member_openid、C2C 用 user_openid、群 ID 用 group_openid

【修复】消息发送
  - 修正图片 msg_type:从 1 改为 7(官方 media 类型)
  - 新增 msg_seq 防重复机制
  - 修正类型注解:group_id/user_id 为 str(openid 是字符串)

【修复】鉴权与连接
  - 修正 token 缓存时间:从固定 6600 秒改为 expires_in - 60
  - 修复 ClientSession 跨事件循环使用导致的 Timeout 错误
  - test_connection 始终创建临时 client,不复用已运行适配器的 client

【修复】命令匹配与权限诊断
  - event_bus 新增消息事件接收日志和命令匹配诊断日志
  - event_bus 新增权限拒绝日志,便于定位权限问题

【注意事项】QQ 官方适配器限制
  - user_id 是 member_openid(加密字符串,非 QQ 号),与 OneBot 数据不互通
  - 不支持群成员角色查询,管理员命令需将 member_openid 加入 superusers
  - 不支持禁言、踢人、撤回等群管操作
  - 被动回复限制:5 秒内需回复,AI 聊天等耗时操作可能超时
  - 主动消息有配额限制,需 msg_id 且有时效
  - GROUP_MESSAGE_CREATE(全量消息)需申请白名单权限,未开通则只收 GROUP_AT_MESSAGE_CREATE


v2.0.1-beta-update-2
----------------------------------------
【优化】思考模型支持
  - AI 聊天新增「输出思考内容」开关(群级配置,WebUI 可修改)
  - 关闭时:省略思考内容,仅发送正式回复(默认行为,节省 token 与阅读成本)
  - 开启时:将思考内容与正式回复一起发送,格式为「💭 思考过程 + 💬 回复」
  - 兼容多种思考模型字段:reasoning_content(DeepSeek-R1)、
    reasoning(OpenAI o1)、thinking(QwQ/部分供应商)
  - 思考内容不写入对话上下文,避免污染历史消息影响后续回复质量
  - 支持批量配置:WebUI 批量更新群 AI 配置时可一并设置此项

【新增】配置向后兼容
  - 旧配置文件自动补全 show_reasoning 字段(默认 False),无需手动迁移


v2.0.1-beta-update-1
----------------------------------------
【新增】统一插件调用格式
  - 扩展 plugins/utils.py 为完整工具库,新增统一消息构造函数
    (reply_msg/at_msg 等)与 JsonDataManager 基类(懒加载+线程锁+延迟保存)
  - core/onebot/bot.py 新增 17 个 typed API 方法,覆盖常用 OneBot v11 接口

【新增】在线更新保留自定义插件
  - core/updater.py 新增 _BUILTIN_PLUGINS 内置插件清单
  - 更新时仅覆盖清单内的内置插件,plugins/ 目录下用户自定义插件原样保留

【新增】插件开发文档
  - 官网新增 develop.php 插件开发文档(12 章完整教程)
  - README.md 新增「插件开发」章节


v2.0.1-beta
----------------------------------------
【新增】在线自动更新功能
  - 新增版本检测模块 core/updater.py,调用官网 API 获取最新版本数据
  - 版本对比支持语义化版本号,正确处理 beta/正式版类型关系
  - WebUI 登录后自动检测新版本,弹窗提示(显示版本名称+版本号)
  - 版本详情页支持一键在线更新:下载→解压→备份→覆盖→重启 全自动
  - 更新进度实时显示(下载/解压/覆盖/重启各阶段)
  - 更新失败自动回滚,保证数据安全
  - 严格保留 config/ 和 venv/ 目录,不破坏用户配置与运行环境
  - 启动脚本(start.bat/start.sh)启动前自动检测,交互式询问是否更新

【新增】WebUI 版本更新页面
  - 侧边栏新增"版本更新"入口
  - 展示当前版本、最新版本、更新时间、下载链接
  - 一键在线更新,无需手动下载覆盖

v2.0.0 正式版
----------------------------------------
【变更】版本号升级为 v2.0.0 正式版

【修复】网页截图功能
  - 根因:Windows 下 SelectorEventLoop 不支持 asyncio 子进程操作,
          asyncio.create_subprocess_exec 会抛出 NotImplementedError,
          导致 Chrome 从未启动,截图从未生成。
  - 修复:改用 subprocess.run() + asyncio.to_thread() 在线程池中运行 Chrome,
          绕过事件循环的子进程限制。
  - 图片发送改用 base64:// 协议(OneBot v11 标准),兼容性最好。
  - 增强错误诊断:异常信息显示类型名与 repr,便于排查。

【修复】进群验证重复触发
  - 根因:消息处理器中存在 fallback 逻辑,对不在验证状态但刚进群的用户
          会再次触发验证,导致进群后首次发言时重复收到验证提示。
  - 修复:移除消息处理器中的 fallback 触发逻辑,验证仅在进群通知时发起。
          消息处理只针对已在验证流程中的用户(验证码校验/发言通过)。
  - 优化:重新发送验证提示时复用原验证码,避免验证码不一致。
          重新发送时取消原有的超时任务,避免重复创建。

【优化】发布版打包 WebUI 构建产物
  - 发布版直接包含已构建的 WebUI 前端(dist 目录),用户无需等待构建
  - start.bat 优先检测 webui\frontend\dist\index.html,已存在则跳过构建


v2.0.0-beta-fix2
----------------------------------------
【变更】系统名称统一为「陌城qqbot框架」
  - 启动横幅、启动脚本、命令行描述等处统一使用新名称

【变更】启动脚本(start.bat)全面中文化
  - 标题、步骤提示、错误信息、警告等全部改为中文
  - 步骤:[1/5]检查Python → [2/5]虚拟环境 → [3/5]安装依赖 → [4/5]构建WebUI → [5/5]启动框架

【新增】WebUI 后台配置入口
  - 连接配置页新增「全局并发配置」Card,可在线修改 dispatch.max_concurrent(1~512),即时生效
  - AI配置页供应商管理新增故障转移说明提示

【修复】发布版前端产物不匹配
  - 修复打包 zip 内前端产物为旧版导致菜单与根目录运行版不一致的问题
  - 打包前清理 dist 旧产物残留,确保 zip 内为最新构建

【变更】版本号更新为 v2.0.0-beta-fix2


v2.0.0-beta-update1
----------------------------------------
【新增】群列表自动同步
  - 打开任意会显示群列表的页面(群设置、Dashboard 群数等),后端自动静默同步
    OneBot get_group_list,无需再手动点「同步群列表」按钮
  - 同步失败时降级返回本地数据,不阻塞页面、不报 503
  - 群名持久化到 group_settings[gid].group_name,重启后不丢失

【新增】AI 供应商故障转移
  - AI 聊天调用失败时,自动按顺序尝试其它已启用的 AI 供应商
  - 群配置的 provider 作为首选,其它 enabled 供应商作为 fallback 池
  - 全部供应商都不可用时,回复「无可用AI供应商,请联系管理员」
  - 充分利用已配置的多个供应商,提升 AI 聊天可用性

【新增】全局并发可配置
  - 新增 dispatch.max_concurrent 配置项(默认 16),限制并发事件处理任务数
  - 高并发时自动排队,避免压垮内存与 AI 供应商
  - WebUI 后台新增 /api/dispatch 接口,可在线查看与修改并发数(1~512)
  - 修改即时生效,无需重启

【优化】性能
  - 事件间并发受全局 Semaphore 限流,事件内 matcher 仍按优先级串行(保留 block 语义)
  - AI HTTP 会话复用共享连接池,减少连接建立开销
  - 插件加载不阻塞主循环,单个插件失败不影响其它插件


v2.0.0-beta-fix1
----------------------------------------
【修复】AI 聊天消息串群问题
  - 根因:Matcher 作为全局单例,事件分发(dispatch)时将 bot/event 存储在单例属性上。
          AI 聊天 handler 内部有长达数秒~120秒的 await(调用大模型 API),在此期间
          另一个群的新事件触发 dispatch 会覆盖单例上的 event,导致 handler 恢复后
          调用 matcher.finish() 时使用了被覆盖的 event,把 A 群的 AI 回复发到了 B 群。
  - 修复:在 core/event_bus.py 中引入 contextvars.ContextVar,每次 dispatch 调用
          handler 前将当前 bot/event 绑定到协程上下文,Matcher.send/finish 优先从
          ContextVar 读取,确保并发下仍路由到正确的事件目标。
  - 兼容性:Matcher.send/finish 对外 API 签名不变,无需修改任何插件;self.bot/
            self.event 属性仍保留作为 fallback。
  - 影响范围:修复所有 handler 内含 await 且通过 matcher.send/finish 发送消息的
              插件(AI 聊天因 API 耗时最长而最易暴露,其它插件也一并受益)。


v2.0.0-beta
----------------------------------------
【新增】脱离 nonebot,自包含框架
  - 移除 nonebot2 / nonebot-adapter-onebot 依赖
  - 新增 core/ 核心包:事件总线(EventBus)、权限、生命周期、插件加载器、OneBot v11 协议层
  - 21 个插件从 nonebot 导入迁移到 core 导入,功能保持不变
  - requirements.txt 剔除 nonebot 相关依赖

【新增】控制台详细日志
  - 启动时配置 Python logging,带时间戳格式输出到 stdout
  - WebSocket 连接/断连/重连输出日志
  - 收到群消息/私聊消息/通知/请求输出日志(含群号、用户、内容摘要)
  - 命令执行输出命令名与执行结果
  - 插件加载输出成功/失败日志
  - API 错误输出简洁单行警告(同类 60 秒节流,避免刷屏)

【新增】路径可移植性
  - main.py 定义 BASE_DIR 并 os.chdir 到项目根目录
  - config_manager.py、log_manager.py 默认路径基于 __file__ 计算绝对路径
  - 全部 7 个数据插件(group_essence_stats/group_board_games/group_checkin/
    group_points/group_games/group_simulation/group_stats)的数据路径改为基于
    __file__ 的绝对路径,程序可在任意工作目录运行

【新增】版本号显示
  - 新增 core/version.py 定义 __version__
  - 启动横幅显示 Version: v2.0.0-beta

【优化】一键启动脚本健壮性
  - start.bat 使用 cd /d "%~dp0" 切换到脚本目录
  - 使用 %PY% -m pip 安装依赖,绕过中文路径下 pip 启动器编码问题
  - WebUI 绑定 127.0.0.1 并关闭 access_log,减少无效 HTTP 请求噪音
  - Windows 下使用 Selector 事件循环,避免 ProactorReadPipeTransport 错误

【修复】运行时错误
  - 修复 event.to_me 属性缺失(GroupMessageEvent/PrivateMessageEvent)
  - 修复 bot.send 因 isinstance 判断失败导致群消息发到私聊(改用属性 duck typing)
  - 修复 CQ 码(如 [CQ:at,qq=xxx])被当作纯文本发送的问题(新增正则解析器)
  - 新增 ApiError 异常类,API 失败不再抛 RuntimeError 满屏 traceback
