企业官网建设流程全解析

1. 项目概述：Paperclip 不是回形针，而是一个轻量级 AI Agent 框架

你搜“paperclip”时，第一反应可能是办公桌抽屉里那枚银色小金属件——但最近半年，在 Node.js 和 React 开发者圈子里，“Paperclip”正以一种安静却持续升温的方式被反复提及。它不是 UI 组件库，不是状态管理工具，更不是又一个“React + AI”的营销概念包装品。它是一个面向本地化、可嵌入、低侵入式 AI Agent 构建的开源运行时框架，核心定位非常清晰：让开发者能在已有 Node.js 后端服务或 Electron/Next.js 桌面/全栈应用中，不重写架构、不引入复杂调度中心、不依赖云托管平台，就能把 LLM 能力像“插件”一样缝进真实业务逻辑里。

我第一次在 GitHub 上看到它的 README 时，就注意到它刻意避开了所有“Enterprise”“Cloud-native”“Scalable Orchestrator”这类高大上词汇，取而代之的是三行加粗说明：“Runs in-process. No external broker. Zero config for basic agent.” —— 这不是口号，而是它整个设计哲学的浓缩。它不试图替代 LangChain 或 LlamaIndex，也不对标 Microsoft AutoGen 的多智能体编排；它解决的是另一个更具体、更常被忽略的问题：当你的产品已经跑在一台客户内网服务器上，或者打包成 macOS/Windows 桌面应用，甚至嵌入到 VS Code 插件里，你突然需要让某个按钮点击后调用本地部署的 Qwen2-7B 做文档摘要，或者让 Excel 导入功能自动识别字段语义并生成 SQL 查询模板——这时候，你不需要一个分布式任务队列，你只需要一个能和 Express 路由共存、能和 React Query 的 mutation 函数直接对接、能被 Web Worker 安全调用的“AI 执行单元”。Paperclip 就是为这种场景而生的。

它天然适配 Node.js 18+（LTS 稳定版起）和 React 18+（支持 Server Components 和 Client Components 双模式），但关键在于：它不强制你用 React 渲染 Agent 界面，也不要求你用 Node.js 做唯一后端。你可以把它当作一个“AI 调度胶水层”，在 Next.js App Router 的 server action 里初始化一个 Paperclip 实例，让它调用本地 Ollama 服务；也可以在 Electron 主进程中启动一个 Paperclip runtime，再通过 IPC 把能力暴露给 React 渲染进程；甚至可以在 Deno 或 Bun 环境下运行（社区已有非官方适配 PR）。这解释了为什么它在掘金、V2EX 和 GitHub Discussions 里讨论热度不高但复购率极强——用过的人基本都留在了项目里，因为一旦你踩过“在离线环境里硬塞一个 LangChain + Redis + Celery”的坑，再回头看到 Paperclip 的new Agent({ model: 'qwen2:7b', tools: [fileReader, sqlGenerator] })这一行代码，会有一种“终于不用再写胶水代码”的释然感。它不追求炫技，只解决“让 AI 在真实生产约束下可靠落地”这个朴素问题。

2. 核心设计思路与选型逻辑：为什么是 Paperclip，而不是别的？

2.1 “In-process” 优先：拒绝抽象层堆叠，直面运行时本质

几乎所有主流 AI Agent 框架（LangChain、LlamaIndex、AutoGen）都默认假设你拥有一个“可自由支配的基础设施环境”：可以装 Redis、可以开 RabbitMQ、可以部署 FastAPI 服务、可以配置 CORS 和反向代理。但现实中的很多项目根本没这个条件。比如某制造业客户的 MES 系统，运行在 Windows Server 2016 内网，IT 部门明确禁止安装任何非白名单软件；再比如某设计师工具的桌面版，打包后体积必须控制在 300MB 以内，不可能塞进一个 Python 运行时加 Flask 服务。Paperclip 的破局点非常务实：它不提供“服务”，它提供“函数”。

它的核心 runtime 是一个纯 JavaScript 类，实例化后直接运行在当前 Node.js 进程的主线程或 Worker 线程中。没有 HTTP 服务监听，没有消息总线，没有中间件管道。当你调用agent.run({ input: '总结这份PDF' })，它内部执行的是：

1. 解析输入，匹配预注册的 tool（如pdfExtractor）；
2. 同步或异步调用该 tool 的execute()方法（传入原始 buffer 或文件路径）；
3. 将 tool 返回结果喂给 LLM（通过适配器调用本地 Ollama / LM Studio / llama.cpp 的 HTTP API，或直接调用 WASM 版本）；
4. LLM 输出结构化 JSON 或自然语言响应；
5. 返回 Promise 结果，全程无跨进程通信开销。

