Skip to content

3.4.0

Choose a tag to compare

View all tags
@Ruqiehou Ruqiehou released this 23 May 08:48
· 79 commits to main since this release
3.4.0
dd6ec6c

Joha v3.4.0 发版声明

发布日期：2026-05-23

🎉 概述

Joha v3.4.0 正式发布！本次更新聚焦于架构优化、稳定性增强和开发者体验提升，对核心模块进行了精简重构，移除了冗余的知识库系统，让整体代码更加清晰可维护。

✨ 新特性

🏗️ 架构重构

  • 适配层独立 (joha/adapter/)：将 NapCatQQ 连接、事件分发、BotAPI 封装为独立适配层，通过 connection.yaml 统一管理连接配置
  • 配置文件标准化：连接配置与业务配置彻底分离，不再耦合在 main.py 中硬编码
  • 决策引擎 v1.0：采用"总分架构"的 DecisionEngine 统一编排决策流水线，各子模块（回复决策、意图分类、命令分析、冷却管理、群组状态）保持单一职责

🤖 AI 能力

  • 多 Provider 动态切换：支持运行时通过 /切换模型 <名称> 无感切换 LLM Provider，无需重启
  • 意图识别独立配置：支持为意图识别单独配置 AI 模型（intent_recognition），不占用对话模型配额
  • 工具调用专用模型：支持为工具调用单独配置模型（tool_calling），实现对话、意图、工具三线解耦
  • 多模态支持增强：自动检测当前模型是否支持图片，不支持的模型自动跳过图片处理

🎛️ 决策系统

  • 智能意图融合：规则分类与 AI 分类双重判断，加权融合（blend 配置），支持根据一致性动态调整权重
  • 垃圾信息检测：字符多样性分析、重复内容检测、无意义消息过滤，自动降低回复概率
  • 群组动态调节：根据消息频率（MPM）自动分级（very_busy / busy / normal / quiet / dead），动态调整阈值
  • 认可率反馈：群内好评/差评自动调节回复阈值（threshold_adjustments）

🔧 工程化

  • 统一启动入口 run.py：通过 joha/adapter/config/connection.yaml 自动读取连接参数
  • 日志系统升级：多级别日志、文件轮转、预定义日志记录器
  • LRU 缓存系统：TTL 过期、函数结果缓存装饰器
  • 配置热加载：reply_decision.json 修改后无需重启，/知识库刷新 或代码 reply_cfg.reload() 即可生效

⚠️ 破坏性变更

🗑️ 知识库系统移除

本次版本移除了本地知识库（RAG）模块，包括以下内容：

移除项 位置
KnowledgeBase 类 joha/tools/knowledge/core.py
BM25 检索引擎 joha/tools/knowledge/core.py
分片式 JSON 存储 joha/storage/txt/
save_conversation() joha/core/handlers/service.py
get_latest_json_file() joha/core/handlers/service.py
知识库搜索工具 joha/decision/decision_engine.py → tool_map
知识库相关命令 群内 /知识库* 命令失效

迁移建议： 如需知识增强功能，建议通过配置外部搜索工具（joha/tools/search/）或接入外部 RAG 服务实现。

🔄 配置文件变更

  • config.example.json 新增 intent_recognition 和 tool_calling 配置块
  • reply_decision.json 新增 blend、spam_detection、threshold_adjustments 等配置节点
  • 请务必检查并合并示例配置文件中的新增字段

📦 引入变更

  • 不再依赖 jieba（随知识库移除）

📂 当前项目结构

