the-pocket--pocketflow-tutorial-codebase-knowledge/README.md

<!-- WEHUB_ZH_README -->
> [!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 文件为准。

<h1 align="center">用 AI 将代码库变成易懂教程</h1>

![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
 <a href="https://discord.gg/hUHHE9Sa6T">
    <img src="https://img.shields.io/discord/1346833819172601907?logo=discord&style=flat">
</a>
> *你是否曾盯着别人写的新代码库，完全不知从何下手？本教程将教你如何构建一个 AI 智能体（agent），用于分析 GitHub 仓库，并生成面向初学者的教程，清晰讲解代码究竟是如何工作的。*

<p align="center">
  <img
    src="./assets/banner.png" width="800"
  />
</p>

这是 [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)

&nbsp;&nbsp;**🔸 🎉 登上 Hacker News 首页**（2025 年 4 月），获得超过 900 个赞：[讨论 »](https://news.ycombinator.com/item?id=43739456)



## ⭐ 热门 GitHub 仓库的示例结果！

<p align="center">
    <img
      src="./assets/example.png" width="600"
    />
</p>

🤯 这些教程全部是通过爬取 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）。


<details>
 
<summary> 🐳 <b>使用 Docker 运行</b> </summary>

要在 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
```
</details>

## 💡 开发教程

- 我使用 [**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 开发教程：

<br>
<div align="center">
  <a href="https://youtu.be/AFY67zOpbSo" target="_blank">
    <img src="./assets/youtube_thumbnail.png" width="500" alt="Pocket Flow Codebase Tutorial" style="cursor: pointer;">
  </a>
</div>
<br>