global-stock-data

name	global-stock-data
description	美股港股全栈数据工具包（官方源优先）— 十三层架构·30+端点·11数据源·全部零鉴权。在原有行情/K线/技术指标(MA/MACD/RSI/KDJ/布林带)/基本面/资金面/期权/SEC Filing/工具八层之上，新增：CBOE官方期权链(完整希腊字母+IV+0DTE流+异动识别)、FINRA全市场每日空头成交量、SEC EDGAR申报事件流(Form4内部人/8-K/13F机构持仓)、EDGAR全市场横截面筛选、美债收益率曲线/CFTC COT/财报日历。每个数据源标注合规级别与条款原文。内嵌全部调用代码，自包含零依赖外部文件。适用于美股港股个股分析、全市场筛选、财报解读、期权与0DTE策略、做空数据追踪、SEC文件检索、资金流与机构持仓分析等场景。
origin	custom
version	2.0.3

📦 项目主页：https://github.com/simonlin1212/global-stock-data — 更新、反馈、支持作者

作者：Simon 林 · X @linsizhen · 邮箱：[e-mail]

美股港股全栈数据工具包 V2.0 — 官方源优先

十三层数据架构，30+ 个端点，11 个数据源，全部零鉴权，实测可用（2026-07-24 全量回归验证）。

V2.0 设计原则：官方源优先。 新增层的主力数据取自美国政府（SEC EDGAR / Treasury / CFTC）、 自律组织（FINRA）与交易所（CBOE / Nasdaq）的公开端点。每个数据源都标注了合规级别与条款原文 （见下方「数据源合规分级」）——"官方"不等于"可自由使用"，各源差异极大。

本工具只分发代码，不分发、不转售任何市场数据；数据由使用者自行按各源条款获取。

使用方式： 将本文件放入 ~/.claude/skills/global-stock-data/SKILL.md，Claude Code 会自动识别并在美股/港股相关对话中激活。

行情层（实时/延时）
├── 新浪财经     → 美股 gb_XXXX 36字段 / 港股 rt_hkXXXXX 25字段
├── 腾讯财经     → 美股 usXXXX 71字段 / 港股 r_hkXXXXX 78字段
└── 东财 push2   → 美股/港股 secid 实时行情，含中文名/涨跌幅/换手率

K线层（日/周/月/分钟）
├── 新浪          → 美股日K (回溯至1984年)
└── Yahoo chart   → 美股+港股 (v8 API, 零crumb)

技术指标层（纯计算，零额外依赖）
└── MA/EMA + MACD + RSI + KDJ + 布林带    基于K线OHLCV，纯Python计算

基本面层
├── 东财 datacenter → 美股/港股三表(资产负债+利润+现金流) + GMAININDICATOR(关键指标)
├── Yahoo crumb     → 23个模块(财务数据+关键指标+分析师+机构持仓)
└── SEC EDGAR XBRL  → 美股503个GAAP指标 (仅美股)

资金面层
└── 东财 push2his → 日级资金流(主力/大单/中单/小单) 美股+港股

期权层（仅美股）
└── Yahoo crumb → 期权链(calls+puts, 所有到期日) 仅美股(港股期权不在Yahoo覆盖范围)

SEC Filing层（仅美股）
├── EDGAR submissions → 10-K/10-Q/8-K 完整Filing列表
└── EDGAR XBRL        → 结构化财务指标(营收/净利/EPS等)

工具层
├── 东财 search    → 股票搜索(中英文, 含市场代码映射)
├── 东财 push2     → 全市场股票列表(涨跌幅/成交量排名, 美股5925只+港股18000+只)
├── Yahoo search   → 新闻资讯(按股票代码)
└── SEC CIK mapping → ticker↔CIK 映射 (仅美股)

━━━ 以下为 V2.0 新增（官方源优先）━━━

期权层·CBOE 官方（仅美股）⭐
└── CBOE cdn → 全链 + IV + delta/gamma/vega/theta/rho + 0DTE + 异动flow   [C级·需授权]

做空层（仅美股）⭐
└── FINRA Reg SHO → 全市场每日空头成交量(实测12,112只) + 个股时序 + 排行  [B级]

申报事件流（仅美股）⭐
├── EDGAR 每日索引 → Form4内部人/8-K/13F机构持仓/144，当日全量           [S级]
└── EDGAR 全文检索 → 2001至今所有申报正文，按关键词+表单+日期            [S级]

全市场横截面（仅美股）⭐
└── EDGAR frames → 任意XBRL标签一次拿全市场(实测1,842~5,309家)=免费screener [S级]

宏观 / 日历 ⭐
├── Treasury → 美债收益率曲线(1M~30Y, 每日)                             [S级]
├── CFTC     → COT 持仓报告                                             [S级]
└── Nasdaq   → 财报日历(含盘前盘后+EPS预期)                             [C级·未核实]

---

端点路由速查（按需定位，不必通读全文）

我想要…	去哪层	主力源	合规级
实时/延时报价	Layer 1	新浪 / 腾讯 / 东财	C
K 线（日/周/月）	Layer 2	新浪 / Yahoo	C
技术指标 MA/MACD/RSI/KDJ/布林	Layer 3	本地计算	—
财报三表 / 关键指标 / 分析师 / 机构持仓	Layer 4	东财 / Yahoo / EDGAR	C·S
日级资金流	Layer 5	东财	C
期权链 + 希腊字母 + IV + 0DTE + 异动flow	Layer 6.1	CBOE 官方 ⭐	C
期权链（无希腊字母，后备）	Layer 6.2	Yahoo	C
10-K/10-Q/8-K 列表、XBRL 财务	Layer 7	SEC EDGAR	S
搜索 / 新闻 / CIK 映射 / 全市场列表	Layer 8	东财 / Yahoo / SEC	C·S
全市场每日空头成交量、个股空头占比	Layer 9	FINRA Reg SHO ⭐	B
当日申报流：Form 4 内部人 / 8-K / 13F	Layer 10.1	EDGAR 每日索引 ⭐	S
申报全文检索（2001 至今正文）	Layer 10.2	EDGAR FTS ⭐	S
全市场基本面横截面（免费 screener）	Layer 11	EDGAR frames ⭐	S
美债收益率曲线 / CFTC COT / 财报日历	Layer 12	Treasury / CFTC / Nasdaq	S·C

⭐ = V2.0 新增，且为 yfinance 与多数开源方案不具备的能力。

---

数据源合规分级（取用前必读 — 各级均引条款原文）

下表结论来自 2026-07-24 逐家实读各源条款原文，不是推断。引号内为原文。 各源差异极大，"官方"不等于"可自由使用"。

S 级 — 可自由使用（含商用与再分发）

源	依据（原文）
SEC EDGAR	官网明示："Anyone can access and download this information for free"、"We allow scripted access to sec.gov content"。硬性要求：Current max request rate: 10 requests/second，且必须声明 User-Agent（格式 Company Name [e-mail]），否则触发 "Undeclared Automated Tool" / Access Denied
US Treasury / CFTC	美国联邦政府作品不受版权保护（17 U.S.C. §105）。⚠️ 本次未逐条核验两站条款正文，按政府数据惯例归此级

B 级 — 数据文件系主动公开，但站点条款含限制

源	依据（原文）
FINRA	Reg SHO 每日文件是 FINRA 主动发布供下载的监管披露文件；但其 Terms of Use 同时禁止 "use any process to monitor or copy the FINRA Website in bulk, or use any data mining, scraping or harvesting tools (including robots)"，且站点声明 "FINRA Data provides non-commercial use of data"。→ 下载已发布的数据文件属常规用法；批量爬站点页面不属于。商用前请自行向 FINRA 确认。

C 级 — 使用需事先授权，或条款未核实

源	依据（原文）
CBOE	Use of Content 政策：使用任何 Cboe Content 须 "receive approval in advance from Cboe"，并须 "execution of a license agreement"；政策不区分商用/非商用、不区分实时/延时。→ 本工具的 CBOE 期权层仅供个人研究；商业用途或再分发前，须先向 Cboe 申请授权。
Nasdaq	本次抓取条款页超时，未核实。按未核实处理
Yahoo / 东财 / 新浪 / 腾讯	Yahoo 官方文档写明 personal use only；其余为站点前端接口。仅供个人研究，勿用于商业产品或再分发

⛔ 已排除的源

源	原因
HKEX（CCASS 港股席位持股）	其 Terms of Use 明文禁止 "any 'robot', 'bot', 'spider', 'scraper' or other automated device... to access, obtain, copy, monitor or republish any portion of the Website"，禁止 "text or data mining or web scraping"，且适用于 "whether or not for gain"（不论是否营利）。→ 本工具不提供 CCASS 抓取代码。 需要港股席位持股/南向资金数据者，请通过 HKEX 授权渠道或其网页人工查询

给使用者的三条硬规则

1. 商业用途：只依赖 S 级（SEC EDGAR / Treasury / CFTC）。B 级需自行确认，C 级须先取得授权。
2. 再分发：本工具只分发代码，不分发任何市场数据。你也不应把 B/C 级源取得的数据对外分发。
3. 限速：所有新增层的请求已内置节流（见「统一 HTTP 层」）。不要绕过它——SEC 的 10 req/s 是官方硬上限。

---

When to Activate

