@openbrt/audioctl 0.1.4 → 0.1.6

package/README.md

@@ -19,15 +19,20 @@ Agent contract:
 
 - If already bound, inspect the device and run the high-level task directly.
 - If not bound, ask the user only for the short binding code, then bind and continue.
+- Bluetooth/Wi-Fi provisioning is only for getting the device online and binding
+  it to weclawbot.link. It must not decide whether the speaker is used for
+  NetEase, Spotify, voice remote control, smart-home control, or anything else.
 - Preferred BYOA flow: use a legal music platform API in the agent environment
-  to build a playable queue, then push it with `audioctl queue QUEUE.json --play --json`.
-  NetEase Cloud Music Open Platform can be used this way to request the highest
-  available quality URLs. Spotify should be driven through official Spotify
-  Connect/Web Playback SDK or existing-user playback control; do not assume the
-  Spotify Web API gives full-track direct audio URLs.
-- If music-platform authorization is missing, guide the user through the
-  platform authorization entry available to the agent/phone, then continue after
-  the user says “已授权”.
+  or another user-approved source to build a playable queue, then push it with
+  `audioctl queue QUEUE.json --play --json`. The plugin suggests sources; the
+  agent and user choose. NetEase Cloud Music Open Platform can be used this way
+  to request the highest available quality URLs. Spotify should be driven through
+  official Spotify Connect/Web Playback SDK or existing-user playback control;
+  do not assume the Spotify Web API gives full-track direct audio URLs.
+- If music-platform authorization is missing, use the current agent's official
+  connector, OAuth flow, or secret store for that platform. Bluetooth/Wi-Fi
+  provisioning is not a music-platform authorization entry and is not a
+  product-purpose decision point.
 - Never ask the user to paste AppSecret, PrivateKey, accessToken, refreshToken,
   Wi-Fi passwords, MQTT credentials, or other secrets into chat.
 
@@ -61,6 +66,11 @@ audioctl volumeup
 audioctl volumedown
 audioctl status
 audioctl inspect --json
+audioctl feedback signal ready
+audioctl feedback flash cyan --repeat 2
+audioctl feedback volume 66
+audioctl feedback beep
+audioctl feedback clear
 audioctl queue ./work-bgm.queue.json --play
 audioctl workbgm --play
 audioctl rule ./my-playlist-rule.json
@@ -73,6 +83,29 @@ existing MQTT channel. Agent scripts can read Wi-Fi connection state, BLE
 provisioning state, wake-word capability, playback, VM/app status, and health
 without receiving Wi-Fi passwords, MQTT credentials, or music-platform secrets.
 
+`feedback`/`led` controls expose generic device feedback. Agents should prefer
+semantic signals (`ready`, `busy`, `success`, `error`, `playing`, `paused`,
+`volume_step_up`, `volume_step_down`, `button_press`) so each hardware adapter
+can map them to its native LED ring, small screen, haptic motor, or speaker
+prompt. Explicit LED controls are also available:
+
+```bash
+audioctl feedback signal playing
+audioctl feedback flash '#00ffff' --repeat 2
+audioctl feedback volume 42
+audioctl feedback beep
+audioctl feedback clear
+audioctl led flash amber --repeat 1
+```
+
+Physical keys/touch surfaces are reported as VM capabilities such as
+`input.touch.read`, `input.gesture.read`, and `input.button.bind`. A VM app can
+declare those capabilities and bind local gestures to safe device actions; for a
+music endpoint the recommended default is center click = play/pause toggle,
+edge click = next, and clockwise/counter-clockwise = volume step up/down with a
+short beep and a volume LED indication. These bindings are device-local for low
+latency and do not require the agent to be online for every tap.
+
 `queue --play` is the generic agent-built music path. The agent uses the user's
 authorized music provider outside the speaker, writes a
 `weclawbot.playable_queue.v1`/`schemaVersion: 1` queue containing only safe media
@@ -89,8 +122,9 @@ If the device reports `netease_auth_refresh_failed`, that only means the legacy
 device-side NetEase runtime cannot refresh itself. The better agent behavior is
 to switch to the BYOA queue/app path: obtain the user's music-platform identity
 in the agent environment, build a fresh queue, and push it with `audioctl queue`.
