Node.js + React 构建 AI Agent 开源框架 paperclip 实战指南

1. 从“paperclip”这个名字说起：它到底想解决什么问题

第一次看到paperclip这个项目名，我脑子里蹦出来的不是回形针，而是那个经典的“回形针最大化”思想实验——一个足够聪明的智能体，为了完成“多造回形针”这个目标，最终把整个世界都变成了回形针工厂。做 AI agent 的人对这个梗都不陌生，而把这个名字用在一个开源项目上，作者大概率是想表达一种自嘲式的清醒：我们正在造的可能就是那个“回形针”，所以得把它的每一颗齿轮都摊开给你看。

paperclip是一个基于Node.js + React技术栈构建的AI agents 开源框架/工具。它要解决的问题很具体：现在市面上讲 agent 的文章一大堆，但真正能让你在本地跑起来、看得见每一步推理、改得动每一行代码的项目并不多。大多数要么是封装得密不透风的商业 API，要么是只给你一个 demo 视频、代码却跑不通的“论文复现”。paperclip的定位就是把这些黑盒拆开，用前端工程师最熟悉的 React 做交互层，用 Node.js 做 agent 的运行时和工具调用层，让你能像调试一个普通 Web 应用一样去调试一个 AI agent。

它适合谁？如果你是一个前端或者全栈开发者，对 AI agent 感兴趣但一直觉得“那是 Python 圈的事”，那这个项目就是为你准备的。你不需要先去学 LangChain 那一套 Python 生态，用你已有的 Node.js 和 React 技能就能上手。如果你是一个已经在做 agent 但苦于调试困难的人，paperclip提供的可视化推理链路和状态管理思路也值得参考。哪怕你只是想看看“手写一个 React agent”到底长什么样，这个项目的代码结构也能给你不少启发。

我花了大概两周时间把这个项目从 clone 到跑通、再到改出自己需要的功能，中间踩了不少坑，也总结了一些官方文档里不会写的经验。下面我就按“设计思路—核心细节—实操过程—问题排查”这个顺序，把整个项目的骨架和血肉都拆给你看。

2. 整体架构设计：为什么是 Node.js + React 这个组合

2.1 前后端分离在 agent 场景下的特殊意义

传统的 Web 应用前后端分离，主要是为了职责清晰和独立部署。但在 AI agent 场景下，前后端分离还有一个更关键的理由：agent 的执行是长时、异步、多步的，而 UI 需要实时反映每一步的状态。如果你把 agent 逻辑和 UI 塞在一个进程里，一个耗时 30 秒的工具调用就会把界面卡死；而如果你用传统的请求-响应模式，前端根本没法知道 agent 现在是在“思考”还是在“调工具”还是在“等用户确认”。

paperclip的做法是：Node.js 后端作为 agent 的“大脑”，负责编排推理步骤、调用工具、管理记忆；React 前端作为“仪表盘”，通过 SSE（Server-Sent Events）或 WebSocket 接收后端的实时事件流，把 agent 的每一步都渲染出来。这个架构选择背后有一个很实际的考量：SSE 比 WebSocket 更简单，对于 agent 这种“服务器单向推送状态”的场景足够用，而且 SSE 天然支持断线重连，浏览器兼容性也好。当然如果你需要双向通信（比如用户在 agent 执行中途插话），那就得换成 WebSocket，paperclip的代码里也留了切换的接口。

我实测下来，SSE 在本地开发时几乎零配置，Node.js 端用res.write()就能推事件，React 端用EventSource就能收，比 WebSocket 少写不少样板代码。但有一个坑：SSE 默认不支持自定义请求头，如果你需要在连接时传认证 token，要么用 query param，要么就得换 WebSocket。这个后面讲排查技巧时再细说。

2.2 为什么不用 Python 生态而选 Node.js

