Paperclip：AI工作流编排框架核心原理与工程实践

1. 项目概述：Paperclip 不是回形针，而是一个被严重误读的 AI 工程化枢纽

“Paperclip”这个词在中文技术圈里最近频繁跳出来，和 Node.js、React、OpenClaw、Claude 这些词捆在一起刷屏。很多人第一反应是——“哦，又一个前端 UI 组件库？或者某个 CLI 工具？”甚至有人搜“paperclip react 组件”，结果点开全是英文文档里一句冷冰冰的 “Paperclip is a framework for building AI-native applications”。更尴尬的是，不少人在掘金、知乎、V2EX 上发帖问：“Paperclip 是不是 OpenClaw 的前端？是不是 Claude 的客户端？能不能用 React 写 Paperclip 插件？”——这说明，连核心定位都没搞清，就急着配环境、跑 demo、写面经了。

我去年底在帮一家做智能文档协同的团队做架构评审时，第一次系统接触 Paperclip。当时他们已经用 OpenClaw 搭好了本地知识库检索链路，也接入了 Claude 的 API 做摘要生成，但卡在“用户一句话提问后，系统该调哪个工具、查哪份文档、要不要触发审批流”这个环节上。他们试过手写状态机、用 LangChain 的 AgentExecutor、甚至硬编码 if-else 路由逻辑，结果越写越乱：业务规则一改，整个调度层就得重测；加个新工具，要改三处代码；审计日志分散在不同模块，根本没法追溯一次完整会话的决策路径。直到我们把 Paperclip 引入，用它定义了一套 YAML 格式的“AI 工作流契约”，才真正把“意图识别→工具选择→参数绑定→执行调度→结果聚合”这条链路从代码里抽出来，变成可版本管理、可灰度发布、可 AB 测试的配置项。

Paperclip 的本质，是一个面向生产环境的 AI 应用编排框架（AI Orchestration Framework），不是 UI 库，不是 SDK，更不是某个大模型的专属伴侣。它解决的不是“怎么调 Claude API”，而是“当用户说‘帮我对比下 Q3 和 Q4 的销售报表差异，并邮件抄送财务总监’时，系统该怎么拆解、调度、串联、兜底、审计”。它的核心价值，在于把 AI 应用里最脆弱、最难维护、最易出错的那一段——也就是“人话到机器动作”的翻译层——从散落在各处的 JavaScript 函数、Python 脚本、Shell 命令里，统一收束成结构化、可验证、可协作的声明式定义。你完全可以不用 React 写前端，用 Node.js 做后端，用 OpenClaw 当向量库，用 Claude 当推理引擎，而 Paperclip 就站在它们中间，当那个冷静的“交通指挥员”。

所以，如果你正被这些热搜词裹挟着安装 Node.js、配置 VSCode、折腾 OpenClaw Ubuntu 安装教程，却还没想清楚“我的业务里，到底哪一段逻辑最需要 Paperclip 来接管”，那很可能花了三天时间配好环境，最后发现只是跑通了一个官方 demo，离真实业务还隔着一堵墙。Paperclip 不是万能胶，它是手术刀——只在你明确知道“这里需要精准切开、缝合、监控”的地方才值得动刀。

2. 核心设计思想与架构选型逻辑：为什么是 YAML + Node.js + 可插拔执行器？

Paperclip 的设计哲学，可以用一句话概括：把 AI 应用的“决策逻辑”从“执行逻辑”中彻底剥离，并让前者具备工程级的可维护性。这不是空谈理念，而是由一系列非常务实的技术选型共同支撑起来的。我带团队落地过三个 Paperclip 生产项目，从零开始搭起整套链路，下面拆解每一个关键选择背后的硬逻辑。

2.1 为什么首选 YAML 作为工作流定义语言？

你可能会疑惑：都 2025 年了，为什么不用 TypeScript 接口、不用 JSON Schema、甚至不用低代码拖拽界面？答案很直接：协作成本与变更安全性的极致平衡。

