1. 项目概述：Paperclip 不是回形针，而是一个正在悄悄改变前端开发范式的 AI Agent 框架

你搜“paperclip”时，第一反应可能是办公桌抽屉里那枚银色小金属——但最近半年，在 GitHub Trending 和 React 社区讨论帖里，“Paperclip”出现的频率，已经远超文具品类。它不是 UI 组件库，不是状态管理工具，更不是又一个“React + Node.js”的脚手架套壳。它是一个以 React 为宿主、Node.js 为执行引擎、专为构建可调试、可追踪、可组合的 AI Agent 而生的开源框架。核心关键词 paperclip、Node.js、React、AI agents、open-source 并非随意堆砌：paperclip 是项目名，Node.js 是运行时底座（负责模型调用、工具执行、上下文持久化），React 是交互层与可视化层（Agent 的“大脑界面”），AI agents 是目标产物（不是单个聊天机器人，而是能拆解任务、调用工具、自我反思、多步协作的智能体），open-source 是它的基因——所有设计决策、调试协议、Agent 编排逻辑全部公开，连调试器源码都带完整 TypeScript 类型定义。

我第一次在掘金看到 Paperclip 的 Demo 视频时，没点开代码就关掉了——因为太像玩具：一个 React 页面里拖拽几个“思考块”，连线生成“搜索→摘要→翻译→格式化”流程，点击运行，右侧实时输出 token 流和每一步的中间结果。但两周后，我用它重写了团队内部一个需要人工核对 3 类 API 返回值、再填入 Excel 模板的周报生成脚本。原来要写 200 行 Python + 80 行 JS 前端 + 1 个 cron job，现在变成 47 行 React 组件 + 3 个 Node.js 工具函数，部署在公司内网 Node.js 服务上，前端直接嵌入现有管理后台。最关键是：当某天第三方 API 字段变更导致 Agent 报错时，我不用翻日志、不用查 traceID，打开浏览器开发者工具里的 Paperclip Debug Panel，就能看到错误发生在“摘要”步骤的第 3 次重试时，输入是原始 JSON，输出是空字符串，立刻定位到是模型提示词里漏写了字段容错说明。这种可观察性（observability）不是附加功能，而是 Paperclip 的底层契约——它把 AI Agent 从黑盒变成了透明流水线。

适合谁？如果你正被这些场景困扰：React 项目里硬塞一个 chatbot SDK，结果业务逻辑和 AI 逻辑耦合到无法单元测试；Node.js 后端写了一堆工具函数，却只能靠 curl 或 Postman 手动触发，没法让 Agent 自动编排；面试官问“如何设计一个能自动处理报销单的 Agent”，你只能答“用 LangChain + OpenAI”，却说不清状态怎么存、错误怎么回滚、用户怎么干预。那么 Paperclip 就是为你准备的。它不替代 LangChain 或 LlamaIndex，而是给你一套 React + Node.js 原生的、零魔法的 Agent 构建协议。接下来，我会带你从零开始，真正搞懂它为什么敢叫“Paperclip”——不是因为它轻量，而是因为它像回形针一样，把散落的 React 界面、Node.js 工具、LLM 调用、用户意图，牢牢固定在一个可理解、可调试、可协作的结构里。

2. 核心架构设计：为什么必须是 React + Node.js 双 Runtime？拆解 Paperclip 的三层契约

Paperclip 的架构不是“前端调后端，后端调大模型”的传统分层，而是基于“Agent 即组件（Agent-as-Component）”的全新契约。这个契约由三层构成，每一层都决定了它为何必须同时依赖 React 和 Node.js，且无法被单一框架替代。

2.1 第一层：React 作为 Agent 的“神经突触”——UI 即控制平面

在 Paperclip 里，React 组件不是展示层，而是 Agent 的控制平面（Control Plane）。每个<AgentNode>组件对应一个可执行的 Agent 步骤，比如<SearchTool />、<SummarizeStep />、<TranslateStep />。它们不是纯函数组件，而是继承自BaseAgentNode的类组件，自带execute()、retry()、interrupt()方法。关键在于：这些方法的调用时机、参数、返回值，全部通过 React 的 props 和 state 暴露给开发者。例如：

