GitHub 项目学习方法论 SOP

适用场景

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

核心原则

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

标准流程

1. 快速扫描（5-10分钟）

# 查看项目结构
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分钟）

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

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

技巧：

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

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

3. 实测验证（20-40分钟）

# 最小可运行示例
# 1. 按README安装依赖
# 2. 运行smoke test或demo脚本
# 3. 修改参数观察行为变化
# 4. 添加print/logger追踪执行路径

避坑：

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

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

4. 问题定位（按需）

# 遇到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/

入口追踪

# 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. ❌ 记录过于详细 → 记忆膨胀难维护

检查清单

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