• 用户要查美股/港股行情（价格/涨跌幅/成交量）
• 用户要拉 K 线（日线/周线/月线/分钟线）
• 用户要看财报（资产负债表/利润表/现金流量表）
• 用户要看关键财务指标（PE/PB/ROE/利润率/目标价）
• 用户要看分析师预期（EPS预测/评级/目标价区间）
• 用户要看机构持仓（前十大机构/持股比例）
• 用户要看资金流向（主力/大单/中单/小单净流入）
• 用户要查期权链（calls/puts/到期日/Greeks）
• 用户要查 SEC Filing（10-K/10-Q/8-K/年报/季报）
• 用户要做美股财报量化分析（从 XBRL 拉多年营收/净利/EPS 趋势）
• 用户要搜索股票（中英文均可）
• 用户要看美股/港股新闻
• 用户要看全市场涨跌幅排名（当日涨幅/跌幅最大的股票）
• 用户要做全市场筛选（遍历美股/港股列表做初筛）
• 用户要看关键财务指标概览（营收/净利/EPS/ROE/ROA/资产负债率 中文版）
• 用户要看技术指标（MACD/RSI/KDJ/布林带/均线）
• 用户要判断金叉死叉/超买超卖/变盘信号
• 关键词：美股、港股、AAPL、苹果、腾讯、00700、TSLA、特斯拉、BABA、阿里巴巴、行情、K线、财报、PE、PB、ROE、分析师、目标价、期权、call、put、SEC、10-K、年报、季报、资金流、主力、机构持仓、新闻、涨幅排名、全市场、筛选、关键指标、MACD、RSI、KDJ、布林带、均线、金叉、死叉、超买、超卖、技术分析

---

Prerequisites

pip install requests

依赖	版本要求	用途
requests	any	所有 HTTP API 直连

极简依赖： 仅需 requests，所有数据源均为直连 HTTP API，零第三方数据封装。

---

市场代码规则

东财 secid 前缀（push2/push2his 用）

前缀	市场	示例
105	美股 NASDAQ	105.AAPL, 105.TSLA
106	美股 NYSE	106.BABA, 106.JD
107	美股 ETF/其他	107.CRSH
116	港股	116.00700, 116.09988

如何判断 105/106/107？ 调 stock_search() 获取 MktNum 字段自动映射。

Yahoo Finance 代码格式

市场	格式	示例
美股	直接 ticker	AAPL, TSLA, BABA
港股	四/五位数字 + .HK	0700.HK, 9988.HK

东财 datacenter SECUCODE 格式

市场	格式	示例
美股 NASDAQ	TICKER.O	AAPL.O, TSLA.O
美股 NYSE	TICKER.N	BABA.N, JD.N
港股	CODE.HK	00700.HK, 09988.HK

---

共用 Helper 函数

Yahoo Finance crumb 管理器

Yahoo quoteSummary/options 等 v7/v10 接口需要 cookie+crumb。以下 helper 自动获取并缓存：

import requests

_yahoo_session = None

def get_yahoo_session() -> requests.Session:
    """获取带 crumb 的 Yahoo Finance session（自动缓存）"""
    global _yahoo_session
    if _yahoo_session and hasattr(_yahoo_session, '_crumb'):
        return _yahoo_session
    
    s = requests.Session()
    s.headers['User-Agent'] = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36'
    
    # Step 1: 获取 cookie
    s.get('https://fc.yahoo.com', timeout=10)
    
    # Step 2: 获取 crumb
    r = s.get('https://query2.finance.yahoo.com/v1/test/getcrumb', timeout=10)
    r.raise_for_status()
    s._crumb = r.text
    
    _yahoo_session = s
    return s

def yahoo_quote_summary(symbol: str, modules: list[str]) -> dict:
    """Yahoo quoteSummary 统一查询"""
    s = get_yahoo_session()
    r = s.get(f'https://query2.finance.yahoo.com/v10/finance/quoteSummary/{symbol}', params={
        'modules': ','.join(modules),
        'crumb': s._crumb,
    }, timeout=15)
    r.raise_for_status()
    results = r.json().get('quoteSummary', {}).get('result', [{}])
    return results[0] if results else {}

东财数据中心统一查询

UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
DATACENTER_URL = "https://datacenter-web.eastmoney.com/api/data/v1/get"

def eastmoney_datacenter(report_name: str, columns: str = "ALL",
                          filter_str: str = "", page_size: int = 50,
                          sort_columns: str = "", sort_types: str = "-1") -> list[dict]:
    """东财数据中心统一查询"""
    params = {
        "reportName": report_name, "columns": columns,
        "filter": filter_str, "pageNumber": "1", "pageSize": str(page_size),
        "sortColumns": sort_columns, "sortTypes": sort_types,
        "source": "WEB", "client": "WEB",
    }
    r = requests.get(DATACENTER_URL, params=params, headers={"User-Agent": UA}, timeout=15)
    d = r.json()
    if d.get("result") and d["result"].get("data"):
        return d["result"]["data"]
    return []

---

官方源统一出口（限流 + UA 声明）— V2.0 新增

V2.0 新增的 Layer 9–12 全部走这个出口。它负责三件事：按源限速、SEC User-Agent 声明、 友好错误提示。

⚠️ 使用前必改：把 SEC_CONTACT 换成你自己的真实姓名与邮箱。 SEC 官方要求声明 User-Agent，未声明会被判定为 Undeclared Automated Tool 并拒绝服务。

import requests, time, threading

# ⚠️⚠️ 必改：SEC 要求 UA 含真实联系方式，格式 "Company Name [e-mail]"
SEC_CONTACT = "your-name [e-mail]"


class DataNotAvailable(RuntimeError):
    """该日/该标的确实没有数据（如非交易日、文件尚未发布）——可安全回退到下一个候选日。

    与配置错误、网络错误区分开：后者必须立刻抛给调用方，
    否则「SEC_CONTACT 没配」会被日期回退循环吞掉，最后伪装成「没找到数据」。
    """


class _RateLimiter:
    """线程安全的最小间隔节流器（用锁，避免并发下被击穿）"""

    def __init__(self, max_per_sec: float):
        self._interval = 1.0 / float(max_per_sec)
        self._last = 0.0
        self._lock = threading.Lock()

    def wait(self) -> None:
        with self._lock:
            gap = self._interval - (time.monotonic() - self._last)
            if gap > 0:
                time.sleep(gap)
            self._last = time.monotonic()


# 各源限速：SEC 官方硬上限 10/s，此处取 8/s 留余量；其余为自律保护值
_LIMITS = {
    "sec.gov": _RateLimiter(8),
    "finra.org": _RateLimiter(4),
    "cboe.com": _RateLimiter(4),
    "nasdaq.com": _RateLimiter(2),
    "_default": _RateLimiter(5),
}


def () -> _RateLimiter:
     host, lim  _LIMITS.items():
         host !=   host  url:
             lim
     _LIMITS[]


 () -> :
    
     resp.status_code == :
         
     resp.status_code != :
         
    ctype = (resp.headers.get()  ).lower()
    head = (resp.text  )[:]
       ctype    head


 ():
    
       url:
           SEC_CONTACT:
             RuntimeError(
                
                )
        h = {: SEC_CONTACT, : }
    :
        h = {: UA}
    h.update(headers  {})

    _limiter_for(url).wait()
    :
        r = requests.get(url, params=params, headers=h, timeout=timeout)
        r.raise_for_status()
     requests.HTTPError  e:
        resp = e.response
        code = resp.status_code
        low = (resp.text  )[:].lower()
        
         _is_object_missing(resp):
             DataNotAvailable(
                )  e
        
         code ==     low:
             RuntimeError(
                
                
                )  e
        
        hint = {: ,
                : ,
                : }.get(code, )
         RuntimeError()  e
     requests.RequestException  e:
         RuntimeError()  e
     r.json()  as_json  r.text










 () -> :
    
    t = (ticker).upper()
     t.endswith()  (t.isdigit()  (t)  (, )):
         ValueError(
                         )
      t.replace(, ).replace(, ).isalnum():
         ValueError()
     t

requests 会自动解压 gzip 响应，因此上面带 Accept-Encoding 是安全的。 若你改用 urllib 自行实现，必须手动 gzip.decompress，否则 SEC 返回的内容会解析失败。

---

Layer 1: 行情层

1.1 美股实时行情 — 新浪 + 腾讯

两个独立数据源，任一可用即可。新浪字段侧重价格成交，腾讯字段更全（含52周高低/市值/PE）。

import requests, re

def us_stock_quote_sina(ticker: str) -> dict:
    """
    新浪美股行情 — 36字段
    ticker: 纯字母，如 "AAPL", "TSLA", "BABA"
    """
    url = f"https://hq.sinajs.cn/list=gb_{ticker.lower()}"
    r = requests.get(url, headers={
        "Referer": "https://finance.sina.com.cn/",
        "User-Agent": UA,
    }, timeout=10)
    r.encoding = "gbk"
    text = r.text
    
    m = re.search(r'"(.+)"', text)
    if not m:
        return {}
    
    fields = m.group(1).split(",")
    if len(fields) < 30:
        return {}
    
    return {
        "name": fields[0],           # 中文名
        "price": float(fields[1]),    # 最新价
        "change_pct": float(fields[2]),  # 涨跌幅 %
        "timestamp": fields[3],       # 时间
        "prev_close": float(fields[26]),  # 昨收
        "open": float(fields[5]),     # 开盘
        "high": float(fields[]),     
        : (fields[]),      
        : (fields[])  fields[]  ,  
        : (fields[])  fields[]  ,  
        : (fields[])  fields[]  ,   
        : (fields[])  fields[]  ,  
        : (fields[])  fields[]  ,  
        : (fields[])  fields[]  ,   
    }


 () -> :
    
    url = 
    r = requests.get(url, timeout=)
    r.encoding = 
    text = r.text
    
    m = re.search(, text)
      m:
         {}
    
    fields = m.group().split()
     (fields) < :   
         {}
    
    
     {
        : fields[],           
        : fields[],       
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : ((fields[]))  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,  
        : (fields[])  fields[]  ,        
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : fields[],      
        : fields[],
    }

1.2 港股实时行情 — 腾讯 + 新浪