// src/agents/ReportGenerator.tsx import { BaseAgentNode } from 'paperclip'; import { searchAPI, formatExcel } from '../tools'; export class ReportGenerator extends BaseAgentNode { // 这个 state 不是 UI 状态，而是 Agent 的“工作记忆” state = { rawResults: [] as any[], summary: '', translatedSummary: '', excelBuffer: null as Buffer | null, }; async execute() { // 步骤1：调用 Node.js 工具 const data = await this.callTool('searchAPI', { query: this.props.query }); // 步骤2：触发下一个 Agent 节点（React 内部调度） this.setState({ rawResults: data }); this.emit('next', { step: 'summarize', input: data }); } }

这里没有fetch，没有axios，this.callTool()是 Paperclip 提供的跨 Runtime 调用桥接。React 组件在这里承担了三重角色：状态容器（存储中间结果）、事件总线（emit/subscribe 控制流）、可视化代理（渲染每个步骤的输入/输出/耗时）。为什么必须是 React？因为只有 React 的声明式更新、Hooks 的细粒度状态管理、以及 DevTools 的时间旅行调试能力，才能支撑 Agent 复杂的状态变迁。你无法用 Vue 的ref或 Svelte 的$:实现同等粒度的“步骤级重放”——Paperclip 的 Debug Panel 能让你点击任意历史步骤，重新执行并查看其独立上下文，这依赖 React 的 Fiber 架构对更新优先级的精确控制。

2.2 第二层：Node.js 作为 Agent 的“脊髓反射弧”——工具即原子能力

Node.js 在 Paperclip 中不是“后端 API”，而是 Agent 的执行脊髓（Execution Spine）。所有工具函数（Tool Function）必须部署在 Node.js 环境中，原因有三：
第一，安全隔离。LLM 生成的工具调用指令（如{ "name": "downloadFile", "args": { "url": "https://evil.com/malware.exe" } }）必须在沙箱中执行。Paperclip 默认使用vm2沙箱运行工具，而 vm2 仅支持 Node.js 环境。你在 React 里写的callTool('downloadFile')，实际是通过 WebSocket 发送到本地 Node.js 服务，由沙箱解析指令、校验参数白名单、执行下载、返回结果。
第二，IO 密集型操作。文件读写、数据库查询、HTTP 请求这些阻塞操作，在浏览器中会冻结 UI。Paperclip 的formatExcel工具调用的是exceljs库，它需要完整的 Node.jsfs模块和streamAPI，浏览器环境无法提供。
第三，模型调用一致性。Paperclip 推荐使用@paperclip/llm-client，它封装了 OpenAI、Anthropic、Ollama 等多种后端，但所有请求都走 Node.js 的https模块（而非浏览器fetch），避免 CORS、请求头限制、token 泄露等前端固有问题。

提示：Paperclip 的 Node.js 服务不是 Express/Koa 应用，而是一个极简的http.Server+ WebSocket 服务器。它只做三件事：接收工具调用请求、执行沙箱工具、推送执行日志到前端。启动代码仅 32 行，你甚至可以用node server.js直接运行，无需npm start。这是刻意为之的设计——降低学习成本，让开发者聚焦 Agent 逻辑，而非 Web 框架配置。

2.3 第三层：Paperclip Core 作为“突触间隙”——协议即胶水

React 和 Node.js 如何通信？不是 REST API，不是 GraphQL，而是 Paperclip 定义的Agent Execution Protocol（AEP）。这是一个基于 WebSocket 的二进制协议，消息结构如下：

这个协议是 Paperclip 的灵魂。它让 React 组件能像调用本地方法一样callTool()，而实际执行在 Node.js；让 Node.js 工具能通过emit('debug', { step: 'summarize', tokens: 128 })向前端推送调试信息，前端自动渲染在 Debug Panel 里。协议的精简性（仅 4 个字段）保证了低延迟——实测在本地网络，一次工具调用平均耗时 12ms（含序列化/反序列化），远低于 HTTP 的 80ms+。这也是为什么 Paperclip 能做到“实时 token 流”：LLM 返回的每个 token 都被打包成DEBUG_LOG消息，通过 WebSocket 推送，前端用requestIdleCallback渲染，避免阻塞主线程。

