MiroFish 踩坑记录与解决方案
本文记录我在 Windows + Conda 环境下启动与调试 MiroFish 时遇到的问题和对应解决办法，便于快速复用与排查。
项目官网（仓库地址）：https://github.com/666ghj/MiroFish/tree/main
项目介绍
MiroFish 是一个基于多智能体技术的 AI 预测引擎，核心思路是从现实世界种子信息中构建高保真数字世界，驱动大量具备记忆与行为逻辑的智能体进行交互与演化，从而生成可解释的预测结果与报告，并支持与模拟世界进行深度互动。
环境说明
- 操作系统：Windows
- Python：Conda 环境（示例：
mao_yolo，Python 3.11） - Node.js：建议 18/20 LTS（Node 22 在 Windows 上容易触发 Rollup 可选依赖问题）
坑 1：uv 命令找不到
现象
'uv' 不是内部或外部命令，也不是可运行的程序原因
uv 安装在 Conda 环境中，但通过 npm run dev 启动后端时不会进入该环境，导致命令找不到。
解决
- 后端单独启动（推荐）：
powershell
cd d:\deeplearning\mirrofish_test\MiroFish\backend
conda run -n mao_yolo python run.py- 或使用
uv完整路径：
powershell
cd d:\deeplearning\mirrofish_test\MiroFish\backend
conda run -n mao_yolo python -m uv run python run.py坑 2：前端启动报 Rollup 原生包缺失
现象
Error: Cannot find module @rollup/rollup-win32-x64-msvc原因
Windows 下 npm 的可选依赖安装异常，导致 Rollup 原生模块未安装。
解决方案 A（最快）
powershell
cd d:\deeplearning\mirrofish_test\MiroFish\frontend
npm i -D @rollup/rollup-win32-x64-msvc
npm run dev解决方案 B（更稳）
- 切换到 Node 18/20 LTS
- 删除依赖后重装
powershell
Remove-Item -Recurse -Force node_modules, package-lock.json
npm install坑 3：一键 npm run dev 后端启动失败
原因
后端脚本调用 uv，但执行环境不在 Conda 环境中。
解决
建议前后端分开启动：
powershell
cd d:\deeplearning\mirrofish_test\MiroFish\backend
conda run -n mao_yolo python run.py
powershell
cd d:\deeplearning\mirrofish_test\MiroFish\frontend
npm run dev如需一键启动，可把 package.json 的 backend 脚本改为：
cd backend && conda run -n mao_yolo python -m uv run python run.py坑 4：API Key 测试与安全
建议
- 不要硬编码 API key，优先使用
.env配置。 - 测试脚本可用
test_api_key.py/test_bailian_api_key.py。
示例
powershell
cd d:\deeplearning\mirrofish_test\MiroFish
python test_bailian_api_key.py最小可用启动流程（Windows）
.env填写LLM_API_KEY/LLM_BASE_URL/LLM_MODEL_NAME/ZEP_API_KEY- 前端
npm install - 后端
conda run -n mao_yolo python -m uv sync - 后端
conda run -n mao_yolo python run.py - 前端
npm run dev