未来预测！对 MiroFish 项目的系统性深度拆解

使用 LLM，根据系统提示 ONTOLOGY_SYSTEM_PROMPT，强约束输出结构：
- 实体类型（entity_types）：
  - 必须恰好 10 个
  - 其中最后两个是兜底类型：Person、Organization
  - 前 8 个根据具体语料自动设计（如 Student、Professor、Company、MediaOutlet 等），要求有清晰的边界定义和英文描述
- 关系类型（edge_types）：
  - 6–10 个
  - 名称采用 UPPER_SNAKE_CASE（例如：WORKS_FOR、COMMENTS_ON、SUPPORTS、OPPOSES 等）
  - 每个关系有 source_targets 约束，用来限定实体类型组合（比如 Student → University）
- 属性设计约束：
  - 每个实体 1–3 个关键属性
  - 禁用保留字段（如 name、uuid、group_id、created_at、summary），避免和系统字段冲突
生成结果是一个 JSON，本身用于：
- 作为 Zep 图谱的 schema
- 动态生成内部 EntityModel / EdgeModel Python 类（通过字符串拼接代码）

前端体验： Step1GraphBuild.vue 中：

调用 POST /api/graph/ontology/generate：上传文件 + simulation_requirement + 可选 project_name、additional_context。
实时显示“正在分析文档…”等进度信息（ontologyProgress）。
以标签形式展示：
- projectData.ontology.entity_types（实体类型）
- projectData.ontology.edge_types（关系类型）
点击某个实体/关系标签，会弹出详情浮层：
- 描述（description）
- 属性列表（attributes）
- 示例实体（examples）
- 对于关系，还展示 source_targets（哪类实体与哪类实体之间的关系）

价值：

和直接“无 schema 地用 RAG”不同，MiroFish先通过一个域内专用 schema，把“谁在场”“谁能在社交平台发声”这件事设计得非常严谨，这一步为之后的多智能体模拟打下了结构化语义基础。

2）图谱构建（GraphRAG with Zep）

由 GraphBuilderService 负责（backend/app/services/graph_builder.py）：

关键流程（异步）：

创建构图任务 TaskManager.create_task(type="graph_build")，前端可以轮询任务进度。
create_graph(graph_name)：通过 Zep API 创建一个新的图谱。
set_ontology(graph_id, ontology)：把上一步生成的 ontology 装载到 Zep。
文本分块：
1. chunk_size = 500，chunk_overlap = 50：避免语义被粗暴截断。
2. 得到多个 chunks。
分批添加文本：
1. batch_size = 3：三块一批写入 Zep，防止一次性太大。
2. 通过内部回调，实时更新任务进度（约 20–60% 区间）。
调用 _wait_for_episodes：等待 Zep 对所有 episodes 处理完毕（60–90%）。
最后从 Zep 拉取：
1. 所有节点 nodes
2. 所有边 edges 并将其整合为：

{
  "graph_id": "...",
  "nodes": [...],
  "edges": [...],
  "node_count": N,
  "edge_count": M
}

Graph API (backend/app/api/graph.py) 还提供：

GET /api/graph/data/<graph_id>：获取图谱数据（节点+边）
DELETE /api/graph/delete/<graph_id>：删除图谱
Project 级别管理（创建、列表、删除、重置）

前端体验：同样在 Step1GraphBuild.vue 中：

POST /api/graph/build：发起构图
展示统计卡片：
- graphStats.nodes：实体节点数
- graphStats.edges：关系边数
- graphStats.types：SCHEMA 类型数
结合本体信息，用户可以看到“这个数字世界里有多少个真实主体，关系类型分布是什么样”。

Step 02：环境搭建（Env Setup – Agent Profiles + Simulation Config）

这一部分由 Step2EnvSetup.vue + 若干服务类完成：

1）代理人设生成（Agent Profile Generation）

由 OasisProfileGenerator + SimulationManager 组成（服务侧实现大致可推断）：