def hk_stock_quote_tencent(code: str) -> dict:
    """
    腾讯港股行情 — 78字段（最全）
    code: 五位数字，如 "00700", "09988"
    """
    url = f"https://qt.gtimg.cn/q=r_hk{code}"
    r = requests.get(url, timeout=10)
    r.encoding = "gbk"
    text = r.text
    
    m = re.search(r'"(.+)"', text)
    if not m:
        return {}
    
    fields = m.group(1).split("~")
    if len(fields) < 76:   # 需读到 fields[75](币种)，港股正常返回 78 个
        return {}
    
    # ⚠️ 下标以实测为准，与美股那套不同（见本节末「腾讯行情字段对照表」）
    return {
        "name": fields[1],           # 中文名
        "code": fields[2],           # 五位代码，如 "00700"（旧版误当英文名）
        "name_en": fields[46],       # 英文名，如 "TENCENT"
        "price": float(fields[3]) if fields[3] else 0,
        "prev_close": float(fields[4]) if fields[4] else 0,
        "open": float(fields[5]) if fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : ((fields[]))  fields[]  ,  
        : (fields[])  fields[]  ,     
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,  
        : (fields[])  fields[]  ,        
        : fields[],      
        : fields[],
    }


 () -> :
    
    url = 
    r = requests.get(url, headers={
        : ,
        : UA,
    }, timeout=)
    r.encoding = 
    text = r.text
    
    m = re.search(, text)
      m:
         {}
    
    fields = m.group().split()
     (fields) < :
         {}
    
     {
        : fields[],
        : fields[],           
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
        : (fields[])  fields[]  ,
    }

腾讯行情字段对照表（qt.gtimg.cn · 2026-07-26 实测校准）

⚠️ 美股与港股的字段布局不同，不能共用一套下标。 美股返回 71 个字段，港股 78 个。 下面每个下标都以真实响应逐个核对过（usAAPL / hk00700），网上流传的映射表多处有误。

含义	美股下标	港股下标	实测值（AAPL / 00700）
中文名	1	1	苹果 / 腾讯控股
代码	2	2	AAPL.OQ / 00700
英文名	46	46	Apple Inc. / TENCENT
现价	3	3	333.02 / 434.600
昨收 / 今开	4 / 5	4 / 5	—
成交量	6	6	⚠️ 港股带小数位（22959603.0），必须 int(float(x))
涨跌幅 %	32	32	3.53 / -2.38
当日最高 / 最低	33 / 34	33 / 34	—
币种	35	75	USD / HKD
PE	39	39	40.32 / 15.87
流通市值（亿本币）	44	44	48881.62 / 39516.08
总市值（亿本币）	45	45	48911.83 / 39516.08
EPS	47	—	8.26（333.02 ÷ 8.26 = 40.32 ✓ 与 PE 自洽）
52 周最高 / 最低	48 / 49	48 / 49	334.99·200.72 / 677.7·411.0
PB	51	58	45.93 / 3.14

市值单位是「亿本币」，不是股数：AAPL 总市值 48911.83（亿美元）= 现价 333.02 × 总股本 14,687,356,000，可用 fields[62] 的总股本反算核对。港股同理，单位为亿港元。

自行复现命令（行号 N ↔ 数组下标 N−1）：

curl -s "https://qt.gtimg.cn/q=usAAPL"  | iconv -f GBK -t UTF-8 | tr '~' '\n' | cat -n
curl -s "https://qt.gtimg.cn/q=hk00700" | iconv -f GBK -t UTF-8 | tr '~' '\n' | cat -n

港股 hk 与 r_hk 两种前缀返回的字段布局完全一致（均 78 个），可互换。 感谢 @HoRiZonn0 在 issue #2 中提供的完整对照，本表据此逐条复测后修订。

1.3 东财 push2 实时行情 — 美股 + 港股

东财 push2 接口，通过 secid 统一查询美股/港股实时行情。优点：有中文名、换手率、涨跌幅，且 secid 可由 stock_search() 自动获取。

def stock_quote_eastmoney(ticker_or_code: str, secid_prefix: int = 105) -> dict:
    """
    东财 push2 实时行情 — 美股+港股统一接口
    美股: stock_quote_eastmoney("AAPL", 105)  # NASDAQ
          stock_quote_eastmoney("BABA", 106)  # NYSE
    港股: stock_quote_eastmoney("00700", 116)
    返回: 最新价/开高低收/成交量/成交额/换手率/涨跌幅/中文名
    
    secid_prefix 说明: 105=NASDAQ, 106=NYSE, 107=US_ETF, 116=港股
    如不确定前缀，先调 stock_search() 获取 mkt_num
    """
    url = "https://push2.eastmoney.com/api/qt/stock/get"
    params = {
        "secid": f"{secid_prefix}.{ticker_or_code}",
        "fields": "f43,f44,f45,f46,f47,f48,f55,f57,f58,f59,f60,f170",
    }
    r = requests.get(url, params=params, timeout=10)
    d = r.json().get("data")
    if not d:
        return {}
    
    # f59 = 小数位数, 价格字段需除以 10^f59 还原真实值
    dec = d.get("f59", 3)
    divisor = 10 ** dec
    
    def _p(key):
        v = d.get(key)
        if v is None or v == "-":
            return None
        return round(v / divisor, dec)
    
    return {
        "code": d.get("f57"),           # 股票代码
        "name": d.get("f58"),           # 中文名
        "price": _p(),             
        : _p(),              
        : _p(),               
        : _p(),              
        : d.get(),         
        : d.get(),         
        : d.get(),  
        : _p(),        
        : (d[] / , )  d.get()     ,  
    }

---

Layer 2: K线层

2.1 美股 K 线 — 新浪（主）+ Yahoo（备）

两个独立数据源。新浪最长可回溯到 1984 年；Yahoo 适合需要复权数据的场景。

注意： 东财 push2his kline/get 端点实测不返回美股/港股数据（2026-05-20 验证），仅支持 A 股。美股/港股 K 线用新浪和 Yahoo。

def us_stock_kline_sina(ticker: str, num: int = 120) -> list[dict]:
    """
    新浪美股日K — 可回溯到1984年
    ticker: 如 "AAPL"
    返回: [{date, open, high, low, close, volume}, ...]
    """
    url = "https://stock.finance.sina.com.cn/usstock/api/jsonp.php/var/US_MinKService.getDailyK"
    params = {"symbol": ticker.upper(), "num": num}
    r = requests.get(url, params=params, headers={"Referer": "https://finance.sina.com.cn/"}, timeout=15)
    text = r.text
    
    # 解析 JSONP: var=([{...},...])
    import json
    m = re.search(r'\((\[.+\])\)', text)
    if not m:
        return []
    
    items = json.loads(m.group(1))
    result = []
    for item in items:
        result.append({
            "date": item.get("d"),
            "open": float(item.get("o", 0)),
            "high": float(item.get("h", 0)),
            "low": float(item.get("l", 0)),
            "close": float(item.get("c", 0)),
            "volume": int(item.get("v", 0)),
        })
     result


 () -> []:
    
    url = 
    params = {: interval, : range_}
    r = requests.get(url, params=params, headers={
        : 
    }, timeout=)
    r.raise_for_status()
    
    d = r.json()
    chart = d.get(, {}).get(, [{}])[]
    timestamps = chart.get(, [])
    quote = chart.get(, {}).get(, [{}])[]
    
     datetime  datetime
    result = []
     i, ts  (timestamps):
        result.append({
            : datetime.fromtimestamp(ts).strftime()    interval    interval  datetime.fromtimestamp(ts).strftime(),
            : (quote[][i], )  quote[][i]  ,
            : (quote[][i], )  quote[][i]  ,
            : (quote[][i], )  quote[][i]  ,
            : (quote[][i], )  quote[][i]  ,
            : (quote[][i])  quote[][i]  ,
        })
     result

2.2 港股 K 线 — Yahoo（唯一可用源）

港股 K 线只有 Yahoo 一个可用源（新浪港股K线已失效，东财 push2his 不返回港股K线数据）。

# 港股 Yahoo K线: 直接调 stock_kline_yahoo("0700.HK")

---

Layer 3: 技术指标层

基于 K 线 OHLCV 数据的纯 Python 技术指标计算，零额外依赖。

使用方式： 先调 K 线函数获取数据，再传入技术指标函数：

klines = us_stock_kline_sina("AAPL", 120)
macd = calc_macd(klines)
rsi = calc_rsi(klines)

3.1 移动平均线 MA / EMA

def _ema(values: list[float], period: int) -> list[float]:
    """EMA 指数移动平均（内部辅助）"""
    result = [values[0]]
    k = 2 / (period + 1)
    for v in values[1:]:
        result.append(v * k + result[-1] * (1 - k))
    return result


def calc_ma(klines: list[dict], periods: list[int] = None) -> list[dict]:
    """
    移动平均线 MA + EMA
    klines: K线数据 [{date, open, high, low, close, volume}, ...]
    periods: 周期列表，默认 [5, 10, 20, 60]
    返回: [{date, close, ma5, ma10, ma20, ma60, ema12, ema26}, ...]
    """
    if periods is None:
        periods = [5, 10, 20, 60]
    closes = [k["close"] for k in klines]
    
    # EMA 12/26（MACD 常用）
    ema12 = _ema(closes, 12)
    ema26 = _ema(closes, 26)
    
    result = []
    for i, k in enumerate(klines):
        row = {"date": k["date"], "close": k["close"]}
         p  periods:
             i >= p - :
                row[] = ((closes[i - p + :i + ]) / p, )
            :
                row[] = 
        row[] = (ema12[i], )
        row[] = (ema26[i], )
        result.append(row)
     result

3.2 MACD

def calc_macd(klines: list[dict], fast: int = 12, slow: int = 26,
              signal: int = 9) -> list[dict]:
    """
    MACD (Moving Average Convergence Divergence)
    klines: K线数据
    fast/slow/signal: 快线/慢线/信号线周期（默认 12/26/9）
    返回: [{date, close, dif, dea, macd_hist}, ...]
    
    dif = EMA(fast) - EMA(slow)        金叉/死叉看 dif 穿越 dea
    dea = EMA(signal) of dif           信号线
    macd_hist = (dif - dea) * 2        柱状图（红涨绿跌）
    """
    closes = [k["close"] for k in klines]
    ema_fast = _ema(closes, fast)
    ema_slow = _ema(closes, slow)
    
    dif = [round(f - s, 4) for f, s in zip(ema_fast, ema_slow)]
    dea = _ema(dif, signal)
    
    result = []
    for i, k in enumerate(klines):
        result.append({
            "date": k["date"],
            "close": k["close"],
            "dif": round(dif[i], 4),
            "dea": round(dea[i], 4),
            "macd_hist": round((dif[i] - dea[i]) * 2, 4),
        })
    return result

