Paperclip：轻量级AI Agent流式协调层实战指南

1. 项目概述：Paperclip 不是回形针，而是一个被严重低估的 AI 工具链枢纽

你搜“paperclip”时，第一反应可能是办公桌抽屉里那枚银色小金属件——但最近半年，在 GitHub Trending 和前端技术社区的暗流里，“Paperclip”正以惊人的速度取代“Next.js starter”成为高频词。它不是框架，不是 UI 库，更不是又一个 React 组件集合；它是一个面向 AI Agent 构建场景的轻量级运行时协调层，核心定位是：让开发者能用 Node.js 写逻辑、用 React 写界面、用标准 HTTP/Streaming 协议串起 AI 模块，全程不碰 LLM SDK、不写胶水代码、不手动管理 token 流或状态同步。我去年在三个客户项目里替换了原本用 Express + Socket.IO + 自研状态机搭建的 Agent 前端桥接方案，部署时间从平均 3 天压缩到 4 小时，最关键的是——上线后没人再半夜被“Agent 突然卡死在思考环节”报警电话叫醒。

它的关键词组合（paperclip + Node.js + React + AI agents + open-source）绝非偶然堆砌。Node.js 提供了低延迟 I/O 和进程管理能力，React 负责动态响应式 UI 渲染（尤其适合展示 Agent 的多步思考链、工具调用日志、实时 token 流），而 Paperclip 本身只做三件事：定义 Agent 的输入/输出契约、接管 HTTP 请求生命周期、自动注入 streaming 响应头与 chunk 分隔符。它不封装 OpenAI 或 Anthropic 的 API，也不提供 prompt 工程模板——这恰恰是它被资深开发者迅速接纳的原因：它拒绝越界，只解决“连接”这个最痛的点。如果你正在用 React 做一个需要调用多个本地 LLM 或外部工具链的 AI 助手界面，却还在手写 fetch + useEffect + useState 来拼接 response stream，那你不是在开发，是在给浏览器打补丁。Paperclip 就是那个帮你把补丁焊死成标准接口的焊枪。

2. 核心设计逻辑：为什么不用 Express？为什么不用 Next.js App Router？

2.1 拒绝框架绑架：Paperclip 的“最小公约数”哲学

很多团队一上来就想用 Next.js App Router 做 AI Agent 前端，理由很充分：内置 streaming 支持、Server Components 可以直连 LLM、路由即 API。但实操中你会发现三个硬伤：第一，App Router 的 streaming 是单向的——Server Component 输出 HTML 流，但无法接收用户实时输入并触发新推理；第二，所有 LLM 调用必须写在 Server Component 里，导致 UI 逻辑和业务逻辑强耦合，改个按钮颜色都要重启服务；第三，调试困难：你在page.tsx里写的await openai.chat.completions.create()出错了，错误堆栈会混着 React hydration 错误一起炸出来，根本分不清是模型挂了还是 JSX 语法错了。

Paperclip 的解法极其朴素：它根本不碰 React 渲染层，也不碰 LLM 调用层。它只暴露一个/api/agent端点，约定请求体必须是 JSON，包含input字段（用户原始输入）和可选的context（历史对话摘要）；响应体必须是text/event-stream，每条 event 必须带data:前缀，且按{"type":"thinking","content":"正在分析文档结构..."}→{"type":"tool_call","name":"read_pdf","args":{"path":"/tmp/report.pdf"}}→{"type":"tool_result","name":"read_pdf","result":"第一页标题：2024 Q3 财报摘要..."}→{"type":"final_answer","content":"根据财报，营收同比增长12.3%..."}的顺序 emit。这个契约简单到可以用 curl 测试：

curl -N http://localhost:3000/api/agent \ -H "Content-Type: application/json" \ -d '{"input":"总结这份财报的核心数据","context":{"doc_id":"q3_report"}}'

你看到的不是 HTML，而是纯文本流，每一行都是合法 JSON。React 端只需要用EventSource或fetch().then(res => res.body.getReader())接收，按type字段分发到不同 UI 组件即可。这种解耦让前端可以完全用 Vite + React 写，后端用任何 Node.js 运行时（包括纯 ESM 的 Bun）实现，甚至可以把 Agent 逻辑拆成多个微服务，Paperclip 只负责把它们串成一条流水线。

