ai-exchange/docs/AI_ICT_Swing_Identification_Spec_v1.md

AI ICT Swing Identification 规格说明 v1

1. 文档目标

本文档定义 swing identification 模块的识别规则、强度分层、确认时机、参数化方式、边界情况、落库结构与验证要求，用于指导 swings 表和相关规则引擎实现。

目标：

• 统一 swing high / swing low 判定口径
• 建立 ST / IT / LT 强度层级
• 明确 provisional / confirmed 确认时机
• 支持按 timeframe 参数化
• 为 dealing range、liquidity、MSS/MSB 提供稳定上游结构点

适用范围：AI ICT 项目第一阶段 MVP。

关联文档：

1. AI_ICT_总体设计文档_v1.md
2. AI_ICT_PostgreSQL_Schema_v1.md
3. AI_ICT_MVP_规则规格书_v1.md
4. AI_ICT_开发路线图_v1.md
5. AI_ICT_执行检查清单_v1.md

---

2. 设计目标与边界

2.1 目标

swing identification 负责从标准化 candles 中提取结构高低点，作为后续 dealing range、liquidity pools、structure events 的基础输入。

输出必须支持：

• swing_high
• swing_low
• ST / IT / LT 强度分层
• provisional / confirmed 状态
• 多 timeframe 稳定重算

2.2 不负责的内容

第一版 swing 模块不负责：

• 直接计算 dealing range
• 直接判定 liquidity pool
• 直接判定 MSB / MSS
• 直接生成 trade signal

这些能力依赖 swing 结果，但由后续模块单独实现。

---

3. 核心概念

3.1 Swing High

swing_high 指某一根 candle 的高点，相对于其左右观察窗口内的其他 candles，构成局部显著高点。

3.2 Swing Low

swing_low 指某一根 candle 的低点，相对于其左右观察窗口内的其他 candles，构成局部显著低点。

3.3 Left / Right Bars

• left_bars：候选 pivot 左侧参与比较的 bars 数量
• right_bars：候选 pivot 右侧参与比较的 bars 数量

3.4 Provisional / Confirmed

• provisional：左侧条件满足，但右侧确认窗口尚未走完
• confirmed：左右侧窗口都满足条件，pivot 已确认

---

4. 输入与输出

4.1 输入

最小输入：

• instrument_id
• timeframe
• 标准化 candles
• 当前 swing 参数配置
• 待重算时间范围

candles 最低要求字段：

• ts_open
• high
• low
• close

4.2 输出

输出到 swings 表，遵循既有 schema：

• instrument_id
• timeframe
• kind
• strength
• price
• ts
• left_bars
• right_bars
• confirmed
• meta

---

5. Pivot 判定规则

5.1 基础判定窗口

给定某根 candle i，若要判断它是否为 pivot：

• 左侧比较范围：i - left_bars 到 i - 1
• 右侧比较范围：i + 1 到 i + right_bars

5.2 Swing High 判定

第一版推荐规则：

candle[i].high > max(left window highs)
and
candle[i].high >= max(right window highs)

即：

• 对左侧使用严格大于
• 对右侧使用大于等于

这样做的目的：

• 避免在左侧已有同价高点时重复生成 pivot
• 在右侧出现相同高点时，优先保留更早出现的候选点

5.3 Swing Low 判定

第一版推荐规则：

candle[i].low < min(left window lows)
and
candle[i].low <= min(right window lows)

即：

• 对左侧使用严格小于
• 对右侧使用小于等于

5.4 使用 wick 还是 close

第一版 swing 判定统一基于：

• high pivot 使用 high
• low pivot 使用 low

不使用 close 来定义 swing 本身。

原因：

• swing 的本质是结构极值点
• wick 对流动性与局部极值更敏感
• close 更适合后续 displacement / MSS 过滤，而不是 swing 原始识别

---

6. ST / IT / LT 强度层级

6.1 ST 定义

