AlphaQuant-Bot · 系统架构设计

§ 01

一、系统分层架构

全栈按职责切分为 5 层，自上而下分别处理：用户配置、行情接入、领域计算、信号决策、结果输出。每一层只依赖下一层，可独立替换实现。

① 用户交互层

Presentation

任务管理页 task_manager.html

图表看板 btcusdt_ema_chart.html

职责：表单输入、参数校验、图表展示。接口：HTTP（fetch /api/tasks）+ 静态 JSON 数据消费。

HTTP / JSON：tasks 配置 ↑↓、klines + zones 静态文件 ↓

② 服务接入层

Service Gateway

任务配置服务 tasks_server.py · :5001

CCXT 接入层

OKX REST API

职责：任务持久化（tasks.json）、行情拉取代理。接口：REST /api/tasks + CCXT fetch_ohlcv()。

OHLCV 数组 [timestamp, o, h, l, c, v] · 任务参数 dict

③ 数据采集层

Data Pipeline

K 线采集 fetch_klines.py

本地缓存 *_klines.json

职责：定时采集（cron 0,15,30,45 * * * *）、去重合并、写盘。接口：内存 list[list] + 磁盘 JSON。

K 线列表 list[list[ts, o, h, l, c, v]] + 趋势/入场周期标识

④ 分析计算层

Domain Logic

M1 趋势分析 m1_trend.py

M2 关键位识别 m2_key_level.py

M3 信号检测

M4 交易计划

职责：所有领域计算的纯函数化封装。接口：dataclass（TrendResult / KeyLevel / Signal / Plan）。

TrendResult + list[KeyLevel] + Signal + TradingPlan

⑤ 输出推送层

Output / Notify

图表看板（再渲染）

Discord Bot Push

Telegram / Email（规划）

职责：把分析结果转成"用户可消费"的图表、文字、推送。接口：HTML 文件 + Discord Webhook / Bot API。

各层接口契约与可替换性

① 用户交互层已实现

包含模块: 任务管理页、图表看板（前端纯 HTML/JS）
对下接口: POST /api/tasks（写入任务）· GET /api/tasks（读取任务）· 通过 fetch 加载 *_klines.json
数据格式: 任务对象 {symbol, trend_tf, entry_tf, ema_periods, status}
可扩展: 可替换为 React/Vue SPA；图表可换 TradingView 嵌入；新增"回测面板"不影响下层

② 服务接入层已实现

包含模块: tasks_server.py（HTTP :5001）、CCXT 调用封装、OKX 外部 API
对上接口: RESTful /api/tasks，CORS 全开放
对下接口: 磁盘文件 tasks.json（系统唯一权威配置源）；行情接口 exchange.fetch_ohlcv(symbol, tf, since, limit)
可扩展: 可替换为 FastAPI/Flask；CCXT 已天然多交易所兼容，仅需切换 datafeed_exchange_id

③ 数据采集层已实现

包含模块: fetch_klines.py（含 cron）、本地 JSON 缓存
对上接口: 读取 tasks.json，调用 CCXT 接口
对下接口: 持久化为 {symbol}_klines.json，结构 list[[ts_ms, o, h, l, c, v]] 时间升序
可扩展: 可替换为 Redis / TimescaleDB 缓存；可注入 WebSocket 实时推送替代 cron 轮询

④ 分析计算层 M1/M2 已实现 · M3/M4 规划中

包含模块: M1 TrendModule、M2 KeyLevelModule、M3 SignalModule（规划）、M4 PlanModule（规划）
对上接口: 统一构造：Module(config).run(symbol, klines, ...) 返回 dataclass
对下接口: 纯函数式输出，不写盘、不发网络；输出被 ⑤ 层消费
可扩展: 每个模块为"算法可插拔"框架：M1 可换 MACD / SuperTrend；M2 可换聚类 / 价格密度；M3 可加 RSI 背离

⑤ 输出推送层图表+Discord 已实现 · 多渠道规划中

