Reolink 攝影機操作員
概述
主要介面：reolink-cli（預設為 JSON stdout）。除非被要求，否則不要啟動 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 預覽→套用 | 清除舊快照/「清除快取」 |
/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}}（stderr） |
| CLI batch | {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 命令或閘道器 POST /api 回應的 JSON 輸出中推導而來。
禁止：示範風格的清單、猜測的佈局、合成值、在錯誤/逾時後偽造成功、模仿 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 比對型號+hw_ver；閘道器讀取本機檔案；自動分窗/停止等待。詳細資訊請參考 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 位址/串流網址/HA/Frigate/go2rtc/VLC | stream url [--kind rtsp,rtmp,flv] [--stream main,sub,ext] [--with-auth] | 預設 --kind rtsp --stream main。僅在使用者明確要求一次性貼上網址時才使用 --with-auth。NVR：先執行 device expand，然後使用 --tag <nvr>。詳細資訊請參考 references/media.md。 |
| 具有 8 個頻道的 NVR/RLN 子攝影機/頻道 N | `device expand [--yes | --names A,B,C]` |
| 命令被拒絕 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 | 僅在使用者明確表示儲存/錄製/匯出時使用。封包計數，而非秒數；主串流約 25 fps，子串流約 10 fps |
| 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]`** |
| 設防/撤防/離家/在家/我要離開/場景模式/我在的時候停止錄製 | 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 |
| 人物偵測 | 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） | 讀取裝置記錄的事件日誌（命令 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 + cursor + lastFires + 每個規則的 expired/secondsRemaining）或 events monitor history --last N [--rule NAME] [--since 30m] | 檢查正在執行的守護行程，無需重新啟動。篩選條件在 --last 之前套用，因此 --rule watch --last 20 是該規則的最後 20 次觸發，而不是全域尾端中剩下的任何記錄。 |
| 監控此攝影機 |
...
[因翻譯而截斷]