MiroFish 深度技术研究报告

1. 项目概述与核心定位

1.1 项目愿景与设计理念

1.1.1 群体智能镜像：映射现实世界的数字孪生

MiroFish 的核心愿景是构建 "映射现实的群体智能镜像"——一种能够精确复刻复杂社会系统动态的数字孪生系统。该项目由盛大集团战略支持与孵化，其技术路径区别于传统预测方法：不是从输入直接映射到输出，而是构建完整的数字社会系统并观察其自发演化。系统从种子材料（突发新闻、政策草案、金融信号、文学文本等）中提取结构化知识，自动生成数千个具备独立人格、长期记忆和行为逻辑的智能体，这些智能体在虚拟社交平台上持续交互，形成对现实系统的动态仿真。

这一设计理念的技术基础是知识图谱驱动的智能体初始化。系统通过 GraphRAG 技术将非结构化文本转化为语义网络，其中节点代表实体（人物、组织、事件、概念），边代表关系（隶属、因果、对立等）。智能体的人格参数从图谱中派生，确保其行为根植于输入材料的真实语境，而非随机生成。例如，在《红楼梦》失传结局推演案例中，系统从前 80 回提取数百个人物关系和情节线索，为主要角色生成符合其性格特征的智能体，最终通过群体交互涌现叙事上合理的后续发展。

数字孪生的关键特征是时间演化能力。与静态的知识库不同，MiroFish 的智能体记忆随仿真过程持续更新：每轮交互产生的新观点、新关系被写回图谱，影响后续轮次的决策。这种设计使系统能够捕捉路径依赖效应——早期的小随机波动可能通过正反馈机制放大为后期的重大分歧，这正是社会系统的核心复杂性所在。

1.1.2 涌现性预测：从个体互动到群体行为的非线性推演

MiroFish 采用的涌现性预测范式从根本上挑战了传统统计方法的线性假设。传统预测将系统行为建模为输入特征的加权组合，而涌现性预测承认：群体层面的模式无法从个体属性简单叠加得到。这一范式的学术基础来自复杂系统科学和计算社会学，OASIS 引擎的设计借鉴了经过同行评审的研究成果，能够复现信息传播、群体极化、从众效应等已记录的社会现象。

涌现性预测的实现依赖于三个关键机制。异质性主体建模：每个智能体拥有独特的反应速度、影响力等级、记忆深度和立场倾向，这些差异在交互中产生丰富的行为多样性。动态反馈循环：智能体的行为立即改变环境状态（如发布帖子影响他人时间线），环境变化又驱动下一轮决策，形成持续的共同演化。多尺度时间结构：仿真以离散轮次推进，每轮代表固定时间单位（如 3 分钟），智能体的 24 小时活动模式由时间引擎管理，这种设计既保证了计算效率，又保留了社会节奏的真实性。

项目文档报告了该方法在实际应用中的有效性：在波动市场的新经济政策影响预测中达到了 92% 的准确率。这一数字需要谨慎解读——它更可能反映的是仿真结果与事后观察的叙事一致性，而非严格的统计验证。但无论如何，涌现性预测为处理反事实问题（"如果当时采取不同行动会怎样"）提供了传统方法难以企及的能力。

1.1.3 零风险决策实验室：政策与战略的预演沙盒

MiroFish 的第三个核心设计理念是 "零风险决策实验室"——在数字环境中预演重大决策，将试错成本降至最低。这一价值主张对于政策制定者、企业战略家和公关团队具有直接吸引力：传统决策支持依赖历史案例类比或专家直觉，验证困难且风险不可控；而数字仿真允许在虚拟空间中测试数百种情景，识别潜在风险点和优化杠杆。

上帝视角的事件注入系统 是这一理念的技术支撑。用户可以在仿真进行中动态引入外部变量：发布澄清声明、调整产品定价、模拟竞争对手反应、或引入突发危机事件，然后观察系统的重新组织。这种能力使 MiroFish 超越了被动预测工具，成为主动的决策实验平台。例如，在危机公关场景中，团队可以并行运行多个仿真版本，测试不同回应策略的效果分布，选择最优方案后再真实执行。

盛大集团的战略支持背景暗示了该系统的商业化方向。从开源社区的反馈看，企业级需求主要集中在：数据主权控制（私有化部署）、领域适配（垂直行业本体库）、以及人机协同（专家知识注入与结果校验）。这些需求正在驱动社区 fork 的多样化发展，如 MiroFish-Offline 分支的完全本地部署方案。

1.2 技术定位与差异化优势

1.2.1 区别于单模型预测的多智能体仿真范式

MiroFish 的技术定位首先体现在对单模型预测范式的根本性超越。传统大语言模型预测采用"单点询问"模式：用户提交问题，模型基于内部知识生成答案。这种方法的局限在于：答案反映的是模型的"平均意见"，而非多元主体的真实互动；无法捕捉时间维度上的动态演化；缺乏对社交传播机制的显式建模。

MiroFish 的多智能体架构从根本上解决了这些问题。系统为每个智能体维护独立的状态——人格特征、记忆历史、社会关系、当前情感——并通过 OASIS 引擎协调它们的交互。这种设计使得**"让一千个数字人类相互争论直到形成集体决策"**成为可能。关键差异可总结如下：

多智能体架构的代价是计算复杂度和成本。一个包含 1,000 智能体、运行 40 轮的仿真，意味着约 40,000 次 LLM 调用（未计入报告生成）。项目通过多种策略控制成本：双模型策略（轻量模型用于高频仿真轮次，强模型用于关键决策和报告生成）、批处理优化（OASIS 的并行推理）、以及本地部署选项（Ollama 等开源模型）。

1.2.2 基于 OASIS 引擎的学术级仿真框架

MiroFish 的技术可信度很大程度上源于其对学术级仿真框架的采用。OASIS（Open Agent Social Interaction Simulator）由 CAMEL-AI 研究社区开发，2024 年 11 月发表于 arXiv 并经过同行评审。该框架的核心贡献在于解决了大规模智能体仿真的计算瓶颈：通过高效的批处理推理和 GPU 并行，支持 100 万智能体的并发仿真，同时实现 23 种社交动作类型和双平台（Twitter + Reddit）场景。

MiroFish 对 OASIS 的集成深度体现在多个层面。架构层面：通过子进程隔离实现仿真引擎与主服务的解耦，便于资源管理和故障恢复。功能层面：扩展了动态记忆更新、上帝视角事件注入、以及 ReACT 架构的报告生成等原生 OASIS 不具备的能力。产品层面：添加了完整的 Web 界面、可视化工具和交互式分析功能，使学术框架转化为可用的商业产品。

值得注意的是，OASIS 采用 AGPL-3.0 许可证，这意味着任何通过网络提供 MiroFish 服务的部署都必须公开完整源代码。这对商业化路径构成重要约束，可能解释为何盛大集团选择战略支持而非直接收购——开源生态的社区贡献可以加速技术迭代，而商业变现需要通过增值服务（托管部署、定制开发、培训咨询）实现。

1.2.3 全链路自动化：从种子材料到交互式数字世界

MiroFish 的第三个差异化优势在于其端到端自动化能力。用户只需完成两个简单步骤——上传种子材料并用自然语言描述预测需求——系统即可自动执行完整的五阶段 pipeline：

这种自动化程度大大降低了多智能体仿真的使用门槛。对比其他 multi-agent 框架（如 AutoGPT、MetaGPT），MiroFish 的用户无需编写代码定义 agent 行为或编排任务流程，而是通过声明式配置和可视化界面完成全部操作。代价是灵活性的部分牺牲——高度封装的 pipeline 难以适应极端定制需求，这也是社区 fork 活跃的原因之一。

