@zhin.js/plugin-lottery 1.0.0

package/src/evaluate/tracker.ts

@@ -0,0 +1,311 @@
+import { DEFAULT_WEIGHTS, type DrawNumbers, type GameId, type GamePick, type HitSummary, type NormalizedDraw, type ScoreWeights, type AccuracySnapshot } from '../types.js';
+
+import { loadDraws, parseStoredJson, type LotteryDb } from '../db.js';
+
+import { comparePickToDraw, tuneWeightsFromDraw, formatHitSummary } from './hit-rate.js';
+import { formatWeights, normalizeWeights } from '../stats/weights.js';
+
+export const PREDICTIONS_TABLE = 'lottery_predictions';
+export const WEIGHTS_TABLE = 'lottery_model_weights';
+export const MEMORY_TABLE = 'lottery_agent_memory';
+
+export function defineEvalTables(db: { define: (name: string, schema: Record<string, unknown>) => void }): void {
+  db.define(PREDICTIONS_TABLE, {
+    game_id: { type: 'text', nullable: false },
+    predict_at: { type: 'text', nullable: false },
+    predict_date: { type: 'text', default: '' },
+    numbers: { type: 'text', default: '{}' },
+    weights: { type: 'text', default: '{}' },
+    status: { type: 'text', default: 'pending' },
+    actual_issue: { type: 'text', default: '' },
+    actual_numbers: { type: 'text', default: '' },
+    hit_summary: { type: 'text', default: '' },
+    analysis: { type: 'text', default: '' },
+    evaluated_at: { type: 'text', default: '' },
+  });
+  db.define(WEIGHTS_TABLE, {
+    game_id: { type: 'text', nullable: false },
+    freq_weight: { type: 'text', default: '0.4' },
+    omit_weight: { type: 'text', default: '0.35' },
+    trend_weight: { type: 'text', default: '0.25' },
+    eval_count: { type: 'text', default: '0' },
+    avg_hit_rate: { type: 'text', default: '0' },
+    updated_at: { type: 'text', default: '' },
+  });
+  db.define(MEMORY_TABLE, {
+    game_id: { type: 'text', default: '' },
+    memory_type: { type: 'text', default: 'insight' },
+    content: { type: 'text', default: '' },
+    created_at: { type: 'text', default: '' },
+  });
+}
+
+export async function loadGameWeights(db: LotteryDb, gameId: GameId): Promise<ScoreWeights> {
+  const model = db.models.get(WEIGHTS_TABLE);
+  if (!model) return { ...DEFAULT_WEIGHTS };
+  const rows = (await model.select().where({ game_id: gameId })) as Array<{
+    freq_weight: string;
+    omit_weight: string;
+    trend_weight: string;
+  }>;
+  if (!rows.length) return { ...DEFAULT_WEIGHTS };
+  const r = rows[0];
+  if (!r) return { ...DEFAULT_WEIGHTS };
+  return {
+    freq: Number.parseFloat(r.freq_weight) || DEFAULT_WEIGHTS.freq,
+    omit: Number.parseFloat(r.omit_weight) || DEFAULT_WEIGHTS.omit,
+    trend: Number.parseFloat(r.trend_weight) || DEFAULT_WEIGHTS.trend,
+  };
+}
+
+export async function hasWeightsRow(db: LotteryDb, gameId: GameId): Promise<boolean> {
+  const model = db.models.get(WEIGHTS_TABLE);
+  if (!model) return false;
+  const rows = (await model.select().where({ game_id: gameId })) as unknown[];
+  return rows.length > 0;
+}
+
+export async function saveGameWeights(
+  db: LotteryDb,
+  gameId: GameId,
+  weights: ScoreWeights,
+  evalCount: number,
+  avgHitRate: number,
+): Promise<void> {
+  const model = db.models.get(WEIGHTS_TABLE);
+  if (!model) return;
+  const normalized = normalizeWeights(weights);
+  const existing = (await model.select().where({ game_id: gameId })) as unknown[];
+  const row = {
+    game_id: gameId,
+    freq_weight: String(normalized.freq),
+    omit_weight: String(normalized.omit),
+    trend_weight: String(normalized.trend),
+    eval_count: String(evalCount),
+    avg_hit_rate: String(avgHitRate),
+    updated_at: new Date().toISOString(),
+  };
+  if (existing.length) await model.delete().where({ game_id: gameId });
+  await model.insert(row);
+}
+
+export async function loadAccuracySnapshot(db: LotteryDb, gameId: GameId): Promise<AccuracySnapshot | undefined> {
+  const model = db.models.get(WEIGHTS_TABLE);
+  const predModel = db.models.get(PREDICTIONS_TABLE);
+  if (!model || !predModel) return undefined;
+  const wrows = (await model.select().where({ game_id: gameId })) as Array<{
+    eval_count: string;
+    avg_hit_rate: string;
+  }>;
+  const evalCount = Number.parseInt(wrows[0]?.eval_count ?? '0', 10) || 0;
+  const avgHitRate = Number.parseFloat(wrows[0]?.avg_hit_rate ?? '0') || 0;
+  const preds = (await predModel.select().where({ game_id: gameId, status: 'evaluated' })) as Array<{
+    hit_summary: string | HitSummary;
+    evaluated_at: string;
+  }>;
+  const recent = [...preds]
+    .sort((a, b) => (b.evaluated_at ?? '').localeCompare(a.evaluated_at ?? ''))
+    .slice(0, 5)
+    .map((p) => {
+      const h = parseStoredJson<HitSummary>(p.hit_summary, { total: 0, hits: 0, rate: 0, detail: '-' });
+      return `${(h.rate * 100).toFixed(0)}%`;
+    });
+  if (!evalCount) return undefined;
+  return { evalCount, avgHitRate, recent5: recent.length ? recent.join(',') : '-' };
+}
+
+export async function cancelTodayPendingPredictions(
+  db: LotteryDb,
+  gameId: GameId,
+  date = new Date(),
+): Promise<void> {
+  const model = db.models.get(PREDICTIONS_TABLE);
+  if (!model) return;
+  const today = date.toISOString().slice(0, 10);
+  const pending = (await listPendingPredictions(db, gameId)) as Array<{ predict_at: string; predict_date: string }>;
+  for (const row of pending.filter((p) => p.predict_date === today)) {
+    await model.delete().where({ game_id: gameId, predict_at: row.predict_at, status: 'pending' });
+  }
+}
+
+export async function savePrediction(db: LotteryDb, pick: GamePick, at = new Date()): Promise<void> {
+  const model = db.models.get(PREDICTIONS_TABLE);
+  if (!model) return;
+  await model.insert({
+    game_id: pick.gameId,
+    predict_at: at.toISOString(),
+    predict_date: at.toISOString().slice(0, 10),
+    numbers: JSON.stringify(pick.numbers),
+    weights: JSON.stringify(pick.weights),
+    status: 'pending',
+    actual_issue: '',
+    actual_numbers: '',
+    hit_summary: '',
+    analysis: '',
+    evaluated_at: '',
+  });
+}
+
+export async function listPendingPredictions(db: LotteryDb, gameId?: GameId): Promise<unknown[]> {
+  const model = db.models.get(PREDICTIONS_TABLE);
+  if (!model) return [];
+  if (gameId) {
+    return model.select().where({ game_id: gameId, status: 'pending' });
+  }
+  const all = (await model.select().where({ status: 'pending' })) as unknown[];
+  return all;
+}
+
+export async function submitAgentReview(
+  db: LotteryDb,
+  input: {
+    gameId: GameId;
+    predictAt: string;
+    actualIssue: string;
+    actualNumbers: DrawNumbers;
+    analysis: string;
+    adjustWeights?: boolean;
+  },
+  historyLimit: number,
+): Promise<HitSummary | null> {
+  const predModel = db.models.get(PREDICTIONS_TABLE);
+  if (!predModel) return null;
+  const pending = (await predModel.select().where({
+    game_id: input.gameId,
+    predict_at: input.predictAt,
+    status: 'pending',
+  })) as Array<{ numbers: string | DrawNumbers; weights: string | ScoreWeights }>;
+  if (!pending.length) return null;
+
+  const row = pending[0];
+  if (!row) return null;
+  const pick: GamePick = {
+    gameId: input.gameId,
+    label: '',
+    numbers: parseStoredJson<DrawNumbers>(row.numbers, {}),
+    weights: parseStoredJson<ScoreWeights>(row.weights, DEFAULT_WEIGHTS),
+    stats: { gameId: input.gameId, sampleSize: 0, hot: [], cold: [], detail: '' },
+  };
+  const draw: NormalizedDraw = {
+    gameId: input.gameId,
+    issue: input.actualIssue,
+    drawTime: '',
+    numbers: input.actualNumbers,
+    source: 'fucai',
+  };
+  const hit = comparePickToDraw(pick, draw);
+  const history = await loadDraws(db, input.gameId, historyLimit);
+  const analysis = input.analysis.trim() || formatHitSummary(input.gameId, hit, input.actualIssue);
+
+  let evalCount = 0;
+  let avgHitRate = 0;
+  const wrows = (await db.models.get(WEIGHTS_TABLE)?.select().where({ game_id: input.gameId }) ?? []) as Array<{
+    eval_count: string;
+    avg_hit_rate: string;
+  }>;
+  if (wrows[0]) {
+    evalCount = Number.parseInt(wrows[0].eval_count, 10) || 0;
+    avgHitRate = Number.parseFloat(wrows[0].avg_hit_rate) || 0;
+  }
+  evalCount++;
+  avgHitRate = avgHitRate + (hit.rate - avgHitRate) / evalCount;
+
+  let weights = pick.weights;
+  if (input.adjustWeights !== false) {
+    weights = tuneWeightsFromDraw(weights, pick.numbers, draw.numbers, input.gameId, history);
+  }
+
+  await predModel.delete().where({ game_id: input.gameId, predict_at: input.predictAt, status: 'pending' });
+  await predModel.insert({
+    game_id: input.gameId,
+    predict_at: input.predictAt,
+    predict_date: input.predictAt.slice(0, 10),
+    numbers: JSON.stringify(pick.numbers),
+    weights: JSON.stringify(pick.weights),
+    status: 'evaluated',
+    actual_issue: input.actualIssue,
+    actual_numbers: JSON.stringify(input.actualNumbers),
+    hit_summary: JSON.stringify(hit),
+    analysis: analysis,
+    evaluated_at: new Date().toISOString(),
+  });
+  await saveGameWeights(db, input.gameId, weights, evalCount, avgHitRate);
+  return hit;
+}
+
+export async function saveAgentMemory(
+  db: LotteryDb,
+  content: string,
+  memoryType = 'insight',
+  gameId = '',
+): Promise<void> {
+  const model = db.models.get(MEMORY_TABLE);
+  if (!model || !content.trim()) return;
+  await model.insert({
+    game_id: gameId,
+    memory_type: memoryType,
+    content: content.trim(),
+    created_at: new Date().toISOString(),
+  });
+}
+
+export async function loadAgentMemory(db: LotteryDb, gameId?: string, limit = 20): Promise<unknown[]> {
+  const model = db.models.get(MEMORY_TABLE);
+  if (!model) return [];
+  let rows: unknown[] = [];
+  if (gameId) {
+    rows = (await model.select().where({ game_id: gameId })) as unknown[];
+  } else {
+    const games: Array<GameId | ''> = ['kl8', 'ssq', 'dlt', 'fc3d', 'pl3', 'pl5', ''];
+    for (const g of games) {
+      const part = (await model.select().where({ game_id: g })) as unknown[];
+      rows.push(...part);
+    }
+  }
+  return [...rows]
+    .sort((a, b) => String((b as { created_at?: string }).created_at ?? '').localeCompare(String((a as { created_at?: string }).created_at ?? '')))
+    .slice(0, limit);
+}
+
+export async function formatReviewReport(db: LotteryDb, gameId?: GameId): Promise<string> {
+  const predModel = db.models.get(PREDICTIONS_TABLE);
+  const memModel = db.models.get(MEMORY_TABLE);
+  if (!predModel) return '数据库未就绪';
+  const games: GameId[] = gameId ? [gameId] : ['kl8', 'ssq', 'dlt', 'fc3d', 'pl3', 'pl5'];
+  const lines = ['【彩票推荐复盘】', ''];
+  for (const gid of games) {
+    const weights = await loadGameWeights(db, gid);
+    const snap = await loadAccuracySnapshot(db, gid);
+    const preds = (await predModel.select().where({ game_id: gid, status: 'evaluated' })) as Array<{
+      actual_issue: string;
+      hit_summary: string | HitSummary;
+      analysis: string;
+      evaluated_at: string;
+    }>;
+    const recent = [...preds]
+      .sort((a, b) => (b.evaluated_at ?? '').localeCompare(a.evaluated_at ?? ''))
+      .slice(0, 5);
+    lines.push(`■ ${gid} 模型 ${formatWeights(weights)}`);
+    if (snap) {
+      lines.push(`  累计 ${snap.evalCount} 期 平均命中 ${(snap.avgHitRate * 100).toFixed(1)}%`);
+    } else {
+      lines.push('  尚无复盘数据');
+    }
+    for (const p of recent) {
+      const h = parseStoredJson<HitSummary>(p.hit_summary, { total: 0, hits: 0, rate: 0, detail: '-' });
+      lines.push(`  第${p.actual_issue}期 ${h.detail} (${(h.rate * 100).toFixed(0)}%)`);
+      if (p.analysis?.trim()) lines.push(`    ${p.analysis.trim()}`);
+    }
+    lines.push('');
+  }
+  if (memModel) {
+    const mem = await loadAgentMemory(db, gameId, 5);
+    if (mem.length) {
+      lines.push('【Agent 记忆】');
+      for (const m of mem as Array<{ game_id?: string; content?: string; memory_type?: string }>) {
+        lines.push(`- [${m.game_id || 'global'}/${m.memory_type}] ${m.content}`);
+      }
+    }
+  }
+  return lines.join('\n').trim();
+}

