gaokao-volunteer-system/docs/TUTORIAL.md

# 使用教程

## 🎯 这个文档写给谁

- 第一次接触本系统的用户
- 想深入了解功能的开发者
- 需要快速找到某个功能的人

## 📚 文档导航

### 🚀 快速上手

- [README.md](../README.md) - 项目总览（**先看这个**）
- [快速使用指南](#快速使用指南) - 5分钟上手

### 📖 深入使用

- [Skills使用](#skills使用) - 3个Skill详细用法
- [脚本使用](#脚本使用) - 命令行工具
- [可视化报告](#可视化报告) - 生成HTML/PDF

### 🏗️ 开发相关

- [开发指南](DEVELOPMENT.md) - 如何贡献
- [架构设计](ARCHITECTURE.md) - 系统架构
- [API参考](#api参考) - 脚本API

### 📋 规范参考

- [错误模式库](../rules/errors/ERRORS.md) - 15种错误
- [省份规则](../rules/provinces.md) - 省份规则索引与真相源入口
- [测试用例](#测试用例) - 验证方法

### 📝 案例与优化

- [真实案例](case-studies/) - 实际使用案例
- [优化日志](optimization-log/) - 改进过程
- [变更日志](../CHANGELOG.md) - 版本历史

---

## 🚀 快速使用指南

### 1. 在Hermes对话中（最简单）

```
# 加载Skill
/skill gaokao-college-advisor

# 然后正常对话
"我是一名湖南考生，578分，物理+化学+生物选科"

# AI会引导你：
# 1. 兴趣测评（霍兰德测试）
# 2. 学科评估
# 3. 家庭情况
# 4. 生成方案

# 然后检查
/skill gaokao-spec-checker
"请检查这个方案..."
```

### 2. 使用命令行（生成报告）

```bash
# 步骤1：信息收集
python3 ~/.local/bin/gaokao-quick-3min.py
# 显示问卷模板

# 步骤2：保存问卷回复到文件
# （用户在对话中完成）

# 步骤3：生成报告
python3 ~/.local/bin/gaokao-visual-report-v2.py
# 输出：HTML + PDF + Markdown

# 步骤4：规范检查
python3 ~/.local/bin/gaokao-checker plan.txt
# 输出：检查报告
```

### 3. 演示完整流程

```bash
bash ~/.local/bin/gaokao-demo-full-workflow.sh
# 自动演示：
# 1. 显示问卷
# 2. 模拟用户回复
# 3. 生成报告
# 4. 输出文件
```

---

## 🤖 Skills使用

### gaokao-college-advisor（方案生成）

**作用**：根据考生信息生成个性化志愿方案

**特点**：

- 基于霍兰德职业兴趣测试
- 考虑学科优劣势
- 物理+化学+生物 选科专业覆盖
- 数据基于2025年位次

**使用流程**：

```
1. 加载Skill
2. 提供基本信息（省份/分数/选科）
3. 回答兴趣测评（5个问题）
4. 回答学科评估
5. 等待方案生成
6. 检查方案（用 spec-checker）
```

### gaokao-spec-checker（规范检查）

**作用**：自动检查志愿方案是否符合本省最新政策

**特点**：

- 支持27个省份自动识别
- 检测8+种常见错误
- 输出致命/严重/警告三级分类
- 提供具体修正建议

**使用场景**：

- 生成方案后立即检查
- 填报前最终核对
- 用户咨询时验证方案

### zhangxuefeng-skillset（张雪峰风格）

**作用**：以张雪峰的风格推荐志愿

**特点**：

- 直接、接地气
- 注重就业导向
- 强调"普通家庭"视角
- 避免"高大上"陷阱

**适用用户**：

- 偏好张雪峰推荐风格
- 普通家庭考生
- 重视就业前景

---

## 🛠️ 脚本使用

### gaokao-checker（规范检查）

```bash
# 基本用法
python3 ~/.local/bin/gaokao-checker plan.txt

# 指定省份
python3 ~/.local/bin/gaokao-checker plan.txt 浙江

# 完整工作流演示
bash ~/.local/bin/gaokao-demo-full-workflow.sh
```

**输出**：自动检测省份，输出针对性检查报告

### gaokao-visual-report-v2.py（可视化）

```bash
# 直接运行（使用示例数据）
python3 ~/.local/bin/gaokao-visual-report-v2.py
# 输出：/tmp/gaokao_report_*.html/pdf/md
```

**修改示例数据**：编辑脚本底部的 `student_data` 和 `volunteer_list`

### gaokao-quick-3min.py（问卷）

```bash
# 显示问卷
python3 ~/.local/bin/gaokao-quick-3min.py
```

**特点**：

- 1分钟极速版（5个问题）
- 3分钟快速版（10个问题）
- 包含霍兰德类型速查表

### gaokao-collect-info.py（7步完整收集）

```bash
# 启动交互式收集
python3 ~/.local/bin/gaokao-collect-info.py
```

**特点**：

- 7步分步引导
- 实时输入验证
- 自动保存为JSON

---

## 📊 可视化报告

### 报告类型

#### HTML报告

- **优点**：精美、可分享、有交互
- **用途**：手机/平板查看、分享链接
- **大小**：约15KB

#### PDF报告

- **优点**：可打印、格式固定
- **用途**：存档、提交
- **大小**：约300KB

#### Markdown报告

- **优点**：可编辑、可转换
- **用途**：二次加工
- **大小**：约8KB

### 报告内容

1. **考生画像雷达图** - 四维度匹配度
2. **院校对比决策表** - 冲稳保可视化
3. **专业匹配度热力图** - 颜色编码
4. **风险检测报告** - 红绿灯警示

---

## 📋 错误模式库

15种已识别错误（详见 `rules/errors/ERRORS.md`）：

### 致命错误（5种）

- E001: 志愿单位错误
- E002: 调剂范围错误
- E003: 投档后规则错误
- E004: 征集志愿次数错误
- E005: 模式错误

### 严重错误（5种）

- S001: 主观概率
- S002: 选科要求一刀切
- S003: 位次数据年份错误
- S004: 2026年位次未说明
- S005: 未提及模式概念

### 一般警告（5种）

- W001: 体检要求缺失
- W002: 专业代码缺失
- W003: 院校代码缺失
- W004: 数据来源未标注
- W005: 风险提示缺失

---

## 🧪 测试用例

### 标准测试

#### 湖南方案（错误版）

```python
plan = """
湖南578分考生志愿方案
本次共填报45个学校志愿：
志愿01：江西财经大学，会计学
录取概率35%
"""
# 应检测出：致命错误
```

#### 湖南方案（修正版）

```python
plan = """
湖南2026高考志愿填报方案（578分）
本次共填报45个院校专业组志愿...
每组最多6个专业+1个组内专业服从...
"""
# 应通过基础检查
```

#### 浙江方案（专业+学校）

```python
plan = """
浙江省，630分
本次共填报80个专业+学校志愿：
每个志愿填1个专业。
"""
# 应识别为"专业+学校"模式
```

### 自动测试

```bash
# 添加测试用例到 tests/cases/
# 编写测试脚本 tests/test_all.py
python3 tests/test_all.py
```

---

## ❓ 常见问题

### Q1：哪个Skill应该先加载？

A：先 `gaokao-college-advisor` 生成方案，再用 `gaokao-spec-checker` 检查。

### Q2：报告生成失败怎么办？

A：检查是否安装了 weasyprint（PDF需要）和 jinja2（HTML需要）。

### Q3：找不到我的省份？

A：当前支持27个省份。如需添加新省份，编辑 `PROVINCE_RULES` 字典。

### Q4：方案被打回怎么办？

A：检查致命错误，优先修正。然后严重错误，最后警告。

### Q5：可以批量处理多个考生吗？

A：可以，参考 `gaokao-visual-report-v2.py` 中的 `student_data` 字典结构，编写循环脚本。

---

## 📞 获取帮助

- **文档**：本目录
- **案例**：`docs/case-studies/`
- **优化**：`docs/optimization-log/`
- **变更**：`CHANGELOG.md`

---

**版本**：v2.0  
**最后更新**：2026-06-11