paperclip：轻量级AI Agent编排实战，Node.js+React+Qwen2.5-3B

1. 从“paperclip”说起：一个被低估的AI Agent编排思路

第一次看到“paperclip”这个词，很多人脑子里蹦出来的可能是那个经典的“回形针助手”——就是早年Office里那个总爱跳出来问“您似乎正在写信，需要帮助吗”的小动画。但在AI Agent的语境下，paperclip指向的是一种更本质的东西：把零散的工具、模型、数据源像回形针一样“夹”在一起，形成一个可调度、可编排、可观测的工作流。

我接触过不少号称“AI Agent框架”的项目，大多数要么太重——上来就是一堆抽象概念，学半天还没跑通一个demo；要么太轻——本质上就是个API调用封装，谈不上“编排”。paperclip这个方向之所以值得聊，是因为它踩中了一个真实痛点：当你的系统里同时存在Node.js服务、React前端、多个AI模型、外部工具接口时，怎么让它们像一个团队一样协作，而不是各自为政。

这篇文章适合三类人看：第一类是想从零搭一个AI Agent编排层的前端或全栈工程师；第二类是在用OpenClaw这类工具做自动化，但总觉得“差点意思”的实践者；第三类是对React + Node.js技术栈熟悉，想看看AI Agent到底怎么落地的人。我会从设计思路、核心细节、实操过程、问题排查四个维度展开，尽量把“为什么这么做”讲清楚，而不是只丢一堆代码。

提示：本文涉及的Node.js版本建议在22.12+，React部分基于函数组件与Hooks体系，不涉及类组件写法。

2. 整体设计：为什么是“回形针”而不是“大管家”

2.1 核心思路：轻编排、重连接

很多AI Agent框架喜欢把自己定位成“大管家”——什么都要管，从模型加载到记忆存储到工具注册到任务规划，全包。结果就是学习曲线陡峭，调试困难，一旦某个环节出问题，你根本不知道是框架的锅还是自己的锅。

paperclip的思路反过来：它不试图成为大脑，而是成为“连接器”。你可以把它理解成一个智能路由层——左边是各种输入源（用户消息、文件变化、定时任务、Webhook），右边是各种执行单元（本地模型、远程API、脚本、数据库操作），paperclip负责在中间做匹配、转发、状态跟踪。

这种设计的好处很明显：

• 技术栈无关：你的模型可以是Qwen2.5-3B本地跑，也可以是远程接口，paperclip不关心，它只关心输入输出格式。
• 渐进式增强：一开始可以只接一个模型、一个工具，跑通了再加，不会因为框架的复杂度而卡住。
• 调试友好：每个环节都是显式的，出问题能快速定位是连接层、模型层还是工具层。

我试过用“大管家”型框架做一个文件监控+自动摘要的Agent，光是把框架跑起来就花了两天，最后发现它内置的文件监控模块和我的Node.js版本不兼容。换成paperclip这种轻编排思路后，文件监控直接用Node.js的fs.watch，摘要模型单独调，中间用paperclip做事件转发，半天就跑通了。

2.2 技术选型：Node.js + React + AI Agents的组合逻辑

为什么是Node.js而不是Python？这个问题我被问过很多次。Python在AI领域确实生态更成熟，但paperclip的场景里，Node.js有几个不可替代的优势：

第一，事件驱动模型天然适合Agent编排。Node.js的EventEmitter、Stream、异步I/O，本质上就是在处理“一件事触发另一件事”的逻辑，这和Agent的工作方式高度吻合。你用Python写异步编排，还得考虑GIL、asyncio事件循环的嵌套问题，Node.js这边顺手得多。

第二，前后端同构。如果你的Agent需要跟React前端交互——比如实时推送Agent的执行状态、展示中间结果——Node.js作为中间层可以无缝衔接。前端用React + SSE/WebSocket，后端用Node.js做Agent调度，数据格式统一用JSON，省去了跨语言序列化的麻烦。

第三，部署轻量。一个Node.js进程加上几个依赖包，扔到任何支持Node.js的服务器上就能跑。CentOS 7.9上装Node.js 22.12+虽然需要额外步骤（后面会讲），但一旦装好，部署成本极低。

