Sequoia-X 项目研究站 · 安装与回填
Sequoia-X 安装与历史回填：先把本地库准备出来
这套选股程序不连在线行情服务，所有形态判定都读本地 SQLite。所以初次上手只有两件事：把 Python 环境和依赖装好、把全市场历史日 K 灌进库里。安装有两种官方方式（uv sync 或 pip install .），配置只有一个必填项（飞书 Webhook），回填是一条命令 python main.py --backfill，中途断了可以重跑续传。
Sequoia-X 安装前置条件：七项先对齐
下表来自仓库 pyproject.toml、.env.example、全量文件树与 README；「不满足会怎样」一列是源码与配置校验的真实后果。
| 条件 | 要求 | 不满足会怎样 | 注意点 |
|---|---|---|---|
| Python 版本 | requires-python >=3.10 | 低于 3.10 时依赖声明不满足，安装在依赖解析阶段就会被拒 | 建独立虚拟环境，避免与系统里已有的 pandas/akshare 版本互相污染 |
| 数据源网络 | 能访问 baostock（公开接口，无需注册与 API Key） | 登录或查询失败会被记为失败并跳过该只股票 | 项目未提供代理配置项，受限网络需要自行在系统层放行 |
| 飞书 Webhook | FEISHU_WEBHOOK_URL 为必填字段 | 缺失时配置校验抛 ValidationError，程序在初始化阶段直接退出 | 想按策略分群推送，可另配 STRATEGY_WEBHOOK_<KEY>；只配默认项也能跑 |
| 磁盘空间 | 本地 SQLite 单文件库，默认 data/sequoia_v2.db | 写入阶段报错，回填的进度会停在中途 | 库文件可以整体拷贝迁移，换机器不用重灌数据 |
| 系统与调度 | 官方 README 只给出 crontab 示例 | Windows 上没有 crontab，需要自己用任务计划程序替代 | 日常模式不需要常驻进程，定时触发一次即可 |
| 仓库里没有的东西 | 全量文件树中没有 Dockerfile、没有 CI 配置、没有 requirements.txt、没有 docs 目录、也没有任何 Release | 想按「官方镜像」或「官方文档站」的教程部署会找不到对应材料 | 依赖与命令都以 pyproject.toml、uv.lock 和 README 为准 |
| 许可 | README 声明 MIT，但仓库文件树中没有 LICENSE 文件，GitHub 的 license 字段为空 | 无法仅凭仓库文件确认授权范围 | 商用或二次分发前请向作者确认，不要只按 README 的一行声明判断 |
Sequoia-X 安装四步与预期结果
命令来自官方 README 的「快速开始」与 main.py 的 argparse 定义。
取得源码并建虚拟环境
克隆仓库后进入目录，创建并激活虚拟环境（例如
python -m venv .venv，Windows 用.venv\Scripts\activate）。预期：命令行提示符前出现虚拟环境标识，确认后续命令都装在这个环境里。安装依赖
官方推荐
uv sync（仓库自带约 253 KB 的uv.lock，能把全部依赖锁到确定版本）；也可以用pip install .走 pyproject 声明安装。预期：安装结束不报解析错误；用python -c "import baostock, akshare, rich"能静默通过。写配置 .env
把
.env.example复制成.env（Linux/macOS 用cp，Windows 用copy），至少填写FEISHU_WEBHOOK_URL。预期：再执行python main.py时不再于配置校验阶段退出。确认程序可运行
先执行
python main.py --help看参数是否齐全，应能看到--backfill选项与程序说明。预期：打印 argparse 用法与参数说明——能打印就说明依赖与入口都没问题。
main.py 启动时会先加载 .env，而配置模型把飞书 Webhook 定义为必填字段。所以「先复制 .env 再运行」不是可选项——反过来做，初次运行必定停在配置校验上。Sequoia-X 的 .env 字段逐个说明
仓库 .env.example 只给了这些字段；下表补上「写错的后果」。
| 字段 | 默认值 | 作用 | 缺失或写错的后果 |
|---|---|---|---|
DB_PATH | data/sequoia_v2.db | SQLite 库文件位置，目录不存在时程序会自动创建 | 用默认相对路径 + 定时任务工作目录不同时，库会生成在别的地方，表现为「数据莫名其妙没了」 |
START_DATE | 2024-01-01 | 回填模式拉取历史的起始日期 | 设得太早会显著拉长回填时间；日常增量不受它影响，只从库里最新日期往后补 |
FEISHU_WEBHOOK_URL | 无默认值，必填 | 默认推送目标；未被单独配置的策略也回落到它 | 缺失时配置校验报错、程序不启动，这是初次上手最常见的失败点 |
STRATEGY_WEBHOOK_<KEY> | 无默认值，可选（示例文件给出 7 个） | 把指定策略的结果推到专属机器人，实现分群播报 | 键名拼错不会报错，只会静默回落默认 Webhook——表现为「所有策略都推到一个群」 |
| 前缀命名规则 | 以 STRATEGY_WEBHOOK_ 开头 | 配置层扫描环境变量，去掉前缀并统一转小写后作为策略标识 | 前缀拼错等于没配置；大小写不影响识别 |
| 加载时机 | main.py 启动即 load_dotenv() | 从项目根目录读取 .env | 在别的目录执行脚本就读不到配置，表现为「明明填了却说必填项缺失」 |
首次回填：用 Sequoia-X 把历史灌进本地库
这是整条流程里最需要耐心的一步，README 自述约 12 分钟覆盖全市场。
执行回填命令
python main.py --backfill。程序先通过 baostock 取全市场股票清单（只保留上市状态且类型为股票的代码），再逐只拉取从START_DATE到今天的后复权日 K。预期：日志出现「进入回填模式...」与「获取股票列表完成，共 N 只」。让它跑完并观察进度
回填是单线程的，每处理 500 只会打印一次「已处理 i/总数，成功 x 跳过 y 失败 z」。预期：进度行持续增长，就说明在推进。
读结束汇总
结束会打印「回填完成 — 成功: x | 跳过: y | 失败: z」。预期：失败数通常来自网络抖动；失败的股票没有被记为已入库，所以下一次执行会自然重试。
确认库里有数据
用任意 SQLite 客户端打开库文件执行
SELECT COUNT(*), MAX(date) FROM stock_daily;，条数应为百万级、最新日期应接近今天。预期：能查到行数即回填成功。
| 维度 | --backfill（回填模式） | 日常模式（python main.py） | 什么时候用 |
|---|---|---|---|
| 并发方式 | 单线程逐只查询，稳定但慢 | 最多 8 个进程分片并行 | 首次/补历史用回填，每个交易日用日常 |
| 覆盖范围 | 从 START_DATE 到今天的全部历史 | 只补「库里最新日期之后」的增量 | 换新库后初次必须回填 |
| 失败重试 | 单只最多重试 3 次，等待 2s / 4s / 8s，并重连数据源 | 不针对单只股票重试 | 网络不稳时回填更耐错 |
| 连接管理 | 每 200 只强制断开重连一次，避免长连接超时 | 每个子进程各自登录一次 | 长时间运行的场景才需要重连 |
| 重复执行行为 | 已入库的股票直接 skip，可中断续跑 | 先删除当日记录再写入，重跑不会产生重复行 | 中断了直接重跑原命令即可 |
| 典型耗时 | README 自述约 12 分钟（约 5200 只） | README 自述约 2~3 分钟 | 两者均为项目自述值，实际受网络与机器影响 |
装完自检与 Sequoia-X 常见的七个误解
这些现象都能在源码头文件与日志文案里找到出处。
| 现象 | 真实原因 | 处理方式 |
|---|---|---|
| 启动即报配置校验失败，提示缺少飞书 Webhook | .env 没创建，或必填项为空 | 复制 .env.example 为 .env 并填入 Webhook 地址，再在项目根目录执行 |
| 日志提示「本地无股票数据，请先执行 --backfill」 | 直接跑了日常模式，库里还没有任何股票 | 先执行一次回填模式，再回到日常模式 |
| 日常模式跑完提示「无新数据（可能非交易日）」 | 当天不是交易日，或数据源当日数据未就绪 | 属预期行为，不需要反复重跑 |
| 回填跑了很久还没结束 | 单线程逐只拉取，机器与网络都会影响总时长 | 看每 500 只的进度行判断是否在推进；中断后重跑即可续传，不必清库重来 |
| 结束汇总里出现失败数 | 个别股票查询报错或三次重试仍未成功 | 失败的不算已入库，下次回填会自动重试 |
| 换机器后数据还在吗 | 数据是本地 SQLite 单文件，与程序解耦 | 直接拷贝库文件，并同步调整 DB_PATH |
| 能不能用 Docker 一键部署 | 仓库里没有 Dockerfile、没有 CI、没有 requirements.txt | 没有官方镜像；要容器化需自己编写镜像或用裸机部署 |
pyproject.toml、.env.example、main.py 与 sequoia_x/data/engine.py 源码，未做实测；实际差异以官方仓库与源码为准。常见问题
装 Sequoia-X 必须用 uv 吗？只用 pip 行不行？
两者都行。README 的安装章节给出 uv sync（推荐，仓库带锁定文件）与 pip install . 两种写法，差别只在依赖解析速度与版本锁定程度，不改变程序行为。以官方 README 为准。
Sequoia-X 的飞书 Webhook 是必须的吗？
不能。飞书 Webhook 被定义为必填配置项，缺失时配置校验会抛错并让程序在初始化阶段退出。也就是说没有它连回填都跑不了。以源码中的配置模型为准。
Sequoia-X 回填要跑多久？可以中途关掉吗？
README 自述约 12 分钟覆盖约 5200 只股票，实际取决于网络与机器。可以关掉：回填对已入库的股票会跳过，重新执行同一条命令即可从断点续跑，不会重复灌入。以源码中的回填逻辑为准。
Sequoia-X 的数据存在哪里？占多大空间？
存在本地 SQLite 文件里，默认路径是 data/sequoia_v2.db，可用 DB_PATH 改到别的目录。项目没有给出体积承诺，实际取决于回填的起始日期与覆盖的股票数量。以官方 README 与源码为准。
Sequoia-X 回填完就能选股了吗？
回填只把数据准备好。选股要在日常模式里由七个策略依次扫描本地库完成，其中定增公告策略不读本地库、而是走公开的增发公告接口。策略条件见「突破信号」与「反转信号」两页。
不想自己装环境，有别的上手方式吗？
如果只是想先用一句话问清某个数据或指标，可看对比页列出的本机技能路线（自然语言选股、技术指标、盯盘预警、行情取数等）。需要注意：本项目与该技能路线无已证实集成，它不是本项目的安装方式。