执行 hermes doctor 或启动 Hermes Agent 时出现 ModuleNotFoundError、ImportError 等依赖错误，需在 Hermes 自建虚拟环境中强制重装核心依赖；先激活对应系统虚拟环境，再用 pip --force-reinstall --no-deps 或 uv 彻底重建纯净依赖链。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你执行 hermes doctor 或启动 Hermes Agent 时反复报出 ModuleNotFoundError、ImportError，或日志中明确提示 python-telegram-bot not found、aiohttp version conflict 等错误，说明当前 Python 环境中存在依赖版本错乱、多环境路径混淆或缓存污染问题，必须绕过系统 pip 干扰，直接在 Hermes 自建虚拟环境中重建纯净依赖链。
强制进入 Hermes 虚拟环境重装核心依赖
这一步是解决 90% 依赖冲突的首选方案，它不依赖系统 pip 配置，而是显式激活 Hermes 内置 venv，在隔离上下文中强制覆盖关键包。
第一步：打开终端（Windows 用户必须使用 PowerShell；macOS/Linux 使用默认 Terminal）。
第二步：切换到 Hermes 安装根目录——【这是关键前提，路径错则全部失效】：
macOS/Linux 执行 cd ~/.hermes；Windows PowerShell 执行 cd $env:LOCALAPPDATA\hermes。
第三步：激活虚拟环境：
macOS/Linux 运行 source bin/activate；Windows 运行 Scripts\activate.ps1（若提示执行策略被阻止，请先运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser）。
第四步：在已激活环境中，执行强制重装：pip install --force-reinstall --no-deps python-telegram-bot uvloop aiohttp cryptography。
注意：不要加 -r requirements.txt，避免引入旧版冲突依赖；【--no-deps 是必须参数，否则会触发 pip 的递归依赖解析，反而加剧冲突】。
用 uv 替代 pip 彻底重建依赖树
当 pip 重装失败或仍报缓存污染时，uv 是 Hermes 官方指定的替代方案，它跳过 pip 缓存机制，从零构建依赖图谱，对多版本 Python 共存场景特别有效。
方法一：确认 uv 已安装
在终端输入 uv --version，有输出即表示就绪；无输出则执行 curl -LsSf https://astral.sh/uv/install.sh | sh 安装。
方法二：清除旧缓存并重建环境
进入 Hermes 项目目录后，依次执行：uv cache clean → uv venv .venv → source .venv/bin/activate（macOS/Linux）或 .venv\Scripts\activate.ps1（Windows）→ uv pip install -r requirements.txt。
这一步会完全丢弃原有 .venv 目录，生成全新隔离环境。如果之前手动修改过 requirements.txt，请确保该文件为官方原始版本，否则可能引入不兼容依赖。
跳过依赖检查并强制覆盖安装
适用于你已手动修改过项目源码、或插件与主程序存在 pydantic/typing_extensions 等底层库版本硬冲突的场景。
① 进入 Hermes Agent 源码根目录：cd hermes-agent。
② 卸载现有安装：pip uninstall -y hermes-agent。
③ 强制覆盖依赖：pip install --force-reinstall --no-deps -r requirements.txt。
这会无视所有已有包版本，只按 requirements.txt 中声明的版本写入。
④ 重新安装主包：pip install --no-deps -e .。
注意：两次都带 --no-deps，否则 pip 会尝试校验已卸载包的依赖关系，导致中断。
⑤ 补装缺失运行时依赖：pip install "pydantic>=2.6" "typing-extensions>=4.8.0"（根据报错提示的具体模块名调整）。
