Blankly / 指标与绩效口径
README 只举了三个指标，实际有 28 个
Blankly 的 README 在示例部分提到 RSI、MACD、Golden Cross 三种用法，给人的印象是内置指标不多。实际上对已安装版本做一次反射，blankly.indicators 会导出 28 个指标函数，blankly.metrics 提供 11 个绩效函数。这一页把清单按源码文件族整理出来（官方没有提供这份中文对照），并说明回测结果对象里的 12 个汇总字段与这些函数的区别。
blankly/indicators/ 下的源码文件划分：moving_averages.py、oscillators.py、statistics.py、indicators.py）。归类按文件归属，不代表有效性评价。Blankly 内置哪些指标？28 个函数按源码文件族分组
下面四张表覆盖 Blankly 全部 28 个可调用函数。这份清单不在官方 README 里，是本站对发行版执行反射后按源码文件归类的结果。
| 移动平均族（9 个） | 函数名 | 它解决什么 | 选用时的注意点 |
|---|---|---|---|
| 简单移动平均 | sma | 最基础的平滑，双均线策略的主力 | 对最新数据与最老数据等权，转折处滞后明显 |
| 指数移动平均 | ema | 更重视近期数据，转折更灵敏 | 需要指定跨度参数，跨度不同结论差异大 |
| 加权移动平均 | wma | 线性加权平滑 | 与 EMA 相比衰减速度不同，需按数据频率试算 |
| 成交量加权平均 | vwma | 把成交量纳入均价 | 依赖数据里的 volume 真实可用 |
| 零延迟指数平均 | zlema | 减小 EMA 的滞后 | 在震荡市里假信号可能增加 |
| 赫尔移动平均 | hma | 兼顾平滑与灵敏 | 数学结构较复杂，参数解释成本高 |
| 三角移动平均 | trima | 双重平滑，噪声更小 | 更平滑意味着信号更晚 |
| 考夫曼自适应平均 | kaufman_adaptive_ma | 按市场噪声自动调节平滑度 | 参数较多，需要谨慎设置 |
| 指数平滑异同 | macd | 快慢线差与信号线 | 三个周期参数共同决定行为，不要只调一个 |
| 振荡与动量族（7 个） | 函数名 | 它解决什么 | 选用时的注意点 |
|---|---|---|---|
| 相对强弱指标 | rsi | 超买超卖判断，官方模板默认使用 | 强趋势市场里可长期停留在极值区 |
| 随机指标 | stochastic_oscillator | 收盘价在区间中的相对位置 | 需要指定 K 与 D 的平滑参数 |
| 随机 RSI | stochastic_rsi | 对 RSI 再做一次区间归一 | 叠加两层平滑，滞后更大 |
| 阿隆振荡 | aroon_oscillator | 判断趋势成立还是盘整 | 参数影响趋势判定长度 |
| 钱德动量振荡 | chande_momentum_oscillator | 把上涨与下跌幅度合并成一个动量读数 | 与 RSI 类似但算法不同，不要混用结论 |
| 绝对价格振荡 | absolute_price_oscillator | 快慢均线之差 | 绝对值随价格水平变化，跨标的比较需谨慎 |
| 百分比价格振荡 | percentage_price_oscillator | 把上一项转成百分比 | 跨标的比较时通常比 APO 更合适 |
| 统计族（6 个） | 函数名 | 它解决什么 | 选用时的注意点 |
|---|---|---|---|
| 滚动标准差 | stddev_period | 波动幅度度量 | 受极值影响，注意异常值处理 |
| 滚动方差 | var_period | 标准差的平方 | 量纲与标准差不同，报表里要写清单位 |
| 滚动标准误 | stderr_period | 均值估计的不确定性 | 与标准差常被混用，含义不同 |
| 滚动最小值 | min_period | 区间低点 | 常用于止损位参考 |
| 滚动最大值 | max_period | 区间高点 | 常用于突破型策略 |
| 滚动求和 | sum_period | 区间累计（如区间成交额） | 与均值指标搭配使用时注意周期一致 |
| 覆盖与波动族（6 个） | 函数名 | 它解决什么 | 选用时的注意点 |
|---|---|---|---|
| 布林带 | bbands | 均线加减若干倍标准差形成的通道 | 带宽参数决定敏感度；通道收窄常被解读为变盘前兆（属经验判断） |
| 真实波幅 | true_range | 把跳空纳入的单期波动 | 是 ATR 的输入，通常不单独做信号 |
| 平均真实波幅 | average_true_range | 平滑后的波动幅度 | 常用于按波动调整仓位大小 |
| 威廉指标 | willr | 与随机指标同源的反向读数 | 取值方向与直觉相反，读数前先确认符号约定 |
| 累积派发 | wad | 结合价格与成交量判断资金累积/派发方向 | 依赖成交量质量；缺失或占位数据会让它失真 |
| 威尔斯平滑 | wilders | 威尔斯式平滑（RSI、ATR 的内部算法） | 通常作为其它指标的组成部分使用 |
blankly.metrics 有哪 11 个函数？
Blankly 的这些函数是「你可以直接对一条收益或权益序列调用的工具」，与回测结果对象里的汇总字段不是同一批东西，用法也不同。
| 函数 | 含义 | 典型用途 | 注意点 |
|---|---|---|---|
sharpe | 夏普比率 | 风险调整后收益的横向比较 | 依赖无风险利率与年化口径，跨工具比较前先统一 |
sortino | 索提诺比率 | 只惩罚下行波动的变体 | 与夏普不可直接互换解读 |
calmar | 卡玛比率 | 年化收益与最大回撤的比值 | 回撤口径不同会导致结果差异 |
cagr | 复合年化增长率 | 把区间收益折算为年化 | 区间长度过短时年化会失真 |
cum_returns | 累计收益 | 区间总收益率 | 是绝对收益，不含对照 |
volatility | 波动率 | 风险度量基准 | 取决于采样频率 |
variance | 方差 | 波动率的平方 | 单位与标准差不同 |
beta | 贝塔 | 相对基准的系统性风险敞口 | 必须提供基准序列才有意义 |
var | 在险价值 | 给定置信水平下的潜在损失估计 | 对尾部假设敏感 |
cvar | 条件在险价值 | 超出 VaR 之后的平均损失 | 比 VaR 更关注尾部，但样本不足时不稳定 |
max_drawdown | 最大回撤 | 峰值到谷底的最大跌幅 | 只是单个数字，看不出发生时间 |
回测结束后，结果对象里到底有什么
下表是本站对真实回测结果执行字段枚举得到的清单。它明确了「框架帮你算了什么」与「你必须自己算什么」的分界。
| 字段 | 显示名 | 类型 | 说明 |
|---|---|---|---|
calmar | Calmar Ratio | 数值 | 卡玛比率 |
cagr | Compound Annual Growth Rate (%) | 数值（百分比） | 年化增长率 |
cavr | Conditional Value-at-Risk | 数值 | 条件在险价值；键名是 cavr |
cum_returns | Cumulative Returns (%) | 数值（百分比） | 累计收益 |
max_drawdown | Max Drawdown (%) | 数值（百分比） | 最大回撤 |
resampled_time | Resampled Time | 数值（秒） | 账户价值重采样周期，实测日线为 86400.0 |
risk_free_rate | Risk Free Return Rate | 数值 | 本次计算所用的无风险利率，默认 0.0 |
sharpe | Sharpe Ratio | 数值 | 夏普比率 |
sortino | Sortino Ratio | 数值 | 索提诺比率 |
value_at_risk | Value-at-Risk | 数值 | 在险价值 |
variance | Variance (%) | 数值（百分比） | 方差 |
volatility | Volatility | 数值 | 波动率 |
场景 → 指标 → 理由：怎么挑
指标不是越多越好。下表按你要回答的问题组织，每一行给出一条可执行的取舍理由。
| 你的问题 | 优先考虑的指标 | 理由 | 需要避开的做法 |
|---|---|---|---|
| 判断趋势方向 | sma / ema / macd / aroon_oscillator | 都是对方向敏感的平滑类工具，冗余度低 | 同时叠加五种均线，信号互相冲突且无法归因 |
| 判断超买超卖 | rsi / stochastic_oscillator / willr | 三者都在 0-100 或等价区间内，便于设阈值 | 在强趋势市里照搬固定阈值 |
| 度量波动幅度 | average_true_range / bbands / stddev_period | ATR 可作仓位缩放，布林带可作通道，标准差是通用底料 | 把不同采样频率算出的波动率直接比较 |
| 做横截面比较 | percentage_price_oscillator / 收益率序列 | 百分比形式不受价格水平影响 | 用绝对价差类指标横向排序 |
| 做成交量相关判断 | vwma / wad | 把量价一起纳入 | 在成交量列是占位数据时使用它们 |
| 评估回撤风险 | max_drawdown 加自算回撤序列 | 汇总值看不出时间分布 | 只看最大回撤数值就下结论 |
| 横向比较不同策略 | 统一口径后的 sharpe / sortino / calmar | 三者互补：波动、下行、回撤 | 在不同无风险利率与采样频率下比较 |
哪六种指标误用会导致错误结论？
Blankly 的内置指标本身没有错，错的是口径和上下文。下面每一条都指出「错在哪、怎么发现」。
| 误用 | 会得出什么错误结论 | 怎么发现 | 正确做法 |
|---|---|---|---|
| 用百分比类指标做跨标的金额比较 | 误以为某标的「收益更高」 | 看指标单位是否为百分比 | 跨标的比较统一用百分比形式；金额分析另算 |
| 用不同采样频率算出的波动率互相比较 | 误判哪个策略更稳 | 检查 resampled_time 是否一致 | 统一重采样频率后再比较 |
把 beta 用在没有基准的序列上 | 得到一个没有意义的数值 | 检查是否提供了基准序列 | 先设基准（结果字段里 benchmark_symbol 默认为空） |
把 cavr 写成 cvar 取值 | 直接 KeyError，或误以为框架不支持 | 打印 metrics.keys() 确认键名 | 使用源码里的真实键名 |
| 只看最大回撤数值 | 误以为风险可控，实际回撤集中在某个未察觉的阶段 | 把回撤序列画出来 | 用 get_returns() 自算回撤序列并对照时间轴 |
| 用胜率作为主要评价标准 | 少量交易的高胜率被当成策略优势 | 同时看交易笔数与平均盈亏 | 胜率必须与交易笔数、盈亏比、样本外结果一起看 |
关于指标与绩效口径的高频问题
清单来自对发行版 1.18.25b0 的反射结果；函数签名与算法细节以官方源码为准。
为什么官方 README 只写三个指标，实际有 28 个？
README 的作用是「让人快速理解能做什么」，所以只举了 RSI、MACD、Golden Cross 三个最常见例子。指标模块本身是把一个开源技术指标库封装进来的，所以数量远多于示例。这也意味着这些指标的实现细节与上游库一致，遇到精度或边界问题时，应当去查上游实现的说明。
这些指标需要联网或密钥吗？
不需要。指标模块是对你传入的序列做纯计算，与交易所无关。你可以把它当成一个独立的工具集使用——只要包能正常导入（需要先解决 numpy 依赖问题），就能对任意序列调用这些函数。
回测结果是字典吗？我 print 出来是对象地址。
不是字典。回测返回的是一个结果对象，直接 print 只会显示对象地址与内存位置。要拿数据有三种方式：读 .metrics 属性、调 .get_metrics() 方法、或调 .to_dict() 转成字典。实测中 dict(result) 会抛 TypeError: 'BacktestResult' object is not iterable。
框架为什么不提供胜率？
本站只能陈述事实：12 个汇总字段里没有交易次数与胜率。至于原因，不排除是因为「胜率」的定义依赖口径（是否含手续费、是否只算已平仓、多空是否分开统计），不同使用者差异太大，因此留给自己算。实务上这是好事——逼你显式声明口径。
想加一个框架里没有的指标，怎么做？
两条路。第一，在策略回调里用 pandas 或 numpy 自己算，把结果存进 state.variables，这是最直接的方式。第二，如果这个指标要在多处复用，就写成独立函数放在你自己的模块里，再在回调中调用。要注意的是：自定义指标不会享有框架对内置指标的滞后保护，未来函数风险由你自行保证。
绩效函数的输入是收益率还是账户价值？
不同函数的期望输入不同，本站不做统一断言。稳妥做法是调用前先确认函数签名与它期望的序列形态（例如 cagr 与 max_drawdown 的输入通常是账户价值序列，sharpe 类通常需要收益率序列）。拿一条已知结论的简单序列（例如单调上涨）自测一遍，就能确认单位与方向是否正确。