• TypeScript 接口太重：定义一个包含 5 个工具调用、3 层条件分支、2 种错误重试策略的工作流，TypeScript 类型声明动辄上百行，前端、后端、算法、产品四类角色根本没法一起审阅。产品经理看不懂type ToolCall = { name: string; args: Record<string, any> }，但能一眼看出 YAML 里if: ${input.query contains "审批"}这句话的意思。
• JSON Schema 太死板：它擅长校验结构，不擅长表达逻辑。比如“当用户身份为部门经理且申请金额 > 5 万时，自动触发风控模型；否则走常规流程”，这种嵌套条件在 JSON Schema 里要么写成一堆$ref和oneOf，要么干脆放弃校验，失去意义。
• 低代码拖拽太脆弱：所有生产环境反馈都指向同一个痛点——拖拽生成的流程图，一旦业务规则微调（比如加一个“节假日自动顺延审批”的分支），整个节点连线就要重画，历史版本 diff 几乎不可读，Git 合并冲突频发。

而 YAML，恰恰卡在这个黄金点上：

• 人类可读性强：缩进即层级，-即列表，:即键值对，没有括号嵌套地狱。我见过最复杂的 Paperclip 工作流 YAML 文件有 800 行，但业务方每周都能自己修改其中的timeout: 30s或retry: { max_attempts: 2, backoff: "exponential" }参数，无需开发介入。
• Git 友好：YAML 是纯文本，diff 工具能清晰标出哪一行加了条件、哪一行删了工具调用。我们上线前的 CR（Code Review）流程，就是产品经理和后端工程师对着 GitHub PR 页面，逐行确认 YAML 变更是否符合需求文档。
• 可验证性高：Paperclip 提供paperclip validate --schema ./workflow.yaml命令，能基于内置 Schema 对 YAML 进行静态检查，提前拦截语法错误、必填字段缺失、工具名拼写错误等低级问题，避免运行时才发现流程崩了。

实操心得：我们团队约定，所有 Paperclip 工作流 YAML 文件必须放在src/workflows/目录下，文件名格式为{业务域}-{场景}.yaml（如hr-onboarding-new-employee.yaml），每个文件顶部加注释块，说明该流程适用的用户角色、触发条件、SLA 要求（如“95% 请求响应 < 2s”）。这套规范让新人入职第三天就能独立修改审批流，而不是花一周看懂某段 TypeScript 的泛型嵌套。

2.2 为什么底层运行时选 Node.js，而非 Python 或 Go？

看到 OpenClaw（Python）、Claude（HTTP API）、React（前端）这些关键词，很多人直觉认为“Python 全家桶”更顺。但我们三个生产项目全部采用 Node.js 作为 Paperclip 运行时，理由非常实际：

• I/O 密集型场景的天然优势：Paperclip 的核心任务不是 CPU 计算，而是高频发起 HTTP 请求（调 Claude、调 OpenClaw API、调内部服务）、处理 WebSocket/SSE 流、解析大文件（PDF/PPT）、做轻量字符串匹配与模板渲染。Node.js 的事件循环模型在这种场景下，资源占用比 Python 的多线程/协程方案低 30%-40%。我们压测过同一套工作流：Node.js 版本在 2C4G 的 ECS 上稳定支撑 120 QPS，Python 版本（用 FastAPI + httpx）在相同配置下，QPS 刚过 80 就开始出现连接池耗尽告警。
• 生态无缝衔接前端：团队里 70% 的工程师主攻 React，他们写的工具函数（如parseExcelToJSON、generateReportMarkdown）天然就是 JavaScript/TypeScript。Paperclip 允许直接在 YAML 中import这些.ts文件，并在script字段里调用，省去了 Python-JS 桥接的序列化/反序列化开销和类型转换陷阱。一个典型例子：前端同事写了个calculateOvertimeHours函数，Paperclip 工作流里只需写script: ./utils/calculateOvertimeHours.ts，参数自动注入，返回值自动传给下一步，全程无 JSON stringify/parse。
• 部署与运维一致性：我们的 CI/CD 流水线（Jenkins + Docker）早已为 Node.js 项目优化多年，镜像构建缓存命中率高，启动速度快（Paperclip 服务冷启动 < 1.2s）。而 Python 环境（尤其涉及 OpenClaw 的依赖）在不同 Linux 发行版（Ubuntu/CentOS）上常因glibc版本、numpy编译问题导致构建失败，光解决 pip install 就耗费过两个迭代周期。