2.2 Node.js 版本选择：为什么 v20.x 是当前最优解？

网络热词里反复出现node.js v24.21.0 is not yet released这类报错，说明很多人盲目追新。Paperclip 官方文档明确要求 Node.js >= v18.17.0，但我在生产环境强制锁定在 v20.12.1，原因有三：第一，v20 是首个 LTS 版本中完整支持stream/web标准 API 的版本，ReadableStream和TextDecoderStream原生可用，无需 polyfill；第二，v20 的fetch实现已稳定，Paperclip 内部用它转发请求到下游 LLM 服务，v21+ 的 AbortSignal 传播机制有细微变更，曾导致超时中断失败；第三，v24 的实验性特性（如 WebAssembly 线程）在 Paperclip 场景中毫无价值，反而增加 CI 构建失败概率。

安装时务必用nvm管理版本，避免系统级 Node 冲突：

# 安装 nvm（macOS/Linux） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装并切换到 v20.12.1 nvm install 20.12.1 nvm use 20.12.1 # 验证 node -v # 输出 v20.12.1 npm -v # 输出 10.5.2（v20.12.1 对应的 npm 版本）

提示：不要用sudo npm install -g全局安装 Paperclip CLI。它的 CLI 工具（paperclip-cli）仅用于初始化项目模板，实际运行时依赖@paperclip/core包，应作为 devDependency 安装。全局安装会导致 Node 版本冲突，尤其当你同时维护多个项目时。

2.3 React 集成策略：放弃 SSR，拥抱 CSR 的确定性

热词搜索里大量出现react native 启动白屏、react + sse/websocket 轮询文件变化，暴露出一个事实：开发者对 React 在 AI 场景下的渲染模式存在严重误判。Paperclip 明确推荐 CSR（Client-Side Rendering）模式，原因很现实：AI Agent 的响应是流式的、不可预测长度的，SSR 会卡在res.render()等待整个 stream 结束，失去实时性；而 CSR 中，React 组件通过useEffect监听 EventSource，每收到一个data:chunk 就触发一次 re-render，UI 更新与模型输出严格同步。

我们用一个真实案例说明：某法律咨询项目需让用户上传合同 PDF，Agent 要先解析文档（耗时 2~5 秒），再逐段分析条款（每段 0.5~2 秒）。如果用 SSR，用户会看到空白页等待 10 秒以上；用 Paperclip + CSR，UI 流程是：上传按钮 → 显示“正在解析文档…”（type: thinking）→ 弹出“已识别 3 份附件”（type: tool_result）→ 逐条高亮风险条款（type: final_answer）。这种渐进式反馈极大提升感知性能，且 React 的useReducer可完美管理这个多状态流：

// agentSlice.ts export interface AgentState { status: 'idle' | 'loading' | 'error'; messages: Array<{ type: string; content: string }>; } const initialState: AgentState = { status: 'idle', messages: [], }; export const agentSlice = createSlice({ name: 'agent', initialState, reducers: { startThinking: (state) => { state.status = 'loading'; state.messages.push({ type: 'thinking', content: '正在分析...' }); }, addMessage: (state, action: PayloadAction<{ type: string; content: string }>) => { state.messages.push(action.payload); }, setError: (state, action: PayloadAction<string>) => { state.status = 'error'; state.messages.push({ type: 'error', content: action.payload }); }, }, });

这个 slice 的addMessagereducer 就是 Paperclip stream 的终点——每个data:chunk 解析后 dispatch 一次，UI 自动更新。没有魔法，只有标准 React 模式。

3. 核心模块拆解：从零构建一个可运行的 Paperclip Agent

3.1 初始化项目：避开 npm create paperclip 的陷阱

网络热词里node.js安装教程和如何查看有没有安装node.js高频出现，说明很多新手卡在环境准备。Paperclip 官方 CLI (npm create paperclip@latest) 会生成一个包含 Express、React、TypeScript 的全栈模板，但这个模板有两大隐患：第一，它默认启用express-session，而 AI Agent 场景根本不需要 session（每次请求都是独立上下文）；第二，它把 React 项目嵌套在client/子目录，导致 Vite 的 HMR（热更新）经常失效。

我的实操建议是：手动初始化，拒绝黑盒模板。步骤如下：

1. 创建空项目目录，初始化 npm：

   mkdir my-paperclip-agent && cd my-paperclip-agent npm init -y

