内容
# 量化研究工具
> **美国股票量化研究，构建于您的AI助手之中。**
> 通过 [MCP](https://modelcontextprotocol.io) 将其与 **Claude 或 Codex** 集成，询问任何股票代码 — 获取可解释的评级、关键水平和理由，然后在同一聊天中讨论。也可以作为一个命令行的CLI工具使用。
简体中文 | [English](README.md)
[](https://github.com/TingdeLiu/quant.ai/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
`quant.ai` 是一个面向 **美国股票** 的命令行量化研究工具包，适用于日常投资者。只需输入一个命令，即可获取可解释的评级、关键支撑/阻力水平以及背后的原因 — 所有这些都源自历史价格，完全离线友好，且无需券商账户。
> ⚠️ **仅用于研究** — **非投资建议**。它从不下达或建议下达实时订单。
> 默认输出为 **中文**；添加 `--lang zh` （或在 `quant-ai init` 中选择）即可切换到中文。
## 快速开始
```bash
pip install -e . # 或：pip install -r requirements.txt
quant-ai doctor # 环境自检（依赖 + 数据连接）
quant-ai analyze AAPL # 秒级评估一只股票
```
没有入口点？`python -m quant_agent analyze AAPL` 效果相同。
## 您将获得
<img src="assets/analyze-example.png" alt="quant-ai analyze AAPL 的实际输出" width="820">
`quant-ai analyze AAPL` 的实际输出 — **默认中文**，添加 `--lang zh` 即可切换到中文。评级范围从 **强烈买入** 到 **中立** 再到 **强烈卖出**。添加 `--output-dir` 即可导出 Markdown + JSON，或添加 `--chart` 即可生成 PNG图表。
## 在 Claude 或 Codex 中使用
主要功能 — 将 quant.ai 暴露为 [MCP](https://modelcontextprotocol.io) 服务器，让您的 AI 助手调用它：
```bash
claude mcp add quant-research -- python -m quant_agent.mcp_server
```
然后直接在您工作的同一个聊天窗口中询问：
> *"NVDA 的行情如何？"* · *"关注 TSLA。"* · *"我以 182.5 的价格买入了 15 股 AAPL — 跟踪它。"* · *"我的仓位表现如何？"* · *"生成今日的市场报告。"*
Claude（或 Codex）调用实际项目数据，显示量化分析结果，您可以直接在聊天窗口中讨论 — 无需单独的网站，无需复制粘贴。每日报告以 **您的持仓盈亏** 开头，并渲染为精致的 **HTML 文档**。请参阅 [手册](docs/manual_zh.md#集成到-claudemcp) （中文）以获取 Claude Desktop / Codex 配置的详细信息。
**让您的 AI 助手安装它** — 将以下内容粘贴到 Claude Code（或任何 AI CLI）中，它可以设置所有内容：
```text
安装 https://github.com/TingdeLiu/quant.ai 作为 MCP 服务器：
1. git clone https://github.com/TingdeLiu/quant.ai && cd quant.ai
2. pip install -e .
3. claude mcp add quant-research -- python -m quant_agent.mcp_server
4. 验证：`claude mcp list` 应该显示 quant-research ✓ 已连接
```
## 主要特点
- 🤖 **集成到您的 AI 助手中** — 主要功能。将内置的 MCP 服务器与 **Claude 或 Codex** 集成，询问 *"NVDA 的行情如何？"* 它从该项目中提取实际的量化分析结果，因此您可以在 **一次对话中查看分析结果并讨论**。大多数股票分析工具都是独立的网站 — 而这个工具嵌入在您已经在聊天的 AI 中。
- 💼 **通过聊天管理您的观察列表和持仓**。告诉 Claude *"关注 NVDA"* 或 *"我以 182.5 的价格买入了 15 股 AAPL"* — 它们在本地的 `data/portfolio.json` 中持久化，并在每次分析中自动折算，每日报告 **以您的仓位和未实现盈亏开头** （尽力而为的实时报价， fallback 到上次收盘价）。
- 🖼️ **可渲染的每日报告** — 市场简报以自包含的浅色/深色 HTML 文件形式提供，Claude 将其渲染为内联文档；Markdown 和 JSON 也会写入其他所有内容。
- 🎯 **零配置单股票分析** — `analyze AAPL` 返回评级、回报率、RSI、波动率、MA 位置、支撑/阻力水平和人类可读的原因。
- 🧩 **个性化观察列表** — `quant-ai init` 构建一个包含 **2/3 您自己的选择** （您关心公司 + 行业）和 **1/3 由引擎从更广泛的市场中发现** 的股票池。
- 🔬 **研究回测** — 截面信号（12-1 动量，20/50 趋势，1 个月反转，低波动），信号权重搜索，**滚动** 稳定性分析，以及 SPY 和等权重基准，以将 alpha 与 beta 分开。
- 📊 **本地仪表盘和每日市场报告** — 一个无需密钥的市场情报简报和交互式市场仪表盘，在本地提供。
- 🛡️ **安全设计** — 确定性信号 + 风险层，友好地在网络/数据错误时降级，仅纸上交易 — 永远不会提交真实订单。
## 每日市场报告和仪表盘
`quant-ai market-report` 生成每日美国股票研究报告 — 您的持仓盈亏（当设置时），市场概览，观察/高风险列表，按持有期限划分的量化选择，以及免费新闻头条 — 以 Anthropic 风格设计，以 HTML + 自包含文档 + Markdown + JSON 形式编写：
<img src="assets/market-report-example.png" alt="每日市场报告 — 您的持仓盈亏在报告开头" width="820">
`quant-ai serve-dashboard` （或 `write-dashboard`）渲染回测诊断 — 主要指标，警报，周期分解，风险检查，仓位和交易 — 带有内置的 **EN / 中文** 切换：
<img src="assets/dashboard-example.png" alt="本地仪表盘" width="820">
## 常用命令
| 命令 | 功能 |
| --- | --- |
| `quant-ai analyze AAPL MSFT NVDA` | 评估一只或多只股票 |
| `quant-ai analyze --file watchlist.txt` | 从文件中评估股票代码 |
| `quant-ai init` | 构建个性化观察列表（交互式） |
| `quant-ai analyze --watchlist` | 评估您的个性化观察列表 |
| `quant-ai run-backtest --config configs/default.yaml` | 运行研究回测 |
| `quant-ai market-report` | 生成每日市场情报报告 |
| `quant-ai serve-dashboard` | 启动本地仪表盘服务 |
| `quant-ai doctor` | 环境自检 |
## 工作原理
1. **数据** — 默认情况下，从 Yahoo Finance (`yfinance`) 获取每日 OHLCV，或本地 CSV/Parquet。缓存和验证。
2. **信号** — 截面，点时间滞后的因子，按每日 z-score。
3. **投资组合和风险** — 在仓位/换手/流动性限制下的确定性目标权重。
4. **评估** — 训练/验证/测试分割，滚动窗口，和基准相对指标（夏普比率，索提诺比率，卡尔玛比率，最大回撤，alpha/beta）。
5. **AI（可选）** — LLM 仅 **审查** 和 **叙述** 研究；它从不生成订单。当未设置 API 密钥时，fallback 到离线模板。
## 文档
- **完整手册（中文）：** [docs/manual_zh.md](docs/manual_zh.md) — 详细配置，回测/滚动，仪表盘 API，MCP 集成，输出文件。
- **更新日志：** [CHANGELOG.md](CHANGELOG.md) · **贡献指南：** [CONTRIBUTING.md](CONTRIBUTING.md) · **路线图：** [roadmap.md](roadmap.md)
## 测试
```bash
python -m pytest # 72 个测试，无网络依赖
python -m ruff check quant_agent tests conftest.py
```
## 免责声明
本项目 **仅用于量化研究和教育**。它分析历史价格并生成研究信号 — **非投资建议**，且 **不授权交易**。市场具有风险；您对自己的决策负责。
## 许可证
[MIT](LICENSE)