包含模块: 图表看板（再渲染）、Discord Bot、Telegram/Email（规划）
对上接口: 消费 dataclass（TrendResult / list[KeyLevel] / Signal / Plan），渲染或推送
对下接口: HTML 文件挂载到 nginx · Discord Bot API POST · 截图通过 Oracle 中转
可扩展: NotifierRegistry 模式：实现 Notifier.send(plan) 接口即可加入新渠道（Telegram / Email / Lark）

§ 02

二、每个模块的完整参数表

九个模块的输入 / 输出契约、核心算法描述、可替换框架。所有参数名以代码现状为准，规划模块按设计意图列出。

1. 任务管理页（前端表单）已实现

类型 前端 HTML · 文件 task_manager.html · 用户操作入口

▸ 输入参数（用户填写）

参数名	类型	默认值	说明
symbol	str	"BTC/USDT:USDT"	CCXT 格式的交易对，含合约后缀 `:USDT`
trend_tf	enum	"4H"	趋势周期；选项 15m / 1H / 4H / 1D
entry_tf	enum	"15m"	入场周期；通常比趋势周期更细
ema_periods	list[int]	[21, 55, 144]	三条 EMA 的周期数（fast/mid/slow）
status	enum	"running"	running / paused，用于启停任务

▸ 输出（提交给后端的 POST body）

字段	类型	说明
tasks	list[Task]	整张任务列表（全量覆盖，非增量）

▸ 核心逻辑

表单读取用户输入 → 前端用正则校验 symbol/tf 格式 → 序列化为 JSON → fetch POST /api/tasks。UI 上以列表展示已有任务，可启停、删除。

▸ 可替换实现

作为表现层可整体替换为 React/Vue/SwiftUI 应用，只要保持 POST/GET /api/tasks 的 JSON 契约即可。

2. 任务配置服务（tasks_server.py）已实现

类型 HTTP 服务 · 端口 5001 · 基于 BaseHTTPServer

▸ 输入参数

参数名	类型	默认值	说明
TASKS_FILE	path	./tasks.json	持久化路径（与脚本同目录）
port	int	5001	HTTP 监听端口
body	JSON	—	POST 请求体，必须是合法 JSON 数组

▸ 输出数据结构

字段	类型	说明
tasks.json	list[Task]	磁盘持久化，UTF-8 含缩进
GET /api/tasks	200 JSON	返回当前 tasks.json 全部内容
POST /api/tasks	{"ok":true}	校验为合法 JSON 后写盘

▸ 核心逻辑

极简 HTTP 服务：GET 透传文件 / POST 校验后写盘 / OPTIONS 处理 CORS。无并发锁——任务变更频率极低，竞态可接受。

▸ 可替换实现

未来可换为 FastAPI + Pydantic 校验 + SQLite 持久化；接口保持 /api/tasks 即可无缝替换。

3. K 线采集程序（fetch_klines.py）已实现

类型 定时脚本 · cron 0,15,30,45 * * * * · CCXT + OKX

▸ 输入参数

参数名	类型	默认值	说明
TIMEFRAME	str	"15m"	采集周期（当前硬编码，规划支持多周期）
DISPLAY_LIMIT	int	300	展示用 K 线根数
WARMUP_LIMIT	int	300	预热用 K 线根数（EMA144 需 ≥432）
INTERVAL_MS	int	900_000	周期毫秒数
SYMBOLS	list[tuple]	动态读 tasks.json	(ccxt_symbol, file_stem) 元组列表

▸ 输出数据结构

字段	类型	说明
{symbol}_klines.json	list[list]	结构 `[ts_ms, open, high, low, close, volume]`，时间升序
stdout 日志	text	每次拉取的统计与精度
下游触发	file write	JSON 写盘后，看板和 M1/M2 各自再次读取

▸ 核心逻辑

分两批拉取（warmup + display 共 ~600 根）→ 按 timestamp 去重合并 → 写盘。EMA144 收敛门槛 ≥432 根，预热保证首根计算准确。Discord 推送通过 Oracle 中转规避 AWS IP 限制。

▸ 可替换实现