提示：Node.js 版本选择有讲究。Paperclip 官方明确要求 >= 18.18.0（LTS），但强烈建议用 20.12.0 或 22.12.0。原因在于 V8 引擎对Promise.withResolvers()和AbortSignal.timeout()的原生支持，能让超时控制、取消传播更可靠。我们曾用 18.20.4 部署，遇到过极端情况下timeout: 5s实际等待 15s 才触发的问题，升级到 22.12.0 后消失。

2.3 为什么执行器（Executor）设计成可插拔，而非内置？

Paperclip 的executor概念，是它区别于 LangChain、LlamaIndex 等框架的关键。它不预设你“必须用 HTTP 调 Claude”，也不规定“OpenClaw 必须走 REST API”。你可以为每种工具类型，编写一个独立的 Executor：

• claude-executor.ts：封装@anthropic-ai/sdk，处理 API Key 轮换、请求体构造（system prompt + user message + tool definitions）、流式响应解析（SSE chunk）、token 计费统计。
• openclaw-executor.ts：基于openclaw-clientnpm 包，实现向量搜索、RAG 上下文拼接、元数据过滤（filter: { department: "HR", status: "active" }）。
• email-executor.ts：对接企业邮箱 SMTP 服务，支持附件嵌入、HTML 模板渲染、发送状态回调。
• custom-api-executor.ts：用axios调用内部 Java 微服务，自动注入 JWT Token、处理 429 限流重试。

这种设计带来的好处是颠覆性的：

• 故障隔离：Claude API 服务抖动，只影响claude-executor，不会波及 OpenClaw 搜索或邮件发送。我们在生产环境做过演练：手动停掉 Claude 的 mock server，工作流自动降级到“仅提供文档链接”，其他步骤照常执行。
• 性能定制：OpenClaw 搜索慢？在openclaw-executor里加 Redis 缓存层，缓存query + filter组合的结果，命中率 65%，平均响应从 800ms 降到 120ms，且完全不影响其他 Executor。
• 合规审计：金融客户要求所有外部 API 调用必须记录完整请求/响应体。我们只需在claude-executor的execute方法开头加一行auditLogger.log({ method, url, body, timestamp })，所有 Claude 调用日志自动归集，无需改动任何工作流 YAML。

常见误区：很多新手以为 Executor 就是“写个 fetch 调 API”，结果写出的代码无法处理流式响应、没有重试机制、不记录 token 消耗。Paperclip 官方文档里Executor接口定义只有 3 个方法：init()（初始化连接池/认证）、execute(input: any)（核心执行）、close()（优雅关闭），但真正考验功力的，全在execute的实现细节里。

3. 核心工作流定义与实操实现：从 YAML 到可执行的完整链路

Paperclip 的威力，最终体现在一份份 YAML 文件里。下面以一个真实生产案例——“员工入职材料智能核验工作流”为例，带你走完从设计、编码、调试到上线的全流程。这个流程要完成：接收 HR 上传的 PDF 入职材料包 → 提取身份证、学历证、无犯罪记录证明三类文件 → 分别调用 OCR 服务识别文字 → 用 Claude 检查信息一致性（如身份证姓名与学历证是否一致）→ 若发现问题，生成修正建议并邮件通知 HR → 全部通过则触发 OA 系统创建工号。

3.1 工作流 YAML 结构详解：不只是配置，是契约