3.3 RSI

def calc_rsi(klines: list[dict],
             periods: list[int] = None) -> list[dict]:
    """
    RSI (Relative Strength Index)
    klines: K线数据
    periods: 周期列表（默认 [6, 12, 24]）
    返回: [{date, close, rsi6, rsi12, rsi24}, ...]
    
    RSI > 70 超买区（可能回调）
    RSI < 30 超卖区（可能反弹）
    """
    if periods is None:
        periods = [6, 12, 24]
    closes = [k["close"] for k in klines]
    
    # 涨跌额序列
    changes = [0.0] + [closes[i] - closes[i - 1] for i in range(1, len(closes))]
    gains = [max(c, 0) for c in changes]
    losses = [max(-c, 0) for c in changes]
    
    result = []
    for i, k in enumerate(klines):
        row = {"date": k["date"], "close": k["close"]}
        for p in periods:
            if i < p:
                row[f"rsi{p}"] = None
                continue
            avg_gain = (gains[i - p + :i + ]) / p
            avg_loss = (losses[i - p + :i + ]) / p
             avg_loss == :
                row[] = 
            :
                rs = avg_gain / avg_loss
                row[] = ( -  / ( + rs), )
        result.append(row)
     result

3.4 KDJ

def calc_kdj(klines: list[dict], n: int = 9,
             m1: int = 3, m2: int = 3) -> list[dict]:
    """
    KDJ 随机指标
    klines: K线数据
    n: RSV 周期（默认9）
    m1/m2: K/D 平滑系数（默认3/3）
    返回: [{date, close, k, d, j}, ...]
    
    K/D > 80 超买，K/D < 20 超卖
    J > 100 或 J < 0 为极端信号
    金叉: K 上穿 D；死叉: K 下穿 D
    """
    k_val, d_val = 50.0, 50.0
    result = []
    
    for i, kline in enumerate(klines):
        if i < n - 1:
            result.append({"date": kline["date"], "close": kline["close"],
                           "k": None, "d": None, "j": None})
            continue
        
        window = klines[i - n + 1:i + 1]
        high_n = max(w["high"] for w in window)
        low_n = min(w["low"] for w in window)
        
        rsv = (kline["close"] - low_n) / (high_n - low_n) * 100 if high_n != low_n else 50.0
        k_val = (1 / m1) * rsv + (1 -  / m1) * k_val
        d_val = ( / m2) * k_val + ( -  / m2) * d_val
        j_val =  * k_val -  * d_val
        
        result.append({
            : kline[],
            : kline[],
            : (k_val, ),
            : (d_val, ),
            : (j_val, ),
        })
     result

3.5 布林带

def calc_boll(klines: list[dict], period: int = 20,
              num_std: float = 2.0) -> list[dict]:
    """
    布林带 (Bollinger Bands)
    klines: K线数据
    period: 中轨 MA 周期（默认20）
    num_std: 标准差倍数（默认2）
    返回: [{date, close, upper, middle, lower, bandwidth}, ...]
    
    价格触及 upper → 可能超买
    价格触及 lower → 可能超卖
    bandwidth 收窄 → 即将变盘
    """
    closes = [k["close"] for k in klines]
    result = []
    
    for i, k in enumerate(klines):
        if i < period - 1:
            result.append({"date": k["date"], "close": k["close"],
                           "upper": None, "middle": None, "lower": None,
                           "bandwidth": None})
            continue
        
        window = closes[i - period + 1:i + 1]
        ma = sum(window) / period
        std = (sum((x - ma) ** 2 for x in window) / period) ** 0.5
        upper = ma + num_std * std
        lower = ma - num_std * std
        
        result.append({
            "date": k["date"],
            "close": k["close"],
            : (upper, ),
            : (ma, ),
            : (lower, ),
            : ((upper - lower) / ma * , )  ma  ,
        })
     result

---

Layer 4: 基本面层

4.1 财报三表 — 东财 datacenter

东财 datacenter 提供美股/港股的资产负债表、利润表、现金流量表，中文字段名，按科目行展开。

def financial_statements_eastmoney(secucode: str, statement: str = "balance",
                                     page_size: int = 200) -> list[dict]:
    """
    东财 datacenter 财报三表
    secucode: "AAPL.O" (NASDAQ) / "BABA.N" (NYSE) / "00700.HK" (港股)
    statement: "balance" / "income" / "cashflow"
    返回: [{ITEM_NAME, AMOUNT, YOY_RATIO, REPORT, REPORT_DATE, ...}, ...]
    
    注意: 数据按科目行展开，每行一个科目（如"流动资产合计"、"营业收入"等），
    同一期报告有多行。用 REPORT_DATE 分组可还原整张报表。
    """
    # 报表名映射（注意命名不统一：balance/income 用 F10，cashflow 用 SK）
    report_map = {
        "balance": {"us": "RPT_USF10_FN_BALANCE", "hk": "RPT_HKF10_FN_BALANCE"},
        "income":  {"us": "RPT_USF10_FN_INCOME",  "hk": "RPT_HKF10_FN_INCOME"},
        "cashflow": {"us": "RPT_USSK_FN_CASHFLOW", "hk": "RPT_HKSK_FN_CASHFLOW"},
    }
    
    market = "hk" if secucode.endswith(".HK") else "us"
    report_name = report_map[statement][market]
    
    return eastmoney_datacenter(
        report_name=report_name,
        filter_str=f'(SECUCODE="{secucode}")',
        page_size=page_size,
        sort_columns="REPORT_DATE",
        sort_types="-1",
    )
    # 每行字段:
    # SECUCODE, SECURITY_CODE, SECURITY_NAME_ABBR, REPORT_DATE,
    # STD_ITEM_CODE, ITEM_NAME (科目名), AMOUNT (金额),
    # YOY_RATIO (同比%), REPORT (如 "2026/Q2"), REPORT_TYPE,
    
    

4.2 关键财务指标(中文) — 东财 GMAININDICATOR

东财 datacenter 的 GMAININDICATOR 报表，提供中文关键财务指标概览。美股 49 字段、港股 75 字段，包含 ROE/ROA/EPS/毛利率/资产负债率/流动比率等，按季度报告。

def key_indicators_eastmoney(secucode: str, page_size: int = 4) -> list[dict]:
    """
    东财 GMAININDICATOR 关键财务指标（中文）
    secucode: "AAPL.O" (NASDAQ) / "BABA.N" (NYSE) / "00700.HK" (港股)
    page_size: 返回最近几期报告（默认4期=一年）
    返回: [{REPORT_DATE, OPERATE_INCOME, BASIC_EPS, ROE_AVG, ROA, ...}, ...]
    
    美股核心字段(49): OPERATE_INCOME(营收), GROSS_PROFIT(毛利), GROSS_PROFIT_RATIO(毛利率%),
      PARENT_HOLDER_NETPROFIT(归母净利), NET_PROFIT_RATIO(净利率%), BASIC_EPS, DILUTED_EPS,
      ROE_AVG(平均ROE%), ROA(%), CURRENT_RATIO(流动比率), DEBT_ASSET_RATIO(资产负债率%),
      OPERATE_INCOME_YOY(营收同比%), BASIC_EPS_YOY(EPS同比%)
    
    港股额外字段(75): BPS(每股净资产), ROIC(投入资本回报率), EQUITY_RATIO(产权比率),
      HOLDER_PROFIT(股东应占溢利), OCF_SALES(经营现金流/营收%), DPS_HKD(每股股息),
      DIVI_RATIO(股息率%), PER_NETCASH_OPERATE(每股经营现金流)
    """
    market = "hk" if secucode.endswith(".HK") else "us"
    report_name = f"RPT_{'HK' if market == 'hk' else 'US'}F10_FN_GMAININDICATOR"
    
    return eastmoney_datacenter(
        report_name=report_name,
        filter_str=f'(SECUCODE="{secucode}")',
        page_size=page_size,
        sort_columns="REPORT_DATE",
        sort_types="-1",
    )

4.3 关键财务指标(英文) — Yahoo quoteSummary

Yahoo quoteSummary 的 financialData + defaultKeyStatistics 模块提供最核心的估值指标。

def key_statistics(symbol: str) -> dict:
    """
    Yahoo 关键财务指标
    symbol: "AAPL" (美股) 或 "0700.HK" (港股)
    返回: PE/PB/EV/EBITDA/利润率/目标价/ROE/Beta 等
    """
    data = yahoo_quote_summary(symbol, ["financialData", "defaultKeyStatistics", "summaryDetail"])
    
    fd = data.get("financialData", {})
    ks = data.get("defaultKeyStatistics", {})
    sd = data.get("summaryDetail", {})
    
    def _val(d, key):
        v = d.get(key, {})
        return v.get("raw") if isinstance(v, dict) else v
    
    return {
        # 价格相关
        "current_price": _val(fd, "currentPrice"),
        "target_high": _val(fd, "targetHighPrice"),
        "target_low": _val(fd, "targetLowPrice"),
        "target_mean": _val(fd, "targetMeanPrice"),
        "recommendation": fd.get("recommendationKey"),  # buy/hold/sell
        
        # 估值指标
        "trailing_pe": _val(sd, "trailingPE"),
        "forward_pe": _val(ks, "forwardPE"),
        "peg_ratio": _val(ks, "pegRatio"),
        "price_to_book": _val(ks, "priceToBook"),
        "enterprise_value": _val(ks, ),
        : _val(ks, ),
        : _val(ks, ),
        
        
        : _val(ks, ),
        : _val(fd, ),
        : _val(fd, ),
        : _val(fd, ),
        : _val(fd, ),
        
        
        : _val(fd, ),
        : _val(fd, ),
        
        
        : _val(ks, ),
        : _val(ks, ),
        
        
        : _val(sd, ),
        : _val(ks, ),
        
        
        : _val(sd, ),
        : _val(fd, ),
        : _val(fd, ),
        : _val(fd, ),
    }