package/src/evaluate/train-weights.ts

@@ -0,0 +1,134 @@
+import { DEFAULT_WEIGHTS, type GameId, type ScoreWeights } from '../types.js';
+
+import { loadDraws, type LotteryDb } from '../db.js';
+
+import { runAdaptiveSimulation, type SimulationResult } from './adaptive-sim.js';
+import { walkForwardBacktest } from './backtest.js';
+import { shouldFallbackWeights } from './weight-guard.js';
+import { saveGameWeights } from './tracker.js';
+import { formatWeights } from '../stats/weights.js';
+
+export interface TrainWeightsOptions {
+  pickCount: number;
+  minHistory: number;
+  historyLimit: number;
+  randomTrials: number;
+  /** Start training from these weights; default F40/O35/T25. */
+  initialWeights?: ScoreWeights;
+  persist?: boolean;
+  holdoutWindow?: number;
+  holdoutFallback?: boolean;
+}
+
+export interface TrainWeightsResult extends SimulationResult {
+  totalDraws: number;
+  trainSteps: number;
+  holdoutFallbackApplied?: boolean;
+}
+
+async function loadChronologicalDraws(db: LotteryDb, gameId: GameId, limit: number) {
+  const draws = await loadDraws(db, gameId, limit);
+  return [...draws].sort((a, b) => a.issue.localeCompare(b.issue));
+}
+
+/**
+ * Full-history training: from first predictable issue through all DB draws,
+ * predict → compare → tune weights each step; optionally persist final weights.
+ */
+export async function trainGameWeights(
+  db: LotteryDb,
+  gameId: GameId,
+  options: TrainWeightsOptions,
+): Promise<TrainWeightsResult | null> {
+  const chronological = await loadChronologicalDraws(db, gameId, options.historyLimit);
+  if (chronological.length <= options.minHistory) return null;
+
+  const initial = options.initialWeights ?? { ...DEFAULT_WEIGHTS };
+  const sim = runAdaptiveSimulation(chronological, gameId, {
+    pickCount: options.pickCount,
+    minHistory: options.minHistory,
+    randomTrials: options.randomTrials,
+    initialWeights: initial,
+    adaptive: true,
+    // no scoreWindow → every training step is scored
+  });
+  if (!sim) return null;
+
+  if (options.persist !== false) {
+    let weightsToSave = sim.finalWeights;
+    let holdoutFallbackApplied = false;
+    if (options.holdoutFallback !== false && options.holdoutWindow && options.holdoutWindow > 0) {
+      const holdout = await walkForwardBacktest(db, gameId, {
+        pickCount: options.pickCount,
+        minHistory: options.minHistory,
+        randomTrials: options.randomTrials,
+        historyLimit: options.historyLimit,
+        window: options.holdoutWindow,
+        initialWeights: { ...DEFAULT_WEIGHTS },
+      });
+      if (shouldFallbackWeights(holdout)) {
+        weightsToSave = { ...DEFAULT_WEIGHTS };
+        holdoutFallbackApplied = true;
+      }
+    }
+    await saveGameWeights(db, gameId, weightsToSave, sim.periods, sim.adaptiveAvgHitRate);
+    return {
+      ...sim,
+      finalWeights: weightsToSave,
+      totalDraws: chronological.length,
+      trainSteps: sim.periods,
+      holdoutFallbackApplied,
+    };
+  }
+
+  return {
+    ...sim,
+    totalDraws: chronological.length,
+    trainSteps: sim.periods,
+  };
+}
+
+export async function trainAllGameWeights(
+  db: LotteryDb,
+  gameIds: GameId[],
+  options: TrainWeightsOptions,
+): Promise<TrainWeightsResult[]> {
+  const out: TrainWeightsResult[] = [];
+  for (const gameId of gameIds) {
+    const result = await trainGameWeights(db, gameId, options);
+    if (result) out.push(result);
+  }
+  return out;
+}
+
+function pct(rate: number): string {
+  return (rate * 100).toFixed(1);
+}
+
+function signedPct(delta: number): string {
+  const v = delta * 100;
+  return v >= 0 ? `+${v.toFixed(1)}` : v.toFixed(1);
+}
+
+export function formatTrainLine(r: TrainWeightsResult): string {
+  const init = formatWeights(r.initialWeights);
+  const fin = formatWeights(r.finalWeights);
+  const fallback = r.holdoutFallbackApplied ? ' [holdout→默认]' : '';
+  return [
+    `${r.gameId}: 训练${r.trainSteps}期 (${r.firstScoredIssue}→${r.lastScoredIssue})${fallback}`,
+    `命中 调优${pct(r.adaptiveAvgHitRate)}% / 固定${pct(r.fixedAvgHitRate)}% / 随机${pct(r.randomAvgHitRate)}%`,
+    `Δ调优-随机 ${signedPct(r.adaptiveVsRandom)}%`,
+    `权重 ${init} → ${fin}`,
+  ].join('\n  ');
+}
+
+export function formatTrainReport(results: TrainWeightsResult[]): string {
+  if (!results.length) return '训练失败：历史数据不足，请先同步开奖。';
+  const lines = [
+    '【权重训练】全历史 walk-forward：预测→比对→调权，已写入 lottery_model_weights',
+    ...results.map(formatTrainLine),
+    '',
+    '说明：训练≠保证未来更准；终权重供后续 lottery 推荐使用。',
+  ];
+  return lines.join('\n');
+}