React在这个组合里的角色往往被低估。很多人觉得React只是“画界面”的，但在paperclip场景下，React承担的是Agent状态可视化的职责。Agent在后台跑了什么、当前在哪一步、调用了哪个工具、返回了什么结果——这些信息通过SSE推送到前端，用React组件实时渲染，你才能对Agent的行为有直观感知。没有这层可视化，调试Agent就像盲人摸象。

2.3 与OpenClaw的关系：互补而非替代

OpenClaw是一个很实用的自动化工具，但它的定位偏向“执行器”——你告诉它做什么，它去做。paperclip的定位偏向“编排器”——它决定什么时候、用什么、按什么顺序去做。

举个例子：你想实现“监控某个文件夹，有新文件就自动摘要，摘要结果推送到Teams”。OpenClaw可以完成“摘要”和“推送”这两个动作，但“监控文件夹”和“决定何时触发”需要额外的逻辑。paperclip就是补上这一环的。

实际部署中，我通常把paperclip作为主控层，OpenClaw作为工具层的一个可选执行单元。paperclip监听到文件变化后，调用OpenClaw的接口执行摘要，拿到结果后再通过paperclip的推送模块发到Teams。这样职责清晰，任何一层出问题都不会影响其他层。

注意：OpenClaw在SL2环境下有时会出现安全验证问题，典型报错是提示需要在PowerShell中运行wsl --status。这通常是因为WSL子系统状态异常导致的，跟paperclip本身无关，但如果你在Windows上做开发，这个问题会卡住整个流程，后面排查章节会详细说。

3. 核心细节：从零搭建paperclip编排层的五个关键决策

3.1 事件模型设计：为什么用“主题-订阅”而不是“直接调用”

paperclip内部的事件流转，我建议用“主题-订阅”模式，而不是简单的函数直接调用。原因在于Agent场景下，一个事件往往需要触发多个动作，而且这些动作之间可能没有强依赖关系。

比如“文件变化”这个事件，可能需要同时触发：摘要生成、日志记录、前端状态更新。如果用直接调用，你得在文件监控的回调里依次调用三个函数，耦合度高，加一个新动作就要改回调。用主题-订阅模式，文件监控只负责发布file:changed事件，摘要模块、日志模块、前端推送模块各自订阅这个事件，互不干扰。

Node.js里实现这个很简单，用内置的EventEmitter就够了：

const EventEmitter = require('events'); const bus = new EventEmitter(); // 文件监控模块 fs.watch(watchPath, (eventType, filename) => { bus.emit('file:changed', { path: path.join(watchPath, filename), eventType }); }); // 摘要模块 bus.on('file:changed', async (payload) => { const summary = await summarizeFile(payload.path); bus.emit('summary:ready', { path: payload.path, summary }); }); // 前端推送模块 bus.on('summary:ready', (payload) => { sseClients.forEach(client => client.send(JSON.stringify(payload))); });

这个模式的好处是可观测性强。你可以在bus上加一个全局监听器，把所有事件打上时间戳记到日志里，Agent执行了哪些步骤一目了然。

3.2 模型接入：Qwen2.5-3B本地部署与远程API的取舍

paperclip本身不绑定任何模型，但实际使用中，Qwen2.5-3B是一个很合适的起点。3B参数量在消费级显卡上就能跑，量化后甚至CPU也能勉强推理，适合做本地摘要、分类、简单问答这类任务。

本地部署Qwen2.5-3B的流程大致是：下载模型权重、用推理框架加载、暴露一个HTTP接口给paperclip调用。推理框架的选择上，如果你追求简单，可以用Ollama；如果追求性能，可以用vLLM。Ollama的优势是安装即用，一条命令拉模型，接口兼容OpenAI格式，paperclip这边不用做额外适配。

远程API的取舍逻辑不同。远程API的优势是模型能力强、无需本地算力，劣势是延迟不可控、成本随调用量线性增长、数据要出本地。我的建议是混合使用：高频、低复杂度的任务（如文件分类、简单摘要）走本地Qwen2.5-3B；低频、高复杂度的任务（如长文档深度分析、多轮推理）走远程API。paperclip的路由层根据任务类型自动选择模型，对上层透明。

3.3 React前端的角色：不只是展示，更是调试工具

React在paperclip架构里最容易被做“薄”——只做一个消息列表展示。但我的经验是，前端做得好，Agent调试效率能提升一倍。

具体来说，React前端应该展示这几类信息：

