PocketFlow 详解：100 行代码的 LLM 框架
LangChain 40 万行、装完胖 166MB——"框架膨胀"是这两年 LLM 应用开发最常被吐槽的痛点。The-Pocket/PocketFlow（Pocket Flow）给出的答案激进到近乎行为艺术：整个框架只有 100 行 Python，零依赖、零厂商锁定，只保留一个核心抽象——图（Graph）。在此之上，Agent、Workflow、RAG 等设计模式全部回归"组合"而非"内置"。约 11.2k Star、MIT 协议，作者 Zachary Huang 同时把它当作 Agentic Coding 范式的载体：人写设计文档，AI Agent 写代码。本文从核心抽象、源码结构、使用范式到选型对比，完整拆解。
1、项目概述
PocketFlow 定位为"100 行的极简 LLM 框架"（100-line minimalist LLM framework），核心主张是：LLM 框架的必需抽象只有一个——图；其余的应用级包装（QA、总结器）与厂商级包装（OpenAI、Pinecone 适配）都是膨胀来源，应当剥离。仓库约 11.2k Star、1.2k Fork，主语言 Python，由 Zachary Huang（组织 The-Pocket）维护，2024 年 12 月创建，配有官方文档站、视频教程与 Discord 社区。
基本盘：
- 协议：MIT，pip install pocketflow 一条命令，或直接复制 100 行源码即用
- 体量：框架本体 100 行、+56KB，对比 LangChain 40.5 万行 / +166MB、CrewAI 1.8 万行 / +173MB（README 数据）
- 多语言：TypeScript、Java、C++、Go、Rust、PHP 官方移植版各成仓库
- 生态：40 个 Cookbook 教程（从 Dummy 到 Advanced）+ 独立示例仓库群（YouTube 摘要、AI Paul Graham 等）
- 文档：the-pocket.github.io/PocketFlow/，覆盖设计模式与工具函数，README 提供九种语言版本
2、核心抽象：一切皆图
PocketFlow 认为 LLM 框架的本质只有一个：把"节点 + 转移"组织成有向图，其余一切（Agent 决策、RAG 检索、工作流）都是这张图上的设计模式。
概念拆解：
- Node（节点）：最小执行单元，生命周期固定三段——prep 读取共享存储、exec 执行核心逻辑、post 写回并返回 action
- action（动作）：post 的返回值即路由键，决定走哪条边，形成条件分支
- Flow（流）：图的运行时，从 start 节点起沿 action 链步进直到无后继
- shared（共享存储）：所有节点读写同一 dict，是图内唯一的状态载体
- 语法糖：node1 >> node2 连边；node - "action" >> node3 条件转移，用运算符重载替代配置式 DSL
三类变体节点与流：
- Node：带 max_retries / wait 的重试机制与 exec_fallback 兜底，LLM 调用失败自动退避
- BatchNode：prep 返回条目列表，exec 逐条执行，天然适配批量翻译、批量摘要
- AsyncParallelBatchNode：asyncio.gather 并发执行整批条目，Cookbook 实测并行提速 3～8 倍
抽象要点：
1. Agent = "决策节点 + 工具循环"：post 依据 LLM 判断返回不同 action，重试参数兜住工具调用失败，零内置工具
2. RAG = "检索节点 + 生成节点" 串联，向量化与召回全部用户自写，框架不绑定 Pinecone / OpenAI
3. 多 Agent = 图嵌套：Flow 本身继承 BaseNode，子图可直接作为节点挂进父图，supervisor、debate 模式由此组合
4. 复杂度全部沉在"组合层"：100 行管编排，节点内容、Prompt、工具定义全在用户代码里，白盒可调试
3、100 行源码结构
整个框架就是 pocketflow/__init__.py 一个文件，10 个类、100 行，可分为四层。
// 层 1：BaseNode —— 生命周期骨架（节选，Python 原码）
class BaseNode:
def __init__(self): self.params, self.successors = {}, {}
def next(self, node, action="default"):
self.successors[action] = node; return node
def _run(self, shared):
p = self.prep(shared) # 1. 读取共享存储
e = self._exec(p) # 2. 执行核心逻辑
return self.post(shared, p, e) # 3. 写回并返回 action
def __rshift__(self, other): return self.next(other) # a >> b 连边
def __sub__(self, action): ... # a - "act" >> c 条件转移
// 层 2：Node —— 重试与兜底（节选）
class Node(BaseNode):
def __init__(self, max_retries=1, wait=0): ...
def _exec(self, prep_res):
for self.cur_retry in range(self.max_retries):
try: return self.exec(prep_res)
except Exception as e:
if self.cur_retry == self.max_retries - 1:
return self.exec_fallback(prep_res, e) # 最终失败走兜底
if self.wait > 0: time.sleep(self.wait) # 退避等待
// 层 3：Flow —— 图运行时（节选）
class Flow(BaseNode):
def _orch(self, shared, params=None):
curr, p, last_action = copy.copy(self.start_node), ..., None
while curr:
curr.set_params(p)
last_action = curr._run(shared) # 节点执行后拿 action
curr = copy.copy(self.get_next_node(curr, last_action))
return last_action # 图结束返回末次 action
// 层 4：Batch/Async 家族（节选）
class AsyncParallelBatchNode(AsyncNode, BatchNode):
async def _exec(self, items):
return await asyncio.gather(*(super()._exec(i) for i in items))源码要点：
1. 四层结构：BaseNode 骨架 → Node 加重试 → Flow 加图遍历 → Batch/Async 家族加批处理，每层只叠加一个能力
2. 图即编排器：_orch 的 while 循环逐节点步进，action 缺失即图自然终止，没有独立的状态机引擎
3. 节点执行前 copy.copy 浅拷贝，同一图定义可被 BatchFlow 复用多轮而不互相污染
4. AsyncNode 的 _run 直接 raise，强制异步场景必须走 AsyncFlow，同步异步不混用
5. 全文件 import 仅 asyncio、warnings、copy、time 四个标准库，"零依赖"名副其实
4、使用范式：Agentic Coding
PocketFlow 主推的开发范式不是"人手写节点"，而是 Agentic Coding：人写设计文档，AI Agent（如 Cursor、Claude Code）照文档生成代码，作者宣称 10 倍生产力提升。
# 安装与最小使用
pip install pocketflow
# Agentic Coding 起步模板（官方提供）
# 1. git clone https://github.com/The-Pocket/PocketFlow-Template-Python
# 2. 在 docs/design.md 里写下流程设计（节点、action、共享字段）
# 3. 让 AI Agent 依据设计文档生成 flow.py 与各节点实现
# 4. 运行 python flow.py 验证范式要点：
1. 设计先行：人只维护 docs/design.md（含 Mermaid 流程图与节点职责），代码是可再生的衍生物
2. 100 行框架降低了 Agent 的理解成本——抽象越少，生成的代码越不容易跑偏，这正是极简框架与 Agentic Coding 互相成就的地方
3. Cookbook 40 个教程即 40 份"设计文档 + 生成代码"的对照样本，从 Chat、RAG、Map-Reduce 到 Coding Agent（6 工具 + 记忆 + 补丁子流）
4. 进阶示例独立成仓：YouTube 摘要、AI Paul Graham、弹丸论破模拟器等，每个都是"Human Design + Agent Code"两栏结构
5、定位对比：轻量框架三选一
把 PocketFlow 与 LangGraph、CrewAI 放在一张桌上，各自的位置清晰起来。
三者对比：
- PocketFlow：100 行、零依赖的图框架，MIT，一切皆组合；配套 Agentic Coding 范式与 40 个 Cookbook，11.2k Star
- LangGraph：LangChain 系图编排引擎，Checkpointer、Human-in-the-loop、时间旅行等生产特性齐备，深度绑定 LangChain 生态
- CrewAI：角色化多 Agent 协作框架，内置大量工具与厂商适配，开箱即用但体积与抽象层更厚（+173MB）
选型建议：
1. 要白盒掌控每个环节、配合 AI 编码代理开发 → PocketFlow
2. 要生产级状态管理、断点恢复、深度集成 LangChain 工具链 → LangGraph
3. 要快速搭角色分工的多 Agent 团队、接受框架默认封装 → CrewAI
4. 组合玩法：PocketFlow 做应用骨架，模型调用层走 LiteLLM 网关，工具与记忆参考 Cookbook 模式自写
6、总结
PocketFlow 是一个只有 100 行代码的 MIT 极简 LLM 框架（约 11.2k Star、1.2k Fork）：唯一核心抽象是图——Node 以 prep / exec / post 三段生命周期执行并返回 action 路由，Flow 沿边遍历整图，BatchNode 与 Async 并行变体覆盖批量与并发场景，整个实现只依赖标准库。在此之上，Agent、Workflow、RAG、多 Agent 全部以设计模式回归组合；项目同步推广 Agentic Coding 范式——人写设计文档、AI Agent 生成代码，40 个 Cookbook 与多语言移植版（TypeScript、Java、C++、Go、Rust、PHP）构成生态。
适用与边界：它适合想白盒理解与掌控 LLM 应用每个环节、并配合 Cursor / Claude Code 等编码代理开发的工程师与学习者；极简意味着没有内置工具、检索器与持久化，生产级的状态保存、断点恢复、可观测需要自建或另接组件，团队若依赖开箱即用的厂商适配与成熟中间件，LangGraph / CrewAI 的厚封装反而是效率优势。100 行的框架定位是"教学与骨架"，把复杂度还给应用本身。
