• 快速开始
• 项目概述
• 技术架构
• 项目结构
• 安装与配置
• 开发指南
• API 接口
• 功能说明
• 使用示例
• 部署指南
• 常见问题

---

确保您的系统已安装以下工具：

• Python 3.12+
• Node.js 18+
• npm 或 bun
• uv (Python 包管理器)

# 1. 克隆项目
git clone https://cnb.cool/XMZZUZHI/AgentRun/opinion_analysis.git
cd opinion_analysis

# 2. 安装依赖
make install

# 3. 配置环境变量
# 编辑 src/backend/.env 文件，添加必要的配置

# 4. 启动开发环境
make dev

# 访问 http://localhost:8000

make verify

---

舆情分析专家是一个基于 PydanticAI 框架构建的全栈智能舆情分析系统，采用前后端分离架构，能够自动收集、分析和总结网络舆情信息，为企业和组织提供实时的舆情监测和分析服务。

• 🚀 实时状态推送：基于 SSE 的实时 Agent 状态同步
• 📊 智能情感分析：自动识别正面/负面/中性舆情
• 🔍 多源信息采集：支持新闻、社交媒体、论坛等多渠道
• 📈 数据可视化：集成 ECharts 生成趋势图表和词云
• 🎨 现代化 UI：基于 Next.js 15 + Tailwind CSS 的响应式界面
• 🌐 浏览器集成：支持 Browser Sandbox 实时预览
• 📝 报告导出：支持 PDF 和图片格式导出

• 品牌声誉监测与管理
• 危机预警与舆情监控
• 竞品分析与市场调研
• 公众意见收集与分析
• 社交媒体舆情追踪
• 产品反馈分析

---

架构说明：

• 前端层：基于 Next.js 15 + React 19，提供用户交互界面
• 后端层：基于 FastAPI + PydanticAI，处理业务逻辑和 Agent 执行
• 外部服务：LLM API、搜索 API、Browser Sandbox 提供核心能力
• 通信协议：
  • 前后端：AG-UI 协议（基于 HTTP SSE）
  • 浏览器控制：CDP（Chrome DevTools Protocol）

• 框架：Next.js 15.3.2 (React 19)
• 语言：TypeScript 5
• 样式：Tailwind CSS 4
• UI 组件：自定义组件
• 图表库：ECharts
• 其他：
  • @ag-ui/client - AG-UI 协议客户端
  • @novnc/novnc - VNC 客户端
  • html2canvas - 截图导出
  • html2pdf - PDF 导出

• 框架：FastAPI + Uvicorn
• Agent 框架：PydanticAI
• 语言：Python 3.12
• 包管理：uv
• 核心依赖：
  • pydantic-ai-slim - PydanticAI 核心库
  • agentrun-sdk - AgentRun SDK
  • pandas - 数据处理
  • googlesearch-python - 搜索功能
  • logfire - 日志记录

• 前后端通信：AG-UI 协议 (HTTP SSE)
• 实时状态推送：Server-Sent Events
• 浏览器控制：CDP (Chrome DevTools Protocol)

---

opinion_analysis/
├── src/
│   ├── frontend/                 # 前端项目
│   │   ├── src/
│   │   │   ├── app/             # Next.js App Router
│   │   │   │   ├── layout.tsx   # 根布局
│   │   │   │   ├── page.tsx     # 首页
│   │   │   │   └── globals.css  # 全局样式
│   │   │   ├── components/      # React 组件
│   │   │   │   ├── OpinionDashboard.tsx  # 舆情分析仪表盘
│   │   │   │   ├── ThemeSwitcher.tsx     # 主题切换器
│   │   │   │   └── VncViewer.tsx         # VNC 查看器
│   │   │   ├── hooks/           # 自定义 Hooks
│   │   │   │   ├── useAgentState.ts      # Agent 状态管理
│   │   │   │   └── useTheme.tsx          # 主题管理
│   │   │   └── lib/             # 工具库
│   │   │       ├── const.ts     # 常量定义
│   │   │       └── types.ts     # 类型定义
│   │   ├── public/              # 静态资源
│   │   │   ├── echarts/         # ECharts 库
│   │   │   ├── libs/            # 第三方库
│   │   │   └── novnc/           # noVNC 库
│   │   ├── package.json         # 前端依赖
│   │   ├── next.config.ts       # Next.js 配置
│   │   ├── tsconfig.json        # TypeScript 配置
│   │   └── tailwind.config.js   # Tailwind 配置
│   │
│   └── backend/                 # 后端项目
│       ├── src/
│       │   ├── agent.py         # Agent 核心逻辑
│       │   ├── main.py          # FastAPI 主应用
│       │   ├── event_queue.py   # 事件队列管理
│       │   └── analysis_standards.py  # 分析标准
│       ├── requirements.txt     # Python 依赖
│       └── .python-version      # Python 版本
│
├── public/                      # 公共静态资源
├── Makefile                     # 构建脚本
├── build.yaml                   # 构建配置
├── publish.yaml                 # 发布配置
├── README.md                    # 项目文档
└── LICENSE                      # 许可证

