filmweb 是做什么的？
使用一个小型无依赖的 Python CLI scripts/filmweb.py 从 www.filmweb.pl 背后的 JSON API 获取数据，该脚本始终输出 JSON。
运行脚本
从本技能目录运行。使用任意可用的 Python 启动器：
| 操作系统 | 命令 |
|---|---|
| Linux / macOS | python3 scripts/filmweb.py <command> … |
| Windows | py scripts/filmweb.py <command> … (或 python) |
无需安装步骤。
工作流程
- 获取 Filmweb ID。
- 用户提供了链接 → 运行
filmweb.py id "<url>"（离线处理）。 ID 是 slug 末尾的数字：filmweb.pl/film/Matrix-1999-628→628，filmweb.pl/serial/Gra+o+tron-2011-476848→476848。 - 用户提供了标题 → 运行
filmweb.py search "<title>"。结果按相关性排序。 当用户明确指向电视剧时，添加--type=serial（电影则用--type=film）。 如果有多个标题可能匹配（重拍版、续集、电影 vs 剧集），使用film命令按年份检查，或询问用户。
- 用户提供了链接 → 运行
- 仅获取问题所需的数据。
- 评分、类型、导演、简要剧情 →
film - “谁出演了……” →
cast（film已包含两位主要演员） - “在哪里可以看……” →
vod - “什么时候首映……” →
dates - 完整剧情 →
description；关于某人的详细信息 →person <personId>
- 评分、类型、导演、简要剧情 →
- 用用户的语言回答，并引用
film返回中的url。评分四舍五入到一位小数，并提及投票数（例如“7,6/10 z 872 tys. ocen”）。VOD 价格以兹罗提（zł）给出。
电影和剧集
电影、电视剧和游戏在 Filmweb 上共享同一个 ID 空间，每个命令都接受任意类型——对剧集也可以使用 film <id>（例如 film 476848 获取“Gra o tron”）。输出中的 type 字段（film、serial 等）会标明类型。对于剧集，year 表示第一季的年份，duration 是一集的时长，而非整部剧的时长。
命令
| 命令 | 返回 |
|---|---|
| `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 输出到 stdout；错误输出到 stderr，格式为 {"error": "...", "type": "..."}。
| 退出码 | 含义 | 处理方式 |
|---|---|---|
0 | 成功 | 使用 JSON |
2 | 未找到 | 告知用户；重新检查 ID |
64 | 用法错误 | 修正参数 |
69 | Filmweb / 网络错误 | 重试一次；如果仍然失败，使用备用方案 |
备用方案
该 API 是非官方的，可能因网络原因发生变化或被屏蔽。如果脚本持续以退出码 69 失败，或者用户需要脚本无法提供的数据（角色名、评论、完全演职员表），请使用网页抓取工具或 curl 获取公开页面（来自 film 的 url，或 https://www.filmweb.pl/film/<slug>-<id>）并从中读取数据。告知用户数据来自网页。
规则
- 不要“以防万一”对每个搜索结果都调用
film；只检查你需要的候选条目。 - 不要编造脚本未返回的数据。