指标原语参考指南

指标原语(Indicator Primitives)用于从价格数据计算技术指标。这些组件接收OHLCV(开盘价、最高价、最低价、收盘价、成交量)数据，并输出时间序列指标值。

通用参数

大多数指标原语支持以下通用参数：

• column: 指定用于计算的价格列名(默认通常为'Close')
• period: 计算的回溯期(如移动平均的窗口大小)

注意：指标原语的价格列参数是 column。field 是 market_indicators 转换器（如 IdentityTransformer、MovingAverageTransformer）的参数名，两者不可混用。

可用指标原语

移动平均类

SMA (简单移动平均)

计算价格的简单移动平均。

{
  "id": "ma50",
  "type": "SMA",
  "params": {
    "period": 50,
    "column": "Close"
  }
}

参数:

• period: 移动平均的周期(默认: 20)
• column: 使用的价格列(默认: 'Close')

EMA (指数移动平均)

计算价格的指数移动平均，对近期价格赋予更高权重。

{
  "id": "ema20",
  "type": "EMA",
  "params": {
    "period": 20,
    "column": "Close"
  }
}

参数:

• period: 移动平均的周期(默认: 20)
• column: 使用的价格列(默认: 'Close')
• adjust: 是否使用调整系数(默认: false)

动量指标类

RSI (相对强弱指数)

计算RSI指标，用于测量价格变动的速度和变化。

{
  "id": "rsi14",
  "type": "RSI",
  "params": {
    "period": 14,
    "column": "Close"
  }
}

参数:

• period: RSI计算周期(默认: 14)
• column: 使用的价格列(默认: 'Close')

注意事项:

• RSI值范围在0-100之间
• 传统上，RSI > 70被视为超买，RSI < 30被视为超卖
• RSI计算使用Wilder's平滑方法

MACD (移动平均收敛发散)

计算MACD指标，显示两条移动平均线之间的关系。

{
  "id": "macd_indicator",
  "type": "MACD",
  "params": {
    "fast_period": 12,
    "slow_period": 26,
    "signal_period": 9,
    "column": "Close"
  }
}

参数:

• fast_period: 快线EMA周期(默认: 12)
• slow_period: 慢线EMA周期(默认: 26)
• signal_period: 信号线周期(默认: 9)
• column: 使用的价格列(默认: 'Close')

MACD 是多输出指标，引用时必须带输出后缀：macd_indicator.macd、macd_indicator.signal、macd_indicator.histogram。

波动率指标类

ATR (真实波幅)

计算Average True Range，衡量市场波动性。

{
  "id": "atr20",
  "type": "ATR",
  "params": {
    "period": 20
  }
}

参数:

• period: ATR计算周期(默认: 14)

BollingerBands (布林带)

计算布林带，包括中轨(SMA)、上轨和下轨。

{
  "id": "bbands",
  "type": "BollingerBands",
  "params": {
    "period": 20,
    "std_dev": 2,
    "column": "Close",
    "method": "sma"
  }
}

参数:

• period: 中轨SMA周期(默认: 20)
• std_dev: 标准差倍数(默认: 2.0)
• column: 使用的价格列(默认: 'Close')
• method: 中轨计算方法 sma / ema(默认: sma)

布林带是多输出指标，引用时必须带输出后缀：bbands.upper、bbands.middle、bbands.lower。

极值指标类

通道突破（breakout）语义注意：HighestValue / LowestValue 是通用滚动极值，窗口包含当前 bar（HighestValue(High, N)[t] = max(High[t-N+1 … t])）。直接用 Close > HighestValue(High, N) 并不是一个正确的"突破前 N 日高点"条件——当前 bar 的 High 通常不低于 Close，未排除当前 bar 时该条件几乎不可能成立。

要表达"突破已收盘的前 N 日最高/最低"，canonical 组合是先把极值信号延迟一期：HighestValue(High, N) → Lag(periods=1) → GreaterThan(Close, …)（见组合原语文档的突破模式）。专门的通道原语 DonchianChannel 把"排除当前 bar"变成显式参数（exclude_current，默认 true），比手写 Lag 组合更不易写错。

HighestValue (最高值)

计算过去N个周期内的最高价。窗口包含当前 bar。

{
  "id": "highest_60",
  "type": "HighestValue",
  "params": {
    "period": 60,
    "column": "High"
  }
}

参数:

• period: 查找最高值的周期(默认: 14)
• column: 使用的价格列(默认: 'Close')
• output_format: series / dataframe(默认: series)

LowestValue (最低值)