组件说明：

• OpinionDashboard：主仪表盘组件，展示舆情分析结果
• ThemeSwitcher：主题切换组件，支持亮色/暗色主题
• VncViewer：VNC 查看器组件，用于 Browser Sandbox 实时预览
• useAgentState：管理 Agent 运行状态和 SSE 事件流
• useTheme：管理应用主题状态

---

• 操作系统：Linux / macOS / Windows (WSL)
• Python：3.12 或更高版本
• Node.js：18 或更高版本
• 内存：建议 4GB 以上
• 磁盘空间：至少 2GB 可用空间

# 安装 uv (Python 包管理器)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证安装
uv --version
node --version
npm --version

# 使用 Makefile 安装所有依赖
make install

# 或手动安装
cd src/frontend && npm install
cd ../backend && uv sync

创建 src/backend/.env 文件：

# LLM 配置
OPENAI_API_KEY=your_openai_api_key
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL=gpt-4o-mini

# 搜索 API 配置（可选）
SEARCH_API_KEY=your_search_api_key

# AgentRun 配置
AGENTRUN_API_KEY=your_agentrun_api_key

# 日志配置
LOGFIRE_API_KEY=your_logfire_api_key

make verify

cd src/frontend

# 启动开发服务器
npm run dev

# 访问 http://localhost:3000

cd src/backend

# 启动后端服务
uv run src/main.py

# 访问 http://localhost:8000

# 构建前端并启动后端
make dev

# 访问 http://localhost:8000

---

• 使用 TypeScript 编写所有组件
• 遵循 React Hooks 最佳实践
• 使用 Tailwind CSS 进行样式开发
• 组件命名使用 PascalCase
• 文件命名使用 PascalCase (组件) 或 camelCase (工具)

• 使用 Python 3.12+ 类型注解
• 遵循 PEP 8 代码风格
• 使用 async/await 处理异步操作
• 函数命名使用 snake_case
• 类命名使用 PascalCase

# 1. 创建功能分支
git checkout -b feature/your-feature

# 2. 开发功能
# 编辑代码...

# 3. 运行代码检查
make lint

# 4. 测试功能
make dev

# 5. 提交代码
git add .
git commit -m "feat: add your feature"

# 6. 推送代码
git push origin feature/your-feature

开发流程图：

流程说明：

1. 创建功能分支：从主分支创建新的功能分支
2. 开发功能：编写代码实现功能
3. 代码检查：运行 make lint 检查代码规范
4. 测试功能：运行 make dev 本地测试
5. 提交代码：使用规范的 commit message 提交
6. 推送代码：推送到远程仓库
7. 创建 PR：创建 Pull Request 进行代码审查
8. 合并分支：审查通过后合并到主分支

• 使用浏览器 DevTools 查看 Network 请求
• 检查 SSE 事件流
• 使用 React DevTools 查看组件状态

• 查看控制台日志输出
• 使用 print() 调试关键信息
• 检查事件队列状态

# 安装依赖
make install

# 启动开发环境
make dev

# 构建生产版本
make build

# 运行代码检查
make lint

# 验证环境配置
make verify

# 清理构建文件
make clean

# 发布到仓库
make publish

---

执行 Agent 分析任务，支持实时状态推送。

请求体：

{
  "run_id": "unique-run-id",
  "thread_id": "thread-id",
  "messages": [
    {
      "role": "user",
      "content": "分析最近一周关于某品牌的网络舆情"
    }
  ],
  "state": {
    "max_results": 50
  }
}

响应类型： text/event-stream

事件类型：

• RUN_STARTED - 任务开始
• STATE_SNAPSHOT - 状态快照
• RUN_ERROR - 任务错误
• RUN_FINISHED - 任务完成

示例响应：

data: {"type":"RUN_STARTED","threadId":"thread-id","runId":"unique-run-id"}

data: {"type":"STATE_SNAPSHOT","state":{"collected_count":10,"analyzed_count":5}}

data: {"type":"RUN_FINISHED","threadId":"thread-id","runId":"unique-run-id"}

SSE 通信流程：

事件类型说明：