# src/workflows/hr-onboarding-verification.yaml name: "HR Onboarding Verification" description: "Automated verification of new employee onboarding documents" version: "1.3.0" # 语义化版本，用于灰度发布 trigger: type: "http" method: "POST" path: "/api/v1/onboard" input_schema: type: "object" properties: employee_id: type: "string" pattern: "^EMP[0-9]{6}$" document_package_url: type: "string" format: "uri" steps: - id: "extract-documents" type: "script" script: "./executors/extractDocuments.ts" input: package_url: "${trigger.input.document_package_url}" output: - id: "id_card_pdf" path: "$.id_card" - id: "degree_cert_pdf" path: "$.degree_cert" - id: "no_crime_pdf" path: "$.no_crime" - id: "ocr-id-card" type: "executor" executor: "ocr-executor" input: document: "${steps.extract-documents.output.id_card_pdf}" document_type: "id_card" timeout: "15s" retry: max_attempts: 2 backoff: "exponential" jitter: true - id: "ocr-degree-cert" type: "executor" executor: "ocr-executor" input: document: "${steps.extract-documents.output.degree_cert_pdf}" document_type: "degree_cert" timeout: "15s" retry: "inherit" # 继承上一步的重试策略 - id: "ocr-no-crime" type: "executor" executor: "ocr-executor" input: document: "${steps.extract-documents.output.no_crime_pdf}" document_type: "no_crime" timeout: "15s" retry: "inherit" - id: "validate-consistency" type: "executor" executor: "claude-executor" input: system_prompt: | You are an HR compliance auditor. Compare the following extracted texts and identify inconsistencies. Return ONLY valid JSON with keys: 'consistent' (boolean), 'issues' (array of strings), 'suggestions' (array of strings). user_message: | ID Card Text: ${steps.ocr-id-card.output.text} Degree Certificate Text: ${steps.ocr-degree-cert.output.text} No Crime Certificate Text: ${steps.ocr-no-crime.output.text} timeout: "30s" - id: "send-report" type: "conditional" condition: "${steps.validate-consistency.output.consistent == false}" then: - id: "notify-hr" type: "executor" executor: "email-executor" input: to: "hr@company.com" subject: "[URGENT] Onboarding Inconsistency for ${trigger.input.employee_id}" body: | Issues found: ${steps.validate-consistency.output.issues.join("\n- ")} Suggestions: ${steps.validate-consistency.output.suggestions.join("\n- ")} else: - id: "create-employee" type: "executor" executor: "oa-api-executor" input: employee_id: "${trigger.input.employee_id}" name: "${steps.ocr-id-card.output.name}" start_date: "${steps.ocr-id-card.output.issue_date}" error_handlers: - step_id: "ocr-id-card" on_error: "skip" - step_id: "ocr-degree-cert" on_error: "skip" - step_id: "ocr-no-crime" on_error: "fail" # 任一 OCR 失败，整体流程终止

这份 YAML 的每一行，都不是随意写的，而是承载着明确的工程契约：

• version: "1.3.0"：这是灰度发布的锚点。我们上线前，会先将1.3.0版本部署到 5% 的流量，监控成功率、延迟、错误码分布，确认无异常后再全量。YAML 版本号直接映射到 Git Tag，确保线上运行的每一份流程，都有对应的代码快照。
• trigger.input_schema：这是工作流的“入口契约”。它强制要求上游服务（如 HR 系统）必须按此 Schema 提交数据，否则 Paperclip 在解析阶段就返回 400 错误，避免无效请求进入执行链路。我们曾因此拦截了大量因前端表单漏填employee_id导致的空指针异常。
• output的path: "$.id_card"：使用 JSONPath 语法，精确指定从extractDocuments.ts返回对象的哪个字段提取为输出。这比output: "id_card"这种模糊映射更健壮，防止函数返回结构微调（如从{ id_card: "..."}变成{ data: { id_card: "..." } }）导致下游步骤取不到值。
• retry: "inherit"：不是偷懒，而是为了保持重试策略的一致性。如果 OCR 服务在高峰期普遍响应慢，我们只需在ocr-executor.ts的init()方法里统一调整defaultRetryConfig，所有引用该 Executor 的步骤自动生效，无需逐个 YAML 修改。
• error_handlers：这是 Paperclip 最被低估的特性。它允许你为每个步骤定义“失败后怎么办”，而不是全局 catch。skip表示忽略该步骤失败，继续执行后续；fail表示立即终止整个流程；还可以写fallback: "step-id"调用备用步骤（如 OCR 失败时，调用一个更慢但更准的旧版 OCR 服务）。我们用skip+fail组合，实现了“身份证 OCR 失败可容忍，但无犯罪记录证明 OCR 失败必须阻断”的强合规要求。

3.2 Executor 编码实操：以 claude-executor 为例

YAML 只是蓝图，Executor 才是血肉。下面展示claude-executor.ts的核心实现，重点解释那些官方文档没细说、但生产环境踩过坑的关键点：

