GitHub 源码解读助手

适用边界

使用本 skill：

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

不要使用本 skill：

• 用户只想克隆仓库
• 用户只想要一句简介或推荐语
• 用户要解读论文或普通技术文章

核心交付

在合适的 ~/Documents/working 子目录下创建项目分析目录，并产出两份文档：

• <repo_name>_源码解读.md
• <repo_name>_快速上手.md

可额外产出：

• structure.txt
• metadata.json

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

工作流

1. 确定工作目录

按以下优先级选择输出目录：

1. 用户明确指定的目录
2. 当前上下文里已存在且明显合适的 ~/Documents/working 子目录
3. 默认使用 ~/Documents/working/github-analysis/<repo_name>

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

2. 定位仓库

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

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

3. 初始化分析目录

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

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

如果脚本不可用，就手动完成以下事情：

• 创建分析目录
• 导出目录结构
• 记录仓库路径、分支、最后提交时间等基础信息

4. 阅读与分析

至少覆盖这些内容：

• README.md 和核心文档
• 依赖或构建文件，如 package.json、pyproject.toml、Cargo.toml
• 主要源码目录
• 测试、示例、文档目录

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

5. 生成两份文档

源码解读文档

至少包括：

• 项目是做什么的
• 适用场景
• 优点与局限
• 整体架构与关键模块
• 核心原理 / 关键数据流 / 关键算法
• 设计思想与值得借鉴的点
• 必要术语解释
• Mermaid 图（按需添加）
• 对悟鸣的启发（仅在确实有价值时补充）

快速上手文档

至少包括：

• 环境要求
• 安装步骤
• 配置说明
• 最小可运行示例
• 常见问题
• 下一步建议先读哪些源码

6. 结合悟鸣背景补充启发

只有在“对悟鸣的启发”这一节确实值得写时，再按需读取：

• ~/Documents/coding/our/skills-wuming/skills/personal-secretary/references/人物/我/04_工作相关.md
• ~/Documents/coding/our/skills-wuming/skills/personal-secretary/references/人物/我/07_AI相关/07_AI探索.md
• ~/Documents/coding/our/skills-wuming/skills/personal-secretary/references/人物/我/05_创作分享/05_我的创作经验.md

不要为了凑内容硬写。

7. 交付要求

完成初稿后，先把两份文档路径明确告诉用户，再补充：

• 仓库本地路径
• 输出目录路径
• 本次分析范围
• 还没验证的部分

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

8. 复查原则

如果当前环境支持后续提醒或定时复查，可以安排约 1 小时后的复查。 如果不方便安排，就不要假装已经安排成功，直接告诉用户即可。

复查时遵循增量更新：

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

输出要求

汇报时至少包含：

• 仓库名与本地路径
• 输出目录
• 两份文档路径
• 本次聚焦模块
• 是否安排了后续复查

注意事项

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