Skip to content

2.5.0

Choose a tag to compare

View all tags
@Ruqiehou Ruqiehou released this 17 May 08:04
· 99 commits to main since this release
2.5.0
151a6ba

Joha v2.5.0 — 架构解耦与SDK迁移

🎯 概述

2.5.0 是一次深度架构重构版本，核心目标是消除外部依赖、扁平化包结构、解耦模块间强绑定。自研 joha/sdk 取代 ncatbot 成为消息平台通信层，决策层全面扁平化，知识库引擎归入工具层，配置管理进一步解耦。

🔥 核心变更

1️⃣ 自研 SDK 替代 ncatbot

变更项 旧 新
消息平台入口 from ncatbot.core import BotClient from joha.sdk import BotClient
事件模型 ncatbot GroupMessage SDK GroupMessageEvent（强类型 dataclass）
发送消息 bot_api.post_group_msg() bot_api.send_group_message()
连接配置 config.set_ws_uri() → 全局 config BotClient 构造参数 ws_url / access_token
依赖 ncatbot>=4.4.1 websockets>=12.0
  • GroupMessageEvent 新增 at_user_ids / reply_message_id 字段，从消息段自动解析 @ 和回复信息
  • image_utils.py 全面适配 SDK 消息段格式（segments + file_base64）

2️⃣ 知识库引擎迁移

旧: joha/decision/knowledge/     ← 位于决策层，职责不匹配
新: joha/tools/knowledge/        ← 归入工具层，与 search / webpage 同级
  • 所有导入路径从 joha.decision.knowledge.base → joha.tools.knowledge.base
  • tools/__init__.py 统一导出全部工具

3️⃣ decision 层扁平化

旧:
joha/decision/
  ├── knowledge/     ← 已迁移
  ├── tools/         ← 已删除（废弃重复文件）
  └── *.py

新:
joha/decision/
  └── *.py           ← 8 个模块平铺，无子目录
  • 删除 decision/tools/（其中的 search.py / webpage.py / link_preview.py 是 joha/tools/ 的过期副本）
  • decision/__init__.py 精简导出，移除 KnowledgeBase 和工具名

4️⃣ 回复决策配置解耦

  • reply_decision 参数从 config.json 剥离，独立为 config/reply_decision.json
  • 新增 reply_config.py 加载器，支持懒加载 + 热重载（reload()）
  • reply_decison_config.py 现已修复 → reply_config.py（修复命名拼写错误）

5️⃣ 模块导入解耦

解耦点 方案
斜杠命令跳过意图识别 3 层防护：message_handler 前缀拦截 → command_handler 直接处理 → 返回 handled
generator 与管理命令 commands.py 顶部移除 from joha.ai.generator，改为 /切换模型 内局部 import
decision/knowledge 已整体迁移，decision/ 不再导入知识库

📊 版本对比

指标 v2.4.x v2.5.0
第三方消息依赖 ncatbot==4.4.1 无（自研 SDK）
decision 子目录 2 个（knowledge / tools） 0 个
独立配置文件 — reply_decision.json
模块扁平度 4 层嵌套 3 层（joha/ → decision/ → *.py）

🔧 升级指南

从 v2.0.x 升级：

# 1. 更新依赖
pip install websockets>=12.0
pip uninstall ncatbot

# 2. 配置文件迁移
#    无需额外操作，reply_decision.json 会自动读取

# 3. 启动参数迁移
#    原 config.yaml 的 ws_uri / ws_token → 直接传入 BotClient 构造参数

⚠️ 注意：如果存在自定义脚本直接引用 joha.decision.knowledge 或 joha.decision.tools，需更新为 joha.tools.knowledge / joha.tools。

✅ 兼容性

  • 现有 main.py 入口需升级为 SDK 写法（已更新 README 示例）
  • 存储层（storage/txt/ 分片 JSON）格式不变，向前兼容
  • 配置文件 config.json 格式不变，reply_decision 字段已剥离
  • 全部运行时命令（/全局启动、/切换模型 等）行为不变
Assets 2
Loading