candidate-pool 2.0.0

package/build_universe.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * build_universe.js —— 生成/刷新候选观察池 candidates.json
+ *
+ * 背景：R01（量能验证突破）的市值门槛是 20~500 亿，属于中小盘短线打法；
+ *       R07（板块内补涨）要求同行业有足够样本，中位涨幅才有代表性。
+ *       因此观察池必须「行业铺得开 + 中小盘为主 + 保留少量龙头做行业锚」。
+ *
+ * 做法：种子清单只维护【6 位代码 + 申万一级行业】，其余全部由接口回填并校验：
+ *   1. 批量拉 qt.gtimg.cn 报价（一次可查上百只，GBK 编码）
+ *   2. 丢弃：代码不存在 / 停牌无价 / 名称含 ST / 总市值低于下限
+ *   3. 股票名称一律以接口返回为准，避免人工维护的名称与代码错配
+ *
+ * 用法：
+ *   node build_universe.js                 # 生成 candidates.json
+ *   node build_universe.js --min-cap 15    # 自定义市值下限（亿）
+ *   node build_universe.js --dry           # 只打印结果不写文件
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { now } = require('./time');
+const paths = require('./paths');
+
+// 输出跟随工作目录（见 paths.js）：默认 <仓库根>/candidates.json
+const OUT = paths.candidatesFile();
+const BATCH = 60;          // 每批查询只数
+const DEFAULT_MIN_CAP = 15; // 总市值下限（亿）
+
+// ---------------------------------------------------------------------------
+// 种子清单：申万一级行业 -> 6 位代码
+// 以中小盘为主，并保留各行业龙头作为行业涨幅锚点（R01 会用 20~500 亿自行卡市值）
+// ---------------------------------------------------------------------------
+const SEED = {
+  '食品饮料': ['600519', '000858', '600887', '603288', '002557', '002847', '002216', '600305',
+    '002481', '603719', '300973', '603345', '002732', '603517', '603866', '600882',
+    '603711', '603317', '002507', '002661', '603027', '603697'],
+  '医药生物': ['600276', '603259', '300760', '300122', '300003', '002007', '300244', '300482',
+    '603658', '300529', '688180', '300639', '603987', '002019', '600079', '000513',
+    '600976', '603229', '300888', '002020'],
+  '电力设备': ['300750', '601012', '300274', '002028', '601567', '300001', '002518', '603606',
+    '002335', '300724', '002851', '603063', '300827', '002531', '300443', '603985',
+    '002080', '600885', '002506'],
+  '汽车': ['002594', '601633', '600104', '002472', '603596', '002536', '603997', '300258',
+    '002101', '601965', '002906', '603178', '600699', '603348', '300825', '605005'],
+  '家用电器': ['000333', '000651', '600690', '002032', '002242', '603868', '002508', '002959',
+    '603579', '002614', '605365', '300894', '603515', '002035', '000921', '603355', '002403'],
+  '电子': ['002475', '002241', '603501', '688981', '002049', '300623', '300782', '688396',
+    '002156', '300661', '002185', '300223', '603160', '300458', '603662', '002138',
+    '300408', '300207', '300679', '603236', '300346'],
+  '计算机': ['002230', '688111', '603019', '300454', '002439', '300036', '300253', '300377',
+    '300271', '603039', '300579', '300085', '002195', '300229', '600845', '002261', '300525'],
+  '传媒': ['300413', '002027', '300251', '002739', '601801', '300058', '002400', '600088',
+    '300148', '002803', '601928', '300182', '600551', '300364', '002624', '300043'],
+  '银行': ['600036', '601398', '002142', '002966', '601528', '601860', '600926', '002807',
+    '603323', '601128', '600908', '601077', '601187', '600928', '002958'],
+  '非银金融': ['300059', '600030', '601377', '600909', '601198', '000728', '600155', '002926',
+    '601108', '000750', '601375', '002673', '601696', '300773'],
+  '房地产': ['600048', '000002', '000961', '600325', '002244', '600663', '600648', '000402',
+    '600383', '600895', '000031', '600639', '002285'],
+  '建筑材料': ['600585', '002271', '603737', '600801', '000401', '603916', '002088', '603601',
+    '300715', '002233', '600720', '603266'],
+  '基础化工': ['600309', '002324', '603650', '002326', '600409', '002250', '603067', '300848',
+    '002741', '603379', '002497', '600596', '600426'],
+  '机械设备': ['600031', '300124', '603338', '002158', '603611', '300415', '603757', '002559',
+    '002438', '300185', '603025', '002097', '300747', '603667'],
+  '有色金属': ['601899', '002460', '600549', '002203', '000807', '600711', '002378', '601168',
+    '000630', '600497', '002114', '000751', '600459', '002240'],
+  '煤炭': ['601088', '601225', '000983', '600971', '601001', '000933', '600985', '601699',
+    '600395', '601918', '000552', '600123', '601666'],
+  '石油石化': ['600028', '601857', '603353', '002554', '600583', '603727', '002207', '600871',
+    '000637', '603619', '300084', '002828'],
+  '钢铁': ['600019', '000709', '600507', '000825', '600282', '002110', '600581', '000778',
+    '600808', '002478', '600117', '002756', '603878'],
+  '交通运输': ['002352', '601816', '600233', '002468', '603056', '002120', '601008', '600717',
+    '000088', '600798', '601018', '600018', '603565', '603967'],
+  '农林牧渔': ['002714', '300498', '002567', '603477', '002385', '002124', '600975', '002100',
+    '300761', '600598', '000998', '002299', '603609', '002234', '300087', '002311'],
+  '公用事业': ['600900', '000883', '000539', '600863', '000027', '600995', '601016', '000531',
+    '600236', '000601', '600098', '300070', '000544', '601158'],
+  '通信': ['000063', '600941', '002396', '600498', '300394', '002281', '600487', '002115',
+    '603322', '002446', '600522', '300628'],
+  '国防军工': ['600760', '600893', '300696', '002389', '300719', '002465', '300775', '603267',
+    '600435', '002025', '600501', '300581', '002829', '688122'],
+  '商贸零售': ['601933', '002251', '600694', '000759', '600828', '002697', '603708', '002187',
+    '600682', '000715', '603214', '603123'],
+  '美容护理': ['603605', '603983', '300740', '605136', '002762', '603630', '300886', '605009'],
+  '轻工制造': ['603833', '002572', '603816', '300616', '603313', '002853', '603898', '600433',
+    '002078', '600966', '002511', '603116'],
+};
+
+// ---------------------------------------------------------------------------
+function toFullCode(c) {
+  const s = String(c).trim();
+  if (/^6/.test(s)) return 'sh' + s;
+  if (/^[03]/.test(s)) return 'sz' + s;
+  if (/^[48]/.test(s)) return 'bj' + s;
+  return 'sh' + s;
+}
+
+function decodeGbk(buf) {
+  try { return new TextDecoder('gbk').decode(buf); }
+  catch (e) { return buf.toString('binary'); } // 兜底：中文会乱码，但代码/数字仍可用
+}
+
+function getRaw(url, retries = 3) {
+  return new Promise(async (resolve, reject) => {
+    let lastErr;
+    for (let i = 0; i < retries; i++) {
+      if (i > 0) await new Promise(r => setTimeout(r, 600 * i));
+      try {
+        return resolve(await new Promise((res, rej) => {
+          const req = https.get(url, {
+            timeout: 20000,
+            headers: { 'User-Agent': 'Mozilla/5.0', 'Referer': 'https://gu.qq.com/' },
+          }, r => {
+            const chunks = [];
+            r.on('data', c => chunks.push(c));
+            r.on('end', () => res(Buffer.concat(chunks)));
+          });
+          req.on('error', rej);
+          req.on('timeout', () => { req.destroy(); rej(new Error('timeout')); });
+        }));
+      } catch (e) { lastErr = e; }
+    }
+    reject(lastErr);
+  });
+}
+
+async function fetchBatch(codes) {
+  const buf = await getRaw('https://qt.gtimg.cn/q=' + codes.join(','));
+  const txt = decodeGbk(buf);
+  const out = {};
+  for (const seg of txt.split(';')) {
+    const m = seg.match(/v_([a-z]{2}\d{6})="([^"]*)"/);
+    if (!m) continue;
+    const f = m[2].split('~');
+    if (f.length < 50) continue;
+    const price = parseFloat(f[3]) || parseFloat(f[4]);
+    out[m[1]] = {
+      code: m[1],
+      name: (f[1] || '').replace(/\s+/g, ''), // 交易所原始简称含空格（如“五 粮 液”），统一去掉
+      price,
+      circCapYi: parseFloat(f[44]),   // 流通市值（亿）
+      totalCapYi: parseFloat(f[45]),  // 总市值（亿）
+    };
+  }
+  return out;
+}
+
+function parseArgs() {
+  const a = process.argv.slice(2);
+  const get = (k, d) => { const i = a.indexOf(k); return i >= 0 ? a[i + 1] : d; };
+  return { minCap: +get('--min-cap', DEFAULT_MIN_CAP), dry: a.includes('--dry') };
+}
+
+(async () => {
+  const { minCap, dry } = parseArgs();
+
+  // 展开种子清单并去重（同一代码若出现在多个行业，以首次出现为准）
+  const seen = new Set();
+  const wanted = [];
+  for (const [sector, list] of Object.entries(SEED)) {
+    for (const c of list) {
+      const full = toFullCode(c);
+      if (seen.has(full)) continue;
+      seen.add(full);
+      wanted.push({ code: full, sector });
+    }
+  }
+  console.log(`种子清单 ${wanted.length} 只，覆盖 ${Object.keys(SEED).length} 个申万一级行业`);
+
+  // 分批拉报价
+  const quotes = {};
+  for (let i = 0; i < wanted.length; i += BATCH) {
+    const chunk = wanted.slice(i, i + BATCH);
+    process.stdout.write(`  拉取报价 ${i + 1}~${Math.min(i + BATCH, wanted.length)} ...`);
+    try {
+      Object.assign(quotes, await fetchBatch(chunk.map(w => w.code)));
+      console.log(' ok');
+    } catch (e) { console.log(' 失败: ' + e.message); }
+  }
+
+  // 校验过滤
+  const kept = [], dropped = [];
+  for (const w of wanted) {
+    const q = quotes[w.code];
+    if (!q) { dropped.push([w.code, w.sector, '接口无返回（代码可能不存在）']); continue; }
+    if (!q.price || !isFinite(q.price)) { dropped.push([w.code, w.sector, '无有效价格（长期停牌/退市）']); continue; }
+    if (/ST|退/i.test(q.name)) { dropped.push([w.code, w.sector, `风险股 ${q.name}`]); continue; }
+    const cap = isFinite(q.totalCapYi) ? q.totalCapYi : q.circCapYi;
+    if (!isFinite(cap) || cap < minCap) { dropped.push([w.code, w.sector, `市值过小 ${cap}亿`]); continue; }
+    kept.push({ code: w.code, name: q.name || w.code, sector: w.sector, capYi: Math.round(cap) });
+  }
+
+  // 统计
+  const bySector = {};
+  for (const k of kept) (bySector[k.sector] = bySector[k.sector] || []).push(k);
+  const inR01Band = kept.filter(k => k.capYi >= 20 && k.capYi <= 500);
+
+  console.log(`\n保留 ${kept.length} 只 / 剔除 ${dropped.length} 只`);
+  if (dropped.length) {
+    console.log('剔除明细:');
+    dropped.forEach(d => console.log(`  ${d[0]}  [${d[1]}]  ${d[2]}`));
+  }
+  console.log(`\n落在 R01 市值带（20~500亿）的标的: ${inR01Band.length} 只`);
+  console.log('各行业成分数:');
+  Object.entries(bySector).sort((a, b) => b[1].length - a[1].length)
+    .forEach(([s, v]) => {
+      const band = v.filter(x => x.capYi >= 20 && x.capYi <= 500).length;
+      console.log(`  ${s.padEnd(6)} 共 ${String(v.length).padStart(2)} 只（其中 R01 市值带 ${band} 只）`);
+    });
+
+  const thin = Object.entries(bySector).filter(([, v]) => v.length < 5).map(([s]) => s);
+  if (thin.length) console.log(`\n⚠ 样本偏少(<5)的行业，R07 中位数代表性弱: ${thin.join('、')}`);
+
+  if (dry) { console.log('\n--dry 模式，未写入文件'); return; }
+
+  const payload = {
+    name: 'A股短线候选观察池',
+    note: '由 build_universe.js 生成；名称/市值来自腾讯行情接口校验，可手工增删 stocks 条目',
+    generatedAt: now(),
+    minCapYi: minCap,
+    count: kept.length,
+    stocks: kept.map(k => ({ code: k.code, name: k.name, sector: k.sector })),
+  };
+  fs.writeFileSync(OUT, JSON.stringify(payload, null, 2), 'utf8');
+  console.log(`\n已写出 ${OUT}（${kept.length} 只）`);
+})().catch(e => { console.error('构建失败:', e.message); process.exit(1); });

