| 1 | <!-- Parent: ../AGENTS.md --> |
| 2 | <!-- Generated: 2026-03-27 | Updated: 2026-03-27 --> |
| 3 | |
| 4 | # user_modes |
| 5 | |
| 6 | ## Purpose |
| 7 | Strategy pattern implementations for user download modes. Each strategy defines how to collect and filter content for a specific mode (posts, likes, mixes, music). Auto-discovered by `UserModeRegistry`. |
| 8 | |
| 9 | ## Key Files |
| 10 | |
| 11 | | File | Description | |
| 12 | |------|-------------| |
| 13 | | `__init__.py` | Package marker | |
| 14 | | `base_strategy.py` | `BaseUserModeStrategy` ABC — paged collection, cursor pagination, filtering, metadata expansion | |
| 15 | | `post_strategy.py` | Downloads a user's published posts (`mode_name="post"`) | |
| 16 | | `like_strategy.py` | Downloads a user's liked videos (`mode_name="like"`) | |
| 17 | | `mix_strategy.py` | Downloads a user's mixes/collections (`mode_name="mix"`) — expands metadata items to aweme lists | |
| 18 | | `music_strategy.py` | Downloads a user's music-related content (`mode_name="music"`) — expands metadata items | |
| 19 | |
| 20 | ## For AI Agents |
| 21 | |
| 22 | ### Working In This Directory |
| 23 | - Each strategy sets `mode_name` and `api_method_name` class attributes |
| 24 | - `BaseUserModeStrategy._collect_paged_aweme()` handles cursor-based pagination with stall detection |
| 25 | - Mix and music strategies override `collect_items()` to use `_expand_metadata_items()` for two-level fetching |
| 26 | - `apply_filters()` chains time-range filtering and count limiting from config |
| 27 | - The `number` and `increase` config sections control per-mode limits and incremental behavior |
| 28 | - New modes: create a new `*_strategy.py` with a class inheriting `BaseUserModeStrategy`, set `mode_name` and `api_method_name`, and it will be auto-discovered |
| 29 | |
| 30 | ### Testing Requirements |
| 31 | - Tests: `tests/test_user_mode_strategies.py`, `tests/test_user_downloader_modes.py` |
| 32 | |
| 33 | ### Common Patterns |
| 34 | - Strategy pattern: each mode is a pluggable strategy class |
| 35 | - Registry auto-discovery: `UserModeRegistry` scans this directory for `BaseUserModeStrategy` subclasses |
| 36 | - Two-level fetching: metadata items → expanded aweme lists (mix/music strategies) |
| 37 | - Page normalization: `_normalize_page_data()` handles both `items` and `aweme_list` API response formats |
| 38 | |
| 39 | ## Dependencies |
| 40 | |
| 41 | ### Internal |
| 42 | - `core/downloader_base.py` — `DownloadResult` for return values |
| 43 | - `core/user_downloader.py` — `UserDownloader` reference (TYPE_CHECKING only) |
| 44 | - `utils/logger.py` — logging |
| 45 | |
| 46 | <!-- MANUAL: --> |
| 47 |