From fc249591f7ac12fed71dac6d6605e6c63b7915e0 Mon Sep 17 00:00:00 2001 From: WpyQwq <3911625973@qq.com> Date: Sat, 11 Apr 2026 13:50:23 +0800 Subject: [PATCH] Update README.md --- README.md | 285 ++++++++++++++++++++++++++---------------------------- 1 file changed, 139 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index 6159587..8067705 100644 --- a/README.md +++ b/README.md @@ -1,151 +1,144 @@ -Air2: High-Performance Download Engine -Air2 is a high-performance, multi-threaded download manager written in Python. It focuses on maximizing download speed through ultra-high concurrency, dynamic chunking strategies, and support for multiple protocols including HTTP/HTTPS, SFTP, and extensible architectures for BitTorrent. The tool provides both an interactive command-line interface (CLI) with modern visual feedback and a scriptable mode for automation. -Features -High Concurrency: Optimized thread pool supporting up to 200 concurrent workers to maximize bandwidth usage. -Dynamic Chunking: Automatically adjusts chunk sizes based on file size to optimize throughput and reduce overhead. -Multi-Protocol Support: Native support for HTTP/HTTPS and SFTP; architecture designed for easy addition of BitTorrent and other protocols. -Robust Resume Capability: Handles Range requests efficiently to ensure zero data loss during network interruptions. -Modern CLI Interface: Built with the rich library for real-time progress bars, speed meters, and ETA calculations without clutter. -Intelligent Input: Optional integration with prompt_toolkit for command auto-completion, history navigation, and syntax highlighting. -Task Management: Full lifecycle control including add, start, pause, resume, cancel, remove, and automatic ZIP extraction. -Speed Limiting: Configurable download speed limits to prevent network congestion. -Single File Deployment: Designed as a single executable script for easy distribution and deployment. -Installation -Ensure you have Python 3.8 or higher installed. Install the required dependencies: -bash -1 -Note: prompt_toolkit is optional but recommended for enhanced command-line features like auto-completion. -Usage -Interactive Mode -Run the script directly to enter the interactive shell: -bash -1 -Available Commands: -help: Display command list and help text. -add [options]: Add a new download task. -start : Start a waiting task. -pause : Pause a running task. -resume : Resume a paused task. -cancel : Cancel a task (keeps downloaded files). -remove [--delete]: Remove a task and optionally delete the file. -unzip [output_dir]: Extract completed ZIP files. -list / ls: Show all tasks and their status. -status: Display system statistics and overall progress. -exit / quit: Close the application. -Example: -text -1234 -Command Line Mode (Scripting) -You can also run commands directly from the terminal without entering the interactive shell: -bash -1234567891011 -Options for add Command ---threads=N: Number of concurrent threads (default: 8). ---output=DIR: Destination directory (default: current directory). ---chunk-size=S: Force specific chunk size (e.g., 10M, 1G). Defaults to dynamic calculation. ---speed-limit=N: Limit download speed in KB/s (0 for unlimited). ---timeout=N: Request timeout in seconds. ---retry=N: Number of retry attempts on failure. -Architecture -The codebase is structured into distinct modules for maintainability: -DownloadEngine: Manages the core logic, including task queues, thread pools, and state synchronization. -ChunkDownloader: Handles individual block retrieval, error recovery, and checksum verification. -ProtocolHandler: Abstract base class for different protocols (HTTP, SFTP, etc.), allowing easy extension. -ModernCLI: Provides the user interface layer using rich and prompt_toolkit. -Configuration -The engine automatically detects file sizes and adjusts chunk counts. For large files (>1GB), it increases chunk size to 16MB; for medium files (>100MB), it uses 4MB chunks. This dynamic approach minimizes connection overhead while maintaining high parallelism. -Users can override these defaults via command-line arguments if specific network conditions require manual tuning. -License -This project is licensed under the MIT License. -Requirements -Python 3.8+ -requests -rich -urllib3 -prompt_toolkit (optional) -README.md格式，中英混 +Air2 - 高性能多线程下载引擎 +Air2 是一个用 Python 编写的高性能命令行下载工具，支持多线程分块下载、断点续传、速度限制和美观的实时进度显示。它提供交互式命令行界面和单命令快速执行两种模式，兼顾易用性与强大性能。 -Air2: High-Performance Download Engine -Air2 是一个基于 Python 开发的高性能多线程下载管理器。它专注于通过超高并发、动态分块策略以及多协议支持（HTTP/HTTPS, SFTP, BitTorrent）来最大化下载速度。该工具提供现代化的交互式命令行界面 (CLI) 和便于脚本自动化的命令行模式。 -Features / 核心功能 -High Concurrency / 超高并发: Optimized thread pool supporting up to 200 concurrent workers to maximize bandwidth usage. (优化的线程池，支持多达 200 个并发工作线程以最大化带宽利用率。) -Dynamic Chunking / 动态分块: Automatically adjusts chunk sizes based on file size to optimize throughput and reduce overhead. (根据文件大小自动调整分块大小，优化吞吐量并减少开销。) -Multi-Protocol Support / 多协议支持: Native support for HTTP/HTTPS and SFTP; architecture designed for easy addition of BitTorrent and other protocols. (原生支持 HTTP/HTTPS 和 SFTP；架构设计便于扩展 BitTorrent 及其他协议。) -Robust Resume Capability / 强大的断点续传: Handles Range requests efficiently to ensure zero data loss during network interruptions. (高效处理 Range 请求，确保网络中断时零数据丢失。) -Modern CLI Interface / 现代化 CLI 界面: Built with the rich library for real-time progress bars, speed meters, and ETA calculations without clutter. (基于 rich 库构建，提供实时进度条、速度计和预计剩余时间计算，界面简洁。) -Intelligent Input / 智能输入: Optional integration with prompt_toolkit for command auto-completion, history navigation, and syntax highlighting. (可选集成 prompt_toolkit，支持命令自动补全、历史记录导航和语法高亮。) -Task Management / 任务管理: Full lifecycle control including add, start, pause, resume, cancel, remove, and automatic ZIP extraction. (完整的全生命周期控制，包括添加、启动、暂停、恢复、取消、移除及自动 ZIP 解压。) -Speed Limiting / 限速控制: Configurable download speed limits to prevent network congestion. (可配置的下载速度限制，防止网络拥塞。) -Single File Deployment / 单文件部署: Designed as a single executable script for easy distribution and deployment. (设计为单执行脚本，便于分发和部署。) -Installation / 安装 -Ensure you have Python 3.8 or higher installed. Install the required dependencies: -请确保已安装 Python 3.8 或更高版本。安装所需依赖： +✨ 主要优点 (中文) +1. 🚀 极致下载速度 +智能多线程分块：根据文件大小动态调整分块数量与大小（最大支持 16 MB 块），充分利用带宽资源。 + +大缓冲区优化：单次写入使用 1 MB 缓冲区，减少磁盘 I/O 开销。 + +高并发连接池：每个任务支持多达 16 个并发连接，线程池可容纳 200 个工作线程，大幅提升大文件下载效率。 + +2. 🛠️ 完善的断点续传与错误恢复 +支持从已下载的部分继续下载，避免重复传输。 + +内置智能重试机制（指数退避），对网络波动、临时服务器错误自动恢复。 + +下载前预分配文件空间，减少磁盘碎片并提高写入稳定性。 + +3. 📊 美观且实时的进度反馈 +基于 Rich 库构建的终端界面，提供彩色进度条、实时速度、预计剩余时间等关键信息。 + +支持多任务并行下载时独立显示每个任务的进度，一目了然。 + +速度计算采用平滑算法，避免数据剧烈跳动。 + +4. 💻 两种使用模式，灵活高效 +交互式命令行 (CLI)：输入 air2 进入专属 Shell，支持命令补全（需 prompt_toolkit）、历史记录、快捷键操作。 + +单命令直接执行：如 air2 add 可直接添加并开始下载，适合脚本调用或一次性任务。 + +5. 🔧 丰富的功能选项 +可自定义线程数、输出目录、分块大小、速度限制、超时时间等。 + +内置 ZIP 解压功能，下载完成后可一键解压。 + +任务管理完善：暂停、恢复、取消、移除（可选删除文件）均支持。 + +6. 📦 轻量依赖，易于部署 +仅依赖 requests、urllib3、rich 等少量第三方库，安装简单。 + +支持 Python 3.7+，跨平台运行（Windows / macOS / Linux）。 + +✨ Key Advantages (English) +1. 🚀 Blazing Fast Downloads +Intelligent Multi-threaded Chunking: Dynamically adjusts chunk count and size (up to 16 MB per chunk) based on file size to fully saturate network bandwidth. + +Large Buffer Optimization: Uses a 1 MB write buffer to minimize disk I/O overhead. + +High-Concurrency Connection Pool: Up to 16 connections per task and a 200-worker thread pool dramatically accelerate large file downloads. + +2. 🛠️ Robust Resume & Error Recovery +Seamless resume from interrupted downloads, avoiding redundant data transfer. + +Built-in exponential backoff retry mechanism handles transient network issues and server errors gracefully. + +File space pre-allocation reduces disk fragmentation and improves write stability. + +3. 📊 Beautiful, Real-Time Progress Feedback +A Rich-powered terminal interface featuring colored progress bars, live speed, ETA, and more. + +Multiple concurrent tasks are displayed independently with clear, organized status updates. + +Smoothed speed calculation prevents erratic display fluctuations. + +4. 💻 Dual-Mode Operation for Maximum Flexibility +Interactive CLI: Run air2 to enter a dedicated shell with command completion (via prompt_toolkit), history navigation, and keyboard shortcuts. + +Single-Command Execution: Use commands like air2 add directly for scripting or one-off tasks. + +5. 🔧 Extensive Feature Set +Fine-grained control over thread count, output directory, chunk size, speed limit, timeout, etc. + +Built-in ZIP extraction for immediate unpacking of downloaded archives. + +Full task lifecycle management: pause, resume, cancel, and remove (with optional file deletion). + +6. 📦 Lightweight & Cross-Platform +Minimal dependencies (requests, urllib3, rich), easy to install via pip. + +Compatible with Python 3.7+ and runs on Windows, macOS, and Linux. + +📦 安装 / Installation +基础安装 (Basic) bash -1 -Note: prompt_toolkit is optional but recommended for enhanced command-line features like auto-completion. -(注：prompt_toolkit 为可选依赖，但推荐使用以获得自动补全等增强功能。) -Usage / 使用方法 -Interactive Mode / 交互模式 -Run the script directly to enter the interactive shell: -直接运行脚本进入交互式 Shell： +pip install requests rich urllib3 +推荐安装 (增强体验 / Enhanced Experience) bash -1 -Available Commands / 可用命令: -Command -Description / 描述 -help -Display command list and help text. / 显示命令列表和帮助信息。 -add [options] -Add a new download task. / 添加新的下载任务。 -start -Start a waiting task. / 开始等待中的任务。 -pause -Pause a running task. / 暂停正在运行的任务。 -resume -Resume a paused task. / 恢复暂停的任务。 -cancel -Cancel a task (keeps downloaded files). / 取消任务（保留已下载文件）。 -remove [--delete] -Remove a task and optionally delete the file. / 移除任务并可选择删除文件。 -unzip [output_dir] -Extract completed ZIP files. / 解压已完成的 ZIP 文件。 -list / ls -Show all tasks and their status. / 显示所有任务及其状态。 -status -Display system statistics and overall progress. / 显示系统统计数据和总体进度。 -exit / quit -Close the application. / 关闭应用程序。 -Example / 示例: +pip install prompt_toolkit # 启用命令补全与历史记录 / Enables command completion & history +将 air2.py 放置于 PATH 目录下，或直接运行 python air2.py。 + +🕹️ 使用方法 / Usage +交互模式 (Interactive Mode) +直接运行程序进入交互式 Shell： + +bash +python air2.py +然后输入命令进行操作： + text -1234 -Command Line Mode / 命令行模式 (Scripting) -You can also run commands directly from the terminal without entering the interactive shell: -您也可以直接在终端运行命令，无需进入交互式 Shell： +add https://example.com/file.zip --threads=16 +start a1b2c3d4 +pause a1b2c3d4 +resume a1b2c3d4 +cancel a1b2c3d4 +remove a1b2c3d4 --delete +unzip a1b2c3d4 /path/to/extract +list +status +help +exit +命令行模式 (Command-Line Mode) +支持单条命令直接执行，无需进入交互界面： + bash -1234567891011 -Options for add Command / add 命令选项 ---threads=N: Number of concurrent threads (default: 8). / 并发线程数（默认：8）。 ---output=DIR: Destination directory (default: current directory). / 目标目录（默认：当前目录）。 ---chunk-size=S: Force specific chunk size (e.g., 10M, 1G). Defaults to dynamic calculation. / 强制指定分块大小（例如 10M, 1G）。默认为动态计算。 ---speed-limit=N: Limit download speed in KB/s (0 for unlimited). / 限制下载速度（KB/s），0 表示不限制。 ---timeout=N: Request timeout in seconds. / 请求超时时间（秒）。 ---retry=N: Number of retry attempts on failure. / 失败后的重试次数。 -Architecture / 架构 -The codebase is structured into distinct modules for maintainability: -代码库结构清晰，分为独立模块以便于维护： -DownloadEngine: Manages the core logic, including task queues, thread pools, and state synchronization. (管理核心逻辑，包括任务队列、线程池和状态同步。) -ChunkDownloader: Handles individual block retrieval, error recovery, and checksum verification. (处理单个块的检索、错误恢复和校验和验证。) -ProtocolHandler: Abstract base class for different protocols (HTTP, SFTP, etc.), allowing easy extension. (不同协议的抽象基类，便于扩展新协议。) -ModernCLI: Provides the user interface layer using rich and prompt_toolkit. (使用 rich 和 prompt_toolkit 提供用户界面层。) -Configuration / 配置 -The engine automatically detects file sizes and adjusts chunk counts. For large files (>1GB), it increases chunk size to 16MB; for medium files (>100MB), it uses 4MB chunks. This dynamic approach minimizes connection overhead while maintaining high parallelism. Users can override these defaults via command-line arguments if specific network conditions require manual tuning. -引擎会自动检测文件大小并调整分块数量。对于大文件（>1GB），分块大小会增加到 16MB；对于中等文件（>100MB），使用 4MB 分块。这种动态方法在保持高并行度的同时最小化了连接开销。如果特定的网络条件需要手动调整，用户可以通过命令行参数覆盖这些默认值。 -License / 许可 -This project is licensed under the MIT License. -本项目采用 MIT 许可证授权。 -Requirements / 环境要求 -Python 3.8+ -requests -rich -urllib3 -prompt_toolkit (optional) +# 添加并开始下载 +python air2.py add https://example.com/file.zip --threads=16 --output=./downloads + +# 开始已有任务 +python air2.py start a1b2c3d4 + +# 暂停任务 +python air2.py pause a1b2c3d4 + +# 列出所有任务 +python air2.py list + +# 解压已完成的 ZIP 任务 +python air2.py unzip a1b2c3d4 ./extracted +⚙️ 添加任务选项 / Task Options +选项 说明 (中文) Description (English) +--threads=N 下载线程数 (默认 8) Number of download threads (default 8) +--output=DIR 保存目录 (默认当前目录) Output directory (default current dir) +--chunk-size=SIZE 分块大小，支持 K/M/G 后缀 (如 10M) Chunk size with optional K/M/G suffix (e.g., 10M) +--speed-limit=KB 速度限制 (KB/s)，0 表示不限速 Speed limit in KB/s, 0 for unlimited +🗂️ 项目结构 / Project Structure +text +air2.py # 主程序文件 +air2.log # 运行日志 (自动生成) +~/.air2_history # 命令历史记录 (需 prompt_toolkit) +🤝 贡献与反馈 / Contributing +欢迎提交 Issue 和 Pull Request 来改进 Air2。遇到问题或有功能建议，请在 GitHub 仓库中留言。 + +📄 许可证 / License +本项目采用 MIT License 开源，欢迎自由使用和修改。