- 开发工具
- 桌面应用
【免费下载链接】script-commands
Script Commands let you tailor Raycast to your needs. Think of them as little productivity boosts throughout your day.
本指南基于 commands/remote-control/samsung-tv 目录下的 README 与配套 Python 源码，讲解如何将三星电视的开关机操作接入 Raycast 快捷命令体系。读完本文，你将掌握wakeonlan依赖安装、电视 IP/MAC 获取、模板脚本改名为可运行命令的全流程，并能从源码层理解开机（Wake-on-LAN 魔法包）与关机（Samsung WebSocket 远程控制 API）两条命令的底层工作机制。
命令概览：一键掌控电视开关
该目录为 Raycast Script Commands 仓库中remote-control分类下的三星电视控制命令，包含两个核心命令：
- Turn On TV：通过 Wake-on-LAN 向电视发送魔法包（magic packet），实现局域网内远程开机；
- Turn Off TV：通过三星电视的 WebSocket 远程控制通道发送电源键指令，实现远程关机。
两个命令在 Raycast 中都以compact模式运行（见 turn-on.template.py 与 turn-off.template.py 的@raycast.mode compact），即执行后在 Raycast 界面中展示轻量结果，不打断当前工作流。启用后，在 Raycast 中搜索 "samsung tv" 即可看到上述两条命令并一键运行。
兼容性说明
README 明确指出，并非所有三星电视型号都支持这套远程控制方式，Samsung 官方在开发者站点上维护了完整的兼容型号分组列表（tv-model-groups）。可以推断，该列表对应的是支持 Smart TV WebSocket 远程控制 API的型号群体。在配置前建议先确认自己的电视型号在兼容范围内，否则命令可能无法建立连接。
初始配置三步走
1. 安装 Python 依赖
开机命令依赖wakeonlan第三方库，README 要求通过pip安装：
pip3 install wakeonlan该依赖在 turn-on.template.py 头部注释中被明确声明，并在源码中以import wakeonlan的形式被直接引用。
2. 获取电视的 IP 与 MAC 地址
Samsung 电视的 IP 地址与 MAC 地址都可以在电视本身的网络设置菜单中查到（两个模板脚本的源码注释都明确标注了这一点）。拿到地址后：
- 将电视的MAC 地址填入
turn-on.template.py中的mac_address变量； - 将电视的IP 地址填入
turn-off.template.py中的ip_address变量。
3. 重命名模板并重载 Raycast
仓库中的脚本均为模板形式（文件名含.template.），必须将其重命名以激活：
将
turn-on.template.py→turn-on.py，turn-off.template.py→turn-off.py，即从文件名中移除.template.段。
重命名后，在 Raycast 中重新加载脚本命令，即可看到Turn On TV与Turn Off TV两条命令并开始使用。
深入源码：Raycast 元数据如何驱动命令
两个模板脚本顶部都携带了完整的 Raycast 元数据注释，这些注释定义了命令在 Raycast 中的展示与行为：
| 元数据字段 | Turn On TV 的值 | 说明 |
|---|---|---|
@raycast.schemaVersion | 1 | 脚本命令 Schema 版本号 |
@raycast.title | Turn On TV | 命令在 Raycast 中的显示名称 |
@raycast.mode | compact | 输出模式，另支持inline、fullOutput、silent等 |
@raycast.packageName | Samsung TV | 所属包名，用于命令分组 |
@raycast.icon | images/logo.png | 命令图标，引用同目录下的 logo.png |
@raycast.author | Darryl Brooks | 作者信息 |
@raycast.description | Turns on/off a Samsung TV. | 命令功能描述，显示在 Raycast 搜索列表中 |
这套元数据是 Raycast Script Commands 的标准声明式配置，Raycast 会据此将普通 Python 脚本注册为可搜索、可执行的原生命令。
开机命令的原理：Wake-on-LAN 魔法包
turn-on.template.py 的实现非常精简，核心逻辑只有两行：
import wakeonlan mac_address = '00:00:00:00:00:00' # 填入电视的 MAC 地址 wakeonlan.send_magic_packet(mac_address)wakeonlan.send_magic_packet()会向局域网广播发送标准的 WoL 魔法包（magic packet），该数据帧内重复包含目标设备的 MAC 地址，处于待机状态且开启网络唤醒功能的三星电视收到后即被唤醒开机。
由于开机依赖的是数据链路层广播而非 IP 层连接，因此开机命令只需要 MAC 地址，不需要 IP 地址——这正是turn-on.template.py只声明mac_address参数的原因。
关机命令的原理：Samsung WebSocket 远程控制 API
关机流程远比开机复杂，它需要与电视建立实时的 WebSocket 长连接。整体调用链如下：
turn-off.template.py └─ SamsungTVWS(host=ip_address, port=8002, token_file=tv-token.txt) └─ tv.shortcuts().power() └─ SamsungTVShortcuts.power() └─ remote.send_key('KEY_POWER') └─ SamsungTVWS._ws_send({method: 'ms.remote.control', ...})连接参数与 Token 缓存
turn-off.template.py 创建了SamsungTVWS客户端实例：
ip_address = '192.168.0.00' # 填入电视的 IP 地址 token_file = os.path.dirname(os.path.realpath(__file__)) + '/tv-token.txt' tv = SamsungTVWS(host=ip_address, port=8002, token_file=token_file) tv.shortcuts().power()关键点：
port=8002：这是三星电视 WebSocket 远程控制 API 的标准端口。从 samsunghelper.py 的_is_ssl_connection()方法可见，端口为 8002 时被视为 SSL/TLS 安全连接，会走wss://协议并携带 token。token_file：首次连接时电视会下发一个认证 token，客户端将其缓存在tv-token.txt文件中（路径为脚本所在目录），后续连接自动复用，避免每次都弹出授权确认。
连接协议与认证流程
samsunghelper.py 定义了两种连接 URL 格式：
_URL_FORMAT = 'ws://{host}:{port}/api/v2/channels/samsung.remote.control?name={name}' _SSL_URL_FORMAT = 'wss://{host}:{port}/api/v2/channels/samsung.remote.control?name={name}&token={token}'- 非 8002 端口：使用明文
ws://，通过name参数（默认SamsungTvRemote，经_serialize_string()做 base64 编码）标识设备； - 8002 端口：使用加密
wss://，URL 中额外携带从token_file读取的token。
open()方法（samsunghelper.py）负责建立连接：发送请求后读取响应，若响应data中包含token字段则通过_set_token()写入 token 文件；若响应事件不是ms.channel.connect，则关闭连接并抛出ConnectionFailure异常。
按键指令的发送格式
send_key()方法（samsunghelper.py）把按键封装为标准的三星远程控制消息：
{ 'method': 'ms.remote.control', 'params': { 'Cmd': 'Click', 'DataOfCmd': 'KEY_POWER', 'Option': 'false', 'TypeOfRemote': 'SendRemoteKey' } }发送后根据key_press_delay（默认 1 秒）等待按键生效。而power()命令本身定义在 samsungshortcuts.py 中：
def power(self): self.remote.send_key('KEY_POWER')即向电视发送电源键（KEY_POWER）的点击事件，电视收到后执行关机。
异常处理体系
samsungexceptions.py 定义了三个异常类型，覆盖了命令运行中的主要失败场景：
ConnectionFailure：连接建立失败或握手事件异常；ResponseError：电视返回内容无法解析（源码注释提示"可能该型号不支持此功能"）；HttpApiError：HTTP API 调用错误（为后续扩展预留）。
从源码结构看，这套异常体系是命令在真实网络环境中保持稳定性的保障——例如首次连接时电视拒绝授权、电视型号不支持远程控制等场景，都会以异常形式暴露给用户排查。
部署注意事项与已知问题
辅助文件必须与命令放在同一目录
两个模板脚本头部注释都强调：必须将samsunghelper.py、samsungshortcuts.py、samsungexceptions.py三个辅助文件复制到启用后的命令脚本旁边，否则关机命令无法运行。此外 turn-off.template.py 中的sys.path.append('../')会将上一级目录加入模块搜索路径，这是为了兼容 Raycast 对脚本命令的组织方式。
首次使用的授权流程
README 的 "Important" 部分明确了两点首次使用的注意事项：
- 首次连接需要在电视上允许设备接入——当你第一次运行关机命令时，电视屏幕会弹出连接授权提示，确认后电视才会下发 token；
- 部分电视需要在系统设置中开启"允许 IP 远程设备连接"——如果你的电视型号默认关闭此选项，命令将无法建立连接，需先在电视设置中手动开启。
已知问题：关机后无法立即开机
README 记录了该命令集目前已知的固有限制：
电视关机后，约 10～15 秒内无法通过
Turn On TV命令重新开机。
这是由电视关机后的网络状态决定的——刚断电/待机的短时间内，电视的网络唤醒栈尚未完全就绪或仍处于连接关闭状态，WoL 魔法包会被忽略。如果你的使用场景对"关机后立刻开机"有强需求，需要接受这一延迟。
小结
三星电视控制命令是 Raycast Script Commands 中"以几行 Python 完成智能家居远程控制"的典型示例：开机复用成熟的 Wake-on-LAN 协议，仅需一行send_magic_packet；关机则借助 samsunghelper.py 封装的三星 WebSocket 远程控制 API，完成 token 认证、SSL 连接与按键指令下发。整个配置过程只需安装依赖、填入电视 IP/MAC、重命名模板三步。若需排查问题，可从异常定义与按键封装入手，结合本文的调用链逐层定位。
- 开发工具
- 桌面应用
【免费下载链接】script-commands
Script Commands let you tailor Raycast to your needs. Think of them as little productivity boosts throughout your day.
相关推荐
开源项目安装与配置指南：Raycast Script Commands
开源项目安装与配置指南：Raycast Script Commands 1. 项目基础介绍 Raycast Script Commands 是一个开源项目，它允
开发工具桌面应用Raycast Script Commands 使用指南
Raycast Script Commands 使用指南 1. 项目介绍 Raycast 是一款允许用户通过几个键盘快捷键控制桌面工具的应用程序。通过安装 Sc
开发工具桌面应用Raycast Script Commands实战：从零构建你的第一个脚本命令
Raycast Script Commands实战：从零构建你的第一个脚本命令 本文详细介绍了Raycast Script Commands的开发实践，从基础模
开发工具桌面应用
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
