合并方案：fixed_merge_to_allcoins → main

生成日期：2026-02-16
目标：将 fixed_merge_to_allcoins 分支合并到 main，使 main 同时支持通用多币种服务和 HYPE 专用服务

1. 概述

1.1 合并目标

在 main 分支上同时管理两个独立运行的服务：

两个服务共享同一套交易模块（src/trading/），通过 TradingConfig.is_symbol_allowed() 控制各自可交易的币种范围。

1.2 架构升级要点

fixed_merge_to_allcoins 分支对交易模块做了多币种隔离升级，核心变化：

• strategy.py：单体 SymbolState 拆分为 SymbolBaseline（纯计算状态）+ 独立的 per-symbol 字典
• orchestrator.py：数据灌入从单 symbol 改为 per-symbol 循环；数据自愈下沉到 service_base
• position_manager.py：新增禁止平仓机制、DB 恢复方法复用、孤儿检测优化

1.3 冲突规模

dry-run merge 检测到 12 个冲突文件：

.env.example                              内容冲突      低
docs/README.md                            modify/delete 低
src/config.py                             自动合并      -
src/trading/orchestrator.py               内容冲突      高
src/trading/position_manager.py           内容冲突      高
src/trading/risk_manager.py               内容冲突      中
src/trading/strategy.py                   内容冲突      高
src/utils/analysis/kline_data_filler.py   内容冲突      中
src/utils/analysis/risk_evaluator.py      add/add       中
src/utils/data_healing/repair_executor.py add/add       低
src/utils/hyperliquid_candles.py          add/add       低
src/utils/monitoring/alert_sender.py      add/add       中
src/utils/monitoring/signal_alert_formatter.py  add/add 中

2. 逐文件合并决策

2.1 核心交易模块（高优先级）

2.1.1 src/trading/strategy.py — 采用 allcoins 版本

决策：以 fixed_merge_to_allcoins 为准

理由：

• 拆分后语义更清晰：SymbolBaseline 生命周期是服务启动→结束，PositionTracker 是开仓→平仓
• per-symbol 的诊断/冷却/突破状态消除了多币种交叉污染风险
• 核心算法（EMA、Welford、adaptive_z）两版完全一致，不涉及计算逻辑变更

操作步骤：

# 冲突解决时直接采用 allcoins 版本
git checkout fixed_merge_to_allcoins -- src/trading/strategy.py

验证：确认 process_signal() 方法签名未变、prime_buffer(symbol, values) 接口兼容。

2.1.2 src/trading/orchestrator.py — 以 allcoins 为基础，合入 main 告警改动

决策：以 fixed_merge_to_allcoins 为基础

allcoins 版本包含 3 项关键改进：

main 在最新提交中也引入了 ENABLE_SIGNAL_DETAIL_ALERT、AlertSender、format_signal_alert 等，与 allcoins 的告警升级方向一致。

操作步骤：

# 1. 先采用 allcoins 版本
git checkout fixed_merge_to_allcoins -- src/trading/orchestrator.py

# 2. 手动确认以下 import 存在（allcoins 已包含）：
#    from src.utils.monitoring.alert_sender import AlertSender
#    from src.utils.monitoring.alert_level import AlertStatus
#    from src.utils.monitoring.signal_alert_formatter import format_signal_alert
#    from src.config import ENABLE_SIGNAL_DETAIL_ALERT

注意事项：

• allcoins 移除了 from src.config import HYPE_ALT_SYMBOL（不再硬编码单一 symbol）
• allcoins 移除了 self._risk_manager.load_peak_equity()（重启即新起点）
• _send_close_notification() 新增了 skip_reason 处理（配合 close_disabled 功能）
• 超时平仓改为限价单（force_market = "超时" not in reason），止损仍用市价单

2.1.3 src/trading/position_manager.py — 采用 allcoins 版本

决策：以 fixed_merge_to_allcoins 为准

allcoins 新增 3 项功能（纯增量，不删除已有逻辑）：

操作步骤：

git checkout fixed_merge_to_allcoins -- src/trading/position_manager.py

2.2 告警与监控模块（中优先级）

2.2.1 src/utils/monitoring/signal_alert_formatter.py — 采用 main 版本

决策：以 main (HEAD) 为准

操作步骤：

# 保留 main 版本（冲突解决时选择 ours）
git checkout HEAD -- src/utils/monitoring/signal_alert_formatter.py

2.2.2 src/utils/monitoring/alert_sender.py — 采用 main 版本

决策：以 main (HEAD) 为准

main 的逻辑更严谨：相同内容不管是否限流都不应重复发送。

操作步骤：

git checkout HEAD -- src/utils/monitoring/alert_sender.py

2.2.3 src/utils/analysis/risk_evaluator.py — 采用 main 版本

决策：以 main (HEAD) 为准

两版差异在于趋势维度的语义方向：

main 的 trend_safety 语义（越高越好）与其他 4 个维度方向一致，更直观，无需在加权时做反转。

操作步骤：