从 Zep 图谱中抽取“可发声主体”（只保留本体中允许作为社交账号的实体类型）。
结合本体的属性和关系，生成每个 Agent 的：
- username / name
- profession（职业）
- bio（简介）
- interested_topics（感兴趣的话题列表）

前端（Step2EnvSetup.vue）展示：

已生成 Agent 数量：profiles.length
预期总 Agent 数：expectedTotal
现实种子关联话题数：totalTopicsCount
Agent 列表 preview（可点击查看/选择某个代理）：
- 显示姓名、昵称、职业、简介、前三个关注话题等

2）模拟配置生成（Simulation Config Generation）

依托 simulation_config_generator.py，结合用户的 simulation_requirement 和当前图谱信息，由 LLM 自动生成完整模拟参数，写入 simulation_config.json：

time_config：
- total_simulation_hours（总模拟时长）
- minutes_per_round（每轮时长）
- 计算总轮数：total_hours * 60 / minutes_per_round
- agents_per_hour_min / agents_per_hour_max（每小时最大活跃代理数）
- peak_hours（高峰时段）
- peak_activity_multiplier（峰值放大倍数）

SimulationManager（backend/app/services/simulation_manager.py）负责：

管理每个 simulation 的状态 SimulationState：
- status：CREATED, PREPARING, READY, RUNNING, COMPLETED 等
- entity_types，entities_count，profiles_count 等
把 simulation 的所有文件落盘：
- simulation_config.json
- {platform}_profiles.json
- state.json（simulation state）
提供 get_run_instructions(simulation_id)：
- 返回脚本路径 scripts/ 和运行命令：
  - 单平台：run_twitter_simulation.py / run_reddit_simulation.py
  - 并行：run_parallel_simulation.py

前端体验：

Step 02 卡片中，第二小步是：
- Step 02：生成 Agent 人设（POST /api/simulation/prepare）
- Step 03：生成双平台模拟配置（同一 API，只是流程向前推进）
动态显示生成进度 prepareProgress 和配置 preview。

Step 03：模拟运行（Simulation – OASIS Engine）

执行核心在 simulation_runner.py（backend/app/services/simulation_runner.py），背后的环境由 OASIS 引擎(camel-oasis) 提供。

1）运行状态建模

SimulationRunState 记录单次模拟的完整运行时态：

整体信息：
- simulation_id
- runner_status（IDLE / STARTING / RUNNING / COMPLETED / FAILED 等）
- current_round / total_rounds
- simulated_hours / total_simulation_hours
平台维度状态：
- Twitter：
  - twitter_running, twitter_completed
  - twitter_current_round, twitter_simulated_hours
  - twitter_actions_count
- Reddit：
  - reddit_running, reddit_completed
  - reddit_current_round, reddit_simulated_hours
  - reddit_actions_count
最近动作队列：
- recent_actions（默认保留最新 50 条）
每轮摘要 RoundSummary：
- 每轮的开始/结束时间、模拟小时数
- action 计数，不同平台区分
- 当轮所有 AgentAction 列表

前端 Step3Simulation.vue 中就直接绑定了这些字段：

左上两个“平台卡片”：
- Twitter = “Info Plaza”，Reddit = “Topic Community”
- 实时显示：
  - ROUND: current_round / total_rounds
  - Elapsed Time
  - ACTS: actions_count
- 可用动作列表（平台动作空间）：
  - Twitter：POST, LIKE, REPOST, QUOTE, FOLLOW, IDLE
  - Reddit：POST, COMMENT, LIKE, DISLIKE, SEARCH, TREND, FOLLOW, MUTE, REFRESH, IDLE

2）时间线式事件流展示

前端通过 allActions + chronologicalActions 构造一条跨平台统一时间线：

每个动作卡片 timeline-card 显示：
- Agent 名称、平台图标（Twitter 或 Reddit）
- 动作类型（badge 显示，样式由 getActionTypeClass 控制）
- 如为 CREATE_POST 且有 action_args.content，则展示帖子正文
最顶部有统计栏：
- TOTAL EVENTS: allActions.length
- 各平台事件分布占比

