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

release: v0.2.0 repository hygiene, CI, and docs sync

Browse Source 
Stop tracking personal workflow artifacts at repo root, add CI and MIT
license, align README and agent skills with artifacts/ defaults, and
enable Ruff in dev/CI so releases are verifiable without local-only runs.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
windyboy
2026-06-01 15:32:03 +08:00
co-authored by Claude Sonnet 4.5 Cursor
parent e70bd35498
commit 6f0df5a774
101 changed files with 1451 additions and 653105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/vlm-library-workflow/references/cli-reference.md
+3 -1
View File
@@ -1,5 +1,5 @@
# Documentation Status
- Updated to current CLI options on 2026-02-16.
- Updated to current CLI options on 2026-06-01. Default artifact paths are under `artifacts/`.
# VLM CLI Reference
@@ -14,6 +14,8 @@
- `vlm enrich [--input JSON] [--output JSON] [--refresh-all]`: Fetch TMDB metadata.
- `vlm analyze [--input JSON] [--output JSON]`: Find gaps and duplicates.
- `vlm plan [--input JSON] [--analysis JSON] [--output JSON]`: Generate operations.
- `vlm review-plan [--input JSON] [--output CSV] [--tui]`: Export manual review CSV (optional Textual UI).
- `vlm apply-review [--plan JSON] [--csv PATH]`: Sync edited review CSV into plan.
- `vlm execute [--plan JSON] [--confirm] [--yes] [--verbose-ops] [--safe-mode] [--preserve-directories]`: Move/Rename/Quarantine operations with safety guards.
- `vlm rollback [--log PATH]`: Undo operations.
skills/vlm-library-workflow/references/command-recipes.md
+30 -37
View File
@@ -1,11 +1,11 @@
# Documentation Status
- Synced with refactor baseline on 2026-02-16.
- Synced with artifacts/ baseline on 2026-06-01.
# VLM Command Recipes
## Baseline
Run from repository root unless user specifies otherwise.
Run from repository root unless the user specifies otherwise.
```bash
vlm --help
@@ -13,7 +13,7 @@ vlm config show
vlm config validate
```
If `vlm` is not on PATH, switch to:
If `vlm` is not on PATH:
```bash
uv run vlm --help
@@ -23,52 +23,45 @@ uv run vlm config validate
## End-to-End Pipeline
Default artifact paths match CLI defaults under `artifacts/`:
```bash
vlm scan --output inventory.csv
vlm parse --input inventory.csv --output identities.json --inventory inventory.csv
vlm scan
vlm parse --inventory artifacts/inventory.csv
vlm enrich
vlm analyze --input identities.json --output analysis.json --inventory inventory.csv
vlm plan --input identities.json --output plan.json --analysis analysis.json
vlm review-plan --input plan.json --output plan_manual_review.csv
vlm execute --plan plan.json
vlm execute --plan plan.json --confirm
vlm analyze --inventory artifacts/inventory.csv
vlm plan --analysis artifacts/analysis.json
vlm review-plan --input artifacts/plan.json --output artifacts/plan_manual_review.csv
vlm apply-review
vlm execute
vlm execute --confirm
```
## Artifact Expectations
1. `inventory.csv`: discovered video files with filesystem and optional ffprobe metadata.
2. `identities.json`: parsed identities for movie/series/anime/other, optionally with embedded quality metadata.
3. `analysis.json`: completeness gaps and duplicate groups with quality comparison context.
4. `plan.json`: planned operations (`move`, `rename`, `quarantine`, `no-op`) and summary data.
5. `plan_manual_review.csv`: high-risk operations requiring human confirmation before `--confirm`.
1. `artifacts/inventory.csv` — discovered files with filesystem and optional ffprobe metadata.
2. `artifacts/identities.json` — parsed identities (v2 when parse used `--inventory`).
3. `artifacts/analysis.json` — completeness gaps and duplicate groups.
4. `artifacts/plan.json` — planned operations (`move`, `rename`, `quarantine`, `no-op`).
5. `artifacts/plan_manual_review.csv` — high-risk rows for human review before `--confirm`.
Do not commit these files to Git.
## Focused Workflows
```bash
# Parse only, with metadata embedding
vlm parse --inventory inventory.csv
# Analyze only
vlm analyze --input identities.json --output analysis.json --inventory inventory.csv
# Plan from analysis-assisted duplicate decisions
vlm plan --input identities.json --analysis analysis.json --output plan.json
# Roll back latest confirmed execution
vlm parse --inventory artifacts/inventory.csv
vlm analyze --input artifacts/identities.json --output artifacts/analysis.json --inventory artifacts/inventory.csv
vlm plan --input artifacts/identities.json --analysis artifacts/analysis.json --output artifacts/plan.json
vlm rollback
```
## Frequent Failure Triage
1. Missing config:
Run `vlm config init`, then set `library_root` in `~/.vlm/config.yaml`.
2. Invalid config values:
Run `vlm config validate` and fix reported keys.
3. Missing input artifact:
Run the prerequisite stage (`scan` before `parse`, `parse` before `analyze`, `analyze` before analysis-driven `plan`).
4. Unexpected duplicate decisions:
Check `plan.duplicate_keep` in config and rerun `vlm plan --analysis analysis.json`.
5. Unsafe or undesired execution results:
Run `vlm rollback` and inspect plan before re-running `execute --confirm`.
6. `vlm` command not found:
Use `uv run vlm ...` fallback for the same subcommands.
1. Missing config: `vlm config init`, set `library_root`.
2. Invalid config: `vlm config validate`.
3. Missing input artifact: run prerequisite stage (scan → parse → analyze → plan).
4. Unexpected duplicate decisions: check `plan.duplicate_keep`, rerun `vlm plan --analysis artifacts/analysis.json`.
5. Unsafe execution: `vlm rollback`, re-run `review-plan` / `apply-review`.
6. `vlm` not found: use `uv run vlm ...`.
7. TMDB rate limits: lower `enrichment.max_concurrency` in config and retry later.
skills/vlm-library-workflow/references/workflow.md
+21 -17
View File
@@ -1,5 +1,5 @@
# Documentation Status
- Synced with refactor baseline on 2026-02-16.
- Synced with artifacts/ baseline on 2026-06-01.
# VLM Workflow Guide
@@ -11,30 +11,30 @@ This guide details the standard end-to-end process for organizing a video librar
```bash
vlm config init
```
Edit `~/.vlm/config.yaml` to set `library_root`.
Edit `~/.vlm/config.yaml` to set `library_root` and optionally `workspace_dir: artifacts`.
### Library Scan
```bash
vlm scan
```
- **Goal**: Create `inventory.csv`.
- **Goal**: Create `artifacts/inventory.csv`.
- **Note**: Ensure `ffprobe` is installed for resolution and codec metadata.
## 2. Identification
### Filename Parsing
```bash
vlm parse --inventory inventory.csv
vlm parse --inventory artifacts/inventory.csv
```
- **Goal**: Create `identities.json`.
- **Why --inventory?**: It embeds video metadata (v2 schema) required for quality-based duplicate resolution.
- **Goal**: Create `artifacts/identities.json`.
- **Why --inventory?**: Embeds video metadata (v2 schema) required for quality-based duplicate resolution.
### Metadata Enrichment
```bash
vlm enrich
```
- **Goal**: Update `identities.json` with TMDB data.
- **Troubleshooting**: If matches are missing, check `enrichment.api_keys` in config.
- **Goal**: Update `artifacts/identities.json` with TMDB data.
- **Troubleshooting**: Check `enrichment.api_keys` in config; never commit `~/.vlm/config.yaml`.
## 3. Analysis and Planning
@@ -42,25 +42,29 @@ vlm enrich
```bash
vlm analyze
```
- **Goal**: Create `analysis.json`.
- **Outputs**: Lists duplicate files and episode gaps in series.
- **Goal**: Create `artifacts/analysis.json`.
- **Outputs**: Episode gaps and duplicate groups.
### Create Execution Plan
```bash
vlm plan --analysis analysis.json
vlm plan --analysis artifacts/analysis.json
```
- **Goal**: Create `plan.json`.
- **Strategy**: VLM uses the `duplicate_keep` policy (default: `by_reputation`) to decide which files to keep and which to quarantine.
- **Goal**: Create `artifacts/plan.json`.
- **Strategy**: Uses `plan.duplicate_keep` (default: `by_reputation`) for duplicate decisions.
## 4. Execution and Safety
## 4. Review and Execution
### Review the Plan
Open `plan.json` and check the `human_summary` field or the proposed `operations`.
### Human review
```bash
vlm review-plan
# Optional: vlm review-plan --tui (requires textual extra)
vlm apply-review # after editing artifacts/plan_manual_review.csv
```
### Execute Changes
```bash
vlm execute # Dry-run
vlm execute --confirm # Actual operations
vlm execute --confirm # Actual operations (explicit confirmation)
```
### Reverting Changes