FastGPT 系统工具架构设计从分类、仓储到展示层的完整实现解析【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPTFastGPT 将 Agent 可调用的能力统一抽象为「工具Tool」本文基于仓库中 DESIGN.md 的设计蓝图结合packages/global/core/app/tool与packages/service/core/app/tool下的真实源码系统讲解 FastGPT 的工具分类体系、仓储层Repo的数据管理与密钥处理以及展示层Presenter/Client如何把远端工具元数据转换为画布节点。读完本文你将理解一条工具从插件市场/数据库中被发现、加载、校验、编译成模型 Function 参数最终渲染为工作流节点的完整链路并掌握工具 ID 规则、系统密钥加密、计费与版本管理等关键实现细节。一、工具分类三类来源统一抽象按照 DESIGN.md 的设计FastGPT 的工具分为三大类系统工具从 FastGPT-Plugin Service 获得的工具通常是纯代码实现的能力插件系统工作流工具商业版Pro后台配置的工具本质上关联一个 FastGPT 工作流应用由管理员在后台完成关联与发布用户自定义工具MCP 工具通过 MCP 协议接入的远程工具HTTP 工具通过 OpenAPI 或手动配置接入的 REST 接口工具工作流工具团队成员创建的工作流/Agent 应用Agent 本身也可以被其他 Agent 作为工具调用。1.1 源码中的工具来源枚举分类在代码中被收敛为AppToolSourceEnum见 packages/global/core/app/tool/constants.tsexport enum AppToolSourceEnum { personal personal, // this is a app. systemTool systemTool, // FastGPT-plugin tools, pure code. commercial commercial, // configured in Pro, with associatedPluginId. Specially, commercial-dalle3 is a systemTool mcp mcp, // mcp http http, // http /** * will be replaced by systemTool * deprecated */ community community }各来源的语义如下来源值含义典型载体personal个人/团队创建的应用含普通工作流MongoApp中的应用systemTool来自 FastGPT-Plugin Service 的代码型插件Plugin Service 接口 MongoSystemToolcommercial商业版后台配置、关联了工作流的工具MongoSystemTool.customConfig.associatedPluginId指向一个应用mcpMCP 工具集 / MCP 子工具MongoApp中mcpToolSet类型的应用httpHTTP 工具集 / HTTP 子工具MongoApp中httpToolSet类型的应用community已废弃的旧插件来源运行时被归一化为systemTool历史数据兼容其中commercial-dalle3是一个特例虽然前缀是commercial但它实际是代码型系统工具见 packages/global/core/app/tool/utils.ts 中的兼容分支。1.2 工具 ID 规则source id 的组合寻址工具在系统中的唯一标识遵循一套固定规则定义在splitCombineToolId见 packages/global/core/app/tool/utils.ts- personal: ObjectId(旧版), personal-objectId(新版) - commercial: commercial-ObjectId - systemTool: systemTool-id - mcp toolset: appId - mcp tool pluginId: mcp-appId/toolname - http toolset: appId - http tool pluginId: http-appId/toolname (废弃) community: community-id解析要点无前缀的裸 ID 被当作个人应用personal此时authAppId与pluginId相同mcp/http子工具的pluginId采用appId/toolname形式其中 toolname 可能本身以/开头如appId//test因此专门提供了splitToolsetToolPluginId负责把父 ID 与 toolName 拆分避免误切见 packages/global/core/app/tool/utils.ts工具身份由source 与 id 共同决定getToolIdentityKey生成${source}:${id}的复合键避免系统与团队同名插件互相覆盖见 packages/global/core/app/tool/utils.ts。1.3 团队隔离与调试态来源除了正式来源运行时还引入了两类内部来源见 packages/global/core/app/tool/utils.ts团队隔离来源teamId:xxx插件市场允许团队自行发布插件getTeamPluginSource(teamId)构造隔离 sourceisTeamPluginSource判断并可通过parseTeamPluginSource还原 teamId调试来源debug:tmbId:xxx用于 Agent 节点调试面板中的工具hasDebugToolInNodes会检查普通工具节点、工具集配置和selectedTools输入三处确保调试工具不会被发布到线上版本见 packages/global/core/app/tool/utils.ts。1.4 工作流工具的关联限制系统工作流工具复用了完整的 FastGPT 工作流但并非所有输入类型都适合以工具形式被外部调用。workflowToolUnsupportedInputTypes见 packages/global/core/app/tool/workflowTool/utils.ts明确禁止关联包含以下输入的工作流文件选择fileSelect知识库选择selectDataset、selectDatasetParamsModal、settingDatasetQuotePrompt模型选择selectLLMModel、settingLLMModel外部动态输入customVariable、addInputParam而hidden内部变量不属于禁止类型它会保留在 JSON Schema 中供运行时恢复默认值并在模型与外部参数边界被过滤。validateSystemToolWorkflowAssociation见 packages/service/core/app/tool/workflowTool/service.ts在关联前执行该校验关联时使用最新已发布版本尚未发布时回退到应用草稿。二、仓储层Repo统一管理系统工具的来源与状态仓储层是系统工具的数据访问中枢。SystemToolRepo采用单例模式实现见 packages/service/core/app/tool/systemTool/systemTool.repo.ts其核心职责在源码注释中被明确为「管理系统工具的来源plugin service 获取 / mongo 中存的对于业务层透明的缓存」unimplement标注缓存暂未实现。2.1 双数据源模型系统工具的元数据来自两个地方仓储层负责合并FastGPT-Plugin Service远端通过pluginClient见 packages/service/thirdProvider/fastgptPlugin调用listTools/getTool/listPluginVersions获得插件的名称、描述、Schema、版本与权限支持多语言环境withPluginClientLocaleMongoDB本地MongoSystemTool集合见 packages/service/core/app/plugin/tool/systemToolSchema.ts中存放管理员对工具的覆写配置——展示名、排序、费用、系统密钥、隐藏/推广标签以及商业版工作流工具的associatedPluginId关联关系。列表合并逻辑在getSystemToolList中见 systemTool.repo.ts先从插件服务按op/sources/tags拉取全部工具再用SystemToolCodec.attachToolConfig把数据库配置附着上去最后把数据库里带associatedPluginId的工作流插件DBWorkflowPlugins一并合入并按createSystemToolSorter排序——无标签时按pluginOrder有标签时优先按标签命中数排序见 systemTool.repo.ts。2.2 组合 ID 的归一化由于 ID 前缀可能被拼接systemTool-、commercial-仓储层用getSystemToolConfigIds见 systemTool.repo.ts生成候选 ID 集合例如commercial-xxx会同时尝试查commercial-xxx、xxx与systemTool-xxx三条记录再通过getFirstSystemToolConfig取第一条命中项兼顾新旧数据格式。SystemToolCodec见 packages/global/core/app/tool/systemTool/codec.ts则负责 DB 类型与列表类型的双向转换getDBPluginId把裸 pluginId 加上systemTool-前缀用于查库fromDBTypeToListItemType把数据库记录转换为统一的SystemToolListItemTypeattachToolConfig把配置附着到插件服务返回的列表项上并计算hasSystemSecret/systemSecretStatus。2.3 仓储层核心 APISystemToolRepo对外暴露的方法及其用途方法用途getSystemToolList获取系统工具列表插件服务 DB 合并、排序、多语言getSystemToolDetail获取单一插件的完整 Detail含 JSON Schema、子工具、密钥状态、版本信息getSystemToolDisplayInfo轻量展示信息刻意不返回 schema、不加载工作流版本仅用于路径/模板列表等 UI 元数据场景getSystemToolDisplayInfoWithChildIcons工具集展开列表需要子工具头像时补读 detail 获取 icongetVersions版本列表工作流工具返回关联应用的版本记录普通插件返回插件版本号getSystemToolRuntime运行前数据费用、解密后的系统密钥、权限并断言工具可运行下线工具返回PluginErrEnum.unExistgetSystemToolWorkflowRuntime商业版工作流工具运行时要求pluginId以commercial-开头返回关联应用的 nodes/edges/chatConfig 组装成AppToolRuntimeType其中getSystemToolDetail针对三种形态分别处理见 systemTool.repo.ts工作流工具读取MongoSystemTool.customConfig.associatedPluginId找到对应应用后经workflowToolNodes2JsonSchema把pluginInput/pluginOutput节点转换为输入/输出 JSON Schema工具集Toolset父插件带children时逐个子工具读取 DB 配置输出children数组含各自 schema、费用、icon普通系统工具直接透传插件服务的 schema、描述并附上 DB 中的展示/费用配置。workflowToolNodes2JsonSchema见 systemTool.repo.ts是实现工作流工具 Schema 化的关键函数它从节点中找到pluginInput与pluginOutput分别调用nodeInputs2JsonSchema/nodeOutputs2JsonSchema生成 JSON Schema其中filterInternalInputs: false以保留 hidden 输入的元数据与默认值。2.4 系统密钥加密存储与最小化暴露系统工具的密钥体系在 packages/global/core/app/tool/systemTool/constants.ts 中定义了三种来源与三种配置状态export enum SystemToolSecretInputTypeEnum { system system, // 系统密钥 team team, // 团队密钥unimplemented 未实现 manual manual // 自定义 } export enum SystemToolSystemSecretStatusEnum { none none, configured configured, unconfigured unconfigured }密钥值在存储时使用 AES-256-GCM 加密见 packages/service/common/secret/aes256gcm.ts并配套三段式工具见 packages/service/core/app/tool/systemTool/secrets.tsencryptSystemToolSecrets管理员提交时将 secret 字段加密为{ secret: 密文, value: }结构对未编辑字段保留原值掩码值__FASTGPT_SYSTEM_SECRET_MASKED__表示已有密钥但不回显maskSystemToolSecrets管理员详情接口只返回「已配置」标记绝不把明文或密文回传给前端decryptSystemToolSecrets运行时解密兼容历史非 AES 明文结构避免单个坏字段导致整个工具无法运行。此外工具节点输入中的敏感值统一经过formatToolInputSecrets见 packages/service/core/app/tool/secretConfig.ts处理保证 Agent 嵌套工具与普通工具使用一致的密钥规则systemInputConfig里的 secret 输入会被加密headerSecret走storeSecretValue密码类输入走encryptSecretValue。三、展示层把工具元数据渲染为工作流节点展示层负责把仓储层的数据转换前端可直接消费的节点模板FlowNodeTemplateType核心入口是 packages/service/core/app/tool/utils/client.ts 中的getClientToolPreviewNode与其内部的getClientSystemToolPreviewNode。3.1 工具预览节点的生成流程getClientToolPreviewNode见 client.ts按来源分支处理systemTool / commercial转调getClientSystemToolPreviewNode走SystemToolRepo.getSystemToolDetailpersonal应用从MongoApp读取应用。若是mcpToolSet/httpToolSet类型直接从存储解码工具集节点否则读取指定或最新版本再根据节点形态判定类型含pluginInput节点 →pluginModule工作流插件仅含toolSet节点 →toolSetMCP/HTTP 工具集仅含tool节点 →tool单个工具其余 →appModule对话工作流Agent 本身被调用mcp按appId/toolname解析父应用通过getMCPChildren拉取子工具列表并匹配工具名支持旧版多段命名回退见getToolNameCandidates生成 MCP 运行时节点getMCPToolRuntimeNodehttp通过getHTTPToolList拉取接口列表匹配后生成 HTTP 运行时节点getHTTPToolRuntimeNode。系统工具预览节点getClientSystemToolPreviewNode见 client.ts的关键处理把secretSchema通过jsonSchema2SecretInput转为systemInputConfig隐藏输入把inputSchema/outputSchema通过jsonSchema2NodeInput/jsonSchema2NodeOutput转成节点 IO工作流工具使用projectExternalVariableInput对外部变量输入做投影节点类型固定为pluginModule工具集写入toolConfig.systemToolSet普通工具写入toolConfig.systemTool输出若不含 error 输出自动追加Output_Template_Error_Message。3.2 工具集的存储解码MCP/HTTP 工具集以应用形式存在其节点数据在存储时经过压缩编码。读取侧通过decodeMcpToolSetNodesFromStorage/decodeHttpToolSetNodesFromStorage还原见 packages/service/core/app/tool/mcpTool/entity.ts 与 packages/service/core/app/tool/httpTool/entity.ts二者均按teamId ids批量查询MongoApp若解码结果与原始modules不同则返回解码后的副本且不写回存储。3.3 工具配置的数据结构MCP 工具见 packages/global/core/app/tool/mcpTool/type.tsMcpToolConfigSchema只含name、description、inputSchema三个字段工具集数据McpToolSetDataTypeSchema额外携带url与headerSecret。HTTP 工具见 packages/global/core/app/tool/httpTool/type.tsHttpToolConfigTypeSchema最为丰富除name/description/inputSchema/outputSchema外还包含path、method请求路径与 HTTP 方法requestSchema原始请求结构staticParams/staticHeaders固定 Query 参数与固定请求头staticBody静态请求体支持typeContentTypescontentJSON/XML/RawformData表单字段headerSecret请求头密钥。3.4 Agent 工具的持久化配置Agent 节点中选中工具的输入配置被抽象为AgentToolSchema见 packages/global/core/app/tool/type.tsconst AgentToolBaseSchema z.object({ id: z.string(), version: z.string().optional(), // 空字符串表示保持最新版本 source: z.string().optional(), toolConfig: NodeToolConfigTypeSchema.optional(), inputs: z.array(AgentToolInputConfigSchema).optional(), config: z.record(z.string(), z.any()) });每个输入项的来源由AgentToolInputConfigSchema源自CanonicalAgentToolInputConfigSchema定义mode决定是「由模型生成」agentGenerated还是使用AgentTool.config[key]中的固定值manualkey标识工具输入字段。该配置随工作流草稿或版本快照保存。四、运行时编译从 Schema 到模型 Function工具要被大模型调用最终需要编译为 OpenAI 风格的 Function 调用参数。这一过程由compileToolRuntime完成见 packages/global/core/app/tool/runtime.ts其输入是节点 IO 与可选的原始 JSON Schema输出是CompiledToolRuntimeexport type CompiledToolRuntime { modelTool: ChatCompletionTool; // 模型可见的 function schema agentGeneratedKeys: string[]; // 由模型生成的入参白名单 fixedInputBindings: Recordstring, unknown; // 固定绑定的入参 };核心步骤定义归一createToolInputDefinitions对每个输入计算allowedModes——只有canInputBeAgentGenerated的输入才允许模型生成reference 输入在执行前已解析为固定值因此可作为手动绑定配置解析createToolInputConfigurations从持久化格式解析出每个输入的最终mode与绑定值非法 mode 自动回退到allowedModes[0]Schema 编译用buildModelVisibleToolJsonSchema只保留模型生成的参数生成parameterSchema当没有模型生成入参时按 OpenAI function calling 约定省略parameters字段冲突检测同一字段不能同时出现在「模型生成」与「固定绑定」中否则抛出Tool input ${key} cannot be both generated and fixed。运行时合并模型参数与固定绑定时调用mergeToolRuntimeParams见 runtime.ts固定绑定在前模型生成的参数按白名单过滤后合并最终作为工具的真实入参。五、参数校验与计费5.1 基于 AJV 的 Schema 校验工具入参在执行前需要校验。仓库内置了三套 AJV 编译器分别支持 JSON Schema draft-07 / 2019-09 / 2020-12按$schema字段自动选择见 runtime.ts并通过validatorCache按序列化后的 schema 缓存编译结果validateToolInputValue用单个字段的 property schema 校验手工配置值validateToolRuntimeParams在外部调用前用完整 schema 校验剔除内部字段后的参数assertToolRuntimeParams服务端运行时断言失败信息带可定位的instancePath。5.2 工具计费规则费用计算集中在 packages/service/core/app/tool/runtime/utils.ts代码型系统工具单次费用computedSystemToolUsagecurrentCost (useSystemKey ? systemKeyCost : 0)——调用费与密钥来源无关只有实际使用平台系统密钥时才额外收取系统密钥费整体工具计分computedAppToolUsage系统/商业插件成功返回「单次积分 子流程积分可配置hasTokenFee」出错返回 0个人插件无论成败都只计子流程积分错误归一getAppToolOutputError只有 commercial 工作流工具输出中的error才被归一化为运行时错误文本personal 工作流工具可以把error作为业务字段返回不能误判为执行失败。5.3 工作流工具的变量注入工作流工具执行时由updateWorkflowToolInputByVariables见 packages/service/core/app/tool/workflowTool/utils.ts把外部参数注入pluginInput节点hidden 内部变量用默认值恢复密码输入解密string/number/boolean 直接赋值其余类型尝试 JSON.parse。filterWorkflowToolInputVariables则在入参边界只保留允许外部传入的字段。六、小结一条工具的完整生命周期综合上述各层一条系统工具在 FastGPT 中的完整生命周期可以概括为发现getSystemToolList合并 FastGPT-Plugin Service 与MongoSystemTool产出带配置、排序、密钥状态的列表选择前端经getClientToolPreviewNode拿到节点模板pluginModule/toolSet/tool/appModule用户将其加入 Agent 的selectedTools持久化Agent 节点以AgentToolSchema保存工具 ID、版本与输入来源agentGenerated/manual编译compileToolRuntime将 IO 编译为模型 Function schema 与固定绑定校验与执行assertToolRuntimeParams用 AJV 校验参数工作流工具经变量注入后按版本运行关联工作流系统密钥在运行时解密使用计费computedAppToolUsage依据来源与成败结算积分同时hasDebugToolInNodes确保调试工具不会进入线上发布数据。这种「分类枚举 组合 ID 仓储合并 Schema 化展示 运行时编译」的分层设计让代码型插件、工作流应用、MCP、HTTP 四类能力在 Agent 中拥有统一的调用契约也是理解 FastGPT 插件体系与 Agent 编排机制的钥匙。相关核心实现可继续阅读 packages/service/core/app/tool/systemTool/systemTool.repo.ts、packages/service/core/app/tool/utils/client.ts 与 packages/global/core/app/tool/runtime.ts。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考