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/SKILL.md
+39 -40
View File
@@ -1,9 +1,9 @@
# Documentation Status
- Synced with refactor baseline on 2026-02-16.
- Synced with artifacts/ baseline on 2026-06-01.
---
name: vlm-library-workflow
description: Operate and extend the Video Library Manager (`vlm`) with a safety-first, human-in-the-loop workflow across scan, parse, enrich, analyze, plan, review-plan, execute, rollback, and developer verification. Use when requests involve organizing a video library, producing or reviewing `inventory.csv`/`identities.json`/`analysis.json`/`plan.json`, tuning VLM config templates, resolving duplicates or episode gaps, running dry-run/confirm execution, recovering changes via rollback, explaining VLM CLI usage, or developing/modifying VLM features (parser, providers, planner, executor, commands, tests).
description: Operate and extend the Video Library Manager (`vlm`) with a safety-first, human-in-the-loop workflow across scan, parse, enrich, analyze, plan, review-plan, apply-review, execute, rollback, and developer verification. Use when requests involve organizing a video library, producing or reviewing `artifacts/inventory.csv`, `artifacts/identities.json`, `artifacts/analysis.json`, `artifacts/plan.json`, tuning VLM config templates, resolving duplicates or episode gaps, running dry-run/confirm execution, recovering changes via rollback, explaining VLM CLI usage, or developing/modifying VLM features (parser, providers, planner, executor, commands, tests).
---
# VLM Library Workflow
@@ -12,31 +12,35 @@ description: Operate and extend the Video Library Manager (`vlm`) with a safety-
Run the repository's built-in media organization pipeline with consistent safety checks and explicit output verification. Prefer incremental, reviewable steps and never skip dry-run and plan inspection before destructive operations.
**Do not commit** generated CSV/JSON under `artifacts/` or at the repository root.
## Workflow Order
Run commands in this default sequence unless the user asks for a specific stage:
1. `vlm config init` then set `library_root` in `~/.vlm/config.yaml`
2. `vlm scan` to produce `inventory.csv`
3. `vlm parse --inventory inventory.csv` to produce metadata-rich `identities.json`
2. `vlm scan` → `artifacts/inventory.csv`
3. `vlm parse --inventory artifacts/inventory.csv` → `artifacts/identities.json` (v2 schema)
4. `vlm enrich` when bilingual titles and reputation signals are needed
5. `vlm analyze --inventory inventory.csv` to produce `analysis.json`
6. `vlm plan --analysis analysis.json` to produce `plan.json`
7. `vlm execute` (dry-run) and inspect summary
8. `vlm execute --confirm` only after explicit user confirmation
9. `vlm rollback` if the user requests revert
5. `vlm analyze --inventory artifacts/inventory.csv` → `artifacts/analysis.json`
6. `vlm plan --analysis artifacts/analysis.json` → `artifacts/plan.json`
7. `vlm review-plan` → `artifacts/plan_manual_review.csv` (use `--tui` only when Textual is installed)
8. Edit CSV if needed, then `vlm apply-review` to sync decisions into `plan.json`
9. `vlm execute` (dry-run) and inspect summary
10. `vlm execute --confirm` only after explicit user confirmation
11. `vlm rollback` if the user requests revert
If `vlm` is not on PATH, prefix commands with `uv run`.
## Preflight Checks
Run these checks before executing workflow commands:
1. Confirm current working directory is repository root.
2. Probe command availability in this order:
1. `vlm --help`
2. if unavailable, switch all commands to `uv run vlm --help`
2. Probe command availability: `vlm --help` or `uv run vlm --help`.
3. Run the target subcommand `--help` when options are uncertain.
4. Confirm config validity with `vlm config validate` after config edits.
5. Verify required input files exist before downstream stages.
5. Verify required input artifacts exist under `artifacts/` (or paths passed via flags).
6. Treat `execute --confirm` as destructive and require explicit user confirmation.
## Execution Rules
@@ -44,35 +48,30 @@ Run these checks before executing workflow commands:
Follow these rules while executing tasks:
1. Prefer read-only stages first: scan, parse, enrich, analyze, plan.
2. Treat `plan.json` as reviewable contract; summarize counts and conflicts before execution.
3. Run dry-run (`vlm execute`) before `vlm execute --confirm`.
4. If execution is interrupted or results are incorrect, locate rollback logs and run `vlm rollback`.
5. Keep outputs explicit in responses: file path, record counts, and next command.
6. If user asks for partial workflow, run only required stages and clearly state skipped dependencies.
7. Before `execute --confirm`, run `vlm review-plan --input plan.json --output plan_manual_review.csv` and report high-risk counts.
8. If high-risk operations > 0, default to pause and require user explicit override to continue confirm execution.
2. Treat `artifacts/plan.json` as the reviewable contract; summarize counts and conflicts before execution.
3. Run `review-plan` and `apply-review` before `execute --confirm` when manual decisions are required.
4. Run dry-run (`vlm execute`) before `vlm execute --confirm`.
5. If execution is interrupted or results are incorrect, locate rollback logs and run `vlm rollback`.
6. Keep outputs explicit in responses: file path, record counts, and next command.
7. If the user asks for a partial workflow, run only required stages and state skipped dependencies.
8. Before `execute --confirm`, run `vlm review-plan` and report high-risk counts; pause if the user has not reviewed high-risk operations.
## Decision Points
Use these decision policies:
1. Duplicate handling:
Choose `plan.duplicate_keep` policy (`by_quality`, `by_reputation`, `first_seen`, `manual`) based on user preference.
2. Enrichment:
Skip `vlm enrich` only when user does not need translations/reputation or API keys are unavailable.
3. Metadata quality:
Prefer `vlm parse --inventory inventory.csv` when duplicate quality ranking matters.
4. Analysis-assisted planning:
Prefer `vlm plan --analysis analysis.json` when user wants automatic duplicate quarantine decisions.
5. Parser boundary risk:
Treat filenames containing resolution-like `1920x1080/1440x1080` and `Sample` clips as high-risk; require review-plan output before confirmation.
1. Duplicate handling: choose `plan.duplicate_keep` (`by_quality`, `by_reputation`, `by_reputation_quality_time`, `first_seen`, `manual`) per user preference.
2. Enrichment: skip `vlm enrich` only when translations/reputation are not needed or API keys are unavailable.
3. Metadata quality: prefer `vlm parse --inventory artifacts/inventory.csv` when duplicate quality ranking matters.
4. Analysis-assisted planning: prefer `vlm plan --analysis artifacts/analysis.json` for automatic duplicate quarantine decisions.
5. Parser boundary risk: treat resolution-like tokens (`1920x1080`) and `Sample` clips as high-risk; require review-plan output before confirmation.
## Output Contract
Return concise, operational summaries:
1. Commands executed.
2. Artifacts generated or updated.
2. Artifacts generated or updated (under `artifacts/` by default).
3. Key counts (files scanned, identities parsed, duplicate groups, plan operations).
4. Risk counts from `review-plan` (manual_review / sample_source / high_season / high_episode / conflicts).
5. Blocking errors and exact remediation command.
@@ -80,18 +79,18 @@ Return concise, operational summaries:
## Developer Verification
When modifying VLM core logic, verify integrity with these recipes:
When modifying VLM core logic:
1. **Full Suite**: `pytest`
2. **Core Components**: `pytest tests/test_scanner.py tests/test_planner.py tests/test_executor.py`
3. **Property Tests**: `pytest tests/test_analysis_properties.py`
4. **Integration**: `pytest tests/test_reports_integration.py`
1. **Full suite**: `uv run pytest -q`
2. **Core components**: `uv run pytest tests/test_scanner.py tests/test_planner.py tests/test_executor.py`
3. **Property tests**: `uv run pytest tests/test_analysis_properties.py`
4. **Lint** (with dev extras): `uv run ruff check src tests`
## References
Load these references on demand:
1. `references/command-recipes.md`: command syntax, artifact expectations, and failure triage.
2. `references/workflow.md`: end-to-end operator workflow guidance.
3. `references/cli-reference.md`: command and config option quick reference.
4. `references/dev-guide.md`: project architecture and developer modification patterns.
1. `references/command-recipes.md` — command syntax, artifact expectations, failure triage.
2. `references/workflow.md` — end-to-end operator workflow.
3. `references/cli-reference.md` — command and config quick reference.
4. `references/dev-guide.md` — architecture and developer modification patterns.
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