3. 核心细节解析：从零搭建一个可调试的 AI Agent，详解 5 个关键环节

搭建 Paperclip Agent 不是配置一堆 YAML 文件，而是编写可测试、可复用的 TypeScript 类。下面以“自动分析 GitHub Issue 并生成修复建议”为例，详解从初始化到上线的 5 个关键环节，每个环节都包含你查文档找不到的实操细节。

3.1 环境初始化：Node.js 版本与 React 项目结构的隐性约束

Paperclip 对 Node.js 版本有明确要求：必须 >= 18.17.0，推荐 20.11.1 LTS。这不是随便定的——它依赖 Node.js 18+ 的WebStreamAPI 实现 token 流式传输，以及vm.Module的增强沙箱能力。如果你用 Node.js 16，vm2会降级为不安全的eval，Paperclip 启动时会抛出ERR_PAPERCLIP_VM_INSECURE错误。安装命令不是npm install paperclip，而是：

# 必须全局安装 CLI 工具（用于生成模板） npm install -g @paperclip/cli # 在现有 React 项目根目录执行（注意：不是 create-react-app，必须是 Vite 或 Next.js） paperclip init --framework react-vite # 这会生成： # - src/agents/ # Agent 类存放目录 # - src/tools/ # Node.js 工具函数目录 # - server/ # Node.js 执行服务 # - paperclip.config.ts # 核心配置

注意：Paperclip 不支持 Create React App（CRA）。因为 CRA 的 webpack 配置会污染globalThis，导致 vm2 沙箱失效。如果你的项目是 CRA，必须先迁移至 Vite。迁移只需 3 步：1)npm create vite@latest新建 Vite 项目；2) 复制 src 文件；3) 在vite.config.ts中添加define: { 'process.env': {} }。实测迁移耗时 < 15 分钟，但能避免后续所有沙箱问题。

3.2 Agent 类编写：状态管理、错误恢复与用户干预的三位一体设计

Paperclip 的 Agent 类不是简单继承，而是遵循Stateful Agent Pattern。以IssueAnalyzer为例：

// src/agents/IssueAnalyzer.tsx import { BaseAgentNode, ToolCallResult } from 'paperclip'; export class IssueAnalyzer extends BaseAgentNode { // 【关键1】状态必须用 interface 显式定义，否则 TS 类型推导失败 state = { issueContent: '', codeSnippets: [] as string[], errorCount: 0, lastError: '' as string, }; // 【关键2】execute 方法必须返回 Promise<void>，且不能 throw async execute() { try { // 步骤1：提取代码片段（调用 Node.js 工具） const snippets = await this.callTool('extractCode', { text: this.state.issueContent }); // 步骤2：逐个分析（体现 Agent 的“思考”过程） for (const snippet of snippets) { const result = await this.callTool('analyzeCode', { code: snippet }); // 【关键3】主动中断：用户点击“跳过此片段”时触发 if (this.isInterrupted()) { this.setState({ lastError: '用户手动跳过' }); return; } this.setState(prev => ({ codeSnippets: [...prev.codeSnippets, result.suggestion] })); } } catch (err) { // 【关键4】错误恢复：最多重试 2 次，超过则标记失败 this.setState(prev => ({ errorCount: prev.errorCount + 1, lastError: (err as Error).message })); if (this.state.errorCount < 3) { await this.retry(); // 内置重试逻辑，自动延时 1s 后重 exec } else { this.fail(`分析失败 ${this.state.errorCount} 次: ${this.state.lastError}`); } } } }

这里的关键细节：

• isInterrupted()是 Paperclip 注入的方法，监听前端 Debug Panel 的“中断”按钮。
• retry()不是简单地execute()，而是重置沙箱环境、清空工具缓存、重新加载模型上下文，确保重试是干净的。
• fail()会触发整个 Agent 流程终止，并在 UI 显示红色错误横幅，这是 Paperclip 的错误边界机制。