这个问题我被问过很多次。Python 有 LangChain、AutoGPT、CrewAI，生态确实成熟，但paperclip选 Node.js 有几个很实在的理由。第一，前端开发者基数大，用 React 的人远多于用 Streamlit 或 Gradio 的人，降低门槛意味着更多人能参与进来改。第二，Node.js 的异步 I/O 模型天然适合 agent 这种“大量等待”的场景，一个 agent 可能同时等 LLM 返回、等工具执行、等用户输入，Node 的事件循环处理这些比 Python 的 GIL 要舒服。第三，npm 生态里有大量现成的工具库，比如文件操作、HTTP 请求、JSON 解析，agent 要调用的工具往往就是这些基础能力的组合。

当然 Node.js 做 AI 也有短板：科学计算和本地模型推理不是它的强项。但paperclip的定位是“编排层”而不是“推理层”，它调用的是远程 LLM API（比如 OpenAI、Claude 或本地 Ollama 的 HTTP 接口），所以这个短板影响不大。如果你真的需要在 Node.js 里跑本地模型，那得用node-llama-cpp这类绑定库，但那是另一个话题了。

2.3 核心模块划分与数据流

paperclip的代码结构大致分为四层。最底层是LLM 适配层，封装了不同模型提供商的 API 调用，统一成chat(messages, tools)这样的接口。往上是Agent 核心层，负责维护对话历史、决定下一步是调工具还是回复用户、解析 LLM 返回的 tool call。再往上是工具层，每个工具是一个独立的模块，导出name、description、parameters和execute函数。最上层是服务层，用 Express 或 Fastify 暴露 HTTP 接口和 SSE 端点，React 前端通过它来驱动 agent。

数据流是这样的：用户在 React 界面输入一句话 → 前端 POST 到/api/chat→ 后端把消息加入历史 → 调用 LLM → LLM 返回要么是普通文本（直接推给前端），要么是 tool call（后端执行工具，把结果加入历史，再次调用 LLM）→ 循环直到 LLM 返回最终文本 → 通过 SSE 把每一步事件推给前端。这个循环就是 agent 的核心，paperclip把它写成了一个while循环加一个最大步数限制，防止无限循环。

注意：最大步数限制非常关键。我见过有人忘了设这个，结果 agent 在两个工具之间反复横跳，一晚上烧掉几十美元的 API 费用。paperclip默认设的是 10 步，你可以根据任务复杂度调整，但千万别设成无限。

3. 核心细节解析：Agent 循环、工具调用与状态管理

3.1 Agent 循环的每一步到底在干什么

很多人第一次看 agent 代码会觉得“不就是个 while 循环吗”，但真正写好这个循环需要处理很多边界情况。paperclip的循环大致是这样的：先把系统提示词和用户消息拼成 messages 数组，然后进入循环。每一轮先检查步数是否超限，然后调用 LLM。如果 LLM 返回的是普通文本，就把这条消息加入历史，推给前端，循环结束。如果返回的是 tool call，就解析出工具名和参数，找到对应的工具执行，把执行结果作为一条tool角色的消息加入历史，然后继续下一轮。

这里有几个细节值得展开。第一，工具执行结果需要截断。有些工具（比如读文件）可能返回几万字符，直接塞进 messages 会撑爆上下文窗口。paperclip的做法是设一个maxToolResultLength，超过就截断并加省略号。第二，工具执行可能抛异常，这时候不能直接让整个 agent 崩溃，而是要把错误信息作为工具结果返回给 LLM，让 LLM 自己决定是重试还是换方法。第三，并行工具调用。有些 LLM 支持一次返回多个 tool call，paperclip用Promise.all并行执行它们，但要注意如果工具之间有依赖关系就不能并行，这个得在工具定义里标注。

我自己的经验是，在循环里加一个“思考日志”非常有用。每次调用 LLM 之前，把当前的 messages 长度、步数、上一步的工具结果摘要打出来，这样调试的时候一眼就能看出 agent 卡在哪。paperclip默认没开这个日志，但代码里留了debug开关，打开后控制台会输出彩色日志，强烈建议开发阶段打开。

3.2 工具定义的设计哲学：让 LLM 看得懂比功能强大更重要

