GitHub 7 万 Star 的 MiroFish 到底在做什么？把一群 AI 放进数字社会，看事情会怎样发展

GitHub 7 万 Star 的 MiroFish 到底在做什么把一群 AI 放进数字社会看事情会怎样发展我把 MiroFish 的中文 README、环境配置和后端几个关键文件对了一遍。仓库首页那句“简洁通用的群体智能引擎预测万物”确实很抓人。落到代码里它做的事情具体得多。它读入一份 PDF、Markdown 或 TXT 材料从中抽取人物、组织、事件和关系。随后系统为这些实体生成身份和行为参数把它们放进类似 Twitter 与 Reddit 的社交环境。一群 AI 角色开始发帖、关注、点赞、评论和转发。模拟结束后另一个报告智能体进入现场查询关系图也可以采访模拟角色最后整理成报告。这套思路很像给一件尚未发生的事排练几个版本。排练能够暴露传播路径和角色冲突无法把未来提前写死。截至2026 年 8 月 10 日MiroFish 的 GitHub 页面显示约7.08 万 Star。根目录package.json里的版本仍是0.1.0代码还在快速更新。本文按当前公开源码和官方文档来讲。我没有消耗真实 API 跑完一场完整仿真所以这是一篇源码解读和上手指南不会把官方演示写成我的亲测结果。 专栏介绍 《GitHub小白开源成长课》这个专栏写给计算机初学者、大学生和刚接触 AI 开源项目的读者。每篇文章挑一个值得动手的 GitHub 项目读源码查依赖也把费用、许可证和使用边界讲清楚。读完以后你至少能判断这个项目解决什么问题自己能不能跑以及下一步该从哪个文件学起。如果你正在从“会收藏项目”走向“能读懂项目”可以关注这个专栏。后面还会继续拆解多智能体、AI 漫剧和科研工具方向的开源项目。一、MiroFish 所说的“预测”究竟指什么日常说到预测人们很容易想到一个模型读完资料直接给出“会发生什么”。MiroFish 多做了一段过程。它把材料中的角色放进环境让角色互相影响然后观察局面如何变化。项目官方给出的用法覆盖舆情、政策草案、金融信号和小说故事。当前公开演示有两组材料。一组使用舆情报告进行热点事件推演另一组读入《红楼梦》前八十回推演失传结局。这两组案例放在一起很能说明问题。MiroFish 关心的输入是一批带关系的角色和事件。它既能处理现实材料也能把小说人物带进模拟环境。最终质量始终受输入材料约束。舆情报告漏掉一类人模拟世界里可能就少掉一种声音。小说文本对某个人物交代得很少生成的人设也会更依赖模型补全。因此我更愿意把它称作情景推演工具。它能帮助人查看“在这套材料和参数下事情可能怎样发展”。报告里出现的趋势仍需交叉验证尤其涉及投资、公共政策和现实人物时更要把它当作辅助材料。二、一段模型回答和一场群体推演差在哪里普通问答通常只有一条明显路径。用户给模型材料和问题模型生成回答。MiroFish 把中间过程展开了。模拟中的每个角色都有独立资料。源码里的 Agent Profile 可以保存姓名、简介、人格、职业、兴趣话题和影响力等信息。系统还会给角色安排活跃时间、发言频率、情感倾向和立场。角色进入环境后可以做的动作也很具体。Twitter 风格环境包含发帖、点赞、转发、关注和引用。Reddit 风格环境还加入评论、搜索、趋势查看、踩和静音等动作。角色也可以保持沉默。沉默很重要。现实中的人看到一条消息并不会人人表态。一个让所有 Agent 每轮都积极发言的模拟很快会变成模型集体抢麦。MiroFish 的配置里专门设计了活跃时段、响应延迟和每小时激活数量源码默认还考虑了早间、工作时段、晚间高峰和深夜低谷。所以群体推演留下的主要成果有两部分。一部分是报告另一部分是过程。谁先发言哪种观点得到更多互动哪些角色逐渐靠近事件加入以后传播方向有没有变化这些记录为后续判断提供了线索。三、一份材料怎样变成一场模拟官方 README 把流程分成五步。源码里还能看到每一步对应的 API 和服务。第一步 读取种子材料用户上传 PDF、Markdown 或纯文本文件再用自然语言说明自己想推演的问题。当前后端允许的单个上传请求上限为 50 MB。系统先解析文件并切分文本。默认切块大小是 500重叠部分是 50。随后LLM 根据文档生成本体结构决定材料中有哪些实体类型和关系类型。如果输入是一份校园舆情报告本体里可能出现学生、学校、媒体和事件等类型。这里的例子用于解释流程具体类型由模型根据实际材料生成。第二步 构建关系图文本切块和本体结构会进入 Zep Cloud。系统在图中保存实体、关系和上下文前端可以展示节点数、关系数和类型数。关系图给后面的 Agent 提供共同背景。某个角色和事件有什么联系他认识谁过去发生过什么都会影响人设和模拟中的行动。当前源码只接受 Zep Cloud 配置。Config.validate()会拒绝自定义的ZEP_API_URL。想把整套图谱服务完全放在本地需要自己改代码不能只换一行环境变量。第三步 生成人设和模拟参数MiroFish 会把图谱中的实体转换成 OASIS 需要的 Agent Profile。生成过程还会再次查询图谱为角色补充上下文。人设包含年龄、职业、兴趣和社交媒体资料。模拟配置则决定角色的活跃度、发言频率、响应速度、立场与影响力。时间配置会说明一次模拟跨越多少小时每轮代表多少分钟每小时激活多少角色。源码采用分批生成人设的办法每批默认处理 15 个 Agent。这样能降低单次输出过长带来的失败概率但总体模型调用量依然可能很大。第四步 在双平台中运行MiroFish 的仿真引擎由 CAMEL-AI 的 OASIS 驱动。OASIS 提供 Twitter 和 Reddit 风格的社交媒体环境。MiroFish 可以运行其中一个也可以并行运行两个。模拟按轮次推进。角色读取环境选择动作平台记录发帖和互动。系统还能把这些活动动态写回 Zep 图谱让后面的角色接触到已经发生的事。这一步最容易消耗 Token。Agent 数量增加、激活概率提高、模拟轮次变长调用量都会上升。MiroFish 的示例配置明确提醒新用户把首次尝试控制在 40 轮以内。第五步 生成报告并继续追问模拟结束以后ReportAgent 会先拟定报告结构再逐节查询环境。源码给它准备了四类主要工具可以做深度洞察、全景搜索、快速搜索也能采访模拟角色。生成报告之后用户还可以继续聊天。比如追问某一类角色为什么改变立场或者查找一条消息如何扩散。这个环节让报告从一份静态文本变成可继续调查的入口。四、拿《红楼梦》演示来走一遍官方演示使用《红楼梦》前八十回的数十万字文本推演失传结局。README 没有公开这次演示的全部参数和评估标准我们可以根据源码看懂大致过程不能据此复刻完全相同的结果。文件上传后模型先识别人物、事件和关系。关系图保存人物之间的联系也保留相关文本。系统接着为可参与模拟的实体生成人设把材料中的描述变成 Agent 可以使用的资料。用户输入的问题决定模拟方向。配置生成器据此安排初始事件、热点话题和定时事件也会设置角色的活动规律。人物进入社交环境后持续互动新的行动又会写回记忆。最后ReportAgent 查询模拟后的图谱和行动记录整理出一份结局推演。用户若对某个人物的决定有疑问还能继续采访对应 Agent。这个演示很好玩也把系统边界照得很清楚。模型识别错一段人物关系后面的互动会沿着错误继续走。人设生成时补入了原文没有的性格结局也会受影响。它适合帮助创作者探索分支不能替代文本考证。五、本地运行要准备哪些东西官方当前推荐源码部署。环境要求如下。项目要求Node.js18 及以上Python3.11 到 3.12uv最新可用版本LLM支持 OpenAI SDK 格式的 API图谱记忆Zep Cloud API Key根目录示例默认使用qwen-plus也可以换成兼容 OpenAI SDK 格式的模型服务。能正常聊天还不够模型还要稳定输出结构化内容。便宜模型如果频繁生成坏 JSON省下来的调用费可能会变成排错时间。源码部署先克隆项目。gitclone https://github.com/666ghj/MiroFish.gitcdMiroFish复制环境变量文件。Linux、macOS 和 Git Bash 可以执行下面的命令。cp.env.example .envWindows PowerShell 可以使用这一条。Copy-Item.env.example.env打开.env填入模型和 Zep Cloud 配置。LLM_API_KEYyour_api_key LLM_BASE_URLhttps://your-compatible-endpoint/v1 LLM_MODEL_NAMEyour_model_name ZEP_API_KEYyour_zep_api_key安装所有依赖。npmrun setup:all启动前端和后端。npmrun dev浏览器打开http://localhost:3000。后端 API 使用http://localhost:5001。Docker 部署配置好同一份.env后也可以直接启动官方镜像。dockercompose up-ddocker-compose.yml会映射 3000 和 5001 两个端口并把backend/uploads挂载出来保存上传与模拟数据。跑通以后应该看到什么前端把整个过程分成工作台步骤。图谱阶段会显示生成的实体类型、关系类型和节点统计。环境阶段可以查看 Agent 人设、模拟时长和每轮配置。运行页面会持续更新双平台进度和行动数量。最后进入报告和互动页面。第一次尝试可以用一份短的公开材料问题也写得具体一些。模拟轮数控制得少一点。这样一旦失败你能看出故障出在文件解析、图谱构建、人设生成还是仿真运行。六、它会花多少钱MiroFish 没有给出一张固定价格表因为费用来自你选择的 LLM、Agent 数量和模拟轮次。底层 OASIS 的官方说明也提醒Token 使用量会随 Agent 数量、激活概率和时间步增长。一次模拟里LLM 要参与本体生成、人设生成、配置生成、角色行动和报告撰写。Agent 多起来以后每一轮又会激活其中一部分。普通聊天按一次问答计费的直觉在这里很容易低估开销。我会给小白一个很朴素的起步办法。先用公开短文不要一上来上传几十万字。减少角色数量观察生成的人设是否正常。先跑少量轮次确认行动日志能持续产生。看完报告再加规模记录每次调用费用。项目 README 已经给了“小于 40 轮”的提醒。这个数字适合当上限提示首次排错还可以更短。七、预测报告该信到什么程度一场模拟至少经过材料解析、关系抽取、人设生成、环境互动和报告归纳。每一层都会把自己的误差带到下一层。种子材料决定系统能看到什么。LLM 决定它怎样理解材料。人设和参数决定角色怎样行动。Twitter 与 Reddit 风格环境又会限制角色能够做的事。ReportAgent 最后只能分析模拟世界里已经留下的记录。因此同一份材料换一个模型、换一组参数或多跑几次结果可能不同。这种差异本身也有用。你可以比较哪些趋势在多次模拟中反复出现哪些结论只依赖某个人设或某次随机过程。现实决策还需要现实证据。金融预测要回到数据和风险控制舆情研究要验证样本与人群政策评估要经过领域专家和真实反馈。MiroFish 提供了一种观察复杂互动的办法它不会替这些工作签字。八、隐私和许可证也要提前看MiroFish 需要外部 LLM API 和 Zep Cloud。你上传的材料会进入相关处理流程。涉及未公开论文、企业资料、个人信息或内部舆情数据时应先查看模型服务商与 Zep 的数据政策也可以先做脱敏。项目使用AGPL-3.0。个人在本地学习和修改可以按许可证使用。若把修改后的版本作为网络服务提供给用户AGPL 通常要求向这些用户提供相应源码。准备商用、二次发布或提供在线服务时应该认真阅读仓库中的LICENSE必要时咨询专业人士。还有一件小事容易被忽略。.env里放着模型和 Zep 的密钥不要把它提交到 GitHub。仓库已经提供.gitignore提交前仍要看一眼git status。九、这个项目适合哪些初学者想学习多智能体系统的人很适合读 MiroFish。它把文档解析、知识图谱、Agent 人设、社会仿真和报告生成接成了一套完整流程比单独看概念更容易建立整体认识。想做 AI 漫剧或互动故事的人也能从中得到启发。人物关系可以进入图谱角色拥有独立记忆事件可以按时间加入。把 Twitter 与 Reddit 环境换成剧情场景以后这套结构很接近多人角色共同推进故事的系统。科研新手可以把它当作一个多智能体应用样本。前端使用 Vue 3、Vite 和 D3后端使用 Flask图谱记忆依赖 Zep Cloud仿真部分由 OASIS 驱动。项目把各层分得比较清楚顺着backend/app/services目录读下去能看到图谱、人设、配置、运行和报告各自怎样实现。只想点一下就得到可靠预测的人可能会失望。安装需要两类 API运行会产生费用结果还要继续验证。它更适合愿意看过程、改参数并承担判断责任的人。十、我最建议小白读的几个文件文件能学到什么README-ZH.md完整使用流程和环境要求.env.example外部服务和模型配置backend/app/config.py文件限制、模拟动作和默认参数ontology_generator.py怎样从材料生成实体与关系类型oasis_profile_generator.py怎样把图谱实体变成 Agent 人设simulation_config_generator.py怎样生成时间、事件和角色配置simulation_runner.pyTwitter 与 Reddit 仿真怎样运行report_agent.py报告智能体怎样查图谱和采访角色frontend/src/components五步工作台怎样呈现给用户第一次读这种项目不必从最大文件的第一行啃到最后一行。先打开config.py看系统有哪些能力再沿着 README 的五步流程找对应服务。读到一个类时问它接收什么又把结果交给谁。项目的脉络会慢慢显出来。十一、我会怎样开始第一次尝试我会选一篇自己熟悉的公开短文把模拟问题收窄只跑几轮。报告出来以后先不急着看它押中了什么。我会回到种子材料逐条检查人物关系有没有抽错人设里添了哪些原文没有的信息再看哪种结论随着这些补充出现。这一步做完MiroFish 才从一个热闹的演示变成可以分析的工具。至于“预测万物”我愿意把它当作项目的远方。眼下这份代码已经提供了一个能动手、能观察、也能继续改的数字社会实验台。如果这篇文章帮你看懂了 MiroFish欢迎点赞、收藏并关注《GitHub小白开源成长课》。下一篇我还会继续找适合初学者的多智能体或 AI 创作项目边使用边把踩坑过程写出来。参考资料MiroFish GitHub 仓库MiroFish 中文说明MiroFish 环境配置示例MiroFish AGPL-3.0 许可证OASIS GitHub 仓库Zep 官方文档本文配图均为根据项目流程制作的原创示意图不属于 MiroFish 官方界面截图。项目状态、Star 数和配置核对时间为 2026 年 8 月 10 日。GitHubMiroFish多智能体群体智能AI Agent开源项目人工智能