提示：这种设计意味着 Paperclip 的启动时间 < 50ms（实测 Node.js 20.12 下），内存占用峰值 < 15MB（含模型适配器），远低于启动一个 Express 子进程的成本。它不是“轻量”，而是“零重量附加”。

对比来看，LangChain 的AgentExecutor默认依赖CallbackManager和Runnable抽象，底层仍需LLMChain+Tool+Agent三层封装；AutoGen 强制要求ConversableAgent实例间通过send方法通信，隐含了事件循环调度成本。Paperclip 则把“Agent”降维成一个状态机 + 工具路由表 + 模型调用器的组合，所有逻辑都在单次函数调用生命周期内完成。这不是技术倒退，而是对“AI 能力即函数”的回归——就像你调用fs.readFileSync不需要先启动一个文件服务一样，调用agent.run()也不该需要先部署一套基础设施。

2.2 工具（Tools）即插即用：不绑定执行环境，只约定接口契约

Paperclip 对 “tool” 的定义极其简洁：一个对象，必须包含name（字符串）、description（字符串）、execute(input: any): Promise<any>（返回 Promise 的函数）。仅此而已。它不关心这个execute方法内部是调用child_process.execSync('pdftotext')，还是fetch('http://localhost:11434/api/generate')，或是await sqlite3.run('SELECT * FROM logs WHERE time > ?')。只要它返回 Promise，且 resolve 的值能被 LLM 的 system prompt 理解，就合法。

这种松耦合带来三个实际好处：

• 开发隔离：前端团队可以独立开发excelParsertool（用 SheetJS 解析.xlsx），后端团队同时开发databaseSearchertool（用 Knex 查询 PostgreSQL），双方只需约定好input的 TypeScript interface（如{ filePath: string }或{ query: string, limit: number }），无需协调部署节奏。
• 环境适配自由：同一个webSearchertool，在开发环境可调用 SerpAPI，在生产内网环境则 fallback 到本地爬虫服务（http://intranet-search:8080/search?q=），只需替换execute实现，Agent 逻辑完全不变。
• 调试友好：你可以直接console.log(await myTool.execute({ url: 'https://example.com' }))测试 tool，无需启动整个 Agent 或 mock LLM 调用。我们团队曾用这种方式在 2 小时内定位出一个因node-fetch未处理重定向导致的 tool 超时问题，而如果走完整 Agent 链路，排查时间至少翻倍。

注意：Paperclip 内置了 7 个常用 tool 模板（fileReader,shellRunner,httpCaller,jsonParser,regexMatcher,dateCalculator,stringTransformer），但它们全部是“参考实现”，而非强制依赖。你完全可以删掉node_modules/paperclip/tools目录，用自己的cryptoTool.ts替代——只要它导出符合接口的对象即可。这种“框架不带轮子，只教你怎么造轮子”的理念，正是它被大量嵌入式/边缘计算项目选用的关键。

2.3 React 集成非侵入：不接管状态，只暴露 hook

很多“React AI 框架”喜欢把useAgent包装成类似useReducer的黑盒，内部管理 loading/error/state，强迫你用它的 Provider 包裹整个 App。Paperclip 的做法截然不同：它提供usePaperclip，但这个 hook只做一件事——返回一个已初始化的 Agent 实例引用，其余状态管理完全交给你。

// src/hooks/useDocumentSummarizer.ts import { usePaperclip } from 'paperclip/react'; import { useState, useCallback } from 'react'; export function useDocumentSummarizer() { const agent = usePaperclip(); // ← 仅获取实例，无副作用 const [summary, setSummary] = useState<string>(''); const [isRunning, setIsRunning] = useState(false); const summarize = useCallback(async (file: File) => { setIsRunning(true); try { // 直接调用 agent.run，传入自定义参数 const result = await agent.run({ input: `请总结以下文档内容：${await file.text()}`, tools: ['fileReader'], // 显式指定可用工具 }); setSummary(result.output); } catch (err) { console.error('Summarize failed:', err); } finally { setIsRunning(false); } }, [agent]); return { summary, isRunning, summarize }; }

这段代码里，usePaperclip()不创建新 Agent，不订阅任何事件，不触发 re-render——它只是从 React context 中读取你在PaperclipProvider（通常放在 App 根组件）中预设的 Agent 实例。这意味着：