• 事件流时间线：每个事件的时间戳、类型、来源、去向，用列表或时间轴组件渲染。
• 模型调用详情：每次模型调用的输入prompt、输出结果、耗时、token消耗。
• 工具执行状态：每个工具调用的开始、进行中、完成、失败状态，用不同颜色标识。
• 错误与异常：任何环节的报错信息，附带堆栈和上下文。

这些信息通过SSE从Node.js后端推送到前端。为什么用SSE而不是WebSocket？因为Agent状态推送是单向的（后端到前端），SSE更轻量，自动重连机制也更简单。WebSocket适合双向通信场景，比如前端要主动发指令给Agent，这时候可以再加WebSocket通道。

React组件设计上，我习惯用一个AgentDashboard容器组件管理SSE连接和状态，下面拆成EventTimeline、ModelCallPanel、ToolStatusPanel、ErrorPanel四个展示组件。状态用useReducer管理，因为事件流是追加式的，reducer比多个useState更清晰。

3.4 文件监控：fs.watch的坑与chokidar的取舍

Node.js内置的fs.watch在Linux上表现尚可，但在Windows和macOS上经常出现重复触发、漏触发的问题。如果你在开发环境用Windows，生产环境用Linux，fs.watch的行为差异会让你很头疼。

我的建议是直接用chokidar这个库。它封装了不同平台的差异，提供了更稳定的事件触发，还支持忽略特定文件、防抖等实用功能。虽然多了一个依赖，但省下的调试时间远超这点成本。

