crawlo 1.3.2__py3-none-any.whl → 1.3.4__py3-none-any.whl

crawlo/templates/project/settings_simple.py.tmpl

@@ -1,102 +1,165 @@
 # -*- coding: UTF-8 -*-
 """
-简化模式配置模板
-最小配置，适合快速开始和简单项目
+{{project_name}} 项目配置文件（简化版）
+=============================
+基于 Crawlo 框架的简化爬虫项目配置。
+适合快速开始和简单项目。
 """
 
 # ============================== 项目基本信息 ==============================
 PROJECT_NAME = '{{project_name}}'
 
-# ============================== 简化运行模式 ==============================
-# 运行模式：'standalone'(单机), 'distributed'(分布式), 'auto'(自动检测)
-RUN_MODE = 'standalone'  # 单机模式 - 适用于开发和小规模数据采集
+# ============================== 运行模式 ==============================
+RUN_MODE = 'standalone'
 
-# 并发配置
-CONCURRENCY = 4  # 低并发数以减少资源占用
-DOWNLOAD_DELAY = 1.0  # 增加延迟以降低目标网站压力
+# ============================== 并发配置 ==============================
+CONCURRENCY = 4
+MAX_RUNNING_SPIDERS = 1
+DOWNLOAD_DELAY = 1.0
 
-# ============================== 队列配置 ==============================
-
-# 注意：框架已提供默认的队列配置，以下配置项通常无需修改
-# 如需自定义，请取消注释并修改相应值
-
-# 队列类型：'auto'（自动选择）, 'memory'（内存队列）, 'redis'（分布式队列）
-# QUEUE_TYPE = 'auto'  # 自动检测，如果Redis可用则使用Redis队列
-# SCHEDULER_MAX_QUEUE_SIZE = 1000
-# SCHEDULER_QUEUE_NAME = f'crawlo:{{project_name}}:queue:requests'
-# QUEUE_MAX_RETRIES = 3
-# QUEUE_TIMEOUT = 300
+# ============================== 下载器配置 ==============================
+# 可选下载器:
+# DOWNLOADER = 'crawlo.downloader.aiohttp_downloader.AioHttpDownloader'
+# DOWNLOADER = 'crawlo.downloader.httpx_downloader.HttpXDownloader'
+# DOWNLOADER = 'crawlo.downloader.cffi_downloader.CurlCffiDownloader'
+DOWNLOADER = 'crawlo.downloader.aiohttp_downloader.AioHttpDownloader'
 
-# ============================== 去重过滤配置 ==============================
+# ============================== 队列配置 ==============================
+QUEUE_TYPE = 'memory'
 
-# 注意：框架已提供默认的去重配置，以下配置项通常无需修改
-# 如需自定义，请取消注释并修改相应值
+# ============================== 去重过滤器 ==============================
+FILTER_CLASS = 'crawlo.filters.memory_filter.MemoryFilter'
 
-# 简化模式下使用内存去重管道和过滤器
-# DEFAULT_DEDUP_PIPELINE = 'crawlo.pipelines.memory_dedup_pipeline.MemoryDedupPipeline'
-# FILTER_CLASS = 'crawlo.filters.memory_filter.MemoryFilter'
+# ============================== 默认去重管道 ==============================
+DEFAULT_DEDUP_PIPELINE = 'crawlo.pipelines.memory_dedup_pipeline.MemoryDedupPipeline'
 
-# --- Redis 配置（用于分布式去重和队列） ---
-# REDIS_HOST = '127.0.0.1'
-# REDIS_PORT = 6379
-# REDIS_PASSWORD = ''  # 如果有密码，请填写
+# ============================== 爬虫模块配置 ==============================
+SPIDER_MODULES = ['{{project_name}}.spiders']
 