JohaChat/
├── run.py                            # 统一启动入口
├── requirements.txt
├── docs/                             # 📚 技术文档
│   ├── architecture.md               # 系统架构设计
│   ├── configuration.md              # 配置详解
│   ├── modules.md                    # 模块说明
│   ├── development.md                # 二次开发指南
│   ├── api_reference.md              # 核心 API 参考
│   ├── deployment.md                 # 部署运维文档
│   ├── troubleshooting.md            # 故障排查文档
│   └── faq.md                        # 常见问题
│
├── joha/
│   ├── adapter/                      # 适配层（NapCatQQ 连接）
│   │   ├── bot_client.py
│   │   ├── napcat_launcher.py
│   │   ├── config/                   # 连接配置
│   │   └── core/                     # 事件、API、事件总线
│   │
│   ├── core/                         # 编排入口层
│   │   ├── handlers/                 # 消息处理、命令、服务
│   │   ├── builders/                 # 上下文构建、消息队列
│   │   └── utils/                    # 运行时上下文、工具注册、后处理
│   │
│   ├── ai/                           # AI 驱动层
│   │   ├── clients.py                # OpenAI 协议客户端
│   │   ├── providers.py              # 多 Provider 管理
│   │   ├── bot.py                    # 高层 Bot 封装
│   │   ├── generator.py              # 回复生成器
│   │   └── classifier.py             # 文本分类器
│   │
│   ├── decision/                     # 决策大脑层
│   │   ├── decision_engine.py        # 总控引擎
│   │   ├── reply_decision.py         # 回复概率计算
│   │   ├── reply_config.py           # 决策配置热加载
│   │   ├── intent_classifier.py      # AI 意图识别
│   │   ├── command_analyzer.py       # 自然语言命令分析
│   │   ├── group_state.py            # 群组状态追踪
│   │   └── cooldown.py               # 冷却管理
│   │
│   ├── managers/                     # 数据管理层
│   │   ├── personas.py               # 人设管理
│   │   ├── style_learner.py          # 风格学习
│   │   ├── history_manager.py        # 历史记录
│   │   ├── user_profile.py           # 用户画像
│   │   └── admin.py                  # 管理员系统
│   │
│   ├── tools/                        # 工具层
│   │   ├── search/                   # 网络搜索
│   │   └── webpage/                  # 网页抓取
│   │
│   └── config/                       # 配置与基础设施
│       ├── managers/                 # 配置管理器、群组模式
│       └── infrastructure/           # 日志、缓存
│
└── logs/                             # 运行日志

📦 依赖

依赖 版本 用途
websockets >=12.0 WebSocket 客户端
openai >=1.0.0 LLM API 调用
pyyaml >=6.0 YAML 配置解析
python-dotenv >=1.0.0 环境变量管理（可选）

🚀 升级指南

从 v3.3.x 升级到 v3.4.0

# 1. 拉取最新代码
git pull origin main

# 2. 安装依赖（jieba 已不再需要，可手动卸载）
pip install -r requirements.txt
pip uninstall jieba -y  # 可选

# 3. 合并配置文件
# 对比 config.example.json，手动合并新增字段到你的 config.json
# contrast reply_decision.json，确认是否有新增节点

# 4. 创建连接配置文件
cp joha/adapter/config/config.example.yaml joha/adapter/config/connection.yaml
# 编辑 connection.yaml，填入你的机器人 QQ 号和 WebSocket 地址

# 5. 重启机器人
python run.py  # 新的统一启动入口

配置文件迁移要点

  1. connection.yaml 新增字段：

    • auto_start：是否自动启动 NapCat
    • napcat_dir：NapCat 目录路径
    • webui_uri / webui_token：WebUI 连接信息
    • root：超级管理员 QQ 号

  2. reply_decision.json 新增节点：

    • blend：规则与 AI 意图融合权重
    • spam_detection：垃圾信息检测参数
    • threshold_adjustments：认可率动态阈值调节
    • length_bonuses 拆分为独立节点

  3. config.json 新增节点：

    • intent_recognition：意图识别模型独立配置
    • tool_calling：工具调用模型独立配置

📖 文档

本次版本新增完整的技术文档（位于 docs/ 目录）：

文档 说明
architecture.md 系统架构设计
configuration.md 配置项完整说明
modules.md 模块接口文档
development.md 二次开发指南
api_reference.md 核心 API 参考
deployment.md 部署运维指南
troubleshooting.md 故障排查手册
faq.md 常见问题解答

🤝 致谢

感谢所有为 Joha 贡献反馈和建议的用户！

Joha v3.4.0 — 更轻量、更稳定、更智能

Assets 2
Loading