PanWatch 现象一：行情为空怎么办？
先记住一条：PanWatch 在所有数据源都失败时返回空值而不抛错，所以「空」是降级的结果，不是崩溃。
| 可能成因 | 怎么判定 | 怎么处理 |
|---|---|---|
| 所有候选源都失败 | 数据源页逐个点「测试」看哪些源活着 | 修网络/代理；或启用备用源 |
| 需要凭据或代理的源没启用 | 看该源是否启用（雪球 cookie / YFinance 装包 / Yahoo 代理默认关闭） | 补齐条件后再启用 |
| 代码不符合该市场的正则 | A 股 6 位且以 0/3/6 开头；港股 5 位；美股 1–5 位字母 | 改用正确的代码格式 |
| 该市场当前不在交易时段 | 行情仍应可取，但 Agent 的 single 模式会跳过该标的 | 等开市，或确认是不是 Agent 跳过而不是行情失败 |
| 命中缓存 | 数据本来没变 | 报价缓存 5 秒；低频数据缓存 5 分钟；日 K/资金流/事件不在包内缓存 | 等过缓存窗口再看；或看时间戳判断 |
| 停牌或长期无成交 | 该标的处于停牌或流动性极低状态 | 这不是工具问题；看最新交易日与公告 |
行情为空的三分钟判定顺序
PanWatch 现象二：设了提醒却没收到消息怎么办？
这是 PanWatch 里出现频率最高的一个问题，而它的答案分两类：规则没命中与命中了但没推成功。
| 先确认 | 判定依据 | 属于故障还是设计 |
|---|---|---|
| 规则是否启用、是否被 once 自动关闭 | 列表开关状态 | 设计：只触发一次的规则命中后会自动停用 |
| 是否在交易时段 | 规则的「仅交易时段生效」+ 该市场当前状态 | 设计：仅交易时段的规则在盘外静默 |
| 是否达到日上限或仍在冷却 | 命中历史的触发时间分布 | 设计：日上限按 UTC 日算（北京 08:00 重置） |
| 条件是否真的命中 | 把阈值放宽到 0.1% 试一次 | 若宽松值也不动，问题在数据而非规则 |
| 渠道是否启用 | 渠道列表状态；规则是否指定了渠道 | 设计：指定了渠道就只走指定渠道 |
| 是否被静默时段吞掉 | quiet_hours 与策略时区（默认 UTC） | 设计：静默时段默认不是应用时区，这是最常见的配置坑 |
| 命中记录里的通知结果 | notify_success / notify_error | 故障：渠道侧问题（Token、Chat ID、网络） |
notify_success 为假，问题在渠道而不在规则。另一个反向线索：手动触发有、自动触发没有——手动触发可以绕过交易时段门槛，所以这种组合几乎总是指向时段门槛或扫描节奏，而不是数据或渠道。
PanWatch 现象三：提醒重复或 Agent 漏跑怎么办？
PanWatch 这类问题的共同点是「时间语义」而不是「逻辑错误」，因此先确认你理解的是不是同一套时间口径。
| 现象 | 成因 | 属于故障还是设计 |
|---|---|---|
| 同一分钟内收到多条 | 同分钟去重桶是 UTC 分钟；跨过分钟边界就会各自触发 | 设计：去重单位是分钟 |
| 日上限提前重置 | 日计数按 UTC 日（北京时间 08:00）重置 | 设计：不是零点重置 |
| 重启后收到重复通知 | 批量 Agent 的通知按内容哈希 + TTL 去重，窗口外会重新发 | 设计：窗口内才去重 |
| 某个标的没跑 | Agent 是 single 模式时会跳过非交易时段的市场 | 设计：见调度模式差异 |
| 整批都没跑 | 该 Agent 默认关闭（盘前与盘中都是关闭状态） | 设计：需要你手动启用 |
| 盘中分析频率比预期低 | event_only=True + 30 分钟抑制窗口 | 设计：成本控制 |
扫描节奏的三个参数（price_alert_scheduler.py）seconds=self.interval_seconds, # 默认 60s（最小 15s）
jitter=20, # 抖动错峰，避免与模拟盘每 60s 同刻写 SQLite
coalesce=True, max_instances=1 # 上一轮未结束则本轮跳过PanWatch 现象四：分析超时、截图失败怎么办？
PanWatch 的这三类问题都发生在「重活」上：调用模型、启动浏览器、首次安装依赖。
| 现象 | 成因 | 验证与处理 |
|---|---|---|
| 深度分析跑到一半失败 | 默认单次总超时 15 分钟、单请求 120 秒、输出上限 4096 token；图内重试次数为 0 | 看运行记录里的失败终态；需要重跑请手动再触发一次（不会自动重试） |
| 模型请求被网关断开 | llm_max_tokens 限制输出正是为了避免网关空闲超时 | 属于设计内的保护；若仍频繁发生，考虑换模型或缩短输出 |
| K 线截图一直失败 | Playwright 的 Chromium 没装完、卷未挂载或网络不可达 | 看数据卷里是否有 playwright 目录；不需要截图可设 PLAYWRIGHT_SKIP_BROWSER_INSTALL=1 |
| 首次启动几分钟没反应 | 正在下载 Chromium 到数据卷 | 看容器日志有无下载进度；这是官方文档明确写过的行为 |
| 安装依赖极慢 | TradingAgents 是 git 直装，首次约 115 个依赖包、2–5 分钟 | 不启用深度分析则零开销，可以先不装 |
PanWatch 现象五：时间不对、节假日还在跑，怎么排查？
这一类问题的答案大多在「多市场时区与交易日历」页，这里只给最短定位路径。
| 现象 | 成因 | 最短定位路径 |
|---|---|---|
| 美股提醒在深夜来 | 美股 09:30 对应北京时间 21:30（夏令时） | 这是时区事实；用静默时段或独立渠道处理 |
| 港股/美股节假日仍推送 | 港美股只判周末，节假日被判成交易日 | 官方在代码注释里把它称为「诚实降级」 |
| A 股休市日跑了盘前分析 | 盘前分析是 batch 模式，不检查交易时段 | 用启用开关控制；或临时移出自选 |
| 夜间静默没生效 | 静默策略默认时区是 UTC，与 TZ 不同 | 把策略时区改成应用时区，或换算成 UTC 再填 |
| 换服务器后 cron 全乱 | 调度时区来自 TZ | 在容器启动参数或 compose 中固定 TZ |
| 日上限感觉提前重置 | 日计数按 UTC 日（北京 08:00） | 改用冷却时间控制频率 |
PanWatch 现象六：数据卷与升级故障怎么处理？
这类故障的代价最高（可能丢数据），所以要按顺序确认而不是边试边改。
| 现象 | 成因 | 处理与预防 |
|---|---|---|
| 容器重建后数据没了 | 卷没挂上（漏写 -v 或卷名不一致） | docker inspect 看 Mounts；启动命令与 compose 文件保持卷名一致 |
| 数据目录被清空 | 用清理未跟踪文件的方式清理了 data/（它不受版本管理） | 官方明确提醒过这一点；清理前先备份 |
| 升级后行为变化 | 项目发布密集（0.10.2 到 0.16.1 共 10 个版本） | 升级前读 Release Notes 并备份数据卷 |
| 升级失败想回滚 | 缺少旧镜像 tag 或数据卷备份 | 回滚的两个前提：数据卷备份 + 记住升级前镜像 tag |
| 端口冲突启不来 | 宿主 8000 被占用 | 换宿主端口（如 -p 18000:8000） |
| 登录凭据丢失 | 用了预设的 AUTH_USERNAME/AUTH_PASSWORD 却未记录 | 按官方说明重置；建议一开始就把凭据记到密码管理器 |
.env、Token 或持仓数据。为什么官方不把「节假日」也判准？
因为港股与美股没有等价的公开交易日历源。官方在代码注释里选择「只判周末」并把这称作诚实降级，取舍理由是「宁可多发一条通知，也不能把交易日误判为休市」。在缺权威日历的前提下，这个选择让系统偏向「多跑」而不是「漏跑」。
分析失败会自动重试吗？
不会。官方把图内重试次数默认设为 0，注释写明是「失败快速落终态，不在图内重复重试」——多 Agent 链路重试一次可能就再花一遍钱。需要重跑请手动再触发一次。
怎么确认到底是数据问题还是规则问题？
用一个宽松到必然命中的阈值（例如涨跌幅 0.1%）建一条临时规则。如果它也不触发，问题在数据或扫描；如果它触发了，问题在阈值设置。另一个判据：手动触发能绕过交易时段门槛，所以「手动有、自动没有」指向时段或扫描节奏。
日志要我开 DEBUG 吗？
排查「调度有没有跑、采集有没有失败」这类问题时需要。注意官方说明：界面日志板始终保留完整记录，控制台的 INFO 只输出业务事件与错误。分享日志前先脱敏，别把 Token 与持仓数据一起贴出去。
它说自己有数据源健康度，在哪看？
在数据源页。每次取数的成败与延迟都会被记录，健康度按内存滚动窗口保留最近 100 次，包含每个厂商的成功率、p50 延迟、最近错误与样本数。这是排查「行情为空」最快的入口。
为什么我的提醒比预期慢？
提醒是轮询式的：默认每 60 秒扫一轮并带 20 秒抖动，报价还有 5 秒缓存；若上一轮未跑完（max_instances=1）本轮会直接跳过。因此实际延迟取决于规则数量与数据源响应速度，不要把它当逐笔实时。
遇到表里没有的问题怎么办？
先去官方仓库查 issue 与 Release Notes（版本更新较密集，很多现象已经在新版本里变化）；第二步准备脱敏后的证据：版本号、部署方式、相关配置（去掉密钥）、复现步骤、日志片段。安全相关问题不要开公开 issue——官方要求邮件私发。
排查时最该先看哪一个日志？
分情况：如果是「该跑没跑」，看调度日志与运行记录（判断 Agent 是否启用、是否被交易时段跳过、是否超时失败）；如果是「跑了但结果不对」，看数据源健康度与采集日志（判断输入是否完整）；如果是「推送没到」，看命中记录里的通知结果字段（区分规则未命中与渠道失败）。官方也说明过：界面日志板始终保留完整记录，控制台的 INFO 级别只输出业务事件与错误，排查细节时需要临时调成 DEBUG。