1.3 应用场景矩阵

1.3.1 舆情事件推演与热度预测

舆情推演是 MiroFish 最成熟的应用场景，直接继承自其前作 BettaFish。该场景的技术配置建议为：启用 Zep 图谱进行长期记忆管理、采用双平台并行模拟、设置 72 小时或更长时间的仿真周期。典型工作流程包括：上传舆情相关的背景材料（新闻报道、社交媒体数据、事件时间线），系统提取关键实体（当事人、机构、议题）和关系网络，生成代表不同利益相关方的智能体群体，追踪 sentiment evolution（情感演化）、topic propagation（话题传播）和 influence dynamics（影响力动态）。

该场景的价值在于识别关键转折点和高风险窗口。仿真可以揭示：哪些叙事会主导早期讨论、意见领袖何时何地涌现、负面情绪何时可能突破临界点、以及不同回应策略的效果分布。这些洞察对于政府部门的危机公关、企业的品牌管理、以及媒体的热点追踪都具有直接决策支持作用。

1.3.2 金融趋势与市场反应模拟

金融预测是 MiroFish 重点拓展的方向，其方法论区别于传统量化模型。项目文档明确将**"金融趋势预测：股市、加密货币的多 Agent 模拟分析"列为核心应用场景，并报告了 92% 准确率的案例。该场景的技术特点在于异质性投资者建模**：系统为智能体配置不同的投资策略（价值投资、趋势跟踪、噪声交易）、风险厌恶系数、信息获取渠道和社交影响力，模拟这些差异如何产生市场层面的价格波动。

与直接预测价格点位不同，MiroFish 提供的是**"叙事压力测试"**——观察市场参与者如何相互影响、形成共识或分歧，以及这些动态如何影响资产价格。例如，可以模拟美联储利率决策公告后的市场反应：不同投资者类型如何解读信号、信息如何通过社交网络传播、恐慌或乐观情绪何时达到临界点。这种分析对于理解市场微观结构、设计交易策略、以及评估系统性风险具有独特价值。

1.3.3 文学叙事续写与剧情推演

文学推演展示了 MiroFish 技术的通用性和创意应用潜力。标志性案例是**《红楼梦》失传结局预测**：系统从前 80 回提取数十万字的人物关系、情节线索和主题隐喻，为主要角色生成符合其性格特征的智能体，通过群体交互涌现叙事上合理的后续发展。

该场景的技术挑战在于叙事一致性的维护。与舆情或金融场景不同，小说世界有明确的作者意图和文本约束，智能体行为必须与原著风格保持协调。MiroFish 通过精细的本体论提取和人格建模应对这一挑战：从原文中提取人物性格特征、关系动态、主题模式，确保生成的智能体行为与原著保持一致。结果评估也需要特殊处理——不是简单的统计准确率，而是叙事合理性、人物一致性和主题连贯性的综合判断。

1.3.4 企业战略决策预演

企业战略场景利用 MiroFish 模拟市场竞争环境，测试不同商业策略的效果。典型用例包括：新产品发布前的市场反应预测、并购公告后的投资者情绪模拟、组织架构调整的员工接受度分析、以及竞争对手策略变化的应对预案。该场景需要定制化的本体论和智能体类型：通过扩展 entity_extractor.py 和 ontology_generator.py，可以构建特定行业的知识图谱；通过修改 oasis_profile_generator.py，可以生成符合行业特征的智能体画像。

"预演实验室"的价值在于识别潜在的意外后果。例如，在产品发布场景中，仿真可以揭示：哪些用户群体最可能积极响应、哪些群体可能产生负面反馈、负面情绪的传播路径和放大机制、以及关键意见领袖的立场演变。这些洞察帮助企业在真实投入资源前优化策略设计。

1.3.5 产品发布与用户反馈预测

产品发布场景是 MiroFish 企业应用的细分类型，具有独立的技术特点。系统内置的行业模板包含供应链参与者、竞争对手、消费者群体等多维度智能体，支持评估定价策略、营销信息、渠道选择等决策要素。仿真输出包括：采用曲线预测、用户满意度分布、潜在投诉热点、以及口碑传播的 viral 可能性。

该场景的成本效益尤为突出。据社区报告，使用混合模型配置（GPT-4o-mini 用于本体生成和报告，Gemini 2.0 Flash 免费层用于仿真轮次），单次完整仿真的 API 成本可低至约 0.01 美元。这与传统市场调研方法（焦点小组、用户访谈、A/B 测试）相比，在速度和成本上都有显著优势，尽管精度验证仍是开放问题。

---

2. 系统架构与核心组件

2.1 整体技术栈

2.1.1 前端层：Vue 3 + Vite + D3.js 可视化

MiroFish 的前端采用 Vue 3 + Vite + D3.js 技术组合，实现了现代化的单页应用架构。Vue 3 的 Composition API 为复杂状态管理提供了清晰模式——系统的核心状态（当前会话、任务进度、图谱数据、仿真状态）通过响应式系统实现跨组件自动同步，避免了传统选项式 API 的事件总线混乱。Vite 的快速热更新（HMR）显著提升了开发迭代速度，特别是对于需要频繁调整可视化参数的图谱开发场景。

D3.js 承担的图谱可视化是用户体验的核心。系统需要渲染包含数千节点和边的动态网络，支持力导向布局、缩放平移、节点拖拽、关系过滤等交互操作。更高级的功能包括：时序演化的动画回放（观察图谱如何随仿真轮次变化）、特定智能体的关系路径高亮（追踪影响力传播）、以及社区结构的自动检测和着色。这些功能的实现挑战在于性能优化——力导向仿真的物理计算、大量 DOM 元素的更新、以及平滑动画的帧率保障需要精细的算法设计和渲染优化。

前端与后端的通信采用 RESTful API + WebSocket 混合模式：标准数据操作通过 HTTP 请求完成，仿真状态的实时推送通过 WebSocket 实现低延迟更新。这种设计使前端能够显示当前轮次、活跃智能体数、热门话题等动态指标，增强用户的参与感和控制感。

2.1.2 后端层：Python + FastAPI/Flask 异步服务

后端技术栈经历了演进过程。早期版本基于 Flask 3.0+，采用同步架构处理请求；后续逐步引入 FastAPI 以支持异步 I/O 密集型场景。当前架构是混合模式：Flask 保留用于传统路由和会话管理，FastAPI 用于新建的异步端点（如仿真状态流式推送）。Python 版本被严格限定在 3.11-3.12，源于关键依赖（如 tiktoken）的兼容性要求——Pull Request #453 专门修复了 Python 3.13 导致的构建失败问题。

后端架构的关键设计决策包括：异步任务处理（图谱构建和仿真运行是长时操作，采用后台任务队列避免阻塞 HTTP 请求）、子进程隔离（OASIS 仿真引擎在独立 Python 进程中运行，通过 IPC 与主服务通信）、以及状态持久化（任务状态、会话元数据、仿真结果写入文件系统，支持断点续传和会话恢复）。

API 设计遵循资源导向风格，核心端点包括：

2.1.3 仿真引擎：CAMEL-AI OASIS 多智能体框架

OASIS 引擎是 MiroFish 的技术基石，负责执行实际的多智能体仿真。该框架由 CAMEL-AI 研究社区开发，其学术背景为 MiroFish 提供了技术可信度：2024 年 11 月发表于 arXiv 并经过同行评审，设计借鉴了计算社会科学的最新成果。