package/candidates.example.json

@@ -0,0 +1,269 @@
+{
+  "name": "A股短线候选观察池（示例模板）",
+  "note": "这是**示例模板**，不是可用的观察池。请按自己的口径替换 stocks —— 推荐用 `node build_universe.js` 按市值门槛重建（会校验名称并补全行业），或直接手工增删条目。",
+  "generatedAt": "2026-09-21T05:14:50.201Z",
+  "minCapYi": 15,
+  "count": 52,
+  "stocks": [
+    {
+      "code": "sz002352",
+      "name": "顺丰控股",
+      "sector": "交通运输"
+    },
+    {
+      "code": "sh601816",
+      "name": "京沪高铁",
+      "sector": "交通运输"
+    },
+    {
+      "code": "sz300413",
+      "name": "芒果超媒",
+      "sector": "传媒"
+    },
+    {
+      "code": "sz002027",
+      "name": "分众传媒",
+      "sector": "传媒"
+    },
+    {
+      "code": "sh600900",
+      "name": "长江电力",
+      "sector": "公用事业"
+    },
+    {
+      "code": "sz000883",
+      "name": "湖北能源",
+      "sector": "公用事业"
+    },
+    {
+      "code": "sz002714",
+      "name": "牧原股份",
+      "sector": "农林牧渔"
+    },
+    {
+      "code": "sz300498",
+      "name": "温氏股份",
+      "sector": "农林牧渔"
+    },
+    {
+      "code": "sh600276",
+      "name": "恒瑞医药",
+      "sector": "医药生物"
+    },
+    {
+      "code": "sh603259",
+      "name": "药明康德",
+      "sector": "医药生物"
+    },
+    {
+      "code": "sh601933",
+      "name": "永辉超市",
+      "sector": "商贸零售"
+    },
+    {
+      "code": "sz002251",
+      "name": "步步高",
+      "sector": "商贸零售"
+    },
+    {
+      "code": "sh600760",
+      "name": "中航沈飞",
+      "sector": "国防军工"
+    },
+    {
+      "code": "sh600893",
+      "name": "航发动力",
+      "sector": "国防军工"
+    },
+    {
+      "code": "sh600309",
+      "name": "万华化学",
+      "sector": "基础化工"
+    },
+    {
+      "code": "sz002324",
+      "name": "普利特",
+      "sector": "基础化工"
+    },
+    {
+      "code": "sz000333",
+      "name": "美的集团",
+      "sector": "家用电器"
+    },
+    {
+      "code": "sz000651",
+      "name": "格力电器",
+      "sector": "家用电器"
+    },
+    {
+      "code": "sh600585",
+      "name": "海螺水泥",
+      "sector": "建筑材料"
+    },
+    {
+      "code": "sz002271",
+      "name": "东方雨虹",
+      "sector": "建筑材料"
+    },
+    {
+      "code": "sh600048",
+      "name": "保利发展",
+      "sector": "房地产"
+    },
+    {
+      "code": "sz000002",
+      "name": "万科Ａ",
+      "sector": "房地产"
+    },
+    {
+      "code": "sh601899",
+      "name": "紫金矿业",
+      "sector": "有色金属"
+    },
+    {
+      "code": "sz002460",
+      "name": "赣锋锂业",
+      "sector": "有色金属"
+    },
+    {
+      "code": "sh600031",
+      "name": "三一重工",
+      "sector": "机械设备"
+    },
+    {
+      "code": "sz300124",
+      "name": "汇川技术",
+      "sector": "机械设备"
+    },
+    {
+      "code": "sz002594",
+      "name": "比亚迪",
+      "sector": "汽车"
+    },
+    {
+      "code": "sh601633",
+      "name": "长城汽车",
+      "sector": "汽车"
+    },
+    {
+      "code": "sh601088",
+      "name": "中国神华",
+      "sector": "煤炭"
+    },
+    {
+      "code": "sh601225",
+      "name": "陕西煤业",
+      "sector": "煤炭"
+    },
+    {
+      "code": "sz300750",
+      "name": "宁德时代",
+      "sector": "电力设备"
+    },
+    {
+      "code": "sh601012",
+      "name": "隆基绿能",
+      "sector": "电力设备"
+    },
+    {
+      "code": "sz002475",
+      "name": "立讯精密",
+      "sector": "电子"
+    },
+    {
+      "code": "sz002241",
+      "name": "歌尔股份",
+      "sector": "电子"
+    },
+    {
+      "code": "sh600028",
+      "name": "中国石化",
+      "sector": "石油石化"
+    },
+    {
+      "code": "sh601857",
+      "name": "中国石油",
+      "sector": "石油石化"
+    },
+    {
+      "code": "sh603605",
+      "name": "珀莱雅",
+      "sector": "美容护理"
+    },
+    {
+      "code": "sh603983",
+      "name": "丸美生物",
+      "sector": "美容护理"
+    },
+    {
+      "code": "sz002230",
+      "name": "科大讯飞",
+      "sector": "计算机"
+    },
+    {
+      "code": "sh688111",
+      "name": "金山办公",
+      "sector": "计算机"
+    },
+    {
+      "code": "sh603833",
+      "name": "欧派家居",
+      "sector": "轻工制造"
+    },
+    {
+      "code": "sz002572",
+      "name": "索菲亚",
+      "sector": "轻工制造"
+    },
+    {
+      "code": "sz000063",
+      "name": "中兴通讯",
+      "sector": "通信"
+    },
+    {
+      "code": "sh600941",
+      "name": "中国移动",
+      "sector": "通信"
+    },
+    {
+      "code": "sh600019",
+      "name": "宝钢股份",
+      "sector": "钢铁"
+    },
+    {
+      "code": "sz000709",
+      "name": "河钢股份",
+      "sector": "钢铁"
+    },
+    {
+      "code": "sh600036",
+      "name": "招商银行",
+      "sector": "银行"
+    },
+    {
+      "code": "sh601398",
+      "name": "工商银行",
+      "sector": "银行"
+    },
+    {
+      "code": "sz300059",
+      "name": "东方财富",
+      "sector": "非银金融"
+    },
+    {
+      "code": "sh600030",
+      "name": "中信证券",
+      "sector": "非银金融"
+    },
+    {
+      "code": "sh600519",
+      "name": "贵州茅台",
+      "sector": "食品饮料"
+    },
+    {
+      "code": "sz000858",
+      "name": "五粮液",
+      "sector": "食品饮料"
+    }
+  ]
+}

