d786b8ee96
新增文档： - docs/ARCHITECTURE.md - 系统架构设计 - docs/DEVELOPMENT.md - 开发指南 - docs/TUTORIAL.md - 使用教程（导航+快速上手+API参考） 新增测试： - tests/test_all.py - 自动化测试脚本 - 省份简称识别（5个） - 方案检查（5个用例） - 所有测试通过 - tests/cases/hunan-578.md - 湖南测试用例 - tests/cases/zhejiang-630.md - 浙江测试用例 测试结果：所有6个测试用例通过 - 湘/浙/鲁/粤/鄂简称识别 - 湖南错误版方案检测 - 湖南修正版方案通过 - 浙江错误模式检测 - 山东正确方案通过 - 未提供省份处理
187 lines
3.9 KiB
Markdown
187 lines
3.9 KiB
Markdown
# 开发指南
|
||
|
||
## 🎯 项目目标
|
||
|
||
为高考考生提供**专业、准确、规范化**的志愿填报辅助。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 场景1：在Hermes对话中使用（推荐）
|
||
|
||
```
|
||
/skill gaokao-college-advisor
|
||
"我是湖南考生，578分..."
|
||
|
||
# 生成方案后立即检查
|
||
/skill gaokao-spec-checker
|
||
"请检查这个方案..."
|
||
```
|
||
|
||
### 场景2：命令行使用
|
||
|
||
```bash
|
||
# 1. 信息收集（3分钟问卷）
|
||
python3 ~/.local/bin/gaokao-quick-3min.py
|
||
|
||
# 2. 生成可视化报告
|
||
python3 ~/.local/bin/gaokao-visual-report-v2.py
|
||
|
||
# 3. 规范检查
|
||
python3 ~/.local/bin/gaokao-checker plan.txt
|
||
|
||
# 4. 完整流程演示
|
||
bash ~/.local/bin/gaokao-demo-full-workflow.sh
|
||
```
|
||
|
||
### 场景3：项目开发
|
||
|
||
```bash
|
||
# 进入项目
|
||
cd /home/long/projects/gaokao-volunteer-system
|
||
|
||
# 提交变更
|
||
git add .
|
||
git commit -m "feat: 新增功能"
|
||
|
||
# 同步到Hermes
|
||
cp skills/gaokao-spec-checker/scripts/spec_checker_v2.py \
|
||
~/.hermes/skills/gaokao-spec-checker/scripts/
|
||
```
|
||
|
||
## 🏗️ 架构
|
||
|
||
### 分层架构
|
||
|
||
```
|
||
┌─────────────────┐
|
||
│ 用户对话层 │ Hermes Skills
|
||
├─────────────────┤
|
||
│ 业务逻辑层 │ Python脚本
|
||
├─────────────────┤
|
||
│ 数据规则层 │ rules/ 目录
|
||
├─────────────────┤
|
||
│ 持久化层 │ docs/, data/
|
||
└─────────────────┘
|
||
```
|
||
|
||
### 核心组件
|
||
|
||
1. **gaokao-college-advisor** - 方案生成
|
||
2. **gaokao-spec-checker** - 规范检查
|
||
3. **zhangxuefeng-skillset** - 风格化推荐
|
||
4. **独立脚本** - 数据处理、可视化
|
||
5. **规则库** - 省份、年度、错误规则
|
||
|
||
## 📝 开发规范
|
||
|
||
### 代码规范
|
||
|
||
- Python 3.10+（使用类型提示）
|
||
- 遵循 PEP 8
|
||
- 函数和类必须有 docstring
|
||
- 关键逻辑添加中文注释
|
||
|
||
### 命名规范
|
||
|
||
- 目录：lowercase-hyphen
|
||
- 文件：lowercase_underscore 或 lowercase-hyphen
|
||
- 类：PascalCase
|
||
- 函数/变量：snake_case
|
||
|
||
### 提交规范
|
||
|
||
```
|
||
feat: 新功能
|
||
fix: 修复bug
|
||
docs: 文档更新
|
||
style: 格式调整
|
||
refactor: 重构
|
||
test: 测试
|
||
chore: 构建/工具变更
|
||
```
|
||
|
||
## 🧪 测试
|
||
|
||
### 手动测试
|
||
|
||
```bash
|
||
# 1. 测试湖南方案
|
||
python3 ~/.local/bin/gaokao-checker tests/cases/hunan-578.md
|
||
|
||
# 2. 测试浙江方案
|
||
python3 ~/.local/bin/gaokao-checker tests/cases/zhejiang-630.md
|
||
```
|
||
|
||
### 测试用例位置
|
||
|
||
- `tests/cases/` - 各省测试用例
|
||
- 每省至少1个标准用例
|
||
- 至少1个错误用例（用于验证检测能力）
|
||
|
||
## 📦 部署
|
||
|
||
### 同步到Hermes
|
||
|
||
```bash
|
||
# Skills
|
||
cp -r skills/gaokao-college-advisor/ ~/.hermes/skills/
|
||
cp -r skills/gaokao-spec-checker/ ~/.hermes/skills/
|
||
cp -r skills/zhangxuefeng-skillset/ ~/.hermes/skills/
|
||
|
||
# 脚本
|
||
cp scripts/gaokao-checker ~/.local/bin/
|
||
cp scripts/gaokao-visual-report-v2.py ~/.local/bin/
|
||
```
|
||
|
||
### 部署检查清单
|
||
|
||
- [ ] 所有技能可用（`/skill`命令加载）
|
||
- [ ] 脚本可执行（`chmod +x`）
|
||
- [ ] 路径正确（`which gaokao-checker`）
|
||
- [ ] 测试通过
|
||
- [ ] 文档更新
|
||
|
||
## 🐛 调试
|
||
|
||
### 常见问题
|
||
|
||
1. **Skill不加载** → 检查 SKILL.md frontmatter
|
||
2. **脚本不执行** → 检查 `chmod +x`
|
||
3. **检查器报错** → 检查省份是否在 PROVINCE_RULES
|
||
|
||
### 调试工具
|
||
|
||
```python
|
||
# 启用详细日志
|
||
import logging
|
||
logging.basicConfig(level=logging.DEBUG)
|
||
```
|
||
|
||
## 📚 参考资料
|
||
|
||
- 阳光高考：https://gaokao.chsi.com.cn/
|
||
- 湖南省教育考试院：http://jyt.hunan.gov.cn/
|
||
- 各省2026年高考政策文件
|
||
|
||
## 🤝 贡献指南
|
||
|
||
### 贡献方式
|
||
|
||
1. 发现错误 → 添加到 `rules/errors/ERRORS.md`
|
||
2. 优化方案 → 更新对应Skill
|
||
3. 添加省份 → 扩展 `PROVINCE_RULES`
|
||
4. 真实案例 → 记录到 `docs/case-studies/`
|
||
|
||
### 贡献流程
|
||
|
||
1. 修改文件
|
||
2. 运行测试
|
||
3. 提交（`git commit`）
|
||
4. 同步到Hermes
|
||
5. 记录到 `CHANGELOG.md`
|
||
|
||
---
|
||
|
||
**版本**：v2.0
|
||
**最后更新**：2026-06-11
|