Paperclip：面向工程化的AI Agent协作协议与调试框架

1. 项目概述：Paperclip 不是回形针，而是一个被低估的 AI Agent 开发范式

你搜“paperclip”，第一反应可能是办公桌抽屉里那个银色小金属件——但最近半年，在 Node.js 和 React 开发者圈子里，“Paperclip”已经悄悄变成一个高频技术代号。它不是某个大厂新发布的框架，也不是某家明星创业公司的闭源产品，而是一个开源、轻量、可嵌入的 AI Agent 协作协议层。我第一次在 GitHub 上看到它的 README 时，心里一紧：这东西怎么没早两年出来？我们团队过去三年为多个客户定制的“AI 工具链中台”，有 70% 的胶水代码，其实都在重复解决 Paperclip 现在用 200 行核心逻辑就搞定的问题。

Paperclip 的本质，是把 AI Agent 从“单体黑盒”拉回到“可组合、可调试、可版本化”的工程化轨道上。它不训练模型，不封装 LLM API，也不做 UI 渲染——它只干一件事：定义 Agent 之间如何安全、可追溯、带上下文地交换结构化指令与反馈。你可以把它理解成 HTTP 之于 Web 服务，或者 gRPC 之于微服务——但专为 AI 原生工作流设计。它用 Node.js 实现运行时调度中枢，用 React 构建开发者控制台，所有协议消息走 JSON Schema 校验，支持本地调试、生产环境 trace 追踪、甚至离线回放。这不是又一个“React + LLM”的玩具 demo，而是真正能塞进企业级 CI/CD 流水线里的 Agent 编排基础设施。

为什么现在突然火？因为大家终于意识到：光堆 prompt、调 API、套 wrapper，撑不起一个可持续迭代的 AI 应用。上周我帮一家做智能法务 SaaS 的客户重构他们的合同审查流程，他们原来用的是三个独立的 LangChain Chain，每个 Chain 调一个 LLM，中间靠 Redis 存临时状态，出错时根本不知道是哪个环节的 system prompt 写错了，还是哪次 token 截断导致了语义丢失。换成 Paperclip 后，整个流程变成 4 个可独立测试的 Agent：doc-parser→clause-extractor→risk-analyzer→summary-generator，每个 Agent 只暴露一个execute(input: InputSchema): Promise<OutputSchema>接口，输入输出自动校验，错误直接定位到具体 Agent 的第 3 行 prompt 模板。Node.js 侧负责路由、重试、超时、日志注入；React 控制台则实时显示每个 Agent 的输入/输出/耗时/token 数，连 temperature 值都标红显示——这才是工程师该有的调试体验。

它适合谁？不是刚学完 React 基础的前端新人，也不是只会调openai.ChatCompletion.create()的 API 玩家。它面向的是那些已经踩过至少三轮 Agent 开发坑的实战者：你写过超过 5 个不同用途的 LLM 封装函数，你手动维护过 prompt 版本 diff，你为 context 长度限制改过三次数据预处理逻辑，你深夜被线上 agent 返回的"I don't know"报警电话叫醒过……如果你正卡在“AI 功能能跑通，但没法上线、没法监控、没法交接给同事维护”这个阶段，Paperclip 就是为你准备的。

2. 核心架构拆解：为什么选择 Node.js + React 组合，而不是 Python 或纯前端方案？

2.1 Node.js 作为运行时中枢：不是“因为 JS 全栈”，而是“因为事件驱动 + 生态成熟”

很多人第一眼看到 Paperclip 用 Node.js，下意识觉得：“哦，又是前端团队写的玩具”。但实际翻它的core/runtime目录，你会发现它根本没用 Express 或 Fastify 做 Web Server——它用的是原生EventEmitter+Worker Threads构建的轻量级调度内核。为什么不用 Python？我们团队做过对比实验：同样执行 100 个并发 Agent 调用（每个调用含 3 次 LLM API + 2 次数据库查询），Python 的 asyncio 在高并发下内存泄漏明显，GC 周期不可控，而 Node.js 的 libuv 事件循环在 10K+ 并发连接下依然稳定。更重要的是，Node.js 的 npm 生态对“协议层开发”极度友好：json-schema-validator、pino日志、undiciHTTP 客户端、node-fetch的 AbortController 支持——这些不是“能用”，而是“开箱即用且经过百万级项目验证”。

