gaokao-pro 0.1.0

package/dist/paiming.js

@@ -0,0 +1,66 @@
+// paiming — aggregate ranking presentation for one school across 5 sources:
+//   软科 (Shanghai Ranking), QS World, US News, 校友会 (Cuaa), 第四轮学科评估.
+// 22 of the 100 candidate-validator agents asked "this school's overall rank" —
+// this verb gives Claude a single call that pulls all five into one view.
+import { getSchoolInfo } from "./gaokao-cn.js";
+import { loadIndex } from "./index-loader.js";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const SRC_DIR = dirname(__filename);
+function loadXuekePinggu() {
+    const candidates = [
+        resolve(SRC_DIR, "..", "data", "datasets", "xueke-pinggu-disculun.json"),
+        resolve(SRC_DIR, "..", "..", "data", "datasets", "xueke-pinggu-disculun.json")
+    ];
+    for (const p of candidates) {
+        if (!existsSync(p))
+            continue;
+        const raw = JSON.parse(readFileSync(p, "utf8"));
+        const out = {};
+        for (const s of raw.disclosed_schools ?? []) {
+            out[s.school] = { a_plus_count: s.a_plus_count, a_plus_subjects: s.a_plus_subjects };
+        }
+        return out;
+    }
+    return {};
+}
+let xuekeCache = null;
+export async function paiming(schoolQuery) {
+    if (!xuekeCache)
+        xuekeCache = loadXuekePinggu();
+    const index = loadIndex();
+    const row = index.rows.find((r) => r.zs_code === schoolQuery)
+        ?? index.rows.find((r) => r.gaokao_cn_id === Number(schoolQuery))
+        ?? index.rows.find((r) => r.name.includes(schoolQuery));
+    if (!row)
+        throw new Error(`no school matched "${schoolQuery}"`);
+    const info = await getSchoolInfo(row.gaokao_cn_id);
+    const rank = (info.rank ?? {});
+    const xueke = (info.xueke_pinggu ?? info.xueke_rank ?? {});
+    return {
+        schoolId: row.gaokao_cn_id,
+        name: row.name,
+        zsCode: row.zs_code,
+        rankings: {
+            ruanke: rank.ruanke_rank && rank.ruanke_rank !== "0" ? String(rank.ruanke_rank) : null,
+            xyh: rank.xyh_rank && rank.xyh_rank !== "0" ? String(rank.xyh_rank) : null,
+            qsWorld: rank.qs_world && rank.qs_world !== "0" ? String(rank.qs_world) : null,
+            usNews: rank.us_rank && rank.us_rank !== "0" ? String(rank.us_rank) : null,
+            tws_china: rank.tws_china && rank.tws_china !== "0" ? String(rank.tws_china) : null
+        },
+        xueke_pinggu_round4: {
+            a_plus: xueke["A+"] ?? null,
+            a: xueke["A"] ?? null,
+            a_minus: xueke["A-"] ?? null,
+            b_plus: xueke["B+"] ?? null,
+            b: xueke["B"] ?? null,
+            b_minus: xueke["B-"] ?? null,
+            c_plus: xueke["C+"] ?? null,
+            c: xueke["C"] ?? null,
+            c_minus: xueke["C-"] ?? null
+        },
+        xueke_pinggu_round5_disclosed: xuekeCache?.[row.name] ?? null
+    };
+}

package/dist/probe.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/probe.js