• RUN_STARTED：任务开始，包含 run_id 和 thread_id
• STATE_SNAPSHOT：状态快照，包含当前采集数量、分析数量等
• RUN_ERROR：任务错误，包含错误信息
• RUN_FINISHED：任务完成，表示分析流程结束

获取 Browser Sandbox 的 VNC/Livestream URL。

响应：

{
  "available": true,
  "vnc_url": "ws://...",
  "livestream_url": "ws://...",
  "sandbox_id": "sandbox-id",
  "message": "VNC URL 获取成功"
}

获取所有可用的 Browser Sandbox 列表。

响应：

{
  "sandboxes": [
    {
      "sandbox_id": "sandbox-id",
      "status": "running"
    }
  ],
  "count": 1
}

获取指定 Browser Sandbox 的截图。

查询参数：

• sandbox_id - Sandbox ID（可选）

响应： image/png

---

• 多源信息抓取：支持新闻、社交媒体、论坛等多渠道
• 关键词智能匹配：基于 NLP 的关键词提取和匹配
• 实时数据更新：支持定时更新和增量采集
• 数据清洗：自动去重、过滤无效信息

• 情感倾向分析：自动识别正面/负面/中性舆情
• 热点话题提取：基于 TF-IDF 和关键词提取
• 传播路径追踪：分析信息传播路径和关键节点
• 影响力评估：基于传播范围和互动数据评估

• 结构化分析报告：自动生成 Markdown 格式报告
• 数据可视化图表：集成 ECharts 生成趋势图、词云等
• 趋势预测建议：基于历史数据预测未来趋势
• 多格式导出：支持 PDF、图片等格式导出

数据流说明：

1. 数据输入：用户输入查询、关键词和配置参数
2. 信息采集：从新闻、社交媒体、论坛等多渠道采集数据
3. 数据处理：数据清洗、关键词提取、情感分析
4. 深度分析：热点话题、趋势分析、影响力评估
5. 可视化：生成趋势图表、词云图、传播网络图
6. 报告输出：生成 Markdown 报告，支持 PDF 和图片导出

1. 自主搜索：根据关键词自动检索相关信息
2. 智能分析：对海量信息进行情感分析和分类
3. 代码执行：在 Sandbox 中执行数据处理和可视化代码
4. 报告生成：自动生成专业的舆情分析报告
5. 实时状态推送：通过 SSE 实时推送分析进度

状态说明：

• Idle（空闲）：Agent 初始化完成，等待接收用户请求
• Receiving（接收）：接收并解析用户请求
• Searching（搜索）：执行搜索任务，获取多源信息
• Collecting（采集）：收集和清洗数据，去重过滤
• Analyzing（分析）：进行情感分析和分类
• Processing（处理）：在 Sandbox 中进行数据处理
• Visualizing（可视化）：生成趋势图表和词云
• Reporting（报告）：生成 Markdown 格式的分析报告
• Completed（完成）：任务执行完成，返回到空闲状态
• Error（错误）：任务执行失败，记录错误信息

流程说明：

1. 用户输入查询：用户在界面输入分析需求
2. Agent 接收请求：后端接收并解析用户请求
3. 执行搜索任务：调用搜索 API 获取多源信息
4. 信息收集与清洗：去重、过滤无效信息
5. 情感分析与分类：识别正面/负面/中性舆情
6. 热点话题提取：基于 TF-IDF 提取关键词
7. Sandbox 数据处理：使用 pandas 进行数据分析
8. 生成可视化图表：使用 ECharts 生成趋势图和词云
9. 输出分析报告：生成 Markdown 格式的分析报告
10. 实时推送状态：通过 SSE 实时推送分析进度

---

本章节详细说明舆情分析系统的各种工作流程，包括用户交互、Agent 执行、错误处理和数据质量筛选。

流程说明：

1. 初始化：用户打开页面，组件加载依赖（html2canvas、html2pdf、noVNC）
2. 输入配置：用户输入关键词，可选配置最大采集数量（5-100条）
3. 开始分析：点击"开始分析"按钮，发送消息到后端
4. 数据收集阶段：自动切换到"浏览器"Tab，实时查看VNC预览和系统日志
5. 数据分析阶段：自动切换到"分析"Tab，显示情感分布、关键词、摘要等分析结果
6. 报告撰写阶段：继续在"分析"Tab，流式显示报告内容，自动滚动到最新内容
7. 报告展示阶段：自动切换到"报告"Tab，显示完整的HTML报告
8. 导出报告：可选择导出为PDF、PNG、Word或HTML格式
9. 重新分析：可选择重新输入关键词进行新的分析
10. 错误处理：显示错误信息，可选择重试或返回空闲状态

