invest-a-gap-scan 跳空缺口扫描

工具约束说明：frontmatter 的 allowed-tools 是 Claude Code 约定；在 DSH 等不读取该字段的 harness 下不生效，实际可用工具由平台自身沙箱控制。本技能主体操作为本地数据采集与计算（Bash/Python 引擎）；部分维度经 WebSearch/WebFetch 补充检索

概述

扫描沪深300 + 中证A500 + 科创50 成分股并集（去重后约 450~500 只，随指数调仓变动），找出同时满足：

1. 近 60 个交易日内有向上跳空缺口（low[i] > high[i-1]，幅度 >= 1%）
2. 自缺口日起，在可计算 MA60 的 bar 上收盘未跌破 MA60（close[t] >= MA60[t]；含 epsilon 容差与有效值门槛，见「MA60 计算」）
3. 缺口形成后最低价从未回补至上沿及以下（min(low[gap_idx+1:]) > gap_high）

产出性质：观察清单。 命中 = 「这几只标的存在未回补的向上缺口且未跌破 MA60」这一规则化形态检出结果， 不是交易信号、不是预测、不是推荐排序，也不含任何方向性判断或基本面/事件核验。 形态可在任何时点被回补；请把它当作进一步研究的入口，而不是结论。禁买卖/仓位建议。

缺口定义

  gap_high  ─────── low[i]         (缺口上沿 = 跳空日最低价)
                      |
                   gap_pct = low[i] / high[i-1] - 1
                      |
  gap_low   ─────── high[i-1]      (缺口下沿 = 前日最高价)

• 未回补: 缺口形成后所有交易日的最低价均 > 缺口上沿
• 跨停牌: 缺口前一交易日为停牌日 -> 单独列出，不参与常规排序

筛选漏斗

池规模与分布随指数调仓与市况变动，不是固定值（历史文档曾写死「478 只」与一组固定桶值，与实测不符）。2026-09-21 实测（出处 reports/gap-scan/2026-09-21-06-40-36.md）呈现如下分布，且闭合：

池 480 只  ─ 排除（扫描前剔除）
 |--  ~5 (1.0%)   低流动性        -- 当前尾部 20 日均额 < 1 亿
 |--   0          上市不足 / 数据缺失 / ST / 退市 / 获取失败
 |
 |  进入缺口判定 475 只  ─ 未命中（扫描后无合格缺口）
 |-- 266 (55.4%)  无缺口          -- 60 日内无 low[i] > high[i-1]
 |-- 110 (22.9%)  低于阈值        -- 有缺口但幅度 < 1%
 |--  78 (16.2%)  MA60破          -- 缺口后收盘跌破 MA60，或 MA60 覆盖度不足
 |--  11 (2.3%)   缺口回补        -- 最低价回补至上沿
 |--   1 (0.2%)   最新bar待收盘确认 -- 最新 bar 尚未完成，两边结论都不下
 |--   0          量比低          -- 仅在设置量比门槛时可能出现
 |
 |  命中  9 (1.9%)                 -- 观察清单条目（非交易信号）
 |--   0          跨停牌          -- 缺口前一交易日为停牌日，单列不参与排序

闭合恒等式（可用于自查报告是否漏桶；零值桶不显示，须由该式推得）：

池规模 = 排除（扫描前） + 未命中（扫描后） + 命中 + 跨停牌
480    = 5              + 466（266+110+78+11+1） + 9    + 0

运行

基本用法

cd "${INVEST_SKILLS_ROOT:-.}" && uv run python skills/invest-a-gap-scan/scripts/scan.py

参数表

示例

# 提高缺口阈值
cd "${INVEST_SKILLS_ROOT:-.}" && uv run python skills/invest-a-gap-scan/scripts/scan.py --gap-min-pct 2.0

# 要求放量缺口（门槛同样适用于 <1.0 的取值）
cd "${INVEST_SKILLS_ROOT:-.}" && uv run python skills/invest-a-gap-scan/scripts/scan.py --gap-min-vol-ratio 1.5

