MiroFish 项目分析

2. 结论先行

2.1 对笔记目标的回答

MiroFish 不是一个经过统计校准的通用预测算法，而是一套“材料抽取 → 云端知识图谱 → 角色与事件配置 → 双社交平台 LLM Agent 演化 → 图谱检索式报告”的完整应用工作流。项目自述（约第 14-64 行）使用“预测万物”“高保真平行世界”等强表述，但源码没有历史回测、误差度量、置信区间、基线模型或预测准确率评测。因此，它更适合被定义为叙事型情景推演沙箱，不应被定义为可直接支撑高风险决策的预测系统。

四个关注点的成熟度并不相同：

2.2 明确决策

引入结论：暂不建议整套直接引入生产系统。 主要阻断项不是“代码量大”，而是标准主流程的报告/访谈状态矛盾、报告证据与模拟行动之间缺少直接可审计链路、展示配置未真正驱动模拟、随机过程不可复现、无认证及不安全富文本渲染，以及 Zep Cloud 绑定与 AGPL-3.0 义务。若目标是内部、低风险、非敏感材料的概念验证，可在隔离环境中建议局部引入图谱写入编排与五步工作流原型，但必须先通过第 12 节的门槛。

参照结论：建议仅作设计参照。 优先参照五步任务分解、图谱/工作台并置、长任务进度与日志反馈、云端写入的幂等标识/模糊结果对账、报告生成前的资源生命周期屏障；不要照搬“预测”产品表述、未接线的平台配置、图谱事实与模拟事实混写方式，以及前端正则 Markdown 转 HTML 的实现。

2.3 专题解析导航

三个重点机制都跨越多个模块，需要原始类名、方法名、调用链和源码片段才能完整说明，因此从主报告拆出以下专题；主报告仍是结论和导航的唯一入口。

2.4 关键类与方法总览

下表保留原项目符号名。中文说明用于解释职责，不能替代原始类名或方法名；本地链接打开锁定源码文件，固定提交链接提供稳定行级定位。

3. 系统架构与责任边界

以下为基于入口、服务调用和持久化位置还原的架构。它说明一份材料如何跨越前端、后端、三类外部模型服务和本地文件系统。

3.1 入口与模块边界

• 应用工厂（约第 19-74 行）创建后端应用、启用跨域并注册图谱、模拟和报告三组接口；这三组接口是业务边界，不是独立部署的服务。
• 图谱接口（约第 266-766 行）负责上传、解析、本体生成、图谱构建/恢复以及项目状态迁移；真正的云端图谱操作下沉到图谱构建服务（约第 61-733 行）。
• 模拟管理器（约第 128-440 行）负责准备阶段和模拟元数据；模拟运行器（约第 371-765 行）负责子进程、运行状态、日志读取与结束屏障；双平台脚本（约第 1492-1649 行）持有实际 OASIS 环境。
• 报告接口（约第 32-286 行）只允许完成/停止且图谱写入已排空的模拟进入报告；报告代理（约第 871-1810 行）负责规划、检索、逐章生成和落盘。
• 前端路由（约第 9-44 行）把流程拆成项目、环境、运行、报告、交互五个页面；主处理页和运行页维持图谱与工作台的左右并置。

3.2 持久化边界

4. 技术栈、依赖与版本影响

版本以清单约束和锁文件为准；“锁定”表示当前提交解析出的版本，而不是对未来兼容性的保证。

5. 材料驱动的图谱构建

5.1 实际数据流

1. 本体生成接口（约第 266-446 行）接收 PDF、Markdown 或文本文件及模拟需求，创建项目、保存原文件、抽取并预处理文本。
2. 本体生成器（约第 48-201、203-463 行）让 LLM 输出社会舆情模拟所需实体类型、属性和关系。本体不是从预设数据模式或专家规则推导，而是模型生成后再做名称、字段和数量归一化。
3. 长文本最多取 50,000 字符；抽样实现（约第 270-370 行）先按 8,000 字符、200 字符重叠切分，再最多等距选择 60 个片段。因此它覆盖首中尾，但不是语义摘要，也不保证关键小段一定入选。
4. 图谱构建接口（约第 448-766 行）按项目锁检查状态、恢复已有批次或发起新构建；文本处理器负责句界和重叠分块。
5. 图谱构建服务（约第 218-609 行）创建图谱、把 LLM 本体动态转换为 Zep 可接受的数据模型、写入文本事件，并等待所有条目与图谱事件处理完成。

5.2 值得参照的工程点

