FinScope Pro

FinScope Pro是一套面向量化研究与投资分析的 AI 工作台。用户可以用自然语言创建研究任务，让数据智能体结合行情、财务指标与分析工具，完成个股诊断、基本面分析、资产对比、指数技术分析、组合风险评估和策略回测，并在统一界面中查看研究过程与结果。

本项目提供的是研究与分析工具，生成内容不构成任何投资建议。市场数据可能存在延迟或缺失，使用结果前请独立核验。

核心能力

模块	主要用途
AI 研究工作台	用自然语言创建任务，查看智能体思考过程、工具调用与研究结果
策略平台	查看股票池、K 线、板块资金流、因子目录与量化基础数据
研究报告	管理研究报告、洞察与自动化研究任务
数据服务	提供实时行情、历史 K 线、基本面、筛选与回测接口
技能管理	管理和版本化智能体的专业研究技能
评测平台	维护评测集、评测队列与模型效果验证
运维与可观测性	查看服务状态，并可选接入 Loki、Grafana 和 Alloy

技术架构

浏览器 / Electron 桌面端
          │
          ▼
 Next.js 16 + React 19
          │
    ┌─────┴──────────┐
    ▼                ▼
 PI Agent       行情数据 API
    │            (FastAPI)
    └─────┬──────────┘
          ▼
 TimescaleDB / Redis / ClickHouse（可选）

层级	技术
Web	Next.js 16、React 19、TypeScript、Tailwind CSS
智能体	PI Agent、可配置模型供应商
行情后端	Python 3.14、FastAPI、AkShare、BaoStock
数据存储	TimescaleDB/PostgreSQL、Prisma、Redis、可选 ClickHouse
桌面端	Electron
测试	Vitest、Pytest、Playwright

快速开始

1. 环境要求

开始前请安装：

• Node.js 22.19.0 或更高版本
• npm 10.0.0 或更高版本
• Docker Desktop（用于 TimescaleDB 和 Redis）
• uv（用于自动管理 Python 3.14 和行情服务依赖）

确认环境：

node --version
npm --version
docker --version
uv --version

2. 安装依赖并生成本地配置

在项目根目录执行：

npm install
npm run ensure:env

安装过程会依据 .env.example 创建或补全本地的 .env 与 .env.local。这两个文件可能包含密钥，不要提交到 Git。

3. 配置模型

打开 .env.local，至少配置一种可用的模型凭证。推荐使用项目默认的 ModelPort 模式：

MODELPORT_API_KEY="你的 API Key"

如不需要长期记忆服务，可在本地开发时关闭：

QUANTPILOT_MEMORY_ENABLED=0

完整配置项及默认值请参考 .env.example。切勿把真实密钥写入示例文件。

4. 启动基础服务并初始化数据库

确保 Docker Desktop 正在运行，然后执行：

npm run db:up
npm run db:init

默认启动的服务如下：

服务	默认地址	作用
Web	http://localhost:3000	主应用
Market API	http://127.0.0.1:8000	行情与量化数据接口
TimescaleDB	127.0.0.1:35433	业务与时序数据
Redis	127.0.0.1:36380	缓存与任务协调

5. 启动应用

npm run dev

该命令会启动 Web 应用，并在启用行情能力时自动启动 Market API。终端显示服务就绪后，访问：

http://localhost:3000

若只调试 Web 界面，可运行：

npm run dev:web

若希望使用桌面端开发模式，可运行：

npm run dev:desktop

用户使用步骤

1. 打开工作台：访问 http://localhost:3000，进入首页。

2. 检查设置：在“设置”中确认模型与所需服务可用；首次使用建议先运行 npm run doctor。

3. 选择研究能力：根据任务选择个股诊断、基本面分析、资产对比、指数技术分析、组合风险或策略回测等能力。

4. 输入研究问题：描述研究对象、时间范围、指标和期望输出。例如：

   分析贵州茅台近 60 个交易日的趋势、量能、估值与主要风险，
   给出关键数据依据，并明确数据日期。
   

5. 创建任务：选择模型后提交。系统会创建独立研究项目，并展示执行进度、工具调用和中间结果。

6. 核验结果：重点检查数据日期、数据源、计算口径和风险提示；行情服务不可用时，部分能力会降级。

7. 继续追问：在同一项目中补充条件或要求修改输出，例如“加入沪深 300 作为基准”或“把结果整理成表格”。

8. 查看成果：从首页最近项目进入历史任务，也可在“研究报告”或相关平台页面管理成果。

常用命令

命令	说明
npm run dev	启动完整开发环境
npm run dev:web	仅启动 Web 应用
npm run dev:market	单独启动行情服务
npm run db:up	启动 TimescaleDB 和 Redis
npm run db:down	停止 Docker 基础服务
npm run db:doctor	检查数据库状态
npm run doctor	检查本地开发环境
npm run test	运行前后端测试
npm run type-check	执行 TypeScript 类型检查
npm run lint	执行代码规范检查
npm run build	构建生产版本
npm run prisma:studio	打开 Prisma 数据管理界面

可选服务

可观测性

启动 Loki、Grafana 和 Alloy：

npm run obs:up

Grafana 默认地址为 http://127.0.0.1:33012。开发环境默认账户配置见 .env；生产环境必须修改默认密码。

ClickHouse

ClickHouse 默认未启用。如需大规模分析，可在环境变量中启用并单独启动容器：

docker compose up -d clickhouse

QUANTPILOT_CLICKHOUSE_ENABLED=1

常见问题

Docker 服务无法连接

先确认 Docker Desktop 已启动，再检查容器状态：

docker compose ps
npm run db:logs

页面可以打开，但无法执行 AI 任务

检查 .env.local 中的模型 API Key，然后运行：

npm run check:models
npm run doctor

行情能力不可用

检查健康接口和本地环境：

curl http://127.0.0.1:8000/health
npm run dev:market

Windows PowerShell 也可以使用：

Invoke-RestMethod http://127.0.0.1:8000/health

端口被占用

npm run dev 会尝试为 Web 应用寻找可用端口。也可以显式指定端口：

npm run dev -- --port 3001

如修改数据库、Redis 或行情端口，请同时更新 .env / .env.local 中对应的连接地址。

项目目录

quant804/
├─ src/                    # Next.js 页面、组件、API 与业务逻辑
├─ services/market-data/   # Python 行情和量化数据服务
├─ prisma/                 # 数据模型与数据库迁移
├─ sqls/                   # 时序数据库初始化及数据修复脚本
├─ scripts/                # 开发、构建、检查、运维与评测脚本
├─ benchmarks/             # 量化能力评测数据集与快照
├─ config/                 # 模型、服务、权限和评测配置
├─ deploy/                 # Docker、systemd 与可观测性配置
├─ electron/               # Electron 桌面端入口
└─ public/                 # Logo、图标等静态资源

生产构建

构建前先执行完整检查：

npm run doctor:full
npm run type-check
npm run test
npm run build

启动生产构建：

npm run start

生产部署前请基于 .env.production.example 配置独立密钥、强密码、HTTPS、安全 Cookie、访问控制及备份策略，不要直接沿用开发环境默认值。

License

本项目基于 MIT License 发布。