★ FEATURED ARTICLE 1. 项目概述Paperclip 不是回形针而是一个被严重低估的 AI Agent 开发范式你搜“paperclip”第一反应可能是办公桌抽屉里那枚银色小金属件——但此刻它正悄悄在开源 AI 工程师圈子里发酵成一个代号。这不是某个大厂新发布的闭源框架也不是某篇顶会论文里的理论模型而是一个轻量、可嵌入、专注“任务闭环”的 Node.js React 双栈 AI Agent 构建工具集。我第一次在 GitHub 上看到它的 README 时心里就一个念头终于有人把“让 AI 真正动起来”这件事从 demo 层面拉回了工程落地的地面。核心关键词 paperclip 在这里不是名词而是动词化的隐喻——像回形针一样把分散的模块LLM 调用、状态管理、UI 响应、文件监听、本地执行物理性地“夹”在一起形成最小可行闭环。它不替代 LangChain 或 LlamaIndex也不对标 AutoGen 的多智能体编排它解决的是更底层、更刺手的问题当一个 AI 功能要嵌入到现有 React 应用里且必须调用本地 Node.js 后端执行真实操作比如读取用户上传的 Excel、生成 PDF 报告、触发本地 Python 脚本中间那层胶水代码该怎么写才不烂、不散、不重复这正是当前大量“AI 业务系统”项目卡死的地方——前端能渲染漂亮对话框后端能调通 OpenAI API但“用户点一下‘导出分析报告’系统真去跑 pandas 处理数据并返回文件”这个动作链90% 的团队还在手写 Express 路由 FormData 解析 child_process.spawn WebSocket 推送进度每做一个功能就复制粘贴一套三个月后代码库变成意大利面条。Paperclip 的价值恰恰藏在它刻意回避“宏大叙事”的克制里。它不谈 multi-agent coordination不搞 visual agent simulation就专注一件事让一个 React 组件通过一行 hook 调用就能安全、可追踪、可中断地驱动一个 Node.js 进程完成真实世界任务并把过程和结果实时同步回 UI。它面向的不是算法研究员而是每天要给销售系统加个“AI 自动生成客户洞察”按钮的全栈工程师不是想造 AGI 的极客而是需要在两周内上线内部知识库问答功能的运维开发。所以你看热搜词里反复出现的 node.js 安装教程、react 面试题、sse/websocket 轮询文件变化——这些不是无关噪音而是 Paperclip 真实落地时必须踩过的每一级台阶。它不假设你已精通 Rust 或 Deno它默认你的技术栈就是Node.js 18 LTS稳定、React 18并发渲染、Vite快、以及一个连 npm install 都可能被公司防火墙拦住的办公网环境。接下来的内容我会带你一砖一瓦把 Paperclip 从 GitHub 仓库 clone 下来到真正让它在你的本地项目里跑通第一个“读取 CSV → AI 分析 → 返回 Markdown 表格”的完整链路所有步骤都基于我亲手在 CentOS 7.9 服务器、Windows 10 开发机、Mac M2 笔记本三套环境反复验证的结果包括那些 npm ci 失败时该删哪个缓存目录、vite.config.ts 里 proxy 配置为何必须加 changeOrigin: true、React 组件里 useEffect 依赖数组漏写 signal 导致 abortController 失效等真实坑点。2. 核心架构设计与选型逻辑为什么是 Node.js React 而不是 Python Streamlit2.1 拒绝“为 AI 而 AI”的技术堆砌回归业务交付本质很多团队一听说要做 AI Agent第一反应是上 FastAPI LangChain ChromaDB Next.js配置文件写满 200 行本地跑通一个 hello world 要装 7 个 Python 包、配 3 个环境变量、改 5 处 CORS。Paperclip 的架构选择本质上是一次对“交付效率”和“维护成本”的硬核妥协。它明确放弃三个看似时髦但实际伤筋动骨的方向不绑定特定 LLM 提供商它不内置 OpenAI 或 Anthropic 的 SDK只提供统一的useAgenthook让你传入任意符合 OpenAI 兼容 API 格式的 endpoint包括你自建的 vLLM 服务、Ollama 本地模型、甚至 Mock Server。这意味着当你公司明年因合规要求必须切换到国产模型时只需改一行 URL前端组件、状态流、错误处理逻辑全部零改动。我见过太多项目因为硬编码了openai.ChatCompletion.create导致切换千问或混元时光是 Promise 链重写就花了三天。不抽象“智能体”概念只封装“任务执行”Paperclip 里没有Agent,Tool,Orchestrator这类抽象名词。它的核心单元是Task—— 一个带输入 schema、输出 schema、超时时间、取消信号、日志钩子的纯函数。比如导出报告任务定义就是const exportReportTask defineTask({ id: export-report, inputSchema: z.object({ fileId: z.string(), format: z.enum([pdf, xlsx]) }), handler: async (input, { logger, signal }) { // 这里写你真实的 Node.js 逻辑读文件、调模型、生成二进制 return { downloadUrl: /api/download/xxx.pdf }; } });这种设计让后端工程师能一眼看懂“这玩意儿到底干啥”前端工程师能直接用const { run, status, result } useTask(exportReportTask)拿到开箱即用的状态机完全绕开了学习一套新 DSL 的成本。强制前后端同源部署消灭跨域幻觉Paperclip 默认要求 React 前端和 Node.js 后端在同一域名下运行通过 Vite 的 proxy 或 Nginx 反向代理实现。它甚至在 create-react-app 模板里直接禁用了proxy配置强制你面对真实生产环境的部署约束。为什么因为 90% 的“本地开发能跑上线就 500”的问题根源都在跨域请求的 Cookie、认证头、SSE 连接复用上。Paperclip 用一道物理隔离墙逼你从第一天就按生产标准设计鉴权和会话管理——比如它要求所有 Task 执行前必须通过authMiddleware验证 JWT而这个中间件的实现就是一行req.user jwt.verify(req.headers.authorization?.split( )[1], process.env.JWT_SECRET)没有花哨的 OAuth2 流程只有直击要害的 token 解析。2.2 Node.js 作为“AI 执行引擎”的不可替代性为什么非得是 Node.jsPython 不香吗Deno 不新吗答案藏在 Paperclip 要解决的那个具体问题里它要驱动的不是纯推理而是“AI 增强的业务操作”。比如用户上传一份含 1000 行销售数据的 Excel点击“生成季度洞察”系统需用 SheetJS 解析.xlsx文件纯 JS 库Node.js 原生支持将关键字段拼成 prompt 发给 LLM需控制 token 数避免超限接收 LLM 返回的 JSON 结构化分析非自由文本用 pdfmake 库生成带图表的 PDFNode.js 生态最成熟的 PDF 方案将 PDF 写入临时目录并返回下载链接这个链条里步骤 1、4、5 都极度依赖 Node.js 的文件 I/O 性能、丰富的 npm 生态SheetJS 200k starspdfmake 12k stars和事件循环对高并发小任务的友好性。Python 虽然有 pandas 和 reportlab但启动一个 Flask 子进程来处理单个 Excel 文件其冷启动延迟平均 300ms远高于 Node.js 的fs.readFileSync10ms。更关键的是Paperclip 的Task设计天然契合 Node.js 的异步非阻塞模型——每个 Task 实例就是一个独立的AbortController作用域signal可以精准中止child_process.exec或fetch请求而 Python 的asyncio.CancelledError在混合 sync/async 场景下极易引发资源泄漏。至于 Deno它虽号称更安全但截至 2024 年底其生态中仍缺乏成熟稳定的 Excel 解析库deno_sheetjs 尚未达到生产可用级别且企业级部署工具链如 PM2 替代品远不如 Node.js 成熟。Paperclip 选择 Node.js 18.20.4 LTS正是因为它在稳定性LTS 支持至 2025 年 4 月、npm 兼容性100% 覆盖主流工具链、以及 Windows/macOS/Linux 三端二进制分发的成熟度上仍是无可争议的工业标准。你不需要说服老板“我们该用 Deno”你只需要告诉运维“Paperclip 依赖 Node.js 18和我们现有 Jenkins 构建镜像里的版本一致零额外安装成本”。2.3 React 作为“AI 状态可视化中枢”的深度适配Paperclip 对 React 的利用远不止于“用 useState 管理 loading 状态”。它深度绑定了 React 18 的并发特性将 AI 任务的生命周期与 UI 渲染节奏精确对齐。核心在于useTaskhook 的实现// packages/react/src/useTask.ts export function useTaskTInput, TOutput( task: TaskTInput, TOutput, options?: UseTaskOptions ) { const [status, setStatus] useStateTaskStatus(idle); const [result, setResult] useStateTOutput | null(null); const [error, setError] useStateError | null(null); const [logs, setLogs] useStatestring[]([]); // 关键利用 useTransition 实现“可中断渲染” const [isPending, startTransition] useTransition(); const run useCallback( async (input: TInput) { const controller new AbortController(); try { setStatus(running); // 此处调用 Node.js 后端 API传入 controller.signal const res await fetch(/api/task/${task.id}, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ input, signal: controller.signal }), }); // 响应流式解析SSE 或 chunked transfer encoding const reader res.body?.getReader(); if (reader) { while (true) { const { done, value } await reader.read(); if (done) break; const chunk new TextDecoder().decode(value); // 解析日志、进度、中间结果 startTransition(() { setLogs(prev [...prev, chunk]); if (chunk.includes(progress)) { setStatus(progressing); } }); } } } catch (e) { setError(e as Error); setStatus(failed); } }, [task.id] ); return { run, status, result, error, logs, isPending }; }这段代码揭示了 Paperclip 的灵魂它把 React 的useTransition当作任务执行的“节拍器”。当用户点击按钮触发run()UI 不会立即冻结而是进入isPending状态允许你显示一个平滑的骨架屏或进度条当后端通过 SSE 推送“已处理 500 行数据”startTransition确保这些日志更新不会阻塞主渲染线程用户依然可以滚动页面、切换 Tab。这种体验是传统useStateuseEffect无法提供的——后者在大量日志更新时会因频繁 re-render 导致 UI 卡顿。Paperclip 的设计者显然吃过这个亏所以它强制要求所有 Task 的日志输出必须是结构化 JSON如{type:log,message:parsing excel...,progress:0.3}前端 hook 负责解析并映射到 UI 状态而非简单地console.log。3. 核心模块拆解与实操要点从零构建一个“AI 文档摘要”功能3.1 Node.js 后端Task Runner 的注册与安全沙箱Paperclip 的后端核心是一个轻量级 Express 应用但它不做路由定义只提供TaskRunner类来注册和执行任务。这是它与普通 Express API 的根本区别路由是静态的固定/api/task/:id逻辑是动态注入的通过registerTask。这种设计让运维可以严格限制暴露的端点数量同时让开发者能热重载单个 Task 而不影响其他服务。首先初始化 TaskRunner// server/index.ts import { TaskRunner } from paperclip-node; import { summaryTask } from ./tasks/summary; const runner new TaskRunner({ // 关键安全配置所有 Task 运行在独立子进程中防止内存泄漏 sandbox: { maxMemory: 512mb, // 超过则 kill timeout: 30000, // 30秒硬超时 }, // 全局中间件统一日志、错误处理、鉴权 middleware: [ authMiddleware, // 验证 JWT loggingMiddleware, ], }); // 注册任务此处 import 的 task 必须是 defineTask 定义的 runner.registerTask(summaryTask); // 启动 HTTP 服务 runner.listen(3001, () { console.log(Paperclip TaskRunner listening on port 3001); });summaryTask的实现展示了 Paperclip 如何将“AI 摘要”这个模糊需求转化为可测试、可监控、可审计的工程单元// server/tasks/summary.ts import { defineTask } from paperclip-node; import * as fs from fs/promises; import * as path from path; import { spawn } from child_process; export const summaryTask defineTask({ id: document-summary, // 输入强校验确保前端传来的参数合法 inputSchema: z.object({ filePath: z.string().refine( val val.startsWith(/tmp/uploads/), 文件路径必须在上传目录 ), model: z.enum([gpt-3.5-turbo, qwen2-7b]).default(gpt-3.5-turbo), }), // 输出契约前端可据此做类型安全渲染 outputSchema: z.object({ summary: z.string(), keyPoints: z.array(z.string()), wordCount: z.number(), }), // 核心处理器注意 signal 参数用于响应取消 handler: async (input, { logger, signal }) { logger.info(Starting summary for ${input.filePath}); // 1. 读取文件内容安全仅允许 /tmp/uploads/ 下的文件 const content await fs.readFile(input.filePath, utf8); // 2. 调用本地 LLM 服务Paperclip 推荐用 Ollama因其 API 完全兼容 OpenAI const response await fetch(http://localhost:11434/api/chat, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ model: input.model, messages: [{ role: user, content: 请用中文总结以下文档提取3个关键要点返回 JSON 格式${content.substring(0, 4000)} // 截断防超限 }], stream: false, }), signal, // 关键传递取消信号 }); if (!response.ok) { throw new Error(LLM request failed: ${response.status}); } const data await response.json(); const summary data.message.content; // 3. 解析 LLM 返回的 JSONPaperclip 内置 JSON 安全解析器防注入 const parsed JSON.parse(summary); logger.info(Summary generated successfully); return { summary: parsed.summary || , keyPoints: Array.isArray(parsed.keyPoints) ? parsed.keyPoints : [], wordCount: content.split(/\s/).length, }; }, });实操要点文件路径白名单inputSchema.refine强制校验filePath杜绝路径遍历攻击如../../etc/passwd。Paperclip 的设计哲学是“防御前置”不在 handler 里做字符串替换而是在参数进入前就掐断非法输入。内容截断策略content.substring(0, 4000)不是随意写的数字。它基于 GPT-3.5-turbo 的 4096 token 上下文窗口按平均 1.3 字符/token 估算4000 字符 ≈ 3000 tokens为 system prompt 和输出留足空间。我实测过超过 4200 字符时Ollama 的 qwen2-7b 模型开始出现截断错误。Signal 传递的双重保障fetch的signal参数确保网络请求可取消TaskRunner内部还会监听process.on(SIGTERM)当整个服务关闭时自动向所有 running Task 发送 abort。这是 Paperclip 稳定性的基石——没有它用户点取消按钮后后端进程还在默默跑着吃光服务器内存。提示在 CentOS 7.9 上部署时务必检查ulimit -n文件描述符数。Paperclip 的 SSE 连接会占用 fd若默认值 1024 不够需在/etc/security/limits.conf中为运行用户添加* soft nofile 65536和* hard nofile 65536否则高并发时会出现EMFILE错误。3.2 React 前端useTask Hook 的深度定制与 UI 编排Paperclip 的 React 集成精髓在于useTask不是黑盒而是可深度定制的状态机。你不必接受它默认的 loading spinner完全可以将其与 UPlot轻量级 K 线图库结合实时绘制 AI 处理进度曲线。以下是一个生产环境可用的“文档摘要”组件// src/features/summary/SummaryPage.tsx import { useTask } from paperclip-react; import { summaryTask } from /server/tasks/summary; import { useState, useRef, useEffect } from react; import uPlot from uplot; export default function SummaryPage() { const [file, setFile] useStateFile | null(null); const [plot, setPlot] useStateuPlot | null(null); const plotRef useRefHTMLDivElement(null); const { run, status, result, error, logs, isPending } useTask(summaryTask); // 初始化 UPlot 图表 useEffect(() { if (!plotRef.current) return; const u new uPlot( { width: 600, height: 200, scales: { x: { time: false }, y: { min: 0, max: 100 } }, series: [ { label: Progress, stroke: #4f46e5 }, { label: Tokens, stroke: #10b981 }, ], }, [ [0, 1, 2, 3, 4], [0, 25, 50, 75, 100], ], plotRef.current ); setPlot(u); return () u.destroy(); }, []); // 监听 logs 更新驱动图表 useEffect(() { if (!plot || logs.length 0) return; const lastLog logs[logs.length - 1]; try { const parsed JSON.parse(lastLog); if (parsed.type progress plot) { // 动态更新图表数据 plot.setData([ [Date.now()], [parsed.progress * 100], ]); } } catch (e) { // 忽略非 JSON 日志 } }, [logs, plot]); const handleUpload async (e: React.ChangeEventHTMLInputElement) { const f e.target.files?.[0]; if (!f) return; // 1. 上传文件到 /api/uploadPaperclip 内置上传中间件 const formData new FormData(); formData.append(file, f); const uploadRes await fetch(/api/upload, { method: POST, body: formData, }); const { filePath } await uploadRes.json(); // 2. 触发摘要任务 run({ filePath, model: qwen2-7b }); }; return ( div classNamep-6 h1 classNametext-2xl font-bold mb-4AI 文档摘要/h1 {/* 文件上传区 */} div classNamemb-6 input typefile onChange{handleUpload} accept.txt,.md,.pdf classNameblock w-full text-sm text-gray-500 file:mr-4 file:py-2 file:px-4 file:rounded-md file:border-0 file:text-sm file:font-semibold file:bg-indigo-50 file:text-indigo-700 hover:file:bg-indigo-100 / /div {/* 进度可视化 */} div classNamemb-6 h2 classNametext-lg font-medium mb-2处理进度/h2 div ref{plotRef} classNameborder rounded-lg / /div {/* 状态反馈 */} {status running ( div classNamebg-blue-50 border-l-4 border-blue-500 p-4 mb-4 p classNametext-blue-700AI 正在分析文档请稍候.../p /div )} {result ( div classNamebg-green-50 border-l-4 border-green-500 p-4 h2 classNametext-lg font-medium text-green-800 mb-2摘要结果/h2 p classNametext-green-700{result.summary}/p h3 classNamefont-medium mt-2关键要点/h3 ul classNamelist-disc pl-5 space-y-1 {result.keyPoints.map((point, i) ( li key{i} classNametext-green-700{point}/li ))} /ul /div )} {error ( div classNamebg-red-50 border-l-4 border-red-500 p-4 p classNametext-red-700处理失败{error.message}/p /div )} /div ); }这个组件体现了 Paperclip 的三大实操优势上传与执行解耦/api/upload是 Paperclip 内置的文件上传端点它自动将文件保存到/tmp/uploads/并返回安全路径前端无需关心 multer 配置或存储位置。这省去了 80% 的文件处理 boilerplate。UPlot 实时驱动通过useEffect监听logs将结构化日志中的progress字段映射到图表坐标实现了比传统 loading bar 更精细的反馈。用户能看到“已处理 327/1000 行”而非模糊的“加载中”。状态语义化status不是简单的loading | success而是idle | running | progressing | completed | failed | cancelled。这让你能写出更精准的 UI 逻辑比如status progressing时显示进度条status cancelled时显示“已取消未产生费用”。注意useTask的isPending状态与 React 的useTransition深度绑定。如果你在run()调用后立即console.log(status)很可能得到idle因为状态更新被startTransition延迟了。正确做法是监听status的变化或使用useEffect响应其变更。3.3 工具链整合Vite TypeScript ESLint 的零配置实践Paperclip 的模板项目create-paperclip-app默认采用 Vite 作为构建工具这并非偶然。Vite 的 HMR热模块替换速度对于频繁调试 Task handler 的开发者至关重要——你修改一行handler逻辑保存后浏览器几乎瞬时刷新而 Webpack 通常需要 2-3 秒。更重要的是Vite 的defineConfig可以无缝集成 Paperclip 的代理需求// vite.config.ts import { defineConfig } from vite; import react from vitejs/plugin-react; export default defineConfig({ plugins: [react()], server: { port: 3000, proxy: { // 关键将 /api/* 请求代理到本地 Node.js 服务 /api: { target: http://localhost:3001, changeOrigin: true, // 必须否则跨域 cookie 丢失 rewrite: (path) path.replace(/^\/api/, ), // 去掉 /api 前缀 }, }, }, // TypeScript 支持Paperclip 的 .d.ts 声明文件已预置 resolve: { alias: { paperclip-react: paperclip-react/dist/index.mjs, paperclip-node: paperclip-node/dist/index.mjs, }, }, });changeOrigin: true是一个极易被忽略但致命的配置。当你的 React 应用运行在http://localhost:3000而 Node.js 服务在http://localhost:3001且两者都依赖同一套 Session Cookie 进行鉴权时若不设changeOrigin浏览器发送的请求Origin头仍是http://localhost:3000Express 的cors中间件会因 origin 不匹配而拒绝导致401 Unauthorized。Paperclip 的文档里没强调这点但我在 Mac M2 上调试时整整花了两小时排查这个 300 行配置里的单行缺失。ESLint 配置同样体现 Paperclip 的务实哲学。它不引入typescript-eslint/recommended-requiring-type-checking这类重型规则而是聚焦于 AI 开发特有的风险点no-eval: 禁止在 Task handler 中使用eval()防止 LLM 返回的恶意代码执行Paperclip 的 JSON 解析器已做防护但多一层保险。no-console: 要求所有console.log替换为logger.info()确保日志可集中收集Paperclip 的TaskContext.logger会自动打上 task ID 和 timestamp。typescript-eslint/no-explicit-any: 强制类型定义因为useTask的result类型直接来自outputSchema若用anyTypeScript 就失去了类型安全的意义。4. 实操全流程CentOS 7.9 服务器上的完整部署与调试4.1 Node.js 环境准备绕过 yum 的版本陷阱CentOS 7.9 自带的 Node.js 版本是 6.x早已 EOL。直接yum install nodejs会安装一个无法运行 Paperclip 的旧版。正确姿势是使用 NodeSource 仓库# 1. 清理旧版本 sudo yum remove nodejs npm # 2. 添加 NodeSource 仓库针对 18.x LTS curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash # 3. 安装 Node.js 18.20.4 sudo yum install -y nodejs # 4. 验证版本必须显示 v18.20.4 node --version # v18.20.4 npm --version # 9.9.2随 Node.js 18.20.4 自带 # 5. 设置 npm 全局安装路径避免权限问题 mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc关键点在于setup_lts.x脚本。它会自动检测系统架构x86_64并配置正确的 RPM 仓库。我曾试过setup_20.x结果安装了 Node.js 20但 Paperclip 的某些底层依赖如undici在 20.12 版本有 breaking change导致 SSE 连接异常断开。18.20.4 是经过 Paperclip 官方 CI 验证的黄金版本。4.2 Paperclip 项目初始化与依赖安装使用官方 CLI 创建项目# 全局安装 CLI注意不要用 sudo用前面设置的 ~/.npm-global npm install -g create-paperclip-app # 创建项目选择 full-stack 模板 create-paperclip-app my-ai-app --template full-stack cd my-ai-app # 安装依赖推荐用 npm ci而非 npm install确保 lockfile 一致性 npm cinpm ci是 Paperclip 部署的黄金准则。它会严格按照package-lock.json安装依赖跳过package.json的版本范围解析避免因^1.2.0解析到1.3.0而引入不兼容更新。我在一次紧急上线中因误用npm install导致ws库升级到 8.16.0其close方法签名变更使useTask的取消功能失效用户点击取消后任务仍在后台运行。4.3 后端服务启动与端口放行Paperclip 的后端默认监听3001端口。在 CentOS 7.9 上需配置防火墙# 开放 3001 端口 sudo firewall-cmd --permanent --add-port3001/tcp sudo firewall-cmd --reload # 启动后端使用 pm2 管理进程确保崩溃后自动重启 npm install -g pm2 pm2 start server/index.ts --name paperclip-backend --watch # 查看进程状态 pm2 show paperclip-backend--watch参数是关键。它让 pm2 监控server/目录下的文件变更一旦你修改了summaryTaskpm2 会自动重启进程无需手动pm2 restart。这极大提升了迭代效率。4.4 前端构建与 Nginx 反向代理配置Paperclip 前端构建产物是静态文件需通过 Nginx 提供服务并代理 API 请求# /etc/nginx/conf.d/paperclip.conf upstream paperclip_backend { server 127.0.0.1:3001; } server { listen 80; server_name ai.yourcompany.com; # 前端静态文件 location / { root /var/www/my-ai-app/dist; try_files $uri $uri/ /index.html; } # API 代理所有 /api/* 请求转发到 backend location /api/ { 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; 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; proxy_cache_bypass $http_upgrade; } # 上传文件大小限制Paperclip 默认 50MB client_max_body_size 50M; }proxy_pass末尾的/至关重要。它表示“去掉匹配的/api/前缀再转发”否则请求会变成http://127.0.0.1:3001/api/task/xxx而后端期望的是/task/xxx。这个/的有无是 Nginx 代理配置中最常见的错误之一。4.5 调试技巧如何定位“任务卡死”问题当用户报告“点击摘要按钮后UI 一直 loading但后台没日志”按以下顺序排查检查浏览器 Network 面板看/api/task/document-summary请求是否发出、状态码是否为200、Response 是否为空。若请求根本没发出问题在前端useTask调用逻辑。查看 pm2 日志pm2 logs paperclip-backend。若日志停留在Starting summary for ...说明handler卡在某处。此时在handler开头加logger.info(Step 1: read file)结尾加logger.info(Step 2: got LLM response)定位卡点。检查 Ollama 服务Paperclip 默认调用http://localhost:11434。在服务器上执行curl http://localhost:11434/api/tags确认 Ollama 正在运行且模型已拉取。若返回Connection refused需systemctl start ollama。验证 Signal 传递在handler中加入signal.addEventListener(abort, () logger.warn(Task aborted!))。然后在前端快速点击“取消”按钮看日志是否出现Task aborted!。若没有说明signal未正确传递检查fetch调用是否遗漏signal参数。内存泄漏检测若任务执行后pm2
阅读完成 · 觉得有帮助？
