DEV Community: Henry Lin

美股-后端服务模块

Henry Lin — Sun, 14 Jun 2026 09:19:45 +0000

后端服务模块（backend/）

FastAPI 后端负责加载离线快照数据，提供查询、过滤、排序等 API，支持实时数据推送、预警系统、信号产品系统、因子回测和宏观/板块数据接口。

目录结构

backend/
├── main.py               # FastAPI 应用入口，路由注册，生命周期管理
├── prod_app.py           # 生产环境应用（含静态文件服务）
├── loader.py             # 数据加载、缓存、查询引擎
├── meta.py               # 元数据与筛选分组定义
├── presets.py            # 多时间周期预设策略定义
├── market_hours.py       # 美股交易时段与假日日历
│
│  # ── 实时数据 ──
├── rt_api.py             # 实时数据 API 路由
├── rt_hub.py             # 实时推送中心（WebSocket 编排）
├── rt_ws.py              # WebSocket 端点（设备注册、订阅管理）
├── rt_aliyun_ticker.py   # 阿里云行情后台 Ticker
│
│  # ── 预警系统 ──
├── alerts_api.py         # 预警 API 路由（CRUD + 事件查询）
├── alerts_db.py          # SQLite 存储层（规则、事件、设备）
├── alert_engine.py       # 预警引擎（规则评估、状态管理）
├── alert_dispatcher.py   # 预警分发器（WebSocket 推送）
├── alert_evaluators.py   # 规则评估器（6 种预警类型）
├── alert_models.py       # 数据结构（AlertRule, AlertEvent 等）
├── alerts_presets.py     # 预警模板（6 种预设规则）
│
│  # ── 信号产品系统 ──
├── signal_product_api.py    # 信号产品 API 路由（候选池、信号、绩效、模拟交易）
├── signal_product_models.py # 信号数据模型（Candidate/Signal/Outcome/Position）
├── signal_product_db.py     # 信号 SQLite 持久化（4 表：candidates/signals/outcomes/positions）
├── signal_entry_engine.py   # 盘中信号入场评估引擎
│
│  # ── 回测系统 ──
├── backtest_api.py       # 因子回测 API 路由（IC 评估、绩效分析）
│
│  # ── 数据接口 ──
├── screener_api.py       # 选股器 API（排名、评分）
├── macro.py              # 宏观经济指标接口
├── sectors.py            # 板块轮动数据接口
│
│  # ── 工具 ──
├── app/factors/
│   └── date_utils.py     # 日期格式工具（YYYYMMDD 标准化）
└── test_*.py             # 测试文件

启动流程

应用启动
  ↓
加载 config.yaml（实时数据 + 预警配置）
  ↓
load_snapshot()  → 缓存到 _SNAPSHOT_CACHE
load_history()   → 缓存到 _HISTORY_CACHE
  ↓
初始化 RTManager（实时数据管理器）
初始化 RTHub（推送中心）
初始化 AlertEngine + AlertDispatcher（预警引擎）
初始化 DeviceRegistry（WebSocket 设备注册）
初始化 SignalProductRepository（信号产品 SQLite）
  ↓
注册路由 + CORS 中间件
  ↓
可选：启动 Aliyun Ticker（后台定时获取行情）
  ↓
uvicorn 启动，监听 8000 端口

各文件详解

main.py — 应用入口

FastAPI 应用的主入口，管理生命周期和路由。

生命周期：

启动时：加载配置、初始化实时数据管理器、RTHub 推送中心、预警引擎、信号产品仓库、加载快照和历史数据
关闭时：停止 Aliyun Ticker、清理资源

API 端点：

端点	方法	说明	参数
`/api/meta`	GET	返回筛选元数据（分组、标签、统计）	—
`/api/stocks`	GET	查询股票列表	filters, conditions, sort_by, sort_asc, offset, limit
`/api/pattern-stats`	GET	形态统计（触发次数、胜率、收益率）	—
`/api/combo-stats`	GET	多信号组合统计	—
`/api/stocks/{symbol}/history`	GET	单只股票历史 K 线	range (3m/6m/1y/2y)
`/api/stock/{symbol}`	GET	单只股票快照数据	—
`/api/stocks/{symbol}/fundamentals`	GET	单只股票基本面数据	—
`/api/presets`	GET	多时间周期预设策略列表	—

loader.py — 数据引擎

核心数据模块，负责 parquet 加载、内存缓存和查询处理。

缓存机制：

data.parquet  →  _SNAPSHOT_CACHE (DataFrame)  →  内存常驻
history.parquet → _HISTORY_CACHE (DataFrame)  →  内存常驻

全局变量 _SNAPSHOT_CACHE / _HISTORY_CACHE 实现懒加载
首次访问时从磁盘加载，后续直接读内存

查询流程：

query_stocks(filters, conditions, sort_by, sort_asc, offset, limit)
  ↓
_apply_filters()      →  按标志列筛选（value=1）
  ↓
_parse_conditions()   →  解析 JSON 条件（支持 <, <=, >, >=, =）
  ↓
_apply_conditions()   →  应用连续值条件过滤
  ↓
排序 + 分页
  ↓
_to_records()         →  转换为 JSON 格式返回

列分类：

类别	说明	示例
REQUIRED_COLUMNS	必需字段	trade_date, symbol, name
CONTINUOUS_FILTER_COLUMNS	连续值列	ret_1d, ma5, forward_pe, piotroski_score, value_quality_score, altman_z_score, rsi_14, macd_dif, mfi_14...
SORTABLE_COLUMNS	可排序字段	signal_score, market_cap, piotroski_score, value_quality_score, altman_z_score...
PATTERN_FLAG_COLUMNS	形态标志列	96+ 个二值指标（含 ind_macd_bull_cross, ind_rsi_oversold, ind_bb_squeeze 等）

meta.py — 元数据定义

定义前端的筛选分组结构和统计信息。

筛选分组：

分组 ID	名称	指标数	示例指标
single_candle	单 K 形态	7	bull_candle, hammer, doji
double_candle	双 K 形态	3	bullish_engulfing, inside_bar
triple_candle	三 K 形态	2	three_white_soldiers
trend_structure	趋势结构	6	ma_bull, platform_breakout
volume_volatility	量价波动	4	volume_breakout, vol_contraction
momentum	动量	4	break_high_20, consec_up_3
valuation	估值指标	5	forward_pe, peg_ratio
financials	财务指标	8	roe, profit_margin, revenue_growth
fundamental_quality	基本面质量	3	fund_piotroski_strong, fund_value_quality, risk_financial_distress
advanced_indicators	高级技术指标	20+	ind_macd_bull_cross, ind_rsi_oversold, ind_bb_squeeze, ind_mfi_oversold 等

核心函数：

build_meta_response() — 构建完整的元数据响应（含统计）
build_pattern_stats_response() — 形态命中统计和标签
_count_indicator_hits() — 计算各指标命中数量

signal_product_api.py — 信号产品 API

信号产品系统的 REST API，覆盖候选池、入场信号、绩效追踪和模拟交易全流程。

端点	方法	说明
`/api/signals/status`	GET	信号系统状态（活跃信号数、今日候选数、日期）
`/api/signals/candidates`	GET	每日候选股列表（支持按日期/自选股/股票代码过滤）
`/api/signals/active`	GET	当前活跃（持仓中）信号列表
`/api/signals/history`	GET	信号历史（分页，含已平仓信号）
`/api/signals/performance/summary`	GET	聚合绩效指标（胜率、收益率、Sharpe）
`/api/signals/evaluate`	GET	用实时数据评估今日全部候选股
`/api/signals/evaluate/{symbol}`	GET	用实时数据评估单只候选股
`/api/signals/portfolio`	GET	模拟持仓列表
`/api/signals/portfolio/follow`	POST	跟随信号开仓（模拟交易）
`/api/signals/portfolio/{position_id}/close`	POST	平仓（模拟交易）

signal_product_models.py — 信号数据模型

信号产品管线的全部数据结构。

核心数据类：

数据类	说明	关键字段
`CandidateRecord`	每日候选股	candidate_id, symbol, rank, offline_score, 各维度评分, 风险标签
`SignalRecord`	盘中入场信号	signal_id, candidate_id, symbol, entry/stop/target 价格, trigger_reasons
`SignalOutcome`	信号绩效追踪	forward_return_1d/3d/5d/10d, MFE, MAE, hit_stop, hit_target
`PaperPosition`	模拟交易仓位	symbol, entry_price, quantity, stop/target, unrealized_pnl

CandidateRecord 风险门控：

HARD_RISK_FLAGS = {"low_liquidity", "abnormal_volatility", "weekly_downtrend"}
is_eligible() — 检查评分阈值和无硬性风险标记

signal_product_db.py — 信号 SQLite 存储

信号产品系统的持久化层，使用 SQLite WAL 模式。

数据表：

表	用途	关键索引
candidates	每日候选股打分结果	date, symbol
signals	盘中入场信号	date, symbol, status
signal_outcomes	后验绩效（MFE/MAE/前向收益）	signal_id, symbol
paper_positions	模拟交易仓位	symbol, status

特性：WAL 模式并发、JSON 序列化、UPSERT 更新。

signal_entry_engine.py — 盘中信号入场引擎

评估是否为候选股生成盘中入场信号。

4 重入场门控（全部通过才生成信号）：

门控	函数	条件
VWAP 门控	`_gate_price_above_vwap()`	当前价 > VWAP
动量门控	`_gate_momentum()`	最新价 > 3根 Bar 前价格
量能门控	`_gate_volume_surge()`	成交量 ≥ 1.5 × 近期均量
波动率门控	`_gate_realized_volatility()`	实现波动率 < 4%

可配置参数：

参数	默认值	说明
min_offline_score	70	最低离线评分阈值
min_intraday_score	70	最低盘中评分阈值
default_stop_pct	0.04	默认止损比例（4%）
default_reward_risk_ratio	2.0	默认盈亏比
volume_surge_threshold	1.5	量能突破倍数
max_realized_volatility	0.04	最大允许实现波动率（4%）

核心函数：

evaluate_entry_signal() — 主评估函数
compute_intraday_score() — 计算 0-100 盘中评分
build_trade_plan() — 根据配置计算止损/目标价

backtest_api.py — 因子回测 API

因子评估和策略绩效的 REST API。

端点	方法	说明
`/api/backtest/factors`	GET	因子评估（IC/ICIR 统计、IC 分布）
`/api/backtest/performance`	GET	策略绩效（NAV、Sharpe、回撤、月度收益）
`/api/backtest/compare`	GET	多策略对比
`/api/backtest/cache/clear`	POST	清除计算缓存

预定义因子：momentum_20d, momentum_5d, rsi_14, volume_ratio_5

绩效指标：NAV 曲线、Sharpe/Calmar 比率、最大回撤、年化收益/波动率、胜率、超额收益

presets.py — 多时间周期预设策略

定义跨日/周/60 分钟的多时间周期共振策略。

4 种预设策略：

预设	说明
trend_following	趋势追踪（多周期均线共振）
pullback_buy	回调买入（趋势确认 + 回踩支撑）
momentum_breakout	动量突破（多周期突破共振）
value_quality	价值质量（基本面 + 技术面共振）

每个预设在日/周/60 分钟三个周期分别定义 conditions，后端根据快照数据计算匹配度并返回评分。

market_hours.py — 交易时段

美股交易时段感知工具。

功能：

判断当前交易时段（盘前/盘中/盘后/空闲）
美东时区处理（America/New_York）
内置假日日历（2026-2027 年）
决定实时数据获取策略（空闲时段暂停）

rt_api.py — 实时数据路由

提供盘中实时数据的 API 端点。

端点	说明	可用性
`/api/rt/quotes`	获取实时报价	免费
`/api/rt/ranking`	实时排名	付费
`/api/rt/kline`	分钟 K 线	付费
`/api/rt/scan`	全市场扫描	付费
`/api/rt/status`	服务状态查询	免费
`/api/rt-prices`	轻量价格轮询端点	免费

rt_hub.py — 实时推送中心

实时报价的核心编排模块，连接上游数据源和下游 WebSocket 客户端。

功能：

管理所有 WebSocket 客户端连接
处理订阅/取消订阅（每个客户端可订阅不同股票）
接收上游推送并广播给订阅的客户端
交易时段感知（非交易时段自动暂停推送）

rt_ws.py — WebSocket 端点

提供 /ws/rt WebSocket 端点供前端连接。

功能：

设备注册与断线清理
subscribe/unsubscribe 消息处理
ping/pong 心跳检测
连接状态追踪

rt_aliyun_ticker.py — 阿里云 Ticker

后台定时任务，通过阿里云 API 获取实时行情并合并到快照缓存。

特性：

可配置更新间隔（默认 60 秒）
交易时段感知（盘前显示 after_price，盘中显示 price，盘后显示 after_price）
支持启动/停止控制
通过 config.yaml 中的 aliyun_ticker_enabled 开关

alerts_api.py — 预警 API

预警系统的 REST API 接口。

端点	方法	说明
`/api/alerts/rules`	GET	获取预警规则列表
`/api/alerts/rules`	POST	创建预警规则
`/api/alerts/rules/{id}`	DELETE	删除预警规则
`/api/alerts/events`	GET	获取触发事件历史（分页）
`/api/alerts/presets`	GET	获取预警模板列表

参数验证：每设备最多 50 条规则，规则类型和参数校验。

alerts_db.py — 预警 SQLite 存储

预警系统的持久化存储层。

数据表：

表	用途
devices	设备注册信息
alert_rules	预警规则（类型、参数、状态）
alert_events	触发事件记录

特性：

WAL 模式支持并发读写
事件自动清理（默认保留 30 天）
外键级联删除

alert_engine.py — 预警引擎

核心预警处理模块，负责规则评估、状态管理和事件分发。

工作流：

实时报价到达
  ↓
遍历所有 armed 状态的规则
  ↓
alert_evaluators 评估条件
  ↓
条件满足 → 触发事件
  ├── 状态变为 fired
  ├── 写入 SQLite (alert_events)
  └── alert_dispatcher → WebSocket 推送到前端

alert_evaluators.py — 规则评估器

6 种预警类型的条件评估逻辑。

评估器	类型	说明
价格变动	price_change	涨跌幅超过阈值（如 ±3%）
突破新高	breakout_high	价格突破指定高点
跌破新低	breakout_low	价格跌破指定低点
成交量异动	volume_spike	成交量超过 N 倍均值
均线交叉	ma_cross	短期均线穿越长期均线
52 周高低	week52_high_low	接近或突破 52 周高低点

alert_models.py — 数据结构

预警系统的类型定义。

AlertRule — 用户创建的预警规则
CompiledRule — 编译后的规则（含评估器）
AlertEvent — 触发的事件记录
AlertPreset — 预警模板

alerts_presets.py — 预警模板

6 种预定义预警模板，方便用户快速创建规则：

模板	说明
急涨急跌	涨跌幅超过阈值
突破新高	价格突破近期高点
跌破新低	价格跌破近期低点
放量异动	成交量异常放大
均线金叉	短期均线上穿长期均线
52 周新高	接近 52 周最高价

alert_dispatcher.py — 预警分发器

