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

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

用 AI 将代码库变成易懂教程

你是否曾盯着别人写的新代码库，完全不知从何下手？本教程将教你如何构建一个 AI 智能体（agent），用于分析 GitHub 仓库，并生成面向初学者的教程，清晰讲解代码究竟是如何工作的。

这是 Pocket Flow, 一个仅 100 行的 LLM 框架）的教程项目。它会爬取 GitHub 仓库，并从代码中构建知识库。它分析整个代码库以识别核心抽象（abstraction）及其交互方式，并将复杂代码转化为配有清晰可视化的、面向初学者的教程。

• 想了解更多？请查看图书 《Crack Any Codebase with AI》

• 想了解更多？请查看 YouTube 开发教程

• 想了解更多？请查看 Substack 帖子教程

  🔸 🎉 登上 Hacker News 首页（2025 年 4 月），获得超过 900 个赞：讨论 »

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

🤯 这些教程全部是通过爬取 GitHub 仓库，完全由 AI 生成的！

• AutoGen Core - 构建能像同事一样交流、思考并共同解决问题的 AI 团队！

• Browser Use - 让 AI 替你浏览网页，像数字助理一样点击按钮、填写表单！

• Celery - 用后台任务为你的应用提速，让你在睡觉时任务照常运行！

• Click - 只需一个装饰器，就能把 Python 函数变成精致的命令行工具！

• Codex - 用这个 AI 终端向导，把自然语言变成可运行代码！

• Crawl4AI - 训练你的 AI，从任意网站精确提取真正重要的内容！

• CrewAI - 组建一支 AI 专家梦之队，攻克看似不可能的问题！

• DSPy - 像搭乐高一样构建 LLM 应用，还能自我优化！

• FastAPI - 闪电般创建 API，并自动生成客户会喜欢的文档！

• Flask - 用极简代码打造 Web 应用，从原型到生产都能扩展！

• Google A2A - 让 AI 智能体跨平台协作的通用语言！

• LangGraph - 把 AI 智能体设计成流程图，让每一步都记住之前发生了什么！

• LevelDB - 用 Google 驱动区块链的高速引擎，以惊人速度存储数据！

• MCP Python SDK - 通过优雅协议构建强大应用，无需纠结底层细节！

• NumPy Core - 掌握数据科学背后的引擎，让 Python 快如 C！

• OpenManus - 构建拥有数字大脑、能像人类一样思考、学习并使用工具的 AI 智能体！

• PocketFlow - 100 行 LLM 框架。让智能体构建智能体！

• Pydantic Core - 仅凭 Python 类型提示，以火箭般的速度校验数据！

• Requests - 用 Python 与互联网对话，代码简单到像作弊一样！

• SmolaAgents - 构建小巧却实力超群的 AI 智能体！

• 在 Discussions! 中展示你由 AI 生成的教程

🚀 快速开始

1. 克隆本仓库

   git clone https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge
   

2. 安装依赖：

   pip install -r requirements.txt
   

3. 在 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）。运行以下命令可验证配置是否正确：

   python utils/call_llm.py
   

4. 运行主脚本生成完整代码库教程：

   # 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 镜像

   docker build -t pocketflow-app .
   

2. 运行容器

   你需要提供 GEMINI_API_KEY，LLM 才能正常工作。若要分析私有 GitHub 仓库或避免速率限制，还需提供 GITHUB_TOKEN。

将本地目录挂载到容器内的 /app/output，即可在主机上访问生成的教程。

分析公开 GitHub 仓库的示例：

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

分析本地目录的示例：

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, 最快的开发范式构建本项目，人类只需 设计，由智能体（Agents）编码。

• 秘诀是 Pocket Flow, 一个仅 100 行的 LLM 框架，让智能体（例如 Cursor AI）为你构建

• 请查看分步 YouTube 开发教程：