流程说明：

1. 初始化阶段：解析请求参数，创建事件队列，推送RUN_STARTED事件
2. 数据收集阶段（collect_data）：
   • 检查Sandbox模板是否存在，不存在则抛出错误
   • 创建Browser Sandbox实例，失败则抛出错误
   • 生成多平台搜索查询（新闻、微博、知乎等）
   • 连接Playwright CDP，获取browser和page
   • 循环执行搜索，直到收集到目标数量
   • 评估每个结果的相关性，只保留相关性 >= 0.3 的结果
   • 对高相关性结果进行深入抓取，获取详细内容
3. 数据分析阶段（analyze_data）：
   • 统计数据来源分布
   • 准备分析数据（前30条 + 详细内容）
   • 构建分析Prompt，包含数据样本
   • 调用LLM进行深度分析，流式输出分析进度
   • 解析JSON响应，失败则使用模板生成分析结果
4. 报告撰写阶段（write_report）：
   • 构建报告Prompt，包含分析结果
   • 调用Writer Agent，流式输出报告内容
   • 清理代码块标记，更新state.report_text
5. HTML渲染阶段（render_html）：
   • 转换Markdown为HTML
   • 生成ECharts配置（情感分布、热度趋势等）
   • 包装HTML模板，包含样式和脚本
   • 更新state.final_html

流程说明：

1. Sandbox相关错误：
   • 模板不存在：抛出SandboxTemplateNotFoundError，提示检查AGENTRUN_BROWSER_SANDBOX_NAME配置
   • 创建失败：抛出SandboxCreationError，记录具体失败原因
2. 网络相关错误：
   • 超时错误：增加重试计数，等待2秒后重试，达到最大重试次数则失败
   • 连接错误：直接失败，推送RUN_ERROR事件
3. 浏览器相关错误：
   • Sandbox已关闭：检测关闭模式，移除旧Sandbox，重新创建Sandbox
   • 页面操作错误：直接失败，推送RUN_ERROR事件
4. 数据相关错误：
   • 数据不足：生成补充查询（第N页/相关/资讯），继续搜索
   • 数据解析错误：直接失败，推送RUN_ERROR事件
5. LLM相关错误：
   • API调用失败：使用模板生成结果，降级处理
   • 响应解析错误：直接失败，推送RUN_ERROR事件
6. 未知错误：记录stack trace，推送RUN_ERROR事件

流程说明：

1. 基础筛选：
   • 中文关键词必须在结果中有中文内容，否则直接拒绝
   • 排除明显的无关网站（calculator、deepseek、chegg等）
2. 相关性评分：
   • 关键词完全匹配：基础分 +0.6
   • 部分匹配：字符/单词匹配率 >= 50%，得分 +0.4 * 匹配率
   • 匹配率 < 50%：直接拒绝
3. 加分项：
   • 时效性加分：包含"最新/今日/近日"等关键词，+0.1
   • 舆情加分：包含"评价/评论/讨论"等关键词，+0.1
   • 平台加分：包含"知乎/微博/豆瓣"等平台，+0.1
4. 减分项：
   • 广告减分：包含"广告/推广/优惠"等关键词，-0.2
   • 长度减分：内容过短（< 20字符），-0.3
5. 最终筛选：
   • 相关性得分 < 0.3：拒绝
   • 相关性得分 >= 0.3：保留
6. 详细内容抓取（仅针对高相关性结果）：
   • 打开详情页，等待页面加载
   • 根据平台类型提取详细内容（知乎、微博、新闻等）
   • 内容长度 > 50字符才保留
   • 限制内容长度，最多2000字符
   • 最多抓取3个详细内容段

---

用户输入：

分析最近一周关于"XX品牌"的网络舆情

Agent 执行流程：

1. 使用搜索工具检索相关新闻、微博、论坛帖子
2. 提取关键信息和评论内容
3. 进行情感分析和分类
4. 在 Sandbox 中生成趋势图表
5. 输出完整的分析报告

输出示例：

# XX品牌舆情分析报告（2024.XX.XX - 2024.XX.XX）

## 舆情概览
- 总信息量：1,250 条
- 正面舆情：65%
- 负面舆情：15%
- 中性舆情：20%

## 热点话题
1. 新品发布（热度：85%）
2. 售后服务（热度：45%）
3. 价格调整（热度：30%）

## 情感分析趋势
[趋势图表]

## 重点关注
- 发现 3 个潜在危机点
- 建议采取应对措施...

用户输入：

分析"竞品A"和"竞品B"的用户评价对比

Agent 执行流程：