-Only if the user explicitly wants the device-side NetEase runtime should the
-agent route them to the phone authorization entry.
+Only if the user explicitly wants the legacy device-side NetEase runtime should
+the agent say a separate device-side music-account settings entry is required.
+That entry must be separate from Bluetooth/Wi-Fi provisioning.
 
 `deepnight` pushes the bundled “深夜工作” playlist rule and asks the device to
 refresh/play according to its local runtime. The package never contains music
@@ -113,3 +147,22 @@ The MQTT control message is:
 
 Supported commands include `play`, `pause`, `toggle`, `next`, `previous`,
 `seek`, `set_volume`, `volume_up`, `volume_down`, `status`, and `set_rule`.
+
+Feedback messages use the same MQTT envelope:
+
+```json
+{
+  "schema": "weclawbot.control.v1",
+  "id": "feedback_<uuid>",
+  "kind": "feedback_command",
+  "feedback": {
+    "command": "flash",
+    "color": { "red": 0, "green": 255, "blue": 255, "alpha": 255 },
+    "repeat": 2
+  }
+}
+```
+
+Supported feedback commands are `signal`, `flash`, `volume`, `beep`, and
+`clear`. Devices that do not report a matching `feedback.*` capability should
+reject the command instead of pretending to support it.

package/agent-plugin.json

@@ -6,10 +6,16 @@
   "bin": "audioctl",
   "description": "Bind and drive WeClawBot-compatible audio, voice, and ambient I/O devices from user-owned AI agents.",
   "transport": "weclawbot.link/mqtt",
