sonos-hybrid-control

分类: 内容与多媒体 | 上传者: nakamotoliu | 下载: 0 | 版本: v1.0（最新）
Hybrid Sonos control for OpenClaw agent. Use Sonos Web App for media search and playlist selection. Use Sonos CLI for volume, grouping, and transport controls. This design is optimized for locked-screen execution. --- # Sonos Hybrid Control Skill ## Prerequisites **Required (one-time setup):** 1. **OpenClaw Browser Relay Extension for Chrome** - **Location**: `~/clawd/projects/openclaw-browser-relay-rewrite/src/` - **Installation**: Load unpacked extension in `chrome://extensions` - **Must enable**: "Enable auto-attach on all HTTP/HTTPS websites" in extension options - **See**: `~/Documents/OpenClaw-Wiki/03-SOP/SOP_默认网页访问与操作方式.md` 2. **Sonos Web App Login** - Account credentials are stored in Bitwarden (item name maintained there) - Do **not** hardcode or document the account username in this skill - **Auto-login**: If login page appears, credentials are retrieved from Bitwarden at runtime and filled in - Use the local wiki-documented Bitwarden retrieval pattern; do not invent a new secret access flow 3. **Sonos CLI** - Installed via Homebrew: `brew install sonos` - Used for volume, grouping, transport controls **This skill does NOT auto-install the extension.** The extension must be installed and configured manually once. After that, auto-attach mode ensures all HTTP/HTTPS pages (including Sonos Web App) are automatically attached when opened. --- ## Core Principle Use **Sonos Web App** only for: - searching music - selecting playlists - triggering playback when media search is required Use **Sonos CLI** for: - setting target room - adjusting volume - grouping or ungrouping rooms - play / pause / next / previous for already-authorized/currently-loaded content - all control actions during locked-screen execution **Important playback authorization rule:** - When the task involves choosing content (playlist / album / search result / recommendation), the **final playback trigger must be clicked in Sonos Web App**. - Do **not** use CLI to start newly selected content af
更新日志: Source: GitHub https://github.com/nakamotoliu/sonos-hybrid-control
目录结构

当前层级: 根目录
📁 scripts/
- 📄 review.js 939 B
📁 src/
- 📁 cli/
  - 📄 sonos.js 731 B
📄 .gitignore 410 B
📄 EXTENSION_ARCH.md 4.1 KB
📄 README.md 3.5 KB
📄 SKILL.md 28.2 KB
SKILL.md

---
name: sonos-hybrid-control
version: 2.1.0
description: >
  Hybrid Sonos control for OpenClaw agent.
  Use Sonos Web App for media search and playlist selection.
  Use Sonos CLI for volume, grouping, and transport controls.
  This design is optimized for locked-screen execution.
---

# Sonos Hybrid Control Skill

## Prerequisites

**Required (one-time setup):**

1. **OpenClaw Browser Relay Extension for Chrome**
   - **Location**: `~/clawd/projects/openclaw-browser-relay-rewrite/src/`
   - **Installation**: Load unpacked extension in `chrome://extensions`
   - **Must enable**: "Enable auto-attach on all HTTP/HTTPS websites" in extension options
   - **See**: `~/Documents/OpenClaw-Wiki/03-SOP/SOP_默认网页访问与操作方式.md`

2. **Sonos Web App Login**
   - Account credentials are stored in Bitwarden (item name maintained there)
   - Do **not** hardcode or document the account username in this skill
   - **Auto-login**: If login page appears, credentials are retrieved from Bitwarden at runtime and filled in
   - Use the local wiki-documented Bitwarden retrieval pattern; do not invent a new secret access flow

3. **Sonos CLI**
   - Installed via Homebrew: `brew install sonos`
   - Used for volume, grouping, transport controls

**This skill does NOT auto-install the extension.** The extension must be installed and configured manually once. After that, auto-attach mode ensures all HTTP/HTTPS pages (including Sonos Web App) are automatically attached when opened.

---

## Core Principle

Use **Sonos Web App** only for:
- searching music
- selecting playlists
- triggering playback when media search is required

Use **Sonos CLI** for:
- setting target room
- adjusting volume
- grouping or ungrouping rooms
- play / pause / next / previous for already-authorized/currently-loaded content
- all control actions during locked-screen execution

