Windows 原生安装 Hermes Agent 踩坑记录｜Git 冲突 + 子模块失败 通俗解读

目录

Windows 原生安装 Hermes Agent 踩坑记录｜Git 冲突 + 子模块失败 通俗解读

一、通俗大白话讲明白两个问题

1. Git Merge 冲突 是什么？

2. 子模块更新失败 是什么？

二、问题因果关系（一句话记住）

三、Windows 原生极简修复方案（可直接复制）

四、后续避坑要点

纯 Windows 原生环境，全程无 WSL、无虚拟机，使用官方 PowerShell 一键脚本安装 Hermes Agent 时，连续触发两个连锁报错，直接终止安装流程：

报错原文：✗ Installation failed: Submodule 'tinker-atropos' registered for pathGit merge 冲突：hermes_cli/setup.py 存在本地修改，导致 git pull 强制中止连锁问题：因为主线代码拉取失败，后续子模块自动更新流程直接断掉

一、通俗大白话讲明白两个问题

1. Git Merge 冲突 是什么？

打个形象比方：项目源码就像一份公共共用的文档，官方一直在线上更新改版。你本地这台电脑里，之前残留了旧文件、或是不小心改动了setup.py配置文件。当安装脚本自动执行git pull拉取最新代码时：Git 发现：本地文件 和 官方新版文件不一样它不知道该保留你的本地修改，还是直接覆盖成官方版本，不敢擅自操作，直接罢工卡住，拉代码流程直接终止。

简单总结：本地文件被改动 / 残留旧数据 → 和线上新版本对不上 → Git 两难，直接停止更新。

2. 子模块更新失败 是什么？

Hermes Agent 不是单一文件，是「主程序 + 多个依赖小模块」拼装起来的。tinker-atropos就是它依赖的一个外置子模块，相当于必备配件、核心零件。

正常安装逻辑：先更新主项目代码 → 再自动下载、拼装所有子模块配件。

现在问题是：第一步「主代码拉取」因为冲突已经卡死中断，后面下载配件、补全依赖的流程自然跑不了，属于前面崩了，后面全部连锁报废。

二、问题因果关系（一句话记住）

本地文件修改 → 引发 Git 合并冲突 → 代码拉取中断 → 子模块无法下载 → 安装整体失败

三、Windows 原生极简修复方案（可直接复制）

1. 清空本地改动，强制同步官方原版代码

git reset --hard origin/main git pull

1. 手动单独下载缺失的子模块，绕过自动脚本失败问题

git clone https://github.com/nousresearch/tinker-atropos tinker-atropos

1. 重建虚拟环境、安装依赖，继续正常部署

python -m venv .venv .venv\Scripts\Activate.ps1 pip install -r requirements.txt python main.py

四、后续避坑要点

1. Windows 装 AI 本地项目，不要随便手动改项目内部配置文件；
2. 重复安装、覆盖安装前，最好删掉旧文件夹，防止残留文件冲突；
3. 官方一键脚本容易受网络、子模块拉取限制，失败后手动分步部署最稳；
4. 全程纯 Windows 原生操作，坚决不用 WSL，避免环境混乱。