• 你可以为不同业务模块创建不同配置的 Agent（如marketingAgent用 GPT-4-turbo，supportAgent用本地 Phi-3），并在各自组件中usePaperclip({ name: 'marketing' })获取对应实例；
• 你可以把 Agent 实例存在 Zustand store 或 Jotai atom 中，完全绕过 Context API；
• 你甚至可以在非 React 环境（如 Node.js CLI 工具）中import { Agent } from 'paperclip'直接使用，无需任何 React 依赖。

这种“框架归框架，UI 归 UI”的分离，让 Paperclip 成为少数几个能真正融入现有 React 技术栈而不引发架构冲突的 AI 工具。尤其适合那些正在重构老系统的团队——你不需要说服老板“我们要全面迁移到新 AI 框架”，只需在某个新需求页面里npm install paperclip && import { usePaperclip }，就能立刻获得 AI 能力，风险可控，收益可见。

3. 核心细节解析与实操要点：从零开始构建一个可用 Agent

3.1 环境准备：Node.js 与 React 版本的隐形门槛

Paperclip 官方声明支持 Node.js 18+ 和 React 18+，但实际落地时，版本选择直接影响开发体验和稳定性。我们团队在三个不同项目中踩过坑，结论很明确：

• Node.js 推荐版本：20.12.0 LTS（2024年10月发布）
  Node.js 18.x 虽然被标记为 LTS，但其 OpenSSL 版本（3.0.2）对某些国产 SSL 证书（如 CFCA）兼容性较差，我们在某金融客户内网部署时，Agent 调用本地 Ollama 服务频繁报ERR_SSL_VERSION_OR_CIPHER_MISMATCH。升级到 20.12 后，OpenSSL 升级至 3.0.13，问题消失。更重要的是，Node.js 20 原生支持WebAssembly.compileStreaming()，这让 Paperclip 的 WASM 模型适配器（如 llama.cpp-wasm）加载速度提升 40%。不要贪图“LTS 最稳”，要选“LTS 中最新稳定版”。

• React 推荐版本：18.3.1（2024年8月 patch）
  React 18.2.x 存在一个useEffect在严格模式下重复执行的 bug，当 Agent 的 tool 触发多次异步操作时，可能导致agent.run()被意外调用两次。18.3.1 修复了该问题。另外，Paperclip 的usePapercliphook 内部使用useSyncExternalStore优化性能，该 API 在 18.3+ 中才完全稳定。如果你还在用 18.0.x，请务必升级——这不是可选项，是必选项。

• 构建工具链建议：Vite 5.4+ 或 Next.js 14.2+
  Paperclip 的 ESM 模块输出（"type": "module"）与 Vite 的原生 ES 模块支持完美契合。我们测试过 Webpack 5.90，需要额外配置resolve.fullySpecified: true和experiments.topLevelAwait: true，否则import { Agent } from 'paperclip'会报错。Next.js 14.2 默认启用 Turbopack，对 Paperclip 的动态 tool 加载（import('./tools/fileReader.js')）支持更好。避免使用 Create React App（CRA），其 Webpack 4 配置与 Paperclip 的现代模块语法存在兼容性问题。

实操心得：在package.json中锁定版本比写^更稳妥。我们线上项目的engines字段如下：

"engines": { "node": ">=20.12.0", "npm": ">=10.2.4" }, "dependencies": { "paperclip": "^0.8.3", "react": "18.3.1", "react-dom": "18.3.1" }

每次npm install后运行npx check-engines验证环境，能避免 80% 的初期集成失败。

3.2 Agent 初始化：配置项背后的权衡取舍

Paperclip 的Agent构造函数接受一个配置对象，表面看只有model、tools、systemPrompt等几项，但每个参数的选择都隐含着性能、安全、可维护性的权衡：

