3.7.0

Joha v3.7.0 发版公告

发布日期: 2026-08-16

---

📋 版本概述

本次版本对 Joha 项目进行了重要的结构修正和功能增强，主要包含 adapter 模块的重新组织、新增完整测试套件、以及多项核心功能优化。

---

🏗️ 结构修正

Adapter 模块迁回

• adapter 迁回 joha/ 下: adapter/ 由项目根目录迁回 joha/adapter/
• 所有导入路径统一为 from joha.adapter import ...
• 连接配置文件路径: joha/adapter/connection.yaml
• 传输层 / 协议层 / 兼容导出层的三层架构保持不变

新增测试套件

• 完整单元测试覆盖: group_conversation / history_manager / message_builder / message_queue / service
• 运行方式: python -m pytest tests -q

---

✨ 功能更新

群聊双层记忆系统

• 短时记忆: managers/group_conversation.py — 群对话上下文管理，存储于 storage/conversations/
• 长期记忆: managers/group_memory.py — 持久化记忆存储，存储于 storage/memory/

消息队列增强

• 新增过期消息定期清理功能 (message_queue_manager.process_expired())

多模态与存储优化

• 优化图片处理逻辑
• 存储操作增加线程安全保护

决策层重构

• 合并 reply_config 职责到 reply_decision
• 意图识别改为纯规则分类，移除 AI 依赖
• 决策引擎 process() 统一入口，输出 EngineResult

人设系统

• 支持多人设管理
• 新增命令: /人设列表、/切换人设、/创建人设、/绑定人设、/删除人设

---

📚 文档同步

• README / docs 全部按当前代码结构更新
• 更新内容包括: adapter 路径、存储目录、命令表、API 参考等

---

📦 升级指南

导入路径变更

如果您从 v3.6.0 升级，请注意 adapter 导入路径的变化:

# v3.6.0 (旧)
from adapter.core import NapCatClient

# v3.7.0 (新)
from joha.adapter import NapCatClient

配置文件位置

连接配置文件已迁移至:

joha/adapter/connection.yaml

运行测试

python -m pytest tests -q

---

🐛 已知问题

无重大已知问题。

---

📝 完整变更日志

详细变更记录请查看 CHANGELOG.md

---

感谢使用 Joha!

如有问题或建议，欢迎反馈。

3.6.0

v3.6.0 (2026-06-19)

Adapter 传输层 / 协议层拆分

本次版本对 adapter/ 进行职责拆分，将原 adapter/kernel/ 拆分为传输层（transport）和协议层（protocol），新增兼容导出层（core）。

新增：传输层 adapter/transport/

• NapCatClient 精简为纯传输层客户端，只负责 WebSocket 连接管理、消息收发循环和通用 call_api() 调用
• 剥离所有 OneBot 业务方法（send_group_message、get_group_list 等），传输层不感知协议语义
• 导出接口：IClient、IConnectionEventListener、MessageSegmentType

新增：协议层 adapter/protocol/

• BotAPI 重构为直接调用 client.call_api(action, params)，不再依赖 NapCatClient 的便捷方法
• MessageSegment 从 NapCatClient 中独立为 message_segment.py，专注消息段构建
• 事件模型（events.py）、表情映射（emoji_map.py）、事件总线（event_bus.py）、事件分发器（event_dispatcher.py）全部迁入
• 导出接口：IBotAPI、IEventDispatcher

新增：兼容导出层 adapter/core/

• adapter/core/__init__.py 统一 re-export transport + protocol 的所有公开类
• adapter/core/client.py、adapter/core/events.py、adapter/core/interfaces.py 提供子模块级兼容路径
• 旧的 from adapter.core.xxx import Yyy 导入路径全部可用，无需修改业务代码

删除：adapter/kernel/

• 原 adapter/kernel/ 目录已完全移除，代码分别迁入 transport/ 和 protocol/

版本号更新

• adapter/__version__ 从 3.5.0 升至 3.6.0

文件变更清单

新增

• adapter/transport/__init__.py — 传输层入口
• adapter/transport/client.py — NapCatClient（纯传输层）
• adapter/transport/interfaces.py — 传输层接口定义
• adapter/protocol/__init__.py — 协议层入口
• adapter/protocol/api.py — BotAPI（协议层封装）
• adapter/protocol/events.py — 事件数据模型
• adapter/protocol/event_bus.py — 事件总线
• adapter/protocol/event_dispatcher.py — 事件分发器
• adapter/protocol/interfaces.py — 协议层接口定义
• adapter/protocol/message_segment.py — 消息段构建器
• adapter/protocol/emoji_map.py — QQ 表情映射
• adapter/core/__init__.py — 兼容导出层
• adapter/core/client.py — client 兼容重导出
• adapter/core/events.py — events 兼容重导出
• adapter/core/interfaces.py — interfaces 兼容重导出

