在 Celigo 中构建可复用工具（Tool）时如何设计输入…

当同一段查找/导入/转换逻辑需要被多个 Flow、API、AI Agent、MCP Server 或其他 Tool 复用时，把它封装成 Celigo Tool。

适用场景

解决思路

1. 判断是否该建 Tool：需要构建 MCP server、同一逻辑被 2+ 消费者使用、希望调用方灵活传入不同连接、或需要工具嵌套编排时，就建 Tool；否则内联为 lookup/import 处理器。
2. 区分 Tool 与 API：API 可从 Celigo 外部通过 HTTP 访问，Tool 只能从 Celigo 内部（flow 步骤、AI agent、API、其他 tool）访问；若两者都需可达，先建 Tool 再用 API endpoint 暴露它。
3. 区分 Tool 与 Flow：Tool 不能自启动，没有 schedule、listener、flow 运行时控制（如 proceedOnFailure）和 abstract/instance 层；『每晚执行 X』或『webhook 到达时执行 Y』应建 Flow，Tool 只是 Flow 执行的内容。
4. 按架构组织：Tool 包含 input（JSON Schema）、routers[]（处理管线）、output（schema、mappings、lookups、hooks）；routers 含 branches，branches 含 pageProcessors（exports 查找、imports 写入、transfers）。
5. 理解执行管线：input 按 JSON Schema 校验 → routeRecordsUsing 评估分支条件 → 选中分支处理 → page processors 顺序执行 → 每个 processor 的 responseMapping 把数据传给下一个 processor → 按 output 配置做输出映射 → 返回给调用方。
6. 按调用方决定执行模式：Flow 调用走 flow 模式（批处理、run console、错误管理）；API 调用走 API 模式（单请求/响应）；AI Agent 调用带 agent 上下文；MCP Server 调用暴露为 MCP tool endpoint；Tool 调用为父 tool 上下文内的嵌套执行。
7. 遵循连接模型：始终 bring-your-own-keys，由调用方（flow、API、agent、MCP server）在配置时把连接映射到 tool；MCP Server 可按 server 覆盖连接而不修改 tool。
8. 按构建顺序推进：Connection → Export + Import → Tool → 消费者（Flow / API / Agent / MCP Server）。
9. 规划 response mapping：在 pageProcessors[] 上配置，用于把 processor 响应字段提取回记录；lookup 响应有 data[] 和 errors[]（单结果用 data[0].fieldName），import 用 _json.fieldName；使用 Transformation 1.0 语法（extract/generate 对）。
10. 规划 postResponseMap hook：在 pageProcessors[] 上配置，用于 response mapping 之后的 JavaScript 处理。
11. 区分两种 lookup：分支 page-processor lookup（pageProcessors[].type: "export"）在运行时调用外部系统（如按 email 在 NetSuite 查客户），用 responseMapping 把字段拉回记录；output 静态 lookup 表（output.lookups[]）是不访问外部系统的固定键值翻译表，由 output.mappings[] 通过 lookupName 引用。
12. 确定 tool 用途：明确被调用时应做什么，定义期望的输入和处理步骤。
13. 识别 integration：每个 tool 属于一个 integration，先找到或创建它（celigo integrations list）。
14. 检查已有模式：用 celigo account search "<keyword>" 搜索账户、celigo account dependencies tool <id> 查看已有 tool 依赖、celigo account lint 找可复用孤儿资源、celigo tools list 查相似 tool、celigo templates marketplace 搜预建模板；账户索引超过 4 小时自动刷新，可用 celigo account snapshot 强制刷新。
15. 自底向上构建连接、exports 和 imports：先建 connections，再建使用这些连接的 exports 和 imports，最后建把它们串起来的 tool（参考 configuring-exports 和 configuring-imports）。
16. 定义 input schema：用 JSON Schema 对象描述 tool 接受的数据；为兼容 MCP，根 schema 必须有 type: "object"。
17. 按需配置路由：无路由则跳过 routers；基于过滤用 routeRecordsUsing: "input_filters" 在每个分支写声明式表达式规则；基于脚本用 routeRecordsUsing: "script" 由自定义 JavaScript 函数返回分支名。
18. 把 page processors 接入分支：每个分支的 pageProcessors[] 是有序的 exports（查找）和 imports（动作）列表；每个 processor 配置 type（"export" 或 "import"）、_exportId 或 _importId、responseMapping、hooks.postResponseMap、proceedOnFailure。
19. 配置 output：用 mappings[]（extract/generate 字段对，Celigo 标准映射格式）、lookups[]（静态键值富化表）、hooks.preMap / hooks.postMap（映射前后脚本钩子）；注意分支 responseMapping 把 processor 响应合并到在途记录供下游分支和 router 使用，而 output mappings 只在最后组装返回值且只能看到最终在途记录，若某 processor 响应字段要出现在输出中，必须先在该 processor 上配置 response mapping。
20. 构建 JSON：参考 Schema Index 获取确切字段，按 Which Schemas to Read 规则决定查阅哪些文件（request.yml、input.yml、output.yml、router.yml、response.yml）。
21. 仅在用户明确要求时重构步骤为 Tool：触发词如 refactor、factor out、extract、turn this into a tool、make this part reusable、pull these steps out as their own tool；绝不主动提议。
22. 执行重构：把指定步骤解析为单一入口、单一出口的连续选择（有效 tool 拓扑）；针对边界处真实记录形状设计新 tool 的 input 和 output schema；为父级构建 wrapper 指向新 tool，然后重写父级移除选中步骤并接入新 tool-step。
23. 重构时注意：入口和出口节点永不移动（flow 的 trigger 步骤、API 的 request/response 书签、tool 的 input/output 节点都从选择中剔除）；不克隆任何资源，新 tool 的 page processors 引用父级内联使用的同一 export/import ID，若这些底层资源被更新以适配新 tool 的输入输出形状，变更会传播到所有其他消费者；重构不可撤销，没有程序化逆操作，回退需手动删除新 tool 及其 wrapper 并恢复父级；一次只重构一个父级。
24. 使用 CLI 命令：CRUD 用 celigo tools list/get/create/update/set/delete；管理 page processors 用 celigo tools add-processor <id> <exportOrImportId> [--router <routerId>] [--branch <branchName>] [-y] 和 remove-processor；测试用 celigo tools test-run、test-run-step-results、test-run-step-logs；调试用 celigo tools debug-requests、debug-request-detail（需在底层 export/import 上启用 debug）；发现用 celigo account search、celigo templates marketplace。
25. 提交前检查必填项：name 已设置、_integrationId 引用有效 integration、input.schema 已定义且根为 type: "object"（MCP 兼容必需）。
26. 提交前检查管线：所有 _exportId / _importId 引用存在资源、被引用 exports/imports 的连接在线、router ID 在 tool 内唯一、所有分支汇回 output 节点（无悬空分支）、链中最后一个分支用 nextRouterId: "outputRouter" 退出 tool。
27. 提交前检查跨资源一致性：如需 response mapping 已在分支内 pageProcessors[] 上配置、如用路由则 routeRecordsUsing 和分支 filters/scripts 配置正确、如用于 MCP 则 tool name 在该 MCP server 所有 tool 和 API 条目中唯一。
28. 避免常见陷阱：PUT 会抹掉省略字段，先 GET 再改再 PUT（set 命令可处理）；router ID 在 tool 内必须唯一，分支 nextRouterId 必须引用真实 router id 或特殊值 "outputRouter"；不允许悬空分支；除非需要，不要在 router 上包含 routeRecordsTo 或 routeRecordsUsing，否则 API 可能要求顶层 dataType 字段触发校验错误；tool 在使用中不能删除，先查 Used by 依赖；add-processor 会自动创建 router（无 router 时创建默认单分支 router，否则默认定位第一个 router 的第一个分支，用 --router 和 --branch 指定位置）；MCP Server 中 tool name 必须唯一；debug 日志在 export/import 上而非 tool 上，用 celigo exports enable-debug 或 celigo imports enable-debug 后在 tool 上查看；test run 结果可能 base64 编码，CLI 自动解码但原始 API 响应需手动解码；两种 lookup 不可互换；重构不可撤销且仅用户驱动。
29. 处理常见错误：422 _integrationId required 需设置有效 integration ID；422 input.schema invalid 需确保根 schema 有 type: "object" 且 JSON Schema 语法有效；422 router id not unique 需每个 router id 在 tool 内唯一；422 dangling branch 需在每个分支设 nextRouterId 为有效 router ID 或 "outputRouter"；422 _exportId not found / _importId not found 需验证引用资源存在未删除；409 tool in use 需先从所有 flows、APIs、agents、MCP servers 移除该 tool 再删除；422 dataType required 需从简单 tool 移除 routeRecordsTo / routeRecordsUsing，API 会正确默认。

适用边界 · 注意事项

• 逻辑仅属于单个 flow 或 API 且不会复用时——直接内联为 lookup/import 处理器。
• 需要多租户模式的 abstract/instance 模板时——使用 abstract flows。
• 用户未明确要求重构时——不要主动提议把步骤抽取为 tool，复用决策属于用户，且该操作会创建真实 Celigo 记录并可能修改共享资源。