# 强制 baostock（无 Tushare token；与停牌检测是否跳过无关，后者取决于交易日历是否可得）
cd "${INVEST_SKILLS_ROOT:-.}" && uv run python skills/invest-a-gap-scan/scripts/scan.py --source baostock

# 调试: 只扫前 30 只
cd "${INVEST_SKILLS_ROOT:-.}" && uv run python skills/invest-a-gap-scan/scripts/scan.py --universe-limit 30

# JSON 输出 (供脚本消费)
cd "${INVEST_SKILLS_ROOT:-.}" && uv run python skills/invest-a-gap-scan/scripts/scan.py --json

# 全量刷新
cd "${INVEST_SKILLS_ROOT:-.}" && uv run python skills/invest-a-gap-scan/scripts/scan.py --no-cache

算法详解

容忍规则 (Tolerance Rule)

缺口按从新到旧排序，遇到第一个满足全部条件的即命中。判定顺序与各分支的桶归属由下表固定（顺序会影响未命中桶的归属，不得改动复现步骤）：

for gap in qualified_gaps (newest first):
    if MA60 覆盖度不足 或 在可计算 MA60 的 bar 上收盘跌破 MA60:
        -> 继续检查更老的缺口          # 不置位；全部失败则归「MA60破」
    if 该 bar 是数据中最新的一根 bar 且尚未完成（未收盘）:
        -> 标「最新bar待收盘确认」并继续更老的缺口
           （既不下「未回补」也不下「已回补」结论）
    if gap 已被回补:
        -> 继续检查更老的缺口
    if 量比 < 门槛 (门槛生效时):
        -> 继续检查更老的缺口
    -> 命中（此外不区分跨停牌与否，跨停牌在命中后单列）

不回退到已回补的缺口。这意味着：如果最新缺口已回补但更老的缺口未回补且 MA60 完好，会命中老缺口。

未命中桶的归属优先级（决定报告里落在哪个桶）：

1. 没有任何合格缺口满足 MA60 → MA60破
2. 没有任何缺口被确认为未回补，且存在「最新bar待收盘确认」→ 最新bar待收盘确认（终结桶：一旦有任何缺口命中，本条不成立）
3. 没有任何缺口被确认为未回补 → 缺口回补
4. 有未回补缺口但量比不达标 → 量比低
5. 其余 → 缺口回补

扫描时点与数据截止（after_close）

最新一根 bar 的缺口没有后续数据，能否判定未回补取决于该 bar 是否已完成，而不是运行时的墙钟：

按墙钟（旧实现 hour >= 15）判定会丢掉可判定的命中：实测同一份数据（最新 bar = 周五，已完成）， 周六 23:46 扫描得 10 命中，周一 06:40 扫描只得 9 命中 + 1 条「最新bar待收盘确认」。 判定为逐股进行（停牌股的最新 bar 更早，同样视为已完成）；强制覆盖只存在于库接口 （scan_all(after_close=...)，供测试重放），CLI 不提供该开关。

数据截止与「最新收盘」：报告首部给出数据截止日（全池最新 bar 日期），命中表与逐股简析 逐行给出「数据日」（停牌、数据落后或部分缓存命中的标的更早）。价格一律是该行数据日的收盘价， 不是实时价；K 线缓存 TTL 为 3 天，命中缓存时数据可能滞后，报告同时披露缓存命中数、实际新拉数、 拉取失败数与未定稿重拉数、缓存条目年龄（见「缓存」）。

缓存复用前提：只有当缓存里最后一根 bar 已定稿（缓存写入时刻晚于该 bar 自身交易日的收盘）时才复用； 盘中写入的快照会隔日失效并重拉——否则会拿未走完的低点去断言「缺口未回补」（见「缓存」的定稿判据）。

跨停牌缺口