const chokidar = require('chokidar'); const watcher = chokidar.watch('./watch-dir', { ignored: /(^|[\/\\])\../, // 忽略隐藏文件 persistent: true, awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 } }); watcher.on('change', (path) => { bus.emit('file:changed', { path, eventType: 'change' }); });

awaitWriteFinish这个配置很关键。文件写入过程中会触发多次change事件，如果不加这个，你的Agent会对同一个文件反复处理。stabilityThreshold: 500表示文件大小稳定500毫秒后才触发事件，基本能避免写入过程中的误触发。

3.5 状态持久化：为什么用SQLite而不是JSON文件

Agent运行过程中会产生大量状态：事件历史、模型调用记录、工具执行结果、错误日志。一开始你可能想用JSON文件存，简单直接。但很快会遇到问题：并发写入冲突、查询效率低、文件越来越大。

SQLite是更合适的选择。它单文件、零配置、支持SQL查询，Node.js里用better-sqlite3这个库，同步API写起来很顺手。表结构设计上，至少需要这几张表：

表名	用途	关键字段
events	事件流记录	id, type, payload, created_at
model_calls	模型调用记录	id, model, prompt, response, duration_ms, created_at
tool_calls	工具执行记录	id, tool_name, input, output, status, created_at
errors	错误记录	id, source, message, stack, created_at

有了这些表，你可以随时查询“过去一小时模型调用了多少次”“哪个工具失败率最高”“平均响应时间是多少”，对优化Agent行为很有帮助。

4. 实操过程：从环境准备到跑通第一个Agent

4.1 Node.js 22.12+的安装与版本管理

Node.js的安装看似简单，但版本管理不当会在后期带来很多麻烦。我的建议是用nvm管理Node.js版本，而不是直接装系统级Node.js。

Linux/macOS下安装nvm：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22.12.0 nvm use 22.12.0

Windows下可以用nvm-windows，安装包在GitHub releases页面下载。安装后同样用nvm install 22.12.0和nvm use 22.12.0切换版本。

为什么强调22.12+？因为这个版本对ES模块的支持更完善，fs.watch的递归监控在部分平台上也有改进。如果你在CentOS 7.9上部署，系统自带的Node.js版本可能很老，需要先通过nvm安装新版本，或者用NodeSource的仓库安装。

CentOS 7.9上通过NodeSource安装Node.js 22：

curl -fsSL https://rpm.nodesource.com/setup_22.x | bash - yum install -y nodejs node -v # 应输出 v22.x.x

注意：CentOS 7.9的glibc版本较老，某些Node.js 22的新特性可能受限。如果遇到GLIBC_2.28 not found这类报错，说明系统库版本不满足要求，需要考虑升级系统或改用容器化部署。

验证Node.js是否安装成功，除了node -v，还可以跑一个简单的HTTP服务测试：

const http = require('http'); http.createServer((req, res) => { res.end('paperclip node ok'); }).listen(3000, () => console.log('listening on 3000'));

4.2 paperclip项目初始化与依赖安装

新建项目目录，初始化package.json：

mkdir paperclip && cd paperclip npm init -y npm install express better-sqlite3 chokidar eventsource npm install -D nodemon

express作为HTTP服务框架，better-sqlite3做状态持久化，chokidar做文件监控，eventsource用于SSE推送。nodemon是开发时热重载用的。

目录结构建议这样组织：

paperclip/ ├── src/ │ ├── index.js # 入口，启动HTTP服务和事件总线 │ ├── bus.js # 事件总线封装 │ ├── watcher.js # 文件监控模块 │ ├── model/ │ │ ├── local.js # 本地模型调用 │ │ └── remote.js # 远程模型调用 │ ├── tools/ │ │ └── openclaw.js # OpenClaw工具封装 │ ├── db.js # SQLite初始化与操作 │ └── sse.js # SSE推送模块 ├── web/ # React前端 │ ├── src/ │ │ ├── App.jsx │ │ └── components/ │ └── package.json └── package.json

这个结构的好处是职责清晰。每个模块只做一件事，模块之间通过事件总线通信，不直接依赖。你想替换本地模型为远程API，只改model/local.js就行，其他模块不受影响。

4.3 事件总线与SSE推送的完整实现

先写事件总线bus.js：

const EventEmitter = require('events'); const db = require('./db'); const bus = new EventEmitter(); bus.setMaxListeners(50); // 全局事件记录 bus.on('newListener', (event) => { if (event !== 'newListener') { console.log(`[bus] listener added for: ${event}`); } }); // 包装emit，自动记录到数据库 const originalEmit = bus.emit.bind(bus); bus.emit = (event, payload) => { db.insertEvent(event, payload); return originalEmit(event, payload); }; module.exports = bus;

SSE推送模块sse.js：

const clients = new Set(); function handleSSE(req, res) { res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' }); res.write('\n'); clients.add(res); req.on('close', () => clients.delete(res)); } function broadcast(event, data) { const message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`; clients.forEach(client => client.write(message)); } module.exports = { handleSSE, broadcast };

然后在index.js里把bus的事件转发到SSE：

const bus = require('./bus'); const { broadcast } = require('./sse'); ['file:changed', 'summary:ready', 'model:called', 'tool:executed', 'error:occurred'] .forEach(event => { bus.on(event, (payload) => broadcast(event, payload)); });

这样前端就能通过EventSource订阅这些事件，实时更新界面。

4.4 接入Qwen2.5-3B做本地摘要

假设你用Ollama跑Qwen2.5-3B，先拉模型：

ollama pull qwen2.5:3b

然后写本地模型调用模块model/local.js：

const OLLAMA_URL = 'http://localhost:11434/api/generate'; async function summarize(text) { const start = Date.now(); const response = await fetch(OLLAMA_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'qwen2.5:3b', prompt: `请用三句话总结以下内容：\n\n${text}`, stream: false }) }); const data = await response.json(); const duration = Date.now() - start; bus.emit('model:called', { model: 'qwen2.5:3b', prompt_length: text.length, response_length: data.response.length, duration_ms: duration }); return data.response; }

这里有个细节：prompt_length和response_length记录的是字符数，不是token数。如果你需要精确的token统计，Ollama的response里其实有eval_count和prompt_eval_count字段，可以直接用。

4.5 React前端：用SSE实时展示Agent状态

前端用Vite创建React项目：

npm create vite@latest web -- --template react cd web && npm install

核心是AgentDashboard组件：

import { useEffect, useReducer } from 'react'; const initialState = { events: [], modelCalls: [], toolCalls: [], errors: [] }; function reducer(state, action) { switch (action.type) { case 'event': return { ...state, events: [...state.events, action.payload].slice(-100) }; case 'model': return { ...state, modelCalls: [...state.modelCalls, action.payload].slice(-50) }; case 'tool': return { ...state, toolCalls: [...state.toolCalls, action.payload].slice(-50) }; case 'error': return { ...state, errors: [...state.errors, action.payload].slice(-20) }; default: return state; } } export default function AgentDashboard() { const [state, dispatch] = useReducer(reducer, initialState); useEffect(() => { const es = new EventSource('/api/events'); es.addEventListener('file:changed', e => dispatch({ type: 'event', payload: JSON.parse(e.data) })); es.addEventListener('model:called', e => dispatch({ type: 'model', payload: JSON.parse(e.data) })); es.addEventListener('tool:executed', e => dispatch({ type: 'tool', payload: JSON.parse(e.data) })); es.addEventListener('error:occurred', e => dispatch({ type: 'error', payload: JSON.parse(e.data) })); return () => es.close(); }, []); return ( <div className="dashboard"> <section> <h3>事件流</h3> {state.events.map((ev, i) => ( <div key={i} className="event-item"> <span className="time">{new Date(ev.created_at).toLocaleTimeString()}</span> <span className="type">{ev.type}</span> <span className="path">{ev.payload?.path}</span> </div> ))} </section> {/* 其他面板类似 */} </div> ); }

