MiroFish 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

MiroFish 是一个使用 Python 编写的群体智能引擎，项目定位是“简洁通用的群体智能引擎，预测万物”。根据仓库资料，它通过种子材料、实体关系、角色设定和多智能体交互构建平行数字世界，并在模拟完成后生成预测报告。

仓库默认分支为 main，许可证为 AGPL-3.0。GitHub 元信息显示该项目有 71096 个 Star 和 11059 个 Fork；这些数值属于仓库资料提供时的快照，不代表后续实时数据。源码部署要求 Node.js 18 及以上、Python 3.11 至 3.12、uv，以及可用的兼容 OpenAI SDK 格式的模型接口和 Zep Cloud 配置。

定位与目标用户

本项目的核心价值不在于提供单次文本生成，而在于把输入材料转化为可交互的多智能体模拟环境。读者可以用它处理公共舆论、政策草案、金融信号等现实材料，也可以将小说文本或其他设定材料作为模拟起点。

README 将目标场景分为宏观决策和微观创作两类：宏观层面用于在低风险环境中演练政策与公共关系方案，微观层面用于推演故事结局和想象性场景。这里的“预测”应理解为基于输入材料、角色设定和模拟过程生成的推演结果，而不是经过独立验证的事实结论。

输入与输出边界

• 输入：种子材料，以及用自然语言描述的预测要求。README 举例包括数据分析报告和小说故事材料。
• 处理中间结果：种子信息抽取、集体或个体记忆注入、关系图谱构建、实体关系抽取、角色生成和智能体配置。
• 输出：预测报告、模拟后的数字世界，以及与其中智能体和 ReportAgent 进行深度交互的能力。
• 不应推断：资料没有给出预测准确率、校准方法、置信区间、成功率、SLA 或固定规模下的资源消耗。

核心功能

README 将 MiroFish 的工作过程划分为图谱构建、环境设置、模拟、报告生成和深度交互五个阶段。每个阶段都承担不同的数据转换职责，实际运行还依赖模型 API 与 Zep Cloud 记忆图谱配置。

种子材料抽取与 GraphRAG 构建

系统首先从现实材料中提取种子信息，再注入个体记忆和集体记忆，最后构建 GraphRAG（图检索增强生成，Graph Retrieval-Augmented Generation）结构。触发条件是用户提交材料并提出预测需求；输入是报告、新闻、政策草案、金融信号或故事文本，输出是供后续环境设置使用的关系与记忆基础。

资料没有提供图谱节点类型、边类型、切分策略、召回算法或图数据库实现细节，因此不能据此断言其内部采用了某一种固定图数据库或索引方案。README 明确提到 Zep Cloud 配置，环境变量章节则要求提供 ZEP_API_KEY。

实体关系抽取与角色生成

环境设置阶段从种子信息中抽取实体关系，并据此生成角色设定，再注入智能体配置。角色生成的结果服务于后续独立智能体运行；README 对智能体的描述包括独立人格、长期记忆和行为逻辑，但没有给出角色模板格式、字段定义或人工审核界面。

这一阶段的输入是图谱构建结果和相关记忆，输出是用于模拟的实体、关系、角色和智能体配置。所需模型类型、调用次数及配置粒度未在给定资料中公开，部署者应以仓库最新 README 和实际配置文件为准。

双平台并行模拟与动态记忆

模拟阶段包含“双平台并行模拟”、自动解析预测要求以及动态时间记忆更新。用户提交自然语言预测要求后，系统会将需求转化为模拟所需的运行目标，智能体在环境中交互并持续更新时间相关记忆。

README 没有解释“双平台”的具体平台名称、进程模型、消息协议或并行度参数，也没有公布“数千个智能体”对应的最低硬件条件。文章只保留仓库明确给出的能力描述，不将其转化为性能承诺。

报告生成与深度交互

模拟结束后，ReportAgent 使用工具集与模拟环境进行深度交互，并生成详细预测报告。该输出适合作为分析材料或方案讨论输入，但仓库资料没有提供报告 schema、导出格式、引用链、可重复运行标识或自动事实核验机制。