// src/executors/claude-executor.ts import { Anthropic } from "@anthropic-ai/sdk"; import { Executor, ExecutorContext, ExecutorResult } from "paperclip"; // 1. 全局 Client 实例，复用连接池，避免每次新建 HTTP Client const anthropicClient = new Anthropic({ apiKey: process.env.CLAUDE_API_KEY || "", // 关键：设置合理的 timeout，避免长连接阻塞 timeout: 30_000, // 30s 总超时 }); // 2. Executor 类必须实现 init/close，用于资源生命周期管理 export class ClaudeExecutor implements Executor { private client: Anthropic; async init(context: ExecutorContext): Promise<void> { // 初始化时校验 API Key 是否有效，避免运行时才发现 try { await this.client.messages.list({ limit: 1 }); } catch (e) { throw new Error(`Claude API Key validation failed: ${e.message}`); } } async execute(input: any, context: ExecutorContext): Promise<ExecutorResult> { const { system_prompt, user_message, model = "claude-3-haiku-20240307" } = input; // 3. 构造标准 Claude Messages 格式，注意 system prompt 的位置 // Claude 不支持在 messages 数组里放 system role，必须用单独的 system 字段 const messages = [ { role: "user", content: user_message } ]; try { // 4. 关键：使用 stream: true 获取 SSE 流，Paperclip 会自动处理 chunk 解析 const response = await this.client.messages.stream({ model, system: system_prompt, messages, max_tokens: 1024, // 5. 重要：设置 temperature=0 保证确定性，AI 工作流不能“发挥创意” temperature: 0, // 6. 关键：添加自定义 header，用于后端审计追踪 headers: { "X-Request-ID": context.requestId, "X-Workflow-Version": context.workflowVersion, } }); // 7. Paperclip 期望的 result 格式：必须是 { success: boolean, data: any, error?: string } // data 字段会自动注入到下一步的 input 中，所以必须是 JSON 可序列化的 plain object let accumulatedContent = ""; for await (const chunk of response) { if (chunk.type === "content_block_delta") { accumulatedContent += chunk.delta.text || ""; } } // 8. 严格 JSON 解析，失败则抛出 error，让 Paperclip 触发 error_handler try { const parsedData = JSON.parse(accumulatedContent); return { success: true, data: parsedData }; } catch (e) { return { success: false, error: `Failed to parse Claude response as JSON: ${e.message}. Raw content: ${accumulatedContent}` }; } } catch (e) { // 9. 统一错误包装，便于上层分类处理 const errorMessage = e instanceof Error ? e.message : String(e); return { success: false, error: `Claude API call failed: ${errorMessage}` }; } } async close(): Promise<void> { // 清理资源，如关闭连接池 } } // 10. 必须导出 default 实例，Paperclip 通过 import 调用 export default new ClaudeExecutor();

实操心得：

• Connection Pool 复用：anthropicClient是单例，不是每次execute都新建。Node.js 的http.Agent默认 keepAlive 是开启的，但必须显式设置maxSockets（默认 50），否则高并发下会耗尽 socket。我们在init()里加了this.client = new Anthropic({...})，并在close()里调用this.client.close()。
• Temperature=0 是铁律：AI 工作流里，模型“自由发挥”等于灾难。temperature: 0强制模型输出最可能的 token，保证相同输入永远得到相同输出，这是可测试、可审计的前提。我们曾因忘记设这个，导致自动化测试每天随机失败。
• Error Handling 的粒度：catch里不直接throw，而是返回success: false的ExecutorResult。因为 Paperclip 的error_handlers机制，只对ExecutorResult.success === false的情况生效。如果execute方法里throw，会直接 crash 整个工作流进程，无法触发skip或fallback。
• X-Request-ID 透传：这是全链路追踪的生命线。Paperclip 的context.requestId会在整个工作流执行过程中保持不变，我们把它注入到每个外部 API 的 header 里，再配合 Jaeger 或 SkyWalking，就能在 Grafana 里看到“一次入职核验请求，经过了哪几个 Executor，每个耗时多少，哪个步骤失败了”。

3.3 本地调试与线上部署：如何避免“本地跑通，线上跪了”

