# littledl unified documentation bundle

This file merges the repository documentation into a single agent-friendly reference.
It is intended for tooling and LLM ingestion, so duplicated English/Chinese pages are consolidated into canonical topic sections instead of repeating the same guidance twice.

Scope included in this bundle:

- Project overviews: README.md, README.zh.md
- User docs: docs/en/** and docs/zh/**
- Project policy docs: CONTRIBUTING.md, CONTRIBUTING.zh.md, SECURITY.md, SECURITY.zh.md
- Release notes: CHANGELOG.md, CHANGELOG.zh.md
- Implementation map for source-oriented questions

Scope intentionally excluded:

- LICENSE
- GitHub issue/PR templates
- Generated cache/report markdown outside the maintained documentation set

## Project metadata

- Project: littledl
- Package import: littledl
- Package location: src/littledl
- Current version: 1.0.0
- Python requirement: 3.10+
- Primary interfaces: Python library and `littledl` CLI
- Supported platforms: Windows, macOS, Linux, FreeBSD
- Documentation languages: English and Simplified Chinese

## What littledl is

littledl is a high-performance file download library and CLI focused on single-file and batch downloads. It supports HTTP Range based chunked downloading, resume, adaptive scheduling, progress callbacks, authentication, proxy support, speed limiting, file reuse, and multi-source failover.

Core capabilities consolidated from the README and user guides:

- Multi-threaded segmented download using HTTP Range requests
- Automatic strategy selection based on file size, server capability, and network conditions
- Multiple download styles: single, multi, adaptive, fusion, hybrid_turbo
- Atomic file writing: chunked downloads land in a `.part` file (preallocated, positional writes serialized by a lock) and are atomically renamed to the final name on success; existing files are never destroyed mid-download
- Resume support for interrupted downloads
- Real-time speed, ETA, and progress reporting
- Automatic fallback to single-stream mode when chunked transfer is not viable
- Authentication support: Basic, Bearer, Digest, API key, OAuth2
- Proxy support: system proxy, custom HTTP/HTTPS proxy, SOCKS5
- Speed limiting with configurable modes
- Optional post-download hash verification
- Content-aware file reuse and batch multi-source backup URLs

## Documentation consolidation policy

The repository ships parallel English and Simplified Chinese docs for the same major topics:

- getting started
- configuration
- authentication
- proxy
- error handling
- advanced usage
- batch download
- CLI
- API reference
- README, CONTRIBUTING, SECURITY, CHANGELOG

For this single-file bundle, those parallel pages are de-duplicated into one canonical section per topic. If a translated page adds no extra technical detail beyond the English page, the content is merged once here.

## Installation

Install with pip:

```bash
pip install littledl
```

Install with uv:

```bash
uv add littledl
```

CLI availability check:

```bash
littledl --version
```

Expected version at the time of this bundle: `littledl 1.0.0`.

## Quick start

### Synchronous download

```python
from littledl import download_file_sync

path = download_file_sync("https://example.com/file.zip")
print(f"Downloaded to: {path}")
```

### Asynchronous download

```python
import asyncio
from littledl import download_file

async def main():
	path = await download_file(
		"https://example.com/file.zip",
		save_path="./downloads",
		filename="my_file.zip",
	)
	print(f"Downloaded to: {path}")

asyncio.run(main())
```

### Basic progress callback

Recommended event-style callback:

```python
from littledl import download_file_sync, ProgressEvent

def on_progress(event: ProgressEvent):
	print(f"[{event.filename}] {event.progress:.1f}% {event.speed / 1024 / 1024:.1f} MB/s")

download_file_sync("https://example.com/file.zip", progress_callback=on_progress)
```

Supported callback input styles:

- Event object: `ProgressEvent`
- Dictionary payload: `dict`
- Keyword payload: `**payload`
- Legacy positional form: `(downloaded, total, speed, eta)`

## Download styles

littledl supports five download styles plus one compatibility alias.

| Style | Meaning | Best fit |
| --- | --- | --- |
| `single` | Single-threaded download | Small files or servers without Range support |
| `multi` | Fixed multi-thread segmented download | Large files on stable connections |
| `adaptive` | Traditional adaptive scheduler | Older tuning workflows |
| `fusion` | Four-phase adaptive scheduler: PROBE -> RAMP -> CRUISE -> TAIL | Default and recommended mode |
| `hybrid_turbo` | Aggressive AIMD adaptive mode | Bursty or unstable networks |
| `auto` | Alias of `fusion` | Compatibility with older scripts |

Important style notes from the README, CLI guide, and advanced guide:

- FUSION is the default style.
- The CLI `auto` style is an alias of `fusion`.
- StrategySelector recommends FUSION for medium and large files.
- `apply_style()` accepts either `DownloadStyle` or style-name strings.
- A style only changes behavior if it is mapped into `DownloadConfig` or CLI options used by the downloader flow.

### Style examples

CLI:

```bash
littledl "https://example.com/file.zip"
littledl "https://example.com/file.zip" -s single
littledl "https://example.com/file.zip" -s fusion -c 16
littledl "https://example.com/file.zip" -s hybrid_turbo -c 32
```

Python:

```python
from littledl import DownloadConfig, DownloadStyle

config = DownloadConfig().apply_style(DownloadStyle.FUSION)
```

## CLI reference

The `littledl` command supports single-file downloads, multiple direct URLs, and batch input from a file.

### Basic commands

Single file:

```bash
littledl "https://example.com/large-file.zip" -o ./downloads
```

Multiple direct URLs:

```bash
littledl "https://example.com/file1.zip" "https://example.com/file2.pdf" -o ./downloads
```

Batch file mode:

```text
# comments allowed
https://example.com/file1.zip
https://example.com/file2.pdf
https://example.com/file3.doc
```

```bash
littledl -F urls.txt -o ./downloads
```

### Common options

| Option | Meaning | Default |
| --- | --- | --- |
| `-o, --output PATH` | Output directory or file path | `./downloads` |
| `-f, --filename NAME` | Explicit output filename | Server provided |
| `-c, --max-chunks N` | Maximum parallel chunks | `16` |
| `-t, --timeout SECONDS` | Request timeout | `300` |
| `--proxy URL` | HTTP proxy | none |
| `--speed-limit BYTES/s` | Speed cap | unlimited |
| `--retry N` | Retry attempts | `3` |
| `--temp-dir PATH` | Temporary file directory | same as output |
| `-v, --verbose` | Verbose output | disabled |
| `-q, --quiet` | Minimal output | disabled |
| `-i, --info` | Show file info / analysis without downloading | disabled |
| `-F, --batch-file` | Read URLs from a file | none |
| `--max-concurrent` | Batch file concurrency | adaptive or configured |
| `--output-format {auto,json,text}` | Output mode | `auto` |

### Output modes

- `auto`: text for TTY, JSON for piped or scripted use
- `text`: human-readable output
- `json`: structured output for integrations

Example JSON output fields:

- single download: success, path, size
- batch download: total, completed, failed, total_bytes, elapsed_seconds, average_speed, tasks[]

### Progress display behavior

- TTY: animated progress bar and live stats
- non-interactive stdout: reduced machine-friendly output
- Rich-powered enhanced batch display is available, with graceful fallback to plain text

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | General error |
| `2` | URL error or invalid argument |
| `3` | Download failed after retries |
| `4` | Cancelled by user |

### CLI analysis mode

Use `--info` to inspect a resource before downloading. Typical output includes:

- filename
- size
- content type
- resume support
- recommended style
- recommended chunks
- estimated speedup

### CLI environment variables

- `LANG`: language selection, for example `zh_CN` or `en_US`
- standard proxy variables are also respected, described in the proxy section

## Library API overview

### Core functions

Synchronous download:

```python
from littledl import download_file_sync

path = download_file_sync(
	url,
	save_path=".",
	filename=None,
	config=None,
	progress_callback=None,
	chunk_callback=None,
)
```

Asynchronous download:

```python
from littledl import download_file

path = await download_file(
	url,
	save_path=".",
	filename=None,
	config=None,
	progress_callback=None,
	chunk_callback=None,
)
```

### DownloadConfig

Main configuration model used by single-file and batch download flows.

Representative initialization:

```python
from littledl import DownloadConfig

config = DownloadConfig(
	enable_chunking=True,
	max_chunks=16,
	chunk_size=4 * 1024 * 1024,
	buffer_size=64 * 1024,
	timeout=300,
	resume=True,
	verify_ssl=True,
)
```

Key options consolidated from README, configuration guide, advanced docs, and API reference:

| Option | Type | Default | Meaning |
| --- | --- | --- | --- |
| `enable_chunking` | bool | True | Enable segmented download |
| `max_chunks` | int | 16 | Maximum concurrent chunks |
| `chunk_size` | int | 4 MB | Default chunk size |
| `buffer_size` | int | 64 KB | Write buffer size |
| `timeout` | float | 300 | Read/write timeout in seconds |
| `resume` | bool | True | Enable resume support |
| `verify_ssl` | bool | True | Verify certificates |
| `fallback_to_single_on_failure` | bool | True | Fallback to single-stream mode |
| `enable_adaptive` | bool | True | Enable adaptive scheduling |
| `enable_hybrid_turbo` | bool | True | Enable hybrid turbo AIMD mode |
| `enable_fusion` | bool | True | Enable FUSION scheduler |
| `fusion_probe_chunks` | int | 2 | Initial PROBE workers |
| `fusion_probe_duration` | float | 2.0 | Upper bound on PROBE duration; PROBE advances to RAMP after one speed sample once `min(this, adaptive_interval)` elapses |
| `fusion_tail_ratio` | float | 0.20 | Remaining ratio to enter TAIL |
| `fusion_tail_boost` | int | 2 | Extra workers allowed in TAIL |
| `hybrid_aimd_increase_step` | int | 1 | AIMD additive increase step |
| `hybrid_aimd_decrease_factor` | float | 0.5 | AIMD multiplicative decrease factor |
| `hybrid_speedup_threshold` | float | 0.08 | Minimum relative gain to keep scaling |
| `hybrid_slow_chunk_ratio` | float | 0.45 | Threshold for very slow chunks |
| `verify_hash` | bool | False | Validate file hash after download |
| `expected_hash` | str | None | Expected hash string |
| `hash_algorithm` | str | `sha256` | Hash algorithm |
| `min_file_size` | int | None | Reject too-small files |
| `max_file_size` | int | None | Reject too-large files |
| `progress_update_interval` | float | 0.5 | Callback emission interval |
| `auth` | AuthConfig | None | Authentication settings |
| `proxy` | ProxyConfig | None | Proxy settings |
| `speed_limit` | SpeedLimitConfig | None | Speed-limiting settings |
| `progress_callback` | Callable | None | File progress callback |
| `chunk_callback` | Callable | None | Chunk status callback |

### Important DownloadConfig methods

`apply_style(style)`:

- Reconfigures scheduling, chunking thresholds, and adaptive parameters from a named style.
- Accepts either `DownloadStyle` or a style string such as `"FUSION"`.

`create_file_config(...)`:

- Creates a per-file config cloned from the parent config.
- Used by batch downloaders so auth, proxy, retry, FUSION tuning, resplit settings, and speed limits are preserved while per-file chunk counts are overridden.

## Authentication

Authentication is configured with `AuthConfig` and `AuthType`.

Supported types:

- BASIC
- BEARER
- DIGEST
- API_KEY
- OAUTH2

Examples:

Basic auth:

```python
from littledl import AuthConfig, AuthType

auth = AuthConfig(
	auth_type=AuthType.BASIC,
	username="user",
	password="pass",
)
```

Bearer token:

```python
auth = AuthConfig(
	auth_type=AuthType.BEARER,
	token="your-api-token",
)
```

API key:

```python
auth = AuthConfig(
	auth_type=AuthType.API_KEY,
	api_key="your-api-key",
	api_key_header="X-API-Key",
)
```

Digest auth:

```python
auth = AuthConfig(
	auth_type=AuthType.DIGEST,
	username="user",
	password="pass",
)
```

OAuth2:

```python
auth = AuthConfig(
	auth_type=AuthType.OAUTH2,
	client_id="client-id",
	client_secret="client-secret",
	token_url="https://example.com/oauth/token",
)
```

Use with DownloadConfig:

```python
from littledl import DownloadConfig

config = DownloadConfig(auth=auth)
```

## Proxy configuration

Proxy support is configured with `ProxyConfig` and `ProxyMode`.

Proxy modes:

- `SYSTEM`: detect and use system proxy settings
- `CUSTOM`: explicit proxy values
- `NONE`: disable proxy use

Examples:

System proxy:

```python
from littledl import ProxyConfig, ProxyMode

proxy = ProxyConfig(mode=ProxyMode.SYSTEM)
```

Custom HTTP/HTTPS proxy:

```python
proxy = ProxyConfig(
	mode=ProxyMode.CUSTOM,
	http_proxy="http://proxy.example.com:8080",
	https_proxy="https://proxy.example.com:8080",
)
```

SOCKS5:

```python
proxy = ProxyConfig(
	mode=ProxyMode.CUSTOM,
	socks5_proxy="socks5://user:pass@proxy.example.com:1080",
)
```

Environment variables respected:

- `HTTP_PROXY` / `http_proxy`
- `HTTPS_PROXY` / `https_proxy`
- `SOCKS_PROXY` / `socks_proxy`
- `NO_PROXY` / `no_proxy`

## Speed limiting

Use `SpeedLimitConfig` with `SpeedLimitMode`.

Representative example:

```python
from littledl import DownloadConfig, SpeedLimitConfig, SpeedLimitMode

speed_limit = SpeedLimitConfig(
	enabled=True,
	mode=SpeedLimitMode.GLOBAL,
	max_speed=1024 * 1024,
)

config = DownloadConfig(speed_limit=speed_limit)
```

Modes:

- `GLOBAL`: cap total download speed
- `PER_CHUNK`: cap each chunk independently

## Progress and callback model

### Single-file callbacks

Supported input styles:

- `ProgressEvent`
- `dict`
- `**payload`
- legacy positional arguments

`ProgressEvent` fields include:

- downloaded
- total
- speed
- eta
- progress
- remaining
- timestamp
- unknown_size
- filename
- url

### Chunk callbacks

Chunk mode emits `ChunkEvent` containing:

- chunk_index
- status
- downloaded
- total
- progress
- speed
- error
- timestamp

### Unified callback system

The callback subsystem also exposes richer event types for custom download managers and UI layers.

Important event categories:

- FILE_PROGRESS
- FILE_COMPLETE
- FILE_ERROR
- FILE_RETRY
- BATCH_PROGRESS
- BATCH_COMPLETE
- CHUNK_PROGRESS
- CHUNK_COMPLETE
- CHUNK_ERROR

Important exported callback helpers:

- `UnifiedCallbackAdapter`
- `ThrottledCallback`
- `CallbackChain`
- `ProgressAggregator`
- `detect_callback_mode`

Representative rich event types:

- `FileProgressEvent`
- `FileCompleteEvent`
- `BatchProgressEvent`
- `ChunkProgressEvent`

Callback helper behavior from docs and changelog:

- `ProgressEvent` now includes `filename` and `url`
- batch callbacks now standardize on `BatchProgress`
- adapters auto-detect event, dict, kwargs, and legacy forms
- throttling is available to avoid UI overload

## Batch download

littledl provides specialized batch downloaders for mixed workloads and large task sets.

### Core batch features

- Adaptive concurrency across files
- Small-file prioritization
- Shared connection pool
- Domain affinity scheduling to reuse hot connections
- Batch probe via parallel HEAD requests
- Smart per-file chunking based on file size
- Global chunk budget to limit aggregate active chunks across all files
- Optional existing-file reuse
- Optional multi-source failover support

### Quick examples

Synchronous batch:

```python
from littledl import batch_download_sync

results = batch_download_sync(
	urls=[
		"https://example.com/file1.zip",
		"https://example.com/file2.zip",
		"https://example.com/file3.zip",
	],
	save_path="./downloads",
	max_concurrent_files=5,
)
```

Asynchronous batch:

```python
import asyncio
from littledl import BatchDownloader

async def main():
	downloader = BatchDownloader(
		max_concurrent_files=5,
		max_concurrent_chunks_per_file=4,
		enable_adaptive_concurrency=True,
	)
	await downloader.add_urls([
		"https://example.com/file1.zip",
		"https://example.com/file2.zip",
	], "./downloads")
	await downloader.start()

asyncio.run(main())
```

High-performance batch downloader pattern from the README:

```python
from littledl import EnhancedBatchDownloader

downloader = EnhancedBatchDownloader(
	max_concurrent_files=5,
	max_total_threads=15,
	enable_existing_file_reuse=True,
	enable_multi_source=True,
)
```

### Batch callback model

Batch progress callbacks support:

- `BatchProgress` object
- `dict`
- `**kwargs`
- legacy positional format

`BatchProgress` includes:

- total_files
- completed_files
- failed_files
- active_files
- pending_files
- total_bytes
- downloaded_bytes
- overall_speed
- smooth_speed
- eta
- speed_stability
- elapsed_time
- files: tuple of per-file entries
- progress property
- files_progress property

Per-file progress entries include file identity, status, size, downloaded bytes, speed, progress, timestamps, and error state.

### File complete callbacks

File completion handlers receive a `FileTask` object.

### Smart chunking guidance

Default chunking strategy from the docs:

| File size | Typical strategy |
| --- | --- |
| < 5 MB | single chunk |
| 5 MB to 100 MB | about 4 chunks |
| > 100 MB | about 8 chunks |

### Adaptive concurrency behavior

Batch mode automatically adjusts concurrency:

- speed trend improving: increase file concurrency gradually
- speed trend degrading: reduce concurrency to stabilize throughput
- error rate rising: reduce concurrency
- per-file chunk growth remains bounded by the batch-wide chunk budget

### Operational controls

Batch downloader APIs support:

- add_url
- add_urls
- start
- pause
- resume
- cancel
- stop
- get_task
- get_all_tasks
- get_progress
- get_stats

### Batch implementation notes

- each file's config is cloned from the full parent `DownloadConfig` via `create_file_config()`
- dynamic style allocation sorts by file size, priority, and current chunk count
- adaptive concurrency increases on positive speed trends and reduces on negative ones
- a global chunk budget prevents over-expansion when many files are active
- domain affinity reuses warm connections within the same host set

## Advanced usage

### Manual chunk tuning

```python
from littledl import DownloadConfig

config = DownloadConfig(
	enable_chunking=True,
	chunk_size=8 * 1024 * 1024,
	max_chunks=8,
)
```

### Disable chunking

```python
config = DownloadConfig(enable_chunking=False)
```

### Multiple simultaneous downloads

```python
import asyncio
from littledl import download_file

async def download_multiple(urls):
	tasks = [download_file(url) for url in urls]
	return await asyncio.gather(*tasks)
```

### Custom headers

```python
config = DownloadConfig(
	headers={
		"User-Agent": "MyApp/1.0",
		"Accept": "application/octet-stream",
	}
)
```

### Cookies

```python
config = DownloadConfig(cookies={"session_id": "abc123"})
```

### SSL configuration

Custom CA bundle:

```python
config = DownloadConfig(verify_ssl=True, ssl_cert="/path/to/ca-bundle.crt")
```

Disable verification only for controlled scenarios:

```python
config = DownloadConfig(verify_ssl=False)
```

### Streaming API

```python
from littledl import download_file_stream

async for chunk in download_file_stream("https://example.com/large_file.zip"):
	process(chunk)
```

### Performance tuning knobs

- `buffer_size`
- `max_connections`
- `max_keepalive_connections`
- `chunk_size`
- `max_chunks`

Performance guidance:

- FUSION is the default strategy, with four phases: PROBE, RAMP, CRUISE, TAIL
- PROBE advances to RAMP after the first speed sample (once a short min-elapsed passes) to avoid a slow start
- RAMP doubles concurrency one adaptive_interval per round, stopping at the bandwidth ceiling
- CRUISE uses a ceiling-aware AIMD with P50/trend hysteresis so single speed blips do not cause sawtooth
- TAIL lifts target concurrency toward the number of pending chunks and can temporarily exceed the normal chunk count by `fusion_tail_boost`
- resume checkpoints and pause/cancel checks are important for stability in long-running downloads
- hash verification should be enforced post-download if integrity guarantees matter

## Error handling

Primary documented exceptions:

- `DownloadException`: base download error
- `NetworkError`: connection, timeout, DNS, and related transport failures
- `AuthenticationError`: auth failures
- `FileExistsError`: target exists while overwrite is disabled

Typical handling:

```python
from littledl import DownloadException

try:
	path = download_file_sync("https://example.com/file.zip")
except DownloadException as exc:
	print(f"Download failed: {exc}")
```

### Retry configuration

```python
from littledl import DownloadConfig, RetryConfig, RetryMode

retry = RetryConfig(
	enabled=True,
	mode=RetryMode.EXPONENTIAL,
	max_retries=3,
	initial_delay=1.0,
	max_delay=60.0,
)

config = DownloadConfig(retry=retry)
```

### Validation guidance

Recommended safeguards before download:

- validate URL scheme and host
- restrict protocols to HTTP/HTTPS where appropriate
- set `max_file_size` if the caller needs hard caps
- set `min_file_size` if undersized responses should be rejected

Example URL validation logic from the docs:

```python
from urllib.parse import urlparse

def validate_url(url: str) -> bool:
	parsed = urlparse(url)
	return parsed.scheme in ("http", "https")
```

## Security guidance

### Supported version line

Security updates apply to the current 1.0.x line.

### Reporting vulnerabilities

Do not report vulnerabilities through public GitHub issues.

Preferred channels:

1. GitHub Security Advisories
2. Email: zsxiaoshu@outlook.com

Suggested report contents:

- vulnerability description
- impact
- reproduction steps
- proof of concept if available
- suggested fix if available

Published response expectations:

- initial response within 48 hours
- confirmation within 5 business days
- fix timing based on severity
- disclosure after release of the fix

### Secure usage practices

- keep `verify_ssl=True` in production
- avoid embedding tokens in source code; prefer environment variables
- validate untrusted URLs before passing them to the downloader
- restrict protocols to safe allowlists
- block internal IPs if SSRF is a concern
- use caution when enabling proxies
- reduce chunk counts for very large files if memory pressure matters

Example secure auth pattern:

```python
import os
from littledl import AuthConfig

config = AuthConfig(
	auth_type="bearer",
	token=os.environ.get("API_TOKEN"),
)
```

### Known security considerations

- SSRF risk when accepting arbitrary URLs from untrusted users
- memory pressure on very large multi-chunk downloads

## Development and contribution

### Contributor prerequisites

- Python 3.10+
- uv package manager
- Git

### Development setup

```bash
git clone https://github.com/YOUR_USERNAME/little-tree-downloader.git
cd little-tree-downloader
uv sync --all-extras
uv run pytest tests/ -v
uv run ruff check src/
```

### Contribution expectations

- check existing issues before filing duplicates
- provide reproduction steps and environment details for bugs
- provide concrete use cases for feature requests
- add tests for new functionality
- update docs when behavior changes

### Coding standards

- follow PEP 8
- add type hints for function signatures
- write docstrings for public modules, functions, classes, and methods
- keep maximum line length at 120 characters

### Commit format

Conventional Commits are used:

```text
<type>(<scope>): <description>

[optional body]

[optional footer(s)]
```

Common types:

- feat
- fix
- docs
- style
- refactor
- perf
- test
- chore

### Pull request process

- ensure tests pass
- update documentation for new features
- add tests for new functionality
- follow the PR template
- request maintainer review
- respond to review feedback promptly

## Release highlights

This section summarizes the capabilities of the current release.

### 1.0.0

- atomic chunked downloads: data lands in a preallocated `.part` file via a single OS file descriptor with lock-serialized positional writes, then atomically renamed to the final name on success
- layout-aware resume: persisted chunk byte ranges are restored exactly (including resplit chunks), with ETag/Last-Modified compatibility validation before resuming
- FUSION four-phase adaptive scheduler (PROBE -> RAMP -> CRUISE -> TAIL) with bandwidth-ceiling estimation, P50 speed, and marginal-gain detection
- intelligent strategy selection based on file size, server capability, and network conditions, with FUSION as the default style
- unified callback system supporting event/dict/kwargs/legacy signatures for both single-file and batch downloads
- batch downloads with global chunk budgeting, domain affinity, adaptive concurrency, and rich progress UI
- authentication (Basic/Bearer/Digest/API Key/OAuth2), proxy (system/PAC/SOCKS5), speed limiting, hash verification, file reuse, and multi-source failover
- single source of truth for the package version via `importlib.metadata`, reflected in `__version__` and the default User-Agent

## Implementation map

Use this source map for implementation questions instead of relying on README-level descriptions alone.

- `src/littledl/__init__.py`: top-level exports and public API surface
- `src/littledl/downloader.py`: single-file downloader, ProgressEvent, chunk flow, callback adapters
- `src/littledl/batch.py`: BatchDownloader, EnhancedBatchDownloader, FileTask, BatchProgress, batch callbacks
- `src/littledl/callback.py`: EventType, event dataclasses, UnifiedCallbackAdapter, ThrottledCallback, CallbackChain
- `src/littledl/__main__.py`: argparse CLI, output modes, progress display, batch CLI behavior
- `src/littledl/config.py`: DownloadConfig and related configuration types/enums
- `src/littledl/connection.py`: connection pool and request construction
- `src/littledl/scheduler.py`: chunk scheduling, adaptive behavior, FusionScheduler, strategy logic
- `src/littledl/writer.py`: positional file writer used by chunked downloads
- `src/littledl/resume.py`: resume metadata persistence and layout restoration
- `tests/test_littledl.py`: usage examples and regression coverage for callbacks, CLI, scheduling, batch logic, and the writer/resume path

## Source coverage inventory

The following maintained documentation sources are represented in this bundle.

Root docs:

- README.md
- README.zh.md
- CONTRIBUTING.md
- CONTRIBUTING.zh.md
- SECURITY.md
- SECURITY.zh.md
- CHANGELOG.md
- CHANGELOG.zh.md

English docs:

- docs/en/index.md
- docs/en/getting-started/index.md
- docs/en/configuration/index.md
- docs/en/authentication/index.md
- docs/en/proxy/index.md
- docs/en/error-handling/index.md
- docs/en/advanced/index.md
- docs/en/batch-download/index.md
- docs/en/cli/index.md
- docs/en/api-reference/index.md

Chinese docs:

- docs/zh/index.md
- docs/zh/getting-started/index.md
- docs/zh/configuration/index.md
- docs/zh/authentication/index.md
- docs/zh/proxy/index.md
- docs/zh/error-handling/index.md
- docs/zh/advanced/index.md
- docs/zh/batch-download/index.md
- docs/zh/cli/index.md
- docs/zh/api-reference/index.md

## Practical usage guidance for agents

If answering product usage questions:

- prefer the sections above over the README alone
- assume FUSION is the default style unless the user explicitly overrides it
- mention that callbacks support event, dict, kwargs, and legacy forms
- mention batch global chunk budgeting and domain affinity for multi-file performance questions

If answering implementation questions:

- use the implementation map and source files
- verify behavior in `config.py`, `downloader.py`, `batch.py`, and `scheduler.py`
- for FUSION scheduling behavior, read `scheduler.py` (`FusionScheduler` four-phase logic) and the resume/writer flow in `downloader.py`

If answering security-sensitive questions:

- recommend URL validation, SSL verification, and careful credential handling
- mention SSRF considerations when users accept arbitrary URLs