# GitHub 项目学习方法论 SOP

## 适用场景
从陌生 GitHub 项目快速建立理解，定位核心逻辑，完成功能扩展或问题修复。

## 核心原则
1. **结构优先**：先看目录树和README，建立全局认知
2. **入口追踪**：从启动文件/API入口反向追溯核心流程
3. **实测验证**：边读边跑，用实际执行验证理解
4. **增量记忆**：关键发现立即记录，避免重复探索

## 标准流程

### 1. 快速扫描（5-10分钟）
```python
# 查看项目结构
tree /F  # Windows
ls -R    # Linux

# 关键文件优先级
1. README.md / docs/ - 了解项目定位和快速开始
2. requirements.txt / pyproject.toml - 技术栈和依赖
3. main.py / app.py / __main__.py - 程序入口
4. tests/ - 理解预期行为
```

**输出**：项目定位、技术栈、核心模块清单

### 2. 入口追踪（15-30分钟）
```python
# 从入口文件开始
# 1. 找到启动命令（README或setup.py）
# 2. 定位主函数/路由定义
# 3. 追踪关键类的初始化和调用链

# 示例：FastAPI项目
# app.py → @app.post("/api/xxx") → service.method() → core_logic()
```

**技巧**：
- 用IDE的"查找引用"功能追踪函数调用
- 关注类的`__init__`和核心方法
- 记录数据流转路径（输入→处理→输出）

**输出**：核心流程图、关键类/函数清单

### 3. 实测验证（20-40分钟）
```python
# 最小可运行示例
# 1. 按README安装依赖
# 2. 运行smoke test或demo脚本
# 3. 修改参数观察行为变化
# 4. 添加print/logger追踪执行路径
```

**避坑**：
- 环境问题优先查issue和discussions
- 依赖版本冲突先看requirements.txt的固定版本
- 配置文件缺失先看`.example`或`config.template`

**输出**：可运行的最小示例、环境配置清单

### 4. 问题定位（按需）
```python
# 遇到bug或需要扩展功能时
# 1. 从错误栈/日志定位出错文件和行号
# 2. 向上追溯调用链，找到触发条件
# 3. 检查相关测试用例，理解预期行为
# 4. 小范围修改+测试验证
```

**技巧**：
- 用`git blame`查看代码历史和commit message
- 搜索issue看是否有类似问题
- 对比相似功能的实现代码

### 5. 知识沉淀（任务结束时）
按L0规范分层记录：
- **L2（global_mem.txt）**：项目路径、核心模块、技术栈、关键配置
- **L3（专项SOP）**：特定任务的避坑指南、扩展方法
- **避免记录**：通用Python知识、可快速查到的API文档

## 实战案例：AIVIDEO项目

### 结构扫描
```
aivideo/
├── src/aivideo/
│   ├── webapp_new.py      # FastAPI主应用
│   ├── highlight_detector.py  # 精彩片段检测
│   ├── progress_manager.py    # WebSocket进度推送
│   └── three_mode_pipeline.py # 三模式生成
├── tests/
└── scripts/
```

### 入口追踪
```python
# webapp_new.py
@app.post("/api/upload")  # 上传入口
→ analyze_video_task()    # 异步分析任务
  → detector.detect_highlights()  # 场景检测
  → progress_callback()           # 进度推送

@app.websocket("/ws/progress/{job_id}")  # WebSocket端点
→ progress_manager.connect()
```

### 关键发现
1. **WebSocket参数顺序**：`connect(websocket, job_id)`不是`connect(job_id, websocket)`
2. **detect_highlights参数**：用`duration_tolerance`不是`max_clip_duration`
3. **前端交互**：选择文件→显示按钮→点击后上传（避免自动上传）

### 沉淀位置
- L2: `global_mem.txt` § AIVIDEO_MVP_VERIFIED
- L3: 本SOP作为方法论参考

## 常见陷阱
1. ❌ 只看代码不运行 → 理解偏差大
2. ❌ 深入细节忘记全局 → 迷失在实现中
3. ❌ 不记录关键发现 → 重复踩坑
4. ❌ 记录过于详细 → 记忆膨胀难维护

## 检查清单
- [ ] 能用一句话描述项目作用
- [ ] 知道如何启动和测试
- [ ] 画出核心流程的数据流图
- [ ] 记录了关键配置和避坑点
- [ ] 能独立完成一个小功能扩展