内容
# Robinhood AI 投资组合副驾驶
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://nextjs.org/)
[](https://ai.pydantic.dev/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](https://myportfoliocopilot.com/)
**生产级别的AI投资组合副驾驶** - 连接Robinhood（或导入CSV/Excel），分析持仓与宏观背景，检测配置风险，并与**PydanticAI代理**聊天，支持**MCP工具**和**Gemini 2.5 Flash**。
> **PydanticAI + MCP + FastAPI**的参考实现：类型化只读工具，隔离的MCP服务器，SSE流式传输，跨会话内存，以及通过Logfire的OpenTelemetry。适用于构建代理金融科技或学习生产代理模式。
**在线试用：** [myportfoliocopilot.com](https://myportfoliocopilot.com/) - 创建免费账户，连接Robinhood或导入CSV，探索仪表盘，宏观脉搏和AI助手。
**本地部署：** `cp .env.example .env` → 设置 `GOOGLE_API_KEY` → `docker compose up --build` → 打开 http://localhost:3000
---
## 演示
**在线应用：** [myportfoliocopilot.com](https://myportfoliocopilot.com/)
三个核心界面的简短演示（每个剪辑不到30秒）。GitHub可靠地渲染README中的GIF；每个剪辑下都链接了MP4源。
### AI 投资组合助手
用日常英语询问关于持仓的问题。代理使用只读MCP工具访问实时投资组合数据。
[下载MP4](assets/demos/Clip_ai.mp4)
### 宏观脉搏
九个宏观指标，健康区，投资组合暴露分解和与您的持仓相关的AI评论。
[下载MP4](assets/demos/Clips_macropulse.mp4)
### 市场与AI新闻
市场头条和与投资组合相关的新闻，带有AI摘要和情绪标签。
[下载MP4](assets/demos/clip_market_ai.mp4)
---
## 为什么选择这个仓库
| 功能 | 您获得的内容 |
|---|---|
| **代理架构** | PydanticAI + FastMCP，带有10个只读投资组合工具和研究子代理 |
| **真实经纪人数据** | Robinhood MFA登录，CSV/Excel导入，交易聚合 |
| **投资组合智能** | 健康评分，板块集中度，ETF重叠，宏观暴露 |
| **可观察性** | LLM、MCP、SQL和HTTP的Logfire跨度 - 兼容OTel |
| **安全基线** | JWT注销，速率限制，Fernet加密，CSP/HSTS头部 |
## 架构
```mermaid
flowchart LR
subgraph client [Next.js 前端]
UI[仪表盘 / 聊天 / 宏观]
end
subgraph api [FastAPI 后端]
Auth[JWT身份验证]
Engine[投资组合引擎]
Agent[PydanticAI代理]
end
subgraph mcp [FastMCP服务器]
Tools[10个只读工具]
end
subgraph data [数据层]
PG[(PostgreSQL)]
RH[Robinhood / CSV]
FH[Finnhub / RSS]
end
UI -->|REST + SSE| api
Agent -->|流式HTTP| mcp
Tools --> PG
Engine --> PG
api --> RH
api --> FH
Agent -->|Gemini 2.5 Flash| LLM[谷歌AI]
```
---
## 功能
- **用户身份验证** - 注册，登录，电子邮件验证（6位OTP），密码重置，基于JWT的会话，具有无状态注销（`token_version`），bcrypt哈希和失败尝试后账户锁定。
- **账户删除** - 用户可以永久删除其账户和所有数据，确认对话框和级联清理。
- **Robinhood直接连接** - 使用`robin_stocks`进行两步MFA流程（SMS，电子邮件，TOTP，推送通知）。包括30秒倒计时，自动触发和内联状态反馈。
- **CSV导入** - 上传持仓CSV或Robinhood交易导出。自动检测Robinhood格式并运行聚合引擎，从买入/卖出/拆分/股息交易中计算持仓，实时价格来自Finnhub。
- **Plaid集成（仅后端）** - 适配器，端点和服务层已完成。前端Plaid Link小部件计划在未来版本中发布。
- **仪表盘** - 连接经纪商，持仓，未实现收益，现金余额，健康评分小部件，风险警报摘要和投资组合新闻情绪分解（风险/积极/中立计数，钻取）。
- **经纪商管理** - 连接，同步，断开或删除经纪商账户。加密令牌存储与Fernet。
- **投资组合健康评分** - 五个子评分（多样化，单一股票集中度，ETF重叠，波动性，费用效率）的综合0-100评分，带有每个因素的解释和改进建议。
- **分配风险检测** - 板块超重检测与标普500，单一股票集中度阈值（> 10%黄色，> 20%红色），ETF重叠检测。在警报页面和仪表盘小部件上显示。
- **市场页面** - 新闻标签，带有AI丰富市场摘要头条和最新发展。投资组合新闻标签，带有每只股票新闻，3个要点AI总结和情绪标签（风险/积极/中立）。来源聚合自Finnhub和11个免费RSS源（CNBC，路透社，雅虎财经，福布斯等）。
- **股票页面** - 可浏览的标普500 +用户持仓网格，实时报价，股票图标和拥有徽章指示器。股票详情视图，包含简介，报价，交互式价格图表（1D-MAX范围，悬停提示），关键统计数据，收益历史，公司新闻和AI分析（图表解释，新闻影响，持仓影响）。
- **宏观脉搏页面** - 九个宏观指标（VIX，10年期国债，CPI，标普500，美元指数，PMI，高收益利差，石油，波罗的海干散货指数），实时值，健康区和纯语言定义。投资组合宏观暴露分解，涵盖六个类别（增长，周期性，防御性，利率敏感性，商品链接，国际）。AI生成的宏观总结，将市场状况与用户特定持仓联系起来。
- **AI投资组合助手** - 完整的聊天界面，带有可调整的历史侧边栏，会话重命名/星标/归档，持久的多轮上下文（40条消息窗口），跨会话内存（最多25个提取的事实），流式SSE响应，基于MCQ的澄清问题和上下文建议的提示。由PydanticAI在谷歌Gemini 2.5 Flash上提供支持，投资组合数据通过FastMCP。包括用于股票筛选，基本面比较和板块分析的研究子代理。
- **浮动AI聊天小部件** - 可拖动的右下角聊天小部件，可从任何页面访问。页面感知建议的提示，新聊天按钮和展开到全视图链接。
- **可观察性** - 通过Pydantic Logfire进行全栈跟踪：LLM调用，MCP工具调用，SQL查询，HTTP请求捕获为结构化跨度。本地开发的控制台回落。
- **安全强化** - 速率限制（slowapi），CORS收紧，HTTP安全头部（CSP，HSTS，X-Frame-Options，Referrer-Policy，Permissions-Policy），输入验证，最大长度约束，分页，所有列表端点，有界TTL缓存，日志中PII的删除，时间安全的令牌比较，通用错误响应，非根Docker用户。
- **设置** - 个人资料信息，系统诊断，注销和账户删除（危险区）。
- **响应式UI** - Next.js 16，Tailwind CSS，shadcn/ui，暗/亮模式，保护路由，侧边栏+顶部栏布局，自定义错误页面（404/500）。
- **Dockerized开发环境** - `docker compose up --build`运行所有内容，带有绑定挂载，实现实时重新加载。
## 技术栈
- **后端**：Python，FastAPI，SQLAlchemy（异步），Pydantic，JWT，bcrypt，Fernet加密，slowapi（速率限制），Finnhub API，yfinance，异步RSS聚合
- **AI / 代理**：PydanticAI，谷歌Gemini 2.5 Flash（免费层，可互换），FastMCP（Streamable-HTTP传输），DuckDuckGo网络搜索，研究子代理，股票筛选器+基本面比较+板块性能工具
- **可观察性**：Pydantic Logfire（兼容OpenTelemetry），自动为PydanticAI，FastAPI，SQLAlchemy和HTTPX提供仪器
- **前端**：Next.js 16，React 19，TypeScript，Tailwind CSS，shadcn/ui，Zustand，TanStack Query，Recharts，react-markdown，服务器发送事件流
- **数据库**：PostgreSQL 16（UUID主键，JSONB，索引外键）
- **DevOps**：Docker，Docker Compose，并发（多进程开发），非根容器
## AI后端架构
- **LLM提供商** - 谷歌Gemini，通过谷歌AI Studio免费层（10 RPM / 250K TPM / 250 RPD on `gemini-2.5-flash`，无需计费）。设置`GOOGLE_API_KEY`和可选`GOOGLE_MODEL`。通过PydanticAI提供商无关。
- **代理框架** - PydanticAI。类型化，基于模式的代理，带有内置工具调用，流式传输和消息历史重放。
- **工具协议** - MCP（模型上下文协议）。投资组合工具位于单独的FastMCP进程中，通过Streamable-HTTP进行隔离。
- **投资组合工具（10）** - LLM仅看到此固定工具集；它不能直接写入SQL或访问DB。
- `get_holdings(limit)` - 按市值排序的当前持仓。
- `get_recent_transactions(limit)` - 最新交易，股息，费用。
- `get_cash_position()` - 最新现金余额。
- `get_performance_summary(period)` - 投资组合价值在1W / 1M / 3M / 6M / 1Y / ALL期间的变化。
- `get_position_for_symbol(symbol)` - 用户在单个股票中的仓位，权重%。
- `get_symbol_profile(symbol)` - 公司/基金简介（板块，行业，描述）。
- `get_symbol_quote(symbol)` - 最新价格，日涨幅%，成交量。
- `get_symbol_key_stats(symbol)` - 市值，市盈率，EPS，beta，52周范围，股息收益率。
- `get_symbol_earnings(symbol)` - 下一次盈利事件+历史EPS超出/未达预期。
- `get_symbol_candles_summary(symbol, period)` - OHLC摘要（非原始条形）用于趋势分析。
- **研究子代理** - 通过`research_and_analyze`工具委托进行深入分析：标普500股票筛选器，多股票基本面比较，GICS板块性能排名和DuckDuckGo网络搜索以获取定性背景。
- **用户内存** - 跨会话持久内存（每个用户最多25个事实）。注入系统提示以实现连续性。
- **MCQ澄清** - 当问题过于宽泛时，助手会询问结构化的多选题以澄清偏好。
- **用户范围** - 服务器端注入`user_id`作为MCP元数据通过`process_tool_calls`。LLM永远不会看到或伪造它。
- **仅读设计** - 没有公开写入工具。代理无法下单或更改账户状态。
- **聊天持久性** - `ChatSession.agent_history`存储序列化PydanticAI消息。每个回合重放最后40条消息。
- **流式传输** - SSE（`delta`/`done`/`error`事件）带有进度阶段（思考，分析投资组合，研究等）。
- **延迟构造** - 代理在首次使用时构建并 memoized。缺少`GOOGLE_API_KEY`仅导致assistant路由503。
- **传输安全** - FastMCP运行DNS反绑定保护和主机允许列表。MCP容器中不暴露任何端口。
## 可观察性（Pydantic Logfire）
- **捕获内容** - PydanticAI代理运行（模型，令牌，成本，持续时间），MCP工具调用，FastAPI请求，HTTPX调用，SQLAlchemy查询。后端和MCP服务器作为两个服务通过OTel跟踪ID链接。
- **隐私控制** - 默认PII擦除器激活。设置`LOGFIRE_SCRUB_PROMPTS=true`以删除用户问题和LLM提示。
- **控制台回落** - `LOGFIRE_CONSOLE=true`在开发环境中将跨度打印到stdout。
- **零配置模式** - 空的`LOGFIRE_TOKEN`运行Logfire作为本地noop。
- **未锁定** - 构建在OpenTelemetry上。通过OTLP导出器切换到Honeycomb / Datadog / Grafana Tempo。
## 安全
- **速率限制** - slowapi具有每个端点的限制（5/min注册，10/min登录，20/min AI查询）。当Redis不可用时，fallback到内存存储。
- **身份验证** - JWT，具有无状态注销的`token_version`。bcrypt密码哈希。5次失败尝试后账户锁定（5分钟冷却期，通过有界TTL缓存）。
- **HTTP头部** - CSP，HSTS，X-Frame-Options，X-Content-Type-Options，Referrer-Policy，Permissions-Policy。生产环境中的HTTPS重定向。
- **CORS** - 严格执行显式方法和头部。调试模式下的开发环境来源；生产环境中的单个`FRONTEND_URL`。
- **输入验证** - Pydantic的`max_length`在所有字符串字段上，查询的边界，缓存边界以防止内存耗尽。
- **错误净化** - 客户端的通用错误消息。无堆栈跟踪，无内部细节，无日志中的PII。
- **加密** - Fernet用于存储经纪人令牌。OTP和重置令牌的时间安全比较。
- **生产启动保护** - 如果机密是默认值，调试开启或前端URL不安全，则拒绝启动。
- **Docker** - 后端和前端容器中的非root `appuser`。`.dockerignore`排除`.env`文件。
## 运行应用程序
在**myportfoliocopilot.com**上尝试托管版本（无需设置）。要本地运行或自行托管：
### 1：Docker（推荐）
1. 安装并启动 [Docker Desktop](https://www.docker.com/products/docker-desktop/)。
2. 复制`.env.example`到`.env`并配置。至少设置`GOOGLE_API_KEY`（https://aistudio.google.com/apikey）。
3. 构建并启动：
```
docker compose up --build
```
4. 打开：
- 前端：http://localhost:3000
- 后端API：http://localhost:8000
- Swagger文档：http://localhost:8000/docs
5. 源代码绑定挂载 - 编辑文件，变化自动反映。
6. 停止：`docker compose down`
### 2：本地开发
1. 安装Python依赖项：
```
pip install -r requirements.txt
```
2. 安装前端依赖项：
```
cd frontend && npm install
```
3. 复制`.env.example`到`.env`并配置。设置`DATABASE_URL`，`MCP_SERVER_URL=http://localhost:8765/mcp`和`GOOGLE_API_KEY`。
4. 启动PostgreSQL：
```
docker compose up -d postgres
```
5. 启动所有三个服务（后端8000，MCP 8765，前端3000）：
```
cd frontend && npm run dev
```
FastAPI，FastMCP和Next.js同时运行，带有彩色日志。`Ctrl+C`停止所有。
## 项目结构
```
app/
main.py # FastAPI入口，中间件，异常处理程序
config.py # Pydantic Settings来自.env
auth/ # 注册，登录，电子邮件验证，JWT，密码重置
broker_integrations/ - Robinhood，Plaid，CSV适配器，同步，仓位，交易
portfolio_engine/ - 投资组合健康计算，风险检测
stocks/ - 股票宇宙，详情，蜡烛，AI分析，新闻
markets/ - 市场新闻（RSS + Finnhub），投资组合新闻，AI摘要
macro/ - 宏观脉搏指标，暴露评分，AI摘要
ai_agent/ - PydanticAI助手，研究子代理，内存，提示
mcp_server/ - FastMCP工具服务器（仅读投资组合数据）
chat/ - Chat会话CRUD，消息持久性
database/ - SQLAlchemy引擎，ORM模型
utils/ - 日志，安全，加密，缓存，可观察性
frontend/
src/app/ - Next.js页面（仪表盘，市场，股票，宏观脉搏等）
src/features/ - 功能模块（auth，ai，stocks，market等）
src/components/ - 共享UI组件（布局，投资组合，视觉反馈）
```## 链接
- **Live app:** https://myportfoliocopilot.com/
- **源码：** 本仓库
- **许可证：** MIT
