alphax/AGENTS.md

AGENTS.md

1. 项目定位

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

当前仓库是一个 Docker 化运行目录。运行时数据库已经切换为 PostgreSQL；SQLite 只作为历史数据导入来源，不再作为应用运行时数据库。后续开发和排查都应以 PostgreSQL、DATABASE_URL、Docker 服务和当前 migration 为准。

2. 当前技术栈

• 后端：FastAPI, uvicorn, pydantic
• 数据库：PostgreSQL 16，连接入口为 DATABASE_URL
• 数据访问：psycopg + 兼容旧 row 读取方式的 DbRow
• 数据与计算：pandas, numpy
• 交易所/行情：ccxt, requests
• 配置：rules.yaml + app/config/config_loader.py + system_config/runtime DB 配置
• 测试：pytest / unittest
• 部署：Dockerfile, docker-compose.yml
• 前端：static/*.html 页面，由 FastAPI/Jinja2 提供页面壳和 API

3. 真实运行架构

3.1 Docker 服务

当前 docker-compose.yml 定义的核心服务：

• postgres
  • PostgreSQL 16
  • 默认宿主机端口 5433 -> 5432
  • 数据保存在 compose volume postgres_data
• alphax-web
  • FastAPI + 页面/API
  • 默认宿主机端口 8191 -> 8190
  • 启动入口：app.web.web_server:app
• alphax-scheduler
  • 后台调度器
  • 从 PostgreSQL 中读取任务配置和运行状态
  • 以并发子进程运行，通过 lock group 避免关键写路径冲突
• alphax-price-streamer
  • 实时价格流服务
  • 更新最新价格缓存，供页面和部分链路读取

关键原则：

• PostgreSQL 是唯一运行时数据库。
• DATABASE_URL 是唯一运行时数据库连接入口。
• SQLite 只用于历史导入脚本，不参与应用运行。
• .env、data/、数据库文件、日志等不应被打进镜像。

3.2 数据库入口

• app/db/schema.py
  • PostgreSQL schema/init 门面。
  • init_db() 实际调用 apply_migrations()。
  • get_conn 来自 app.db.postgres_connection.connect。
• app/db/postgres_connection.py
  • PostgreSQL 连接、migration、row factory 的底层实现。
  • DbRow 用于兼容旧代码里按下标读取 row 的过渡逻辑。
• app/db/migrations/*.sql
  • PostgreSQL migration 单一事实源。
  • 新表/字段优先新增 migration，不要在业务函数里临时补 schema。

3.3 调度入口

• docker/entrypoint.sh
  • web -> 启动 uvicorn
  • scheduler -> 启动 docker/scheduler.py
  • price-streamer -> 启动实时价格流
  • once -> 执行单次命令
• docker/scheduler.py
  • 从 scheduler_job_config 加载任务。
  • 写入 scheduler_runtime_status。
  • 支持 scheduler_manual_trigger 手动触发。
  • 使用 lock group 控制并发冲突。
• app/cli.py
  • 统一命令入口：screener, confirm, tracker, paper-trader, price-streamer, market, review, event, sentiment, onchain, llm-insights。

4. 代码主线

4.1 推荐系统业务闭环

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

1. app/services/market_overview.py 采集全市场快照，为行情环境、涨幅榜和市场温度提供数据。
2. app/services/altcoin_screener.py 负责粗筛/细筛，基于 Binance 行情、量价/结构等规则找候选币。
3. app/services/altcoin_confirm.py 负责确认，判断候选是否形成更可执行的机会，并生成入场计划、上下文和推送候选。
4. app/services/event_driven_screener.py 负责事件/舆情驱动的快速触发检查，是技术筛选主链路的补充入口。
5. app/services/price_streamer.py 负责实时价格缓存，不等同于完整推荐状态跟踪。
6. app/services/price_tracker.py 负责可执行推荐的价格跟踪、状态迁移和动态风险提示。
7. app/services/paper_trader.py 负责模拟交易账本同步，真实 TP/SL、移动止盈、杠杆和资金口径在 paper trading 层管理。
8. app/services/review_engine.py 负责复盘与策略自迭代，包括信号绩效、漏选复盘、规则候选、版本演进。

4.2 Web/API

app/web/web_server.py 只应负责 FastAPI 应用装配、模板装配、中间件、全局异常处理和 router include。新增业务 API 优先放到对应 route 模块：

• app/web/routes_auth.py
• app/web/routes_chat.py
• app/web/routes_recommendations.py
• app/web/routes_review_center.py
• app/web/routes_strategy.py
• app/web/routes_onchain.py
• app/web/routes_paper_trading.py
• app/web/routes_market.py
• app/web/routes_admin.py
• app/web/routes_pages.py
• app/web/routes_content.py
• app/web/shared.py

如果要改 Web 逻辑，先判断问题属于哪一层：

• 数据口径问题：优先检查 app/db/*、app/core/opportunity_lifecycle.py、app/core/opportunity_funnel.py
• 参数问题：优先检查 rules.yaml、app/config/config_loader.py
• 页面展示问题：再检查 static/*.html
• 管理端/运行态问题：检查 app/db/scheduler_db.py、app/db/runtime_config_db.py、app/config/system_config.py

4.3 状态与漏斗中心

• app/core/opportunity_lifecycle.py
  • 推荐生命周期、展示桶、执行状态、买点质量闸门的中心。
  • 新增状态时必须同步 API、前端、推送、统计和测试。
• app/core/opportunity_funnel.py
  • 漏斗阶段词表与筛选层映射中心。
  • 筛选、确认、pipeline 页面和分析口径应优先复用这里的 vocabulary。
• app/core/opportunity_level.py
  • 机会级别、持有周期、入场/止损/止盈模型等结构化口径。
• app/core/signal_taxonomy.py
  • 信号分类与信号语义口径。

5. 数据与状态中心

5.1 DB 模块分工

• app/db/altcoin_db.py
  • 现在主要是历史兼容门面和少量读接口；推荐写入、推送、状态派生、跟踪、筛选、cron、复盘基础写入等都应走细分模块。
  • 后续新增查询不要默认继续塞回这里，优先放到更细分模块。
• app/db/recommendation_commands.py
  • 推荐创建、旧推荐过期、推荐 action_status 状态迁移、派生字段重算、操作状态更新。
• app/db/coin_state_queries.py
  • 旧 coin_state 兼容状态写入、active 状态读取、过期状态清理。
• app/db/screening_queries.py
  • 筛选日志写入、细筛历史读取、确认层候选读取。
• app/db/recommendation_state.py
  • 推荐状态派生、展示桶、发现层/交易层字段、entry_plan 解析、观察池分层。
• app/db/recommendation_queries.py
  • 推荐热路径查询、active/deduped 查询；不应反向依赖 altcoin_db.py。
• app/db/push_queries.py
  • 推送冷却去重、推送日志、推送前单条推荐读取；推送层只能消费这里派生后的主链路口径。
• app/db/tracking_queries.py
  • 最新价格缓存、推荐跟踪价格/PnL 写入、入场时点更新。
• app/db/cron_queries.py
  • cron/调度任务运行日志写入、列表与汇总查询。
• app/db/review_basic_queries.py
  • 基础复盘写入、漏选记录写入、信号绩效和动态权重读取。
• app/db/strategy_rule_queries.py
  • 策略规则候选、失败模式、候选状态判定、历史回填、候选生成、dry-run/refresh、迭代 dashboard 等复盘迭代基础能力。
• app/db/strategy_insights.py
  • 策略归因读模型，基于 opportunity/recommendation 与 paper_trades 转化统计，不把 recommendation.pnl_pct 当交易收益。
• app/db/analytics.py
  • 筛选历史、复盘概览、cron 汇总等读多写少查询。
• app/db/review_queries.py
  • 策略迭代日志和汇总查询；不应再直接顶层依赖 altcoin_db.py。
• app/db/admin_queries.py
  • 管理端数据查询。
• app/db/scheduler_db.py
  • 调度任务配置、运行态、手动触发。
• app/db/runtime_config_db.py
  • 运行时系统配置。
• app/db/paper_trading.py
  • 模拟交易账本、仓位、成交事件和资金口径。
• app/db/market_db.py
  • 市场快照。
• app/db/system_logs.py
  • 系统错误与异常日志。
• app/db/auth_db.py
  • 用户、会员、邀请码、邮箱验证、订阅、订单预留。

5.2 核心表

当前 PostgreSQL 运行时重要表包括：

• recommendation
• screening_log
• price_tracking
• latest_price_cache
• review_log
• missed_explosions
• cron_run_log
• scheduler_job_config
• scheduler_runtime_status
• scheduler_manual_trigger
• paper_trades
• paper_trade_events
• market_snapshots
• sentiment_events
• onchain_*
• llm_insights
• system_config
• system_error_log
• app_user / user_* / subscription_plan

不要把 SQLite 文件或 data/altcoin_monitor.db 当作当前状态来源。排查最近链路数据时，优先查询 PostgreSQL。

6. 配置中心

• rules.yaml 是策略参数单一事实源。
• app/config/config_loader.py 负责读取、缓存、兼容旧信号名，以及部分复盘参数写回。
• app/config/rules_schema.py 负责规则结构校验。
• app/config/system_config.py 负责运行时系统配置，如 scheduler dry run、poll interval 等。
• system_config / strategy_runtime_config 等 PostgreSQL 表承载运行态配置。

如果要改筛选阈值、确认门槛、止盈止损、动态权重逻辑，优先检查 rules.yaml 和 app/config/config_loader.py。如果要改调度行为或系统开关，优先检查 runtime config，而不是只看环境变量。

7. 目录速览

• /app
  • 真实实现层，按职责拆成 services, db, core, config, integrations, analysis, web
• /static
  • 页面文件，如 app.html, pipeline.html, paper_trading.html, review_center.html, market.html, onchain.html, chat.html
• /tests
  • 状态机、认证订阅、推荐链路、调度、模拟交易、行情、复盘、前端页面约束等回归测试
• /scripts
  • 校验脚本和 PostgreSQL 导入/备份/恢复脚本
• /scripts/postgres
  • PostgreSQL migration、SQLite 历史导入、导入校验、备份恢复
• /docker
  • 容器入口与调度器
• /tools
  • 非主链路工具脚本，如回测和输出摘要脚本
• /templates
  • 后端读取的 HTML 模板资源
• /docs
  • 项目结构、迁移、专题审计、参考 schema 等文档
• /data
  • 本地挂载数据目录，主要用于历史导入源或运行产物，不是 PostgreSQL 主存储
• /logs
  • 运行日志目录

根目录应尽量只保留：

• 顶层配置
• Docker 入口与部署文件
• 项目说明文档
• 明确约定的非代码资产目录

Python 业务实现不应直接留在根目录。

8. 运行与验证

8.1 Docker 启动

常规启动：

cp .env.example .env
docker compose build
docker compose up -d postgres alphax-web alphax-scheduler alphax-price-streamer

访问：

http://127.0.0.1:8191

常用状态检查：

docker compose ps
docker compose logs --tail=100 alphax-web
docker compose logs --tail=100 alphax-scheduler
docker compose logs --tail=100 alphax-price-streamer

容器内 API smoke：

docker compose exec alphax-web curl -fsS http://127.0.0.1:8190/api/stats
docker compose exec alphax-web curl -fsS 'http://127.0.0.1:8190/api/pipeline/runs?page=1&page_size=5'
docker compose exec alphax-web curl -fsS http://127.0.0.1:8190/api/onchain/overview

8.2 CLI

统一入口：

python -m app.cli screener
python -m app.cli confirm
python -m app.cli tracker
python -m app.cli paper-trader
python -m app.cli market
python -m app.cli review
python -m app.cli event
python -m app.cli sentiment --collect
python -m app.cli onchain
python -m app.cli llm-insights --scope sentiment --limit 40

Docker 内建议通过 docker compose exec alphax-web python -m app.cli ... 执行，确保使用容器内 DATABASE_URL 和依赖环境。

8.3 测试与校验

常用回归命令：

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

涉及 PostgreSQL migration/import 时：

docker compose run --rm alphax-web python scripts/postgres/run_migrations.py
docker compose run --rm alphax-web python scripts/postgres/validate_import.py --all-tables

如果只是小范围修改，优先跑和改动模块最相关的测试文件，不要盲目只看 pytest 是否全绿。

9. 开发守则

9.1 改动前先判断“应该改哪一层”

• 调参数：优先 rules.yaml
• 策略配置读取/兼容：app/config/config_loader.py
• 系统运行态配置：app/config/system_config.py / app/db/runtime_config_db.py
• 状态口径：app/core/opportunity_lifecycle.py
• 漏斗口径：app/core/opportunity_funnel.py
• DB 表结构：新增 PostgreSQL migration
• DB 查询：优先对应 app/db/*_queries.py 或细分 DB 模块
• API 契约：优先对应 app/web/routes_*.py
• 页面壳和交互：static/*.html
• 调度任务：app/cli.py + app/db/scheduler_db.py + docker/scheduler.py

9.2 PostgreSQL 约束

这个项目当前运行时依赖 PostgreSQL，因此要特别注意：

• 不要新增 SQLite 运行时分支。
• 不要把 data/*.db 当作线上或当前状态来源。
• schema 变化必须通过 app/db/migrations/*.sql。
• 查询最新运行状态优先看 PostgreSQL 表，而不是历史文件。
• Docker 容器内运行和宿主机运行可能使用不同连接地址，排查时先确认 DATABASE_URL。
• 调度器并发运行时要检查 lock group，避免多个任务同时写推荐主链路。

9.3 状态机不要各写各的

项目已经存在比较强的状态派生中心化趋势：

• normalize_action_status
• derive_display_bucket
• apply_entry_quality_gate
• apply_recommendation_state_transition
• screening_stage_meta
• build_screening_detail

新增状态时，必须检查：

1. DB 中原始状态字段怎么存。
2. API 输出怎么派生。
3. 前端如何解释。
4. 推送是否会误触发。
5. paper trading 是否会误开仓或误平仓。
6. 复盘统计是否会被污染。
7. 相关测试是否需要补齐。

9.4 推荐链路当前特别注意点

当前主链路已经能持续产生筛选和确认样本，但后半段仍需要重点盯住：

• latest_price_cache 可能是实时的，但不代表 recommendation.pnl_pct 已更新。
• price_tracking 是跟踪流水，不应和 latest_price_cache 混为一谈。
• price_tracker.py 会为 active 观察池样本更新观察价/PnL，但未触发入场的 watch_pool/wait_pullback 不能触发止盈止损、不能进入 paper trading 收益账本。
• rec_state 是发现层状态（如“爆发/加速”），execution_status/trade_stage 才是交易执行阶段（如 buy_now/wait_pullback/observe），不要把“发现爆发”直接解读成“现在可买”。
• 静K蓄力旁路已要求配置化共振（见 rules.yaml 的 screener.static_accumulation_bypass.require_resonance），避免单一静K样本淹没确认层；无追高风险的强势榜异动仍可作为发现入口。
• paper_trader.py 只应处理可执行推荐，不能把观察池样本当成已成交。
• review_engine.py 的可信度依赖跟踪数据质量；如果 PnL 没更新，复盘结论也会失真。
• missed_explosions 历史数据可能存在同一 symbol 多次记录，读模型/KPI 需要保持去重口径，写入侧后续仍建议加唯一性或冷却约束。

9.5 面向兼容开发

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

• DbRow 兼容旧的 row 下标读取。
• app/config/config_loader.py 中的信号别名兼容。
• 多处 entry_plan_json / detail_json / *_context_json。
• app/db/altcoin_db.py 仍承载较多历史兼容逻辑。

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

10. 当前仓库事实

• 当前运行态是 PostgreSQL，不是 SQLite。
• README_DOCKER.md 是 Docker/PostgreSQL 运行说明的重要事实源。
• docs/PROJECT_STRUCTURE.md 记录了目录整理背景，但具体运行状态仍以代码、compose 和 PostgreSQL 为准。
• DESIGN.md 当前更像品牌/样式 YAML，不是系统架构设计文档。
• app/db/altcoin_db.py 仍保留兼容门面，但推荐写入/状态迁移已迁到 recommendation_commands.py，推送去重已迁到 push_queries.py，状态派生、价格/跟踪写入、筛选日志、旧 coin_state、cron 日志、基础复盘写入、策略规则候选、策略归因也已迁出；后续新增 DB 查询应优先放到 recommendation_queries.py、screening_queries.py、tracking_queries.py、cron_queries.py、review_basic_queries.py、strategy_rule_queries.py、strategy_insights.py、analytics.py、review_queries.py、admin_queries.py、paper_trading.py 等分组模块。

11. 推荐的后续重构方向

后续若继续开发，建议优先考虑：

1. 继续把 app/db/altcoin_db.py 剩余读接口迁到 recommendation_queries.py / analytics.py，最终让它只保留极薄兼容导出或逐步废弃。
2. 为 watch_pool / wait_pullback 建立更完整的观察绩效报表，继续避免和已执行仓位 PnL 混在一起。
3. 把 rules.yaml 的 schema 校验从“顶层结构校验”推进到“关键子字段校验”。
4. 让 Docker、文档、测试样例全面收敛到 python -m app.cli ... 入口。
5. 继续梳理推送链路，把“是否推送”的判断、推送内容组装、通道发送彻底分层。
6. 对 missed_explosions 写入侧建立唯一性或冷却约束，避免重复样本继续进入历史表。
7. 梳理 price-streamer、tracker、paper-trader 三者边界，确保实时价格、推荐跟踪、模拟成交各自语义清晰。

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

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

1. 先确认问题发生在“筛选 / 确认 / 跟踪 / 模拟交易 / 复盘 / Web 展示 / 认证订阅 / 调度运行态”哪一层。
2. 再确认它属于“参数失真、状态派生错误、DB 查询口径不一致、前端展示错误、任务调度副作用、数据水位滞后、样本去重缺失”中的哪一类。
3. 排查数据时直接查 PostgreSQL，不要使用 SQLite 文件作为当前状态来源。
4. 修改后至少补 1 个相关测试，最好补到最接近业务口径的那层。
5. 如果变更影响推荐状态或展示桶，务必同时检查 API、前端、推送、paper trading、历史统计五个面。
6. 如果变更影响调度任务，务必检查 scheduler_job_config、scheduler_runtime_status 和最近 cron_run_log。

---

这份文档以当前仓库实际代码、Docker compose 和 PostgreSQL 运行态为准整理。后续如果引入新的服务、迁移表结构、改变调度模式或调整推荐状态机，必须同步更新本文件，避免后续 Agent 再被过时信息带偏。