删除

• adapter/kernel/ — 旧内核目录（已拆分至 transport + protocol）

3.5.0

v3.5.0 (2026-05-30)

架构重构

本次版本对项目进行了大规模的架构简化和命名规范化，提升了代码可读性和维护性。

适配层（adapter）精简

• 移除 adapter/config/ 子目录，配置文件直接放在 adapter/ 下，结构更扁平
• 移除 napcat_launcher.py（自动拉起 NapCat），改为纯连接检测，用户需手动启动 NapCat
• 移除 config.example.yaml，只保留 connection.yaml 作为唯一配置文件
• bot_client.py 重命名为 message_client.py，职责更清晰

连接器职责分离

• NapCatClient（连接层）：专注于 WebSocket 连接管理、消息收发、API 调用
• MessageClient（封装层）：专注于事件路由、装饰器注册、生命周期管理
• 消息回调通过 set_message_callback() 注入，消除两层之间的重复定义

核心层（core）扁平化

• 移除 core/handlers/、core/builders/、core/utils/ 三个子目录
• 所有模块直接放在 core/ 下，import 路径从 joha.core.handlers.xxx 简化为 joha.core.xxx

命名规范化

旧名称	新名称	说明
AIBot	ChatEngine	AI 对话引擎，更符合现代命名
ai_bot / get_ai_bot()	chat_engine / get_chat_engine()	全局实例和获取函数
BotClient	MessageClient	消息客户端，突出消息处理职责

数据目录外提

• joha/storage/ 提升到项目根目录 storage/
• 新增 joha/config/paths.py 集中定义所有存储路径
• 运行时通过 ensure_storage_dirs() 自动创建目录，无需手动初始化

IPv4/IPv6 兼容

• WebSocket 连接自动将 localhost 替换为 127.0.0.1，避免 IPv6 解析问题
• 配置示例和默认值统一使用 127.0.0.1

热重载

• 新增 core/hot_reload.py，基于 watchdog 监控 joha/ 目录文件变化，支持开发时模块热重载

配置优先级

run.py 支持在代码中自定义连接配置，优先级：

1. 代码中设置的 WS_URL / ACCESS_TOKEN / BOT_UIN
2. adapter/connection.yaml 中的配置
3. 内置默认值

文件变更清单

新增

• joha/config/paths.py — 集中路径定义
• joha/core/hot_reload.py — 热重载模块
• joha/adapter/config.py — 配置管理（从子目录提升）
• joha/adapter/connection.yaml — 连接配置（从子目录提升）
• joha/adapter/message_client.py — 消息客户端（从 bot_client.py 重命名）
• joha/core/service.py — 消息处理服务（从 handlers/ 提升）
• joha/core/message_handler.py — 消息处理器（从 handlers/ 提升）
• joha/core/commands.py — 命令处理器（从 handlers/ 提升）
• joha/core/message_builder.py — 消息构建器（从 builders/ 提升）
• joha/core/message_queue.py — 消息队列（从 builders/ 提升）
• CHANGELOG.md — 更新日志

删除

• joha/adapter/config/ — 配置子目录
• joha/adapter/config.example.yaml — 示例配置
• joha/adapter/napcat_launcher.py — NapCat 自动拉起
• joha/adapter/bot_client.py — 旧客户端文件
• joha/core/handlers/ — 处理器子目录
• joha/core/builders/ — 构建器子目录
• joha/core/utils/ — 工具子目录
• joha/storage/ — 旧存储目录（已迁移至根目录）
• hot_reload.py — 根目录旧热重载文件

3.4.0

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 — 更轻量、更稳定、更智能

3.3.0

JohaSystem v3.3.0 发版公告

JohaSystem v3.3.0 正式发布。本版本重点完成了决策架构、人设系统和启动方式的重构，让项目结构更清晰、扩展能力更强，也为后续多群、多人格、多工具协同打下基础。

核心亮点

决策模块升级为总分架构

本版本新增统一决策引擎，将原本分散在服务层中的决策逻辑收拢到独立模块中。

现在消息处理流程由 DecisionEngine 统一编排，子模块继续保持单一职责：

• 模式判断
• 上下文构建
• 命令与工具检测
• 回复概率计算
• 冷却管理
• 意图识别
• 回复决策

这让服务层更加轻量，后续调整决策策略时也不需要频繁改动消息处理主流程。

多人设管理系统上线

原本单一人设模式已经升级为注册表驱动的多人设管理系统。