package/db/.env.example

@@ -0,0 +1,13 @@
+# Cloudflare D1 凭据（从 Cloudflare 控制台获取）
+#
+# 用法：复制本文件为 db/.env 并填入真实值即可生效（请勿提交真实值，已被 .gitignore 忽略）。
+# 该文件由 db/d1client.js 通过 dotenv 加载，被 backfill.js / write_live.js / enrich_stock_base.js 等复用。
+# 优先级：**已存在的系统环境变量 / CI Secrets 优先**（dotenv 默认不覆盖已存在的变量）。
+CF_ACCOUNT_ID=your_account_id
+CF_D1_DATABASE_ID=your_d1_database_id
+CF_API_TOKEN=your_api_token_with_d1_edit_permission
+
+# 获取位置：
+# - CF_ACCOUNT_ID：右侧头像 → Account Home 里的 "Account ID"
+# - CF_D1_DATABASE_ID：wrangler d1 create 后返回的 uuid，或控制台 Storage/D1 详情页
+# - CF_API_TOKEN：API Tokens 页创建，权限勾选 "Account → D1 → Edit"

package/db/backfill.js

@@ -0,0 +1,71 @@
+'use strict';
+// 历史回填：遍历 data/snapshot-*.json（覆盖全部历史运行），规范化后写入
+//   Cloudflare D1（默认，不写本地）/ 本地 SQLite（--local）/ 两边都写（--both）。
+// 也支持 --dry 仅解析统计、不接触网络。
+//
+// 全量幂等重放：run_batch UNIQUE(anchor_date)、pick_record UNIQUE(run_id,code)、
+// price_daily UNIQUE(code,date)，重复运行不会重复插入 —— 因此「哪边落后就跑一次」即可追平。
+const fs = require('fs');
+const path = require('path');
+const { normalizeSnap } = require('./normalize');
+const { persistSnap } = require('./persist');
+const { resolveTargets } = require('./clients');
+const paths = require('../paths');
+
+// 快照目录跟随工作目录（见 paths.js）：默认 <仓库根>/data
+const DATA = paths.dataDir();
+const isDry = process.argv.includes('--dry');
+
+function listSnaps() {
+  if (!fs.existsSync(DATA)) return [];
+  return fs.readdirSync(DATA).filter(f => /^snapshot-\d{4}-\d{2}-\d{2}\.json$/.test(f)).sort();
+}
+
+(async () => {
+  const files = listSnaps();
+  if (!files.length) { console.log('[backfill] 无 snapshot 文件'); return; }
+
+  const { targets, notes } = isDry ? { targets: [], notes: [] } : resolveTargets();
+  for (const n of notes) console.log('[backfill] ' + n);
+  if (!isDry && !targets.length) {
+    console.log('[backfill] 未指定写入目标：--local 写本地 / --both 两边都写 / 配好 CF_* 凭据后默认写远程');
+  }
+  for (const t of targets) console.log(`[backfill] 写入目标 ${t.name}${t.file ? ' -> ' + t.file : ''}`);
+
+  console.log(`[backfill] 发现 ${files.length} 份快照${isDry ? '（dry-run，不写库）' : ''}`);
+
+  const totals = new Map();
+  for (const t of targets) totals.set(t.name, { picks: 0, prices: 0, base: 0, fail: 0 });
+
+  let totalPicks = 0, totalPrices = 0, totalBase = 0, parseFail = 0;
+  for (const f of files) {
+    const file = path.join(DATA, f);
+    let snap;
+    try { snap = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch (e) { console.log(`  ✗ ${f}: 解析失败 ${e.message}`); parseFail++; continue; }
+    const { run, picks, prices, base } = normalizeSnap(snap);
+    console.log(`  · ${run.anchor_date}  全池 ${run.universe_count}  重点 ${run.high_count} / 次级 ${run.secondary_count} / 条件 ${run.conditional_count} / 排除 ${run.excluded_count}  R01 ${run.r01_count} R07 ${run.r07_count} R05 ${run.r05_count}`);
+    totalPicks += picks.length; totalPrices += prices.length; totalBase += base.length;
+
+    for (const t of targets) {
+      try {
+        await persistSnap(snap, t.client);
+        const acc = totals.get(t.name);
+        acc.picks += picks.length; acc.prices += prices.length; acc.base += base.length;
+      } catch (e) {
+        console.log(`  ✗ ${f} → ${t.name}: 入库失败 ${e.message}`);
+        totals.get(t.name).fail++;
+      }
+    }
+  }
+  for (const t of targets) if (t.client.close) t.client.close();
+
+  console.log(`[backfill] 解析合计：picks=${totalPicks} prices=${totalPrices} base=${totalBase}${parseFail ? ` 解析失败 ${parseFail}` : ''}`);
+  for (const [name, a] of totals) {
+    const runs = files.length - parseFail - a.fail;
+    console.log(`[backfill] ${name} 完成：runs=${runs} picks=${a.picks} prices=${a.prices} base=${a.base}${a.fail ? ` 失败 ${a.fail}` : ''}`);
+  }
+  if (!isDry && targets.length > 1) {
+    console.log('[backfill] 提示：两端都写完后可跑 `node db/verify_sync.js` 核对指纹是否一致');
+  }
+})().catch(e => { console.error('[backfill] 中止:', e.message); process.exit(1); });

package/db/clients.js

@@ -0,0 +1,48 @@
+'use strict';
+// 入库目标选择：把「写远程 D1 / 写本地 SQLite / 两边都写」收敛到一处，
+// 供 backfill.js 与 write_live.js 共用（此前两边各写了一份互斥判断）。
+//
+// 为什么要有 --both：
+//   两个库原本由「互斥分支」写入 —— 不加 --local 只写远程，加了只写本地，
+//   一次运行只能写一边。而本机日常任务（run_today.*）与 GitHub 定时任务
+//   （daily-screen.yml）走的都是远程，于是 db/local.db 永远停在旧数据上。
+//   data/snapshot-*.json 是唯一真相来源，且 backfill 是「全量幂等重放」，
+//   所以「谁落后就跑 --both 追平」就够了，不需要增量同步或差异比对。
+const localSqlite = require('./sqlite_client');
+const d1 = require('./d1client');
+
+const has = (argv, flag) => argv.includes(flag);
+
+/**
+ * 解析命令行参数得出写入目标。
+ *
+ * | 参数      | 远程 D1        | 本地 db/local.db |
+ * |-----------|----------------|------------------|
+ * | （无）    | 有凭据则写     | 不写             |
+ * | --local   | 不写           | 写               |
+ * | --both    | 有凭据则写     | 写               |
+ *
+ * @param {string[]} argv 命令行参数，默认 process.argv
+ * @returns {{targets: Array<{name: 'remote'|'local', client: object, file?: string}>, notes: string[]}}
+ *   notes 是需要调用方打印的提示（例如缺少远程凭据）。
+ */
+function resolveTargets(argv = process.argv) {
+  const wantLocal = has(argv, '--local') || has(argv, '--both');
+  const wantRemote = has(argv, '--both') || !has(argv, '--local');
+  const targets = [];
+  const notes = [];
+
+  if (wantRemote) {
+    if (d1.cfg()) targets.push({ name: 'remote', client: d1 });
+    else notes.push('未配置 CF_ACCOUNT_ID / CF_D1_DATABASE_ID / CF_API_TOKEN，跳过远程 D1（设 --local 只写本地，或配好凭据后重跑）');
+  }
+
+  if (wantLocal) {
+    const client = localSqlite.createClient();
+    targets.push({ name: 'local', client, file: client.file });
+  }
+
+  return { targets, notes };
+}
+
+module.exports = { resolveTargets };