docs: make Chinese README the default
This commit is contained in:
wehub-resource-sync
@@ -1,10 +1,16 @@
|
||||
<h1 align="center">Turns Codebase into Easy Tutorial with AI</h1>
|
||||
<!-- 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>
|
||||
|
||||
|
||||
<a href="https://discord.gg/hUHHE9Sa6T">
|
||||
<img src="https://img.shields.io/discord/1346833819172601907?logo=discord&style=flat">
|
||||
</a>
|
||||
> *Ever stared at a new codebase written by others feeling completely lost? This tutorial shows you how to build an AI agent that analyzes GitHub repositories and creates beginner-friendly tutorials explaining exactly how the code works.*
|
||||
> *你是否曾盯着别人写的新代码库，完全不知从何下手？本教程将教你如何构建一个 AI 智能体（agent），用于分析 GitHub 仓库，并生成面向初学者的教程，清晰讲解代码究竟是如何工作的。*
|
||||
|
||||
<p align="center">
|
||||
<img
|
||||
@@ -12,20 +18,20 @@
|
||||
/>
|
||||
</p>
|
||||
|
||||
This is a tutorial project of [Pocket Flow](https://github.com/The-Pocket/PocketFlow), a 100-line LLM framework. It crawls GitHub repositories and builds a knowledge base from the code. It analyzes entire codebases to identify core abstractions and how they interact, and transforms complex code into beginner-friendly tutorials with clear visualizations.
|
||||
这是 [Pocket Flow](https://github.com/The-Pocket/PocketFlow), 一个仅 100 行的 LLM 框架）的教程项目。它会爬取 GitHub 仓库，并从代码中构建知识库。它分析整个代码库以识别核心抽象（abstraction）及其交互方式，并将复杂代码转化为配有清晰可视化的、面向初学者的教程。
|
||||
|
||||
|
||||
- Check out the [book "Crack Any Codebase with AI"](https://www.manning.com/books/crack-any-codebase-with-ai) for more!
|
||||
- 想了解更多？请查看图书 [《Crack Any Codebase with AI》](https://www.manning.com/books/crack-any-codebase-with-ai)
|
||||
|
||||
- Check out the [YouTube Development Tutorial](https://youtu.be/AFY67zOpbSo) for more!
|
||||
- 想了解更多？请查看 [YouTube 开发教程](https://youtu.be/AFY67zOpbSo)
|
||||
|
||||
- Check out the [Substack Post Tutorial](https://zacharyhuang.substack.com/p/ai-codebase-knowledge-builder-full) for more!
|
||||
- 想了解更多？请查看 [Substack 帖子教程](https://zacharyhuang.substack.com/p/ai-codebase-knowledge-builder-full)
|
||||
|
||||
**🔸 🎉 Reached Hacker News Front Page** (April 2025) with >900 up‑votes: [Discussion »](https://news.ycombinator.com/item?id=43739456)
|
||||
**🔸 🎉 登上 Hacker News 首页**（2025 年 4 月），获得超过 900 个赞：[讨论 »](https://news.ycombinator.com/item?id=43739456)
|
||||
|
||||
|
||||
|
||||
## ⭐ Example Results for Popular GitHub Repositories!
|
||||
## ⭐ 热门 GitHub 仓库的示例结果！
|
||||
|
||||
<p align="center">
|
||||
<img
|
||||
@@ -33,69 +39,69 @@ This is a tutorial project of [Pocket Flow](https://github.com/The-Pocket/Pocket
|
||||
/>
|
||||
</p>
|
||||
|
||||
🤯 All these tutorials are generated **entirely by AI** by crawling the GitHub repo!
|
||||
🤯 这些教程全部是通过爬取 GitHub 仓库，**完全由 AI 生成**的！
|
||||
|
||||
- [AutoGen Core](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/AutoGen%20Core) - Build AI teams that talk, think, and solve problems together like coworkers!
|
||||
- [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) - Let AI surf the web for you, clicking buttons and filling forms like a digital assistant!
|
||||
- [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) - Supercharge your app with background tasks that run while you sleep!
|
||||
- [Celery](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Celery) - 用后台任务为你的应用提速，让你在睡觉时任务照常运行！
|
||||
|
||||
- [Click](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Click) - Turn Python functions into slick command-line tools with just a decorator!
|
||||
- [Click](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Click) - 只需一个装饰器，就能把 Python 函数变成精致的命令行工具！
|
||||
|
||||
- [Codex](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Codex) - Turn plain English into working code with this AI terminal wizard!
|
||||
- [Codex](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Codex) - 用这个 AI 终端向导，把自然语言变成可运行代码！
|
||||
|
||||
- [Crawl4AI](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Crawl4AI) - Train your AI to extract exactly what matters from any website!
|
||||
- [Crawl4AI](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Crawl4AI) - 训练你的 AI，从任意网站精确提取真正重要的内容！
|
||||
|
||||
- [CrewAI](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/CrewAI) - Assemble a dream team of AI specialists to tackle impossible problems!
|
||||
- [CrewAI](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/CrewAI) - 组建一支 AI 专家梦之队，攻克看似不可能的问题！
|
||||
|
||||
- [DSPy](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/DSPy) - Build LLM apps like Lego blocks that optimize themselves!
|
||||
- [DSPy](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/DSPy) - 像搭乐高一样构建 LLM 应用，还能自我优化！
|
||||
|
||||
- [FastAPI](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/FastAPI) - Create APIs at lightning speed with automatic docs that clients will love!
|
||||
- [FastAPI](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/FastAPI) - 闪电般创建 API，并自动生成客户会喜欢的文档！
|
||||
|
||||
- [Flask](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Flask) - Craft web apps with minimal code that scales from prototype to production!
|
||||
- [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) - The universal language that lets AI agents collaborate across borders!
|
||||
- [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) - Design AI agents as flowcharts where each step remembers what happened before!
|
||||
- [LangGraph](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/LangGraph) - 把 AI 智能体设计成流程图，让每一步都记住之前发生了什么！
|
||||
|
||||
- [LevelDB](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/LevelDB) - Store data at warp speed with Google's engine that powers blockchains!
|
||||
- [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) - Build powerful apps that communicate through an elegant protocol without sweating the details!
|
||||
- [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) - Master the engine behind data science that makes Python as fast as C!
|
||||
- [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) - Build AI agents with digital brains that think, learn, and use tools just like humans do!
|
||||
- [OpenManus](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/OpenManus) - 构建拥有数字大脑、能像人类一样思考、学习并使用工具的 AI 智能体！
|
||||
|
||||
- [PocketFlow](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/PocketFlow) - 100-line LLM framework. Let Agents build Agents!
|
||||
- [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) - Validate data at rocket speed with just Python type hints!
|
||||
- [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) - Talk to the internet in Python with code so simple it feels like cheating!
|
||||
- [Requests](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/Requests) - 用 Python 与互联网对话，代码简单到像作弊一样！
|
||||
|
||||
- [SmolaAgents](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/SmolaAgents) - Build tiny AI agents that punch way above their weight class!
|
||||
- [SmolaAgents](https://the-pocket.github.io/PocketFlow-Tutorial-Codebase-Knowledge/SmolaAgents) - 构建小巧却实力超群的 AI 智能体！
|
||||
|
||||
- Showcase Your AI-Generated Tutorials in [Discussions](https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge/discussions)!
|
||||
- 在 [Discussions](https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge/discussions)! 中展示你由 AI 生成的教程
|
||||
|
||||
## 🚀 Getting Started
|
||||
## 🚀 快速开始
|
||||
|
||||
1. Clone this repository
|
||||
1. 克隆本仓库
|
||||
```bash
|
||||
git clone https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge
|
||||
```
|
||||
|
||||
3. Install dependencies:
|
||||
3. 安装依赖：
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
4. Set up LLM in [`utils/call_llm.py`](./utils/call_llm.py) by providing credentials. To do so, you can put the values in a `.env` file. By default, you can use the AI Studio key with this client for Gemini Pro 2.5 by setting the `GEMINI_API_KEY` environment variable. If you want to use another LLM, you can set the `LLM_PROVIDER` environment variable (e.g. `XAI`), and then set the model, url, and API key (e.g. `XAI_MODEL`, `XAI_URL`,`XAI_API_KEY`). If using Ollama, the url is `http://localhost:11434/` and the API key can be omitted.
|
||||
You can use your own models. We highly recommend the latest models with thinking capabilities (Claude 3.7 with thinking, O1). You can verify that it is correctly set up by running:
|
||||
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. Generate a complete codebase tutorial by running the main script:
|
||||
5. 运行主脚本生成完整代码库教程：
|
||||
```bash
|
||||
# Analyze a GitHub repository
|
||||
python main.py --repo https://github.com/username/repo --include "*.py" "*.js" --exclude "tests/*" --max-size 50000
|
||||
@@ -107,64 +113,64 @@ This is a tutorial project of [Pocket Flow](https://github.com/The-Pocket/Pocket
|
||||
python main.py --repo https://github.com/username/repo --language "Chinese"
|
||||
```
|
||||
|
||||
- `--repo` or `--dir` - Specify either a GitHub repo URL or a local directory path (required, mutually exclusive)
|
||||
- `-n, --name` - Project name (optional, derived from URL/directory if omitted)
|
||||
- `-t, --token` - GitHub token (or set GITHUB_TOKEN environment variable)
|
||||
- `-o, --output` - Output directory (default: ./output)
|
||||
- `-i, --include` - Files to include (e.g., "`*.py`" "`*.js`")
|
||||
- `-e, --exclude` - Files to exclude (e.g., "`tests/*`" "`docs/*`")
|
||||
- `-s, --max-size` - Maximum file size in bytes (default: 100KB)
|
||||
- `--language` - Language for the generated tutorial (default: "english")
|
||||
- `--max-abstractions` - Maximum number of abstractions to identify (default: 10)
|
||||
- `--no-cache` - Disable LLM response caching (default: caching enabled)
|
||||
- `--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 响应缓存（默认：启用缓存）
|
||||
|
||||
The application will crawl the repository, analyze the codebase structure, generate tutorial content in the specified language, and save the output in the specified directory (default: ./output).
|
||||
应用会爬取仓库、分析代码库结构、按指定语言生成教程内容，并保存到指定目录（默认：./output）。
|
||||
|
||||
|
||||
<details>
|
||||
|
||||
<summary> 🐳 <b>Running with Docker</b> </summary>
|
||||
<summary> 🐳 <b>使用 Docker 运行</b> </summary>
|
||||
|
||||
To run this project in a Docker container, you'll need to pass your API keys as environment variables.
|
||||
要在 Docker 容器中运行本项目，需要将 API 密钥作为环境变量传入。
|
||||
|
||||
1. Build the Docker image
|
||||
1. 构建 Docker 镜像
|
||||
```bash
|
||||
docker build -t pocketflow-app .
|
||||
```
|
||||
|
||||
2. Run the container
|
||||
2. 运行容器
|
||||
|
||||
You'll need to provide your `GEMINI_API_KEY` for the LLM to function. If you're analyzing private GitHub repositories or want to avoid rate limits, also provide your `GITHUB_TOKEN`.
|
||||
|
||||
Mount a local directory to `/app/output` inside the container to access the generated tutorials on your host machine.
|
||||
|
||||
**Example for analyzing a public GitHub repository:**
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
**Example for analyzing a local directory:**
|
||||
|
||||
```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
|
||||
```
|
||||
你需要提供 `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>
|
||||
|
||||
## 💡 Development Tutorial
|
||||
## 💡 开发教程
|
||||
|
||||
- I built using [**Agentic Coding**](https://zacharyhuang.substack.com/p/agentic-coding-the-most-fun-way-to), the fastest development paradigm, where humans simply [design](docs/design.md) and agents [code](flow.py).
|
||||
- 我使用 [**Agentic Coding**](https://zacharyhuang.substack.com/p/agentic-coding-the-most-fun-way-to), 最快的开发范式构建本项目，人类只需 [设计](docs/design.md)，由智能体（Agents）[编码](flow.py)。
|
||||
|
||||
- The secret weapon is [Pocket Flow](https://github.com/The-Pocket/PocketFlow), a 100-line LLM framework that lets Agents (e.g., Cursor AI) build for you
|
||||
- 秘诀是 [Pocket Flow](https://github.com/The-Pocket/PocketFlow), 一个仅 100 行的 LLM 框架，让智能体（例如 Cursor AI）为你构建
|
||||
|
||||
- Check out the Step-by-step YouTube development tutorial:
|
||||
- 请查看分步 YouTube 开发教程：
|
||||
|
||||
<br>
|
||||
<div align="center">
|
||||
@@ -173,6 +179,3 @@ To run this project in a Docker container, you'll need to pass your API keys as
|
||||
</a>
|
||||
</div>
|
||||
<br>
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user