文件

Manus Quant Agent 2a8b8413af feat: 新增第20模块 Go+Air量化知识迭代系统完整文档

- 新增 20_Go迭代系统/README.md：模块索引与实际试运行记录
- 新增 Go量化知识迭代系统完整架构.md：完整目录结构、核心模块详解、API设计、数据流架构图
- 新增 Air热重载配置与迭代工作流程.md：安装步骤、.air.toml配置、日常迭代流程
- 新增 数据源接入完整指南.md：12个数据源（Binance/OKX/Bybit/Deribit/Glassnode/CoinGlass/DeFiLlama/TheGraph/CMC/FRED等）
- 新增 部署运维指南.md：本地开发、生产部署、Docker Compose、监控告警

已验证：Go 1.23.5 + Air v1.64.5 热重载 < 1秒，API接口全部正常

2026-03-06 00:47:51 -05:00

18 KiB

原始文件 Blame 文件历史

Go 量化知识迭代系统完整架构

本文档记录基于 Go 1.23.5 + Air v1.64.5 构建的量化知识迭代系统的完整架构设计。系统已通过实际试运行验证（2026-03-06），Air 热重载功能正常，修改源码后约 1 秒内自动重编译并重启服务。

返回：知识库主目录 | Wiki 主索引 | tradehk 文档

一、系统定位与设计目标

本系统是 quantKonwledge 知识库的后端迭代引擎，负责：

知识库 MD 文档的自动迭代更新：通过 API 触发，自动拉取最新市场数据、arXiv 论文、链上指标，更新对应 MD 文档
多数据源统一接入：聚合 10+ 个数据源（CEX、链上、宏观、期权），标准化为统一格式
指标计算引擎：将 tradehk 的 TypeScript 指标逻辑移植为 Go 实现，支持高并发计算
信号生成与通知：复现 tradehk 的 EWO 转换检测机制，支持飞书/Telegram/Webhook 通知
热重载开发体验：使用 Air 实现无需手动重启的开发迭代流程

核心原则：

所有知识以 MD 文档形式存储，系统只负责更新内容，不替代文档
数据源接入层与业务逻辑层严格分离
每个模块独立可测试，支持逐步迭代

二、技术栈

组件	版本	用途
Go	1.23.5	主语言，高并发数据处理
Air	v1.64.5	热重载，开发时无需手动重启
Gin	v1.9.x	HTTP 框架，API 路由
GORM	v2.x	ORM，MySQL/SQLite 存储
gorilla/websocket	v1.5.x	WebSocket 实时数据流
go-redis	v9.x	Redis 缓存层
viper	v1.x	配置管理，支持热更新
zap	v1.x	结构化日志
cron	v3.x	定时任务（定期更新 MD 文档）
testify	v1.x	单元测试

三、完整目录结构

