# claude-financial-services

**Repository Path**: HSKS/claude-financial-services

## Basic Information

- **Project Name**: claude-financial-services
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 量化智能体（aiquant）

基于 [claude-agent-sdk](https://pypi.org/project/claude-agent-sdk/) 的 **A 股量化智能体** Web 应用：FastAPI 后端 + React 前端，前后端打进**单个可执行文件**（PyInstaller onefile，内嵌前端产物与 CLI）。面向普通投资者——说人话、给依据、给风险，买卖决策由用户自主。

## 项目介绍

### 是什么

一个能对话的 A 股量化助手。直接打字问「贵州茅台适合买吗」「今天大盘怎么样」「推荐几只黑马股」，AI 用 22 个量化工具取数分析，给结构化结论 + 风险提示 + 免责。

### 核心能力

| 能力 | 说明 |
|------|------|
| **个股诊断** | 技术面 + 估值分位 + 财务 + 资金 + 消息 + 排雷（质押/商誉/增减持），五合一买卖建议 |
| **估值判断** | PE/市净率全历史分位（0%=最便宜 100%=最贵），一眼看贵不贵 |
| **排雷预警** | 股权质押、商誉占净资产、大股东增减持，有雷必提示 |
| **概念题材** | AI/机器人/低空经济等概念板块成分股 |
| **黑马选股** | 多因子打分（活跃度/资金/估值/业绩/安全）+ 智能回测验证 + 综合排序 |
| **策略回测** | 7 个预设策略 + 智能策略自动分发，akquant 引擎秒级回测 |
| **市场温度** | 赚钱效应涨跌家数 + 沪深两所总貌 + 行业资金流 |
| **自选管理** | 名称搜代码、加自选实时看涨跌 |

### 技术栈

| 层 | 技术 |
|---|---|
| 后端 | Python 3.11+ / FastAPI / uvicorn / pydantic-settings，uv 管理依赖 |
| 前端 | Vite / React 19 / TypeScript / Tailwind CSS 4，bun 管理依赖 |
| 数据 | akshare（A 股日线/财务/资金/事件）+ akquant（回测引擎 + talib 指标） |
| 契约 | `frontend/src/contracts/`（FE 线协议）与 `src/backend/contracts/`（BE 校验）同源对译 |
| 打包 | PyInstaller onefile（vite build 产物以 datas 内嵌，运行时经 `sys._MEIPASS` 服务） |

### 目录结构

```
├── main.py                 # PyInstaller 打包入口（dev 直接用 python -m backend）
├── build.py                # 打包器：vite build → pyinstaller → bin/aiquant-{platform}-{arch}-{ver}
├── pyproject.toml          # 后端依赖 + ruff/pytest 配置（uv）
├── version.txt             # 版本号（打包时内嵌）
├── .env                    # 服务级配置 + 模型默认值（首次运行自动生成空模板）
├── src/backend/            # FastAPI 应用
│   ├── app.py              # 组装：中间件栈 → 路由 → 错误处理（BASE_URL 子路径包装）
│   ├── env.py              # 环境变量唯一来源（启动即校验；首次自动生成 .env 模板）
│   ├── core/               # 数据管道（data.py）/ 指标（factors.py）/ 中间件 / 日志 / 响应
│   ├── modules/agent/      # 会话注册表、SSE 事件翻译、审批流、22 个 quant MCP 工具
│   ├── modules/auth/       # JWT 登录（24h 滑动续期）、用户档案
│   ├── modules/quant/      # 量化数据直连 API（前端卡片取数，不经模型消息流）
│   └── modules/system/     # 单实例锁、自更新、launch 服务
├── frontend/               # Web UI（src/contracts 为前后端线协议契约）
└── tests/                  # pytest（106 测试）
```

## 开发指南

### 前置

- [uv](https://docs.astral.sh/uv/)（Python 包管理）
- [bun](https://bun.sh/)（前端包管理）
- Python 3.11+、Node 18+

### 启动 dev

```powershell
# 1. 安装依赖
uv sync
bun install --cwd frontend

# 2. 启动后端（读 .env，默认端口 10068；vite dev 会代理 /api 到它）
uv run python -m backend

# 3. 启动前端 dev server（另开终端，http://localhost:3001）
bun run --cwd frontend dev
```

> dev 模式后端不内嵌前端（`has_frontend=False`），页面由 vite dev server 提供；生产形态由 exe 同源服务前端。

### 常用命令

```powershell
uv sync                          # 同步后端依赖
uv add <pkg>                     # 加后端依赖
uv run pytest                    # 测试（106 测试）
uv run pytest tests/test_quant_prompt.py -v  # 单跑 quant prompt 测试
uv run ruff check src tests      # lint
bun run --cwd frontend build     # 仅构建前端
bun run --cwd frontend tsc --noEmit  # 前端类型检查
```

### 架构要点

- **双通道数据**：MCP 工具（模型调用，结果进消息流 → 卡片渲染）+ HTTP 直连（`quant_route.py`，前端卡片直接 fetch 取数/轮询），同源复用 `core.data`。
- **SSE 事件流**：`GET /api/agent/session/events`，每事件带自增 `seq`；EventSource 断线自动携 `Last-Event-ID` 增量重放。
- **流式翻译**：`agent_event_translator.py` 把 SDK 消息翻译成 SSE 事件——partial 流 + 完整消息回填。
- **多源降级**：A 股日线数据 东财→腾讯→Baostock 三源降级 + Parquet 缓存（hfq 增量/qfq TTL 全量刷）+ 断网陈旧缓存兜底。
- **回测隔离**：`run_backtest` 在子进程执行（fd 级静默 + 超时 + 代码长度限制），frozen 下不毒化 JSON-RPC 流。
- **单实例锁**：二次启动冷热转发帧给主实例后退出。
- **优雅停机**：SIGINT/SIGTERM 先关全部 agent 会话再停服。

### 量化工具一览（22 个 MCP 工具）

| 类别 | 工具 |
|------|------|
| 行情 | `search_symbol` `get_stock_history` `get_index_history` `get_realtime_quote` |
| 技术 | `calc_indicators`（16 种：MA/MACD/RSI/BOLL/KDJ/ADX/ATR/CCI/WR/ROC/MOM/TRIX/OBV/MFI/SAR） |
| 情绪 | `get_zt_pool`（涨停池家族 6 种）`get_market_overview`（赚钱效应+沪深总貌） |
| 基本面 | `get_financial_indicators` `get_valuation_history`（PE/PB 历史分位） |
| 资金/筹码 | `get_stock_capital`（fund_flow/hsgt/gdhs/restricted/fhps/cyq 6 类） |
| 事件 | `get_market_events`（lhb/yjbb/yjyg/dzjy/margin 5 类）`get_stock_events`（notice/forecast/ggcg/repurchase/jgdy/gpzy/sy/comment 8 类） |
| 板块 | `get_board_stocks` `get_board_list`（industry/concept）`get_sector_flow` `get_index_weights` |
| 选股 | `screen_stocks`（多因子黑马筛选 + 5 维度打分）`compare_stocks` |
| 其他 | `manage_watchlist` `get_research_reports` `run_backtest` |

## 打包指南

### 单 exe 打包

```powershell
uv run python build.py          # vite build + pyinstaller onefile
uv run python build.py --skip-ui    # 前端已构建时跳过 vite
```

产物：`bin/aiquant-{platform}-{arch}-{version}[.exe]`（如 `aiquant-windows-x64-0.1.13.exe`），内嵌：

- 前端 `dist/`（运行时挂 `/`，SPA 回退 index.html）
- CLI 二进制（SDK `_bundled`，frozen 下经 cli-cache 解包使用）
- `version.txt`

**跨平台**：PyInstaller 无法交叉编译，Windows / Linux / macOS 需在各自系统执行 `uv run python build.py`。构建脚本已处理平台差异（路径分隔符、venv 结构、产物命名）。

### 打包约束

- `akshare` 按需子模块加载（`_ak()` 绕过 `__init__.py` 全量 import），打包时剔除 polars/plotly/matplotlib 等重依赖。
- `py_mini_racer` stub：dev 未装时兜底；frozen 已恢复 racer 打包。
- `baostock` 全局单连接（login/logout 持锁，多线程并发不互相登出）。

### exe 常用参数

```
aiquant-windows-x64-0.1.13.exe --version
aiquant-windows-x64-0.1.13.exe --help
aiquant-windows-x64-0.1.13.exe open [--user <name>]
aiquant-windows-x64-0.1.13.exe update
```

深链接：`csmcode://download?url=<zip>&name=<workspace>&user=<name>`

## 配置指南

### .env（服务级配置 + 模型默认值）

首次运行自动生成空模板（`env.py:ensure_env_file`）。exe 同级（frozen）或 CWD（dev）无 `.env` → 写默认模板。关键项：

| 变量 | 说明 | 默认                    |
|---|---|-----------------------|
| `PORT` | 后端端口 | 8888（dev）/ exe 自选     |
| `BASE_URL` | 子路径部署前缀（如 `/aiquant`），留空为根路径 | `/`                   |
| `JWT_SECRET` | JWT 签名密钥（base64 ≥32 字节）；缺省降级 dev 常量（生产必配） | 空                     |
| `AUTH_ADMIN_USERS` | 管理员白名单（逗号分隔用户名） | 空                     |
| `AGENT_CONFIG_ROOT` | 会话数据隔离根 | `data/claude-configs` |
| `ANTHROPIC_BASE_URL` | LLM 网关地址（透传给 SDK 子进程） | 空                     |
| `ANTHROPIC_AUTH_TOKEN` | LLM 网关 token | 空                     |
| `ANTHROPIC_MODEL` | 默认模型 | 空                     |
| `ANTHROPIC_FALLBACK_MODELS` | 备用模型序列（逗号分隔） | 空                     |
| `AGENT_EFFORT` | 思考强度（high/standard/low） | high                  |
| `AGENT_THINKING` | 思考模式（enabled/adaptive/disabled） | adaptive              |

### 模型配置（UI 覆盖 .env）

用户在 **设置** 页配置的模型信息存 `model-config.json`（per-user），**空字段回退 .env 默认**：

- UI 配的 base_url/token/model → 覆盖 .env
- UI 未配的字段 → 回退 .env
- 新会话生效（子进程 env 每次开启读）

### 认证（JWT 滑动续期）

- 登录 → 签 24h JWT（HttpOnly cookie）
- 每次打开应用调 `/api/auth/me` → token 有效则**重签 24h cookie**（滑动续期）
- token 过期 → 401 → 前端自动跳 `/login`
- 会话中途 401（非 auth 端点）→ `api.ts` 全局拦截 → 跳 `/login`

## 使用指南

### 第一步：配置模型

点右上角 **设置**，填 API Key + Base URL + 模型名 → 点 **测试连通性** → **保存**。不配置模型无法使用。

### 第二步：开始使用

点左侧 **新建** 建会话，然后：

**直接打字问**（最简单，直接说人话）：
- 「贵州茅台适合买吗」— 诊断一只票
- 「茅台现在贵不贵」— 看估值在历史什么位置
- 「茅台和五粮液哪个好」— 两只对比
- 「AI 概念有哪些票」— 查概念板块成分
- 「今天大盘怎么样」— 看市场温度
- 「推荐几只黑马股」— 多因子选股

**或点 ⚡量化 选模板**（更方便）：

输入框下方点 **⚡量化** → 选任务 → 输股票名 → 发送。

| 模板 | 干什么 |
|---|---|
| 📊 个股速览 | 快速看一只票（行情+估值+新闻） |
| 🩺 个股体检 | 深度诊断（含排雷：质押/商誉/增减持） |
| 📈 简单回测 | 测试策略赚不赚钱 |
| 🌐 大盘速览 | 看今天大盘（涨跌家数+赚钱效应） |
| 🚀 涨停复盘 | 看今天热点 |
| 🐴 黑马选股 | 多因子打分选股（涨停+资金+估值+排雷+回测验证） |

### 黑马选股流程

用户说"推荐几只黑马股"时：
1. AI 弹出 **AskUserQuestion** 问两个问题：筛选几只（5/10/20）、回测几只（全部/top 3/不回测）
2. 用户未回答 → 走默认值：筛选 10 只 + 全部回测
3. `screen_stocks` 多因子打分（活跃度/资金/估值/业绩/安全，各 0-2 分，总分 0-10）
4. 对回测候选用 Task 子智能体并行 `run_backtest`，先 `calc_indicators` 分析趋势/震荡状态自动选适配策略
5. 综合因子得分 + 回测表现重新排序 → 输出推荐 + 每只点评 + 免责

### 右侧自选股

搜代码或名称 → 点选添加 → 实时看涨跌。点某只股票直接分析，拖进输入框填指令。

### 快捷键

- **Esc** — 立即停止 AI 回复
- **Shift+Esc** — 关闭当前会话
- 会话列表 hover — 关闭 / 重命名 / 删除

### 执行模式

| 模式 | 说明 |
|------|------|
| auto | 自动放行工具，不审批（最快） |
| standard | 危险工具审批（Write/Bash 等），安全工具放行 |
| safe | 全部工具审批 |
| plan | 只读模式，不执行修改 |

### ⚠ 重要提醒

行情为延迟数据，分析仅供研究参考，**不构成投资建议**，据此操作风险自担。回测历史不代表未来。回测引擎无涨跌停撮合建模，打板类策略偏乐观。