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 后重跑日常 | 当天数据已入库 | 当天记录会被整体重写，不产生重复行 |
| 怀疑数据写坏 | 先备份库文件，再评估是否重建 | 外部工具改动过库 | 删库是最贵的一步，务必先确认并留备份 |
Sequoia-X 没给的三个开关，以及怎么绕过去
跑久了总会遇到这些需求：只补几只票、只跑策略不补数、单独重跑某个策略。Sequoia-X 的 main.py 里 argparse 只定义了一个参数 --backfill，所以下面这些只能自己动手。
| 想做的事 | 源码现状 | 可行做法（教程扩展，非官方功能） | 代价与风险 |
|---|---|---|---|
| 只跑策略、不补数据 | Sequoia-X 日常模式一定会先执行 sync_today_bulk()，没有跳过开关 | 临时注释掉那一行，或直接写个小脚本：DataEngine(settings) → 实例化策略 → run() → 打印结果 | 改动源码后要注意环境安装方式（pip install . 需重装，可编辑安装才即时生效） |
| 只补某几只股票 | Sequoia-X 的增量按整库分组执行，没有单票参数 | 用 Sequoia-X 的 engine.backfill(["600519"]) 直接调用回填接口，传入你关心的代码列表 | 回填里已有「已入库则跳过」判断，重复调用是安全的 |
| 单独重跑某个策略 | Sequoia-X 的策略列表在 main.py 里按顺序执行，无法从命令行指定 | 写一份三行脚本单独实例化那个策略类并调用 run() | 不会自动推送——推送逻辑在主流程里，需要自己补 FeishuNotifier(settings).send(...) |
| 补某一天的缺口 | 增量只补「最新一根 K 线之后」的日期 | 先 DELETE FROM stock_daily WHERE date = 'YYYY-MM-DD'; 再跑日常模式 | 危险操作：删库前先备份文件；删除的是当天的全市场记录，不是单只股票 |
| 换一个干净的库重来 | 库路径来自配置 DB_PATH | 把 DB_PATH 指向新文件，再跑一次 --backfill | 旧库别删，保留下来做对照 |
# 示例：单独跑一次海龟突破并打印结果（放在项目根目录执行）
from dotenv import load_dotenv; load_dotenv()
from sequoia_x.core.config import get_settings
from sequoia_x.data.engine import DataEngine
from sequoia_x.strategy.turtle_trade import TurtleTradeStrategy
settings = get_settings()
engine = DataEngine(settings)
hits = TurtleTradeStrategy(engine=engine, settings=settings).run()
print(len(hits), hits)data/ 目录，任何因改动源码造成的数据差异由你自己承担；以官方源码为准。排查类常见问题
程序报错退出，退出码 1 是什么意思？
主流程捕获到未处理异常后会打印 traceback 并以退出码 1 结束，这是源码里显式的处理方式。定时任务建议据此判断当天是否执行成功；具体异常原因看 traceback 的最后一行与上文的配置检查项。
非交易日到底算不算故障？
不算。没有新数据时会输出「无新数据（可能非交易日）」并正常返回，写入条数为 0。周末与法定节假日都属这一类，crontab 照常触发也没有问题。
回填跑到一半断了，数据会坏吗？
不会。逐只写入且靠 UNIQUE 约束去重，中断只影响「还没拉到的那些股票」；重跑时会跳过已完成的部分，从缺口继续。本站没有实测运行数据，以上描述依据源码的跳过与冲突处理逻辑。
为什么某个策略一直没结果？
三种常见原因：一是它的最小 K 线要求没被满足（如需要 60 根），二是阈值本身很严导致当天没有标的符合，三是它依赖外部接口而接口不可用（定增类）。对照日志里该策略那一行可以区分前两者。
推送失败会导致当天白跑吗？
不会。推送异常在源码里被捕获并只记错误日志，数据已经写入库中。修好配置后重跑当天，日常模式会重写当日数据并重新尝试推送。
有没有官方的问题清单？
仓库没有单独的 FAQ 或 troubleshooting 文档（文件树里没有 docs 目录）。本站的排查项来自源码里的容错分支与日志文案；遇到本篇未覆盖的问题，建议对照源码或到仓库 Issues 检索，具体以官方仓库为准。
能只跑策略、不补数据吗？
没有现成开关：main.py 的 argparse 只定义了 --backfill，日常模式必定先执行增量同步。可行做法是自己写一小段脚本，实例化 DataEngine 与目标策略后直接调用 run()（本页有示例）。注意这样做不会自动推送，需要自己调用 FeishuNotifier(settings).send(...)。属于教程扩展，改动前先备份数据目录，以官方源码为准。