MiroFish 使用指南

一、平台介绍与核心功能

MiroFish 是一款基于多智能体（Multi-Agent）技术的 AI 预测与推演引擎。它通过注入现实世界的“种子信息”，在数字沙盘中构建成千上万个具备独立人格和长期记忆的智能体，模拟其交互与社会演化以推演未来趋势。

🌱 主要功能亮点

• 📝 种子材料解析支持上传数据分析报告、政策草案、突发新闻甚至小说故事等素材。
• 利用 GraphRAG（图谱检索增强）技术，自动构建底层知识图谱与记忆库。
• 🤖 社会仿真模拟自动生成智能体的人设及实体关系网络。
• 让大量智能体在数字世界中自由交互、协作或竞争进行推演。
• 🕹️ 动态干预（上帝视角）在模拟过程中，用户可随时注入新变量或突发事件。
• 精准观测群体行为涌现的连锁反应与蝴蝶效应。
• 📊 多维报告与深度互动模拟结束后由 ReportAgent 自动解析并生成详尽预测报告。
• 支持直接与数字世界中的任意智能体或报告助手进行对话交互。

二、适用人群与应用场景

MiroFish 适用于需要进行推演分析、内容创作及 AI 研究的各类角色：

• 🏛️ 决策者与公关团队应用场景： 政策出台前的影响模拟、社会热点与突发舆情事件的演化推演。
• 核心价值： 实现“零风险试错”，预判潜在舆论走向。
• 💹 金融与时政分析师应用场景： 基于宏观金融信号或时政要闻数据，推演市场走势与趋势变化。
• 核心价值： 辅助投资决策，识别系统性风险。
• 🖋️ 内容创作者与编剧应用场景： 导入小说前序章节（如示例中的《红楼梦》前 80 回）。
• 核心价值： AI 推演失传结局或生成新的脑洞故事线。
• 👨‍💻 AI 开发者与研究员应用场景： 探索多智能体协同机制、群体智能涌现现象及社会仿真学实验。

三、费用说明：开源免费 vs. 服务成本

项目本身完全开放，但运行所需的算力或 API 消耗需按需付费。

💰 软件授权

• 状态： ✅ 完全开源免费
• 模式： 允许直接获取源码本地部署或使用 Docker 容器化运行。

⚠️ 第三方服务成本（必须配置）

MiroFish 作为 AI 引擎，其核心能力依赖于外部大模型服务和记忆存储层

四、快速上手：源码部署指南

项目支持源码或 Docker 两种方式，推荐新手通过源码部署。请严格遵循以下步骤：

📋 步骤一：配置环境变量

这是最关键的初始化步骤。进入项目根目录后执行复制并重命名配置文件：

bash

cp .env.example .env
cp .env.example .env

编辑 .env 文件并填入必要参数（如 LLM API Key）：

• LLM_API_KEY: 阿里百炼或其他平台的 Token 密钥。
• ZEP_API_KEY: Zep Cloud 的记忆层接口密钥。

🔧 步骤二：一键安装依赖

环境要求： Node.js (v18+) | Python (3.11-3.12) | uv

在根目录下执行以下命令，自动完成所有虚拟环境及前端/后端的依赖安装：

bash

npm run setup:all
npm run setup:all

注：该命令将同时处理 python 后端与 node 前端的依赖库。

🚀 步骤三：启动服务并访问

在根目录下执行以下启动命令，确保前后端同步运行：

bash

npm run dev
npm run dev

控制台提示成功后，打开浏览器访问沙盘界面： 👉 http://localhost:3000

五、避坑指南

初次部署与使用 MiroFish 时，请务必注意以下关键问题：

⚡ Token 消耗预警

• 现象： 智能体密集交互会导致 LLM Token 飞速耗尽。
• 建议： 初次测试务必将模拟轮数控制在 40 轮以内。防止账户余额瞬间被刷空，后续可再逐步增加规模。

🐍 Python 版本锁死

• 现象： setup 命令或运行后端时直接报错。
• 原因： 依赖库对版本极其敏感，不兼容过新或过旧版本。
• 要求： 严格锁定在 Python >= 3.11 且 <= 3.12。
• ❌ 避免使用 Python 3.10（太老）或 Python 3.13/3.14+（可能缺失依赖）。

🐢 Docker 网络加速

• 现象： docker compose up -d 时长时间卡在拉取镜像阶段。
• 原因： 国内网络连接速度较慢。
• 解决： 记得修改 .env.yml 或 docker-compose.yml，启用官方提供的Gitee/Mirrors 加速镜像地址。