• 写入操作建立确定性的业务操作标识、分块内容摘要和批次元数据；对超时或响应含糊的写入不盲目重试，而是先查询云端状态进行对账。固定提交证据显示这套策略专门避免重复图谱事件。
• 图谱删除、重建、报告读取和模拟记忆写入共享生命周期锁与 reader 注册，避免报告生成中图谱被替换。报告启动屏障（约第 159-286 行）是可复用的长任务资源租约模式。
• 项目把“上传完成”“本体完成”“批次写入”“云端处理完成”分成明确状态，前端也按这些阶段展示；这比一个模糊进度条更利于排错。

5.3 语义与实现限制

• 提示词要求“恰好 10 个实体类型”，但校验逻辑（约第 432-564 行）主要执行上限截断，并在缺失时补人物/组织兜底类型；如果模型只返回少量类型，并不会补齐到 10 个。这是提示承诺与执行约束不一致。
• 本体提示强绑定“社交媒体舆情模拟”和可发言实体，不是通用知识建模；迁移到供应链、科研或工业场景时不能原样使用。
• 图谱创建和检索均依赖 Zep Cloud；没有本地图数据库适配层。替换服务会牵动本体、写入、搜索、生命周期和报告工具，不是简单换 SDK。
• 输入材料、抽取事实和后续模拟活动最终可进入同一图谱。尽管模拟图谱事件的元数据带有来源、模拟编号、平台等字段，活动文本转换（约第 25-91 行）本身没有醒目的“假设/模拟”限定，报告检索也未见按来源过滤，存在事实污染风险。

6. 多 Agent 情景模拟运行时

6.1 从实体到 Agent

模拟准备流程（约第 244-440 行）先从 Zep 读取带定义类型的实体及关系，再由人设生成器（约第 205-983 行）并行调用 LLM 生成社交账号、性格、职业、立场等字段；失败时会生成随机回退人设。随后配置生成器（约第 53-405 行）生成时间、事件、初始帖子和每个 Agent 的活动频率/影响力/立场配置。

这条链路的核心假设是“材料中的实体可以转化为可行动主体”。它适合舆情、组织行为或故事演化，但对于抽象概念、指标、设备、法规条款等非主体实体，最终仍要靠 LLM 转写或回退，保真度没有客观校验。

6.2 运行模型

• 活动 Agent 选择（约第 1040-1083 行）按时段、活动水平、平台基数和随机抽样决定每轮参与者；没有看到随机种子持久化或注入。因此同一材料、同一配置也无法保证重放一致。
• 双平台主循环（约第 1579-1589 行）通过并发协程同时运行 Twitter 与 Reddit，但两者分别创建环境、Agent 图、SQLite 数据库和行动日志。它们共享初始人设/事件，却不是一个能跨平台传播状态的统一社交网络。
• 每轮由 CAMEL/OASIS 的大模型行动节点生成行为，再从数据库读取真实落地动作并追加到行动日志；运行监视器（约第 620-830 行）每两秒读取增量、更新状态，并可把成功且非空闲的行为提交给图谱写入器。
• 标准前端启动参数（约第 382-425 行）强制双平台重启，并显式开启图谱记忆更新；API 自身的默认值则是关闭。这意味着“报告能否看到模拟活动”取决于调用入口，接口语义并不一致。

6.3 配置接线缺口

平台配置模型（约第 131-145、339-372 行）生成并在第二步界面展示时效性、热度、相关性、病毒传播阈值和回音室强度。全仓库静态检索显示，这些字段只出现在配置生成、配置摘要和前端展示中；实际双平台脚本没有读取它们。因此它们目前是展示性配置，不是运行时控制量。这会让用户误以为自己在观察某种推荐算法或回音室强度的效果。

6.4 记忆写回的价值与风险

图谱记忆写入器（约第 213-560 行）以 5 条为一批，把行动转成自然语言图谱事件并等待云端处理；终态只有在已接受写入全部排空后才发布。这个“终态屏障”很扎实，能防止报告读取到半完成图谱。

但语义层面存在反向风险：推演生成的帖子、点赞、关注等假设行为会与原材料事实共用图谱。元数据虽然保留来源，报告工具的搜索接口却没有显式按来源与模拟编号过滤，也没有在输出中强制展示图谱事件的来历。若重跑时复用图谱，还可能累积不同运行的模拟事实。对于决策系统，必须把原始事实、模型推断、模拟事件分成可查询的命名空间，并让报告逐条显示来源。

7. 未来推演与报告证据链

7.1 报告如何生成

报告代理（约第 871-1060 行）采用 ReACT 结构，每节最多 5 次工具调用、最多 3 轮反思。它可用的工具是深度洞察、全景搜索、快速搜索和 Agent 采访；前三者都通过图谱工具服务检索 Zep，搜索使用交叉编码器重排。