**Important playback authorization rule:**
- When the task involves choosing content (playlist / album / search result / recommendation), the **final playback trigger must be clicked in Sonos Web App**.
- Do **not** use CLI to start newly selected content after discovery, because CLI may fail on permission/authorization for some items even when Web App can play them.

Never use Web UI slider for volume control.
Never rely on Web UI for room grouping if Sonos CLI is available.

---

## Supported Actions

- play_music
- adjust_volume
- group_rooms
- transport_control

---

## Input Interpretation Rules

### play_music
Expected user intent may include:
- play some relaxing music in living room
- 在客厅放一点放松的音乐
- 播放专注歌单
- 在卧室播放适合睡觉的歌

Extract:
- action = play_music
- user_intent = the user's real current listening intent / scene
- target_room = optional
- candidate_queries = 3-5 short natural search phrases generated from the scene

### adjust_volume
Expected user intent may include:
- set living room volume to 20
- 把客厅音量调到20
- 音量小一点
- 把卧室声音调大一点

Extract:
- action = adjust_volume
- target_room = optional
- volume_level = required if explicitly given
If user says only "大一点/小一点", interpret as relative adjustment with small safe steps.

### group_rooms
Expected user intent may include:
- group living room and bedroom
- 把客厅和卧室合并播放
- 让书房也一起播
- 只保留客厅播放

Extract:
- action = group_rooms
- target_room = anchor room / main room
- rooms = list of rooms to join or retain

### transport_control
Expected user intent may include:
- pause
- next song
- 播放下一首
- 暂停客厅
- 继续播放

Extract:
- action = transport_control
- transport = play / pause / next / prev
- target_room = optional

---

## Room Name Resolution (Mandatory)

When user says a fuzzy room keyword (e.g. "客厅"), do not use it directly in CLI.
You must resolve it to an exact speaker name first (e.g. "客厅 play5").

Resolution order:
1. For control-only tasks, prefer resolving exact names from CLI first (`sonos discover`, `sonos status --format json`, `sonos group status --format json` when available).
2. For media-discovery tasks already using the Web App, room cards in the Sonos Web App may also be used as an exact-name source.
3. If multiple exact names match the same keyword, ask a short clarification before control.

After resolution:
- Store `resolved_room_name`
- Use this exact value for every CLI command in this task
- Never fallback to the fuzzy keyword once resolved

## Global Rules

1. If the task requires searching media or choosing content, use Web App.
2. If the task is only control-related, use CLI directly.
3. For locked-screen execution, prefer CLI whenever possible **except** for the final play click on newly selected content, which must stay in Web App.
4. Never claim success without checking result.
5. Default maximum volume is 50 unless the user explicitly requests a higher value.
6. If a room is specified, always resolve user keyword to the exact Sonos speaker name first (mandatory).
7. Use the resolved exact room name for all CLI calls (`--name "<exact_name>"`).
8. If Web playback is triggered successfully, subsequent volume / transport / grouping should use CLI, not Web UI.
9. **Before starting scheduled playback (or any room-specific play task), always run a grouping pre-check.** If current status shows the target room is in a group, ungroup first, then continue playback.
10. Group pre-check must be verified by CLI status after ungroup; do not assume ungroup succeeded.
11. For newly selected media, never replace the Web play trigger with `sonos open`, `sonos play spotify`, `sonos smapi ... + CLI play`, or any other CLI-based start command.

---

## Action: play_music

### When to use
Use this action when the user wants to:
- search by mood / keyword
- play a playlist
- find music in Sonos Web App

### Step 0: Group Pre-check (Mandatory)
If `target_room` is present (especially in cron/scheduled tasks):
1. Resolve target room to exact room name.
2. Run CLI status check for that exact room.
3. If status indicates grouped playback (target room is joined with other rooms), ungroup the target room first using a command that actually exists in this CLI, typically `sonos group solo --name "<resolved_room_name>"` or `sonos group unjoin --name "<resolved_room_name>"`.
4. Re-run `sonos group status` and/or `sonos status --name "<resolved_room_name>"` and confirm the target room is standalone.
5. Only then continue to media search/playback steps.