深度交互阶段允许用户与模拟世界中的任意智能体对话，也允许用户与 ReportAgent 交互。其前提是前面的环境已经成功构建并完成模拟；具体前端入口、后端接口签名和鉴权方式，官方仓库未提供该信息，建议以最新 README 为准。

系统架构与关键模块

从仓库根目录的脚本、Docker 配置和 README 可以确认，MiroFish 采用前后端分离的运行形态，并通过根目录脚本协同启动。资料没有提供完整目录树和模块级依赖图，因此下面只描述已被文件或 README 明确支持的边界。

前端与后端

根目录 package.json 通过 npm run frontend 进入 frontend 目录并执行前端开发命令，通过 npm run backend 进入 backend 目录并使用 uv run python run.py 启动后端。npm run dev 使用 concurrently 同时启动两项服务，并设置为任一进程结束时终止其他进程。

README 给出的本地服务地址是前端 http://localhost:3000、后端 API http://localhost:5001。资料没有说明前端框架、后端 Web 框架、API 路由、数据库或认证组件，因此不应从端口推导具体实现。

依赖与脚本编排

根目录脚本将 Node.js 依赖安装与 Python 依赖安装分开管理：npm run setup 安装根目录和前端 Node 依赖，npm run setup:backend 在 backend 中执行 uv sync，npm run setup:all 顺序组合两者。

Dockerfile 使用 Python 3.11 基础镜像，安装 Node.js 与 npm，并从 uv 官方镜像复制 uv 和 uvx。镜像构建阶段读取根目录及前端的 npm 锁定文件、后端的 pyproject.toml 和 uv.lock，然后复制项目源码。

容器运行边界

docker-compose.yml 使用 ghcr.io/666ghj/mirofish:latest 镜像，映射前端 3000 和后端 5001 端口，并将根目录的 ./backend/uploads 挂载到容器内的 /app/backend/uploads。Compose 服务名和容器名均为 mirofish。

Dockerfile 的启动命令是 npm run dev，注释明确说明该方式以开发模式同时运行前后端。生产环境是否应采用其他进程模型、反向代理或静态资源托管方式，官方仓库未提供该信息，建议以最新 README 为准。

依赖与运行环境

源码部署的最低环境约束已在 README 中列出，版本范围不能随意替换为资料之外的版本。部署前应分别检查 Node.js、Python 和 uv 是否可执行，再准备模型服务与 Zep Cloud 凭据。

README 推荐使用阿里百炼平台的 Qwen-plus 模型，并给出了兼容 OpenAI SDK 格式的 Base URL。推荐项不等于项目唯一兼容项；资料明确写明，LLM API 支持任意符合该 SDK 格式的接口。

快速开始

下面的流程覆盖安装、配置、启动和本地验证四个环节，适用于本地测试环境。命令均来自仓库 README 或根目录脚本；敏感字段使用占位符，不能把占位符直接当作真实凭据提交。

步骤一：准备源码与环境文件

cp .env.example .env
node -v
python --version
uv --version

执行第一条命令会从示例文件创建本地配置文件。随后三个版本检查命令用于确认命令行工具可用；README 给出的约束是 Node.js 18+、Python ≥3.11 且 ≤3.12、uv 为 Latest。

步骤二：填写最小配置并安装依赖

# 编辑 .env，填写 LLM_API_KEY 与 ZEP_API_KEY
npm run setup:all

npm run setup:all 会依次执行根目录及前端的 npm 安装，以及后端的 uv sync。配置文件至少需要可用的 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL_NAME 和 ZEP_API_KEY；占位值 your_api_key_here 不能用于实际调用。

步骤三：启动并验证

npm run dev

# 浏览器验证地址
# http://localhost:3000
# 后端 API 地址
# http://localhost:5001

启动命令会并行运行前端和后端。最小验证闭环是确认前端地址能够打开，并检查后端 API 地址是否已经监听；仓库资料没有给出健康检查路径，因此不能把某个未记录的 /health 地址写入验证步骤。