OASIS 的核心技术特性包括：

MiroFish 通过 子进程方式 集成 OASIS：simulation_runner.py 使用 subprocess.Popen 启动独立的 Python 进程执行 OASIS 脚本，双方通过基于文件的 IPC 机制交换命令和状态。这种设计的好处是隔离性——仿真引擎的崩溃或资源耗尽不会影响主服务；代价是 IPC 开销和实时性限制，社区已提出改进方案（见第 8 章）。

2.1.4 记忆系统：Zep Cloud + Graphiti 时序 GraphRAG

记忆系统是 MiroFish 实现"高保真"仿真的关键组件，采用 Zep Cloud + Graphiti 的组合方案。Zep Cloud 是专门为 AI Agent 设计的托管记忆服务，提供：向量存储（语义检索）、图谱存储（关系推理）、以及时序检索（历史追踪）三大能力。Graphiti 则负责图谱的时序组织和版本管理，支持"在时间 T，实体 A 与实体 B 的关系强度为 X"的查询。

记忆更新的工作流程为：每轮仿真结束后，系统将智能体的新观点、新关系、关键事件转换为自然语言描述，通过 ZepGraphMemoryUpdater 写入图谱。这种设计使智能体能够"记住"过往交互，在后续轮次中基于累积经验调整行为。例如，一个智能体可能对之前争论过的对手持有负面态度，或在相似情境下复用成功的策略。

成本与隐私权衡是记忆系统的关键考量。Zep Cloud 提供每月免费额度，足以支撑简单试用；但对于大规模部署或敏感数据场景，社区 fork 提供了替代方案：amadad/mirofish 使用嵌入式 KuzuDB，MiroFish-Offline 分支使用 Neo4j Community Edition，实现完全的数据主权控制。

2.1.5 部署方案：Docker Compose 容器化编排

MiroFish 提供 Docker Compose 作为推荐的部署方案，实现前后端服务的一键启动。docker-compose.yml 配置包括：

Docker 部署的优势在于环境一致性——复杂的依赖栈（Node.js 18+、Python 3.11-3.12、uv、特定 PyTorch 版本等）被封装为可复现的镜像，避免"在我机器上能跑"问题。镜像构建过程中，配置文件中已通过注释提供加速镜像地址，方便国内用户快速部署。

源码部署保留为开发和深度定制的选项，流程包括：git clone → cp .env.example .env → npm run setup:all → npm run dev。两种部署方式共享相同的 .env 配置机制，便于环境迁移。

2.2 目录结构与模块划分

2.2.1 frontend/：交互界面与图谱可视化

frontend/ 目录包含完整的 Vue 3 单页应用，按功能模块组织：

国际化支持是前端的重要特性。原始版本主要面向中文用户，社区 fork（amadad/mirofish、nikmcfly/MiroFish-Offline）已完成完整的英文翻译，涉及 60+ 文件、1000+ 字符串。实现采用 Vue I18n 插件，语言文件模块化组织，并预留 RTL（从右到左）布局支持。

2.2.2 backend/app/api/：RESTful API 端点（图谱/仿真/报告）

backend/app/api/ 实现轻量级的 RESTful 端点，采用 Flask 蓝图机制组织。设计原则为"瘦 API"——路由处理仅负责请求验证、参数解析、响应格式化，业务逻辑委托给 services/ 层。

当前 API 的安全局限需要关注：所有端点均未做身份校验，未登录即可执行创建/删除项目、触发仿真等敏感操作。这是版本 0.1.2 的已知问题，企业部署时需要额外关注。社区 Pull Request #445 报告了"Flask debug mode enabled by default, exposed on 0.0.0.0"的安全问题，体现了社区对配置安全的持续审查。

2.2.3 backend/app/core/：会话管理、资源加载、任务调度

backend/app/core/ 是系统的"操作系统"层，提供跨模块的基础设施：

会话元数据持久化到 backend/uploads/workbench_sessions/，任务状态保存到 backend/uploads/tasks/。这种设计支持会话的跨设备恢复和任务的断点续传。

2.2.4 backend/app/resources/：项目/文档/数据库/仿真适配器

backend/app/resources/ 实现适配器模式，为不同类型的持久化数据提供统一接口：

适配器模式的关键价值在于可替换性：底层存储技术的变化（如从 KuzuDB 迁移到 Neo4j）不会影响到上层业务逻辑。MiroFish-Offline 分支通过实现相同的适配器接口，完成了 Zep Cloud 到 Neo4j 的迁移。

2.2.5 backend/app/tools/：可组合工作流操作（摄取/构建/准备/运行/报告）

backend/app/tools/ 实现工作流的原子操作，采用函数式组合设计：

工具之间通过 Pydantic 模型定义数据契约，支持链式组合和条件执行。例如，BuildTool 和 PrepareTool 在数据就绪后可以部分并行，RunTool 必须等待 PrepareTool 完成。

2.2.6 backend/app/services/：核心服务实现

backend/app/services/ 是系统的业务逻辑核心，包含七个关键服务模块：

simulation_runner.py 的详细分析见第 2.3.5 节。

2.2.7 backend/app/utils/：LLM 客户端与通用工具

backend/app/utils/ 提供跨模块的通用功能，最重要的是 llm_client.py——多提供商 LLM 客户端。该客户端统一了不同 LLM API 的调用细节，支持：

客户端实现容错和降级：API 失败时自动重试（指数退避）、支持超时配置、可配置备用模型。这些机制对于长时运行的仿真任务尤为重要。

2.3 核心服务组件详解

2.3.1 graph_storage.py：图谱存储抽象与 KuzuDB/JSON 后端

graph_storage.py 实现图谱存储的抽象接口，支持多种后端实现：

抽象接口定义了图谱操作的基本语义：节点和边的 CRUD、属性查询、路径遍历、子图提取、全图导入导出等。KuzuDB 作为默认选择，平衡了性能和部署简便性：无需独立服务进程，数据以文件形式存储，查询性能足以支撑百万级节点/边的分析场景。

2.3.2 graph_db.py：多后端兼容门面模式

graph_db.py 实现门面模式（Facade Pattern），为上层模块提供简化的图谱访问接口。门面封装了复杂的查询逻辑，提供语义化方法如：

• get_entity_neighbors(entity_id, relation_type=None, depth=1)：获取实体的邻居子图
• find_shortest_path(source, target, max_length=5)：计算实体间的最短路径
• compute_centrality(metric='betweenness')：计算网络中心性指标
• detect_communities(algorithm='louvain')：社区检测

门面还负责连接池管理、事务封装、错误重试等横切关注点，确保图谱操作的可靠性和性能。

2.3.3 entity_extractor.py：LLM 驱动的实体关系抽取

entity_extractor.py 实现从非结构化文本到结构化知识的转换，采用纯 LLM 驱动方案（无传统 NLP 管道）。核心流程：

1. 文本分块：将长文档分割为适合 LLM 上下文窗口的片段（通常 2,000-4,000 令牌）
2. 本体论引导抽取：使用 ontology_generator.py 生成的概念框架，提示 LLM 识别实体、属性、关系
3. 多轮验证：对低置信度抽取进行复核，解决冲突和歧义
4. 结果融合：合并跨块的抽取结果，进行实体消歧和关系去重

LLM 驱动的优势在于领域适应性——无需为每个新领域训练专门模型，通过提示工程即可处理从金融报告到小说故事的广泛内容。代价是API 成本和抽取速度，这是 BuildTool 阶段的主要耗时环节（7-10 分钟 for 15,000 字符文档）。