这样的 UI 帮助使用者从“上帝视角”查看整个世界在某个时间窗内发生了什么，非常利于肉眼理解复杂演化。

3）控制与关闭环境

simulation.py 提供了一些控制 API，例如：

POST /api/simulation/close-env：
- 请求包含 simulation_id 和可选 timeout
- 调用 SimulationRunner.close_simulation_env，并将 simulation 状态标记为 COMPLETED

同时支持从本地 db（{platform}_simulation.db）中读取“interview history”，用于之后的“访谈”功能（Step 05）。

Step 04：报告生成（Report Generation – ReACT Agent）

由 ReportAgent + ReportLogger + report.py 组合完成。

1）整体流程（后端）

API：POST /api/report/generate

核心流程：

校验：
1. 必须有 simulation_id
2. 对应的 simulation 必须存在
3. 找到关联 project，确保有 graph_id 和 simulation_requirement
若已存在完成状态的报告，且未指定 force_regenerate=true，则直接返回现有报告的元数据（避免重复消耗 LLM 调用）。
创建 report_id（如 report_<uuid>），并创建一个异步任务（TaskManager.create_task(type="report_generate")）。
在线程中执行 run_generate()：
1. 初始化 ReportAgent(graph_id, simulation_id, simulation_requirement)
2. 定义 progress_callback，实时更新任务进度（阶段、进度百分比、消息）
3. 调用 agent.generate_report(progress_callback, report_id=...)
4. 生成完成后，通过 ReportManager.save_report(report) 落盘

2）ReportLogger：可追溯的生成过程记录

ReportLogger 把每一步行动以 JSONL 写入 agent_log.jsonl，内容包括：

timestamp
elapsed_seconds（自报告生成开始以来的耗时）
report_id
action（如 report_start, planning_start, section_start, react_thought 等）
stage（planning / generating / pending 等）
section_title, section_index
details（任意 dict，常含 message、outline、thought 等）

这样可以做到：

后台可审计：知道 LLM 是如何一步步做出的决策和调用工具的。
前端可以用这些日志来驱动“工作流时间线”可视化。

3）前端展示（Step4Report.vue）

左侧：预测报告正文

顶部：
- 标签“Prediction Report”
- ID: reportId
- 标题 reportOutline.title
- 摘要 reportOutline.summary
章节列表：
- 来自 reportOutline.sections
- 每个章节都有状态：
  - is-active：当前正在生成
  - is-completed：已生成
  - is-pending：未来章节
- 展开/折叠（带小箭头）
章节内容：
- 若已生成，使用 renderMarkdown(generatedSections[idx+1]) 渲染
- 若正在生成，则显示“正在生成 {{section.title}} …”

右侧：工作流时间线 + 进度概览

顶部状态条：
- 显示当前阶段（如规划、生成、完成）
- 状态点颜色根据 activeStep.status
Metric 区：
- Sections：已完成章节数 / 总章节数
- Elapsed：formatElapsedTime 计算的耗时
- Tools：totalToolCalls，统计 Agent 调用了多少工具
- Status：文字形式状态，如 “Running / Completed”
时间线：
- 直接映射 agent_log.jsonl 的日志为一个可点击、可折叠列表
- 每条有：
  - 动作标签（getActionLabel(log.action)，如“规划完成”、“生成某章节”）
  - 时间戳 formatTime(log.timestamp)
  - 详情内容（如某轮 ReACT 思考的自然语言内容）

当报告完全生成后，会出现一个“进入深度互动”按钮，进入 Step 05。

Step 05：深度互动（Interaction – 与世界/Report Agent 对话）

前端组件：Step5Interaction.vue

左侧：延续 Step 4 的报告大纲 + 内容（只是一种“回顾视角”）。

右侧：交互工具区（Interactive Tools）：

1）与 Report Agent 对话