将触发的预警事件通过 WebSocket 推送到对应设备的前端。

维护设备 ID → WebSocket 连接的映射
Best-effort 交付（连接断开则跳过）
与 AlertEngine 事件回调对接

screener_api.py — 选股器 API

提供选股结果和评分排名接口。

端点	方法	说明
`/api/screener/status`	GET	选股器运行状态
`/api/screener/results`	GET	排名结果列表
`/api/screener/stock/{symbol}`	GET	单只股票评分详情

macro.py — 宏观指标接口

读取 macro.parquet 并提供宏观指标 API。

端点	方法	说明
`/api/macro`	GET	获取宏观指标数据

返回内容：

各指标（VIX、10Y、DXY、SPX）的最新值和变化
风险等级分类：calm（平静）/ normal（正常）/ risk（风险）
缓存机制（mtime 感知，文件更新自动刷新）

sectors.py — 板块轮动接口

读取 sectors.parquet 并提供板块轮动数据 API。

端点	方法	说明
`/api/sectors`	GET	获取板块轮动数据

返回内容：

11 个板块 ETF + 3 个风格 ETF 的排名
20 日 / 60 日收益率
相对 SPY 基准的相对强弱
动量评分

prod_app.py — 生产环境包装

在主应用基础上增加静态文件服务。如果 static/ 目录存在，自动挂载为静态资源路由。

运行命令

cd backend
source .venv/bin/activate
uvicorn main:app --reload --port 8000

美股-数据管线模块

Henry Lin — Sun, 14 Jun 2026 09:19:26 +0000

数据管线模块（scripts/）

数据管线负责从外部数据源获取股票行情和财务数据，计算技术指标和基本面评分，并构建离线快照文件供后端服务使用。同时包含宏观指标、板块数据、信号候选池和信号绩效的构建脚本。

目录结构

scripts/
├── config.yaml            # 股票池与获取配置
├── yfinance_client.py     # yfinance API 封装
├── feature_engine.py      # 技术指标与形态识别
├── scorer.py              # 综合评分 + 价值-成长复合评分
├── build_snapshot.py      # 快照构建入口（编排器）
├── build_macro.py         # 宏观指标数据构建
├── build_sectors.py       # 板块 ETF 数据构建
├── rt_manager.py          # 实时数据管理器
├── rt_providers.py        # 实时数据源抽象层（yfinance / 阿里云）
├── rt_push_providers.py   # 实时推送源实现（TickFlow / Ashen / 阿里云）
├── ashen_ws_client.py     # Ashen WebSocket 客户端
├── signal_candidate_pool.py # 信号候选池离线打分
├── signal_outcomes.py     # 信号绩效计算（MFE/MAE/前向收益）
├── dev_server.sh          # 开发服务器管理脚本
└── daily5_alpha_select.py # Alpha 因子选股脚本

数据流

config.yaml
    ↓
yfinance_client.py  ──获取──→  原始行情 + 股票信息 + 财务指标
    ↓
feature_engine.py   ──计算──→  技术指标（~80 列）+ 高级指标（MACD/RSI/BB/VWAP/MFI/Williams %R/ADX/CCI/Stochastic/OBV/Chaikin/ATR）
    ↓
scorer.py           ──评分──→  signal_score（0-100）+ value_quality_score + piotroski_score
    ↓
build_snapshot.py   ──输出──→  data.parquet + history.parquet

build_macro.py      ──获取──→  macro.parquet（VIX / 10Y / DXY / SPX）
build_sectors.py    ──获取──→  sectors.parquet（14 个板块/风格 ETF）

signal_candidate_pool.py ──打分──→  candidates.parquet / candidates.csv（每日 Top 20）
signal_outcomes.py       ──计算──→  MFE/MAE + 1/3/5/10 日前向收益

各文件详解

config.yaml — 配置中心

定义股票池、数据获取参数、实时数据配置和预警配置。

股票池（约 200 只，分 9 组）：

分组	说明	示例
tech	科技/半导体（70+只）	AAPL, NVDA, MSFT, TSLA, ARM, TSM
finance	金融/支付	JPM, V, MA, BRK-B, COIN
healthcare	医疗/生物科技	JNJ, UNH, LLY, MRNA
energy	能源/资源	XOM, CVX, COP, NEM, FCX
industrial	工业/航空/国防	CAT, BA, GE, HON, RTX
consumer	消费/零售/餐饮	PG, KO, MCD, WMT, NFLX
infra	通信/公用事业/REIT	T, VZ, NEE, AMT, EQIX
aerospace	太空/航空/国防	RKLB, ASTS, LUNR, LHX, HEI
other	汽车/交通/其他	F, RIVN, UBER, BIDU, PDD

获取参数：

参数	默认值	说明
history_period	2y	历史数据时间跨度
batch_size	20	每批获取股票数量
batch_delay	2.0s	批次间隔
max_retries	2	最大重试次数
request_timeout	30s	单次请求超时

多时间周期配置：

时间周期	interval	period
日线	1d	2y
周线	1wk	5y
60 分钟	60m	730d
30 分钟	30m	60d
15 分钟	15m	60d
5 分钟	5m	60d

实时数据配置：

配置	说明
`realtime.provider`	数据源选择：free (yfinance) / premium (aliyun)
`realtime.push.provider`	推送源选择：tickflow / ashen / aliyun
`realtime.trading_hours`	交易时段定义（盘前/盘中/盘后）
`realtime.update_interval_sec`	报价更新间隔（秒）
`alerts.enabled`	预警引擎开关
`alerts.db_path`	SQLite 数据库路径
`alerts.max_rules_per_device`	每设备最大规则数（50）
`alerts.retention_days`	事件保留天数（30）

yfinance_client.py — 数据获取

封装 yfinance API，提供批量获取、重试和标准化功能。

核心函数：

函数	用途	返回
`load_config()`	加载 config.yaml	dict
`get_stock_pool()`	提取去重后的股票列表	list[str]
`fetch_history_batch()`	批量下载历史行情	dict[str, DataFrame]
`fetch_stock_info()`	获取单只股票基本信息	StockInfo
`fetch_financial_metrics()`	获取财务指标	dict
`fetch_all_data()`	主入口，获取全部数据	(history, info, financials)

数据类：

FetchConfig — 获取参数（history_period, batch_size 等）
StockInfo — 股票基本信息（symbol, name, market_cap, total_share）

处理逻辑：

分批下载避免 API 限流
自动重试失败请求
列名标准化（yfinance 格式 → 统一格式）

feature_engine.py — 技术指标计算

从原始 OHLCV 数据中计算约 80 个技术指标列。

指标分类：

移动平均与趋势

指标	说明
ma5, ma10, ma20, ma60	简单移动平均线
ret_1d, ret_5d, ret_20d	收益率
amplitude	振幅

K 线形态识别（二值标志列，0/1）

单 K 形态：bull_candle, bear_candle, hammer, shooting_star, doji, dragonfly_doji, gravestone_doji

双 K 形态：bullish_engulfing, bearish_engulfing, inside_bar

三 K 形态：three_white_soldiers, three_black_crows

趋势形态：ma_bull, trend_confirm, pullback_hold, break_high_20, break_high_60, platform_breakout, false_breakout, double_bottom

量价形态：volume_breakout, volume_shrink_pullback

波动率形态：volatility_contraction, volatility_expansion

连续上涨：consec_up_3, consec_up_5

高级技术指标（连续值 + 信号标志）

MACD（移动平均收敛发散）

列名	类型	说明
macd_dif	连续值	DIF 线（12日 EMA - 26日 EMA）
macd_dea	连续值	DEA 信号线（DIF 的 9日 EMA）
macd_hist	连续值	MACD 柱状图 = 2 × (DIF - DEA)
ind_macd_bull_cross	标志	金叉（DIF 上穿 DEA）
ind_macd_bear_cross	标志	死叉（DIF 下穿 DEA）
ind_macd_hist_positive	标志	柱状图由负转正

RSI（相对强弱指数）

列名	类型	说明
rsi_14	连续值	14日 RSI（Wilder 平滑）
ind_rsi_oversold	标志	RSI < 30（超卖）
ind_rsi_overbought	标志	RSI > 70（超买）
ind_rsi_bull_divergence	标志	价格新低但 RSI 未新低（看涨背离）

Bollinger Bands（布林带）

列名	类型	说明
bb_upper	连续值	上轨 = MA20 + 2 × 标准差
bb_mid	连续值	中轨 = 20日 SMA
bb_lower	连续值	下轨 = MA20 - 2 × 标准差
bb_width	连续值	带宽百分比 = (上轨 - 下轨) / 中轨 × 100
ind_bb_squeeze	标志	带宽处于 20日最低值（即将突破）
ind_bb_upper_touch	标志	价格触及或超过上轨
ind_bb_lower_touch	标志	价格触及或跌破下轨

VWAP（成交量加权平均价）

列名	类型	说明
vwap	连续值	当日成交量加权均价（日内累计，每个交易日重置）
ind_price_above_vwap	标志	收盘价 > VWAP

MFI（资金流量指数）

列名	类型	说明
mfi_14	连续值	14日 MFI（带量的 RSI）
ind_mfi_oversold	标志	MFI < 20（超卖）
ind_mfi_overbought	标志	MFI > 80（超买）

Williams %R（威廉指标）

列名	类型	说明
willr_14	连续值	14日 Williams %R（范围 -100 ~ 0）
ind_willr_oversold	标志	Williams %R < -80（超卖）
ind_willr_overbought	标志	Williams %R > -20（超买）

ADX（平均趋向指数）

列名	类型	说明
adx_14	连续值	14日 ADX（趋势强度）
di_plus_14	连续值	+DI（正向趋向指标）
di_minus_14	连续值	-DI（负向趋向指标）
ind_adx_strong_trend	标志	ADX > 25（强趋势）
ind_di_bull_cross	标志	+DI 上穿 -DI

CCI（商品通道指数）

列名	类型	说明
cci_20	连续值	20日 CCI
ind_cci_oversold	标志	CCI < -100（超卖）
ind_cci_overbought	标志	CCI > 100（超买）

Stochastic（随机指标）

列名	类型	说明
stoch_k_14	连续值	14日 %K（快速）
stoch_d_14	连续值	%K 的 3日 SMA（慢速）
ind_stoch_oversold	标志	%K < 20（超卖）
ind_stoch_overbought	标志	%K > 80（超买）
ind_stoch_bull_cross	标志	%K 上穿 %D（且 %K < 80）

OBV（能量潮）

列名	类型	说明
obv	连续值	累计能量潮
ind_obv_uptrend	标志	OBV > 5日前 OBV

Chaikin Oscillator（佳庆振荡器）

列名	类型	说明
chaikin_osc	连续值	A/D 线的 3日 EMA - 10日 EMA
ind_chaikin_bullish	标志	Chaikin 振荡器上穿零线

ATR（平均真实范围）

列名	类型	说明
atr_14	连续值	14日 ATR（Wilder 平滑）
atr_stop_long	连续值	Chandelier 止损 = 周期最高价 - 3 × ATR

成交量与波动率

指标	说明
vol_ratio_5	5 日量比
body_ratio	实体比率
upper/lower_shadow_ratio	上下影线比率
risk_ma20_dev, risk_ma60_dev	均线偏离度
risk_dd_20d	20 日最大回撤
risk_vol_20d	20 日波动率

基本面评分指标

列名	类型	说明
piotroski_score	连续值	Piotroski F-Score (0-9)
fund_piotroski_strong	标志	Piotroski ≥ 7（财务强健）
altman_z_score	连续值	Altman Z-Score（破产预警）
risk_financial_distress	标志	Altman Z < 1.81（财务困境）
value_quality_score	连续值	价值-成长复合评分 (0-100)
fund_value_quality	标志	复合评分 ≥ 70

核心函数：

add_features(df) — 主入口，给历史 DataFrame 添加全部技术指标
add_financial_features(df, metrics) — 将财务指标合并到最新行（含 Piotroski 评分）

scorer.py — 综合评分

计算每只股票的信号评分（0-100 分）和价值-成长复合评分。

信号评分组成：

维度	说明	分值范围
标志指标	多头信号加分，空头信号减分	-20 ~ +50
连续指标	收益率、ROE、利润率等百分位排名	0 ~ +25
PE 惩罚	forward_pe 过高时扣分	-10 ~ 0

关键权重：

信号	权重
pattern_ma_bull	+15
trend_confirm	+12
break_high_60	+10
false_breakout	-8
three_black_crows	-6

价值-成长复合评分（compute_value_quality_score()）：

维度	权重	排名方向	包含指标
估值质量	40%	反向（低估值 = 高分）	forward_pe, price_to_book, peg_ratio, ps_ratio
盈利能力	30%	正向	roe, roa, profit_margin, operating_margin
成长性	30%	正向	revenue_growth, earnings_growth

build_snapshot.py — 快照编排器

协调数据获取 → 特征计算 → 基本面评分 → Altman Z-Score → 输出的完整流程。

核心函数：

函数	用途
`build_snapshot()`	主入口，输出 parquet 文件
`build_snapshot_dataframe()`	构建快照 DataFrame（每只股票一行）
`build_history_dataframe()`	构建历史 DataFrame（全部日期）
`_compute_altman_z(balance_sheet)`	计算 Altman Z-Score（破产预警）

Altman Z-Score 公式：

Z = 1.2×X1 + 1.4×X2 + 3.3×X3 + 0.6×X4 + 1.0×X5

变量	定义
X1	营运资本 / 总资产
X2	留存收益 / 总资产
X3	EBIT / 总资产
X4	市值 / 总负债
X5	营收 / 总资产

Piotroski F-Score（在 add_financial_features() 中调用 _add_piotroski_score()）：

9 项评分标准：

#	维度	条件
1	盈利能力	ROA > 0
2	现金流	经营利润率 > 0（作为经营现金流代理）
3	ROA 改善	盈利增长 > 0
4	应计项目	经营利润率 > ROA
5	杠杆	负债权益比 < 1.0
6	流动性	流动比率 > 1.5
7	股本稀释	ROA > 0.05（代理）
8	利润率	净利润率 > 0.15
9	营收增长	营收增长 > 0

输出文件：

data.parquet — 最新交易日的快照（~200 行 × 80+ 列）
history.parquet — 全部历史技术指标数据

build_macro.py — 宏观指标构建

获取宏观经济指标历史数据，输出 macro.parquet。

跟踪指标：

Symbol	指标	说明
^VIX	VIX 恐慌指数	市场波动率预期
^TNX	10 年期美债收益率	无风险利率基准
DX-Y.NYB	美元指数 DXY	美元强弱
^GSPC	标普 500 指数	大盘基准

处理逻辑：

10Y 收益率自动转换为百分比格式
每个指标独立获取，单个失败不影响其他
输出格式：date, symbol, close, change_pct

build_sectors.py — 板块数据构建

获取板块 ETF 和风格 ETF 的历史数据，输出 sectors.parquet。

11 个板块 ETF：XLK, XLF, XLV, XLE, XLI, XLY, XLU, XLRE, XLB, XLC, IBB

3 个风格 ETF：SPY（大盘基准）, QQQ（科技基准）, IWM（小盘基准）

输出格式：date, symbol, close, volume