-  "user_contract": "用户只需要给出设备身份和目标；agent 负责选择合法平台 API、完成授权引导、构建最小权限脚本/队列、推送到设备 VM、诊断和报告结果。",
+  "user_contract": "用户只需要给出设备身份和目标；agent 负责选择合法平台 API、通过 agent 自己的连接器/OAuth/secret store 获取平台身份、构建最小权限脚本/队列、推送到设备 VM、诊断和报告结果。",
+  "separation_of_concerns": {
+    "provisioning": "蓝牙/Wi-Fi 配网只负责设备入网、发现和 weclawbot.link 绑定，不承载音乐平台授权，也不决定设备用途。",
+    "music_platform_auth": "音乐平台授权属于 agent 侧能力，由 agent 的连接器、OAuth、secret store 或用户明确提供的运行环境凭据完成。",
+    "device_purpose": "设备用途由 agent 安装的 VM app 和显式 capabilities 决定，不由配网流程决定。"
+  },
   "device_classes": [
     "audio_io",
     "audio_output",
+    "ambient_io",
     "voice_endpoint",
     "smart_home_endpoint",
     "music_player"
@@ -35,6 +41,14 @@
     "audio.tts",
     "voice.wakeword",
     "voice.capture",
+    "input.touch.read",
+    "input.gesture.read",
+    "input.button.bind",
+    "feedback.signal",
+    "feedback.led",
+    "feedback.led_ring",
+    "feedback.volume_level",
+    "feedback.beep",
     "iot.control",
     "device.inspect",
     "music.autopilot",
@@ -54,13 +68,19 @@
     {
       "intent": "帮我在音箱建立一个工作 BGM 歌单，持续播放",
       "primary_command": "audioctl queue QUEUE.json --play --json",
-      "agent_strategy": "先运行 audioctl inspect --json。优先在 agent 侧使用用户授权的音乐平台 API 生成 QUEUE.json，再运行 audioctl queue QUEUE.json --play --json；网易云开放平台可生成最高可用音质播放 URL。Spotify 必须走官方 Spotify Connect/Web Playback SDK 或控制用户已有 Spotify 设备，不能假设 Web API 能提供完整歌曲直链。如果 agent 当前没有音乐平台身份，只要求用户在 agent/手机授权入口完成对应平台授权。",
+      "agent_strategy": "先运行 audioctl inspect --json。音乐来源由 agent 和用户协商，插件只做建议：可选用户已授权的音乐平台 API、用户媒体库、合法公开音源或生成式环境声。选定来源后，在 agent 侧生成 QUEUE.json，再运行 audioctl queue QUEUE.json --play --json。网易云开放平台可请求最高可用音质播放 URL；Spotify 必须走官方 Spotify Connect/Web Playback SDK 或控制用户已有 Spotify 设备，不能假设 Web API 能提供完整歌曲直链。如果 agent 当前没有音乐平台身份，只要求用户把音乐平台连接到该 agent 的连接器/OAuth/secret store；蓝牙配网和设备入网不是音乐平台授权入口。",
       "fallback_command": "audioctl workbgm --play --json",
       "if_unbound": "只向用户索要绑定码，然后运行 audioctl bind CODE --name AGENT；不要要求用户理解 MQTT、topic 或凭据文件。",
-      "if_music_platform_auth_missing": "告诉用户：我需要你给这个 agent 一个音乐平台身份。请在 agent 支持的网易云开放平台或 Spotify 官方授权入口完成授权；完成后只需回复“已授权”。不要把 AppSecret、PrivateKey、accessToken、refreshToken、Wi-Fi 密码或 MQTT 凭据粘贴到聊天里。",
-      "if_device_side_netease_auth_failed": "这是设备内置网易运行时的旧授权失效。优先不要让用户折腾原厂 App；改由 agent 侧使用用户授权的音乐平台 API 生成队列并推送。只有当用户明确要继续使用设备侧网易运行时时，才引导手机端重新授权。",
+      "if_music_platform_auth_missing": "告诉用户：我需要你把音乐平台身份连接到当前 agent。请使用当前 agent 提供的网易云开放平台、Spotify 等官方连接器/OAuth/secret store 完成授权；完成后只需回复“已授权”。音乐授权不属于蓝牙/Wi-Fi 配网范围，也不要把 AppSecret、PrivateKey、accessToken、refreshToken、Wi-Fi 密码或 MQTT 凭据粘贴到聊天里。",
+      "if_device_side_netease_auth_failed": "这是设备内置网易运行时的旧授权失效。优先不要让用户折腾设备侧音乐账号；改由 agent 侧使用用户授权的音乐平台 API 生成队列并推送。只有当用户明确要求继续使用设备侧网易运行时时，才提示需要一个独立的设备侧音乐账号设置入口；不要把它混入蓝牙/Wi-Fi 配网流程。",
       "after_user_confirms_authorized": "agent 使用已授权的平台 API 生成 QUEUE.json，运行 audioctl queue QUEUE.json --play --json，然后报告是否 active/degraded。"
     },
+    {
+      "intent": "帮我把设备灯效、音量灯和按键反馈音接上",
+      "primary_command": "audioctl feedback signal ready",
+      "agent_strategy": "先运行 audioctl inspect --json 确认设备报告 feedback.* 和 input.* capabilities。语义反馈优先使用 audioctl feedback signal ready|busy|success|error|playing|paused|volume_step_up|volume_step_down；显式灯色可用 audioctl feedback flash cyan --repeat 2；音量环可用 audioctl feedback volume 66；短反馈音可用 audioctl feedback beep。物理按键/触控属于 VM app 的 input.button.bind 能力，默认建议：中心单击 toggle/pause-play，边缘点按 next，旋转/滑动 volume_up 和 volume_down，同时给 feedback.beep 与 feedback.volume_level。",
+      "if_missing_capability": "不要伪造灯效或按键能力；如果 inspect 未报告对应 capability，只说明当前设备适配未提供该能力，并建议安装或升级设备 VM。"
+    },
     {
       "intent": "让音箱作为语音遥控、家庭智能或语音互动端点",
       "primary_command": "audioctl app install MANIFEST.json APP.wasm",
@@ -84,6 +104,14 @@
       "name": "control",
       "usage": "audioctl play|pause|toggle|next|previous|volumeup|volumedown|status"
     },
+    {
+      "name": "feedback",
+      "usage": "audioctl feedback signal NAME | flash COLOR | volume 0..100 | clear | beep"
+    },
+    {
+      "name": "led",
+      "usage": "audioctl led flash COLOR [--repeat N]"
+    },
     {
       "name": "volume",
       "usage": "audioctl volume 0..100"

package/bin/audioctl.mjs

@@ -13,6 +13,7 @@ import {
   buildAppInstallControl,
   buildAgentPrompt,
   buildAudioControl,
+  buildFeedbackControl,
   buildQueueControl,
   buildWorkBgmAppInstallControl,
   expandPath,
@@ -52,6 +53,7 @@ async function run(name, values) {
   if (name === "deepnight") return commandDeepnight(values);
   if (name === "volume") return commandVolume(values);
   if (name === "seek") return commandSeek(values);
+  if (name === "feedback" || name === "led") return commandFeedback(values);
   return commandControl(name, values);
 }
 
@@ -64,6 +66,11 @@ function usage(exitCode = 0) {
   ${COMMAND_NAME} play|pause|toggle|next|previous|volumeup|volumedown|status
   ${COMMAND_NAME} volume 0..100
   ${COMMAND_NAME} seek MILLISECONDS
+  ${COMMAND_NAME} feedback signal NAME [--level 0..100]
+  ${COMMAND_NAME} feedback flash COLOR [--repeat N]
+  ${COMMAND_NAME} feedback volume 0..100
+  ${COMMAND_NAME} feedback clear|beep
+  ${COMMAND_NAME} led flash COLOR [--repeat N]
   ${COMMAND_NAME} rule RULE.json
   ${COMMAND_NAME} queue QUEUE.json [--play]
   ${COMMAND_NAME} app install MANIFEST.json APP.wasm
@@ -309,6 +316,62 @@ async function commandSeek(values) {
   await send("seek", options, { positionMs: options._[0] });
 }
 
+async function commandFeedback(values) {
+  const subcommand = String(values[0] || "").replace(/-/gu, "_").toLowerCase();
+  const shorthandSignals = new Set([
+    "ready",
+    "busy",
+    "loading",
+    "success",
+    "error",
+    "playing",
+    "paused",
+    "wake",
+    "music_beat",
+    "volume_step_up",
+    "volume_step_down",
+    "button_press",
+    "button_long_press",
+  ]);
+  const options = parseOptions(values.slice(1), {
+    credentials: credentialsPath(),
+    timeout: 12,
+    json: false,
+    nowait: false,
+  });
+
+  let command = subcommand;
+  const payload = {};
+  if (!command) throw new Error("feedback_requires_subcommand");
+  if (shorthandSignals.has(command)) {
+    payload.semantic = command;
+    command = "signal";
+  } else if (command === "signal") {
+    payload.semantic = options._[0];
+  } else if (command === "flash") {
+    payload.color = options._[0] || options.color;
+    payload.repeat = options.repeat;
+    payload.alpha = options.alpha;
+  } else if (command === "volume") {
+    payload.level = options._[0] ?? options.level;
+  } else if (command === "beep") {
+    payload.pattern = options._[0] || options.pattern;
+  } else if (command === "clear" || command === "off" || command === "hide") {
+    command = "clear";
+  }
+  if (options.level !== undefined && payload.level === undefined) payload.level = options.level;
+  if (options.volume !== undefined && payload.level === undefined) payload.level = options.volume;
+
+  const control = buildFeedbackControl(command, payload);
+  const credentials = await readCredentials(options.credentials);
+  const delivery = await publishAudioControl(credentials, control, {
+    timeoutMs: Number(options.timeout) * 1000,
+    wait: !options.nowait,
+  });
+  print(delivery.status || delivery, options.json);
+  if (delivery.status?.kind === "rejected") process.exitCode = 1;
+}
+
 async function commandControl(name, values) {
   const options = parseOptions(values, {
     credentials: credentialsPath(),
@@ -349,11 +412,17 @@ function parseOptions(values, defaults = {}) {
     if (!new Set([
       "agent",
       "alias",
+      "alpha",
+      "color",
       "credentials",
       "endpoint",
+      "level",
       "name",
+      "pattern",
       "profile",
+      "repeat",
       "timeout",
+      "volume",
     ]).has(key)) {
       throw new Error(`option_unknown: --${key}`);
     }

package/lib/index.mjs

@@ -47,6 +47,36 @@ export const WORKBGM_RULE = Object.freeze({
 
 export const PLAYABLE_QUEUE_SCHEMA = "weclawbot.playable_queue.v1";
 
+export const FEEDBACK_COLOR_NAMES = Object.freeze({
+  red: Object.freeze({ red: 255, green: 0, blue: 0, alpha: 255 }),
+  green: Object.freeze({ red: 0, green: 255, blue: 64, alpha: 255 }),
+  blue: Object.freeze({ red: 0, green: 96, blue: 255, alpha: 255 }),
+  cyan: Object.freeze({ red: 0, green: 255, blue: 255, alpha: 255 }),
+  yellow: Object.freeze({ red: 255, green: 220, blue: 0, alpha: 255 }),
+  amber: Object.freeze({ red: 255, green: 96, blue: 0, alpha: 255 }),
+  orange: Object.freeze({ red: 255, green: 96, blue: 0, alpha: 255 }),
+  purple: Object.freeze({ red: 180, green: 0, blue: 255, alpha: 255 }),
+  white: Object.freeze({ red: 255, green: 255, blue: 255, alpha: 255 }),
+  off: Object.freeze({ red: 0, green: 0, blue: 0, alpha: 0 }),
+});
+
+export const FEEDBACK_SIGNALS = Object.freeze([
+  "ready",
+  "busy",
+  "loading",
+  "success",
+  "error",
+  "playing",
+  "paused",
+  "wake",
+  "music_beat",
+  "volume_step_up",
+  "volume_step_down",
+  "button_press",
+  "button_long_press",
+  "clear",
+]);
+
 const WORKBGM_APP_WASM_BASE64 =
   "AGFzbQEAAAABBAFgAAADAgEABwgBBG1haW4AAAoEAQIACw==";
 
@@ -176,6 +206,16 @@ export function buildAudioControl(command, options = {}) {
   };
 }
 
+export function buildFeedbackControl(command, options = {}) {
+  const feedback = normalizeFeedbackCommand(command, options);
+  return {
+    schema: "weclawbot.control.v1",
+    id: string(options.id) || `feedback_${crypto.randomUUID()}`,
+    kind: "feedback_command",
+    feedback,
+  };
+}
+
 export function buildQueueControl(options = {}) {
   return buildAudioControl("set_queue", {
     id: options.id,
@@ -225,6 +265,11 @@ export function buildWorkBgmAppInstallControl(options = {}) {
         "music.state.read",
         "music.rule.write",
         "music.playback.write",
+        "input.touch.read",
+        "input.button.bind",
+        "feedback.signal",
+        "feedback.led_ring",
+        "feedback.beep",
       ],
       limits: {
         wasm_bytes: 4096,
@@ -248,6 +293,33 @@ export function buildWorkBgmAppInstallControl(options = {}) {
         play_request_id: play ? `play_${crypto.randomUUID()}` : "",
         refresh: true,
         rule: WORKBGM_RULE,
+        input_bindings: [
+          {
+            input: "center.single_click",
+            action: "music.toggle",
+            feedback: ["feedback.beep", "feedback.signal:button_press"],
+          },
+          {
+            input: "ring.single_click",
+            action: "music.next",
+            feedback: ["feedback.beep", "feedback.signal:button_press"],
+          },
+          {
+            input: "ring.clockwise",
+            action: "music.volume_up",
+            feedback: ["feedback.beep", "feedback.volume_level"],
+          },
+          {
+            input: "ring.counter_clockwise",
+            action: "music.volume_down",
+            feedback: ["feedback.beep", "feedback.volume_level"],
+          },
+        ],
+        feedback_policy: {
+          button_sound: true,
+          volume_led: true,
+          playback_led: true,
+        },
       },
     },
   });
@@ -310,6 +382,95 @@ export function normalizeAudioCommand(command, options = {}) {
   return music;
 }
 
+export function normalizeFeedbackCommand(command, options = {}) {
+  const aliases = new Map([
+    ["hide", "clear"],
+    ["off", "clear"],
+    ["baseline", "clear"],
+    ["light", "flash"],
+    ["led", "flash"],
+    ["sound", "beep"],
+    ["tone", "beep"],
+    ["ding", "beep"],
+    ["vol", "volume"],
+    ["volume_level", "volume"],
+  ]);
+  const raw = string(command || options.command || options.action || "signal")
+    .replace(/-/gu, "_")
+    .toLowerCase();
+  const normalized = aliases.get(raw) || raw;
+  const supported = new Set(["signal", "flash", "volume", "clear", "beep"]);
+  if (!supported.has(normalized)) {
+    throw new Error(`feedback_command_unsupported: ${command}`);
+  }
+
+  const feedback = { command: normalized };
+  if (normalized === "signal") {
+    const semantic = string(
+      options.semantic ||
+        options.signal ||
+        options.name ||
+        options.value ||
+        "button_press",
+    ).replace(/-/gu, "_").toLowerCase();
+    if (!/^[a-z0-9_.:]{1,64}$/u.test(semantic)) {
+      throw new Error("feedback_signal_invalid");
+    }
+    feedback.signal = semantic;
+    if (options.level !== undefined || options.volume !== undefined) {
+      feedback.level = normalizePercent(options.level ?? options.volume);
+    }
+  }
+  if (normalized === "flash") {
+    feedback.color = normalizeFeedbackColor(options.color || options.value || "cyan", {
+      alpha: options.alpha,
+    });
+    feedback.repeat = clamp(Number(options.repeat) || 1, 1, 8);
+  }
+  if (normalized === "volume") {
+    feedback.level = normalizePercent(options.level ?? options.volume ?? options.value);
+  }
+  if (normalized === "beep" && options.pattern !== undefined) {
+    const pattern = string(options.pattern);
+    if (!/^[a-z0-9_.:-]{1,64}$/u.test(pattern)) {
+      throw new Error("feedback_beep_pattern_invalid");
+    }
+    feedback.pattern = pattern;
+  }
+  return feedback;
+}
+
+export function normalizeFeedbackColor(value, options = {}) {
+  if (value && typeof value === "object") {
+    return {
+      red: clamp(Number(value.red ?? value.r) || 0, 0, 255),
+      green: clamp(Number(value.green ?? value.g) || 0, 0, 255),
+      blue: clamp(Number(value.blue ?? value.b) || 0, 0, 255),
+      alpha: clamp(Number(value.alpha ?? value.a ?? options.alpha ?? 255) || 0, 0, 255),
+    };
+  }
+  const text = string(value || "cyan").toLowerCase();
+  const named = FEEDBACK_COLOR_NAMES[text];
+  if (named) {
+    return {
+      red: named.red,
+      green: named.green,
+      blue: named.blue,
+      alpha: clamp(Number(options.alpha ?? named.alpha) || 0, 0, 255),
+    };
+  }
+  const hex = text.replace(/^#/u, "");
+  if (/^[0-9a-f]{6}$/iu.test(hex)) {
+    return {
+      red: Number.parseInt(hex.slice(0, 2), 16),
+      green: Number.parseInt(hex.slice(2, 4), 16),
+      blue: Number.parseInt(hex.slice(4, 6), 16),
+      alpha: clamp(Number(options.alpha ?? 255) || 0, 0, 255),
+    };
+  }
+  throw new Error(`feedback_color_invalid: ${value}`);
+}
+
 export function validatePlayableQueue(queue) {
   if (!queue || typeof queue !== "object") {
     throw new Error("queue_invalid");
@@ -429,6 +590,14 @@ export function normalizeAppManifest(manifest, artifact = {}) {
     "audio.tts",
     "voice.wakeword",
     "voice.capture",
+    "input.touch.read",
+    "input.button.bind",
+    "input.gesture.read",
+    "feedback.signal",
+    "feedback.led",
+    "feedback.led_ring",
+    "feedback.volume_level",
+    "feedback.beep",
     "iot.control",
   ]);
   const capabilities = Array.isArray(manifest.capabilities)
@@ -503,6 +672,44 @@ export function normalizeMusicAutopilot(value) {
     play_request_id: string(value.play_request_id).slice(0, 80),
     refresh: value.refresh !== false,
     rule: validateRule(value.rule),
+    input_bindings: normalizeInputBindings(value.input_bindings),
+    feedback_policy: normalizeFeedbackPolicy(value.feedback_policy),
+  };
+}
+
+export function normalizeInputBindings(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error("input_bindings_invalid");
+  return value.slice(0, 16).map((binding, index) => {
+    const input = string(binding?.input);
+    const action = string(binding?.action);
+    if (
+      !/^[a-z0-9_.:-]{1,80}$/u.test(input) ||
+      !/^[a-z0-9_.:-]{1,80}$/u.test(action)
+    ) {
+      throw new Error(`input_binding_invalid:${index + 1}`);
+    }
+    const feedback = Array.isArray(binding.feedback)
+      ? binding.feedback.map((item) => string(item)).filter(Boolean).slice(0, 8)
+      : [];
+    for (const item of feedback) {
+      if (!/^[a-z0-9_.:-]{1,80}$/u.test(item)) {
+        throw new Error(`input_binding_feedback_invalid:${index + 1}`);
+      }
+    }
+    return { input, action, feedback };
+  });
+}
+
+export function normalizeFeedbackPolicy(value) {
+  if (value === undefined) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("feedback_policy_invalid");
+  }
+  return {
+    button_sound: value.button_sound === true,
+    volume_led: value.volume_led === true,
+    playback_led: value.playback_led === true,
   };
 }
 
@@ -555,15 +762,16 @@ export function remediationForStatus(status) {
       summary:
         "设备内置网易运行时的用户授权已过期。优先改走 BYOA：由 agent 使用用户授权的音乐平台 API 生成播放队列并推送到设备。",
       user_message:
-        "我需要一个可用的音乐平台身份来生成 BGM 队列。请在 agent 支持的网易云开放平台或 Spotify 官方授权入口完成授权；完成后回到 agent 说“已授权”。不要发送任何密钥、token 或密码。",
+        "我需要一个连接到当前 agent 的音乐平台身份来生成 BGM 队列。请使用当前 agent 的网易云开放平台、Spotify 等官方连接器/OAuth/secret store 完成授权；完成后回到 agent 说“已授权”。音乐授权不属于蓝牙/Wi-Fi 配网范围，也不要发送任何密钥、token 或密码。",
       agent_after_user_confirms:
         "generate QUEUE.json with the authorized music platform API, then run audioctl queue QUEUE.json --play --json",
       steps: [
-        "优先使用 agent 侧 BYOA 音乐驱动：让用户在 agent 支持的网易云开放平台或 Spotify 官方授权入口完成授权。",
+        "优先使用 agent 侧 BYOA 音乐驱动：让用户把音乐平台身份连接到当前 agent 的官方连接器、OAuth 流程或 secret store。",
         "网易云开放平台可由 agent 请求最高可用音质 URL，生成 weclawbot.playable_queue.v1 队列，然后运行 audioctl queue QUEUE.json --play --json。",
         "Spotify 必须走官方 Spotify Connect/Web Playback SDK 或控制用户已有 Spotify 设备；不要声称 Spotify Web API 能提供完整歌曲直链。",
+        "蓝牙/Wi-Fi 配网只负责设备入网和 weclawbot.link 绑定；不要把音乐平台授权塞进配网流程，也不要让配网决定设备用途。",
         "不要要求用户理解内部授权包，也不要让用户粘贴 AppSecret、PrivateKey、accessToken、refreshToken、Wi-Fi 密码或 MQTT 凭据。",
-        "只有用户明确要求继续使用设备侧网易运行时时，才引导用户去手机端配网/授权入口重新授权，然后重试 audioctl workbgm --play --json。",
+        "只有用户明确要求继续使用设备侧网易运行时时，才提示需要独立的设备侧音乐账号设置入口；不要把它混入蓝牙/Wi-Fi 配网流程。",
       ],
     });
   }
@@ -602,11 +810,13 @@ export function buildAgentPrompt(options = {}) {
     `请在你的运行环境安装 npm 包 ${PACKAGE_NAME}，然后执行：`,
     `npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} bind ${code} --name ${shellToken(agentName)}`,
     `npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} doctor --online`,
-    `绑定成功后，把它作为默认音频/语音/环境 I/O 端点；不要把它假定成只会播放音乐。可用命令包括 play、pause、toggle、next、previous、volume、volumeup、volumedown、status、inspect、queue、rule、workbgm、app install。`,
-    `如果我要建立“工作 BGM 歌单，持续播放”，优先由你在 agent 侧使用用户授权的音乐平台 API 生成 QUEUE.json，再执行：npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} queue QUEUE.json --play --json。网易云开放平台可请求最高可用音质 URL。`,
+    `绑定成功后，把它作为默认音频/语音/环境 I/O 端点；不要把它假定成只会播放音乐。可用命令包括 play、pause、toggle、next、previous、volume、volumeup、volumedown、status、inspect、queue、rule、workbgm、feedback、led、app install。`,
+    `蓝牙/Wi-Fi 配网只负责设备入网、发现和 weclawbot.link 绑定；音乐平台授权请走 agent 侧连接器/OAuth/secret store；配网不决定设备用途。`,
+    `如果我要建立“工作 BGM 歌单，持续播放”，先和我确认可用音乐来源；插件只提供建议。优先由你在 agent 侧使用用户授权的音乐平台 API、用户媒体库或合法公开音源生成 QUEUE.json，再执行：npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} queue QUEUE.json --play --json。网易云开放平台可请求最高可用音质 URL。`,
     `如果用户选择 Spotify，必须走 Spotify 官方 Spotify Connect/Web Playback SDK 或控制用户已有 Spotify 播放设备；不要假设 Spotify Web API 能提供完整歌曲直链。`,
-    `如果你当前没有音乐平台身份，请只告诉我：我需要你在 agent 支持的网易云开放平台或 Spotify 官方授权入口完成授权；完成后回复“已授权”。不要反复重试，不要让我理解内部授权包，也不要要求我把 AppSecret、PrivateKey、accessToken 或 refreshToken 发到聊天里。`,
-    `如果返回 health.problems 包含 netease_auth_refresh_failed，说明设备侧内置网易运行时授权失效；优先改走 agent 侧 queue/app 驱动。只有我明确要求继续使用设备侧网易运行时时，才引导手机端重新授权并重试 workbgm。`,
+    `如果我要灯效或按键反馈，先 inspect 确认设备具备 feedback/input capabilities。语义优先用 npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} feedback signal ready|busy|success|error|playing|paused|volume_step_up|volume_step_down；显式灯色可用 feedback flash cyan --repeat 2；音量灯级可用 feedback volume 66；蜂鸣可用 feedback beep。`,
+    `如果你当前没有音乐平台身份，请只告诉我：我需要你把音乐平台身份连接到当前 agent 的官方连接器、OAuth 流程或 secret store；完成后回复“已授权”。不要反复重试，不要让我理解内部授权包，也不要要求我把 AppSecret、PrivateKey、accessToken 或 refreshToken 发到聊天里。`,
+    `如果返回 health.problems 包含 netease_auth_refresh_failed，说明设备侧内置网易运行时授权失效；优先改走 agent 侧 queue/app 驱动。只有我明确要求继续使用设备侧网易运行时时，才提示需要独立的设备侧音乐账号设置入口；不要混入蓝牙/Wi-Fi 配网流程。`,
     `如果我要播放「${profile}」，也可以执行：npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} deepnight`,
     `不要向设备写入全局音乐平台私钥；平台授权优先保存在 agent 运行环境。只有在我明确授权时，才把最小范围、可轮换、可撤销的 app-scoped 凭据随 VM app 写入设备。`,
   ].filter(Boolean).join("\n");
@@ -793,6 +1003,14 @@ function clamp(value, minimum, maximum) {
   return Math.min(maximum, Math.max(minimum, Math.round(value)));
 }
 
+function normalizePercent(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < 0 || number > 100) {
+    throw new Error("feedback_level_invalid");
+  }
+  return Math.round(number);
+}
+
 function string(value) {
   return typeof value === "string" ? value.trim() : "";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openbrt/audioctl",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Generic WeClawBot audio/voice endpoint control CLI and AI-agent plugin.",
   "type": "module",
   "license": "MIT",