# MiroFish 仓库详细介绍 MiroFish 是一个面向**社会舆论模拟**的全栈项目,核心基于 OASIS 框架实现多平台(Twitter/Reddit)的智能体(Agent)舆论仿真,结合 GraphRAG(图谱增强检索生成)、本体生成、模拟管控等能力,提供从本体构建、图谱生成到多轮模拟、报告输出的完整舆论模拟解决方案。 ## 一、项目整体架构 项目采用前后端分离架构,技术栈覆盖 Python(后端)、Vue.js(前端),核心分为**后端服务层**、**模拟执行层**、**前端交互层**三大模块,整体架构如下: ```Plain MiroFish/ ├── backend/ # 后端核心代码 │ ├── app/ # Web服务(FastAPI/Flask)、业务服务、数据模型 │ └── scripts/ # 模拟执行脚本(Twitter/Reddit仿真) ├── frontend/ # 前端交互界面 │ ├── src/api/ # 接口封装 │ ├── src/components/ # 页面组件 │ └── package-lock.json # 前端依赖 └── LICENSE # 开源许可证(基于GPL类协议) ``` ## 二、核心功能模块 ### 1. 本体(Ontology)生成与管理 核心模块:`backend/app/services/ontology_generator.py` - **功能**:根据输入的文档/模拟需求,自动生成自定义实体/关系类型的 Python 代码(兼容 Zep Cloud 本体规范),支持实体属性定义、关系类型映射、边的源目标配置。 - **关键能力**: - 标准化实体类(继承 `EntityModel`)和关系类(继承 `EdgeModel`); - 自动生成 `ENTITY_TYPES`/`EDGE_TYPES` 字典,适配图谱构建; - 支持关系的 source_targets 映射配置。 ### 2. GraphRAG 图谱构建 核心模块: - 前端接口:`frontend/src/api/graph.js` - 后端逻辑:`backend/app/services/graph_builder_service.py`(关联代码片段) - **功能**:基于生成的本体,构建面向舆论模拟的知识图谱,支持: - 上传文档+模拟需求,生成本体; - 按项目维度构建图谱,实时查询构建进度; - 图谱数据查询、项目信息获取。 - **交互流程**:前端通过 `/api/graph/ontology/generate` 生成本体 → `/api/graph/build` 构建图谱 → `/api/graph/task/{taskId}` 查询构建状态。 ### 3. 多平台舆论模拟(核心能力) #### (1)模拟载体:Twitter/Reddit 双平台 核心脚本: - `backend/scripts/run_twitter_simulation.py`:Twitter 平台模拟 - `backend/scripts/run_reddit_simulation.py`:Reddit 平台模拟 - **核心逻辑**: - 加载模拟配置(总时长、每轮分钟数、Agent 配置); - 初始化 LLM 模型、Agent 图谱、OASIS 仿真环境; - 执行多轮模拟循环(按时间切片激活不同 Agent); - 支持初始事件(如初始帖子发布)、Agent 行为决策(基于 LLM); - 模拟完成后生成数据库记录,支持后续 Interview 交互。 #### (2)Agent 配置与 Profile 管理 核心模块:`backend/app/services/oasis_profile_generator.py` - 定义 `OasisAgentProfile` 数据结构,支持: - 通用字段(user_id、persona、bio 等); - 平台专属字段(Reddit 的 karma、Twitter 的 follower_count 等); - 多格式转换(Reddit/Twitter/通用字典); - 关联实体信息(source_entity_uuid/type)。 #### (3)模拟管控:IPC 命令交互 核心模块: - `backend/scripts/run_reddit_simulation.py`(IPCHandler 类) - `backend/app/services/simulation_ipc.py`(IPC 数据结构) - **功能**:模拟运行中支持动态命令交互,如: - `INTERVIEW`:单 Agent 采访(获取特定 Agent 舆论观点); - `BATCH_INTERVIEW`:批量 Agent 采访; - `CLOSE_ENV`:关闭模拟环境; - 命令/响应通过文件系统交互(JSON 格式),保证跨进程通信可靠性。 ### 4. 模拟报告与状态管理 #### (1)报告状态接口 核心模块: - 后端:`backend/app/api/report.py` - 前端:`frontend/src/api/report.js` - **功能**: - 检查模拟报告状态(`/api/report/check/{simulation_id}`); - 判断是否解锁 Interview 功能(仅报告完成后解锁); - 返回报告 ID、状态(completed/failed)等关键信息。 #### (2)任务进度管理 核心模块:`backend/app/models/task.py` - 定义 `Task` 数据类,统一管理任务状态: - 基础字段(task_id、type、status、created_at/updated_at); - 进度字段(progress 百分比、progress_detail 详细进度); - 结果/错误字段(result、error); - 支持字典序列化(to_dict),适配前端展示。 ### 5. 通用工具能力 #### (1)重试机制 核心模块:`backend/app/utils/retry.py` - 实现 `call_with_retry` 函数,支持: - 可配置重试次数、初始延迟、退避因子; - 指定需要重试的异常类型; - 随机化延迟时间,避免并发重试冲突; - 完整的日志记录(失败原因、重试间隔)。 #### (2)文本预处理 核心模块:`backend/app/services/text_processor.py` - 标准化文本格式: - 统一换行符(\r\n → \n); - 移除连续空行(保留最多2个换行); - 行首行尾空白清理。 #### (3)项目文件管理 核心模块:`backend/app/models/project.py` - 提供 `get_project_files` 方法,按项目 ID 读取文件列表,支持项目维度的文件管理。 ## 三、前端交互核心流程 前端基于 Vue.js 开发,核心交互流程: 1. **Step 1:本体生成** → 上传文档+模拟需求,调用 `/api/graph/ontology/generate` 生成本体; 2. **Step 2:图谱构建** → 调用 `/api/graph/build` 构建 GraphRAG 图谱,实时展示进度(0-100%); 3. **模拟配置** → 选择平台(Twitter/Reddit)、设置模拟参数(时长、Agent 数量); 4. **模拟运行** → 启动模拟,实时监控状态,模拟完成后生成报告; 5. **Agent 采访** → 报告完成后解锁 Interview 功能,动态交互获取 Agent 观点; 6. **报告查看** → 查询报告状态,导出/查看模拟结果。 ## 四、技术亮点 1. **多平台适配**:基于 OASIS 框架实现 Twitter/Reddit 差异化模拟,适配不同平台的 Agent 行为特征; 2. **GraphRAG 融合**:本体生成+图谱构建,强化模拟的知识驱动能力; 3. **可靠的重试机制**:API 调用失败时自动重试,支持退避策略,提升稳定性; 4. **动态管控能力**:IPC 命令交互支持模拟运行中动态采访,而非仅静态输出; 5. **全栈交互**:前端进度可视化、后端状态管理、模拟层可配置化,形成完整闭环。 ## 五、适用场景 - 社会舆论研究:模拟特定事件在社交平台的传播路径、Agent 观点演化; - 智能体仿真:验证不同人格/属性的 Agent 在舆论场中的行为模式; - GraphRAG 落地:结合本体生成的图谱增强检索,提升模拟的知识准确性。 ## 六、部署与运行 1. **后端依赖**:需安装 OASIS 框架、Zep Cloud 客户端、SQLite(模拟数据库)、异步依赖(asyncio)等; 2. **前端依赖**:通过 `npm install` 安装前端包(package-lock.json 已锁定版本); 3. **模拟启动**: 1. Twitter 模拟:执行 `backend/scripts/run_twitter_simulation.py`; 2. Reddit 模拟:执行 `backend/scripts/run_reddit_simulation.py`; 4. **Web 服务**:启动后端 Web 服务(如 FastAPI),前端访问对应端口即可交互。 ## 七、开源许可证 项目 LICENSE 文件包含 GPL 类开源协议条款,核心强调: - 允许自由使用、修改、分发; - 衍生作品需保持开源; - 需保留原始版权声明,且不承担使用风险。 综上,MiroFish 是一个功能完整、架构清晰的社会舆论模拟平台,结合了知识图谱、智能体仿真、全栈交互等技术,适用于舆论研究、智能体仿真等领域的开发者和研究者。