Paperclip 提供了强大的本地开发体验，但生产环境的坑往往藏在细节里。以下是我们的标准化流程：

本地调试（Dev）：

1. npm run dev:workflows启动 Paperclip 开发服务器，它会自动监听src/workflows/下所有 YAML 文件变化，热重载。
2. 使用curl或 Postman 发送测试请求：

   curl -X POST http://localhost:3000/api/v1/onboard \ -H "Content-Type: application/json" \ -d '{"employee_id":"EMP000001","document_package_url":"https://mock-bucket.s3.amazonaws.com/test-package.pdf"}'

3. 关键技巧：Paperclip 开发服务器默认开启--debug模式，所有步骤的输入/输出、执行耗时、错误堆栈，都会打印在控制台。我们习惯在extractDocuments.ts里加console.log("DEBUG: extracted files:", result)，然后在终端里Ctrl+F搜索DEBUG快速定位。

CI/CD 部署（Prod）：

• Docker 构建：我们使用多阶段构建，基础镜像node:22.12.0-slim，只 COPYdist/和src/workflows/，体积 < 120MB。
• 环境变量隔离：.env.production文件里只放CLAUDE_API_KEY、OPENCLAW_URL等密钥，通过 Kubernetes Secret 挂载，绝不写入镜像。
• 健康检查：Paperclip 服务暴露/healthz端点，返回{"status":"ok","workflows":["hr-onboarding-verification"]}，K8s Liveness Probe 每 10s 检查一次。
• 灰度发布：使用 Istio VirtualService，将1.3.0版本的流量按百分比路由。我们有个canary标签的 Deployment，专门跑新版本，Prometheus 监控其paperclip_workflow_execution_duration_seconds_bucket指标，与stable版本对比。

注意：线上环境必须禁用--debug模式！它会把敏感的input和output（如身份证号、OCR 文本）全打到日志里，违反 GDPR 和国内《个人信息保护法》。我们 CI 流水线里有一条强制检查：grep -r "debug" dist/ && exit 1，确保生产包里没有 debug 代码。

4. 常见问题排查与避坑指南：来自三个生产项目的血泪总结

Paperclip 的学习曲线不算陡峭，但生产环境的坑，往往不在文档里。以下是我们在真实项目中踩过的、反复出现的、且官方 FAQ 没覆盖的典型问题，附带排查思路和根治方案。

4.1 问题：工作流执行一半就静默退出，日志里没有任何错误信息

现象：YAML 里定义了 6 个步骤，但curl请求后，只看到前 3 步的日志，第 4 步validate-consistency完全没动静，HTTP 响应卡住，最终超时返回 504。

排查思路：

1. 首先确认不是网络问题：kubectl exec -it <pod-name> -- sh进入容器，curl -v https://api.anthropic.com看是否能通。
2. 检查 Paperclip 日志级别：paperclip start --log-level info默认只打 info 级别，而 Executor 的console.log是 debug 级，看不到。临时改成--log-level debug，重新触发，果然看到claude-executor在await this.client.messages.stream(...)这行卡住。
3. 进一步分析：stream方法返回的是一个 AsyncIterable，Paperclip 的 runtime 会for await它。但如果 Claude 的 SSE 响应头里Content-Type不是text/event-stream，或者第一个 chunk 不是event: message-start，某些 Node.js 版本的ReadableStream会 hang 住。

根治方案：

• 在claude-executor.ts的execute方法里，加一层AbortController超时保护：

  const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 30_000); // 30s try { const response = await this.client.messages.stream({ // ... 其他参数 signal: controller.signal, // 关键！传入 signal }); // ... 处理 stream } finally { clearTimeout(timeoutId); }

• 同时，确保@anthropic-ai/sdk版本 >= 0.25.0，该版本修复了signal传递到底层fetch的 bug。

4.2 问题：YAML 中${steps.xxx.output.yyy}语法报错 “Cannot read property 'yyy' of undefined”

现象：extract-documents步骤返回{ id_card: "url1", degree_cert: "url2" }，但ocr-id-card步骤的input.document: "${steps.extract-documents.output.id_card}"却报错，提示id_card不存在。

