DEV Community: Henry Lin

用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 接到外部系统。

Hermes Agent 05. 工具与工具集

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

05. 工具与工具集

这一章解释 Hermes 为什么能“做事”，以及你该如何控制它能做哪些事。

本章目标

理解 tool 与 toolset 的关系
了解 Hermes 内置工具的大类能力
学会按会话或平台启停工具
学会区分 terminal、file、web、browser、execute_code、delegation 的适用场景

适用读者

所有认真使用 Hermes 的用户
需要控制安全边界和执行能力的部署者
开发者

前置条件

已理解 CLI 与配置系统

核心概念

Tool 是能力单位，Toolset 是开关单位

Hermes 内置工具注册在中央 registry 中，每个工具属于一个 toolset。你平时更常操作的是 toolset，而不是单个 tool。

常见 toolset 包括：

file
terminal
web
browser
skills
memory
code_execution
delegation
cronjob

工具是否可用，取决于三个层面

该工具或 toolset 是否启用
所需环境变量或依赖是否存在
当前平台是否允许该能力

这意味着“文档里有这个工具”不等于“你当前会话里一定能用”。

内置工具的常见边界

file：适合读写搜索文本文件
terminal：适合执行 shell 命令和后台进程
web：适合搜索网页和抽取正文
browser：适合真正的页面交互、表单、按钮、复杂界面
execute_code：适合 3 步以上的机械化串联操作
delegate_task：适合上下文隔离、并行研究、独立子任务

操作步骤

查看当前 toolset

CLI 内：

/toolsets
/tools list

CLI 外：

hermes tools

按会话启用指定 toolset

hermes chat --toolsets web,file,terminal
hermes chat --toolsets debugging
hermes chat --toolsets all

其中 debugging 这类 composite toolset 会展开成多个核心 toolset。

在当前会话中禁用某个工具

/tools disable browser
/tools enable browser

这对“想限制行为”或“怀疑某个工具在误导模型”时非常有用。

学会按任务选对能力层级

优先顺序通常是：

单次网页信息获取：web
复杂网页交互：browser
代码仓库文件理解：file
实际跑命令、构建、测试：terminal
批量顺序处理：execute_code
并行或新上下文分析：delegate_task

理解凭据型工具

有些工具并不是默认可用，例如：

web_search 需要 EXA_API_KEY、PARALLEL_API_KEY、FIRECRAWL_API_KEY 或 TAVILY_API_KEY
image_generate 需要 FAL_KEY
homeassistant 需要 HASS_TOKEN

如果环境变量没配好，工具会被排除或不可用。

常见场景

场景 1：代码分析

优先用 file 和 terminal。如果只是查文件结构或读取文本，没必要打开 browser。

场景 2：网页调研

优先用 web_search 和 web_extract。只有在需要登录、点按钮、处理复杂页面时再切换到 browser。

场景 3：十几个重复步骤的数据处理

优先用 execute_code，因为它能把工具调用和中间逻辑放进脚本里，避免主会话被中间结果淹没。

场景 4：三条研究线并行推进

优先用 delegate_task，让不同子代理分别处理不同问题，再回收摘要。

常见问题与排错

为什么我明明启用了 toolset，工具还是没出现

最常见原因是该工具的 check_fn 失败了，比如缺 API key、缺依赖、缺平台前提。

`browser` 和 `web` 为什么要分开

因为它们成本和能力完全不同。web 更快、更便宜、更适合信息获取；browser 更重，但能真实操作页面。

什么时候不该乱开全部工具

当你需要安全边界、成本控制或更可预测的行为时。工具越多，模型的选择空间越大，行为也越难控。

本章总结

Hermes 的执行力来自工具，但稳定性来自对工具的约束。真正高效的用法不是“什么都开”，而是为任务提供最小且足够的能力集合。

下一步建议

继续看技能、记忆与上下文文件，理解 Hermes 如何长期保持方法和偏好。

Hermes Agent 04. 配置体系与模型管理

Henry Lin — Mon, 13 Apr 2026 01:29:19 +0000

04. 配置体系与模型管理

Hermes 的强大很大程度上来自“入口统一，但后端可替换”。要把这一点用好，就必须掌握配置体系。

本章目标

理解 config.yaml 与 .env 的角色分工
学会选择 provider 和模型
理解 profile 的隔离价值
学会管理常见配置项

适用读者

已经完成首次运行的用户
想在不同场景下切换模型或部署多实例的用户
需要排查配置问题的开发者

前置条件

已完成安装并能进入 CLI

核心概念

`config.yaml` 与 `.env` 的分工

你可以简单记成：