1. 搜索两个竞品的用户评价
2. 提取评价关键词和情感倾向
3. 对比分析优劣势
4. 生成对比报告

用户输入：

监控"XX事件"的舆情发展，设置负面舆情阈值

Agent 执行流程：

1. 实时监控相关舆情
2. 计算负面舆情比例
3. 超过阈值时触发预警
4. 生成危机应对建议

---

流程说明：

1. 环境检查：验证系统是否满足最低要求（Python 3.12+、Node.js 18+）
2. 安装依赖：安装必要的工具（uv、Python、Node.js）
3. 克隆代码：从 Git 仓库克隆最新代码
4. 配置环境：创建并配置 .env 文件，设置 API 密钥等
5. 安装依赖：运行 make install 安装前后端依赖
6. 构建项目：运行 make build 构建生产版本
7. 测试验证：运行 make verify 验证配置正确性
8. 部署应用：使用 Docker 或传统方式部署应用
9. 配置代理：配置 Nginx 反向代理
10. 配置 SSL：可选，使用 Let's Encrypt 配置 HTTPS
11. 启动监控：配置 Logfire 日志监控
12. 最终测试：访问应用验证部署成功

# 构建生产版本
make build

确保生产环境的 .env 文件配置正确：

# LLM 配置
OPENAI_API_KEY=your_production_api_key
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL=gpt-4o

# 生产环境配置
ENV=production
LOG_LEVEL=warning

# 使用 Docker 部署（推荐）
docker build -t opinion-analysis .
docker run -p 8000:8000 --env-file .env opinion-analysis

# 或使用传统方式
uvicorn src.main:app --host 0.0.0.0 --port 8000 --workers 4

部署架构图：

部署说明：

• 负载均衡：使用 Nginx 作为反向代理和负载均衡器
• 容器化部署：使用 Docker 容器化应用，支持水平扩展
• 静态资源：前端静态文件由 Nginx 直接提供服务
• 外部服务：LLM API、搜索 API、Browser Sandbox 通过网络调用
• 数据存储：Redis 用于缓存和队列，数据库用于持久化存储（可选）
• 日志服务：使用 Logfire 收集和分析日志

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_cache_bypass $http_upgrade;
    }
}

# 使用 Let's Encrypt
certbot --nginx -d your-domain.com

• 使用多个 Worker 进程
• 启用连接池
• 配置缓存策略
• 优化数据库查询

• 启用静态资源压缩
• 配置 CDN 加速
• 优化图片加载
• 使用代码分割

import logfire

logfire.configure(
    send_to_logfire=True,
    api_key=your_logfire_api_key
)

• API 响应时间
• Agent 执行成功率
• 错误率统计
• 资源使用情况

---

解决方案：

• 在控制台优化搜索关键词设置
• 调整搜索范围和时间窗口
• 增加搜索深度获取更多结果
• 使用多个搜索源交叉验证

解决方案：

• 选择更高性能的模型
• 减少搜索结果数量
• 使用快速分析模式
• 启用缓存机制

解决方案：

• 选择专门针对情感分析优化的模型
• 调整情感判定阈值
• 启用深度分析模式
• 增加训练数据样本

解决方案：

• 检查后端服务是否正常运行
• 确认端口配置是否正确
• 检查防火墙设置
• 查看浏览器控制台错误信息

解决方案：

• 检查网络连接稳定性
• 增加超时时间配置
• 实现自动重连机制
• 检查代理服务器配置

解决方案：

• 确认 Sandbox ID 配置正确
• 检查 AgentRun API Key 是否有效
• 验证网络连接和防火墙设置
• 查看 Sandbox 状态是否为运行中

1. 数据隐私：确保不分析涉及个人隐私的敏感信息
2. 搜索配额：注意搜索 API 的调用限制
3. 结果时效性：舆情信息具有时效性，建议定期更新分析
4. 模型选择：不同模型对中文情感分析能力差异较大，建议测试后选择
5. 可视化限制：Sandbox 中的图表生成受资源限制，避免处理超大数据集
6. 成本控制：合理控制 LLM API 调用次数，避免产生过高费用
7. 安全防护：生产环境务必配置 SSL 和访问控制

---

• 文档：查看项目文档获取更多详细信息
• 问题反馈：通过 Issue 提交问题和建议
• 社区支持：加入社区讨论获取帮助

---

本项目采用 AGPL-3.0 许可证。详见 LICENSE 文件。

---

感谢以下开源项目的支持：

• Next.js
• PydanticAI
• FastAPI
• Tailwind CSS
• ECharts

---

通过 AgentRun 控制台的可视化配置，无需编写代码即可快速部署和定制您的舆情分析系统。