SuperAPI AI 工具集

repo-walkthrough

编程与开发

查看项目

更新于 10-22 05:36

技能介绍

用途

repo-walkthrough 用于把代码仓库快速转化为可浏览的架构讲解材料。目标可以是本地目录、公开 GitHub 仓库、私有 GitHub 仓库,或一段 git diff 变更范围(如两次提交或两个分支之间),帮助理解仓库的入口、执行引擎、核心领域模块、数据与事件流以及工具和存储适配层。

输出模式

  • 网站模式(--mode website):生成独立的交互式架构查看器(index.html 与 data.js),用户可探索分层图、点击文件或连接查看其角色与代码,并播放逐步语音讲解。若提供 GEMINI_API_KEY,会合成 Gemini TTS 音频(audio/step-*.wav);否则可用 --no-tts 回退到浏览器语音合成。
  • 网站 + 视频模式(--mode video):先构建交互网站,再用 Gemini TTS 合成讲解,并渲染带动画的分步讲解 MP4(<slug>-walkthrough.mp4),在讲解时逐步切换层并高亮相关文件。

环境要求

可用 node ~/projects/repo-walkthrough/scripts/build_walkthrough.mjs --check-prereqs 检查环境。

  • Python 3:两种模式均需要,用于运行 fetch_repo.py 分析本地或 GitHub 仓库。
  • Node.js 20+:两种模式均需要,运行构建、音频和视频脚本。
  • GEMINI_API_KEY:网站模式可选(--no-tts 时用浏览器语音);视频模式必需,用于生成 Gemini TTS 讲解并对齐语音提示。
  • ffmpeg:视频模式必需,用于把渲染帧和音频编码为 MP4。
  • Playwright + Chrome:网站模式可选,视频模式必需,用于在无头 Chrome 中渲染讲解帧。
  • gh CLI:仅私有 GitHub 仓库需要(--mode gh),两种模式可选。

使用方式

  1. 分析目标仓库或 diff 范围。使用 fetch_repo.py 针对本地路径、owner/repo、GitHub URL(含 /tree/<branch>/<subpath>),或通过 --diff <rev-range> 分析 git diff。示例: python3 ~/projects/repo-walkthrough/scripts/fetch_repo.py <owner/repo-or-local-path> --json /tmp/repo-analysis.json python3 ~/projects/repo-walkthrough/scripts/fetch_repo.py <local-repo-path> --diff <base-rev>..<head-rev> --json /tmp/diff-analysis.json 然后阅读分析 JSON 以理解代码库结构。
  2. 编写 data.js。默认采用 5 个水平层、12–18 个节点、6–8 个讲解步骤(层数可在 3–6 间调整)。默认层:入口(y=26)、引擎(y=150)、核心抽象/代理(y=274)、流程(y=398)、能力/工具与存储(y=522),必要时第 6 层基础设施(y=646)。节点 x 坐标从 200 起,每行最多 4 个,左侧 x 14..190 留给分区标题。步骤讲解侧重输入、转换逻辑及输出如何被下游使用,而非复述代码语法。语音提示按讲解中文件出现的时间顺序排列,并锚定到实际说出的文件名,以便提示及时切换高亮。
  3. 验证并构建。网站模式: node ~/projects/repo-walkthrough/scripts/build_walkthrough.mjs --data <out-dir>/data.js --out-dir <out-dir> --mode website --open 网站 + 视频模式: node ~/projects/repo-walkthrough/scripts/build_walkthrough.mjs --data <out-dir>/data.js --out-dir <out-dir> --mode video --open

适用场景

适合需要快速理解陌生代码库、向他人讲解架构、演示 git 变更影响、制作代码走查视频,以及为文档或评审准备可视化材料的场景。

限制

视频模式依赖 GEMINI_API_KEY、ffmpeg 与 Playwright + Chrome;私有仓库需要 gh CLI 且有相应权限。生成质量取决于 data.js 的节点与步骤编排。其他收费、平台兼容细节暂未提供。