Docker 方式

cp .env.example .env
docker compose up -d

该方式使用 Compose 文件中的镜像和端口映射。运行前仍需填写根目录 .env，容器会读取该文件中的模型和 Zep Cloud 配置；上传目录通过卷挂载保留在宿主机的 ./backend/uploads。

配置说明

配置项集中在根目录的 .env 文件中，示例由 .env.example 提供。下表严格保留资料中的字段名和示例默认值；“默认值”列中的占位符表示示例文件内容，不代表有效密钥。

必需配置与可选配置

README 将 LLM API 配置和 Zep Cloud 配置列为必需环境变量。加速 LLM 配置是可选项，但示例文件特别说明：如果不使用加速配置，.env 中不要出现这些配置项，而不是保留示例占位值。

LLM_BASE_URL 与 LLM_MODEL_NAME 应与所选服务的实际兼容接口和模型名称一致。项目没有在给定资料中提供超时、重试、并发、成本上限或模型参数字段，不能额外假设这些字段可用。

进阶用法

进阶使用的重点是改变输入材料、预测问题和模拟轮数，而不是修改未公开的接口。README 明确建议由于消耗较大，可先进行少于 40 轮的模拟；该表述是使用建议，不是性能基准或固定上限。

按场景准备种子材料

• 公共舆论推演：使用已有的舆论报告或相关事件材料，明确要观察的传播、态度或反应问题。
• 政策方案演练：输入政策草案或分析材料，将待比较的变量写入自然语言预测要求。
• 故事结局推演：输入小说文本或章节材料，描述需要推演的角色关系和结局问题。
• 金融信号分析：README 将金融信号列为种子信息示例，但没有给出数据接入器、行情接口或金融指标格式。

材料越长、角色越多、模拟轮数越高，模型调用与记忆处理的范围就会扩大；这是根据系统工作流对处理链条的直接判断，不应当被解释为仓库已经公布的容量结论。具体的输入大小限制、单次任务时长和费用计算规则，官方仓库未提供该信息。

从独立服务启动

调试前后端时，可以拆开运行两个服务。根目录脚本提供 npm run backend 和 npm run frontend，分别进入对应目录启动服务；这适合定位依赖安装、模型调用或界面问题，但两项服务之间的通信协议仍需以源码为准。

npm run backend
npm run frontend

可观测性与运维

给定资料只确认了服务启动方式、端口、容器重启策略和上传目录挂载，没有提供日志格式、指标名称、链路追踪、健康检查、告警规则或备份方案。运维设计因此应把这些内容作为部署前的待确认项，而不是从项目资料中补写成既有能力。

本地与容器检查清单

• 检查 http://localhost:3000 是否可以访问前端。
• 检查 http://localhost:5001 是否有后端服务响应；具体响应路径和格式未在资料中说明。
• 确认 .env 已被服务读取，并且模型密钥和 Zep Cloud 密钥不是示例占位值。
• 使用 Docker 时，检查 Compose 是否映射了 3000:3000 和 5001:5001，以及上传目录是否正确挂载。
• 保留模拟输入、轮数、模型配置和生成报告，便于在同一环境下复核结果；该复核要求是根据本文作者的经验判断，仓库没有提供自动实验记录功能说明。

资源与成本管理

README 只提醒推荐的 Qwen-plus 配置消耗较大，并建议先使用少于 40 轮的模拟。资料没有给出 token 预算、并发限制、单轮调用数量或费用估算器，因此部署者需要在授权的模型服务侧查看实际用量，并在测试环境控制任务规模。

安全与合规边界

MiroFish 的输入可以包含新闻、政策、金融信号、公共舆论报告和小说材料，其中现实材料可能携带个人信息、内部信息或受版权保护的内容。使用者应仅处理已获得授权的数据，并在上传到模型服务或 Zep Cloud 前完成数据分类、脱敏和访问控制。

