• 1. 概述
• 2. 项目结构
• 3. 技术架构
• 4. 快速开始
• 5. 部署指南
• 6. 功能说明
• 7. 配置指南
• 8. 开发指南
• 9. 使用示例
• 10. 常见问题

---

AI搜学助手是基于 PydanticAI 框架构建的智能学习助手系统，能够自动收集、分析和总结网络学习资料，帮助用户快速理解和掌握各种知识概念。

• 快速学习新概念和知识
• 整理和梳理学习资料
• 技术文档和教程收集
• 知识点深入理解和讲解
• 学习资源汇总

• 自动化资料搜集与筛选
• 智能内容分析与分类
• 知识热度趋势分析
• 可视化知识讲解报告生成

---

ai_learning/
├── public/                      # 静态资源
│   ├── echarts/                # ECharts 图表库
│   ├── libs/                   # 工具库（html2canvas、html2pdf）
│   └── novnc/                  # noVNC 远程桌面库
├── src/
│   ├── backend/                # 后端服务（Python）
│   │   ├── requirements.txt    # Python 依赖
│   │   └── src/
│   │       ├── main.py         # 主程序入口
│   │       ├── agent.py        # Agent 逻辑
│   │       ├── analysis_standards.py  # 分析标准
│   │       └── event_queue.py  # 事件队列
│   └── frontend/               # 前端服务（Next.js）
│       ├── package.json        # Node.js 依赖
│       ├── next.config.ts      # Next.js 配置
│       ├── tsconfig.json       # TypeScript 配置
│       └── src/
│           ├── app/            # 应用页面
│           ├── components/     # React 组件
│           ├── hooks/          # 自定义 Hooks
│           └── lib/            # 工具库
├── publish.yaml                # 发布配置（应用中心）
├── src/s.yaml                  # 部署配置（Serverless Devs）
├── build.yaml                  # 构建配置
├── Makefile                    # 构建脚本
└── README.md                   # 项目文档

• 框架：PydanticAI
• 语言：Python 3.12
• 运行时：AgentRun（阿里云函数计算）
• 核心能力：集成 LLM、搜索工具、浏览器沙箱

• 框架：Next.js（React）
• 语言：TypeScript
• 运行时：阿里云函数计算（FC3 Custom Runtime）
• UI 组件：Bootstrap CSS + Material Design 原则
• 可视化：ECharts
• 远程桌面：noVNC

系统采用 Server-Sent Events (SSE) 实现前后端实时通信，确保用户能够实时查看 Agent 执行进度和状态更新。

SSE 连接建立流程：

事件推送流程：

关键文件说明：

• 后端 SSE 实现：src/backend/src/main.py (第 88-170 行)
• 事件队列管理：src/backend/src/event_queue.py
• 状态推送：src/backend/src/agent.py (第 680-695 行)
• 前端 SSE 客户端：src/frontend/src/hooks/useAgentState.ts

采用单 Agent 设计，该 Agent 具备多项能力：

• 信息检索能力（通过搜索工具）
• 数据分析能力（通过 Sandbox 环境）
• 自然语言理解与生成（通过 LLM）

Agent 在执行过程中会经历多个状态，每个状态对应不同的执行阶段。系统通过 SSE 实时推送状态更新，前端可以实时展示 Agent 的执行进度。

状态转换流程：

状态说明：

状态	说明	current_phase	发生时机
idle	空闲状态	-	Agent 初始化或任务完成后
collecting	收集中	"资料收集"	调用 collect_data 工具时
collected	收集完成	-	数据收集工具执行完成
analyzing	分析中	"数据分析"	调用 analyze_data 工具时
analyzed	分析完成	-	数据分析工具执行完成
writing	撰写中	"报告撰写"	调用 write_report 工具时
written	撰写完成	-	报告撰写工具执行完成
rendering	渲染中	"HTML 渲染"	调用 render_html 工具时
complete	完成	-	所有工具执行完成
error	错误	"错误"	任何阶段发生错误时

相关文件：

• 状态定义：src/backend/src/agent.py (OpinionState 类)
• 状态推送：src/backend/src/agent.py (push_state_event 函数)

系统数据从用户输入到最终输出的完整流转过程，展示数据在各阶段的转换和处理。

