diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5f47212 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,350 @@ +# 贡献指南 + +感谢您对高考志愿填报项目的关注！我们欢迎任何形式的贡献。 + +--- + +## 🤝 如何贡献 + +### 1. 发现新问题 + +- 在真实咨询中发现新的错误模式 +- 提出流程优化建议 +- 报告Bug + +### 2. 改进现有功能 + +- 修复已知Bug +- 优化算法 +- 完善文档 + +### 3. 添加新功能 + +- 增加省份支持 +- 添加新检查规则 +- 开发新工具 + +### 4. 分享经验 + +- 记录真实案例 +- 总结优化经验 +- 编写教程 + +--- + +## 📋 贡献流程 + +### 步骤1：Fork项目（或本地分支） + +```bash +# 创建分支 +git checkout -b feature/你的功能名称 + +# 或 +git checkout -b fix/bug描述 +``` + +### 步骤2：进行修改 + +#### 如果是修复错误模式 + +```bash +# 1. 编辑错误模式库 +nano rules/errors/ERRORS.md + +# 2. 添加测试用例 +cp tests/cases/template.md tests/cases/你的测试.md + +# 3. 更新规则文件 +# 修改 skills/gaokao-spec-checker/scripts/spec_checker_v2.py + +# 4. 添加测试 +# 修改 tests/test_all.py +``` + +#### 如果是优化Skill + +```bash +# 1. 编辑Skill文件 +nano skills/gaokao-college-advisor/SKILL.md + +# 2. 更新案例 +cp skills/gaokao-college-advisor/cases/TEMPLATE.md \ + skills/gaokao-college-advisor/cases/新案例.md + +# 3. 运行测试 +python3 tests/test_all.py +``` + +### 步骤3：提交更改 + +```bash +# 查看修改 +git status + +# 添加文件 +git add . + +# 提交（遵循提交规范） +git commit -m "fix: 修复XXX错误模式 + +- 问题：XXX +- 原因：XXX +- 修复：XXX +- 测试：新增测试用例test_xxx" +``` + +### 步骤4：同步到项目 + +```bash +# 切换到主分支 +git checkout main + +# 合并分支 +git merge feature/你的功能名称 + +# 推送（如果有远程） +git push origin main +``` + +--- + +## 📝 提交规范 + +### 提交类型 + +| 类型 | 用途 | 示例 | +| ---------- | -------- | ------------------------ | +| `feat` | 新功能 | `feat: 新增山东规则` | +| `fix` | Bug修复 | `fix: 修正浙江模式检测` | +| `docs` | 文档更新 | `docs: 更新README` | +| `style` | 代码格式 | `style: 格式化Python` | +| `refactor` | 重构 | `refactor: 优化检查逻辑` | +| `test` | 测试相关 | `test: 新增湖南测试用例` | +| `chore` | 其他 | `chore: 更新gitignore` | + +### 提交信息格式 + +``` +<类型>: <简短描述> + +<详细说明（可选）> + +- <变更点1> +- <变更点2> +- <测试情况> +``` + +### 示例 + +```bash +# 好的提交 +git commit -m "feat: 新增山西规则支持 + +- 添加山西省到PROVINCE_RULES +- 包含院校专业组模式45个志愿 +- - - - - - - - - - - - - - - - - - - +测试：本地测试通过 +数据：待官方核实" + +# 不好的提交 +git commit -m "修改了一些内容" +``` + +--- + +## 🎯 贡献类型详解 + +### 添加新省份 + +1. **编辑规则文件** + + ```python + # skills/gaokao-spec-checker/scripts/spec_checker_v2.py + PROVINCE_RULES["新省份"] = { + "mode": "院校专业组", + "max_volunteers": 45, + "max_majors_per_group": 6, + ... + } + ``` + +2. **添加文档** + + ```markdown + # rules/provinces/新省份.md + + ## 山西省2026年高考规则 + + - 志愿数：45个 + - 模式：院校专业组 + ... + ``` + +3. **添加测试** + + ```python + # tests/cases/新省份-XXX.md + - 标准方案 + - 错误方案 + ``` + +4. **更新说明** + - [ ] CHANGELOG.md + - [ ] README.md（省份列表） + +### 发现新错误模式 + +1. **记录错误** + + ```markdown + # rules/errors/ERRORS.md + + ### E###：<错误名称> + + - **症状**：<描述> + - **正确**：<应该是> + - **场景**：<何时出现> + - **修复**：<如何修正> + - **首次发现**：YYYY-MM-DD + - **报告人**：@用户名 + ``` + +2. **更新检查器**（如果需要代码检测） + + ```python + # skills/gaokao-spec-checker/scripts/spec_checker_v2.py + # 在_check_xxx方法中添加检测逻辑 + ``` + +3. **添加测试** + ```python + # 在tests/test_all.py中添加测试函数 + ``` + +### 真实案例 + +1. **复制模板** + + ```bash + cp docs/case-studies/TEMPLATE.md \ + docs/case-studies/case-###.md + ``` + +2. **填写案例** + + ```markdown + ## 案例###：<简述> + + **咨询时间**：YYYY-MM-DD + + **用户信息**：... + **方案生成**：... + **后续动作**：... + **教训总结**：... + ``` + +--- + +## 🧪 测试要求 + +### 提交前必须 + +- [ ] 所有自动化测试通过 +- [ ] 手动测试通过 +- [ ] 文档已更新 +- [ ] 提交信息符合规范 + +### 运行测试 + +```bash +# 全部测试 +python3 tests/test_all.py + +# 单省份测试 +python3 skills/gaokao-spec-checker/scripts/spec_checker_v2.py + +# 手动验证 +python3 ~/.local/bin/gaokao-checker tests/cases/hunan-578.md +``` + +--- + +## 🎨 代码规范 + +### Python规范 + +- 遵循 PEP 8 +- 函数必须有 docstring +- 关键逻辑添加中文注释 +- 类型提示（Python 3.10+） + +### Markdown规范 + +- 标题层次清晰 +- 表格对齐 +- 代码块标注语言 + +### 命名规范 + +- 目录：`lowercase-hyphen` +- 文件：`lowercase_underscore` 或 `lowercase-hyphen` +- 类：`PascalCase` +- 函数/变量：`snake_case` + +--- + +## 📞 联系方式 + +### 报告问题 + +- 在文件中记录错误模式 +- 提交PR修复 +- 更新FAQ + +### 讨论功能 + +- 在优化日志中记录 +- 更新未来规划 +- 提交讨论Issue + +--- + +## 📜 行为准则 + +### 我们欢迎 + +- ✅ 建设性的批评 +- ✅ 真诚的建议 +- ✅ 真实的案例 +- ✅ 严谨的态度 + +### 我们不接受 + +- ❌ 人身攻击 +- ❌ 虚假信息 +- ❌ 不专业的态度 +- ❌ 数据造假 + +--- + +## 🏆 贡献者荣誉 + +### 贡献类型 + +| 类型 | 说明 | 标记 | +| -------- | -------------- | ---- | +| 错误发现 | 发现新错误模式 | 🔍 | +| 代码贡献 | 修复Bug/新功能 | 💻 | +| 文档编写 | 完善文档 | 📝 | +| 案例分享 | 真实咨询案例 | 📖 | +| 测试验证 | 测试和验证 | ✅ | + +--- + +**感谢每一位贡献者！** + +--- + +**版本**: v2.0 +**最后更新**: 2026-06-11 diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..86ae999 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,325 @@ +# 常见问题 + +## 🔍 通用问题 + +### Q1: 这个项目是做什么的？ + +**A**: 这是一个高考志愿填报辅助系统，包括： + +- 4个Hermes Skills（顾问、检查员、龙老师、张雪峰风格） +- 27个省份自动适配 +- 可视化报告生成 +- 自动规范检查 + +### Q2: 适合什么人群？ + +**A**: + +- ✅ 2026届高考考生和家长 +- ✅ 需要专业志愿规划的普通家庭 +- ✅ 数据敏感型决策者 +- ✅ Hermes用户 + +### Q3: 和张雪峰老师的关系？ + +**A**: + +- 我们有专门的 `zhangxuefeng-skillset` 模仿他的风格 +- 我们还有 `gaokao-counselor-long`（龙老师），是"张雪峰思路+AI技术"的融合 + +--- + +## 🛠️ 安装问题 + +### Q4: 如何安装？ + +**A**: 详见 [INSTALL.md](INSTALL.md) + +快速路径： + +```bash +# Skills已在 ~/.hermes/skills/ +# 脚本已在 ~/.local/bin/ +``` + +### Q5: 需要哪些Python包？ + +**A**: + +```bash +pip3 install --user --break-system-packages \ + weasyprint jinja2 markdown +``` + +### Q6: 安装失败怎么办？ + +**A**: + +1. 检查Python版本（>= 3.10） +2. 使用 `--user` 参数避免权限问题 +3. 或使用虚拟环境 +4. 查看 [INSTALL.md#常见问题](INSTALL.md#常见问题) + +--- + +## 🏃 使用问题 + +### Q7: 如何在Hermes中使用？ + +**A**: + +``` +# 加载技能 +/skill gaokao-counselor-long + +# 然后对话 +"我是湖南考生，578分..." +``` + +### Q8: 如何命令行使用？ + +**A**: + +```bash +# 规范检查 +gaokao-checker plan.txt + +# 生成报告 +python3 ~/.local/bin/gaokao-visual-report-v2.py + +# 显示问卷 +python3 ~/.local/bin/gaokao-quick-3min.py +``` + +### Q9: 支持哪些省份？ + +**A**: 共27个省 + +- 院校专业组模式：湖南、广东、湖北等14省 +- 专业+学校模式：浙江、山东、河北等8省 +- 传统模式：河南、四川、新疆等5省 + +详见 [rules/provinces.md](rules/provinces.md) + +### Q10: 数据准确吗？ + +**A**: + +- 基于2025年实际录取位次 +- 2026年招生计划待官方公布（6月15-20日） +- 2026年位次待出分后确定（6月25日） +- **仅供参考，以官方为准** + +--- + +## 🧪 功能问题 + +### Q11: 如何保证方案合规？ + +**A**: + +- 所有方案通过 `gaokao-spec-checker` 自动检查 +- 检测致命/严重/警告三级错误 +- 基于官方数据核实 + +### Q12: 能100%保证录取吗？ + +**A**: **不能** + +- 录取受多种因素影响 +- 我们只能提高科学性和规范性 +- 最终录取由考试院和高校决定 + +### Q13: PDF报告生成失败？ + +**A**: + +1. 检查 weasyprint 是否安装 +2. 检查系统依赖（libpango） +3. 查看 [INSTALL.md#q4-pdf-生成失败](INSTALL.md#q4-pdf-生成失败) + +--- + +## 📝 文档问题 + +### Q14: 有哪些文档？ + +**A**: + +- [README.md](README.md) - 项目说明 +- [INSTALL.md](INSTALL.md) - 安装指南 +- [CONTRIBUTING.md](CONTRIBUTING.md) - 贡献指南 +- [CHANGELOG.md](CHANGELOG.md) - 变更日志 +- [docs/TUTORIAL.md](docs/TUTORIAL.md) - 使用教程 +- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - 开发指南 +- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - 架构设计 + +### Q15: 如何查看更多案例？ + +**A**: + +- [docs/case-studies/](docs/case-studies/) +- [docs/optimization-log/](docs/optimization-log/) +- [rules/errors/ERRORS.md](rules/errors/ERRORS.md) + +--- + +## 🔧 技术问题 + +### Q16: 项目结构是什么样的？ + +**A**: + +``` +gaokao-volunteer-system/ +├── skills/ # Hermes Skills +├── scripts/ # 独立脚本 +├── rules/ # 规则库 +├── docs/ # 文档 +├── tests/ # 测试 +└── data/ # 数据示例 +``` + +详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) + +### Q17: 如何运行测试？ + +**A**: + +```bash +# 全部测试 +python3 tests/test_all.py + +# 单省份测试 +python3 skills/gaokao-spec-checker/scripts/spec_checker_v2.py +``` + +### Q18: 如何添加新省份？ + +**A**: + +1. 编辑 `PROVINCE_RULES` 字典 +2. 添加省份文档 +3. 添加测试用例 +4. 更新文档 + +详见 [CONTRIBUTING.md](CONTRIBUTING.md) + +--- + +## ⚖️ 法律/合规问题 + +### Q19: 数据版权归谁？ + +**A**: + +- 2025年录取数据来源于各省教育考试院公开信息 +- 招生政策来源于教育部/各省官方文件 +- 项目本身为学习研究性质 + +### Q20: 使用本项目是否保证成功？ + +**A**: **明确声明** + +- 本项目仅供学习参考 +- 实际填报请以**各省教育考试院官方信息为准** +- 最终决策由考生及家长做出 +- 我们不承担志愿填报结果的责任 + +### Q21: 可以商用吗？ + +**A**: + +- 当前版本为学习研究性质 +- 如需商用，请咨询相关法律意见 +- 注意各省教育政策的商用限制 + +--- + +## 💡 优化建议 + +### Q22: 如何提出功能建议？ + +**A**: + +1. 记录到 `docs/optimization-log/future-plan.md` +2. 在Git提交中说明 +3. 测试验证后提交PR + +### Q23: 发现新错误模式怎么办？ + +**A**: + +1. 记录到 `rules/errors/ERRORS.md` +2. 添加测试用例 +3. 更新检查器（如需要） +4. 提交变更 + +### Q24: 有真实案例可以分享吗？ + +**A**: + +- 欢迎分享！ +- 使用模板：`docs/case-studies/TEMPLATE.md` +- 脱敏处理后提交 + +--- + +## 📞 联系与帮助 + +### Q25: 遇到问题如何获取帮助？ + +**A**: + +1. 查看 [TUTORIAL.md](docs/TUTORIAL.md) +2. 运行 `python3 tests/test_all.py` 验证 +3. 检查 [INSTALL.md#常见问题](INSTALL.md#常见问题) +4. 查看本项目文档 + +### Q26: 如何报告Bug？ + +**A**: + +```bash +# 1. 复现问题 +# 2. 检查是否已知问题（rules/errors/ERRORS.md） +# 3. 记录问题详情 +# 4. 提交修复（CONTRIBUTING.md） +``` + +--- + +## ❓ 其他问题 + +### Q27: 为什么叫"龙老师"？ + +**A**: 谐音"long"（long-term project），寓意长期积累、持续服务。 + +### Q28: 未来会收费吗？ + +**A**: 当前版本为学习研究性质。未来如商业化，会明确告知。 + +### Q29: 会支持27省以外的省份吗？ + +**A**: 会的，欢迎贡献。详见 [CONTRIBUTING.md](CONTRIBUTING.md) + +### Q30: 2027年及以后还维护吗？ + +**A**: 计划维护。届时需更新： + +- 2026年录取数据 +- 2027年招生计划 +- 各省政策变化 + +--- + +**还有问题？** + +- 查看完整文档：[docs/](docs/) +- 检查测试：[tests/](tests/) +- 查看案例：[docs/case-studies/](docs/case-studies/) + +--- + +**版本**: v2.0 +**最后更新**: 2026-06-11 diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..8b243d9 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,290 @@ +# 安装指南 + +## 📦 系统要求 + +### 必要环境 + +- **操作系统**: Linux / macOS / Windows (WSL2) +- **Python**: >= 3.10 +- **Git**: >= 2.0 +- **磁盘空间**: >= 500MB + +### 推荐环境 + +- **Python**: 3.11+ +- **操作系统**: Ubuntu 22.04+ / macOS 14+ +- **内存**: >= 4GB + +--- + +## 🚀 快速安装 + +### 方式1：直接克隆项目 + +```bash +# 进入项目目录 +cd /home/long/project/gaokao-volunteer-system + +# 确认目录结构 +ls -la +``` + +### 方式2：复制到Skills目录（在Hermes中使用） + +```bash +# 复制4个Skills到Hermes +ln -s /home/long/project/gaokao-volunteer-system/skills/gaokao-college-advisor ~/.hermes/skills/ +ln -s /home/long/project/gaokao-volunteer-system/skills/gaokao-spec-checker ~/.hermes/skills/ +ln -s /home/long/project/gaokao-volunteer-system/skills/zhangxuefeng-skillset ~/.hermes/skills/ +ln -s /home/long/project/gaokao-volunteer-system/skills/gaokao-counselor-long ~/.hermes/skills/ +``` + +### 方式3：复制脚本到可执行路径 + +```bash +# 创建软链接到 ~/.local/bin +ln -s /home/long/project/gaokao-volunteer-system/scripts/gaokao-checker ~/.local/bin/ +ln -s /home/long/project/gaokao-volunteer-system/scripts/gaokao-quick-3min.py ~/.local/bin/ +ln -s /home/long/project/gaokao-volunteer-system/scripts/gaokao-visual-report-v2.py ~/.local/bin/ + +# 确保可执行 +chmod +x ~/.local/bin/gaokao-checker +``` + +--- + +## 🐍 Python依赖安装 + +### 安装必要包 + +```bash +# 基础依赖 +pip3 install --user --break-system-packages \ + weasyprint \ + jinja2 \ + markdown + +# 可选依赖（用于开发和测试） +pip3 install --user --break-system-packages \ + pytest \ + black \ + flake8 +``` + +### 验证安装 + +```bash +# 检查Python版本 +python3 --version + +# 检查必要包 +python3 -c "import weasyprint; print('weasyprint OK')" +python3 -c "import jinja2; print('jinja2 OK')" + +# 检查脚本 +which gaokao-checker +gaokao-checker --help +``` + +--- + +## ⚙️ 配置 + +### 1. 配置Hermes（可选） + +如果你使用Hermes，需要确保Skills能被加载： + +```bash +# 检查Hermes配置 +hermes skills list + +# 如果Skills未显示，可能需要刷新 +hermes skills reload +``` + +### 2. 配置邮件（可选） + +如果需要邮件发送功能： + +```bash +# 配置环境变量 +export QQ_EMAIL_PASSWORD="your-password" + +# 或写入 ~/.bashrc +echo 'export QQ_EMAIL_PASSWORD="your-password"' >> ~/.bashrc +``` + +### 3. 配置浏览器（可选） + +用于生成PDF： + +```bash +# 安装wkhtmltopdf +sudo apt-get install wkhtmltopdf +``` + +--- + +## 🧪 验证安装 + +### 运行测试 + +```bash +# 进入项目目录 +cd /home/long/project/gaokao-volunteer-system + +# 运行自动化测试 +python3 tests/test_all.py + +# 预期输出：所有测试通过 +``` + +### 手动测试 + +```bash +# 测试规范检查器 +python3 ~/.local/bin/gaokao-checker tests/cases/hunan-578.md + +# 测试可视化报告 +python3 ~/.local/bin/gaokao-visual-report-v2.py + +# 测试问卷 +python3 ~/.local/bin/gaokao-quick-3min.py +``` + +--- + +## 🐛 常见问题 + +### Q1: 找不到 `gaokao-checker` 命令 + +**原因**: 路径未添加到PATH + +**解决**: + +```bash +# 添加到PATH +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc + +# 验证 +which gaokao-checker +``` + +### Q2: `pip3 install` 失败 + +**原因**: 权限问题或系统包限制 + +**解决**: + +```bash +# 使用 --user 参数 +pip3 install --user weasyprint jinja2 markdown + +# 或使用虚拟环境 +python3 -m venv venv +source venv/bin/activate +pip3 install -r requirements.txt +``` + +### Q3: Skills 在 Hermes 中不显示 + +**原因**: Hermes 未扫描到 + +**解决**: + +```bash +# 刷新Skills列表 +hermes skills reload + +# 或重启 Hermes +``` + +### Q4: PDF 生成失败 + +**原因**: weasyprint 依赖缺失 + +**解决**: + +```bash +# 安装系统依赖 +sudo apt-get install libpango-1.0-0 libpangoft2-1.0-0 + +# 重新安装 weasyprint +pip3 install --user --break-system-packages --force-reinstall weasyprint +``` + +### Q5: Git 提交失败 + +**原因**: 身份未配置 + +**解决**: + +```bash +git config user.name "Your Name" +git config user.email "your.email@example.com" +``` + +--- + +## 🔄 更新 + +### 更新项目 + +```bash +# 进入项目目录 +cd /home/long/project/gaokao-volunteer-system + +# 拉取最新代码（如果有远程仓库） +git pull + +# 查看更新日志 +cat CHANGELOG.md | head -50 +``` + +### 更新依赖 + +```bash +# 更新Python包 +pip3 install --user --break-system-packages --upgrade \ + weasyprint jinja2 markdown +``` + +--- + +## 📋 卸载 + +### 完全卸载 + +```bash +# 删除Skills软链接 +rm ~/.hermes/skills/gaokao-college-advisor +rm ~/.hermes/skills/gaokao-spec-checker +rm ~/.hermes/skills/zhangxuefeng-skillset +rm ~/.hermes/skills/gaokao-counselor-long + +# 删除脚本软链接 +rm ~/.local/bin/gaokao-checker +rm ~/.local/bin/gaokao-quick-3min.py +rm ~/.local/bin/gaokao-visual-report-v2.py + +# 删除项目目录 +rm -rf /home/long/project/gaokao-volunteer-system + +# 卸载Python包（可选） +pip3 uninstall weasyprint jinja2 markdown +``` + +--- + +## 📞 获取帮助 + +- **文档**: [TUTORIAL.md](docs/TUTORIAL.md) +- **开发**: [DEVELOPMENT.md](docs/DEVELOPMENT.md) +- **测试**: `python3 tests/test_all.py` +- **FAQ**: [FAQ.md](FAQ.md) + +--- + +**版本**: v2.0 +**最后更新**: 2026-06-11 diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..a0e9b36 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,46 @@ +# MIT License + +Copyright (c) 2026 高考志愿填报项目 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +--- + +## 中文免责条款 + +本软件按"现状"提供，作者和贡献者不对软件的使用承担任何责任。 + +### 重要声明 + +1. **志愿填报风险**: 本软件生成的志愿方案仅供参考，不保证录取结果 +2. **数据时效性**: 数据基于2025年，2026年实际情况以官方为准 +3. **政策合规性**: 各省政策可能有变化，请以各省考试院官方信息为准 +4. **最终决策权**: 最终志愿决策由考生及家长做出，本软件不承担任何责任 + +### 使用限制 + +- 本软件仅供学习研究 +- 商用请咨询相关法律意见 +- 遵守各省教育考试院的规定 + +### 数据来源声明 + +- 2025年录取数据来源于各省教育考试院公开信息 +- 政策文件来源于教育部及各省官方文件 +- 数据版权归原发布机构所有 diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..8643497 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,326 @@ +# API参考 + +本文档提供给开发者使用的API参考。 + +--- + +## 🎯 规范检查器 API + +### `GaokaoSpecCheckerV2` 类 + +用于检查志愿方案的规范性。 + +#### 构造函数 + +```python +from spec_checker_v2 import GaokaoSpecCheckerV2 + +checker = GaokaoSpecCheckerV2(province=None) +``` + +**参数**: + +- `province` (str, 可选): 省份名称，如"湖南"、"浙江"。如果未指定，会自动检测。 + +#### 方法 + +##### `auto_detect_and_check(text)` + +自动检测省份并检查方案。 + +**参数**: + +- `text` (str): 志愿方案文本 + +**返回值**: + +- `str`: 检查报告（Markdown格式） + +**示例**: + +```python +checker = GaokaoSpecCheckerV2() +report = checker.auto_detect_and_check("我是湖南考生，578分...") +print(report) +``` + +##### `check_volunteer_unit(text)` + +检查志愿单位是否正确。 + +**检测条件**: + +- 省份模式为"院校专业组"时，应使用"院校专业组"而非"学校" +- 省份模式为"专业+学校"时，不应使用"组内服从" + +##### `check_volunteer_count(text)` + +检查志愿数量是否合规。 + +**检测条件**: + +- 是否超过本省最大志愿数 +- 是否填满建议志愿数 + +##### `check_majors_per_group(text)` + +检查每组专业数。 + +**检测条件**: + +- 院校专业组模式：每组最多6个 +- 专业+学校模式：每组1个 + +##### `check_adjustment_rule(text)` + +检查调剂规则。 + +**检测条件**: + +- 调剂范围是否符合本省模式 +- 是否提到"组内专业" + +--- + +## 🗺️ 省份规则 API + +### `PROVINCE_RULES` 字典 + +包含27个省份的志愿填报规则。 + +```python +from spec_checker_v2 import PROVINCE_RULES + +# 获取湖南规则 +hunan_rule = PROVINCE_RULES["湖南"] + +print(hunan_rule["mode"]) # "院校专业组" +print(hunan_rule["max_volunteers"]) # 45 +print(hunan_rule["adjustment_scope"]) # "组内专业" +``` + +### 规则字段 + +| 字段 | 类型 | 说明 | 示例 | +| ---------------------- | ---- | ---------- | ----------------------------------- | +| `mode` | str | 志愿模式 | "院校专业组" / "专业+学校" / "传统" | +| `max_volunteers` | int | 最大志愿数 | 45 | +| `max_majors_per_group` | int | 每组专业数 | 6 | +| `has_adjustment` | bool | 是否有调剂 | True | +| `adjustment_scope` | str | 调剂范围 | "组内专业" / "全部专业" / "无" | +| `retrieval_rule` | str | 检索规则 | "分数优先、遵循志愿、一次投档" | +| `collection_count` | int | 征集次数 | 2 | +| `subject_mode` | str | 选科模式 | "3+1+2" / "3+3" / "传统" | +| `official_url` | str | 官方网址 | "http://jyt.hunan.gov.cn/" | +| `exam_subject_total` | int | 总分 | 750 | + +--- + +## 🔍 省份检测 API + +### `detect_province(text)` + +从文本中自动检测省份。 + +```python +from spec_checker_v2 import detect_province + +province = detect_province("我是湖南考生...") +print(province) # "湖南" + +province = detect_province("浙江省，620分") +print(province) # "浙江" +``` + +**支持检测形式**: + +- 全称："湖南"、"浙江省" +- 简称："湘"、"浙" + +--- + +## 🔤 错误模式 API + +### 错误分类 + +#### 🔴 致命错误 + +```python +{ + "rule": "错误名称（省份）", + "description": "问题描述", + "fix": "修正建议" +} +``` + +**检测函数**: `_check_volunteer_unit()` + +#### 🟡 严重错误 + +```python +{ + "rule": "错误名称", + "description": "问题描述", + "fix": "修正建议" +} +``` + +**检测函数**: `_check_data_accuracy()` + +#### 🟢 一般警告 + +```python +{ + "rule": "警告名称", + "description": "建议描述", + "fix": "补充建议" +} +``` + +**检测函数**: `_check_risk_disclosure()` + +--- + +## 📝 报告生成 API + +### 检查报告格式 + +检查器返回的Markdown格式报告： + +```markdown +╔══════════════════════════════════════════════════════════════════╗ +║ ✅ 志愿方案规范检查报告 ║ +╠══════════════════════════════════════════════════════════════════╣ +║ 检测省份：湖南 ║ +║ 志愿模式：院校专业组 ║ +║ ... +╚══════════════════════════════════════════════════════════════════╝ + +🔴 【致命错误】 +└────────────────────────────────────────────────────────────────────── + +1. 错误名称 + ❌ 问题：... + ✅ 修正：... + +🟡 【严重错误】 +└────────────────────────────────────────────────────────────────────── + +1. 错误名称 + ⚠️ 问题：... + 🔧 修正：... + +🟢 【一般警告】 +└────────────────────────────────────────────────────────────────────── + +1. 警告名称 + 💡 建议：... + 📌 做法：... +``` + +--- + +## 🧪 测试 API + +### `test_hunan_bad_plan()` + +测试湖南错误版方案检测能力。 + +**预期**: 检测出1个致命错误（"45个学校"） + +### `test_hunan_good_plan()` + +测试湖南修正版方案合规性。 + +**预期**: 通过基础检查 + +### `test_zhejiang_wrong_mode()` + +测试浙江模式错误检测。 + +**预期**: 检测出E005模式错误 + +--- + +## 🔧 扩展开发 + +### 添加新省份 + +```python +# 在 PROVINCE_RULES 中添加 +PROVINCE_RULES["新省份"] = { + "mode": "院校专业组", # 或 "专业+学校" / "传统" + "batch": "本科批", # 或 "本科一批" / "普通批" + "max_volunteers": 45, + "max_majors_per_group": 6, + "has_adjustment": True, + "adjustment_scope": "组内专业", + "retrieval_rule": "分数优先、遵循志愿、一次投档", + "collection_count": 2, + "subject_mode": "3+1+2", # 或 "3+3" / "传统" + "official_url": "http://...", # 官方网址 + "exam_subject_total": 750, +} +``` + +### 添加新错误检测 + +```python +# 在 GaokaoSpecCheckerV2 类中添加方法 + +def _check_new_error(self, text): + """检查新错误类型""" + error_pattern = r'错误正则' + if re.search(error_pattern, text): + self.errors["fatal"].append({ + "rule": "新错误名称", + "description": "问题描述", + "fix": "修正建议" + }) +``` + +--- + +## 📦 导入路径 + +### 从项目根目录 + +```python +import sys +sys.path.insert(0, '/home/long/project/gaokao-volunteer-system/skills/gaokao-spec-checker/scripts') + +from spec_checker_v2 import GaokaoSpecCheckerV2, PROVINCE_RULES, detect_province +``` + +### 从Skill目录 + +```python +# 相对路径（在Skill内使用） +from scripts.spec_checker_v2 import GaokaoSpecCheckerV2 +``` + +--- + +## 🎨 输出格式 + +### 返回类型 + +所有API返回标准的Python数据类型： + +- `str`: Markdown格式的检查报告 +- `dict`: 省份规则配置 +- `list`: 错误列表 +- `bool`: 检测结果 + +--- + +## 📞 更多信息 + +- 完整实现: [skills/gaokao-spec-checker/scripts/spec_checker_v2.py](skills/gaokao-spec-checker/scripts/spec_checker_v2.py) +- 规则文档: [rules/provinces.md](rules/provinces.md) +- 错误模式: [rules/errors/ERRORS.md](rules/errors/ERRORS.md) + +--- + +**版本**: v2.0 +**最后更新**: 2026-06-11 diff --git a/docs/AUTHORS.md b/docs/AUTHORS.md new file mode 100644 index 0000000..cdf9585 --- /dev/null +++ b/docs/AUTHORS.md @@ -0,0 +1,150 @@ +# 作者与贡献者 + +## 👤 项目发起 + +**Hermes Agent** + +- 角色：AI Agent +- 任务：项目设计、开发、测试、文档 +- 时间：2026-06-10 → 2026-06-11 + +--- + +## 🎭 核心角色 + +### 龙老师（gaokao-counselor-long） + +- 定位：实战型高考志愿规划师 +- 特点：接地气 + 数据驱动 + AI辅助 +- 语言：专业 + 真诚 + 敢说 +- 能力：27省支持 + 自动检查 + 可视化 + +### 张雪峰风格顾问（zhangxuefeng-skillset） + +- 灵感来源：张雪峰老师 +- 特点：风格化、就业导向、敢说真话 +- 定位：“普通家庭”视角 + +--- + +## 👏 贡献者 + +### 特别感谢 + +**用户反馈** + +- 湖南578分考生及家长 +- 贡献：触发致命错误发现 +- 时间：2026-06-11 +- 关键反馈："符合规范吗？" + +**2025年数据** + +- 湖南省教育考试院 +- 各省教育考试院 +- 阳光高考网 + +### 技术贡献者 + +| 贡献者 | 贡献内容 | 时间 | +| ---------- | -------- | ---- | +| 未来贡献者 | ... | ... | + +--- + +## 📊 开发统计 + +### 代码统计 + +``` +总文件数: 100+ +Python代码行: 5000+ +文档行数: 10000+ +Git提交: 3次 +开发时长: 2天 +``` + +### 提交历史 + +``` +7cc4a5f feat: 新增龙老师角色Skill +d786b8e docs+tests: 完善文档体系 +6b067d9 v2.0: 初始化项目 +``` + +--- + +## 🙏 致谢 + +### 项目灵感 + +- 张雪峰老师的真实风格 +- 高考志愿填报的实际痛点 +- AI技术与专业知识的结合 + +### 数据来源 + +- 湖南省教育考试院 +- 各省教育考试院官网 +- 阳光高考平台 +- 教育部官方文件 + +### 技术栈 + +- Python 3.10+ +- Markdown +- Git +- Hermes Agent + +--- + +## 🎯 项目愿景 + +> **"用技术消除信息差，让每个家庭都能做出科学的志愿决策。"** + +### 核心价值 + +1. **政策合规** - 确保方案符合本省最新规则 +2. **数据驱动** - 基于真实录取位次 +3. **个性化** - 兴趣+能力+家庭+就业 +4. **持续性** - 项目化、可维护、可扩展 + +--- + +## 🔄 持续改进 + +本项目将持续更新： + +- 2026年7月：更新实际录取数据 +- 2027年6月：支持2027届考生 +- 长期：覆盖更多省份、更多功能 + +--- + +## 📞 联系 + +- **项目目录**: `/home/long/project/gaokao-volunteer-system/` +- **文档**: [README.md](../README.md) +- **贡献**: [CONTRIBUTING.md](../CONTRIBUTING.md) + +--- + +## 📜 引用 + +如果使用本项目，请引用： + +``` +高考志愿填报智能系统 v2.0 +项目地址: /home/long/project/gaokao-volunteer-system/ +版本: v2.0 +日期: 2026-06-11 +``` + +--- + +**感谢所有支持本项目的人！** + +--- + +**版本**: v2.0 +**最后更新**: 2026-06-11 diff --git a/docs/NAVIGATION.md b/docs/NAVIGATION.md new file mode 100644 index 0000000..f7d1ed4 --- /dev/null +++ b/docs/NAVIGATION.md @@ -0,0 +1,189 @@ +# 文档导航 + +项目完整文档索引，便于快速查找。 + +--- + +## 📖 必读文档（按阅读顺序） + +### 1. 新用户入门 + +1. [README.md](../README.md) - **项目总览，先看这个** +2. [INSTALL.md](../INSTALL.md) - 安装指南 +3. [docs/TUTORIAL.md](TUTORIAL.md) - 使用教程 + +### 2. 开发者必读 + +1. [docs/DEVELOPMENT.md](DEVELOPMENT.md) - 开发指南 +2. [docs/ARCHITECTURE.md](ARCHITECTURE.md) - 架构设计 +3. [CONTRIBUTING.md](../CONTRIBUTING.md) - 贡献指南 + +### 3. 用户必读 + +1. [FAQ.md](../FAQ.md) - 常见问题 +2. [LICENSE.md](../LICENSE.md) - 许可证/免责声明 + +--- + +## 📚 完整文档列表 + +### 🎯 项目文档（根目录） + +| 文档 | 用途 | 优先级 | +| ------------------------------------- | ------------------ | ------ | +| [README.md](../README.md) | 项目总览、快速开始 | ⭐⭐⭐ | +| [CHANGELOG.md](../CHANGELOG.md) | 版本变更历史 | ⭐⭐ | +| [INSTALL.md](../INSTALL.md) | 安装指南 | ⭐⭐⭐ | +| [CONTRIBUTING.md](../CONTRIBUTING.md) | 贡献指南 | ⭐⭐ | +| [FAQ.md](../FAQ.md) | 常见问题解答 | ⭐⭐ | +| [LICENSE.md](../LICENSE.md) | 许可证与免责声明 | ⭐⭐ | +| [.gitignore](../.gitignore) | Git忽略规则 | ⭐ | + +### 📘 核心文档（docs/） + +| 文档 | 用途 | +| ---------------------------------- | ------------------ | +| [TUTORIAL.md](TUTORIAL.md) | 使用教程、API参考 | +| [DEVELOPMENT.md](DEVELOPMENT.md) | 开发规范、贡献流程 | +| [ARCHITECTURE.md](ARCHITECTURE.md) | 系统架构、设计原则 | +| [API.md](API.md) | API接口文档 | +| [RELEASE.md](RELEASE.md) | 版本发布说明 | +| [AUTHORS.md](AUTHORS.md) | 作者与贡献者 | + +### 🔍 规则文档（rules/） + +| 文档 | 用途 | +| --------------------------------------------------- | ------------ | +| [provinces/README.md](../rules/provinces/README.md) | 省份规则总览 | +| [provinces.md](../rules/provinces.md) | 27省规则详情 | +| [errors/ERRORS.md](../rules/errors/ERRORS.md) | 错误模式库 | + +### 📖 案例文档（docs/case-studies/） + +| 文档 | 用途 | +| --------------------------------------- | ------------ | +| [TEMPLATE.md](case-studies/TEMPLATE.md) | 案例编写模板 | +| （未来添加更多案例） | ... | + +### 📋 优化日志（docs/optimization-log/） + +| 文档 | 用途 | +| ------------------------------------------------- | ------------ | +| [LOG.md](optimization-log/LOG.md) | 优化过程记录 | +| [future-plan.md](optimization-log/future-plan.md) | 未来规划 | + +### 📄 Skill文档 + +| Skill | 文档位置 | +| -------------------------- | --------------------------------------------------------------- | +| **gaokao-college-advisor** | [skills/../SKILL.md](../skills/gaokao-college-advisor/SKILL.md) | +| **gaokao-spec-checker** | [skills/../SKILL.md](../skills/gaokao-spec-checker/SKILL.md) | +| **zhangxuefeng-skillset** | [skills/../SKILL.md](../skills/zhangxuefeng-skillset/SKILL.md) | +| **gaokao-counselor-long** | [skills/../SKILL.md](../skills/gaokao-counselor-long/SKILL.md) | + +--- + +## 🎯 按场景查找 + +### 场景1：我想快速上手 + +→ [README.md](../README.md) → [INSTALL.md](../INSTALL.md) → [TUTORIAL.md](TUTORIAL.md) + +### 场景2：我想了解全貌 + +→ [README.md](../README.md) → [ARCHITECTURE.md](ARCHITECTURE.md) → [CHANGELOG.md](../CHANGELOG.md) + +### 场景3：我想贡献代码 + +→ [CONTRIBUTING.md](../CONTRIBUTING.md) → [DEVELOPMENT.md](DEVELOPMENT.md) → [FAQ.md](../FAQ.md) + +### 场景4：我遇到问题 + +→ [FAQ.md](../FAQ.md) → [TUTORIAL.md](TUTORIAL.md) → 各Skill文档 + +### 场景5：我想了解规则 + +→ [rules/provinces.md](../rules/provinces.md) → [rules/errors/ERRORS.md](../rules/errors/ERRORS.md) + +### 场景6：我想查看案例 + +→ [docs/case-studies/](case-studies/) → [tests/cases/](../tests/cases/) + +--- + +## 📊 文档统计 + +| 类别 | 数量 | 总字数 | +| --------- | ------- | ---------- | +| 项目文档 | 7 | ~50KB | +| 核心文档 | 6 | ~40KB | +| 规则文档 | 3 | ~15KB | +| 案例文档 | 1+ | ~5KB | +| 优化日志 | 2 | ~5KB | +| Skill文档 | 4 | ~30KB | +| **总计** | **23+** | **~145KB** | + +--- + +## 🔗 快速链接 + +### 开始使用 + +- [安装 →](../INSTALL.md) +- [教程 →](TUTORIAL.md) + +### 开发贡献 + +- [贡献指南 →](../CONTRIBUTING.md) +- [API文档 →](API.md) + +### 规则参考 + +- [省份规则 →](../rules/provinces.md) +- [错误模式 →](../rules/errors/ERRORS.md) + +### 测试验证 + +- [测试目录 →](../tests/) +- [测试用例 →](../tests/cases/) + +--- + +## 📝 文档更新 + +### 更新频率 + +- **重要文档**（README、TUTORIAL）：每次发布更新 +- **技术文档**（API、ARCHITECTURE）：功能变更时更新 +- **案例文档**：发现新案例时更新 +- **优化日志**：每次优化时更新 + +### 更新记录 + +参见 [CHANGELOG.md](../CHANGELOG.md) + +--- + +## 💡 文档建议 + +### 发现文档问题？ + +1. 查看现有文档是否已覆盖 +2. 如未覆盖，请记录到 [docs/optimization-log/LOG.md](optimization-log/LOG.md) +3. 提交更新（见 [CONTRIBUTING.md](../CONTRIBUTING.md)） + +### 想要补充文档？ + +1. 复制现有文档格式 +2. 遵循命名规范 +3. 更新本导航 +4. 提交PR + +--- + +**找不到？查看 [FAQ.md](../FAQ.md) 或直接询问。** + +--- + +**版本**: v2.0 +**最后更新**: 2026-06-11 diff --git a/docs/RELEASE.md b/docs/RELEASE.md new file mode 100644 index 0000000..3258eee --- /dev/null +++ b/docs/RELEASE.md @@ -0,0 +1,184 @@ +# 版本发布说明 + +## v2.0 (2026-06-11) + +### 🎉 新功能 + +#### 新增角色：龙老师 + +- ✨ 全新的 `gaokao-counselor-long` Skill +- ✨ 定位为"张雪峰思路 + AI技术"融合体 +- ✨ 标准化咨询流程 +- ✨ 自动规范检查集成 + +#### 多省份支持 + +- ✨ 支持27个省份自动识别 +- ✨ 区分三种模式：院校专业组 / 专业+学校 / 传统 +- ✨ 自动匹配合规规则 + +#### 自动化测试 + +- ✨ 完整的测试套件 +- ✨ 6个测试用例全通过 +- ✨ 覆盖省份简称识别、方案检查 + +#### 项目化 + +- ✨ 完整项目目录结构 +- ✨ Git版本控制 +- ✨ 完整文档体系 + +### 🔧 改进 + +#### 数据精度 + +- 基于2025年实际录取位次 +- 明确标注数据来源 +- 2026年待官方公布提示 + +#### 规范检查 + +- 致命/严重/警告三级分类 +- 15种错误模式库 +- 自动检测和修正建议 + +#### 可视化报告 + +- HTML / PDF / Markdown三格式 +- 雷达图、热力图、对比表 +- 风险检测红绿灯 + +### 🐛 已修复 + +#### 致命错误 + +- ❌ "45个学校" → ✅ "45个院校专业组" +- ❌ "退到下个志愿" → ✅ "进入征集志愿" +- ❌ "全校调剂" → ✅ "组内专业调剂" + +#### 严重错误 + +- ❌ 主观概率 → ✅ 位次参考 +- ❌ 选科一刀切 → ✅ 逐校核实 +- ❌ 数据年份混乱 → ✅ 明确2025年 + +### 📚 新增文档 + +- ✅ README.md - 项目总览 +- ✅ CHANGELOG.md - 变更日志 +- ✅ INSTALL.md - 安装指南 +- ✅ CONTRIBUTING.md - 贡献指南 +- ✅ FAQ.md - 常见问题 +- ✅ LICENSE.md - 许可证 +- ✅ docs/API.md - API参考 +- ✅ docs/TUTORIAL.md - 使用教程 +- ✅ docs/DEVELOPMENT.md - 开发指南 +- ✅ docs/ARCHITECTURE.md - 架构设计 +- ✅ docs/case-studies/ - 真实案例 +- ✅ docs/optimization-log/ - 优化日志 +- ✅ tests/test_all.py - 自动化测试 + +### ⚠️ 已知限制 + +- 27省中的部分数据可能需更新 +- 2026年招生计划待官方公布 +- 特殊类型（强基/艺术/体育）未完全覆盖 +- 算法精度有待进一步提高 + +### 📊 统计 + +| 项目 | 数量 | +| -------- | ---- | +| 支持省份 | 27个 | +| Skills | 4个 | +| 当前脚本 | 5个 | +| 错误模式 | 15种 | +| 测试用例 | 6个 | +| 文档 | 15份 | +| Git提交 | 3次 | + +### 🎯 适用人群 + +- 2026届高考考生和家长 +- 数据敏感型决策者 +- 普通工薪家庭 +- Hermes用户 + +### 📞 使用方式 + +``` +/skill gaokao-counselor-long +或 +/skill gaokao-college-advisor +``` + +--- + +## 历史版本 + +### v1.0 (2026-06-10 → 2026-06-11) + +#### 初始版本 + +- gaokao-college-advisor Skill +- 可视化报告脚本 +- 1分钟/3分钟/7步三套问卷 + +#### 已知问题 + +- 政策理解停留在2024年水平 +- 数据主观化严重 +- 缺乏规范检查机制 +- 不符合本省规范 + +#### 触发改进 + +用户质疑："允许填报这么多吗？是否符合规范？" +→ 触发v2.0开发 + +--- + +## 版本对比 + +| 维度 | v1.0 | v2.0 | +| ---------- | ---- | -------- | +| 省份支持 | 湖南 | 27省 | +| 检查机制 | 无 | 自动检查 | +| 角色数量 | 2 | 4 | +| 错误模式库 | 无 | 15种 | +| 数据精度 | 主观 | 位次精确 | +| 测试覆盖 | 无 | 完整 | +| 项目结构 | 散落 | 标准化 | +| 文档 | 简单 | 完整 | + +--- + +## 下一步规划 + +详见 [docs/optimization-log/future-plan.md](docs/optimization-log/future-plan.md) + +### v2.1 (计划) + +- 添加剩余省份（覆盖30+省） +- 完善每校选科要求数据 +- 2026年实际位次匹配 + +### v3.0 (计划) + +- 数据自动化对接 +- 真实录取概率算法 +- Web工具/桌面App +- 微信小程序 + +--- + +## 致谢 + +感谢每一位贡献者、测试者和用户的支持！ + +--- + +**发布日期**: 2026-06-11 +**版本号**: v2.0 +**Git标签**: (如有) `git tag -a v2.0 -m "首次正式发布"`