# PocketFlow

**Repository Path**: nanjing-cai/pocket-flow

## Basic Information

- **Project Name**: PocketFlow
- **Description**: 你是否曾盯着复杂的AI框架，心想：“它真的需要这么复杂吗？” 在与臃肿的框架斗争了一年之后，我决定剔除所有不必要的部分。最终的成果就是Pocket Flow ，一个仅有100行代码的极简LLM框架。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 12
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <img src="./img/title.png" alt="PocketFlow" width="600"/>
  <br>
  <strong style="font-size:2em">《手搓AI Agent》配套代码</strong>
  <br>
  <a href="./pocketflow/__init__.py"><img src="https://img.shields.io/badge/📄 框架源码-100行-blue" alt="源码"/></a>
</div>

本仓库是《手搓AI Agent：100行代码构建全部AI模式》一书的配套代码库。

书中所有示例均基于 PocketFlow —— 一个仅有100行代码的极简LLM框架。无依赖、无黑箱、无厂商锁定，让你真正理解每一行代码在做什么。

---

## 为什么只需100行？

当前主流LLM框架动辄数十万行代码，充斥着大量应用封装和厂商绑定。大部分开发者其实只需要框架的**核心抽象**，而不是那些臃肿的包装。

PocketFlow用100行代码证明：你根本不需要那些复杂框架。

<div align="center">
  <img src="./img/meme.jpg" width="400"/>
</div>

<div align="center">

|                | **核心抽象**          | **应用封装**                                      | **厂商绑定**                                    | **代码行数**       | **安装体积**    |
|----------------|:-----------------------------: |:-----------------------------------------------------------:|:------------------------------------------------------------:|:---------------:|:----------------------------:|
| LangChain  | Agent, Chain               | 大量 <br><sup><sub>（如 QA、摘要等）</sub></sup>              | 大量 <br><sup><sub>（如 OpenAI、Pinecone 等）</sub></sup>                   | 405K          | +166MB                     |
| CrewAI     | Agent, Chain            | 大量 <br><sup><sub>（如 FileReadTool、SerperDevTool）</sub></sup>         | 大量 <br><sup><sub>（如 OpenAI、Anthropic、Pinecone 等）</sub></sup>        | 18K           | +173MB                     |
| SmolAgent   | Agent                      | 部分 <br><sup><sub>（如 CodeAgent、VisitWebTool）</sub></sup>         | 部分 <br><sup><sub>（如 DuckDuckGo、Hugging Face 等）</sub></sup>           | 8K            | +198MB                     |
| LangGraph   | Agent, Graph           | 部分 <br><sup><sub>（如语义搜索）</sub></sup>                     | 部分 <br><sup><sub>（如 PostgresStore、SqliteSaver 等）</sub></sup>        | 37K           | +51MB                      |
| AutoGen    | Agent                | 部分 <br><sup><sub>（如 Tool Agent、Chat Agent）</sub></sup>              | 大量 <sup><sub>[可选]<br>（如 OpenAI、Pinecone 等）</sub></sup>        | 7K <br><sup><sub>（仅核心）</sub></sup>    | +26MB <br><sup><sub>（仅核心）</sub></sup>          |
| **PocketFlow** | **Graph**                    | **无**                                                 | **无**                                                  | **100**       | **+56KB**                  |

</div>

---

## 核心抽象：图（Graph）

PocketFlow的100行代码捕获了LLM框架的核心抽象——**图（Graph）**。

所有AI设计模式，无论是Agent、工作流、RAG还是多Agent协作，本质上都是图的不同表达。

<div align="center">
  <img src="./img/abstraction.png" width="700"/>
</div>

从这个抽象出发，可以轻松实现所有主流AI设计模式：

<div align="center">
  <img src="./img/design.png" width="700"/>
</div>

### 三个核心概念

- **节点（Node）** —— 执行单元，遵循三步模式：`prep`（准备）→ `exec`（执行）→ `post`（后处理）
- **流程（Flow）** —— 节点的编排方式，支持四种操作：串联、分支、循环、嵌套
- **共享存储（Shared Store）** —— 一个简单的Python字典，作为节点间的通信桥梁

掌握这三个概念，你就掌握了构建任何AI应用的能力。

---

## 配套示例

以下示例由浅入深，覆盖所有核心AI设计模式。

<div align="center">