计算过去N个周期内的最低价。窗口包含当前 bar。

{
  "id": "lowest_60",
  "type": "LowestValue",
  "params": {
    "period": 60,
    "column": "Low"
  }
}

参数:

• period: 查找最低值的周期(默认: 14)
• column: 使用的价格列(默认: 'Close')
• output_format: series / dataframe(默认: series)

PercentFromHighest (距离最高点百分比)

计算当前价格距离过去N个周期最高价的百分比。

{
  "id": "drawdown",
  "type": "PercentFromHighest",
  "params": {
    "period": 252,
    "column": "Close"
  }
}

参数:

• period: 查找最高值的周期(默认: 14)
• column: 使用的价格列(默认: 'Close')
• output_format: series / dataframe(默认: series)

通道指标类

DonchianChannel (唐奇安通道)

一次性算出 High/Low 通道的四个值：upper（区间最高）、lower（区间最低）、middle（(upper+lower)/2）、width（upper−lower）。四个输出共享同一个索引和有效性掩码。

{
  "id": "entry_channel",
  "type": "DonchianChannel",
  "params": {
    "period": 20,
    "upper_column": "High",
    "lower_column": "Low",
    "exclude_current": true
  }
}

参数:

• period: 通道窗口的 bar 数，≥ 1(默认: 20)
• upper_column: 上轨使用的价格列(默认: 'High')
• lower_column: 下轨使用的价格列(默认: 'Low')
• exclude_current: 是否排除当前 bar(默认: true)

exclude_current 是通道语义的核心：

• true（默认，突破安全）：bar t 的通道值只用已收盘的 bar 计算——upper[t] = max(High[t-period … t-1])。这正是"突破前 20 日最高点"的正确口径。
• false：普通滚动区间，窗口包含 bar t 自身。

用一个例子看差别：过去 20 个已收盘 bar 的最高 High = 100，当前 bar High = 110、Close = 105。

	upper	判定 Close > upper
exclude_current: true	100	105 > 100 → 突破确认
false（含当前 bar）	110	105 > 110 → 不成立

Warm-up：period = N 且 exclude_current = true 时，需要完整 N 个已收盘 bar 才有第一个有效通道值；没有 partial-window 通道。窗口之前的 session 输出为无效（NaN 掩码），信号图上对应为 unavailable / empty。

多输出引用：DonchianChannel 是四输出指标，引用时必须带后缀——entry_channel.upper、entry_channel.lower、entry_channel.middle、entry_channel.width。不带后缀或写错后缀都会被校验拒绝。

突破组合（20 日高点入场 / 10 日低点出场）：

{
  "strategy_definition": {
    "trade_strategy": {
      "indicators": [
        {
          "id": "entry_channel",
          "type": "DonchianChannel",
          "params": { "period": 20, "upper_column": "High", "lower_column": "Low", "exclude_current": true }
        },
        {
          "id": "exit_channel",
          "type": "DonchianChannel",
          "params": { "period": 10, "upper_column": "High", "lower_column": "Low", "exclude_current": true }
        }
      ],
      "signals": [
        {
          "id": "entry",
          "type": "GreaterThan",
          "inputs": [
            { "column": "Close" },
            { "ref": "entry_channel.upper" }
          ]
        },
        {
          "id": "exit",
          "type": "LessThan",
          "inputs": [
            { "column": "Close" },
            { "ref": "exit_channel.lower" }
          ]
        }
      ],
      "outputs": {
        "buy_signal": "entry",
        "sell_signal": "exit"
      }
    },
    "capital_strategy": {
      "name": "PercentCapitalStrategy",
      "params": { "initial_capital": 100000, "percents": 100 }
    }
  }
}

20/10 与 55/20 是同一机制的不同窗口参数，不是"最优参数"。两个实例分别使用不同的 period，证明入场窗口与出场窗口相互独立。

持仓状态：突破条件与持仓状态是两个不同概念。通道 + 收盘确认产生 bar t 的决策，随后进入标准 Portfolio order lifecycle；实际成交发生在下一个可执行 session。GreaterThan / LessThan 是每日重新计算的 level condition，不是一次性的 crossover event——持仓状态由既有 BUY → HOLD → SELL → EMPTY 状态机维护，入场条件在后续 session 变为 false 并不会自动退出，也不需要 Crossover 去模拟持仓状态。

边界：本原语只表达通道突破的入场/出场水平，不是完整 Turtle 系统——没有 ATR/N 风险单位仓位、没有 pyramiding、没有日内 stop-entry 或按突破价成交。这些属于仓位管理与执行层，不是本原语的能力。