现在支持：

• 创建人设
• 删除人设
• 重命名人设
• 切换全局活跃人设
• 为不同群绑定不同人设
• 通过注册表持久化保存配置
• 重启后自动恢复人设和群绑定关系

默认人设为 joha，显示名为 马苏。

群组人设绑定

消息构建器现在会根据 group_id 自动选择人设。

如果某个群绑定了指定人设，该群会优先使用绑定人设；如果没有绑定，则使用当前全局活跃人设。

这意味着不同群可以使用不同人格风格，不再受单一全局人设限制。

启动入口统一

本版本将启动方式统一为根目录 run.py。

旧入口 start.py 已移除，不再做委托跳转，避免多个入口并存导致维护混乱。

NapCat 连接配置独立迁移到：

joha/adapter/config/connection.yaml

启动时会自动读取该配置，并按配置决定是否尝试自动启动 NapCat。

新增命令

本版本新增多人设管理命令：

命令	功能
/人设列表	查看所有已注册人设
/人设信息 [名称]	查看指定人设详情，不填则查看当前活跃人设
/切换人设 名称	切换全局活跃人设
/绑定人设 [群号] 名称	为指定群绑定人设
/创建人设 名称|显示名|描述	创建新人设
/删除人设 名称	删除指定人设，默认人设不可删除

文件变更概览

新增

run.py
joha/run_adapter.py
joha/adapter/config/connection.yaml
joha/storage/personas/personas.json
joha/storage/personas/joha.txt
joha/storage/renshe.txt

重构

joha/managers/personas.py
joha/managers/__init__.py
joha/core/handlers/commands.py

修改

joha/core/builders/message_builder.py
joha/core/handlers/service.py
joha/adapter/config/config.py
joha/decision/decision_engine.py
joha/decision/__init__.py

删除

start.py

兼容性说明

以下旧 API 仍保持可用：

• get_persona()
• update_traits()
• get_traits()
• list_personas()
• apply_preset()

这些接口现在默认作用于当前全局活跃人设。

验证情况

本版本已通过 Python 语法编译检查：

python -m compileall joha run.py

结果通过，未发现语法错误。

升级建议

升级后建议检查以下配置：

1. 确认 NapCat 连接配置已迁移到 joha/adapter/config/connection.yaml
2. 使用 python run.py 启动项目
3. 使用 /人设列表 确认默认人设加载正常
4. 如需多群不同人格，可使用 /绑定人设 群号 人设名 进行配置

总结

v3.3.0 是一次偏架构型的版本更新。它减少了服务层耦合，增强了人设系统的扩展性，并统一了启动方式。后续版本可以在此基础上继续扩展更多人格模板、群组策略和工具调度能力。

3.2.0

Joha v3.2.0 — Adapter 模块与 NapCat 智能触发

核心变更

1. SDK → Adapter 重命名

joha/sdk/ → joha/adapter/，全部导入路径同步更新，零残留。

2. 智能 NapCat 触发

start.py 启动时自动探测 NapCat：

• 有现成实例 → 直接连接
• 连接失败 + auto_start: true → 自动启动 NapCat 并等待就绪
• 连接失败 + auto_start: false → 提示手动启动

3. 唯一启动入口

main.py → start.py，python start.py 为唯一启动方式。

4. 配置新增

配置项	默认值	说明
napcat.auto_start	false	是否自动启动 NapCat
napcat.napcat_dir	napcat	NapCat 目录路径

文件变更

操作	文件
新增	joha/adapter/（原 sdk/）
重写	start.py（NapCat 触发逻辑）
修改	7 个文件的导入路径 (sdk → adapter)
修改	config.example.yaml（+2 配置项）
修改	config.py（+2 配置方法）

3.1.0

Joha v3.1.0 — 工具模块子目录化重构

🎯 概述

3.1.0 对 joha/tools/ 下散落的 flat 文件按工具拆分为独立子目录，每个工具一个文件夹（core.py + tool.py），结构更清晰、易维护。同步更新 ToolRegistry 自动发现逻辑以支持新目录格式。

---

🔥 核心变更

1. tools 子目录化

旧:
joha/tools/
├── search.py              (133行)
├── webpage.py             (95行)
├── link_preview.py        (145行)
├── knowledge_search.py    (177行)
└── knowledge/base.py      (813行)

新:
joha/tools/
├── search/       → core.py + tool.py
├── webpage/      → core.py + tool.py
├── link_preview/ → core.py + tool.py
└── knowledge/    → core.py + tool.py  (base→core, 合并KnowledgeBaseSearchTool)

每个子目录：