根本原因：Paperclip 的变量解析发生在工作流编译期，而extractDocuments.ts的返回值是运行时动态的。如果extractDocuments.ts因为 PDF 解析失败，返回了{}空对象，那么output.path: "$.id_card"就找不到值，Paperclip 会返回undefined，导致后续步骤崩溃。

解决方案：

• 防御性编程：在extractDocuments.ts里，强制返回结构：

  export async function extractDocuments(input: { package_url: string }): Promise<{ id_card: string; degree_cert: string; no_crime: string; }> { const result = await parsePdfPackage(input.package_url); // 即使没找到某类文件，也返回空字符串，不返回 undefined return { id_card: result.id_card || "", degree_cert: result.degree_cert || "", no_crime: result.no_crime || "" }; }

• YAML 层面加默认值：Paperclip 支持${steps.xxx.output.yyy ?: "default_value"}语法，可以在变量后加?:提供 fallback：

  input: document: "${steps.extract-documents.output.id_card ?: 'https://placeholder.com/blank.pdf'}"

4.3 问题：OpenClaw 搜索结果为空，但手动 curl OpenClaw API 却能返回数据

现象：openclaw-executor调用search方法，返回[]，但用curl "http://openclaw:3000/search?q=xxx"却能看到结果。

排查发现：Paperclip 的openclaw-executor里，filter参数是这样传的：

const response = await axios.post(`${this.baseUrl}/search`, { query: input.query, filter: input.filter // 这里传的是一个 JS 对象 });

而 OpenClaw 的 REST API，filter参数期望的是一个 JSON 字符串，不是对象。axios默认会把对象序列化成application/json，但 OpenClaw 的/searchendpoint 实际上是application/x-www-form-urlencoded，它把filter当成了普通字符串字段，而不是解析 JSON。

根治方案：

• 修改openclaw-executor.ts，显式序列化filter：

  const response = await axios.post(`${this.baseUrl}/search`, { query: input.query, filter: JSON.stringify(input.filter) // 关键！转成字符串 }, { headers: { "Content-Type": "application/x-www-form-urlencoded" } });

• 或者，更优解：让 OpenClaw 的/searchendpoint 支持application/json，统一接口风格。我们后来推动 OpenClaw 团队升级了 API，现在filter直接传对象即可。

4.4 问题：React 前端调用 Paperclip API 时，CORS 报错 “No 'Access-Control-Allow-Origin' header”

现象：前端fetch("http://paperclip-service/api/v1/onboard")报 CORS 错误，但 Postman 调用正常。

原因：Paperclip 的paperclip start命令启动的是一个 Express 服务，但它默认不启用 CORS 中间件。fetch是浏览器行为，受同源策略限制；Postman 是独立 HTTP 客户端，不受此限。

解决方案：

• 在 Paperclip 项目根目录下，创建server.js（或index.js），覆盖默认启动逻辑：

  const express = require('express'); const { createServer } = require('paperclip'); const app = express(); // 添加 CORS 中间件 app.use((req, res, next) => { res.header('Access-Control-Allow-Origin', 'https://your-react-app.com'); // 生产环境精确域名 res.header('Access-Control-Allow-Methods', 'POST, GET, OPTIONS, PUT, DELETE'); res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization'); if (req.method === 'OPTIONS') { res.sendStatus(200); } else { next(); } }); // 创建 Paperclip Server，并挂载到 Express const paperclipServer = createServer({ workflowsDir: './src/workflows', // 其他配置... }); app.use('/api', paperclipServer); app.listen(3000, () => { console.log('Paperclip server running on port 3000'); });

• 启动命令改为node server.js，而不是paperclip start。

4.5 问题：工作流执行成功，但 Prometheus 监控显示paperclip_workflow_failed_total指标持续上涨

现象：业务功能一切正常，但监控大盘里失败率曲线在缓慢爬升，查日志发现大量Step 'xxx' failed: TypeError: Cannot read property 'text' of undefined。

根因分析：这是典型的“上游步骤失败，下游步骤未做空值校验”导致的连锁失败。ocr-id-card步骤因为 PDF 损坏返回了{ text: undefined }，validate-consistency步骤的user_message模板里写了${steps.ocr-id-card.output.text}，结果模板渲染成 `"ID