统一工具抽象
FIM One 的核心设计理念是智能体能做的一切都是工具。计算器、知识库查询、ERP API 调用和第三方 MCP 服务器都实现相同的Tool 协议：name、description、parameters_schema、category 和 run()。智能体不知道也不关心它是在调用本地 Python 函数、查询向量数据库、代理到遗留系统还是调用社区 MCP 服务器。它看到的是 ToolRegistry 中的一个平面工具列表。
这是一个刻意的架构选择，而不是偶然的简化。这意味着添加新的能力源永远不需要改变智能体、执行引擎或上下文管理层。你注册工具；智能体使用它们。
四个能力源汇聚到一个注册表。智能体平等地从所有这些源中获取。
四个能力来源
内置工具
在启动时通过discover_builtin_tools() 自动发现。将 BaseTool 子类放入 core/tool/builtin/，它会在没有任何配置的情况下自动注册。类别包括计算（calculator、python_exec）、网络（web_search、web_fetch）、文件系统（file_ops）和通用（email_send、json_transform、template_render、text_utils）。这些是智能体的原生能力——始终可用，零配置。
知识库
条件性。当智能体绑定了kb_ids 时，通用的 kb_retrieve 工具会被替换为专门的检索工具。在简单模式下，KBRetrieveTool 执行基本的 RAG 检索。在接地模式下，GroundedRetrieveTool 运行一个 5 阶段的管道：多知识库检索、引用提取、对齐评分、冲突检测和置信度计算。知识库不是一个独立的子系统，而是作为专门的工具进入智能体——它受到与其他所有工具相同的 Tool 协议的约束。
连接器
ConnectorToolAdapter 将企业系统操作包装为工具。每个操作都成为一个名为 {connector}__{action} 的工具，分类为 connector。该适配器添加了带有身份验证注入的 HTTP 代理（bearer、API 密钥、基本身份验证）、操作级访问控制（读/写/管理员）、响应截断和审计日志。对于直接数据库访问，DatabaseToolAdapter 提供了具有可选只读强制的架构感知 SQL 执行。连接器是 AI 和遗留系统之间的桥梁 — 核心差异化因素。有关完整设计，请参阅 连接器架构。
MCP
外部 MCP 服务器通过标准协议提供第三方工具。每个服务器在自己的进程中运行（stdio 或 HTTP 传输），完全与平台隔离。工具被适配到Tool 协议中，并在 mcp 类别下注册。管理员可以配置全局 MCP 服务器，自动为所有用户加载。MCP 是生态系统的关键——任何兼容 MCP 的服务器都可以无需自定义集成而工作。
按请求进行工具组装
每个聊天请求都通过_resolve_tools() 中的过滤管道组装一个新鲜的工具集。这不是静态配置 — 它是根据智能体的设置、用户身份以及可用的连接器和 MCP 服务器按请求计算的。
六个步骤：
- 基础发现。
discover_builtin_tools()加载所有内置工具，范围限定在对话的沙箱内。 - 智能体类别过滤。
filter_by_category(*agent.tool_categories)限制为仅智能体被允许使用的类别。 - 知识库注入。 如果智能体有
kb_ids，通用检索工具会根据检索模式被替换为KBRetrieveTool或GroundedRetrieveTool。 - 连接器加载。 从数据库查询智能体绑定的连接器。每个连接器的操作（或数据库模式）被实例化为工具适配器并注册。
- MCP 加载。 用户的个人 MCP 服务器以及管理员配置的全局 MCP 服务器被加载、连接，并注册其工具。
- 运行时选择。 如果工具总数超过 12，一个轻量级 LLM 调用会为此特定查询选择最相关的子集（最多 6 个）。选择失败是非致命的 — 智能体会回退到完整集合。
何时使用什么
| 需求 | 使用 | 原因 |
|---|---|---|
| 通用计算、代码执行、文本转换 | 内置工具 | 始终可用，无需配置 |
| 企业系统集成（ERP、CRM、OA） | 连接器 | 身份验证治理、审计跟踪、操作级访问控制 |
| 带引用和证据的知识检索 | 知识库 | RAG 管道、有根据的生成、冲突检测 |
| 第三方工具生态系统 | MCP | 标准协议、流程隔离、社区服务器 |
| 直接数据库访问 | 数据库连接器 | 模式感知 SQL、可选的只读强制执行 |
| 自定义内部工具 | MCP 或内置 | MCP 用于流程隔离；内置用于紧密集成 |
执行引擎是正交的
工具系统和执行引擎是独立的关注点。两个引擎都从同一个ToolRegistry 消费工具。引擎的选择影响智能体如何编排工具，而不是哪些工具可用。
ReAct 是一个迭代工具循环。智能体进行推理、选择工具、观察结果，然后重复，直到完成。它擅长探索性、对话式任务，其中下一步取决于前一步的结果。循环最多运行 50 次迭代，通过 ContextGuard 进行每次迭代的上下文管理。有关实现细节，请参阅 ReAct Engine。
DAG 将目标分解为 2-6 个并行步骤。每个步骤运行一个独立的 ReAct 智能体。PlanAnalyzer 评估目标是否已实现；如果未实现，管道会自主重新规划（最多 3 轮）。DAG 擅长具有明确子任务且可以并发运行的任务——“搜索三个来源并比较结果”在一次搜索的时间内完成，而不是三次。有关完整管道，请参阅 DAG Engine。
两个引擎共享基础设施：用于可靠结构化输出的 structured_llm_call、用于令牌预算强制执行的 ContextGuard 和用于工具解析的 ToolRegistry。添加新工具不需要对任何引擎进行任何更改。添加新引擎（如果需要）不需要对工具系统进行任何更改。
生命周期概览
启动。start.sh 运行 Alembic 迁移，启动 FastAPI 服务器，发现内置工具，并为任何预配置的全局服务器建立 MCP 服务器连接。
按请求。 JWT 身份验证、智能体配置查找、工具组装（上述 6 步管道）、引擎选择（基于智能体配置的 ReAct 或 DAG）、SSE 流式执行以及结果持久化。
横切关注点。 上下文管理（5 层令牌预算）保护每个 LLM 调用免于溢出。审计日志跟踪每个连接器工具调用。沙箱隔离包含代码执行工具。双 LLM 架构（智能 + 快速）优化规划、执行和合成的成本。
该架构的设计使得每个关注点——工具注册、执行编排、上下文管理、安全性——都可以独立演进。可以添加新的连接器类型、新的执行引擎或新的上下文策略，而不会在系统中产生级联变化。