Do not skip this step for scheduled playback jobs.

### Step A: Ensure Chrome is Running with Sonos Tab

This step MUST work on a locked screen. Never use AppleScript GUI scripting.

**Resource policy (mandatory):**
- On the first attempt, you may reuse an existing attached Sonos tab (`browser tabs` + same domain + attachment info).
- On any retry after a failed playback/search/UI attempt, **always open a fresh Chrome window** for Sonos instead of reusing the previous one.
- Record tab(s) created in this run and close only those tabs/windows when task completes (do not close unrelated user tabs).

1. **Check if Chrome is running:**
   ```bash
   pgrep -x "Google Chrome"
   ```

2. **If Chrome is NOT running (no PID returned):**
   Launch Chrome with a fresh window (works on locked screen, more stable for relay context):
   ```bash
   open -na "Google Chrome" --args --new-window "https://play.sonos.com/zh-cn/web-app"
   ```
   **MANDATORY: Wait 5 seconds** for:
   - Chrome to start
   - Page to load
   - Auto-attach to complete
   
   Then proceed to Step B to verify relay attach status.

3. **If Chrome IS running:**
   Check browser tabs for an existing Sonos tab:
   ```
   browser: action: "tabs", profile: "chrome"
   ```
   - If a tab with URL containing `play.sonos.com` exists and has `wsUrl` → use its `targetId`, go to Step B.
   - If no reusable Sonos tab exists → open one via shell (prefer fresh window for deterministic attach):
     ```bash
     open -na "Google Chrome" --args --new-window "https://play.sonos.com/zh-cn/web-app"
     ```
     **MANDATORY: Wait 5 seconds** for page load and auto-attach to complete.
     Then proceed to Step B to verify relay attach status.

4. **If Chrome was force-quit or zombie:**
   Sometimes Chrome processes linger after force-quit. Kill cleanly first:
   ```bash
   pkill -x "Google Chrome" 2>/dev/null; sleep 2
   open -na "Google Chrome" --args --new-window "https://play.sonos.com/zh-cn/web-app"
   ```
   **MANDATORY: Wait 5 seconds** for page load and auto-attach to complete.
   Then proceed to Step B to verify relay attach status.

5. **If the user wants to watch live:**
   Prefer the visible Chrome relay tab/profile for interactive playback/search demonstrations.
   Only fall back to the isolated `openclaw` browser profile when the visible Chrome relay tab is unavailable, detached, or unusable.

### Step B: Verify Relay Attach

**CRITICAL: This step must happen AFTER the mandatory 5-second wait in Step A.**

**With auto-attach all sites enabled (default)**, pages should attach automatically within 5 seconds of opening.

After the 5-second wait and opening the Sonos page, verify the relay is connected:
```
browser: action: "tabs", profile: "chrome"
```

Attach is considered successful only if:
- a Chrome tab URL contains `play.sonos.com`
- and that tab shows browser-relay attachment metadata (for example `wsUrl` if present in the current tool output)

Do not hardcode a single field name as the only success signal forever. Use the current `browser tabs` output shape and confirm the tab is actually attached.

If no attached Sonos tab is visible after Chrome is running with the Sonos page:
1. Wait 5 more seconds and re-check tabs (auto-attach needs time after page load)
2. If still no `wsUrl`, reopen the Sonos page once in visible Chrome and re-check:
   ```bash
   open -na "Google Chrome" --args --new-window "https://play.sonos.com/zh-cn/web-app"
   ```
   Wait 5 seconds, then re-run `browser tabs`.
3. If still no `wsUrl`, check extension status:
   - Verify extension is loaded in `chrome://extensions`
   - Verify "Enable auto-attach on all HTTP/HTTPS websites" is checked in extension options
   - Verify gateway token is configured correctly
4. If extension is properly configured but still not attaching, try reloading the extension:
   ```
   Tell user: "请在 chrome://extensions 中重新加载 Browser Relay 扩展"
   ```
5. If still fails after verification, report: "Chrome relay 未连接。请确认：
   1. OpenClaw Browser Relay 扩展已安装
   2. Auto-attach all sites 已启用
   3. Gateway token 已配置
   详见：~/Documents/OpenClaw-Wiki/03-SOP/SOP_默认网页访问与操作方式.md"