项目资料没有声明数据保留期限、加密方式、租户隔离、权限模型、审计日志或第三方服务的数据处理地域。部署前应向组织的隐私、法务和安全负责人确认模型服务与 Zep Cloud 的使用边界，不能因为代码采用开源许可证就推断数据处理自动合规。

授权环境与隔离要求

• 公共舆论和政策材料应确认来源合法，并避免将未经授权的个人身份信息直接上传。
• 金融、政治和公共事件推演结果应标注为模拟分析，不应直接替代专业审核、法律意见或正式决策流程。
• 测试时使用独立的 API 密钥和隔离环境，不把真实生产凭据写入 Git 仓库、镜像层或公开日志。
• 通过容器部署时，应限制宿主机上传目录的访问权限，并审查需要暴露的端口。
• 不要把系统用于未授权目标的数据收集、操纵舆论、账号自动化或规避平台检测；本文不提供此类用法。

上述边界是对模型调用、上传材料和模拟决策场景的合规约束说明。官方仓库未提供针对特定行业的认证、合规声明或安全审计报告，相关结论应以组织自身审核和仓库最新声明为准。

许可证与商用条款

仓库许可证为 GNU Affero General Public License（GNU Affero 通用公共许可证，AGPL）第 3 版，许可证文件标注版本日期为 2007 年 11 月 19 日。AGPL-3.0 是自由软件许可证，许可证文本没有以“非商业使用”作为授权条件，因此在遵守许可证要求和其他适用法律的前提下，商业使用并非被许可证名称直接排除。

但商用并不意味着可以闭源保留所有修改。LICENSE 说明，AGPL 专门针对网络服务器软件：如果运营者在服务器上运行修改版本并向公众提供使用，应按照许可证要求向相关用户提供该修改版本的源代码；具体触发条件、对应源码范围、通知义务和分发条件均以仓库 LICENSE 为准。

分发与界面义务

LICENSE 还规定了版权声明、许可证文本、对应源代码和交互式用户界面法律声明等相关要求。本文不对某种 SaaS、内部部署、插件组合或二次分发模式作确定法律结论；计划商用、改造或再分发时，应由法务依据完整许可证文本审查，并保留原项目版权与许可证信息。

项目依赖和外部模型服务还可能具有独立条款。AGPL 只说明 MiroFish 项目本身的授权边界，不能替代模型供应商、Zep Cloud、输入材料版权方或数据保护法规的要求。

局限性与已知限制

资料清楚描述了工作流，但没有提供可复现实验数据，因此无法据此评价预测质量。系统输出依赖种子材料、角色生成、模型响应和记忆更新过程，结果应接受人工复核，而不是直接当作现实事件的确定性预测。

• 没有公开准确率、召回率、校准指标、基线对比或独立评测集。
• 没有公开单机硬件要求、最大智能体数量、最大输入长度、并行度和任务耗时。
• 没有公开 API 文档、请求签名、错误码、鉴权方案和版本化接口承诺。
• 没有在给定资料中说明模型调用失败、Zep Cloud 不可用或部分模拟中断时的恢复策略。
• Dockerfile 启动命令采用开发模式，生产部署的进程治理和安全加固方案未提供。
• 项目的实时 Star、Fork、依赖漏洞状态和维护响应时间没有在资料中给出。

如果部署需求包含严格的可重复性、审计性或确定性结果，应先检查源码和最新文档是否补充了实验记录、随机性控制、数据版本和报告引用能力。官方仓库未提供该信息，建议以最新 README 为准。

适合谁

下列信号表明 MiroFish 与需求匹配度较高，判断依据来自仓库已公开的工作流和部署方式，而不是未公布的性能承诺。

• 团队已有 Python 3.11 至 3.12、Node.js 18+ 和 uv 环境，并能维护前后端同时运行的本地或容器化服务。
• 需求需要把一批材料转化为角色、关系和交互过程，而不仅是对单份文本进行一次问答。
• 团队可以提供符合 OpenAI SDK 格式的 LLM API，以及 Zep Cloud API Key，并能承担相关调用费用。
• 使用者接受“模拟推演加人工审阅”的工作方式，能够记录输入材料、预测要求和输出报告。
• 场景属于公共舆论、政策演练、故事结局或其他授权的假设性分析，不要求仓库已经提供行业级 SLA 或验证后的预测准确率。

