feat: 解决 aarch64 上 Qlib 安装（源码 git 固化依赖）并记录下载代理规则

- backend/pyproject.toml + uv.lock: pyqlib 以 git+https 固定 commit 79633dd 注册为核心依赖，
  替代无法在 Linux aarch64 安装的 PyPI wheel（ROADMAP §2 旧备注）
- engine.py: 更正占位说明（Qlib 现已可安装，工作流实现待 Phase 2 补齐）
- AGENT.md §0: 网络下载困难时使用 HTTP 代理 192.168.1.160:3128
- README / ROADMAP: 同步 Qlib 安装方式与代理说明

AGENT.md

@@ -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. 项目定位
 
 这是一个：

README.md

@@ -60,7 +60,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

backend/app/quant/qlib_adapter/engine.py

@@ -1,15 +1,14 @@
 """Qlib 后端引擎（桥接占位）。
 
-当前开发平台为 Linux aarch64 + CPython 3.12：pyqlib 官方仅提供 x86_64 /
+本模块是 Qlib 引擎的桥接边界（AGENT.md §14 / §15：Qlib 只允许在
-macOS / Windows 且最高 Python 3.8 的 wheel（实测 uv 解析不可满足），因此
+quant/qlib_adapter/ 内被引用）。Qlib（pyqlib）已通过「源码 git 安装」成功
-Qlib 实现在此平台无法安装运行。
+部署到本机（Linux aarch64 + CPython 3.12，backend/.venv，uv 管理；
+backend/pyproject.toml 固定 commit，细节见 docs/ROADMAP.md §2 备注）。
 
-受支持平台（如 x86_64 Linux + Python 3.11）启用方式：
+基于 Qlib 的因子 / 回测工作流（Parquet/本地行情 → QlibDataset → Alpha158 →
-    cd backend && uv pip install pyqlib==0.9.7
+LightGBM 训练/预测 → 回测，并归一化为 domain.entities.research 输出）属
-    将本模块替换为真实实现：Parquet/本地行情 → QlibDataset → Alpha158 →
+Phase 2 后续实现；当前默认研究引擎仍为 LocalEngine（纯 pandas，见
-    LightGBM 训练/预测 → 回测，并归一化为 domain.entities.research 输出。
+app/quant/engine.py），业务层经 QuantEngine Protocol 注入，切换无需改业务代码。
-
-业务层经 app.quant.engine.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。"
+    "Qlib 引擎工作流尚未实现：pyqlib 现已可在本机安装使用（见 docs/ROADMAP.md §2），"
-    "请改用 LocalEngine 或在受支持平台安装 pyqlib 后实现（见本模块 docstring）。"
+    "但 QlibDataset → LightGBM 的实现待 Phase 2 补齐。当前请使用默认 LocalEngine。"
 )
 
 

backend/pyproject.toml

@@ -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]

docs/ROADMAP.md

@@ -68,10 +68,14 @@
 
 ## 2. Phase 2 —— 研究引擎（M2）
 
-> 实施备注（2026）：pyqlib 官方 wheel 仅支持 x86_64 / macOS / Windows 且最高 Python 3.8 构建；
+> 实施备注（2026-09 更新）：PyPI `pyqlib` 官方 wheel 仅支持 x86_64 / macOS / Windows，在 Linux aarch64 上 pip 解析不可满足（旧备注）；
-> 本项目开发机为 Linux aarch64 + Python 3.12，无法安装 Qlib（已实测 pip 解析不可满足）。
+> 现已改用 **microsoft/qlib 源码 git 安装**并验证成功：开发机 Linux aarch64 + CPython 3.12（backend/.venv，uv 管理），
-> 依据 AGENT.md §40「更简单、可替换优先」与 Qlib 经 Adapter 隔离的约束，M2 交付**引擎接口 + 默认自研轻量引擎**（pandas 实现因子/评估/低频回测，完整可测）；
+> 依赖已注册进 `backend/pyproject.toml`（`pyqlib @ git+https://github.com/microsoft/qlib.git@79633dd`，固定 commit，随 uv.lock 固化）；
-> `quant/qlib_adapter/` 保留桥接边界，在支持平台安装 pyqlib 后填充 Qlib Dataset / LightGBM 工作流实现，业务层不感知切换。
+> 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 驱动「因子 → 评估 → 低频选股回测」闭环，产出标准化结果。