### Step C: Verify UI Ready and Handle Login

Use browser snapshot.

**If the page shows login form** (email/password input):
1. Get credentials from Bitwarden using the local wiki-documented retrieval pattern.
   - Do **not** hardcode the username or password in this skill.
   - Use the maintained Bitwarden helper/session flow documented in the wiki.
   - Read the relevant local wiki note first if needed, then retrieve the login item and extract username/password at runtime.

2. Fill in login form using browser automation:
   ```
   browser: action: "act", kind: "type", ref: <email_input_ref>, text: "$USERNAME"
   browser: action: "act", kind: "type", ref: <password_input_ref>, text: "$PASSWORD"
   browser: action: "act", kind: "click", ref: <login_button_ref>
   ```

3. Wait 5 seconds for login to complete

4. Take a new snapshot and verify login succeeded

5. If login fails after 2 attempts:
   - Check if credentials are correct in Bitwarden
   - Report: "Sonos 登录失败，请检查 Bitwarden 中的凭证是否正确"

**If the page is already logged in**, confirm at least one of the following is visible:
- playback controls
- room cards
- now playing area
- search entry

If UI elements are still not visible after login:
- Refresh the page and wait 5 seconds
- If still failing, report UI readiness issue

### Step D: Controlled-Randomized Candidate Query Planning
1. Snapshot current playback state
2. If currently playing, pause first
3. Wait until paused state is reflected in UI
4. **For every new search round, open the canonical Sonos search page directly:** `https://play.sonos.com/zh-cn/search`
   - Do not rely on the current page's embedded/top search box when you are inside a playlist, album, or detail page.
   - Reusing the in-page search box from a detail page is considered unreliable and should be treated as invalid for this workflow.
   - After navigating to `/zh-cn/search`, if a previous search layer/panel is still open, **click `关闭` first** to dismiss the stale search overlay/state.
   - Then ensure you are in a fresh search state before entering the new query.
   - After entering the query, verify that the result state actually refreshed for the new keyword before selecting content.
5. Infer the user's **real current listening scene** from the request
   - Treat the user's words as the scene/intention, not as a fixed keyword to compress mechanically.
   - Example scene types:
     - 早晨 / 通勤 / 刚开始工作
     - 上班提神 / 提升状态 / 打起精神
     - 下午专注 / 保持效率
     - 晚上放松 / 回家过渡
     - 睡前 / 安静 / 助眠
     - 怀旧 / 某位歌手 / 某种年代感

5. Generate **3-5 short, natural candidate search phrases** for this scene (mandatory)
   - Think like a real human using a music app to find a fitting playlist.
   - Candidate phrases should be short, natural, and playlist-friendly.
   - Allow slight angle variation between runs so results do not become pathologically fixed.
   - But variation must stay scene-bounded; never drift away from the user's current context just for randomness.
   - Good candidate length: usually 2-6 Chinese characters, sometimes a short natural phrase.

   **Core planning rule: controlled randomization**
   - Do **not** always reuse the same first query for the same intent.
   - For the same scene, rotate among nearby angles such as mood / energy / routine / time-of-day / platform-typical phrasing.
   - Keep all candidates semantically close to the user's present scene.

   **Examples by scene:**
   - 现在时间的歌 / 早上 / 早晨 / 早安
     - 早安
     - 清晨
     - 通勤
     - 晨间
     - 今日节奏
   - 上班提神 / 打起精神 / 提升状态
     - 热歌
     - 提神
     - 振奋
     - 通勤
     - 上班歌单
   - 下午工作 / 保持效率
     - 专注
     - 节奏
     - 工作
     - 提效
     - 轻节拍
   - 晚上放松 / 回家 / 降下来一点
     - 放松
     - 慵懒
     - 治愈
     - 晚间
     - 下班后
   - 睡前 / 助眠
     - 助眠
     - 安静
     - 夜晚
     - 轻音乐
     - 入睡

6. Try candidate queries one by one
   - Start with the strongest/plausible candidate, but permit light variation in candidate order between runs.
   - If a query returns weak, irrelevant, or radio-heavy results, move to the next candidate.
   - Do not keep hammering the same failed wording.