git checkout HEAD -- src/utils/analysis/risk_evaluator.py

注意：allcoins 版本新增了 _get_period_data() 辅助函数和部分注释。这些在 main 版本中已存在或不需要（signal_alert_formatter.py 中有同名函数）。

2.3 数据层模块（中优先级）

2.3.1 src/utils/analysis/kline_data_filler.py — 以 allcoins 为准

决策：以 fixed_merge_to_allcoins 为准

唯一变化：新增 max_duration=KLINE_FILLER_MAX_DURATION_SECONDS 参数传递（30 秒超时保护）。

操作步骤：

git checkout fixed_merge_to_allcoins -- src/utils/analysis/kline_data_filler.py

2.3.2 src/utils/hyperliquid_candles.py — 采用 allcoins 版本

决策：以 fixed_merge_to_allcoins 为准

新增 max_duration 参数支持和超时判断逻辑（配合 kline_data_filler 使用）。

操作步骤：

git checkout fixed_merge_to_allcoins -- src/utils/hyperliquid_candles.py

2.3.3 src/utils/data_healing/repair_executor.py — 采用 allcoins 版本

决策：以 fixed_merge_to_allcoins 为准

add/add 冲突，两边都是新文件。allcoins 版本更新更完整。

操作步骤：

git checkout fixed_merge_to_allcoins -- src/utils/data_healing/repair_executor.py

2.4 配置文件

2.4.1 src/config.py — 合并两边

决策：自动合并（git 已成功 auto-merge）

allcoins 的关键变更（全部采纳）：

• COINTEGRATION_THRESHOLD: 2 → 3（协整门槛提高）
• 新增 KLINE_FILLER_MAX_DURATION_SECONDS = 30（数据补充超时保护）
• 新增 HEALING_TIMEOUT_SECONDS（数据自愈超时）
• 注释增强（各参数增加中文说明）

2.4.2 src/trading/config.py — 采用 allcoins 版本

决策：以 fixed_merge_to_allcoins 为准（git 未报冲突，已自动合并）

allcoins 新增：

• close_disabled_symbols: set[str] 字段
• is_close_disabled(symbol) 方法
• _parse_close_disabled_symbols() 环境变量解析

2.4.3 .env.example — 以 allcoins 为基础，review 参数值

决策：以 fixed_merge_to_allcoins 为基础

allcoins 变更：

• 新增 LOG_LEVEL=DEBUG
• 新增 TRADING_CLOSE_DISABLED_SYMBOLS=
• TRADING_MAX_HOLD_HOURS: 72.0 → 0.5（需确认是否为测试值）
• TRADING_STRATEGY_ADAPTIVE_THRESHOLD: 2.5 → 4（全量币种适合更高阈值）
• TRADING_STRATEGY_COOLDOWN_MINUTES: 30 → 5
• 更详细的限价单配置注释

操作步骤：

git checkout fixed_merge_to_allcoins -- .env.example

⚠️ 合并后需 review：

• TRADING_MAX_HOLD_HOURS=0.5 是否仅用于测试？生产环境是否应恢复为 72.0？
• TRADING_STRATEGY_ADAPTIVE_THRESHOLD=4 对 HYPE 服务是否合适？（原 HYPE 用 2.5）

2.5 辅助文件

2.5.1 src/trading/risk_manager.py — 采用 allcoins 版本

决策：以 fixed_merge_to_allcoins 为准

变更很小：

• 移除 from pathlib import Path（不再使用）
• load_peak_equity() 方法被移除（重启即新起点，不加载历史峰值）
• update_peak_equity() 注释更新

git checkout fixed_merge_to_allcoins -- src/trading/risk_manager.py

2.5.2 docs/README.md — 保留 main 版本

决策：保留 main 版本

allcoins 删除了此文件（modify/delete 冲突），但 main 仍在维护。

git checkout HEAD -- docs/README.md

2.6 自动合并的文件（无冲突，确认即可）

以下文件 git 自动合并成功，需人工 review 确认无误：

2.7 allcoins 删除的文件

以下文件在 allcoins 分支被删除（main 上存在），合并后会被移除：

确认：这些文件是否都可以安全删除？如有需要保留的请在合并前标记。

3. 执行步骤

3.1 准备

# 确保工作区干净
git stash  # 如有未提交改动

# 更新两个分支到最新
git fetch origin

# 创建合并工作分支（可选，安全操作）
git checkout main
git checkout -b merge/allcoins-to-main

3.2 执行合并

# 开始合并（不自动提交）
git merge --no-commit --no-ff fixed_merge_to_allcoins

3.3 逐文件解决冲突

按优先级从高到低执行：

# ── 高优先级：核心交易模块 ──

# strategy.py — 采用 allcoins
git checkout fixed_merge_to_allcoins -- src/trading/strategy.py

# orchestrator.py — 采用 allcoins
git checkout fixed_merge_to_allcoins -- src/trading/orchestrator.py