CCXT 已封装 100+ 交易所，换 Binance 仅需改 datafeed_exchange_id；调度可换 APScheduler / Celery Beat / k8s CronJob；缓存可换 Redis Time Series。

4. 趋势分析模块 M1（m1_trend.py）已实现

类型 纯函数模块 · 类 TrendModule · 当前算法 ema_triple_v1

▸ 输入参数

参数名	类型	默认值	说明
symbol	str	—	交易对标识（仅透传到输出）
klines	list[list]	—	CCXT 格式 OHLCV，时间升序，含预热段
config.ema_fast	int	21	快线周期
config.ema_mid	int	55	中线周期
config.ema_slow	int	144	慢线周期

▸ 输出 TrendResult（dataclass）

字段	类型	说明
symbol	str	交易对透传
direction	Literal	"涨势" / "跌势" / "震荡"
ema_fast / mid / slow	float	最后一根 K 线对应的三条 EMA 数值（round 4 位）
source_close_time	str	ISO 8601 UTC 时间戳

▸ 核心算法逻辑

对收盘价序列分别计算三条 EMA（递推公式 k = 2/(n+1)） → 取最后一根的 (a, b, c)。多头排列 a>b>c=涨势；空头排列 a<b<c=跌势；其余=震荡。

▸ 可替换算法（框架说明）

TrendModule 是框架，目前实现是 ema_triple_v1。新增 macd_v1 / supertrend_v1 只需：① 实现同名 .run() 接口、② 返回相同 dataclass、③ 在 m0_config.py 切换 trend_method_main。下游无感知。

5. 关键位识别模块 M2（m2_key_level.py）已实现

类型 纯函数模块 · 类 KeyLevelModule · 支持方案 A / B / C 切换

▸ 输入参数

参数名	类型	默认值	说明
symbol	str	—	交易对标识
klines	list[list]	—	OHLCV 数组（最后一根为未收盘，会被剔除）
direction	str	—	趋势方向；当前实现按契约接收但未参与计算
swing_n	int	5	摆动点确认窗口（左右各 N 根无更高/低）
zone_pct	float	0.003	区间宽度（±0.15%，合并近邻摆动点用）
kline_window	int	300	展示窗口（超出此根数标记 EXPIRED）

▸ 输出 list[KeyLevel]（dataclass）

字段	类型	说明
symbol	str	交易对
price_high / price_low	float	区间上下边界（含 zone_pct 展开）
level_type	Literal	"support" / "resistance"（Flip 由上层组合判定）
status	Literal	"ACTIVE" / "HIDDEN" / "EXPIRED"
touch_count	int	区间内收盘价触碰计数
kline_index	int	摆动点所在 K 线索引

▸ 核心算法逻辑

扫描全部已收盘 K 线 → 在每个 swing_n 窗口内识别局部最高/最低 → 以摆动价 ±zone_pct/2 展开为价格区间 → 统计落在区间内的收盘价数量作 touch_count → 距今超出 kline_window 的标记 EXPIRED，仅返回 ACTIVE。当前在 m2 内部还包含 方案 A 聚类 / B 角色互换 / C 价格密度 三种 Flip 判定的备选路径。

▸ 可替换算法（框架说明）

关键位识别是独立框架。当前同模块内可切换 A/B/C；未来可接入 VPVR（成交量分布）、Order Block、Fair Value Gap 等算法，只要返回 list[KeyLevel] 即可。

6. 信号检测模块 M3 规划中

类型 纯函数模块 · 计划文件 m3_signal.py · 形态识别

▸ 输入参数（设计）

参数名	类型	默认值	说明
klines	list[list]	—	入场周期 K 线，至少需要最近 3 根
key_levels	list[KeyLevel]	—	M2 输出，用于"价格进入区间"判定
trend	TrendResult	—	M1 输出，用于过滤反向信号
pin_shadow_ratio	float	2.0	Pin Bar 影线 / 实体最小倍数
engulf_min_body_ratio	float	1.0	吞没形态实体比例阈值

▸ 输出 Signal（设计）