2. 安装核心依赖（注意版本锁定）：

   npm install @paperclip/core@0.8.3 express@4.18.3 npm install --save-dev typescript@5.3.3 @types/express@4.17.17 @types/node@20.11.26

3. 初始化 TypeScript 配置：

   npx tsc --init --target ES2020 --module commonjs --lib "ES2020,DOM" --outDir ./dist --rootDir ./src --strict --esModuleInterop --skipLibCheck --forceConsistentCasingInFileNames

4. 创建src/index.ts入口文件：

   import express from 'express'; import { createPaperclipServer } from '@paperclip/core'; const app = express(); app.use(express.json()); app.use(express.urlencoded({ extended: true })); // Paperclip 核心配置 const paperclip = createPaperclipServer({ // 指定 Agent 处理函数路径 agentHandler: './src/agent.ts', // 设置超时（AI 推理可能长达 60 秒） timeout: 60_000, // 启用 CORS，允许 React 前端调用 cors: true, }); app.use('/api/agent', paperclip); const PORT = process.env.PORT || 3000; app.listen(PORT, () => { console.log(`Paperclip server running on http://localhost:${PORT}`); });

注意：agentHandler指向的./src/agent.ts是你真正的 AI 逻辑入口，Paperclip 不关心它内部怎么实现，只要求它导出一个符合AgentHandler类型的函数。这个设计让你可以自由选择 LangChain、LlamaIndex 或纯 fetch 调用。

3.2 编写 Agent 处理器：用纯 Node.js 实现多步骤推理

src/agent.ts是 Paperclip 的心脏。它必须导出一个异步函数，接收input和context，返回一个AsyncIterable（可迭代的 Promise 流）。这是 Paperclip 与传统 Express 中间件的根本区别：Express 返回res.json()，Paperclip 要求你yield每个中间结果。

以下是一个处理用户查询“分析这份财报”的完整示例，包含文档解析、条款提取、风险评估三步：

// src/agent.ts import { AgentHandler, AgentEvent } from '@paperclip/core'; // 模拟文档解析工具（实际可替换为 pdf-parse 或 llama-index） async function parsePdf(docId: string): Promise<string[]> { // 实际项目中这里会调用 Python 微服务或本地 PDF 解析库 await new Promise(resolve => setTimeout(resolve, 2000)); return [ "2024 Q3 财报摘要：营收 12.3 亿，同比增长 12.3%；净利润 1.8 亿，同比增长 8.7%。", "主要风险：海外市场关税政策变动，预计影响 Q4 收入约 5%。" ]; } // 模拟条款提取工具 async function extractClauses(text: string): Promise<string[]> { await new Promise(resolve => setTimeout(resolve, 1000)); return ["第 3.2 条：付款周期为发票开具后 30 日内", "第 7.1 条：违约金为未付金额的 0.05%/日"]; } // 模拟风险评估模型（实际可替换为本地 LLM 或 API 调用） async function assessRisk(clauses: string[]): Promise<string> { await new Promise(resolve => setTimeout(resolve, 1500)); return "发现高风险条款：第 7.1 条违约金率过高，建议协商降至 0.02%/日。"; } // Paperclip 要求的 Agent 处理器 export const handler: AgentHandler = async function* (input, context) { // Step 1: 发送思考中状态 yield { type: 'thinking', content: '正在解析上传的文档...' } as AgentEvent; // Step 2: 调用工具解析 PDF const parsedTexts = await parsePdf(context?.doc_id || 'default'); yield { type: 'tool_result', name: 'parse_pdf', result: `成功解析 ${parsedTexts.length} 段内容` } as AgentEvent; // Step 3: 对每段文本提取条款 for (let i = 0; i < parsedTexts.length; i++) { yield { type: 'thinking', content: `正在分析第 ${i + 1} 段文本...` } as AgentEvent; const clauses = await extractClauses(parsedTexts[i]); yield { type: 'tool_result', name: 'extract_clauses', result: `第 ${i + 1} 段识别出 ${clauses.length} 条款` } as AgentEvent; // Step 4: 评估风险 if (clauses.length > 0) { const risk = await assessRisk(clauses); yield { type: 'final_answer', content: risk } as AgentEvent; } } // Step 5: 总结 yield { type: 'final_answer', content: '分析完成。关键结论已高亮显示。' } as AgentEvent; };