大纲规划（约第 1176-1257 行）仅接收图谱统计、相关事实和实体类型；逐章生成（约第 1576-1745 行）把工具结果交给 LLM 并逐章落盘。对报告代理及其图谱工具的静态调用检索没有发现读取平台行动日志、平台 SQLite 数据库、行动时间线或 Agent 统计的路径。因此：

1. 标准前端开启图谱写回时，报告可能通过 Zep 间接检索到行动的自然语言 episode；
2. 其他 API 调用若未开启图谱写回，报告主要基于原始材料图谱和 LLM 合成，模拟本身几乎没有直接证据入口；
3. 即使写回开启，报告也没有行动 id、轮次、平台、原文和图谱事实之间的强制引用格式，无法从报告结论稳定追溯到具体模拟事件。

因此现有“预测报告”更准确的名称应是“基于材料图谱与可选模拟记忆的情景叙事报告”。在完成行动级引用、来源区分和多次运行统计之前，不应把单次 LLM 群体演化描述为概率预测。

7.2 标准主流程的状态矛盾（静态推断，需运行复现）

这是当前提交最严重的集成问题：

1. 模拟运行器命令启动并行脚本时没有传入“模拟后立即退出”开关；
2. 并行脚本默认在所有轮次结束后进入命令等待循环，以保留 OASIS 环境供访谈；
3. 运行监视器（约第 641-745 行）只有子进程退出后才发布完成/已停止终态并排空图谱写入；
4. 报告接口拒绝运行中、启动中和停止处理中状态，只接受完成或已停止；
5. 第三步组件（约第 93-102、440-463、645-679 行）虽然实现了停止方法，却没有在模板中绑定停止按钮；报告按钮又要求页面进入完成阶段，而该阶段只在收到终态或手动停止成功后到达；
6. 后端存在关闭环境接口（约第 2811-2859 行），但第三步标准页面没有调用它。

静态源码由此推断：正常网页路径在轮次结束后可能停留于“环境仍活着/运行态”，用户既看不到关闭按钮，也不能点击报告；若通过外部接口关闭环境进入报告，报告代理的采访工具又明确要求环境仍存活。采访工具（约第 1270-1391 行）与报告入口屏障因此互相排斥。实际行为必须用端到端运行确认，但在确认前应视为整套引入的阻断项。

8. 交互设计：可复用部分与问题

8.1 值得复用的设计

• 五步心智模型：建图、环境准备、模拟、报告、深度交互与后端真实阶段基本一致，用户知道当前产物和下一步门槛。前端路由和各步骤组件形成稳定的信息架构。
• 图谱与任务并置：图谱面板支持力导向图、缩放、关系标签开关、自环聚合、节点/边详情；运行页允许图谱、分屏、工作台三种布局。这种“对象状态 + 操作过程”并置比把图谱藏在独立页面更利于理解。
• 渐进式长任务反馈：环境准备组件分别展示人设、时间、事件、平台参数和准备日志；报告组件逐章显示大纲、工具调用和生成内容，能把长时间黑盒变成可观察过程。
• 双平台行动时间线：模拟组件（约第 1-285、492-589 行）同时显示轮次、模拟时间、行动数和增量事件卡片，且不强制自动滚动，便于回看。
• 交互后的细分任务：深度交互组件（约第 250-417 行）把报告问答、单 Agent 对话和多 Agent 问卷拆成不同模式，尤其“选择人群 → 提问 → 汇总”适合复用为情景研究工具。

8.2 交互风险

• 刷新即重跑：doStartSimulation()（强制重启模拟并开启图谱写回的启动函数）由 onMounted()（组件挂载钩子）直接调用；运行页刷新或重新进入会清理旧运行产物后重跑。对高费用、长时任务是破坏性默认行为。
• 展示与控制不一致：第二步平台参数看起来像可解释的算法设置，实际不可编辑且未被运行时读取；用户会形成错误因果认知。
• 关键关闭动作不可见：后端与父页面具备关闭/停止能力，第三步主模板未提供显式控制，导致第 7.2 节的流程断点。
• 不安全富文本渲染：报告模板和交互模板把 renderMarkdown()（报告页的 Markdown-to-HTML 函数）及交互页同类函数的结果通过 Vue 富文本指令注入；没有看到 HTML 转义或等价白名单清洗。模型/材料内容可形成存储型或反射型 XSS。
• 来源感知不足：图谱详情能显示 fact 和 episode，但用户界面没有明确区分“原材料事实”“LLM 推断”“模拟行动”。这种区别比节点颜色更重要。

9. 扩展性、可靠性与安全性

9.1 扩展点