字段	类型	说明
direction	Literal	"long" / "short" / None（无信号）
pattern	Literal	"pin_bar" / "engulfing" / ...
trigger_kline_index	int	触发 K 线索引
trigger_price	float	触发价（通常为收盘价）
touched_zone	KeyLevel	触发的关键位区间引用

▸ 核心算法逻辑

最新 K 线的 [low, high] 与各关键位 [price_low, price_high] 区间相交 → 命中后运行形态识别（Pin Bar 看影线比例、吞没看相邻 K 线包含关系） → 与趋势方向比对，同向放行 / 反向丢弃。

▸ 可替换算法

作为形态检测框架，未来可加入 RSI 背离、Hammer、Doji、内包形态等；通过策略注册器组合多种形态。

7. 交易计划模块 M4 规划中

类型 纯函数模块 · 计划文件 m4_plan.py · 入场/止损/止盈/盈亏比

▸ 输入参数（设计）

参数名	类型	默认值	说明
signal	Signal	—	M3 输出
key_levels	list[KeyLevel]	—	用于查找止盈目标
sl_buffer_pct	float	0.001	止损在影线极值外的安全距离
min_rr	float	2.0	最小盈亏比阈值

▸ 输出 TradingPlan（设计）

字段	类型	说明
entry	float	入场价（触发 K 线收盘价或区间中心）
stop_loss	float	止损价（影线极值 ± sl_buffer_pct）
take_profit	float	止盈价（沿方向最近的下一关键位中心）
rr	float	盈亏比；< min_rr 时整个 plan 为 None
direction	Literal	"long" / "short"

▸ 核心算法逻辑

从信号取入场 → 把止损贴到 Pin Bar 影线极值外侧并加 sl_buffer_pct → 沿信号方向查询下一关键位区间中心 作为 TP → 计算 RR = |TP − entry| / |entry − SL| → 不达 min_rr 直接丢弃。

▸ 可替换算法

未来可加入 多档位止盈（TP1/TP2/TP3）、ATR 自适应止损、仓位大小计算（凯利公式或固定风险百分比）。

8. 图表看板（btcusdt_ema_chart.html）已实现 · 信号标注规划中

类型 纯前端 HTML · Canvas / ECharts · 自动刷新

▸ 输入数据

参数名	类型	说明
klines_json	JSON file	来自 fetch_klines.py 的 OHLCV
ema_values	list[3]	来自 M1 的三条 EMA 数值（或前端再算一次）
key_levels	list[KeyLevel]	来自 M2，绘制填充矩形
trading_plan	TradingPlan	规划中，绘制入场/止损/止盈三色虚线

▸ 输出

对象	说明
HTML 渲染	K 线主图 + EMA21/55/144 折线 + 关键位区间填充矩形（Flip 金色 / 支撑绿 / 阻力红）+ 算法切换 A/B/C 按钮
截图供推送	无头浏览器抓图，作为 Discord 消息附件

▸ 核心逻辑

fetch 加载 *_klines.json → Canvas 绘制 K 线 → 叠加 EMA 折线 → 遍历 key_levels 绘制半透明填充矩形并横跨时间轴 → 右侧标注 "FLIP ×11" 类文字。信号标注（箭头 + 三线 + 盈亏比）为下一阶段。

▸ 可替换实现

可替换为 TradingView Widget / Lightweight Charts / Plotly；保持读取相同 JSON 结构即可。

9. Discord 通知推送已实现

类型 Bot 集成 · Plugin 方式 · 通过 Oracle 中转

▸ 输入参数

参数名	类型	默认值	说明
channel_id	str	"1505213022656790698"	目标频道 ID
token	str	.env	Bot Token（从 ~/.claude/channels/... 读取）
content	str	—	消息文本（含交易对、趋势、入场/止损/止盈）
image_path	path	None	图表截图（规划中由 Playwright 生成）

▸ 输出

对象	说明
Discord 消息	带文本 + 截图附件的频道消息
http_code	用于错误恢复流程的状态反馈

▸ 核心逻辑