吊灯指标类

ChandelierExit (吊灯出场)

基于ATR的止损指标，输出基于最高价与 ATR 倍数的出场水平。

{
  "id": "ce_long",
  "type": "ChandelierExit",
  "params": {
    "period": 60,
    "multiplier": 4.0,
    "add_ma": false,
    "ma_period": 250
  }
}

参数:

• period: 回溯周期(默认: 60)
• multiplier: ATR乘数(默认: 4.0)
• add_ma: 是否同时输出一条长周期均线(默认: false)
• ma_period: add_ma=true 时的均线周期(默认: 250)

吊灯出场是出场参考水平，不是买卖信号本身；与价格比较（如 GreaterThan / LessThan）后才成为信号。它不提供方向参数——出场方向由你在信号图里写明的比较方向决定。

常量类

Constant (常量值)

生成固定值的时间序列，常用于阈值。

{
  "id": "upper_threshold",
  "type": "Constant",
  "params": {
    "value": 70
  }
}

参数:

• value: 常量值(必需)

基本面指标类

基本面指标用于读取已对齐的财务字段（由 fundamental_inputs 提供），主要用于判断“是否开仓”和“开多大仓位”，不用于全市场选股排名。

使用前提

• 在策略配置中开启 strategy_definition.fundamental_inputs
• 建议保持 point_in_time: true（只使用当时已经披露的数据）
• 当前语义仅面向个股（A股/美股个股），不建议直接用于 ETF

示例：

{
  "strategy_definition": {
    "fundamental_inputs": {
      "metrics": ["roe", "pe_ttm", "revenue_yoy", "operating_cashflow", "debt_ratio"],
      "frequency": "daily",
      "point_in_time": true,
      "max_staleness_days": 120
    }
  }
}

ROE (净资产收益率)

读取 ROE 列，常用于判断公司盈利能力（例如 roe > 10）。

{
  "id": "roe_metric",
  "type": "ROE"
}

参数:

• column: 列名(默认: roe)

PE_TTM (滚动市盈率)

读取 PE_TTM 列，常用于估值约束（例如 pe_ttm < 35）。

{
  "id": "pe_metric",
  "type": "PE_TTM"
}

参数:

• column: 列名(默认: pe_ttm)

注意事项:

• A股个股：通常可用于限制开仓条件或降低仓位
• 美股个股：当前 pe_ttm 历史点通常为 null/NaN（避免前视偏差），建议用于监控输出，不建议作为硬性开仓条件

RevenueYoY (营收同比)

读取营收同比列，常用于增长质量判断和景气告警。

{
  "id": "revenue_metric",
  "type": "RevenueYoY"
}

参数:

• column: 列名(默认: revenue_yoy)

OperatingCashflow (经营现金流)

读取经营现金流列，常用于利润质量和现金流安全垫判断。

{
  "id": "cashflow_metric",
  "type": "OperatingCashflow"
}

参数:

• column: 列名(默认: operating_cashflow)

DebtRatio (资产负债率)

读取资产负债率列，常用于判断杠杆风险和触发风险提醒。

{
  "id": "debt_metric",
  "type": "DebtRatio"
}

参数:

• column: 列名(默认: debt_ratio)

常见用法示例

1. 开仓条件检查（价格 + 基本面）

{
  "id": "risk_gate",
  "type": "And",
  "inputs": [
    {"ref": "trend_up"},
    {"ref": "roe_ok"},
    {"ref": "debt_ok"},
    {"ref": "revenue_ok"},
    {"ref": "cashflow_ok"}
  ]
}

2. 风险较高时降低仓位

{
  "id": "risk_alert_throttle",
  "type": "ConditionalWeight",
  "inputs": [{"ref": "risk_alert"}],
  "params": {
    "true_weight": 0.35,
    "false_weight": 1.0
  }
}

最佳实践

1. 参数选择:

   • 短期参数(如RSI 9)对市场变化反应更敏感，但可能产生更多假信号
   • 长期参数(如RSI 21)提供更平滑的信号，但可能反应较慢

2. 指标组合:

   • 单一指标通常不足以构建可靠策略
   • 考虑组合趋势、动量和波动率指标

3. 常见错误:

   • 过度拟合 - 不要仅基于历史数据优化参数
   • 忽略市场环境 - 某些指标在特定市场环境中表现更好

4. 数据质量:

   • 确保输入的OHLCV数据没有缺失或异常值
   • 考虑调整股票分割、股息等因素