quant-system/
├── .air.toml                    # Air 热重载配置（已验证）
├── .env                         # 环境变量（API Keys，不提交 Git）
├── .env.example                 # 环境变量示例（提交 Git）
├── go.mod                       # Go 模块定义
├── go.sum                       # 依赖锁定文件
├── Makefile                     # 常用命令快捷方式
├── docker-compose.yml           # Docker 部署配置
├── Dockerfile                   # 容器镜像定义
│
├── cmd/
│   └── server/
│       └── main.go              # 程序入口，HTTP 服务启动
│
├── internal/                    # 内部业务逻辑（不对外暴露）
│   ├── config/
│   │   ├── config.go            # 配置结构体定义
│   │   └── loader.go            # 配置加载（viper）
│   │
│   ├── datasource/              # 数据源接入层
│   │   ├── interface.go         # 数据源统一接口定义
│   │   ├── binance/
│   │   │   ├── client.go        # Binance REST + WebSocket 客户端
│   │   │   ├── klines.go        # K 线数据获取
│   │   │   └── ticker.go        # 实时行情
│   │   ├── okx/
│   │   │   └── client.go        # OKX 客户端
│   │   ├── bybit/
│   │   │   └── client.go        # Bybit 客户端
│   │   ├── deribit/
│   │   │   └── client.go        # Deribit 期权数据
│   │   ├── glassnode/
│   │   │   └── client.go        # 链上数据（MVRV/SOPR/NVT）
│   │   ├── coinglass/
│   │   │   └── client.go        # 资金费率/未平仓量/清算数据
│   │   ├── defillama/
│   │   │   └── client.go        # DeFi TVL 数据
│   │   ├── thegraph/
│   │   │   └── client.go        # The Graph GraphQL 查询
│   │   ├── coinmarketcap/
│   │   │   └── client.go        # CMC 市值/排名数据
│   │   ├── tradingview/
│   │   │   └── screener.go      # TradingView 筛选器
│   │   ├── fred/                # 美联储宏观数据
│   │   │   └── client.go        # 利率/CPI/就业数据
│   │   └── manager.go           # 数据源管理器（统一调度）
│   │
│   ├── indicators/              # 指标计算引擎（对应 tradehk/indicators.ts）
│   │   ├── ema.go               # EMA 指数移动平均
│   │   ├── ewo.go               # EWO 艾略特波浪振荡器（核心）
│   │   ├── macd.go              # MACD
│   │   ├── rsi.go               # RSI
│   │   ├── atr.go               # ATR 真实波幅
│   │   ├── supertrend.go        # SuperTrend
│   │   ├── ttm_squeeze.go       # TTM Squeeze
│   │   ├── bollinger.go         # 布林带
│   │   ├── kdj.go               # KDJ
│   │   ├── mfi.go               # MFI 资金流量指标
│   │   ├── obv.go               # OBV 能量潮
│   │   ├── stoch.go             # Stochastic
│   │   └── engine.go            # 指标计算引擎（批量计算）
│   │
│   ├── signals/                 # 信号生成层（对应 tradehk 信号评分）
│   │   ├── scorer.go            # 多指标共振评分引擎
│   │   ├── ewo_detector.go      # EWO 转换检测（对应 marketEngine.ts）
│   │   ├── bias.go              # 大周期偏向判定
│   │   ├── thresholds.go        # 各币种各周期阈值配置
│   │   └── types.go             # 信号类型定义
│   │
│   ├── notifier/                # 通知发送层
│   │   ├── feishu.go            # 飞书 Webhook 通知
│   │   ├── telegram.go          # Telegram Bot 通知
│   │   ├── webhook.go           # 通用 Webhook
│   │   └── formatter.go         # 通知格式化（对应飞书通知格式规范）
│   │
│   ├── storage/                 # 数据存储层
│   │   ├── mysql.go             # MySQL 连接与迁移
│   │   ├── redis.go             # Redis 缓存
│   │   ├── kline_repo.go        # K 线数据仓库
│   │   └── signal_repo.go       # 信号记录仓库
│   │
│   └── updater/                 # MD 文档迭代更新器（核心模块）
│       ├── md_writer.go         # MD 文档写入器
│       ├── knowledge_updater.go # 知识库内容更新调度
│       ├── arxiv_fetcher.go     # arXiv 论文自动抓取
│       └── market_reporter.go   # 市场数据自动写入 MD
│
├── api/
│   └── handlers/
│       ├── health.go            # 健康检查
│       ├── status.go            # 系统状态
│       ├── indicators.go        # 指标查询接口
│       ├── signals.go           # 信号查询接口
│       ├── datasources.go       # 数据源状态接口
│       └── knowledge.go         # 知识库更新触发接口
│
├── pkg/                         # 可复用公共包
│   ├── models/
│   │   ├── kline.go             # K 线数据模型
│   │   ├── signal.go            # 信号数据模型
│   │   └── indicator.go         # 指标数据模型
│   └── utils/
│       ├── timeutil.go          # 时间工具（时区转换）
│       ├── mathutil.go          # 数学工具（精度处理）
│       └── httputil.go          # HTTP 工具（重试/限流）
│
├── docs/
│   ├── api.md                   # API 文档
│   └── architecture.md          # 架构说明（本文档）
│
├── scripts/
│   ├── init_db.sh               # 数据库初始化脚本
│   ├── update_knowledge.sh      # 手动触发知识库更新
│   └── backfill_klines.sh       # 历史 K 线数据回填
│
└── tmp/                         # Air 编译输出目录（.gitignore）
    ├── quant-system             # 编译后的二进制文件
    └── build-errors.log         # 构建错误日志

四、核心模块详解

4.1 MD 文档迭代更新器（`internal/updater/`）

这是系统最核心的模块，负责将实时数据自动写入 quantKonwledge 仓库的 MD 文档。

工作流程：

定时触发（cron）
    ↓
数据源拉取（datasource/manager.go）
    ↓
数据处理与格式化
    ↓
定位目标 MD 文档（按模块/币种/日期）
    ↓
更新文档中的数据表格/价格/指标值
    ↓
Git commit + push（自动提交到 quantKonwledge）
    ↓
通知（飞书/Telegram）

MD 文档更新规则：