2.3.4 graph_builder.py：本体论到图谱的构建管道

graph_builder.py 协调从本体论定义到实例化图谱的完整流程，采用流式处理架构支持大规模数据：

构建进度通过状态机跟踪，前端可轮询获取当前阶段和预估剩余时间。

2.3.5 simulation_runner.py：OASIS 多智能体仿真子进程管理

simulation_runner.py 是 MiroFish 最核心的服务模块，代码规模达 1768 行、67.6 KB，负责管理 OASIS 仿真引擎的完整生命周期。

核心方法 start_simulation 的实现逻辑：

def start_simulation(
    self,
    simulation_id: str,
    platform: str,  # "twitter", "reddit", "parallel"
    max_rounds: Optional[int] = None,
    enable_graph_memory_update: bool = False,
    graph_id: Optional[str] = None
) -> Dict[str, Any]:
    # 1. 验证阶段：检查仿真是否已在运行
    # 2. 配置加载：读取 simulation_config.json
    # 3. 脚本选择：根据 platform 参数选择执行脚本
    # 4. 子进程启动：subprocess.Popen 创建独立进程组
    # 5. 记忆更新器初始化（可选）：ZepGraphMemoryUpdater
    # 6. 监控线程启动：_monitor_simulation 后台运行

关键设计决策：

监控线程 _monitor_simulation 的核心逻辑：

def _monitor_simulation(self, process, simulation_id, state, config):
    while process.poll() is None:  # 进程仍在运行
        # 增量读取 Twitter actions.jsonl
        twitter_pos = _read_action_log(twitter_log, twitter_pos, state, "twitter")
        # 增量读取 Reddit actions.jsonl  
        reddit_pos = _read_action_log(reddit_log, reddit_pos, state, "reddit")
        _save_run_state(state)  # 持久化状态
        time.sleep(1)  # 每秒检查一次

状态机设计：RunnerStatus 枚举涵盖 IDLE、STARTING、RUNNING、PAUSED、STOPPING、STOPPED、COMPLETED、FAILED 八种状态，支持精细的运行控制和故障诊断。

已知局限与改进方向：社区分析指出当前 IPC 机制存在实时性不足（文件轮询延迟）、可靠性风险（竞争条件、子进程崩溃静默检测延迟最长 60 秒）等问题。建议改进方案：采用 asyncio.create_subprocess_exec 替代 subprocess.Popen，使用每仿真一对的 asyncio.Queue 替代文件 IPC，实现真正的异步协程通信。

2.3.6 report_agent.py：ReACT 工具调用型报告生成代理

report_agent.py 实现 ReACT（Reasoning + Acting）架构的报告生成代理，区别于简单的模板填充。ReACT 循环的工作机制：

1. 推理（Reasoning）：分析预测需求，确定信息收集策略
2. 行动（Acting）：调用可用工具获取信息
3. 观察（Observation）：整合工具返回结果
4. 迭代：重复 1-3 直到信息充分，生成最终报告

可用工具集（定义于 graph_tools.py）：

循环控制参数（config.py 配置）：

2.3.7 graph_tools.py：搜索、访谈与分析工具集

graph_tools.py 为 ReportAgent 和上层模块提供图谱操作的工具函数，设计需平衡表达能力与易用性：

搜索工具支持多种查询模式：

• 精确匹配：按实体名称或 ID 查找
• 语义搜索：基于向量相似度的模糊匹配
• 结构查询：按关系类型、路径模式、时序窗口过滤
• 子图遍历：从给定实体出发，按深度和关系类型探索邻居

访谈工具实现与特定智能体的对话：

• 加载智能体的完整状态（人格参数、记忆历史、当前观点）
• 维护对话上下文，支持多轮交互
• 将用户问题转换为智能体视角的自然语言响应

分析工具提供定量分析能力：

• 网络分析：中心性（度、介数、特征向量）、社区检测（Louvain、Leiden）、传播模拟
• 时序分析：趋势提取、突变检测、周期性分析
• 情感分析：观点极性、情感强度、立场分布

---

3. 配置系统与环境管理

3.1 config.py 核心作用

3.1.1 环境变量加载机制：从 .env 到 Python 对象

config.py 实现分层配置加载机制，遵循十二因素应用方法论：

# 伪代码示意
from dotenv import load_dotenv
import os

# 1. 加载 .env 文件（若存在）
env_path = Path(__file__).parent.parent.parent / '.env'
if env_path.exists():
    load_dotenv(env_path, override=True)

# 2. 定义 Config 类，从环境变量读取
class Config:
    SECRET_KEY = os.environ.get('FLASK_SECRET_KEY', 'default-unsafe-key')
    DEBUG = os.environ.get('FLASK_DEBUG', 'False').lower() == 'true'
    LLM_API_KEY = os.environ.get('LLM_API_KEY')  # 必填，无默认值
    # ... 其他配置

加载优先级：系统环境变量 > .env 文件 > 代码默认值。这种设计支持开发环境（本地 .env）和生产环境（平台注入变量）的灵活切换，同时确保敏感信息（API 密钥）不会进入版本控制。

3.1.2 Flask 应用配置聚合：密钥、调试模式、跨域设置

Config 类聚合 Flask 框架运行所需的全部参数：

已知安全问题：Pull Request #445 报告"Flask debug mode enabled by default, exposed on 0.0.0.0"，版本 0.1.2 尚未修复。企业部署时需显式设置 FLASK_DEBUG=False 并限制绑定地址。

3.1.3 LLM 配置中心：API 密钥、基地址、模型名称、温度参数

LLM 配置是 config.py 的业务核心，直接决定系统功能和成本：

双模型策略（社区扩展）：PRIMARY_LLM_* 用于高质量低频率任务（本体论生成、报告合成），SECONDARY_LLM_* 或 LLM_BOOST_* 用于高频率相对简单任务（智能体动作决策），显著降低成本。

3.1.4 文件上传配置：大小限制、超时设置、路径管理

上传文件的处理采用流式解析策略，避免大文件完全加载到内存。PDF 解析依赖 PyPDF2/pdfplumber，Markdown 解析处理 frontmatter 和链接，TXT 需要编码检测（chardet）和段落分割。

3.1.5 日志与监控：级别控制、格式规范、存储策略

日志配置通过独立 logger.py 模块实现，关键参数：

生产环境建议接入集中式日志收集（ELK、Loki、Fluentd），支持全文检索和告警规则。

3.2 关键环境变量解析

3.2.1 LLM_API_KEY / LLM_BASE_URL / LLM_MODEL_NAME：大模型接入

这三个变量构成 LLM 接入的完整配置，灵活性是 MiroFish 的重要设计特点——支持任意 OpenAI SDK 兼容的端点：

成本优化建议：仿真轮次使用轻量模型（gpt-4o-mini、qwen-turbo），关键决策和报告生成使用强模型（gpt-4o、qwen-plus），可降低 50-70% 成本而不显著影响质量。

3.2.2 ZEP_API_KEY：长期记忆图谱服务

ZEP_API_KEY 用于认证 Zep Cloud 服务，提供时序 GraphRAG 能力：

替代方案（社区 fork）：

• amadad/mirofish：KuzuDB 嵌入式图数据库，零外部依赖
• MiroFish-Offline：Neo4j Community Edition + Ollama，完全本地部署

3.2.3 FLASK_SECRET_KEY / FLASK_DEBUG：服务安全与调试

安全审计建议：定期检查 DEBUG 模式是否意外启用，验证 SECRET_KEY 是否使用默认值，确认 CORS 配置未过度开放。

