Sequoia-X 报错现象速查表
先按现象找到对应分支，再去看该分支的处理步骤。
| 现象 | 日志/报错文案 | 原因 | 处理 |
|---|---|---|---|
| 程序一起步就退出 | 配置校验异常（pydantic ValidationError），主流程打印 traceback 后 sys.exit(1) | 缺少必填的 FEISHU_WEBHOOK_URL | 在项目根目录建 .env 并填默认 Webhook |
| 日常模式什么都没做 | 本地无股票数据，请先执行 --backfill | 库里没有股票记录，属于首次运行 | 先跑 python main.py --backfill，再跑日常模式 |
| 周末或节假日跑出「没数据」 | 无新数据（可能非交易日） | 当天没有新的交易日数据 | 属预期行为，无需处理；crontab 也照跑不误 |
| 提示所有股票已最新 | 所有股票已是最新，无需更新 | 库里最新日期已经是今天 | 重复执行时的正常输出 |
| 有推送日志但群里没消息 | 飞书推送失败 [key] HTTP状态=... 飞书响应=... | 响应体 code != 0，或地址/权限有问题 | 按响应体定位；核对机器人是否还在群内 |
| 推送请求直接异常 | 飞书推送请求异常 [key]：... | 网络不可达、DNS 或代理问题 | 换网络环境；超时为 10 秒，网络差时可能超时 |
| 回填卡住或很慢 | 每 500 只打印一次进度，单只失败会打印重试等待 | 长连接超时或上游限速 | 让它继续跑，中断后重跑会跳过已入库股票 |
| 定增策略没有结果 | 获取定增数据失败 或 近期无新定增公告 | 外部接口不可用，或最近 7 天确实没有定向增发公告 | 两条日志含义不同：前者是故障，后者是正常空结果 |
Sequoia-X 回填的断点续传与重试
回填之所以能中断后续跑，靠的是「已入库就跳过」这个判断。
| 机制 | 实现 | 适用场景 | 注意点 |
|---|---|---|---|
| 跳过已入库 | 回填前查 MAX(date)，若已是今天则计入「跳过」 | 中断后重跑、或重复执行回填 | 已经完整的股票不会重复拉取，重跑成本远低于首次 |
| 单只重试 | 最多 3 次，等待 2s / 4s / 8s，每次重试前重连 | 偶发查询失败 | 3 次都失败才计入「失败」并继续下一只 |
| 定期重连 | 每处理 200 只强制 logout 后重新 login | 长时间连续拉取 | 重连失败会终止回填并记错误日志 |
| UNIQUE 约束兜底 | 写入冲突时捕获 IntegrityError 静默跳过 | 同一股同日重复写入 | 静默意味着不会因为重复而中断，但也不会提示你重复了 |
| 进度可观测 | 每 500 只打印「已处理 x/N，成功 a 跳过 b 失败 c」 | 判断是否还在推进 | 长时间看不到新进度才算真卡住 |
| 结束汇总 | 输出「回填完成 — 成功 / 跳过 / 失败」三计数 | 评估是否需要再跑一轮 | 失败计数不为零时，直接再跑一次即可补上 |
按日志定位失败环节
四条命令式的自助检查，不用改代码。
先看程序有没有真的启动
日志首行应是启动记录，随后是「数据库初始化完成：<路径>」。缺少这两行说明失败发生在配置或导入阶段，重点看 traceback 的最后一行。
确认数据是不是到了今天
查找同步相关的那一行：写入条数为 0 且带有「无新数据」字样时，是交易日判断问题；提示「本地无股票数据」时，是先跑回填的问题。
看每个策略的输出行
七个策略各会打印「XXXStrategy 选出 N 只股票」。某个策略完全没打印，说明它在遍历前就返回了（例如 RPS 读库失败会记 error 后返回空列表）。
最后看推送行
命中为空的策略不会出现推送记录；有推送记录时，成功与失败文案不同——成功记 info，失败记 error 并附带 HTTP 状态与响应体。
Sequoia-X 数据体检：先确认库的状态
用 SQL 或任意 SQLite 工具查这几项，比反复重跑更快。
| 检查项 | 怎么看 | 正常范围 | 异常时的含义 |
|---|---|---|---|
| 股票数量 | SELECT COUNT(DISTINCT symbol) FROM stock_daily | 与「获取股票列表完成，共 N 只」的 N 接近 | 远小于 N 说明回填只完成了一部分 |
| 最新日期 | SELECT MAX(date) FROM stock_daily | 最近一个交易日 | 落后多个交易日说明日常模式没在跑 |
| 总行数 | SELECT COUNT(*) FROM stock_daily | 约等于股票数 × 交易日数 | 明显偏小说明历史区间短 |
| 重复行 | 按 (symbol, date) 分组查计数大于 1 | 应为零（由 UNIQUE 约束保证） | 出现重复说明表被外部工具改过 |
| 零成交量行 | 查 volume <= 0 是否还存在 | 正常为 0 行（写入时已过滤） | 有残留说明数据来源不是本项目脚本 |
| 窗口可用性 | 按股票数历史长度是否 ≥60 | 多数标的应满足 | 不足 60 根的标的会被两个策略跳过 |
Sequoia-X 何时重跑回填、何时只跑日常
选错方式会白等或补不上数据。
| 情形 | 该跑什么 | 适用场景 | 注意点 |
|---|---|---|---|
| 初次使用 | 回填（--backfill），完成后再跑日常 | 库为空 | README 自述约 12 分钟，实际随网络与区间变化 |
| 回填被中断 | 再跑一次回填 | 断电、断网、手工终止 | 已入库的会被跳过，重跑成本集中在未完成部分 |
| 漏跑了一两天日常 | 跑日常模式即可 | 缺口在最近几天 | 日常模式按每只股票的最新日期往后补，能覆盖短期缺口 |
| 想加深历史 | 改 START_DATE 后重跑回填 | 需要更长窗口的策略 | 已有数据的股票默认仍从断点续拉，不会自动向前补历史 |
| 只是想重发一次推送 | 修好 Webhook 后重跑日常 | 当天数据已入库 | 当天记录会被整体重写，不产生重复行 |
| 怀疑数据写坏 | 先备份库文件，再评估是否重建 | 外部工具改动过库 | 删库是最贵的一步，务必先确认并留备份 |
排查类常见问题
程序报错退出，退出码 1 是什么意思？
主流程捕获到未处理异常后会打印 traceback 并以退出码 1 结束，这是源码里显式的处理方式。定时任务建议据此判断当天是否执行成功；具体异常原因看 traceback 的最后一行与上文的配置检查项。
非交易日到底算不算故障？
不算。没有新数据时会输出「无新数据（可能非交易日）」并正常返回，写入条数为 0。周末与法定节假日都属这一类，crontab 照常触发也没有问题。
回填跑到一半断了，数据会坏吗？
不会。逐只写入且靠 UNIQUE 约束去重，中断只影响「还没拉到的那些股票」；重跑时会跳过已完成的部分，从缺口继续。本站没有实测运行数据，以上描述依据源码的跳过与冲突处理逻辑。
为什么某个策略一直没结果？
三种常见原因：一是它的最小 K 线要求没被满足（如需要 60 根），二是阈值本身很严导致当天没有标的符合，三是它依赖外部接口而接口不可用（定增类）。对照日志里该策略那一行可以区分前两者。
推送失败会导致当天白跑吗？
不会。推送异常在源码里被捕获并只记错误日志，数据已经写入库中。修好配置后重跑当天，日常模式会重写当日数据并重新尝试推送。
有没有官方的问题清单？
仓库没有单独的 FAQ 或 troubleshooting 文档（文件树里没有 docs 目录）。本站的排查项来自源码里的容错分支与日志文案；遇到本篇未覆盖的问题，建议对照源码或到仓库 Issues 检索，具体以官方仓库为准。