| 难度 | 示例 | 说明 |
|:----:|:-----|:-----|
| ☆☆☆ 基础入门 | [Hello World](./pocketflow-hello-world/) | 最简单的PocketFlow示例，了解Node和Flow基本概念 |
| | [节点基础](./pocketflow-node/) | 文本摘要 + 重试机制，理解Node的prep/exec/post |
| | [聊天机器人](./pocketflow-chat/) | 带对话历史的聊天bot，展示自循环模式 |
| | [结构化输出](./pocketflow-structured-output/) | 从简历中提取结构化数据，YAML解析 + 校验 |
| | [工作流](./pocketflow-workflow/) | 写作流水线：大纲 → 撰写 → 润色 |
| | [流程控制](./pocketflow-flow/) | 交互式文本变换，展示分支路由 |
| | [节点通信](./pocketflow-communication/) | 通过Shared Store在节点间传递数据 |
| | [Agent](./pocketflow-agent/) | 研究Agent：搜索网页并回答问题 |
| | [RAG](./pocketflow-rag/) | 检索增强生成的完整流程 |
| | [批处理](./pocketflow-batch/) | 将Markdown批量翻译成多种语言 |
| | [LLM流式输出](./pocketflow-llm-streaming/) | 实时LLM流式响应 + 用户中断 |
| | [聊天护栏](./pocketflow-chat-guardrail/) | 旅行顾问聊天bot，只处理旅行相关问题 |
| | [多数投票](./pocketflow-majority-vote/) | 多次尝试 + 共识投票提升准确率 |
| | [Map-Reduce](./pocketflow-map-reduce/) | 简历批量评估的Map-Reduce模式 |
| | [命令行HITL](./pocketflow-cli-hitl/) | 命令行笑话生成器，人机协同反馈循环 |
| ★☆☆ 进阶实践 | [多Agent通信](./pocketflow-multi-agent/) | Taboo猜词游戏，两个Agent异步通信 |
| | [监督者](./pocketflow-supervisor/) | Agent输出不可靠？加一个监督流程 |
| | [并行批处理](./pocketflow-parallel-batch/) | 异步并行执行，3倍加速 |
| | [并行批处理Flow](./pocketflow-parallel-batch-flow/) | 并行图像处理，8倍加速 |
| | [思维链](./pocketflow-thinking/) | Chain-of-Thought逐步推理解决复杂问题 |
| | [对话记忆](./pocketflow-chat-memory/) | 短期 + 长期记忆的聊天bot |
| | [MCP协议](./pocketflow-mcp/) | 通过Model Context Protocol调用工具 |
| | [追踪可视化](./pocketflow-tracing/) | Langfuse集成，追踪Flow执行过程 |
| | [评判者模式](./pocketflow-judge/) | LLM作为评判者的评估-优化循环 |
| | [辩论模式](./pocketflow-debate/) | 对抗推理：正方、反方与裁判 |
| | [智能RAG](./pocketflow-agentic-rag/) | Agent驱动的检索增强生成 |
| | [自愈Mermaid](./pocketflow-self-healing-mermaid/) | 生成Mermaid图表，自动检测错误并修复 |
| | [心跳监控](./pocketflow-heartbeat/) | 嵌套Flow实现ClawBot式持续监控 |
| | [Text2SQL](./pocketflow-text2sql/) | 自然语言转SQL查询 + 自动纠错 |
| | [代码生成器](./pocketflow-code-generator/) | 生成测试用例、实现代码、迭代改进 |
| | [Agent技能](./pocketflow-agent-skills/) | 可复用的Markdown技能路由 |
| | [A2A协议](./pocketflow-a2a/) | Agent-to-Agent通信协议集成 |
| | [异步基础](./pocketflow-async-basic/) | AsyncNode异步API调用 |
| | [批处理节点](./pocketflow-batch-node/) | CSV大文件分块处理 |
| | [批处理Flow](./pocketflow-batch-flow/) | 多参数组合的图像滤镜处理 |
| | [嵌套批处理](./pocketflow-nested-batch/) | 学校→班级→学生的层级批处理 |
| ★★☆ 实战应用 | [线索生成](./pocketflow-lead-generation/) | 销售线索：抓取 → 富化 → 评分 → 个性化邮件 |
| | [AI周报](./pocketflow-newsletter/) | AI新闻策展：搜索 → 筛选 → 摘要 → 排版 |
| | [发票处理](./pocketflow-invoice/) | PDF视觉提取发票数据 + 数学验证 |
| | [播客生成](./pocketflow-notebook-lm/) | 文档变双主持人AI播客 |
| | [深度研究](./pocketflow-deep-research/) | 递归Map-Reduce研究，迭代完善 |
| | [FastAPI后台任务](./pocketflow-fastapi-background/) | FastAPI + SSE实时进度推送 |
| | [FastAPI人机协同](./pocketflow-fastapi-hitl/) | FastAPI实现审批工作流 |
| | [FastAPI WebSocket](./pocketflow-fastapi-websocket/) | WebSocket实时聊天 + LLM流式响应 |
| | [Gradio人机协同](./pocketflow-gradio-hitl/) | Gradio界面的多节点决策流程 |
| | [Streamlit状态机](./pocketflow-streamlit-fsm/) | Streamlit + 有限状态机的图像生成 |
| | [语音聊天](./pocketflow-voice-chat/) | VAD + STT + LLM + TTS语音对话 |
| | [网页爬虫](./pocketflow-tool-crawler/) | 受控域名内的网页爬取与分析 |
| | [数据库工具](./pocketflow-tool-database/) | SQLite安全参数化查询 |
| | [Embeddings工具](./pocketflow-tool-embeddings/) | OpenAI文本嵌入向量生成 |
| | [PDF视觉工具](./pocketflow-tool-pdf-vision/) | 多PDF批量视觉提取 |
| | [搜索工具](./pocketflow-tool-search/) | SerpAPI网页搜索 + LLM分析 |
| | [Google日历](./pocketflow-google-calendar/) | Google Calendar API事件管理 |
| | [Flow可视化](./pocketflow-visualization/) | D3.js交互式Flow图可视化 |
| ★★★ 高级项目 | [编程Agent](./pocketflow-coding-agent/) | 生产级编程Agent：6个工具 + 记忆 + Patch子流程 |