数据流转流程：

数据结构说明：

数据字段	类型	说明	生成阶段
keyword	string	用户输入的关键词	用户输入
raw_data	List[SearchResult]	原始搜索结果列表	数据收集
collected_data_summary	List[Dict]	数据摘要列表	数据收集
analysis.keywords	List[str]	提取的关键词列表	数据分析
analysis.sentiment_score	float	情感得分	数据分析
analysis.summary	string	分析摘要	数据分析
analysis.key_opinions	List[Dict]	关键观点列表	数据分析
report_text	string	报告文本	报告撰写
final_html	string	最终 HTML 报告	HTML 渲染

数据转换过程：

1. 搜索阶段：用户输入关键词 → 搜索引擎返回结果 → 存储为 SearchResult 对象
2. 收集阶段：从搜索结果中提取内容 → 生成摘要 → 存储到 raw_data 和 collected_data_summary
3. 分析阶段：LLM 分析原始数据 → 提取关键词、情感、观点 → 生成 AnalysisResult
4. 撰写阶段：基于分析结果撰写报告 → 生成 report_text
5. 渲染阶段：在 Sandbox 中生成图表 → 将文本和图表合并为 HTML → 生成 final_html
6. 展示阶段：通过 SSE 推送到前端 → 渲染为可视化报告 → 用户查看

• 支持主流大语言模型（用户可自选）
• 需要配置搜索 API 访问权限
• 需要 Sandbox 环境支持

---

• Node.js: >= 18.x
• Python: >= 3.12
• npm: >= 9.x
• Serverless Devs: >= 3.0.0

• 阿里云账号（已开通函数计算、日志服务、AgentRun）
• 阿里云 AccessKey（具有相应权限）

git clone https://github.com/devsapp/agentrun-template.git
cd ai_learning

cd src/backend
pip install -r requirements.txt

cd ../frontend
npm install

cd backend
python src/main.py

cd frontend
npm run dev

访问 http://localhost:3000 查看应用。

---

1. 注册并登录阿里云
2. 开通以下服务：
   • 函数计算（FC）
   • 日志服务（SLS）
   • AgentRun

1. 访问 AgentRun 模板市场
2. 点击"立即部署"
3. 填写配置参数：
   • 地域：选择部署地域（cn-beijing / cn-hangzhou）
   • 大语言模型：选择模型服务（建议 qwen3-max）
   • 模型名称：填写具体模型名称
   • 浏览器沙箱：选择浏览器沙箱模板
4. 点击"部署"按钮
5. 等待部署完成（约 2-5 分钟）
6. 部署完成后，访问提供的公网 URL

npm install -g @serverless-devs/s
s config add

编辑 src/s.yaml，设置以下变量：

vars:
  region: cn-hangzhou          # 部署地域
  agent_name: opinion_analysis # Agent 名称
  role: AliyunAgentRunDefaultRole  # 权限角色

cd src
s deploy

s info

cd src/frontend
npm run build

构建产物将输出到 src/frontend/out 目录。

---

资料采集模块

• 多源信息抓取（百科、知乎、B站、技术博客等）
• 关键词智能匹配
• 实时数据更新

分析处理模块

• 内容难度分析（入门/进阶/高级）
• 核心概念提取
• 知识结构梳理
• 学习价值评估

报告生成模块

• 结构化知识讲解文档
• 数据可视化图表
• 学习路径建议

1. 自主搜索：根据关键词自动检索相关学习资料
2. 智能分析：对海量资料进行内容分析和分类
3. 代码执行：在 Sandbox 中执行数据处理和可视化代码
4. 报告生成：自动生成通俗易懂的知识讲解报告

• 交互式界面：提供友好的用户交互界面
• 可视化展示：使用 ECharts 展示数据分析结果
• VNC 远程桌面：支持通过 noVNC 远程查看 Sandbox 环境
• 主题切换：支持浅色/深色主题切换
• 报告导出：支持导出为 PDF 格式

---

environmentVariables:
  PYTHONPATH: /code/python:/opt/python:/code:/code/python
  AGENTRUN_MODEL_NAME: '{{ modelServiceName }}'          # 模型服务名称
  MODEL_NAME: '{{ modelName }}'                          # 模型名称
  AGENTRUN_BROWSER_SANDBOX_NAME: '{{ browserTemplate }}' # 浏览器沙箱

