跟踪 X 账号的抓取程序

这是什么、解决什么问题、现状与部署。

这是什么。 expert/X/ 是一个基于 twikit（非官方 X GraphQL 客户端）的航天 X 账号抓取器。它用一次性登录得到的 cookie 做无头登录，按种子清单批量拉取账号 profile 与时间线，把 twikit 的松散对象归一化后落进本机 SQLite（x.sqlite3），并可产出中英对照的 Markdown / HTML / PDF 报告。

解决什么问题。 为「Satellite Agent」（agent/，全球卫星互联网产业决策 agent）提供每日的 X 侧信号源。抓取器只负责「把推文抓进 SQLite」，agent 侧再只读增量地把新推文映射成事件（events），喂进 decide / 日报 / wiki 回写。

当前数据规模。 SQLite 已存 95 个账号 / 3123 条推文（2026-06-06 实测，NEXT_STEPS.md:3）；其中 5 个种子账号报 user_not_found（handle 停用/改名）。账号按 9 大分类组织。

两大块，共用底层 expert/X/data/x.sqlite3，去向不同。

下游 agent 侧只读 x.sqlite3，绝不重抓、绝不写 X 的表。分两条链路（沿用 x-bridge-operator-runbook.md 字母约定）：

上游抓取库 + agent 桥接的关键文件。

DDL 集中在 db.py:11-94，全 IF NOT EXISTS、init_schema 可反复执行。共 5 表 + 3 索引；时间戳统一由 utcnow_iso() 生成（UTC 秒级 ISO8601）。

4.1 accounts — 账号 db.py:12-29

主键 username。字段分三组：抓取回填、种子导入、运维状态。无外键，也无「建行时间」字段。

4.2 tweets — 推文 db.py:31-55

主键 id（TEXT）。唯一外键 author_username → accounts(username)。三索引：author / created_at / type。

4.3 media / 4.4 translations / 4.5 runs

• media（db.py:61-71）：复合主键 (tweet_id, media_key)。无到 tweets(id) 的外键——即便 foreign_keys=ON 也可能写入孤儿媒体行。photo 存图片直链，video/gif 存最高码率 mp4 直链（_best_video_url）。
• translations（db.py:73-81）：复合主键 (kind, ref_id)，kind ∈ {tweet,bio}。db.py 本身只有 DDL、无读写函数——写在 import_translations.py（INSERT OR REPLACE），读在 reports.py 与 x_sqlite.py。
• runs（db.py:83-93）：抓取运行账本。finished_at=NULL 即 run 未正常收尾（中断/崩溃），据此判僵尸 run。记 total/ok/failed 与 tweets_new/seen。

4.6 first_seen_at 增量判定 核心不变量

ScrapeConfig（frozen dataclass）默认：tweets_per_account=40（每个 tab 的目标条数）、include_replies=True、sleep_between_accounts=(3,7)、rate_limit_sleep=900、max_retries=3。

5.1 登录 / cookie

两条路径，登录态与抓取解耦，凭证只在登录时用：interactive_login（scraper.py:53）一次性交互登录产出 cookie JSON（支持 totp_secret 2FA）；make_client（scraper.py:42）无头路径，cookie 不存在直接 RuntimeError 提示先 cli login，不带任何明文凭证。Cookie 复用规避重复登录挑战与风控。

5.2 归一化层（松散对象 → 稳定 dict）

全字段走 getattr(..,None) / .get(default) 容错，X 掉字段也不崩：_classify 按 RT>reply>quote>original 优先级判类型；_best_video_url 挑最高 bitrate 的 mp4；_normalize_tweet 的 author_username 恒为传入种子账号（RT 时非原作者）。

5.3 分页 _fetch_timeline · scraper.py:188

5.4 单账号流程 scrape_account · scraper.py:205

返回 (new, seen, error)：① get_user_by_screen_name 本地 try 只捕 UserNotFound/Unauthorized 成软错误（不含 429，故 429 冒泡到 run 层退避）；② upsert profile；③ 抓 Tweets tab（不套 try），若 include_replies 再抓 Replies——仅此处套 try/except NotFound 兜 Replies 端点 404，保留 Tweets-only；④ 两 tab 都 fetch 完才跑写库循环（逐条 normalize+upsert_tweet+upsert_media）；⑤ 写 {username}.json 快照。

5.5 run 编排 run_scrape · scraper.py:275

• --only 过滤：不在 seed 清单的账号显式 warn（修此前静默跳过的已知问题 #1）；全不命中 → SystemExit。
• 逐账号重试循环：TooManyRequests → attempt<max_retries 则 sleep 900s 后从 get_user 重跑整账号（upsert 幂等不重复）；BadRequest/TwitterException 与兜底 Exception 记错 break，绝不掀翻整轮。
• commit-per-account（347 行）：每账号后 conn.commit() checkpoint，配合 WAL 让 stats/report 在 run 进行中就读到已完成账号，中途崩溃不丢前面成果。

5.6 twikit 补丁 _twikit_patch.py

由 __init__.py:2 在任何 Client 使用前 import 生效（强依赖此导入路径，绕过则每请求 Couldn't get KEY_BYTE indices 全线失败）。两处：get_indices 适配 X 2026-03 后 ondemand.s 拆 index+hash 两段（upstream #408）；User.__init__ 换成全字段 .get(default) 版容忍缺字段（#417），含 following_count = legacy.friends_count 映射。

5.7 限流 / 重试的陷阱（均已核查更正）

进程唯一入口 main（cli.py:263）：parse_args → _load_config → _resolve_paths → args.func(args,cfg,paths)。子命令统一签名，返回值即退出码。