3.3 Node.js 工具开发：沙箱安全、参数校验与性能陷阱规避

工具函数写在server/tools/目录下，必须导出为export function xxx()。以analyzeCode为例：

// server/tools/analyzeCode.ts import { ToolDefinition } from 'paperclip'; export const analyzeCode: ToolDefinition = { name: 'analyzeCode', description: '分析 JavaScript 代码片段，返回潜在 bug 和修复建议', parameters: { type: 'object', properties: { code: { type: 'string', minLength: 1, maxLength: 2000 }, // 【关键1】必须严格校验 }, required: ['code'] }, async execute({ code }) { // 【关键2】沙箱内禁止访问外部变量，所有依赖必须显式 import const { analyze } = await import('code-analyzer'); // 动态 import 避免打包污染 // 【关键3】性能陷阱：LLM 调用必须设 timeout，否则 Agent 卡死 const controller = new AbortController(); setTimeout(() => controller.abort(), 15000); // 15s 超时 try { const result = await fetch('https://api.llm.example/v1/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'gpt-4-turbo', messages: [{ role: 'user', content: `分析代码: ${code}` }] }), signal: controller.signal // 【关键4】必须传递 signal }); return await result.json(); } catch (err) { if (err.name === 'AbortError') { throw new Error('代码分析超时，请检查网络或简化代码'); } throw err; } } };

实操心得：

• 参数校验用 JSON Schema，Paperclip 会在调用前自动验证，非法参数直接拒绝，不进入沙箱。
• setTimeout+AbortController是强制要求，Paperclip 的 Agent 调度器会监控每个工具的执行时间，超时自动 kill 进程。
• 动态import()是为了防止工具函数被 Webpack 打包进前端 bundle，造成体积膨胀和安全风险。

3.4 调试协议集成：Debug Panel 的 3 种视图模式与真实故障排查案例

Paperclip 的 Debug Panel 不是装饰品，而是生产环境必备。它有三种视图模式：
Timeline View（时间线视图）：显示每个步骤的开始/结束时间、耗时、token 数。当你发现“翻译步骤”耗时 8.2s，而其他步骤均 < 200ms，立刻怀疑是模型响应慢或网络抖动。
State View（状态视图）：以树形结构展示 Agent 全局 state，支持点击任意属性展开/收起。当codeSnippets数组为空时，你能直接看到issueContent是否被正确传入。
Log View（日志视图）：按DEBUG_LOG消息级别过滤，支持搜索。最常用的是搜索ERROR，但高级用法是搜索tool_call:extractCode查看每次调用的原始参数。

真实故障案例：某次上线后，Agent 在分析大型 PR 时频繁失败。Timeline View 显示extractCode步骤耗时突增至 12s，但 State View 里issueContent长度正常。切换到 Log View，搜索tool_result:extractCode，发现返回的codeSnippets数组里有 1 个元素是null。追查extractCode工具，发现正则表达式/```(js|ts)\n([\s\S]*?)\n```/g在匹配超长文本时回溯爆炸，导致 V8 引擎卡死。解决方案：改用acorn解析 AST 提取代码块，耗时降至 80ms。

3.5 生产部署：Node.js 服务进程管理与 React 构建的协同优化

Paperclip 的生产部署不是“前后端分离”，而是Runtime Co-location（运行时共置）。最佳实践是将 Node.js 服务和 React 静态文件打包进同一个 Docker 镜像：

# Dockerfile FROM node:20.11.1-alpine # 构建 React 前端 WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . RUN npm run build # 构建 Node.js 服务 WORKDIR /app/server RUN npm ci --only=production # 启动服务（前端静态文件由 Node.js 服务托管） CMD ["npm", "start"]

server/index.ts的启动逻辑：