@@ -0,0 +1,73 @@
+// Probe static-data.gaokao.cn to map gaokao.cn school_id → 教育部 zs_code (5-digit).
+// Walks ids in a range and writes a JSON index to docs/school-index.json.
+// Run with: pnpm probe -- --start 1 --end 100
+import { writeFileSync, mkdirSync } from "node:fs";
+import { gzipSync } from "node:zlib";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getSchoolInfo } from "./gaokao-cn.js";
+const __filename = fileURLToPath(import.meta.url);
+// cli/src/probe.ts → repo root is two levels up, cli/data is one level up.
+const CLI_ROOT = resolve(dirname(__filename), "..");
+function parseRange() {
+    const args = process.argv.slice(2);
+    const get = (flag, fallback) => {
+        const idx = args.indexOf(flag);
+        return idx >= 0 ? Number(args[idx + 1]) : fallback;
+    };
+    return {
+        start: get("--start", 1),
+        end: get("--end", 3000),
+        concurrency: get("--concurrency", 25)
+    };
+}
+async function probeOne(id) {
+    try {
+        const info = await getSchoolInfo(id);
+        return {
+            gaokao_cn_id: Number(info.school_id),
+            zs_code: info.zs_code,
+            name: info.name,
+            province: info.province_name,
+            city: info.city_name,
+            level: info.level_name,
+            type: info.type_name,
+            nature: info.nature_name,
+            belong: info.belong,
+            f985: info.f985 === "1",
+            f211: info.f211 === "1",
+            dual_class: info.dual_class_name,
+            pro_type_min: info.pro_type_min ?? {}
+        };
+    }
+    catch (e) {
+        return null;
+    }
+}
+async function main() {
+    const { start, end, concurrency } = parseRange();
+    process.stderr.write(`probing school_ids [${start}..${end}] with concurrency ${concurrency}\n`);
+    const rows = [];
+    let cursor = start;
+    const workers = Array.from({ length: concurrency }, async () => {
+        while (cursor <= end) {
+            const id = cursor++;
+            const row = await probeOne(id);
+            if (row) {
+                rows.push(row);
+                process.stderr.write(`  ${id.toString().padStart(5)} → ${row.zs_code} ${row.name}\n`);
+            }
+        }
+    });
+    await Promise.all(workers);
+    rows.sort((a, b) => a.gaokao_cn_id - b.gaokao_cn_id);
+    const payload = JSON.stringify({ generated_at: new Date().toISOString(), rows });
+    const outPath = resolve(CLI_ROOT, "data", "school-index.json.gz");
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, gzipSync(Buffer.from(payload, "utf8")));
+    process.stderr.write(`\nwrote ${rows.length} schools → ${outPath}\n`);
+}
+main().catch((err) => {
+    process.stderr.write(String(err) + "\n");
+    process.exit(1);
+});

package/dist/provinces/guangdong.d.ts

@@ -0,0 +1,27 @@
+export type RankTable = {
+    province: "guangdong";
+    year: number;
+    track: "物理类" | "历史类";
+    rows: Array<{
+        score: number;
+        cumulative: number;
+    }>;
+};
+export declare const GUANGDONG_SOURCE: {
+    readonly province: "广东";
+    readonly bureau: "广东省教育考试院";
+    readonly url: "https://eea.gd.gov.cn/ptgk/";
+    readonly attachments: {
+        readonly 2025: "https://eea.gd.gov.cn/attachment/0/583/583759/4734345.zip";
+    };
+    readonly notes: readonly ["Zip contains 16 PDFs: 1=历史类总表, 2=物理类总表, 3-16=各类艺术/体育子类", "PDF tables are landscape, multi-column, page-paginated — need OCR or tabula", "Refresh cadence: published once per year, ~June 25 after gaokao results"];
+};
+/**
+ * Return the 一分一段 table for 广东 / year / track if extracted JSON exists locally.
+ * Throws with the official source URL if not — never auto-downloads PDFs.
+ */
+export declare function fetchRankTable(year: number, track: "物理类" | "历史类"): RankTable;
+/** score → rank lookup (returns cumulative rank for highest score ≤ input). */
+export declare function scoreToRank(table: RankTable, score: number): number | null;
+/** rank → score lookup (returns lowest score whose cumulative ≥ input rank). */
+export declare function rankToScore(table: RankTable, rank: number): number | null;

package/dist/provinces/guangdong.js

