Jellyfin 控制

一个功能强大的技能，可通过 CLI 控制 Jellyfin 播放及电视电源。

特性

• 🎯 一键播放： tv play "Breaking Bad" —— 开启电视、启动 Jellyfin、查找下一集并开始播放。
• 智能续播： 自动为剧集查找尚未播放的下一集。
• 精准续播位置： 精确恢复电影/剧集上次中断的位置（LG WebOS/Tizen 设备上使用 Seek 作为后备方案）。
• 设备发现： 自动检测可控制的会话（电视、手机、网页端）。
• 远程控制： 完整的播放控制功能（播放、暂停、停止、下一集、上一集、音量调节、静音）。
• 电视电源与应用管理： 开关电视、启动应用 —— 支持在有无 Home Assistant 的环境下工作。
• 双电视后端支持： 可选 Home Assistant 集成或直连 WebOS（适用于 LG 电视，无需 HA）。
• Android TV 支持： 提供直连 ADB 后端，兼容搭载 Google TV 的 Chromecast、Nvidia Shield、Fire TV、Mi Box —— 无需 Home Assistant。
• 三种连接模式： Home Assistant（任意品牌电视）、直连 WebOS（LG 电视）、直连 ADB（Android TV / Fire TV）。

快速入门

最小化配置（仅 Jellyfin，不控制电视）

{
  "skills": {
    "entries": {
      "jellyfin-control": {
        "env": {
          "JF_URL": "http://YOUR_IP:8096",
          "JF_API_KEY": "your-api-key-here",
          "JF_USER": "your-username"
        }
      }
    }
  }
}

配合 Home Assistant（推荐用于电视控制）

{
  "skills": {
    "entries": {
      "jellyfin-control": {
        "env": {
          "JF_URL": "http://192.168.1.50:8096",
          "JF_API_KEY": "your-jellyfin-api-key",
          "JF_USER": "victor",
          "HA_URL": "http://192.168.1.138:8123",
          "HA_TOKEN": "your-ha-long-lived-token",
          "HA_TV_ENTITY": "media_player.lg_webos_tv_oled48c34la",
          "TV_MAC": "AA:BB:CC:DD:EE:FF"
        }
      }
    }
  }
}

直连 WebOS（LG 电视，无需 Home Assistant）

{
  "skills": {
    "entries": {
      "jellyfin-control": {
        "env": {
          "JF_URL": "http://192.168.1.50:8096",
          "JF_API_KEY": "your-jellyfin-api-key",
          "JF_USER": "victor",
          "TV_IP": "192.168.1.100",
          "TV_MAC": "AA:BB:CC:DD:EE:FF"
        }
      }
    }
  }
}

首次使用 WebOS 直连： 电视将显示配对提示。请确认配对，并保存技能输出的 TV_CLIENT_KEY —— 将其加入环境变量后，下次即可跳过该提示。

直连 ADB（Android TV / Fire TV / 搭载 Google TV 的 Chromecast，无需 Home Assistant）

{
  "skills": {
    "entries": {
      "jellyfin-control": {
        "env": {
          "JF_URL": "http://192.168.1.50:8096",
          "JF_API_KEY": "your-jellyfin-api-key",
          "JF_USER": "victor",
          "ADB_DEVICE": "192.168.1.100:5555",
          "TV_MAC": "AA:BB:CC:DD:EE:FF"
        }
      }
    }
  }
}

首次使用 ADB： 在电视上启用开发者选项（设置 → 关于 → 连续点击“版本号”7 次），然后启用网络/USB 调试。首次连接时电视将弹出“是否允许调试？”提示，请确认。要求 OpenClaw 主机已安装 adb（sudo apt install adb）。

环境变量

Jellyfin（必需）

电视控制（可选 —— 任选一种后端）

自动检测逻辑： 若 TV_BACKEND 为 auto（默认值），则按以下顺序判断：

1. 同时设置了 HA_URL、HA_TOKEN 和 HA_TV_ENTITY → 使用 Home Assistant 后端
2. 设置了 ADB_DEVICE → 使用直连 ADB（Android TV）
3. 设置了 TV_IP → 使用直连 WebOS（LG 电视）
4. 均未设置 → 禁用电视指令，进入 Jellyfin 独立运行模式