7. Expand full results before choosing content (mandatory)
   - After entering a search query, **first click `全部`** (or the equivalent “all results” entry) to expand the full result view.
   - Treat the pre-expanded mixed summary view as unreliable for final selection.
   - After clicking `全部`, always take a **fresh snapshot** before selecting a result.
   - If the desired result area appears below the fold after expansion, scroll first, then snapshot again, then act.
   - Never reuse a pre-expansion ref after `全部` is clicked.

8. Strict result filter (no live radio)
   - allowed services only: **网易云音乐** and **QQ音乐**
   - after `全部` is expanded, **prioritize results visually grouped under the 网易云音乐 / QQ音乐 icon labels**
   - first choice: 来自网易云音乐 / QQ音乐的 播放列表 / 歌单 / mix / collection
   - second choice: 来自网易云音乐 / QQ音乐的 专辑 / 艺人页中的“播放全部”
   - hard block: 站点 / Radio / Sonos Radio / TuneIn / 直播电台
   - hard block: any result from services other than **网易云音乐** or **QQ音乐**
   - avoid single-song detail pages if possible
   - do not select a result from a generic mixed list if the same search has a clearer 网易云音乐 / QQ音乐 section lower on the page

9. Prefer `播放` as the default final trigger for newly selected content
   - Use `播放` first as the default and more stable path.
   - Use `随机播放` only when the user explicitly asks for shuffle/random playback.
   - This Web App click is mandatory for newly selected content.
   - Do not substitute a CLI start command here, even as a shortcut.

### Step D-1: Search Result Card Click Rule (Mandatory)
When selecting a search result from the results list:
1. Prefer clicking the **outer clickable result card / button**, not an inner text node, icon, paragraph, or label.
2. Match a result card using the combined evidence of:
   - target title text
   - service icon/label (网易云音乐 or QQ音乐)
   - result type hint (播放列表 / 专辑 / 可接受的播放入口)
3. If only inner text is easy to find, walk up to the nearest clickable ancestor (`button`, `[role="button"]`, clickable card container) before clicking.
4. After clicking a result card, you must verify page transition by checking at least one of:
   - detail page opened
   - 播放 / 随机播放 button appeared for that selected item
   - now-playing context clearly switched to the selected content page
5. If click returns without a page transition, treat it as a failed click and retry with a stronger fallback.

### Step D-2: Web Click Fallback Rule (Mandatory)
If snapshot ref click fails, times out, or the page re-renders before the click lands:
1. Refresh the snapshot once if needed.
2. If the failure happened after switching source or clicking `全部`, assume layout changed and the target result may now be lower on the page.
3. Scroll to the relevant 网易云音乐 / QQ音乐 result section if needed.
4. Take a fresh snapshot.
5. If ref-based click is still unstable, fallback immediately to a DOM/evaluate-based click on the **outer clickable result card**, using stable visible text + nearest clickable ancestor.
6. After fallback click, verify that page transition actually happened.
7. Do not keep retrying a stale aria ref multiple times.

Priority order for Web clicks:
- first: snapshot ref click
- second: fresh snapshot ref click after layout refresh / scroll
- third: DOM/evaluate click on nearest clickable ancestor

### Step E: Verify Playback
**Playback-button targeting rule (mandatory):**
- On the selected content detail page, do **not** blindly click the first button whose visible name contains `播放`.
- Prefer the playback button whose `aria-label` is clearly bound to the selected target title, i.e. it contains both `播放` and the chosen content title.
- Example: if the selected title is `『舒缓安神』失眠专属助眠纯音乐`, prefer a button like:
  - `button[aria-label="播放『舒缓安神』失眠专属助眠纯音乐"]`
  - or, if exact match is unavailable, a button whose `aria-label` contains the target title text.
- This rule exists to avoid misclicking the bottom transport bar play control, another card's play button, or an unrelated generic `播放` button elsewhere on the page.
- Only if no title-bound playback button can be found may you fallback to a main-detail-area `播放` / `随机播放` button; if you do, explicitly note in the result that title-bound targeting was unavailable and fallback was used.

