必须在 ubuntu wsl 终端中安装 hermes agent v0.19.1，禁用 powershell/cmd；需卸载残留、安装 python 3.11 及 distutils、手动创建 venv、用 uv 或强制 pip 安装、修复 path 并运行 hermes doctor 自检。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
安装 Hermes Agent 最新 v0.19.1 版本时反复失败，不是网络卡顿或命令敲错的问题，而是环境上下文在 pip、venv、shell 和系统权限四层之间发生断裂——比如你看到 externally-managed-environment 错误却还在用系统 Python 3.12 跑 install，或 hermes: command not found 却没检查 PATH 是否加载了 ~/.local/bin，这些信号都在告诉你：安装流程已脱离 Hermes 的预期执行路径。
先确认是否踩进“Windows原生命令行”陷阱
这一步必须最先做。Hermes v0.19.1 官方明确不支持 PowerShell 或 CMD 直接安装，哪怕你装了 WSL2，只要当前终端窗口标题栏写着“PowerShell”或“命令提示符”，后续所有操作都无效。
打开 Windows 开始菜单 → 搜索并启动 “Ubuntu”（不是“WSL”或“Windows Terminal”）→ 确认终端第一行显示类似 username@DESKTOP-XXXX:~$ → 执行 uname -a，输出中必须含 Linux 和内核版本号。
如果仍用 PowerShell 运行 curl -fsSL https://hermes.dev/install.sh | bash，脚本会静默跳过 venv 创建、直接写入系统级 bin，【导致后续所有 hermes 命令均不可用且无法修复】。
强制重建纯净 Python 3.11 虚拟环境
v0.19.1 已锁定 Python 3.11.x 兼容性，但 Ubuntu/Debian 默认的 python3.12-venv 模块禁用 ensurepip，会触发 externally-managed-environment 报错，且无法通过 --break-system-packages 绕过。
第一步：卸载残留环境
执行 rm -rf ~/.hermes ~/.hermes-venv ~/.local/bin/hermes，清空所有旧痕迹。
第二步：安装受控 Python 运行时
运行 sudo apt install -y python3.11 python3.11-venv python3.11-dev python3.11-distutils，特别注意 distutils 是解决 ensurepip disabled 的关键包。
第三步：手动创建并验证 venv
执行 python3.11 -m venv ~/.hermes-venv && source ~/.hermes-venv/bin/activate && python -c "import sys; print(sys.version)"，输出必须是 3.11.x 开头，否则终止后续步骤。
绕过 pip 冲突，用 uv 替代 pip 安装
方法一：直接使用 uv（推荐）
在激活的 ~/.hermes-venv 环境中，执行 curl -LsSf https://astral.sh/uv/install.sh | sh → 关闭再重开终端 → 运行 source ~/.hermes-venv/bin/activate → 执行 uv pip install -r requirements.txt。
方法二：强制覆盖 pip 行为
若坚持用 pip，在同一环境中运行：pip install --force-reinstall --no-deps -r requirements.txt && pip install --no-deps -e .。
注意：这一步必须在 source ~/.hermes-venv/bin/activate 后立即执行，【离开激活状态再运行将彻底失效】。
修复 PATH 与命令注册断点
1、确认 hermes 二进制位置
进入项目根目录（如 ~/hermes-agent），执行 python -m build，成功后会在 dist/ 下生成 hermes_agent-*.whl 文件。
2、手动安装 wheel 并注册命令
运行 pip install --force-reinstall dist/hermes_agent-*.whl，安装完成后立即执行 hermes --version。
3、若仍提示 command not found，追加 PATH：
执行 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc，然后关闭终端重开。
最后执行自检链
第一步：运行 hermes doctor，观察输出是否全为 ✅；
第二步：若出现 ❌，立即执行 hermes doctor --fix；
第三步：执行 hermes setup --skip-model 跳过模型配置，验证基础服务能否启动；
第四步：运行 hermes logs，等待 10 秒，确认日志流持续滚动且无 Traceback。
