2026-05-13 22:32:50 +08:00

9.9 KiB

Raw Blame History

AGENTS.md

1. 项目定位

AlphaX 是一个以 Python + FastAPI + SQLite + 静态 HTML 组成的加密市场机会监控系统，当前核心目标不是做完整交易执行，而是围绕“发现机会 -> 确认机会 -> 跟踪机会 -> 复盘迭代”建立一套可持续优化的研究与提示闭环。

当前仓库是一个 Docker 化副本，从 README_DOCKER.md 的描述看，它被设计为和线上主实例隔离运行，默认端口、数据库挂载、调度器行为都以“先验证、后放量”为原则。

2. 当前技术栈

后端：FastAPI, uvicorn, pydantic
数据与计算：sqlite3, pandas, numpy
交易所/行情：ccxt, requests
配置：rules.yaml + config_loader.py
测试：pytest / unittest
部署：Dockerfile, docker-compose.yml
前端：static/*.html 模板页，由 FastAPI/Jinja2 提供页面壳和 API

3. 代码主线

3.1 业务闭环

建议把系统理解为 6 个层次：

altcoin_screener.py 负责粗筛，基于 Binance 行情、量价/结构等规则找候选币。
altcoin_confirm.py 负责确认，判断是否形成更可执行的机会，并生成入场计划、上下文和推送候选。
price_tracker.py 负责跟踪活跃推荐，更新盈亏、止盈止损、趋势衰减、行动状态。
review_engine.py 负责复盘与策略自迭代，包括信号绩效、漏选复盘、规则候选、版本演进。
event_driven_screener.py 负责事件/舆情驱动的快速触发检查，属于技术筛选主链路的补充入口。
web_server.py 负责用户端和管理端 API、页面壳、订阅与认证相关接口。

3.2 数据与状态中心

altcoin_db.py 是交易/推荐/状态的核心数据库层，体量很大，承担了：
- 初始化表结构
- recommendation / screening_log / tracking / review 等主表读写
- 推荐状态派生与展示口径整理
- 部分状态迁移与兼容逻辑
auth_db.py 是会员、邀请码、邮箱验证、订阅、订单预留的数据库层。
opportunity_lifecycle.py 是机会生命周期和买点质量闸门的规则中心，决定：
- 哪些机会只是观察池
- 哪些机会可以进入“可即刻买入”
- 哪些状态应该被视为历史/盈利管理/观察态

3.3 配置中心

rules.yaml 是策略配置单一事实源。
config_loader.py 负责：
- 读取/缓存配置
- 暴露各子模块配置访问函数
- 将部分复盘后的参数改写回 rules.yaml
- 兼容旧信号名

如果要改筛选阈值、确认门槛、止盈止损、动态权重逻辑，优先检查 rules.yaml 和 config_loader.py，不要直接在业务脚本里硬编码新参数。

4. 目录速览

4.1 核心目录

/static
- 页面文件，如 app.html, auth.html, subscription.html, strategy.html
/tests
- 针对状态机、认证订阅、复盘、事件驱动、策略版本等的回归测试
/scripts
- 若干结构/状态机/信号时效性校验脚本
/docker
- 容器入口与串行调度器
/data
- SQLite 数据库存放目录
/logs
- 运行日志目录
/docs
- 当前只有少量专题文档，不是完整系统文档中心

4.2 根目录关键文件

5. Web/API 观察

web_server.py 体量非常大，既包含：

认证接口
订阅接口
推荐/筛选/复盘/策略看板接口
新闻/舆情接口
管理端接口
页面路由

如果要改 Web 逻辑，先确认变更属于哪一类：

“数据口径问题”优先去 altcoin_db.py / opportunity_lifecycle.py
“参数问题”优先去 rules.yaml
“页面展示问题”再回到 static/*.html

不要第一反应直接在 web_server.py 里堆业务分支，否则会继续放大这个文件的复杂度。

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
- scheduler -> 启动 docker/scheduler.py
- once -> 执行单次脚本
docker/scheduler.py
- 统一调度 event_driven_screener.py
- price_tracker.py
- altcoin_confirm.py
- altcoin_screener.py
- sentiment_monitor.py
- review_engine.py

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 推荐命令

常用回归命令：

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
配置读取/兼容：config_loader.py
状态口径：opportunity_lifecycle.py 或 altcoin_db.py
DB 表结构/查询：altcoin_db.py / auth_db.py
API 契约：web_server.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

新增状态时，必须检查：

DB 中的原始状态字段怎么存
API 输出怎么派生
前端如何解释
推送是否会误触发
相关测试是否需要补齐

8.4 面向兼容开发

这个仓库里有不少“迭代中兼容旧逻辑”的痕迹，例如：

config_loader.py 中的信号别名兼容
altcoin_db.py 中大量 ALTER TABLE 迁移兜底
多处 entry_plan_json / detail_json / *_context_json

因此改动时应优先做增量兼容，而不是假设数据库、配置、旧数据永远是干净新鲜的。

9. 当前仓库的几个事实

当前目录 不是 git 仓库根目录，git status 会失败；如果后续需要版本管理，请先确认真正的 Git 根目录或重新初始化。
DESIGN.md 当前内容更像一份品牌/样式 YAML，不是这个项目的系统设计文档，阅读时不要误判。
根目录存在一些临时/非核心文件，例如 .tmp_patch_tp1.py、.tmp_strategy_v2_marker.txt、=，后续开发前建议先确认这些文件是否仍有保留价值。
web_server.py 和 altcoin_db.py 都已经非常大，后续新增功能应尽量避免继续把复杂度集中到这两个文件。

10. 推荐的后续重构方向

后续若继续开发，建议优先考虑这几个方向：

把 web_server.py 按认证、推荐、策略、管理端拆分路由模块。
把 altcoin_db.py 拆成 schema/init、recommendation、review、analytics、admin 查询几个子模块。
为 rules.yaml 建立更明确的 schema 校验，避免配置漂移。
给核心脚本增加更稳定的 CLI 参数入口，而不是依赖脚本内默认行为。
梳理推送链路，把“是否推送”的判断和“推送内容生成”进一步解耦。

11. 给后续 Agent 的工作方式建议

接手这个仓库时，优先按下面顺序理解问题：

先确认问题发生在“筛选 / 确认 / 跟踪 / 复盘 / Web 展示 / 认证订阅”哪一层。
再确认它属于“参数失真、状态派生错误、DB 查询口径不一致、前端展示错误、任务调度副作用”中的哪一类。
修改后至少补 1 个相关测试，最好补到最接近业务口径的那层。
如果变更影响推荐状态或展示桶，务必同时检查 API、前端、推送、历史统计四个面。

这份文档以当前仓库实际代码为准整理。如果后续完成模块拆分、引入新的持久层或把静态页面改造成更现代的前端工程，记得同步更新本文件，而不是让它变成另一份过时说明书。

9.9 KiB Raw Blame History Unescape Escape