Codebase (2026-06-27): this engine now lives in meno-gaokao-counsellor (
core/…), extracted from reflection-game — see gaokao-standalone-plan. Module paths below use the newcore/layout.
这是什么 · What this is
中文：忠实说明 Meno「反思均衡 · 志愿推演」系统如何与合作平台雨来高考（
gaokao.yusoong.com）的数据 API 对接：用它的哪些接口、拿什么数据、数据边界在哪、以及调查员（investigator）何时用雨来、何时退回本地 grounding 知识库、何时才去联网检索。客户端代码：core/yulai.py。EN: A faithful account of how Meno’s 反思均衡 / 志愿推演 system integrates with the partner platform 雨来高考 (Yusoong) data API: which endpoints we use, what we pull, where the data boundaries are, and when the investigator uses 雨来 vs. falls back to the local grounding KB vs. only then reaches for web search. Client:
core/yulai.py.
为什么对接雨来 · Why integrate 雨来
中文：雨来是我们的合作方，握有比我们自己多得多的、可核验的真实数据——尤其是我们 grounding 层一直在用 LLM 蒸馏 + 联网检索「近似」的两个维度：历年录取分和等位分（分数↔位次换算）。对接之后，这两个维度从「估算」变成「权威真实」，专业目录/判别也有了权威背书。
EN: 雨来 is our collaborating partner and holds far more verified real data than we do — especially the two dimensions our grounding layer has been approximating with LLM distillation + web search: historical admission scores (录取分) and equivalent-score conversion (等位分, score↔rank). Integrating turns those from estimates into authoritative truth, and gives the major catalogue / 专业判别 an authoritative backbone.
用到的接口 · Endpoints we use
中文：只读 API（/api/v1/partner，Bearer 鉴权，限流 120 次 / 60 秒），响应信封 { ok, data, meta }。
| 分组 | 接口 | 我们用来做什么 |
|---|---|---|
| 专业 | GET /majors、/majors/{id}、POST /majors/batch | 权威专业目录 / 详情，替换蒸馏目录 |
| 专业 | /majors/related、/majors/facets、/majors/{id}/decision | 相关推荐（挑对比项）、级联筛选、专业判别（误区/同类/替代/红线/核查）喂给调查员 |
| 录取分 | GET /scores | 院校专业历年录取分 → 回答「能不能考上」「往年要多少分/位次」 |
| 等位分 | POST /equivalent-score (+batch) | 分数↔位次换算，跨省/跨年比较 |
| 画像 | GET /student-profile/{id} | 脱敏学生画像（需该生在雨来侧授权） |
EN: Read-only API (/api/v1/partner, Bearer auth, 120 req/60s), envelope { ok, data, meta }. We pull authoritative major catalogue/detail (replacing the distilled catalogue), related/facets/decision (专业判别) for the investigator’s contrast + pitfalls, /scores for historical admission scores (“can I get in / what score+rank did it take”), /equivalent-score for score↔rank conversion across provinces/years, and de-identified /student-profile.
数据边界（重要，避免误用）· Data boundaries (important, avoid misuse)
中文：
- 等位分目前仅云南有真实数据：
data.status="ready"才可用，其余省份返回非 ready —— UI/调查员必须先判 status，不是 ready 就不展示等位分。 - 录取分覆盖度不一：
meta.coverage标注可靠性（<省>_verified/data_may_be_partial）；只在 verified 时当硬数字用，partial 时定性。 subjectType是英文枚举：physics/history/arts/science（绝不传中文）。- 学生画像需授权：未授权返回
403；返回内容已脱敏（无姓名/精确分数位次）。
EN: 等位分 currently has real data only for 云南 (data.status="ready" gates it — don’t show 等位分 unless ready); 录取分 reliability varies (meta.coverage: <prov>_verified vs data_may_be_partial — hard number only when verified, else qualitative); subjectType is an English enum (physics/history/arts/science); 学生画像 needs the student’s authorization (403 otherwise) and is de-identified.
调查员的取数顺序（来源分层）· Investigator source tier
中文：调查员每一步要用真实事实时，按这个优先级取数，命中即止：
- 雨来（权威层） — 专业/录取分/等位分/专业判别。命中即用，标注来源「雨来高考」。
- 本地 grounding 知识库（回退） — 859 专业的事实/观点卡 + 2347 校就业数据。雨来没覆盖到该 (维度·学校·专业) 时用。
- 联网检索（最后手段） — 只有当雨来与 KB 都给不出该 (维度·学校·专业) 的可靠数据时才触发；仍受 SRC_RULE 权威来源纪律约束。
- 定性兜底 — 都查不到就只给定性描述，绝不编数字。
为什么这个顺序 · Why this order
中文：雨来是核验过的真实数据，最该优先；KB 是我们蒸馏的、快但需交叉验证；联网检索最慢且最易引入噪声/错配（见 调查员 investigator 里修过的 PKU/港校错配 bug），所以降为最后手段。雨来覆盖越广，越少触发联网检索 → 更快更准。
EN: 雨来 is verified real data → first. The KB is our distilled data — fast but needs cross-checking → fallback. Web search is slowest and most prone to noise / cross-attribution (see the PKU/HK mismatch bug fixed in 调查员 investigator) → last resort. The wider 雨来’s coverage, the less web search fires → faster + more accurate.
EN (tier list): 1) 雨来 (authoritative) — majors / 录取分 / 等位分 / decision; 2) local grounding KB (fallback) — 859-major fact/opinion cards + 2347-uni employment data, when 雨来 lacks the exact (factor·school·major); 3) web search (last resort) — only when both 雨来 and the KB can’t give reliable data for that (factor·school·major), still under SRC_RULE; 4) qualitative — if nothing is found, stay qualitative, never fabricate.
对接状态 · Integration status
中文：
- ✅ 客户端
core/yulai.py已就绪（6 组接口；环境变量YULAI_API_KEY+YULAI_BASE_URL）。无 key 时自动「禁用」——所有方法返回None，调用方自然回退到 KB / 联网，线上游戏不会因此崩。 - ✅ key 已 live（
yl_live_…，2026-06-20 实测facets/scores返回 200），已设在 gaokao Render 服务的环境变量里。 - ✅ 已接入调查员来源层（雨来排在本地 KB 之上）。
- ⏳ 对全 859 专业重跑
enrich_grounding.py，把雨来权威字段落地（进行中）。
EN: Client core/yulai.py is ready (6 endpoint groups; env YULAI_API_KEY + YULAI_BASE_URL); gracefully disabled without a key (every method returns None → callers fall back to KB / web, the live game never breaks). Pending the api-key + base URL from 雨来’s 对接人 to go live; the grounding/investigator tier-wiring lands next.
相关 · Related
对接待确认清单 · Open questions for the 雨来 team (2026-06-20)
基于实测 live API 得出的、需要和雨来对接人确认的点(上线前):
- 数据分工确认. 我们实测雨来有:专业目录/详情/判别 · 等位分 · 录取分(按省
verified/partial);没有就业数据(无就业端点)。→ 确认:就业(就业率/升学/薪资/行业)由我们侧补齐(gaokao.cn 各校就业质量报告 + 阳光高考专业课程),雨来不重复做。 - 录取/等位分省份扩展时间表. 等位分目前仅云南
ready;录取分按省coverage。→ 6/24 前云南之外有哪些省ready/verified?决定”分数维度=云南 only 还是更多省”。 - 用户侧画像能给到什么(关键). 现合作方
/student-profile剔除了精确分数位次 / 年龄性别,只给抽象画像 + 人格 DNA。但我们做真实志愿需要:用户自己的分数(框定可达学校)、家庭状况/收入(冲 vs 稳倾向)、前期问卷。→ 能否为”从雨来窗口进入本游戏”的学生开放更深字段(分数/省份/选科/家庭/问卷)?还是这些必须我们自己 intake 收? - 授权流程.
/student-profile/{id}未授权返回 403。→ 学生从雨来窗口进来时能否预授权本合作方 + 透传一个studentId,让我们直接取画像 + 用录取/等位框定可达集? - 集成形态/差异化. 入口:接在雨来窗口。差异化:雨来管”能去哪”(查分/查专业),我们管”你到底想要哪、为什么”(反思均衡)。集成设计:雨来录取/等位 → 框定可达集 → 我们在可达集内跑反思均衡推演。→ 确认入口位置 + 跳转/嵌入方式 + 数据回传(我们是否把反思结果回传雨来)。
进度
这些是会前/对接前要和雨来敲定的;详见 6·24 上线准备 §2 集成结论。