Pocket Flow 部署与实战教程：只用 100 行代码构建你的 LLM 智能体工作流

Pocket Flow（The-Pocket/PocketFlow，MIT 协议，GitHub 星数约 1.13 万，最近提交 2026-07-26）是一个号称"100 行代码"的极简 LLM 框架。它没有 LangChain 那种几千个类、几百 MB 的依赖树，整个核心只有一个 pocketflow/__init__.py（约 100 行），零依赖、零厂商锁定。它把 LLM 应用抽象成一个图（Graph）：每个节点是一段 Python 代码，节点之间用 post 返回的字符串决定下一步去哪。Workflow、Agent、RAG、Multi-Agent、Map-Reduce、Judge、Debate、Deep Research 全是这一张图的不同画法。

本文严格对照官方 README 给出安装、最小示例与 30+ cookbook 的实战路径。

一、项目介绍与适用场景

官方一句话："Pocket Flow is a 100-line minimalist LLM framework"。

它不做的事：

• 不封装 OpenAI/Anthropic SDK；
• 不内置向量库；
• 不写一堆 QA、Summarization 这种"应用级 wrapper"；
• 不绑定某家厂商。

它只做的事：

• 给你一个 Node 基类，你实现 prep / exec / post；
• 给你一个 Flow，把节点连起来；
• 让你用任意 LLM SDK、任意向量库、任意 HTTP 客户端自己组装。

适用场景：

• 想理解 LLM 框架原理，而不是套黑盒；
• 想用最少的依赖写一个可维护的 agent 工作流；
• 用 Cursor / Claude Code 这种"Agentic Coding"方式快速搭 LLM App；
• 给现有 Python 项目嵌入一个轻量工作流引擎，而不是引入 100MB 的框架。

二、核心功能逐条拆解

1. Graph 抽象：节点是 Python 对象，边是 post 返回的字符串。
2. Multi-Agent / Agent：节点里放 LLM 调用即可。
3. Workflow：线性或分支的节点链。
4. RAG：在节点里做检索 + 生成。
5. Map-Reduce / Parallel / Streaming / Memory / Guardrail / Judge / Debate / MCP / A2A / Deep Research：全是 cookbook 里的示例。
6. 多语言移植版：TypeScript、Java、C++、Go、Rust、PHP 都有官方移植。
7. 30+ cookbook 示例：从 Chat 到 Deep Research 到 Coding Agent，难度从 ☆☆☆ 到 ★★★。

三、全套官方链接

四、硬件与环境前置要求

• Python 3.9+（官方未严格限定，推荐 3.10/3.11）；
• 内存无硬性要求；
• 网络：首次 pip install 走 PyPI；运行时调 LLM 需要联网；
• 可选：OpenAI / Anthropic / DeepSeek 等任意厂商 API key。

五、多平台部署步骤

5.1 安装（官方原文）

官方 README 给两条等价路径：

pip install pocketflow

或者：直接把 100 行源码 复制到你项目里，作为本地模块用——这是官方推荐的"零依赖"玩法。

5.2 验证安装

python3 -c "import pocketflow; print(pocketflow.__file__)"

打印出 site-packages 路径即成功。

5.3 跑最小 Workflow（以官方 Workflow cookbook 为例）

官方 cookbook 目录在 cookbook/ 下。克隆仓库：

git clone https://github.com/The-Pocket/PocketFlow.git
cd PocketFlow

最小骨架（基于官方 Node 契约，伪代码骨架，实际以 cookbook 源码为准）：

from pocketflow import Node, Flow

class Outline(Node):
    def prep(self, shared):
        return shared["topic"]
    def exec(self, topic):
        return call_llm(f"为主题 {topic} 写大纲")
    def post(self, shared, prep_res, exec_res):
        shared["outline"] = exec_res
        return "to_write"

class Write(Node):
    ...

flow = Flow(start=Outline())
flow.run(shared={"topic": "开源 LLM 框架对比"})

官方 cookbook/pocketflow-workflow/ 里有完整可跑版本，建议直接 cd cookbook/pocketflow-workflow && python main.py。

5.4 跑 Agent cookbook

cd cookbook/pocketflow-agent
# 按 README 里说明配 OPENAI_API_KEY
python main.py

这个示例是一个能搜网页、能回答问题的 research agent。

5.5 Docker 部署

官方 README 未提供 Dockerfile；因为它是纯 Python 库，按普通 Python 项目打 Docker 即可。本文不展开。

5.6 多语言移植版

README 末尾官方列出：

• TypeScript：https://github.com/The-Pocket/PocketFlow-Typescript
• Java：https://github.com/The-Pocket/PocketFlow-Java
• C++：https://github.com/The-Pocket/PocketFlow-CPP
• Go：https://github.com/The-Pocket/PocketFlow-Go
• Rust：https://github.com/The-Pocket/PocketFlow-Rust
• PHP：https://github.com/The-Pocket/PocketFlow-PHP

按各自仓库 README 装。

六、配置文件全部参数解释

Pocket Flow 本身没有配置文件，零依赖。所有"配置"都是你自己写的 Python 代码：

更细的 API 见 https://the-pocket.github.io/PocketFlow/ 。