6.1 config.yaml（全可选，缺文件用默认）

6.2 cookie 导入 & 种子加载

_extract_from_browser_export（cli.py:72）支持 3 种导出格式归一成 {name:value}，按 _X_DOMAINS 过滤，必需 {auth_token, ct0}（缺则 WARN 不 fail——真失败要到 scrape 才暴露）。load_seed_accounts（accounts.py:18）读活动 sheet，首行前 4 列须严格等于 (分类,账号名称,@用户名,简介核心内容) 否则 ValueError；按去 @ 用户名去重。seed_accounts 用 ON CONFLICT DO UPDATE 只覆盖 source_* 三列，重导种子不清已抓数据。

write_reports（reports.py:735）：collect() 得 Report → 渲染 md + 自包含 html → 可选 headless Chrome 转 pdf。md/html 必出，pdf 可缺。

collect（唯一读库处，reports.py:118）：6 条 SQL 一次性把 5 张表读进内存 shape 成 Report dataclass，渲染层不再碰 DB。派生：by_category 分桶后桶内按 followers 降序；top = 全部推文按 Tweet.score 降序取 30。

报告结构

统计头部 → 目录 → 全局 Top 30 推文 → 按分类展开（每账号 profile + 该账号全部推文按 score 降序，含媒体缩略图，中英对照）→ 失败账号表。HTML 内联 CSS+JS，含深/浅/print 三主题、搜索过滤、中英显隐、?expand=1 展开。

PDF 靠本机 Chrome（_find_chrome 先查 macOS 四个 .app 再 shutil.which），命令 chrome --headless=new --print-to-pdf，找不到则静默降级只出 md+html。

XSqliteSource（x_sqlite.py:136）把 x.sqlite3 作为只读、增量的 Source 接进 agent 抓取层。

8.1 增量映射 XSqliteSource.fetch

• 只读打开（_open_ro）：3 段 fallback file:?mode=ro&immutable=1（WAL 下唯一稳，读 last commit 不抢锁）→ ?mode=ro → 普通 connect；db 不存在设 last_error 返回 None 降级不抛。
• 增量 SQL：text<>'' 恒成立，since 非空再加 (first_seen_at IS NULL OR first_seen_at > ?)（开区间；NULL 行永远放过，靠下游去重挡），LEFT JOIN accounts 取 category/display_name，ORDER BY first_seen_at DESC NULLS LAST（老 SQLite 去词 fallback），LIMIT（source 默认 500 / job 默认 200）。
• 过滤：默认过滤 reply / retweet；可选 categories 白名单；二次空文本过滤。
• 中英拼接：若 translations 有 zh 译，text = 原文 + "\n\n[zh] 译文"，让 classifier 同看中英提升中文命中。

8.2 9 分类 → 主线（关键设计：不映射）

KNOWN_CATEGORIES 9 大分类：全球卫星运营商 / 其他细分航天企业 / 军工航天巨头 / 各国官方航天机构 / 在轨专项航天项目账号 / 民营航天企业（美国）/ 航天从业者/宇航员 / 航天媒体&资讯博主 / 非洲航天相关。这 9 分类不映射到主线——只拼进 source 标签 X · {category} · @{handle} 供反查，主线判定完全由下游 classifier 读 text 决定（媒体博主/在轨专项常跨主线，强绑会误分）。

8.3 x-ingest cron 链 · 24h 时序

抓取是 operator 手动触发的（不在时钟上），产出 x.sqlite3 后，两条链路各自按固定时刻消费。下图按每日时钟排布 4 类执行者的调度点。

各 action 明细：

8.4 export / backfill / 回写 wiki（均手动，不在 cron）

• export_x_events.py：复用 XSqliteSource 读近 30 天 → 按 shared_keywords 过滤 → 脱敏 5 字段 JSONL → data-live/x-events-archive.jsonl（原子落盘）→ push → Actions 读它。Actions 永远看不到 x.sqlite3 本体。
• backfill_x_occurred_at.py：一次性把历史 Twitter 格式 occurred_at 回填成 ISO（幂等、--dry-run）；因 decide 窗口/排序按字符串比 occurred_at，非 ISO 给错时序。
• x_to_wiki.py：读近 14 天 → 用 wiki 实体别名 matcher 做 NER → 命中 slug 整段替换目标 md 的 ## X 动态 段（原子写）；整账号零命中 → 起草 _drafts/x_new_entities/<account>.md 供人审。

• 登录 / 换 cookie：首次 cli login 或 import-cookies（校验 auth_token+ct0）。cookie 失效表现为整份 seed 逐个跑成 unauthorized——见到即重导 fresh cookie。
• 续跑 / 省 quota：撞 429 或部分失败后用 scrape --only <handle…> 只抓未成功账号（未命中会 WARN）。
• 429 应对：等 1–2 小时让限流窗口过 → --only 续跑 → 实在卡死重导 cookie。降概率：把 sleep_between_accounts 从 [3,7] 拉到 [8,15]（上轮在第 63 账号 429）。
• 定时窗口：抓取手动（不进调度链）；ingest 链 launchd 03:00（本机）/ 生产 06:45；x-freshness 断供监控 48h，注册须 --max-failures 999。
• 翻译工作流：dump_for_translate.py（去已译、CJK≥60% 跳过、每 250 条一批）→ 人工/子 agent 译 → import_translations.py（_lenient_parse 容忍未转义引号，INSERT OR REPLACE）。
• 路径：脚本硬编码 /Users/john/InvesResearch/expert/X；NEXT_STEPS.md:29 残留老路径 /Users/john/lichao/X，换机器要改。

散落的重要 file:line 速查表。