举个真实例子：Paperclip 的timeout机制不是简单设个setTimeout。它在 Worker Thread 启动时，就注入一个AbortSignal，所有内部异步操作（HTTP 请求、DB 查询、甚至本地 LLM 调用）都绑定这个 signal。一旦超时，整个 Worker 线程被优雅终止，不会留下僵尸 promise。这个能力在 Python 的asyncio.wait_for里实现起来要绕七八个弯，而在 Node.js 里，就是两行代码：

const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), config.timeoutMs); // 所有异步操作传入 signal await fetch(url, { signal: controller.signal });

更关键的是部署适配性。Paperclip 的生产部署包是单个dist/目录，里面只有index.js和package.json，npm install --production后体积 <8MB。我们把它塞进 Alpine Linux 的 Docker 镜像，基础镜像才 5MB。而同等功能的 Python 方案，光torch+transformers依赖就压垮了容器内存。CentOS 7.9 上部署？Paperclip 只要求 Node.js 18.20.4 LTS（官方长期支持版），curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs三行命令搞定。你不用操心glibc版本冲突，不用编译numpy，更不用在/usr/local/lib下手动 ln -s ——这就是 Node.js 在基础设施层的真实优势。

2.2 React 作为控制台：不是“为了炫技”，而是“因为状态可预测 + DevTools 深度集成”

Paperclip 的 React 部分，代码量不到整个项目的 15%，但它决定了开发者能否真正掌控 Agent。这里有个反直觉的设计：Paperclip 的 React 应用不渲染任何业务 UI，它只渲染三样东西：Agent 列表、消息流时间轴、JSON Schema 输入/输出面板。所有业务逻辑（比如合同审查的 UI 表单、图表展示）都由外部 React 应用通过@paperclip/clientSDK 注入。为什么这么设计？因为我们发现，90% 的 Agent 调试失败，根源不在模型输出，而在输入数据格式错位。比如clause-extractorAgent 的 input schema 要求{"document_id": "string", "page_range": [number, number]}，但上游传进来的是{"docId": "xxx", "pages": "1-5"}——这种类型不匹配，在纯终端日志里根本看不出，但在 React 控制台里，Schema 面板会用红色边框高亮docId字段，并提示 “Expected string, got undefined”。

React 的useReducer+immer组合，让整个调试状态完全可回溯。你点“Replay from step 3”，控制台会精确还原当时所有 Agent 的输入、输出、中间状态，连Math.random()生成的 seed 都被序列化保存。这背后是 Paperclip 的state-snapshot协议：每次 Agent 执行完成，Node.js 运行时会把input,output,metadata（含 timestamp, duration, token_count）打包成一个带 hash 的 JSON 对象，存入本地 LevelDB。React 控制台通过 WebSocket 订阅这些快照，用react-virtualized渲染万级消息流而不卡顿。你甚至可以导出.pcp文件（Paperclip Protocol），发给同事，他双击就能在本地复现整个执行链路——这比截图 debug 日志强十倍。

再看热词里反复出现的 “react state与hooks” ——Paperclip 的控制台正是 Hooks 最佳实践的教科书。useAgentStatus()自动订阅 Agent 状态变更；useMessageStream()处理 SSE 流式响应；useSchemaValidator()动态加载 JSON Schema 并实时校验输入。没有useState堆砌，全是useMemo缓存计算结果、useCallback防止重渲染。我们实测过：当同时打开 12 个 Agent 的实时日志面板，CPU 占用率稳定在 8% 以下，而同类 Vue 实现的控制台在 6 个面板时就飙到 45%。这不是框架之争，而是 React 的 Fiber 架构在复杂状态同步场景下的工程红利。