**Post-click settle window (mandatory):**
- After clicking `播放` / `随机播放` on a selected non-radio playlist/result, wait **10 seconds** before the CLI verification.
- Do not check CLI immediately after the click.

Playback is successful only if **CLI confirms PLAYING** and Web UI is consistent:
1. target room is correct, if specified
2. now playing content is plausible for the selected result
3. UI state indicates playing or has clearly transitioned
4. CLI `sonos status --name "<room>"` shows `State: PLAYING`

**Truth-source rule (mandatory):**
- Treat Web UI as the action surface for search/selection/clicking.
- Treat CLI as the source of truth for actual playback state.
- If Web UI and CLI disagree temporarily, trust CLI for final success/failure reporting.
- Only claim success when CLI confirms the target room is `PLAYING` and `nowPlaying` is reasonable for the selected content.

Additional hard checks:
- If URI contains `x-sonosapi-stream` (live radio/tunein style), treat as invalid result for this workflow and re-select non-radio content.
- Do not claim success when CLI is `STOPPED` or `PAUSED_PLAYBACK` even if Web UI looks like it played.

**Playback failure recovery (strict two-result policy):**
- Attempt #1: Use the **first suitable non-radio playlist/result** you found, click `播放` / `随机播放`, wait **10 seconds**, then check CLI.
- If CLI still does not confirm `PLAYING`, do **not** click play again on the same playlist/result.
- Do **not** do a second play retry on the same playlist/result.
- Attempt #2: Move directly to the **next suitable non-radio playlist/result** from the current search results, click `播放` / `随机播放`, wait **10 seconds**, then check CLI again.
- If the second result still does not produce CLI-confirmed `PLAYING`, report: `playback could not be confirmed`.

**Explicit limits (mandatory):**
- No third playback attempt.
- No fresh Chrome window retry for playback failure.
- No regenerating candidate queries because playback failed.
- No restarting the whole search round because playback failed.
- Web Click Fallback may help the current click land, but must not increase the number of playback attempts.

### Step F: Optional CLI Room Control
If target_room is specified after Web playback begins:
run CLI with resolved exact room name:
`sonos status --name "<resolved_room_name>"`

If needed after the Web App has already successfully authorized and started the chosen content, you may use:
`sonos play --name "<resolved_room_name>"`

But do **not** use `sonos play` (or any CLI start/open command) as a replacement for the initial playback trigger of newly selected content.

---

## Action: adjust_volume

### Principle
All volume operations must use Sonos CLI.
Do not use Web UI slider.

### If target_room is specified
Resolve to exact room name first, then run:
`sonos status --name "<resolved_room_name>"`

### If user provided exact volume
Run:
`sonos volume set --name "<resolved_room_name>" <volume_level>`

### If user said relative change only
Use safe small-step adjustment:
- "大一点" = increase slightly
- "小一点" = decrease slightly

This CLI should be treated as **absolute-volume only** unless you have directly verified a relative subcommand exists.
Default procedure:
1. Read current volume with `sonos volume get --name "<resolved_room_name>"` (or `sonos status --name "<resolved_room_name>"` if needed).
2. Calculate a nearby safe target.
3. Apply it with `sonos volume set --name "<resolved_room_name>" <target>`.

Do not invent commands such as `volume up`, `volume down`, or additive volume syntax unless `sonos volume --help` on this machine explicitly shows them.

### Safety Rule
If requested volume > 50 and user did not explicitly authorize high volume:
- cap at 50
- tell the user you used the safe limit

### Verification
Run:
`sonos status --name "<resolved_room_name>"`

Confirm:
- target room is correct
- volume reflects the intended target or expected relative change

---

## Action: group_rooms

### Principle
All grouping and ungrouping must use Sonos CLI.

### Grouping
1. Resolve anchor room to exact name (`resolved_room_name`).

2. For each room in rooms, resolve the exact name, then use the actual CLI syntax supported here, typically:
`sonos group join --name "<member_room>" "<resolved_room_name>"`

3. Verify grouping with:
`sonos group status`
and, if useful, `sonos status --name "<resolved_room_name>"`

Confirm that grouped rooms are reflected in group status output.

