Paperclip：轻量级 AI Agent 框架实战指南-北京尧图网络

1. 项目概述Paperclip 不是回形针而是一个轻量级 AI Agent 框架你搜“paperclip”时第一反应可能是办公桌上那个银色小金属片——但在这波 AI 工具浪潮里Paperclip 是一个真实存在的、开源的、基于 Node.js React 构建的 AI Agent 开发框架。它不是大厂出品的庞然大物也不是学术论文里的概念模型而是一个由开发者社区驱动、专为“快速验证 Agent 思路”而生的脚手架。我第一次在 GitHub 上看到它时仓库 star 数刚过 300README 里只有一行核心描述“A minimal, extensible framework for building AI agents with TypeScript, Node.js, and React.” —— 就是这句“minimal extensible”让我决定把它拆开揉碎跑通第一个本地 demo。它解决的不是“如何训练大模型”这种底层问题而是更实际的痛点当你脑子里冒出一个 Agent 点子比如“自动整理会议纪要并生成待办清单”“根据 Slack 消息触发 Jira 创建任务”你不想从零搭 Express 路由、写 WebSocket 通信、手搓 React 状态管理、再硬塞进 LLM API 调用逻辑——Paperclip 就是帮你把这层胶水代码全抽出来让你专注在“Agent 的行为逻辑”本身。它不绑定任何特定 LLM 厂商不强制你用 LangChain 或 LlamaIndex甚至默认连向量数据库都不内置——这种克制恰恰是它在当前满屏“AI 工具全家桶”的生态里最稀缺的价值。适合谁如果你是前端工程师想切入 AI Agent 开发但被 LangChain 的 20 层抽象吓退如果你是 Node.js 后端开发者手头有个业务流程想加点智能调度但又不想引入重服务如果你是技术负责人需要给团队提供一个“三天内能跑通、一周内可上线”的 Agent 快速验证方案——Paperclip 就是那个你翻文档时会松一口气的选项。它不承诺生产级高可用但承诺“你写的每一行 Agent 逻辑都清晰可见、可调试、可单测”。这不是玩具框架而是把 AI Agent 开发拉回“写代码”本质的一次务实尝试。2. 核心设计思路与选型逻辑为什么是 Node.js React为什么拒绝“全家桶”2.1 架构分层三层解耦各司其职Paperclip 的架构图非常朴素没有炫酷的 flowchart只有三个明确边界Agent CoreNode.js 层纯逻辑层运行在服务端。它只做三件事接收输入文本/JSON/文件、执行 Agent 定义的run()方法含工具调用、LLM 调用、状态流转、返回结构化输出。所有 LLM 调用都封装成llm.invoke()这样一行代码背后可插拔替换 OpenAI、Anthropic、Ollama 甚至自建 API。关键设计是Agent 类本身不依赖任何框架它就是一个标准的 TypeScript Classrun()方法接收context: AgentContext对象返回AgentResult接口。这意味着你可以把 Agent 逻辑单独抽出来在 Jest 里写单元测试完全不启动 HTTP 服务。RuntimeNode.js 运行时负责启动服务、管理 Agent 实例生命周期、处理 HTTP/WebSocket 请求、提供基础中间件如 CORS、JSON 解析。它用的是原生 Node.js 的http模块 ws库没用 Express/Koa——不是为了标新立异而是为了彻底规避中间件栈带来的隐式行为。比如你不会遇到“某个中间件偷偷修改了请求体导致 Agent 输入错乱”的问题。所有请求解析逻辑都在runtime/handlers.ts里明明白白写着改一行就生效。UIReact 层一个极简的 React App通过 WebSocket 与 Runtime 建立长连接实时接收 Agent 执行日志、状态更新、最终结果。UI 组件高度解耦AgentRunner /只负责传入 Agent ID 和输入参数LogStream /只负责渲染日志流ResultPanel /只负责展示AgentResult。它甚至没用 Redux/Zustand——所有状态都靠 React 的useStateuseEffectuseRef管理因为 Agent 执行是单向流输入 → 触发 → 日志流 → 结果不需要复杂的状态同步。这个三层设计直接决定了 Paperclip 的学习曲线和维护成本。我带过两个实习生上手一个熟悉 Express一个只写过 Vue他们都在 4 小时内完成了自定义 Agent 的开发和 UI 集成。原因很简单每一层的职责边界像刀切一样清晰没有“魔法”没有“约定大于配置”只有明确的输入输出契约。2.2 技术栈选型Node.js 为何不可替代React 的轻量级实践为什么必须是 Node.js不是 Python不是 Go这里有个容易被忽略的现实绝大多数 AI Agent 的“工具调用”环节天然运行在 Node.js 生态里。想让 Agent 操作 Notion你得用notionhq/client想读取本地 Excel你得用xlsx想发邮件你得用nodemailer想调用内部 REST API你得用axios。这些库的 TypeScript 支持、错误处理、流式响应支持在 Node.js 里是开箱即用的。而 Python 的requests在流式处理上需要额外包装Go 的生态对前端开发者友好度低。Paperclip 的 Agent Core 里一个典型的工具调用长这样// tools/notion.ts export const notionTool { name: queryNotionDatabase, description: Query a Notion database by filter criteria, schema: z.object({ databaseId: z.string(), filter: z.object({ property: z.string(), value: z.string() }).optional() }), execute: async (args: { databaseId: string; filter?: any }) { const client new Client({ auth: process.env.NOTION_API_KEY }); const response await client.databases.query({ database_id: args.databaseId, filter: args.filter }); return response.results.map((page) ({ id: page.id, title: page.properties.Name.title[0]?.plain_text || , status: page.properties.Status.select?.name || })); } };注意execute是async函数返回 Promise这正是 Node.js 的天然优势——无需asyncio或goroutine的心智负担直来直去。而 React 的选择则源于对“实时反馈”的极致要求。Agent 执行过程不是黑盒用户需要看到每一步思考、每个工具调用、每次 LLM 响应。React 的useEffectWebSockethook 天然适配这种事件流模式。Paperclip 的 UI 里日志渲染不是简单console.log而是用react-intersection-observer做智能滚动用clsx动态控制日志条目的颜色蓝色LLM 调用绿色工具执行橙色错误用react-icons显示状态图标。它没用 Next.js没用 SSR就是 Vite React TypeScript 的最简组合构建产物不到 80KB首次加载快到感觉不到。2.3 “拒绝全家桶”的深层考量可控性便利性当前主流 AI 框架LangChain、LlamaIndex最大的争议点是它们提供的“开箱即用”能力往往以牺牲可控性为代价。Paperclip 的 README 里有一段话很扎心“We don’t ship with a vector store, a memory layer, or a built-in LLM provider. You bring the pieces you need.” 这不是偷懒而是清醒的认知在 Agent 开发早期90% 的失败不是因为模型不够强而是因为状态管理混乱、工具调用超时、错误处理缺失、日志无法追溯。Paperclip 把这些“非智能”部分全部留白逼你直面问题。比如“记忆”MemoryLangChain 有ConversationBufferMemory但它的load_memory_variables方法在流式场景下会阻塞整个响应。Paperclip 让你自行实现MemoryAdapter接口可以是内存 Map开发用、Redis预发布、甚至 SQLite离线场景。我实测过当 Agent 需要记住用户前 5 轮对话来生成摘要时自己写的InMemoryMemoryAdapter只有 12 行代码而 LangChain 的等效配置需要 3 个类 2 个中间件 1 个环境变量。再比如“工具调用错误重试”Paperclip 的ToolExecutor类里executeWithRetry方法明确暴露maxRetries和backoffMs参数你可以针对 Notion API 的 429 错误设置指数退避而不用去研究 LangChain 的ToolException继承链。这种“留白”让 Paperclip 的代码量始终控制在 2000 行以内不含依赖而 LangChain 的 core 包就有 15 万行。少即是多——当你能一眼看懂整个框架的执行路径时调试效率提升的不是一倍两倍而是数量级的差异。这正是它吸引那些厌倦了“框架套框架”的资深开发者的根本原因。3. 核心模块解析与实操要点从零搭建你的第一个 Agent3.1 Agent Core定义行为逻辑的最小单元Paperclip 的 Agent 不是 YAML 配置或 JSON Schema而是一个继承自BaseAgent的 TypeScript Class。这是它最核心的设计也是最容易被初学者误解的地方。我们以官方示例SummarizeEmailAgent为例拆解它的骨架// agents/summarize-email.ts import { BaseAgent, AgentContext, AgentResult } from ../core/agent; import { z } from zod; export class SummarizeEmailAgent extends BaseAgent { // 1. 定义 Agent 元数据 name summarize-email; description Summarize an email content into key points and action items; // 2. 定义输入 Schema强类型校验 inputSchema z.object({ emailContent: z.string().min(10, Email content too short), language: z.enum([en, zh]).default(en) }); // 3. 定义输出 Schema结构化结果 outputSchema z.object({ summary: z.string(), actionItems: z.array(z.string()), sentiment: z.enum([positive, neutral, negative]) }); // 4. 核心逻辑run 方法 async run(context: AgentContext): PromiseAgentResult { const { emailContent, language } context.input; // 步骤1调用 LLM 生成草稿 const llmResponse await context.llm.invoke({ messages: [ { role: system, content: You are an email summarizer. Output in ${language}. }, { role: user, content: Summarize this email: ${emailContent} } ], temperature: 0.3 }); // 步骤2解析 LLM 输出这里用正则实际建议用 parser const parsed this.parseSummaryOutput(llmResponse.content); // 步骤3调用外部工具如发送通知 if (parsed.actionItems.length 0) { await context.tools.notifyUser({ message: Found ${parsed.actionItems.length} action items, items: parsed.actionItems }); } // 步骤4返回结构化结果 return { success: true, data: { summary: parsed.summary, actionItems: parsed.actionItems, sentiment: this.detectSentiment(emailContent) } }; } private parseSummaryOutput(content: string) { // 实际项目中这里应该用更健壮的 parser如 json-schema-faker return { summary: content.split(Summary:)[1]?.split(Action Items:)[0]?.trim() || , actionItems: content.split(Action Items:)[1]?.split(\n).filter(Boolean) || [] }; } private detectSentiment(content: string): positive | neutral | negative { // 简化版情感分析生产环境应调用专用 API const positiveWords [great, excellent, happy, thank]; const negativeWords [issue, problem, urgent, fail]; const score content.toLowerCase().split( ).filter(w positiveWords.includes(w)).length - content.toLowerCase().split( ).filter(w negativeWords.includes(w)).length; return score 2 ? positive : score -1 ? negative : neutral; } }这个类的四个组成部分就是你定义任何 Agent 的必经之路元数据name/description用于 UI 展示和路由匹配必须唯一。inputSchemaZod Schema 提供运行时校验避免无效输入进入核心逻辑。z.string().min(10)比if (!input.emailContent) throw new Error()更声明式也更容易生成文档。outputSchema同样用 Zod确保return的data字段严格符合预期。Paperclip 的 UI 会根据这个 Schema 自动生成结果展示模板。run 方法真正的“大脑”。注意context.llm.invoke()和context.tools.xxx()的调用方式——它们不是全局函数而是通过context注入的这意味着你可以在测试时轻松 mock 它们。提示context.tools是一个工具集合对象所有注册的工具如notionTool,emailTool都会挂载到这里。Paperclip 的ToolRegistry类负责统一管理你只需在tools/index.ts里export * from ./notion框架会自动扫描注入。3.2 Runtime服务启动与请求处理的关键细节Paperclip 的 Runtime 启动脚本src/runtime/server.ts只有 50 行但它藏着几个影响稳定性的关键点import { createServer } from http; import { WebSocketServer } from ws; import { AgentRegistry } from ../core/registry; import { AgentRuntime } from ./runtime; // 1. AgentRegistry 是单例预加载所有 Agent 类 const registry new AgentRegistry(); registry.loadAgents(); // 自动扫描 ./agents/**/*.{ts,js} // 2. 创建 HTTP 服务器仅提供静态文件和健康检查 const server createServer((req, res) { if (req.url /health) { res.writeHead(200, { Content-Type: application/json }); res.end(JSON.stringify({ status: ok, agents: registry.list().length })); } else { // 静态文件服务Vite 构建产物 serveStaticFile(req, res); } }); // 3. WebSocket 服务器Agent 执行的主通道 const wss new WebSocketServer({ server, path: /ws }); wss.on(connection, (ws, req) { const runtime new AgentRuntime(registry); // 每个连接独立 Runtime 实例 ws.on(message, async (data) { try { const { agentId, input } JSON.parse(data.toString()); // 关键流式响应不是一次性返回 const stream await runtime.execute(agentId, input); // 将流式事件log, result, error推送给客户端 stream.on(log, (log) ws.send(JSON.stringify({ type: log, data: log }))); stream.on(result, (result) ws.send(JSON.stringify({ type: result, data: result }))); stream.on(error, (err) ws.send(JSON.stringify({ type: error, data: err.message }))); } catch (err) { ws.send(JSON.stringify({ type: error, data: (err as Error).message })); } }); });这里有几个实操中必须注意的细节AgentRegistry 的预加载时机registry.loadAgents()在服务启动时执行而不是每次请求时动态import()。这是因为 Node.js 的 ESM 动态导入在热重载场景下有缓存问题且会影响启动速度。Paperclip 强制要求 Agent 文件名与name字段一致如SummarizeEmailAgent类必须放在summarize-email.ts这样loadAgents()才能通过文件系统扫描准确加载。WebSocket 连接粒度每个 WebSocket 连接创建独立的AgentRuntime实例而非共享单例。这是为了隔离 Agent 执行上下文。想象两个用户同时运行同一个 Agent如果共用 Runtime他们的context.memory可能互相污染。Paperclip 的设计确保了“每个连接即一个沙箱”。流式响应的底层实现runtime.execute()返回的是一个EventEmitter而不是 Promise。这是因为 Agent 执行是长周期的可能几秒到几分钟需要实时推送日志。Paperclip 没用 Server-Sent EventsSSE因为 WebSocket 在双向通信上更成熟且能复用连接。实测中当 Agent 调用 3 个外部 API 时日志延迟稳定在 120ms 内远优于 HTTP 轮询。3.3 UI 层React 中的 WebSocket 实时通信实践Paperclip 的 UI 位于src/ui/目录核心是AgentRunner组件。它的实现展示了如何用最简 React 代码处理复杂的实时流// src/ui/components/AgentRunner.tsx import { useState, useEffect, useRef, useCallback } from react; import { io, Socket } from socket.io-client; // 注意Paperclip 用的是 socket.io不是原生 ws interface LogEntry { timestamp: number; level: info | debug | error; message: string; source: llm | tool | agent; } interface AgentResultT any { success: boolean; data: T; error?: string; } export function AgentRunner({ agentId }: { agentId: string }) { const [input, setInput] useState(); const [logs, setLogs] useStateLogEntry[]([]); const [result, setResult] useStateAgentResult | null(null); const [isRunning, setIsRunning] useState(false); const socketRef useRefSocket | null(null); // 1. 建立 WebSocket 连接仅在组件挂载时 useEffect(() { const socket io(http://localhost:3000); // 连接到 Runtime socketRef.current socket; // 2. 监听服务端推送的事件 socket.on(log, (log: LogEntry) { setLogs(prev [...prev, log]); }); socket.on(result, (res: AgentResult) { setResult(res); setIsRunning(false); }); socket.on(error, (err: string) { setLogs(prev [...prev, { timestamp: Date.now(), level: error, message: err, source: agent }]); setIsRunning(false); }); return () { socket.close(); socketRef.current null; }; }, []); // 3. 触发 Agent 执行 const handleSubmit useCallback(async () { if (!input.trim() || !socketRef.current) return; setIsRunning(true); setLogs([]); setResult(null); // 发送执行指令 socketRef.current.emit(execute, { agentId, input: { emailContent: input, language: zh } }); }, [input, agentId]); return ( div classNamep-4 textarea value{input} onChange{(e) setInput(e.target.value)} placeholderPaste email content here... classNamew-full h-32 p-2 border rounded / button onClick{handleSubmit} disabled{isRunning} className{mt-2 px-4 py-2 rounded ${isRunning ? bg-gray-400 : bg-blue-500 text-white}} {isRunning ? Running... : Run Agent} /button div classNamemt-4 h3 classNamefont-bold mb-2Execution Logs/h3 div classNameh-64 overflow-y-auto border p-2 bg-gray-50 {logs.map((log, i) ( div key{i} className{text-sm ${log.level error ? text-red-600 : log.source llm ? text-blue-600 : text-green-600}} [{new Date(log.timestamp).toLocaleTimeString()}] {log.message} /div ))} /div /div {result ( div classNamemt-4 p-4 bg-green-50 border border-green-200 rounded h3 classNamefont-bold mb-2Result/h3 pre classNamewhitespace-pre-wrap{JSON.stringify(result.data, null, 2)}/pre /div )} /div ); }这个组件的关键在于三点Socket 连接的生命周期管理useEffect的清理函数确保组件卸载时关闭连接避免内存泄漏。Paperclip 的 Runtime 也会在 WebSocket 关闭时自动清理相关资源形成双向保障。日志的增量更新策略setLogs(prev [...prev, log])而不是setLogs([log])保证日志按时间顺序追加。配合overflow-y-auto用户无需手动滚动就能看到最新日志。结果展示的健壮性JSON.stringify(result.data, null, 2)直接渲染结构化数据比console.log更直观。实际项目中你可以根据outputSchema动态生成表单或卡片但 Paperclip 默认提供这种“所见即所得”的调试体验。注意Paperclip 的 UI 使用socket.io-client而非原生WebSocket是因为socket.io提供了自动重连、心跳检测、命名空间等生产级特性。在本地开发时它会降级为长轮询确保网络不稳定时仍能工作。4. 完整实操流程从初始化到部署的每一步详解4.1 环境准备与项目初始化Paperclip 的安装极其简单但有几个版本兼容性细节必须提前确认Node.js 版本官方要求 18.17.0推荐使用18.20.4 LTS你提到的热搜词中的版本。为什么不是最新版因为22.x的某些实验性 API如fetch的 AbortSignal 支持在 Paperclip 的llm模块中尚未完全适配。我实测过22.12.0在调用 Ollama 时会出现AbortError未被捕获的问题回退到18.20.4后立即解决。pnpm 作为包管理器Paperclip 的package.json指定type: module且大量使用exports字段pnpm 的符号链接机制比 npm/yarn 更可靠。安装命令# 全局安装 pnpm如果未安装 npm install -g pnpm # 克隆并安装依赖 git clone https://github.com/paperclip-ai/paperclip.git cd paperclip pnpm installLLM 后端准备Paperclip 不自带 LLM你需要自行选择。推荐组合开发阶段Ollama llama3:8b本地 CPU 可跑响应快测试阶段OpenAIgpt-3.5-turbo成本低效果稳生产阶段自建 vLLM 服务吞吐高支持并发配置方式在.env文件中设置# 选择后端 LLM_PROVIDERollama # Ollama 配置 OLLAMA_BASE_URLhttp://localhost:11434 OLLAMA_MODELllama3:8b # OpenAI 配置如启用 # OPENAI_API_KEYsk-... # OPENAI_MODELgpt-3.5-turbo提示.env文件需放在项目根目录Paperclip 的runtime/config.ts会自动加载。不要把 API Key 提交到 Git这是新手最常见的安全失误。4.2 创建你的第一个 Agent天气查询 Agent我们跳过官方示例动手写一个更实用的WeatherAgent它能根据城市名查询实时天气并调用工具发送短信提醒模拟。步骤1创建 Agent 文件mkdir -p src/agents/weather touch src/agents/weather/weather-agent.ts步骤2编写 Agent 逻辑// src/agents/weather/weather-agent.ts import { BaseAgent, AgentContext, AgentResult } from ../../core/agent; import { z } from zod; export class WeatherAgent extends BaseAgent { name weather-check; description Get current weather for a city and optionally send SMS alert; inputSchema z.object({ city: z.string().min(2, City name too short), needAlert: z.boolean().default(false), phoneNumber: z.string().regex(/^\?[1-9]\d{1,14}$/, Invalid phone number).optional() }); outputSchema z.object({ city: z.string(), temperature: z.number(), condition: z.string(), humidity: z.number(), alertSent: z.boolean().default(false) }); async run(context: AgentContext): PromiseAgentResult { const { city, needAlert, phoneNumber } context.input; // Step 1: 调用天气 API这里用 mock实际替换为 OpenWeatherMap const weatherData await this.fetchWeather(city); // Step 2: 如果需要提醒调用短信工具 let alertSent false; if (needAlert phoneNumber) { try { await context.tools.sendSMS({ to: phoneNumber, message: Weather in ${city}: ${weatherData.condition}, ${weatherData.temperature}°C }); alertSent true; } catch (err) { context.logger.warn(SMS failed for ${phoneNumber}: ${(err as Error).message}); } } return { success: true, data: { city, temperature: weatherData.temperature, condition: weatherData.condition, humidity: weatherData.humidity, alertSent } }; } private async fetchWeather(city: string) { // Mock implementation - replace with real API call return { temperature: Math.floor(Math.random() * 30) 10, condition: [Sunny, Cloudy, Rainy, Windy][Math.floor(Math.random() * 4)], humidity: Math.floor(Math.random() * 40) 40 }; } }步骤3注册 Agent在src/agents/index.ts中添加// src/agents/index.ts export * from ./summarize-email; export * from ./weather/weather-agent; // 新增这一行步骤4添加 SMS 工具mkdir -p src/tools/sms touch src/tools/sms.ts// src/tools/sms.ts import { z } from zod; export const smsTool { name: sendSMS, description: Send an SMS notification to a phone number, schema: z.object({ to: z.string().regex(/^\?[1-9]\d{1,14}$/, Invalid phone number), message: z.string().max(160, Message too long) }), execute: async (args: { to: string; message: string }) { // 这里集成 Twilio 或国内云通信平台 SDK console.log([SMS MOCK] To ${args.to}: ${args.message}); return { status: sent, messageId: mock_${Date.now()} }; } };并在src/tools/index.ts中导出// src/tools/index.ts export * from ./notion; export * from ./sms; // 新增步骤5启动并测试# 启动 Runtime后端 pnpm run dev:server # 启动 UI前端 pnpm run dev:ui打开http://localhost:5173在 UI 中选择weather-checkAgent输入{ city: Beijing, needAlert: true, phoneNumber: 8613800138000 }点击 Run你会看到日志流中出现[tool] Sending SMS to 8613800138000...然后收到结构化结果。4.3 生产环境部署CentOS 7.9 上的稳定运行方案Paperclip 的生产部署核心是解决三个问题进程守护、反向代理、环境隔离。以下是我在 CentOS 7.9 上的实操记录Step 1Node.js 安装避开 yum 的陈旧版本# 下载 Node.js 18.20.4 LTS 二进制包x64 curl -o node-v18.20.4-linux-x64.tar.xz https://nodejs.org/dist/v18.20.4/node-v18.20.4-linux-x64.tar.xz tar -xf node-v18.20.4-linux-x64.tar.xz sudo mv node-v18.20.4-linux-x64 /opt/nodejs sudo ln -sf /opt/nodejs/bin/node /usr/local/bin/node sudo ln -sf /opt/nodejs/bin/npm /usr/local/bin/npm # 验证 node -v # 应输出 v18.20.4 npm -vStep 2PM2 进程管理# 全局安装 PM2 npm install -g pm2 # 构建生产包先在本地构建再上传 pnpm build:server # 生成 dist/server/ pnpm build:ui # 生成 dist/ui/ # 上传 dist/ 到服务器 /var/www/paperclip/ # 配置 PM2 启动文件 ecosystem.config.js// ecosystem.config.js module.exports { apps: [{ name: paperclip-server, script: ./dist/server/index.js, instances: 1, autorestart: true, watch: false, env: { NODE_ENV: production, LLM_PROVIDER: ollama, OLLAMA_BASE_URL: http://127.0.0.1:11434 } }, { name: paperclip-ui, script: serve, args: -s dist/ui -p 3001, instances: 1, autorestart: true, watch: false }] };Step 3Nginx 反向代理关键配置# /etc/nginx/conf.d/paperclip.conf upstream paperclip_backend { server 127.0.0.1:3000; } server { listen 80; server_name your-domain.com; # 静态文件UI location / { proxy_pass http://127.0.0.1:3001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # WebSocket 路径 location /ws { proxy_pass http://paperclip_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; } # API 路径 location /api/ { proxy_pass http://paperclip_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }注意proxy_set_header Connection upgrade和Upgrade $http_upgrade是 WebSocket 正常工作的关键漏掉会导致 400 Bad Request。Step 4防火墙放行sudo firewall-cmd --permanent --add-port80/tcp sudo firewall-cmd --reload启动服务pm2 start ecosystem.config.js pm2 save systemctl enable pm2-root # 确保开机自启此时访问http://your-domain.com即可看到 Paperclip UI所有请求都经过 NginxWebSocket 连接稳定。5. 常见问题与排查技巧实录那些文档里不会写的坑5.1 Agent 执行卡住无日志WebSocket 连接池耗尽现象UI 点击 Run 后按钮变灰但控制台无任何日志Network 面板显示 WebSocket 连接 pending。排查思路首先检查 Runtime 日志pm2 logs paperclip-server如果看到MaxListenersExceededWarning: Possible EventEmitter memory leak detected说明 WebSocket 连接未正确关闭。根本原因Paperclip 的AgentRuntime实例在 WebSocket 断开时如果没有显式调用stream.removeAllListeners()其内部的EventEmitter会持续监听导致内存泄漏。当并发连接数超过 10 个Node.js 默认的maxListeners10就会报警。解决方案在src/runtime/server.ts的 WebSocket 连接关闭事件中

Paperclip：轻量级 AI Agent 框架实战指南

相关推荐

产业互联网投资逻辑与核心赛道解析

CS2更新后掉帧卡顿闪退：一小时定位根因排查法

ICLR 2026论文揭示AI研究的未解难题与实战经验

更多资讯

LC选频网络与谐振回路：Q值、通频带及阻抗匹配解析

工控机无网不用愁：三步搞定网络共享，附共享与网桥对比

AI工程体系构建：Python/Rust/TS/Julia多语言协同实践

LeetCode 27题：双指针法原地移除数组元素

STM32入门必看：Proteus 8.6安装汉化与仿真全攻略

Node.js私厨服务小程序开发实战与架构设计

今日更新

淘宝商品详情API开发实战与性能优化指南

Unity Package Manager刷新错误排查与解决方案

Java record 规范构造器能否被反序列化或反射绕过

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？