import express from 'express'; import { createServer } from 'paperclip'; const app = express(); const port = process.env.PORT || 3000; // 【关键】静态文件托管路径必须与 React 构建输出一致 app.use(express.static(path.join(__dirname, '../dist'))); // Paperclip WebSocket 服务挂载在 /paperclip-ws const wsServer = createServer(); wsServer.listen('/paperclip-ws'); app.listen(port, () => { console.log(`Paperclip server running on http://localhost:${port}`); });

这样做的优势：

• 单端口暴露（http://your-domain.com），避免跨域问题。
• WebSocket 连接复用 HTTP 连接，减少握手开销。
• Node.js 服务可直接读取dist/下的index.html，注入 runtime config（如 LLM API Key 加密后端地址）。
• 最重要的是：Agent 的调试能力在生产环境依然可用。只要在paperclip.config.ts中设置debug: true，管理员登录时即可打开 Debug Panel，无需 SSH 登录服务器查日志。

4. 实操全流程：从本地开发到线上灰度，手把手完成一个 Issue 分析 Agent

现在我们把前面所有细节串起来，完成一个真实可用的IssueAnalyzerAgent。全程基于 Vite + React + Node.js，不依赖任何第三方云服务，所有代码均可本地运行。

4.1 初始化项目与配置

# 1. 创建 Vite 项目（选择 React + TypeScript） npm create vite@latest paperclip-demo -- --template react-ts cd paperclip-demo # 2. 全局安装 Paperclip CLI npm install -g @paperclip/cli # 3. 初始化 Paperclip 结构 paperclip init --framework react-vite # 4. 安装依赖（Paperclip 会自动添加） npm install # 5. 修改 paperclip.config.ts

// paperclip.config.ts import type { PaperclipConfig } from 'paperclip'; export default { // 【关键配置1】指定 Node.js 服务端口，必须与 package.json scripts 一致 serverPort: 3001, // 【关键配置2】LLM 配置，支持多种后端 llm: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY || 'sk-xxx', // 开发时可明文，生产需加密 model: 'gpt-4-turbo', }, // 【关键配置3】工具目录映射，必须绝对路径 toolsDir: './server/tools', // 【关键配置4】调试开关，生产环境设为 false debug: true, } satisfies PaperclipConfig;

4.2 编写核心 Agent 类

// src/agents/IssueAnalyzer.tsx import { BaseAgentNode } from 'paperclip'; export class IssueAnalyzer extends BaseAgentNode { state = { issueUrl: '', issueContent: '', analysisResult: '' as string, isProcessing: false, }; // 【关键】Agent 的入口方法，由 React 组件调用 async startAnalysis(url: string) { this.setState({ issueUrl: url, isProcessing: true }); try { // 步骤1：获取 Issue 内容（调用工具） const content = await this.callTool('fetchIssue', { url }); this.setState({ issueContent: content }); // 步骤2：分析内容 const result = await this.callTool('analyzeIssue', { content, url }); this.setState({ analysisResult: result.suggestion, isProcessing: false }); } catch (err) { this.setState({ analysisResult: `分析失败: ${(err as Error).message}`, isProcessing: false }); } } // 【关键】React 组件中绑定的事件处理器 handleStart = () => { this.startAnalysis(this.props.issueUrl); }; }

4.3 开发 Node.js 工具函数

// server/tools/fetchIssue.ts import { ToolDefinition } from 'paperclip'; export const fetchIssue: ToolDefinition = { name: 'fetchIssue', description: '根据 GitHub Issue URL 获取原始内容', parameters: { type: 'object', properties: { url: { type: 'string', pattern: '^https://github.com/.*?/issues/\\d+$' } }, required: ['url'] }, async execute({ url }) { // 【关键】GitHub API 需要 token，从环境变量读取 const token = process.env.GITHUB_TOKEN; if (!token) throw new Error('GITHUB_TOKEN not set'); // 解析 URL 获取 owner/repo/number const match = url.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/); if (!match) throw new Error('Invalid GitHub URL'); const [_, owner, repo, number] = match; const res = await fetch( `https://api.github.com/repos/${owner}/${repo}/issues/${number}`, { headers: { 'Authorization': `token ${token}`, 'Accept': 'application/vnd.github.v3+json' } } ); if (!res.ok) throw new Error(`GitHub API error: ${res.status}`); const data = await res.json(); return `${data.title}\n\n${data.body}`; } };

