1. 项目概述Paperclip 不是回形针而是一个面向 AI Agent 开发的轻量级 Node.js 运行时框架你搜“paperclip”时第一反应可能是办公桌抽屉里那枚银色小金属件——但最近在掘金、GitHub 和 React 前端技术群聊里“Paperclip”正以高频词身份反复出现和 Node.js、React、OpenClaw 绑定在一起。它不是 UI 组件库不是状态管理工具更不是又一个“AI 前端胶水层”。Paperclip 是一个专为本地化、可调试、低侵入式 AI Agent 构建而设计的 Node.js 运行时框架核心定位非常明确让开发者用 React 写 Agent 的逻辑界面UI State Interaction用 Node.js 承载真实 Agent 的执行上下文LLM 调用、工具调度、文件系统访问、进程控制两者通过极简 IPC 通信桥接不依赖浏览器环境、不强制云部署、不抽象掉关键控制权。我去年在给一家做工业设备远程诊断的团队做技术咨询时就遇到典型痛点他们想用 LLM 解析现场上传的 JSON 日志PDF 故障报告生成维修建议并调用内部工单系统 API。当时试过 LangChain Next.js SSR、也跑过 FastAPI Streamlit但要么调试链路太长前端改个 prompt 得等 30 秒热更新、要么权限太重需要完整 Python 环境GPU 支持、要么根本没法读取本地设备日志目录。最后我们用 Paperclip 搭了一套方案React 做诊断面板带拖拽上传区、实时 token 流式渲染、历史会话树Node.js 层直接fs.readdirSync(/var/log/device/)读取原始日志用child_process.spawn(python3, [analyze.py])调用遗留 Python 分析脚本再把结果喂给本地 Ollama 模型。整个流程在开发机上 5 分钟搭完上线后运维同事能直接 SSH 进去改 Node.js 里的工具函数不用碰前端构建。它和 OpenClaw 的关系常被误解——OpenClaw 是一个功能完备、开箱即用的 AI Agent 平台含 Web UI、多模型路由、记忆存储、插件市场而 Paperclip 更像它的“内核拆解版”去掉所有平台级封装只保留最精简的 Agent 生命周期管理init → think → act → observe → loop和 React/Node 双端协同机制。你可以把它理解成“OpenClaw 的最小可行内核”或者“手写 React Agent 的标准化脚手架”。这也是为什么搜索热词里同时出现 “openclaw ubuntu安装教程” 和 “手写react agent”——前者要开箱即用后者要深度掌控Paperclip 正好卡在这中间。适合谁不是纯 UI 工程师也不是纯后端架构师而是那些正在从“调 API 做智能对话”迈向“构建可落地 Agent 应用”的实战派懂 React Hooks 状态流、能写 Node.js 文件操作和子进程调用、愿意为业务逻辑写真实工具函数比如解析 Excel、调用串口、生成 PDF 报告的人。如果你还在用fetch()轮询后端接口来模拟 Agent 行为或者把所有逻辑硬塞进useEffect里靠setInterval驱动Paperclip 提供的是一条更干净、更可控、更贴近真实 Agent 运行语义的路径。2. 核心设计思路与选型逻辑为什么是 Node.js React为什么拒绝 Electron 和 Next.js2.1 为什么必须用 Node.js 作为 Agent 执行层这不是为了“全栈工程师情怀”而是由 AI Agent 的本质决定的。Agent 的核心能力不是“展示结果”而是“感知环境→决策→执行→观察反馈”。这个闭环里90% 的关键动作都发生在服务端上下文文件系统访问读取用户上传的.log、.csv、.pcap文件扫描/tmp/下临时生成的截图监听./data/目录变化触发自动分析进程控制调用ffmpeg转码视频、用pandoc转换文档格式、执行nmap扫描局域网设备、启动tshark抓包本地服务集成连接本地 PostgreSQL 存储记忆、调用curl http://localhost:8080/api/v1/status获取设备心跳、向mqtt://localhost:1883发布控制指令模型运行时支持加载本地 Ollama 模型ollama run llama3、调用 LM Studio 的 HTTP 接口、甚至直接require(xenova/transformers)在 Node.js 里跑小型量化模型。这些能力浏览器环境天然缺失。Electron 虽然能访问文件系统但它把整个 Chromium 实例打包进来内存占用动辄 800MB启动慢、调试难、更新麻烦——而 Paperclip 的 Node.js 层启动时间 300msps aux | grep paperclip一眼就能看到进程树node --inspect-brk直接断点调试工具函数。更重要的是Node.js 的child_process、fs.promises、streamAPI 对上述场景支持成熟稳定错误处理清晰比如spawn的exit code、signal、stderr分离不像 Electron 的remote模块已被废弃新版本里跨进程通信还得自己搭 IPC 通道。提示Paperclip 的 Node.js 层默认使用 CommonJS 模块系统非 ESM原因很实际——大量现成的 CLI 工具如jq、exiftool、pdfinfo都是通过spawn调用的而 Node.js 的 ESM 对require.resolve()动态路径解析支持较弱CommonJS 在__dirname和path.join(__dirname, ../tools/)这类路径拼接上更可靠。这不是守旧是为降低工具链接入成本。2.2 为什么 React 是唯一推荐的 UI 层而非 Vue 或 SvelteReact 的优势不在语法糖而在其State Effect Ref 的三元模型完美映射 Agent 的运行范式useState管理 Agent 的当前状态快照如currentStep: analyzing | waiting_for_user_input | executing_tooluseEffect处理副作用触发当currentStep executing_tool时自动调用ipcRenderer.send(run-tool, { name: parse_log, args: [...] })useRef持有长期引用对象如const toolProcessRef useRef(null)用于中止正在运行的ffmpeg进程。对比来看Vue 的watch虽然也能响应状态变化但触发时机不如useEffect明确watch是异步队列useEffect是同步清理异步执行Svelte 的$:响应式声明在复杂嵌套状态如agent.memory.conversations[0].messages[3].tool_calls[0].result下容易产生难以追踪的 rerender。而 Paperclip 的官方模板里一个典型的 Agent UI 组件结构是function DiagnosticPanel() { const [state, setState] useStateAgentState({ status: idle, currentTool: null, messages: [] }); // 当 state.status 变为 running_tool自动触发 Node.js 层执行 useEffect(() { if (state.status running_tool state.currentTool) { ipcRenderer.send(execute-tool, state.currentTool); // 同时启动 WebSocket 监听工具输出流 const ws new WebSocket(ws://localhost:3001/tool-output); ws.onmessage (e) { setState(prev ({ ...prev, messages: [...prev.messages, { role: tool, content: e.data }] })); }; } }, [state.status, state.currentTool]); return ( div UploadZone onFiles{(files) setState({...state, status: processing})} / MessageList messages{state.messages} / StatusIndicator status{state.status} / /div ); }这种“状态驱动行为”的模式让 UI 层彻底摆脱了手动管理loading、error、success三态的繁琐所有 Agent 的生命周期流转都由state.status单一字段驱动逻辑集中、易测试、易扩展。这也是为什么“react 面经”里高频出现useReducer和useTransition——Paperclip 的实际项目中我们确实用useReducer管理 Agent 的复杂状态机12 个状态节点用useTransition保证大文件上传时不阻塞 UI 响应。2.3 为什么坚决不用 Next.jsServer Components 会破坏 Agent 的本地性Next.js 的 App Router 和 Server Components 看似强大但对 Paperclip 场景是灾难性的Server Component 无法访问 Node.js 的fs、child_process它运行在 Vercel 边缘函数或你自己部署的 Node.js server 上但 Paperclip 的核心诉求是“本地 Agent”——工具必须运行在用户本机而不是远端服务器。把fs.readdirSync(/home/user/logs/)放到 Server Component 里结果只能是Error: ENOENT: no such file or directoryStreaming 不等于 Agent 流式Next.js 的generateStaticParamsasync Server Component能实现页面级流式渲染但无法做到tool output → UI update → user input → next tool call的细粒度、低延迟交互。Paperclip 的 WebSocket 连接直通本地 Node.js 进程延迟 50ms而 Next.js 的 RSC 需要经过 HTTP 请求 → server render → HTML stream → client hydration端到端延迟通常 800ms部署模型错位Next.js 天然导向“部署到云”而 Paperclip 的典型部署是“用户双击start.bat启动本地服务”。我们给某医疗设备厂商做的方案最终交付物就是一个 12MB 的.zip包解压后npm install npm start所有日志分析、DICOM 图像预处理、HL7 消息生成都在客户内网完成完全不触网——这种场景 Next.js 根本不适用。所以 Paperclip 的启动脚本package.json里永远是start: concurrently \npm run react\ \npm run node\两个独立进程react-scripts start启动 Webpack Dev Server端口 3000ts-node src/main.ts启动 Node.js Agent Runtime端口 3001用http-proxy-middleware把/api/*代理到 3001用WebSocket实现双向实时通信。简单、透明、可控。3. 核心模块拆解与实操要点从零搭建一个 Paperclip Agent3.1 Node.js 层Agent Runtime 的骨架设计Paperclip 的 Node.js 层不是 Express 应用而是一个基于EventEmitter的轻量级运行时。它的核心文件结构如下src/ ├── main.ts # Agent 入口初始化事件总线、加载工具、启动 HTTP/WebSocket 服务 ├── agent/ │ ├── lifecycle.ts # 定义 Agent 标准生命周期init() → think() → act() → observe() → loop() │ └── memory.ts # 本地记忆存储JSON 文件 LRU 缓存 ├── tools/ │ ├── filesystem.ts # 封装 fs.promises API提供 listDir、readFile、watchDir 等方法 │ ├── cli-tools.ts # spawn 封装支持超时、信号控制、stdout/stderr 分流 │ └── llm-client.ts # 适配 Ollama / LM Studio / 自建 vLLM 的统一接口 └── utils/ └── logger.ts # 结构化日志level、timestamp、agent_id、tool_name最关键的lifecycle.ts定义了 Agent 的标准行为契约export interface AgentState { id: string; status: idle | thinking | acting | observing | done; memory: Memory; currentThought?: string; lastAction?: ToolCall; observation?: string; } export class AgentRuntime extends EventEmitter { private state: AgentState; constructor(private config: AgentConfig) { super(); this.state { id: crypto.randomUUID(), status: idle, memory: new LocalMemory(config.memoryPath), }; } // think 阶段调用 LLM 生成下一步行动 async think(prompt: string): PromiseToolCall | null { this.setState({ status: thinking }); const response await this.llmClient.chat({ messages: [ { role: system, content: this.config.systemPrompt }, { role: user, content: prompt }, ], tools: this.getAvailableTools(), // 返回工具描述数组供 LLM 选择 }); if (response.tool_calls?.length) { const toolCall response.tool_calls[0]; this.setState({ status: acting, lastAction: toolCall }); return toolCall; } return null; // LLM 决定直接回复不调用工具 } // act 阶段执行工具调用 async act(toolCall: ToolCall): Promisestring { this.setState({ status: acting }); const tool this.tools.find(t t.name toolCall.name); if (!tool) throw new Error(Tool ${toolCall.name} not found); const result await tool.execute(toolCall.arguments); this.setState({ status: observing, observation: result }); return result; } // observe 阶段将工具结果反馈给 LLM进入下一轮 async observe(observation: string): Promisestring { this.setState({ status: observing }); const response await this.llmClient.chat({ messages: [ { role: user, content: observation }, { role: assistant, content: Observation received. } ] }); this.setState({ status: idle, currentThought: response.content }); return response.content; } private setState(update: PartialAgentState) { this.state { ...this.state, ...update }; this.emit(state-change, this.state); // 触发 UI 更新 } }这个设计的关键在于状态变更与事件发射的严格分离setState()方法不仅更新内部状态还通过emit(state-change)广播给所有监听者包括 WebSocket 连接和日志记录器。UI 层通过ipcRenderer.on(state-change, ...)接收避免了轮询或长连接维持。实测下来单个 Agent 实例在 M1 Mac 上内存占用稳定在 45MBCPU 占用峰值 12%远低于 Electron 的 300MB。注意think()方法返回ToolCall | null而不是Promisestring这是 Paperclip 的核心哲学——Agent 必须显式区分“生成行动”和“生成回复”。很多初学者会把 LLM 输出直接当最终答案导致无法插入工具调用。Paperclip 强制要求 LLM 的 system prompt 中包含明确的 tool calling 指令如 “You must use one of the provided tools. If no tool is suitable, respond with ‘I cannot assist with that.’”并在think()返回null时由 UI 层决定是否显示最终回复或提示用户补充信息。3.2 React 层Agent UI 的状态流与通信桥接Paperclip 的 React UI 不是传统 SPA而是一个“状态镜像器”。它不持有任何业务逻辑只做三件事展示状态、捕获用户输入、转发指令。所有useState的初始值都来自 Node.js 层的state-change事件// src/App.tsx import { useEffect, useState } from react; import { ipcRenderer } from electron; // 注意这里用 electron 的 ipcRenderer但 Paperclip 也支持纯 WebSocket 方案 function App() { const [agentState, setAgentState] useStateAgentState | null(null); const [inputValue, setInputValue] useState(); // 初始化首次连接时获取当前状态 useEffect(() { ipcRenderer.send(get-initial-state); const handleStateChange (_: any, state: AgentState) { setAgentState(state); }; ipcRenderer.on(state-change, handleStateChange); return () { ipcRenderer.off(state-change, handleStateChange); }; }, []); // 用户提交输入 const handleSubmit () { if (!inputValue.trim()) return; ipcRenderer.send(user-input, { content: inputValue }); setInputValue(); }; // Agent 状态变化时自动触发 think useEffect(() { if (agentState?.status idle agentState?.memory.lastUserInput) { ipcRenderer.send(trigger-think, { prompt: agentState.memory.lastUserInput }); } }, [agentState]); if (!agentState) return divLoading.../div; return ( div classNameapp Header status{agentState.status} / MessageList messages{agentState.memory.messages} / InputBox value{inputValue} onChange{setInputValue} onSubmit{handleSubmit} / StatusPanel state{agentState} / /div ); } export default App;这里的关键细节useEffect的依赖数组必须精确[agentState?.status]不能写成[agentState]否则每次state-change都会触发重新渲染造成性能问题。我们只关心status变化来驱动think其他字段如messages由MessageList组件自己监听ipcRenderer.send()的语义化命名user-input、trigger-think、run-tool这些 channel 名不是随意起的它们对应 Node.js 层main.ts中的事件监听// src/main.ts ipcMain.on(user-input, (event, payload) { agentRuntime.memory.addUserMessage(payload.content); event.reply(state-change, agentRuntime.state); }); ipcMain.on(trigger-think, async (event, payload) { try { const toolCall await agentRuntime.think(payload.prompt); if (toolCall) { const result await agentRuntime.act(toolCall); await agentRuntime.observe(result); } event.reply(state-change, agentRuntime.state); } catch (err) { console.error(Think failed:, err); event.reply(error, { message: err.message }); } });错误处理下沉到通信层event.reply(error, ...)而不是throw new Error()因为 UI 层需要捕获并展示错误如 “Tool ‘parse_log’ failed: Permission denied”而不是让整个 Agent Runtime 崩溃。3.3 工具开发规范如何编写一个可被 LLM 调用的本地工具Paperclip 的工具Tool不是黑盒函数而是有严格契约的 TypeScript 类。以parse_log工具为例// src/tools/log-parser.ts import { Tool } from ../agent/lifecycle; export class LogParserTool implements Tool { name parse_log; description Parse a log file and extract error patterns, timestamps, and service names. Input must be a valid file path.; parameters { type: object, properties: { file_path: { type: string, description: Absolute or relative path to the log file } }, required: [file_path] }; async execute(args: { file_path: string }): Promisestring { try { // 1. 安全校验禁止路径遍历 if (args.file_path.includes(..) || args.file_path.startsWith(/)) { throw new Error(Invalid file path: traversal detected); } // 2. 构建绝对路径相对于项目根目录 const fullPath path.join(process.cwd(), args.file_path); // 3. 读取文件限制大小防 OOM const stat await fs.stat(fullPath); if (stat.size 10 * 1024 * 1024) { // 10MB 限制 throw new Error(File too large: ${stat.size} bytes); } const content await fs.readFile(fullPath, utf8); // 4. 执行解析这里用正则生产环境建议用专用 parser const errors content.match(/ERROR.*?\n/g) || []; const timestamps content.match(/\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/g) || []; const services Array.from(new Set(content.match(/service: (\w)/g)?.map(m m.split(:)[1].trim()) || [])); return JSON.stringify({ file_path: args.file_path, error_count: errors.length, recent_errors: errors.slice(-3), timestamps: timestamps.slice(0, 5), services: services }, null, 2); } catch (err) { throw new Error(Failed to parse log: ${err.message}); } } }这个工具被注册到 AgentRuntime 时// src/main.ts import { LogParserTool } from ./tools/log-parser; const agentRuntime new AgentRuntime(config); agentRuntime.registerTool(new LogParserTool());LLM 在think()阶段会收到工具描述{ name: parse_log, description: Parse a log file and extract error patterns, timestamps, and service names. Input must be a valid file path., parameters: { type: object, properties: { file_path: { type: string, description: Absolute or relative path to the log file } }, required: [file_path] } }然后 LLM 可能生成这样的 tool call{ name: parse_log, arguments: { file_path: logs/app.log } }实操心得工具开发最容易踩的坑是路径安全和资源泄漏。我们曾在线上环境遇到过用户输入file_path: ../../../../etc/shadow导致敏感文件泄露后来强制加入路径规范化校验const normalized path.normalize(args.file_path); if (normalized.startsWith(..) || normalized.startsWith(/)) { throw new Error(Path traversal attempt blocked); }另一个常见问题是spawn子进程未正确清理。Paperclip 的cli-tools.ts封装了带超时和信号控制的spawnexport async function safeSpawn( command: string, args: string[], options: { timeoutMs?: number; signal?: AbortSignal } {} ): Promise{ stdout: string; stderr: string; code: number } { const controller new AbortController(); if (options.signal) options.signal.addEventListener(abort, () controller.abort()); return new Promise((resolve, reject) { const proc spawn(command, args, { stdio: [pipe, pipe, pipe] }); let stdout ; let stderr ; proc.stdout.on(data, (chunk) stdout chunk.toString()); proc.stderr.on(data, (chunk) stderr chunk.toString()); proc.on(close, (code, signal) { resolve({ stdout, stderr, code: code ?? -1 }); }); proc.on(error, (err) { reject(err); }); // 超时控制 setTimeout(() { if (proc.pid) { proc.kill(SIGTERM); setTimeout(() proc.kill(SIGKILL), 2000); } reject(new Error(Command timed out after ${options.timeoutMs || 30000}ms)); }, options.timeoutMs || 30000); }); }这样即使ffmpeg卡死也会在 30 秒后被强制终止不会让 Agent 无限等待。4. 完整实操流程从安装 Node.js 到部署一个日志分析 Agent4.1 环境准备Node.js 版本与依赖安装Paperclip 对 Node.js 版本有明确要求最低 18.20.4 LTS推荐 20.11.1。为什么不是最新版因为 Node.js 22 的某些实验性特性如--experimental-permission与 Paperclip 的child_process.spawn权限模型冲突而 18.20.4 是最后一个稳定支持fs.watch在 macOS 上可靠工作的 LTS 版本。安装步骤以 Ubuntu 22.04 为例# 1. 卸载旧版 Node.js如果存在 sudo apt remove nodejs npm sudo apt autoremove # 2. 添加 NodeSource 仓库官方推荐 curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - # 3. 安装 Node.js 18.x sudo apt-get install -y nodejs # 4. 验证版本 node -v # 应输出 v18.20.4 npm -v # 应输出 9.9.2 或更高 # 5. 安装构建工具编译 native addon 必需 sudo apt-get install -y build-essential python3注意CentOS 7.9 用户需额外安装gcc-c和python3-devel且 Node.js 18 的二进制包需从官网手动下载https://nodejs.org/dist/v18.20.4/因为 CentOS 7 的 glibc 版本过低NodeSource 仓库不支持。安装完成后全局安装pnpmPaperclip 官方推荐比 npm/yarn 更快更省磁盘npm install -g pnpm pnpm -v # 验证输出4.2 初始化项目使用 Paperclip CLI 脚手架Paperclip 提供官方 CLI 工具一键生成标准项目结构# 创建新项目 pnpm create papercliplatest my-log-analyzer # 进入目录 cd my-log-analyzer # 安装依赖自动识别 Node.js 版本安装对应依赖 pnpm install # 启动开发环境 pnpm devCLI 会生成以下结构my-log-analyzer/ ├── package.json ├── tsconfig.json ├── public/ │ └── index.html ├── src/ │ ├── main.ts # Node.js 入口 │ ├── renderer.ts # React 入口Web │ ├── agent/ │ │ └── config.ts # Agent 配置system prompt、memory path、LLM endpoint │ ├── tools/ │ │ └── index.ts # 工具注册入口 │ └── utils/ │ └── logger.ts └── scripts/ └── setup.sh # 一键安装 Ollama 下载 llama3 模型src/agent/config.ts是关键配置文件export const AGENT_CONFIG { // LLM 配置支持多种后端 llm: { provider: ollama, // ollama | lmstudio | vllm | openai model: llama3:8b, // Ollama 模型名 baseUrl: http://localhost:11434, // Ollama 默认地址 }, // 记忆存储路径相对项目根目录 memoryPath: ./data/memory.json, // 系统提示词决定 Agent 行为 systemPrompt: You are a senior DevOps engineer analyzing application logs. Your goal is to identify errors, extract timestamps, and suggest root causes. Use tools only when necessary. If user asks for summary, reply directly. Always respond in Chinese. .trim(), // 工具白名单提高 LLM 调用准确率 availableTools: [parse_log, list_files, search_in_logs], };4.3 开发第一个工具list_files工具实现在src/tools/下新建list-files.tsimport { Tool } from ../agent/lifecycle; import * as fs from fs/promises; import * as path from path; export class ListFilesTool implements Tool { name list_files; description List files and directories in a specified path. Supports filtering by extension.; parameters { type: object, properties: { path: { type: string, description: Directory path to list. Must be relative to project root. }, extensions: { type: array, items: { type: string }, description: Optional list of file extensions to filter (e.g., [.log, .json]) } }, required: [path] }; async execute(args: { path: string; extensions?: string[] }): Promisestring { try { // 路径安全校验 if (args.path.includes(..) || args.path.startsWith(/)) { throw new Error(Invalid path: traversal detected); } const fullPath path.join(process.cwd(), args.path); const entries await fs.readdir(fullPath, { withFileTypes: true }); const filtered entries.filter(entry { if (!args.extensions) return true; const ext path.extname(entry.name).toLowerCase(); return args.extensions.some(e e.toLowerCase() ext); }); const result filtered.map(entry ({ name: entry.name, type: entry.isDirectory() ? directory : file, size: entry.isDirectory() ? undefined : entry.size, })); return JSON.stringify(result, null, 2); } catch (err) { throw new Error(Failed to list files: ${err.message}); } } }然后在src/tools/index.ts中注册import { ListFilesTool } from ./list-files; export const TOOLS [ new ListFilesTool(), // ... 其他工具 ];4.4 React UI 开发构建日志分析面板修改src/renderer.tsx替换默认 UIimport React, { useState, useEffect } from react; import { ipcRenderer } from electron; function LogAnalyzer() { const [files, setFiles] useStateany[]([]); const [selectedFile, setSelectedFile] useStatestring(); const [analysisResult, setAnalysisResult] useStatestring(); const [isAnalyzing, setIsAnalyzing] useState(false); // 加载文件列表 useEffect(() { ipcRenderer.send(run-tool, { name: list_files, arguments: { path: logs/ } }); const handleToolResult (_: any, result: string) { try { const parsed JSON.parse(result); setFiles(parsed); } catch (e) { console.error(Parse files list failed:, e); } }; ipcRenderer.on(tool-result, handleToolResult); return () ipcRenderer.off(tool-result, handleToolResult); }, []); const handleAnalyze () { if (!selectedFile) return; setIsAnalyzing(true); setAnalysisResult(); ipcRenderer.send(run-tool, { name: parse_log, arguments: { file_path: logs/${selectedFile} } }); const handleParseResult (_: any, result: string) { setAnalysisResult(result); setIsAnalyzing(false); }; ipcRenderer.once(tool-result, handleParseResult); }; return ( div classNamelog-analyzer h2日志分析面板/h2 div classNamefile-selector label选择日志文件/label select value{selectedFile} onChange{(e) setSelectedFile(e.target.value)} option value-- 请选择 --/option {files.map((file, i) ( option key{i} value{file.name}{file.name}/option ))} /select /div button onClick{handleAnalyze} disabled{isAnalyzing || !selectedFile} {isAnalyzing ? 分析中... : 开始分析} /button {analysisResult ( div classNameresult-panel h3分析结果/h3 pre{analysisResult}/pre /div )} /div ); } export default LogAnalyzer;4.5 启动与调试全流程验证启动 Ollama如果未安装curl -fsSL https://ollama.com/install.sh | sh ollama run llama3:8b # 下载并运行模型启动 Paperclippnpm dev控制台会输出 Starting Paperclip Agent... Node.js Runtime listening on http://localhost:3001 React UI running on http://localhost:3000 Agent initialized with ID: 7a2b3c4d...打开浏览器http://localhost:3000看到日志分析面板点击下拉框选择app.log确保logs/app.log文件存在点击“开始分析”观察Node.js 控制台输出Executing tool: parse_log with args { file_path: logs/app.log }几秒后UI 显示 JSON
1. 项目概述Paperclip 不是回形针而是一个面向 AI Agent 开发的轻量级 Node.js 运行时框架你搜“paperclip”时第一反应可能是办公桌抽屉里那枚银色小金属件——但最近在掘金、GitHub 和 React 前端技术群聊里“Paperclip”正以高频词身份反复出现和 Node.js、React、OpenClaw 绑定在一起。它不是 UI 组件库不是状态管理工具更不是又一个“AI 前端胶水层”。Paperclip 是一个专为本地化、可调试、低侵入式 AI Agent 构建而设计的 Node.js 运行时框架核心定位非常明确让开发者用 React 写 Agent 的逻辑界面UI State Interaction用 Node.js 承载真实 Agent 的执行上下文LLM 调用、工具调度、文件系统访问、进程控制两者通过极简 IPC 通信桥接不依赖浏览器环境、不强制云部署、不抽象掉关键控制权。我去年在给一家做工业设备远程诊断的团队做技术咨询时就遇到典型痛点他们想用 LLM 解析现场上传的 JSON 日志PDF 故障报告生成维修建议并调用内部工单系统 API。当时试过 LangChain Next.js SSR、也跑过 FastAPI Streamlit但要么调试链路太长前端改个 prompt 得等 30 秒热更新、要么权限太重需要完整 Python 环境GPU 支持、要么根本没法读取本地设备日志目录。最后我们用 Paperclip 搭了一套方案React 做诊断面板带拖拽上传区、实时 token 流式渲染、历史会话树Node.js 层直接fs.readdirSync(/var/log/device/)读取原始日志用child_process.spawn(python3, [analyze.py])调用遗留 Python 分析脚本再把结果喂给本地 Ollama 模型。整个流程在开发机上 5 分钟搭完上线后运维同事能直接 SSH 进去改 Node.js 里的工具函数不用碰前端构建。它和 OpenClaw 的关系常被误解——OpenClaw 是一个功能完备、开箱即用的 AI Agent 平台含 Web UI、多模型路由、记忆存储、插件市场而 Paperclip 更像它的“内核拆解版”去掉所有平台级封装只保留最精简的 Agent 生命周期管理init → think → act → observe → loop和 React/Node 双端协同机制。你可以把它理解成“OpenClaw 的最小可行内核”或者“手写 React Agent 的标准化脚手架”。这也是为什么搜索热词里同时出现 “openclaw ubuntu安装教程” 和 “手写react agent”——前者要开箱即用后者要深度掌控Paperclip 正好卡在这中间。适合谁不是纯 UI 工程师也不是纯后端架构师而是那些正在从“调 API 做智能对话”迈向“构建可落地 Agent 应用”的实战派懂 React Hooks 状态流、能写 Node.js 文件操作和子进程调用、愿意为业务逻辑写真实工具函数比如解析 Excel、调用串口、生成 PDF 报告的人。如果你还在用fetch()轮询后端接口来模拟 Agent 行为或者把所有逻辑硬塞进useEffect里靠setInterval驱动Paperclip 提供的是一条更干净、更可控、更贴近真实 Agent 运行语义的路径。2. 核心设计思路与选型逻辑为什么是 Node.js React为什么拒绝 Electron 和 Next.js2.1 为什么必须用 Node.js 作为 Agent 执行层这不是为了“全栈工程师情怀”而是由 AI Agent 的本质决定的。Agent 的核心能力不是“展示结果”而是“感知环境→决策→执行→观察反馈”。这个闭环里90% 的关键动作都发生在服务端上下文文件系统访问读取用户上传的.log、.csv、.pcap文件扫描/tmp/下临时生成的截图监听./data/目录变化触发自动分析进程控制调用ffmpeg转码视频、用pandoc转换文档格式、执行nmap扫描局域网设备、启动tshark抓包本地服务集成连接本地 PostgreSQL 存储记忆、调用curl http://localhost:8080/api/v1/status获取设备心跳、向mqtt://localhost:1883发布控制指令模型运行时支持加载本地 Ollama 模型ollama run llama3、调用 LM Studio 的 HTTP 接口、甚至直接require(xenova/transformers)在 Node.js 里跑小型量化模型。这些能力浏览器环境天然缺失。Electron 虽然能访问文件系统但它把整个 Chromium 实例打包进来内存占用动辄 800MB启动慢、调试难、更新麻烦——而 Paperclip 的 Node.js 层启动时间 300msps aux | grep paperclip一眼就能看到进程树node --inspect-brk直接断点调试工具函数。更重要的是Node.js 的child_process、fs.promises、streamAPI 对上述场景支持成熟稳定错误处理清晰比如spawn的exit code、signal、stderr分离不像 Electron 的remote模块已被废弃新版本里跨进程通信还得自己搭 IPC 通道。提示Paperclip 的 Node.js 层默认使用 CommonJS 模块系统非 ESM原因很实际——大量现成的 CLI 工具如jq、exiftool、pdfinfo都是通过spawn调用的而 Node.js 的 ESM 对require.resolve()动态路径解析支持较弱CommonJS 在__dirname和path.join(__dirname, ../tools/)这类路径拼接上更可靠。这不是守旧是为降低工具链接入成本。2.2 为什么 React 是唯一推荐的 UI 层而非 Vue 或 SvelteReact 的优势不在语法糖而在其State Effect Ref 的三元模型完美映射 Agent 的运行范式useState管理 Agent 的当前状态快照如currentStep: analyzing | waiting_for_user_input | executing_tooluseEffect处理副作用触发当currentStep executing_tool时自动调用ipcRenderer.send(run-tool, { name: parse_log, args: [...] })useRef持有长期引用对象如const toolProcessRef useRef(null)用于中止正在运行的ffmpeg进程。对比来看Vue 的watch虽然也能响应状态变化但触发时机不如useEffect明确watch是异步队列useEffect是同步清理异步执行Svelte 的$:响应式声明在复杂嵌套状态如agent.memory.conversations[0].messages[3].tool_calls[0].result下容易产生难以追踪的 rerender。而 Paperclip 的官方模板里一个典型的 Agent UI 组件结构是function DiagnosticPanel() { const [state, setState] useStateAgentState({ status: idle, currentTool: null, messages: [] }); // 当 state.status 变为 running_tool自动触发 Node.js 层执行 useEffect(() { if (state.status running_tool state.currentTool) { ipcRenderer.send(execute-tool, state.currentTool); // 同时启动 WebSocket 监听工具输出流 const ws new WebSocket(ws://localhost:3001/tool-output); ws.onmessage (e) { setState(prev ({ ...prev, messages: [...prev.messages, { role: tool, content: e.data }] })); }; } }, [state.status, state.currentTool]); return ( div UploadZone onFiles{(files) setState({...state, status: processing})} / MessageList messages{state.messages} / StatusIndicator status{state.status} / /div ); }这种“状态驱动行为”的模式让 UI 层彻底摆脱了手动管理loading、error、success三态的繁琐所有 Agent 的生命周期流转都由state.status单一字段驱动逻辑集中、易测试、易扩展。这也是为什么“react 面经”里高频出现useReducer和useTransition——Paperclip 的实际项目中我们确实用useReducer管理 Agent 的复杂状态机12 个状态节点用useTransition保证大文件上传时不阻塞 UI 响应。2.3 为什么坚决不用 Next.jsServer Components 会破坏 Agent 的本地性Next.js 的 App Router 和 Server Components 看似强大但对 Paperclip 场景是灾难性的Server Component 无法访问 Node.js 的fs、child_process它运行在 Vercel 边缘函数或你自己部署的 Node.js server 上但 Paperclip 的核心诉求是“本地 Agent”——工具必须运行在用户本机而不是远端服务器。把fs.readdirSync(/home/user/logs/)放到 Server Component 里结果只能是Error: ENOENT: no such file or directoryStreaming 不等于 Agent 流式Next.js 的generateStaticParamsasync Server Component能实现页面级流式渲染但无法做到tool output → UI update → user input → next tool call的细粒度、低延迟交互。Paperclip 的 WebSocket 连接直通本地 Node.js 进程延迟 50ms而 Next.js 的 RSC 需要经过 HTTP 请求 → server render → HTML stream → client hydration端到端延迟通常 800ms部署模型错位Next.js 天然导向“部署到云”而 Paperclip 的典型部署是“用户双击start.bat启动本地服务”。我们给某医疗设备厂商做的方案最终交付物就是一个 12MB 的.zip包解压后npm install npm start所有日志分析、DICOM 图像预处理、HL7 消息生成都在客户内网完成完全不触网——这种场景 Next.js 根本不适用。所以 Paperclip 的启动脚本package.json里永远是start: concurrently \npm run react\ \npm run node\两个独立进程react-scripts start启动 Webpack Dev Server端口 3000ts-node src/main.ts启动 Node.js Agent Runtime端口 3001用http-proxy-middleware把/api/*代理到 3001用WebSocket实现双向实时通信。简单、透明、可控。3. 核心模块拆解与实操要点从零搭建一个 Paperclip Agent3.1 Node.js 层Agent Runtime 的骨架设计Paperclip 的 Node.js 层不是 Express 应用而是一个基于EventEmitter的轻量级运行时。它的核心文件结构如下src/ ├── main.ts # Agent 入口初始化事件总线、加载工具、启动 HTTP/WebSocket 服务 ├── agent/ │ ├── lifecycle.ts # 定义 Agent 标准生命周期init() → think() → act() → observe() → loop() │ └── memory.ts # 本地记忆存储JSON 文件 LRU 缓存 ├── tools/ │ ├── filesystem.ts # 封装 fs.promises API提供 listDir、readFile、watchDir 等方法 │ ├── cli-tools.ts # spawn 封装支持超时、信号控制、stdout/stderr 分流 │ └── llm-client.ts # 适配 Ollama / LM Studio / 自建 vLLM 的统一接口 └── utils/ └── logger.ts # 结构化日志level、timestamp、agent_id、tool_name最关键的lifecycle.ts定义了 Agent 的标准行为契约export interface AgentState { id: string; status: idle | thinking | acting | observing | done; memory: Memory; currentThought?: string; lastAction?: ToolCall; observation?: string; } export class AgentRuntime extends EventEmitter { private state: AgentState; constructor(private config: AgentConfig) { super(); this.state { id: crypto.randomUUID(), status: idle, memory: new LocalMemory(config.memoryPath), }; } // think 阶段调用 LLM 生成下一步行动 async think(prompt: string): PromiseToolCall | null { this.setState({ status: thinking }); const response await this.llmClient.chat({ messages: [ { role: system, content: this.config.systemPrompt }, { role: user, content: prompt }, ], tools: this.getAvailableTools(), // 返回工具描述数组供 LLM 选择 }); if (response.tool_calls?.length) { const toolCall response.tool_calls[0]; this.setState({ status: acting, lastAction: toolCall }); return toolCall; } return null; // LLM 决定直接回复不调用工具 } // act 阶段执行工具调用 async act(toolCall: ToolCall): Promisestring { this.setState({ status: acting }); const tool this.tools.find(t t.name toolCall.name); if (!tool) throw new Error(Tool ${toolCall.name} not found); const result await tool.execute(toolCall.arguments); this.setState({ status: observing, observation: result }); return result; } // observe 阶段将工具结果反馈给 LLM进入下一轮 async observe(observation: string): Promisestring { this.setState({ status: observing }); const response await this.llmClient.chat({ messages: [ { role: user, content: observation }, { role: assistant, content: Observation received. } ] }); this.setState({ status: idle, currentThought: response.content }); return response.content; } private setState(update: PartialAgentState) { this.state { ...this.state, ...update }; this.emit(state-change, this.state); // 触发 UI 更新 } }这个设计的关键在于状态变更与事件发射的严格分离setState()方法不仅更新内部状态还通过emit(state-change)广播给所有监听者包括 WebSocket 连接和日志记录器。UI 层通过ipcRenderer.on(state-change, ...)接收避免了轮询或长连接维持。实测下来单个 Agent 实例在 M1 Mac 上内存占用稳定在 45MBCPU 占用峰值 12%远低于 Electron 的 300MB。注意think()方法返回ToolCall | null而不是Promisestring这是 Paperclip 的核心哲学——Agent 必须显式区分“生成行动”和“生成回复”。很多初学者会把 LLM 输出直接当最终答案导致无法插入工具调用。Paperclip 强制要求 LLM 的 system prompt 中包含明确的 tool calling 指令如 “You must use one of the provided tools. If no tool is suitable, respond with ‘I cannot assist with that.’”并在think()返回null时由 UI 层决定是否显示最终回复或提示用户补充信息。3.2 React 层Agent UI 的状态流与通信桥接Paperclip 的 React UI 不是传统 SPA而是一个“状态镜像器”。它不持有任何业务逻辑只做三件事展示状态、捕获用户输入、转发指令。所有useState的初始值都来自 Node.js 层的state-change事件// src/App.tsx import { useEffect, useState } from react; import { ipcRenderer } from electron; // 注意这里用 electron 的 ipcRenderer但 Paperclip 也支持纯 WebSocket 方案 function App() { const [agentState, setAgentState] useStateAgentState | null(null); const [inputValue, setInputValue] useState(); // 初始化首次连接时获取当前状态 useEffect(() { ipcRenderer.send(get-initial-state); const handleStateChange (_: any, state: AgentState) { setAgentState(state); }; ipcRenderer.on(state-change, handleStateChange); return () { ipcRenderer.off(state-change, handleStateChange); }; }, []); // 用户提交输入 const handleSubmit () { if (!inputValue.trim()) return; ipcRenderer.send(user-input, { content: inputValue }); setInputValue(); }; // Agent 状态变化时自动触发 think useEffect(() { if (agentState?.status idle agentState?.memory.lastUserInput) { ipcRenderer.send(trigger-think, { prompt: agentState.memory.lastUserInput }); } }, [agentState]); if (!agentState) return divLoading.../div; return ( div classNameapp Header status{agentState.status} / MessageList messages{agentState.memory.messages} / InputBox value{inputValue} onChange{setInputValue} onSubmit{handleSubmit} / StatusPanel state{agentState} / /div ); } export default App;这里的关键细节useEffect的依赖数组必须精确[agentState?.status]不能写成[agentState]否则每次state-change都会触发重新渲染造成性能问题。我们只关心status变化来驱动think其他字段如messages由MessageList组件自己监听ipcRenderer.send()的语义化命名user-input、trigger-think、run-tool这些 channel 名不是随意起的它们对应 Node.js 层main.ts中的事件监听// src/main.ts ipcMain.on(user-input, (event, payload) { agentRuntime.memory.addUserMessage(payload.content); event.reply(state-change, agentRuntime.state); }); ipcMain.on(trigger-think, async (event, payload) { try { const toolCall await agentRuntime.think(payload.prompt); if (toolCall) { const result await agentRuntime.act(toolCall); await agentRuntime.observe(result); } event.reply(state-change, agentRuntime.state); } catch (err) { console.error(Think failed:, err); event.reply(error, { message: err.message }); } });错误处理下沉到通信层event.reply(error, ...)而不是throw new Error()因为 UI 层需要捕获并展示错误如 “Tool ‘parse_log’ failed: Permission denied”而不是让整个 Agent Runtime 崩溃。3.3 工具开发规范如何编写一个可被 LLM 调用的本地工具Paperclip 的工具Tool不是黑盒函数而是有严格契约的 TypeScript 类。以parse_log工具为例// src/tools/log-parser.ts import { Tool } from ../agent/lifecycle; export class LogParserTool implements Tool { name parse_log; description Parse a log file and extract error patterns, timestamps, and service names. Input must be a valid file path.; parameters { type: object, properties: { file_path: { type: string, description: Absolute or relative path to the log file } }, required: [file_path] }; async execute(args: { file_path: string }): Promisestring { try { // 1. 安全校验禁止路径遍历 if (args.file_path.includes(..) || args.file_path.startsWith(/)) { throw new Error(Invalid file path: traversal detected); } // 2. 构建绝对路径相对于项目根目录 const fullPath path.join(process.cwd(), args.file_path); // 3. 读取文件限制大小防 OOM const stat await fs.stat(fullPath); if (stat.size 10 * 1024 * 1024) { // 10MB 限制 throw new Error(File too large: ${stat.size} bytes); } const content await fs.readFile(fullPath, utf8); // 4. 执行解析这里用正则生产环境建议用专用 parser const errors content.match(/ERROR.*?\n/g) || []; const timestamps content.match(/\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/g) || []; const services Array.from(new Set(content.match(/service: (\w)/g)?.map(m m.split(:)[1].trim()) || [])); return JSON.stringify({ file_path: args.file_path, error_count: errors.length, recent_errors: errors.slice(-3), timestamps: timestamps.slice(0, 5), services: services }, null, 2); } catch (err) { throw new Error(Failed to parse log: ${err.message}); } } }这个工具被注册到 AgentRuntime 时// src/main.ts import { LogParserTool } from ./tools/log-parser; const agentRuntime new AgentRuntime(config); agentRuntime.registerTool(new LogParserTool());LLM 在think()阶段会收到工具描述{ name: parse_log, description: Parse a log file and extract error patterns, timestamps, and service names. Input must be a valid file path., parameters: { type: object, properties: { file_path: { type: string, description: Absolute or relative path to the log file } }, required: [file_path] } }然后 LLM 可能生成这样的 tool call{ name: parse_log, arguments: { file_path: logs/app.log } }实操心得工具开发最容易踩的坑是路径安全和资源泄漏。我们曾在线上环境遇到过用户输入file_path: ../../../../etc/shadow导致敏感文件泄露后来强制加入路径规范化校验const normalized path.normalize(args.file_path); if (normalized.startsWith(..) || normalized.startsWith(/)) { throw new Error(Path traversal attempt blocked); }另一个常见问题是spawn子进程未正确清理。Paperclip 的cli-tools.ts封装了带超时和信号控制的spawnexport async function safeSpawn( command: string, args: string[], options: { timeoutMs?: number; signal?: AbortSignal } {} ): Promise{ stdout: string; stderr: string; code: number } { const controller new AbortController(); if (options.signal) options.signal.addEventListener(abort, () controller.abort()); return new Promise((resolve, reject) { const proc spawn(command, args, { stdio: [pipe, pipe, pipe] }); let stdout ; let stderr ; proc.stdout.on(data, (chunk) stdout chunk.toString()); proc.stderr.on(data, (chunk) stderr chunk.toString()); proc.on(close, (code, signal) { resolve({ stdout, stderr, code: code ?? -1 }); }); proc.on(error, (err) { reject(err); }); // 超时控制 setTimeout(() { if (proc.pid) { proc.kill(SIGTERM); setTimeout(() proc.kill(SIGKILL), 2000); } reject(new Error(Command timed out after ${options.timeoutMs || 30000}ms)); }, options.timeoutMs || 30000); }); }这样即使ffmpeg卡死也会在 30 秒后被强制终止不会让 Agent 无限等待。4. 完整实操流程从安装 Node.js 到部署一个日志分析 Agent4.1 环境准备Node.js 版本与依赖安装Paperclip 对 Node.js 版本有明确要求最低 18.20.4 LTS推荐 20.11.1。为什么不是最新版因为 Node.js 22 的某些实验性特性如--experimental-permission与 Paperclip 的child_process.spawn权限模型冲突而 18.20.4 是最后一个稳定支持fs.watch在 macOS 上可靠工作的 LTS 版本。安装步骤以 Ubuntu 22.04 为例# 1. 卸载旧版 Node.js如果存在 sudo apt remove nodejs npm sudo apt autoremove # 2. 添加 NodeSource 仓库官方推荐 curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - # 3. 安装 Node.js 18.x sudo apt-get install -y nodejs # 4. 验证版本 node -v # 应输出 v18.20.4 npm -v # 应输出 9.9.2 或更高 # 5. 安装构建工具编译 native addon 必需 sudo apt-get install -y build-essential python3注意CentOS 7.9 用户需额外安装gcc-c和python3-devel且 Node.js 18 的二进制包需从官网手动下载https://nodejs.org/dist/v18.20.4/因为 CentOS 7 的 glibc 版本过低NodeSource 仓库不支持。安装完成后全局安装pnpmPaperclip 官方推荐比 npm/yarn 更快更省磁盘npm install -g pnpm pnpm -v # 验证输出4.2 初始化项目使用 Paperclip CLI 脚手架Paperclip 提供官方 CLI 工具一键生成标准项目结构# 创建新项目 pnpm create papercliplatest my-log-analyzer # 进入目录 cd my-log-analyzer # 安装依赖自动识别 Node.js 版本安装对应依赖 pnpm install # 启动开发环境 pnpm devCLI 会生成以下结构my-log-analyzer/ ├── package.json ├── tsconfig.json ├── public/ │ └── index.html ├── src/ │ ├── main.ts # Node.js 入口 │ ├── renderer.ts # React 入口Web │ ├── agent/ │ │ └── config.ts # Agent 配置system prompt、memory path、LLM endpoint │ ├── tools/ │ │ └── index.ts # 工具注册入口 │ └── utils/ │ └── logger.ts └── scripts/ └── setup.sh # 一键安装 Ollama 下载 llama3 模型src/agent/config.ts是关键配置文件export const AGENT_CONFIG { // LLM 配置支持多种后端 llm: { provider: ollama, // ollama | lmstudio | vllm | openai model: llama3:8b, // Ollama 模型名 baseUrl: http://localhost:11434, // Ollama 默认地址 }, // 记忆存储路径相对项目根目录 memoryPath: ./data/memory.json, // 系统提示词决定 Agent 行为 systemPrompt: You are a senior DevOps engineer analyzing application logs. Your goal is to identify errors, extract timestamps, and suggest root causes. Use tools only when necessary. If user asks for summary, reply directly. Always respond in Chinese. .trim(), // 工具白名单提高 LLM 调用准确率 availableTools: [parse_log, list_files, search_in_logs], };4.3 开发第一个工具list_files工具实现在src/tools/下新建list-files.tsimport { Tool } from ../agent/lifecycle; import * as fs from fs/promises; import * as path from path; export class ListFilesTool implements Tool { name list_files; description List files and directories in a specified path. Supports filtering by extension.; parameters { type: object, properties: { path: { type: string, description: Directory path to list. Must be relative to project root. }, extensions: { type: array, items: { type: string }, description: Optional list of file extensions to filter (e.g., [.log, .json]) } }, required: [path] }; async execute(args: { path: string; extensions?: string[] }): Promisestring { try { // 路径安全校验 if (args.path.includes(..) || args.path.startsWith(/)) { throw new Error(Invalid path: traversal detected); } const fullPath path.join(process.cwd(), args.path); const entries await fs.readdir(fullPath, { withFileTypes: true }); const filtered entries.filter(entry { if (!args.extensions) return true; const ext path.extname(entry.name).toLowerCase(); return args.extensions.some(e e.toLowerCase() ext); }); const result filtered.map(entry ({ name: entry.name, type: entry.isDirectory() ? directory : file, size: entry.isDirectory() ? undefined : entry.size, })); return JSON.stringify(result, null, 2); } catch (err) { throw new Error(Failed to list files: ${err.message}); } } }然后在src/tools/index.ts中注册import { ListFilesTool } from ./list-files; export const TOOLS [ new ListFilesTool(), // ... 其他工具 ];4.4 React UI 开发构建日志分析面板修改src/renderer.tsx替换默认 UIimport React, { useState, useEffect } from react; import { ipcRenderer } from electron; function LogAnalyzer() { const [files, setFiles] useStateany[]([]); const [selectedFile, setSelectedFile] useStatestring(); const [analysisResult, setAnalysisResult] useStatestring(); const [isAnalyzing, setIsAnalyzing] useState(false); // 加载文件列表 useEffect(() { ipcRenderer.send(run-tool, { name: list_files, arguments: { path: logs/ } }); const handleToolResult (_: any, result: string) { try { const parsed JSON.parse(result); setFiles(parsed); } catch (e) { console.error(Parse files list failed:, e); } }; ipcRenderer.on(tool-result, handleToolResult); return () ipcRenderer.off(tool-result, handleToolResult); }, []); const handleAnalyze () { if (!selectedFile) return; setIsAnalyzing(true); setAnalysisResult(); ipcRenderer.send(run-tool, { name: parse_log, arguments: { file_path: logs/${selectedFile} } }); const handleParseResult (_: any, result: string) { setAnalysisResult(result); setIsAnalyzing(false); }; ipcRenderer.once(tool-result, handleParseResult); }; return ( div classNamelog-analyzer h2日志分析面板/h2 div classNamefile-selector label选择日志文件/label select value{selectedFile} onChange{(e) setSelectedFile(e.target.value)} option value-- 请选择 --/option {files.map((file, i) ( option key{i} value{file.name}{file.name}/option ))} /select /div button onClick{handleAnalyze} disabled{isAnalyzing || !selectedFile} {isAnalyzing ? 分析中... : 开始分析} /button {analysisResult ( div classNameresult-panel h3分析结果/h3 pre{analysisResult}/pre /div )} /div ); } export default LogAnalyzer;4.5 启动与调试全流程验证启动 Ollama如果未安装curl -fsSL https://ollama.com/install.sh | sh ollama run llama3:8b # 下载并运行模型启动 Paperclippnpm dev控制台会输出 Starting Paperclip Agent... Node.js Runtime listening on http://localhost:3001 React UI running on http://localhost:3000 Agent initialized with ID: 7a2b3c4d...打开浏览器http://localhost:3000看到日志分析面板点击下拉框选择app.log确保logs/app.log文件存在点击“开始分析”观察Node.js 控制台输出Executing tool: parse_log with args { file_path: logs/app.log }几秒后UI 显示 JSON