package/src/evaluate/weight-guard.ts

@@ -0,0 +1,68 @@
+import { DEFAULT_WEIGHTS, type GameId, type ScoreWeights } from '../types.js';
+
+import type { LotteryDb } from '../db.js';
+import { loadGameWeights } from './tracker.js';
+import type { SimulationResult } from './adaptive-sim.js';
+import { walkForwardBacktest, type BacktestOptions } from './backtest.js';
+
+export interface WeightPlan {
+  /** Explicit weights for recommend; only lists holdout-fallback games. */
+  overrides: Map<GameId, ScoreWeights>;
+  fallbacks: GameId[];
+}
+
+export function gamesToPredict(
+  gameIds: GameId[],
+  missingToday: GameId[],
+  weightPlan: WeightPlan,
+): GameId[] {
+  const regenFallback = weightPlan.fallbacks.filter((g) => !missingToday.includes(g));
+  const ordered = new Set<GameId>();
+  for (const gid of gameIds) {
+    if (missingToday.includes(gid) || regenFallback.includes(gid)) ordered.add(gid);
+  }
+  return [...ordered];
+}
+
+export function planRecommendWeights(
+  gameIds: GameId[],
+  holdoutSummaries: SimulationResult[],
+  holdoutFallback: boolean,
+): WeightPlan {
+  const byGame = new Map(holdoutSummaries.map((s) => [s.gameId, s]));
+  const overrides = new Map<GameId, ScoreWeights>();
+  const fallbacks: GameId[] = [];
+  if (!holdoutFallback) return { overrides, fallbacks };
+
+  for (const gid of gameIds) {
+    const summary = byGame.get(gid);
+    if (summary && summary.adaptiveVsRandom < 0) {
+      overrides.set(gid, { ...DEFAULT_WEIGHTS });
+      fallbacks.push(gid);
+    }
+  }
+  return { overrides, fallbacks };
+}
+
+export async function runHoldoutBacktest(
+  db: LotteryDb,
+  gameIds: GameId[],
+  options: BacktestOptions,
+): Promise<SimulationResult[]> {
+  const out: SimulationResult[] = [];
+  for (const gameId of gameIds) {
+    const initial = await loadGameWeights(db, gameId);
+    const summary = await walkForwardBacktest(db, gameId, { ...options, initialWeights: initial });
+    if (summary) out.push(summary);
+  }
+  return out;
+}
+
+export function formatWeightFallbackNote(fallbacks: GameId[]): string {
+  if (!fallbacks.length) return '';
+  return `【权重保护】近端 holdout 调优未跑赢随机，以下玩法已回退默认 F40/O35/T25：${fallbacks.join(', ')}`;
+}
+
+export function shouldFallbackWeights(summary: SimulationResult | null | undefined): boolean {
+  return summary != null && summary.adaptiveVsRandom < 0;
+}