-# 根据是否有密码生成 URL
-# if REDIS_PASSWORD:
-#     REDIS_URL = f'redis://:{REDIS_PASSWORD}@{REDIS_HOST}:{REDIS_PORT}/0'
-# else:
-#     REDIS_URL = f'redis://{REDIS_HOST}:{REDIS_PORT}/0'
-
-# Redis key配置已移至各组件中，使用统一的命名规范
-# crawlo:{project_name}:filter:fingerprint (请求去重)
-# crawlo:{project_name}:item:fingerprint (数据项去重)
-# crawlo:{project_name}:queue:requests (请求队列)
-# crawlo:{project_name}:queue:processing (处理中队列)
-# crawlo:{project_name}:queue:failed (失败队列)
-
-# REDIS_TTL = 0
-# CLEANUP_FP = 0
-# FILTER_DEBUG = True
-# DECODE_RESPONSES = True
-
-# ============================== 域名过滤配置 ==============================
-# OffsiteMiddleware 配置，用于限制爬虫只爬取指定域名的页面
-# 如需启用域名过滤功能，请取消注释并配置允许的域名列表
-# ALLOWED_DOMAINS = ['example.com', 'www.example.com']
-
-# ============================== 用户自定义中间件配置 ==============================
-# 注意：框架默认中间件已自动加载，此处可添加或覆盖默认中间件
-
-# 中间件列表（框架默认中间件 + 用户自定义中间件）
+# ============================== 中间件 ==============================
 # MIDDLEWARES = [
-    # '{{project_name}}.middlewares.CustomMiddleware',  # 示例自定义中间件
+#     'crawlo.middleware.simple_proxy.SimpleProxyMiddleware',
 # ]
 
-# ============================== 用户自定义数据管道配置 ==============================
-# 注意：框架默认管道已自动加载，此处可添加或覆盖默认管道
+# ============================== 默认请求头配置 ==============================
+# 为DefaultHeaderMiddleware配置默认请求头
+DEFAULT_REQUEST_HEADERS = {
+    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+    'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
+    'Accept-Encoding': 'gzip, deflate, br',
+}
+
+# ============================== 允许的域名 ==============================
+# 为OffsiteMiddleware配置允许的域名
+# ALLOWED_DOMAINS = ['example.com']
 
-# 数据处理管道列表（框架默认管道 + 用户自定义管道）
+# ============================== 数据管道 ==============================
 # PIPELINES = [
-    # '{{project_name}}.pipelines.DatabasePipeline',        # 自定义数据库管道
-    # 'crawlo.pipelines.mysql_pipeline.AsyncmyMySQLPipeline',  # MySQL 存储
-    # 'crawlo.pipelines.mongo_pipeline.MongoPipeline',      # MongoDB 存储
+#     'crawlo.pipelines.mysql_pipeline.AsyncmyMySQLPipeline',     # MySQL 存储（使用asyncmy异步库）
 # ]
 
-# ============================== 用户自定义扩展组件 ==============================
-# 注意：框架默认扩展已自动加载，此处可添加或覆盖默认扩展
-
-# 扩展组件列表（框架默认扩展 + 用户自定义扩展）
+# ============================== 扩展组件 ==============================
 # EXTENSIONS = [
-    # 'crawlo.extension.memory_monitor.MemoryMonitorExtension',  # 内存监控
-    # 'crawlo.extension.request_recorder.RequestRecorderExtension',  # 请求记录
-    # 'crawlo.extension.performance_profiler.PerformanceProfilerExtension',  # 性能分析
-    # 'crawlo.extension.health_check.HealthCheckExtension',  # 健康检查
+#     'crawlo.extension.log_interval.LogIntervalExtension',
+#     'crawlo.extension.log_stats.LogStats',
+#     'crawlo.extension.logging_extension.CustomLoggerExtension',
 # ]
 
 # ============================== 日志配置 ==============================
-
 LOG_LEVEL = 'INFO'
+LOG_FILE = 'logs/{{project_name}}.log'
+LOG_ENCODING = 'utf-8'  # 明确指定日志文件编码
 STATS_DUMP = True