Tab：与Report Agent对话
说明：
- “报告生成智能体的快速对话版本，可调用 4 种专业工具，拥有 MiroFish 的完整记忆”
实际上就是对 ReportAgent 包了一层 Chat 模式的接口：
- 用户提问
- Agent 可调用图谱工具 / 模拟日志 / 分析工具等，给出更聚焦的分析

2）与任意世界个体对话

Agent 下拉菜单：
- 显示 profiles.length 个智能体
- 每个代理展示头像（首字母）、姓名、职业
选择某个代理后，切换到与该代理的对话模式（后端利用 OASIS 的“interview”能力，从 simulation db 读取该 Agent 的记忆/历史，再用 LLM 生成回答）。

3）发送问卷调查到世界

第三个 Tab：
- “发送问卷调查到世界中”
可理解为一次性向一批代理发出同样的问题，根据他们的立场/记忆生成回答，用来做“群体分布”分析。

这一阶段，MiroFish已从“模拟+报告”的结果，变成了一个可以持续对话、做多轮实验的虚拟社会实验场。

三、技术栈与架构概览

总体技术栈

层次	技术
前端	Vue3 + Vite +（可能）TailwindCSS，Node.js ≥ 18
后端	Python 3.11–3.12，Flask 3.x，uv 作为包管理
LLM 接口	OpenAI SDK 兼容接口（可配置 base_url/model），推荐使用阿里百炼 qwen-plus
多智能体引擎	camel-oasis（OASIS：Open Agent Social Interaction Simulations） + camel-ai 框架
记忆/知识图谱	Zep Cloud / Zep Graph Memory（GraphRAG 实现）
文档处理	PyMuPDF（PDF 提取）、md/txt/markdown 解析
配置/环境	.env + python-dotenv，统一从项目根目录加载

部署模式

源码部署：
- 复制 .env.example → .env，填入：
  - LLM_API_KEY / LLM_BASE_URL / LLM_MODEL_NAME
  - ZEP_API_KEY
- npm run setup:all 安装前后端依赖
- npm run dev 一键跑起前后端：
  - 前端：http://localhost:3000
  - 后端：http://localhost:5001
Docker 部署：
- Dockerfile 把 Python 3.11 + Node+npm + uv 打进一个镜像
- docker-compose.yml 暴露 3000/5001，挂载 .env
- docker compose up -d 即可

四、实现方式上的关键设计思想

图谱优先，而不是直接 Agent
1. 先通过本体 + GraphRAG 把“世界中的谁是谁”结构化出来，再去生成 Agent 人设和行为规则，避免了一开始 Agent 设计完全拍脑袋的问题。
OASIS 替换自研仿真引擎
1. 直接复用 OASIS 这套已经能跑到百万 Agent 的开源社会模拟平台（含推荐系统、行动空间、数据库存储）
2. MiroFish 更多精力放在“如何把现实文本翻译成 OASIS 可用的配置和 Agent”的上层问题。
Report Agent 使用 ReACT + 工具 + 日志全记录
1. 不只是简单“让 LLM 写个总结”，而是有：
  - 纲要规划阶段
  - 按章节多轮思考+工具调用
  - 完整的行为日志（以 JSONL 保存）
2. 这一点使得报告生成过程可解释、可调优，也方便未来做“Agent 反思与自我改进”。
Step-by-step UI 把复杂系统变成“五步向导”
1. 对用户来讲，只要跟着 5 步按钮走：上传 → 构图 → 生成世界 → 跑模拟 → 看报告 → 聊天/问卷
2. 把底层极其繁琐的组件组合隐藏在流程背后，降低使用门槛。

五、目前基于 MiroFish / OASIS 的二次开发与生态

从已掌握的公开信息看，严格意义上“以 MiroFish 为基础进行二次开发并形成独立项目”的案例目前还不多，主要原因是：

MiroFish 本身是 2025 年底以后才开源，Star 快速增长（数千级），但生态处于早期。
很多使用者更多是在项目内部做定制，而未单独开源为新项目。

比较明确、与其强关联的生态链路在 OASIS 一侧：