package/src/games/kl8-groups.ts

@@ -0,0 +1,98 @@
+import { DEFAULT_WEIGHTS, type DrawNumbers, type Kl8GroupStrategy, type Kl8PickGroup, type NormalizedDraw, type ScoreWeights } from '../types.js';
+
+import { pickTopUnique, scorePool, type PoolScore } from '../stats/engine.js';
+
+function poolDraws(draws: NormalizedDraw[], extract: (n: DrawNumbers) => number[]): number[][] {
+  return draws.map((d) => extract(d.numbers)).filter((a) => a.length > 0);
+}
+
+export const KL8_STRATEGY_LABELS: Record<Kl8GroupStrategy, string> = {
+  balanced: '均衡',
+  hot: '热号',
+  cold: '冷号',
+  trend: '趋势',
+};
+
+const STRATEGY_PRESETS: Record<Exclude<Kl8GroupStrategy, 'balanced'>, ScoreWeights> = {
+  hot: { freq: 0.55, omit: 0.2, trend: 0.25 },
+  cold: { freq: 0.2, omit: 0.55, trend: 0.25 },
+  trend: { freq: 0.25, omit: 0.25, trend: 0.5 },
+};
+
+export interface Kl8Config {
+  pickCount: number;
+  recommendGroups: number;
+  groupStrategies: Kl8GroupStrategy[];
+}
+
+export interface Kl8ConfigInput {
+  pickCount?: number;
+  recommendGroups?: number;
+  groupStrategies?: string[];
+}
+
+export function parseKl8GroupStrategy(raw: string): Kl8GroupStrategy {
+  const s = raw.trim().toLowerCase();
+  if (s === 'balanced' || s === 'hot' || s === 'cold' || s === 'trend') return s;
+  return 'balanced';
+}
+
+export function resolveKl8Config(globalPickCount: number, raw?: Kl8ConfigInput): Kl8Config {
+  const strategies = (raw?.groupStrategies?.length ? raw.groupStrategies : ['balanced', 'hot', 'cold']).map(
+    parseKl8GroupStrategy,
+  );
+  const recommendGroups = Math.min(10, Math.max(1, raw?.recommendGroups ?? 3));
+  const pickCount = Math.min(10, Math.max(1, raw?.pickCount ?? globalPickCount));
+  return { pickCount, recommendGroups, groupStrategies: strategies };
+}
+
+export function weightsForKl8Strategy(strategy: Kl8GroupStrategy, base: ScoreWeights): ScoreWeights {
+  if (strategy === 'balanced') return { ...base };
+  return { ...STRATEGY_PRESETS[strategy] };
+}
+
+function strategiesForGroupCount(count: number, strategies: Kl8GroupStrategy[]): Kl8GroupStrategy[] {
+  const pool = strategies.length ? strategies : (['balanced'] as Kl8GroupStrategy[]);
+  return Array.from({ length: count }, (_, i) => pool[i % pool.length] ?? pool[0] ?? 'balanced');
+}
+
+export interface RecommendKl8GroupsResult {
+  groups: Kl8PickGroup[];
+  scores: PoolScore[];
+}
+
+/** Multi-strategy KL8 rows; groups may overlap — each picks top-N by its own weights. */
+export function recommendKl8Groups(
+  draws: NormalizedDraw[],
+  options: {
+    pickCount: number;
+    recommendGroups: number;
+    strategies: Kl8GroupStrategy[];
+    tieSeed: string;
+    baseWeights: ScoreWeights;
+  },
+): RecommendKl8GroupsResult {
+  const rows = poolDraws(draws, (n) => n.main ?? []);
+  const groupStrategies = strategiesForGroupCount(options.recommendGroups, options.strategies);
+  const groups: Kl8PickGroup[] = [];
+  let primaryScores: PoolScore[] = [];
+
+  for (let i = 0; i < groupStrategies.length; i++) {
+    const strategy = groupStrategies[i] ?? 'balanced';
+    const weights = weightsForKl8Strategy(strategy, options.baseWeights);
+    const scores = scorePool(rows, 1, 80, `${options.tieSeed}:${strategy}:${i}`, weights);
+    if (i === 0) primaryScores = scores;
+    const main = pickTopUnique(scores, options.pickCount);
+    groups.push({
+      index: i + 1,
+      strategy,
+      label: KL8_STRATEGY_LABELS[strategy],
+      numbers: main,
+      weights,
+    });
+  }
+
+  return { groups, scores: primaryScores };
+}
+
+export { DEFAULT_WEIGHTS };