4.4 分析师预期与评级 — Yahoo quoteSummary

def analyst_estimates(symbol: str) -> dict:
    """
    Yahoo 分析师预期 — EPS预测/评级趋势/升降级历史
    symbol: "AAPL" 或 "0700.HK"
    """
    data = yahoo_quote_summary(symbol, [
        "earningsTrend", "recommendationTrend", "upgradeDowngradeHistory",
        "earnings", "earningsHistory",
    ])
    
    # EPS 趋势
    et = data.get("earningsTrend", {}).get("trend", [])
    eps_trend = []
    for t in et:
        eps_trend.append({
            "period": t.get("period"),
            "end_date": t.get("endDate"),
            "eps_estimate": t.get("earningsEstimate", {}).get("avg", {}).get("raw"),
            "eps_high": t.get("earningsEstimate", {}).get("high", {}).get("raw"),
            "eps_low": t.get("earningsEstimate", {}).get("low", {}).get("raw"),
            "revenue_estimate": t.get("revenueEstimate", {}).get("avg", {}).get("raw"),
            "num_analysts": t.get("earningsEstimate", {}).get("numberOfAnalysts", {}).get("raw"),
        })
    
    # 评级趋势 (最近4个月)
    rt = data.get("recommendationTrend", {}).get("trend", [])
    rating_trend = []
    for r_  rt:
        rating_trend.append({
            : r_.get(),
            : r_.get(),
            : r_.get(),
            : r_.get(),
            : r_.get(),
            : r_.get(),
        })
    
    
    udh = data.get(, {}).get(, [])[:]
    upgrades = []
     u  udh:
        upgrades.append({
            : u.get(),
            : u.get(),
            : u.get(),
            : u.get(),
            : u.get(),  
        })
    
     {
        : eps_trend,
        : rating_trend,
        : upgrades,
    }

4.5 机构持仓 — Yahoo quoteSummary

def institutional_holders(symbol: str) -> dict:
    """
    Yahoo 机构持仓 — 前10大机构 + 内部人持股比例
    symbol: "AAPL" 或 "0700.HK"
    """
    data = yahoo_quote_summary(symbol, ["institutionOwnership", "majorHoldersBreakdown"])
    
    # 持股比例总览
    mhb = data.get("majorHoldersBreakdown", {})
    def _val(d, key):
        v = d.get(key, {})
        return v.get("raw") if isinstance(v, dict) else v
    
    overview = {
        "insiders_pct": _val(mhb, "insidersPercentHeld"),
        "institutions_pct": _val(mhb, "institutionsPercentHeld"),
        "institutions_float_pct": _val(mhb, "institutionsFloatPercentHeld"),
        "institutions_count": _val(mhb, "institutionsCount"),
    }
    
    # 前10大机构
    io = data.get("institutionOwnership", {}).get("ownershipList", [])
    top_holders = []
    for h in io[:10]:
        top_holders.append({
            "name": h.get("organization"),
            "shares": _val(h, "position"),
            "value": _val(h, "value"),
            "pct_held": _val(h, "pctHeld"),
            "report_date": h.get("reportDate", {}).get("fmt")  (h.get(), )  ,
        })
    
     {: overview, : top_holders}

4.6 年度/季度财报明细 — Yahoo quoteSummary

东财 datacenter 按科目行展开，Yahoo 直接返回完整报表结构，两个互补。

def financial_statements_yahoo(symbol: str,
                                 quarterly: bool = False) -> dict:
    """
    Yahoo 财报三表 — 结构化完整报表
    symbol: "AAPL" 或 "0700.HK"
    quarterly: False=年度, True=季度
    返回: {"income": [...], "balance": [...], "cashflow": [...]}
    """
    suffix = "Quarterly" if quarterly else ""
    data = yahoo_quote_summary(symbol, [
        f"incomeStatementHistory{suffix}",
        f"balanceSheetHistory{suffix}",
        f"cashflowStatementHistory{suffix}",
    ])
    
    def _extract(statements):
        result = []
        for stmt in statements:
            row = {}
            for k, v in stmt.items():
                if isinstance(v, dict) and "raw" in v:
                    row[k] = v["raw"]
                elif isinstance(v, dict) and "fmt" in v:
                    row[k] = v["fmt"]
                else:
                    row[k] = v
            result.append(row)
        return result
    
    income_key = f"incomeStatementHistory{suffix}"
    balance_key = f"balanceSheetHistory{suffix}"
    cashflow_key = 
    
     {
        : _extract(data.get(income_key, {}).get(, [])),
        : _extract(data.get(balance_key, {}).get(, [])),
        : _extract(data.get(cashflow_key, {}).get(, [])),
    }

---

Layer 5: 资金面层

5.1 日级资金流 — 东财 push2his

def fund_flow_daily(ticker_or_code: str, secid_prefix: int = 105,
                      limit: int = 100) -> list[dict]:
    """
    东财 push2his 日级资金流 — 主力/大单/中单/小单净流入
    美股: fund_flow_daily("AAPL", 105)  # NASDAQ
          fund_flow_daily("BABA", 106)  # NYSE
    港股: fund_flow_daily("00700", 116)
    返回: [{date, main_net, big_net, mid_net, small_net, main_pct, ...}, ...]
    """
    url = "https://push2his.eastmoney.com/api/qt/stock/fflow/daykline/get"
    params = {
        "secid": f"{secid_prefix}.{ticker_or_code}",
        "klt": 101,
        "fields1": "f1,f2,f3,f7",
        "fields2": "f51,f52,f53,f54,f55,f56,f57",
        "lmt": limit,
    }
    r = requests.get(url, params=params, timeout=15)
    d = r.json()
    data = d.get("data")
    if not data or not data.get("klines"):
        return []
    
    result = []
    for line in data["klines"]:
        parts = line.split(",")
        # f51=日期, f52=主力净流入, f53=小单净流入, f54=中单净流入, f55=大单净流入, f56=超大单净流入
        result.append({
            "date": parts[0],
            "main_net": float(parts[1]),       # 主力净流入（元）
            "small_net": float(parts[]),       
            : (parts[]),         
            : (parts[]),         
            : (parts[]),   
            : (parts[])  (parts) >   parts[]  ,  
        })
     result

---

Layer 6: 期权层

6.1 期权链 + 希腊字母 + 0DTE 流 — CBOE 官方（主力 ⭐ V2.0 新增）

数据源 cdn.cboe.com，零鉴权。单只标的全链一次返回（实测 NVDA 3,908 / TSLA 6,200 / AAPL 3,576 合约）， 字段含 bid/ask/volume/open_interest/iv/delta/gamma/vega/theta/rho。

⚠️ 合规（C 级）：Cboe 的 Use of Content 政策要求使用前取得书面批准与 license。 以下代码仅供个人研究；商业用途或再分发前须先向 Cboe 申请授权。

import re
from datetime import datetime, timezone, timedelta
# 依赖「官方源统一出口」的 official_get / assert_us_ticker

CBOE_BASE = "https://cdn.cboe.com/api/global/delayed_quotes"
# OCC 合约代码: 标的 + YYMMDD + C/P + 8位行权价(千分之一美元)
# root 允许含数字：拆股/分拆等公司行为会产生调整后合约（如 NVDA1、BRKB1）。
# 后面全是定宽组（6+1+8=15 字符），正则回溯能正确对齐，标准合约解析结果不变。
_OSI = re.compile(r"^(?P<root>[A-Z][A-Z0-9]*)(?P<y>\d{2})(?P<m>\d{2})(?P<d>\d{2})"
                  r"(?P<cp>[CP])(?P<strike>\d{8})$")


def parse_osi(symbol: str) -> dict:
    """解析 OCC 合约代码 → {expiry, type, strike}；无法解析返回 {}"""
    m = _OSI.match(symbol)
    if not m:
        return {}
    g = m.groupdict()
    return {"expiry": f"20{g['y']}-{g['m']}-{g['d']}",
            "type": "call" if g["cp"] == "C" else "put",
            "strike": int(g["strike"]) / 1000.0}


def options_chain_cboe(ticker: str) -> dict:
    """
    CBOE 官方延时期权全链（仅美股）。
    返回 {"ticker","timestamp","spot","contracts":[{symbol,expiry,type,strike,bid,ask,
          volume,open_interest,iv,delta,gamma,vega,theta,rho,last_trade_price}]}
    """
    ticker = assert_us_ticker(ticker)
    raw = official_get(, as_json=)
    data = raw.get()  {}
    contracts = []
     o  data.get()  []:
        meta = parse_osi(o.get(, ))
          meta:
            
        contracts.append({
            : o[], **meta,
            : o.get(), : o.get(),
            : o.get()  ,
            : o.get()  ,
            : o.get(), : o.get(), : o.get(),
            : o.get(), : o.get(), : o.get(),
            : o.get(),
        })
      contracts:
         DataNotAvailable(
                               )
     {: ticker, : raw.get(),
            : data.get(), : contracts}


