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 前端作为“仪表盘”通过 SSEServer-Sent Events或 WebSocket 接收后端的实时事件流把 agent 的每一步都渲染出来。这个架构选择背后有一个很实际的考量SSE 比 WebSocket 更简单对于 agent 这种“服务器单向推送状态”的场景足够用而且 SSE 天然支持断线重连浏览器兼容性也好。当然如果你需要双向通信比如用户在 agent 执行中途插话那就得换成 WebSocketpaperclip的代码里也留了切换的接口。我实测下来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 callpaperclip用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.17Node.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 如果用 Homebrewbrew install node20然后brew link node20。装完记得npm config set registry换成国内镜像不然npm install会慢到怀疑人生。4.2 项目初始化与依赖安装Clone 项目之后先看package.json里的engines字段确认 Node 版本要求。然后npm install这一步可能会遇到几个问题。如果卡在node-gyp编译说明某个依赖需要本地编译CentOS 上要装gcc-c和makemacOS 上要装 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/v1LLM_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.jsimport 进来加到数组里。重启后端在聊天框输入“现在几点了”如果 agent 调用了这个工具并返回时间就成功了。这里有个细节required数组如果为空要写[]而不是省略有些 LLM 对 schema 的完整性要求很严缺字段会报错。另外execute函数必须是 async 的即使里面没有 await因为 agent 核心层用await调用它返回非 Promise 会出问题。4.4 前端接入 SSE 的完整代码与调试技巧前端接收 SSE 的核心代码大概长这样const eventSource new EventSource(/api/stream?sessionIdxxx); 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 常见问题速查表问题现象可能原因排查方法解决方案前端报 Failed to fetch后端没启动或端口不对检查后端控制台和VITE_API_URL启动后端修正 API 地址SSE 连接建立后无数据代理缓冲或后端未推事件DevTools Network 看 EventStream关闭 Nginx 缓冲检查后端推送逻辑Agent 不调用工具description 模糊或模型能力不足看 LLM 返回的原始内容改 description换更强模型工具调用参数错误schema 类型不精确打印 LLM 返回的 tool call精确 schema加枚举值流式输出卡顿重渲染太频繁React DevTools ProfileruseReducer React.memo长时间运行后崩溃内存泄漏看 Node 进程内存曲线清理 EventSource限制 messages 长度CentOS 上安装失败glibc 版本过低ldd --version用 Node 18.x 或 nvm 预编译版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 并渲染成表格或图表体验会好很多。这些等我踩完坑再另开一篇聊。