停牌检测基于交易日历 + 日线数据对比：某个交易日在 trade_cal 中存在但该标的不在 daily_by_date 中 -> 标记为停牌。缺口前一交易日为停牌日 -> 归入 across_suspension_hits，不参与常规排序。

注意: 无 Tushare token 时使用自然日估算交易日历（Mon-Fri），此时跳过停牌检测以避免假期误判（报告的「交易日历」行会标注停牌检测已跳过）。

MA60 计算

使用 invest-a-stock 的 lib.technical.sma（60 日简单移动平均）。前 59 个位置 MA60 为 None。判定规则：

• 只对可计算 MA60 的 bar 判定：ma60[t] is None 的位置跳过；有效值门槛要求缺口日起至少有 max(25% × bar 数, 3) 根 bar 有 MA60 值，否则不判 MA60，直接归入「MA60破」
• epsilon 容差：math.isclose(close, ma60, rel_tol=1e-5, abs_tol=0.01)，用于吸收前复权换算的浮点尾差（绝对带 0.01 元，低价股上近似 0.2%）；真实跌破幅度远大于此，不会被容差掩盖
• NaN close 触发 MA60 失败（利用 not (NaN >= MA60) 恒为 True 的特性）

覆盖度会随报告输出（逐股简析的「MA60 判定覆盖: valid/total」）——短历史标的的有效 bar 少，命中的强度含义弱于长历史标的。复算示例：

n=74 根、缺口 idx=14：total=60，valid=15（MA60 自 bar 59 起有效），need=max(ceil(60×0.25),3)=15 → 通过
n=64 根、缺口 idx=10：total=54，valid=5，need=max(ceil(54×0.25),3)=14 → 5 < 14 → 归入「MA60破」

即 K 线少于约 74 根的标的几乎不可能通过 MA60 判定；这类标的不会静默消失，而是明确落在「MA60破」桶。

前复权 (QFQ)

• Tushare 路径: 原始价格 x adj_factor / latest_adj_factor -> 以最新日为基准的前复权价格
• Baostock 路径: adjustflag="2" 直接返回前复权价格，无需额外计算

两种路径的 QFQ 算法存在细微差异，因此缓存按数据源隔离（{kline}/{source}/{ts_code}.pkl）。

数据流

1. build_universe()        指数成分股并集 -> 去重 + ST/退市过滤 -> 约 480 只（随调仓变动）
       |
2. create_source("auto")   有 Token 且可用 -> TushareBulkSource (按日批量)
                          否则 -> BaostockSource  (逐股查询)
                          （实际使用源与尝试源写入报告；降级会显式标注）
       |
3. _fetch_trade_cal()      Tushare trade_cal API -> 真实交易日历
                           失败 -> 自然日估算 (Mon-Fri, 跳过停牌检测)
       |
4. kline_cache.load()      命中 -> 跳过拉取（TTL 3 天，报告披露命中数与条目年龄）
                          未命中 -> fetch_daily_batch + build_stock_kline + cache.save
       |
5. detect_suspensions()    对比 trade_cal vs daily_by_date -> 停牌日期列表
       |
6. scan_all()              逐股: 流动性排除 -> 找缺口 -> 容忍规则 -> 命中/排除/未命中
                          逐股按数据日期判定最新 bar 是否已完成（见「扫描时点」）
       |
7. format_brief()          命中表 (缺口幅度降序) + 排除/未命中统计
   format_markdown_report() 详文档 -> reports/gap-scan/{YYYY-MM-DD-HH-MM-SS}.md

详文档路径带时分秒：同日二次运行不覆盖历史（目录固定为 gap-scan，因为汇总扫描无单一标的）。

数据量

性能

输出

stdout 摘要

========================================================================
  invest-a-gap-scan vX.Y.Z -- 跳空缺口扫描
========================================================================

  **风险声明（非投资建议）**：本报告由规则化扫描自动生成 ...（首尾各一条，节选）