本机为 AWS IP，被 Cloudflare 限制 POST → SSH 到 Oracle 机器执行 curl → Discord API /channels/{id}/messages → 返回 http_code 用于失败重试。

▸ 可替换实现

抽象出 Notifier.send(plan, image) 接口；新增 TelegramNotifier / EmailNotifier / LarkNotifier 只需实现该接口并注册到 NotifierRegistry。

§ 03

三、完整流程图

四条流程覆盖系统全生命周期：主流程（每根 K 线收盘）、配置更新（用户操作）、错误恢复（异常路径）、初始化（启动加载）。

① 主流程：K 线收盘 → 推送闭环

⏱ 每根 K 线收盘后 · cron 触发 / 0,15,30,45 * * * *

K 线采集程序

← CCXT.fetch_ohlcv() · 拉 600 根（预热+展示）

合并去重 + 写盘 *_klines.json

→ 触发下游 M1 / M2

并行分析（独立无依赖）

M1 趋势分析 → TrendResult

M2 关键位识别 → list[KeyLevel]

M3 信号检测（价格 ∩ 关键位 + 形态识别 + 趋势同向）

分支判断

有信号

M4 交易计划（entry / SL / TP / RR）

RR ≥ min_rr

同时输出

图表叠加信号 + 三色虚线

Discord 推送（文本 + 截图）

无信号

仅更新图表（K 线/EMA/关键位）

等待下一根 K 线

② 配置更新流程：用户修改 → 下次采集生效

👤 用户在 task_manager.html 修改任务

前端校验（symbol/tf 格式、ema 正整数）

POST /api/tasks

tasks_server.py 校验 JSON 合法性

原子写入 tasks.json（全量覆盖）

⏱ 等待下一次 cron 触发（< 15 分钟）

fetch_klines.py 重新读 tasks.json

→ 新增 symbol 进入采集队列；已删除任务停止采集

新任务进入下一个主流程循环

③ 错误恢复流程：API 请求失败的退避与告警

调用 CCXT fetch_ohlcv() / Discord POST

捕获异常

异常类型判定（网络 / 限流 / 鉴权）

指数退避

重试 #1（等待 2 秒）

仍失败

重试 #2（等待 4 秒）

仍失败

重试 #3（等待 8 秒）

三次均失败

熔断 + 告警

跳过本轮（保留上一轮缓存）

写入 fetch_klines.log（含 stacktrace）

Discord 告警 channel 推送异常

⏱ 等待下一次 cron · 自动恢复

④ 初始化流程：系统冷启动 → 进入主循环

🚀 systemctl start / 容器启动

tasks_server.py 监听 :5001

加载 tasks.json（不存在则用 _DEFAULT_SYMBOLS）

遍历 running 任务，去重 symbol 列表

每个 symbol

预热阶段（首次拉取充足历史）

趋势周期：≥432 根（EMA144 收敛）

入场周期：≥300 根（信号检测窗口）

写入 {symbol}_klines.json · 内存预填

或常驻 scheduler 进程

进入主循环（§ ① 主流程）

§ 04

四、落地阶段计划

五个阶段从"已能用"逐步走到"可托管 7×24"。每阶段以用户视角的可体验效果为目标，附完整验收标准与 DoD。

Phase 1 · 已完成单品种行情看板 + 趋势 + 关键位

目标效果：用户打开浏览器，能看到 BTC/USDT 的实时 K 线图、三条均线、当前趋势文字标签（涨/跌/震荡）、关键位填充矩形，并能切换 A/B/C 三种算法对比。

▸ 模块清单

任务管理页（表单 + POST）· tasks_server.py（HTTP + 持久化）· fetch_klines.py（CCXT + cron）
M1 TrendModule · M2 KeyLevelModule（含 A/B/C 三种方案）
btcusdt_ema_chart.html（看板）· Discord Bot（每根 K 线收盘推送）

▸ 验收标准