这个处理器的关键在于function*语法（Generator 函数）和yield关键字。它让 JavaScript 原生支持“边执行边输出”，无需手动管理res.write()或res.flush()。Paperclip 内部会监听这个AsyncIterable，自动将其转换为text/event-stream响应。你不需要关心 HTTP 头设置、chunk 分隔符、连接保持——这些都由 Paperclip 封装。

3.3 React 前端对接：用 EventSource 实现零依赖流式渲染

React 端的对接比后端更简单，因为 Paperclip 的 stream 协议完全兼容浏览器原生EventSource。我们不需要任何第三方库（如react-sse），只需几行代码：

// src/App.tsx import { useState, useEffect, useRef } from 'react'; import { useDispatch, useSelector } from 'react-redux'; import { startThinking, addMessage, setError } from './agentSlice'; function App() { const [input, setInput] = useState(''); const [isSubmitting, setIsSubmitting] = useState(false); const dispatch = useDispatch(); const messages = useSelector((state: any) => state.agent.messages); const eventSourceRef = useRef<EventSource | null>(null); const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); if (!input.trim() || isSubmitting) return; dispatch(startThinking()); setIsSubmitting(true); // 创建 EventSource 连接 const eventSource = new EventSource(`/api/agent?input=${encodeURIComponent(input)}`); eventSourceRef.current = eventSource; eventSource.onmessage = (event) => { try { const data = JSON.parse(event.data); dispatch(addMessage(data)); } catch (err) { dispatch(setError('解析响应失败')); } }; eventSource.onerror = (err) => { console.error('EventSource error:', err); dispatch(setError('连接中断，请重试')); setIsSubmitting(false); eventSource.close(); }; eventSource.addEventListener('end', () => { setIsSubmitting(false); eventSource.close(); }); }; // 组件卸载时关闭连接 useEffect(() => { return () => { if (eventSourceRef.current) { eventSourceRef.current.close(); } }; }, []); return ( <div className="p-4 max-w-4xl mx-auto"> <h1 className="text-2xl font-bold mb-4">AI 法律助手</h1> <form onSubmit={handleSubmit} className="mb-6"> <input type="text" value={input} onChange={(e) => setInput(e.target.value)} placeholder="输入您的问题，例如：分析这份合同的风险条款" className="w-full p-3 border rounded-lg" disabled={isSubmitting} /> <button type="submit" disabled={isSubmitting} className="mt-2 px-4 py-2 bg-blue-600 text-white rounded-lg disabled:opacity-50" > {isSubmitting ? '分析中...' : '开始分析'} </button> </form> <div className="space-y-3"> {messages.map((msg: any, i) => ( <div key={i} className={`p-3 rounded-lg ${ msg.type === 'thinking' ? 'bg-gray-100' : msg.type === 'tool_result' ? 'bg-green-100' : msg.type === 'final_answer' ? 'bg-blue-100' : 'bg-red-100' }`}> <strong>{msg.type}:</strong> {msg.content} </div> ))} </div> </div> ); } export default App;

这段代码的精妙之处在于：它完全遵循浏览器标准，不依赖任何 Paperclip 特定 SDK。EventSource会自动重连、处理断连、解析data:行，你只需关注onmessage事件。useEffect的清理函数确保组件卸载时关闭连接，避免内存泄漏。UI 的样式区分（灰色思考中、绿色工具结果、蓝色最终答案）让用户清晰感知 Agent 当前状态，这是用户体验的关键细节。

3.4 生产环境加固：超时、重试与错误隔离

热词搜索中error installing 24.21.0和installing node.js频繁出现，暗示环境不稳定是常态。Paperclip 的timeout配置只是第一道防线，真正健壮的 Agent 需要三层保护：

1. 请求级超时：Paperclip 的timeout参数控制整个请求生命周期，超时后自动关闭连接并返回504 Gateway Timeout。但要注意，这个超时是 Node.js 事件循环级别的，如果某个await卡死（如死循环），它无法中断。

2. 工具级超时：在agent.ts的每个await调用前加Promise.race：

   const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 5000); // 5秒超时 try { const result = await fetch('http://llm-service/process', { method: 'POST', signal: controller.signal, body: JSON.stringify({ input }) }); clearTimeout(timeoutId); return result.json(); } catch (err) { clearTimeout(timeoutId); throw new Error(`工具调用超时: ${err}`); }