// server/tools/analyzeIssue.ts import { ToolDefinition } from 'paperclip'; export const analyzeIssue: ToolDefinition = { name: 'analyzeIssue', description: '分析 GitHub Issue 内容，生成修复建议', parameters: { type: 'object', properties: { content: { type: 'string' }, url: { type: 'string' } }, required: ['content', 'url'] }, async execute({ content, url }) { // 【关键】调用 LLM，使用 Paperclip 封装的客户端 const { createLlmClient } = await import('@paperclip/llm-client'); const client = createLlmClient(); const response = await client.chat.completions.create({ model: 'gpt-4-turbo', messages: [ { role: 'system', content: '你是一个资深前端工程师，专门分析 GitHub Issue 并给出具体修复代码和步骤。回复必须用中文，格式为：1. 问题定位；2. 修复方案；3. 示例代码。' }, { role: 'user', content: `Issue 内容：${content}\nURL：${url}` } ], temperature: 0.3 // 【关键】降低温度，保证输出稳定 }); return { suggestion: response.choices[0].message.content || '' }; } };

4.4 构建 React 前端界面

// src/App.tsx import React, { useState, useRef } from 'react'; import { IssueAnalyzer } from './agents/IssueAnalyzer'; function App() { const [url, setUrl] = useState(''); const [result, setResult] = useState(''); const agentRef = useRef<IssueAnalyzer>(null); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (!agentRef.current) return; // 【关键】调用 Agent 的公共方法 agentRef.current.startAnalysis(url); }; return ( <div className="p-4 max-w-4xl mx-auto"> <h1 className="text-2xl font-bold mb-4">GitHub Issue 分析 Agent</h1> <form onSubmit={handleSubmit} className="mb-6"> <input type="url" value={url} onChange={(e) => setUrl(e.target.value)} placeholder="https://github.com/owner/repo/issues/123" className="w-full p-2 border rounded mr-2" required /> <button type="submit" disabled={!url} className="px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50" > 分析 Issue </button> </form> {/* 【关键】Agent 组件必须用 ref 绑定 */} <IssueAnalyzer ref={agentRef} /> {result && ( <div className="mt-6 p-4 bg-gray-50 rounded"> <h2 className="font-bold mb-2">分析结果：</h2> <pre className="whitespace-pre-wrap">{result}</pre> </div> )} </div> ); } export default App;

4.5 启动与调试全流程

# 1. 设置环境变量（开发时） export OPENAI_API_KEY="sk-xxx" export GITHUB_TOKEN="ghp_xxx" # 2. 启动 Paperclip 服务（自动启动 Node.js + Vite） npm run dev # 3. 访问 http://localhost:3000，输入 GitHub Issue URL # 4. 打开浏览器 DevTools → Paperclip Tab → 选择 Timeline View

实测效果：

• 输入https://github.com/facebook/react/issues/25924，3.2 秒后返回分析结果。
• Timeline View 显示：fetchIssue耗时 1.1s（网络延迟），analyzeIssue耗时 2.1s（LLM 响应）。
• 点击analyzeIssue步骤，State View 显示输入content长度 1284 字符，输出suggestion包含 3 条具体修复建议。
• 如果故意输入错误 URL，fetchIssue步骤立即失败，Debug Panel 显示红字错误，且analyzeIssue步骤不会执行——证明控制流正确。

5. 常见问题与独家避坑指南：那些官方文档不会告诉你的实战经验

Paperclip 的文档清晰但略显理想化。在真实项目中，你会遇到一堆“文档没写但必须解决”的问题。以下是我在 3 个生产项目中踩过的坑，附带可直接复制的解决方案。

5.1 问题：Agent 在生产环境启动失败，报错Error: Cannot find module 'paperclip'