tasks_server.py 监听 5001，curl POST /api/tasks 写入 tasks.json，GET 取回一致
fetch_klines.py 在 cron 节拍下生成 btcusdt_klines.json，最后一根 timestamp 与当前时间差 < 15 分钟
看板打开后能正确渲染最近 300 根 K 线、三条 EMA、≥3 个关键位矩形（Flip 金色、支撑绿、阻力红）
切换 A/B/C 按钮后矩形数量与位置发生明显变化（不同算法逻辑生效）
Discord 频道每 15 分钟收到 1 条文字通知（含 BTC 趋势 + EMA 值）

▸ 技术风险

⚠ EMA 收敛

首次启动 EMA144 不准 · 对策：预热 ≥432 根

⚠ AWS IP 限制

Discord POST 被 Cloudflare 阻断 · 对策：SSH Oracle 中转

Definition of Done：连续 72 小时无人工干预运行，看板与 Discord 推送均正常；切换算法立即生效；任务管理页能新增 / 删除任务。

Phase 2 · 当前阶段信号检测 + 交易计划 + 图表三线标注

目标效果：当 BTC 价格进入关键位区间 + 出现 Pin Bar/吞没形态 + 与趋势同向，用户能在图表上看到入场/止损/止盈三色虚线 + 盈亏比文字，并在 Discord 收到带截图的完整交易计划。

▸ 模块清单

M3 SignalModule（Pin Bar + 吞没形态）
M4 PlanModule（entry / SL / TP / RR 计算）
图表看板升级（增加三色虚线 + 信号箭头 + 盈亏比标注）
截图能力（Playwright 或 puppeteer 抓图）

▸ 验收标准

M3 输出 Signal dataclass，包含 direction / pattern / trigger_kline_index / touched_zone
M3 在历史数据回放中至少能识别出已知的 5 个 Pin Bar 案例（人工抽样验证）
M4 计算的 RR < min_rr 时返回 None，主流程跳过推送
图表能在触发 K 线位置绘制方向箭头，水平蓝/红/绿三色虚线分别对应 entry/SL/TP
Discord 推送的截图清晰可读，包含图表全部要素 + 文字行：方向 / 入场 / 止损 / 止盈 / 盈亏比

▸ 技术风险

⚠ 形态误识别

Pin Bar 阈值过宽产生噪音 · 对策：参数化阈值 + 回测样本调优

⚠ 截图延迟

Playwright 启动 ~3 秒影响时效 · 对策：预热常驻浏览器实例

Definition of Done：用历史数据回放至少识别出 10 个完整信号事件（含 plan）；实盘运行 1 周内至少有 3 个真实信号被准确推送；用户在 Discord 看到图带"看一眼就知道怎么下单"。

Phase 3 · 规划中多交易对并行 + 调度器化

目标效果：用户在任务管理页可同时启动 BTC / ETH / SOL 三个任务并行监控，每个任务独立运行、互不阻塞，看板支持多 tab 切换查看，Discord 推送区分品种和方向。

▸ 模块清单

调度器（APScheduler 或常驻 asyncio 进程，替代 cron）
任务级并发（每个 symbol 独立任务 ID，独立运行状态）
任务管理页扩展（多任务列表 + 状态徽章）
看板路由（/chart?symbol=BTC 动态切换）

▸ 验收标准

同时运行 ≥3 个任务，CPU 平均占用 < 30%，无相互阻塞
任一任务挂掉不影响其他任务（异常隔离）
任务管理页能看到每个任务的"最近运行时间 / 状态 / 最近一次信号"
看板能通过 URL 参数切换不同品种，且加载时间 < 1 秒
Discord 推送标题清晰标注 [BTC short] / [ETH long]

▸ 技术风险

⚠ 资源争抢

多任务同时调用 OKX 触发限流 · 对策：全局令牌桶限流 + 错峰调度

⚠ 缓存膨胀

多品种 JSON 文件占用磁盘 · 对策：定时清理 + 历史归档

Definition of Done：5 个交易对并行运行 7 天无故障；任意一个任务的状态变更对其他任务无副作用；用户可一键启停单个任务。

Phase 4 · 规划中系统健壮性 · 重试 / 日志 / 告警闭环