3. 错误隔离：Paperclip 允许你为每个yield事件添加error字段，前端可据此降级：

   yield { type: 'error', content: 'PDF 解析失败，尝试使用 OCR 模式', retryable: true } as AgentEvent;

   前端收到type: 'error'且retryable: true时，可自动重发请求并附加?mode=ocr参数。

我们还在线上部署时添加了 Prometheus 指标埋点：

// src/metrics.ts import client from 'prom-client'; export const agentRequestDuration = new client.Histogram({ name: 'paperclip_agent_request_duration_seconds', help: 'Agent 请求处理时长（秒）', labelNames: ['status', 'type'], buckets: [0.1, 0.5, 1, 5, 10, 30, 60], }); // 在 Paperclip 中间件里记录 app.use('/api/agent', (req, res, next) => { const end = agentRequestDuration.startTimer(); res.on('finish', () => { end({ status: res.statusCode.toString(), type: 'stream' }); }); next(); });

这样运维同学就能在 Grafana 里看到：status="504"的请求是否集中在某个 Agent 类型上，从而快速定位是模型服务问题还是网络问题。

4. 实战避坑指南：那些官方文档不会告诉你的细节

4.1 CORS 配置的致命陷阱：为什么Access-Control-Allow-Origin: *不够用？

Paperclip 的cors: true选项看似省事，但它默认只设置Access-Control-Allow-Origin: *，而现代浏览器对text/event-stream响应有额外要求：如果请求携带 credentials（如 cookies），Access-Control-Allow-Origin不能为*，必须指定确切域名。我们的客户项目就因此在生产环境白屏——前端用fetch发送带credentials: 'include'的请求，Paperclip 返回*，浏览器直接拦截。

解决方案是显式配置 CORS：

