windy/dl-organizer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs sync post-refactor baseline

Browse Source
This commit is contained in:
windyboy
2026-04-07 11:07:01 +08:00
parent 0a6bddcc7e
commit c9d22d5136
14 changed files with 75 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+30 -24
View File
@@ -1,7 +1,7 @@
# CLAUDE.md
## Documentation Status
- Synchronized with refactor baseline on 2026-02-16 (see `CHANGELOG.md`).
- Synchronized with post-refactor baseline on 2026-04-07 (see `CHANGELOG.md`).
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
@@ -25,6 +25,8 @@ uv pip install -e ".[dev]"
uv pip install -e ".[tui]"
```
The default CLI path does not require Textual; it is imported only when `uv run vlm review-plan --tui` is used.
### Testing
```bash
# Run all tests (use uv run to execute in the project environment)
@@ -52,17 +54,20 @@ uv run vlm --help
uv run vlm config init
# Common workflow
uv run vlm scan # Discover files
uv run vlm parse # Extract identities (v1 schema)
uv run vlm parse --inventory inventory.csv # Extract identities with embedded metadata (v2 schema, recommended)
uv run vlm enrich # (Optional) Enrich titles/reputation via TMDB
uv run vlm enrich --refresh-all # Force full refresh (ignore cache)
uv run vlm analyze # Detect gaps/duplicates
uv run vlm plan # Generate execution plan
uv run vlm plan --analysis analysis.json # Generate plan with duplicate resolution
uv run vlm execute # Dry-run (default)
uv run vlm execute --confirm # Actually execute
uv run vlm rollback # Undo executed operations
uv run vlm scan # Discover files
uv run vlm parse # Extract identities (v1 schema)
uv run vlm parse --inventory artifacts/inventory.csv # Embed metadata for quality-aware duplicate handling
uv run vlm enrich # (Optional) Enrich titles/reputation via TMDB
uv run vlm enrich --refresh-all # Force full refresh (ignore cache)
uv run vlm analyze # Detect gaps/duplicates
uv run vlm plan # Generate execution plan
uv run vlm plan --analysis artifacts/analysis.json # Generate plan with duplicate resolution
uv run vlm review-plan # Export CSV + terminal review preview
uv run vlm review-plan --tui # Optional full-screen review UI
uv run vlm apply-review # Sync edited CSV decisions back into the plan
uv run vlm execute # Dry-run (default)
uv run vlm execute --confirm # Actually execute
uv run vlm rollback # Undo executed operations
# Reporting
uv run vlm report summary # Overview statistics
@@ -84,15 +89,16 @@ uv run vlm state set <file> --status reviewed
### Core Workflow
VLM follows a read-first, multi-stage pipeline:
1. **Scan** → discovers video files, extracts metadata via ffprobe (optional), saves to inventory.csv
2. **Parse** → extracts titles/years/seasons/episodes from filenames, saves to identities.json
- Use `--inventory inventory.csv` to embed video metadata (v2 schema) for accurate duplicate resolution by quality
1. **Scan** → discovers video files, extracts metadata via ffprobe (optional), saves to `artifacts/inventory.csv`
2. **Parse** → extracts titles/years/seasons/episodes from filenames, saves to `artifacts/identities.json`
- Use `--inventory artifacts/inventory.csv` to embed video metadata (v2 schema) for accurate duplicate resolution by quality
- Without `--inventory`, produces v1 schema (lightweight, no embedded metadata)
3. **Enrich** (optional) → adds bilingual titles and reputation (TMDB); updates identities.json in place; uses SQLite cache for incremental runs
4. **Analyze** → detects episode gaps and duplicates, saves to analysis.json
5. **Plan** → generates reviewable execution plan (plan.json) with file operations
6. **Execute** → performs file operations (dry-run by default, --confirm to execute)
7. **Rollback** → reverses executed operations (best-effort)
3. **Enrich** (optional) → adds bilingual titles and reputation (TMDB); updates `artifacts/identities.json` in place; uses SQLite cache for incremental runs
4. **Analyze** → detects episode gaps and duplicates, saves to `artifacts/analysis.json`
5. **Plan** → generates reviewable execution plan (`artifacts/plan.json`) with file operations
6. **Review / Apply Review** → previews high-risk operations in terminal or optional TUI, then syncs edited CSV decisions back into the plan when needed
7. **Execute** → performs file operations (dry-run by default, `--confirm` to execute)
8. **Rollback** → reverses executed operations (best-effort)
### Module Organization
- `cli.py` - Click-based CLI interface, global options, command registration
@@ -101,12 +107,12 @@ VLM follows a read-first, multi-stage pipeline:
- `scanner.py` - File discovery using system `find` command, metadata extraction via ffprobe
- `parser.py` - Filename parsing using regex patterns (movies: title + year, series: SxxExx)
- `enrichment.py` - Enrichment pipeline; `cache.py` - SQLite cache; `providers/` - TMDB etc.
- `io.py` - Unified JSON/CSV I/O helpers (including analysis writer and data adapters)
- `io.py` - Unified JSON/CSV I/O helpers, including validated typed plan loading/saving
- `utils.py` - UTC time, format_size, shared helpers
- `analysis.py` - Completeness checking (episode gaps) and duplicate detection
- `duplicate_resolve.py` - Duplicate group resolution (by_quality, by_reputation, first_seen, manual)
- `planner.py` - Execution plan generation with conflict detection
- `executor.py` - File operations (move/rename/quarantine) with rollback logging
- `duplicate_resolve.py` - Duplicate group resolution with explicit failures for unresolved strategies/data
- `planner.py` - Execution plan generation with conflict detection and manual-review duplicate fallback
- `executor.py` - File operations (move/rename/quarantine) with rollback logging and library-root safety checks
- `quarantine.py` - Quarantine management with manifest tracking
- `state.py` - File state tracking across workflow stages
- `reports.py` - Report generation (inventory, completeness, duplicates, summary)