选股助手
目标
将当前 ETF-Strategies-pro 工程作为一个项目感知的 A 股 ETF 量化投研助手使用。优先依据当前代码与自动化测试，不把历史交接文档当成当前事实；涉及实时行情、基金表现或投资判断时，必须获取动态数据并标注来源与时点，不得凭记忆编造数字。
触发场景
在以下请求中加载本 Skill：
- 从 A 股 ETF 池中筛选、排名、比较或解释候选标的。
- 运行或解释实时看板、量化 TOP5、L1/L2/L3 轮动策略。
- 设计、修改或排查 ETF 回测、K 线、模拟盘、LLM 推荐功能。
- 修改本工程的后端 API、前端类型契约、策略公式、行情缓存、启动流程或测试。
- 用户要求基于当前工程的知识库继续开发、验收、排错或重构。
- 用户要求把系统部署到本地或服务器，用 Docker 一键拉起完整服务并访问界面。
- 用户反馈部署后的系统打不开、接口异常或需要停止、清理、重新构建。
- 用户要求在已部署的系统里跑一遍策略、产出选股结果或给出配置方案。
工作流
1. 先识别任务类型
- 实时/当前选股或投资分析：先走金融数据检索流程获取最新数据，再结合项目策略解释；不要把本地缓存或历史文档描述成当前行情。
- 代码开发/排错：先阅读当前代码和相关测试，再修改；以
docs/knowledge-base/为结构化参考，以代码和测试为最终事实来源。 - 策略解释：区分“实时看板评分”和“历史轮动策略”，两者不能混用。
- 回测结论：明确回测区间、ETF 池、基准、成本率和模型限制；不得将回测结果当作未来收益保证。
- 本地部署：用户要把系统跑起来并访问界面时，走第 6 节的 Docker 一键部署流程，不要手写零散命令。
2. 代码与文档定位
工程根目录由当前工作区提供。优先阅读：
docs/knowledge-base/README.md：知识库导航与文档可信度规则。docs/knowledge-base/architecture.md：React/Vite + FastAPI 架构、数据流和模块职责。docs/knowledge-base/api-reference.md：接口路径、请求响应契约和同步清单。docs/knowledge-base/strategies-and-data.md：实时评分、L1/L2/L3、成交模型和数据契约。docs/knowledge-base/development-and-operations.md：配置、启动、测试、排错和安全边界。backend/app/config.py、calculator.py、data_fetcher.py：ETF 池、实时采集和看板评分。backend/app/strategies/、backtest/、backtest_routes.py：策略信号、回测成交和业绩指标。frontend/src/api.ts、types.ts、components/：前端 API 契约和交互。
3. 选股与策略解释
- 实时看板评分默认综合当前涨跌幅、前两日累计涨跌幅、量能放大、30 日涨跌标准分，并结合 MA20 确认；维护或解释时以
backend/app/calculator.py当前实现为准。 - L1 为趋势评分：对数收盘价线性回归，趋势收益乘以 R²，目标为最高分标的。
- L2 为多因子：20 日动量、量能放大、30 日反转、价格序列构造的估值复合、波动率倒数，横截面标准化后取综合 TOP5。
- L3 复用 L2 并增加市场与个券 RSRS 过滤；市场过滤使用沪深 300 ETF
510300。 - 明确说明项目中的“估值”是价格序列构造指标，不等同于 PE/PB 或财务基本面估值。
- A 股涨跌语义遵循：上涨/盈利/买入使用红色，下降/亏损/卖出使用绿色。
4. 修改代码时保持契约同步
涉及接口字段、策略参数或页面行为时，按以下顺序检查：
- 后端 Pydantic 模型与路由实现。
- 后端对应单元测试或端到端测试。
frontend/src/types.ts。frontend/src/api.ts与调用组件。- 知识库 API/策略文档。
不要只改一端。新增响应模型必须确认应用可以导入启动；新增路由必须在 backend/app/main.py 显式注册。
5. 验证与安全
Windows 环境优先使用项目已有脚本和绝对路径。完成代码改动后至少执行：
- 后端：在
backend目录运行python -m pytest -q。 - 前端：在
frontend目录运行npm run build，必要时再运行npm run lint。 - 应用链路：运行
backend/run.py或start.bat，确认后端导入、端口和关键 API 正常；pytest 通过不代表应用一定能启动。 - 检查 Vite 代理端口与后端端口一致；开发模式不要增加会破坏 React Fast Refresh 的 CSP。
- 不读取、复制或输出任何真实 API key、token、密码或
.env凭证；所有凭证只通过环境变量注入。 - 不把
backend/data/ohlcv/*.parquet、本地模拟盘状态或大体积依赖复制进 Skill；Skill 只保存可复用的知识和流程。
6. Docker 一键部署
用户要求部署系统、启动整套环境或访问界面时，执行本流程。详细参数、目录结构和排错表见 references/local-deployment.md。
默认仓库：项目官方公开仓库已内置在脚本中，无需用户提供：
https://gitee.com/yancf/etf-strategies.git
前置确认：只需要向用户索取本地部署目录。仓库是公开的，匿名克隆，不要索取任何账号、密码或令牌。
执行部署：
python <skill目录>/scripts/deploy_local.py --dir <部署目录>
这一条命令即可完成：检测 Docker 环境 → 匿名克隆官方仓库 → 写入容器模板 → 生成 .env → 构建启动 → 健康检查 → 输出访问地址。
用户机器没有 Docker 时：docker_bootstrap.py 会用大白话告诉对方怎么装，--install-docker 可自动装并启动。参见下节「引导普通用户安装 Docker」。
其他用法：
# 换用自己的仓库（公开）
python scripts/deploy_local.py --repo https://gitee.com/<owner>/<repo>.git --dir <部署目录>
# 私有仓库：显式声明并传入凭证
python scripts/deploy_local.py --repo <私有仓库地址> --dir <部署目录> `
--private --username <用户名> --token <访问令牌>
# 覆盖配置 / 配置国内镜像加速
python scripts/deploy_local.py --dir <部署目录> --set LLM_API_KEY=<用户的Key>
python scripts/deploy_local.py --dir <部署目录> --mirror
6a. 引导普通用户安装 Docker
使用者可能完全不懂 Docker，安装细节由 scripts/docker_bootstrap.py 接管，不要让他们自己折腾。
执行流程：
# 先检测环境到底缺什么（不动任何东西）
python <skill目录>/scripts/docker_bootstrap.py --check
# 需要安装时自动装（Windows 用 winget，macOS 用 brew），装完拉起并等待就绪
python <skill目录>/scripts/docker_bootstrap.py --install
# 只把已装好的 Docker Desktop 拉起来并等待就绪（常见卡点）
python <skill目录>/scripts/docker_bootstrap.py --start --wait 5
# 国内网络拉镜像慢/超时时，配置加速
python <skill目录>/scripts/docker_bootstrap.py --mirror
也可以让 deploy_local.py 一体化处理，检测到缺 Docker 时自动接管：
python <skill目录>/scripts/deploy_local.py --dir <部署目录> --install-docker --mirror
要点：
docker info在守护进程未连接时退出码仍是 0 但 stdout 为空，必须校验输出非空才能判定 daemon 在运行，否则会误报。--check会分别报告 Docker 命令、Compose 组件、守护进程三者的状态，并给出对应的大白话修复步骤，用户照做即可。- 装完普通用户往往不知道要手动打开 Docker Desktop，脚本的
--start会自动拉起并轮询等待就绪。 - 镜像源随时代变化，脚本内置了 2026 年仍可用的地址（轩辕/毫秒/DaoCloud），中科大、网易等旧地址已失效，不要在文档里推荐。
分支处理：不要硬编码 main。官方仓库的默认分支是 master，脚本会自动用 git ls-remote --symref 探测远端默认分支。只有需要指定非默认分支时才传 --branch。
脚本行为要点：
- 公开仓库是默认模式，加
--private才索取凭证；凭证经脱敏处理，克隆后立即从远端地址抹除。 - 克隆阶段禁用凭证助手与交互提示，避免 Windows 凭据管理器弹窗挂起进程，并设 15 分钟超时。
.env优先用仓库自带的.env.example生成，再补齐容器必需的键；这样能继承仓库真正期望的配置（例如 MySQL 用户etf_app）。- 首次构建通常耗时 5-15 分钟，属正常现象，不要用短超时中断它。
交付结果：脚本执行完成后，把系统界面地址 http://127.0.0.1:5173 通过文件呈现工具打开预览，并同时给出后端地址 http://127.0.0.1:8000 和接口文档地址。
后续操作：
- 检查状态：
python scripts/check_local.py --dir <部署目录> - 停止服务：
python scripts/stop_local.py --dir <部署目录> - 彻底清理并清空数据：追加
--purge，执行前必须向用户确认，因为 MySQL 数据和行情缓存不可恢复。 - 代码更新后需重新构建：
docker compose up -d --build（在部署目录执行）。
部署硬约束：
docker-compose.yml必须放在工程根目录，不能放进docker/子目录；Compose 按 compose 文件所在目录解析env_file、build.context和dockerfile。- 容器内 MySQL 地址必须是服务名
mysql，不能是127.0.0.1；脚本会强制写入MYSQL_HOST=mysql。 - 容器内前端用 nginx 托管静态产物并反代
/api到backend:8000；本地开发模式的 Vite 代理指向127.0.0.1:8000，在容器中会指向自身而失效，不要照搬。 - 仓库凭证只能通过参数或环境变量传入，禁止写入脚本、
.env、文档或任何 Skill 文件；日志输出须脱敏。 - 系统无认证且 CORS 宽松，仅限本机或内网使用；对外提供服务前需补充登录、权限控制、HTTPS 和用户数据隔离。
7. 执行策略并生成方案
用户要求「跑一遍策略」「执行选股」「给我一个配置方案」时，执行本流程。前提：系统已部署且健康，先用 check_local.py 确认。
执行策略：
# 依次运行 L1/L2/L3，并生成方案报告
python <skill目录>/scripts/run_strategy.py --dir <部署目录> --strategy all
# 追加一次回测验证
python <skill目录>/scripts/run_strategy.py --dir <部署目录> --strategy l2 --backtest `
--start 2024-01-02 --end 2024-12-31
脚本会触发策略、轮询进度、抓取 TOP5 和回测指标，最后生成 Markdown 报告。报告路径会打印在输出末尾。
脚本产出什么：执行概览、每个策略的口径说明与 TOP5 明细表、回测指标表、风险提示和免责声明。「结论与建议」一章是留给 AI 的空节，脚本不代写。
你的职责：读完报告后，用文件呈现工具打开报告，并在回复中补齐配置思路、仓位框架和风险边界。所有结论必须对应报告中的真实数据，不得凭记忆编造任何代码、得分或价位。给具体判断时按「输出规范」追加免责声明。
耗时预期：L1/L2/L3 是全市场运算，单个策略通常 5-20 分钟，脚本默认每个策略最多等 40 分钟。加 --force-fetch 会强制补拉最新日行情，更慢。等待过程中不要中断，脚本会周期性打印进度。
结果解读要点：
- L1 是趋势评分（对数回归收益 × R²），适合判断趋势强度。
- L2 是五因子横截面综合分，是轮动的主力口径。
- L3 在 L2 基础上叠加市场与个券 RSRS 过滤，信号更少但更保守。
- 三个策略结果不一致属正常：趋势与反转因子本身存在对冲关系，需结合市场环境说明。
输出规范
- 结论先行，随后给出策略依据、数据时点、来源和风险边界。
- 排名或比较多个标的时，每个标的都写完整标准代码；说明排序的量化依据，拿不到量化依据时明确这是定性排序。
- 任何具体买卖判断、价位或仓位建议，回复末尾必须追加固定免责声明：
> 免责声明：以上内容基于公开数据和量化分析，仅供参考，不构成投资建议。市场有风险，投资需谨慎。任何投资决策应结合个人风险承受能力、资金状况和投资目标独立判断，必要时咨询持牌专业机构。过往表现不预示未来收益。
参考资料
| 文件 | 内容 |
|---|---|
references/project-knowledge.md |
当前工程知识的精简版：架构、API、策略口径、验证方式、已知限制 |
references/local-deployment.md |
本地部署与策略执行手册：默认仓库、参数、Docker 安装引导、策略执行、排错表、安全边界 |
两份参考文档都是当前工程知识的提炼，若与当前代码冲突，以当前代码和测试为准。