七、启动、后台常驻与开机自启

Pocket Flow 是库不是服务，没有"启动端口"。如果用它包一个 FastAPI 应用（参考 cookbook/pocketflow-fastapi-websocket/），按 FastAPI 方式起：

uvicorn main:app --host 0.0.0.0 --port 8000

后台常驻用 systemd 或 pm2，与普通 Python 服务一致。

八、功能实操教程

第 1 步：pip install pocketflow，验证 5.2。 第 2 步：克隆仓库，跑 cookbook/pocketflow-chat/（基础聊天机器人，带历史）。 第 3 步：跑 cookbook/pocketflow-workflow/（大纲→写作→润色）。 第 4 步：跑 cookbook/pocketflow-agent/（带搜索的 research agent）。 第 5 步：跑 cookbook/pocketflow-multi-agent/（两个 agent 通过异步通信玩 Taboo 游戏）。 第 6 步：跑 cookbook/pocketflow-deep-research/（递归 map-reduce 深度研究）。 第 7 步：自己新开一个项目，直接复制 100 行源码进去，写一个属于你的节点图。

九、全套报错故障排查

1. 报错：ModuleNotFoundError: No module named 'pocketflow'。 解决：pip install pocketflow 或把源码拷到项目里。

2. 报错：post 返回的字符串找不到对应节点。 原因：Node 映射里没有这个 key。 解决：按官方文档，在 Flow 里用 >> 或 add_edges 显式声明边。

3. 报错：LLM 调用 401。 原因：API key 没配。 解决：在你自己的代码里 os.environ["OPENAI_API_KEY"] = "..."。

4. 报错：cookbook/ 里示例缺依赖。 原因：每个 cookbook 自己有 requirements.txt。 解决：进对应目录 pip install -r requirements.txt。

5. 报错：流式输出卡住。 解决：参考 cookbook/pocketflow-llm-streaming/ 里的标准写法，用 generator 透传。

十、升级、回滚与卸载

• 升级：pip install -U pocketflow。
• 回滚：pip install pocketflow==<旧版本>。
• 卸载：pip uninstall pocketflow。
• 零依赖玩法：因为整个库就一个文件，你想固定版本，把 pocketflow/__init__.py 直接 commit 到你自己仓库里即可。

十一、商用许可与合规风险提示

Pocket Flow 采用 MIT License（README 顶部 badge 明确），商用友好。

注意：

1. 它不封装厂商 SDK：意味着你自己接 OpenAI/Anthropic 时，要自己遵守对方 ToS；
2. 示例代码里可能用了第三方工具：cookbook 里 web search、TTS、STT 等示例会调外部服务，商用前确认那些服务的授权；
3. MCP / A2A 示例：接外部 MCP server 时注意权限与数据边界。

十二、进阶：从 cookbook 到生产 Agent

12.1 推荐的入门路径

官方 cookbook 难度从 ☆☆☆（Dummy）到 ★★★（Advanced），建议按这个顺序练：

1. pocketflow-chat —— 最小聊天机器人，理解 shared 与节点；
2. pocketflow-workflow —— 线性三步工作流，理解 post 路由；
3. pocketflow-agent —— 带搜索的 research agent；
4. pocketflow-rag —— 检索增强生成；
5. pocketflow-multi-agent —— 两个 agent 异步通信；
6. pocketflow-deep-research —— 递归 map-reduce 深度研究；
7. pocketflow-coding-agent —— 带 6 个工具、记忆、patch-as-subflow 的生产级编码 agent。

12.2 Agentic Coding 工作流

官方推荐的玩法是：人写设计文档，AI 写代码。仓库给了一个官方模板 PocketFlow-Template-Python。做法是：

• 先用 Markdown 把工作流拆成节点、每个节点输入输出、失败回退路径写清楚；
• 把这份设计文档喂给 Cursor / Claude Code / Copilot；
• 让它按 Pocket Flow 的 Node / Flow 契约把代码生成出来；
• 人负责 review、调 prompt、调路由，AI 负责写样板代码。

README 里列了 7 个完整示范应用（Website Chatbot、Danganronpa Simulator、Codebase Knowledge Builder、Build Cursor with Cursor、Ask AI Paul Graham、Youtube Summarizer、Cold Opener Generator），每个都有"设计文档 + flow.py"两份，是最好的进阶教材。

12.3 什么时候不该用 Pocket Flow

• 你要的是一个开箱即用的多租户 SaaS agent 平台——选 Langflow / Dify 这种带 UI 的；
• 你要的是重型 RAG、企业知识库、复杂权限——选 Cognee / LlamaIndex；
• 你需要的是超长记忆、向量库自动运维——Pocket Flow 不做这些，你自己接。

参考链接

• 官方 README：https://github.com/The-Pocket/PocketFlow
• 官方文档：https://the-pocket.github.io/PocketFlow/
• 100 行源码：https://github.com/The-Pocket/PocketFlow/blob/main/pocketflow/init.py
• 设计模式：Agent / Workflow / RAG / Multi-Agent 章节见官方文档 design_pattern/ 目录
• 模板：https://github.com/The-Pocket/PocketFlow-Template-Python