283 lines
11 KiB
Markdown
283 lines
11 KiB
Markdown
# AGENTS.md
|
||
|
||
## 1. 项目定位
|
||
|
||
AlphaX 是一个以 `Python + FastAPI + SQLite + 静态 HTML` 组成的加密市场机会监控系统，当前核心目标不是做完整交易执行，而是围绕“发现机会 -> 确认机会 -> 跟踪机会 -> 复盘迭代”建立一套可持续优化的研究与提示闭环。
|
||
|
||
当前仓库是一个 **Docker 化副本**，从 `README_DOCKER.md` 的描述看，它被设计为和线上主实例隔离运行，默认端口、数据库挂载、调度器行为都以“先验证、后放量”为原则。
|
||
|
||
## 2. 当前技术栈
|
||
|
||
- 后端：`FastAPI`, `uvicorn`, `pydantic`
|
||
- 数据与计算：`sqlite3`, `pandas`, `numpy`
|
||
- 交易所/行情：`ccxt`, `requests`
|
||
- 配置：`rules.yaml` + `app/config/config_loader.py`
|
||
- 测试：`pytest` / `unittest`
|
||
- 部署：`Dockerfile`, `docker-compose.yml`
|
||
- 前端：`static/*.html` 模板页，由 FastAPI/Jinja2 提供页面壳和 API
|
||
|
||
## 3. 代码主线
|
||
|
||
### 3.1 业务闭环
|
||
|
||
建议把系统理解为 6 个层次：
|
||
|
||
1. `app/services/altcoin_screener.py`
|
||
负责粗筛，基于 Binance 行情、量价/结构等规则找候选币。
|
||
2. `app/services/altcoin_confirm.py`
|
||
负责确认，判断是否形成更可执行的机会，并生成入场计划、上下文和推送候选。
|
||
3. `app/services/price_tracker.py`
|
||
负责跟踪活跃推荐，更新盈亏、止盈止损、趋势衰减、行动状态。
|
||
4. `app/services/review_engine.py`
|
||
负责复盘与策略自迭代，包括信号绩效、漏选复盘、规则候选、版本演进。
|
||
5. `app/services/event_driven_screener.py`
|
||
负责事件/舆情驱动的快速触发检查，属于技术筛选主链路的补充入口。
|
||
6. `app/web/web_server.py`
|
||
现在主要负责 FastAPI 应用装配、模板装配和中间件绑定。
|
||
|
||
### 3.2 数据与状态中心
|
||
|
||
- `app/db/altcoin_db.py` 仍是交易/推荐/状态的核心数据库层，体量很大，当前主要承担：
|
||
- 初始化表结构
|
||
- recommendation / screening_log / tracking / review 等主表读写
|
||
- 推荐状态派生与展示口径整理
|
||
- 部分状态迁移与兼容逻辑
|
||
- `app/db/recommendation_queries.py`
|
||
- 已开始承接推荐热路径查询和推送冷却判断，如 active 推荐查询、push 去重、推送消费口径
|
||
- `app/db/analytics.py`
|
||
- 已开始承接筛选历史、复盘概览、cron 汇总等读多写少的查询
|
||
- `app/db/auth_db.py` 是会员、邀请码、邮箱验证、订阅、订单预留的数据库层。
|
||
- `app/core/opportunity_lifecycle.py` 是机会生命周期和买点质量闸门的规则中心，决定：
|
||
- 哪些机会只是观察池
|
||
- 哪些机会可以进入“可即刻买入”
|
||
- 哪些状态应该被视为历史/盈利管理/观察态
|
||
|
||
### 3.3 配置中心
|
||
|
||
- `rules.yaml` 是策略配置单一事实源。
|
||
- `app/config/config_loader.py` 负责：
|
||
- 读取/缓存配置
|
||
- 暴露各子模块配置访问函数
|
||
- 将部分复盘后的参数改写回 `rules.yaml`
|
||
- 兼容旧信号名
|
||
|
||
如果要改筛选阈值、确认门槛、止盈止损、动态权重逻辑，优先检查 `rules.yaml` 和 `app/config/config_loader.py`，不要直接在业务脚本里硬编码新参数。
|
||
|
||
## 4. 目录速览
|
||
|
||
### 4.1 核心目录
|
||
|
||
- `/app`
|
||
- 当前真实实现层，按职责拆成 `services`, `db`, `core`, `config`, `integrations`, `analysis`, `web`
|
||
- `/static`
|
||
- 页面文件，如 `app.html`, `auth.html`, `subscription.html`, `strategy.html`
|
||
- `/tests`
|
||
- 针对状态机、认证订阅、复盘、事件驱动、策略版本等的回归测试
|
||
- `/scripts`
|
||
- 若干结构/状态机/信号时效性校验脚本
|
||
- `/docker`
|
||
- 容器入口与串行调度器
|
||
- `/tools`
|
||
- 非主链路工具脚本，如回测和输出摘要脚本
|
||
- `/templates`
|
||
- 被后端读取的 HTML 模板资源
|
||
- `/reports`
|
||
- 本地分析/回测结果产物
|
||
- `/legacy`
|
||
- 历史实验脚本、旧页面备份、临时整理归档
|
||
- `/data`
|
||
- SQLite 数据库存放目录
|
||
- `/logs`
|
||
- 运行日志目录
|
||
- `/docs`
|
||
- 当前只有少量专题文档，不是完整系统文档中心
|
||
|
||
### 4.2 根目录关键文件
|
||
|
||
- [rules.yaml](/Users/aaron/Desktop/code/alphax-docker/rules.yaml)
|
||
- [docker-compose.yml](/Users/aaron/Desktop/code/alphax-docker/docker-compose.yml)
|
||
- [README_DOCKER.md](/Users/aaron/Desktop/code/alphax-docker/README_DOCKER.md)
|
||
|
||
### 4.3 根目录保留原则
|
||
|
||
根目录应尽量只保留这些类型：
|
||
|
||
- 顶层配置
|
||
- Docker 入口与部署文件
|
||
- 项目说明文档
|
||
- 明确约定的非代码资产目录
|
||
|
||
Python 业务实现不应再直接留在根目录。
|
||
|
||
像下面这些内容应放在分层目录里：
|
||
|
||
- 服务流程：`/app/services`
|
||
- 数据访问：`/app/db`
|
||
- 领域与规则：`/app/core`
|
||
- 配置访问：`/app/config`
|
||
- Web 层：`/app/web`
|
||
- 第三方集成：`/app/integrations`
|
||
- 顶层配置
|
||
- Docker 入口
|
||
- 关键说明文档
|
||
|
||
## 5. Web/API 观察
|
||
|
||
Web 层已经开始拆分，当前建议优先在这些文件上继续演进：
|
||
|
||
- `app/web/routes_auth.py`
|
||
- `app/web/routes_recommendations.py`
|
||
- `app/web/routes_strategy.py`
|
||
- `app/web/routes_admin.py`
|
||
- `app/web/routes_pages.py`
|
||
- `app/web/routes_content.py`
|
||
- `app/web/shared.py`
|
||
|
||
如果要改 Web 逻辑，先确认变更属于哪一类：
|
||
|
||
- “数据口径问题”优先去 `app/db/altcoin_db.py` / `app/core/opportunity_lifecycle.py`
|
||
- “参数问题”优先去 `rules.yaml`
|
||
- “页面展示问题”再回到 `static/*.html`
|
||
|
||
`app/web/web_server.py` 不应该再继续承载业务路由实现；新增接口优先落到对应 `routes_*` 模块。
|
||
|
||
## 6. 调度与运行方式
|
||
|
||
### 6.1 Docker 运行
|
||
|
||
主要服务：
|
||
|
||
- `alphax-web`
|
||
- 对外提供 FastAPI + 页面
|
||
- 宿主机默认映射 `8191 -> 8190`
|
||
- `alphax-scheduler`
|
||
- 串行调度任务
|
||
- 默认 `ALPHAX_SCHEDULER_DRY_RUN=1`
|
||
|
||
关键原则：
|
||
|
||
- 调度器是 **串行** 执行任务，用来规避 SQLite 写锁冲突。
|
||
- 副本默认不应影响线上实例。
|
||
- 数据库挂载路径是 `./data/altcoin_monitor.db`。
|
||
|
||
### 6.2 入口
|
||
|
||
- `docker/entrypoint.sh`
|
||
- `web` -> 启动 uvicorn (`app.web.web_server:app`)
|
||
- `scheduler` -> 启动 `docker/scheduler.py`
|
||
- `once` -> 执行单次脚本
|
||
- `app/cli.py`
|
||
- 统一命令入口：`screener / confirm / tracker / review / event / sentiment`
|
||
- `docker/scheduler.py`
|
||
- 统一通过 `python -m app.cli ...` 串行调度任务
|
||
|
||
## 7. 测试与验证建议
|
||
|
||
### 7.1 优先跑的测试
|
||
|
||
每次涉及以下模块改动时，至少补跑相关测试：
|
||
|
||
- 状态机 / 展示口径 / 推送条件
|
||
- `tests/test_recommendation_state_mainline.py`
|
||
- `tests/test_recommendation_execution_status.py`
|
||
- `tests/test_opportunity_lifecycle.py`
|
||
- 认证订阅
|
||
- `tests/test_user_subscription_auth.py`
|
||
- 舆情事件
|
||
- `tests/test_event_driven_screener.py`
|
||
- 时效性与门控
|
||
- `tests/test_confirm_freshness_gate.py`
|
||
- `tests/test_pa_recency.py`
|
||
- `tests/test_vp_fly_recency.py`
|
||
|
||
### 7.2 推荐命令
|
||
|
||
常用回归命令：
|
||
|
||
```bash
|
||
pytest -q
|
||
python3 scripts/validate_docker_layout.py
|
||
python3 scripts/validate_state_machine.py
|
||
python3 scripts/validate_push_state_flow.py
|
||
python3 scripts/validate_signal_recency.py
|
||
```
|
||
|
||
如果只是小范围修改，优先跑和改动模块最相关的测试文件，不要盲目只看 `pytest` 是否全绿。
|
||
|
||
## 8. 开发守则
|
||
|
||
### 8.1 改动前先判断“应该改哪一层”
|
||
|
||
- 调参数：优先 `rules.yaml`
|
||
- 配置读取/兼容：`app/config/config_loader.py`
|
||
- 状态口径：`app/core/opportunity_lifecycle.py` 或 `app/db/altcoin_db.py`
|
||
- DB 表结构/查询：`app/db/altcoin_db.py` / `app/db/auth_db.py`
|
||
- API 契约：优先对应 `app/web/routes_*.py`
|
||
- 页面壳和交互：`static/*.html`
|
||
|
||
### 8.2 SQLite 相关约束
|
||
|
||
这个项目高度依赖 SQLite，因此要特别注意：
|
||
|
||
- 避免引入并发写入路径
|
||
- 避免在不同脚本里制造长事务
|
||
- 任何新增 cron/task 设计，都先考虑是否会和现有调度冲突
|
||
- 新增写操作时，优先复用已有 `get_conn()` 约定
|
||
|
||
### 8.3 状态机不要各写各的
|
||
|
||
项目已经存在比较强的“状态派生中心化”趋势：
|
||
|
||
- `normalize_action_status`
|
||
- `derive_display_bucket`
|
||
- `apply_entry_quality_gate`
|
||
- `apply_recommendation_state_transition`
|
||
|
||
新增状态时，必须检查：
|
||
|
||
1. DB 中的原始状态字段怎么存
|
||
2. API 输出怎么派生
|
||
3. 前端如何解释
|
||
4. 推送是否会误触发
|
||
5. 相关测试是否需要补齐
|
||
|
||
### 8.4 面向兼容开发
|
||
|
||
这个仓库里有不少“迭代中兼容旧逻辑”的痕迹，例如：
|
||
|
||
- `app/config/config_loader.py` 中的信号别名兼容
|
||
- `app/db/altcoin_db.py` 中大量 `ALTER TABLE` 迁移兜底
|
||
- 多处 `entry_plan_json` / `detail_json` / `*_context_json`
|
||
|
||
因此改动时应优先做增量兼容，而不是假设数据库、配置、旧数据永远是干净新鲜的。
|
||
|
||
## 9. 当前仓库的几个事实
|
||
|
||
- 当前目录 **不是 git 仓库根目录**，`git status` 会失败；如果后续需要版本管理，请先确认真正的 Git 根目录或重新初始化。
|
||
- [DESIGN.md](/Users/aaron/Desktop/code/alphax-docker/DESIGN.md) 当前内容更像一份品牌/样式 YAML，不是这个项目的系统设计文档，阅读时不要误判。
|
||
- 根目录存在一些临时/非核心文件，例如 `.tmp_patch_tp1.py`、`.tmp_strategy_v2_marker.txt`、`=`，后续开发前建议先确认这些文件是否仍有保留价值。
|
||
- `app/db/altcoin_db.py` 仍然很大，后续新增 DB 查询应优先放到 `recommendation_queries.py`、`analytics.py`、`review_queries.py` 等分组模块。
|
||
|
||
## 10. 推荐的后续重构方向
|
||
|
||
后续若继续开发，建议优先考虑这几个方向：
|
||
|
||
1. 继续把剩余页面/内容能力从 `app/web` 拆成更细的 service 或 data provider，而不是继续把查询塞回路由层。
|
||
2. 继续把 `app/db/altcoin_db.py` 的真实实现迁出到 schema/init、recommendation、review、analytics、admin 分组模块。
|
||
3. 把 `rules.yaml` 的 schema 校验从“顶层结构校验”推进到“关键子字段校验”。
|
||
4. 让 Docker、文档、测试样例全面收敛到 `python -m app.cli ...` 入口。
|
||
5. 继续梳理推送链路，把“是否推送”的判断、推送内容组装、通道发送彻底分层。
|
||
|
||
## 11. 给后续 Agent 的工作方式建议
|
||
|
||
接手这个仓库时，优先按下面顺序理解问题：
|
||
|
||
1. 先确认问题发生在“筛选 / 确认 / 跟踪 / 复盘 / Web 展示 / 认证订阅”哪一层。
|
||
2. 再确认它属于“参数失真、状态派生错误、DB 查询口径不一致、前端展示错误、任务调度副作用”中的哪一类。
|
||
3. 修改后至少补 1 个相关测试，最好补到最接近业务口径的那层。
|
||
4. 如果变更影响推荐状态或展示桶，务必同时检查 API、前端、推送、历史统计四个面。
|
||
|
||
---
|
||
|
||
这份文档以当前仓库实际代码为准整理。如果后续完成模块拆分、引入新的持久层或把静态页面改造成更现代的前端工程，记得同步更新本文件，而不是让它变成另一份过时说明书。
|