| name | netease-baomihua-player |
| description | 通过 bmh 命令行工具操作网易爆米花 macOS 客户端。只要用户要在网易爆米花里搜索、查找、推荐、识别、播放、筛选、刮削，或提到 Emby/Jellyfin/FnOS/WebDAV/SMB/媒体库/网盘，就必须使用此 skill。它适用于 CLI 和 OpenClaw 一类 AI 外部调用场景，重点是先校验客户端状态，再按来源选择正确命令和参数，避免误把服务器内部 ID 当成 TMDB ID。 |
网易爆米花
适用边界
这个 skill 只解决“通过 bmh 控制网易爆米花客户端”。
- 用户要执行媒体操作：使用这个 skill
- 用户只是在问实现原理、接口设计、Swift/CLI 开发：优先做常规代码分析，不要硬套本 skill
- 用户既要操作客户端又要解释 CLI 行为：先按本 skill 完成操作，再补说明
默认工作方式
除非用户明确限制，否则始终按下面顺序执行：
- 解析意图：搜索 / 播放 / 筛选 / 刮削 / 查看来源
- 初始化路径变量
- 执行
check-install
- 根据意图补充
list-filter-sources 或 list-providers
- 只使用真实 CLI 输出组织回复，不脑补结果
如果某一步缺少必要信息，优先通过 CLI 获取；只有 CLI 也无法消除歧义时才向用户确认。
快速启动
执行任何命令前，先初始化路径变量：
BMH_CLI="/Applications/网易爆米花.app/Contents/MacOS/bmh"
每次操作前必须先确认客户端状态：
$BMH_CLI check-install
返回 installed、is_running。
- 未安装：停止并给出安装指引
- 未运行：提示用户先启动客户端
- 已运行：再进入搜索 / 播放 / 筛选 / 刮削分支
这些状态字段用于内部判断。默认只在未安装、未启动或用户明确要求排障时对用户展示。
来源与字段判定
所有后续命令都依赖来源判定，先按这个规则理解返回值：
- 媒体库：
source 为空 / nil / bmh，或来源列表中的 source_type=bmh
- 媒体服务器：
source_type 或归一化后的来源属于 emby、jellyfin、fnos
- 媒体库播放参数：
--tmdb-id + --media-type
- 媒体服务器播放参数：
--credentials-id + --item-id + --media-type
关键约束：
- Emby/Jellyfin/FnOS 条目的
tmdb_id 可能是服务器内部 ID，不能直接当作 --tmdb-id
- 来源不明时，先查来源列表，不要先拍脑袋选一个源
media_type 映射（play 前必查）
play --media-type 只接受整数 2（电影）或 3（剧集），不同来源命令的字段类型不同：
| 结果来源 | 原始 media_type | 传给 play 的值 |
|---|
search | 2（int） | 直接用 2 |
search | 3（int） | 直接用 3 |
filter-bmh-media | "movie"（string） | 必须转成 2 |
filter-bmh-media | "series"（string） | 必须转成 3 |
filter-media-server | "movie"（string） | 必须转成 2 |
filter-media-server | "series"（string） | 必须转成 3 |
禁止：直接把字符串 "movie" / "series" 传给 play --media-type，CLI 会报错。
source 值与播放参数映射
| source（int） | 对应 source_type | 必需参数 |
|---|
nil | bmh | --tmdb-id + --media-type |
1 | emby | --credentials-id + --item-id + --media-type |
2 | jellyfin | --credentials-id + --item-id + --media-type |
3 | fnos | --credentials-id + --item-id + --media-type |
播放前检查清单
执行 play 前逐条确认：
意图路由
把用户请求先归到下面五类之一：
- 搜索/识别/找片/推荐某类内容：
search
- 播放具体条目：
play
- 按条件浏览内容：
filter-bmh-media 或 filter-media-server
- 查看媒体源、网盘、媒体库：
list-filter-sources / list-providers
- 开始刮削、查看进度、刮某个目录：
scrape-start / scrape-status
用户说“推荐”时，不要凭常识直接给片单；优先用搜索或筛选拿真实结果，再基于结果做简短推荐。
命令速查
search - 搜索媒体
$BMH_CLI search --keyword "关键词" --source-type bmh --page 1 --page-size 20
$BMH_CLI search --keyword "关键词" --source-type emby --source-id "uuid"
--source-type 必填：bmh | emby | jellyfin | fnos--source-id：emby/jellyfin/fnos 时传 credentialsID，可先通过 list-filter-sources 获取- 返回单源结果；如果要做“全源搜索”，需要先
list-filter-sources，再对每个来源分别调用 search，最后按来源合并展示
用户未指定来源时，先执行 list-filter-sources 获取所有来源，再逐个来源执行搜索。某个源报错或无结果不影响其他源。
list-filter-sources - 获取可用源
$BMH_CLI list-filter-sources
返回 sources[]（含 source_id, source_type, name）。搜索和媒体服务器筛选前优先调用。
play - 播放媒体
根据来源选择对应的播放参数：
| 来源 | 必填参数 |
|---|
| 媒体库 | --tmdb-id + --media-type |
| Emby/Jellyfin/FnOS | --credentials-id + --item-id + --media-type |
$BMH_CLI play --media-type 2 --tmdb-id "550"
$BMH_CLI play --media-type 2 --credentials-id "uuid" --item-id "12345"
--season 1 --episode 1
关键陷阱：
- Emby/Jellyfin/FnOS 条目的
tmdb_id 绝不能传给 --tmdb-id
search 结果里的 media_type 直接复用；任一 filter 结果若返回 movie/series，必须先转成 2/3- 如果当前上下文里没有可靠的
credentials_id / item_id / tmdb_id，先重新搜索或先展示候选项，不要直接播放
filter-bmh-media - 筛选媒体库
$BMH_CLI filter-bmh-media --media-type "电影" --genres "科幻" --country "日本" --sort-type "高分好评"
所有参数中文传值。支持 --media-type、--genres、--country、--sort-type、--release-year、--page、--page-size。
filter-media-server - 筛选 Emby/Jellyfin（单源）
$BMH_CLI filter-media-server --source-id "uuid" --source-type emby --category "电影" --genres "恐怖" --sort-type "最新更新"
--source-id 和 --source-type 必填- 支持
--category（全部/电影/电视剧/收藏）、--genres、--sort-type（最新更新/最新上映/影片评分）、--release-year
- 不支持
--country
- 所有参数传中文，禁止传英文或 Emby 原生字段名
list-providers - 获取网盘列表
$BMH_CLI list-providers
返回 providers[]（含 provider_id, provider_type, name）。
scrape-start - 启动刮削
$BMH_CLI scrape-start --scope all
$BMH_CLI scrape-start --scope provider --provider-id "uuid"
$BMH_CLI scrape-start --scope path --provider-id "uuid" --path "/Movies"
scrape-status - 查询刮削状态
$BMH_CLI scrape-status
返回 is_active、scan_progress、match_progress。
参数映射原则
把自然语言映射到 CLI 参数时，优先遵循下面规则：
- 地区词：
日本、韩国、美国 -> --country，仅媒体库支持
- 类型词：
电影、电视剧、综艺、动漫 -> 媒体库用 --media-type，媒体服务器用 --category
- 题材词：
科幻、动作、喜剧、恐怖 -> --genres
- 排序词：按命令支持范围映射到
--sort-type
- 年份：
2024、2023 -> --release-year
如果用户条件跨命令不兼容，例如“在 Emby 里按国家筛选”，要明确说明该命令不支持 --country，并给出最接近的可执行方案。
筛选命令选择
| 场景 | 命令 | 是否支持 country |
|---|
| 媒体库 | filter-bmh-media | 支持 |
| Emby/Jellyfin | filter-media-server | 不支持 |
| 来源不明 | 两边都执行，按来源合并展示 | 部分支持 |
关键点：地区词一定映射到 --country，绝不能误塞进 --genres。
回复规范
回复目标是“让用户知道你做了什么、拿到了什么、下一步能做什么”，不要只贴原始 JSON。
- 先说执行了哪个命令以及作用对象
- 再按来源分组给结果
- 有分页时说明
count、total_count、has_more
- 有可播放候选项时，在内部保留后续播放所需的关键字段：
media_type、tmdb_id、credentials_id、item_id
- 出错时给出错误码、原因、下一步建议
当结果包含 poster_url 时，可以用 Markdown 图片增强展示，但文字字段优先，海报放在最右或单独附上，避免影响可读性。
用户可见话术
对用户回复时，不要暴露“模式 A / 模式 B”“模式切换”“内部路由”这类实现细节，除非用户明确在问技术原理或排障。
- 根据
media_type 调整称呼：2 优先称“电影”，3 优先称“电视剧”或“剧集”
- 默认不要强调来源类型，优先使用自然表达，例如“已开始播放《<标题>》”
- 默认不要强调来源类型，优先使用自然表达，例如“已为你播放《<标题>》”
- 需要强调类型时，电影可说“已开始播放电影《<标题>》”，电视剧可说“已开始播放电视剧《<标题>》”
- 如果用户明确说“播放电影《<标题>》”或“播放电视剧《<标题>》”，回复时优先沿用用户的类型表述
- 只有在用户明确询问来源、需要排障、或存在多来源歧义时，才补充来源信息
source_type=bmh 时，对用户统一称“媒体库”，不要说“本地媒体库”或“本地”emby、jellyfin、fnos 时，优先使用来源名称，例如“Geek”，而不是笼统说“Emby 来源”- 可以说明来源和动作，但不要描述内部参数选择过程
- 除非用户明确要求解释实现机制，否则禁止在最终回复中出现“模式 A”“模式 B”字样
避免使用：
- “使用模式 A 播放”
- “切换到模式 B”
- “命中播放模式 A/B”
- “已从本地媒体库找到并开始播放《<标题>》”
- “已从本地开始播放《<标题>》”
- “已从 Emby 来源 Geek 找到并开始播放《<标题>》”
- 在
media_type=3 时说成“已开始播放电影《<标题>》”
- 在
media_type=2 时说成“已开始播放电视剧《<标题>》”
优先使用：
- “已开始播放《<标题>》”
- “已从媒体库开始播放《<标题>》”
- “已从 Geek 开始播放《<标题>》”
详细参考
只有在需要补充参数细节、错误恢复或复杂分支时再读取这些 reference，不要每次都把全部参考文档塞进上下文。
约束
- 不得伪造 CLI 输出
- 不得假设客户端正在运行，必须先
check-install 验证
- 不得把媒体服务器条目的内部 ID 当成 TMDB ID 使用
- 不得在来源不明时只搜单一来源并冒充“全局结果”
- 不得把不支持的自然语言条件强行映射成 CLI 参数
- 未经用户明确要求，不修改用户配置文件