@@ -0,0 +1,68 @@
+// 广东省教育考试院 (eea.gd.gov.cn) — 一分一段表 fallback adapter.
+//
+// Status: STUB. The data lives in ZIP-bundled PDFs (e.g.
+// https://eea.gd.gov.cn/attachment/0/583/583759/4734345.zip for 2025),
+// which need OCR/manual extraction before they become queryable JSON.
+//
+// This file is the contract. When extracted JSON data lands at
+// `cli/data/yifenyiduan/guangdong-{year}-{track}.json`, the `fetchRankTable`
+// stub below will read and return it instead of throwing.
+//
+// Why this exists pre-data: it documents the shape and lets `rank` /
+// `--rank` consumers code against the interface without waiting for the
+// data ingest.
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const SRC_DIR = dirname(__filename);
+export const GUANGDONG_SOURCE = {
+    province: "广东",
+    bureau: "广东省教育考试院",
+    url: "https://eea.gd.gov.cn/ptgk/",
+    // 2025 release index:
+    attachments: {
+        2025: "https://eea.gd.gov.cn/attachment/0/583/583759/4734345.zip"
+    },
+    notes: [
+        "Zip contains 16 PDFs: 1=历史类总表, 2=物理类总表, 3-16=各类艺术/体育子类",
+        "PDF tables are landscape, multi-column, page-paginated — need OCR or tabula",
+        "Refresh cadence: published once per year, ~June 25 after gaokao results"
+    ]
+};
+function dataPathFor(year, track) {
+    const trackKey = track === "物理类" ? "wuli" : "lishi";
+    return resolve(SRC_DIR, "..", "..", "data", "yifenyiduan", `guangdong-${year}-${trackKey}.json`);
+}
+/**
+ * Return the 一分一段 table for 广东 / year / track if extracted JSON exists locally.
+ * Throws with the official source URL if not — never auto-downloads PDFs.
+ */
+export function fetchRankTable(year, track) {
+    const path = dataPathFor(year, track);
+    if (!existsSync(path)) {
+        throw new Error(`广东 ${year} ${track} 一分一段表尚未导入 (looked at ${path}).\n` +
+            `下载源: ${GUANGDONG_SOURCE.attachments[year] ?? GUANGDONG_SOURCE.url}\n` +
+            `导入步骤详见 docs/data-sources.md → 一分一段表 ingest pipeline.`);
+    }
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/** score → rank lookup (returns cumulative rank for highest score ≤ input). */
+export function scoreToRank(table, score) {
+    for (const row of table.rows) {
+        if (row.score <= score)
+            return row.cumulative;
+    }
+    return null;
+}
+/** rank → score lookup (returns lowest score whose cumulative ≥ input rank). */
+export function rankToScore(table, rank) {
+    let best = null;
+    for (const row of table.rows) {
+        if (row.cumulative >= rank)
+            best = row.score;
+        else
+            break;
+    }
+    return best;
+}

package/dist/provinces/index.d.ts

@@ -0,0 +1 @@
+export * as guangdong from "./guangdong.js";

package/dist/provinces/index.js

@@ -0,0 +1,17 @@
+// Province-bureau fallback adapters. Each module exports a stable interface
+// for fetching that province's 一分一段表 from the official 考试院 source
+// (or local extracted JSON, when no API exists upstream).
+//
+// Roadmap (verdicts from docs/data-sources.md):
+//   🟢 广东 (eea.gd.gov.cn)        — ZIP+PDF, this round.
+//   🟢 北京 (bjeea.cn)             — open-source CSV from ZE3kr/bjeea-bulk-query.
+//   🟢 河北 (hebeea.edu.cn)        — Excel direct download.
+//   🟢 江苏 (jseea.cn)             — PDF, clean format.
+//   🟢 广西 (gxeea.cn)             — fully public HTML.
+//   🟢 黑龙江 (lzk.hl.cn)          — no auth, HTML tables.
+//   🟢 西藏 (zsks.edu.xizang.gov.cn)
+//   🟡 + 22 more provinces — login or PDF-only.
+//
+// Only `guangdong` has a written adapter today; the rest are documented
+// pointers in docs/data-sources.md.
+export * as guangdong from "./guangdong.js";

package/dist/rank-table.d.ts

@@ -0,0 +1,31 @@
+import { type ProvinceId } from "./codes.js";
+export type RankTableRow = {
+    score: number;
+    count: number;
+    cumulative: number;
+};
+export type RankTable = {
+    province: string;
+    province_name: string;
+    year: number;
+    /** "physics" | "history" for 3+1+2 provinces; "combined" for 3+3; "science" | "liberal" for 老高考. */
+    track: string;
+    source: string;
+    note?: string;
+    count: number;
+    rows: RankTableRow[];
+};
+/** Load a single rank table. Returns null if not present locally. */
+export declare function loadRankTable(provinceId: ProvinceId, year: number, track: string): RankTable | null;
+/** List all (province, year, track) tuples we have data for. */
+export declare function listRankTables(): Array<{
+    province: string;
+    year: number;
+    track: string;
+}>;
+/** score → cumulative rank lookup (returns rank for highest score row whose score ≤ input). */
+export declare function scoreToRank(table: RankTable, score: number): number | null;
+/** rank → score lookup (lowest score whose cumulative ≥ input rank — i.e. the bar that gets you the rank). */
+export declare function rankToScore(table: RankTable, rank: number): number | null;
+/** Try to pick a sensible default track key when caller omits one. */
+export declare function inferDefaultTrack(provinceId: ProvinceId): string;

package/dist/rank-table.js

@@ -0,0 +1,74 @@
+// Loader for cli/data/yifenyiduan/{province}-{year}-{track}.json files.
+// One file per (province, year, track) — see beijing-2024-combined.json as the canonical shape.
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PROVINCES } from "./codes.js";
+const __filename = fileURLToPath(import.meta.url);
+const SRC_DIR = dirname(__filename);
+const CANDIDATE_DIRS = [
+    resolve(SRC_DIR, "..", "data", "yifenyiduan"), // cli/src/  → cli/data/yifenyiduan
+    resolve(SRC_DIR, "..", "..", "data", "yifenyiduan") // cli/dist/ → cli/data/yifenyiduan
+];
+function findDataDir() {
+    for (const d of CANDIDATE_DIRS) {
+        if (existsSync(d))
+            return d;
+    }
+    return null;
+}
+function pinyinFor(provinceId) {
+    return PROVINCES[provinceId].pinyin;
+}
+/** Load a single rank table. Returns null if not present locally. */
+export function loadRankTable(provinceId, year, track) {
+    const dir = findDataDir();
+    if (!dir)
+        return null;
+    const path = resolve(dir, `${pinyinFor(provinceId)}-${year}-${track}.json`);
+    if (!existsSync(path))
+        return null;
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/** List all (province, year, track) tuples we have data for. */
+export function listRankTables() {
+    const dir = findDataDir();
+    if (!dir)
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        const m = f.match(/^([a-z]+)-(\d{4})-([a-z]+)\.json$/);
+        if (m)
+            out.push({ province: m[1], year: Number(m[2]), track: m[3] });
+    }
+    return out.sort((a, b) => a.province.localeCompare(b.province) || b.year - a.year);
+}
+/** score → cumulative rank lookup (returns rank for highest score row whose score ≤ input). */
+export function scoreToRank(table, score) {
+    // rows are sorted descending by score; find first row whose score ≤ input.
+    for (const row of table.rows) {
+        if (row.score <= score)
+            return row.cumulative;
+    }
+    return null;
+}
+/** rank → score lookup (lowest score whose cumulative ≥ input rank — i.e. the bar that gets you the rank). */
+export function rankToScore(table, rank) {
+    let best = null;
+    for (const row of table.rows) {
+        if (row.cumulative >= rank) {
+            best = row.score;
+            break;
+        }
+    }
+    return best;
+}
+/** Try to pick a sensible default track key when caller omits one. */
+export function inferDefaultTrack(provinceId) {
+    const reform = PROVINCES[provinceId].reform;
+    if (reform === "3+3")
+        return "combined";
+    if (reform === "3+1+2")
+        return "physics";
+    return "science";
+}