2.3 协议层设计：为什么不用 gRPC 或 GraphQL，而坚持 JSON over HTTP？

Paperclip 的核心协议，是极简的POST /v1/agent/{id}/execute，body 是纯 JSON，response 也是 JSON。有人问：为什么不搞 gRPC 提高性能？为什么不套 GraphQL 做灵活查询？答案很实在：降低接入门槛，确保协议可读、可调试、可代理。我们服务过金融客户，他们的安全审计要求所有外部请求必须经过 F5 BIG-IP，而 gRPC 的二进制协议会被 F5 拦截；我们也对接过政府云平台，其 WAF 规则只放行标准 HTTP 方法和 JSON Content-Type。Paperclip 的协议，用curl就能完整测试：

curl -X POST http://localhost:3000/v1/agent/doc-parser/execute \ -H "Content-Type: application/json" \ -d '{ "document_url": "https://example.com/contract.pdf", "page_limit": 10 }'

返回的 JSON 包含id（本次执行唯一 ID）、status（running/success/error）、output（结构化结果）、trace_id（用于全链路追踪）。这个设计让 Paperclip 天然兼容任何现有基础设施：Nginx 可以做负载均衡，Prometheus 可以抓取/metrics暴露的paperclip_agent_execution_duration_seconds指标，ELK 可以索引trace_id做日志关联。更重要的是，它让非 JS 开发者也能快速接入。我们有个客户用 Java Spring Boot 写的风控 Agent，只用了 20 行RestTemplate代码就完成了对接，而如果强制用 gRPC，他们得额外维护 proto 文件、生成 stub、处理 TLS 证书——这违背了 Paperclip “最小可行协议” 的初衷。

3. 核心细节解析：从零搭建一个可调试的 Paperclip Agent

3.1 Agent 开发四要素：Schema、Executor、Metadata、Lifecycle Hook

Paperclip 把一个 Agent 定义为四个必需部分，缺一不可。这不是框架的任性，而是来自血泪教训：我们曾见过客户把所有逻辑塞进一个execute()函数，结果无法做输入校验、无法统计 token、无法在失败时自动重试。现在，每个 Agent 必须导出：

• schema.ts：严格的 JSON Schema，定义输入/输出结构
• executor.ts：纯函数，接收input，返回Promise<output>
• metadata.ts：描述性信息（name, description, version, author）
• lifecycle.ts（可选）：onStart,onError,onComplete钩子

来看一个真实的risk-analyzerAgent 示例（简化版）：

// schema.ts export const inputSchema = { type: "object", properties: { clause_text: { type: "string", minLength: 1 }, jurisdiction: { type: "string", enum: ["US", "CN", "EU"] }, risk_threshold: { type: "number", minimum: 0, maximum: 1 } }, required: ["clause_text", "jurisdiction"] } as const; export const outputSchema = { type: "object", properties: { risk_level: { type: "string", enum: ["low", "medium", "high"] }, flagged_terms: { type: "array", items: { type: "string" } }, explanation: { type: "string" } }, required: ["risk_level", "flagged_terms"] } as const;

提示：as const是 TypeScript 5.0+ 的关键语法，它让 schema 在编译期就被锁定为字面量类型，后续input参数的类型推导才能精准到字段级。很多团队忽略这点，导致input.clause_text的类型只是any，失去类型安全。

// executor.ts import { OpenAI } from "openai"; import { z } from "zod"; const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); export async function execute(input: z.infer<typeof inputSchema>) { // 步骤1：构造 prompt，严格遵循 schema 输出格式 const prompt = ` Analyze the following legal clause for risk level. Jurisdiction: ${input.jurisdiction} Risk threshold: ${input.risk_threshold} Clause: "${input.clause_text}" Output ONLY valid JSON matching this schema: ${JSON.stringify(outputSchema)} `; // 步骤2：调用 LLM，强制要求 JSON mode（OpenAI 1.0+） const response = await openai.chat.completions.create({ model: "gpt-4-turbo", messages: [{ role: "user", content: prompt }], response_format: { type: "json_object" }, // 关键！避免 LLM 返回 markdown temperature: 0.1 // 低温度保证确定性 }); // 步骤3：用 Zod 解析并校验输出 const parsed = z.object(outputSchema).parse( JSON.parse(response.choices[0].message.content!) ); return parsed; }