3.2.4 UPLOAD_FOLDER / MAX_CONTENT_LENGTH：文件系统约束

3.3 部署配置策略

3.3.1 源码部署：开发调试与深度定制

前置要求：Node.js 18+、Python 3.11-3.12、uv 最新版

# 完整流程
git clone https://github.com/666ghj/MiroFish.git
cd MiroFish
cp .env.example .env
# 编辑 .env，填入 API 密钥
npm run setup:all      # 安装前后端所有依赖
npm run dev            # 启动开发服务器
# 前端: http://localhost:3000
# 后端: http://localhost:5001

优势：完整源代码访问、断点调试支持、依赖版本精确控制、自定义修改自由度。适用场景：功能开发、性能优化、深度定制、学术研究。

3.3.2 Docker 部署：快速体验与生产环境

cp .env.example .env
# 编辑 .env
docker compose up -d   # 后台启动所有服务

服务组成：

优势：环境一致性、快速启动、隔离性好、便于扩展。适用场景：快速体验、生产部署、CI/CD 集成。

3.3.3 环境隔离：虚拟环境与依赖锁定

Python 依赖管理：采用 uv 工具，替代 pip + virtualenv

Node 依赖管理：package-lock.json 锁定版本，npm ci 用于生产构建。

关键依赖版本（requirements.txt 节选）：

flask>=3.0.0
flask-cors>=6.0.0
camel-oasis==0.2.5      # OASIS 引擎，版本锁定
pydantic>=2.0.0
openai>=1.0.0
tiktoken>=0.5.0         # Python 3.11-3.12 必需

---

4. 核心算法与仿真引擎

4.1 OASIS 引擎集成机制

4.1.1 双平台并行仿真：Twitter + Reddit 社交场景

MiroFish 的双平台并行设计是其架构的重要创新，反映了现实社交媒体的多样性：

技术实现：同一组智能体在两个平台上拥有独立的账号和行为历史，但共享底层的知识图谱和记忆系统。平台特定的状态（时间线内容、投票分数）分别维护，跨平台的内容引用和用户信息流动通过共享图谱实现。这种设计使得同一事件在不同社交语境中产生差异化演化，为预测分析提供更稳健的视角。

4.1.2 智能体生命周期管理：创建、交互、演化、消亡

OASIS 引擎实现完整的智能体状态机：

决策循环的 LLM 调用优化：简单高频动作（点赞、关注）可能基于规则或轻量模型快速决策；复杂低频动作（发帖、长回复）触发完整 LLM 推理。这种分层设计平衡了仿真真实性和计算效率。

4.1.3 时序记忆更新：轮次驱动的图谱动态演化

记忆更新流程（每轮仿真结束后执行）：

1. 事件提取：从本轮 AgentAction 日志识别关键事件（新观点表达、关系变化、情感转折）
2. 自然语言生成：将结构化事件转换为描述性文本（"智能体 A 在话题 X 上与智能体 B 发生争论，态度转为负面"）
3. 图谱写入：通过 ZepGraphMemoryUpdater 更新时序图谱，添加新节点/边或调整权重
4. 索引更新：刷新向量索引和时序索引，确保后续检索效率
5. 一致性校验：检测时间冲突或逻辑矛盾，标记异常供审核

记忆检索的上下文组装：智能体决策时，系统从图谱检索相关记忆，组装为 LLM 上下文。检索策略包括：

• 时间衰减：近期事件优先，远期事件逐渐淡化
• 重要性加权：高情感冲击、高互动量事件增强保留
• 相关性过滤：与当前话题、参与者、情境匹配的记忆优先激活

4.1.4 事件注入系统：上帝视角的变量干预

事件注入是 MiroFish 的独特功能，支持三类干预：

注入时机：仿真开始前（设定初始条件）、仿真进行中（动态干预）、仿真结束后（反事实重跑）。注入效果的可追溯性：系统记录所有注入事件的时间戳、参数、影响范围，支持对比分析和敏感性评估。

4.2 智能体建模体系

4.2.1 人格生成：基于种子材料的角色背景构建

人格参数空间（从种子材料派生）：

生成流程：LLM 基于相关图谱子上下文（实体描述、关系路径、关联事件），使用人格模板填充具体参数值。质量控制包括：参数一致性检查（年龄与职业匹配）、极端值检测（防止全 0 或全 1）、多样性保证（避免智能体同质化）。

4.2.2 动机引擎：目标驱动与情感状态建模

动机层次：

情感状态模型（离散或连续）：

• 离散：愤怒、恐惧、喜悦、悲伤、惊讶、厌恶等基本情绪，以及复合情绪（如希望 = 喜悦 + 预期）
• 连续：效价（正/负）、唤醒度（高/低）、支配感（控制/被控制）的三维空间

情感-行为映射：情感状态影响动作选择概率（愤怒时更可能发表攻击性内容，喜悦时更可能积极互动），同时情感也会因行为结果和环境反馈而动态更新。

4.2.3 社交关系网络：动态亲密度与影响力计算

关系类型与权重：

影响力计算的多因素模型：

Influence(agent) = α × FollowerCount^β 
                 + γ × EngagementRate 
                 + δ × ContentQuality 
                 + ε × NetworkCentrality
                 + ζ × RecencyBoost

参数通过仿真校准或实证数据拟合确定，不同平台（Twitter/Reddit）可能有不同的权重配置。

4.2.4 记忆架构：短期工作记忆与长期图谱记忆

双层架构的设计原理：

记忆晋升机制：工作记忆中的高重要性事件（高情感强度、高互动量、关键决策点）通过巩固过程写入图谱记忆；图谱记忆中的高频检索记忆增强提取强度，低频记忆逐渐衰减。

4.3 MiroFishModel 与 miro_fish 函数分析

4.3.1 模块定位：mirofish 包的核心接口

关键发现：经过对官方仓库 666ghj/MiroFish 及其主要社区 fork 的全面检索，MiroFishModel 类和 miro_fish 函数并非位于主仓库源码中，而是属于独立的 PyPI 包 mirofish-simulator（版本 0.12.0）。

这一发现具有重要的架构理解意义：

• mirofish-simulator 是 OASIS 引擎的上层封装库，将多智能体仿真能力产品化为可导入的 Python 包
• 主仓库 MiroFish 是 完整的 Web 应用，通过 SimulationRunner 服务以子进程方式调用 mirofish-simulator
• 这种分层设计实现了仿真引擎与产品界面的解耦，便于独立演进和多种集成方式

导入语句的证据：simulation_runner.py 中的 from mirofish import MiroFishModel, miro_fish 表明这两个符号是外部依赖，而非项目内部实现。该导入在标准 Python 环境（未安装 mirofish-simulator）中会失败，解释了为何部分开发者报告导入错误。

4.3.2 MiroFishModel：仿真状态与模型参数的封装实体

基于 PyPI 包信息和同类系统设计模式，MiroFishModel 的推测接口：

