gaokao-fetch-volunteers

name	gaokao-fetch-volunteers
description	调用高考智能推荐志愿表 API，根据考生基本信息及专业/城市/院校倾向（映射为 API 选填参数） 获取冲稳保志愿列表，解析为 parsed.json。适用于获取推荐院校、冲稳保志愿表、志愿 API 调用。

获取推荐志愿表

本 Skill 是流水线的第二步：读取 student.json，提取并映射考生倾向到 API 选填参数，调用志愿接口，输出 parsed.json。

上下游

• 上游：gaokao-collect-student-info → student.json
• 下游：gaokao-recommend-majors、gaokao-recommend-schools、gaokao-generate-report

环境准备

cd gaokao-fetch-volunteers
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

执行步骤

1. 从辅助信息提取倾向（Agent 必做）

读取 student.json，根据 preference_mapping.md 将考生倾向补全/写入以下字段：

字段	映射到 API
preferred_universities	universitys
preferred_provinces / preferred_cities	provinces
preferred_tags	tags
preferred_major_classes	majorClass

提取来源：interests、career_direction、preferred_cities、notes 及对话中的院校/专业/层次偏好。

若 Step1 已结构化写入，本步核对并补全；调用 API 前倾向字段不得为空数组（考生无偏好时除外）。

2. 构建 API 请求

python3 scripts/build_api_request.py \
  -i output/student.json \
  -o output/api_request.json \
  --summary output/preference_summary.json

脚本将 preferred_* 转为 API 选填参数；preferred_cities 会自动推导 provinces（见 preference_mapping.md）。

build_api_request.py 会调用 province_config.validate_classify 校验 classify 是否与省份模式匹配。

2.5 调用前参数核对（必做）

在调用 API 前，对照 reference.md 核对 student.json / api_request.json：

检查项	规则
classify	新疆→文科/理科；3+1+2 省→物理/历史；3+3 省→综合。传错会导致批次列表为空
subjects	3+1+2：完整三科（首选+两门再选，如 物理,化学,生物）；3+3：完整三科；新疆不传；京沪津专科由脚本处理
gradeType	仅北京/上海/天津填本科或专科；其他省必须为 null 或不传
score	新疆必传（无一分一段表，仅 rank 无效）
batch	可填泛称「本科批」/「专科批」，由 batch/list 解析为各省具体批次名
西藏	测试环境不支持，应退回采集环节说明

批次 batch：用户侧可填泛称 本科批 / 专科批，脚本通过 batch/list 解析为各省具体批次名（如山东 → 普通类一段）。接口失败时使用 reference.md 中的静态兜底表。

3. 调用志愿 API（两阶段：批次 → 志愿列表）

python3 scripts/fetch_volunteers.py \
  --config output/api_request.json \
  -o output/parsed.json

或一步完成（内置构建逻辑）：

python3 scripts/fetch_volunteers.py \
  --student output/student.json \
  -o output/parsed.json

脚本会先调用 batch/list 根据分数与选科解析具体 batch 和 volunteerType，再请求志愿推荐接口。参数规范化由 scripts/province_config.py 自动完成。可用 --no-auto-batch 关闭自动解析。

两阶段 SOP：

1. GET  batch/list  →  得到各省可选批次 + volunteerType
2. POST intelligenceVolunteer  →  用选中批次的 batch / volunteerType 拉志愿

京沪津在步骤 1 还需传 gradeType（脚本按 score / batch 自动推断）。

4. 向用户说明

结合 preference_summary.json 与 parsed.json 的 stats，说明：

• 传入了哪些倾向参数（院校/省份/层次/专业类）
• 冲/稳/保各多少所

API 选填参数说明

API 字段	含义	来源
universitys	心仪高校	preferred_universities
provinces	省份意向	preferred_provinces 或由城市推导
tags	院校属性	preferred_tags（985/211 等）
majorClass	专业类意向	preferred_major_classes

完整 API 文档见 reference.md。

输出结构（parsed.json）

字段	说明
profile	含传入的选填参数回显
stats	冲/稳/保数量
schools_by_type	分组院校列表
request	实际 API 请求体（含倾向参数）
batch_resolution	批次解析来源、选中项与可选项

故障排查

现象	处理
推荐结果与倾向不符	检查 api_request.json 中选填参数是否正确
没有可填报的批次	查 reference.md；确认 classify 与省份模式一致
批次列表为空	classify 错误（如 3+3 省传了物理）— 脚本会明确报错
西藏考生	测试环境不支持，需换省份或等待平台接入
志愿接口 500	查 reference：gradeType/subjects 是否按省传对
缺少 subjects	3+3/3+1+2 必填选科；新疆/京沪津专科除外
subjects 只有两门	3+1+2 须传完整三科（含物理/历史），不能只传化学,生物
倾向未传入	确认 Step1/本步已填写 preferred_* 字段

附加资源

• preference_mapping.md — 倾向 → API 参数映射规则
• reference.md — API、选科模式、批次接口踩坑速查
• scripts/province_config.py — 各省 classify/subjects/gradeType 校验与规范化
• scripts/test_batch_api.py — 31 省批次接口回归测试
• examples/api_request_shandong.json — 含选填参数示例