:
     zoneinfo  ZoneInfo
    _ET_TZ = ZoneInfo()
 Exception:      
    _ET_TZ = 


 () -> :
    
    now = datetime.now(timezone.utc)
     _ET_TZ   :
         now.astimezone(_ET_TZ).strftime()
    
    y = now.year
    
    
    
    
    mar8 = datetime(y, , , tzinfo=timezone.utc)
    dst_start = (mar8 + timedelta(days=( - mar8.weekday()) % )
                 ).replace(hour=)
    nov1 = datetime(y, , , tzinfo=timezone.utc)
    dst_end = (nov1 + timedelta(days=( - nov1.weekday()) % )
               ).replace(hour=)
    offset =   dst_start <= now < dst_end  
     (now - timedelta(hours=offset)).strftime()


 () -> []:
    
    cs = chain[]
     expiry == :
         [c  c  cs  c[] == _et_today()]
     expiry:
         [c  c  cs  c[] == expiry]
     dte_max   :
        today = datetime.strptime(_et_today(), )
         [c  c  cs
                  <= (datetime.strptime(c[], ) - today).days <= dte_max]
     cs


 () -> []:
    
    out = []
     c  contracts:
        vol, oi = c[], c[]
         vol < min_volume:
            
        ratio = vol / oi  oi >   ()
         ratio >= vol_oi_min:
            out.append({**c, : (ratio, )  oi >   })
     (out, key= x: -x[])


 () -> :
    
    calls = [c  c  contracts  c[] == ]
    puts = [c  c  contracts  c[] == ]
    cv, pv = (c[]  c  calls), (c[]  c  puts)
    coi, poi = (c[]  c  calls), (c[]  c  puts)
    traded = [c  c  contracts  c[] >   c.get()]
    tot_v = (c[]  c  traded)
    vwiv = (c[] * c[]  c  traded) / tot_v  tot_v  
    net_delta = ((c.get()  ) * c[] *   c  contracts)
     {: cv, : pv,
            : (pv / cv, )  cv  ,
            : coi, : poi,
            : (poi / coi, )  coi  ,
            : (vwiv, )  vwiv  ,
            : (net_delta),
            : (contracts),
            : ([c  c  contracts  c[] > ])}


 () -> :
    
     official_get(,
                        as_json=)[]

用法

chain = options_chain_cboe("NVDA")
zero  = filter_expiry(chain, expiry="0DTE")      # 当日到期合约
near  = filter_expiry(chain, dte_max=7)          # 7 日内到期
flow  = unusual_activity(zero, min_volume=1000)  # 0DTE 异动
summ  = chain_summary(zero)                      # P/C 比、加权 IV、净 delta

实测样本（2026-07-24）

标的	全链	0DTE 合约	P/C 量比	量加权 IV	净 delta 敞口
NVDA	3,908	168	0.542	43.1%	+16,496,611 股
TSLA	6,200	326	1.041	83.2%	−37,364,065 股

TSLA 当日 −14.52%，期权层三个指标（put 占优 / IV 83% / 净 delta 为负）独立指向同一方向，可交叉验证。

⚠️ 限制：CBOE 端点仅覆盖美股（港股期权需港交所专有接口）；数据为延时， 不适用于实盘下单，适用于研究与流向分析。

---

6.2 期权链 — Yahoo Finance（后备 · 无希腊字母）

def options_chain(symbol: str, expiration: int = None) -> dict:
    """
    Yahoo 期权链 — calls + puts 完整数据（仅美股）
    symbol: "AAPL", "TSLA" 等美股 ticker
    ⚠️ 港股(如0700.HK)期权不在Yahoo覆盖范围，调用会返回空列表
    expiration: Unix timestamp (不传则返回最近到期日 + 所有到期日列表)
    返回: {"expiration_dates": [...], "calls": [...], "puts": [...]}
    """
    s = get_yahoo_session()
    params = {"crumb": s._crumb}
    if expiration:
        params["date"] = expiration
    
    r = s.get(f"https://query2.finance.yahoo.com/v7/finance/options/{symbol}",
              params=params, timeout=15)
    r.raise_for_status()
    
    oc = r.json().get("optionChain", {}).get("result", [{}])[0]
    
    exp_dates = oc.get("expirationDates", [])
    options = oc.get("options", [{}])[0] if oc.get("options") else {}
    
    def _parse_options(opts):
        result = []
        for o in opts:
            def _val(key):
                v = o.get(key, {})
                return v.get("raw") if isinstance(v, dict) else v
            result.append({
                "strike": _val("strike"),
                "last_price": _val("lastPrice"),
                "bid": _val("bid"),
                : _val(),
                : _val(),
                : _val(),
                : _val(),
                : o.get(),
                : o.get(, {}).get()  (o.get(), )  ,
                : o.get(),
            })
         result
    
     {
        : exp_dates,  
        : _parse_options(options.get(, [])),
        : _parse_options(options.get(, [])),
        : oc.get(, {}).get(),
    }

---

Layer 7: SEC Filing 层（仅美股）

7.1 SEC Filing 列表 — EDGAR submissions

SEC_HEADERS = {"User-Agent": "SimonLin global-stock-data/1.0 ([e-mail])"}

def sec_filings(cik: str, form_type: str = None) -> dict:
    """
    SEC EDGAR Filing 列表
    cik: CIK号（10位补零），如 "0000320193" (Apple)
         可通过 ticker_to_cik() 从 ticker 转换
    form_type: 筛选类型，如 "10-K", "10-Q", "8-K"（不传返回全部）
    返回: {"company_name": ..., "filings": [{form, date, accession_number, primary_document}, ...]}
    """
    url = f"https://data.sec.gov/submissions/CIK{cik}.json"
    r = requests.get(url, headers=SEC_HEADERS, timeout=15)
    r.raise_for_status()
    
    data = r.json()
    recent = data.get("filings", {}).get("recent", {})
    
    forms = recent.get("form", [])
    dates = recent.get("filingDate", [])
    accessions = recent.get("accessionNumber", [])
    primary_docs = recent.get("primaryDocument", [])
    descriptions = recent.get("primaryDocDescription", [])
    
    filings = []
    for i in range(len(forms)):
        if form_type and forms[i] != form_type:
            continue
        filings.append({
            "form": forms[i],
            "date": dates[i],
            "accession_number": accessions[i],
            "primary_document": primary_docs[i] if i < len(primary_docs) else "",
            "description": descriptions[i] if i < len(descriptions) else ,
            :   i < (primary_docs)  primary_docs[i]  ,
        })
    
     {
        : data.get(),
        : cik,
        : data.get(, [])[]  data.get()  ,
        : filings[:],  
    }

7.2 SEC XBRL 结构化财务数据 — EDGAR companyfacts

覆盖 503 个 GAAP 指标，可精确提取多年营收/净利/EPS/资产/负债等。

def sec_xbrl_facts(cik: str, metrics: list[str] = None) -> dict:
    """
    SEC EDGAR XBRL 结构化财务数据
    cik: CIK号（10位补零）
    metrics: 要提取的指标名，如 ["RevenueFromContractWithCustomerExcludingAssessedTax",
             "NetIncomeLoss", "EarningsPerShareDiluted"]
             不传则返回所有可用指标名列表
    
    返回: {"company": ..., "metrics": {"Revenue": [{end, val, form, filed}, ...], ...}}
    """
    url = f"https://data.sec.gov/api/xbrl/companyfacts/CIK{cik}.json"
    r = requests.get(url, headers=SEC_HEADERS, timeout=15)
    r.raise_for_status()
    
    facts = r.json()
    us_gaap = facts.get("facts", {}).get("us-gaap", {})
    
    # 如果不传 metrics，返回所有可用指标
    if not metrics:
        available = []
        for k, v in us_gaap.items():
            label = v.get("label", k)
            units = list(v.get("units", {}).keys())
            available.append({"name": k, "label": label, "units": units})
        return {
            "company": facts.get("entityName"),
            "total_metrics": len(available),
            "available_metrics": available,
        }
    
    # 提取指定指标
    result = {}
    for metric_name in metrics:
        metric = us_gaap.get(metric_name, {})
        if not metric:
            result[metric_name] = []
            continue
        
        # 自动选择单位（USD 或 USD/shares）
        units = metric.get("units", {})
        unit_key =     units  (units.keys())[]  units  
          unit_key:
            result[metric_name] = []
            
        
        entries = units[unit_key]
        
        filtered = [e  e  entries  e.get()  (, )]
        result[metric_name] = [{
            : e.get(),
            : e.get(),
            : e.get(),
            : e.get(),
            : e.get(),
            : e.get(),
        }  e  filtered[-:]]  
    
     {
        : facts.get(),
        : result,
    }

常用 XBRL 指标名速查：

指标	XBRL 名
营业收入	RevenueFromContractWithCustomerExcludingAssessedTax 或 Revenues
净利润	NetIncomeLoss
稀释 EPS	EarningsPerShareDiluted
基本 EPS	EarningsPerShareBasic
总资产	Assets
总负债	Liabilities
股东权益	StockholdersEquity
经营现金流	NetCashProvidedByOperatingActivities
研发费用	ResearchAndDevelopmentExpense
股份回购	PaymentsForRepurchaseOfCommonStock
股息支付	PaymentsOfDividends

---

Layer 8: 工具层

8.1 股票搜索 — 东财 search API

def stock_search(keyword: str, count: int = 10) -> list[dict]:
    """
    东财股票搜索 — 支持中英文，返回代码+市场+中文名
    keyword: "AAPL" / "苹果" / "Tencent" / "00700" / "特斯拉"
    返回: [{code, name, mkt_num, market_name, security_type}, ...]
    
    mkt_num 即 push2/push2his 的 secid 前缀:
    105=NASDAQ, 106=NYSE, 107=美股ETF, 116=港股
    """
    url = "https://searchapi.eastmoney.com/api/suggest/get"
    params = {
        "input": keyword,
        "type": 14,  # 14=全球市场
        "token": "D43BF722C8E33BDC906FB84D85E326E8",
        "count": count,
    }
    r = requests.get(url, params=params, timeout=10)
    d = r.json()
    
    suggestions = d.get("QuotationCodeTable", {}).get("Data", [])
    result = []
    for s in suggestions:
        mkt = s.get("MktNum", "")
        # 只保留美股和港股
        if str(mkt) not in ("105", "106", "107", "116"):
            continue
        
        market_map = {"105": "NASDAQ", "106": "NYSE", "107": "US_OTHER", "116": "HK"}
        result.append({
            "code": s.get("Code"),
            "name": s.get(),
            : (mkt),
            : market_map.get((mkt), (mkt)),
            : s.get(),
        })
     result

8.2 股票新闻 — Yahoo Finance search