</div>

---

## 快速开始

### 方式一：pip安装

```bash
pip install pocketflow
```

### 方式二：直接复制源码

PocketFlow仅有100行代码，你完全可以将 `pocketflow/__init__.py` 直接复制到你的项目中。没有任何外部依赖。

### 运行示例

```bash
# 进入任意示例目录
cd pocketflow-judge

# 安装该示例的依赖
pip install -r requirements.txt

# 运行
python main.py
```

---

## 关于本书

《手搓AI Agent：100行代码构建全部AI模式》 的核心观点是：

> 你不需要复杂的框架来构建强大的AI应用。你只需要理解一个核心抽象——**图**。

本书从这个抽象出发，带你从零开始，用100行代码构建出Agent、工作流、RAG、多Agent协作等所有主流AI设计模式。每个模式都配有完整的代码示例和详细的原理讲解，让你真正做到**知其然，更知其所以然**。

**本书适合谁：** 无论你是（1）想理解AI Agent底层原理的开发者，（2）对主流LLM框架感到困惑、想回归本质的工程师，（3）希望快速上手构建AI应用的技术人员，还是（4）对"少即是多"的设计哲学感兴趣的读者，这本书都能帮你用最少的代码，建立最扎实的理解。

### 章节概览

<div align="center">

| 章节 | 主题 | 核心内容 |
|:----:|:----:|:---------|
| | **第一部分：别学框架了，学图就够了** | |
| 第1章 | 忘掉LangChain的40万行代码 | 为什么LLM框架的核心是图？100行如何替代40万行 |
| 第2章 | 图——唯一的抽象 | Node、Flow、Shared Store；聊天机器人、重试、结构化输出、批处理、异步并行 |
| 第3章 | Workflow、Agent、更多模式 | 工作流、Agent、护栏、思维链、自愈、评判者/投票/辩论 |
| | **第二部分：你花钱用的AI产品，不过是简单工作流** | |
| 第4章 | RAG不过是5个节点串一行 | 何时需要RAG、Embedding、Agentic RAG、数据质量才是关键 |
| 第5章 | 深度研究不过是搜索API的for循环 | 三节点一循环、Map-Reduce、搜索API比模型重要 |
| 第6章 | NotebookLM、Text2SQL、线索生成 | 拆分Prompt、自愈循环、大多数AI产品只有4个节点 |
| | **第三部分：为什么大多数AI Agent都很烂** | |
| 第7章 | Prompt工程：领域知识才是Prompt | 2023年的trick已过时；Few-shot、Rubric、测试驱动Prompt |
| 第8章 | 模型是大宗商品，工具才是护城河 | 三级工具、Action Space、环境设计比模型选择重要 |
| 第9章 | 上下文工程：别再饿死你的Agent | 上下文窗口就是RAM、记忆层级、历史压缩 |
| 第10章 | Cursor、Claude Code、Codex——从零造 | 3个核心工具、编辑难题、两阶段编辑、验证与安全 |
| 第11章 | 多Agent：人人想要，无人需要 | 更多Agent≠更好结果、仅两种拆分理由、Agent即工具 |
| | **第四部分：学够了，发布吧** | |
| 第12章 | Agentic Coding：英语就是编程语言 | 瀑布流才是正解、设计文档是资产、AI的5个常见错误 |
| 第13章 | 从笔记本到生产环境 | 三种部署方式、80%的"AI失败"是工具坏了、安全的致命三角 |

</div>

---

---

<div align="center">

**用100行代码，理解所有AI设计模式。**

*Less is More.*

</div>