-LOG_FILE = f'logs/{{project_name}}.log'
-LOG_FORMAT = '%(asctime)s - [%(name)s] - %(levelname)s: %(message)s'
-LOG_ENCODING = 'utf-8'
+
+# ============================== 输出配置 ==============================
+OUTPUT_DIR = 'output'
+
+# ============================== Redis配置 ==============================
+REDIS_HOST = '127.0.0.1'
+REDIS_PORT = 6379
+REDIS_PASSWORD = ''
+REDIS_DB = 0
+
+# 根据是否有密码生成 URL
+if REDIS_PASSWORD:
+    REDIS_URL = f'redis://:{REDIS_PASSWORD}@{REDIS_HOST}:{REDIS_PORT}/{REDIS_DB}'
+else:
+    REDIS_URL = f'redis://{REDIS_HOST}:{REDIS_PORT}/{REDIS_DB}'
+
+# ============================== MySQL配置 ==============================
+MYSQL_HOST = '127.0.0.1'
+MYSQL_PORT = 3306
+MYSQL_USER = 'root'
+MYSQL_PASSWORD = '123456'
+MYSQL_DB = '{{project_name}}'
+MYSQL_TABLE = '{{project_name}}_data'
+MYSQL_BATCH_SIZE = 100
+MYSQL_USE_BATCH = False  # 是否启用批量插入
+
+# ============================== MongoDB配置 ==============================
+MONGO_URI = 'mongodb://localhost:27017'
+MONGO_DATABASE = '{{project_name}}_db'
+MONGO_COLLECTION = '{{project_name}}_items'
+MONGO_MAX_POOL_SIZE = 200
+MONGO_MIN_POOL_SIZE = 20
+MONGO_BATCH_SIZE = 100  # 批量插入条数
+MONGO_USE_BATCH = False  # 是否启用批量插入
+
+# ============================== 代理配置 ==============================
+# 代理功能默认不启用，如需使用请在项目配置文件中启用并配置相关参数
+PROXY_ENABLED = False  # 是否启用代理
+
+# 简化版代理配置（适用于SimpleProxyMiddleware）
+PROXY_LIST = []  # 代理列表，例如: ["http://proxy1:8080", "http://proxy2:8080"]
+
+# 高级代理配置（适用于ProxyMiddleware）
+PROXY_API_URL = ""  # 代理获取接口（请替换为真实地址）
+
+# 代理提取方式（支持字段路径或函数）
+# 示例: "proxy" 适用于 {"proxy": "http://1.1.1.1:8080"}
+# 示例: "data.proxy" 适用于 {"data": {"proxy": "http://1.1.1.1:8080"}}
+PROXY_EXTRACTOR = "proxy"
+
+# 代理刷新控制
+PROXY_REFRESH_INTERVAL = 60  # 代理刷新间隔（秒）
+PROXY_API_TIMEOUT = 10  # 请求代理 API 超时时间
+
+# ============================== Curl-Cffi 特有配置 ==============================
+# 浏览器指纹模拟（仅 CurlCffi 下载器有效）
+CURL_BROWSER_TYPE = "chrome"  # 可选: chrome, edge, safari, firefox 或版本如 chrome136
+
+# 自定义浏览器版本映射（可覆盖默认行为）
+CURL_BROWSER_VERSION_MAP = {
+    "chrome": "chrome136",
+    "edge": "edge101",
+    "safari": "safari184",
+    "firefox": "firefox135",
+}
+
+# ============================== 下载器优化配置 ==============================
+# 下载器健康检查
+DOWNLOADER_HEALTH_CHECK = True  # 是否启用下载器健康检查
+HEALTH_CHECK_INTERVAL = 60  # 健康检查间隔（秒）
+
+# 请求统计配置
+REQUEST_STATS_ENABLED = True  # 是否启用请求统计
+STATS_RESET_ON_START = False  # 启动时是否重置统计
+
+# HttpX 下载器专用配置
+HTTPX_HTTP2 = True  # 是否启用HTTP/2支持
+HTTPX_FOLLOW_REDIRECTS = True  # 是否自动跟随重定向
+
+# AioHttp 下载器专用配置
+AIOHTTP_AUTO_DECOMPRESS = True  # 是否自动解压响应
+AIOHTTP_FORCE_CLOSE = False  # 是否强制关闭连接
+
+# 通用优化配置
+CONNECTION_TTL_DNS_CACHE = 300  # DNS缓存TTL（秒）
+CONNECTION_KEEPALIVE_TIMEOUT = 15  # Keep-Alive超时（秒）
+
+# ============================== 内存监控配置 ==============================
+# 内存监控扩展默认不启用，如需使用请在项目配置文件中启用
+MEMORY_MONITOR_ENABLED = False  # 是否启用内存监控
+MEMORY_MONITOR_INTERVAL = 60  # 内存监控检查间隔（秒）
+MEMORY_WARNING_THRESHOLD = 80.0  # 内存使用率警告阈值（百分比）
+MEMORY_CRITICAL_THRESHOLD = 90.0  # 内存使用率严重阈值（百分比）

crawlo/templates/project/spiders/__init__.py.tmpl

@@ -3,4 +3,8 @@
 {{project_name}}.spiders
 ========================
 存放所有的爬虫。
-"""
+"""
+
+# 自动导入所有爬虫以确保它们被注册
+# 示例：
+# from .YourSpider import YourSpider

crawlo/templates/run.py.tmpl

