From 1eda214dfcce831225363c8243dd6eb9132cf890 Mon Sep 17 00:00:00 2001 From: jxxghp Date: Fri, 11 Sep 2026 06:53:44 +0800 Subject: [PATCH] docs(agent): clarify common API contracts --- skills/moviepilot-api/SKILL.md | 15 ++++++++++++++- tests/test_builtin_skill_boundaries.py | 2 +- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/skills/moviepilot-api/SKILL.md b/skills/moviepilot-api/SKILL.md index 48e2f33a8..e19161019 100644 --- a/skills/moviepilot-api/SKILL.md +++ b/skills/moviepilot-api/SKILL.md @@ -1,6 +1,6 @@ --- name: moviepilot-api -version: 28 +version: 29 description: >- Use this skill for MoviePilot product operations such as media search, torrent search, downloads, subscriptions, library checks, sites, storage, workflows, @@ -170,6 +170,19 @@ Call the gateway with this shape: } ``` +### Common read and download contracts + +Select the operation for the task first, then send only fields declared by that operation. Common verification contracts are: + +| operation_id | `path_params` | `query` | +| --- | --- | --- | +| `subscription.find` | `media_id` | `media_source`; optional `season`, `music_type` | +| `subscription.list` | none | optional `page`, `count` | +| `download.tasks.active` | none | optional `page`, `count`, `name` | +| `site.list` | none | optional `page`, `count`, `name`, `status=all\|active\|inactive` | + +The `download.add` body must contain `torrent_in` (at least `title` and `enclosure`) plus sibling `media_source` and `media_id`; do not put a magnet URI in `url`, or move media identity and filters into `query`. When a write returns `unknown`, never retry it; verify the actual state with a supported read operation first. + - Put route placeholders such as `subscribe_id`, `hashString`, `plugin_id`, `workflow_id`, `media_id`, `storage`, `rule_id`, and `name` in `path_params`. - Put GET filters and control values in `query`. The gateway also accepts GET diff --git a/tests/test_builtin_skill_boundaries.py b/tests/test_builtin_skill_boundaries.py index d72eefba0..990930d36 100644 --- a/tests/test_builtin_skill_boundaries.py +++ b/tests/test_builtin_skill_boundaries.py @@ -117,7 +117,7 @@ def test_modified_builtin_skills_have_incremented_versions() -> None: "command-dispatch": "2", "database-operation": "7", "feedback-issue": "9", - "moviepilot-api": "28", + "moviepilot-api": "29", "moviepilot-update": "5", "organize-files": "5", "transfer-failed-retry": "5",