WeClaw_42_Agent工具注册全链路从BaseTool到意图识别的标准化接入作者: WeClaw 开发团队日期: 2026-03-29版本: v1.0标签: Agent 工具、BaseTool、意图识别、渐进式暴露、延迟注入 摘要本文系统讲解 WeClaw Agent 工具注册的完整链路。当需要将一个新功能如远程文件分享注册为 LLM 可调用的 Agent 工具时需要经历 8 个步骤的标准化流程。文章以remote_file_share工具为实战案例深入剖析 BaseTool 抽象基类、ActionDef 定义、tools.json 配置、意图识别三表联动、渐进式工具暴露引擎、延迟依赖注入等核心机制。核心收获 掌握 BaseTool 抽象基类和 ActionDef 模型⚙️ 理解 tools.json 声明式工具注册 学会意图识别三表联动CATEGORIES MAPPING PRIORITY 掌握渐进式工具暴露的三级策略 了解延迟依赖注入模式的应用场景 需求背景为什么需要工具注册从能做到会调在第 41 篇中我们实现了send_file_to_pwa()等文件传输方法。但这些方法只是RemoteBridgeClient的内部 API大模型LLM无法自动调用。用户: 帮我做个 PPT 发到手机上 ❌ 没有工具注册时 AI: PPT 已生成保存在 generated/xxx.pptx ← 无法发送 ✅ 注册为 Agent 工具后 AI: 1. 调用 ppt_generator 生成 PPT 2. 自动调用 remote_file_share_send_file(file_pathgenerated/xxx.pptx) 3. PPT 已生成并发送到你的手机完整注册链路一览① 创建工具模块 → ② tools.json → ③ 意图关键词 → ④ 工具映射 ↓ ↓ ↓ ↓ BaseTool 子类 声明式注册 INTENT_CATEGORIES INTENT_TOOL_MAPPING ↓ ⑧ 全链路校验 ← ⑦ GUI 注入 ← ⑥ 构造参数 ← ⑤ 工具名前缀 ↓ ↓ ↓ ↓ validate.py gui_app.py registry.py tool_exposure.py 步骤一创建工具模块BaseTool 抽象基类所有 Agent 工具都继承自BaseTool需实现两个核心方法fromsrc.tools.baseimportActionDef,BaseTool,ToolResult,ToolResultStatusclassRemoteFileShareTool(BaseTool):远程文件分享工具。nameremote_file_shareemojititle远程文件分享description将桌面端文件发送到 PWA 端timeout180# 大文件上传超时defget_actions(self)-list[ActionDef]:定义工具支持的动作列表。...asyncdefexecute(self,action:str,params:dict)-ToolResult:执行指定动作。...ActionDef 定义每个 Action 定义为一个ActionDef包含名称、描述和 JSON Schema 参数defget_actions(self)-list[ActionDef]:return[ActionDef(namesend_file,description(将桌面端本地文件发送到 PWA 端用户。当你为远程 PWA 用户生成了文件必须调用此工具将结果发送回去。),parameters{file_path:{type:string,description:要发送的本地文件绝对路径,},description:{type:string,description:文件描述会显示在 PWA 端,},user_id:{type:string,description:目标 PWA 用户 ID留空则发送给当前会话用户,},},required_params[file_path],),ActionDef(namesend_files,description将多个桌面端本地文件批量发送到 PWA 端用户。,parameters{file_paths:{type:array,items:{type:string},description:要发送的本地文件路径列表,},# ...},required_params[file_paths],),ActionDef(namesend_voice,description将语音/音频文件作为语音消息发送到 PWA 端。,parameters{file_path:{type:string,...},transcript:{type:string,...},# ...},required_params[file_path],),]Schema 生成机制BaseTool.get_schema()自动将 ActionDef 转换为 OpenAI Function Calling 兼容格式# 函数名格式{tool_name}_{action_name}# 例如remote_file_share_send_file# 生成的 schema 示例{type:function,function:{name:remote_file_share_send_file,description:将桌面端本地文件发送到 PWA 端用户...,parameters:{type:object,properties:{file_path:{type:string,...},description:{type:string,...},user_id:{type:string,...},},required:[file_path]}}}⚙️ 步骤二tools.json 声明式注册{remote_file_share:{enabled:true,module:src.tools.remote_file_share,class:RemoteFileShareTool,display:{name:远程文件分享,emoji:,description:将桌面端本地文件发送到 PWA 端,category:communication},config:{},security:{risk_level:low,require_confirmation:false},actions:[send_file,send_files,send_voice]}}字段说明| 字段 | 作用 ||------|------||module/class| 动态导入路径 ||display.category| 意图分类关联 ||config| 传递给构造函数的参数 ||security.risk_level| 高风险工具需用户确认 ||actions| 声明支持的动作用于校验 | 步骤三~四意图识别三表联动WeClaw 的意图识别系统基于三张核心映射表协同工作表一INTENT_CATEGORIES — 关键词 → 意图INTENT_CATEGORIES:dict[str,list[str]]{communication:[发送文件,发文件到手机,传文件,分享文件,发到PWA,发送到手机,传到手机,发给手机,发送语音,语音消息,发语音,录音发送,远程分享,远程发送,文件传输,文件分享,发到浏览器,发送到浏览器,],# ... 其他 17 个意图维度}表二INTENT_TOOL_MAPPING — 意图 → 工具列表INTENT_TOOL_MAPPING:dict[str,list[str]]{communication:[wechat,remote_file_share],# ... 其他意图}表三INTENT_PRIORITY_MAP — 工具优先级INTENT_PRIORITY_MAP:dict[str,dict[str,list[str]]]{communication:{recommended:[wechat,remote_file_share],alternative:[],},# ... 其他意图}三表协同工作流用户输入: 把这份报告发到手机上 ↓ INTENT_CATEGORIES 匹配: 发到手机 → communication (置信度 0.9) ↓ INTENT_TOOL_MAPPING 查找: communication → [wechat, remote_file_share] ↓ INTENT_PRIORITY_MAP 排序: recommended → [wechat, remote_file_share] ↓ 渐进式暴露引擎: 高置信度 → 仅暴露 recommended 工具 ↓ LLM 可见工具: [wechat, remote_file_share] (而非全部 51 工具) 步骤五工具名前缀注册多下划线工具名的解析难题LLM 调用函数时使用{tool_name}_{action_name}格式remote_file_share_send_file │ │ │ │ └─── tool_name ───┘ └ action┘但简单按第一个下划线拆分会得到错误结果remote_file_share_send_file.split(_)[0]# → remote ❌解决方案known_prefixes 前缀表def_extract_tool_name(func_name:str)-str:从函数名中提取工具名。known_prefixes[browser_use,app_control,voice_input,remote_file_share,# 本次新增daily_task,medication,# ... 共 40 前缀]forprefixinknown_prefixes:iffunc_name.startswith(prefix_)orfunc_nameprefix:returnprefix# 默认取第一个下划线前的部分returnfunc_name.split(_)[0]if_infunc_nameelsefunc_name注意事项validate_tool_chain.py中也有一份硬编码的前缀列表需同步更新。 步骤六~七构造参数与依赖注入registry.py — 构造参数映射def_build_init_kwargs(self,tool_name:str,cfg:dict)-dict:从工具配置中提取构造参数。kwargs{}tool_configcfg.get(config,{})iftool_nameshell:kwargs[timeout]tool_config.get(timeout,30)eliftool_namebrowser:kwargs[headless]tool_config.get(headless,False)eliftool_nameremote_file_share:# 无构造参数bridge_client 通过延迟注入pass# ... 50 工具分支returnkwargs延迟依赖注入模式RemoteFileShareTool依赖RemoteBridgeClient但两者的创建时机不同时间线 1. gui_app.py 创建 ToolRegistry → 注册所有工具含 RemoteFileShareTool 2. gui_app.py 创建 MainWindow → MainWindow 创建 RemoteBridgeClient 3. gui_app.py 将 bridge_client 注入到 RemoteFileShareTool ← 延迟注入注入代码# gui_app.py — MainWindow 创建后remote_bridgegetattr(self._window,_remote_bridge,None)ifremote_bridge:rfs_toolself._tool_registry.get_tool(remote_file_share)ifrfs_toolandhasattr(rfs_tool,set_bridge_client):rfs_tool.set_bridge_client(remote_bridge)logger.info(已为 remote_file_share 工具注入 bridge_client)工具端接口classRemoteFileShareTool(BaseTool):def__init__(self)-None:self._bridge_clientNone# 延迟注入defset_bridge_client(self,bridge_client)-None:注入 RemoteBridgeClient 实例。self._bridge_clientbridge_clientdef_check_bridge(self)-ToolResult|None:检查 bridge 是否可用。ifnotself._bridge_client:returnToolResult(statusToolResultStatus.ERROR,error远程桥接客户端未初始化)ifnotself._bridge_client.is_connected:returnToolResult(statusToolResultStatus.ERROR,error远程桥接未连接)returnNone自动选取 PWA 用户当 LLM 未指定user_id时自动选取第一个在线 PWA 用户def_resolve_user_id(self,params:dict)-str:解析目标用户 ID。user_idparams.get(user_id,)ifuser_id:returnuser_id# 自动选取当前在线的 PWA 用户ifself._bridge_clientandself._bridge_client.stats.pwa_connections:first_connself._bridge_client.stats.pwa_connections[0]returnfirst_conn.user_idreturn✅ 步骤八全链路校验validate_tool_chain.py 七项检查$ python scripts/validate_tool_chain.pyWinClaw 工具全链路一致性校验已加载 tools.json:58个启用工具 ✅[1/7]INTENT_TOOL_MAPPING 覆盖:58工具 ✅[2/7]INTENT_TOOL_MAPPING 引用有效 ✅[3/7]INTENT_PRIORITY_MAP 引用有效 ✅[4/7]_extract_tool_name 已知前缀覆盖 ✅[5/7]dependencies 引用有效 ✅[6/7]_build_init_kwargs 覆盖 ✅[7/7]三表 key 对齐:18个意图 结果:7通过,0警告,0失败校验项说明| 校验 | 检查内容 | 确保 ||------|---------|------|| [1] | tools.json 中的工具是否都在 MAPPING 中 | 不遗漏 || [2] | MAPPING 引用的工具是否都在 tools.json 中 | 不多引 || [3] | PRIORITY 引用的工具是否都在 tools.json 中 | 不多引 || [4] | 多下划线工具名在 known_prefixes 中 | 解析正确 || [5] | 依赖的 input_sources 工具存在 | 依赖有效 || [6] | _build_init_kwargs 有对应分支 | 构造正确 || [7] | 三表的 key 完全对齐 | 意图一致 | 经验教训1. 前缀表需双重同步教训只更新了tool_exposure.py的known_prefixes校验仍然失败。原因validate_tool_chain.py中有一份硬编码的副本也需要同步更新。最佳实践每次新增多下划线工具必须同时更新两处。2. 延迟注入的时序依赖教训工具注册在 ToolRegistry 创建时完成但 bridge 在 MainWindow 创建时才存在。解决方案使用set_bridge_client()模式与 CronTool 的set_agent_dependencies()保持一致。3. 意图关键词的覆盖度教训初始只添加了发送文件一个关键词用户说传到手机时无法匹配。解决方案充分枚举同义变体18 个关键词覆盖各种口语表达。 架构总结工具注册八步标准流程| 步骤 | 文件 | 内容 ||------|------|------|| ① |src/tools/xxx.py| 创建 BaseTool 子类 || ② |config/tools.json| 声明式注册 || ③ |src/core/prompts.py| INTENT_CATEGORIES 关键词 || ④ |src/core/prompts.py| INTENT_TOOL_MAPPING PRIORITY || ⑤ |src/core/tool_exposure.py| known_prefixes 前缀 || ⑥ |src/tools/registry.py| _build_init_kwargs 分支 || ⑦ |src/ui/gui_app.py| 延迟依赖注入按需 || ⑧ |scripts/validate_tool_chain.py| 全链路校验 |字数统计: 约 5,200 字阅读时间: 约 14 分钟代码行数: 约 350 行4. 3. 2. 4. 3. - - - - -