目标效果：用户即使关机一周回来，系统仍在稳定运行；遇到异常会自动恢复，关键失败有 Discord 告警弹窗，用户可在管理页看到运行健康度仪表盘。

▸ 模块清单

统一重试装饰器（指数退避 1s / 2s / 4s）
结构化日志（logging + JSON Lines 输出至 logs/）
告警通道（独立 Discord 告警 channel，区分 INFO / WARN / ERROR）
健康检查端点（/health 返回各模块最后心跳）
看板状态栏（红绿灯式健康指示）

▸ 验收标准

注入故障（断网 / Mock API 5xx）→ 系统在 30 秒内重试并恢复，不丢任务
三次重试全部失败 → 自动写日志 + 发送告警 + 跳过本轮、下一轮继续
logs/ 目录每天滚动一份，可追溯任意时刻的运行状态
/health 返回 200 + JSON，包含每个模块的 last_success_ts
任务管理页可看到"最近 24 小时错误数 / 告警数 / 信号数"

▸ 技术风险

⚠ 告警风暴

批量失败短时间内淹没 channel · 对策：同类告警 5 分钟合并

⚠ 日志爆盘

结构化日志体积增长 · 对策：logrotate + 14 天保留

Definition of Done：注入 10 种故障场景全部自动恢复；连续 30 天 SLA > 99%；故障告警 95% 在 1 分钟内送达。

Phase 5 · 规划中扩展能力 · 多交易所 + 多通知 + 回测

目标效果：用户可在配置文件中切换 OKX → Binance，新增 Telegram 频道，把任意历史时段的信号"回放"一次看效果，并对比不同算法（EMA 替换为 MACD）的胜率。

▸ 模块清单

DataFeed 抽象（OKX / Binance / Bybit 等可插拔）
Notifier 抽象（DiscordNotifier / TelegramNotifier / EmailNotifier 注册机制）
算法注册器（M1 / M2 / M3 多算法挂载）
回测引擎（消费历史 JSON，重放主流程，统计胜率 / RR / 最大回撤）
config.yaml 统一入口

▸ 验收标准

修改 config.yaml 中的 exchange: binance 后，无需改代码即可切换交易所
新增 notifiers: [discord, telegram] 后两个通道同时收到推送
把 trend_method: macd_v1 写入配置，下次启动即用 MACD 替代 EMA，下游无感
回测脚本能在 1 小时内跑完 6 个月 BTC 历史，输出 HTML 报告（胜率/RR 分布/累计收益）
回测复用同一套 M1/M2/M3/M4 模块，不需新增逻辑（仅替换 DataFeed 为历史读取）

▸ 技术风险

⚠ 交易所差异

不同交易所 symbol 命名/合约规则不同 · 对策：DataFeed 内做归一化适配

⚠ 回测幸存者偏差

仅看胜率会高估 · 对策：同时输出最大回撤、连亏次数

Definition of Done：切换交易所 / 通知通道 / 算法均为纯配置变更；回测产出的 HTML 报告与实盘看板使用同一套渲染逻辑。

§ 05

五、可扩展性说明

所有"算法 / 数据源 / 通知"均按框架 + 实现设计，新增能力不修改已有模块。

📈替换趋势算法

当前实现：ema_triple_v1。新增方法步骤：

在 trading/ 新建 m1_macd_v1.py，继承同样的 run(symbol, klines) -> TrendResult 签名
在 m0_config.py 中切换 trend_method_main: "macd_v1"
下游 M2 / M3 / 图表无感知（dataclass 契约不变）

🎯替换关键位算法

当前实现：S/R Flip（同模块内含方案 A / B / C）。扩展步骤：

新建 m2_vpvr_v1.py（成交量分布）或 m2_order_block_v1.py（订单块）
保持返回 list[KeyLevel]（含 price_high/low、level_type、touch_count）
在配置 key_level_method: "vpvr_v1" 即可切换

🌐支持更多交易所

当前实现：OKX（CCXT 封装）。CCXT 已支持 100+ 交易所，扩展步骤：