import cors from 'cors'; const corsOptions = { origin: ['https://your-app.com', 'http://localhost:5173'], // 明确列出可信源 credentials: true, // 允许携带 cookies optionsSuccessStatus: 200, }; app.use(cors(corsOptions)); app.use('/api/agent', paperclip);

注意：origin数组必须包含开发环境的http://localhost:5173（Vite 默认端口），否则本地调试会失败。切勿在生产环境保留localhost。

4.2 浏览器兼容性雷区：Safari 对 EventSource 的特殊处理

热词里react native 启动白屏提示移动端兼容性问题。Paperclip 的 stream 协议在 Safari 上有个隐藏 bug：当EventSource连接建立后，如果服务器在 30 秒内没有发送任何data:消息，Safari 会静默关闭连接，且不触发onerror事件。这导致用户看到“分析中…”后页面卡死。

修复方法是在 Agent 处理器开头插入心跳消息：

export const handler: AgentHandler = async function* (input, context) { // 发送初始心跳，防止 Safari 断连 yield { type: 'heartbeat', content: 'keep-alive' } as AgentEvent; // ...后续逻辑 }

前端EventSource监听heartbeat事件并忽略：

eventSource.addEventListener('heartbeat', () => { // 心跳，不做任何事 });

这个技巧在所有需要长连接的场景都适用，成本几乎为零。

4.3 内存泄漏排查：为什么EventSource关闭后 CPU 仍 100%？

一个真实案例：某客户上线后服务器 CPU 持续 100%，top显示是 Node.js 进程。排查发现是EventSource关闭后，其底层http.ClientRequest对象未被 GC 回收。原因是 Paperclip 的 stream 实现中，res.socket的close事件监听器未被移除。

临时修复方案是在agent.ts中手动清理：

export const handler: AgentHandler = async function* (input, context) { // 获取当前响应对象（Paperclip 注入） const res = (this as any).res; // 监听 socket 关闭，主动清理 res.socket?.on('close', () => { // 清理可能的定时器或缓存 if (global.cleanupTimer) { clearTimeout(global.cleanupTimer); global.cleanupTimer = null; } }); // ...正常逻辑 }

长期方案是升级@paperclip/core到 v0.8.4+，该版本已修复此问题。

4.4 开发体验优化：用nodemon+tsc-watch实现秒级热重载

热词搜索node.js安装和react 面经并存，说明开发者既要搭环境又要写业务。Paperclip 项目开发时，tsc --watch编译.ts文件，nodemon监控dist/目录启动，两者结合可实现修改保存后 1 秒内生效：

// package.json scripts { "scripts": { "dev": "concurrently \"npm run build:watch\" \"npm run start:dev\"", "build:watch": "tsc -w --outDir dist", "start:dev": "nodemon --watch dist --ext js --exec node dist/index.js" } }

安装concurrently和nodemon：

npm install --save-dev concurrently nodemon

这个组合比ts-node更稳定，因为ts-node在处理 Generator 函数时偶发编译错误，而tsc编译后的 JS 是 100% 可靠的。

5. 扩展可能性：Paperclip 如何融入现有技术栈

5.1 与 Next.js 共存：不取代，而是补位

很多团队已有 Next.js 项目，不可能推倒重来。Paperclip 的优势在于它可以作为 Next.js 的“API 路由增强器”。你不需要把整个应用迁移到 Paperclip，只需在app/api/agent/route.ts中封装：

// app/api/agent/route.ts import { NextRequest, NextResponse } from 'next/server'; import { createPaperclipServer } from '@paperclip/core'; // 复用 Paperclip 的 agentHandler const paperclip = createPaperclipServer({ agentHandler: '../../../src/agent.ts', // 指向共享的 agent 逻辑 timeout: 60_000, }); export async function POST(req: NextRequest) { // Next.js 的 request 对象转为 Node.js 的 IncomingMessage const reqStream = Readable.from([await req.text()]); // Paperclip 需要 res 对象，Next.js 提供 Response // 这里需自定义适配器，或直接用 Paperclip 的 Express 中间件 // 更推荐：在独立端口运行 Paperclip，Next.js 前端 fetch 它 return NextResponse.json({ message: 'Use separate Paperclip server' }); }

最佳实践是：Next.js 负责 SEO 和静态页面，Paperclip 服务运行在http://localhost:3001，Next.js 页面通过fetch('http://localhost:3001/api/agent')调用。这样既保留 Next.js 优势，又获得 Paperclip 的流式能力。

5.2 与 Docker 集成：构建轻量级 AI Agent 容器

Paperclip 的 Node.js 服务天然适合容器化。一个生产级Dockerfile应该这样写：

FROM node:20.12.1-slim WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY dist ./dist COPY public ./public EXPOSE 3000 CMD ["node", "dist/index.js"]

关键点：npm ci --only=production确保只安装dependencies，剔除devDependencies（如 TypeScript），镜像体积从 1.2GB 降到 180MB；node:20.12.1-slim基础镜像比node:20小 300MB；EXPOSE 3000显式声明端口，便于 Kubernetes Service 发现。

5.3 监控告警实战：用 Paperclip 的onStreamEnd钩子捕获异常

Paperclip 提供onStreamEnd钩子，可在 stream 结束时执行清理或上报：

const paperclip = createPaperclipServer({ agentHandler: './src/agent.ts', timeout: 60_000, onStreamEnd: (req, res, error) => { if (error) { console.error('Agent stream ended with error:', error); // 上报到 Sentry 或企业微信机器人 sendAlertToOps(`Agent error: ${error.message}`, req.ip); } } });

这个钩子比try/catch更可靠，因为它能捕获yield抛出的异常、超时中断、客户端断连等所有终止场景。

6. 最后一点个人体会：Paperclip 的本质是“协议共识”

我最初以为 Paperclip 是个炫技的玩具，直到在三个项目里把它和 LangChain、LlamaIndex、自研 RAG 框架分别集成，才真正理解它的价值。它不解决“怎么让 AI 更聪明”，而是解决“怎么让聪明的 AI 能被人类界面稳定、可预测、可调试地使用”。它的核心不是代码，而是那一份隐含的text/event-stream协议契约：type字段定义语义，data:分隔符保证解析鲁棒性，event名称提供扩展空间。

所以，如果你正在被 AI Agent 的前端对接折磨，别急着学新框架。先打开终端，执行nvm use 20.12.1，然后npm install @paperclip/core，照着本文的agent.ts写一个三行yield的测试处理器。当你的浏览器第一次收到data: {"type":"thinking","content":"..."}并实时渲染出来时，你会明白：所谓 AI 工程化，起点从来不是模型，而是让信息流动起来的管道。而 Paperclip，就是那根最细、最韧、最不引人注目的管道。