config.yaml：结构化配置，控制行为和默认值
.env：密钥、令牌、URL、环境变量

常见位置：

~/.hermes/config.yaml
~/.hermes/.env

模型选择不是单一命令，而是一整套解析流程

Hermes 会综合这些信息来决定最终的模型与 provider：

当前会话显式指定
hermes model 保存的默认值
config.yaml
.env 中的 provider 相关变量

这也是为什么“明明我填了 API key，但还是走了别的 provider”这类问题会出现。

Profile 是隔离实例，不是主题标签

Profile 的作用是把配置、会话、技能、记忆、gateway 状态等全部隔离开。它适合：

工作 / 私人分离
不同 bot 实例分离
测试环境 / 生产环境分离

操作步骤

查看和设置当前模型

最直接的方式：

hermes model

会话中也可以：

/model
/model claude-sonnet-4
/model openrouter:anthropic/claude-sonnet-4
/model custom:qwen-2.5

管理环境变量

最基础的是 provider 凭据，例如：

OPENROUTER_API_KEY=...
OPENAI_API_KEY=...
OPENAI_BASE_URL=...
ANTHROPIC_API_KEY=...
GLM_API_KEY=...

除模型相关之外，还有 web、browser、Gateway、MCP、memory provider 等能力依赖的变量。

管理 config.yaml

常用方式：

hermes config
hermes config get skills.config
hermes config set some.key value

你不需要一开始手改所有配置。很多场景下，用 hermes setup、hermes model、hermes tools、hermes skills 这类命令比直接编辑 YAML 更稳。

使用 profile

先看当前有哪些 profile：

hermes profile list

创建和切换：

hermes profile create work --clone
hermes profile use work
hermes profile show work

如果想回到默认实例：

hermes profile use default

为不同场景建立不同默认值

一个很实用的模式是：

default：个人本地使用
work：工作环境，配置公司 MCP、企业平台和相关技能
bot：部署在服务器上的长期运行实例

这样能减少“在一个配置里堆所有用途”的混乱。

常见场景

场景 1：接多个 provider，按任务切换

你可以默认使用一个通用 provider，然后在特定会话用 /model 临时切换。Hermes 适合这种“一个工作流，多种模型”的使用方式。

场景 2：连接自建 OpenAI-compatible endpoint

常见做法是配置：

OPENAI_API_KEY=...
OPENAI_BASE_URL=http://your-endpoint/v1

然后在会话中选择：

/model custom:your-model-name

场景 3：把工作和私人使用完全隔离

最推荐用 profile，而不是频繁替换同一个 config.yaml。

常见问题与排错

为什么切换模型后表现变化很大

除了模型本身变化，还可能是：

provider 不同
base URL 不同
上下文缓存被打断
会话中的工具使用策略发生变化

为什么我改了配置却没有马上感知

有些改动影响新会话，有些改动影响当前会话，有些需要重新加载相关系统。比如 MCP 配置常常需要 /reload-mcp。

什么时候要小心 prompt cache

如果你频繁改系统提示、模型、上下文文件或技能加载方式，缓存命中会变差，成本和延迟都可能上升。不要把中途乱改配置当成常规工作流。

本章总结

Hermes 的配置核心可以归纳为四件事：provider、model、tooling、profile。理解它们之后，你就能把 Hermes 从“能用”推进到“适合自己的使用方式”。

下一步建议

继续看工具与工具集，理解 Hermes 的实际执行能力边界。

Hermes Agent 03. 首次运行与 CLI 基础

Henry Lin — Mon, 13 Apr 2026 01:28:47 +0000

03. 首次运行与 CLI 基础

Hermes 的 CLI 是最重要的主入口。很多高级能力最终都要回到 CLI 里调试和观察，所以这一章建议认真读。

本章目标

学会启动 Hermes CLI 并完成一次基本对话
掌握常用 slash commands
学会恢复会话、切换模型、观察工具行为
理解 CLI 与消息平台交互面的差异

适用读者

刚完成安装的新用户
希望把 Hermes 当作主工作台的重度用户

前置条件

已完成安装
至少有一个可用模型

核心概念

CLI 是最完整的交互面

CLI 默认拥有最完整的观察能力和调试体验，包括：

slash command 自动补全
工具执行进度显示
会话恢复
中断与重定向
本地图片粘贴
背景会话

有两类命令需要区分

shell 命令：例如 hermes status
会话内 slash commands：例如 /model、/usage、/compress

你可以把前者理解为“启动或管理 Hermes”，把后者理解为“正在和 Hermes 对话时控制当前会话”。

操作步骤

启动 CLI

最简单的方式就是：

hermes