import { Agent } from 'paperclip'; import { ollama } from 'paperclip/adapters'; const agent = new Agent({ model: 'qwen2:7b', // ← 关键：模型标识符，非 URL adapter: ollama(), // ← 关键：适配器工厂函数 tools: [fileReader, webSearcher], // ← 关键：工具数组 systemPrompt: '你是一名专业文档分析师...', // ← 关键：角色定义 maxIterations: 10, // ← 关键：防死循环 timeoutMs: 30_000, // ← 关键：超时保护 });

• model参数：为什么用字符串而非 URL？
  Paperclip 认为“模型地址”是运行时环境变量，不应硬编码在业务逻辑中。model: 'qwen2:7b'实际会被ollama()适配器解析为http://localhost:11434/api/generate，而model: 'gpt-4-turbo'则被openai()适配器解析为https://api.openai.com/v1/chat/completions。这样做的好处是：同一份 Agent 代码，通过切换adapter就能无缝对接不同模型后端，无需修改model字符串。我们在灰度发布时，用环境变量PAPERCLIP_MODEL=phi3:mini切换到轻量模型，验证效果后再切回qwen2:7b，全程零代码变更。

• adapter参数：适配器不是插件，是协议翻译器
  Paperclip 内置ollama、openai、lmstudio、llamacpp四个适配器，它们的作用是将统一的AgentInput结构（{ messages: [], tools: [] }）翻译成目标模型 API 所需的格式，并处理响应解析。例如ollama()适配器会把tools数组转为 Ollama 的template字段中的工具描述，而openai()适配器则生成符合 OpenAI Function Calling 格式的functions数组。你永远不应该自己写 HTTP 请求调用模型——适配器已为你处理了流式响应解析、错误码映射（如 Ollama 的 404 vs OpenAI 的 429）、token 计数等细节。

• maxIterations与timeoutMs：安全阀必须手动设置
  Paperclip 不设默认值，强制开发者思考“我的 Agent 最多应该尝试几次？”和“用户最长愿意等多久？”。我们线上项目的经验值是：maxIterations: 5（超过 5 次 tool 调用大概率陷入死循环），timeoutMs: 15_000（15秒是用户耐心阈值，超过则显示“处理中，请稍候”并提供取消按钮）。这两个值必须根据你的 tool 复杂度调整——如果webSearchertool 内部有重试逻辑，maxIterations应设得更小，避免叠加超时。

3.3 Tool 开发规范：如何写出 Paperclip 兼容的高质量工具

Paperclip 的 tool 接口看似简单，但写出健壮、可维护、易测试的 tool 需要遵循几条隐性规范。我们团队沉淀了一套 checklist，已在 12 个项目中验证有效：

1. 输入必须类型安全，输出必须结构化
   错误示范：

   // ❌ 输入无约束，输出随意 const badTool = { name: 'bad', description: 'do something', execute: async (input) => { return await fetch(`https://api.example.com/${input}`).then(r => r.json()); } };

   正确示范：

   // ✅ 使用 Zod 定义输入 schema，返回明确 interface import { z } from 'zod'; const searchInputSchema = z.object({ query: z.string().min(1).max(200), site: z.string().url().optional(), limit: z.number().int().min(1).max(50).default(10) }); export interface SearchOutput { results: Array<{ title: string; url: string; snippet: string }>; total: number; } const webSearcher = { name: 'webSearcher', description: 'Search the web for information using a search engine', execute: async (input: z.infer<typeof searchInputSchema>): Promise<SearchOutput> => { const validated = searchInputSchema.parse(input); const res = await fetch(`https://api.duckduckgo.com/?q=${encodeURIComponent(validated.query)}&format=json`); const data = await res.json(); return { results: data.RelatedTopics?.map((t: any) => ({ title: t.Text, url: t.FirstURL, snippet: t.Text })) || [], total: data.RelatedTopics?.length || 0 }; } };

2. 错误处理必须显式抛出，不可静默失败
   Paperclip 依赖 tool 的 Promise rejection 来触发 fallback 逻辑或向用户展示错误。execute方法中任何异常（网络错误、JSON 解析失败、schema 验证失败）都必须throw new Error('...')，而不是console.error()后return null。我们约定错误消息格式为[ToolName] Error: 详细原因，便于日志聚合系统识别。

3. 敏感操作必须声明权限，不可隐式执行
   如果 tool 需要访问文件系统、执行 shell 命令或调用外部 API，必须在description中明确说明，例如：

   const shellRunner = { name: 'shellRunner', description: 'Execute shell commands on the host machine. ⚠️ Requires explicit user permission.', execute: async (input: { command: string }) => { if (!confirm('此操作将执行系统命令，是否继续？')) { throw new Error('[shellRunner] User denied permission'); } // ... actual execution } };

   这种设计让 Paperclip 的systemPrompt能动态提示用户风险，也方便审计工具扫描高危 tool 调用。

4. 实操过程与核心环节实现：一个完整的文档分析 Agent 示例

4.1 需求背景与架构设计

我们为某法律科技 SaaS 产品开发一个“合同风险点自动标注”功能：用户上传 PDF 合同，Agent 需完成三步操作——① 提取文本内容；② 识别其中涉及“违约责任”“管辖法院”“保密义务”等关键条款；③ 生成带高亮标记的 HTML 片段供前端渲染。整个流程必须在 30 秒内完成，且支持离线运行（客户内网无外网）。

传统方案需部署 OCR 服务 + NLP 模型服务 + 渲染服务，而 Paperclip 方案只需：

• 前端：React 组件负责文件上传、调用agent.run()、渲染结果；
• 后端：Node.js Express 服务提供/api/analyze接口，内部初始化 Paperclip Agent；
• 模型：Ollama 本地运行qwen2:7b（量化版，GPU 显存占用 < 4GB）；
• Tools：自研pdfTextExtractor（基于 pdfjs-dist）、clauseDetector（基于规则 + LLM 微调）、htmlRenderer（纯前端 JS 生成）。

架构图（文字描述）：

[React Upload Component] ↓ (File Blob) [Express POST /api/analyze] ↓ (req.file.buffer) [Paperclip Agent Instance] ├─→ pdfTextExtractor.execute() → text:string ├─→ clauseDetector.execute({ text }) → { clauses: [...], highlights: [...] } └─→ htmlRenderer.execute({ clauses, highlights }) → html:string ↓ (Promise.resolve(html)) [Express Response] → { success: true, html: '...' }

4.2 关键代码实现与参数详解

步骤一：初始化 Agent（Node.js 端）

// server/agent.ts import { Agent } from 'paperclip'; import { ollama } from 'paperclip/adapters'; import { pdfTextExtractor } from './tools/pdfTextExtractor'; import { clauseDetector } from './tools/clauseDetector'; import { htmlRenderer } from './tools/htmlRenderer'; // 预加载模型，避免首次请求冷启动延迟 await ollama().preload('qwen2:7b'); export const contractAgent = new Agent({ model: 'qwen2:7b', adapter: ollama({ baseUrl: 'http://localhost:11434', // Ollama 服务地址 timeoutMs: 25_000, // 比全局 timeout 小，留出 tool 执行时间 }), tools: [pdfTextExtractor, clauseDetector, htmlRenderer], systemPrompt: ` 你是一名资深法律AI助手，专精于中文合同审查。 请严格按以下步骤处理输入： 1. 接收PDF文本，提取所有文字内容； 2. 识别文本中关于"违约责任"、"管辖法院"、"保密义务"、"知识产权归属"的条款； 3. 对每个识别到的条款，返回其原文位置（页码+行号）和简要摘要； 4. 输出必须为JSON格式：{ "clauses": [{ "type": "...", "text": "...", "page": 1, "line": 5 }], "highlights": [{ "start": 123, "end": 456 }] } `, maxIterations: 3, // 合同分析最多3步：提取→识别→渲染 timeoutMs: 30_000, });

参数说明：

• adapter.preload()是 Paperclip 0.8+ 新增 API，调用后 Ollama 会提前加载模型到 GPU，实测首次agent.run()延迟从 8s 降至 1.2s；
• systemPrompt中明确限定步骤数和输出格式，这是 Paperclip 控制 LLM 行为最有效的手段——比在 tool description 里写一百遍“请返回 JSON”都管用；
• maxIterations: 3是经过 200+ 次测试确定的最优值：少于 3 无法完成三步，大于 3 增加无谓循环风险。

步骤二：实现 pdfTextExtractor Tool（核心难点）

// server/tools/pdfTextExtractor.ts import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs'; import { PDFDataRangeTransport } from 'pdfjs-dist/types/src/display/api.js'; // 配置 pdfjs worker（关键！否则 Node.js 环境报错） pdfjsLib.GlobalWorkerOptions.workerSrc = new URL( 'pdfjs-dist/legacy/build/pdf.worker.mjs', import.meta.url ).toString(); export const pdfTextExtractor = { name: 'pdfTextExtractor', description: 'Extract plain text from PDF files. Supports multi-page documents.', execute: async (input: { buffer: Buffer }): Promise<{ text: string; pages: number }> => { try { // 创建 PDFDocumentLoadingTask（Node.js 环境专用） const loadingTask = pdfjsLib.getDocument({ data: input.buffer, // 必须禁用 worker，Node.js 无浏览器 worker API workerDisabled: true, }); const pdf = await loadingTask.promise; let fullText = ''; const pagePromises = []; for (let i = 1; i <= pdf.numPages; i++) { pagePromises.push( pdf.getPage(i).then(async (page) => { const textContent = await page.getTextContent(); const strings = textContent.items.map((item: any) => item.str); return strings.join(' '); }) ); } const pageTexts = await Promise.all(pagePromises); fullText = pageTexts.join('\n\n--- PAGE BREAK ---\n\n'); return { text: fullText, pages: pdf.numPages, }; } catch (err) { throw new Error(`[pdfTextExtractor] Failed to parse PDF: ${err instanceof Error ? err.message : 'Unknown error'}`); } }, };

实操要点：

• workerDisabled: true是 Node.js 环境必需配置，否则pdfjs-dist会尝试创建 Web Worker 并报错；
• pdfjsLib.GlobalWorkerOptions.workerSrc必须显式设置，指向正确的 worker 脚本路径（Vite/Next.js 项目中需用import.meta.url动态解析）；
• 我们测试发现，page.getTextContent()比page.render()提取文本快 3 倍，且精度足够合同分析——放弃渲染图像是换取速度的关键取舍。

步骤三：Express 接口实现（零胶水代码）

// server/routes/analyze.ts import { contractAgent } from '../agent.js'; export async function analyzeContract(req, res) { try { if (!req.file || req.file.mimetype !== 'application/pdf') { return res.status(400).json({ error: 'Only PDF files allowed' }); } // 直接将文件 buffer 传给 agent.run() const result = await contractAgent.run({ input: '请分析此合同的风险条款', tools: ['pdfTextExtractor', 'clauseDetector', 'htmlRenderer'], // 传递文件 buffer 给 tool（Paperclip 自动注入到 matching tool 的 execute） fileBuffer: req.file.buffer, }); res.json({ success: true, html: result.output }); } catch (err) { console.error('Contract analysis failed:', err); res.status(500).json({ error: err.message || 'Analysis failed' }); } }

关键技巧：Paperclip 支持在agent.run()的input对象中传递任意字段，这些字段会自动注入到匹配的 tool 的execute参数中。这里fileBuffer: req.file.buffer会被pdfTextExtractor.execute()接收到，无需在 tool 内部做任何特殊处理——这是 Paperclip 的“隐式参数注入”机制，极大简化了数据流转。

4.3 React 前端集成：usePaperclip 的正确用法

// src/components/ContractAnalyzer.tsx import { useState, useRef, useCallback } from 'react'; import { usePaperclip } from 'paperclip/react'; export default function ContractAnalyzer() { const agent = usePaperclip(); // 获取全局 Agent 实例 const [htmlResult, setHtmlResult] = useState<string>(''); const [isAnalyzing, setIsAnalyzing] = useState(false); const fileInputRef = useRef<HTMLInputElement>(null); const handleUpload = useCallback(async (e: React.ChangeEvent<HTMLInputElement>) => { const file = e.target.files?.[0]; if (!file || !file.type.includes('pdf')) return; setIsAnalyzing(true); try { // 构造 FormData 并发送到后端 const formData = new FormData(); formData.append('file', file); const res = await fetch('/api/analyze', { method: 'POST', body: formData, }); if (!res.ok) throw new Error(`HTTP ${res.status}`); const data = await res.json(); setHtmlResult(data.html); } catch (err) { alert(`分析失败：${err instanceof Error ? err.message : '未知错误'}`); } finally { setIsAnalyzing(false); } }, []); return ( <div className="contract-analyzer"> <input type="file" ref={fileInputRef} onChange={handleUpload} accept=".pdf" className="hidden" /> <button onClick={() => fileInputRef.current?.click()} disabled={isAnalyzing} > {isAnalyzing ? '分析中...' : '上传合同 PDF'} </button> {htmlResult && ( <div className="result-preview" dangerouslySetInnerHTML={{ __html: htmlResult }} /> )} </div> ); }

注意事项：

• usePaperclip()必须在PaperclipProvider内部调用，该 Provider 通常包裹在_app.tsx或main.tsx中；
• 我们刻意不使用agent.run()直接在前端调用，而是走 Express 接口——因为pdfTextExtractor依赖pdfjs-dist，其 Node.js 版本与浏览器版本 API 不同，直接在前端运行会导致GlobalWorkerOptions配置失效；
• dangerouslySetInnerHTML是安全的，因为htmlRenderertool 输出的 HTML 经过严格 XSS 过滤（使用DOMPurify.sanitize()），已在htmlRenderer.execute()内部完成。

5. 常见问题与排查技巧实录：我们踩过的 7 个典型坑

5.1 问题速查表：高频故障与一键修复