注意：这里response_format: { type: "json_object" }是 OpenAI 1.0+ 的硬性要求。旧版functions参数已被弃用，强行使用会导致 400 错误。我们踩过坑：客户用gpt-3.5-turbo-1106时忘了升级 SDK，结果所有 Agent 返回空字符串。

// metadata.ts export const metadata = { name: "risk-analyzer", description: "Analyzes legal clauses for jurisdiction-specific risk levels", version: "1.2.0", author: "legal-ai-team@client.com", tags: ["legal", "risk", "compliance"] };

// lifecycle.ts export function onError(error: Error, input: any, context: { traceId: string }) { // 发送告警到 Slack if (error.message.includes("rate limit")) { sendSlackAlert(`🚨 Rate limit hit in ${metadata.name} (trace: ${context.traceId})`); } } export function onComplete(output: any, input: any, context: { durationMs: number }) { // 记录到 Prometheus agentExecutionDurationSeconds .labels({ agent: metadata.name, status: "success" }) .observe(context.durationMs / 1000); }

3.2 Node.js 运行时配置：如何平衡性能、可靠性和可观测性

Paperclip 的server.ts不是简单的app.listen()。它包含三层关键配置：

第一层：Worker Pool 管理
默认启动 4 个 Worker Thread（根据 CPU 核数动态调整），每个 Worker 处理一个 Agent 执行。为什么不用cluster模块？因为cluster的进程间通信（IPC）在高频率 Agent 调用下成为瓶颈。Worker Threads 共享内存，postMessage传递数据比 IPC 快 3 倍。我们通过worker_threads.getEnvironmentData()注入 LLM API Key，避免在每个 Worker 里重复读取环境变量。

第二层：LLM 客户端熔断
Paperclip 内置CircuitBreaker类，基于滑动窗口统计失败率。当gpt-4-turbo的 5 分钟失败率 > 30%，自动切换到降级模型gpt-3.5-turbo，并发送告警。配置代码仅 12 行：

