181 lines
6.7 KiB
Markdown
181 lines
6.7 KiB
Markdown
|
# 架构设计
|
|||
|
|
|
|||
|
|
## 🏛️ 整体架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 用户交互层 │
|
|||
|
|
│ ┌─────────────────┐ ┌─────────────────┐ │
|
|||
|
|
│ │ 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输出
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🔌 扩展点
|
|||
|
|
|
|||
|
|
### 添加新省份
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 在 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,
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 添加新错误模式
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
### 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
|