signal_candidate_pool.py — 信号候选池

离线多因子打分脚本，输出每日信号候选股 Top 20。

评分维度与权重：

维度	权重	包含因子
基本面	0.25	盈利增长、ROE、利润率、PE 惩罚
周线	0.20	20日动量、signal_score、MA 排列
日频 Alpha	0.30	signal_score、量能突破、突破信号
技术面	0.25	ADX 趋势、MA 排列、风险指标

风险门控：

低流动性：20日日均成交额 < $5M → 标记
高波动率：20日波动率 > 4.0% → 标记
周线下跌趋势 → 标记

CLI 用法：

python3 scripts/signal_candidate_pool.py \
    --snapshot data.parquet \
    --output tmp/signals/candidates.parquet \
    --csv tmp/signals/candidates.csv

signal_outcomes.py — 信号绩效计算

计算已入场信号的后验绩效指标。

产出指标：

指标	说明
forward_return_1d	1 日前向收益
forward_return_3d	3 日前向收益
forward_return_5d	5 日前向收益
forward_return_10d	10 日前向收益
MFE	最大有利偏移（Maximum Favorable Excursion）
MAE	最大不利偏移（Maximum Adverse Excursion）
hit_stop	是否触及止损
hit_target	是否触及目标价

CLI 用法：

python3 scripts/signal_outcomes.py \
    --db tmp/signals/signals.db \
    --history history.parquet

rt_manager.py & rt_providers.py — 实时数据

提供盘中实时数据的统一接口。

rt_providers.py 定义两种数据源：

数据源	延迟	排名	分钟 K 线
YFinanceProvider（免费）	~15 分钟	不支持	不支持
AliyunProvider（付费）	实时	支持	支持

rt_manager.py 提供缓存层：

LRU 缓存（报价 200 条，K 线 50 条）
统一的异步 API 接口

rt_push_providers.py — 实时推送源

可插拔的实时推送上游数据源架构，支持多种供应商。

支持的供应商：

供应商	协议	说明
TickFlowProvider	HTTP 轮询	默认供应商，API Key 认证
AshenProvider	WebSocket	增量订阅，自动重连
AliyunProvider	HTTP 轮询	阿里云金融 API

特性：

统一的 Provider 接口（工厂模式）
可配置轮询间隔和推送频率
自动重连与退避策略

ashen_ws_client.py — Ashen WebSocket 客户端

Ashen 实时行情服务的 WebSocket 客户端实现。

增量订阅管理（add/remove symbols）
自动重连（指数退避：1s → 2s → 5s → 10s）
心跳检测与超时处理

运行命令

# 构建数据快照
python3 scripts/build_snapshot.py

# 构建宏观指标
python3 scripts/build_macro.py

# 构建板块数据
python3 scripts/build_sectors.py

# 生成信号候选池
python3 scripts/signal_candidate_pool.py --snapshot data.parquet --output tmp/signals/candidates.parquet

# 计算信号绩效
python3 scripts/signal_outcomes.py --db tmp/signals/signals.db --history history.parquet

美股日线选股器 — 项目概览

Henry Lin — Sun, 14 Jun 2026 09:19:01 +0000

美股日线选股器 — 项目概览

项目简介

美股日线选股器（US Stock Screener）是一个基于技术形态和价值指标的股票筛选工具。系统从 yfinance 获取约 200 只美股的日线数据，计算 80+ 个技术指标和形态信号，通过 FastAPI 后端和 React 前端提供交互式筛选、排序和对比功能。

系统还集成了实时行情推送（WebSocket）、预警系统（6种规则类型）、宏观指标监控、板块轮动分析、多时间周期共振策略、基本面评分体系、信号产品系统（候选池→盘中信号→模拟交易→绩效分析）和因子回测等高级功能。

技术栈

层级	技术	说明
数据获取	yfinance	免费 API，无需密钥
特征工程	pandas + numpy	技术指标计算
后端	FastAPI + uvicorn	异步 API 服务
前端	Vite + React 18 + TypeScript	SPA 单页应用
数据存储	Parquet 文件	列式存储，高效压缩
信号存储	SQLite	候选池、信号、模拟仓位持久化
预警存储	SQLite	规则与事件持久化
实时数据	yfinance / 阿里云 / TickFlow	免费（延迟）/ 付费（实时）
实时推送	WebSocket	服务端主动推送报价
K线图表	lightweight-charts	交互式技术图表
路由	react-router-dom	SPA 页面路由

架构总览

┌──────────────────────────────────────────────────────────────────┐
│                      Frontend (React 18 SPA)                        │
│  筛选面板 │ 股票表格 │ 详情抽屉 │ K线图 │ 对比分析 │ 预警中心      │
│  宏观指标 │ 板块轮动 │ 多周期预设 │ 数值筛选 │ 实时扫描器            │
│  信号中心 │ 信号绩效 │ 模拟组合 │ 回测报告 │ 形态统计               │
└─────────────────────────────┬────────────────────────────────────┘
                              │ HTTP + WebSocket (proxy :5173 → :8000)