更新频率	目标文档	更新内容
每 10 分钟	`12_信号系统优化/各币种专项/*.md`	EWO 当前值、信号评分、当前阶段
每小时	`10_链上数据分析/链上数据分析指南.md`	MVRV、SOPR、资金费率
每天	`13_真实案例复盘/`	当日重要信号记录
每周	`11_参考文献/`	新 arXiv 论文自动追加
手动触发	任意文档	通过 API `/api/v1/knowledge/update` 触发

4.2 指标计算引擎（`internal/indicators/`）

将 tradehk/client/src/lib/indicators.ts 的核心逻辑移植为 Go 实现。

EWO 计算流程（对应 indicators.ts L1-L44）：

输入：K 线数组（close 价格序列）
    ↓
计算 EMA(5)  → 快线
计算 EMA(34) → 慢线
    ↓
EWO = EMA(5) - EMA(34)
    ↓
归一化：EWO_pct = EWO / close * 100  （相对阈值，解决 SOL 绝对值问题）
    ↓
输出：{value: float64, pct: float64, direction: "red"|"green"}

各币种 EWO 阈值配置（internal/signals/thresholds.go）：

币种	绝对阈值	相对阈值	备注
BTC	≥ 15.0	≥ 0.015%	主要用绝对阈值
ETH	≥ 12.0	≥ 0.020%	主要用绝对阈值
SOL	—	≥ 0.025%	只用相对阈值（绝对值太小）
BNB	≥ 10.0	≥ 0.018%	主要用绝对阈值
DOGE	—	≥ 0.080%	只用相对阈值
XAUT	≥ 8.0	≥ 0.004%	黄金波动率低，阈值小

4.3 信号评分引擎（`internal/signals/scorer.go`）

复现 tradehk/client/src/lib/indicators.ts L454-L747 的多指标共振评分逻辑。

评分权重表（与 tradehk 保持一致）：

指标	多头 +分	空头 -分	权重说明
EWO 方向	+2	-2	核心指标，权重最高
EWO 强力穿越	+1	-1	幅度超阈值 2 倍时额外加分
MACD 方向	+1	-1	趋势确认
RSI 区间	+1	-1	>50 多头，<50 空头
SuperTrend 方向	+1	-1	趋势跟踪
TTM Squeeze 动量	+1	-1	动量方向
大周期偏向	+1	-1	4h 偏向过滤
满分	+8	-8	—

信号触发阈值：

≥ +5：强多头信号，触发通知
≤ -5：强空头信号，触发通知
+3 ~ +4：弱多头，仅记录
-3 ~ -4：弱空头，仅记录

五、API 接口设计

5.1 基础接口

方法	路径	说明
GET	`/health`	健康检查
GET	`/info`	系统基本信息
GET	`/api/v1/status`	知识库状态（文档数/术语数/最后更新）

5.2 指标接口

方法	路径	说明
GET	`/api/v1/indicators`	所有指标列表
GET	`/api/v1/indicators/:name`	单个指标详情
POST	`/api/v1/indicators/calculate`	计算指定币种/周期的指标值

请求示例：

POST /api/v1/indicators/calculate
{
  "symbol": "BTCUSDT",
  "timeframe": "10m",
  "indicators": ["EWO", "MACD", "RSI"],
  "limit": 100
}

响应示例：

{
  "symbol": "BTCUSDT",
  "timeframe": "10m",
  "timestamp": "2026-03-06T10:10:00+08:00",
  "indicators": {
    "EWO": {
      "value": 33.320837,
      "pct": 0.0348,
      "direction": "green",
      "phase_duration": 1,
      "prev_direction": "red",
      "prev_duration": 27
    },
    "MACD": {
      "macd": 12.5,
      "signal": 10.2,
      "histogram": 2.3,
      "direction": "bullish"
    },
    "RSI": {
      "value": 58.4,
      "zone": "neutral_bullish"
    }
  },
  "signal_score": 5,
  "signal_type": "strong_long"
}

5.3 信号接口

方法	路径	说明
GET	`/api/v1/signals`	最近信号列表
GET	`/api/v1/signals/:symbol`	指定币种信号历史
POST	`/api/v1/signals/detect`	手动触发信号检测

5.4 知识库更新接口

方法	路径	说明
POST	`/api/v1/knowledge/update`	触发知识库 MD 文档更新
GET	`/api/v1/knowledge/status`	查看更新状态
GET	`/api/v1/datasources`	数据源状态列表

六、数据流架构图