ST（Short-Term）是最基础的局部 pivot。

第一版默认：

• 先识别全部 ST swings
• 所有更高层级都建立在 ST 基础上

6.2 IT 定义

IT（Intermediate-Term）是对 ST 的再筛选。

推荐规则：

• 某个 ST swing_high 若高于其相邻的前后 ST swing_high，可升级为 IT swing_high
• 某个 ST swing_low 若低于其相邻的前后 ST swing_low，可升级为 IT swing_low

也就是：

• IT 不是直接从 candles 识别
• IT 从已确认的 ST 序列递归提取

6.3 LT 定义

LT（Long-Term）是对 IT 的再筛选。

推荐规则：

• 某个 IT swing_high 若高于其相邻的前后 IT swing_high，升级为 LT swing_high
• 某个 IT swing_low 若低于其相邻的前后 IT swing_low，升级为 LT swing_low

6.4 层级生成顺序

统一采用：

candles -> ST -> IT -> LT

不允许跳层直接从 candles 识别 LT。

6.5 层级意义

• ST：局部结构、短期波动、触发细节
• IT：中层结构、主工作区间候选
• LT：大级别结构、主 draw 与大范围边界参考

---

7. 确认时机

7.1 ST 确认

某个 ST pivot 只有在右侧 right_bars 数量的 candles 都已经存在后，才能标记 confirmed = true。

因此：

• 当前最新若干根 bars 附近的 pivot 只能是 provisional
• 不能提前把未走完右窗的点当成 confirmed

7.2 IT / LT 确认

IT / LT 的确认建立在下一级 swing 已确认的前提上。

即：

• 未确认的 ST 不能用于确认 IT
• 未确认的 IT 不能用于确认 LT

7.3 实时与历史差异

• 历史回算时，可一次性给出完整 confirmed 结果
• 实时增量时，最新区域必须允许 provisional 存在
• 后续新增 candles 到来后，允许 provisional 升级为 confirmed

---

8. Timeframe 参数化

8.1 参数化原则

不同 timeframe 的波动噪声不同，pivot 窗口必须参数化。

建议按 timeframe 单独配置：

• st_left_bars
• st_right_bars
• it_neighbor_span
• lt_neighbor_span
• min_price_distance（可选）
• min_bar_distance（可选）

8.2 第一版建议参数

以下为建议默认值，后续可调：

M1:  ST = 2/2
M5:  ST = 2/2
M15: ST = 3/3
H1:  ST = 3/3
H4:  ST = 4/4
D1:  ST = 5/5

IT / LT 默认可先使用“前后各 1 个同级 swing 比较”的方式生成。

8.3 噪声过滤参数

第一版可选增加两类过滤：

1. min_bar_distance

   • 两个同向 swing 之间至少相隔若干 bars

2. min_price_distance

   • 两个同向 swing 之间至少相隔最小价格距离或最小 ATR 比例

若未启用过滤，第一版仍可先按纯 pivot 规则运行。

---

9. 边界与异常情况

9.1 数据不足

若当前窗口不足以覆盖 left_bars + right_bars + 1：

• 不生成 confirmed swing
• 可选择不输出，或仅输出 provisional
• 第一版更建议不输出，避免过早污染结构

9.2 相等高点 / 相等低点

当多个相邻 candles 出现相同 high 或 low：

• 按 5.2 / 5.3 的不对称比较规则处理
• 若仍无法唯一确定，优先保留更早出现的 candle
• 同一价格平台不应生成多个完全重复的同级 swing

9.3 外包 K 线

若某一根 candle 同时包住左右多根 bars：

• 只要满足 pivot 条件，仍允许成为 swing
• 不因实体大小过大而自动剔除
• 但可在 meta 中记录 bar range 异常信息

9.4 极端噪声行情

若短时间内产生大量相邻 swings：

• 先按规则落地 ST
• 通过 IT / LT 递归筛选降低噪声
• 如仍过密，再启用 min_bar_distance / min_price_distance

