源码级核验：packages/marketdata + server.py DATA_SOURCE_SEEDS
PanWatch 的数据从哪来：11 类行情、主备降级规则与「未校准字段」清单
PanWatch 的行情不是「接一个接口」，而是一层可插拔的数据包：每类数据有多个厂商候选，按优先级尝试、失败就换下一个，并把每次成败记进健康度。本页把覆盖矩阵、默认源与优先级、降级行为与官方自己标注的未校准字段放在一起——最后这一项，几乎没有任何第三方介绍会提。
PanWatch 的 11 类数据 + 2 类特殊入口：每类有哪些厂商、覆盖哪些市场
官方 packages/marketdata/README.md 把 VENDOR_CLASSES_BY_TYPE 定义为权威清单——这是「某个类型到底能用哪些源」的权威依据，不是文档转述。
| 类型 | 含义 | 已实现厂商（覆盖市场） | 粒度 |
|---|---|---|---|
quote | 实时报价 | tencent（CN+HK+US）、sina（US+HK）、eastmoney（CN）、yfinance（HK+US，可选） | 按标的 |
kline | 日 K 线 | tencent（CN+HK+US）、eastmoney（CN+HK）、stooq（US）、yahoo（US+HK） | 按标的 |
capital_flow | 资金流向 | eastmoney（CN+HK+US）、sina（CN） | 按标的 |
events | 结构化事件（公告） | eastmoney（CN） | 按标的 |
flash_news | 7×24 快讯 | cls 财联社、sina、eastmoney（均 CN） | 市场级 |
fundamentals | 估值与财报指标 | tencent（CN）、eastmoney（CN+HK+US） | 按标的 |
dragon_tiger | 龙虎榜 | eastmoney（CN） | 市场级（单日快照） |
margin | 融资融券 | eastmoney（CN） | 按标的（最新一条） |
shareholders | 股东户数 | eastmoney（CN） | 按标的（最新一期） |
dividend | 分红送转 | eastmoney（CN） | 按标的（全部历史） |
northbound | 北向资金 | ths 同花顺（CN） | 市场级（当日末值） |
discovery（特殊） | 热门榜：个股 / 板块 / 板块成分 | eastmoney 单源，直连不走 Engine | 市场级 |
index（特殊） | 指数行情与指数日 K | 行情走腾讯原始符号；日 K 仅映射过的指数（沪深300/上证/深成指/创业板指/恒生） | 市场级 |
PanWatch 一次取数失败之后会发生什么：主备链与降级规则
PanWatch 官方把数据包的路径描述为「一条路径，两层」，核心规则只有四条，但决定了所有「行情为空」类现象的成因。
主备故障转移的四个规则
priority 从小到大排序（数字越小越先试）。min_count；若所有源都不足，返回条数最多的那一个。| 情形 | 系统的行为 | 你会看到什么 | 怎么确认 |
|---|---|---|---|
| 主源失败、备源可用 | 自动切到备源并缓存结果 | 功能正常，但延迟或字段完整度可能不同 | 查数据源页的 health()：主源成功率下降、备源上升 |
| 所有源都失败 | 返回空值，不抛异常 | 自选页/详情页数据为空；Agent 仍会跑但输入不完整 | 数据源页逐个点「测试」；看日志里的取数失败记录 |
| 源返回的数据条数不足 | K 线按 min_count 判定不足后继续试下一个源 | K 线条数偏少但页面有数据 | 核对 min_count 配置与源的历史深度 |
| 源需要凭据但未配置 | 该源被跳过（默认关闭时就属于未启用） | 表现为「怎么都用不到那个源」 | 看该源在数据源页是否启用，config 里 cookie/代理是否为空 |
| 缓存命中 | 直接返回缓存，不再请求源 | 数据看起来「没更新」 | 包内 TTL 见下一节；K 线、资金流、事件不在包内缓存 |
配置端口的降级特例（src/platform/marketdata/marketdata_client.py）# 腾讯美股接口在当前网络出口稳定返回 501；A/HK 仍保留腾讯作为主源。
if (datatype == "kline" and market_code == "US"
and row.provider == "tencent" and has_us_fallback):
continuePanWatch 默认启用了哪些源？优先级是多少？
下表来自 server.py 的 DATA_SOURCE_SEEDS（只增不删的 upsert 种子）：它是「开箱即用」的真实状态，而不是文档里的能力清单。
| 类型 | 默认启用的源（优先级） | 默认关闭的源 | 说明 |
|---|---|---|---|
| 报价 quote | 腾讯（0）→ 东方财富（3）→ 新浪（5） | YFinance（10） | YFinance 需 pip install yfinance，且不支持 A 股 |
| 日 K kline | 腾讯（0）→ 东方财富（5）→ Stooq（15） | Yahoo（20） | Yahoo 国内访问通常需代理，官方建议配好 proxy 再开 |
| 资金流 capital_flow | 东方财富（0）→ 新浪（5） | — | 新浪仅含主力/超大单净额，无大/中/小单细分 |
| 事件 events | 东方财富（0） | — | 基于公告结构化 |
| 快讯 flash_news | 财联社（0）→ 新浪（5）→ 东方财富（10） | — | 市场级，7×24；与市场级数据不按标的过滤 |
| 基本面 fundamentals | 腾讯（0）→ 东方财富（5） | — | 腾讯只覆盖 A 股；东财覆盖 CN/HK/US |
| 龙虎榜 / 两融 / 股东户数 / 分红 | 东方财富（0） | — | 均为 A 股，注意龙虎榜是市场级单日快照 |
| 北向资金 northbound | 同花顺（0） | — | 种子描述写明「东财已断供；深股通近期不可靠」 |
| 资讯 news | 东方财富资讯（1）→ 东方财富公告（2） | 雪球资讯（0） | 雪球需要登录 cookie，所以虽然优先级最高但默认关闭 |
| K 线截图 chart | 雪球（0，视口 1280×900，额外等待 3000ms） | 东方财富截图（1，额外等待 2000ms） | 这一项依赖 Playwright/Chromium，是首次启动要下载浏览器的原因 |
PanWatch 缓存与健康度：为什么数据看起来没更新
缓存分两层：数据包内的 TTL 与宿主侧的采集缓存。下表是包内的默认 TTL（写在代码里，不是配置）。
| 数据类型 | 包内缓存 TTL | 含义与影响 |
|---|---|---|
报价 quote | 5 秒 | 防止同一轮里重复打源；提醒引擎自己还有一层 5 秒缓存 |
快讯 flash_news | 30 秒 | 7×24 快讯的刷新下限 |
北向资金 northbound | 60 秒 | 当日末值快照 |
| 基本面 / 龙虎榜 / 两融 / 股东户数 / 分红 | 300 秒（5 分钟） | 低频数据，长缓存可显著减少请求 |
日 K kline、资金流 capital_flow、事件 events | 不在包内缓存（0） | 由宿主自己缓存；这也是为什么这类数据的实时性取决于宿主 collector |
健康度 health() | 内存滚动窗口最近 100 次 | 每个厂商的成功率 / p50 延迟 / 最近错误 / 样本数 |
PanWatch 官方标注的「未校准字段」有哪些？七类数据的解析没经过真实抓取验证
这是本站认为 PanWatch 最值得单独成节的一条：packages/marketdata/README.md 用一整段写明——新增类型的字段解析多数未经真实网络抓取验证，因为开发沙箱的代理会拦截东财与同花顺接口。
packages/marketdata/README.md（原文节选）⚠️ 字段映射校准现状
B 阶段新增类型(flash_news / fundamentals / dragon_tiger / margin /
shareholders / dividend / northbound)的字段解析,多数未经真实网络抓取验证
(开发沙箱代理会拦截东财/同花顺等接口,只能靠接口文档 + 历史 PanWatch
collector 实现推断字段映射)。各 dataclass 的 docstring 里已标注"字段待实抓校准"。| 涉及类型 | 为什么容易出问题 | 官方建议的验证方式 |
|---|---|---|
flash_news 快讯 | 三个源的字段结构不同，且有市场级/标的级两套语义 | 在数据源页对该 (type, provider) 点「测试」，核对返回字段 |
fundamentals 基本面 | 腾讯只给 A 股估值快照，东财走另一套接口（美股/港股用 GMAININDICATOR） | 分别用 A 股与美股标的测试，确认字段能对上 |
dragon_tiger 龙虎榜 | 市场级单日快照，需要 test_date；日期不给就返回空 | 配一个已知有龙虎榜的交易日再测 |
margin / shareholders / dividend | 取最新一条 / 最新一期 / 全部历史三种不同语义 | 重点核对时间口径是否与你以为的一致 |
northbound 北向资金 | 官方种子描述直接写「东财已断供；深股通近期不可靠」，且 sgt_net 被点名为已知不稳定字段 | 以同花顺源测试，并把该数值视为「参考」而非「权威」 |
PanWatch 数据源与行情为空常见问题
答案基于固定 commit 的源码与官方包文档；数据源可用性会随上游接口变化，请以你部署时的实际测试为准。
相关页面：自动化 Agent 与条件提醒 · 故障排查手册
PanWatch 需要买行情数据吗？
默认不需要。开箱即用的源都是免 key 的公开接口：腾讯、新浪、东方财富、财联社、Stooq、同花顺。雪球资讯需要登录 cookie，YFinance 需要额外装包，Yahoo 需要代理——这三项默认关闭。免费源的代价是：延迟不保证、字段稳定性不保证、可能随时变动。
「11 类数据」具体指什么？
报价、日 K、资金流、事件（公告）、快讯、基本面、龙虎榜、融资融券、股东户数、分红、北向资金。除此之外还有两类不进主引擎的特殊入口：热门榜（个股/板块/板块成分）与指数行情/指数日 K。每类的厂商覆盖与市场范围不同，详见本页覆盖矩阵。
为什么我的自选页行情是空的？
最可能是降级的结果而不是崩溃：所有候选源都失败时，系统返回空值并继续运行。排查顺序是：① 数据源页逐个点「测试」看哪个源活着；② 看健康度的成功率与最近错误；③ 确认该源是否启用（需要凭据/代理的源默认关闭）；④ 确认标的代码符合该市场的正则（A 股 6 位、港股 5 位、美股字母）。
主源挂了会自动切换吗？
会。按 priority 顺序尝试，取到成功且非空的源就返回并缓存。K 线还有条数门槛：某源返回条数少于 min_count 会被视为不足并继续试下一个；全部不足时返回条数最多的那个。每次取数都会记进健康度，可在数据源页查看。
港股和美股能用哪些数据？
报价与日 K 覆盖较好（报价：腾讯/新浪/yfinance；日 K：腾讯/东财/Stooq/Yahoo）。基本面靠东财（CN+HK+US）；资金流向东财也覆盖三个市场，但口径与 A 股不同。事件、龙虎榜、两融、股东户数、分红、北向资金只有 A 股，港股/美股拿不到这些维度。
数据看起来没更新，是卡住了吗？
先看缓存：报价 5 秒、快讯 30 秒、基本面/龙虎榜/两融/股东户数/分红 5 分钟、北向资金 60 秒。而日 K、资金流与事件不在包内缓存，刷新节奏由宿主采集层决定。如果超过这些窗口仍然不动，再去数据源页看该源的健康度。
官方的数据源可靠吗？有没有已知问题？
官方在包文档里主动披露了两类问题：① 七类新增数据（快讯/基本面/龙虎榜/两融/股东户数/分红/北向）的字段解析多数未经真实网络验证，dataclass 里标注「字段待实抓校准」；② 北向资金条目写明「东财已断供；深股通近期不可靠」。本站把这看作可信度信号——但使用时必须自己先做一次字段校准。