微舆 BettaFish
从社媒、网页和私有数据中研究舆情，并生成交互式分析报告。
证据展示了部分安全意识：数据库工具被描述为只读，依赖被集中列出，自动化工作流使用最小化权限、临时凭据、路径白名单、提交校验和人工合并。扣分在于这些保护主要见于辅助自动化，而核心产品会访问搜索、LLM、数据库、爬虫及多个平台，却没有完整的数据流图、数据保留与脱敏规则、用户逐项确认机制、产品级回滚方案或明确的外部写入边界。示例数据库使用公开的固定弱密码，依赖中大量使用无上界的 >= 范围，且没有锁文件、漏洞扫描或供应链缓解证据。仓库名称和联系邮箱提供了有限归属线索，但发布者身份及完整维护主体并未得到确认。
架构、目录树、工作流和测试夹具共同表明项目具备模块化处理、重试、依赖检查、JSON修复及错误日志设计；错误样例也区分了解析失败、修复失败和一般异常，因此失败消息获得较好但非满分评价。扣分在于 README 的平台覆盖数量前后出现“30+”“10+”等不一致，文档所列 tests/run_tests.py 声称运行所有测试却只手工运行 TestLogMonitor，且大量第三方 API、浏览器、数据库、模型和系统级 PDF 依赖增加可用性风险。未因缺少执行结果而扣除本应由运行验证的项目。
README 清楚面向舆情分析用户和开发者，描述对话式研究、独立 Agent 应用、金融场景改造、OpenAI 兼容模型、PostgreSQL/MySQL、Docker及三大桌面操作系统，环境适配证据较充分。扣分在于能力边界主要以宣传性表述呈现，没有清楚限定支持的平台功能、数据可达性、预测适用条件或私有数据约束；触发方式虽是自然语言查询，但缺乏歧义处理、任务拒绝、敏感用途或高影响决策的触发规则。
双语 README、架构流程表、详细目录树、快速开始、源码启动提示、示例报告、视频和贡献文档构成了很强的信息架构，安装资料也覆盖 Docker、数据库、Python 和操作系统。扣分在于提供的源码启动片段被截断且出现孤立的“c”，FAQ和集中式限制说明不充分；BettaFish、WeiYu/微舆及引出的 MiroFish 等名称并存，命名边界不够稳定。最严重的是 LICENSE 同时拼接 GPL-2.0、非商业学习许可证和 Apache-2.0 文本，彼此授权条件冲突，因而不能视为清晰有效的单一项目许可。README 有 v1.2.1 徽章，但没有给出变更日志证据；维护入口主要是仓库 issues、贡献文件和一个邮箱，责任主体及发布支持承诺仍不明确。
系统提供可交互 HTML、PDF、Markdown、IR、中间章节和多 Agent 汇总报告，并给出报告样例与完整流程，说明输出可用于阅读、复核和再渲染；搜索、私域分析、多模态、论坛协作和模板化报告的组合相较单一聊天输出具有合理增量价值。扣分在于质量与覆盖优势多为项目自述，未由所给材料中的系统性比较支撑；24 小时爬取、多 Agent 多轮 LLM、搜索 API、数据库、浏览器、机器学习模型和 PDF 栈可能带来显著费用与运维负担，而材料没有预算、速率限制、资源估算或降级策略。
目录与测试夹具为日志解析、报告验证及自动化提供了一些交叉证据，示例输出也偶尔列出笼统来源类别。关键扣分是生成内容没有逐条可追踪引用：测试夹具明确包含在搜索结果为空时仍基于“公开权威信息”和常识生成具体事实、数字及视觉推断的输出；另一个样例罗列大量精确财务、诉讼、评级和市场数据，却没有可解析的来源标识。材料也没有展示跨来源冲突解决方法，并将观察、模型推断、预测和想象性视觉描述混写，因此事实与推断分离不足。
- 在部署前人工核对 LICENSE：GPL-2.0、非商业学习条款与 Apache-2.0 被拼接在同一文件中，授权范围存在实质冲突。
- 不要将生成报告中的精确数字、引语、预测或视觉描述直接用于决策；现有样例显示系统可能在无搜索结果时继续生成未逐条引用的具体陈述。
- 使用真实密钥和私有数据库前，应更换示例数据库凭据，并明确第三方 LLM、搜索、抓取服务的数据发送、日志、保留和删除规则。
- 爬取社交平台前应单独确认平台条款、隐私、版权和适用法律；材料没有证明所有宣称平台均可被合规、稳定地访问。
- 生产使用前应锁定依赖、进行漏洞与镜像扫描，并为外部 API 失败、费用上限、速率限制和数据恢复制定措施。
这个 Agent 能做什么，适合哪些场景？
微舆是一个用纯 Python 从零实现的多智能体舆情分析系统，核心组件包括 QueryEngine、MediaEngine、InsightEngine、ForumEngine 和 ReportEngine。Flask 主应用接收自然语言研究问题后，并行运行网页搜索、多模态内容分析和私有数据库挖掘，再通过论坛主持人与多轮研究机制协调各分析智能体。MindSpider 可独立采集社交媒体话题、内容和评论，SentimentAnalysisModel 则提供多语言、BERT、GPT-2、Qwen3 及传统机器学习情感分析方案。ReportEngine 将各引擎结果装订为 Document IR，并输出交互式 HTML；具备相应系统依赖时还可生成 PDF 和 Markdown。项目支持 Docker Compose 或本地 Python 部署，模型调用采用 OpenAI 兼容接口，数据库可使用 PostgreSQL，源码说明也允许自行改为 MySQL。它更适合能够自行管理模型 API、数据库、爬虫合规性和运行环境的研究或工程团队，而不是无需配置的托管分析服务。
完整流程从 app.py 的 Flask 应用接收问题开始，同时启动 Query Agent、Media Agent 和 Insight Agent。QueryEngine 使用国内外网页及新闻搜索工具收集资料；MediaEngine 分析视频、图片和搜索结果中的结构化信息卡片；InsightEngine 通过 SQLAlchemy 异步只读查询、keyword_optimizer.py 和 sentiment_analyzer.py 检索私有舆情数据库、评论及情感信号。研究过程中，ForumEngine/monitor.py 监控智能体发言，llm_host.py 生成主持人引导，各智能体通过 utils/forum_reader.py 读取讨论、反思并调整搜索方向。随后 ReportEngine 选择 Markdown 模板、规划文档布局和篇幅、逐章生成并校验 JSON，再由 stitcher.py 组成 Document IR，最终渲染为交互式 HTML，并可导出 PDF 或 Markdown。MindSpider 还能通过 --broad-topic、--deep-sentiment 或 --complete 独立执行热点提取和社媒深度爬取。
- 品牌或高校研究人员需要汇总网页、社交平台内容及大量评论，形成品牌声誉或事件舆情报告。
- 拥有内部反馈数据库的分析团队，希望把私域业务数据与公开舆情放入同一套研究流程。
- 媒体研究者需要同时检查文字、图片、短视频以及搜索引擎结构化信息，而不只分析文本。
- 数据科学团队希望比较多语言模型、BERT、GPT-2、Qwen3 或传统机器学习方法在微博情感分析中的表现。
- 开发者需要一个不依赖现成 Agent 框架的 Python 多智能体项目，用于学习或定制搜索、论坛协作和报告生成流程。
- 报告工程人员已有三个分析引擎的 Markdown 输出，希望跳过重新研究，直接重试综合报告或重新渲染 HTML、PDF、Markdown。
这个 Agent 有哪些优点和局限？
- 搜索、多模态分析、私有数据库挖掘和报告生成由独立引擎负责，并通过 ForumEngine 的主持与讨论机制进行多轮协作。
- ReportEngine 使用经过校验的 Document IR，将模板选择、布局、篇幅、章节生成和 HTML/PDF/Markdown 渲染拆分为明确阶段。
- 模型层采用 OpenAI 兼容请求格式，各智能体可以分别配置 API_KEY、BASE_URL 和 MODEL_NAME，不限定单一模型提供商。
- 同时提供 Docker Compose、Flask Web 界面、单智能体 Streamlit 应用、独立爬虫命令和无 Web 的报告生成 CLI。
- 情感分析不只依赖大模型，还包含多语言模型、BERT LoRA、GPT-2 LoRA、小参数 Qwen3 和传统机器学习实现。
- 部署需要自行配置模型 API、数据库和浏览器驱动；完整功能并非单一二进制或零配置服务。
- 社媒爬虫必须遵守目标网站 robots.txt、服务条款和适用法律，项目明确把相关法律后果交由使用者承担。
- 项目声明仅用于学习、学术研究和教育，禁止商业用途，也禁止把分析结果用于商业决策或盈利活动。
- PDF 输出依赖 WeasyPrint 及额外系统组件；缺失时安装可能失败或 PDF 功能不可用。
- README 声称覆盖多个社媒与海量评论，但来源没有提供各平台当前可用性、速率限制、抓取稳定性或评测准确率的量化证据。
- 完整分析依赖外部网络、模型服务以及已配置的数据源，服务中断、配额不足或引擎输出缺失都会限制研究和报告生成。
如何安装或部署这个 Agent？
Docker 路径：复制 .env.example 为 .env，填写数据库连接以及所有智能体所需的模型 API 配置，然后在项目根目录运行 docker compose up -d，访问 http://localhost:5000。默认 Docker 数据库参数为 DB_HOST=db、DB_PORT=5432、DB_USER=bettafish、DB_PASSWORD=bettafish、DB_NAME=bettafish。
源码路径：准备 Windows、Linux 或 macOS、Python 3.9+、PostgreSQL 或 MySQL以及至少建议 2GB 内存。可运行 conda create -n your_conda_name python=3.11 和 conda activate your_conda_name，或运行 uv venv --python 3.11。随后执行 pip install -r requirements.txt 或 uv pip install -r requirements.txt，再执行 playwright install chromium。将 .env.example 复制为 .env，至少配置 DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME、DB_CHARSET、DB_DIALECT，并为 Insight、Media 等组件填写 API_KEY、BASE_URL 和 MODEL_NAME。所有模型端点必须兼容 OpenAI 请求格式。PDF 导出是可选功能，但需要额外安装 WeasyPrint 的系统依赖。
如何使用这个 Agent？
完整系统的首次调用方式是在已激活环境的项目根目录运行 python app.py，然后打开 http://localhost:5000，像聊天一样提交分析问题。也可以分别运行 streamlit run SingleEngineApp/query_engine_streamlit_app.py --server.port 8503、streamlit run SingleEngineApp/media_engine_streamlit_app.py --server.port 8502 或 streamlit run SingleEngineApp/insight_engine_streamlit_app.py --server.port 8501。
使用爬虫时先执行 cd MindSpider 和 python main.py --setup；热点提取可运行 python main.py --broad-topic，完整流程可运行 python main.py --complete --date 2024-01-20，指定平台的深度爬取示例为 python main.py --deep-sentiment --platforms xhs dy wb。
如果已有分析日志，可运行 python report_engine_only.py，或用 python report_engine_only.py --query "土木工程行业分析" 指定主题；--skip-pdf、--skip-markdown 和 --verbose 分别控制输出和日志。该工具要求 insight_engine_streamlit_reports、media_engine_streamlit_reports、query_engine_streamlit_reports 中至少一个目录存在 .md 报告。
常见问题
是否必须使用 OpenAI 官方模型？
可以直接用于商业舆情监控或商业决策吗？
必须先运行社媒爬虫才能生成报告吗？
支持哪些数据库？
PDF 生成失败时还能获得结果吗？
--skip-pdf 跳过 PDF；Markdown 也默认生成并可通过 --skip-markdown 关闭。