在 config.yaml 中改 datafeed_exchange_id: "binance"
更新 symbol 格式适配（如 BTC/USDT 现货 vs BTC/USDT:USDT 合约）
对接 API Key 与签名（如需私有接口）

💬支持更多通知渠道

当前实现：Discord Bot。NotifierRegistry 抽象：

定义 Notifier.send(plan, image_path) -> bool 接口
实现 TelegramNotifier / EmailNotifier / LarkNotifier
在 config.yaml 的 notifiers: [] 数组中按需启用，可多通道并发推送

config.yaml 结构建议

# ──── AlphaQuant-Bot 统一配置 ──── exchange: id: "okx" # 可选: okx / binance / bybit / ... datafeed_lib: "ccxt" api_key: "" # 仅私有接口需要 secret: "" tasks: - symbol: "BTC/USDT:USDT" trend_tf: "4H" entry_tf: "15m" kline_window: 300 warmup_window: 432 # EMA144 收敛 status: "running" algorithms: trend_method: "ema_triple_v1" # 可换 macd_v1 / supertrend_v1 ema_triple_v1: ema_fast: 21 ema_mid: 55 ema_slow: 144 key_level_method: "sr_flip_b" # 可换 sr_flip_a / sr_flip_c / vpvr_v1 sr_flip_b: swing_n: 5 zone_pct: 0.003 signal_method: "pin_bar_engulf_v1" pin_bar_engulf_v1: pin_shadow_ratio: 2.0 engulf_min_body_ratio: 1.0 plan: sl_buffer_pct: 0.001 min_rr: 2.0 notifiers: # 数组，按需启用多渠道 - type: "discord" channel_id: "1505213022656790698" token_env: "DISCORD_BOT_TOKEN" - type: "telegram" chat_id: "-1001234567890" token_env: "TG_BOT_TOKEN" scheduler: mode: "cron" # cron / apscheduler / asyncio_loop cron_expr: "0,15,30,45 * * * *" resilience: retry_max: 3 retry_backoff: [2, 4, 8] # 秒 alert_channel_id: "1505000000000000000" logging: level: "INFO" dir: "./logs" rotate_days: 14

一、系统分层架构

各层接口契约与可替换性

① 用户交互层 已实现

② 服务接入层 已实现

③ 数据采集层 已实现

④ 分析计算层 M1/M2 已实现 · M3/M4 规划中

⑤ 输出推送层 图表+Discord 已实现 · 多渠道规划中

二、每个模块的完整参数表

1. 任务管理页（前端表单） 已实现

2. 任务配置服务（tasks_server.py） 已实现

3. K 线采集程序（fetch_klines.py） 已实现

4. 趋势分析模块 M1（m1_trend.py） 已实现

5. 关键位识别模块 M2（m2_key_level.py） 已实现

6. 信号检测模块 M3 规划中

7. 交易计划模块 M4 规划中

8. 图表看板（btcusdt_ema_chart.html） 已实现 · 信号标注规划中

9. Discord 通知推送 已实现

三、完整流程图

① 主流程：K 线收盘 → 推送闭环

② 配置更新流程：用户修改 → 下次采集生效

③ 错误恢复流程：API 请求失败的退避与告警

④ 初始化流程：系统冷启动 → 进入主循环

四、落地阶段计划

五、可扩展性说明

📈替换趋势算法

🎯替换关键位算法

🌐支持更多交易所

💬支持更多通知渠道

config.yaml 结构建议

① 用户交互层已实现

② 服务接入层已实现

③ 数据采集层已实现

⑤ 输出推送层图表+Discord 已实现 · 多渠道规划中

1. 任务管理页（前端表单）已实现

2. 任务配置服务（tasks_server.py）已实现

3. K 线采集程序（fetch_klines.py）已实现

4. 趋势分析模块 M1（m1_trend.py）已实现

5. 关键位识别模块 M2（m2_key_level.py）已实现

8. 图表看板（btcusdt_ema_chart.html）已实现 · 信号标注规划中

9. Discord 通知推送已实现