github-code-interpreter

# GitHub 源码解读助手

## 设计模式

本 skill 主要采用：
- **Pipeline**：按“定位仓库 → 建目录 → 阅读分析 → 生成两份文档 → 交付 → 如有需要再复查”的顺序执行
- **Generator**：稳定产出源码解读与快速上手两份文档
- **Inversion（轻度）**：开始前先确认分析范围，复查前再次征求用户同意

## Gotchas

- 不要把“只想克隆仓库”误判成“源码解读”
- 不要假装已经全读完大型仓库；必须说明本次聚焦模块
- 不要默认安排复查；是否复查必须先征求用户确认
- 不要凭空编造运行命令、依赖关系、架构细节
- 如果当前渠道支持发文件，应优先发文件，不要只丢路径

## 适用边界

使用本 skill：
- 用户提供 GitHub 仓库链接，并明确要“解读源码 / 分析架构 / 理解原理 / 生成学习报告 / 快速上手”
- 用户想把一个开源项目梳理成可读的中文文档

不要使用本 skill：
- 用户只想克隆仓库
- 用户只想要一句简介或推荐语
- 用户要解读论文或普通技术文章

## 核心交付

在合适的 `~/Documents/working` 子目录下创建项目分析目录，并产出两份文档：
- `<repo_name>_源码解读.md`
- `<repo_name>_快速上手.md`

可额外产出：
- `structure.txt`
- `metadata.json`

报告结构参考 `references/report-outline.md`。

## 工作流

### 0. 先确认分析范围（必须先做）

开始前先向用户确认或声明本次分析范围，至少覆盖：

- 是否只做架构解读，还是同时生成快速上手文档
- 是否聚焦某个模块，还是做整体源码导读
- 最终交付以本地文档为主，而不是在对话中直接长篇展开

如果用户已经明确说了“解读源码/分析架构/生成报告”，可直接进入执行，并在回复里顺手说明本次范围。

### 1. 确定工作目录

按以下优先级选择输出目录：
1. 用户明确指定的目录
2. 当前上下文里已存在且明显合适的 `~/Documents/working` 子目录
3. 默认使用 `~/Documents/working/github-analysis/<repo_name>`

不要跳出 `~/Documents/working` 体系。

### 2. 定位仓库

优先在 `~/Documents/coding/github` 中查找目标仓库。

- 已存在：直接使用
- 不存在：克隆到 `~/Documents/coding/github/<repo_name>`

### 3. 初始化分析目录

需要快速完成仓库定位、结构导出、元数据生成时，运行：

```bash
python3 scripts/bootstrap_github_analysis.py <github_url> ~/Documents/working
```

如果脚本不可用，就手动完成以下事情：
- 创建分析目录
- 导出目录结构
- 记录仓库路径、分支、最后提交时间等基础信息

### 4. 阅读与分析

至少覆盖这些内容：
- `README.md` 和核心文档
- 依赖或构建文件，如 `package.json`、`pyproject.toml`、`Cargo.toml`
- 主要源码目录
- 测试、示例、文档目录

大型仓库不要假装“全读完了”。要明确说明本次聚焦的模块或子系统。

### 5. 生成两份文档

#### 源码解读文档
至少包括：
- 项目是做什么的
- 适用场景
- 优点与局限
- 整体架构与关键模块
- 核心原理 / 关键数据流 / 关键算法
- 设计思想与值得借鉴的点
- 必要术语解释
- 按需调用 [`mermaid`](../mermaid/SKILL.md) skill 生成图

#### 快速上手文档
至少包括：
- 环境要求
- 安装步骤
- 配置说明
- 最小可运行示例
- 常见问题
- 下一步建议先读哪些源码

### 6. 交付要求

完成初稿后，先把两份文档路径明确告诉用户，再补充：
- 仓库本地路径
- 输出目录路径
- 本次分析范围
- 还没验证的部分

如果当前渠道支持发文件，就直接发送文件；如果不支持，就至少给出可点击路径。

### 7. 复查原则

默认不自动复查。

如果你判断这份分析值得继续完善，只能先问用户要不要复查；用户明确同意后，才可以安排约 1 小时后的复查。
如果当前环境不方便安排，就不要假装已经安排成功，直接告诉用户即可。

复查时遵循增量更新：
- 先读现有两份文档
- 再看仓库是否有更新
- 补充遗漏架构细节、使用场景、设计思想
- 必要时验证快速上手文档
- 在文档末尾追加复查记录

## 输出要求

汇报时至少包含：
- 仓库名与本地路径
- 输出目录
- 两份文档路径
- 本次聚焦模块
- 是否建议复查，以及如需复查必须先征求用户确认

## 注意事项

- 大型仓库优先聚焦核心模块，不要泛泛而谈
- 先看文档，再读源码，避免误解设计意图
- 快速上手文档尽量基于真实命令，不要凭空猜
- 不要把“当前渠道的文件发送格式”写死成某个平台专用语法