package/dist/recommend-major.d.ts

@@ -0,0 +1,34 @@
+import { type IndexFilter } from "./index-loader.js";
+import { type ProvinceId, type Subject } from "./codes.js";
+export type RecommendMajorInput = {
+    keyword: string;
+    score: number;
+    provinceId: ProvinceId;
+    subjects: Subject[];
+    year: number;
+    filter?: IndexFilter;
+    limit?: number;
+    concurrency?: number;
+};
+export type MajorMatch = {
+    spcode: string;
+    sp_name: string;
+    level3_name: string;
+    schools_count: number;
+    reachable_count: number;
+    schools: Array<{
+        schoolId: number;
+        name: string;
+        city: string;
+        is985: boolean;
+        is211: boolean;
+        baselineMinScore: number;
+        delta: number;
+        reachable: boolean;
+        track: string;
+    }>;
+};
+export declare function recommendMajor(input: RecommendMajorInput): Promise<{
+    query: object;
+    majors_matched: MajorMatch[];
+}>;

package/dist/recommend-major.js

@@ -0,0 +1,119 @@
+// recommend-major — interest keyword in, ranked majors out, each with the
+// schools that recruit it in the user's province. Inverse of `recommend`
+// (which is school-centric).
+//
+// Pipeline:
+//   1. Filter index to schools the user can reach (delta ≥ -25).
+//   2. For each, fetch plan/{schoolId}/{year}/{province}.json (concurrent).
+//   3. Match the keyword against sp_name / spname / level3_name.
+//   4. Group hits by spcode, sort by (schools count desc, top school baseline desc).
+import { loadIndex, filterIndex } from "./index-loader.js";
+import { getAdmissionPlan } from "./gaokao-cn.js";
+import { PROVINCES, TRACK_NAMES } from "./codes.js";
+import { inferTrack } from "./recommend.js";
+export async function recommendMajor(input) {
+    const index = loadIndex();
+    const track = inferTrack(input.provinceId, input.subjects);
+    let rows = input.filter ? filterIndex(index, input.filter) : index.rows;
+    // Only keep schools with a feasible-ish historical baseline in this province + track.
+    const reachableRows = rows.filter((r) => {
+        const entries = r.pro_type_min?.[String(input.provinceId)] ?? [];
+        if (!entries.length)
+            return false;
+        const sorted = [...entries].sort((a, b) => b.year - a.year);
+        for (const e of sorted) {
+            const v = e.type?.[track];
+            const n = v ? Number(v) : NaN;
+            if (Number.isFinite(n) && n > 0 && input.score - n >= -40)
+                return true;
+        }
+        return false;
+    });
+    const keyword = input.keyword.toLowerCase();
+    const matchHit = (item) => item.sp_name?.toLowerCase().includes(keyword) ||
+        item.spname?.toLowerCase().includes(keyword) ||
+        item.level3_name?.toLowerCase().includes(keyword) ||
+        item.spcode?.toLowerCase().includes(keyword);
+    const hits = [];
+    const concurrency = input.concurrency ?? 12;
+    let cursor = 0;
+    await Promise.all(Array.from({ length: concurrency }, async () => {
+        while (cursor < reachableRows.length) {
+            const r = reachableRows[cursor++];
+            if (!r)
+                break;
+            try {
+                const plan = await getAdmissionPlan(r.gaokao_cn_id, input.year, input.provinceId);
+                // Most-recent baseline for this row + track
+                const entries = r.pro_type_min[String(input.provinceId)];
+                const sorted = [...entries].sort((a, b) => b.year - a.year);
+                let baseline = 0;
+                for (const e of sorted) {
+                    const v = e.type?.[track];
+                    const n = v ? Number(v) : NaN;
+                    if (Number.isFinite(n) && n > 0) {
+                        baseline = n;
+                        break;
+                    }
+                }
+                const delta = input.score - baseline;
+                for (const item of plan) {
+                    if (!matchHit(item))
+                        continue;
+                    const spcode = item.spcode || `${item.level3_name}-${item.sp_name}`;
+                    hits.push({
+                        spcode,
+                        sp_name: item.sp_name,
+                        level3_name: item.level3_name,
+                        school: {
+                            schoolId: r.gaokao_cn_id,
+                            name: r.name,
+                            city: r.city,
+                            is985: r.f985,
+                            is211: r.f211,
+                            baselineMinScore: baseline,
+                            delta,
+                            reachable: delta >= -15,
+                            track: TRACK_NAMES[track] ?? track
+                        }
+                    });
+                }
+            }
+            catch { /* skip */ }
+        }
+    }));
+    // Group by spcode
+    const byMajor = new Map();
+    for (const h of hits) {
+        const m = byMajor.get(h.spcode) ?? {
+            spcode: h.spcode,
+            sp_name: h.sp_name,
+            level3_name: h.level3_name,
+            schools_count: 0,
+            reachable_count: 0,
+            schools: []
+        };
+        m.schools.push(h.school);
+        m.schools_count++;
+        if (h.school.reachable)
+            m.reachable_count++;
+        byMajor.set(h.spcode, m);
+    }
+    const majors = Array.from(byMajor.values());
+    for (const m of majors) {
+        m.schools.sort((a, b) => b.baselineMinScore - a.baselineMinScore);
+    }
+    majors.sort((a, b) => b.reachable_count - a.reachable_count || b.schools_count - a.schools_count);
+    return {
+        query: {
+            keyword: input.keyword,
+            score: input.score,
+            province: PROVINCES[input.provinceId].name,
+            year: input.year,
+            subjects: input.subjects,
+            track: TRACK_NAMES[track] ?? track,
+            filter: input.filter
+        },
+        majors_matched: input.limit && input.limit > 0 ? majors.slice(0, input.limit) : majors
+    };
+}

