MiroFish 踩坑记录与解决方案

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 启动后端时不会进入该环境，导致命令找不到。

解决

• 后端单独启动（推荐）：

cd d:\deeplearning\mirrofish_test\MiroFish\backend
conda run -n mao_yolo python run.py

• 或使用 uv 完整路径：

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（最快）

cd d:\deeplearning\mirrofish_test\MiroFish\frontend
npm i -D @rollup/rollup-win32-x64-msvc
npm run dev

解决方案 B（更稳）

1. 切换到 Node 18/20 LTS
2. 删除依赖后重装

Remove-Item -Recurse -Force node_modules, package-lock.json
npm install

坑 3：一键 npm run dev 后端启动失败

原因

后端脚本调用 uv，但执行环境不在 Conda 环境中。

解决

建议前后端分开启动：

cd d:\deeplearning\mirrofish_test\MiroFish\backend
conda run -n mao_yolo python run.py

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。

示例

cd d:\deeplearning\mirrofish_test\MiroFish
python test_bailian_api_key.py

最小可用启动流程（Windows）

1. .env 填写 LLM_API_KEY/LLM_BASE_URL/LLM_MODEL_NAME/ZEP_API_KEY
2. 前端 npm install
3. 后端 conda run -n mao_yolo python -m uv sync
4. 后端 conda run -n mao_yolo python run.py
5. 前端 npm run dev