merge VLM skills into a single workflow expert skill

2026-02-13 12:01:10 +08:00
parent 54416065fe
commit 5931f16a71
6 changed files with 292 additions and 0 deletions
@@ -0,0 +1,26 @@
+# VLM CLI Reference
+
+## Configuration
+- `vlm config init`: Create default config.
+- `vlm config show`: Display current settings.
+- `vlm config validate`: Check config for errors.
+
+## Core Commands
+- `vlm scan [--output PATH]`: Discover video files.
+- `vlm parse [--input CSV] [--output JSON] [--inventory CSV]`: Parse filenames.
+- `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 execute [--plan JSON] [--confirm]`: Move/Rename files.
+- `vlm rollback [--log PATH]`: Undo operations.
+
+## Management & Reporting
+- `vlm quarantine list|add|restore`: Manage the `.quarantine` directory.
+- `vlm report inventory|completeness|duplicates|summary`: Generate human-readable reports.
+- `vlm state show|set|query|clear`: Track manual review status for files.
+
+## Important Config Options (`~/.vlm/config.yaml`)
+- `library_root`: Path to the video collection.
+- `templates`: Naming patterns for movies and series.
+- `plan.duplicate_keep`: Strategy for duplicates (`by_quality`, `by_reputation`, `first_seen`, `manual`).
+- `enrichment.api_keys`: TMDB and OpenAI keys.
@@ -0,0 +1,71 @@
+# VLM Command Recipes
+
+## Baseline
+
+Run from repository root unless user specifies otherwise.
+
+```bash
+vlm --help
+vlm config show
+vlm config validate
+```
+
+If `vlm` is not on PATH, switch to:
+
+```bash
+uv run vlm --help
+uv run vlm config show
+uv run vlm config validate
+```
+
+## End-to-End Pipeline
+
+```bash
+vlm scan --output inventory.csv
+vlm parse --input inventory.csv --output identities.json --inventory 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
+```
+
+## 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`.
+
+## 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 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.
@@ -0,0 +1,30 @@
+# VLM Developer Guide
+
+## Project Structure
+- `src/vlm/cli.py`: Entry point and command definitions.
+- `src/vlm/parser.py`: Regex-based filename parsing logic.
+- `src/vlm/enrichment.py`: Pipeline for external metadata fetching.
+- `src/vlm/providers/`: API implementations (e.g., TMDB).
+- `src/vlm/planner.py`: Logic for mapping identities to filesystem operations.
+- `src/vlm/executor.py`: Safe file manipulation and rollback logging.
+
+## Adding a New Command
+1. Create a new module in `src/vlm/commands/`.
+2. Define the command using `@click.command()`.
+3. Register it in `src/vlm/cli.py` using `main.add_command()`.
+
+## Modifying the Parser
+- The parser uses a sequence of regex patterns in `src/vlm/parser.py`.
+- Add new patterns to the `PATTERNS` list or improve existing ones.
+- Always run `pytest tests/test_parser.py` after changes.
+
+## Data Models
+See `src/vlm/models.py` for core data structures:
+- `VideoFile`: Basic file metadata.
+- `MediaIdentity`: Parsed and enriched information.
+- `PlanOperation`: Definition of a file move/rename/quarantine.
+
+## Testing
+- **Unit Tests**: `pytest`
+- **Property-based Tests**: `pytest tests/test_analysis_properties.py` (uses Hypothesis).
+- **Integration Tests**: `pytest tests/test_reports_integration.py`.
@@ -0,0 +1,67 @@
+# VLM Workflow Guide
+
+This guide details the standard end-to-end process for organizing a video library using VLM.
+
+## 1. Setup and Discovery
+
+### Initialize Configuration
+```bash
+vlm config init
+```
+Edit `~/.vlm/config.yaml` to set `library_root`.
+
+### Library Scan
+```bash
+vlm scan
+```
+- **Goal**: Create `inventory.csv`.
+- **Note**: Ensure `ffprobe` is installed for resolution and codec metadata.
+
+## 2. Identification
+
+### Filename Parsing
+```bash
+vlm parse --inventory inventory.csv
+```
+- **Goal**: Create `identities.json`.
+- **Why --inventory?**: It 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.
+
+## 3. Analysis and Planning
+
+### Detect Issues
+```bash
+vlm analyze
+```
+- **Goal**: Create `analysis.json`.
+- **Outputs**: Lists duplicate files and episode gaps in series.
+
+### Create Execution Plan
+```bash
+vlm plan --analysis 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.
+
+## 4. Execution and Safety
+
+### Review the Plan
+Open `plan.json` and check the `human_summary` field or the proposed `operations`.
+
+### Execute Changes
+```bash
+vlm execute           # Dry-run
+vlm execute --confirm # Actual operations
+```
+
+### Reverting Changes
+```bash
+vlm rollback
+```
+Restores files using the latest log in `~/.vlm/rollback/`.