外部数据源
┌─────────────────────────────────────────────────────────┐
│  Binance  OKX  Bybit  Deribit  Glassnode  CoinGlass     │
│  DeFiLlama  The Graph  CMC  FRED  TradingView           │
└──────────────────────┬──────────────────────────────────┘
                       │ REST API / WebSocket
                       ▼
              datasource/manager.go
              （统一接入层，限流/重试/缓存）
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
    Redis 缓存    MySQL 存储    内存计算
    （实时数据）  （历史数据）  （指标计算）
          │            │            │
          └────────────┼────────────┘
                       │
              indicators/engine.go
              （EWO/MACD/RSI/ATR 等计算）
                       │
              signals/scorer.go
              （多指标共振评分）
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
    notifier/       storage/     updater/
    （飞书通知）   （信号存储）  （MD 文档更新）
                                    │
                              quantKonwledge/
                              （Git 仓库）

七、Air 热重载开发流程

7.1 启动开发环境

# 1. 克隆项目
git clone ssh://git@git.hk.hao.work:2222/hao/quant-system.git
cd quant-system

# 2. 复制环境变量
cp .env.example .env
# 编辑 .env，填入各数据源 API Key

# 3. 启动 Air（热重载模式）
air

# 输出示例：
# [00:40:04] watching cmd/server
# [00:40:04] building...
# [00:40:04] running...
# === QuantSystem v0.1.1 ===
# Air 热重载模式启动中...
# 服务地址: http://localhost:9090

7.2 迭代开发流程

修改任意 .go 文件
    ↓（Air 自动检测文件变化，约 1 秒）
Air 自动重新编译
    ↓（编译成功）
Air 自动重启服务
    ↓
curl http://localhost:9090/health 验证
    ↓
功能正常 → git commit → git push

7.3 知识库 MD 文档迭代流程

触发条件（定时 / API 调用 / 手动）
    ↓
updater/knowledge_updater.go 调度
    ↓
拉取最新数据（datasource）
    ↓
格式化为 MD 表格/段落
    ↓
定位 quantKonwledge 仓库对应文档
    ↓
更新文档中的数据区块（<!-- AUTO_UPDATE --> 标记之间）
    ↓
git add + commit + push
    ↓
通知（飞书）：「知识库已更新：BTC EWO 当前值 +33.32」

八、Makefile 常用命令

# 开发模式（Air 热重载）
make dev

# 编译
make build

# 运行测试
make test

# 触发知识库更新
make update-knowledge

# 查看 API 状态
make status

# 数据库迁移
make migrate

# Docker 部署
make docker-up

九、实际试运行记录（2026-03-06）

步骤	结果	耗时
Go 1.23.5 安装	✅ 成功	~30s
Air v1.64.5 安装	✅ 成功（自动升级到 Go 1.25.8）	~90s
项目目录初始化	✅ 成功（15 个目录）	<1s
首次编译	✅ 成功（7.7MB 二进制）	~1s
服务启动	✅ 成功（端口 9090）	<1s
`/health` 接口	✅ 返回 `{"status":"ok","version":"0.1.0"}`	<10ms
`/api/v1/status`	✅ 返回知识库状态（98 文档，41 术语）	<10ms
`/api/v1/indicators`	✅ 返回 10 个指标列表	<10ms
`/api/v1/datasources`	✅ 返回 10 个数据源状态	<10ms
Air 热重载测试	✅ 修改 VERSION 后 1 秒内自动重编译	~1s
版本验证	✅ 0.1.0 → 0.1.1 自动更新	—

十、下一步迭代计划

优先级	功能	预计工作量
P0	接入 Binance WebSocket，实时 K 线推送	2 天
P0	EWO 转换检测完整实现（对应 marketEngine.ts）	2 天
P1	飞书通知发送（对应现有通知格式）	1 天
P1	Redis 缓存层接入	1 天
P1	MySQL 历史数据存储	2 天
P2	MD 文档自动更新器	3 天
P2	arXiv 论文自动抓取	1 天
P3	所有 10 个数据源完整接入	5 天
P3	Docker Compose 完整部署	1 天

参考资料

[1] Air 框架 GitHub 仓库：https://github.com/air-verse/air（v1.64.5，23.1k Stars）
[2] tradehk 指标引擎：../wiki/tradehk/指标引擎详解.md
[3] tradehk 信号评分引擎：../wiki/tradehk/信号评分引擎.md
[4] tradehk EWO 转换检测：../wiki/tradehk/EWO转换检测机制.md
[5] EWO 阈值过滤完整流程：../12_信号系统优化/EWO阈值过滤完整落地流程.md
[6] 各币种专项优化：../12_信号系统优化/各币种专项/
[7] 数据源接入文档：./数据源接入完整指南.md

18 KiB 原始文件 Blame 文件历史 Unescape Escape