这个组件跑起来后，你打开浏览器就能看到Agent的实时状态。文件一变化，事件流里立刻出现记录；模型一调用，模型面板里出现耗时和输入输出长度；工具一执行，工具面板里出现状态更新。调试的时候盯着这个界面，比看控制台日志直观得多。

5. 常见问题与排查技巧实录

5.1 OpenClaw在SL2环境下的安全验证问题

这是我在Windows上开发时遇到最多的坑。现象是OpenClaw启动时报错，提示“无法安全验证”，并建议在PowerShell中运行wsl --status检查WSL状态。

根本原因通常是WSL子系统没有正确启动，或者默认发行版配置有问题。排查步骤：

1. 在PowerShell中运行wsl --status，查看WSL版本和默认发行版。
2. 如果显示“未安装用于Linux的Windows子系统”，运行wsl --install安装。
3. 如果已安装但状态异常，运行wsl --shutdown然后重新启动。
4. 检查默认发行版：wsl -l -v，确保有一个发行版处于Running状态。
5. 如果问题依旧，尝试wsl --set-default-version 2确保使用WSL2。

注意：这个问题跟paperclip本身无关，但如果你在Windows上做开发，OpenClaw跑不起来会卡住整个工具链。建议在项目初期就把WSL环境配好，避免后期返工。

5.2 Node.js版本不兼容导致的依赖安装失败

better-sqlite3和chokidar对Node.js版本有一定要求。如果你在CentOS 7.9上用系统自带的Node.js（可能是v6或v8），npm install会直接报错。

排查方法：先node -v看版本，低于18的基本可以确定是版本问题。用nvm切换到22.12+后重新npm install。

如果切换版本后仍然报错，检查node-gyp的依赖。better-sqlite3需要编译原生模块，CentOS上需要安装gcc-c++、make、python3：

yum install -y gcc-c++ make python3

5.3 React前端SSE连接断开与重连

SSE连接在长时间空闲后可能被中间层（如Nginx）断开。默认情况下，EventSource会自动重连，但如果服务端没有正确处理，重连后可能丢失事件。

解决方案是在服务端定期发送心跳：

setInterval(() => { clients.forEach(client => client.write(': heartbeat\n\n')); }, 30000);

前端监听onerror事件，在重连时重新拉取最近的事件历史，补齐断开期间丢失的数据：

es.onerror = () => { fetch('/api/events/recent') .then(res => res.json()) .then(events => dispatch({ type: 'bulk', payload: events })); };

5.4 文件监控重复触发导致Agent重复执行

前面提到chokidar的awaitWriteFinish能解决大部分问题，但如果你监控的目录里有大量小文件频繁写入，仍然可能触发多次。额外的防护措施是在事件处理层加一个去重逻辑：