def stock_news(keyword: str, count: int = 10) -> list[dict]:
    """
    Yahoo Finance 新闻搜索
    keyword: 股票代码或关键词，如 "AAPL", "Tesla", "0700.HK"
    返回: [{title, publisher, link, publish_time, thumbnail}, ...]
    注意: 需要先获取 Yahoo cookie 才能调用，否则返回 400
    """
    s = requests.Session()
    s.headers["User-Agent"] = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
    s.get("https://fc.yahoo.com", timeout=10)  # 获取 cookie
    
    url = "https://query2.finance.yahoo.com/v1/finance/search"
    params = {"q": keyword, "quotesCount": 0, "newsCount": count}
    r = s.get(url, params=params, timeout=10)
    r.raise_for_status()
    
    news = r.json().get("news", [])
    result = []
    for n in news:
        result.append({
            "title": n.get("title"),
            "publisher": n.get("publisher"),
            "link": n.get("link"),
            "publish_time": n.get("providerPublishTime"),
            "thumbnail": n.get("thumbnail", {}).get("resolutions", [{}])[0].get("url") if n.get("thumbnail") else None,
        })
    return result

8.3 Ticker → CIK 映射 — SEC EDGAR（仅美股）

_cik_cache = None

def ticker_to_cik(ticker: str) -> dict:
    """
    SEC EDGAR ticker → CIK 映射
    ticker: 如 "AAPL", "TSLA", "MSFT"
    返回: {"ticker": "AAPL", "cik": "0000320193", "company": "Apple Inc."}
    
    首次调用下载完整映射表(~10KB JSON, 10000+公司)并缓存。
    """
    global _cik_cache
    if not _cik_cache:
        r = requests.get("https://www.sec.gov/files/company_tickers.json",
                         headers=SEC_HEADERS, timeout=15)
        r.raise_for_status()
        _cik_cache = r.json()
    
    ticker_upper = ticker.upper()
    for _, v in _cik_cache.items():
        if v.get("ticker") == ticker_upper:
            cik_str = str(v["cik_str"]).zfill(10)
            return {
                "ticker": ticker_upper,
                "cik": cik_str,
                "company": v.get("title"),
            }
    return {}

8.4 全市场股票列表 — 东财 push2

def market_stock_list(market: str = "us_nasdaq", sort_field: str = "f3",
                       sort_desc: bool = True, page: int = 1,
                       page_size: int = 20) -> dict:
    """
    东财 push2 全市场股票列表 — 涨跌幅/成交量/成交额排名
    market: "us_nasdaq" (m:105), "us_nyse" (m:106), "hk" (m:116)
    sort_field: 排序字段
      f3=涨跌幅, f5=成交量, f6=成交额, f2=最新价, f7=振幅, f15=最高, f16=最低
    sort_desc: True=降序(默认), False=升序
    page/page_size: 分页（默认第1页，每页20条）
    返回: {"total": 5925, "stocks": [{code, name, price, change_pct, volume, ...}, ...]}
    
    典型用途:
    - 今日涨幅 TOP 20: market_stock_list("us_nasdaq", "f3", True)
    - 今日跌幅 TOP 20: market_stock_list("us_nasdaq", "f3", False)
    - 成交量 TOP 20: market_stock_list("hk", "f5", True)
    - 遍历全市场: 循环 page=1..N, 每页100条做筛选
    """
    market_map = {"us_nasdaq": "m:105", "us_nyse": "m:106", "us_etf": "m:107", "hk": "m:116"}
    fs = market_map.get(market, market)
    
    url = "https://push2.eastmoney.com/api/qt/clist/get"
    params = {
        "fs": fs,
        "fields": "f2,f3,f4,f5,f6,f7,f12,f14,f15,f16,f17,f18",
        "pn": page,
        "pz": page_size,
        "fid": sort_field,
        "po": 1 if sort_desc else 0,
    }
    r = requests.get(url, params=params, timeout=15)
    d = r.json()
    data = d.get("data", {})
    
    total = data.get("total", 0)
    diff = data.get(, [])
    
    
     (diff, ):
        diff = (diff.values())
    
    stocks = []
     item  diff:
        stocks.append({
            : item.get(),         
            : item.get(),         
            : item.get(),         
            : (item[] / , )  item.get()     ,  
            : item.get(), 
            : item.get(),        
            : item.get(),        
            : (item[] / , )  item.get()     ,  
            : item.get(),         
            : item.get(),          
            : item.get(),         
            : item.get(),   
        })
    
     {: total, : stocks}

---

Layer 9: 做空层 — FINRA Reg SHO（B 级 ⭐ V2.0 新增 · 仅美股）

全市场每日空头成交量，A 股无对应品类。单个文件覆盖全市场（实测 12,112 只）。

⚠️ 合规（B 级）：Reg SHO 每日文件是 FINRA 主动发布供下载的监管披露文件，直接下载属常规用法； 但其站点条款禁止批量爬取页面，且声明数据为 non-commercial use。商用前请自行向 FINRA 确认。

from datetime import datetime, timedelta
# 依赖「官方源统一出口」的 official_get


def _recent_weekdays(days_back: int = 7) -> list[str]:
    d, out = datetime.now(), []
    while len(out) < days_back:
        if d.weekday() < 5:
            out.append(d.strftime("%Y%m%d"))
        d -= timedelta(days=1)
    return out


def short_volume_all(date: str = None, market: str = "CNMS") -> dict:
    """
    FINRA 全市场每日空头成交量。
    market: CNMS(合并全市场) / FNSQ(Nasdaq) / FNYX(NYSE) / FNRA(TRF)
    date: YYYYMMDD；不传则自动回退找最近有数据的交易日
    返回 {"date","market","count","data":{SYMBOL:{short,short_exempt,total,ratio}}}
    """
    for d in ([date] if date else _recent_weekdays(7)):
        try:
            raw = official_get(
                f"https://cdn.finra.org/equity/regsho/daily/{market}shvol{d}.txt")
        except DataNotAvailable:
            continue   # 该日无文件（非交易日/尚未发布），回退下一日
        # 其余异常（网络/限流/配置）直接抛出，不伪装成「没数据」
        rows = {}
        for line in raw.splitlines()[1:]:
            p = line.split("|")
            if len(p) <    p[]:
                
            :
                sv, se, tv = (p[]), (p[]), (p[])
             ValueError:
                
            rows[p[]] = {: sv, : se, : tv,
                          : (sv / tv, )  tv  }
         rows:
             {: d, : market, : (rows), : rows}
    
    
     DataNotAvailable(
                           )


 () -> []:
    
    out = []
     d  _recent_weekdays(days * ):
         (out) >= days:
            
        :
            snap = short_volume_all(date=d, market=market)
         DataNotAvailable:
            
        rec = snap[].get(symbol.upper())
         rec:
            out.append({: d, **rec})
     out


 () -> []:
    
    rows = [{: s, **v}  s, v  snapshot[].items()
             v[] >= min_total  v[]   ]
     (rows, key= x: -x[])[:top]

实测（2026-07-23，覆盖 12,112 只）：NVDA 空头占比 37.5% / TSLA 48.3% / MU 49.6% / AAPL 50.7%； NVDA 近三日 37.5% → 43.0% → 33.5%。

⚠️ 读法：short volume ≠ short interest。前者是当日卖出成交里被标记为空头的部分 （含做市商对冲，天然偏高，40%~50% 常见），后者是未平仓空头存量（双月披露）。 用它看日度变化趋势，不要用绝对值下结论。

---

Layer 10: 申报事件流 — SEC EDGAR（S 级 ⭐ V2.0 新增 · 仅美股）

✅ 合规（S 级）：本工具唯一无争议的可商用源。官方明示允许脚本访问、数据免费。 10 requests/second 是官方硬上限，且必须声明 User-Agent（已由统一出口处理，记得改 SEC_CONTACT）。

10.1 每日申报流（Form 4 内部人 / 8-K / 13F 机构持仓）

_FORM_LABEL = {"4": "内部人交易", "8-K": "重大事件", "13F-HR": "机构持仓",
               "144": "限售股拟出售", "10-K": "年报", "10-Q": "季报",
               "SC 13D": "举牌(主动)", "SC 13G": "举牌(被动)", "S-1": "IPO注册"}


def daily_filings(date: str = None, forms: list[str] = None) -> dict:
    """
    EDGAR 每日申报流。date=YYYYMMDD，不传自动回退找最近有数据的日子。
    forms: 只保留这些表单类型，如 ["4","8-K","13F-HR"]；None=全部
    返回 {"date","total","by_form":{...},"filings":[{form,form_label,company,cik,date,url}]}
    """
    for d in ([date] if date else _recent_weekdays(7)):
        dt = datetime.strptime(d, "%Y%m%d")
        url = (f"https://www.sec.gov/Archives/edgar/daily-index/"
               f"{dt.year}/QTR{(dt.month - 1) // 3 + 1}/form.{d}.idx")
        try:
            raw = official_get(url)
        except DataNotAvailable:
            continue   # 该日无索引文件，回退下一日
        # 配置错误（SEC_CONTACT 未改）与网络错误在此直接抛出——
        # 否则会被 7 次循环吞掉，最终误报成「未找到 EDGAR 每日索引」
        lines = raw.splitlines()
        start = ((i +   i, L  (lines)  L.startswith()), )
        filings, by_form = [], {}
         L  lines[start:]:
             (L) < :
                
            form, company = L[:].strip(), L[:].strip()
            cik, filed, path = L[:].strip(), L[:].strip(), L[:].strip()
              form:
                
            by_form[form] = by_form.get(form, ) + 
             forms  form   forms:
                
            filings.append({: form, : _FORM_LABEL.get(form, ),
                            : company, : cik, : filed,
                            :   path  })
         by_form:
             {: d, : (by_form.values()),
                    : ((by_form.items(), key= x: -x[])),
                    : filings}
     DataNotAvailable()

实测（2026-07-23，当日 3,703 份）：424B2=627 / Form 4 内部人=547 / 8-K=370 / 13F-HR=261 / D=204 / 144=118。

10.2 全文检索（覆盖 2001 年至今所有申报正文）

