> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge) · [上游 README](https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
用 AI 将代码库变成易懂教程
> *你是否曾盯着别人写的新代码库，完全不知从何下手？本教程将教你如何构建一个 AI 智能体（agent），用于分析 GitHub 仓库，并生成面向初学者的教程，清晰讲解代码究竟是如何工作的。*
这是 [Pocket Flow](https://github.com/The-Pocket/PocketFlow), 一个仅 100 行的 LLM 框架）的教程项目。它会爬取 GitHub 仓库，并从代码中构建知识库。它分析整个代码库以识别核心抽象（abstraction）及其交互方式，并将复杂代码转化为配有清晰可视化的、面向初学者的教程。
- 想了解更多？请查看图书 [《Crack Any Codebase with AI》](https://www.manning.com/books/crack-any-codebase-with-ai)
- 想了解更多？请查看 [YouTube 开发教程](https://youtu.be/AFY67zOpbSo)
- 想了解更多？请查看 [Substack 帖子教程](https://zacharyhuang.substack.com/p/ai-codebase-knowledge-builder-full)
**🔸 🎉 登上 Hacker News 首页**（2025 年 4 月），获得超过 900 个赞：[讨论 »](https://news.ycombinator.com/item?id=43739456)
## ⭐ 热门 GitHub 仓库的示例结果！
🤯 这些教程全部是通过爬取 GitHub 仓库，**完全由 AI 生成**的！
- [AutoGen Core](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/AutoGen%20Core) - 构建能像同事一样交流、思考并共同解决问题的 AI 团队！
- [Browser Use](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Browser%20Use) - 让 AI 替你浏览网页，像数字助理一样点击按钮、填写表单！
- [Celery](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Celery) - 用后台任务为你的应用提速，让你在睡觉时任务照常运行！
- [Click](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Click) - 只需一个装饰器，就能把 Python 函数变成精致的命令行工具！
- [Codex](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Codex) - 用这个 AI 终端向导，把自然语言变成可运行代码！
- [Crawl4AI](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Crawl4AI) - 训练你的 AI，从任意网站精确提取真正重要的内容！
- [CrewAI](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/CrewAI) - 组建一支 AI 专家梦之队，攻克看似不可能的问题！
- [DSPy](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/DSPy) - 像搭乐高一样构建 LLM 应用，还能自我优化！
- [FastAPI](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/FastAPI) - 闪电般创建 API，并自动生成客户会喜欢的文档！
- [Flask](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Flask) - 用极简代码打造 Web 应用，从原型到生产都能扩展！
- [Google A2A](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Google%20A2A) - 让 AI 智能体跨平台协作的通用语言！
- [LangGraph](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/LangGraph) - 把 AI 智能体设计成流程图，让每一步都记住之前发生了什么！
- [LevelDB](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/LevelDB) - 用 Google 驱动区块链的高速引擎，以惊人速度存储数据！
- [MCP Python SDK](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/MCP%20Python%20SDK) - 通过优雅协议构建强大应用，无需纠结底层细节！
- [NumPy Core](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/NumPy%20Core) - 掌握数据科学背后的引擎，让 Python 快如 C！
- [OpenManus](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/OpenManus) - 构建拥有数字大脑、能像人类一样思考、学习并使用工具的 AI 智能体！
- [PocketFlow](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/PocketFlow) - 100 行 LLM 框架。让智能体构建智能体！
- [Pydantic Core](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Pydantic%20Core) - 仅凭 Python 类型提示，以火箭般的速度校验数据！
- [Requests](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Requests) - 用 Python 与互联网对话，代码简单到像作弊一样！
- [SmolaAgents](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/SmolaAgents) - 构建小巧却实力超群的 AI 智能体！
- 在 [Discussions](https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge/discussions)! 中展示你由 AI 生成的教程
## 🚀 快速开始
1. 克隆本仓库
```bash
git clone https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge
```
3. 安装依赖：
```bash
pip install -r requirements.txt
```
4. 在 [`utils/call_llm.py`](./utils/call_llm.py) 中配置 LLM 凭据。你可以将值写入 `.env` 文件。默认情况下，可通过设置 `GEMINI_API_KEY` 环境变量，使用该客户端配合 AI Studio 密钥调用 Gemini Pro 2.5。若想使用其他 LLM，可设置 `LLM_PROVIDER` 环境变量（例如 `XAI`），然后配置模型、url 和 API 密钥（例如 `XAI_MODEL`、`XAI_URL`、`XAI_API_KEY`）。若使用 Ollama，url 为 `http://localhost:11434/`，API 密钥可省略。
你也可以使用自己的模型。我们强烈推荐具备思考能力的最新模型（Claude 3.7 with thinking、O1）。运行以下命令可验证配置是否正确：
```bash
python utils/call_llm.py
```
5. 运行主脚本生成完整代码库教程：
```bash
# Analyze a GitHub repository
python main.py --repo https://github.com/username/repo --include "*.py" "*.js" --exclude "tests/*" --max-size 50000
# Or, analyze a local directory
python main.py --dir /path/to/your/codebase --include "*.py" --exclude "*test*"
# Or, generate a tutorial in Chinese
python main.py --repo https://github.com/username/repo --language "Chinese"
```
- `--repo` 或 `--dir` - 指定 GitHub 仓库 URL 或本地目录路径（必填，二者互斥）
- `-n, --name` - 项目名称（可选，省略时从 URL/目录推导）
- `-t, --token` - GitHub 令牌（或设置 GITHUB_TOKEN 环境变量）
- `-o, --output` - 输出目录（默认：./output）
- `-i, --include` - 要包含的文件（例如 "`*.py`" "`*.js`"）
- `-e, --exclude` - 要排除的文件（例如 "`tests/*`" "`docs/*`"）
- `-s, --max-size` - 最大文件大小（字节，默认：100KB）
- `--language` - 生成教程的语言（默认："english"）
- `--max-abstractions` - 要识别的最大抽象数量（默认：10）
- `--no-cache` - 禁用 LLM 响应缓存（默认：启用缓存）
应用会爬取仓库、分析代码库结构、按指定语言生成教程内容，并保存到指定目录（默认：./output）。
🐳 使用 Docker 运行
要在 Docker 容器中运行本项目，需要将 API 密钥作为环境变量传入。
1. 构建 Docker 镜像
```bash
docker build -t pocketflow-app .
```
2. 运行容器
你需要提供 `GEMINI_API_KEY`，LLM 才能正常工作。若要分析私有 GitHub 仓库或避免速率限制，还需提供 `GITHUB_TOKEN`。
将本地目录挂载到容器内的 `/app/output`，即可在主机上访问生成的教程。
**分析公开 GitHub 仓库的示例：**
```bash
docker run -it --rm \
-e GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE" \
-v "$(pwd)/output_tutorials":/app/output \
pocketflow-app --repo https://github.com/username/repo
```
**分析本地目录的示例：**
```bash
docker run -it --rm \
-e GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE" \
-v "/path/to/your/local_codebase":/app/code_to_analyze \
-v "$(pwd)/output_tutorials":/app/output \
pocketflow-app --dir /app/code_to_analyze
```
## 💡 开发教程
- 我使用 [**Agentic Coding**](https://zacharyhuang.substack.com/p/agentic-coding-the-most-fun-way-to), 最快的开发范式构建本项目，人类只需 [设计](docs/design.md)，由智能体（Agents）[编码](flow.py)。
- 秘诀是 [Pocket Flow](https://github.com/The-Pocket/PocketFlow), 一个仅 100 行的 LLM 框架，让智能体（例如 Cursor AI）为你构建
- 请查看分步 YouTube 开发教程：