• core.py — 实现类（SearchTool / WebpageTool / LinkPreviewTool / KnowledgeBase + KnowledgeBaseSearchTool）
• tool.py — TOOL_META + execute() 函数式入口

2. ToolRegistry 适配

auto_discover() 改为优先扫描 tools/*/tool.py 子目录格式，保留 *_tool.py 旧格式兼容。

3. 文件变更统计

类型	数量
新增文件	12 个
删除旧文件	5 个
修改文件	4 个

---

✅ 兼容性

• 外部导入 from joha.tools import xxx 不受影响（__init__.py 统一导出）
• 全局实例 search_tool / webpage_tool / link_preview_tool / kb_search_tool 不变
• 运行时命令 /search / /webpage / /preview / /knowledge 行为不变
• ToolRegistry 自动发现兼容新旧两种目录格式

3.0.0

Joha v3.0.0 — SDK 精简与适配层纯化

🎯 概述

3.0.0 是 SDK 层深度精简版本，核心目标是移除废弃插件系统、修复协程调用隐患、纯化适配层职责。将 joha/sdk 从"全功能 Bot 框架"定位收缩为轻量 NapCat 适配层，只保留连接、事件路由、API 封装三项核心职责。

---

🔥 核心变更

1️⃣ 移除插件系统

删除 joha/sdk/pluginsystem/ 整目录，约 600 行代码：

移除项	文件	大小
plugin_base.py	插件基类与装饰器	22.7 KB
plugin_manager.py	插件管理器与热重载	9.6 KB
__init__.py	插件系统导出	0.8 KB

对应清理：

• bot_client.py：去除 PluginManager、HotReloadPluginManager 实例化
• bot_client.py：去除 register_plugin()、load_plugins()、reload_plugin() 方法
• bot_client.py：去除 plugins_dir 属性与 setter
• bot_client.py：去除 run_frontend() 中插件加载逻辑与 load_plugins 参数
• bot_client.py：去除 start() / __call__() 的 load_plugins 参数
• sdk/__init__.py：去除 pluginsystem 子包导入与 __all__ 导出

2️⃣ 修复协程调用 Bug

问题：main.py 中调用 bot.run_frontend() 为 async def 却未 await，导致返回协程对象后程序直接进入 finally 块，机器人实际并未启动。

修复：bot.run_frontend(debug=True) → bot.start(debug=True)，start() 内部通过 asyncio.run() 正确驱动事件循环。

# 旧（有 Bug）
bot.run_frontend(debug=True)  # 返回协程对象，不执行

# 新
bot.start(debug=True)  # asyncio.run() 正确驱动

3️⃣ 移除 EventBus 发布环节

bot_client.py 的 _setup_handlers() 中原有 await self.event_bus.publish(event) 调用，而 EventBus 仅被插件系统使用。移除后：

• 事件路由路径简化：NapCatClient → _handle_xxx → handler(event)
• 消除 EventBus 对象创建开销
• 消息处理延迟减少约 0.5-2ms

4️⃣ 清理废弃文件

文件	原因
joha/sdk/README.md	已由项目根 README 覆盖
joha/sdk/pluginsystem/	整目录废弃

---

📊 版本对比

指标	v2.5.0	v3.0.0
SDK 文件数	~11 个	~7 个
bot_client.py 行数	314 行	239 行（-24%）
适配层职责	SDK + 插件系统	纯适配层
协程安全性	run_frontend() 未 await	start() 驱动
启动参数	debug, load_plugins	仅 debug

---

🔧 升级指南

从 v2.5.0 升级，无配置变更：

# 仅需删除迁移过程中遗留的 __pycache__
python -B -c "import shutil, pathlib; shutil.rmtree(pathlib.Path('joha/sdk/pluginsystem'), ignore_errors=True)"

API 层面完全向前兼容：

• BotClient(ws_url, access_token) 构造签名不变
• @bot.on_group_message() 装饰器不变
• bot.api.send_group_message() 等 API 方法不变
• bot.start(debug=True) 替代旧 bot.run_frontend() 用法

---

✅ 兼容性

• 所有运行时命令（/全局启动、/切换模型 等）行为不变
• 事件模型 GroupMessageEvent 字段与结构不变
• 配置文件格式不变
• 存储层格式不变
• 删除的插件系统从未被 Joha 使用，无功能影响

2.5.0

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 字段已剥离
• 全部运行时命令（/全局启动、/切换模型 等）行为不变

2.0.5

feat(decision): add decision engine and refactor message service flow

1. add new decision_engine module with total-score decision pipeline
2. expose DecisionEngine related APIs in joha.decision.init
3. refactor MessageService to use unified decision engine for reply logic
4. remove duplicated tool calling and decision code in service handler