@@ -1,9 +1,12 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 # -*- coding: UTF-8 -*-
 """
 {{project_name}} 项目运行脚本
 ============================
 基于 Crawlo 框架的简化爬虫启动器。
+
+框架会自动处理爬虫模块的导入和注册，用户无需手动导入。
+只需指定spider_modules参数，框架会自动扫描并导入所有爬虫。
 """
 import sys
 import asyncio
@@ -12,22 +15,15 @@ from crawlo.crawler import CrawlerProcess
 
 
 def main():
-    """主函数：运行固定的爬虫"""
-    print("🚀 启动 {{project_name}} 爬虫")
-    
-    # 创建爬虫进程（自动加载默认配置）
+    """主函数：运行爬虫"""
     try:
-        # 确保 spider 模块被正确导入
+        # 指定爬虫模块路径，框架会自动导入并注册所有爬虫
         spider_modules = ['{{project_name}}.spiders']
         process = CrawlerProcess(spider_modules=spider_modules)
-        print("✅ 爬虫进程初始化成功")
-        
-        # 运行固定的爬虫
-        # TODO: 请将 'your_spider_name' 替换为实际的爬虫名称
-        asyncio.run(process.crawl('your_spider_name'))
-        
-        print("✅ 爬虫运行完成")
-        
+
+        # 运行指定的爬虫
+        asyncio.run(process.crawl('{{spider_name}}'))
+
     except Exception as e:
         print(f"❌ 运行失败: {e}")
         import traceback

crawlo/templates/spiders_init.py.tmpl

@@ -0,0 +1,10 @@
+# -*- coding: UTF-8 -*-
+"""
+{{project_name}}.spiders
+========================
+存放所有的爬虫。
+
+该文件支持自动导入所有爬虫模块，确保爬虫能被正确注册。
+框架会自动扫描并导入此目录下的所有Python文件（除了__init__.py）。
+"""
+# 框架会自动处理爬虫模块的导入，无需手动导入

crawlo/tools/network_diagnostic.py

