工具系统
Tool System Design
统一管理、注册、发现、执行工具；MCP 协议标准化。工具系统是 Agent 能力的边界。
子问题
1.工具注册：如何定义和注册工具的 schema（名称、参数、返回值）
2.工具发现：Agent 如何知道有哪些工具可用
3.权限控制：哪些工具需要用户确认才能执行
4.结果格式化：工具返回结果如何格式化为 LLM 可理解的文本
5.MCP 协议：Model Context Protocol 标准化工具接口
6.多 MCP Server 端口冲突自动解决：如何在多服务启动时检测并自动分配可用端口
7.跨进程运行时配置同步：多个独立 MCP Server 进程如何共享 Agent 运行时状态
8.市场规则内嵌工具逻辑：交易工具如何内嵌不同市场的业务规则（整手限制、T+1）
9.LLM 供应商兼容层：如何修复不同 LLM 供应商的 tool_calls 格式差异
10.JS REPL 沙箱逃逸防护：vm.Context 已知逃逸向量的缓解策略
11.位置参数到命名参数映射：LLM 生成的函数调用如何自动对齐 schema key 顺序
12.跨轮次沙箱状态：mem 对象如何在多次 evaluate 间持久化而不泄露
13.action 遥测标准化：工具返回的结构化遥测数据如何统一格式供断言验证
14.Rust 原生 MCP 客户端：非 Node.js 环境如何实现 MCP 协议客户端
15.槽位命名冲突：同名插件在不同槽位的共存策略
16.模块解析注入：monorepo 严格依赖下如何让核心包加载插件包
17.插件配置传递：注册时如何将全局配置映射为插件特定配置
18.Tier 渐进解锁：如何按配置复杂度分级，让用户从零配置开始逐步解锁高级工具
19.浏览器 Cookie 提取：如何从本地浏览器自动提取多平台登录凭据
20.mcporter 多 MCP 桥接：如何通过统一 CLI 桥接多个异构 MCP Server
21.安装器与调用层分离：工具系统是否应该包装调用层，还是只做安装检测让 Agent 直接调用上游
22.知识注入替代 Schema：如何通过文档教 Agent 调用工具而非定义 Function Calling Schema
23.URL 自动路由：如何根据 URL 域名自动匹配目标工具渠道
24.后端工具健康检测：如何分层检测 CLI/MCP/API 等不同类型后端的可用性
25.凭据安全管理：如何安全存储和检测 Cookie/Token 等敏感凭据的权限
26.三源异构工具统一管理：Python 函数、MCP Server、Agent Skill 如何共享同一注册表
27.元工具自激活：如何让 Agent 通过工具调用动态控制工具集
28.MCP 双传输模式：stdio（无状态）和 HTTP（有状态）如何共享同一接口
29.Agent Skill 文档驱动：如何通过 YAML Front Matter 和 Markdown 文档定义技能
30.流式非流式统一：同步/异步/生成器工具如何提供统一的流式接口
31.后处理钩子：工具执行后如何修改返回结果而不修改原函数
32.装饰器闭包依赖注入：如何通过装饰器捕获实例方法的 self 实现依赖注入
33.工具调用强制策略：如何通过 prompt 注入强制 LLM 首次必须调用特定工具
34.工具调用历史追踪：如何从 AIMessage.tool_calls 提取参数并格式化为去重键
35.伪工具引导：如何利用 tools/list 机制向 LLM 传递工具使用规范
36.MCP stdout 保护：stdio 传输下如何防止日志破坏 JSON-RPC 协议
37.工具结果 token 预算：如何设计分层返回格式控制每次调用的 token 消耗
38.经济闭环集成：工具调用如何同时触发成本扣除和收入入账形成经济循环
39.Provider 透明包装：如何在不修改上游框架的前提下拦截 LLM 调用追踪成本
40.运行时类变异：如何通过 __class__ 替换升级已有实例而不重建对象
41.工具内业务校验：execute 内部如何做多层参数归一化和业务规则校验
42.声明式技能同步：builtin/customized/active 三级目录的覆盖与反向同步策略
43.闭包工具注入：如何用闭包将运行时依赖绑定到工具函数避免全局变量
44.每查询 Agent 实例化：多渠道服务中如何平衡工具注册开销与会话隔离
45.YAML Front Matter 校验：技能创建时如何强制校验元数据完整性
46.大结果驱逐：工具返回超大内容时如何自动写入文件并替换为预览
47.后端能力检测：如何运行时判断后端是否支持 execute 并动态调整工具集
48.工具描述精确度：如何编写足够详细的工具描述让 LLM 正确使用分页、glob 等参数
49.跨后端状态同步：CompositeBackend 路由写入后如何同步 default 后端的文件列表状态
50.双层工具架构：如何让同一工具同时服务 MCP 协议和内部 Agent loop
51.工具集动态组合：如何按场景（实现/评估）选择性激活工具子集
52.工具 schema 与实现分离：如何独立演进工具定义而不修改实现代码
53.心跳保活：MCP SSE 长连接如何通过周期性 RPC 调用防止服务端超时断开
54.工具结果摘要分片：大网页内容如何分片送入摘要 LLM 并增量合并结果
55.异构工具系统统一协议：同步本地工具和异步远程工具如何共享同一套 XML 调用协议
56.沙箱端点负载均衡：多个沙箱执行端点如何通过随机选择实现简单负载均衡
57.批量查询合并：搜索工具如何支持单次调用传入多个 query 减少 Agent 轮次
58.工具结果摘要：原始工具输出如何压缩为 LLM 可消费的摘要文本
59.工具调用生命周期：如何追踪 pending→running→success/failed 全状态
60.工具优雅降级：依赖缺失时如何保证核心工具可用
61.异步 MCP 初始化在同步上下文中的事件循环桥接
62.跨进程配置同步：Gateway API 修改配置后 LangGraph Server 如何感知
63.条件工具加载：如何根据模型能力（vision）动态决定工具集
64.SubAgent 递归嵌套防护：如何防止子代理创建子代理的无限递归
65.长时工具反馈：索引大仓库等耗时操作如何向用户发送周期性进度更新
66.工具条件加载：如何根据环境变量动态决定是否注册某类工具集
67.搜索自动重试：文件模式无结果时如何自动升级为递归模式重试
68.MCP 多传输自动检测：如何根据 URL 前缀自动判断 stdio/ws/http 传输协议
69.LLM 工具选择 JSON 容错：LLM 返回非标准 JSON 时如何用正则提取有效内容
70.异步/同步桥接：同步 search() 接口如何安全包装异步 MCP 调用避免事件循环冲突
71.MCP 策略分级：如何通过 fast/deep/disabled 三级策略控制 MCP 执行深度与成本
72.Flow-as-Tool 动态 Schema：如何从可视化工作流的 input 节点自动生成工具的 JSON Schema
73.MCP 双角色共存：同一系统既作为 MCP Server 暴露工具又作为 MCP Client 消费外部工具
74.组件 output 选择性暴露：如何通过 tool_mode 标记控制哪些组件方法可被 Agent 调用
75.MCP 传输偏好缓存：首次连接确定可用传输后缓存偏好避免后续重试
76.工具模式 UI 消息静默：组件作为工具调用时如何抑制向 UI 发送的消息
77.MCP 进程级 OAuth 隔离：如何为每个项目启动独立代理进程隔离 OAuth 凭据
78.工具调用经验沉淀：如何从 tool_calls 历史中提取可复用的 when...then... 经验规则
79.工具消息多模态解析：tool 角色消息中混合 text/file/image/audio 内容的结构化提取
80.MCP 方法绑定：模块级函数如何通过猴子补丁绑定为类方法避免循环依赖
81.工具推荐：大工具集下如何为当前任务精准推荐最相关的工具子集
82.Docstring 即 Schema：如何从代码注释自动生成 LLM 可理解的工具描述
83.AST 动态注册：如何在不导入模块的情况下从源码文件注册工具
84.方法级暴露控制：类工具如何只暴露指定方法而隐藏内部实现
85.本地/远程 API 透明路由：同一工具如何根据部署环境自动切换后端实现
86.批量任务轮询与进度反馈：长时异步任务如何轮询状态并向 Agent 报告进度百分比
87.转换结果自动消费：工具如何在返回前自动下载、解压、读取结果而非只返回路径
88.MCP 工具全量替换同步：如何在 Server 上下线时高效重建工具列表而非增量 diff
89.跨 crate 循环依赖规避：工具 trait 定义在 agents crate 但 MCP 桥接在 mcp crate 时如何解耦
90.内部元数据透传与剥离：Agent runner 注入的路由信息如何对内置工具可见但对 MCP Server 不可见
91.工具参数校验：execute 前如何自动校验参数类型和约束
92.工具上下文注入：多渠道场景下如何动态设置工具的路由信息
93.子 Agent 工具隔离：如何通过独立注册表实现工具级权限控制
94.MCP OAuth token 自动刷新：如何在 token 过期时透明地重新交换而不中断工具调用
95.原生搜索检测：如何判断 LLM 供应商的原生搜索是否被调用（不走 tool_calls 机制）
96.搜索结果内嵌摘要：工具内部如何集成 LLM 摘要步骤压缩返回 token 量
97.节点拓扑声明：如何用 require_prior_kind + next_available_node 声明工作流 DAG 依赖
98.MCP Sampling 协议复用：工具节点如何通过 MCP session.create_message 调用 LLM 而非直接调 API
99.多模态媒体透传：工具如何将视频帧路径通过 metadata 透传给 MCP Host 处理 base64 编码
100.工具返回分层摘要：如何用 info_for_llm/info_for_user 分离 LLM 和用户看到的工具执行摘要
101.MCP 格式到 Skill 格式的自动转换：如何将 inputSchema JSON 转为 Markdown 文档格式
102.四格式统一解析：如何让 add_skill 接口同时接受目录/文件/字符串/字典输入
103.向量语义工具发现：如何通过 description 向量化让 Agent 语义搜索匹配工具
104.同步业务到异步 MCP 桥接：如何用 asyncio.to_thread 包装同步 RAG 调用
105.MCP Prompt 注入引导：如何通过 list_prompts 向 LLM 注入工具使用上下文
106.工具类型识别路由：多来源工具如何按优先级分类并路由到对应执行器
107.静态与动态注册表合并：编译时已知工具和运行时数据库工具如何统一管理
108.工具执行计费：SaaS 场景下如何在工具执行路径中集成按调用计费
109.工具 Schema 多路导出：如何为 Composio/DB 配置/SDK 三种来源统一导出工具定义
110.PTC 与 Agent loop 双入口：同一工具如何同时服务沙箱 API 调用和 Agent 内部调用
111.同名工具实现替换：如何根据模式为同一工具名选择不同实现（如 scroll 的 dom/hybrid 版本）
112.多模态工具返回：工具结果如何同时包含结构化数据和视觉截图供视觉模型消费
113.MCP 分页遍历：大量外部工具时如何通过 cursor 分页完整发现所有工具
114.工具描述动态生成：如何根据运行时变量（variables）动态修改工具的 inputSchema 描述
115.数据供应商路由：同一工具如何透明切换底层数据源而不影响 Agent 调用
116.多级配置覆盖：如何支持 category 默认配置和 tool 级精细覆盖的优先级体系
117.选择性降级：如何区分可降级异常（限流）和不可降级异常（参数错误）
118.RL 训练兼容的工具协议：如何让工具调用成为模型可生成的文本序列而非外挂 JSON
119.多模态工具返回注入：图片类工具结果如何编码后注入 VLM 对话上下文
120.批量样本并行工具执行：RL 训练 batch 中多条轨迹如何并行执行工具调用
121.格式奖励驱动工具学习：如何通过 reward shaping 让模型学会正确的工具调用格式
122.图片检索去重：如何防止 Agent 反复检索同一张图片陷入死循环
123.元工具设计：Planner 如何通过工具调用而非硬编码发现 Agent 能力
124.AgentCard 到 Prompt 转换：结构化能力声明如何转为 LLM 可理解的文本
125.A2A 协议集成：如何用标准化 Agent 协议替代自定义能力声明格式
126.Agent 类延迟解析：module:Class spec 如何在线程池中异步解析避免阻塞事件循环
127.两阶段懒加载：如何将工具发现与 schema 加载解耦，按需获取工具详情
128.返回格式分级压缩：如何为同一数据提供 Full/Minimal/Brief 多级视图控制 token 消耗
129.写操作精简返回：如何用 OperationResult 替代完整对象减少写操作的返回 token
130.自动压缩阈值：大结果集如何自动截断并提供 preview + hint 引导
131.Chemistry 工作流模板：如何用 Proto/Mol/Wisp 三相系统实现可复用的工具编排模板
132.Plugin Hook 上下文注入：如何在 SessionStart/PreCompact 时自动注入工具使用规范
133.工厂函数双注册联动：如何在一个循环中同步完成检测器注册和评分策略注册保证 1:1 对应
134.多格式解析器路由：如何用 fmt 字段路由到 gnu/json/eslint/cargo 等不同输出格式的解析器
135.插件契约校验：注册时如何立即校验 LangConfig 的 phases/detect_commands/fixers 等字段完整性
136.覆盖率降级记录：工具执行失败时如何结构化记录降级原因供扫描报告消费
137.处理器链参数注入：TOML prompt 中 Shell 输出替换与用户参数占位符的多阶段处理顺序
138.工具继承与隔离并存：SubAgent 如何同时支持继承父 Agent 工具和独立工具集两种模式
139.声明式命令的 Shell 安全：!{command} 语法在 prompt 中嵌入 Shell 执行的安全边界控制
140.MCP Server 级工具过滤：同一 Server 内如何按工具名白黑名单精细控制暴露范围
141.命令级工具粒度：ShellTool(ls -l) 格式如何限制工具的具体可执行命令
142.工具市场分发：在线市场命令/Agent/MCP 的一键安装与项目/全局作用域管理
143.工具调用记忆化：如何将工具调用历史结构化存储并支持向量检索
144.工具使用模式提取：如何用 LLM 从 Agent 日志中自动提取可复用的工具使用经验
145.工具统计滑动窗口：如何对最近 N 次调用计算成功率/耗时/成本等统计指标
146.记忆类型与工具类型的统一建模：tool 记忆如何复用通用记忆基础设施而非独立建表
147.功能级模型绑定：如何让不同业务功能独立选择供应商和模型而非全局共用
148.多 Key 负载均衡：多个 API Key 如何自动轮询并在故障时临时黑名单
149.Error-driven Discovery：如何从 API 错误响应中自动学习模型的 token 限制
150.模型能力自动分类：552+ 动态模型如何按名称模式自动归类为文本/图片/视频等能力
151.API 端点格式路由：同一供应商的不同模型如何自动选择 chat/images/video 端点
152.Store 版本迁移：多版本 schema 演进如何平滑迁移用户持久化数据
153.RL 训练兼容的工具掩码：如何区分模型采样 token 和工具注入 token 用于梯度计算
154.特殊 token 词表设计：工具调用边界 token 如何与 BPE 词表共存且不被合并
155.工具执行静默降级：calculator 返回 None 时如何不中断自回归生成流
156.流式 tool_call 增量解析：如何在 token 逐个到达时正确提取不完整的 JSON 工具调用
157.模型专用特殊 token 识别：如何处理不同模型的 tool_call 边界标记（特殊 token vs JSON vs XML）
158.tool_choice 到 structured output 的转换：如何将工具选择约束转为模型可执行的输出格式约束
159.MCP Schema 格式差异适配：MCP 生成的 JSON Schema 与推理引擎内部格式的递归转换
160.正则超时防护：tool_call 解析中如何防止恶意输入触发 ReDoS
161.悬挂工具调用修复：LangGraph 中断后如何为缺失 ToolMessage 的 tool_calls 注入占位响应
162.LLM 参数别名修复：如何自动纠正 LLM 常见的参数名拼写错误（q→query）
163.工具结果截断：搜索结果回注 LLM 时如何控制每条结果的字符长度
164.延迟导入隔离：工具适配器如何通过延迟 import 避免启动时加载所有依赖
各项目的解法46 solutions
横向对比
| 维度 | DeerFlow | MiroThinker | AI-Trader | AIRI | Agent-Orchestrator | Agent-Reach | Agent | AgentScope | agentic-rag-for-dummies | AgenticRAGForDummies | claude-mem | ClawWork | CoPaw | DeepAgents | DeepCode | DeepResearch | DeepTutor | FastCode | GPT-Researcher | Langflow | MemOS | MetaGPT | MinerU | Moltis | Nanobot | OpenClaw | Open | OpenManus | OpenStoryline | OpenViking | Refly | Stagehand | system-prompts-and-models-of-ai-tools | TradingAgents | VRAG | ValueCell | Beads | desloppify | iflow-cli | memU | moyin-creator | nanochat | seedance-2 | vLLM | vibe-blog |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 工具注册方式 | YAML config.yaml + resolve_variable 反射加载 module:variable | server_configs 列表 + StdioServerParameters | FastMCP @mcp.tool() 装饰器，Docstring 即 Schema | 数组声明式 actionsList + ActionRegistry 集中管理，支持 registerAction 动态注册 | PluginModule 接口 + PluginRegistry slot:name 键值注册 | Channel ABC 子类 + ALL_CHANNELS 手动实例化有序列表 | Channel 子类硬编码列表，12 个实例在 __init__.py 静态注册 | 三源统一：Python 函数 + MCP Client + Agent Skill 目录 | 装饰器动态注册，运行时调用 tool(name)(method) | — | 数组式声明 + handler 闭包，MCP SDK setRequestHandler 注册 | 继承式 _register_default_tools + super() 链式扩展 | AgentScope Toolkit.register_tool_function + register_agent_skill + register_mcp_client 三层注册 | StructuredTool.from_function 包装后端方法，Annotated 类型注解自动生成 JSON Schema | 双层架构：FastMCP @mcp.tool 装饰器 + nanobot Tool ABC 继承注册 | @register_tool 装饰器 + TOOL_MAP 字典映射，import 即注册 | 模块导入 + __init__.py 统一 re-export，无装饰器/注册表 | Tool ABC 抽象基类 + ToolRegistry 字典式动态注册，支持 register/unregister | match-case 工厂 + 延迟导入，15 种引擎各自独立模块 | 三层自动注册：FastMCP 装饰器 + Flow-as-Tool 数据库扫描 + ComponentToolkit 反射 | FastMCP @mcp.tool() 装饰器，Docstring 自动生成 Schema | @register_tool 装饰器 + inspect 自动提取 docstring/源码生成 schema | @mcp.tool() 装饰器 + Annotated[type, Field()] 自动 Schema | HashMap<String, ToolEntry> 双入口注册（register/register_mcp），ToolSource 枚举追踪来源 | Tool ABC 基类 + ToolRegistry 字典注册表，name 索引 O(1) 查找 | — | 三层组装：Pydantic-as-Tool + @tool 装饰器 + MCP StructuredTool | — | 装饰器 @NODE_REGISTRY.register() + pkgutil 包扫描自动发现 | FastMCP @mcp.tool() 装饰器，Docstring 即 Schema | 六类 ToolType 枚举 + 双层注册表（静态 inventory + DB toolset_inventory） | 工厂函数 + AI SDK tool() 包装，每个工具独立文件 | — | LangChain @tool 装饰器 + Annotated 类型注解自动生成 Schema | Prompt 内嵌 XML 标签定义，无独立注册表 | Agno 框架函数式注册，docstring 自动生成 schema | FastMCP @mcp.tool 装饰器 + _TOOL_CATALOG 静态字典双层注册 | DetectorMeta frozen dataclass + register_detector() 运行时注册，支持观察者回调 | 四层注册：内置 coreTools + MCP Server 发现 + TOML/Markdown 文件 + SubAgent 继承 | StructuredTool.from_function + Pydantic args_schema 自动生成 JSON Schema | 8 个 AIFeature 枚举 + featureBindings 映射表，Zustand persist 持久化 | 无注册表，特殊 token 硬编码在词表和 Engine 中 | — | ToolParserManager 双模式注册表：Lazy dict 存 (module_path, class_name)，首次 get 时 importlib 导入并缓存 | YAML 声明 + importlib 反射加载（resolve_variable 模式） |
| 工具分组/权限 | group 字段分组 + subagent denylist 隔离 | tool_blacklist 集合禁用特定工具 | 按市场类型分组（Trade/Crypto/Price/Search/Math），无权限控制 | — | 7 个 PluginSlot 类型约束分组，配置级选择 | Tier 三级分组（0=零配置/1=免费Key/2=复杂配置） | 三级 Tier 分层（0=零配置/1=需Key/2=需设置），无运行时权限控制 | ToolGroup 分组 + active 标志 + reset_equipped_tools 元工具动态激活 | 无分组，所有工具平等暴露给 LLM | — | 无分组，5 个工具平铺；CORS 限制 localhost 访问 | 经济工具 4 个 + 文件工具 2 个，条件加载 ReadArtifact | 无细粒度权限，内置工具全量注册，技能通过 enable/disable 控制 | interrupt_on 字典配置 6 个危险工具的 HITL 审批 | MCPToolDefinitions 按工具集分组 + 子 Agent 独立注册表隔离 | 无分组/权限机制，所有工具对 Agent 全量可见 | YAML valid_tools 白名单 + Agent 级别工具子集分配 | 子 Agent 独立 ToolRegistry，裁剪掉 message/spawn/cron 工具 | 无显式分组，通过 mcp_strategy(fast/deep/disabled) 控制执行深度 | project_id 过滤 + mcp_enabled 标记控制 Flow 暴露 | 无分组，16 个工具平铺注册，user_id 参数级权限 | tags 分组 + include_functions 方法级过滤 + 'Class:method' 语法 | 无分组无权限，仅 2 个工具全量暴露 | 6 层 Glob 策略合并（Global→Provider→Agent→Group→Sender→Sandbox），deny 始终累积 | 代码级隔离：主 Agent 9 工具，子 Agent 7 工具（无 message/spawn/cron） | — | supervisor 和 researcher 分别组装不同工具集 | — | TOML available_nodes 白名单过滤，无运行时权限控制 | 无细粒度权限，按 MCP Server 粒度隔离 | AgentBaseToolset 按 toolsetKey 分组，builtIn/nonBuiltIn 二分类，OAuth 需用户授权 | 双模式 filterTools（dom/hybrid）+ excludeTools 运行时排除 | — | 4 类 Analyst 各持独立工具子集，通过 bind_tools 隔离 | 无分组无权限，三工具等价暴露给模型 | 每个 Agent 独立 tools 列表，无跨 Agent 共享 | @require_context 装饰器区分读/写操作权限 | dimension 字段分组 + action_type 四级分类（auto_fix/refactor/reorganize/manual_fix） | 白黑名单双重过滤 + SubAgent isInheritTools 继承机制 + 命令级粒度 ShellTool(ls) | — | — | 无分组，仅 calculator 单一工具，无权限控制 | — | allowed_tools 白名单过滤 + annotations.include_in_prompt 控制 schema 可见性 | search/crawl/knowledge 三组 + 环境变量黑名单 |
| MCP 协议支持 | stdio/sse/http 三传输，langchain-mcp-adapters | MCP 原生，7 种 StdioServerParameters 工具服务器 | 原生 FastMCP + streamable-http 传输，MultiServerMCPClient 统一接入 | Rust rmcp crate 原生 MCP 客户端，stdio 传输，Tauri IPC 暴露 | 无 MCP，插件通过 npm 包 + TypeScript 接口集成 | mcporter 桥接多个 MCP Server + 自身暴露 get_status MCP tool | mcporter CLI 桥接多个 MCP 服务 + 自身可作为 MCP Server 暴露 | 原生支持 stdio/HTTP 双传输 + 有状态/无状态双模式 | — | — | 原生 MCP SDK，StdioServerTransport，薄包装层委托 Worker HTTP | 通过 nanobot 的 mcp_servers 配置透传，ClawWork 层不直接处理 | StdIOStatefulClient，config.json 声明式配置，支持热重载替换 | 无原生 MCP，通过 BackendProtocol 抽象实现类似效果 | 核心层 FastMCP Server，支持 stdio/SSE 通信 | NestBrowse 通过 SSE 长连接集成 MCP 浏览器工具 | 不支持，工具接口为项目内部 Python 函数 | FastMCP 装饰器暴露 6 个高层工具，支持 stdio/SSE 双传输 | langchain-mcp-adapters 桥接，stdio/ws/http 三传输自动检测 | 双角色：FastMCP Server 暴露 Flow + MCP Client 消费外部工具 | FastMCP 框架，支持 stdio/http/sse 三种传输 | 不支持 MCP，使用自定义 schema 格式（description+signature+parameters） | FastMCP 原生支持 stdio/SSE/streamable-http 三模式 | McpToolBridge 适配器 + mcp__server__tool 前缀命名 + 内部元数据自动剥离 | MCPToolWrapper 桥接，支持 stdio + HTTP 双传输，懒加载连接 | — | langchain-mcp-adapters + OAuth token exchange + 认证包裹器 | — | FastMCP streamable-http 传输，server.tool() 注册，MCP Sampling 协议复用 LLM | 双传输（streamable-http + stdio），stateless_http 模式 | MultiServerMCPClient 连接用户自定义 MCP 服务器，配置存 DB 并加密敏感字段 | 完整支持：分页 listTools + callTool 代理 + stdio/HTTP 双传输 | — | 无，纯 LangChain ToolNode 体系 | 不支持，使用自定义 XML 标签协议 | 未实现，使用 A2A 协议 AgentCard 替代 | FastMCP 框架原生 stdio 传输，完整 MCP 1.0 实现 | — | stdio/SSE/HTTP 三传输 + includeTools/excludeTools 每 Server 独立过滤 + 同名自动前缀 | README 提及 MCP server 支持，通过 MemoryService 桥接 | — | 不支持，完全自定义的特殊 token 协议 | — | MCPToolServer 通过 SSE 连接多个 MCP Server，trim_schema 递归适配 JSON Schema | 不支持 MCP，纯 Python 函数注册 |
| 热更新/缓存 | mtime 文件修改时间检测，跨进程自动刷新 | 启动时加载，运行时固定 | 重启单个 MCP Server 即可更新，无工具缓存 | — | 不支持热更新，启动时一次性加载并缓存 Promise | 无热更新，静态注册表，重启生效 | 后端可热替换（换 Channel 文件即可），无运行时热更新 | — | — | — | 无热更新；Chroma 可用性运行时检测，策略动态切换 | — | MCPClientManager.replace_client 锁外连接+锁内交换，零停机热替换 | — | 环境变量条件加载，注释即配置切换工具集 | 静态注册，无运行时热更新能力 | Provider 运行时可切换（env/config），无工具热加载 | — | 实例级 _all_tools_cache，不跨会话持久化 | MCPSessionManager 会话池复用 + 传输偏好缓存 | — | register_tools_from_path() 支持运行时从文件路径动态注册，AST 解析无需导入 | 无热更新，工具在启动时静态注册 | sync_mcp_tools 全量替换策略，unregister_mcp 后重新注册所有活跃 bridges | 支持 register/unregister 动态增删，无事件通知机制 | — | — | — | — | Skill 向量索引支持动态 add_skill，无热重载 | ToolFactory 10min TTL + ToolInventoryService 5min TTL，SingleFlightCache 防并发穿透 | 无热更新，MCP 工具在 Agent 初始化时一次性发现 | — | 无热更新，data_cache_dir 缓存供应商数据 | — | — | 连接池 _connection_pool + lru_cache 路径规范化 | — | TOML/Markdown 文件修改后需重启 CLI 加载，/mcp refresh 刷新 MCP 工具列表 | — | Error-driven Discovery 从 400 错误自动学习 token 限制并持久化缓存 | — | — | — | reload() 清空重载 + 全局单例懒初始化 |
| 超时保护 | — | @with_timeout(1200) 20 分钟硬超时 | LLM 调用 timeout=30s，MCP 服务无显式超时 | — | 无插件级超时，由各插件自行实现（如 tmux execFile timeout） | subprocess.run timeout=10-15s 硬超时 | subprocess timeout 10-15s，无重试机制 | — | — | — | Worker health check 超时检测；ppid 心跳防孤儿进程 | — | MCP 连接 60s 超时，shell 工具可配置超时+两阶段终止（terminate→kill） | execute_accepts_timeout lru_cache 签名检查 + max_execute_timeout 上限 | ExecTool 60s + MCP execute_bash 30s 双层超时 | 多层超时：LLM 600s、Visit 900s、Python 50s、总体 150min | code_executor subprocess.timeout + 可配置 code_timeout | ExecTool 60s 超时 + _execute_tool_with_feedback 1200s 最大超时 + 周期性状态反馈 | search() 同步桥接 300s 超时，cleanup 5s 超时 | 30s 连接超时 + 30s 工具执行超时 + 2 次重试 | — | 无内置超时，_run_commands() 遇异常 break 停止后续命令 | 轮询 180 次×10s 上限，无单次调用超时 | ExecTool 内置 30s 默认超时，上限 1800s，tokio::time::timeout 实现 | ExecTool 60s + MCP 工具 30s，超时后 kill/cancel | — | 摘要 60 秒 asyncio.wait_for + 工具执行 execute_tool_safely | — | — | add_resource 有 300s wait_processed 超时 | AdapterFactory 默认 30s 超时 + maxRetries=3 + retryDelay=1000ms | MCP 连接 ping 健康检查，无工具级超时 | — | 无显式超时，依赖供应商 SDK 自身超时 | max_steps 倒计时强制终止 + 强制 answer 提示 | — | asyncio.wait_for 5s git 检测超时 + 30s daemon socket 超时 | — | MCP Server 级 timeout + Shell 全局 shellTimeout:120000ms + Hook 独立 timeout | — | — | SIGALRM 3 秒超时 + 空 builtins 沙箱 | — | regex 库 timeout 参数防 ReDoS，环境变量 VLLM_TOOL_PARSE_REGEX_TIMEOUT_SECONDS 控制 | threading.Thread + join(timeout) 同步超时 |
| 生命周期追踪 | — | — | MCPServiceManager 5 秒轮询进程存活 + 端口可达检查 | TaskExecutor EventEmitter 发射 action:started/completed/failed | LifecycleManager 轮询 Agent.getActivityState 追踪 6 态 | 四态健康状态 ok/warn/off/error，doctor 命令一键检查 | — | — | — | — | StrategySearchResult.usedChroma/fellBack 标记策略路径 | start_task/end_task 包装每次消息处理，JSONL 持久化 | — | — | log_operation 记录操作历史 + get_operation_history 查询 | — | ToolCallRecord dataclass 6 状态机 + JSON 持久化 | IterativeAgent.tool_call_history 记录每轮工具调用 + 去重过滤 | MCPStreamer 三阶段 WebSocket 推送 + add_costs 成本回调 | 引用计数 + 空闲超时清理 + 周期性健康检查 | ToolTrajectoryMemory 类型 + when...then... 经验提取 | 无显式状态机，_run_commands() 顺序执行并拼接输出 | — | — | 无显式状态追踪，错误返回字符串由 LLM 自行处理 | — | — | — | NodeSummary 5 级日志 + ArtifactStore 持久化执行结果 | ToolPart 四态（pending/running/completed/error） | ToolExecutionService 生成 callId（callType:uuid），持久化 executing→success/failed 状态 | recordAgentReplayStep 录制每步操作，支持确定性回放 | — | — | active_mask 追踪每条轨迹的 done 状态 | STARTED/COMPLETED 事件对 + ToolCallPayload 三元组 | — | — | 9 类 Hook 覆盖 PreToolUse→PostToolUse→SessionStart→Stop 全生命周期 | ToolCallResult 记录 success/time_cost/token_cost/score + 滑动窗口统计 | 9 版本 migrate 函数处理 v1 单Key→v9 多供应商多绑定的 schema 演进 | — | — | — | execute_tool 返回 success/error/duration_ms 三元组 |
| 参数校验 | — | — | 工具内多层校验：类型转换 → 正数检查 → 市场规则（整手/T+1） | Zod safeParse 前置校验，详细 issue 路径错误信息 | TypeScript 编译期类型检查 + satisfies 约束 | 无显式参数校验，依赖上游工具自身校验 | — | — | — | — | additionalProperties=true 宽松 schema + Worker 端归一化校验 | 工具内 execute() 业务级校验，返回结构化 JSON 错误 | — | validate_path 防遍历 + Literal 错误码标准化 | Tool.validate_params 递归 JSON Schema 校验 | — | — | Tool._validate 递归 JSON Schema 校验，支持嵌套 object/array/enum | — | Pydantic model_validate + camelCase 自动转 snake_case | 依赖 Python 类型注解，无额外业务校验层 | ToolSchema Pydantic 软校验（失败不阻断），无运行时参数类型检查 | Pydantic Field + 类型注解自动校验 | JSON Schema 定义参数（parameters_schema 方法），execute 内手动校验必填字段 | Tool ABC 内置 JSON Schema 递归校验，execute 前自动调用 | — | — | — | Pydantic BaseModel input_schema + _validate_schema 方法 | SkillLoader 校验 name/description 必填 | LangChain StructuredTool 的 Zod schema 自动校验，ToolDefinitionService 用 zodToJsonSchema 导出 | Zod schema 编译时校验 + jsonSchemaToZod 运行时转换 | — | — | bbox 做 JSON 解析 + 长度/非负校验，search 无校验 | — | — | normalize_tool_specs 对 label/cmd/fmt/id/tier/fix_cmd 逐字段校验 + validate_lang_contract 注册时契约校验 | Zod schema 验证 TOML 配置 + 处理器链三阶段参数注入 | Pydantic Field + description 自动校验，min_relevance_score 范围过滤 | — | 字符白名单 + 危险模式黑名单，无 JSON Schema 校验 | — | tool_choice 四模式校验（none/auto/required/named），Pydantic model_validator 链式验证 | 参数别名自动修复（_PARAM_ALIASES 映射表） |
| 安全防护 | — | — | fcntl 文件锁序列化仓位更新，无 SSRF/注入防护 | vm.createContext 沙箱 + deepFreeze 冻结 + 750ms 超时 + 5 action/轮限制 | tmux sessionId 正则校验，插件加载 try-catch 隔离 | config.yaml chmod 600 + 敏感值 mask + Cookie 域名隔离 | 凭据文件权限 600 + doctor 检查权限过宽 + Cookie 安全提醒 | — | 结构化错误标记（NO_RELEVANT_CHUNKS）而非异常 | — | CORS localhost-only + requireLocalhost 中间件 + console.log 拦截 | CreateArtifactTool 的 os.path.basename 防路径穿越 | — | 路径遍历检测 + Windows 路径拒绝 + allowed_prefixes 白名单 | deny_patterns 正则黑名单 + validate_path 路径遍历检测 + workspace 限制 | — | — | repo_root 路径边界 + ExecTool deny_patterns 命令黑名单 + 路径遍历检测 | — | RFC 7230 Header 校验 + emoji/Unicode 工具名清理 + SSL 可配置 | — | exclusive_tool_commands 限制同类命令只执行首个，special_tool_commands 特殊处理 | — | ApprovalManager 危险命令确认 + SandboxRouter 沙箱路由 + deny-wins 策略 | ExecTool 9 条正则黑名单 + 路径沙箱 + workspace 限制 | — | 工具名冲突检测 + MCP 白名单过滤 + 并发上限控制 | — | — | — | EncryptionService 加密 authData/headers/env，OAuth 凭据不明文存储 | SafetyConfirmationHandler 回调拦截 CUA 模式危险操作 | — | — | 无沙箱，bbox 仅做坐标范围校验 | — | — | — | excludeTools 黑名单优先 + trust 信任模式 + PreToolUse Hook 阻断 + 命令级限制警告非安全机制 | — | — | 三层防御：字符白名单 + 危险模式黑名单 + 空 builtins | — | — | $ENV 引用密钥不硬编码 + 工具黑名单 |
| Schema 生成方式 | @tool decorator + parse_docstring=True 自动提取 | — | FastMCP 从 Python 类型注解 + docstring 自动生成 | Zod z.object() + .describe()，校验与 LLM 提示一体化 | TypeScript 接口即 Schema，无运行时生成 | 无 Function Calling Schema，通过 SKILL.md 知识注入教 Agent 调用 | 无 Schema — 通过 SKILL.md 文档注入调用知识替代 Function Calling | Docstring 自动解析 + Pydantic 动态扩展 + MCP inputSchema 转换 | 装饰器自动从函数签名和 docstring 生成 | — | — | Property-as-Schema：@property parameters 返回 JSON Schema dict | AgentScope 从函数 docstring 自动生成 JSON Schema | Annotated 类型注解 + StructuredTool 自动推导 | — | 类属性声明 + system prompt 内嵌 <tools> 标签 | — | Tool.to_schema() 手动声明 JSON Schema properties | — | json_schema_from_flow 从 Graph input 节点动态生成 | Python 类型注解 + Docstring Args 自动推导 | 双路径：运行时 inspect 反射 + AST 静态解析，docstring 即 schema | Docstring 即 Schema，FastMCP 从类型注解自动生成 | 手写 serde_json::json! 宏内联定义，list_schemas 附加 source 元数据 | — | — | — | — | Pydantic BaseModel → Annotated[type, FieldInfo] → inspect.Signature 动态构建 | 函数签名+Docstring 自动生成 inputSchema | 三路导出：Composio API 获取、DB config 解析、SDK Zod schema 转 JSON Schema | 手写 Zod（内置工具）+ JSON Schema→Zod 自动转换（MCP 工具） | — | Docstring 即 Schema：@tool + Annotated 自动转 JSON Schema | 无 Schema，正则 r'<(search|answer|bbox)>' 硬编码 | Docstring 即 Schema，Agno 自动解析函数签名 | 手写 _TOOL_DETAILS 字典，非自动生成 | ToolSpec TypedDict 契约 + normalize_tool_specs() 严格校验（类型/范围/白名单） | TOML description+prompt 声明式 + MCP Server 自动发现 inputSchema | Pydantic BaseModel 自动导出 JSON Schema（SaveRecallInput/SearchRecallInput） | — | — | — | adjust_request 将 tool_choice + tools 转为 StructuredOutputsParams JSON Schema 约束 | ToolDefinition.to_openai_schema() 手动定义 |
| 数据供应商路由 | — | — | 搜索工具可切换 Jina/AlphaVantage，通过 service_configs 配置 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | get_retrievers() 四级优先级：headers > config.retrievers > config.retriever > Tavily 默认 | — | — | — | — | — | — | — | SearchAPI 枚举路由 Tavily/OpenAI/Anthropic 三种搜索供应商 | — | — | Recipe 统一 RAG 管线，search 支持 target_uri 范围限定 | — | — | — | VENDOR_METHODS 映射表 + category/tool 两级配置覆盖 | — | web_search 内部按环境变量切换 Google/Perplexity | — | — | — | — | Feature Router 功能级路由，每个功能独立绑定 provider:model | — | — | — | 5 搜索引擎并列，由 ResearcherAgent 选择 |
| 供应商降级策略 | — | — | 无自动降级，搜索工具注释切换（Jina↔AlphaVantage） | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | LLM 选择失败降级关键词匹配，工具执行失败 continue 跳过 | — | — | — | — | — | — | — | MCP 连接失败返回空列表，摘要超时返回原始内容 | — | — | — | — | — | — | 仅 RateLimitError 触发 fallback，其他异常直接抛出 | — | Google 不可用时自动 fallback 到 Perplexity OpenRouter | — | — | — | — | ApiKeyManager 90s 黑名单 + round-robin 轮换，429/401/503 自动降级 | — | — | — | is_available() 过滤不可用工具，无自动降级链 |
| 工具内业务校验 | — | — | A 股 100 股整手 + T+1 卖出限制 + 余额/持仓充足性检查 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | BaseNode.load_inputs_from_client 递归处理 base64/dict/list 多类型参数 | — | — | — | — | — | bbox 坐标非负检查 + 图片去重 repeated_nums | — | — | make_generic_fixer 修复后重新 detect 计算 fixed_count，验证修复效果 | — | add_tool_call 校验 memory_type=='tool'，ensure_hash 保证去重 | — | — | — | — | — |
| 工具上下文注入 | runtime.state 传递 sandbox/thread_data/thread_id | — | 通过 RUNTIME_ENV_PATH JSON 文件跨进程共享 TODAY_DATE/SIGNATURE | 柯里化 perform(mineflayer) 延迟绑定 + sandbox 全局变量注入 | — | Config 双源读取（YAML 文件优先 + 环境变量 fallback） | SKILL.md 安装到 Agent skills 目录，Agent 启动时自动加载 | preset_kwargs 预设参数 + extended_model 动态扩展 | 通过 context_summary 注入已执行工具列表 | — | — | 共享 ClawWorkState 实例，工具通过 self._state 访问全局上下文 | create_memory_search_tool 闭包绑定 memory_manager 实例 | FILESYSTEM_SYSTEM_PROMPT + EXECUTION_SYSTEM_PROMPT 动态追加到 system message | — | NestBrowse 通过 kwargs 注入 MCP client/lock/tokenizer | — | set_context(channel, chat_id) 动态设置多渠道路由信息 | MCPRetriever 从 researcher 实例提取 mcp_configs 和 cfg | component_cache 共享 MCPSessionManager 跨组件复用 | 闭包捕获 self.mos_core 实例，无动态上下文 | — | — | Agent runner 注入 _session_key/_conn_id 等路由信息，MCP 桥接时自动剥离 | — | — | — | — | create_tool_wrapper 从 HTTP Header 提取 session_id 构造 NodeState | — | BaseToolParams 注入 reflyService/engine/isGlobalToolset，Regular 工具额外注入 context | provider 参数注入坐标归一化逻辑，variables 注入动态描述 | — | route_to_vendor 根据 config 动态选择供应商实现 | — | AgentCard JSON 声明 skills/tags/examples 注入 Planner 上下文 | ContextVar + with_workspace 装饰器实现请求级 workspace 路由 | — | — | — | — | — | — | — | BaseSearchTool.configure(extra) 从 ToolConfig 注入 |
| 依赖注入 | ToolRuntime[ContextT, ThreadState] 注入沙箱/线程状态 | — | — | 高阶函数柯里化 perform(deps) => (...args) => result | importFn 参数注入解决 pnpm 严格模块解析 | — | — | — | 工厂模式 + 闭包，构造函数注入依赖 | — | — | ClawWorkState dataclass 构造函数注入，替代全局字典 | — | BackendFactory 工厂函数延迟创建后端实例 | — | — | — | — | — | — | — | — | 全局单例 MinerUClient，singleton_func 装饰器 | — | — | — | — | — | make_llm(mcp_ctx) 工厂函数注入 LLM 客户端到 NodeState | — | NestJS Module/Injectable 全链路 DI，ToolModule 统一组织 15+ 服务 | V3 实例通过工厂函数参数注入，支持多 session 并行 | — | config dict 通过 set_config() 注入，工具运行时读取 get_config() | — | — | — | — | — | MemULangGraphTools 构造函数注入 MemoryService 实例 | — | — | — | — | — |
| 工具集动态组合 | groups 过滤 + include_mcp 开关 + subagent_enabled 条件 | — | — | 每次 evaluate 重新 installActionTools，action 用 configurable:true 可更新 | — | — | 不支持 — 12 个渠道始终全部注册，通过 tier 分层展示可用性 | — | — | — | — | enable_file_reading 配置控制 ReadArtifactTool 是否注册 | builtin→customized→active 三级目录同步，customized 覆盖 builtin 同名技能 | wrap_model_call 运行时检测后端能力动态过滤 execute 工具 | — | — | — | FASTCODE_API_URL 环境变量条件加载 FastCode 工具集 | — | tool_mode 标记 + flow_mode_inputs 按场景选择性暴露 | — | — | — | 4 种过滤克隆方法（by_prefix/by_mcp/by_name/by_predicate），Arc 共享零拷贝 | — | — | get_all_tools 按 SearchAPI 枚举 + MCPConfig 动态组装 | — | — | Skill 按 tags 分类，支持语义搜索筛选 | instantiateToolsets 按 GenericToolset[] 选择性激活，支持 selectedTools 过滤 | mode 过滤 + env 条件注册 + excludeTools 三层组合 | — | selected_analysts 参数控制激活哪些 Analyst 及其工具子集 | 固定三工具集，不支持动态增减 | 每个 Agent 构造时静态组装，GridAgent 用 pipeline 替代工具 | Chemistry Proto/Mol/Wisp 三相模板系统支持工作流动态编排 | generic_lang() 按 treesitter 可用性动态组装 phases（浅层→标准→完整） | coreTools 白名单 + excludeTools 黑名单 + allowMCPServers 三层组合 | tools() 方法返回固定 2 工具集（save_memory + search_memory） | resolveImageApiFormat/resolveVideoApiFormat 按模型元数据动态选择 API 端点 | — | — | — | get_tools_by_group 按组获取，无场景级动态组合 |
| 结果摘要 | — | — | — | action 返回结构化遥测（startPos/endPos/movedDistance/elapsedMs） | Agent 插件 getSessionInfo 从 JSONL 提取 summary | — | — | — | — | — | Markdown 表格索引（~50-100 token/条），3-Layer 渐进披露 | 成本摘要行自动附加到响应尾部（Cost/Balance/Status） | — | token 阈值驱逐到文件系统，head+tail 预览替换原始结果 | read_code_mem 从 implement_code_summary.md 提取文件摘要 | Visit 用独立 LLM 提取 evidence/summary，渐进截断重试 | LLM 驱动的工具结果摘要中间层，截断 2000 字符后摘要 | search_codebase 每文件最多 20 匹配 + 总结果 max_results 截断 | 四格式归一化为 {title,href,body}，含 LLM 自身分析作为额外结果 | — | — | 工具输出直接拼接为字符串，无分层摘要机制 | 自动下载 ZIP 解压并读取 Markdown 全文返回 | — | ExecTool 截断 10000 字符，WebFetch 截断 50000 字符 | — | tavily_search 内嵌 LLM 摘要管道，60 秒超时保护 | — | — | query 工具返回 answer+sources+timings 格式化文本 | ToolCallResult.summary 字段提供人类可读摘要，与 data 字段分离 | toModelOutput 钩子：hybrid 模式返回截图+JSON，dom 模式返回纯 JSON | — | — | 无摘要，搜索结果直接作为图片注入上下文 | — | 三级压缩 Full→Minimal→Brief + CompactedResult 自动截断 | — | summarizeToolOutput 按工具类型配置 tokenBudget 摘要压缩 | — | — | 无摘要，calculator 结果直接编码为 token 注入 | — | — | SearchResponse 统一结构 + JSON 截断至 200 字符 |
| JS-REPL 代码即协议 | — | — | — | LLM 输出 JS 代码在 vm 沙箱执行，支持条件分支和多 action 组合 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 模块能力声明 | — | — | — | Plugin Protocol ModuleCapability + contribute:capability:offer 事件 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 工具推荐策略 | — | — | — | — | YAML 配置 defaults + 项目级覆盖，三层优先级 | can_handle(url) 线性扫描 + WebChannel 兜底路由 | URL 路由分发 — can_handle(url) 按域名自动匹配目标渠道 | — | — | — | — | — | — | — | — | 无动态推荐，全量工具写入 system prompt | — | — | strategic LLM 打分选择 + 13 关键词模式匹配降级 | — | — | 两阶段：BM25/TypeMatch 召回 20 → LLM 精排 Top-5 | — | — | — | — | — | — | — | 向量语义搜索 find() 匹配最相关技能 | shouldExposeToolset 过滤 deprecated/internal/未配置 OAuth 工具，mentionList 只展示可用工具 | — | — | — | — | Planner 元工具 + LLM 语义匹配选择 Agent | discover_tools 返回全量目录，由 LLM 自行选择 | — | SubAgent whenToUse 描述 + $agent-type 快捷调用 + /agents online 市场浏览 | — | — | — | — | — | 无推荐，按组批量获取 + is_available 过滤 |
| 双层API架构 | — | — | — | — | 无双层，统一 PluginModule 接口 | — | — | — | — | — | MCP→Worker HTTP→SearchManager→Orchestrator 四层分离 | — | — | — | — | Inference 同步 + NestBrowse 异步，两套独立工具系统 | — | Nanobot 原子工具（read_file/exec）+ FastCode HTTP 工具（code_qa）双层 | MCPRetriever 统一 search() 接口，内部四模块分工协作 | SSE + Streamable HTTP 双传输端点并存 | MCP 直连 MOS 实例 + REST API 通过 MOSProduct 包装 | — | parse_documents 统一入口，内部分流到本地/远程 API | — | — | — | — | — | — | OpenViking MCP（FastMCP 高层）+ AGFS MCP（Server 低层） | Agent loop 用 instantiateToolsets，PTC 用 executeTool API，同一工具两种调用路径 | 内置工具直接调用 V3 方法，MCP 工具通过 callTool 代理 | — | — | — | Agent 层业务工具 + Planner 层元工具双层分离 | BdClientBase ABC + CLI/Daemon 双实现，工厂函数自动选择 | — | — | — | — | — | — | ToolParser（解析层）与 ToolServer（执行层）正交分离，互不依赖 | ToolRegistry（配置驱动）+ BlogToolManager（函数注册）双层独立 |
| 槽位架构 | — | — | — | — | 8 槽位（7 可插拔 + 1 核心），17 个内置实现 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| URL 自动路由 | — | — | — | — | — | urlparse 域名匹配 + 有序列表优先级 + WebChannel 兜底 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 后端工具健康检测 | — | — | — | — | — | 三层递进：CLI 存在 → 认证状态 → 实际调用测试 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | ping + 指数退避重连（0.1s→0.2s→0.4s，最多 3 次） | — | — | — | — | — | — | — | — |
| 凭据安全管理 | — | — | — | — | — | YAML 文件 + chmod 600 + 浏览器 Cookie 自动提取 + 敏感值 mask | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | LangGraph Store 存储 MCP token，自动过期清理 | — | — | — | EncryptionService 对称加密 + DB 存储，运行时解密注入工具实例 | — | — | — | — | — | — | — | — | — | 多 Key 逗号分隔存储，maskApiKey 前8后4掩码显示 | — | — | — | — |
| 流式执行统一 | — | — | — | — | — | — | — | 三种适配器包装为统一 AsyncGenerator[ToolResponse] | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 中间件管道 | — | — | — | — | — | — | — | 洋葱式中间件 + @_apply_middlewares 装饰器 + reversed 反向包装 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 工具优雅降级 | — | — | — | — | — | — | — | FunctionNotFoundError / FunctionInactiveError 结构化错误 | 返回错误标记字符串，不中断执行流 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | default_process 提供节点跳过时的降级路径，mode!=auto 触发 | — | — | — | — | — | — | — | — | ToolRunResult 五级状态 + error_kind 分类 + coverage_warnings 结构化降级记录 | — | — | — | — | — | — | — |
| 状态持久化 | — | — | — | — | — | — | — | state_dict / load_state_dict 保存工具组激活状态 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 后处理钩子 | — | — | — | — | — | — | — | postprocess_func 支持同步/异步后处理函数 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| Agent Skill 系统 | — | — | — | — | — | — | — | YAML Front Matter 元数据 + SKILL.md 文档驱动 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 工具调用生命周期 | — | — | — | — | — | — | — | @trace_toolkit 装饰器 + 中间件前后置处理 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| MCP 内容转换 | — | — | — | — | — | — | — | _convert_mcp_content_to_as_blocks 多模态内容适配 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 重名冲突策略 | — | — | — | — | — | — | — | raise / override / skip / rename 四种策略 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 工具结果格式化 | — | — | — | — | — | — | — | ToolResponse 统一格式 + content/metadata 分离 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 工具调用去重 | — | — | — | — | — | — | — | — | retrieval_keys 集合追踪 parent::id 和 search::query | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 结果格式化 | — | — | — | — | — | — | — | — | 结构化字符串（Parent ID/File Name/Content） | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 闭包工具注入 | — | — | — | — | — | — | — | — | 装饰器捕获实例方法的 self，形成闭包 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 每查询实例隔离 | — | — | — | — | — | — | — | — | 每次查询创建独立 ToolFactory 实例 | — | — | — | query_handler 每次创建新 CoPawAgent，MCP 客户端共享但 Toolkit 独立 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 强制工具调用 | — | — | — | — | — | — | — | — | 首次查询注入 MUST CALL 提示强制搜索 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 伪工具引导 | — | — | — | — | — | — | — | — | — | — | __IMPORTANT 伪工具在 tools/list 时传递 workflow 规范 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | ResearchComplete 空 BaseModel 作为完成信号 | — | — | AGFS MCP 用 list_prompts 注入架构文档引导 LLM | — | — | — | — | — | Planner prompt 中 <tools> 标签描述元工具使用规范 | MCP instructions + bd prime hook 双重引导 Agent 使用规范 | — | — | — | — | — | — | — | — |
| 计费集成 | — | — | — | — | — | — | — | — | — | — | — | TrackedProvider 透明包装 + EconomicTracker per-task 成本记录 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 全局工具集执行后自动扣费，支持 per-tool 和 tier-based 两种计费模型 | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 工具条件加载 | supports_vision 判断加载 view_image_tool | — | — | — | — | — | — | — | — | — | — | 基于 ClawWorkConfig.enable_file_reading 布尔值控制 | memory_search 根据 ENABLE_MEMORY_MANAGER 环境变量条件注册 | — | — | 按 Agent 变体选择工具集：Inference 5 工具 / NestBrowse 4 工具 | — | — | try/except ImportError 可选依赖，HAS_MCP_ADAPTERS 标志位 | — | — | — | 无条件加载，所有工具始终注册 | — | — | — | SearchAPI.NONE 跳过搜索，MCPConfig 为空跳过 MCP | — | TOML available_node_pkgs 控制扫描包，available_nodes 控制注册节点 | — | — | — | — | — | — | — | BEADS_USE_DAEMON 环境变量控制 daemon/CLI 客户端选择 | 三层插件发现：plugin_*.py → 包目录 → .desloppify/plugins/，失败隔离不阻塞 | — | — | classifyModelByName 正则自动分类 552+ 模型能力 | — | — | DemoToolServer 按环境变量（EXA_API_KEY）和依赖可用性动态启用/禁用工具 | — |
| 类变异技巧 | — | — | — | — | — | — | — | — | — | — | — | 运行时 __class__ 替换升级 LiteLLMProvider 为成本捕获子类 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| MCP格式转换 | — | — | — | — | — | — | — | — | — | — | — | — | SKILL.md YAML Front Matter 声明 name/description，Toolkit 自动转换 | — | — | browser.py 工具类将 Agent 参数转为 MCP call_tool 参数 | — | — | — | MCPStructuredTool 子类重写 run/arun 自动转换参数格式 | — | — | — | — | — | — | — | — | — | mcp_to_skill() 自动将 inputSchema 转为 SKILL.md | — | — | — | — | — | — | Claude Plugin skills/commands/agents 三类扩展点与 MCP 工具并行 | — | MCP Server 暴露工具自动 strip schema properties 保持兼容 | — | — | — | — | trim_schema 递归处理 anyOf→type[]、移除 title/default:null，适配 Harmony 格式 | — |
| 声明式技能系统 | — | — | — | — | — | — | — | — | — | — | — | — | SKILL.md + YAML Front Matter 定义技能，非开发者可扩展 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 子 Agent 工具隔离 | allowlist/denylist 双过滤，默认排除 task 防递归 | — | — | — | — | — | — | — | — | — | — | — | — | SubAgent 独立 FilesystemMiddleware 实例，继承后端但隔离工具集 | — | — | — | — | — | — | — | — | — | clone_without_mcp/clone_without 为子 Agent 创建独立过滤注册表 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | allowedTools + allowedMcps + isInheritTools/isInheritMcps 四字段继承隔离 | — | — | — | — | — | — |
| 多模态工具返回 | — | — | — | — | — | — | — | — | — | — | — | — | — | 图片文件 base64 编码为 content_blocks 供视觉模型消费 | — | — | — | — | — | — | ToolParser 解析 text/file/image_url/input_audio 四种类型 | — | — | — | — | — | — | — | — | — | — | — | — | — | 搜索返回图片 base64 编码注入 VLM 上下文 | — | — | — | — | — | — | — | — | — | — |
| 本地远程透明切换 | — | — | — | — | — | — | — | — | — | — | — | — | — | CompositeBackend 路径路由 + SandboxBackendProtocol 能力检测 | — | — | — | — | — | — | — | — | USE_LOCAL_API 环境变量驱动，Agent 无感知 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 延迟导入隔离 | try/except ImportError 保护 MCP 可选依赖 | — | — | — | — | — | — | — | — | — | — | — | — | BackendFactory Callable 延迟到运行时创建后端，避免启动时加载所有依赖 | — | 无延迟导入，所有工具模块在 react_agent.py 顶部 import * | — | — | — | MCP SDK 在 _create_stdio_session 内部延迟 import | — | — | 无延迟导入，启动时加载所有依赖 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | treesitter 相关模块全部延迟导入，is_available() 检测后才加载 _extractors/_imports | — | — | — | — | — | MCP 依赖在 __init__ 中 import mcp 检测，sse_client 在 new_session 中延迟导入 | — |
| 长时工具反馈 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | asyncio.shield + 周期性 OutboundMessage 状态更新（20s 首次，40s 间隔） | — | — | — | — | 轮询时输出 extracted_pages/total_pages 百分比进度 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| Flow-as-Tool 动态 Schema | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 从 Flow Graph 的 input 节点自动提取字段生成 JSON Schema | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 进程级 MCP 隔离 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | MCPComposerService 为每个项目启动独立 mcp-composer 子进程 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 工具轨迹经验化 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | LLM 提取 success/failed 轨迹为 when...then... 可复用经验 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | tool 类型记忆 + when_to_use 提示 + LLM prompt 自动提取工具使用模式 | — | — | — | — | — |
| 记忆类型分类 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 8 种 memory_type 含 ToolSchemaMemory 和 ToolTrajectoryMemory | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 6 类 MemoryType（profile/event/knowledge/behavior/skill/tool）统一存储 | — | — | — | — | — |
| 批量查询合并 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | tavily_search 接受 List[str] queries 单次调用多查询 | — | — | — | — | — | — | — | search 工具按 batch_size=100 合并 HTTP 请求 | — | — | — | — | — | batch-processor 双重约束贪心分批 + runStaggered 并发执行 | — | — | — | — |
| 工作流拓扑声明 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | NodeMeta.require_prior_kind + next_available_node 声明式 DAG 依赖 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 四格式统一入口 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 目录/文件/字符串/字典四种输入自动检测解析 | — | — | — | — | — | — | — | — | TOML 文件 + Markdown 文件 + CLI iflow mcp add-json + 在线市场一键安装 | — | — | — | — | — | — |
| RL训练集成 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | format_reward 驱动模型学习正确工具标签格式 | — | — | — | — | — | — | forced token mask 天然兼容 REINFORCE/GRPO 梯度掩码 | — | — | — |
| 两阶段懒加载 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | discover_tools→get_tool_info 将初始 schema 从 50k 压缩到 500 bytes | discovery.load_all() 按需触发 + registry_state.was_load_attempted() 防重复加载 | — | — | — | — | — | 33 个解析器全部 Lazy 注册，模块导入时只存映射，首次使用时才 import | — |
| 处理器链模式 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | LangConfig.phases 有序 DetectorPhase 列表：tool → structural → AST → security → subjective | ShellProcessor→ShorthandArgProcessor→DefaultArgProcessor 三级处理器链 | — | — | — | — | — | — |
| 功能级模型绑定 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 8 功能域各自绑定多个 provider:model，支持多模型 round-robin 轮询 | — | — | — | — |
| 流式解析状态机 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | RowState 逐 token 状态机，deque 存储 forced tokens | — | 每个 Parser 维护 current_tool_id/streamed_args 等状态，支持增量 token 级解析 | — |
| 模型专用特殊 token 识别 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 4 个专用 token: python_start/end + output_start/end | — | — | — |
最佳实践
1.工具描述要精确：LLM 根据描述选择工具，模糊描述导致误选
2.参数要有默认值：减少 LLM 需要决策的参数数量
3.返回结果要结构化：便于 LLM 解析和引用
4.危险操作需确认：文件删除、网络请求等需要 human-in-the-loop
5.工具数量要控制：太多工具会稀释 LLM 的选择准确率
6.一工具一进程实现故障隔离：单个工具崩溃不影响其他工具服务
7.环境变量驱动端口配置：避免多实例部署时的端口冲突
8.文件锁保护并发状态更新：无需数据库即可实现进程级互斥
9.用 Zod .describe() 同时服务参数校验和 LLM 工具描述，避免两处维护
10.冻结注入数据：deepFreeze + structuredClone 双重保护防止沙箱内修改宿主状态
11.action 返回结构化遥测而非纯文本，支持程序化断言验证（expectMoved/expectNear）
12.内置工具 configurable:false 不可覆盖，动态 action configurable:true 可更新
13.用 satisfies 关键字约束插件导出，保留字面量类型推断
14.插件加载用 try-catch 逐个包裹，单个失败不阻塞系统启动
15.npm 包名编码槽位信息（@scope/plugin-{slot}-{name}），包名即可推断归属
16.check 返回修复指引：健康检查失败时返回人类可读的修复步骤，而非仅报错
17.Fallback Channel 兜底：注册表末尾放通用渠道，确保任何 URL 都有处理路径
18.凭据文件权限保护：配置文件保存后自动 chmod 600，防止其他用户读取敏感信息
19.环境自动检测：区分本地/服务器环境，自动调整安装策略和建议
20.脚手架优于框架：工具系统不包装调用，让 Agent 直接获得上游工具完整能力
21.兜底渠道放最后：URL 路由列表末尾放 catch-all 渠道处理未匹配的 URL
22.MCP 桥接统一入口：用 mcporter 将多个独立 MCP 服务统一为一种 CLI 调用模式
23.检测信息含修复建议：check 返回的 message 应包含具体的安装/配置命令
24.工具分组要有业务语义：按功能域（search/file/code）而非技术类型分组
25.元工具要注入使用说明：reset_equipped_tools 返回的 notes 要详细到 Agent 能理解
26.中间件要保持幂等：同一中间件多次注册不应产生副作用
27.MCP 工具要设置超时：长时工具必须设置 read_timeout_seconds 防止阻塞
28.Agent Skill 要提供示例：SKILL.md 中必须包含具体的使用示例代码
29.工具逻辑用私有方法：防止外部直接调用，通过工厂方法暴露
30.结构化错误标记：返回 LLM 可理解的错误字符串（如 NO_RELEVANT_CHUNKS）而非异常
31.工具调用去重键设计：使用 type::value 格式（如 parent::id, search::query）便于过滤和展示
32.MCP Server 应做薄包装层：协议转换 + HTTP 转发，业务逻辑下沉到独立服务
33.用伪工具（__IMPORTANT）在 tools/list 中传递 workflow 规范比 system prompt 更可靠
34.搜索结果先返回索引再按需获取详情，可节省 10x token 消耗
35.用 dataclass 替代全局字典传递工具间共享状态，获得类型安全和 IDE 支持
36.工具参数校验失败时返回含 error 字段的 JSON，让 LLM 可自动修正重试
37.透明 Provider 包装用 __getattr__ 转发非拦截属性，对框架零侵入
38.MCP 热替换应锁外连接锁内交换，最小化锁持有时间
39.技能发现用约定文件（SKILL.md）而非注册表，降低扩展门槛
40.条件工具注册应通过环境变量控制，支持运行时开关
41.每个同步方法提供 asyncio.to_thread 默认异步版本，避免阻塞事件循环
42.用 lru_cache 缓存签名检查结果，避免重复反射开销
43.大结果驱逐时保留 head+tail 预览而非简单截断，保留上下文线索
44.错误返回字符串而非抛异常：让 LLM 可自行解读错误并重试
45.子 Agent 用独立注册表实例而非运行时过滤：编译期隔离比运行时检查更安全
46.条件加载用环境变量驱动：不可用的工具不注册，避免 LLM 选择不可用工具
47.心跳复用已有 RPC：用 list_tools 做心跳而非专门 ping，减少协议复杂度
48.工具调用用 XML 标签而非 function calling：兼容任意 LLM 后端，不依赖特定 API 格式
49.异步工具在同步 loop 中用 asyncio.run 桥接：简单但需注意事件循环嵌套问题
50.薄包装层与服务层分离：tools/ 只做接口适配，逻辑放 services/
51.工具结果截断后再摘要：防止超长输出撑爆上下文窗口
52.代码执行前用 AST 检查导入：ImportGuard 在执行前拦截危险模块
53.用 module:variable 冒号分隔符避免与 Python 包路径混淆
54.MCP 依赖用 try/except ImportError 保护，保持核心功能不依赖可选包
55.BUILTIN_TOOLS.copy() 避免修改全局列表导致状态污染
56.SubAgent 默认 denylist 包含 task 工具，防止递归嵌套
57.工具执行返回字符串而非抛异常：确保 Agent loop 不因单个工具失败而中断
58.子 Agent 工具集要严格裁剪：禁止 message/spawn 防止递归失控和越权通信
59.MCP stdio 模式下日志必须写文件：stdout 是 JSON-RPC 通道，任何非协议输出都会破坏通信
60.工具选择应有降级路径：LLM 选择不可靠时用关键词匹配兜底
61.MCP 模块应职责分离：连接管理、工具选择、执行、流式输出各自独立
62.工具结果归一化：无论 MCP 返回什么格式都转为统一的 {title,href,body} 结构
63.大枚举选项降级为 string：Dropdown 超过 50 个选项时不生成 Literal 类型避免 token 浪费
64.工具名需要 Unicode 安全化：emoji、变音符号、特殊字符都需要清理为 ASCII 兼容格式
65.MCP 会话应按 server_key 复用而非按 context_id 创建：避免每次调用都启动新子进程
66.camelCase 参数自动修正：LLM 常将 snake_case 参数写成 camelCase，工具层应自动转换
67.MCP 工具函数用 try/except 包裹返回错误字符串而非抛异常，避免 Agent 因异常中断
68.为每种多模态内容类型创建独立 SourceMessage 而非拼接为单一字符串，保留溯源能力
69.用自然语言 schema 而非 JSON Schema：LLM 理解 docstring 比理解 JSON Schema 更准确
70.两阶段推荐控制 token：先 BM25 粗筛再 LLM 精排，避免全量工具撑爆上下文
71.装饰器注册保持代码与 schema 同步：修改代码时 schema 自动更新，无需手动维护
72.exclusive_tool_commands 防止重复操作：同类编辑命令只保留首个，避免 LLM 重复调用
73.极简工具集：专用 MCP Server 工具数量控制在 2-5 个，用统一入口覆盖多场景
74.instructions 字段要写清楚：FastMCP 的 instructions 是 LLM 理解服务器能力的第一入口
75.SSE 模式需手动构建 Starlette 应用：FastMCP 的 SSE 支持需要底层 SseServerTransport 配合
76.deny 始终累积不可覆盖：任何层级的禁止都不应被更高优先级的 allow 推翻
77.工具来源用枚举而非前缀判断：ToolSource 比字符串前缀更可靠，支持类型安全的批量操作
78.MCP 工具命名用双下划线分隔：mcp__server__tool 格式确保 splitn 无歧义拆分
79.错误返回字符串而非抛异常：让 LLM 看到错误并自行修正
80.MCP 工具命名空间隔离：前缀 mcp_{server}_ 避免与内置工具冲突
81.工具输出截断：控制上下文窗口膨胀，ExecTool 和 WebFetch 各有上限
82.闭包替换 coroutine 属性实现零侵入工具增强，不需要继承或修改上游库
83.MCP 工具加载时维护 existing_tool_names 集合防止名称冲突
84.搜索工具内嵌摘要管道时必须加超时保护，防止单个网页摘要阻塞整个搜索
85.用 Annotated[type, FieldInfo] 携带参数描述让 FastMCP 自动生成 JSON Schema，避免手写
86.BaseNode.__call__ 模板方法统一 I/O 序列化，子类只需实现 process() 业务逻辑
87.TOML 白名单 available_nodes 比代码分支更灵活地控制不同部署的工具集
88.用 stateless_http 模式部署 MCP Server 支持横向扩展
89.工具返回结果应包含来源引用和耗时数据便于 LLM 引用和用户验证
90.MCP 工具名用连字符命名（kebab-case）保持跨平台一致性
91.技能注册时同步向量化 description 实现零延迟语义发现
92.用 SingleFlightCache 防止并发缓存穿透，避免多请求同时重建工具实例
93.OAuth 工具在 Composio 未配置时自动隐藏，避免用户看到不可用工具
94.工具集按 toolsetKey 分组共享认证配置，避免每个工具重复配置凭据
95.数据库注册表覆盖静态注册表但保留 class 引用，实现热更新不丢失类型安全
96.模式互斥工具要在注册层裁剪而非 prompt 层引导，减少 LLM 选择负担
97.MCP 连接建立后立即 ping 验证，fail-fast 避免运行时才发现连接不可用
98.无副作用的 think 工具让 Agent 有显式推理空间，提升复杂任务规划质量
99.工具函数体应为薄代理：只做路由调用，不含业务逻辑
100.降级应区分异常类型：仅限流/超时等瞬态故障触发降级，逻辑错误应直接抛出
101.按 Agent 角色隔离工具子集：减少 LLM 选择空间比增加工具描述更有效
102.RL 场景用 XML 标签替代 JSON Schema：模型可直接生成和学习文本化工具调用
103.format reward 强制工具使用模式：奖励函数要求同时包含 search 和 answer 标签
104.批量合并同类工具调用：收集 batch 中所有 search query 一次性发送减少网络往返
105.无效 action 返回重试提示而非终止：给模型自我纠正的机会
106.元工具与业务工具分层：Planner 只注册能力查询工具，不直接调用业务工具
107.AgentCard 配置独立于代码：非开发者可编辑 JSON 调整 Agent 能力描述
108.工具函数用 async 定义：支持 I/O 密集型操作（网络请求、文件读写）不阻塞
109.Agent 初始化懒加载：API key 缺失时返回 None 而非抛异常，保证系统部分可用
110.MCP Server instructions 中引导 Agent 先调用 discover_tools 再按需获取详情
111.为列表类工具提供 brief/fields/max_description_length 三种粒度控制参数
112.写操作默认返回 OperationResult 而非完整对象，brief=False 时才返回全量
113.连接池按 workspace 隔离，健康检查失败时指数退避重连而非立即报错
114.所有日志输出到 stderr 保护 stdio 传输的 JSON-RPC 协议完整性
115.子进程调用设置 stdin=DEVNULL 防止 MCP stdin 被继承
116.frozen dataclass 保证工具元数据注册后不可变，避免运行时篡改
117.工厂函数内双注册（detector + scoring）保证一致性，不要分散注册
118.插件发现失败应隔离记录而非中断加载，保证其他插件正常工作
119.黑名单优先于白名单：excludeTools 永远生效，避免白名单遗漏导致安全漏洞
120.处理器链短路：{{args}} 占位符处理后跳过默认追加，避免参数重复注入
121.命令级限制非安全机制：基于字符串匹配的 ShellTool(cmd) 限制可被绕过，不应作为安全边界
122.SubAgent 默认继承工具：isInheritTools 默认 true 减少配置冗余，仅安全敏感场景设为 false
123.TOML 声明式降低门槛：非开发者通过 description+prompt 两字段即可创建自定义命令
124.工具调用去重用 hash：MD5(tool_name|input|output) 防止相同调用重复记录
125.未知值用哨兵值区分：token_cost=-1 区分'未追踪'和'零消耗'
126.滑动窗口避免历史稀释：只统计最近 N 次调用，反映当前工具状态
127.适配器模式解耦框架集成：MemULangGraphTools 桥接记忆核心与 LangChain 生态
128.按模型名查表而非按 URL：代理平台的模型名与直连一致，避免 URL 变化导致查表失效
129.prefix 匹配按长度降序：避免短前缀误匹配更具体的模型（如 gpt- 不应覆盖 gpt-image-）
130.保守 token 估算（字符/1.5）：宁可高估多分批也不低估撞限制，避免引入重型 tiktoken 库
131.随机起始索引：多 Key 轮询从随机位置开始，避免所有实例都从第一个 Key 开始导致热点
132.工具输出 token 训练掩码为 0：模型只学调用时机和表达式，不学结果值
133.forced token 用 deque 而非 list：popleft O(1) 避免大量注入时的性能退化
134.eval 沙箱清空 builtins：eval(expr, {'__builtins__': {}}, {}) 是最小化 Python 沙箱
135.用 Lazy 注册避免启动时加载所有模型解析器依赖，33 个解析器只在使用时才导入
136.流式解析器必须是有状态实例（维护 current_tool_id 等），非流式解析器可以是无状态的
137.用 partial_json_parser 处理流式不完整 JSON，配合 find_common_prefix 精确控制增量输出
138.支持用户通过 --tool-parser-plugin 加载自定义解析器，不修改引擎源码
139.工具适配器应延迟导入底层 Service：避免启动时加载未安装的依赖导致全局失败
140.双基类优于万能基类：搜索和爬虫接口契约不同，分开定义减少误用
141.参数别名映射表：预定义 LLM 常见参数错误的修正规则，比让 LLM 重试更高效
142.工具执行统计应内置：calls/successes/failures/avg_ms 四维统计帮助定位慢工具