730a8f4f21
为 T10.2 预先更新文档: - README.md 顶部新增 codecov 覆盖率徽章 - CHANGELOG.md 记录 T10.2 已完成（codecov 集成 + 徽章） - 与 feat(ci) commit 隔离：先文档后实现，遵循用户对 文档真实性变更与代码变更分独立 commit 的偏好
178 lines
5.8 KiB
Markdown
178 lines
5.8 KiB
Markdown
# 高考志愿填报智能系统
|
||
|
||
[](https://github.com/phamnazage-jpg/gaokao-volunteer-system/actions/workflows/ci.yml)
|
||
[](https://codecov.io/gh/phamnazage-jpg/gaokao-volunteer-system)
|
||
[](https://www.python.org/)
|
||
|
||
> 一套完整的、专业的、可扩展的高考志愿填报辅助系统
|
||
|
||
## 📋 项目简介
|
||
|
||
本项目旨在为高考考生提供**专业、准确、规范化**的志愿填报辅助，包括：
|
||
|
||
- 方案生成（基于霍兰德兴趣模型 + 学科评估 + 个性化推荐）
|
||
- 方案检查（基于各省2026年最新政策规范的自动检查）
|
||
- 可视化报告（HTML/PDF/Markdown多格式输出）
|
||
- 信息收集（1分钟/3分钟/7步三套问卷）
|
||
- 多省份支持（已支持27个省份自动适配）
|
||
|
||
## 🏗️ 目录结构
|
||
|
||
```
|
||
gaokao-volunteer-system/
|
||
├── README.md # 本文件（项目说明）
|
||
├── CHANGELOG.md # 变更日志
|
||
│
|
||
├── docs/ # 文档
|
||
│ ├── versions/ # 版本历史
|
||
│ ├── case-studies/ # 真实案例研究
|
||
│ └── optimization-log/ # 优化过程记录
|
||
│
|
||
├── rules/ # 规则库
|
||
│ ├── provinces/ # 省份规则（按省份）
|
||
│ ├── years/ # 年度规则（按年份）
|
||
│ └── errors/ # 错误模式库
|
||
│
|
||
├── skills/ # Hermes Skills
|
||
│ ├── gaokao-college-advisor/ # 高考志愿填报顾问
|
||
│ ├── gaokao-spec-checker/ # 规范检查员
|
||
│ └── zhangxuefeng-skillset/ # 张雪峰风格
|
||
│
|
||
├── scripts/ # 独立脚本
|
||
│ ├── gaokao-visual-report-v2.py # 可视化报告V2
|
||
│ ├── gaokao-quick-3min.py # 3分钟问卷
|
||
│ ├── gaokao-collect-info.py # 完整收集
|
||
│ ├── gaokao-checker # 规范检查（多省份）
|
||
│ └── legacy/ # 历史版本
|
||
│
|
||
├── data/ # 数据
|
||
│ ├── templates/ # 模板
|
||
│ └── examples/ # 示例
|
||
│
|
||
└── tests/ # 测试
|
||
└── cases/ # 测试用例
|
||
```
|
||
|
||
## 🎯 核心组件
|
||
|
||
### 1. gaokao-college-advisor（方案生成）
|
||
|
||
- **功能**：基于考生信息生成志愿填报方案
|
||
- **特点**：霍兰德兴趣测试 + 个性化匹配 + 2025年位次数据
|
||
- **位置**：`skills/gaokao-college-advisor/`
|
||
|
||
### 2. gaokao-spec-checker（方案检查）
|
||
|
||
- **功能**：自动检查志愿方案是否符合本省最新政策
|
||
- **特点**：多省份自动适配 + 致命/严重/警告三级分类
|
||
- **位置**：`skills/gaokao-spec-checker/`
|
||
- **已支持**：27个省份（详见 `rules/provinces/`）
|
||
|
||
### 3. zhangxuefeng-skillset（张雪峰风格）
|
||
|
||
- **功能**：以张雪峰风格推荐志愿
|
||
- **特点**：直接、接地气、注重就业导向
|
||
- **位置**：`skills/zhangxuefeng-skillset/`
|
||
|
||
### 4. 独立脚本（可选补充）
|
||
|
||
- **gaokao-visual-report-v2.py**：生成HTML/PDF/MD报告
|
||
- **gaokao-quick-3min.py**：3分钟快速问卷
|
||
- **gaokao-collect-info.py**：7步完整收集
|
||
- **gaokao-checker**：多省份规范检查
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 在Hermes对话中使用（推荐）
|
||
|
||
```
|
||
/skill gaokao-college-advisor
|
||
# 生成方案
|
||
|
||
/skill gaokao-spec-checker
|
||
# 检查方案
|
||
```
|
||
|
||
### 命令行使用
|
||
|
||
```bash
|
||
# 规范检查
|
||
python3 ~/.local/bin/gaokao-checker plan.txt
|
||
|
||
# 生成报告
|
||
python3 ~/.local/bin/gaokao-visual-report-v2.py
|
||
|
||
# 显示问卷
|
||
python3 ~/.local/bin/gaokao-quick-3min.py
|
||
```
|
||
|
||
## 📊 已支持省份
|
||
|
||
| 模式 | 省份数 | 列表 |
|
||
| ---------- | :----: | ------------------------------------------------------------------------------------ |
|
||
| 院校专业组 | 14 | 湖南、广东、湖北、安徽、江西、甘肃、黑龙江、江苏、福建、广西、北京、上海、天津、海南 |
|
||
| 专业+学校 | 8 | 浙江、山东、河北、重庆、辽宁、贵州、青海、吉林 |
|
||
| 传统 | 5 | 河南、四川、新疆、云南、西藏 |
|
||
|
||
**总计27省，可自动识别省份并加载对应规则**
|
||
|
||
## 📝 开发规范
|
||
|
||
### 代码规范
|
||
|
||
- Python：PEP 8 + 中文注释
|
||
- Markdown：清晰标题层次
|
||
- 命名：lowercase-hyphen 或 lowercase_underscore
|
||
|
||
### 文档规范
|
||
|
||
- 每个组件有 README
|
||
- 关键决策记录到 `docs/case-studies/`
|
||
- 优化过程记录到 `docs/optimization-log/`
|
||
- 错误模式记录到 `rules/errors/`
|
||
|
||
### 测试规范
|
||
|
||
- 每个新功能要有测试用例
|
||
- 测试用例放在 `tests/cases/`
|
||
- 错误模式要加入 `rules/errors/`
|
||
|
||
## 🔄 持续优化
|
||
|
||
### 优化日志
|
||
|
||
详见 `docs/optimization-log/`，记录每次优化的：
|
||
|
||
- 优化点
|
||
- 改进效果
|
||
- 用户反馈
|
||
- 后续计划
|
||
|
||
### 已知不足
|
||
|
||
- 27省中的部分规则可能不准确
|
||
- 2026年招生计划待官方公布
|
||
- 部分省份特殊批次未覆盖
|
||
- 算法精度有待提高
|
||
|
||
### 未来规划
|
||
|
||
详见 `docs/optimization-log/future-plan.md`
|
||
|
||
## 📚 相关资源
|
||
|
||
- 阳光高考：https://gaokao.chsi.com.cn/
|
||
- 湖南省教育考试院：http://jyt.hunan.gov.cn/jyt/sjyt/hnsjyksy/
|
||
- 各省教育考试院（详见各省份规则文档）
|
||
|
||
## 📄 版权信息
|
||
|
||
本项目为个人开发项目，仅供学习参考使用。
|
||
|
||
实际志愿填报请以**各省教育考试院**官方信息为准。
|
||
|
||
---
|
||
|
||
**生成时间**：2026年6月11日
|
||
**当前版本**：v2.0
|