进入后先尝试几条基础命令：

/help
/model
/usage
/toolsets

发出第一条有效请求

不要一开始就发“你好”，更推荐给 Hermes 一个能触发真实能力的任务，例如：

阅读当前目录结构并总结这个仓库的核心组成。

这样你能更快看到它是否会搜索文件、是否会调用工具、输出风格是否符合预期。

学会多行输入与中断

CLI 支持多行输入，适合粘贴代码、traceback 和长提示。任务跑偏时可以按 Ctrl+C 中断，再直接发新消息重定向。

掌握最常用的 slash commands

下面这些是高频中的高频：

/help：查看帮助
/model [model]：查看或切换模型
/new / /reset：新会话
/title [name]：给当前会话命名
/resume [name]：恢复之前命名过的会话
/usage：看 token、成本、上下文使用情况
/compress：手动压缩上下文
/verbose：切换工具输出显示级别
/background <prompt>：在后台启动独立任务
/tools [list|enable|disable]：查看或修改当前会话工具
/skills：搜索、查看、安装技能

学会会话恢复

CLI 外部可以用：

hermes -c
hermes -r "会话标题"

CLI 内部可以用：

/resume 会话标题

如果你经常做连续任务，会话命名是非常值得养成的习惯。

观察工具行为

执行复杂任务时，建议切换 /verbose，观察 Hermes 是否：

真正调用了你期望的工具
在错误的地方浪费步骤
因为权限、配置或工具缺失而被卡住

这比盲目重试更有效。

常见场景

场景 1：恢复昨天没做完的任务

hermes -r "auth-refactor"

或者进入 CLI 后：

/resume auth-refactor

场景 2：切换到更合适的模型

/model
/model openrouter:anthropic/claude-sonnet-4
/model zai:glm-5

复杂推理任务和简单格式化任务，往往不该强行用同一个模型。

场景 3：让长任务后台运行

/background 读取当前仓库，整理一份贡献指南并给出改进建议。

这样当前会话仍然可用，后台任务完成后会返回结果。

常见问题与排错

为什么我在 CLI 里看不到工具细节

先执行 /verbose，Hermes 会在不同显示级别之间切换。

为什么一个任务越聊越慢

通常是上下文变长了。先看 /usage，必要时执行 /compress。

为什么同样的命令在消息平台里没有

因为有些 slash commands 是 CLI-only，例如 /tools、/toolsets、/browser、/config、/skills 等。CLI 和 Gateway 共享一部分命令，但并不完全一致。

本章总结

CLI 是你理解 Hermes 行为、观察工具调用、调整模型与会话状态的最佳入口。只要你把 CLI 用顺，后面使用 Gateway、MCP、Cron 和开发扩展时都会轻松很多。

下一步建议

继续看配置体系与模型管理，理解 Hermes 的配置到底怎么组织。

Hermes Agent 02. 安装与初始化

Henry Lin — Sun, 12 Apr 2026 01:22:42 +0000

02. 安装与初始化

这一章解决最实际的问题：怎样把 Hermes Agent 安装好、初始化好，并确认它真的可用。

本章目标

完成 Hermes Agent 安装
理解 ~/.hermes 目录和关键配置文件
完成第一次 hermes setup
知道开发仓库与普通安装的差别

适用读者

新用户
准备在本机或服务器上部署 Hermes 的用户
准备修改仓库源码的开发者

前置条件

Linux、macOS 或 WSL2 环境
网络可访问安装依赖
至少准备一个模型 provider 的 API key 或 OAuth 登录方式

核心概念

Hermes 的默认家目录

默认情况下，Hermes 的配置和状态文件都在 ~/.hermes/ 下。最常见的文件是：

~/.hermes/config.yaml
~/.hermes/.env
~/.hermes/SOUL.md
~/.hermes/skills/
~/.hermes/sessions/

如果你使用 profile 或设置了 HERMES_HOME，这些路径会被隔离到对应目录。

安装和开发是两条路径

普通使用者：用官方安装脚本最快
仓库开发者：在仓库里建虚拟环境并安装 .[all,dev]

操作步骤

方式一：官方安装脚本

这是最简单的路径：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后，重新加载 shell：

source ~/.bashrc
# 或者
source ~/.zshrc

然后直接启动：

hermes

方式二：开发者从仓库安装

如果你要修改这个仓库本身，建议使用下面的流程：

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"

如果你就在本仓库里工作，请记住 AGENTS.md 给出的开发约束：运行 Python 相关命令前应先执行：

source venv/bin/activate

第一次执行 setup

安装后建议立刻运行：

hermes setup

你也可以分模块执行：