def fulltext_search(query: str, forms: str = None, date_from: str = None,
                    date_to: str = None, limit: int = 20) -> dict:
    """
    query: 加引号为精确短语，如 '"HBM4"'
    forms: "8-K" / "10-K" 等；date_from/to: YYYY-MM-DD
    """
    p = {"q": query, "from": 0, "size": limit}
    if forms:
        p["forms"] = forms
    if date_from:
        p["dateRange"], p["startdt"] = "custom", date_from
    if date_to:
        p["dateRange"], p["enddt"] = "custom", date_to
    j = official_get("https://efts.sec.gov/LATEST/search-index", params=p, as_json=True)
    hits = (j.get("hits") or {}).get("hits") or []
    return {"total": ((j.get("hits") or {}).get("total") or {}).get("value", 0),
            "results": [{"form": (h.get("_source") or {}).get("root_form"),
                         "company": ((h.get("_source")  {}).get()  [])[],
                         : (h.get()  {}).get(),
                         : h.get()}  h  hits]}

实测：fulltext_search('"HBM4"', forms="8-K") → 命中 5 条，含 MICRON (MU) 2026-06-24、 AMD 2026-05-05。→ 可用于追踪某个技术名词/产品代号首次出现在哪家公司的正式申报里。

---

Layer 11: 全市场横截面 — EDGAR frames（S 级 ⭐ V2.0 新增 · 免费 screener）

一次请求拿到所有申报公司某个指标某期的值。实测「研发费用 CY2025Q1」覆盖 1,842 家、 「净利润 CY2025Q1」覆盖 5,309 家。

XBRL_TAGS = {
    "营业收入": "Revenues",
    "营业收入(合同)": "RevenueFromContractWithCustomerExcludingAssessedTax",
    "净利润": "NetIncomeLoss",
    "研发费用": "ResearchAndDevelopmentExpense",
    "毛利": "GrossProfit",
    "经营利润": "OperatingIncomeLoss",
    "总资产": "Assets",
    "股东权益": "StockholdersEquity",
    "现金及等价物": "CashAndCashEquivalentsAtCarryingValue",
    "经营现金流": "NetCashProvidedByUsedInOperatingActivities",
    "资本开支": "PaymentsToAcquirePropertyPlantAndEquipment",
    "长期负债": "LongTermDebtNoncurrent",
    "稀释EPS": "EarningsPerShareDiluted",
}

# ⚠️ 时点(instant)概念 —— 资产负债表科目描述的是「某一时刻的余额」，而非一段期间的发生额。
# SEC Frames 对这类概念**要求周期带 I 后缀**，且**没有纯年度周期**：
#   Assets/CY2025Q1  -> 404      Assets/CY2025Q1I -> 200 (5643 家)
#   Assets/CY2024    -> 404      Assets/CY2024Q4I -> 200 (6248 家)
# 期间(duration)概念(营收/净利/现金流等)则相反，用 CY2025Q1 / CY2024。
# 以上均为 2026-07-26 逐个实测结果。
_INSTANT_TAGS = {
    "Assets",
    "StockholdersEquity",
    "CashAndCashEquivalentsAtCarryingValue",
    "LongTermDebtNoncurrent",
}


def _frame_period(year: int, quarter, instant: bool) -> str:
    """时点概念没有纯年度周期，年度请求落到 Q4I。"""
    if instant:
           quarter  
       quarter  


 () -> :
    
    tag = XBRL_TAGS.get(tag, tag)
    guess = (tag  _INSTANT_TAGS)  instant    instant
    attempts = [guess]  instant     [guess,  guess]

    last_err = 
     is_instant  attempts:
        period = _frame_period(year, quarter, is_instant)
        :
            j = official_get(
                ,
                timeout=, as_json=)
         DataNotAvailable  e:      
            last_err = e
            
        rows = [{: d.get(), : d.get(),
                 : d.get(), : d.get()}  d  j.get(, [])]
         {: tag, : period, : unit,
                : is_instant, : (rows), : rows}
     last_err


 () -> []:
     (frame[], key= x: x[], reverse= ascending)[:top]


 () -> []:
    
    out = frame[]
     min_value   :
        out = [r  r  out  r[] >= min_value]
     max_value   :
        out = [r  r  out  r[] <= max_value]
     out

实测：研发费用 CY2025Q1 → Alphabet $13.56B / Meta $12.15B / Apple $8.55B / 微软 $8.20B / NVDA $3.99B；研发 > $10 亿的共 17 家。

⚠️ 不同公司使用的 XBRL 标签口径不完全一致（如营收有 Revenues 与 RevenueFromContractWithCustomerExcludingAssessedTax 两种），做横截面对比时需交叉两个标签取并集。

---

Layer 12: 宏观 / 日历（S 级为主 ⭐ V2.0 新增）

import csv, io


def treasury_yield_curve(year: int = None) -> list[dict]:
    """美国国债收益率曲线（每日，1M~30Y）。政府数据，S 级。返回 [0] 为最新一日"""
    year = year or datetime.now().year
    url = ("https://home.treasury.gov/resource-center/data-chart-center/interest-rates/"
           f"daily-treasury-rates.csv/{year}/all?type=daily_treasury_yield_curve"
           f"&field_tdr_date_value={year}&page&_format=csv")
    return list(csv.DictReader(io.StringIO(official_get(url))))


def cftc_cot(limit: int = 20, market_contains: str = None) -> list[dict]:
    """CFTC 持仓报告(COT)。政府数据，S 级"""
    q = {"$limit": limit, "$order": "report_date_as_yyyy_mm_dd DESC"}
    if market_contains:
        q["$where"] = f"upper(contract_market_name) like upper('%{market_contains}%')"
    return official_get("https://publicreporting.cftc.gov/resource/6dca-aqww.json",
                        params=q, as_json=True)


def earnings_calendar(date: str = None) -> dict:
    """Nasdaq 财报日历。date=YYYY-MM-DD，不传取今天"""
    date = date or datetime.now().strftime()
    j = official_get(,
                     params={: date}, headers={: },
                     as_json=)
    rows = ((j.get()  {}).get())  []
     {: date, : (rows),
            : [{: r.get(), : r.get(),
                      : r.get(), : r.get(),
                      : r.get()}  r  rows]}

实测（2026-07-23/24）：收益率曲线 3M=3.95 / 2Y=4.37 / 10Y=4.71 / 30Y=5.17 （10Y−2Y=+0.34，未倒挂）；CFTC COT 最新报告日 2026-07-14；今日财报日历 41 家 （AXP 盘前 EPS 预期 $4.41、VZ、NEE、HCA…）。

---

数据源优先级

场景	第一优先	备选	说明
美股行情	新浪 gb_XXXX	腾讯 / 东财 push2	新浪有中文名+EPS+PE
港股行情	腾讯 r_hkXXXXX	新浪 / 东财 push2	腾讯字段最全(78个)
美股K线	新浪	Yahoo chart	新浪回溯至1984年；Yahoo支持多周期
港股K线	Yahoo chart	—	新浪港股K线已失效；push2his不返回港股K线
财报三表(中文)	东财 datacenter	—	中文科目名，按行展开
财报三表(结构化)	Yahoo quoteSummary	—	英文，完整报表结构
关键指标(中文)	东财 GMAININDICATOR	—	ROE/ROA/EPS/毛利率/资产负债率 (美49/港75字段)
关键指标(英文)	Yahoo quoteSummary	—	PE/PB/EV/利润率/目标价
分析师预期	Yahoo quoteSummary	—	EPS预测+评级+升降级
机构持仓	Yahoo quoteSummary	—	前10大机构+内部人
资金流	东财 push2his	—	日级主力/大单/中单/小单
期权链/希腊字母/IV/0DTE	CBOE 官方 ⭐	Yahoo options	CBOE 含 delta/gamma/vega/theta/rho；Yahoo 无希腊字母。仅美股。⚠️C 级需授权
异动 options flow	CBOE 官方 ⭐	—	unusual_activity()：vol/OI>1 = 新建仓
全市场每日空头量	FINRA Reg SHO ⭐	—	单文件覆盖全市场，仅美股。B 级
当日申报流(Form4/8-K/13F)	EDGAR 每日索引 ⭐	—	仅美股。S 级可商用
申报全文检索	EDGAR FTS ⭐	—	2001 至今正文。S 级可商用
全市场基本面横截面	EDGAR frames ⭐	—	免费 screener。S 级可商用
收益率曲线 / COT / 财报日历	Treasury / CFTC / Nasdaq ⭐

---

数据源汇总

数据源	合规级	协议	鉴权	覆盖
SEC EDGAR	S	HTTPS	零(需真实UA)	美股 Filing/XBRL/每日申报流/全文检索/全市场横截面
US Treasury	S	HTTPS	零	收益率曲线(1M~30Y)
CFTC	S	HTTPS	零	COT 持仓报告
FINRA	B	HTTPS	零	美股 每日空头成交量(全市场)（商用需自行确认）
CBOE	C	HTTPS	零	美股 期权全链+希腊字母+IV+0DTE（使用需 Cboe 事先授权）
Nasdaq	C	HTTPS	零	美股 财报日历（条款未核实）
东财 push2	C	HTTPS	零	美股+港股 实时行情+全市场列表
东财 push2his	C	HTTPS	零	美股+港股 资金流（K线仅A股，不覆盖美股/港股）
东财 datacenter	C	HTTPS	零	美股+港股 财报三表+GMAININDICATOR关键指标
东财 search API	C	HTTPS	零	全球股票搜索+secid映射
Yahoo Finance	C	HTTPS	cookie+crumb(自动)	美股+港股 全品类
新浪财经	C	HTTP	零	美股+港股 行情、美股K线
腾讯财经	C	HTTPS	零	美股+港股 行情

级别含义：S＝美国政府数据，可商用可再分发｜B＝主动公开的数据文件，商用需自行确认｜C＝需事先授权或条款未核实，仅个人研究。各级依据的条款原文见顶部「数据源合规分级」。

📦 https://github.com/simonlin1212/global-stock-data — Star ⭐ 是最好的支持