@@ -0,0 +1,365 @@
+#!/usr/bin/python
+# -*- coding: UTF-8 -*-
+"""
+网络诊断工具
+提供网络连接问题的诊断和解决方案
+"""
+
+import asyncio
+import socket
+import time
+from typing import Dict, List, Optional, Tuple
+from urllib.parse import urlparse
+
+import aiohttp
+from crawlo.utils.log import get_logger
+
+
+class NetworkDiagnostic:
+    """网络诊断工具类"""
+    
+    def __init__(self):
+        self.logger = get_logger(self.__class__.__name__)
+        self._dns_cache: Dict[str, str] = {}
+    
+    async def diagnose_url(self, url: str) -> Dict[str, any]:
+        """
+        诊断URL的网络连接问题
+        
+        Args:
+            url: 要诊断的URL
+            
+        Returns:
+            诊断结果字典
+        """
+        parsed = urlparse(url)
+        hostname = parsed.hostname
+        port = parsed.port or (443 if parsed.scheme == 'https' else 80)
+        
+        result = {
+            'url': url,
+            'hostname': hostname,
+            'port': port,
+            'dns_resolution': None,
+            'tcp_connection': None,
+            'http_response': None,
+            'recommendations': []
+        }
+        
+        # DNS解析测试
+        dns_result = await self._test_dns_resolution(hostname)
+        result['dns_resolution'] = dns_result
+        
+        if dns_result['success']:
+            # TCP连接测试
+            tcp_result = await self._test_tcp_connection(hostname, port)
+            result['tcp_connection'] = tcp_result
+            
+            if tcp_result['success']:
+                # HTTP响应测试
+                http_result = await self._test_http_response(url)
+                result['http_response'] = http_result
+        
+        # 生成建议
+        result['recommendations'] = self._generate_recommendations(result)
+        
+        return result
+    
+    async def _test_dns_resolution(self, hostname: str) -> Dict[str, any]:
+        """测试DNS解析"""
+        try:
+            start_time = time.time()
+            
+            # 使用asyncio的DNS解析
+            loop = asyncio.get_event_loop()
+            addr_info = await loop.getaddrinfo(hostname, None)
+            
+            resolution_time = time.time() - start_time
+            ip_addresses = list(set([addr[4][0] for addr in addr_info]))
+            
+            # 缓存DNS结果
+            if ip_addresses:
+                self._dns_cache[hostname] = ip_addresses[0]
+            
+            return {
+                'success': True,
+                'ip_addresses': ip_addresses,
+                'resolution_time': resolution_time,
+                'error': None
+            }
+            
+        except socket.gaierror as e:
+            return {
+                'success': False,
+                'ip_addresses': [],
+                'resolution_time': None,
+                'error': {
+                    'type': 'DNSError',
+                    'code': e.errno,
+                    'message': str(e)
+                }
+            }
+        except Exception as e:
+            return {
+                'success': False,
+                'ip_addresses': [],
+                'resolution_time': None,
+                'error': {
+                    'type': type(e).__name__,
+                    'message': str(e)
+                }
+            }
+    
+    async def _test_tcp_connection(self, hostname: str, port: int) -> Dict[str, any]:
+        """测试TCP连接"""
+        try:
+            start_time = time.time()
+            
+            # 尝试TCP连接
+            reader, writer = await asyncio.wait_for(
+                asyncio.open_connection(hostname, port),
+                timeout=10.0
+            )
+            
+            connection_time = time.time() - start_time
+            
+            # 关闭连接
+            writer.close()
+            await writer.wait_closed()
+            
+            return {
+                'success': True,
+                'connection_time': connection_time,
+                'error': None
+            }
+            
+        except asyncio.TimeoutError:
+            return {
+                'success': False,
+                'connection_time': None,
+                'error': {
+                    'type': 'TimeoutError',
+                    'message': 'Connection timeout'
+                }
+            }
+        except Exception as e:
+            return {
+                'success': False,
+                'connection_time': None,
+                'error': {
+                    'type': type(e).__name__,
+                    'message': str(e)
+                }
+            }
+    
+    async def _test_http_response(self, url: str) -> Dict[str, any]:
+        """测试HTTP响应"""
+        try:
+            start_time = time.time()
+            
+            timeout = aiohttp.ClientTimeout(total=30, connect=10)
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.get(url) as response:
+                    response_time = time.time() - start_time
+                    
+                    return {
+                        'success': True,
+                        'url': url,
+                        'status_code': response.status_code,  # 修复：使用status_code而不是status
+                        'response_time': response_time,
+                        'content_length': len(response.body) if response.body else 0,
+                        'headers': dict(response.headers)
+                    }
+                    
+        except aiohttp.ClientError as e:
+            return {
+                'success': False,
+                'status_code': None,
+                'response_time': None,
+                'headers': {},
+                'error': {
+                    'type': type(e).__name__,
+                    'message': str(e)
+                }
+            }
+        except Exception as e:
+            return {
+                'success': False,
+                'status_code': None,
+                'response_time': None,
+                'headers': {},
+                'error': {
+                    'type': type(e).__name__,
+                    'message': str(e)
+                }
+            }
+    
+    def _generate_recommendations(self, result: Dict[str, any]) -> List[str]:
+        """根据诊断结果生成建议"""
+        recommendations = []
+        
+        dns_result = result.get('dns_resolution', {})
+        tcp_result = result.get('tcp_connection', {})
+        http_result = result.get('http_response', {})
+        
+        # DNS问题建议
+        if not dns_result.get('success'):
+            error = dns_result.get('error', {})
+            if error.get('code') == 8:  # nodename nor servname provided, or not known
+                recommendations.extend([
+                    "DNS解析失败 - 检查域名是否正确",
+                    "检查网络连接是否正常",
+                    "尝试使用不同的DNS服务器（如8.8.8.8或1.1.1.1）",
+                    "检查本地hosts文件是否有相关配置",
+                    "确认域名是否可以从外部访问"
+                ])
+            elif error.get('code') == 2:  # Name or service not known
+                recommendations.extend([
+                    "域名不存在或无法解析",
+                    "检查域名拼写是否正确",
+                    "确认域名是否已注册且配置了DNS记录"
+                ])
+        
+        # TCP连接问题建议
+        elif not tcp_result.get('success'):
+            error = tcp_result.get('error', {})
+            if error.get('type') == 'TimeoutError':
+                recommendations.extend([
+                    "TCP连接超时 - 服务器可能无响应",
+                    "检查防火墙设置是否阻止了连接",
+                    "尝试增加连接超时时间",
+                    "检查代理设置"
+                ])
+        
+        # HTTP问题建议
+        elif not http_result.get('success'):
+            error = http_result.get('error', {})
+            recommendations.extend([
+                f"HTTP请求失败: {error.get('message', 'Unknown error')}",
+                "检查URL是否正确",
+                "确认服务器是否正常运行"
+            ])
+        
+        # 性能建议
+        if dns_result.get('success') and dns_result.get('resolution_time', 0) > 1.0:
+            recommendations.append("DNS解析时间较长，考虑使用DNS缓存或更快的DNS服务器")
+        
+        if tcp_result.get('success') and tcp_result.get('connection_time', 0) > 2.0:
+            recommendations.append("TCP连接时间较长，可能存在网络延迟问题")
+        
+        if http_result.get('success') and http_result.get('response_time', 0) > 5.0:
+            recommendations.append("HTTP响应时间较长，服务器可能负载较高")
+        
+        return recommendations
+    
+    async def batch_diagnose(self, urls: List[str]) -> Dict[str, Dict[str, any]]:
+        """批量诊断多个URL"""
+        tasks = []
+        for url in urls:
+            task = asyncio.create_task(self.diagnose_url(url))
+            tasks.append((url, task))
+        
+        results = {}
+        for url, task in tasks:
+            try:
+                result = await task
+                results[url] = result
+            except Exception as e:
+                results[url] = {
+                    'url': url,
+                    'error': f"诊断过程出错: {e}",
+                    'recommendations': ["诊断工具本身出现问题，请检查网络环境"]
+                }
+        
+        return results
+    
+    def format_diagnostic_report(self, result: Dict[str, any]) -> str:
+        """格式化诊断报告"""
+        lines = [
+            f"=== 网络诊断报告 ===",
+            f"URL: {result['url']}",
+            f"主机: {result['hostname']}:{result['port']}",
+            ""
+        ]
+        
+        # DNS解析结果
+        dns = result.get('dns_resolution', {})
+        if dns.get('success'):
+            lines.extend([
+                "✅ DNS解析: 成功",
+                f"   IP地址: {', '.join(dns['ip_addresses'])}",
+                f"   解析时间: {dns['resolution_time']:.3f}秒"
+            ])
+        else:
+            error = dns.get('error', {})
+            lines.extend([
+                "❌ DNS解析: 失败",
+                f"   错误类型: {error.get('type', 'Unknown')}",
+                f"   错误信息: {error.get('message', 'Unknown error')}"
+            ])
+        
+        lines.append("")
+        
+        # TCP连接结果
+        tcp = result.get('tcp_connection', {})
+        if tcp and tcp.get('success'):
+            lines.extend([
+                "✅ TCP连接: 成功",
+                f"   连接时间: {tcp['connection_time']:.3f}秒"
+            ])
+        elif tcp:
+            error = tcp.get('error', {})
+            lines.extend([
+                "❌ TCP连接: 失败",
+                f"   错误类型: {error.get('type', 'Unknown')}",
+                f"   错误信息: {error.get('message', 'Unknown error')}"
+            ])
+        
+        lines.append("")
+        
+        # HTTP响应结果
+        http = result.get('http_response', {})
+        if http and http.get('success'):
+            lines.extend([
+                "✅ HTTP响应: 成功",
+                f"   状态码: {http['status_code']}",
+                f"   响应时间: {http['response_time']:.3f}秒"
+            ])
+        elif http:
+            error = http.get('error', {})
+            lines.extend([
+                "❌ HTTP响应: 失败",
+                f"   错误类型: {error.get('type', 'Unknown')}",
+                f"   错误信息: {error.get('message', 'Unknown error')}"
+            ])
+        
+        # 建议
+        recommendations = result.get('recommendations', [])
+        if recommendations:
+            lines.extend([
+                "",
+                "🔧 建议:",
+            ])
+            for i, rec in enumerate(recommendations, 1):
+                lines.append(f"   {i}. {rec}")
+        
+        return "\n".join(lines)
+
+
+# 便捷函数
+async def diagnose_url(url: str) -> Dict[str, any]:
+    """诊断单个URL的网络问题"""
+    diagnostic = NetworkDiagnostic()
+    return await diagnostic.diagnose_url(url)
+
+
+async def diagnose_urls(urls: List[str]) -> Dict[str, Dict[str, any]]:
+    """批量诊断URL的网络问题"""
+    diagnostic = NetworkDiagnostic()
+    return await diagnostic.batch_diagnose(urls)
+
+
+def format_report(result: Dict[str, any]) -> str:
+    """格式化诊断报告"""
+    diagnostic = NetworkDiagnostic()
+    return diagnostic.format_diagnostic_report(result)