class MiroFishModel:
    def __init__(
        self,
        config: SimulationConfig,
        llm_client: Optional[LLMClient] = None,
        memory_backend: Optional[MemoryBackend] = None
    ):
        self.config = config          # 仿真参数
        self.agents: List[Agent] = [] # 智能体集合
        self.graph: KnowledgeGraph    # 知识图谱
        self.platforms: Dict[str, Platform]  # 平台状态
        self.history: SimulationHistory      # 完整历史
        self.status: ModelStatus = ModelStatus.IDLE
        
    def build_graph(self, seed_material: Union[str, Path, Document]) -> KnowledgeGraph:
        """从种子材料构建知识图谱"""
        
    def generate_agents(self, count: int, diversity_params: Optional[Dict] = None) -> List[Agent]:
        """基于图谱生成智能体人格"""
        
    def step(self, n: int = 1, events: Optional[List[Event]] = None) -> SimulationState:
        """执行 n 轮仿真，可选注入事件"""
        
    def run(self, until: Union[int, Callable, Condition], callbacks: Optional[Dict] = None) -> SimulationResult:
        """执行完整仿真，支持多种终止条件"""
        
    def inject_event(self, event: Event, target: Optional[Union[str, List[str]]] = None) -> None:
        """上帝视角事件注入"""
        
    def get_report(self, query: str, agent: Optional[str] = "report_agent") -> Report:
        """生成预测报告"""
        
    def save(self, path: Union[str, Path]) -> None:
        """序列化完整状态"""
        
    def load(self, path: Union[str, Path]) -> "MiroFishModel":
        """从检查点恢复状态"""
        
    def interact(self, agent_id: str, message: str) -> str:
        """与特定智能体对话"""

4.3.3 miro_fish：主控函数与执行入口

miro_fish 函数提供一步式完整工作流，是库的用户-facing API：

def miro_fish(
    seed_material: Union[str, Path, Document, List[Document]],
    prediction_goal: str,
    config: Optional[SimulationConfig] = None,
    callbacks: Optional[Dict[str, Callable]] = None,
    return_interactive: bool = False
) -> Union[SimulationResult, Tuple[SimulationResult, InteractiveWorld]]:
    """
    MiroFish 主入口：从种子材料到预测报告的完整流程
    
    Parameters
    ----------
    seed_material : 种子材料，支持多种格式
    prediction_goal : 自然语言描述的预测目标
    config : 仿真配置，None 则使用默认配置
    callbacks : 回调函数，用于进度监控和干预
    return_interactive : 是否返回交互式世界对象
    
    Returns
    -------
    SimulationResult 或 (SimulationResult, InteractiveWorld)
        包含预测报告、完整历史、关键指标等
    """
    # 实现：初始化模型 → 构建图谱 → 生成智能体 → 运行仿真 → 生成报告

设计哲学：最简用例可一行代码完成，同时保留高级定制的灵活性。return_interactive=True 模式支持仿真后的深度探索，与 MiroFish Web 应用的"深度互动"阶段对应。

4.3.4 与 SimulationRunner 的协作关系：子进程调用与 IPC 通信

主仓库 MiroFish 通过 SimulationRunner 服务集成 mirofish-simulator，采用子进程 + IPC 架构：

架构对比：

社区已提出异步协程改进方案：使用 asyncio.create_subprocess_exec 替代 subprocess.Popen，采用 asyncio.Queue 替代文件 IPC，可将状态同步延迟从秒级降至毫秒级，同时简化代码结构。

4.4 仿真运行状态机

4.4.1 RunnerStatus 枚举：IDLE / RUNNING / PAUSED / COMPLETED / ERROR

simulation_runner.py 定义了精细的状态机：

状态转换的原子性：通过锁机制确保并发操作的安全，防止竞态条件导致的状态不一致。

4.4.2 AgentAction 数据类：智能体行为的结构化表示

@dataclass
class AgentAction:
    action_id: str           # UUID，全局唯一
    timestamp: datetime      # 仿真时间戳
    round_num: int           # 所属轮次
    platform: str            # "twitter" | "reddit"
    
    agent_id: str            # 执行者标识
    agent_name: str          # 显示名称
    
    action_type: str         # 枚举：CREATE_POST, REPLY_POST, LIKE_POST, 
                             #       RETWEET, FOLLOW, UNFOLLOW, SEARCH, ...
    action_args: Dict        # 类型特定参数
    content: Optional[str]   # 文本内容（发帖/回复）
    target_id: Optional[str] # 目标对象 ID（回复/点赞/关注）
    
    result: Dict             # 执行结果：可见性、互动数、情感标签等
    success: bool            # 是否成功执行
    reasoning: Optional[str] # LLM 决策推理链（可解释性）

数据用途：行为日志支持多种下游分析——时间序列聚合（趋势提取）、网络构建（关系演化）、内容分析（主题建模、情感分析）、以及个体轨迹追踪（特定智能体的行为模式）。

4.4.3 异步事件循环：非阻塞仿真与实时状态推送

后端异步架构：

前端实时更新流程：

1. 用户点击"启动仿真" → POST /api/simulation/start
2. 后端创建 SimulationRunner 实例，启动子进程
3. 后台监控线程每秒读取 actions.jsonl，更新内存状态
4. WebSocket 连接建立，状态变更即时推送
5. 前端 Vue 组件响应式更新，进度条、指标卡片、图谱动画同步刷新

性能瓶颈与优化：当前文件 IPC 机制限制状态更新频率为约 1 秒；改进方案（内存队列 + 异步协程）可将延迟降至 10-100 毫秒，支持更流畅的实时可视化。

---

5. 数据处理与知识图谱

5.1 种子材料处理管道

5.1.1 多格式支持：PDF / Markdown / TXT 解析

MiroFish 支持 PDF、Markdown、TXT 三种主要格式的种子材料上传，各格式的解析策略：

格式选择建议：结构化内容（报告、论文）优先使用 Markdown；扫描文档使用 OCR 后的文本或 PDF；简单笔记使用 TXT。混合格式（如含大量图片的 PDF）可能需要预处理提取关键文本。

5.1.2 文本预处理：分块、清洗、向量化

预处理流程：

分块策略的权衡：

5.1.3 信息密度评估：关键内容提取与噪声过滤

信息密度指标（启发式或模型-based）：

噪声过滤策略：基于密度指标的低质量块过滤、基于主题模型的离群内容检测、以及基于用户反馈的迭代优化。

5.2 本体论生成与实体抽取

5.2.1 LLM 驱动的本体识别：概念、属性、关系三元组

本体论生成流程（ontology_generator.py）：

1. 主题识别：分析种子材料的整体主题和领域类型
2. 概念层次：识别核心概念及其上下位关系（如"人物" ⊃ "官员" ⊃ "部长"）
3. 属性定义：为每个概念定义关键属性（如"人物"有姓名、年龄、职位、立场）
4. 关系类型：识别概念间可能的关系（隶属、合作、竞争、因果等）
5. 约束规则：定义基数约束、值域约束、互斥约束等

LLM 提示工程的关键要素：

• Few-shot 示例：提供领域相关的本体示例，引导模型输出格式
• 迭代精化：多轮对话逐步完善，从粗粒度到细粒度
• 一致性校验：检测循环继承、属性冲突等问题

5.2.2 实体消歧与链接：同名异义与异名同义处理

消歧挑战的类型：

实体链接的流程：候选生成（名称匹配、别名扩展）→ 候选排序（上下文相似度、图谱一致性）→ 阈值判断（置信度 > 0.8 链接，0.5-0.8 人工审核，< 0.5 新建实体）。

5.2.3 关系强度量化：基于共现与语义相似度

关系强度计算的多因素模型：

Strength(e1, e2, relation) = α × CooccurrenceFrequency
                           + β × SemanticSimilarity(e1, e2)
                           + γ × SyntacticCloseness(sentence)
                           + δ × TemporalProximity(events)
                           + ε × UserFeedback(corrections)

5.3 GraphRAG 构建流程

5.3.1 时序图谱组织：时间戳索引与版本管理

时序图谱的核心结构：