不适合谁

以下信号意味着需要谨慎评估，或者应先选择已经满足相应约束的替代系统；仓库资料没有列出具体替代产品，因此本文不指定某个替代方案。

• 团队只能使用低于 Python 3.11 或低于 Node.js 18 的固定运行环境，且无法调整基础设施。
• 数据不能离开内网，或者组织禁止将材料发送给外部 LLM API 与 Zep Cloud。
• 业务要求可证明的预测准确率、审计日志、数据保留策略、细粒度权限和服务级别承诺，而这些内容在资料中未公开。
• 任务要求高并发、严格实时响应或已知的最大智能体规模，但项目没有给出对应 Benchmark、容量上限或并发配置。
• 使用者希望获得无需人工核验的政策、金融、法律或公共事件结论，或者希望将模拟报告直接作为正式决策依据。

常见问题与排查（FAQ / Troubleshooting）

排查应先区分环境、配置、外部服务和应用流程四类问题。仓库给出了安装脚本和端口，但没有给出完整错误码，因此遇到未记录错误时应保留原始日志并对照最新 README。

为什么执行 npm run setup:all 失败

先确认 Node.js 满足 18+，Python 满足 ≥3.11 且 ≤3.12，并确认 uv --version 可执行。该脚本会安装根目录、前端和后端依赖；网络访问、锁文件冲突或本地权限错误的具体处理方式，官方仓库未提供该信息。

前端可以打开，但模拟无法运行

检查 .env 中的 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL_NAME 和 ZEP_API_KEY 是否已填写真实值，并核对模型服务是否接受 OpenAI SDK 格式请求。若配置无误仍失败，应分别检查后端 http://localhost:5001 是否启动，以及 Zep Cloud 和模型服务的调用日志。

是否必须使用 qwen-plus

不是。README 推荐阿里百炼平台的 Qwen-plus，并给出对应 Base URL；同时明确支持任意 OpenAI SDK 格式的 LLM API。替换模型时应同步修改 LLM_BASE_URL、LLM_MODEL_NAME 和密钥，并自行确认兼容性。

是否可以只启动后端或前端

可以，根目录脚本提供 npm run backend 和 npm run frontend。但单独启动一侧不能代表完整功能链路已经可用，完整界面和模拟流程仍需要前后端及外部模型、记忆服务配置共同工作。

Docker 容器重启后上传文件是否保留

Compose 文件将 ./backend/uploads 挂载到 /app/backend/uploads，因此该路径具备宿主机卷映射。资料没有说明其他运行状态、缓存、报告或外部记忆是否持久化，不能据此推断全部任务状态都能恢复。

项目地址与资源

以下链接均出现在仓库资料、README 或项目元信息中。外部服务的账号、配额和数据条款应以对应站点的最新页面为准。

• MiroFish GitHub 仓库
• MiroFish 官网与文档
• MiroFish 在线演示环境
• 阿里百炼平台
• Zep Cloud 控制台
• 盛大官网
• 武汉大学舆情模拟演示视频
• 《红楼梦》佚失结局模拟演示视频
• MiroFish Discord 社区
• MiroFish X 账号
• MiroFish Instagram 账号

参考说明与事实范围

本文关于工作流、环境变量、端口、脚本、Docker 映射和许可证的事实，分别依据 README.md、package.json、Dockerfile、docker-compose.yml、.env.example、LICENSE 以及用户提供的 GitHub 元信息整理。未在这些资料中出现的接口、性能、目录细节和运维能力均明确保留为未知。

“A Simple and Universal Swarm Intelligence Engine, Predicting Anything”
来源：README

项目名称中的“预测万物”是 README 的项目定位语句，不应被解读为对任何领域准确性的承诺。实际部署时，应以源码、完整许可证文本和最新 README 的变化为准。