Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Simon
|
01d818e12a | ||
|
Simon
|
8f8b6d274f |
@@ -10,6 +10,38 @@
|
||||
|
||||
---
|
||||
|
||||
# 0. 网络下载与代理规则
|
||||
|
||||
当网络下载（git clone、pip / uv 安装、wget、数据下载、Docker pull 等）出现**困难或超时**时，
|
||||
统一使用本机局域网 HTTP 代理：
|
||||
|
||||
```text
|
||||
192.168.1.160:3128
|
||||
```
|
||||
|
||||
示例（仅在下载失败 / 超时时启用，不把代理写入代码或 Git）：
|
||||
|
||||
```bash
|
||||
# git clone（仅对 GitHub 等外网 https 目标使用）
|
||||
git -c http.proxy=http://192.168.1.160:3128 -c https.proxy=http://192.168.1.160:3128 clone <url>
|
||||
|
||||
# pip / uv 安装
|
||||
export http_proxy=http://192.168.1.160:3128
|
||||
export https_proxy=http://192.168.1.160:3128
|
||||
uv pip install <pkg>
|
||||
|
||||
# wget / curl
|
||||
wget -e use_proxy=yes -e http_proxy=http://192.168.1.160:3128 <url>
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 代理只用于**外网**下载；内网资源（如 ssh git@192.168.1.10、局域网服务）不要走代理。
|
||||
- 代理 IP 属于局域网配置，不写入 `.env` / `config.yaml` / 任何提交进 Git 的文件。
|
||||
- 直接下载成功时不要多此一举走代理。
|
||||
|
||||
---
|
||||
|
||||
# 1. 项目定位
|
||||
|
||||
这是一个：
|
||||
|
||||
@@ -50,6 +50,10 @@ qlib/
|
||||
└── .env.example # 密钥模板（复制为 .env，勿提交）
|
||||
```
|
||||
|
||||
## 使用说明
|
||||
|
||||
完整使用文档（安装 / 配置 / 数据同步 / API / Agent / 常见问题）见 **[docs/USAGE.md](./docs/USAGE.md)**。
|
||||
|
||||
## 快速开始（后端）
|
||||
|
||||
前置：安装 [uv](https://docs.astral.sh/uv/)（`pip install uv` 或官方脚本）。
|
||||
@@ -60,7 +64,7 @@ cp .env.example .env
|
||||
|
||||
# 2. 安装依赖（自动使用 Python 3.12，见 backend/.python-version）
|
||||
cd backend
|
||||
uv sync
|
||||
uv sync # 含 pyqlib（GitHub 源码依赖，固定 commit）。若网络下载困难/超时，按 AGENT.md §0 设置代理 192.168.1.160:3128 后重试
|
||||
|
||||
# 3. 运行测试
|
||||
uv run pytest
|
||||
|
||||
@@ -105,9 +105,11 @@ def get_settings() -> Settings:
|
||||
secret_env = _deep(cfg, "app.secret_key_env") or "APP_SECRET_KEY"
|
||||
url_env = _deep(cfg, "database.url_env") or "DATABASE_URL"
|
||||
token_env = _deep(cfg, "data_source.tushare_token_env") or "TUSHARE_TOKEN"
|
||||
llm_key_env = _deep(cfg, "agent.llm_key_env") or "LLM_API_KEY"
|
||||
llm_url_env = _deep(cfg, "agent.llm_base_url_env") or "LLM_BASE_URL"
|
||||
llm_model_env = _deep(cfg, "agent.llm_model_env") or "LLM_MODEL"
|
||||
# Agent LLM：URL/模型名在 config.yaml 明文，api_key 只从 .env 读（env 可覆盖 url/model）
|
||||
agent_llm = _deep(cfg, "agent.llm") or {}
|
||||
llm_key_env = agent_llm.get("api_key_env") or "LLM_API_KEY"
|
||||
llm_url_env = agent_llm.get("base_url_env") or "LLM_BASE_URL"
|
||||
llm_model_env = agent_llm.get("model_env") or "LLM_MODEL"
|
||||
|
||||
default_url = "sqlite:///./data/quant.db"
|
||||
database_url = os.environ.get(url_env) or default_url
|
||||
@@ -129,7 +131,7 @@ def get_settings() -> Settings:
|
||||
data_source_fallback=str(_deep(cfg, "data_source.fallback") or "sina"),
|
||||
tushare_token=os.environ.get(token_env, ""),
|
||||
llm_api_key=os.environ.get(llm_key_env, ""),
|
||||
llm_base_url=os.environ.get(llm_url_env) or None,
|
||||
llm_model=os.environ.get(llm_model_env) or "qwen-plus",
|
||||
llm_base_url=os.environ.get(llm_url_env) or (agent_llm.get("base_url") or None),
|
||||
llm_model=os.environ.get(llm_model_env) or agent_llm.get("model") or "qwen-plus",
|
||||
storage=_resolve_storage_dirs(cfg),
|
||||
)
|
||||
|
||||
@@ -1,15 +1,14 @@
|
||||
"""Qlib 后端引擎（桥接占位）。
|
||||
|
||||
当前开发平台为 Linux aarch64 + CPython 3.12：pyqlib 官方仅提供 x86_64 /
|
||||
macOS / Windows 且最高 Python 3.8 的 wheel（实测 uv 解析不可满足），因此
|
||||
Qlib 实现在此平台无法安装运行。
|
||||
本模块是 Qlib 引擎的桥接边界（AGENT.md §14 / §15：Qlib 只允许在
|
||||
quant/qlib_adapter/ 内被引用）。Qlib（pyqlib）已通过「源码 git 安装」成功
|
||||
部署到本机（Linux aarch64 + CPython 3.12，backend/.venv，uv 管理；
|
||||
backend/pyproject.toml 固定 commit，细节见 docs/ROADMAP.md §2 备注）。
|
||||
|
||||
受支持平台（如 x86_64 Linux + Python 3.11）启用方式：
|
||||
cd backend && uv pip install pyqlib==0.9.7
|
||||
将本模块替换为真实实现：Parquet/本地行情 → QlibDataset → Alpha158 →
|
||||
LightGBM 训练/预测 → 回测，并归一化为 domain.entities.research 输出。
|
||||
|
||||
业务层经 app.quant.engine.QuantEngine Protocol 注入引擎，切换无需改业务代码。
|
||||
基于 Qlib 的因子 / 回测工作流（Parquet/本地行情 → QlibDataset → Alpha158 →
|
||||
LightGBM 训练/预测 → 回测，并归一化为 domain.entities.research 输出）属
|
||||
Phase 2 后续实现；当前默认研究引擎仍为 LocalEngine（纯 pandas，见
|
||||
app/quant/engine.py），业务层经 QuantEngine Protocol 注入，切换无需改业务代码。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -20,8 +19,8 @@ from app.domain.entities.research import BacktestResult, FactorTestReport, Resea
|
||||
from app.quant.engine import QuantEngine
|
||||
|
||||
_MSG = (
|
||||
"Qlib 引擎需要 pyqlib，当前平台（Linux aarch64 + Python 3.12）无可用 wheel。"
|
||||
"请改用 LocalEngine 或在受支持平台安装 pyqlib 后实现（见本模块 docstring）。"
|
||||
"Qlib 引擎工作流尚未实现：pyqlib 现已可在本机安装使用（见 docs/ROADMAP.md §2），"
|
||||
"但 QlibDataset → LightGBM 的实现待 Phase 2 补齐。当前请使用默认 LocalEngine。"
|
||||
)
|
||||
|
||||
|
||||
|
||||
@@ -11,6 +11,9 @@ dependencies = [
|
||||
"alembic>=1.13",
|
||||
"pyyaml>=6.0",
|
||||
"httpx>=0.28.1",
|
||||
# Qlib 研究引擎：PyPI 无 aarch64 wheel（见 docs/ROADMAP.md §2 备注），故从源码 git 安装并固定 commit。
|
||||
# 网络下载困难时使用 HTTP 代理（见根目录 AGENT.md §0：192.168.1.160:3128）。
|
||||
"pyqlib @ git+https://github.com/microsoft/qlib.git@79633dd",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
|
||||
@@ -46,3 +46,25 @@ def test_env_file_loading(tmp_path: Path, monkeypatch) -> None:
|
||||
monkeypatch.setenv("TUSHARE_TOKEN", "kept")
|
||||
_load_env_file(env_file)
|
||||
assert os.environ["TUSHARE_TOKEN"] == "kept"
|
||||
|
||||
|
||||
def test_llm_from_config_yaml() -> None:
|
||||
"""URL 与模型名来自 config.yaml 明文，Key 仅来自环境（当前未设置）。"""
|
||||
settings = get_settings()
|
||||
assert settings.llm_model == "qwen-plus"
|
||||
assert settings.llm_base_url == "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
assert settings.llm_api_key == "" # .env 未提供 → 空，Agent 层给出引导提示
|
||||
|
||||
|
||||
def test_llm_env_overrides_yaml(monkeypatch) -> None:
|
||||
from app.core.config import get_settings
|
||||
|
||||
monkeypatch.setenv("LLM_MODEL", "env-model")
|
||||
monkeypatch.setenv("LLM_BASE_URL", "https://example.com/v1")
|
||||
monkeypatch.setenv("LLM_API_KEY", "sk-test")
|
||||
get_settings.cache_clear() # Settings 有 lru_cache，刷新以读取新环境变量
|
||||
s = get_settings()
|
||||
assert s.llm_model == "env-model"
|
||||
assert s.llm_base_url == "https://example.com/v1"
|
||||
assert s.llm_api_key == "sk-test"
|
||||
get_settings.cache_clear()
|
||||
|
||||
Generated
+3297
File diff suppressed because it is too large
Load Diff
+11
@@ -39,5 +39,16 @@ job:
|
||||
# 第一阶段异步任务模式：local（FastAPI BackgroundTasks 级）；Phase 复杂后再引入队列
|
||||
mode: "local"
|
||||
|
||||
agent:
|
||||
llm:
|
||||
# 大模型接入：URL 与模型名在此配置（明文、可提交）；
|
||||
# 密钥只放根目录 .env（LLM_API_KEY，见 .env.example）——本文件不写任何 Key。
|
||||
# 可选：仍可通过 .env 的 LLM_BASE_URL / LLM_MODEL 覆盖下面两个值。
|
||||
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
model: "qwen-plus"
|
||||
base_url_env: "LLM_BASE_URL"
|
||||
model_env: "LLM_MODEL"
|
||||
api_key_env: "LLM_API_KEY"
|
||||
|
||||
logging:
|
||||
level: "INFO"
|
||||
|
||||
+8
-4
@@ -68,10 +68,14 @@
|
||||
|
||||
## 2. Phase 2 —— 研究引擎（M2）
|
||||
|
||||
> 实施备注（2026）：pyqlib 官方 wheel 仅支持 x86_64 / macOS / Windows 且最高 Python 3.8 构建；
|
||||
> 本项目开发机为 Linux aarch64 + Python 3.12，无法安装 Qlib（已实测 pip 解析不可满足）。
|
||||
> 依据 AGENT.md §40「更简单、可替换优先」与 Qlib 经 Adapter 隔离的约束，M2 交付**引擎接口 + 默认自研轻量引擎**（pandas 实现因子/评估/低频回测，完整可测）；
|
||||
> `quant/qlib_adapter/` 保留桥接边界，在支持平台安装 pyqlib 后填充 Qlib Dataset / LightGBM 工作流实现，业务层不感知切换。
|
||||
> 实施备注（2026-09 更新）：PyPI `pyqlib` 官方 wheel 仅支持 x86_64 / macOS / Windows，在 Linux aarch64 上 pip 解析不可满足（旧备注）；
|
||||
> 现已改用 **microsoft/qlib 源码 git 安装**并验证成功：开发机 Linux aarch64 + CPython 3.12（backend/.venv，uv 管理），
|
||||
> 依赖已注册进 `backend/pyproject.toml`（`pyqlib @ git+https://github.com/microsoft/qlib.git@79633dd`，固定 commit，随 uv.lock 固化）；
|
||||
> numpy/pandas/scipy/lightgbm/pyarrow 等使用 aarch64 PyPI wheel，qlib 的两个 Cython 扩展（rolling/expanding）源码构建通过，
|
||||
> 已验证 `import qlib` / `qlib.init()` / LightGBM 训练预测正常。源码 checkout 保留在项目外 `/home/pi/project/qlib-src`（供查阅/二次开发）；
|
||||
> 网络下载困难时按 AGENT.md §0 使用 HTTP 代理（192.168.1.160:3128）。
|
||||
> M2 依据 AGENT.md §40「更简单、可替换优先」与 Qlib 经 Adapter 隔离的约束，交付**引擎接口 + 默认自研轻量引擎**（pandas 实现因子/评估/低频回测，完整可测）；
|
||||
> `quant/qlib_adapter/` 为桥接边界，现可在本机填充 Qlib Dataset / LightGBM 工作流实现（Phase 2 后续），业务层不感知切换。
|
||||
|
||||
> 目标：用 Research Specification 驱动「因子 → 评估 → 低频选股回测」闭环，产出标准化结果。
|
||||
|
||||
|
||||
+258
@@ -0,0 +1,258 @@
|
||||
# qlib-platform 使用说明
|
||||
|
||||
> 适用代码版本：M1–M5 全部完成（`d9be75a` 及之后）；若文档与代码不一致，以代码与
|
||||
> [ARCHITECTURE.md](./ARCHITECTURE.md) / [ROADMAP.md](./ROADMAP.md) 为准。
|
||||
>
|
||||
> 本文覆盖：安装配置、数据同步、启动前后端、研究 API 调用、AI Agent、测试门禁、已知限制。
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目概览（当前完成度）
|
||||
|
||||
个人 A 股中低频量化研究平台，当前已完成：
|
||||
|
||||
| 模块 | 位置 / 说明 |
|
||||
|---|---|
|
||||
| 数据层 | `backend/app/domain`、`backend/app/infrastructure/data_sources`：Tushare 首选 + 新浪备用（Failover 审计），SQLite（未来 MySQL 可切换） |
|
||||
| 研究引擎 | `backend/app/quant`：ResearchSpec → 因子 → IC/RankIC/分层 → TopK 低频回测 → 标准化 `BacktestResult` |
|
||||
| Web | `frontend/web`：Next.js(TS)+ECharts —— 总览 / 股票池 / 因子研究 / 回测 / 实验 |
|
||||
| 异步与归档 | Job 状态机 + Experiment 自动归档 + 一键复跑 + SSE 进度 |
|
||||
| AI Agent | 受控工具白名单 + LLM 编排（需配置模型 Key） |
|
||||
|
||||
**技术栈**：Python 3.12(uv) · FastAPI · SQLAlchemy 2 · Alembic · SQLite · pandas · Next.js 15 · ECharts
|
||||
|
||||
---
|
||||
|
||||
## 2. 环境准备
|
||||
|
||||
```bash
|
||||
# 工具（本机已装则跳过）
|
||||
python3 -m pip install uv
|
||||
# Node 18+ 与 pnpm： https://pnpm.io/installation
|
||||
|
||||
# 1) 后端依赖（backend/.python-version 固定 3.12）
|
||||
cd backend
|
||||
uv sync # 基础依赖
|
||||
uv sync --extra datasource-tushare # 数据同步需要 Tushare SDK（首次）
|
||||
```
|
||||
|
||||
前端：
|
||||
|
||||
```bash
|
||||
cd frontend/web
|
||||
pnpm install # 依赖使用 npmmirror 镜像时较快
|
||||
cp .env.local.example .env.local # NEXT_PUBLIC_API_BASE 默认 http://127.0.0.1:8000/api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 配置
|
||||
|
||||
### 3.1 根目录 `.env`（密钥，不入库）
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
按需填写：
|
||||
|
||||
| 变量 | 必填 | 说明 |
|
||||
|---|---|---|
|
||||
| `TUSHARE_TOKEN` | 同步数据时必填 | Tushare Pro token |
|
||||
| `LLM_API_KEY` | 使用 Agent 时必填 | 大模型 API Key |
|
||||
| `DATABASE_URL` | 否 | 留空使用 SQLite `<项目根>/data/quant.db` |
|
||||
| `APP_SECRET_KEY` | 否 | 应用密钥（未接登录，可暂不改） |
|
||||
|
||||
> 约定：**密钥只放 `.env`**；URL、模型名等可配置项放 `config.yaml`（见下）。`.env` 已被 gitignore，严禁提交。
|
||||
|
||||
### 3.2 根目录 `config.yaml`（可配置项，可入库）
|
||||
|
||||
常用字段：
|
||||
|
||||
```yaml
|
||||
app: {name, version, debug, secret_key_env}
|
||||
api: {prefix: "/api"} # API 前缀
|
||||
database: {url_env: "DATABASE_URL", echo: false, migrations_dir: ...}
|
||||
data_source: {primary: "tushare", fallback: "sina", tushare_token_env: "TUSHARE_TOKEN"}
|
||||
storage: {parquet_dir, qlib_dir, ...} # 相对项目根
|
||||
agent:
|
||||
llm: # ← AI Agent 模型接入
|
||||
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" # URL 在这里配
|
||||
model: "qwen-plus" # 模型名在这里配
|
||||
api_key_env: "LLM_API_KEY" # Key 仍从 .env 读
|
||||
```
|
||||
|
||||
- **换模型**：改 `config.yaml → agent.llm.model`（例如 `deepseek-chat` / `qwen-max` 等
|
||||
OpenAI 兼容接口模型），并同步 `base_url`（如有平台差异）。
|
||||
- 也可以用 `.env` 的 `LLM_BASE_URL` / `LLM_MODEL` 覆盖 yaml 值（两种都支持，env 优先）。
|
||||
|
||||
### 3.3 数据库迁移
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
uv run alembic upgrade head # 建表（首次会自动建 data/quant.db）
|
||||
# 开发中改 Model 后：
|
||||
uv run alembic revision --autogenerate -m "desc"
|
||||
uv run alembic upgrade head
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据同步
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
uv run python -m app.cli.sync basic # 股票基础信息（全市场）
|
||||
uv run python -m app.cli.sync calendar --start 20240101 --end 20241231
|
||||
uv run python -m app.cli.sync daily --symbols 600519.SH,000858.SZ --start 20230101
|
||||
uv run python -m app.cli.sync daily --all --start 20240101 --resume # 全市场 + 断点续传
|
||||
uv run python -m app.cli.sync financial --symbols 600519.SH
|
||||
uv run python -m app.cli.sync verify --symbol 600519.SH # 新浪交叉验证
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 每次拉取写入 `sync_log` 审计（来源 / 成功与否 / 行数 / 区间），禁止静默切换数据源。
|
||||
- `daily` 同时写入日线与复权因子；`--resume` 从本地最新交易日续传。
|
||||
- 新浪（`verify`）仅用于交叉验证，返回**前复权**口径，不会并入不复权主库。
|
||||
- 财务指标带 `announce_date`（公告日），研究侧只允许使用已公告数据（防未来函数）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 启动
|
||||
|
||||
```bash
|
||||
# 后端（端口 8000）
|
||||
cd backend
|
||||
uv run uvicorn app.main:app --reload --port 8000
|
||||
# 交互文档：http://127.0.0.1:8000/docs 健康检查：/api/health
|
||||
|
||||
# 前端（端口 3000）
|
||||
cd frontend/web
|
||||
pnpm dev
|
||||
# 打开 http://127.0.0.1:3000
|
||||
```
|
||||
|
||||
页面：`总览` → `股票池`（搜索/列表）→ `因子研究`（目录 + 单因子 IC/RankIC/分层）→
|
||||
`回测`（参数 → 净值/回撤/月度/持仓/未建模标注）→ `实验`（归档列表 / 详情 / 一键复跑）。
|
||||
|
||||
---
|
||||
|
||||
## 6. 研究 API（curl 示例）
|
||||
|
||||
所有研究输入 = ResearchSpec（统一结构，前端 / API / Agent 同构）：
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:8000/api/backtests \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"type": "backtest",
|
||||
"universe": {"exclude_st": true, "min_listing_days": 0},
|
||||
"factors": [{"name": "momentum_60", "weight": 1.0}],
|
||||
"selection": {"top_n": 5},
|
||||
"rebalance": "monthly",
|
||||
"period": ["2024-03-01", "2024-12-31"]
|
||||
}'
|
||||
```
|
||||
|
||||
| 端点 | 说明 |
|
||||
|---|---|
|
||||
| `GET /api/stocks?q=600519&limit=20` | 股票列表/搜索 |
|
||||
| `GET /api/factors` | 因子目录（含公式/lookback/方向） |
|
||||
| `POST /api/factor-tests` | 同步单因子测试 → `FactorTestReport` |
|
||||
| `POST /api/backtests` | 同步回测（小样本）→ `BacktestResult` |
|
||||
| `GET /api/backtests/last` | 最近一次同步回测 |
|
||||
| `POST /api/jobs` | 创建异步 Job（同 spec），返回 `{"job_id","status":"queued"}` |
|
||||
| `GET /api/jobs/{id}` | 查询状态；成功时内嵌 `result` |
|
||||
| `GET /api/jobs/{id}/events` | SSE 进度（`curl -N ...`） |
|
||||
| `GET /api/experiments` | 实验归档列表（含收益摘要/代码版本） |
|
||||
| `GET /api/experiments/{id}` | 实验详情（spec + 完整结果） |
|
||||
| `POST /api/experiments/{id}/rerun` | 一键复跑 → 新 Job |
|
||||
| `POST /api/agent/chat` | AI 研究助手（见 §7） |
|
||||
|
||||
**防未来函数与真实性**：回测在调仓日收盘成交、自次日起计收益；财务数据只使用
|
||||
`announce_date` 之前已公告内容；成本（佣金/印花税/滑点）、涨跌停、停牌已建模；
|
||||
未建模约束（如开盘一字路径）会写入结果的 `unimplemented` 数组，前端如实展示。
|
||||
|
||||
---
|
||||
|
||||
## 7. AI Agent
|
||||
|
||||
前置：`config.yaml → agent.llm`（URL/模型名已配好，默认阿里云百炼 qwen-plus），
|
||||
`.env` 中设置 `LLM_API_KEY`。
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:8000/api/agent/chat \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"message": "帮我测试 momentum_60 因子并跑一次 Top5 月度回测，评估是否值得深入"}'
|
||||
```
|
||||
|
||||
返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"reply": "（最终结论，中文）",
|
||||
"actions": [
|
||||
{"tool": "test_factor", "args": {...}, "output": "因子测试完成（Experiment EXP-…）..."},
|
||||
{"tool": "run_backtest", "args": {...}, "output": "回测完成（Experiment EXP-…）..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Agent 能力边界（内置受控工具，只读）：
|
||||
|
||||
- `search_stocks` / `get_market_data`：查询
|
||||
- `test_factor` / `run_backtest`：研究并自动归档 Experiment
|
||||
- `get_experiment` / `compare_experiments`：读取/对比归档
|
||||
|
||||
**不提供** shell / 任意代码执行 / 删改数据 / 修改配置与凭证。未配置 Key 时接口返回
|
||||
400 引导信息。研究纪律写入系统提示：禁止仅凭单次样本内高收益判定策略有效，需说明
|
||||
样本外、过拟合、look-ahead bias、成本、参数敏感性等（未验证项要明说）。
|
||||
|
||||
---
|
||||
|
||||
## 8. 测试与质量门禁
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
uv run ruff check app tests && uv run ruff format --check app tests
|
||||
uv run pytest # 当前 79 passed
|
||||
|
||||
cd frontend/web
|
||||
pnpm run typecheck
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
覆盖重点：Provider 归一化与 Failover 审计、Repository 幂等与「未来函数阻断」
|
||||
（`as_of_date`/`announce_date`）、Alembic 迁移、因子/IC/分层、回测记账与成本/涨跌停、
|
||||
Job 状态机与 Experiment 归档、Agent 工具白名单与编排、API 端到端。
|
||||
|
||||
---
|
||||
|
||||
## 9. 已知限制与说明
|
||||
|
||||
1. **Qlib 引擎**：本开发机为 Linux aarch64 + Python 3.12，pyqlib 无匹配 wheel，无法安装。
|
||||
默认研究引擎为自研轻量实现（pandas）；`backend/app/quant/qlib_adapter/` 保留桥接，
|
||||
在受支持平台（x86_64/macOS/Windows）安装 pyqlib 后可填充实现，业务层无感。
|
||||
2. **数据规模**：仓库自带示例数据为 20 只权重股 2023–2024 日线；`sync --all` 可扩展
|
||||
全市场，注意耗时与 Tushare 积分限制。
|
||||
3. **回测为近似建模**：涨跌停按收盘相对上一有效收盘判定、成交假设调仓日收盘，未建模
|
||||
开盘一字 / 集合竞价 / 盘中路径（详见结果 `unimplemented`）。
|
||||
4. **Agent 结论质量取决于模型**：编排只保证「经受控工具 + 归档留痕」，研究有效性判断
|
||||
需要人复核；接不同厂商模型请核对 `base_url` 与 `model` 命名。
|
||||
5. **SSE 与 Job 为单进程内存/本地执行**：重启进程后未完成 Job 需重新提交（后续如需
|
||||
可换 Redis/Celery，第一阶段刻意不引入）。
|
||||
|
||||
---
|
||||
|
||||
## 10. 常见问题（FAQ）
|
||||
|
||||
- **同步报「缺少 TUSHARE_TOKEN」**：把 token 填入根目录 `.env` 的 `TUSHARE_TOKEN`。
|
||||
- **同步报「未安装 tushare 客户端」**：`cd backend && uv sync --extra datasource-tushare`。
|
||||
- **Agent 报 400「未配置 LLM」**：`.env` 设置 `LLM_API_KEY`；换模型改 `config.yaml`。
|
||||
- **前端连不上后端**：确认后端运行在 8000、`frontend/web/.env.local` 的
|
||||
`NEXT_PUBLIC_API_BASE` 正确、CORS 白名单含 `localhost:3000 / 127.0.0.1:3000`。
|
||||
- **数据库被改动想重置**：删除 `data/quant.db` 后 `uv run alembic upgrade head` 重建
|
||||
表结构（行情需重新同步）。
|
||||
- **想切换 MySQL**：`.env` 设 `DATABASE_URL=mysql+pymysql://user:pass@host/db`，
|
||||
业务层无需改动（Repository 已隔离）。
|
||||
Reference in New Issue
Block a user