9.5 上游 candle 修复

若 candles 历史数据被补齐、修正或重采样：

• 必须触发对应 timeframe swing 重算
• 不允许保留旧 swing 结果

9.6 跨 timeframe 独立性

不同 timeframe 的 swing 独立生成：

• M15 swing 不直接映射为 H1 swing
• 高 timeframe 必须基于该 timeframe 自己的 candles 计算

---

10. 存储模型

10.1 swings 字段映射

• instrument_id：所属交易品种
• timeframe：对应时间框架
• kind：swing_high / swing_low
• strength：ST / IT / LT
• price：pivot 价格；high 用 candle.high，low 用 candle.low
• ts：pivot candle 的时间戳，建议使用 ts_open
• left_bars：左窗参数
• right_bars：右窗参数
• confirmed：是否确认
• meta：额外说明

10.2 推荐 meta 内容

建议在 meta 中记录：

• source_timeframe
• pivot_index
• calc_version
• is_provisional
• neighbor_refs
• price_distance
• bar_distance
• rebuild_reason

10.3 唯一性建议

第一版建议逻辑唯一键为：

(instrument_id, timeframe, strength, kind, ts)

如暂不建数据库唯一约束，也应在写入层保证 upsert 口径一致。

10.4 更新策略

建议：

• 历史 confirmed 区域使用幂等 upsert
• 最新 provisional 区域允许被覆盖更新
• 若同一 ts 的 provisional 后续转 confirmed，应更新而不是插入新记录

---

11. 生成流程规范

11.1 历史全量重算

流程：

1. 读取指定 instrument + timeframe + date range
2. 生成 ST 候选并确认
3. 从 ST 提取 IT
4. 从 IT 提取 LT
5. 写入 swings
6. 对结果做去重与顺序检查

11.2 增量刷新

流程：

1. 只拉取受影响的最近窗口 candles
2. 重算尾部 ST
3. 级联刷新受影响的 IT / LT
4. upsert 到 swings

11.3 结果顺序要求

同一 instrument + timeframe + strength 下：

• swings 必须按时间可排序
• 不要求 high / low 严格交替，但若连续同向 swing 过多，应能被后续过滤发现

---

12. 验证与验收要求

12.1 功能验证

至少验证：

• 能按 timeframe 产出稳定 swing 列表
• 同一份 candles 重复计算结果一致
• 最新尾部区域能正确区分 provisional / confirmed
• ST / IT / LT 之间数量呈递减关系

12.2 数据验证

至少验证：

• swing_high 的价格等于对应 candle.high
• swing_low 的价格等于对应 candle.low
• confirmed 只在右侧窗口完成后出现
• 不同 timeframe 结果互不污染

12.3 人工抽查

至少抽查：

• 一个趋势行情样本
• 一个震荡行情样本
• 一个 equal highs / equal lows 附近样本
• 一个最新尾部存在 provisional 的样本

12.4 与下游一致性检查

至少确认：

• dealing range 可引用 swing 结果
• liquidity pools 可从 prior highs / lows 提取候选
• MSS / MSB 使用的参考 swing 与图表直觉一致

---

13. 推荐实现顺序

建议按以下顺序实现：

1. 完成 ST 基础 pivot 识别
2. 完成 confirmed / provisional 状态管理
3. 完成 ST 结果幂等落库
4. 完成 IT 递归提取
5. 完成 LT 递归提取
6. 再补噪声过滤参数

这样可以先保证下游有可用的基础结构点，再逐步增加层级复杂度。

---

14. 最终结论

swing identification 是全部结构分析的基础层。

第一版必须保证四件事：

1. pivot 口径明确
2. 确认时机严格
3. 多层级生成可重复
4. 写入结果可稳定重算

只有这四点成立后，dealing range、liquidity pools、MSS/MSB 才有稳定可靠的结构基础。