package/src/games/registry.ts

@@ -0,0 +1,55 @@
+import type { GameId, LotterySource } from '../types.js';
+
+export interface GameMeta {
+  id: GameId;
+  name: string;
+  source: LotterySource;
+  fucaiName?: string;
+  ticaiGameNo?: string;
+}
+
+export const ALL_GAMES: GameMeta[] = [
+  { id: 'kl8', name: '快乐8', source: 'fucai', fucaiName: 'kl8' },
+  { id: 'ssq', name: '双色球', source: 'fucai', fucaiName: 'ssq' },
+  { id: 'fc3d', name: '福彩3D', source: 'fucai', fucaiName: '3d' },
+  { id: 'dlt', name: '超级大乐透', source: 'ticai', ticaiGameNo: '85' },
+  { id: 'pl3', name: '排列3', source: 'ticai', ticaiGameNo: '35' },
+  { id: 'pl5', name: '排列5', source: 'ticai', ticaiGameNo: '350133' },
+];
+
+const BY_ID = new Map(ALL_GAMES.map((g) => [g.id, g]));
+
+export function getGameMeta(id: GameId): GameMeta {
+  const meta = BY_ID.get(id);
+  if (!meta) throw new Error(`Unknown game: ${id}`);
+  return meta;
+}
+
+export function parseGameId(raw: string): GameId | null {
+  const key = raw.trim().toLowerCase();
+  const aliases: Record<string, GameId> = {
+    kl8: 'kl8',
+    '快乐8': 'kl8',
+    ssq: 'ssq',
+    '双色球': 'ssq',
+    dlt: 'dlt',
+    '大乐透': 'dlt',
+    fc3d: 'fc3d',
+    '福彩3d': 'fc3d',
+    pl3: 'pl3',
+    '排列3': 'pl3',
+    pl5: 'pl5',
+    '排列5': 'pl5',
+  };
+  return aliases[key] ?? (BY_ID.has(key as GameId) ? (key as GameId) : null);
+}
+
+export function resolveEnabledGames(configGames?: string[]): GameId[] {
+  if (!configGames?.length) return ALL_GAMES.map((g) => g.id);
+  const out: GameId[] = [];
+  for (const g of configGames) {
+    const id = parseGameId(g);
+    if (id && !out.includes(id)) out.push(id);
+  }
+  return out.length ? out : ALL_GAMES.map((x) => x.id);
+}