┌─────────────────────────────▼────────────────────────────────────┐
│                    Backend (FastAPI + uvicorn)                       │
│  /api/meta │ /api/stocks │ /api/rt/* │ /api/alerts │ /api/macro     │
│  /api/sectors │ /api/pattern-stats │ /api/presets │ /ws/rt          │
│  /api/signals/* │ /api/backtest/*                                   │
│  loader.py (内存缓存) ← data.parquet (200+行 × 80+列)               │
│  history.parquet │ fundamentals.parquet │ macro/sectors parquet       │
│  RTHub (推送中心) │ AlertEngine (预警引擎) │ SQLite (规则/信号存储)    │
│  SignalEntryEngine (信号入场引擎) │ SignalProductRepository           │
└─────────────────────────────┬────────────────────────────────────┘
                              ↑ 构建时生成
┌─────────────────────────────┴────────────────────────────────────┐
│                  Data Pipeline (scripts/)                            │
│  yfinance_client → feature_engine → scorer → parquet output         │
│  rt_manager → rt_providers → rt_push_providers (实时数据)            │
│  build_macro → macro.parquet │ build_sectors → sectors.parquet      │
│  signal_candidate_pool → candidates │ signal_outcomes → MFE/MAE     │
└──────────────────────────────────────────────────────────────────┘

模块说明

模块	文档	说明
scripts/	01-data-pipeline.md	数据获取、特征工程、快照构建、宏观/板块数据、信号候选池
backend/	02-backend-api.md	API 服务、查询引擎、实时推送、预警系统、信号产品、回测接口
frontend/	03-frontend-ui.md	筛选界面、详情、图表、对比、预警、信号中心、回测报告
demo/	04-factor-backtest.md	Alpha101 因子回测、中性化、多空选股、多信号共振
scripts/screener/	05-realtime-screener.md	多因子实时选股引擎（基本面/周线/Alpha/盘中）
—	06-deployment.md	部署、开发服务器、测试体系、配置管理

核心功能

1. 技术形态筛选

支持 30+ 种 K 线形态和技术信号的组合筛选，包括单 K 形态、双 K 形态、三 K 形态、趋势结构、量价关系和波动率形态。

2. 高级技术指标

80+ 个技术指标覆盖 6 大类别：

类别	指标	信号列
趋势	MACD (DIF/DEA/Histogram)、ADX (+DI/-DI)	金叉/死叉、强趋势
动量	RSI-14、Stochastic (%K/%D)、CCI-20、Williams %R	超买/超卖、背离
波动率	Bollinger Bands (上/中/下/宽度)、ATR + 止损	挤压信号、触及上下轨
量能	OBV、Chaikin Oscillator、MFI-14、VWAP	量价背离、资金进出
财务健康	Piotroski F-Score (0-9)、Altman Z-Score	财务强健/财务困境
综合评分	Value-Growth Composite (0-100)	价值质量

3. 基本面评分体系

三维度基本面分析框架：

Piotroski F-Score：9 项财务健康指标评分（0-9 分），≥7 分标记为"财务强健"
Altman Z-Score：破产预警模型，<1.81 标记为"财务困境"
价值-成长复合评分：估值质量 (40%) + 盈利能力 (30%) + 成长性 (30%)

4. 信号产品系统

完整的交易信号管线，从离线候选到盘中信号到绩效追踪：

候选池生成：离线多因子打分，输出每日 Top 20 候选股
盘中信号入场：4 重入场门控（VWAP、动量、量能、波动率）
模拟交易：Paper Trading 跟踪开仓/平仓/盈亏
绩效分析：MFE/MAE、多周期前向收益 (1/3/5/10 日)、胜率

5. 综合评分

基于多维度的信号评分系统（0-100 分），综合考虑技术形态、连续指标和估值水平。

6. 股票详情

详情抽屉展示完整的股票信息，包含基本面、技术指标、财务数据和风险指标。研究页面提供 K 线图、技术面分析、财务面分析和形态历史回溯。

7. 多股对比

最多 5 只股票的并列对比分析，按 7 个维度比较并高亮最优/最差值。

8. 实时行情

盘中实时数据支持：

免费源：yfinance（~15 分钟延迟）
付费源：阿里云金融 API（真正实时）
WebSocket 推送：服务端主动推送报价到前端
实时排名：按成交额/涨跌幅/成交量排序
异动扫描：涨幅榜、跌幅榜、成交量异动

9. 预设策略

内置 5 种选股策略（趋势突破、回调低吸、质量成长、估值修复、风险预警），一键应用筛选组合。

10. 多时间周期共振

支持日线、周线、60 分钟、30 分钟、15 分钟、5 分钟多周期分析，提供跨周期预设策略与共振评分。

11. 预警系统

6 种预警规则类型（价格变动、突破新高/新低、成交量异动、均线交叉、52 周高低），通过 WebSocket 实时推送 Toast 通知。

12. 宏观指标监控

实时展示 VIX 恐慌指数、10 年期美债收益率、美元指数 DXY、标普 500 等宏观指标，自动计算风险等级（平静/正常/风险）。

13. 板块轮动分析

11 个板块 ETF + 3 个风格 ETF 的相对强弱排名，展示动量和相对 SPY 基准的表现。

14. 因子回测与回测报告

Alpha101 因子评估和多因子选股回测系统：

因子 IC/ICIR 评估与中性化
多空组合绩效分析（Sharpe、回撤、Calmar）
多信号共振回测（形态组合胜率统计）
交易成本建模（佣金、滑点、融券成本）
前端可视化回测报告页面

快速启动

# 1. 构建数据快照
python3 scripts/build_snapshot.py

# 2. 构建宏观与板块数据
python3 scripts/build_macro.py
python3 scripts/build_sectors.py

# 3. 启动后端
cd backend && source .venv/bin/activate
uvicorn main:app --reload --port 8000

# 4. 启动前端
cd frontend && npm install && npm run dev

# 或使用统一脚本
bash scripts/dev_server.sh start

数据说明

股票池：约 200 只美股，覆盖科技、金融、医疗、能源、工业、消费、基建、太空、汽车等 9 个板块
数据源：yfinance（免费，无需 API Key），可选阿里云（付费，实时）
更新频率：手动运行 build_snapshot.py 更新快照
技术指标：约 80 个，包含移动平均、K 线形态、量价关系、波动率、动量、趋势等
财务指标：PE、PEG、ROE、利润率、营收增长、Piotroski F-Score、Altman Z-Score 等
实时推送：WebSocket 服务端推送，支持 TickFlow / Ashen / 阿里云三种上游源
预警规则：SQLite 存储，每设备最多 50 条规则，30 天事件保留
信号系统：SQLite 持久化候选池、入场信号、模拟仓位和绩效追踪

开源量化分析软件功能介绍

Henry Lin — Mon, 08 Jun 2026 06:37:06 +0000

📈 多因子选股系统 — 项目功能介绍

观看地址:https://youtu.be/SpHsZdlyii8

面向 A 股市场的全链路量化分析平台 — 因子计算 · 机器学习 · 组合优化 · 回测验证 · 实时行情

指标	数据
Python 模块	108
业务代码	15,600+ 行
服务模块	30+
API 蓝图	14
内置因子	12

一、整体功能介绍

多因子选股系统是一个覆盖量化研究全流程的分析平台，从数据管理到策略回测一站式完成。系统采用 Flask + SQLAlchemy + SocketIO 技术栈，基于 Parquet + SQLite 双层存储架构，零外部数据库依赖，克隆即可运行。

核心能力总览

实时行情分析：通达信分钟数据接入，MACD、KDJ、RSI、布林带等技术指标实时计算
因子与选股：12 个内置因子 + 自定义因子表达式引擎，支持白名单安全校验
机器学习建模：XGBoost、LightGBM、RandomForest 三大算法的完整模型生命周期
组合优化：等权重、均值方差、风险平价、因子中性四种经典优化方法
回测验证：单策略与多策略回测，丰富的绩效指标（年化收益、夏普比率、最大回撤等）
风险管理：组合持仓管理、实时价格刷新、风险指标监控、预警管理、压力测试

请求流程

HTTP / WebSocket → Blueprint (app/api/*.py) → Service (app/services/*.py) → ParquetDataReader (行情数据)
                                                                             ↕
                                                               SQLAlchemy Models (SQLite 应用状态)

技术栈

类别	技术
后端框架	Python 3.8–3.11、Flask、Flask-SocketIO、Flask-SQLAlchemy、Celery
数据处理	Pandas、NumPy、PyArrow、SciPy、Scikit-learn
机器学习	XGBoost、LightGBM、RandomForest、CVXPY
前端 & 可视化	Bootstrap 5、ECharts、Plotly、Matplotlib / MPLFinance
数据源	通达信（实时行情）、Baostock（历史数据）、Tushare（可选）、Parquet 离线数据包
AI 能力	Ollama（本地 LLM）、OpenAI API（可选）、Text2SQL、Qwen2.5-Coder

二、各模块功能介绍

2.1 实时行情分析模块

API 蓝图前缀：/api/realtime-analysis/*

核心服务：

RealtimeIndicatorEngine（services/realtime_indicator_engine.py）：实时技术指标计算
RealtimeTradingSignalEngine（services/realtime_trading_signal_engine.py）：多策略交易信号生成与融合

功能特性：

功能	说明
实时指标计算	支持 MACD、KDJ、RSI、布林带等经典技术指标的实时计算与展示
多策略信号生成	基于不同策略的交易信号生成，支持信号融合与综合研判
信号监控	交易信号的实时监控与历史回溯
策略回测	对生成的信号进行历史回测验证
板块分析	板块表现统计与异动检测
市场情绪	市场情绪指标的实时追踪

数据源：通达信分钟级行情数据，存储于 data/stock_minute/（Parquet 格式）。

2.2 因子与选股模块

API 蓝图前缀：/api/ml-factor/*、/api

核心服务：

FactorEngine（services/factor_engine.py）：内置因子计算与自定义因子管理
FactorExpressionEngine（services/factor_expression_engine.py）：白名单校验的自定义因子公式引擎
StockScoringEngine（services/stock_scoring.py）：因子评分与 ML 评分的综合选股引擎

内置因子（12 个）

维度	因子名	说明
动量	`momentum_1d`	1 日动量
动量	`momentum_5d`	5 日动量
动量	`momentum_20d`	20 日动量
波动率	`volatility_20d`	20 日波动率
技术指标	`rsi_14`	RSI 相对强弱
技术指标	`turnover_rate`	换手率
基本面	`pe_ratio`	市盈率
基本面	`pb_ratio`	市净率
基本面	`roe`	净资产收益率
基本面	`debt_ratio`	资产负债率
基本面	`current_ratio`	流动比率
基本面	`gross_margin`	毛利率

自定义因子

支持用户通过表达式语法定义自定义因子，表达式引擎采用白名单校验机制，确保安全性。用户可在因子管理界面创建、编辑和管理自定义因子公式。

选股评分

StockScoringEngine 提供两种评分模式：

因子评分：基于多个因子的加权综合评分
ML 评分：基于机器学习模型的预测评分

2.3 机器学习建模模块

API 蓝图前缀：/api/ml-factor/*

核心服务：

MLModelManager（services/ml_models.py）：XGBoost / LightGBM / RandomForest 模型生命周期管理
ModelTrainingJobService（services/model_training_job_service.py）：异步训练任务轮询与管理

功能特性：

功能	说明
模型创建	支持 XGBoost、LightGBM、RandomForest 三大算法的模型创建
模型训练	支持同步与异步训练，异步训练通过 Celery 或内联模式执行
模型预测	训练完成的模型可直接用于股票预测
特征工程	因子组合与特征选择
性能评估	模型性能评估与多模型比较
训练任务管理	异步训练任务的提交、状态查询与管理

2.4 组合优化模块

API 蓝图前缀：/api/ml-factor/*

核心服务：

PortfolioOptimizer（services/portfolio_optimizer.py）：等权 / 均值方差 / 风险平价 / 因子中性

优化方法：

方法	说明	适用场景
等权重优化	所有股票分配相同权重	简单基准、等权组合
均值方差优化	基于 Markowitz 理论的均值-方差优化	追求风险调整后收益最大化
风险平价优化	基于风险贡献均衡的权重分配	风险均衡配置
因子中性组合	控制因子暴露度在中性水平	消除特定因子风险暴露

2.5 回测验证模块

API 蓝图前缀：/api/ml-factor/*

核心服务：

BacktestEngine（services/backtest_engine.py）：单策略与多策略回测

回测能力：

功能	说明
单策略回测	对单个选股策略进行历史回测验证
多策略比较	同时运行多个策略并比较绩效表现
年化收益率	计算策略的年化收益
夏普比率	风险调整后收益指标
最大回撤	策略的最大净值回撤幅度
胜率	盈利交易占比
卡尔玛比率	年化收益与最大回撤的比值

回测结果以可视化图表形式展示，支持净值曲线、收益分布等多种视图。

2.6 风险管理模块

API 蓝图前缀：/api/realtime-analysis/*

核心服务：

RealtimeRiskManager（services/realtime_risk_manager.py）：风险指标、预警管理、压力测试

功能特性：

功能	说明
投资组合持仓 CRUD	创建、查询、更新、删除投资组合持仓记录
实时价格刷新	通过通达信接口获取实时行情价格
风险指标监控	实时计算并展示组合风险指标
预警管理	设定预警规则，触发时自动通知
压力测试	模拟极端市场场景，分析组合表现

2.7 数据管理模块

API 蓝图前缀：/api/data-jobs/*

核心服务：

DataJobs（services/data_jobs/）：数据下载任务执行器

数据架构：

存储	用途	说明
Parquet 文件	市场行情数据	高性能列式存储，承载日线/分钟线行情、基本面、技术面、资金流数据
SQLite 数据库	应用状态	轻量级存储，管理持仓、报告、预警等低并发元数据
Redis 缓存	任务队列 & 缓存	Celery 任务 Broker、实时数据缓存、WebSocket 消息分发（可选）

数据下载工具（位于 app/utils/）：

工具	数据源	说明
`trade_calendar.py`	Tushare / Baostock	交易日历下载
`stock_basic.py`	Tushare / Baostock	股票基本信息下载
其他数据脚本	Tushare / Baostock	行情、财务等数据下载

注意：下载顺序为 trade_calendar.py → stock_basic.py → 其他脚本。

任务执行模式（通过 DATA_JOB_EXECUTION_MODE 环境变量控制）：

inline（默认开发模式）：在 Web 进程中直接执行，无需 Celery
celery（默认生产模式）：通过 Celery Worker 异步执行，需要 Redis

2.8 Text2SQL 自然语言查询模块

API 蓝图前缀：/api

核心服务：

Text2SQLEngine（services/text2sql_engine.py）：LLM 驱动的自然语言转 SQL 查询
LLMService（services/llm_service.py）：LLM 服务封装（Ollama / OpenAI）

功能说明：

用户可以使用自然语言描述查询需求，系统通过 LLM 将自然语言转换为 SQL 查询语句，直接查询股票数据。

LLM 配置：

配置	默认值	说明
默认提供商	Ollama	本地 LLM 服务
默认模型	qwen2.5-coder	阿里通义千问代码模型
可选提供商	OpenAI API	通过 `LLM_CONFIG` 配置切换

2.9 实时分析报告模块

API 蓝图前缀：/api/realtime-analysis/*

核心服务：

RealtimeReportGenerator（services/realtime_report_generator.py）：分析报告生成器

功能：基于实时行情数据和分析结果，自动生成可视化分析报告，涵盖市场概况、板块表现、个股分析等内容。

2.10 WebSocket 推送模块

API 蓝图前缀：/api/websocket/*

核心服务：

WebSocketPushService（app/websocket/websocket_push_service.py）：WebSocket 推送服务

功能：通过 WebSocket 实现数据的实时推送，支持实时行情、交易信号、风险预警等信息的即时通知。

三、系统架构概览

quantitative_analysis/
├── app/                              # 应用主目录
│   ├── __init__.py                  # Flask 工厂模式 (create_app)
│   ├── extensions.py                # 扩展初始化 (SQLAlchemy, SocketIO, Redis)
│   ├── api/                         # API 蓝图
│   │   ├── analysis_api.py          #   市场分析 API
│   │   ├── ml_factor_api.py         #   ML 因子管理 API
│   │   ├── realtime_analysis.py     #   实时分析 API
│   │   ├── realtime_indicators.py   #   实时指标 API
│   │   ├── realtime_signals.py      #   交易信号 API
│   │   ├── realtime_monitor.py      #   实时监控 API
│   │   ├── realtime_risk.py         #   风险管理 API
│   │   ├── realtime_report.py       #   分析报告 API
│   │   ├── text2sql_api.py          #   自然语言查询 API
│   │   ├── data_jobs_api.py         #   数据下载任务 API
│   │   └── websocket_api.py         #   WebSocket 管理 API
│   ├── models/                      # 数据模型 (SQLAlchemy + Parquet 事件)
│   ├── services/                    # 核心业务服务
│   ├── routes/                      # 页面路由 (HTML 渲染)
│   ├── templates/                   # Jinja2 HTML 模板
│   ├── static/                      # CSS / JS / 图片
│   ├── utils/                       # 数据下载脚本 (通达信/Baostock/Tushare)
│   ├── websocket/                   # WebSocket 推送服务
│   └── services/tongdaxin/          # 通达信行情客户端
├── data/                            # 数据目录
│   ├── stock_minute/                #   分钟级行情 Parquet
│   ├── ml_factor_state/             #   ML 因子状态 Parquet
│   └── realtime_events/            #   实时事件 Parquet
├── tests/                           # 测试用例
├── acceptance/                      # 验收标准与里程碑
├── config.py                        # 配置管理
├── run.py                           # Web 启动入口
└── run_system.py                    # 初始化与诊断工具

四、核心服务一览

服务	文件	职责
FactorEngine	`services/factor_engine.py`	内置因子计算与自定义因子管理
FactorExpressionEngine	`services/factor_expression_engine.py`	白名单校验的自定义因子公式引擎
MLModelManager	`services/ml_models.py`	XGBoost / LightGBM / RandomForest 模型生命周期
ModelTrainingJobService	`services/model_training_job_service.py`	异步训练任务轮询与管理
StockScoringEngine	`services/stock_scoring.py`	因子评分与 ML 评分的综合选股引擎
PortfolioOptimizer	`services/portfolio_optimizer.py`	等权 / 均值方差 / 风险平价 / 因子中性
BacktestEngine	`services/backtest_engine.py`	单策略与多策略回测
Text2SQLEngine	`services/text2sql_engine.py`	LLM 驱动的自然语言转 SQL 查询
RealtimeIndicatorEngine	`services/realtime_indicator_engine.py`	实时技术指标计算
RealtimeTradingSignalEngine	`services/realtime_trading_signal_engine.py`	多策略交易信号生成与融合
RealtimeRiskManager	`services/realtime_risk_manager.py`	风险指标、预警管理、压力测试
DataJobs	`services/data_jobs/`	数据下载任务执行器（Inline / Celery）

五、API 蓝图一览

URL 前缀	功能域
`/api`	主 API — 股票、分析、Text2SQL
`/api/ml-factor/*`	因子管理、ML 模型、选股评分、组合优化
`/api/data-jobs/*`	数据下载任务提交与状态查询
`/api/realtime-analysis/*`	实时指标、信号、监控、风险、报告
`/api/websocket/*`	WebSocket 管理端点

六、快速开始

1. 克隆 & 安装

git clone <repository-url>
cd quantitative_analysis

# 安装依赖
pip install -r requirements.txt

# 如遇兼容问题，使用最小依赖
pip install -r requirements_minimal.txt

2. 下载数据

下载预打包的 A 股历史数据，解压到 data/ 目录即可。也可通过系统内的数据管理页面在线更新。

3. 启动系统

# 启动 Web 服务
python run.py

# 访问地址
http://localhost:5000    # Web 界面
http://localhost:5000/api # API 入口

容器化启动（可选）

cp .env.example .env
docker compose up --build

默认启动 Web + SQLite + Redis；市场数据和 ML 因子状态仍使用本地 Parquet 文件。

七、配置说明

所有配置通过 config.py 管理，支持环境变量 .env 文件覆盖。

配置项	默认值	说明
`DATA_SOURCE`	`parquet`	数据源类型
`SQLALCHEMY_DATABASE_URI`	SQLite	应用状态数据库
`REDIS_HOST / REDIS_PORT`	`localhost:6379`	Redis 连接（Celery/缓存）
`FLASK_ENV`	`development`	运行环境
`DATA_JOB_EXECUTION_MODE`	`inline`	任务执行模式（inline / celery）
`LLM_CONFIG`	Ollama (qwen2.5-coder)	LLM 提供商配置

八、项目定位

✅ 适用场景

量化交易入门学习
策略研究与验证
二次开发与定制
量化系统架构参考

❌ 不适用场景

直接用于实盘交易
高频交易系统

九、版本历史

版本	日期	内容
v1.0.0	2025-06-01	多因子选股系统初始版本：因子管理和计算、机器学习模型集成、组合优化、回测验证引擎、Web 界面和 API 接口
v2.0.0-parquet	2026-06-06	架构升级：从 MySQL 迁移到 Parquet + SQLite，零外部数据库依赖。新增实时行情分析模块、通达信行情接入、日频数据中心、投资组合管理完整闭环、报告可视化、离线数据包

多因子选股系统 — 面向 A 股市场的全链路量化分析平台
MIT License

用hermes agent开发的每日市场简报

Henry Lin — Sat, 23 May 2026 13:59:22 +0000

第一次开发token消耗900K左右，后面复用，只需要调用脚本生成，不需要再消耗token。

📊 每日市场简报

2026-05-21（周四） · 共 5501 只股票

全市场成交额 35,072.80亿

一、涨跌概览

指标	数值
上涨家数	695 (12.6%)
下跌家数	4773
平盘家数	33
涨停数	🔴 40
跌停数	🟢 46
涨跌比	0.15:1

二、成交额 TOP10

排名	代码	名称	成交额(亿)	涨跌幅
1	688008.SH	澜起科技	306.55亿	+1.89%
2	603986.SH	兆易创新	281.99亿	-2.95%
3	300308.SZ	中际旭创	243.95亿	-4.21%
4	600584.SH	长电科技	213.24亿	+0.94%
5	688981.SH	中芯国际	206.02亿	-4.92%
6	688256.SH	寒武纪-U	205.30亿	-5.25%
7	002281.SZ	光迅科技	199.59亿	-8.08%
8	002384.SZ	东山精密	193.85亿	-7.19%
9	000988.SZ	华工科技	193.22亿	-5.79%
10	300502.SZ	新易盛	192.60亿	-3.74%

三、行业涨跌排名

排名	行业	均涨幅	上涨	下跌	总数
1	空运	+1.98%	7	0	8
2	公共交通	+0.93%	4	3	7
3	银行	+0.17%	20	18	42
4	白酒	+0.10%	7	12	19
5	路桥	-0.01%	10	7	19
6	水运	-0.03%	9	10	19
7	证券	-0.14%	14	31	50
8	摩托车	-0.24%	3	8	11
9	玻璃	-0.32%	5	14	19
10	汽车整车	-0.35%	5	16	22
11	生物制药	-0.47%	30	50	80
12	旅游服务	-0.57%	2	5	8
13	港口	-0.58%	4	11	16
14	酒店餐饮	-0.67%	3	6	9
15	机场	-0.78%	0	4	5
16	红黄酒	-0.90%	1	8	9
17	旅游景点	-0.91%	3	15	18
18	汽车配件	-0.91%	81	174	258
19	保险	-0.94%	0	5	5
20	纺织机械	-1.13%	3	8	11
21	火力发电	-1.26%	5	26	31
22	公路	-1.30%	0	3	3
23	铁路	-1.48%	0	7	7
24	水力发电	-1.49%	5	17	22
25	家用电器	-1.51%	24	66	91
26	电器连锁	-1.65%	0	2	2
27	普钢	-1.67%	2	24	26
28	机床制造	-1.69%	5	19	24
29	工程机械	-1.77%	9	29	38
30	化学制药	-1.80%	25	120	147
31	园区开发	-1.81%	1	13	14
32	中成药	-1.88%	5	63	68
33	医疗保健	-1.93%	27	153	181
34	水泥	-2.06%	4	19	23
35	多元金融	-2.11%	0	23	23
36	机械基件	-2.23%	34	100	134
37	服饰	-2.26%	10	54	64
38	特种钢	-2.26%	0	10	10
39	造纸	-2.29%	6	28	34
40	仓储物流	-2.31%	2	43	46
41	日用化工	-2.33%	2	18	20
42	汽车服务	-2.33%	1	9	10
43	农业综合	-2.34%	2	40	42
44	新型电力	-2.35%	5	25	30
45	食品	-2.43%	5	87	93
46	医药商业	-2.44%	0	37	37
47	百货	-2.44%	3	32	35
48	水务	-2.45%	0	14	15
49	家居用品	-2.49%	8	63	71
50	饲料	-2.54%	1	22	23
51	元器件	-2.56%	58	242	300
52	纺织	-2.58%	6	36	42
53	石油加工	-2.59%	1	13	14
54	渔业	-2.61%	0	7	7
55	小金属	-2.67%	8	56	64
56	铝	-2.70%	4	26	30
57	啤酒	-2.71%	0	8	8
58	轻工机械	-2.74%	0	7	7
59	黄金	-2.86%	0	10	10
60	农药化肥	-2.91%	3	55	58
61	影视音像	-2.92%	0	35	35
62	乳制品	-2.95%	0	21	21
63	煤炭开采	-2.97%	1	25	26
64	农用机械	-3.00%	0	13	13
65	超市连锁	-3.02%	0	8	8
66	林业	-3.06%	0	4	4
67	出版业	-3.07%	0	29	29
68	建筑工程	-3.12%	7	121	128
69	电器仪表	-3.14%	14	92	106
70	航空	-3.16%	3	49	52
71	电信运营	-3.17%	0	5	5
72	文教休闲	-3.23%	1	50	51
73	矿物制品	-3.24%	4	30	35
74	环境保护	-3.26%	12	108	120
75	其他商业	-3.26%	1	11	12
76	供气供热	-3.31%	3	42	45
77	塑料	-3.36%	7	71	78
78	种植业	-3.43%	0	19	19
79	广告包装	-3.44%	5	49	54
80	运输设备	-3.47%	1	47	48
81	化纤	-3.47%	1	33	34
82	互联网	-3.52%	4	76	80
83	专用机械	-3.53%	24	254	280
84	商贸代理	-3.54%	1	14	16
85	船舶	-3.55%	0	11	11
86	铜	-3.56%	1	17	18
87	铅锌	-3.59%	1	13	14
88	IT设备	-3.67%	4	73	78
89	电气设备	-3.69%	38	303	342
90	批发业	-3.71%	0	5	5
91	软件服务	-3.77%	23	256	279
92	全国地产	-3.80%	1	25	26
93	染料涂料	-3.84%	4	30	34
94	钢加工	-3.84%	0	23	23
95	其他建材	-3.84%	1	29	30
96	陶瓷	-3.93%	0	5	5
97	房产服务	-3.97%	0	13	13
98	化工原料	-4.00%	16	238	255
99	化工机械	-4.08%	1	12	13
100	焦炭加工	-4.13%	0	7	7
101	综合类	-4.14%	0	19	19
102	橡胶	-4.19%	0	17	17
103	装修装饰	-4.20%	1	24	25
104	商品城	-4.28%	0	4	4
105	区域地产	-4.38%	2	42	44
106	通信设备	-4.69%	11	124	135
107	石油贸易	-4.76%	0	4	4
108	软饮料	-4.83%	0	9	9
109	石油开采	-5.36%	0	21	21
110	半导体	-5.76%	17	176	193

四、主力资金动向

🔥 净流入 TOP5

排名	代码	名称	净流入(亿)
1	002050.SZ	三花智控	3.00亿
2	688008.SH	澜起科技	1.99亿
3	300274.SZ	阳光电源	1.91亿
4	600745.SH	闻泰科技	1.35亿
5	300059.SZ	东方财富	1.03亿

💧 净流出 TOP5

排名	代码	名称	净流出(亿)
1	000725.SZ	京东方Ａ	-4.86亿
2	603986.SH	兆易创新	-3.08亿
3	600522.SH	中天科技	-2.57亿
4	601138.SH	工业富联	-2.18亿
5	002384.SZ	东山精密	-1.87亿

五、特殊形态统计

形态	数量
首板（首次涨停）	32
连板（连续涨停）	8
阳包阴	60
连涨≥3天	142

🎯 连板个股明细

代码	名称	连板天数
603779.SH	威龙股份	7连板
603316.SH	诚邦股份	4连板
000518.SZ	*ST四环	2连板
002442.SZ	龙星科技	2连板
003004.SZ	*ST声迅	2连板
300069.SZ	金利华电	2连板
301139.SZ	元道通信	2连板
600611.SH	大众交通	2连板

🌅 阳包阴个股（TOP20）

代码	名称	涨跌幅
920100.BJ	三协电机	+14.18%
301488.SZ	豪恩汽电	+10.64%
600936.SH	北投科技	+10.08%
600156.SH	华升股份	+10.04%
600360.SH	*ST华微	+10.03%
002888.SZ	惠威科技	+10.00%
002940.SZ	昂利康	+10.00%
603373.SH	安邦护卫	+9.99%
600578.SH	京能电力	+9.95%
000404.SZ	长虹华意	+8.46%
001331.SZ	胜通能源	+7.86%
603037.SH	凯众股份	+6.82%
300276.SZ	三丰智能	+6.60%
600481.SH	双良节能	+6.56%
603040.SH	新坐标	+6.31%
603693.SH	江苏新能	+6.29%
001270.SZ	*ST铖昌	+6.19%
601127.SH	赛力斯	+6.14%
002471.SZ	中超控股	+5.71%
002284.SZ	亚太股份	+5.65%

📈 连涨≥3天个股（TOP10）

代码	名称	3日累计涨幅
301020.SZ	密封科技	+32.53%
603316.SH	诚邦股份	+30.02%
603779.SH	威龙股份	+29.99%
001259.SZ	利仁科技	+29.28%
605288.SH	凯迪股份	+28.65%
688585.SH	上纬新材	+28.29%
688610.SH	埃科光电	+27.44%
300152.SZ	ST新动力	+25.67%
301322.SZ	绿通科技	+25.19%
300715.SZ	凯伦股份	+25.10%

由 Hermes Quant 每日市场简报生成器自动生成

生成时间: 2026-05-23 21:39:23

第 1 章：什么是 FreqAI / 安装与首次运行

Henry Lin — Sun, 17 May 2026 07:21:23 +0000

第 1 章：什么是 FreqAI / 安装与首次运行

对应官方文档：https://www.freqtrade.io/en/stable/freqai/

学习目标

用一句话说清 FreqAI 解决什么问题
理解 FreqAI 的"训练—预测—再训练"循环
完成 FreqAI 依赖安装
跑通一个最小可运行的 LightGBM 回归示例，看到 backtest 报告

1.1 FreqAI 是什么

官方原话：

FreqAI is a software designed to automate a variety of tasks associated with training a predictive machine learning model to generate market forecasts given a set of input features.

人话版：FreqAI 是给 Freqtrade 策略加上"机器学习预测能力"的官方框架。你只要在策略里写几个钩子说明"我要用哪些特征、要预测什么"，FreqAI 就自动负责：

拉数据、构造特征、对齐时间戳
切分训练/测试集
训练模型并保存到磁盘
推理出预测列（&- 开头）回填到 dataframe
按时间窗口自动再训练适应市场漂移

你在策略里像用普通 indicator 一样使用预测列就行。

1.2 FreqAI 的工作循环

┌──────────────────────────────────────────────────────────────────┐
│  Freqtrade Pair Dataframe (OHLCV + base indicators)              │
└──────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│  Strategy hooks (你写的):                                        │
│    feature_engineering_expand_all   ──▶ %- 特征（按period展开） │
│    feature_engineering_expand_basic ──▶ %- 特征（不随period展开）│
│    feature_engineering_standard     ──▶ %- 特征（最终统一处理） │
│    set_freqai_targets               ──▶ &- 标签（必须）          │
└──────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│  FreqAI 引擎自动完成：                                           │
│    1. 按 train_period_days 切训练窗口                            │
│    2. 标准化 / 异常值检测 / PCA（可选）                          │
│    3. 调用模型 fit() 训练                                        │
│    4. 保存模型到 user_data/models/<identifier>/                  │
│    5. 在 backtest_period_days 范围内做 predict() 回填到 df       │
└──────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│  策略 populate_entry_trend / populate_exit_trend：               │
│    用 df["&-s_close"] 或 df["do_predict"] 当作普通指标使用       │
└──────────────────────────────────────────────────────────────────┘
                          │
                          ▼
                       下单 / 平仓

关键点：

%- 前缀：模型用作输入的特征
&- 前缀：模型要预测的目标（label）
无前缀：中间计算列，不进入模型
窗口每滚动 backtest_period_days 天就重新训练一次（实盘里改用 live_retrain_hours）

1.3 安装

FreqAI 不在 Freqtrade 默认依赖里，需要单独装：

conda activate freqtrade

# 进入你的 freqtrade 源码或安装目录
pip install -r requirements-freqai.txt

这会装上：lightgbm、catboost、xgboost、scikit-learn、datasieve 等。

Docker 用户改用镜像 freqtradeorg/freqtrade:stable_freqai 即可。

第 7 章的强化学习需要额外的 requirements-freqai-rl.txt（含 stable-baselines3 与 torch，大约 700MB，按需安装）。

1.4 最小可运行示例

我们要做的事情非常简单：预测未来 12 根 5m K 线的平均收盘价相对当前 close 的偏移。本质是一个回归问题，预测出来的值约等于 "未来一小时的预期回报率"。

策略文件：examples/ch01/FreqaiHelloStrategy.py

配置文件：examples/ch01/config_ch01.json

1.4.1 策略代码精读

class FreqaiHelloStrategy(IStrategy):
    timeframe = "5m"
    can_short = False
    process_only_new_candles = True
    startup_candle_count = 40           # >= indicator_periods_candles 最大值 * 2

    def feature_engineering_expand_all(self, dataframe, period, metadata, **kwargs):
        # 每个 period（10, 20）都会被自动展开一遍
        dataframe[f"%-rsi-period_{period}"] = ta.RSI(dataframe, timeperiod=period)
        dataframe[f"%-ema-period_{period}"] = ta.EMA(dataframe, timeperiod=period)
        return dataframe

    def set_freqai_targets(self, dataframe, metadata, **kwargs):
        # 必须实现：定义 &- 开头的列作为预测目标
        horizon = self.freqai_info["feature_parameters"]["label_period_candles"]
        dataframe["&-s_close"] = (
            dataframe["close"].shift(-horizon).rolling(horizon).mean()
            / dataframe["close"] - 1
        )
        return dataframe

    def populate_indicators(self, dataframe, metadata):
        # 把 freqai 引擎接进来——这是必须的一行
        dataframe = self.freqai.start(dataframe, metadata, self)
        return dataframe

    def populate_entry_trend(self, dataframe, metadata):
        # 预测值 > 0 且预测置信度 ok 就开多
        dataframe.loc[
            (dataframe["&-s_close"] > 0.002) & (dataframe["do_predict"] == 1),
            "enter_long",
        ] = 1
        return dataframe

    def populate_exit_trend(self, dataframe, metadata):
        dataframe.loc[dataframe["&-s_close"] < 0, "exit_long"] = 1
        return dataframe

记住两个魔法字段：

do_predict：FreqAI 自动加在 dataframe 上的"这一行预测是否有效"标记（1 表示在 DI 阈值内可信）
&-s_close：你定义的 label 在推理阶段会被同名列自动覆盖为预测值

1.4.2 配置文件精读

config_ch01.json 的 freqai 块：

"freqai": {
    "enabled": true,
    "identifier": "ch01_hello",
    "train_period_days": 15,
    "backtest_period_days": 5,
    "live_retrain_hours": 0,
    "purge_old_models": 2,
    "feature_parameters": {
        "include_timeframes": ["5m"],
        "include_corr_pairlist": [],
        "label_period_candles": 12,
        "include_shifted_candles": 2,
        "indicator_periods_candles": [10, 20]
    },
    "data_split_parameters": { "test_size": 0.2, "shuffle": false },
    "model_training_parameters": { "n_estimators": 300 }
}

最小可运行配置：单时间框架、无相关币种、两个指标周期。

1.5 运行命令

conda activate freqtrade

# 1. 预下载数据（带 35 天 buffer，给 train_period_days=15 + startup=40 留余地）
freqtrade download-data \
  --exchange binance \
  --pairs BTC/USDT ETH/USDT \
  --timeframes 5m \
  --timerange 20240501-20240801

# 2. 跑回测
freqtrade backtesting \
  --config freqai-tutorial/examples/ch01/config_ch01.json \
  --strategy FreqaiHelloStrategy \
  --strategy-path freqai-tutorial/examples/ch01 \
  --freqaimodel LightGBMRegressor \
  --timerange 20240601-20240731

期待输出（节选）：

=========== FREQAI ENABLED ===========
Found XX historical candles for BTC/USDT 5m
Training model for BTC/USDT
...
============================ BACKTESTING REPORT ============================
| Pair        | Entries | Avg Profit % | ... |
| BTC/USDT    | XX      | X.XX         | ... |

只要看到 "Training model for ..." 与最终的 BACKTESTING REPORT 表格，就说明跑通了。

1.6 常见错误

报错	原因	解决
`KeyError: 'freqai'` 或 `freqai_info is None`	配置里没启用 freqai 块	检查 `freqai.enabled: true`，且 `freqaimodel` 命令行参数已传
`No model found in user_data/models/<identifier>/...`	训练窗口不够 / 数据没下载完	把 `--timerange` 起点往后挪到 `train_period_days + startup` 之后
`KeyError: '&-s_close'` 在 populate_entry_trend	忘了在 populate_indicators 里调 `self.freqai.start(...)`	加上那一行
`Cannot use VolumePairList with FreqAI`	用了动态币池	改成静态 `StaticPairList` 或 `ShufflePairList`

1.7 验证情况

✅ 本章示例在 conda activate freqtrade 环境下完整跑通了 backtesting（见教程仓库 README）。如果你的环境跑不起来，多半是数据没下全或 freqtrade 版本太老（建议 ≥ 2024.x）。

1.8 小结与下一章

你已经会跑一个最小 FreqAI 策略了。但很多配置字段是直接照抄的，第 2 章会逐项拆解 freqai 块每个字段的含义，让你能根据自己的需求改配置。

为什么长期做量化，一定要先搭建自己的“数据中台”

Henry Lin — Tue, 12 May 2026 11:24:30 +0000

为什么长期做量化，一定要先搭建自己的数据中台

很多人做量化，第一步就开始研究策略。

今天学一个 MACD，明天学一个 AI 选股，后天开始回测。结果半年后，策略越来越多，代码越来越乱，数据越来越碎，整个系统根本没法扩展。

尤其是个人开发者、独立量化团队，经常会踩一个坑：

把量化系统当成了策略工程，而不是数据工程。

但说实话，真正长期跑得起来的量化系统，重心其实不在策略上，而在数据层。

为什么数据底座这么重要？

量化系统本质上就是数据驱动。所有策略、因子、回测、AI 模型、风控、选股，全都建在数据之上。

数据层一旦出问题，后面什么都跟着乱：

指标没法统一，同一个 PE 不同来源数值不一样
股票代码混乱，有的表叫 code，有的叫 symbol，有的叫 ts_code
时间周期对不上，日线周线分钟线混在一起
财务数据缺失，财报更新不及时
因子重复计算，好几个策略各算一遍一样的东西
回测和实盘用的数据不一致，结果根本没法复现

很多人刚开始只有几十只股票的数据，觉得 CSV 就够了。但做半年以后你会发现，日线、分钟线、基本面、财报、资金流、技术指标、因子库、AI 特征、新闻舆情、宏观数据……数据量增长得比你想的快得多。这时候如果没有统一的数据管理方式，后面几乎没法维护。

一个成熟量化系统需要哪些数据？

长期来看，建议至少把下面这些数据管起来：

                    ┌─────────────────────┐
                    │    数据中台 / DataHub │
                    └─────────────────────┘
                               │
 ┌────────────────────────────────────────────────────────┐
 │                                                        │
 │ • daily_history   (日线行情 OHLCV)                      │
 │ • daily_basic    (基本面 PE/PB/换手率)                  │
 │ • moneyflow      (资金流向)                             │
 │ • stk_factor     (技术指标 MACD/KDJ/RSI)                │
 │ • stock_basic    (股票基础信息)                         │
 │ • balance_sheet  (资产负债表)                           │
 │ • income_statement (利润表)                             │
 │ • cash_flow      (现金流量表)                           │
 │                                                        │
 └────────────────────────────────────────────────────────┘
                               │
        ┌──────────────────────────────────┐
        │                                  │
        │  因子系统 / 回测 / AI / 策略引擎   │
        │                                  │
        └──────────────────────────────────┘

为什么建议一开始就搭？

有开发者会说："我策略还没跑通，先不用那么复杂吧。"

这想法挺正常的，但后期再重构数据层，代价真的很大。

量化有个特点：数据只会越来越多。你今天可能只有 500 只股票的日线，但早晚要加全市场、分钟线、Tick、期货、ETF、美股、港股、AI 特征、另类数据。

如果一开始没设计好数据结构，后面大概率会遇到：表结构崩坏、查询变慢、指标重复计算、Redis 缓存失控、CSV 满天飞、Python 脚本互相依赖改一个挂一片。等你想整理的时候，已经理不清了。

量化的核心其实不是策略，是数据复用

大部分刚入门的人觉得策略最重要。但实际上，成熟的量化团队花在数据一致性、数据清洗、数据标准化、因子复用、特征工程上的精力，远比调参多。

原因很简单：一份数据可以反复用。

比如同一份 daily_history，动量策略用得着，AI 训练用得着，因子分析用得着，行业轮动用得着，回测用得着，择时用得着，可视化展示用得着，选股器也用得着。

所以长期来看，真正有价值的是持续积累的数据资产，不是某一个短期能赚钱的策略。策略会过时，数据不会。

AI 和量化的关系

AI 深度介入量化已经是大趋势了。但 AI 有个硬需求：它要吃数据，而且是干净、结构化、能对齐的数据。

没有稳定的数据底座，特征工程做不了，时序训练做不了，多周期融合做不了，Walk-Forward 做不了，因子挖掘做不了，AutoML 也做不了。

我见过不少人，最后卡住的不是策略能力，是数据根本接不起来。

个人开发者推荐的技术架构

个人或者小团队没必要上来就搞 Hadoop。以下这些够用了：

数据存储： PostgreSQL / ClickHouse / DuckDB / Parquet

缓存层： Redis

任务调度： Airflow / Celery / Cron

数据处理： Python + Pandas + Polars

因子计算： TA-Lib / vectorbt / Qlib

两条不同的路

很多人的路径是这样的：

策略 → 回测 → 亏钱 → 放弃

而把数据当核心资产的人，路径大概是这样：

数据底座 → 因子平台 → 回测框架 → AI 特征工程 → 自动选股 → 多策略组合 → 风控系统 → 实盘交易

区别就在于你把数据当成附属品，还是当成核心资产。

总结

长期做量化，与其急着写策略、做回测、研究 AI，不如先把数据中台搭起来。

策略会失效，市场会变，模型会过时。但数据资产会一直积累，越往后越值钱。

量化这件事，拼到最后，壁垒往往不是什么策略秘密，而是你手里有没有一套长期积累、持续迭代的数据底座。

US Stock Screener

Henry Lin — Wed, 06 May 2026 00:44:39 +0000

US Stock Screener

Access address

https://usstockscreener-production-6b89.up.railway.app/

A daily US stock screener built with FastAPI + React. Fetches a curated tech/value stock pool via yfinance, computes daily technical patterns and rolling indicators into a single data.parquet snapshot, and serves a full-featured filter/sort/research UI with real-time data support.

Features

Main Screener

Pattern filters — single/double/triple candlestick patterns, MA trend patterns, volume/volatility signals, momentum signals
Numeric filters — range conditions on any continuous metric (PE, ROE, market cap, etc.)
Preset strategies — one-click strategy presets combining multiple filters
Sortable table — sort by any column; paginated results
Signal score — composite ranking score shown per stock

Watchlist

Star any stock to add it to your watchlist (persisted via localStorage)
Watchlist-only mode — filter the table to show only starred stocks
Watchlist bar shows count and quick actions

Stock Research Page (`/stock/:symbol`)

Price chart with candlestick + volume
Technical indicators panel (MA, volatility, drawdown)
Financials panel (PE, PB, ROE, margins, growth)
Pattern history panel — win-rate and average return for triggered patterns
Previous / next navigation within current filtered results

Compare Page (`/compare`)

Select 2–5 stocks via checkboxes in the screener or "Add to Compare" on research pages
Side-by-side metric table across 7 categories: Overview, Price Momentum, Valuation, Profitability, Growth, Financial Health, Risk
Best value highlighted green, worst highlighted red per metric row
Selection persists across page navigations (sessionStorage), resets on filter/sort change

Pattern Stats Page (`/pattern-stats`)

Historical win-rate and average return for every pattern signal in the stock pool

美股日线选股器

Henry Lin — Wed, 06 May 2026 00:42:30 +0000

美股日线选股器

访问地址：https://usstockscreener-production-6b89.up.railway.app/

基于 FastAPI + React 构建的美股每日选股工具。通过 yfinance 拉取精选科技/价值股票池，计算日线技术形态与滚动指标，生成 data.parquet 快照文件，并提供功能完整的筛选、排序与研究页面，支持实时数据显示。

功能介绍

主页选股器

形态筛选 — 单日/双日/三日 K 线形态，均线趋势形态，量能/波动率信号，动量信号
数值筛选 — 对任意连续指标（PE、ROE、市值等）设置范围条件
预设策略 — 一键应用组合多个筛选条件的策略预设
可排序表格 — 按任意列排序，支持分页
综合评分 — 每只股票显示合成信号评分

观察列表

点击星标将股票加入观察列表（通过 localStorage 持久化）
仅看观察列表模式 — 过滤表格只展示已收藏的股票
观察列表栏显示数量及快捷操作

个股研究页（`/stock/:symbol`）

K 线图 + 成交量图表
技术指标面板（均线、波动率、最大回撤）
财务指标面板（PE、PB、ROE、利润率、增长率）
形态历史面板 — 展示每个触发形态的历史胜率与平均收益
在当前筛选结果内前后翻页导航

对比页（`/compare`）

在选股器勾选复选框或在研究页点击"添加对比"，最多选取 5 只股票进行对比
7 大类别横向对比指标：综合、价格动量、估值、盈利能力、成长性、财务健康、风险
每行最优值标绿、最差值标红
选择状态跨页保留（sessionStorage），切换筛选/排序条件时自动清空

形态统计页（`/pattern-stats`）

展示股票池中每个形态信号的历史胜率与平均收益

页面使用说明

主页选股器

左侧筛选面板点击形态标签进行筛选，激活的筛选条件显示在顶部标签栏
点击数值筛选图标可对 PE、ROE、市值等连续指标设置范围
点击预设策略按钮一键应用组合策略
表格列头可点击排序，底部分页切换
点击星标（☆）将股票加入观察列表
勾选复选框将股票加入对比列表（最多 5 只）
选满 2 只后，顶部出现比较(N)→ 按钮，底部出现对比栏

实时数据功能

顶部状态栏显示当前数据源类型（FREE/PREMIUM）和延迟状态
点击"排名"按钮可展开/收起实时排名面板（仅付费版）
股票表格中带有闪烁绿点的股票为实时数据
点击"刷新"按钮手动更新实时报价

个股研究页

点击任意股票行进入研究页
顶部可切换到上一只/下一只（在当前筛选结果内）
点击添加对比将该股加入对比列表

对比页

选好 2–5 只股票后，点击对比栏的查看对比 → 或顶部 比较(N)→ 进入
逐行对比 17 项指标，绿色为同行最优，红色为同行最差
点击重新选择清空列表并返回主页

Hermes Agent 项目思维导图

Henry Lin — Sun, 19 Apr 2026 13:38:57 +0000

Hermes Agent 项目思维导图

这份文档用于导入 XMind 或其他支持 Markdown 层级导入的思维导图工具。主体内容尽量使用稳定的分级结构，减少长段解释，方便直接转换为脑图。

Hermes Agent
- 项目定位
- 自主型 AI Agent 运行时
- 不只是聊天界面
- 不只是 IDE copilot
- 目标
  - 调用工具完成任务
  - 跨会话保留长期能力
  - 跨平台运行
  - 支持自动化与扩展
- 典型场景
  - 本地开发助手
  - 远程消息平台代理
  - 定时任务与监控
  - 企业内部系统接入
  - 研究与批处理
- 用户入口
- CLI
  - hermes
  - 交互式主入口
  - 最完整的调试与观察界面
- Gateway
  - hermes gateway
  - Telegram
  - Discord
  - Slack
  - WhatsApp
  - Signal
  - 其他平台适配器
- ACP
  - 编辑器集成
  - VS Code
  - Zed
  - JetBrains
- API Server / Python Library / Batch Runner
  - 程序化调用
  - 轨迹批处理
  - 研究与训练相关入口
- 核心能力
- Tools
  - 文件操作
  - 终端执行
  - Web 搜索与抽取
  - Browser 自动化
  - Vision / TTS / Image Gen
  - Memory
  - Messaging
  - Delegation
  - Cron
- Toolsets
  - 核心 toolset
  - 组合 toolset
  - 平台 toolset
  - 动态 toolset
- Skills
  - 按需加载的流程知识
  - 本地 skills
  - Skills Hub
  - 动态 slash commands
- Memory
  - 跨会话事实信息
  - MEMORY.md / USER.md
  - 外部 memory provider
- Context Files
  - AGENTS.md
  - SOUL.md
  - .cursorrules
  - .cursor/rules/*.mdc
- MCP
  - 外部工具接入
  - stdio server
  - HTTP server
  - 动态工具注册
- Cron
  - 定时运行新 session
  - delivery 到平台
- Delegation
  - 子代理
  - 并行任务
  - 上下文隔离
- 核心运行系统
- AIAgent
  - run_agent.py
  - chat()
  - run_conversation()
  - 同步 agent loop
- Prompt Builder
  - agent/prompt_builder.py
  - 组装系统提示词
  - 注入 personality / memory / context / skills
- Prompt Caching
  - agent/prompt_caching.py
  - 保持 prefix cache
- Context Compression
  - agent/context_compressor.py
  - 长会话压缩
- Provider / Runtime Resolution
  - hermes_cli/runtime_provider.py
  - hermes_cli/auth.py
  - provider 选择
  - credentials 解析
- Tool Dispatch
  - model_tools.py
  - schema 收集
  - handle function call
  - tool availability gating
- Session Storage
  - hermes_state.py
  - gateway/session.py
  - SQLite + FTS5
- Response Delivery
  - CLI display
  - gateway delivery
  - cron delivery
- 核心模块
- 顶层核心文件
  - run_agent.py
  - cli.py
  - model_tools.py
  - toolsets.py
  - hermes_state.py
  - batch_runner.py
- agent/
  - prompt builder
  - context compressor
  - prompt caching
  - auxiliary client
  - display
  - skill commands
  - trajectory
- hermes_cli/
  - main.py
  - config.py
  - commands.py
  - setup.py
  - tools_config.py
  - skills_config.py
  - model_switch.py
  - auth.py
- tools/
  - registry.py
  - terminal_tool.py
  - file_tools.py
  - web_tools.py
  - browser_tool.py
  - code_execution_tool.py
  - delegate_tool.py
  - mcp_tool.py
  - environments/
- gateway/
  - run.py
  - session.py
  - delivery.py
  - pairing.py
  - platforms/
- cron/
  - jobs.py
  - scheduler.py
- 其他关键目录
  - acp_adapter/
  - plugins/
  - skills/
  - optional-skills/
  - website/
  - tests/
- 配置与状态体系
- ~/.hermes/config.yaml
- ~/.hermes/.env
- ~/.hermes/SOUL.md
- ~/.hermes/skills/
- ~/.hermes/sessions/
- HERMES_HOME
- Profiles
  - hermes profile list
  - hermes profile create
  - hermes profile use
  - hermes profile show
- 关键规则
- Prompt cache 不应随意打破
- 不要中途重建系统提示
- Toolset 不应在会话中随意变化
- profile-safe 路径规则
  - get_hermes_home()
  - display_hermes_home()
- Tool / Skill / MCP 的选择边界
  - 流程优先 skill
  - 外部系统优先 MCP
  - 原生底层能力再做 tool
- 测试不要写到真实 ~/.hermes
- 关键文件
- 入口
  - run_agent.py
  - cli.py
  - gateway/run.py
- 工具系统
  - model_tools.py
  - toolsets.py
  - tools/registry.py
- 配置系统
  - hermes_cli/config.py
  - hermes_cli/main.py
  - hermes_constants.py
- 会话与状态
  - hermes_state.py
  - gateway/session.py
- 扩展系统
  - tools/mcp_tool.py
  - agent/skill_commands.py
  - hermes_cli/commands.py
- 关键流程
- CLI 请求流程
  - 用户输入
  - CLI
  - AIAgent
  - Prompt Builder
  - Provider / Runtime Resolution
  - Model API Call
  - Tool Dispatch
  - Built-in Tools / MCP Tools
  - Session Storage
  - CLI display
- Gateway 请求流程
  - 平台消息
  - Gateway
  - 会话解析与授权
  - AIAgent
  - Tool Dispatch
  - Session Storage
  - 平台回传
- Cron 请求流程
  - Scheduler Tick
  - 新 session
  - AIAgent
  - Tool Dispatch
  - Session Storage
  - Delivery target
- MCP 工具接入流程
  - mcp_servers
  - server connect
  - tool discovery
  - dynamic toolset
  - model 可调用
- Tool 调用流程
  - schema collection
  - model tool call
  - handle_function_call()
  - registry dispatch
  - tool result
  - loop continuation
- 常用命令与观察点
- CLI
  - hermes
  - hermes setup
  - hermes model
  - hermes tools
  - hermes gateway
  - hermes cron
- Session Commands
  - /model
  - /usage
  - /compress
  - /tools
  - /toolsets
  - /skills
  - /reload-mcp
  - /background
- Debug
  - hermes doctor
  - hermes status
  - /verbose
  - python -m pytest tests/ -q

Hermes Agent 核心运行系统调用流程--源码分析

Henry Lin — Tue, 14 Apr 2026 12:44:22 +0000

Hermes Agent 核心运行系统调用流程

本文基于当前仓库实现梳理 Hermes Agent 从入口层到结果交付的真实调用链，重点覆盖：

核心运行系统 AIAgent
Prompt Builder / Prompt Caching / Context Compression
Provider / Runtime Resolution
Tool Dispatch
Session Storage
Response Delivery（CLI / gateway / cron）

不展开单个 tool 的内部业务逻辑，重点描述“谁调用谁、数据如何流动、哪些状态被缓存或持久化”。

1. 总体分层

入口层
  CLI: cli.py
  Gateway: gateway/run.py
  Cron: cron/scheduler.py
      ↓
运行时解析
  hermes_cli/runtime_provider.py
  hermes_cli/auth.py
      ↓
核心 Agent 初始化
  run_agent.py -> AIAgent.__init__()
      ↓
系统提示词装配
  AIAgent._build_system_prompt()
  agent/prompt_builder.py
      ↓
同步 agent loop
  AIAgent.run_conversation()
      ↓
模型响应二分
  无 tool_calls -> 最终响应
  有 tool_calls -> tool dispatch -> tool result 回填 -> 下一轮
      ↓
上下文管理
  agent/prompt_caching.py
  agent/context_compressor.py
      ↓
持久化
  hermes_state.py / gateway/session.py
      ↓
结果交付
  CLI Rich/TUI
  Gateway adapter.send(...)
  Cron output file + auto delivery

2. 三个入口如何进入 AIAgent

2.1 CLI 路径

入口主要在 cli.py：

HermesCLI.chat() 先调用 _ensure_runtime_credentials()。
_ensure_runtime_credentials() 通过 resolve_runtime_provider() 解析 provider、api_mode、base_url、api_key。
_init_agent() 在首次使用或路由变化时创建 AIAgent(...)。
HermesCLI.chat() 调用 self.agent.run_conversation(...)。
返回结果后，CLI 负责把 reasoning / response / TTS / streaming 内容显示到终端。

关键点：

CLI 会在 provider、model、route、credential 变化时重建 agent，而不是复用旧 client。
CLI 恢复会话时，会先从 SessionDB 取历史消息，再交给 AIAgent 继续运行。

相关位置：

cli.py:2169 _ensure_runtime_credentials()
cli.py:2269 _init_agent()
cli.py:6309 HermesCLI.chat()

2.2 Gateway 路径

入口主要在 gateway/run.py：

收到平台消息后，SessionStore.get_or_create_session(source) 建立/获取会话。
build_session_context(...) 和 build_session_context_prompt(...) 生成平台上下文。
session_store.load_transcript(session_id) 读取历史对话。
_run_agent(...) 内部解析 runtime、构造或复用 AIAgent。
调用 agent.run_conversation(message, conversation_history=agent_history, ...)。
将新消息写回 transcript / SQLite，并把最终结果返回给 adapter。

关键点：

Gateway 不把 session context 写进持久化的 system prompt，而是作为 ephemeral_system_prompt 每轮临时注入，避免破坏 prompt cache 前缀。
Gateway 会按 session_key + agent config signature 缓存 AIAgent，尽量复用同一个 agent 实例，保持 system prompt 和 tool schema 稳定。

相关位置：

gateway/run.py:2308 获取/创建 session
gateway/run.py:2342 构造 context prompt
gateway/run.py:2435 加载 transcript
gateway/run.py:6647 创建/复用 AIAgent
gateway/run.py:6856 调用 run_conversation()

2.3 Cron 路径

入口主要在 cron/scheduler.py 的 run_job(job)：

构造 cron 专用 prompt（包含 skill 展开、cron 执行提示）。
resolve_runtime_provider() 解析运行时 provider。
创建 AIAgent(..., platform="cron", disabled_toolsets=["cronjob", "messaging", "clarify"], skip_memory=True)。
在线程池里执行 agent.run_conversation(prompt)。
生成 markdown output 文档并保存到 ~/.hermes/cron/output/...。
如配置了 deliver，调用 _deliver_result() 发送到目标平台。

关键点：

cron 是 headless 执行，不允许 clarify。
cron 同样接入 SessionDB，因此历史可被 session_search 检索。
cron 有“无活动超时”机制，不是简单 wall-clock timeout。

相关位置：

cron/scheduler.py:512 run_job()
cron/scheduler.py:623 runtime 解析
cron/scheduler.py:643 创建 AIAgent
cron/scheduler.py:678 调用 run_conversation()
cron/scheduler.py:199 _deliver_result()

3. Provider / Runtime Resolution 调用链

运行时解析由 hermes_cli/runtime_provider.py 统一封装，CLI / gateway / cron 都走这里。

3.1 入口函数

统一入口：

resolve_runtime_provider(...) in hermes_cli/runtime_provider.py:566

它返回一个 runtime dict，典型字段包括：

provider
api_mode
base_url
api_key
command / args（外部进程型 provider）
credential_pool
requested_provider

3.2 解析步骤

resolve_runtime_provider() 的主流程：

resolve_requested_provider() 先决定“用户想要哪个 provider”。
_resolve_named_custom_runtime() 先尝试命名 custom provider。
resolve_provider() in hermes_cli/auth.py 解析最终 provider 名称。
_resolve_explicit_runtime() 处理显式 api_key/base_url 覆盖。
如有 credential pool，优先从 pool 取 runtime credential。
按 provider 类型进入对应分支：
- nous -> resolve_nous_runtime_credentials()
- openai-codex -> resolve_codex_runtime_credentials()
- copilot-acp -> resolve_external_process_provider_credentials()
- anthropic -> 走 Anthropic token 解析
- API-key provider -> resolve_api_key_provider_credentials()
- 其他 -> _resolve_openrouter_runtime()

3.3 `auth.py` 的职责

hermes_cli/auth.py 主要负责：

resolve_provider()：决定 provider 名称
resolve_codex_runtime_credentials()：读取/刷新 Codex token
resolve_nous_runtime_credentials()：刷新 Nous portal access token，并确保短期 inference key 可用
resolve_api_key_provider_credentials()：读取 API-key 类 provider 的密钥和 base_url
resolve_external_process_provider_credentials()：解析 copilot-acp 这类本地子进程 provider

关键位置：

hermes_cli/auth.py:790 resolve_provider()
hermes_cli/auth.py:1174 resolve_codex_runtime_credentials()
hermes_cli/auth.py:1683 resolve_nous_runtime_credentials()
hermes_cli/auth.py:2084 resolve_api_key_provider_credentials()
hermes_cli/auth.py:2122 resolve_external_process_provider_credentials()

3.4 运行时解析的输出如何进入 AIAgent

三个入口都会把 runtime dict 展开为 AIAgent(...) 参数：

api_key
base_url
provider
api_mode
command / args
credential_pool

随后 AIAgent.__init__() 决定使用哪类 client：

anthropic_messages -> Anthropic native client
codex_responses -> Responses API / raw codex path
其他 -> OpenAI-compatible client

4. AIAgent 初始化阶段

核心类位于 run_agent.py：

AIAgent 定义：run_agent.py:470
__init__()：run_agent.py:487
run_conversation()：run_agent.py:6801
chat()：run_agent.py:9170

4.1 初始化时完成的事情

AIAgent.__init__() 不是只做 client 构造，它会一次性初始化整套运行时状态：

保存 model / provider / api_mode / iteration budget。
基于 provider/base_url 判断实际 API 模式。
创建底层 LLM client。
调用 get_tool_definitions(...) 加载当前会话可用工具。
初始化 SessionDB 会话行（如果传入了 session_db）。
初始化 todo store、memory store、memory provider plugin。
初始化 context compressor。
计算 prompt caching 开关。
建立 _cached_system_prompt 缓存槽。
建立 session log 文件路径和 _session_messages 缓冲区。

4.2 初始化时和本题流程直接相关的状态

self.tools
- 来自 model_tools.get_tool_definitions()
self.valid_tool_names
- 当前会话真实可调用的工具名集合
self._cached_system_prompt
- 会话级稳定 system prompt 快照
self.context_compressor
- 长会话压缩器
self._session_db
- SQLite 会话存储
self._memory_store / self._memory_manager
- memory 注入和外部 memory provider
self._use_prompt_caching
- 是否启用 Anthropic/OpenRouter prompt cache 标记

5. Prompt Builder：系统提示词如何被组装

AIAgent._build_system_prompt() 是总装函数，位于：

run_agent.py:2609

真正的提示词拼装细节在：

agent/prompt_builder.py

5.1 组装顺序

_build_system_prompt() 的拼接顺序非常明确：

Agent identity
- 优先 SOUL.md
- 否则 DEFAULT_AGENT_IDENTITY
tool-aware guidance
- 仅当对应 tool 存在时才注入 memory/session_search/skills guidance
Nous subscription prompt
tool-use enforcement
- 按模型名和 config 决定是否注入
调用方传入的 system_message
内建 memory / user profile
外部 memory provider prompt block
skills system prompt
project context files
冻结时间戳 / session id / model / provider
platform hint

5.2 `prompt_builder.py` 提供的核心能力

5.2.1 上下文文件发现与注入

build_context_files_prompt() 负责扫描并注入项目上下文文件：

.hermes.md / HERMES.md
AGENTS.md
CLAUDE.md
.cursorrules / .cursor/rules/*.mdc
SOUL.md

关键特性：

有 prompt injection 扫描：_scan_context_content()
有截断：_truncate_content()
有优先级：只取一种 project context 类型

关键位置：

agent/prompt_builder.py:55 _scan_context_content()
agent/prompt_builder.py:807 load_soul_md()
agent/prompt_builder.py:920 build_context_files_prompt()

5.2.2 Skills 注入

build_skills_system_prompt() 会构建“可用技能索引”，供模型在系统提示词里看到。

它有两层缓存：

进程内 LRU cache
磁盘 snapshot：.skills_prompt_snapshot.json

注意：

这是“skills 索引构建缓存”，不是模型 provider 的 prefix cache。
它的目标是减少每次扫描 skills/ 目录的成本。

关键位置：

agent/prompt_builder.py:505 build_skills_system_prompt()

5.3 会话级 system prompt 稳定策略

Hermes 为了维持 prefix cache 命中，不会每轮都重建 system prompt。

策略是：

首轮调用时构建并缓存到 self._cached_system_prompt
持续会话时，如果有 SessionDB.system_prompt，优先复用库里的快照
只有在 context compression 后才调用 _invalidate_system_prompt() 并重建

相关位置：

run_agent.py:6953 首轮构建/复用 system prompt
run_agent.py:2929 _invalidate_system_prompt()

6. Prompt Caching：prefix cache 如何保持稳定

这一层涉及三种“缓存”，需要区分：

6.1 会话级 system prompt 缓存

由 AIAgent._cached_system_prompt 管理。

作用：

保证同一 session 内 system prompt 文本稳定
避免 memory/context/skills 每轮重建后发生微小漂移

6.2 Skills prompt 构建缓存

由 agent/prompt_builder.py 内部管理。

作用：

加速 skills 索引生成
不直接参与 provider prefix cache

6.3 Provider 级 prompt cache

真正的 provider prefix cache 逻辑在：

agent/prompt_caching.py

入口函数：

apply_anthropic_cache_control()：agent/prompt_caching.py:41

策略：

最多放 4 个 cache_control 断点
system prompt 1 个
最近 3 条非 system message 3 个

在 run_conversation() 里，API 消息构造完成后，如果当前 session 启用了 prompt caching，则调用：

run_agent.py:7239-7244

这就是当前仓库里“保持 prefix cache”的实际执行点。

7. `run_conversation()` 的同步 agent loop

AIAgent.run_conversation() 是核心同步循环，整体是：

准备消息
  ↓
拼 API payload
  ↓
调用模型
  ↓
有 tool_calls ?
  ├─ 否 -> 最终响应 -> 持久化 -> 返回
  └─ 是 -> 执行 tools -> tool result 写回 messages -> 下一轮

7.1 进入循环前的准备

主要步骤：

恢复 primary runtime（如果上轮触发了 fallback）。
清洗用户输入中的 surrogate 字符。
拷贝 conversation_history 到本轮 messages。
去掉旧 budget warning。
从历史中恢复 todo store。
追加本轮 user message。
复用或构建 _cached_system_prompt。
进行 preflight compression。
从 memory provider / plugin hook 获取额外上下文。

相关位置：

run_agent.py:6833-6938
run_agent.py:6953-6991
run_agent.py:6994-7050
run_agent.py:7064-7085

7.2 单轮 API 调用前，如何拼 payload

每次循环会把内部 messages 转成 api_messages：

对当前 user message 注入 external memory / plugin context
assistant message 里的 reasoning 映射成 provider 能理解的字段
移除内部字段：reasoning、finish_reason、_thinking_prefill
对 strict provider 清理 Codex 专用 tool fields
前置 system prompt
注入 prefill_messages
应用 Anthropic/OpenRouter prompt cache 标记
做 tool_call/tool_result 完整性修复
调用 _build_api_kwargs() 产出 provider-specific kwargs

关键位置：

run_agent.py:7169-7250
run_agent.py:5256 _build_api_kwargs()

7.3 `_build_api_kwargs()` 如何分发到不同 API 形态

_build_api_kwargs() 按 self.api_mode 分三路：

anthropic_messages
- 走 Anthropic adapter
codex_responses
- system prompt 变成 instructions
- history 变成 Responses input
- tools 转成 Responses schema
- 带 parallel_tool_calls=True
chat_completions
- 标准 OpenAI-compatible messages + tools
- 对 GPT-5 / Codex 会把第一条 system role 改写成 developer

关键位置：

run_agent.py:5256-5330
run_agent.py:5367-5379

7.4 模型返回后，先做什么

模型返回后会进入一系列规范化/防御逻辑：

处理 incomplete / empty / reasoning-only 情况
修正 hallucinated tool name
校验 tool args JSON
去重 tool calls
限制同轮 delegate_task 数量

然后才决定进入：

tool 分支
final response 分支

相关位置：

run_agent.py:8590-8775
run_agent.py:8845-8977

7.5 `chat()` 只是外层薄封装

AIAgent.chat() 只是：

调 run_conversation()
取出 result["final_response"]

位置：

run_agent.py:9170

8. Tool Dispatch：schema 收集、availability gating、function call 分发

8.1 tool schema 收集

model_tools.py 在 import 时就会执行 _discover_tools()：

import tools/*.py
每个 tool 模块通过 registry.register(...) 自注册
之后构建 TOOL_TO_TOOLSET_MAP 和 TOOLSET_REQUIREMENTS

位置：

model_tools.py:132 _discover_tools()
model_tools.py:170 调用 _discover_tools()

8.2 `get_tool_definitions()` 如何做 availability gating

get_tool_definitions(...) 负责给模型暴露“当前会话真实可见的 tools”。

步骤：

根据 enabled_toolsets / disabled_toolsets 解析 tool 名集合
调 registry.get_definitions(...)
用每个 tool 的 check_fn 做可用性过滤
对 execute_code 动态重建 schema，只列出当前 sandbox 中真实可用的 tools
对 browser_navigate 清理失效的 cross-tool 描述
把最终可用 tool 名写入 _last_resolved_tool_names

位置：

model_tools.py:234 get_tool_definitions()

8.3 模型发出 tool_calls 后的调用链

在 run_conversation() 中，如果 assistant_message.tool_calls 非空：

先校验 tool name 和 JSON 参数
生成 assistant message 并附加到 messages
调 _execute_tool_calls(...)

位置：

run_agent.py:8590-8775
run_agent.py:5948 _execute_tool_calls()

8.4 并行与串行执行策略

_execute_tool_calls() 会根据 _should_parallelize_tool_batch() 决定走：

_execute_tool_calls_sequential()
_execute_tool_calls_concurrent()

并行条件大致是：

多个 tool call
不包含 clarify
只包含并行安全工具
或 path-scoped tool 且目标路径不冲突

位置：

run_agent.py:262 _should_parallelize_tool_batch()
run_agent.py:5948 _execute_tool_calls()
run_agent.py:6045 _execute_tool_calls_concurrent()
run_agent.py:6261 _execute_tool_calls_sequential()

8.5 agent-level tool 与 registry-level tool 的分界

AIAgent._invoke_tool() 先拦截 agent 级工具：

todo
session_search
memory
clarify
delegate_task
memory provider tools

其他工具才走：

handle_function_call(...) in model_tools.py

位置：

run_agent.py:5971 _invoke_tool()
model_tools.py:459 handle_function_call()

8.6 `handle_function_call()` 做什么

handle_function_call() 是 registry 的同步分发入口：

coerce_tool_args() 按 JSON Schema 纠正参数类型
对 read/search loop 做计数重置
执行 plugin pre_tool_call hook
registry.dispatch(...)
执行 plugin post_tool_call hook
返回 JSON string

注意：

todo / memory / session_search / delegate_task 在这里会返回“必须由 agent loop 处理”的 stub，因为它们依赖 agent-level state。

位置：

model_tools.py:372 coerce_tool_args()
model_tools.py:459 handle_function_call()

9. Context Compression：长会话压缩如何接入主流程

核心类：

agent/context_compressor.py:53 ContextCompressor

9.1 初始化

AIAgent.__init__() 会创建 self.context_compressor，传入：

model
provider
base_url
api_key
context_length override
threshold / protect_last_n / summary_model 等 config

位置：

run_agent.py:1186

9.2 压缩触发点

当前实现里至少有三类触发：

Preflight compression
- 本轮 API 还没发出，粗估请求已经超过阈值
正常循环中的 post-tool compression
- 本轮 tool 执行后，根据真实 token 使用量判断
上下文错误恢复
- provider 返回 payload too large / context length exceeded 等错误时，进入压缩重试路径

本题主链里最核心的是前两种。

位置：

run_agent.py:6994 preflight compression
run_agent.py:8827 post-tool compression

9.3 `_compress_context()` 的动作

_compress_context() 不是只改 messages，它还会处理 session 边界。

主流程：

flush_memories() 先给模型一次机会把值得保留的信息写入 memory
调用 ContextCompressor.compress(messages, current_tokens=...)
追加 todo snapshot
_invalidate_system_prompt()
重建 system prompt
若启用 SessionDB：
- end_session(old_session_id, "compression")
- 创建新 session_id
- create_session(parent_session_id=old_session_id)
- 继承并自动编号 title
- update_system_prompt(new_session_id, new_system_prompt)
更新压缩后的 token 估算
重置 file read dedup cache

位置：

run_agent.py:5853 _compress_context()

9.4 `ContextCompressor.compress()` 的内部算法

真实算法不是“简单保留头尾 + 做摘要”，而是：

先裁剪老旧 tool result
保护头部消息
按 token budget 保护尾部消息
对中间消息做结构化摘要
修复 tool_call / tool_result 配对完整性

摘要模板包含：

Goal
Constraints & Preferences
Progress
Key Decisions
Relevant Files
Next Steps
Critical Context

位置：

agent/context_compressor.py:155 _prune_old_tool_results()
agent/context_compressor.py:253 _generate_summary()
agent/context_compressor.py:565 compress()

10. Session Storage：SQLite + FTS5 与 gateway session index 的分工

这里有两套相关但不重复的状态层。

10.1 `SessionDB`：结构化、可检索的长期存储

实现位于：

hermes_state.py

核心设计：

SQLite
WAL mode
sessions 表 + messages 表
messages_fts FTS5 虚表
支持 parent_session_id 链接 compression continuation

关键位置：

hermes_state.py:41 sessions 表
hermes_state.py:71 messages 表
hermes_state.py:93 FTS5 定义
hermes_state.py:115 SessionDB

主要接口：

create_session()
end_session()
update_system_prompt()
append_message()
get_messages_as_conversation()
search_messages()

10.2 `AIAgent` 如何写入 `SessionDB`

每次 turn 结束时调用：

_persist_session()

它会做两件事：

_save_session_log() 写 JSON session snapshot
_flush_messages_to_session_db() 把未刷新的消息增量写入 SQLite

_flush_messages_to_session_db() 用 _last_flushed_db_idx 避免重复写入。

位置：

run_agent.py:1869 _persist_session()
run_agent.py:1882 _flush_messages_to_session_db()

10.3 `SessionStore`：gateway 的会话路由与 transcript 兼容层

实现位于：

gateway/session.py

它负责：

根据 SessionSource 生成 session_key
管理 session reset policy
维护 SessionEntry
管理 transcript（SQLite + JSONL）
生成 gateway 用的 session context prompt

关键位置：

gateway/session.py:202 build_session_context_prompt()
gateway/session.py:692 get_or_create_session()
gateway/session.py:942 append_to_transcript()
gateway/session.py:970 rewrite_transcript()
gateway/session.py:1002 load_transcript()

10.4 `SessionDB` 与 `SessionStore` 的关系

可以把两者理解成：

SessionDB
- 面向 agent / search / 压缩 continuation
- 是结构化 SQLite 正式存储
SessionStore
- 面向 gateway 平台 session 生命周期
- 维护 session_key 与当前 session_id 的映射
- 同时保留 JSONL transcript 兼容层

也就是说：

AIAgent 直接写 SessionDB
gateway 通过 SessionStore 管理“当前聊天应该落在哪个 session_id 上”

11. Response Delivery：CLI、gateway、cron 三条出口

11.1 CLI display

CLI 的交付不是简单 print(final_response)，而是一套 callback + streaming UI：

_init_agent() 给 AIAgent 注入：
- tool_progress_callback
- tool_start_callback
- tool_complete_callback
- stream_delta_callback
- thinking_callback
- reasoning_callback
HermesCLI.chat() 在线程中执行 agent.run_conversation(...)
运行过程中：
- streaming token 通过 _stream_delta(...) 渲染
- reasoning 可单独显示
- tool progress 可实时显示
结束后：
- 若没走 streaming，则用 Rich Panel(...) 包裹最终响应
- 可选 TTS 播放

相关位置：

cli.py:2340-2378 注入 callbacks
cli.py:6481 调用 run_conversation()
cli.py:6621-6644 reasoning display
cli.py:6645-6678 最终 response panel

11.2 Gateway delivery

Gateway 的交付链分两段：

第一段：`_run_agent()` 负责生成 agent 结果

它会：

构造/复用 AIAgent
绑定 tool_progress_callback / step_callback / stream_delta_callback / status_callback
调 run_conversation()
处理 transcript 持久化
更新 SessionStore.last_prompt_tokens
返回最终 response

关键位置：

gateway/run.py:6647-6683
gateway/run.py:6856
gateway/run.py:2996-3078

第二段：平台 adapter 负责真正发送

Gateway 外层收到 _run_agent() 的返回值后，会：

在普通模式下调用 adapter.send(...)
在 streaming 模式下由 stream consumer 边生成边发送
如响应里包含 MEDIA: 或本地文件路径，调用 _deliver_media_from_response(...)
如需要自动语音回复，走 _send_voice_reply(...)

关键位置：

gateway/run.py:7273 queued message 场景下的 adapter.send(...)
gateway/run.py:3080-3098 already streamed 场景下的后处理
gateway/run.py:4287 _send_voice_reply()
gateway/run.py:4345 _deliver_media_from_response()

11.3 Cron delivery

cron 的结果交付分三步：

run_job() 返回 (success, output_doc, final_response, error)
save_job_output() 先把 markdown 文档落盘
如果需要对外发送，_deliver_result(job, content, adapters, loop) 再做平台投递

_deliver_result() 细节：

先 _resolve_delivery_target(job)
优先使用 gateway live adapter（支持 E2EE 等）
失败时 fallback 到 standalone _send_to_platform(...)
先抽取 MEDIA: 标签，附件作为原生文件发送

位置：

cron/scheduler.py:199 _deliver_result()
cron/scheduler.py:856-873 tick 内触发保存与投递

12. 一条完整调用链示例

下面用“gateway 收到一条普通文本消息”举例：

sequenceDiagram
    participant User
    participant Adapter
    participant Gateway as gateway/run.py
    participant Store as gateway/session.py
    participant Runtime as runtime_provider.py
    participant Agent as run_agent.py:AIAgent
    participant Prompt as agent/prompt_builder.py
    participant Tools as model_tools.py
    participant DB as hermes_state.py

    User->>Adapter: 发送消息
    Adapter->>Gateway: MessageEvent
    Gateway->>Store: get_or_create_session(source)
    Gateway->>Store: load_transcript(session_id)
    Gateway->>Runtime: resolve_runtime_provider()
    Gateway->>Agent: AIAgent(...)
    Agent->>Tools: get_tool_definitions(...)
    Agent->>DB: create_session(...) / update_system_prompt(...)
    Gateway->>Agent: run_conversation(message, history)
    Agent->>Prompt: _build_system_prompt()
    Prompt-->>Agent: system prompt
    Agent->>Agent: 同步 loop，调用模型
    alt 模型返回 tool_calls
        Agent->>Tools: handle_function_call(...) / agent-level tool
        Tools-->>Agent: tool result JSON
        Agent->>DB: append_message(...)
        Agent->>Agent: 下一轮 API 调用
    else 模型返回最终文本
        Agent->>DB: flush messages / token counts
    end
    Agent-->>Gateway: {final_response, messages, tokens...}
    Gateway->>Store: append_to_transcript(...) / update_session(...)
    Gateway->>Adapter: send(response)
    Adapter-->>User: 最终消息

13. 本系统里最重要的几个“稳定性约束”

13.1 system prompt 必须尽量稳定

这直接关系到：

Anthropic/OpenRouter prefix cache
多轮会话成本
gateway 复用 cached agent 的收益

因此：

gateway 的动态上下文放到 ephemeral_system_prompt
plugin context 放到 user message
只有 compression 后才主动重建 system prompt

13.2 tool_call / tool_result 配对必须完整

Hermes 在两个地方都做了防御：

API 调用前 _sanitize_api_messages()
compression 后 ContextCompressor._sanitize_tool_pairs()

否则 Anthropic / OpenAI / strict provider 都可能拒绝请求。

13.3 session persistence 不是“最后一次统一保存”，而是多层增量保存

当前实现同时维护：

JSON session snapshot
SQLite messages/session rows
gateway transcript JSONL 兼容层

目标是：即使中途中断、压缩、provider 异常，也尽量不丢会话。

14. 一句话总结

Hermes 的核心运行系统可以概括为：

入口层先通过 runtime_provider + auth 解析可执行 runtime，再由 AIAgent 初始化稳定的 tool surface、system prompt 和 context compressor；随后 run_conversation() 以同步 loop 反复执行“模型调用 -> tool dispatch -> tool result 回填”，并在整个过程中用 SessionDB/SessionStore 持久化状态，最后由 CLI、gateway 或 cron 各自的 display/delivery 层把结果送到用户。

Hermes Agent 06. 技能、记忆与上下文文件

Henry Lin — Mon, 13 Apr 2026 01:30:46 +0000

06. 技能、记忆与上下文文件

如果说工具决定 Hermes “能不能做”，那么技能、记忆和上下文文件决定它“会不会持续做对”。

本章目标

理解 skill、memory、context file 的边界
学会查找、安装和使用 skill
学会用 AGENTS.md 和 SOUL.md 提升稳定性
理解 prompt caching 与上下文注入的约束

适用读者

想长期高效使用 Hermes 的所有用户
想把重复流程沉淀下来的进阶用户
开发者

前置条件

已理解 CLI 和工具系统

核心概念

Skill 是“怎么做”

Skill 是按需加载的流程知识。它更像一份可执行的说明书，而不是一条记忆条目。

适合做成 skill 的内容：

固定工作流
多步骤操作规范
领域知识流程
常见排错套路

Memory 是“是什么”

Memory 适合保存事实信息，例如：

你的偏好
环境事实
常用项目位置
团队约定

经验法则很简单：

可复用流程放 skill
长期事实放 memory

Context File 是“默认注入的背景”

Hermes 会自动读取某些上下文文件，例如：

AGENTS.md
SOUL.md
.cursor/*

这些文件会直接影响每次会话的系统上下文，所以质量和长度都很重要。

操作步骤

查看和使用 skill

最常用的方式：

/skills
/skills search docker
/skills browse

技能安装后通常会直接变成 slash command，例如：

/plan 设计一个 REST API
/ascii-art Make a banner

CLI 外也可以：

hermes skills list
hermes skills install official/research/arxiv

自己创建 skill

用户自定义 skill 放在：

~/.hermes/skills/

典型结构：

~/.hermes/skills/my-category/my-skill/
└── SKILL.md

如果 skill 还需要参考文件、模板或脚本，也可以加 references/、templates/、scripts/。

使用 memory

Memory 用于跨会话保存信息。你可以直接要求 Hermes 记住某个事实，例如：

记住：我们的 CI 用 GitHub Actions，主工作流文件是 deploy.yml。

写好 `AGENTS.md`

对于代码项目，AGENTS.md 非常重要。它适合写：

架构约定
测试方式
代码规范
禁止事项
特定目录行为

它不是 README 的替代，而是“给 agent 的项目说明书”。

区分 `SOUL.md` 和 `AGENTS.md`

SOUL.md：定义 Hermes 的长期人格和表达倾向
AGENTS.md：定义当前项目或工作区的约束

一个偏“说话风格”，一个偏“做事规则”。

常见场景

场景 1：重复做同一种工作流

如果某个任务总要 5 步以上，而且你会重复做，优先考虑做成 skill，而不是每次重写 prompt。

场景 2：希望 Hermes 一直遵守项目约定

优先写 AGENTS.md，而不是每次聊天都重新说一遍。

场景 3：希望 Hermes 长期记住偏好

例如“回答尽量简洁”“默认用 pytest”“某仓库路径固定在某位置”，这些更适合进 memory。

常见问题与排错

为什么安装了 skill，当前会话却没看到

有些 skill 需要新会话才能稳定进入 prompt。必要时重开会话或 /reset。

为什么不建议把 `AGENTS.md` 写得特别长

因为它会被反复注入上下文，太长会拖慢会话、增加 token 消耗，并降低重点信息密度。

为什么 memory 改了但当前会话感觉没变

memory 是跨会话生效的长期上下文。很多情况下写入后要到下一个会话，系统提示里才会以稳定方式体现出来。

什么是 prompt cache 不该被打破

Hermes 很依赖稳定的系统提示前缀来命中缓存。频繁改系统提示、技能载入方式、上下文文件或模型，会降低缓存命中率，提高成本和延迟。

本章总结

工具解决“做事”，skill、memory 和 context file 解决“长期稳定地做对”。高质量的长期使用，离不开这三者的正确分工。

下一步建议

继续看 MCP 与扩展能力，学习如何把 Hermes 接到外部系统。