filmweb は何をしますか？
Filmweb.pl の JSON API からデータを取得します。依存関係のない小さな Python CLI (scripts/filmweb.py) を使用し、常に JSON を出力します。
スクリプトの実行
このスキルのディレクトリから実行します。使用可能な Python ランチャーを使用してください。
| OS | コマンド |
|---|---|
| Linux / macOS | python3 scripts/filmweb.py <command> … |
| Windows | py scripts/filmweb.py <command> … (または python) |
インストール手順は不要です。
ワークフロー
- Filmweb ID を取得する。
- ユーザーがリンクを提供した場合 →
filmweb.py id "<url>"(オフライン)。 ID はスラッグの末尾の数字です:filmweb.pl/film/Matrix-1999-628→628、filmweb.pl/serial/Gra+o+tron-2011-476848→476848。 - ユーザーがタイトルを提供した場合 →
filmweb.py search "<title>"。結果は関連性順に並びます。 ユーザーが明らかにテレビシリーズを指している場合は--type=serialを追加します（映画の場合は--type=film）。 複数のタイトルが一致する可能性がある場合（リメイク、続編、映画とシリーズの区別など）、filmで確認し、年で選ぶか、ユーザーに尋ねます。
- ユーザーがリンクを提供した場合 →
- 質問に必要なデータのみを取得する。
- 評価、ジャンル、監督、短いあらすじ →
film - 「誰が出演していたか」 →
cast(filmにはすでに主な俳優2人が含まれています) - 「どこで見られるか」 →
vod - 「公開日はいつか」 →
dates - 完全なあらすじ →
description；人物の詳細 →person <personId>
- 評価、ジャンル、監督、短いあらすじ →
- ユーザーの言語で回答し、
filmのurlを引用します。評価は小数点以下1桁に丸め、投票数を記載します（例: 「7,6/10 z 872 tys. ocen」）。VOD 料金は złoty で表示します。
映画とシリーズ
映画、テレビシリーズ、ゲームは Filmweb 上で同じ ID 空間を共有しており、すべてのコマンドはそれらのいずれでも受け付けます — シリーズにも film <id> を使用します（例: 「Gra o tron」には film 476848）。出力の type で種類を確認します（film、serial、…）。シリーズの場合、year は最初のシーズン、duration はエピソード1本の長さであり、シリーズ全体ではありません。
コマンド
| コマンド | 戻り値 |
|---|---|
| `search "" [--type=film | serial |
| `film <id | url>` (映画またはシリーズ) |
| `description <id | url>` |
| `cast <id | url> [--limit=10]` |
| `dates <id | url>` |
| `vod <id | url>` |
person <personId> | name, realName, birthDate, birthplace, height, profession, photoUrl, knownForIds, url |
id <url> | {"id": …}、オフライン |
フィールドリファレンス: references/output.md。
終了コード
JSON は標準出力に、エラーは標準エラー出力に {"error": "...", "type": "..."} として出力されます。
| コード | 意味 | 対処方法 |
|---|---|---|
0 | 成功 | JSON を使用 |
2 | 見つからない | ユーザーに伝える；ID を再確認 |
64 | 不正な使用法 | 引数を修正 |
69 | Filmweb / ネットワークエラー | 一度再試行；それでも続く場合はフォールバックを使用 |
フォールバック
この API は非公式であり、変更されたりネットワークによってブロックされる可能性があります。スクリプトがコード 69 で失敗し続ける場合、またはユーザーがスクリプトが提供しないデータ（キャラクター名、レビュー、コメント、完全なクルー）を必要とする場合は、Web 取得ツールまたは curl を使用して公開ページ（film の url、または https://www.filmweb.pl/film/<slug>-<id>）を取得し、そこからデータを読み取ります。データが Web ページから取得されたことをユーザーに伝えます。
ルール
- 検索結果ごとに「念のため」
filmを呼び出さないでください。必要な候補のみを確認してください。 - スクリプトが返さなかったデータをでっち上げないでください。