使用方法

🎯 一键播放（核心功能）

开启电视 → 启动 Jellyfin → 查找下一集 → 播放。全部操作仅需一条命令：

node skills/jellyfin-control/cli.js tv play "Breaking Bad"
node skills/jellyfin-control/cli.js tv play "The Matrix"

该技能会在开启电视前验证内容是否存在（快速失败机制）。

续播 / 智能播放

若电视和 Jellyfin 已处于运行状态：

node skills/jellyfin-control/cli.js resume "Breaking Bad"
node skills/jellyfin-control/cli.js resume "Matrix" --device "Chromecast"

电视控制

node skills/jellyfin-control/cli.js tv on           # 开启电视（Wake-on-LAN）
node skills/jellyfin-control/cli.js tv off          # 关闭电视
node skills/jellyfin-control/cli.js tv launch       # 启动 Jellyfin 应用
node skills/jellyfin-control/cli.js tv launch com.webos.app.hdmi1  # 启动指定应用
node skills/jellyfin-control/cli.js tv apps         # 列出已安装应用

远程控制

node skills/jellyfin-control/cli.js control pause
node skills/jellyfin-control/cli.js control play
node skills/jellyfin-control/cli.js control next
node skills/jellyfin-control/cli.js control vol 50

搜索内容

node skills/jellyfin-control/cli.js search "Star Wars"

媒体库统计与扫描

node skills/jellyfin-control/cli.js stats
node skills/jellyfin-control/cli.js scan            # 需管理员权限 API 密钥

用户历史记录（需管理员权限 API 密钥）

node skills/jellyfin-control/cli.js history
node skills/jellyfin-control/cli.js history jorge --days 7

电视后端选择指南

推荐方案：

• 已部署 Home Assistant？→ 使用 HA 后端（最通用，兼容任意品牌电视）
• 使用 LG WebOS 电视且未部署 HA？→ 使用直连 WebOS 后端
• 使用 Android TV / Fire TV / 搭载 Google TV 的 Chromecast 且未部署 HA？→ 使用直连 ADB 后端
• 无需智能电视控制？→ 跳过电视配置；只要 Jellyfin 应用已打开，resume 命令仍可正常工作

安全须知

• API 密钥仅允许置于 openclaw.json 的 env 字段中 —— 切勿写入 workspace 文件、.env 文件或 Markdown 文档。
• HA Token 具有长期有效性且权限极高。如可能，请创建专用 HA 用户并限制其权限。
• TV_CLIENT_KEY（WebOS）属于敏感信息 —— 它可完全控制你的电视，请视同密码妥善保管。
• ADB 访问权限 可完全控制系统级行为。请确保你的网络环境安全 —— 若启用了调试模式，同一局域网内任何人均可通过 ADB 连接你的 Android TV。
• 管理员操作（如 history、scan）需使用具备管理员权限的 Jellyfin API 密钥；若权限不足，将返回 403 错误并优雅降级。

架构设计

• lib/jellyfin.js —— Jellyfin REST API 封装（认证、搜索、会话管理、播放控制）
• lib/tv.js —— 电视控制抽象层（HA 后端、WebOS 后端、Wake-on-LAN）
• cli.js —— 面向用户的命令行接口，涵盖全部功能指令

工作流示例：Agent 发出指令 “在电视上播放 Star Trek”

Agent → cli.js tv play "Star Trek"
         │
         ├── 1. 在 Jellyfin 中搜索 "Star Trek"（快速失败）
         ├── 2. 查找尚未播放的下一集
         ├── 3. 发送 Wake-on-LAN 指令 → 电视开机
         ├── 4. 等待 10 秒完成系统启动
         ├── 5. 启动 Jellyfin 应用（通过 HA 或 WebOS）
         ├── 6. 等待 8 秒完成会话注册
         ├── 7. 查找 Jellyfin 会话（最多重试 3 次）
         └── 8. 在该会话中播放剧集