MultiAgent4Collusion（renqibing/MultiAgent4Collusion）
1. 以 OASIS 为基础，实现“大规模多智能体合谋行为模拟框架”
2. 主要用于研究在社交系统中，多智能体是否会出现串谋等行为
Shachi（SakanaAI/shachi）
1. 多智能体社会模拟平台，与 OASIS 有对接
2. 在任务配置里提供 task=oasis 的模式，可把 OASIS 环境作为其中一种“世界”
CAMEL-AI 官方生态（camel-ai/oasis + camel-ai/camel）
1. 提供各种围绕 OASIS 的教程、场景例子（如百万智能体玩 Twitter/Reddit）
2. MiroFish 正是站在这些基础设施之上，把“从现实文本到社会模拟”的一整套链路补齐

可以把 MiroFish 看成是**“OASIS 在应用层的一次高度产品化封装”**：

OASIS 负责“世界的物理规律和社交行为引擎”
MiroFish 负责：
- 把现实文本映射到合适的世界设定（ontology + graph + profiles + config）
- 提供易用 UI（五步流 + 报告 + 交互）
- 在企业/研究场景中做“可落地的预测引擎”

因此，如果要做二次开发，现实路线通常是：

在 MiroFish 上层做业务定制：
- 针对某一行业重写本体提示（如金融、医疗、教育），强制生成特定领域实体/关系
- 扩展 Report Agent 工具集，增加自有分析/风控/指标计算工具
- 在 Step 05 里加入自定义的问卷模板和群体分析面板
或者在底层 OASIS 上做算法/系统研究：
- 改进推荐算法、行动策略
- 调整动作空间，模拟新的平台类型（如电商、直播）

六、可操作建议（可行性分析）

1）技术负责人 / 创业者

想用它做产品雏形（如舆情预演、政策沙盘）：
- 先用官方 demo 跑通一个完整流程（金融/舆情案例）。
- 按行业自定义本体提示（Ontology Prompt） → 控制实体类型和关系类型。
- 结合企业自有数据源（内部报告、历史事件），通过 GraphRAG + OASIS 形成“企业专属世界”。
- 定制 Report Agent 的报告模版（章节结构、指标维度）。
- 把 Step 5 的交互部分封装进现有系统（审议会、风控平台等）。

2）研究者 / 博士生

方向：多智能体社会模拟、信息扩散、极化、合谋等
- 直接用 MiroFish 把的实验语料→世界设定这块省掉大量工程时间。
- 把精力放在：
  - 设计种子信息和实验干预（政策变化、谣言注入等）
  - 比较不同配置下的演化结果
- 如需对引擎层更细粒度控制，可直接使用 OASIS 原生接口，然后参考 MiroFish 的“文本→本体/图谱”逻辑自行集成。

3）前后端工程师

想做二次开发 / 功能增强：
- 前端：
  - 熟悉 Step1~Step5 的数据流，增加新的步骤或增强现有 UI（例如更多可视化，地图/热力图等）
- 后端：
  - 在 services 下新建工具（比如新的图谱分析 / 统计接口），并接到 Report Agent 的工具集中
  - 改进任务管理（TaskManager），加入任务队列或分布式执行能力

总结

MiroFish =「文本驱动的社会平行世界构建器」+「基于 OASIS 的多智能体仿真引擎」+「ReACT 报告与交互层」，当前直接以其为基础的开源二次开发项目还不多，但围绕 OASIS 的多智能体研究生态正在迅速扩展，MiroFish是这个生态上最贴近“实际业务场景”的一类应用框架，非常适合作为自建“AI 推演沙盘”的起点。

2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

AI写实图像生成工具对比与技术分析

需要精细控制（ControlNet/LoRA）且无本地显卡：可选海艺AI或LibLib有高端显卡且愿意折腾：SD本地部署或Flux能使用海外网络且预算充足：Midjourney基础需求、低门槛体验：通义万相4K/60fps+ControlNet+限时免费的组合在国产工具中较少见，海艺AI在这方面的配置较为完整。本文基于2026年2月实测。