池构成: 沪深300(300) + 中证A500(500) + 科创50(50) -> 去重 480 只（随指数调仓变动）
数据截止: 20260918（全池最新 bar，不含今日；逐股数据日见「数据日」列）
数据源: Tushare Pro (前复权自算) | 尝试源: tushare
K线缓存: 缓存命中 480 / 新拉 0（TTL 3.0 天，缓存条目年龄 0.4~2.9h）
覆盖率: 100.0% (480/480 有K线) | 命中: 10 只 | 跨停牌: 0 只
参数: 缺口≥1.0% | 回溯60日 | MA60（含容差与有效值门槛） | 日均额≥1.00亿（当前20日均额）

排除（扫描前）: 低流动性 5
未命中（扫描后）: 无缺口 266 | 低于阈值 110 | MA60破 78 | 缺口回补 11

命中（观察清单，非交易信号、非预测、非推荐排序）:
| 代码 | 名称 | 指数 | 板块 | 缺口日 | 缺口% | 缺口区间 | 数据日 | 最新收盘 | MA60 | MA60% | 距上沿% | 量比 | 量比分母 | 当前20日均额 |
|-----|------|-----|-----|--------|------|---------|--------|-----|------|------|--------|-----|---------|---------|
| 300628.SZ | 亿联网络 | 300 | 创业板 | 20260715 | +4.62% | 33.960~35.530 | 20260918 | 41.460 | 38.663 | +7.24% | +16.69% | 2.52 | 3.74亿 | 4.12亿 |

（vX.Y.Z 为占位：正文示例版本串不随 sync_version.py 自动更新，以运行时实际输出为准。 上表数值取自 2026-09-19 实测缓存数据：该行 量比分母 3.74亿 与 当前20日均额 4.12亿 是两个不同窗口， 复算 9.45亿（缺口日成交额）÷ 3.74亿 = 2.52（量比）。

「新拉」是实际成功数，不是计划拉取数：待拉标的可能拉取失败（未进入 K 线映射）。 启用缓存时缓存行写成 缓存命中 X / 新拉 Y / 拉取失败 Z（计入「获取失败/数据缺失」排除桶）； --no-cache 时写成 已禁用（--no-cache）| 计划重拉 N / 新拉 Y / 拉取失败 Z——禁用缓存同样是 「先计划后执行」，不得只写「全部重新拉取」。若全部拉取失败，引擎直接以退出码 1 结束且不产出报告。）

命中表列说明

详文档

reports/gap-scan/{YYYY-MM-DD-HH-MM-SS}.md，含：

• 首尾各一条完整可见的风险声明（非投资建议、观察清单、非交易信号）
• 数据与来源：实际使用源 / 实际尝试过的源及其理由（未配置而跳过 ≠ 尝试后失败）/ K 线缓存 （缓存命中数、实际新拉数、拉取失败数、TTL、条目年龄）/ 交易日历是否降级 / 池规模与覆盖率， 以及字段级来源表——其中「成分股池」行按指数给出实际生效的那一级 （index_stock_cons / index_stock_cons_sina / Tushare index_weight）； 复用旧缓存且无 sidecar 时写「未记录」，不回落成首选源的名字
• 全量命中表 + 逐股简析（数据日、缺口区间、量比与分母、MA60 判定覆盖度）+ 排除/未命中统计 + 运行参数
• 逐股简析中的**「事件/催化」槽位标注为「未采集」**：引擎只做价格形态检出，不做事件归因； 如需补充须另行检索并标注来源与日期，不得把检索摘要直接当事实

缓存

位置