• LLM 调用通过统一客户端走 OpenAI 兼容协议，模型和基础地址可配置；这是供应商替换点，但提示词、JSON 能力和 token 行为仍需适配。
• 人设与模拟配置由独立服务生成，理论上可替换；实际运行仍依赖 OASIS 的 profile schema 和动作枚举，因此不是完全解耦。
• 报告工具在工具定义（约第 925-1060 行）集中注册，增加新的行动统计、引用追踪或外部事实校验工具较直接。
• 图谱层没有抽象为多后端 repository；Zep 的实体/关系模型、搜索结果和 episode 生命周期渗透多个服务，是当前最大替换成本。

9.2 可靠性与并发

优点是图谱全量重建、报告读取、模拟写回都有锁或 reader 租约；云端写入避免无条件重试，并等待完成屏障。缺点是任务进度在内存、项目元数据是本地 JSON、模拟子进程表也主要在内存，服务重启或多实例部署时会出现状态投影与真实子进程/云任务不一致。18 个后端测试文件覆盖了较多 Zep 写入和终态屏障场景，但本次未执行；静态检索没有看到针对“等待访谈 → 关闭环境 → 生成报告”整条网页流程的测试。

9.3 安全、隐私和运维

10. 关键差异与风险优先级

11. 可参照的设计清单

建议吸收

1. 将长链路拆成可见产物：材料文本、本体、图谱、人设、事件/时间配置、行动时间线、报告章节。
2. 图谱与工作台并置，并让每个节点/关系可追溯到 episode；进一步加入来源类型和运行 id。
3. 云端写入使用业务幂等 id、内容 hash、模糊结果对账和处理完成屏障。
4. 报告逐章落盘、实时展示工具调用和生成进度，失败时允许从已完成章节恢复。
5. 把“单个角色访谈”和“群体问卷”作为推演后的研究工具，而不是混在普通聊天里。

不建议照搬

1. 把 LLM 生成的单次社会模拟包装成“预测万物”或“高保真未来”。
2. 让不可编辑、未接线的参数出现在界面中制造可控性错觉。
3. 让模拟事实进入材料事实图谱却不提供来源过滤和引用。
4. 页面挂载即 force 重跑长任务。
5. 用正则手写 Markdown 到 HTML 并直接进行富文本注入。

12. 若要做局部引入 PoC，必须通过的门槛

建议只在隔离环境、非敏感材料、受控模型配额下开展，按以下顺序验证：

1. 闭环门槛：从 5-10 个 Agent、两个平台、5 轮开始，证明轮次完成后可以保留访谈窗口、显式关闭环境、排空图谱写入、成功生成报告，且网页不需要外部 API 操作。
2. 证据门槛：报告中的每个核心结论必须能跳转到原材料 episode 或具体 action id；原始事实、模型推断、模拟事实具有不同视觉与查询命名空间。
3. 可复现门槛：固定材料、模型、提示、依赖和 seed，重复至少 5 次；报告共同趋势、方差和异常运行，禁止只展示一次故事线。
4. 机制门槛：改变活动率、推荐权重、回音室强度时，确认运行脚本实际读取并产生可测试差异；未接线字段从 UI 删除。
5. 安全门槛：补认证/项目隔离、跨域白名单、秘密校验、上传扫描、HTML 清洗、操作审计和资源限额。
6. 恢复门槛：在建图、模拟、图谱写入和报告生成各阶段重启后端，验证任务不会丢失、重复写入或污染旧运行。
7. 容量门槛：分别测试 10/40/100 个 Agent 的时间、token、Zep episode、失败率和费用；把配额耗尽列为预期故障路径。
8. 合规门槛：确认材料可发送到配置的 LLM/Zep 区域，并完成 AGPL-3.0 的网络服务与修改分发义务审查。

只有第 1、2、5、8 项全部通过，才值得讨论“建议局部引入”；若目标是高风险政策、金融、医疗或法律决策，还必须增加领域回测、偏差评估和人类审核，现有源码不能直接满足。

13. 未验证项与证据边界

• 未执行安装、构建、测试或运行；第 7.2 节的主流程断点、XSS 可利用性、服务重启行为均为静态源码推断，需要在隔离环境复现。
• 未调用真实 LLM、Zep Cloud 或 OASIS，无法评价抽取准确率、图谱一致性、Agent 行为质量、跨平台差异、报告事实性和费用。
• 未发现预测数据集、回测脚本、统计基线、置信区间或准确率指标，因此不能从仓库证明“预测”能力。
• 未做大规模图谱和多 Agent 性能测试；前端 D3 大图、SQLite 并发、云端配额和长任务超时上限均待测。
• 外部固定提交页的自动抓取器未成功缓存；本报告的本地相对源码链接已按锁定提交检查，固定 GitHub URL 由仓库、提交和路径机械构造，仍建议在交付环境中人工抽点。

14. 主要证据索引