Reolink 摄像头操作员
概述
主要界面：reolink-cli（默认JSON标准输出）。除非被要求，否则不要启动MCP服务器。当用户需要非CLI访问（浏览器、curl、其他语言）时，引导他们使用网关的POST /api。
斜杠命令（仅限Claude Code）——对于固定/单一操作意图，优先使用这些命令；跳过意图映射的开销：
| 斜杠命令 | 等价命令 | 使用场景 |
|---|---|---|
/reolink-cli:status | reolink-cli status | 用户询问当前状态/仪表盘/“情况如何” |
/reolink-cli:features | reolink-cli features | 用户询问插件能做什么/“能做什么” |
/reolink-cli:scan | reolink-cli discover | 扫描局域网/“扫描” |
/reolink-cli:devices | reolink-cli device list | 列出已注册的摄像头 |
/reolink-cli:cache-clean | reolink-cli cache clean dry-run → apply | 清除旧的快照/“清除缓存” |
/reolink-cli:update | reolink-cli self-update | 升级到最新版本（检查GitHub，如果是最新则无操作） |
/reolink-cli:uninstall | reolink-cli setup --uninstall --purge --no-interactive | 完全卸载 |
Claude Code运行时： 当用户的意图与上述七个之一完全匹配时，必须使用斜杠命令——更快（无LLM延迟）、确定性高、可通过/自动补全发现。
其他代理（Codex / Cursor / Copilot / Gemini）： 这些界面不支持插件定义的斜杠命令，因此“斜杠优先”规则不适用——直接跳转到运行等价的reolink-cli … CLI命令。基于技能的意图映射处理其余所有情况。
所有代理： 对于斜杠列表/七个固定操作未涵盖的复合/模糊意图（“当检测到人时通知”、“让它更亮”），回退到基于技能的CLI命令链。
网关对于几乎每个控制命令都是必需的。 CLI默认通过127.0.0.1:9000路由（在config.toml中设置，该文件位于平台配置目录下——Linux为~/.config/reolink-cli/config.toml，macOS为~/Library/Application Support/reolink-cli/config.toml，Windows为%APPDATA%\reolink-cli\config.toml，配置项名为gateway-addr）。如果看到gateway connect failed: Connection refused，说明网关未运行——启动一次：
reolink-cli gateway start --addr 127.0.0.1:9000 &
无需网关即可运行：device add|list|update|remove|resolve|show、config init、discover、features、doctor、cache status|clean——所有读取本地配置或直接与网络通信的命令。（已通过无网关监听时运行每个命令验证。）其他所有命令（ping、login、info、config get/set、image、osd、ptz、detect、light、audio、preview、snapshot、vod、events、users、system reboot、system upgrade）需要网关启动。
信封格式——在CLI上解析.ok，在网关上解析.status：
| 界面 | 成功 | 错误 |
|---|---|---|
| CLI | {ok:true, command, protocol, data} | {ok:false, error:{code, message, retryable}}（标准错误） |
| CLI 批量 | {command, summary, results:[{camera, host, ok, data, error}]} | 每个目标的ok |
网关 /api | {status:"success", data} | {status:"error", code, message}（HTTP状态码 == code） |
references/ 包含按主题划分的配方文件。必须只加载与你任务匹配的文件——references/index.md是路由器。references/troubleshooting.md包含故障诊断决策树。
事实基础（约束）
禁止陈述或暗示以下事实：设备可达性、登录状态、配置值、能力、检测/AI类型、事件计数、VOD文件存在性、用户账户或任何可观察的摄像头状态——除非这些信息来自当前任务中已执行的reolink-cli命令的JSON输出或网关POST /api响应。
禁止：演示风格的列表、猜测的布局、合成的值、在错误/超时后伪造成功、模拟CLI输出的散文/JSON（没有真实响应）、或“设备有X”而未运行get/info/inventory/capabilities。
必须在数据缺失时：说明缺失了什么及其原因（未注册摄像头、网关宕机、认证失败、设备离线），然后采取一个具体的恢复步骤（来自错误恢复表）或提出一个澄清性问题。禁止用看似合理的默认值填补空缺。
意图解释
在选择命令前解决歧义。如果仍不清楚，提供选项询问。
| 用户说 | 命令 | 原因/注意事项 |
|---|---|---|
| 添加用户 | users add | 设备账户，不是CLI摄像头条目 |
| 添加摄像头 | device add | CLI摄像头条目（~/.config/reolink-cli/aliases.toml），不是设备账户 |
| 更改密码 | users passwd（默认）或 device update（CLI凭据） | 询问具体是哪个 |
| 闪烁灯 | light statusled | 机身LED |
| 夜视 | light ir | 不可见红外LED |
| 聚光灯 | light spotlight（手动）或 light whiteled（报警触发） | 同灯泡，不同接线 |
| 太暗 | 先尝试 image tune --bright，如果是在夜间检查 light ir get | 图像调整，不是聚光灯 |
| 倒置 | image flip set --flip | 垂直方向 |
| 镜像 | image flip set --mirror | 水平方向 |
| 遮罩 | privacy mask | 先读取当前区域 |
| 重命名 | osd set --name（画面叠加文字）或 config set device-name（应用） | 询问具体是哪个 |
| 重启 / 重新启动 | system reboot | 30–60秒离线 |
| 升级 / 刷固件 / OTA | system upgrade <file.pak> | ⚠️ 有变砖风险。通过info匹配型号+硬件版本；网关读取本地文件；自动分窗和停等协议。详情见references/admin.md |
| 恢复出厂设置 | — 独立操作；system upgrade --factory-reset 在刷写期间执行重置 | 独立重置功能不在CLI中；请用户使用Reolink应用 |
| 踢出 | users remove（永久）或 users passwd + system reboot（驱逐会话） | 活动会话在users remove后仍存活，直到重启 |
| 快照 | snapshot [--file PATH] | JPEG格式。父目录由二进制文件自动创建（自v0.5.0起）——不要预先mkdir -p目标路径。vod download和preview capture --file同理。 |
| 慢 / 耗时 / 用时 / 性能 / 延迟 / 基准测试 | benchmark [--iterations N] [--phases ...] [--reuse-session] | 每阶段的p50/p95/p99：连接、登录、信息、快照。--reuse-session用于热路径。详情见references/index.md。 |
| CPU / 内存 / 设备负载 / 摄像头是否过载 / 卡顿 | config get performance | 从设备读取实时数据：cpuUsedPercent、codeRate、netDataRate。只读且瞬时——相隔一秒的两次调用结果不同是正常的。并非所有型号都实现此功能；未实现的型号会返回设备级别的拒绝。与benchmark不同，benchmark测量的是客户端往返时间，而非摄像头本身。 |
| rtsp / rtmp / flv 地址 / 流URL / HA / Frigate / go2rtc / VLC | stream url [--kind rtsp,rtmp,flv] [--stream main,sub,ext] [--with-auth] | 默认--kind rtsp --stream main。仅当用户明确要求一次性可粘贴URL时才使用--with-auth。NVR：先device expand再--tag <nvr>。详情见references/media.md。 |
| 8通道NVR / RLN子摄像头 / 通道N | device expand <nvr-name> [--yes | --names A,B,C] | 仅限NVR。每个通道注册一个条目，并用父名称标记。之后：--tag <nvr-name>进行扇出。 |
| 命令被拒绝返回400 / “型号不支持” / 集线器上的电池摄像头 / 暂停后的第一个命令 | 什么都不用做——网关已经重试了。答案中的attempts字段说明是哪一次尝试成功（暂停后通常是3次，连续操作中通常是1次） | 集线器后面的电池子摄像头会休眠并在命令后返回400，与不支持的命令无法区分。何时休眠无法仅通过空闲时间预测（某天的数据显示约2分钟；但后续过夜窗口显示它处于唤醒状态），所以不要试图预先判断。一致的表现是：休眠摄像头需要固定的3次尝试（约1.6秒）来唤醒，而被拒绝的请求本身就是唤醒信号。如果在预算内仍然失败，info → channel.loginState = standby可解释原因——但该字段有延迟，所以它用于解释失败，不能用于预先检查。 |
| 双镜头 / 两个镜头 / 子弹头+PTZ一体机 / 广角和长焦 / 第二镜头 | 先执行 info（检查channel.views、channel.dualLens），然后在配置命令中使用--view N | --view是第三个轴：--channel选择摄像头，--view选择镜头，--stream选择该镜头的编码配置。已验证每个视角独立的命令：encode、privacy mask、detect motion、PTZ。不独立的命令：snapshot（设备对于view≥1返回400）、preview/stream url（协议没有选择器——这些现在拒绝 --view N而不是静默返回view 0）、image/ISP（共享）。默认0 = 普通摄像头的唯一视角。 |
| 预览 / 看一下 / 看N分钟 / 看实时画面 | preview play（打开ffplay窗口） | 默认使用play，而不是capture。用户想要实时窗口，不是文件。 |
| 录制N秒 / 保存剪辑 / 保存 | preview capture --packets ≈N×25 | 仅当用户明确说保存/录制/导出时使用。包计数，不是秒数；主码流约25fps，子码流约10fps |
| 60秒预览（有歧义！） | 如果用户说“预览N秒/分钟” → preview play --packets N×fps。如果用户说“录制N秒” → preview capture。如果确实不清楚，询问。 | 当动词是“预览/查看”时默认使用play，仅当动词是“录制/保存/导出”时使用capture |
| 音量 | audio volume set（主音量） | 询问是否是指静音：audio mute |
| 静音报警 | audio mute | 仅报警音频，非预览 |
| 警笛 / 警报声 / 拉响警报 / 吓跑他们 / 让它发出哔哔声 | audio siren play [--duration N | --times N] [--wait] | 声音大且有副作用——先确认。cmd 263手动呼叫（应用的警笛按钮）；设备在--duration秒后自动停止，或执行audio siren stop。--wait会保持等待直到持续时间结束，然后显式停止并报告stoppedAt + stopAcknowledged——当你需要能够说警笛已停止（不仅仅是已启动）时使用它。来自集线器后面的电池摄像头的400不能作为硬件相关的证据——休眠的子摄像头会像未实现的命令一样返回400。（另外：在一个Home Hub 2上，即使命令成功，警笛也被测量到根本没有发出声音——请参见下面的verified: false。永远不要声称它响了。）网关会重试（测量：空闲>2分钟的摄像头需要3次尝试，约1.6秒），答案中的attempts字段说明是哪一次尝试成功。如果仍然失败，info → channel.loginState = standby可解释原因——但该字段有延迟，所以它用于解释失败，不能用于预先检查。永远不要因为400就告诉用户他们的摄像头缺少某个功能；capabilities才能回答这个问题。light spotlight同理。“检测到移动时拉响警笛”不同——那是audio siren task联动（新型号上通常是405）。 |
| 布防 / 撤防 / 离家 / 在家 / 我要离开了 / 场景模式 / 我在时停止录制 | scene set <id>（使用scene list获取ID，使用scene set --schedule交回时间表） | 仅集线器/NVR。一个开关重新布防所有通道——它不修改每个摄像头的检测配置。先执行scene show：currentSceneId为0表示时间表在驱动。详情见references/scene-mode.md。 |
| 分辨率 / 比特率 / 帧率 / fps / h265 / h264 / 流质量 / 让流变小 | encode set --stream main|sub|third ... | 先执行encode capability——设备未宣告的值会返回400。stream url无关（它只构建播放URL）。 |
| 人物检测 | detect ai --type person | 先检查device inventory --capabilities |
| 车辆 | detect ai --type vehicle | 非所有型号 |
| 开启录制 | record schedule set --enable | |
| 录制配置 / 录制参数 / 预录秒数 / 剪辑大小 | record config get | 只读；循环/预/后录制 / 包时间 |
| SD卡 / 存储卡 / 容量 / 剩余空间 | storage status | 只读；totalGB / remainGB / formatted / mounted |
| 手动录制 / 立即录制 / 开始录制 | — | Reolink IPC不支持；回退到record schedule set --enable/--disable |
| 下载昨天的录像 / 下载录制内容 | vod search --since 24h → vod download NAME | |
| 下载09:45–09:55 / 仅那个剪辑 / 一个时间范围 | vod download --from 2026-09-02T09:45:00 --to 2026-09-02T09:55:00 | 摄像头端剪切——不要下载整个小时再裁剪 |
| 任何报警 / 今天有任何报警 | events query --since 24h | 需要网关 |
| 比实时缓冲区更早的事件历史 / 上周发生了什么 / 集线器事件日志 | --channel N events history --since 7d [--types people,motion]（仅集线器/NVR） | 读取设备记录的事件日志（cmd 516/517），而不是约500条记录的实时环形缓冲区。独立IPC返回400。空列表 = 无匹配事件；集线器在高负载后可能短暂静默，暂停后重试。 |
| 语音提醒 / 语音播报 / 当有人到达时播报 / 检测到人时播放语音 | audio talk（参见references/voice-alert.md） | 仅PCM16 LE单声道；需要capabilities.audioTalk=1 |
| 检测到X执行Y / 自动化 / 事件触发 / 检测-然后-执行 | 必须使用TOML规则通过events monitor init/check/run。禁止使用临时的bash while + events query循环——参见references/event-monitor.md。 | |
| 监控器是否在运行 / 是否有规则触发 / 监控器状态 / 最近触发了什么 | events monitor status（pid + 游标 + lastFires + 每个规则的expired/secondsRemaining）或 events monitor history --last N [--rule NAME] [--since 30m] | 检查正在运行的守护进程，无需重启。过滤器在--last之前应用，所以--rule watch --last 20是该规则的最后20次触发，而非全局尾部的幸存者。 |
| 监视这个摄像头 |
…
[已截断以进行翻译]