写 agent 工具最容易犯的错误是“功能写得很全，但 description 写得很烂”。LLM 决定调不调一个工具、怎么填参数，完全依赖你给的description和parametersschema。paperclip的工具定义遵循几个原则：description 用自然语言写清楚“这个工具做什么、什么时候用、什么时候不用”，而不是只写“读取文件”。比如读文件的工具，description 会写成“读取指定路径的文本文件内容。当用户要求查看某个文件、或者需要基于文件内容回答问题的时候使用。不要用于读取二进制文件或超过 1MB 的大文件。”

参数 schema 用 JSON Schema 格式，每个参数都要有description和type，枚举类型的参数要把所有可能值列出来。我试过把type写成string但实际传数字，LLM 有时候会猜错，所以类型一定要精确。另外，工具名用蛇形命名法（比如read_file、search_web），不要用驼峰，因为很多 LLM 在生成 tool call 时对下划线更敏感。

还有一个坑：工具数量不要太多。我一开始兴致勃勃地定义了二十多个工具，结果 LLM 经常选错，或者在一个简单任务上反复调用不相关的工具。后来砍到八个核心工具，准确率明显上升。经验值是5 到 10 个工具比较合适，超过 15 个就得考虑分组或者用路由层先筛选。

3.3 状态管理：React 端如何优雅地渲染流式输出

React 端的状态管理是这个项目里前端部分最值得学的。Agent 的输出是流式的，可能先来一段文本，然后来一个工具调用事件，然后工具结果，然后又是文本。如果用useState直接存一个字符串，每次事件都setState(prev => prev + chunk)，在快速流式输出时会导致大量重渲染，界面会卡。

paperclip的做法是用useReducer管理一个事件列表，每个事件是一个对象{type, content, timestamp}。渲染的时候根据事件类型决定显示成文本气泡、工具调用卡片还是错误提示。这样每次 dispatch 只是往数组里 push 一个对象，React 的 diff 成本低很多。另外，用useRef存 EventSource 实例，避免每次渲染都重新创建连接。清理函数里要记得eventSource.close()，否则组件卸载后连接还在，会造成内存泄漏。

我还发现一个小技巧：给事件列表加一个key用时间戳加随机数，不要用 index，因为流式输出时列表是不断增长的，用 index 做 key 会导致 React 复用错误的 DOM 节点，出现内容错位。这个坑我踩过，表现为工具调用的结果显示在了上一条文本气泡里，排查了半天才发现是 key 的问题。

4. 实操过程：从零跑通 paperclip 并改出第一个自定义工具

4.1 环境准备：Node.js 版本选择和安装避坑

paperclip要求 Node.js 18.20.4 LTS 或更高，我建议直接用 20.x 或 22.x 的 LTS 版本。为什么不用最新的 23.x？因为有些依赖（比如node-fetch的某些版本）在奇数版本上会有兼容性问题，而 LTS 版本经过更充分的测试。如果你在 CentOS 7.9 上部署，系统自带的 Node.js 可能是 10.x 甚至更老，需要先卸载再装。

安装步骤我列一下，以 CentOS 7.9 为例。先curl -fsSL https://rpm.nodesource.com/setup_20.x | bash -添加源，然后yum install -y nodejs。装完用node -v和npm -v确认版本。如果node -v显示的还是老版本，可能是 PATH 里有旧的二进制，用which node看一下路径，把旧的删掉或者调整 PATH 顺序。

注意：CentOS 7.9 的 glibc 版本比较老（2.17），Node.js 20.x 官方要求 glibc 2.28+，直接装可能会报GLIBC_2.28 not found。解决办法是用 Node.js 18.x，它对 glibc 的要求低一些，或者用 nvm 装一个预编译版本。我实测 18.20.4 在 CentOS 7.9 上能跑，20.x 需要额外处理。

Windows 和 macOS 用户直接去官网下载 LTS 安装包就行，一路下一步。macOS 如果用 Homebrew，brew install node@20然后brew link node@20。装完记得npm config set registry换成国内镜像，不然npm install会慢到怀疑人生。

4.2 项目初始化与依赖安装

