gaokao-volunteer-system/docs/ARCHITECTURE.md

架构设计

🏛️ 整体架构

┌─────────────────────────────────────────────────────────────┐
│                       用户交互层                              │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │  Hermes对话      │  │  命令行          │                  │
│  └────────┬────────┘  └────────┬────────┘                  │
└───────────┼─────────────────────┼─────────────────────────────┘
            │                     │
┌───────────▼─────────────────────▼─────────────────────────────┐
│                       业务逻辑层                               │
│  ┌──────────────────┐  ┌──────────────────┐                  │
│  │ 3个Hermes Skills │  │ 独立Python脚本   │                  │
│  │ - advisor        │  │ - visual-report  │                  │
│  │ - spec-checker   │  │ - quick-3min     │                  │
│  │ - zhangxuefeng   │  │ - collect-info   │                  │
│  └────────┬─────────┘  └────────┬─────────┘                  │
└───────────┼─────────────────────┼─────────────────────────────┘
            │                     │
┌───────────▼─────────────────────▼─────────────────────────────┐
│                       规则与数据层                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │ provinces/   │  │ errors/      │  │ templates/   │        │
│  │ 省份规则     │  │ 错误模式     │  │ 报告模板     │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
└───────────────────────────────────────────────────────────────┘
            │
┌───────────▼─────────────────────────────────────────────────────┐
│                       持久化层                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ docs/        │  │ data/        │  │ CHANGELOG.md │          │
│  │ 文档案例     │  │ 示例数据     │  │ 变更历史     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘

🎯 设计原则

1. 关注点分离（Separation of Concerns）

• Skills：负责对话式交互
• 脚本：负责批处理和数据处理
• 规则：负责业务规则集中管理
• 数据：负责持久化

2. 单点真相（Single Source of Truth）

• 规则统一在 rules/
• 文档统一在 docs/
• 示例统一在 data/

3. 可扩展性

• 省份可扩展（添加新省份只需修改 PROVINCE_RULES）
• 错误模式可扩展（添加新错误到 ERRORS.md）
• 案例可扩展（添加新案例到 case-studies/）

4. 渐进增强

• 基础对话能力
• 增强：可视化报告
• 高级：自动检查
• 专家：数据驱动决策

🔄 数据流

场景A：对话生成方案

用户输入 → Skill加载 → 收集信息
    ↓
霍兰德评估 → 个性化匹配 → 院校推荐
    ↓
生成方案 → 输出
    ↓
（可选）调用 spec-checker 检查

场景B：检查现有方案

用户方案 → spec-checker加载
    ↓
省份识别 → 加载对应规则
    ↓
规则匹配 → 发现问题
    ↓
分类输出 → 修正建议

场景C：生成可视化报告

考生数据 → 模板渲染
    ↓
HTML生成 → PDF转换
    ↓
Markdown输出

🔌 扩展点

添加新省份

# 在 spec_checker_v2.py 中
PROVINCE_RULES["新省份"] = {
    "mode": "院校专业组",
    "max_volunteers": 45,
    "max_majors_per_group": 6,
    "has_adjustment": True,
    "adjustment_scope": "组内专业",
    "retrieval_rule": "...",
    "collection_count": 2,
    "subject_mode": "3+1+2",
    "official_url": "...",
    "exam_subject_total": 750,
}

添加新错误模式

### E###：<错误名称>

- **症状**：<方案表现>
- **正确**：<应该是>
- **场景**：<何时出现>
- **修复**：<如何修正>
- **首次发现**：<日期>

添加新Skill

skills/
├── my-new-skill/
│   ├── SKILL.md
│   ├── references/
│   ├── templates/
│   └── scripts/

📊 技术栈

层	技术
Skill	Markdown + YAML frontmatter
脚本	Python 3.10+
数据	JSON / YAML / Markdown
版本	Git
文档	Markdown

🎓 学习路径

新手（1天）

1. 阅读 README.md
2. 了解3个Skill的作用
3. 体验1次完整对话流程

进阶（3天）

1. 熟悉 rules/ 目录结构
2. 学习 spec-checker 的工作原理
3. 修改一份现有方案

专家（1周）

1. 添加一个新省份规则
2. 添加一种新错误模式
3. 优化一个Skill的逻辑

---

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