现象：Docker 镜像构建成功，但容器启动时报Cannot find module 'paperclip'，而node_modules里明明有该包。
根本原因：Paperclip 的 CLI 工具在paperclip init时，会向package.json添加"type": "module"字段。但某些 Node.js 版本（特别是 20.11.1 Alpine）的require()无法正确解析 ESM 模块。
解决方案：修改package.json，删除"type": "module"，并在server/index.ts顶部添加：

// server/index.ts import { createRequire } from 'module'; const require = createRequire(import.meta.url); // 然后正常 require const paperclip = require('paperclip');

实操心得：这个坑只在 Alpine Linux 上出现，Ubuntu 镜像无此问题。但生产环境推荐 Alpine（镜像小 70%），所以必须加createRequire。别信文档说的“自动处理”，这是 Node.js 的模块系统差异，Paperclip 无法完全屏蔽。

5.2 问题：Debug Panel 无法连接，WebSocket 报错net::ERR_CONNECTION_REFUSED

现象：前端页面正常，但 Debug Panel 显示“连接中...”，Network Tab 看到ws://localhost:3001/paperclip-ws请求失败。
排查路径：

1. 检查paperclip.config.ts的serverPort是否与package.json的scripts.dev一致；
2. 检查server/index.ts是否调用了createServer().listen('/paperclip-ws')；
3. 最关键：检查 Vite 的proxy配置是否拦截了 WebSocket。

解决方案：在vite.config.ts中添加：

export default defineConfig({ server: { proxy: { '/paperclip-ws': { target: 'http://localhost:3001', changeOrigin: true, // 【关键】必须启用 WebSocket 代理 ws: true, } } } });

注意：ws: true是必须的，否则 Vite 的 dev server 会把 WebSocket 请求当成 HTTP，返回 404。这个配置在 Paperclip 文档里被忽略了，但它是本地开发的刚需。

5.3 问题：Agent 执行时内存持续增长，最终 OOM 崩溃

现象：Agent 运行 10 次后，Node.js 进程内存占用从 120MB 涨到 1.2GB，process.memoryUsage()显示heapUsed持续上升。
根本原因：Paperclip 的vm2沙箱在执行工具函数时，会缓存import()的模块。如果工具函数动态import('some-heavy-lib')，每次调用都会加载新实例，且旧实例不被 GC。
解决方案：在server/tools/目录下创建cache.ts：

// server/tools/cache.ts const moduleCache = new Map<string, any>(); export function safeImport<T>(path: string): Promise<T> { if (moduleCache.has(path)) { return Promise.resolve(moduleCache.get(path)); } return import(path).then((mod) => { moduleCache.set(path, mod); return mod; }); } // 在工具函数中使用 export const analyzeCode: ToolDefinition = { // ... async execute({ code }) { const { analyze } = await safeImport('code-analyzer'); // ... } };

实操心得：这个缓存必须全局共享，不能每个工具函数自己维护。safeImport用Map而不是WeakMap，因为模块引用需要长期持有。实测加入缓存后，100 次调用内存稳定在 180MB。

5.4 问题：React 组件中 Agent 状态更新不及时，UI 卡顿

现象：Agent 正在执行，但setState()后 UI 没有立即刷新，直到整个execute()完成才批量更新。
原因：Paperclip 的BaseAgentNode默认使用useState，但在异步链中，React 的批处理机制会合并多次setState。
解决方案：在src/agents/目录下创建AgentNode.tsx，重写setState：

// src/agents/AgentNode.tsx import { useState, useCallback } from 'react'; import { BaseAgentNode } from 'paperclip'; export abstract class OptimizedAgentNode<T extends object> extends BaseAgentNode { // 使用 useReducer 替代 useState，强制同步更新 private [stateSymbol] = useState<T>({} as T); setState = useCallback((partial: Partial<T> | ((prev: T) => Partial<T>)) => { this[stateSymbol][1](prev => ({ ...prev, ...(typeof partial === 'function' ? partial(prev) : partial) })); }, []); }

然后让所有 Agent 类继承OptimizedAgentNode。这样每次setState都会触发独立的 re-render，Debug Panel 的实时性提升 100%。

5.5 问题速查表：高频问题与一键修复