Clone 项目之后，先看package.json里的engines字段确认 Node 版本要求。然后npm install，这一步可能会遇到几个问题。如果卡在node-gyp编译，说明某个依赖需要本地编译，CentOS 上要装gcc-c++和make，macOS 上要装 Xcode Command Line Tools。如果报ERESOLVE unable to resolve dependency tree，用npm install --legacy-peer-deps绕过，这是 npm 7+ 的严格 peer 依赖检查导致的，React 生态里很常见。

装完之后配置环境变量。项目根目录建一个.env文件，至少要有OPENAI_API_KEY或你用的其他 LLM 提供商的 key。如果用的是本地 Ollama，把LLM_BASE_URL设成http://localhost:11434/v1，LLM_MODEL设成你 pull 下来的模型名。不要把 key 提交到 git，.gitignore里确认有.env。

启动开发服务器：npm run dev。这个命令一般会同时启动后端（比如 3001 端口）和前端（比如 5173 端口）。打开浏览器访问前端地址，如果看到聊天界面就说明跑通了。如果前端报Failed to fetch，检查后端是否真的起来了，以及前端的 API 地址配置是否正确（有些项目用VITE_API_URL环境变量）。

4.3 手写一个自定义工具：以“查询当前时间”为例

跑通默认功能后，最有成就感的步骤就是加一个自己的工具。我以“查询当前时间”为例，因为逻辑简单，适合第一次练手。在tools目录下新建getCurrentTime.js，导出这样一个对象：

export default { name: 'get_current_time', description: '获取当前的日期和时间。当用户询问现在几点、今天几号、或者需要基于当前时间做计算时使用。', parameters: { type: 'object', properties: { timezone: { type: 'string', description: '时区，比如 Asia/Shanghai。不传则使用服务器本地时区。', }, }, required: [], }, async execute({ timezone }) { const now = new Date(); const options = { timeZone: timezone || undefined, hour12: false }; return now.toLocaleString('zh-CN', options); }, };

然后在工具注册的地方（通常是tools/index.js）import 进来，加到数组里。重启后端，在聊天框输入“现在几点了”，如果 agent 调用了这个工具并返回时间，就成功了。

这里有个细节：required数组如果为空，要写[]而不是省略，有些 LLM 对 schema 的完整性要求很严，缺字段会报错。另外execute函数必须是 async 的，即使里面没有 await，因为 agent 核心层用await调用它，返回非 Promise 会出问题。

4.4 前端接入 SSE 的完整代码与调试技巧

前端接收 SSE 的核心代码大概长这样：

const eventSource = new EventSource('/api/stream?sessionId=xxx'); eventSource.onmessage = (event) => { const data = JSON.parse(event.data); dispatch({ type: 'ADD_EVENT', payload: data }); }; eventSource.onerror = (err) => { console.error('SSE error', err); eventSource.close(); };

调试 SSE 有个很实用的技巧：在浏览器 DevTools 的 Network 面板里找stream请求，点进去看 EventStream 标签，能看到每一条推送的事件原文。如果前端没反应但这里能看到数据，说明是onmessage处理逻辑有问题；如果这里也没数据，那就是后端没推或者被代理拦截了。

还有一个常见问题：Nginx 反代 SSE 时需要关闭缓冲。默认 Nginx 会缓冲响应，导致 SSE 事件攒一批才发，前端看起来就是“卡很久然后突然蹦出一堆”。解决办法是在 location 配置里加proxy_buffering off;和proxy_cache off;，并且把proxy_read_timeout设大一点（比如 3600s），否则长连接会被断开。

5. 常见问题与排查技巧实录

5.1 Agent 不调用工具或反复调用同一个工具

这是最常见的问题，原因通常有三个。第一，工具 description 写得太模糊，LLM 不确定该不该用。解决办法是把 description 改得更具体，加上“当用户说 X 的时候使用”这样的触发条件。第二，系统提示词没有强调工具的使用。在 system message 里加一句“你可以使用以下工具来完成任务，当需要外部信息或执行操作时，优先考虑调用工具”，能明显提升调用率。第三，LLM 本身能力不够。小模型（比如 7B 参数）在工具调用上的准确率确实不如大模型，如果条件允许，换一个更强的模型试试。