environmentVariables:
  ENDPOINT: '${resources.opinion_analysis.output.agent.endpoints.0.url}'

参数	类型	默认值	说明
region	string	cn-hangzhou	部署地域（cn-beijing/cn-hangzhou）
role	string	AliyunAgentRunDefaultRole	权限角色
modelServiceName	string	-	大语言模型服务名称
modelName	string	-	模型名称（建议 qwen3-max）
agentRuntimeName	string	opinion_analysis	AgentRuntime 名称
browserTemplate	string	''	浏览器沙箱模板

模型配置

• 在 AgentRun 控制台选择适合的大语言模型
• 建议使用支持长上下文的模型以处理大量学习资料
• 可根据分析精度需求选择不同参数的模型

Sandbox 配置

• 启用 Sandbox 环境
• 配置允许的 Python 库（如 pandas、matplotlib）
• 设置执行时间和资源限制

---

backend/
├── requirements.txt          # Python 依赖
└── src/
    ├── main.py              # 主程序入口
    ├── agent.py             # Agent 逻辑
    ├── analysis_standards.py # 分析标准
    └── event_queue.py       # 事件队列

1. 在 agent.py 中定义新的 Agent 方法
2. 在 main.py 中注册新的路由
3. 在 requirements.txt 中添加依赖

pip install -r requirements.txt

frontend/
├── src/
│   ├── app/                 # 应用页面
│   │   ├── 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         # 类型定义

1. 在 src/components/ 中创建新组件
2. 在 src/app/page.tsx 中引入并使用
3. 添加相应的类型定义到 src/lib/types.ts

npm install <package-name>

cd src/frontend
npm run build

构建产物将输出到 src/frontend/out 目录。

cd src/backend
python -m pytest

cd ../frontend
npm test

---

场景 1：快速学习新概念

用户输入：帮我学习"机器学习"的基础知识

Agent 执行流程：

1. 使用搜索工具检索相关百科、教程、博客文章
2. 提取核心概念和知识点
3. 进行内容分析和难度评估
4. 在 Sandbox 中生成知识结构图表
5. 输出完整的知识讲解报告

输出示例：

# 机器学习知识讲解报告

## 概念简介
- 资料来源：20 条优质学习资料
- 难度等级：入门级
- 学习时长建议：2-4周

## 核心原理
1. 什么是机器学习
2. 监督学习与无监督学习
3. 常见算法介绍

## 应用案例
- 图像识别
- 自然语言处理
- 推荐系统

场景 2：技术文档整理

用户输入：帮我整理"React Hooks"的学习资料

Agent 执行流程：

1. 搜索 React Hooks 官方文档和优质教程
2. 提取常用 Hooks 的用法和示例
3. 生成代码示例和最佳实践
4. 输出结构化的学习文档

---

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

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

• 选择专门针对知识理解优化的模型
• 调整内容相关性阈值
• 启用深度分析模式

• 检查阿里云账号权限是否正确
• 确认 AccessKey 配置是否正确
• 查看日志服务获取详细错误信息

• 检查 ENDPOINT 环境变量是否正确设置
• 确认后端服务是否正常运行
• 检查网络配置和防火墙设置

• 通过阿里云日志服务（SLS）查看
• 使用 s logs 命令查看
• 在 AgentRun 控制台查看实时日志

1. 内容版权：收集的资料仅供学习参考，请尊重原创内容版权
2. 搜索配额：注意搜索 API 的调用限制
3. 结果时效性：部分技术内容会随时间更新，建议关注最新资料
4. 模型选择：不同模型对中文理解能力差异较大，建议测试后选择
5. 可视化限制：Sandbox 中的图表生成受资源限制，避免处理超大数据集
6. 资源限制：注意函数计算的 CPU 和内存限制，避免超时
7. 安全性：不要在代码中硬编码敏感信息，使用环境变量管理密钥

---

• AgentRun 官方文档
• Serverless Devs 文档
• PydanticAI 文档
• Next.js 文档

---

通过 AgentRun 控制台的可视化配置，无需编写代码即可快速部署和定制您的AI搜学助手。