package/dist/recommend.d.ts

@@ -0,0 +1,54 @@
+import { type ProvinceId, type Subject } from "./codes.js";
+import { type IndexFilter } from "./index-loader.js";
+export type Bucket = "保" | "稳" | "冲" | "out";
+export type RecommendInput = {
+    score: number;
+    provinceId: ProvinceId;
+    subjects: Subject[];
+    rank?: number;
+    schoolIds?: Array<number | string>;
+    filter?: IndexFilter;
+    limit?: number;
+};
+export type RecommendCandidate = {
+    schoolId: number;
+    zsCode: string;
+    name: string;
+    province: string;
+    city: string;
+    belong: string;
+    is985: boolean;
+    is211: boolean;
+    dualClass: string;
+    baselineYear: number;
+    baselineMinScore: number;
+    baselineTrack: string;
+    baselineTrackName: string;
+    delta: number;
+    bucket: Bucket;
+};
+export type RecommendOutput = {
+    query: {
+        score: number;
+        province: {
+            id: ProvinceId;
+            name: string;
+            reform: string;
+        };
+        subjects: Subject[];
+        track: string;
+        trackName: string;
+        rank?: number;
+        reform_warning?: string;
+    };
+    evaluated: number;
+    buckets: {
+        "保": RecommendCandidate[];
+        "稳": RecommendCandidate[];
+        "冲": RecommendCandidate[];
+        out: RecommendCandidate[];
+        skipped: number;
+    };
+};
+export declare function inferTrack(provinceId: ProvinceId, subjects: Subject[]): string;
+export declare function recommend(input: RecommendInput): RecommendOutput;