# GitHub实战大本营 - 项目开发报告

**日期**: 2026年7月22日  
**版本**: v1.0.0  
**状态**: 开发完成，待部署

---

## 一、项目概述

GitHub实战大本营是一个帮助新手快速上手GitHub的学习平台。用户可以通过新手村学习基本操作，在大世界自由探索项目。

### 核心价值
- **零门槛入门**: 无需写代码，只需点击、选择、确认
- **AI导师陪伴**: 全程AI助手指导，手把手完成项目
- **即时成就感**: 30分钟内完成第一个项目并部署上线

---

## 二、功能模块

### 2.1 新手村 (Village)

| 场景 | 描述 | 难度 | 状态 |
|-----|------|-----|------|
| 个人主页 | 创建专属名片页 | 入门 | ✅ 完成 |
| 倒计时 | 纪念日/考试倒计时 | 入门 | ✅ 完成 |
| 待办清单 | 日常任务管理工具 | 入门 | ✅ 完成 |
| 番茄钟 | 提升专注力计时器 | 入门 | ✅ 完成 |

每个场景包含4个步骤：Fork项目 → 个性化修改 → 开启Pages → 访问上线

### 2.2 大世界 (World)

**核心特性**: 智能模式区分
- **模板模式**: 用户想法匹配到现有模板时，自动推荐项目
- **创造模式**: 用户想法为创新创意时，进入AI军师对话模式

**技术实现**:
- 多维度评分算法（标签匹配、名称匹配、描述匹配）
- 精确匹配数 + 分数阈值控制推荐精度
- 置信度计算，支持后续优化

---

## 三、技术架构

### 3.1 后端技术栈

| 技术 | 版本 | 用途 |
|-----|------|-----|
| FastAPI | 0.115.0 | Web框架 |
| SQLAlchemy | 2.0.35 | ORM |
| SQLite | - | 数据库 |
| Uvicorn | 0.31.0 | 服务器 |

### 3.2 前端技术栈

| 技术 | 用途 |
|-----|------|
| HTML5 | 页面结构 |
| CSS3 | 样式设计（GitHub风格） |
| JavaScript | 交互逻辑 |

### 3.3 项目结构

```
github-camp/
├── backend/
│   ├── app/
│   │   ├── api/          # 路由层
│   │   ├── models/       # 数据模型
│   │   ├── services/     # 业务逻辑
│   │   ├── schemas/      # 数据校验
│   │   ├── dependencies/ # 依赖注入
│   │   └── utils/        # 工具函数
│   └── data/             # SQLite数据库
└── frontend/
    ├── index.html        # 主页面
    ├── css/style.css     # 样式文件
    └── js/app.js         # 交互逻辑
```

---

## 四、关键技术实现

### 4.1 智能模板匹配算法

**文件**: [ai_service.py](file:///workspace/github-camp/backend/app/services/ai_service.py#L341-L393)

**算法流程**:
1. 将用户想法与项目标签、名称、描述进行多维度匹配
2. 每个匹配项根据长度和类型给予不同权重（标签3分，名称5分，描述2分）
3. 通过精确匹配数(exact_matches)和分数(score)组合判断是否匹配
4. 返回匹配模式(template/create)和置信度

**匹配规则**:
- `(exact_matches >= 2 AND score >= 3)` OR `(exact_matches >= 1 AND score >= 3)`

**测试验证**:

| 想法 | 模式 | 置信度 |
|-----|------|-------|
| "我想做一个个人主页" | template | 45% |
| "我想做一个待办清单" | template | 60% |
| "我想做一个博客" | template | 45% |
| "我想做一个全球热浪下的空调安装游戏" | create | 0% |
| "我想做一个区块链去中心化交易所" | create | 0% |

### 4.2 想法匹配API

**文件**: [project.py](file:///workspace/github-camp/backend/app/api/project.py#L81-L117)

**接口**: `POST /api/projects/match`

**请求体**:
```json
{
    "idea": "我想做一个个人主页"
}
```

**响应体**:
```json
{
    "code": 0,
    "data": {
        "mode": "template",
        "confidence": 45,
        "matched_projects": [...],
        "total_scored": 2
    }
}
```

### 4.3 前端智能路由

**文件**: [app.js](file:///workspace/github-camp/frontend/js/app.js#L810-L860)

**流程**:
1. 用户输入想法 → 调用匹配API
2. 根据返回的mode自动切换：
   - `template`: 展示推荐模板列表
   - `create`: 进入AI军师对话模式

---

## 五、模板库

当前模板库包含20个项目，涵盖多个类别：

| 类别 | 项目数量 | 示例 |
|-----|---------|------|
| personal-site | 5 | 个人主页、作品集、落地页 |
| tool | 9 | 待办清单、番茄钟、天气看板 |
| content | 2 | 博客、简历生成器 |
| game | 3 | 2048、贪吃蛇、打砖块 |

---

## 六、用户体验优化

### 6.1 界面设计
- 采用GitHub风格设计，简洁干净
- 响应式布局，支持移动端
- 清晰的视觉层级和操作指引

### 6.2 交互流程
- 想法输入 → AI分析 → 智能路由 → 结果展示
- 无需手动选择模式，AI自动判断
- 示例标签快捷选择，降低输入门槛

---

## 七、待办事项

- [ ] 接入大模型API，增强创造模式对话能力
- [ ] 添加项目访问量统计（北极星指标）
- [ ] 优化模板匹配算法，提升匹配精度
- [ ] 增加更多模板项目
- [ ] 部署上线

---

## 八、团队

- **产品**: 老焦
- **开发**: AI助手
- **设计**: GitHub风格

---

**报告结束** ✅