反复调用同一个工具，通常是工具返回的结果没有让 LLM 满意。比如读文件工具返回了空字符串，LLM 以为没读到，就再读一次。解决办法是在工具返回里加上明确的状态，比如{ success: true, content: '...' }或{ success: false, error: '文件不存在' }，让 LLM 能区分“读到了空内容”和“读取失败”。

5.2 流式输出卡顿或内容错位

卡顿一般是 React 重渲染太频繁导致的。除了前面说的用useReducer，还可以用React.memo包裹消息气泡组件，只有当content变化时才重渲染。另外，不要在每个 chunk 都触发滚动到底部，用requestAnimationFrame节流一下，或者用scrollIntoView的behavior: 'smooth'但加一个 100ms 的防抖。

内容错位多半是 key 的问题，前面提过了。还有一个可能是事件顺序乱了。SSE 本身保证顺序，但如果你在前端用了setTimeout或者Promise异步处理事件，就可能打乱顺序。解决办法是在 reducer 里同步处理事件，不要在里面做异步操作。

5.3 工具执行超时或内存泄漏

工具执行超时通常是因为工具内部有网络请求或文件 IO 没有设超时。每个工具都应该有自己的超时机制，比如用Promise.race包一层，超过 30 秒就返回超时错误。paperclip在 agent 核心层也设了一个全局超时，但工具级别的超时更精细。

内存泄漏在长时间运行的 agent 上比较明显。主要来源是没有清理的 EventSource、没有取消的 fetch 请求、以及不断增长的 messages 数组。messages 数组要设一个上限，比如保留最近 50 条，超过就把最早的几条删掉（但 system message 要保留）。EventSource 在组件卸载时一定要 close。fetch 请求可以用AbortController来取消。

5.4 常见问题速查表

6. 一些不在文档里的实操心得

6.1 用环境变量切换 LLM 提供商

开发阶段我建议用本地 Ollama 跑一个小模型，省钱且响应快，适合调 UI 和工具逻辑。等逻辑稳定了，再切到远程的大模型做效果验证。paperclip的 LLM 适配层如果写得好，切换只需要改.env里的LLM_PROVIDER和对应的 key。如果项目没做这层抽象，你可以自己加一个简单的工厂函数，根据环境变量返回不同的 client 实例。

6.2 给 agent 加一个“中断”按钮

Agent 跑飞的时候，你肯定想立刻停下来。前端加一个按钮，点击时调用eventSource.close()并 POST 一个/api/abort给后端。后端收到 abort 请求后，设置一个标志位，agent 循环每轮检查这个标志位，如果为 true 就 break。这个功能在调试时能省很多时间和 API 费用。

6.3 日志要分级，不要一股脑输出

console.log用多了控制台会刷屏。建议用debug库或者自己封装一个简单的 logger，分debug、info、warn、error四级。开发时开debug，生产时只开warn以上。Agent 的每一步推理用debug，工具调用和结果用info，异常用error。这样出问题时能快速定位，平时也不会被噪音干扰。

6.4 工具执行结果尽量结构化

工具返回纯字符串虽然简单，但 LLM 解析起来容易出错。返回 JSON 字符串（比如JSON.stringify({status: 'ok', data: ...})）能让 LLM 更准确地理解结果。如果工具返回的是表格数据，可以转成 Markdown 表格再返回，LLM 对 Markdown 的解析能力比纯文本强很多。

6.5 定期清理 node_modules 和 lock 文件

Node.js 项目跑久了，node_modules里会积累各种版本的依赖，有时候会出现“明明代码没改但行为变了”的诡异问题。我一般每隔几周就rm -rf node_modules package-lock.json && npm install一次，保证依赖树干净。如果项目用了pnpm或yarn，同理清理对应的 lock 文件。

这个项目我后续还打算把工具调用做成插件化，支持从远程 URL 动态加载工具定义，这样就能在不重启服务的情况下扩展 agent 能力。另外 React 端的图表展示也值得优化，现在工具返回的数据只能看文本，如果能自动识别 JSON 并渲染成表格或图表，体验会好很多。这些等我踩完坑再另开一篇聊。