const recentEvents = new Map(); bus.on('file:changed', (payload) => { const key = `${payload.path}:${payload.eventType}`; const now = Date.now(); if (recentEvents.has(key) && now - recentEvents.get(key) < 1000) { return; // 1秒内重复事件，忽略 } recentEvents.set(key, now); // 正常处理 });

这个去重窗口设1秒就够了，太长了会漏掉真实的快速连续修改。

5.5 常见问题速查表

问题现象	可能原因	排查步骤	解决方案
OpenClaw报安全验证失败	WSL状态异常	wsl --status	重启WSL或重装发行版
npm install报gyp错误	缺少编译工具	检查gcc/make/python3	安装对应工具链
SSE连接频繁断开	中间层超时	查看Nginx日志	加心跳+前端重连补数据
文件事件重复触发	写入过程多次触发	观察事件时间戳	chokidar awaitWriteFinish + 去重
模型调用超时	本地模型负载高	查看CPU/GPU占用	降低并发或换远程API
SQLite写入冲突	多进程同时写	检查是否有多个Node进程	确保单进程写入或加锁

6. 一些实操心得与扩展思路

6.1 关于Agent调试的体会

调试Agent和调试普通程序最大的区别在于：普通程序的bug是确定性的，Agent的bug往往跟输入内容相关。同一个Agent，处理A文件正常，处理B文件就卡住，原因可能是B文件里有个特殊字符触发了模型的异常输出。

我的做法是把所有模型调用的输入输出都存下来，出问题时能回放。SQLite里model_calls表就是干这个的。你还可以加一个“重放”功能，把某次调用的输入重新跑一遍，看输出是否一致。如果不一致，说明模型本身有随机性，需要在prompt里加约束。

6.2 关于React前端的状态管理

paperclip的前端状态不算复杂，但事件流是持续追加的，如果用useState管理数组，每次追加都要创建新数组，事件多了之后性能会下降。useReducer配合slice(-100)只保留最近100条，基本能平衡性能和可观测性。

如果你需要查看更早的历史事件，不要在前端存，而是从后端SQLite查。前端只展示最近的状态，历史查询走API，这样前端内存占用可控。

6.3 后续可以扩展的方向

paperclip这个编排层跑通之后，有几个方向可以继续深挖：

多Agent协作：现在是一个Agent处理所有事件，可以拆成多个专职Agent，比如“摘要Agent”“分类Agent”“通知Agent”，各自订阅不同事件，通过bus通信。这样每个Agent的prompt可以更专注，效果通常比一个通用Agent好。

工具生态扩展：除了OpenClaw，还可以接入其他工具，比如数据库查询、HTTP请求、文件转换。每个工具封装成一个模块，注册到paperclip的工具注册表里，Agent根据任务类型自动选择。

前端交互增强：现在前端是只读的，可以加一些交互功能，比如手动触发某个Agent任务、暂停/恢复事件处理、调整模型参数。这些通过WebSocket双向通道实现。

部署优化：如果部署在阿里云等云服务器上，可以考虑用PM2做进程管理，用Nginx做反向代理和SSE缓冲优化。PM2的--watch模式还能在代码变更时自动重启，开发体验更好。

6.4 一个容易被忽略的细节：时区与时间戳

事件记录里的时间戳，我建议统一用UTC存储，前端展示时再转本地时区。原因是你不知道Agent会部署在哪个时区的服务器上，如果存本地时间，跨时区查询时会混乱。Node.js里new Date().toISOString()返回的就是UTC时间，SQLite里存TEXT类型即可。

前端展示时用new Date(isoString).toLocaleString()转成本地时间。这个细节虽小，但后期做数据分析时能省很多事。

6.5 关于模型选择的再思考

Qwen2.5-3B做摘要够用，但如果你需要Agent做更复杂的推理——比如根据文件内容决定调用哪个工具、生成多步骤执行计划——3B模型可能力不从心。这时候可以考虑：

• 本地换更大的模型（7B/14B），但需要更强的硬件。
• 远程API做复杂推理，本地模型做简单任务，paperclip路由层根据任务复杂度自动选择。
• 用规则引擎处理确定性高的任务，模型只处理需要理解自然语言的部分。

我个人的经验是，不要试图让一个模型解决所有问题。把任务拆细，简单任务用规则或小模型，复杂任务用大模型，整体成本和效果都比“一个大模型包打天下”好。

6.6 最后分享一个排查技巧

当Agent行为不符合预期时，按这个顺序排查：

1. 看事件流：事件有没有正确触发？触发顺序对不对？
2. 看模型输入：传给模型的prompt是什么？有没有格式问题？
3. 看模型输出：模型返回了什么？是不是空？是不是格式不对？
4. 看工具执行：工具调用参数对不对？返回值是什么？
5. 看错误日志：有没有被捕获但没处理的异常？

这五步走下来，90%的问题都能定位。剩下的10%，通常是模型本身的随机性导致的，需要在prompt层面加约束或换模型。

paperclip这个方向的价值在于它足够轻，轻到你可以在一个下午跑通原型，然后根据实际需求逐步加功能。它不试图解决所有问题，而是给你一个清晰的骨架，让你自己往里填肉。这种“够用就好”的设计哲学，在AI Agent这个快速变化的领域里，反而比大而全的框架更有生命力。