🔍
项目文档/AI代理系统/工具系统/内置工具库/实用工具

实用工具

📎 引用文件

本文引用的文件 - web_search_tool.py - web_reader_tool.py - doc_reader_tool.py - image_vision_tool.py - test_web_search_tool.py - test_doc_reader.py - test_image_vision_tool.py

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与优化
  8. 故障排查指南
  9. 结论
  10. 附录：API与使用示例

简介

本章节面向Vibe-Trading的“实用工具集”，聚焦四类能力： - 网络搜索与信息检索（web_search_tool） - 网页内容解析与结构化提取（web_reader_tool） - 文档解析与文本提取（doc_reader_tool） - 图像识别与OCR/视觉问答（image_vision_tool）

这些工具统一以BaseTool为基类，提供一致的参数契约、可重复调用、安全过滤与错误返回格式。它们既可用于CLI交互，也可嵌入自动化工作流，支撑金融研究、信息收集与内容处理等场景。

项目结构

四个工具均位于 agent/src/tools 目录下，配套测试位于 agent/tests。工具之间相互独立，通过统一的工具注册机制被上层Agent调度。

graph TB subgraph "工具层" WS["WebSearchTool<br/>web_search"] WR["WebReaderTool<br/>read_url"] DR["DocReaderTool<br/>read_document"] IV["AnalyzeImageTool<br/>analyze_image"] end subgraph "外部服务/库" DDGS["ddgs / duckduckgo_search"] JINA["Jina Reader API"] OCR["OCR引擎(可插拔)"] LLM["多模态LLM(聊天适配器)"] end WS --> DDGS WR --> JINA DR --> OCR IV --> LLM

图表来源 - web_search_tool.py:134-349 - web_reader_tool.py:134-152 - doc_reader_tool.py:422-457 - image_vision_tool.py:52-147

章节来源 - web_search_tool.py:1-349 - web_reader_tool.py:1-152 - doc_reader_tool.py:1-457 - image_vision_tool.py:1-147

核心组件

章节来源 - web_search_tool.py:134-349 - web_reader_tool.py:134-152 - doc_reader_tool.py:422-457 - image_vision_tool.py:52-147

架构总览

下图展示从用户输入到各工具执行、再到结果封装的安全与容错路径。

sequenceDiagram participant U as "调用方" participant T as "工具(BaseTool)" participant S as "搜索/读取/解析" participant E as "外部服务" participant F as "安全过滤" U->>T : 调用execute(params) T->>S : 执行业务逻辑(搜索/抓取/解析) S->>E : 访问第三方(搜索引擎/Jina/OCR/LLM) E-->>S : 返回原始数据或错误 S->>F : 对敏感字段做安全脱敏/警告 F-->>T : 安全后的结果 T-->>U : JSON统一响应(status/ok/error + 数据)

图表来源 - web_search_tool.py:172-349 - web_reader_tool.py:61-152 - doc_reader_tool.py:87-100 - image_vision_tool.py:85-147

详细组件分析

WebSearchTool（网络搜索）

flowchart TD Start(["开始"]) --> V["校验参数<br/>query非空, max_results∈[1,10]"] V --> Q{"是否配置IQS?"} Q -- 是 --> IQS["调用阿里云IQS"] IQS --> IQSOK{"有结果?"} IQSOK -- 是 --> OutIQS["返回IQS结果(安全过滤)"] IQSOK -- 否 --> DDGS["调用ddgs(可指定后端)"] Q -- 否 --> DDGS DDGS --> Try{"尝试次数<=3?"} Try -- 是 --> CallDDGS["text(query,max_results,backend)"] CallDDGS --> Err{"异常类型"} Err -- "无结果" --> Empty["返回空结果(状态ok)"] Err -- "网络/连接/超时" --> FB["跳过重试,进入回退"] Err -- "其他" --> Retry["退避重试"] Try -- 否 --> FB FB --> Sogou["尝试搜狗"] Sogou --> SOK{"有结果?"} SOK -- 是 --> OutFB["返回回退结果(安全过滤)"] SOK -- 否 --> Bing["尝试必应中国"] Bing --> BOK{"有结果?"} BOK -- 是 --> OutFB BOK -- 否 --> Fail["返回错误(含排障提示)"]