版本管理策略：为关键实体和关系维护版本历史，支持"在时间 T，图谱状态如何"的查询。存储优化：完整快照 + 增量日志的混合方案，平衡查询效率和存储成本。

5.3.2 社区检测与聚类：群体结构自动发现

社区检测算法：

社区演化的时序分析：追踪社区的分裂、合并、生长、消亡，识别关键转折点（如意见领袖的跨社区流动）。

5.3.3 检索增强生成：子图采样与上下文组装

GraphRAG 的检索流程：

1. 查询理解：将自然语言查询转化为图谱查询意图
2. 种子实体识别：提取查询中的关键实体或生成候选嵌入
3. 子图扩展：从种子出发，按关系类型和深度约束扩展邻居
4. 相关性排序：结合结构重要性（PageRank、中心性）和语义相似度
5. 上下文组装：将子图序列化为自然语言描述，适配 LLM 上下文窗口
6. 生成增强：LLM 基于检索到的图谱上下文生成回答

上下文组装的优化：关键路径优先、冗余信息过滤、多视角整合（不同社区的观点对比）。

5.4 记忆注入与更新机制

5.4.1 个体记忆：智能体私有经验存储

个体记忆的内容：

• 事件记忆：亲身参与的关键事件（发帖、争论、合作）
• 情感记忆：与特定实体或话题关联的情感体验
• 策略记忆：成功或失败的行为模式及其后果
• 关系记忆：与其他智能体的互动历史和当前状态

存储格式：自然语言描述（便于 LLM 理解）+ 结构化标签（便于检索过滤）。

5.4.2 群体记忆：共享事件与公共知识

群体记忆的来源：

• 公共信息发布：新闻、公告、趋势话题
• 高频互动事件：广泛讨论的热点、集体行动
• 制度性知识：平台规则、社会规范、历史共识

与个体记忆的关系：群体记忆为个体提供共享的参考框架，个体记忆在群体记忆基础上添加个性化解读。

5.4.3 记忆衰减与强化：时间衰减与重要性加权

艾宾浩斯风格的遗忘曲线：

Retention(t) = Importance × e^(-λ × t / Stability)

记忆强化机制：成功预测或决策后的复述、情感高峰事件的闪光灯效应、与他人分享时的社会巩固。

---

6. 模型训练与优化策略

6.1 提示工程体系

6.1.1 角色提示模板：人格一致性维护

人格提示的核心要素：

一致性维护策略：关键属性在提示中重复强化、行为结果反馈到记忆并影响后续提示、定期"校准"提示防止漂移。

6.1.2 情境提示构造：上下文窗口优化

上下文窗口的有限性挑战：即使 128K 上下文模型，面对数千智能体的复杂交互历史也会捉襟见肘。

优化策略：

6.1.3 思维链引导：推理过程显性化

思维链（Chain-of-Thought）的应用场景：

• 复杂决策（是否发帖、如何回应争论）
• 情感更新（为何情绪变化、如何表达）
• 关系调整（是否关注/取关、如何维护）

引导方式：提示中明确要求"逐步思考"、提供思考框架（感知 → 评估 → 决策 → 执行）、在输出格式中预留 reasoning 字段。

6.2 仿真参数调优

6.2.1 智能体数量：精度与效率的权衡（建议 < 5000）

规模效应分析：

项目建议：标准场景 500-2000 智能体，复杂场景可扩展至 5000，>5000 需特殊优化和成本评估。

6.2.2 模拟轮次：收敛性判断与提前终止（默认 40 轮）

收敛性指标：

提前终止策略：多指标综合判断，或训练专门的收敛预测模型。

6.2.3 开放度参数：随机性权重与结果多样性

开放度的多维度控制：

6.2.4 快速模式：牺牲精度的加速策略

加速技术：

6.3 反事实模拟与敏感性分析

6.3.1 关键参数扰动：识别决策敏感因素

敏感性分析流程：

1. 确定基准仿真配置和关键输出指标
2. 选择待测试参数及其扰动范围（±20%, ±50%, 极端值）
3. 并行运行多组扰动仿真
4. 量化输出变化，计算敏感性系数
5. 识别高敏感性参数，优先精确估计或稳健化设计

6.3.2 场景分支对比：多版本并行推演

分支策略：

6.3.3 置信度评估：结果稳定性量化

置信度来源：

---

7. 结果生成与可视化

7.1 预测报告生成

7.1.1 ReportAgent 架构：ReACT 循环与工具调用

ReACT 循环的详细流程（report_agent.py）：

循环控制：最大工具调用次数（默认 5）、最大反思轮次（默认 2）、超时限制（防止无限循环）。

7.1.2 报告结构：关键转折点、风险信号、置信度标注

标准报告章节：

7.1.3 多维度分析：时间线、影响力网络、情感演化

时间线分析：识别关键转折点（舆论反转、联盟重组、情绪爆发），标注触发事件，量化变化速度。

影响力网络：计算多中心性指标（度、介数、特征向量、PageRank），识别关键意见领袖和信息桥梁，追踪影响力随时间的流动和集中。

情感演化：整体情感极性和强度的时序变化，不同群体的情感分化，情感与行为的关联模式。

7.2 交互式可视化

7.2.1 动态图谱渲染：D3.js 力导向图与时空演化

D3.js 实现的核心功能：

性能优化：Canvas 渲染替代 SVG（>1000 节点）、Web Worker offload 力计算、层次细节（LOD）简化远距离节点。

7.2.2 智能体画像：个体轨迹与关系探查

智能体画像面板：

7.2.3 对话界面：与报告代理或特定角色的深度访谈

对话模式：

对话状态管理：维护对话历史、注入相关记忆、管理上下文窗口、处理多轮引用和指代。

7.3 结果导出与复用

7.3.1 会话持久化：workbench_sessions/ 元数据存储

会话存储内容：

7.3.2 任务状态管理：tasks/ 长时运行状态恢复

任务状态机持久化：支持崩溃恢复、断点续传、进度查询。关键状态：PENDING、RUNNING、PAUSED、COMPLETED、FAILED、CANCELLED。

7.3.3 报告格式：结构化 JSON 与可读文档双输出

---

8. 性能优化与工程实践

8.1 计算资源管理

8.1.1 内存优化：大规模智能体的分页加载

内存压力来源：每个智能体的完整状态（人格参数、记忆历史、当前情感）可能占用 10-100 KB，10000 智能体即 100 MB-1 GB。

优化策略：

• 活跃/休眠分离：仅活跃智能体常驻内存，休眠智能体序列化到磁盘
• 按需加载：根据当前轮次的平台活动和关注关系，预测需要加载的智能体集合
• 共享结构：相同类型的智能体共享人格模板，仅存储个体差异

8.1.2 并发控制：异步 I/O 与协程调度

当前架构的并发层次：

改进方向：统一为 asyncio 协程架构，减少线程切换开销，提高并发效率。

8.1.3 子进程隔离：仿真引擎的独立运行空间

隔离的益处与代价：

8.2 API 成本控制

8.2.1 令牌消耗预估：轮次 × 智能体数 × 上下文长度

成本模型：

Total Tokens ≈ Rounds × Agents × (Prompt Tokens + Completion Tokens)
            ≈ 40 × 1000 × (4000 + 500) 
            ≈ 180M tokens per simulation