const breaker = new CircuitBreaker({ failureThreshold: 3, timeoutMs: 30000, fallback: () => getFallbackModel() // 返回 gpt-3.5-turbo }); // 在 executor 中调用 await breaker.execute(() => openai.chat.completions.create(...));

第三层：可观测性注入
每条 Agent 执行日志都自动注入trace_id和span_id，格式为pcp-{timestamp}-{random}。我们用pino日志库，输出 JSON 格式，字段包括level,time,pid,hostname,trace_id,span_id,agent,input_hash,output_hash,duration_ms,token_count。这些字段被 ELK 自动提取为 Kibana 可视化指标。特别注意input_hash：它不是简单sha256(JSON.stringify(input))，而是用fast-json-stable-stringify库，确保对象属性顺序不影响哈希值——否则相同输入因 key 顺序不同产生不同 hash，导致缓存失效。

3.3 React 控制台深度定制：不只是看日志，而是重构调试流

Paperclip 的@paperclip/clientSDK 提供了createClient()工厂函数，允许你注入自定义行为：

import { createClient } from "@paperclip/client"; const client = createClient({ // 自定义日志处理器：把 error 日志发到 Sentry onLog: (log) => { if (log.level === "error") { Sentry.captureException(new Error(log.message), { extra: { trace_id: log.trace_id } }); } }, // 自定义输入预处理：自动添加用户 ID preprocessInput: (agentId, input) => ({ ...input, user_id: getCurrentUserId() }), // 自定义输出后处理：对 financial 数据自动格式化 postprocessOutput: (agentId, output) => { if (agentId === "financial-calculator") { return { ...output, amount: formatCurrency(output.amount) }; } return output; } });

控制台的MessageStream组件支持filter属性，你可以按trace_id、agent_name、status实时筛选。最实用的功能是“Step Into”：点击某条output，控制台会自动展开该 Agent 的完整执行上下文，包括：

• 它的input（带 schema 校验结果）
• 它调用的 LLM 原始 request/response（含 token 数、model id）
• 它触发的onComplete钩子日志
• 它下游所有依赖 Agent 的执行记录（通过trace_id关联）

这个功能让我们把平均故障定位时间从 47 分钟缩短到 3.2 分钟。以前查问题要翻 5 个日志系统，现在在控制台一个页面搞定。

4. 实操全流程：从本地开发到生产部署的 7 个关键步骤

4.1 步骤 1：环境初始化——Node.js 版本与依赖安装的避坑指南

Paperclip 要求 Node.js 18.20.4 LTS（2024 年 4 月发布），这是经过严格验证的版本。为什么不是最新版 22.12+？因为 Node.js 22 的fetchAPI 默认启用keepAlive，而某些老旧的 LLM 代理服务（如部分私有化部署的 vLLM）会因 keep-alive 连接复用导致 session 混乱。我们实测过：在 Node.js 22.12+ 下，连续调用 100 次vllm-server，第 87 次开始返回前一次请求的响应。降级到 18.20.4 后问题消失。

安装步骤必须严格按顺序：

1. 卸载所有旧 Node.js：sudo apt remove nodejs npm（Ubuntu）或brew uninstall node（Mac）
2. 用 Nodesource 安装 LTS：

   # Ubuntu/Debian curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs

3. 验证版本：node -v必须输出v18.20.4，npm -v必须输出9.9.2（LTS 绑定版本）
4. 全局安装 pnpm（Paperclip 强制要求）：npm install -g pnpm

   为什么不用 npm 或 yarn？pnpm 的硬链接机制让node_modules体积减少 70%，pnpm install速度比 npm 快 3 倍。Paperclip 的 monorepo 有 12 个子包，用 npm 会生成 2GB 的冗余 node_modules。

4.2 步骤 2：创建第一个 Agent——用 CLI 工具生成骨架

Paperclip 提供@paperclip/cli，运行pnpm create paperclip-agent@latest my-risk-analyzer。它会生成标准目录：

my-risk-analyzer/ ├── src/ │ ├── schema.ts # 输入/输出 schema │ ├── executor.ts # 执行逻辑 │ ├── metadata.ts # 元数据 │ └── lifecycle.ts # 生命周期钩子 ├── package.json └── tsconfig.json

CLI 会自动配置tsc为--noEmit（类型检查不生成 JS），eslint启用@paperclip/eslint-config规则集（强制zod校验、禁止any类型、要求response_format）。最关键的，它会在package.json中注入preparescript：

"scripts": { "prepare": "pnpm run build && pnpm run schema:validate" }

prepare在pnpm install后自动执行，确保每次安装依赖都重新构建并校验 schema。我们曾遇到客户删掉prepare，导致 schema 更新后未 rebuild，Agent 运行时崩溃——这个钩子是 Paperclip 工程质量的底线保障。

4.3 步骤 3：本地开发调试——如何用 React 控制台实时观测 Agent

启动命令是pnpm dev，它会并行运行：

• pnpm --filter server dev：启动 Node.js 运行时（端口 3000）
• pnpm --filter client dev：启动 React 控制台（端口 3001）

控制台首页的+ Add Agent按钮，支持三种方式：

• Local Path：选择本地my-risk-analyzer目录，自动加载metadata.name
• Git URL：输入 GitHub 仓库地址，如https://github.com/your-org/paperclip-agents/tree/main/risk-analyzer
• Registry：从私有 NPM registry 拉取@your-org/risk-analyzer@1.2.0

添加后，点击 Agent 卡片进入调试页。左侧是Input Schema面板，右侧是Execute按钮。输入 JSON 后，点击执行，你会看到：

• 实时日志流（绿色 success / 红色 error）
• Trace ID显示在顶部栏，点击可复制
• Output面板自动高亮 schema 不匹配字段
• 底部Execution Timeline显示每个子步骤耗时（LLM call, DB query, validation）

实操心得：调试时务必开启浏览器 DevTools 的 Network 标签页，观察/v1/agent/{id}/execute请求的 Request Payload 和 Response。如果返回 400，Response body 会明确告诉你哪条 schema 校验失败，比如"input.clause_text: should be string"。

4.4 步骤 4：生产构建——如何生成可部署的单文件包

pnpm build会执行：

• tsc编译所有 TypeScript
• esbuild打包server为单个dist/index.js
• vite build打包client为静态文件到dist/client/
• paperclip-pack工具将dist/和agents/目录合并为paperclip-bundle.tar.gz

最终产物是：

• bundle/目录，含index.js,package.json,agents/（所有 Agent 的编译后 JS）
• client/目录，含index.html,assets/（React 静态资源）

部署时，只需：

# 解压到服务器 tar -xzf paperclip-bundle.tar.gz -C /opt/paperclip # 安装生产依赖（无 devDependencies） cd /opt/paperclip && npm install --production # 启动（自动读取 PORT 环境变量） PORT=8080 NODE_ENV=production node dist/index.js

注意：--production是关键！Paperclip 的devDependencies包含typescript,eslint,jest，总大小 1.2GB。生产环境必须排除，否则 Docker 镜像会暴涨。

4.5 步骤 5：Docker 部署——Alpine 镜像的极致精简技巧

Paperclip 官方 Dockerfile 基于node:18-alpine，但默认 Alpine 的musllibc 与某些 LLM SDK（如llama-cpp-node）不兼容。我们的生产镜像做了三处优化：

# 使用更小的基础镜像 FROM ghcr.io/vercel/node:18-alpine AS builder # 构建阶段：安装构建依赖 RUN apk add --no-cache python3 make g++ && \ npm install -g pnpm # 复制源码并构建 COPY . . RUN pnpm install && pnpm build # 生产阶段：纯净 Alpine FROM node:18-alpine # 复制构建产物，不复制源码 COPY --from=builder /app/dist /app/dist COPY --from=builder /app/agents /app/agents COPY --from=builder /app/client /app/client # 删除构建依赖，只保留 runtime RUN apk del python3 make g++ && \ rm -rf /var/cache/apk/* # 设置非 root 用户 RUN addgroup -g 1001 -f nodejs && \ adduser -S nextjs -u 1001 USER nextjs EXPOSE 3000 CMD ["node", "dist/index.js"]

最终镜像大小仅 92MB（对比 Ubuntu 基础镜像的 1.2GB）。我们用dive工具分析过：node_modules占 68MB，agents/占 12MB，client/占 8MB，其余 4MB 是 Node.js 运行时。这个尺寸，让它能轻松部署到边缘设备（如 NVIDIA Jetson）上运行本地 LLM Agent。

4.6 步骤 6：CI/CD 集成——GitHub Actions 的标准化流水线

Paperclip 的.github/workflows/ci.yml包含 5 个必检阶段：

1. Setup：actions/setup-node@v3安装 Node.js 18.20.4
2. Install：pnpm install --frozen-lockfile（锁文件校验）
3. TypeCheck：pnpm tsc --noEmit（类型检查）
4. Test：pnpm test（Jest 运行单元测试，覆盖率 >85%）
5. Build：pnpm build（生成 bundle）

关键创新点是Agent Schema 自动化校验：在Build阶段后，插入一个schema-validate步骤：

- name: Validate Agent Schemas run: | for agent in agents/*; do if [ -f "$agent/schema.ts" ]; then # 提取 inputSchema 和 outputSchema 的 JSON 字符串 INPUT_SCHEMA=$(grep -A 20 "inputSchema =" "$agent/schema.ts" | grep -v "export" | sed 's/;$//') OUTPUT_SCHEMA=$(grep -A 20 "outputSchema =" "$agent/schema.ts" | grep -v "export" | sed 's/;$//') # 用 ajv-cli 验证 schema 语法 echo "$INPUT_SCHEMA" | ajv validate -s - <<EOF {"type":"object"} EOF fi done

这个脚本确保每个 Agent 的 schema 是合法 JSON Schema，防止因手误（如多写逗号、少写引号）导致生产环境崩溃。我们上线前最后一道防线。

4.7 步骤 7：监控告警——用 Prometheus + Grafana 搭建 Agent 健康仪表盘

Paperclip 的/metrics端点暴露 7 个核心指标：

Grafana 仪表盘预置 4 个核心视图：

• Agent 健康概览：Top 10 Agent 的成功率、平均耗时、错误率热力图
• Token 消耗监控：按模型、按 Agent 的 token 消耗趋势（防止 GPT-4 滥用）
• Trace 分析：输入trace_id，查看完整执行链路（类似 Jaeger）
• 告警看板：paperclip_agent_error_rate > 0.1触发 Slack 告警

实操心得：我们给每个 Agent 设置了token_budget（预算），比如risk-analyzer设为 5000 tokens/分钟。当paperclip_agent_token_usage_total超过阈值，Grafana 自动触发alertmanager，暂停该 Agent 的调度，避免账单爆炸。

5. 常见问题与排查技巧实录：那些文档里不会写的实战经验

5.1 问题 1：Agent 执行返回 “Invalid JSON” 错误，但 LLM 响应看起来是合法 JSON

现象：控制台显示Error: Invalid JSON: Unexpected token '}'，但复制 LLM 的原始 response 内容到 JSONLint 验证是合法的。

根因：OpenAI 的response_format: { type: "json_object" }并非 100% 可靠。当 prompt 过长或模型负载高时，GPT-4 Turbo 仍可能返回带 markdown 代码块的 JSON，例如：

```json {"risk_level": "high", "flagged_terms": ["indemnify"]}

**解决方案**：在 `executor.ts` 中添加 JSON 清洗逻辑： ```typescript function cleanJsonResponse(raw: string): string { // 移除 markdown 代码块标记 const cleaned = raw.replace(/```(?:json)?\n?|\n?```/g, '').trim(); // 移除 BOM 和不可见字符 return cleaned.replace(/^\uFEFF/, ''); } // 在 executor 中调用 const content = cleanJsonResponse(response.choices[0].message.content!); const parsed = z.object(outputSchema).parse(JSON.parse(content));

这个清洗函数是我们在线上跑了 3 个月后加的，修复了 92% 的此类错误。不要相信 LLM 的输出是干净的——永远假设它是脏的。

5.2 问题 2：本地调试正常，生产环境 Agent 执行超时（Timeout）

现象：curl测试http://prod-server:3000/v1/agent/risk-analyzer/execute返回504 Gateway Timeout，但 Node.js 日志无错误。

排查路径：

1. 检查NODE_OPTIONS=--max-old-space-size=4096是否设置（Paperclip 默认 2GB，高并发需调大）
2. 查看paperclip_worker_queue_length指标是否持续 > 0（Worker 队列积压）
3. 检查ulimit -n是否足够（Paperclip 默认需要 65536 文件描述符）

根本原因：生产服务器的ulimit -n是 1024，而 Paperclip 的 Worker Pool 启动 4 个线程，每个线程最多打开 200 个 HTTP 连接（LLM + DB），总需求 800+，但系统限制 1024 导致连接池枯竭。

修复命令：

# 临时提升（重启后失效） sudo ulimit -n 65536 # 永久生效（/etc/security/limits.conf） echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

5.3 问题 3：React 控制台显示 “Connection refused