图表来源 - web_search_tool.py:172-349

章节来源 - web_search_tool.py:1-349 - test_web_search_tool.py:1-199

WebReaderTool（网页阅读）

sequenceDiagram participant C as "调用方" participant R as "WebReaderTool" participant J as "Jina Reader" C->>R : execute(url, no_cache) R->>R : _url_allowed(url) alt 允许 R->>J : GET r.jina.ai/{url} (Accept : text/markdown) J-->>R : Markdown文本(可能含缓存标记) R->>R : 提取Title/截断/标记cached R-->>C : {status,title,url,content,length,cached} else 不允许 R-->>C : {status : error, error : "target URL is not allowed"} end

图表来源 - web_reader_tool.py:24-152

章节来源 - web_reader_tool.py:1-152

DocReaderTool（文档读取）

flowchart TD A["read_document(file_path, pages)"] --> P["安全路径校验"] P --> E{"扩展名"} E -- ".pdf" --> PDF["pypdfium2提取文本<br/>不足则OCR"] E -- ".docx" --> DOCX["python-docx段落+表格"] E -- ".xlsx/.xls" --> XLS["pandas逐表预览"] E -- ".pptx" --> PPTX["python-pptx幻灯片文本"] E -- "图片" --> IMG["PIL+numpy -> OCR"] E -- "文本/代码/配置" --> TXT["多编码回退解码"] PDF --> EN["统一信封(含质量指标)"] DOCX --> EN XLS --> EN PPTX --> EN IMG --> EN TXT --> EN

图表来源 - doc_reader_tool.py:103-419

章节来源 - doc_reader_tool.py:1-457 - test_doc_reader.py:1-186

AnalyzeImageTool（图像视觉）

sequenceDiagram participant U as "调用方" participant I as "AnalyzeImageTool" participant FS as "文件系统" participant M as "多模态LLM(ChatLLM)" U->>I : execute(path, question?) I->>FS : resolve_safe_path() + read_bytes() FS-->>I : 图片字节 I->>M : chat(messages=[text,image_url]) M-->>I : 回答文本 I-->>U : {ok : true, data : {path,question,answer}}

图表来源 - image_vision_tool.py:85-147

章节来源 - image_vision_tool.py:1-147 - test_image_vision_tool.py:1-76

依赖关系分析

graph LR WS["WebSearchTool"] --> DD["ddgs/duckduckgo_search"] WS --> IQS["阿里云IQS(可选)"] WR["WebReaderTool"] --> JN["Jina Reader API"] DR["DocReaderTool"] --> PDF["pypdfium2"] DR --> DOC["python-docx"] DR --> XLS["pandas"] DR --> PPT["python-pptx"] DR --> IMG["Pillow/numpy"] DR --> OCR["OCR引擎(可插拔)"] IV["AnalyzeImageTool"] --> LLM["ChatLLM(多模态)"] WS -.-> SEC["with_security_warnings"] WR -.-> SEC DR -.-> SEC IV -.-> PATH["path_utils(白名单)"]

图表来源 - web_search_tool.py:134-349 - web_reader_tool.py:134-152 - doc_reader_tool.py:422-457 - image_vision_tool.py:52-147

章节来源 - web_search_tool.py:1-349 - web_reader_tool.py:1-152 - doc_reader_tool.py:1-457 - image_vision_tool.py:1-147

性能与优化

[本节为通用性能讨论，不直接分析具体文件]

故障排查指南

章节来源 - web_search_tool.py:172-349 - web_reader_tool.py:61-152 - doc_reader_tool.py:87-419 - image_vision_tool.py:85-147

结论

该工具集围绕“搜索—阅读—解析—视觉”形成完整的信息采集与处理能力链。通过多后端容错、安全白名单、统一信封与安全过滤，既保证了鲁棒性，也便于集成到自动化工作流中。结合批量处理（PDF分页、Excel多Sheet）与缓存控制（网页no_cache），可在保证性能的同时满足高频研究需求。

[本节为总结性内容，不直接分析具体文件]

附录：API与使用示例

read_url（网页阅读）

read_document（文档读取）

analyze_image（图像视觉）

自动化信息收集与工作流示例

[本节为概念性示例，不直接分析具体文件]

← 基本面分析工具 市场数据工具 →