### Ungrouping
If the user wants only one room to keep playing:
1. switch to the target room
2. use an actually supported command such as:
   - `sonos group solo --name "<resolved_room_name>"` (preferred when the target should play by itself)
   - or `sonos group unjoin --name "<resolved_room_name>"` when leaving the current group
3. verify with:
`sonos group status`
and optionally `sonos status --name "<resolved_room_name>"`

### Notes
Do not use nonexistent top-level commands like `sonos ungroup`, `sonos join`, or `sonos leave` unless a future CLI version explicitly adds them and local help confirms it.
Always verify after grouping changes.

---

## Action: transport_control

### Principle
All transport operations should use Sonos CLI whenever possible.

### If target_room is specified
Resolve to exact room name first.

### Execute by transport value (always with exact name)

If transport = play:
`sonos play --name "<resolved_room_name>"`

If transport = pause:
`sonos pause --name "<resolved_room_name>"`

If transport = next:
`sonos next --name "<resolved_room_name>"`

If transport = prev:
`sonos prev --name "<resolved_room_name>"`

### Verification
Run:
`sonos status --name "<resolved_room_name>"`

Confirm:
- play => state becomes playing
- pause => state becomes paused
- next / prev => track info changes if available

---

## Recovery Flow

### Web Layer Recovery
Use this only for search / playlist selection / playback triggering.

**Scope restriction:**
- For playback failure after a valid click, follow the strict two-result policy in Step E.
- Do **not** expand playback recovery into fresh-window retries, third attempts, or a full search restart.
- This section is mainly for UI targeting problems, page rendering issues, attach issues, or login interruptions.

Allowed recovery actions:
1. refresh snapshot / relocate elements for the current page
2. use Web Click Fallback so the current intended click actually lands
3. if login page appears, complete login and continue
4. only if Chrome is globally unresponsive or relay cannot attach anywhere, consider broader browser recovery as a last resort for general UI access

If login page appears during recovery:
- Follow Step C login protocol (retrieve credentials from Bitwarden at runtime and fill in)
- If auto-login fails after 2 attempts, report: "Sonos 自动登录失败，请检查 Bitwarden 中的凭证"

### CLI Layer Recovery
Use this for volume / grouping / transport:
1. re-resolve room keyword to exact room name
2. retry command once with `--name "<resolved_room_name>"`
3. run `sonos status --name "<resolved_room_name>"`
4. if still failing, report CLI command failure clearly

Do not invent success if CLI output does not confirm the action.

---

## Response Style Rules

### Good success examples
- 已在客厅开始播放“放松”相关歌单，并确认已经进入播放状态。
- 已将客厅音量调整到 20。
- 已把卧室加入客厅的播放分组。
- 已暂停书房播放。

### Good partial-result examples
- 我已经在网页端点击了播放，但 CLI 还没有确认客厅进入稳定播放状态。
- 我已经切换到客厅房间，但这次 CLI 没有返回可确认的音量结果。
- Sonos 网页端当前需要登录，我无法继续搜索和选歌单。

### Never say
- 请手动调音量
- 因为技术限制无法操作
- 因为 OpenAI / Anthropic / API 余额不足所以失败
- 我应该已经成功了
- 我猜应该在播了

Always describe only what has actually been verified.

---

## Priority Routing

If user request includes media discovery:
- use Web App for search/selection
- plan 3-5 scene-bounded candidate search phrases first
- try candidates one by one instead of forcing a single fixed keyword path
- choose results only from **网易云音乐** or **QQ音乐**
- use Web App to click the final play trigger on the chosen content
- then use CLI only for follow-up controls/verification

If user request is only control:
- use CLI directly

Examples:

1. “在客厅播放一点放松的音乐”
- Web search + Web play trigger
- CLI room verification if needed

2. “把客厅音量调到20”
- CLI only

3. “暂停卧室”
- CLI only

4. “把客厅和书房合并播放”
- CLI only

5. “下一首”
- CLI only

---

## Final Execution Principle

For Chinese-region Sonos usage:
- Web App is the media selection layer
- CLI is the device control layer

This split is mandatory for stability, especially during locked-screen execution.
登录后下载/点赞/收藏 ❤ 2 | ★ 0
sonos-hybrid-control

目录结构

SKILL.md

举报内容

提示