# position_manager.py — 采用 allcoins
git checkout fixed_merge_to_allcoins -- src/trading/position_manager.py

# risk_manager.py — 采用 allcoins
git checkout fixed_merge_to_allcoins -- src/trading/risk_manager.py


# ── 中优先级：告警与监控 ──

# signal_alert_formatter.py — 保留 main（迭代降级更安全）
git checkout HEAD -- src/utils/monitoring/signal_alert_formatter.py

# alert_sender.py — 保留 main（去重优先+限流记hash更严谨）
git checkout HEAD -- src/utils/monitoring/alert_sender.py

# risk_evaluator.py — 保留 main（trend_safety语义统一）
git checkout HEAD -- src/utils/analysis/risk_evaluator.py


# ── 中优先级：数据层 ──

# kline_data_filler.py — 采用 allcoins（新增超时保护）
git checkout fixed_merge_to_allcoins -- src/utils/analysis/kline_data_filler.py

# hyperliquid_candles.py — 采用 allcoins（max_duration 支持）
git checkout fixed_merge_to_allcoins -- src/utils/hyperliquid_candles.py

# repair_executor.py — 采用 allcoins
git checkout fixed_merge_to_allcoins -- src/utils/data_healing/repair_executor.py


# ── 低优先级：配置与文档 ──

# .env.example — 采用 allcoins（合并后 review 参数值）
git checkout fixed_merge_to_allcoins -- .env.example

# docs/README.md — 保留 main
git checkout HEAD -- docs/README.md

3.4 暂存并检查

# 暂存所有解决后的文件
git add -A

# 检查是否还有未解决的冲突标记
grep -rn '<<<<<<< ' src/ .env.example docs/ || echo "无残留冲突标记"

# 查看最终 diff 确认改动合理
git diff --cached --stat

3.5 提交

git commit -m "$(cat <<'EOF'
merge: fixed_merge_to_allcoins → main (多币种策略架构升级)

核心变更:
- strategy.py: SymbolState 拆分为 SymbolBaseline + 独立 per-symbol 字典
- orchestrator.py: per-symbol 数据灌入 + 数据自愈下沉到 service_base
- position_manager.py: 禁止平仓机制 + DB恢复复用 + 孤儿检测优化
- kline_data_filler: 30s 超时保护
- config: COINTEGRATION_THRESHOLD=3

告警模块保留 main 版本:
- signal_alert_formatter: 迭代降级（更安全）
- alert_sender: 先去重再限流 + 限流记hash（更严谨）
- risk_evaluator: trend_safety 统一语义方向
EOF
)"

4. 合并后验证

4.1 语法检查

python -m py_compile src/trading/strategy.py
python -m py_compile src/trading/orchestrator.py
python -m py_compile src/trading/position_manager.py
python -m py_compile src/utils/analysis/kline_data_filler.py
python -m py_compile src/utils/monitoring/signal_alert_formatter.py
python -m py_compile src/utils/monitoring/alert_sender.py

4.2 import 链验证

确认 orchestrator 的 import 不报错：

python -c "
from src.trading.orchestrator import TradingOrchestrator
from src.trading.strategy import AdaptiveBollingerStrategy, SymbolBaseline, PositionTracker
from src.utils.monitoring.alert_sender import AlertSender
from src.utils.monitoring.signal_alert_formatter import format_signal_alert
from src.utils.analysis.risk_evaluator import evaluate_risk
print('All imports OK')
"

4.3 关键接口一致性检查

python -c "
from src.trading.strategy import AdaptiveBollingerStrategy
import inspect

# 确认 prime_buffer 接受 (symbol, values) 两个参数
sig = inspect.signature(AdaptiveBollingerStrategy.prime_buffer)
params = list(sig.parameters.keys())
assert params == ['self', 'symbol', 'z4h_values'], f'prime_buffer 签名异常: {params}'

# 确认 get_adaptive_z 接受 (symbol) 参数
sig2 = inspect.signature(AdaptiveBollingerStrategy.get_adaptive_z)
params2 = list(sig2.parameters.keys())
assert params2 == ['self', 'symbol'], f'get_adaptive_z 签名异常: {params2}'

print('API signatures OK')
"

4.4 risk_evaluator 语义一致性

确认 main 版本的 trend_safety 与 allcoins 的 trend_risk 不会在下游引起 KeyError：

# 搜索所有引用 trend_risk 或 trend_safety 的地方
grep -rn 'trend_risk\|trend_safety' src/

如果 signal_alert_formatter.py（main 版本）引用了 trend_safety，而 risk_evaluator.py 输出的 key 也是 trend_safety，则一致。如果有不匹配需要修正。

5. 运行约束

5.1 两个服务不能同时运行

建议：通过环境变量或启动脚本确保同一时间只运行一个服务。

5.2 .env 参数适配

合并后 .env.example 中部分参数值适合全量币种场景，HYPE 专用服务可能需要调整：

建议为两个服务维护独立的 .env 文件（如 .env.allcoins / .env.hype）。

6. 决策汇总表