hermes setup model
hermes setup terminal
hermes setup gateway
hermes setup tools
hermes setup agent

hermes setup 主要帮助你完成这些事情：

选择 provider 和默认模型
配置 terminal backend
配置 gateway 平台
配置工具
初始化 agent 行为设置

准备 `.env`

Hermes 会从 ~/.hermes/.env 读取大量环境变量。最基础的是模型 provider：

OPENROUTER_API_KEY=your_key_here

其他能力如 web、browser、TTS、Gateway、MCP 往往也需要额外变量。后面在配置章节会集中展开。

验证安装是否成功

推荐依次跑下面几个命令：

hermes version
hermes doctor
hermes status
hermes

如果你能进入 CLI，并正常发出一条消息，说明基础安装已经通了。

常见场景

场景 1：在自己电脑上做本地助手

最常见组合是：

官方安装脚本
默认 ~/.hermes
只先配置一个 provider
暂时不启用 Gateway

场景 2：在服务器上长期运行

更常见的组合是：

安装后先配好 hermes gateway
设置 allowlist
配置 home channel
再逐步加 cron 和 MCP

场景 3：准备参与仓库开发

你应该优先用仓库安装方式，并且在运行测试、脚本和 Python 命令前先激活 venv。

常见问题与排错

Windows 能直接用吗

官方不支持原生 Windows。推荐使用 WSL2。

`hermes` 命令找不到

通常是安装后没有重新加载 shell，或者 PATH 没更新。先尝试重新打开终端，或者 source ~/.bashrc / source ~/.zshrc。

`hermes doctor` 报 provider 未配置

这通常不是安装失败，而是还没有可用的模型凭据。先配置 ~/.hermes/.env，或者运行 hermes model / hermes auth 完成认证。

我什么时候应该开始用 profile

如果你已经知道自己会同时维护“工作助手”“私人助手”“机器人实例”这类多个隔离环境，那么在一开始就用 profile 会比后面迁移更省事。

本章总结

安装 Hermes 并不难，真正重要的是把配置目录、初始化流程和 provider 凭据这三件事弄清楚。只要这一步稳住，后面 CLI、Gateway、工具和自动化就容易很多。

下一步建议

继续看首次运行与 CLI 基础，把第一次真实使用跑通。

DEV Community: Henry Lin

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

📊 每日市场简报

一、涨跌概览

二、成交额 TOP10

三、行业涨跌排名

四、主力资金动向

🔥 净流入 TOP5

💧 净流出 TOP5

五、特殊形态统计

🎯 连板个股明细

🌅 阳包阴个股（TOP20）

📈 连涨≥3天个股（TOP10）

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

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

学习目标

1.1 FreqAI 是什么

1.2 FreqAI 的工作循环

1.3 安装

1.4 最小可运行示例

1.4.1 策略代码精读

1.4.2 配置文件精读

1.5 运行命令

1.6 常见错误

1.7 验证情况

1.8 小结与下一章

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

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

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

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

为什么建议一开始就搭？

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

推荐的数据中台设计思路

1. 原始数据层（ODS）

2. 标准化层（DWD）

3. 因子层（DWS）

4. 策略层（ADS）

AI 和量化的关系

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

两条不同的路

总结

US Stock Screener

US Stock Screener

Access address

Features

Main Screener

Watchlist

Stock Research Page (/stock/:symbol)

Compare Page (/compare)

Pattern Stats Page (/pattern-stats)

美股日线选股器

美股日线选股器

功能介绍

主页选股器

观察列表

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

对比页（/compare）

形态统计页（/pattern-stats）

页面使用说明

主页选股器

实时数据功能

个股研究页

对比页

Hermes Agent 项目思维导图

Hermes Agent 项目思维导图

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

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

1. 总体分层

2. 三个入口如何进入 AIAgent

2.1 CLI 路径

2.2 Gateway 路径

2.3 Cron 路径

3. Provider / Runtime Resolution 调用链

3.1 入口函数

3.2 解析步骤

3.3 auth.py 的职责

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

4. AIAgent 初始化阶段

4.1 初始化时完成的事情

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

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

Compare Page (`/compare`)

Pattern Stats Page (`/pattern-stats`)

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

对比页（`/compare`）

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

3.3 `auth.py` 的职责

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

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

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

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

8.2 `get_tool_definitions()` 如何做 availability gating

8.6 `handle_function_call()` 做什么

9.3 `_compress_context()` 的动作

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

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

10.2 `AIAgent` 如何写入 `SessionDB`

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

10.4 `SessionDB` 与 `SessionStore` 的关系

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

写好 `AGENTS.md`

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

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