按 GPT-4o-mini 价格（\(0.15/M input,\)0.60/M output）：约 **\(40/仿真**。 #### 8.2.2 模型选择策略：qwen-plus 性价比优势 **成本优化组合**（社区实践）： | 任务 | 模型 | 成本比例 | 质量影响 | |:---|:---|:---|:---| | 本体论生成 | qwen-plus / gpt-4o-mini | 10% | 关键，需高质量 | | 智能体决策 | qwen-turbo / gpt-4o-mini | 60% | 中等，批量优化 | | 报告生成 | qwen-plus / gpt-4o | 20% | 关键，需高质量 | | 交互对话 | 用户选择 | 10% | 按需 | **混合策略总成本**：可降至纯 gpt-4o 的 **10-20%**，质量损失可控。 #### 8.2.3 缓存机制：重复查询的结果复用 **缓存层次**： | 层次 | 键 | 有效期 | 命中率场景 | |:---|:---|:---|:---| | 嵌入向量 | 文本内容哈希 | 永久 | 相同文本多次出现 | | LLM 响应 | (prompt, model, temperature) 哈希 | 会话级 | 相同情境重复决策 | | 图谱查询 | 查询模式 + 参数 | 轮次级 | 相似检索模式 | | 仿真结果 | 完整配置哈希 | 长期 | 相同参数重新运行 | ### 8.3 可观测性建设 #### 8.3.1 日志分级：DEBUG / INFO / WARNING / ERROR **分级策略**： | 级别 | 内容 | 生产启用 | |:---|:---|:---| | DEBUG | 详细执行流程、变量值、中间结果 | 否（性能考虑） | | INFO | 关键里程碑、状态变更、性能指标 | 是 | | WARNING | 非致命异常、降级处理、资源紧张 | 是 | | ERROR | 操作失败、数据不一致、服务异常 | 是（告警） | #### 8.3.2 健康检查端点：`/api/health` 服务状态 **健康检查维度**： - 服务存活：HTTP 响应状态 - 依赖就绪：LLM API、Zep/Neo4j、OASIS 可调用 - 资源充足：磁盘空间、内存使用、连接池状态 - 功能正常：关键路径的端到端测试 #### 8.3.3 仿真进度追踪：实时状态流与断点续传 **进度指标**： - 宏观：当前轮次 / 总轮次、预估剩余时间 - 中观：活跃智能体数、平台内容量、互动频率 - 微观：特定智能体的当前动作、关键事件触发 **断点续传**：定期序列化完整状态，支持从任意轮次恢复，便于长仿真管理和故障恢复。 --- ## 9. 扩展性与生态集成 ### 9.1 插件化架构 #### 9.1.1 资源适配器接口：自定义数据源接入 **适配器接口定义**（推测）： ```python class ResourceAdapter(ABC): @abstractmethod def connect(self, config: Dict) -> Connection: ... @abstractmethod def create(self, data: Dict) -> ResourceID: ... @abstractmethod def read(self, id: ResourceID) -> Dict: ... @abstractmethod def update(self, id: ResourceID, data: Dict) -> None: ... @abstractmethod def delete(self, id: ResourceID) -> None: ... @abstractmethod def query(self, criteria: Dict) -> List[Dict]: ... ``` **社区贡献的适配器**：Neo4jAdapter、KuzuAdapter、WeaviateAdapter（向量数据库）、MinIOAdapter（对象存储）。 #### 9.1.2 工具组合模式：工作流的声明式编排 **工作流定义示例**（YAML 风格）： ```yaml workflow: crisis_communication steps: - name: ingest tool: IngestTool input:\){uploaded_files}

• name: build tool: BuildTool input: \({ingest.output} params: {ontology: "crisis_communication"} - name: prepare tool: PrepareTool input:\){build.output} params: {agent_count: 2000, platforms: [twitter, reddit]}

• name: baseline tool: RunTool input: \({prepare.output} params: {rounds: 40, name: "baseline"} - name: intervention_a tool: RunTool input:\){prepare.output} params: rounds: 40 name: "early_response" events: [{at: 10, type: "official_statement", content: "..."}]

• name: compare tool: CompareTool input: [\({baseline.output},\){intervention_a.output}]

• name: report tool: ReportTool input: ${compare.output}

#### 9.1.3 平台扩展：新增社交场景仿真支持

**扩展方向**：
- **专业社区**：LinkedIn（职场）、GitHub（开发者）、Discord（兴趣社群）
- **垂直平台**：淘宝/京东（电商评价）、美团/大众点评（本地服务）、B站/YouTube（视频社区）
- **新兴市场**：TikTok/Douyin（短视频）、WhatsApp/WeChat（私域社交）

### 9.2 与 CAMEL-AI 生态的协同

#### 9.2.1 `camel-oasis` 版本锁定与兼容性管理

**当前依赖**：`camel-oasis==0.2.5`，版本锁定确保可复现性。

**升级策略**：跟踪 OASIS 上游更新，评估新特性（如新平台支持、性能优化、bug 修复）的集成价值，在测试环境验证后更新。

#### 9.2.2 `camel-ai` 编排能力的上层封装

**CAMEL-AI 生态的 broader 能力**：
- `camel-ai/camel`: 多智能体对话和协作框架
- `camel-ai/oasis`: 社交仿真（MiroFish 使用）
- `camel-ai/owl`: 网络操作学习
- `camel-ai/meme`: 记忆和知识管理

**封装策略**：MiroFish 专注于预测场景的产品化，底层复用 CAMEL 能力，上层添加领域特定的知识注入、报告生成、交互界面。

#### 9.2.3 上游更新追踪：社区贡献与漏洞修复

**协作机制**：GitHub Issues/PRs、Discord 社区、定期同步会议。

**关键关注**：安全漏洞（如依赖库 CVE）、性能回归、API 兼容性变更。

### 9.3 企业级定制路径

#### 9.3.1 私有部署：内网环境与数据安全

**部署模式**：

| 模式 | 架构 | 数据主权 | 适用场景 |
|:---|:---|:---|:---|
| 纯本地 | Ollama + KuzuDB/Neo4j | 完全 | 高度敏感数据、合规要求严格 |
| 混合云 | 本地仿真 + 云端 LLM API | 部分 | 平衡性能和成本 |
| 私有云 | 专属云实例 | 合同保障 | 大规模部署、SLA 要求 |

#### 9.3.2 领域适配：垂直行业的本体库构建

**行业本体示例**：

| 行业 | 核心实体 | 关键关系 | 典型预测场景 |
|:---|:---|:---|:---|
| 金融 | 资产、投资者、机构、政策 | 持有、交易、影响、监管 | 市场反应、风险传染 |
| 医疗 | 疾病、药物、医生、患者 | 诊断、治疗、副作用、传播 | 疫情演化、政策效果 |
| 能源 | 资源、设施、市场、政策 | 供应、消费、价格、转型 | 政策冲击、技术替代 |
| 教育 | 学生、课程、机构、就业 | 学习、评价、升学、就业 | 政策改革、技术影响 |

#### 9.3.3 人机协同：专家知识注入与结果校验

**协同模式**：

| 阶段 | 专家角色 | 系统支持 |
|:---|:---|:---|
| 准备 | 审核种子材料、调整本体论、校准人格参数 | 可视化编辑、版本对比、影响预览 |
| 执行 | 监控仿真进展、注入关键事件、调整参数 | 实时仪表板、异常告警、快速干预 |
| 分析 | 解读报告发现、验证关键结论、识别盲点 | 钻取探查、对比分析、证据追溯 |
| 决策 | 综合仿真结果和业务判断，制定行动 | 情景对比、效果预测、风险评估 |

**持续学习**：专家反馈（标注、修正、扩展）回流到系统，改进本体论、人格模板、报告生成模型。