~/.local/share/investment/gap_scan_cache/
|-- universe_20260719.pkl               (成分股列表，按采集日命名)
|-- universe_20260719.provenance.json   (该次成分股各指数的实际来源 sidecar)
|-- kline/                              (固定段键目录, v0.2.5)
|   |-- tushare/                   (按数据源隔离)
|   |   |-- 000001.SZ.pkl
|   |   `-- ...
|   `-- baostock/
|       |-- 000001.SZ.pkl
|       `-- ...

缓存策略

• TTL: 3 天 (基于文件 mtime；固定段键使跨日命中生效，旧版 {YYYYMMDD} 日期目录随 v0.2.5 一次性清理)
• Scope: 按数据源隔离，tushare/baostock 缓存互不污染
• 格式: Python pickle (pandas DataFrame)
• 强制刷新: --no-cache 跳过加载，重新拉取并覆盖
• ⚠️ 末根 bar 定稿判据（复用前提）: 缓存文件写入时刻必须晚于其末根 bar 自身交易日的收盘（15:00）， 否则该缓存视为未命中并重拉。数据源可能在盘中返回当日尚未走完的 bar，这份快照若被留到次日， 仅按日期比较会被当成已完成 bar（「昨日 < 今日」），从而用未走完的低点断言「缺口未回补」—— 实测该情形可凭空产出命中。报告在缓存行注明「其中 N 只为『缓存末根 bar 未定稿』而重拉」
• 坏条目按未定稿处理，不中止扫描：缓存日期位数为 8 但非合法日历日（如 20260230）、写入时刻 不可得、9 位等位数异常的日期串，一律视为未定稿 → 该股重拉、坏条目被覆盖。缓存校验谓词 不抛异常（调用点在逐股异常隔离之外，抛出会中止整次扫描）；位数异常的日期串不做截断猜测
• ⚠️ 与数据时点的关系: TTL 内命中缓存时，扫描用的是缓存写入时点的 K 线——报告首部的 「数据截止」与逐股「数据日」即反映该时点，缓存命中数与条目年龄也在报告披露。不得把表内价格当作实时价

数据源

降级策略

K 线源（auto）:
  1. TUSHARE_TOKEN 存在 -> 先用 TushareClient.is_available() 做**有效 token 可用性检验**
  2. 检验通过 -> TushareBulkSource (快速批量)
  3. 无 token -> 直接 BaostockSource（**未尝试 Tushare**，不算降级）
     有 token 但检验失败 -> BaostockSource（**真降级**：已尝试且失败）

成分股（逐指数，对每个指数独立降级）:
  1. akshare index_stock_cons
  2. akshare index_stock_cons_sina（仅沪深300）
  3. Tushare index_weight（需 token 可用）
  全失败 -> 该指数不纳入池，并在报告「成分股池」行标注「全部源失败未纳入池」
  来源随缓存落盘为 sidecar（universe_{yyyymmdd}.provenance.json）

交易日历:
  1. Tushare trade_cal API -> 真实日历 + 停牌检测
  2. 失败 -> 自然日估算 (Mon-Fri) + 跳过停牌检测

「有 token」不等于「token 可用」：auto 路径先做可用性检验，检验失败同样降级到 baostock。 报告把实际使用源与尝试过的源分开列出，且**「未配置而跳过」不计入尝试**—— 无 token 时只写 baostock，并注明「未配置 TUSHARE_TOKEN（未尝试 Tushare）」， 不得把「未配置」写成「尝试过但失败」，也不得把降级链写成并列来源。

排除/未命中原因

排除 (扫描前剔除)

未命中 (扫描后无结果)

零值桶不显示在报告中，可由闭合恒等式推得：

池规模 = 排除（扫描前） + 未命中（扫描后） + 命中 + 跨停牌

联动

对命中的标的，接 /invest-a-stock {symbol} 做深度基本面研究——这是独立的事实研究入口，不是行动步骤： 命中只说明该标的落在上述形态规则内，是否值得继续研究由你判断。

合规

• 禁止买卖/仓位建议
• 禁止单一目标价
• 用「缺口区间 / 上沿回补位」等中性表述
• 命中 = 观察清单，非交易信号、非预测、非推荐排序；输出末尾标注"仅供研究，不构成投资建议"