@openbrt/audioctl 0.1.9 → 0.1.11

package/README.md

@@ -51,17 +51,19 @@ One-shot usage:
 npm exec --package @openbrt/audioctl -- audioctl bind 123456 --name codex
 ```
 
-Credentials are saved to `~/.config/weclawbot/audio-mqtt.json` by default.
-`audioctl` serializes concurrent commands that use the same local MQTT
-credentials, because the broker may require an exact MQTT client id.
+Credentials are saved in an audioctl-managed local config file. Agents should
+not inspect or parse that file; use `audioctl bind`, `doctor`, `inspect`, and
+the control commands instead. `audioctl` serializes concurrent commands that use
+the same local MQTT credentials, because the broker may require an exact MQTT
+client id.
 Agent-facing status is intentionally hardware-abstracted as
 `audio_voice_ambient_endpoint`; agents should not infer or search for a device
 brand/model/vendor from screenshots, BLE names, logs, or prior context.
 MQTT is a control plane and deployment path, not a realtime feedback data plane:
 agents should not read MQTT credentials, import `mqtt`, keep persistent MQTT
-connections, or run BPM/while/sleep loops that repeatedly publish LED commands.
-Continuous effects must be started as a device-local effect or VM app, then left
-to run on the device.
+connections, or run BPM/while/sleep loops that repeatedly publish LED/light
+commands. Continuous effects must be started as a device-local light timeline,
+VM app, or compatibility feedback effect, then left to run on the device.
 
 ## Commands
 
@@ -76,10 +78,14 @@ audioctl volumeup
 audioctl volumedown
 audioctl status
 audioctl inspect --json
+audioctl light describe --json
+audioctl light set all --color amber --brightness 0.35
+audioctl light timeline ./hero.light.json
+audioctl light bind ./hero.light-bindings.json
+audioctl light clear
 audioctl feedback signal ready
 audioctl feedback flash cyan --repeat 2
 audioctl feedback volume 66
-audioctl feedback effect music_beat --bpm 76 --color amber
 audioctl feedback beep
 audioctl feedback clear
 audioctl queue ./work-bgm.queue.json --play
@@ -94,7 +100,51 @@ 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
+`light` controls expose programmable visual surfaces. Agents should use
+`audioctl light describe --json` to inspect surfaces such as `all`, `ring`, and
+`center`, plus event sources and runtime limits. For non-trivial visuals, build
+a `weclawbot.light.timeline.v1` file and optionally a
+`weclawbot.light.bind.v1` file so the device can start/stop visuals on local
+events such as `media.playing`, `media.paused`, and `media.ended`.
+
+```bash
+audioctl light describe --json
+audioctl light timeline ./hero.light.json
+audioctl light bind ./hero.light-bindings.json
+audioctl light clear
+```
+
+Example timeline:
+
+```json
+{
+  "schema": "weclawbot.light.timeline.v1",
+  "id": "hero_ambient",
+  "loop": true,
+  "stop_on": ["media.paused", "media.ended", "media.error"],
+  "duration_ms": 3750,
+  "tracks": [
+    {
+      "surface": "ring",
+      "keyframes": [
+        { "t": 0, "color": "#ff6000", "brightness": 0.18 },
+        { "t": 470, "color": "#ff6000", "brightness": 0.55 },
+        { "t": 940, "color": "#301800", "brightness": 0.12 }
+      ]
+    },
+    {
+      "surface": "center",
+      "keyframes": [
+        { "t": 0, "color": "#ffd080", "brightness": 0.08 },
+        { "t": 1875, "color": "#ffd080", "brightness": 0.40 },
+        { "t": 3750, "color": "#301800", "brightness": 0.05 }
+      ]
+    }
+  ]
+}
+```
+
+`feedback`/`led` controls expose simple semantic 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
@@ -104,16 +154,16 @@ prompt. Explicit LED controls are also available:
 audioctl feedback signal playing
 audioctl feedback flash '#00ffff' --repeat 2
 audioctl feedback volume 42
-audioctl feedback effect music_beat --bpm 76 --color amber
 audioctl feedback beep
 audioctl feedback clear
 audioctl led flash amber --repeat 1
 ```
 
-`feedback effect` is for continuous device-local effects such as beat/pulse or
-breathing animations. It sends one control message; the timing loop belongs on
-the device, not in the agent process. `feedback clear` stops the current
-device-local effect and clears the indicator.
+`feedback effect` is a compatibility/demo shortcut for old agents. New agent
+work should prefer `light describe` + `light timeline` + `light bind`, because
+named effects such as `music_beat`, `pulse`, or `breathing` do not describe the
+actual hardware topology. `feedback effect` requires an explicit effect name;
+calling it with no name is rejected.
 
 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
@@ -183,3 +233,35 @@ Feedback messages use the same MQTT envelope:
 Supported feedback commands are `signal`, `flash`, `volume`, `effect`, `beep`,
 and `clear`. Devices that do not report a matching `feedback.*` capability
 should reject the command instead of pretending to support it.
+
+Light messages use a distinct command envelope:
+
+```json
+{
+  "schema": "weclawbot.control.v1",
+  "id": "light_<uuid>",
+  "kind": "light_command",
+  "light": {
+    "command": "timeline",
+    "timeline": {
+      "schema": "weclawbot.light.timeline.v1",
+      "id": "custom_visual",
+      "loop": true,
+      "stop_on": ["media.paused", "media.ended"],
+      "duration_ms": 2000,
+      "tracks": [
+        {
+          "surface": "all",
+          "keyframes": [
+            { "t": 0, "color": "#202020", "brightness": 0.05 },
+            { "t": 1000, "color": "#ff6000", "brightness": 0.5 }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+Supported light commands are `describe`, `set`, `timeline`, `bind`, and
+`clear`. Continuous light timing and event reactions run on the device VM.

package/agent-plugin.json

@@ -15,19 +15,19 @@
   "transport_policy": {
     "mqtt_role": "control_plane_only",
     "agent_must_not": [
-      "不要读取或解析 ~/.config/weclawbot/audio-mqtt.json 里的 MQTT 凭据",
+      "不要读取或解析 audioctl 本地 MQTT 凭据文件",
       "不要直接 import mqtt、打开或保持 MQTT 长连接来控制设备",
       "不要写 agent 端 while/sleep/BPM loop 来反复发布 feedback/LED 命令",
       "不要把 weclawbot.link 当作实时灯效、音频分析或本地交互的数据面"
     ],
-    "continuous_feedback": "连续灯效、节拍灯、呼吸灯、动画和按键反馈必须通过 audioctl feedback effect 或 VM app 一次下发，在设备本地运行；停止使用 audioctl feedback clear。"
+    "continuous_feedback": "连续灯效、节拍灯、呼吸灯、动画和按键反馈必须通过 audioctl light timeline/bind、VM app 或兼容的 feedback effect 一次下发，在设备本地运行；停止使用 audioctl light clear 或 feedback clear。"
   },
   "agent_decision_model": {
     "principle": "agent 不需要也不应该知道具体品牌/产品；只基于 inspect 返回的抽象能力、VM manifest、用户目标和安全边界来推理。",
     "allowed_reasoning": [
       "把用户自然语言目标拆成需要的 I/O、媒体、反馈、输入绑定和持久运行需求",
       "在用户已授权的平台、连接器、OAuth 或 secret store 中选择合法数据来源",
-      "决定使用 queue、rule、feedback、input binding 或 VM app install 的组合",
+      "决定使用 queue、rule、light timeline/bind、feedback、input binding 或 VM app install 的组合",
       "在设备 VM 内放置需要离线、低延迟或持续运行的逻辑"
     ],
     "not_prescribed": "插件不会也无法穷举所有 agent 方案；agent 应读取 capabilities 后自己想办法达到目标。"
@@ -75,6 +75,12 @@
     "feedback.effect",
     "feedback.volume_level",
     "feedback.beep",
+    "light.describe",
+    "light.set",
+    "light.timeline",
+    "light.bind",
+    "light.clear",
+    "event.bind",
     "iot.control",
     "device.inspect",
     "music.autopilot",
@@ -104,7 +110,7 @@
     {
       "intent": "帮我把设备灯效、音量灯和按键反馈音接上",
       "primary_command": "audioctl feedback signal ready",
-      "agent_strategy": "先运行 audioctl inspect --json 确认设备报告 feedback.* 和 input.* capabilities。MQTT 是控制面，不是实时灯效数据面；不要读取 MQTT 凭据、不要 import mqtt、不要保持 MQTT 长连接、不要写 agent 端 BPM/while/sleep 循环去刷 LED。一次性语义反馈可用 audioctl feedback signal/flash/volume/beep/clear；连续灯效、节拍灯、呼吸灯和动画必须通过 audioctl feedback effect 或 VM app 一次下发并在设备本地运行。物理按键/触控属于 VM app 的 input.button.bind 能力，具体绑定由 agent 根据用户目标和 capabilities 自行规划。",
+      "agent_strategy": "先运行 audioctl inspect --json 或 audioctl light describe --json 读取 light.surfaces、events、limits 以及 feedback/input capabilities。MQTT 是控制面，不是实时灯效数据面；不要读取 MQTT 凭据、不要 import mqtt、不要保持 MQTT 长连接、不要写 agent 端 BPM/while/sleep 循环去刷 LED。一次性语义提示可用 audioctl feedback signal/flash/volume/beep/clear；复杂灯效优先使用 audioctl light timeline 和 audioctl light bind，把外圈、中心等 surface 的 keyframes 与 media/input 事件绑定到设备本地。feedback effect 只是兼容/demo 入口，不要把 music_beat/pulse/breathing 当成能力边界。物理按键/触控属于 VM app 的 input.button.bind 能力，具体绑定由 agent 根据用户目标和 capabilities 自行规划。",
       "if_missing_capability": "不要伪造灯效或按键能力；如果 inspect 未报告对应 capability，只说明当前设备适配未提供该能力，并建议安装或升级设备 VM。"
     },
     {
@@ -134,6 +140,10 @@
       "name": "feedback",
       "usage": "audioctl feedback signal NAME | flash COLOR | volume 0..100 | effect NAME [--bpm N] [--color COLOR] | clear | beep"
     },
+    {
+      "name": "light",
+      "usage": "audioctl light describe | set SURFACE --color COLOR [--brightness 0..1] | timeline TIMELINE.json | bind BINDINGS.json | clear"
+    },
     {
       "name": "led",
       "usage": "audioctl led flash COLOR [--repeat N]"

package/bin/audioctl.mjs

@@ -14,6 +14,7 @@ import {
   buildAgentPrompt,
   buildAudioControl,
   buildFeedbackControl,
+  buildLightControl,
   buildQueueControl,
   buildWorkBgmAppInstallControl,
   expandPath,
@@ -54,6 +55,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 === "light") return commandLight(values);
   if (name === "feedback" || name === "led") return commandFeedback(values);
   return commandControl(name, values);
 }
@@ -73,6 +75,11 @@ function usage(exitCode = 0) {
   ${COMMAND_NAME} feedback effect NAME [--bpm N] [--color COLOR]
   ${COMMAND_NAME} feedback clear|beep
   ${COMMAND_NAME} led flash COLOR [--repeat N]
+  ${COMMAND_NAME} light describe
+  ${COMMAND_NAME} light set SURFACE --color COLOR [--brightness 0..1]
+  ${COMMAND_NAME} light timeline TIMELINE.json
+  ${COMMAND_NAME} light bind BINDINGS.json
+  ${COMMAND_NAME} light clear
   ${COMMAND_NAME} rule RULE.json
   ${COMMAND_NAME} queue QUEUE.json [--play]
   ${COMMAND_NAME} app install MANIFEST.json APP.wasm
@@ -81,7 +88,7 @@ function usage(exitCode = 0) {
   ${COMMAND_NAME} manifest
 
 Options:
-  --credentials FILE   default: ${DEFAULT_CREDENTIALS_PATH}
+  --credentials FILE   override audioctl-managed local credential file
   --endpoint URL       default: ${DEFAULT_ENDPOINT}
   --timeout SECONDS    default: 12
   --json               machine-readable output
@@ -318,6 +325,57 @@ async function commandSeek(values) {
   await send("seek", options, { positionMs: options._[0] });
 }
 
+async function commandLight(values) {
+  const subcommand = String(values[0] || "").replace(/-/gu, "_").toLowerCase();
+  if (!subcommand) throw new Error("light_requires_subcommand");
+  const options = parseOptions(values.slice(1), {
+    credentials: credentialsPath(),
+    timeout: 12,
+    json: false,
+    nowait: false,
+  });
+  let control;
+  if (subcommand === "describe" || subcommand === "capabilities") {
+    control = buildLightControl("describe");
+  } else if (subcommand === "set") {
+    control = buildLightControl("set", {
+      surface: options._[0] || options.surface || "all",
+      color: options.color || options._[1],
+      brightness: options.brightness ?? options.level,
+      alpha: options.alpha,
+    });
+  } else if (subcommand === "timeline") {
+    const file = String(options._[0] || "");
+    if (!file) throw new Error("light_timeline_requires_file");
+    control = buildLightControl("timeline", {
+      timeline: JSON.parse(await fs.readFile(file, "utf8")),
+    });
+  } else if (subcommand === "bind") {
+    const file = String(options._[0] || "");
+    if (!file) throw new Error("light_bind_requires_file");
+    control = buildLightControl("bind", {
+      bindings: JSON.parse(await fs.readFile(file, "utf8")),
+    });
+  } else if (subcommand === "clear" || subcommand === "off" || subcommand === "hide") {
+    control = buildLightControl("clear");
+  } else {
+    throw new Error(`light_subcommand_unsupported: ${subcommand}`);
+  }
+
+  const credentials = await readCredentials(options.credentials);
+  const delivery = await publishAudioControl(credentials, control, {
+    timeoutMs: Number(options.timeout) * 1000,
+    wait: !options.nowait,
+  });
+  if (control.light.command === "describe" && options.json) {
+    const light = delivery.status?.inspect?.light || delivery.status?.light || {};
+    process.stdout.write(`${JSON.stringify(redactAgentFacingValue(light))}\n`);
+  } else {
+    print(delivery.status || delivery, options.json);
+  }
+  if (delivery.status?.kind === "rejected") process.exitCode = 1;
+}
+
 async function commandFeedback(values) {
   const subcommand = String(values[0] || "").replace(/-/gu, "_").toLowerCase();
   const shorthandSignals = new Set([
@@ -329,12 +387,12 @@ async function commandFeedback(values) {
     "playing",
     "paused",
     "wake",
-    "music_beat",
     "volume_step_up",
     "volume_step_down",
     "button_press",
     "button_long_press",
   ]);
+  const shorthandEffects = new Set(["music_beat", "pulse", "breathing"]);
   const options = parseOptions(values.slice(1), {
     credentials: credentialsPath(),
     timeout: 12,
@@ -345,11 +403,26 @@ async function commandFeedback(values) {
   let command = subcommand;
   const payload = {};
   if (!command) throw new Error("feedback_requires_subcommand");
-  if (shorthandSignals.has(command)) {
+  if (shorthandEffects.has(command)) {
+    payload.effect = command;
+    payload.bpm = options.bpm;
+    payload.color = options.color;
+    payload.alpha = options.alpha;
+    command = "effect";
+  } else if (shorthandSignals.has(command)) {
     payload.semantic = command;
     command = "signal";
   } else if (command === "signal") {
-    payload.semantic = options._[0];
+    const semantic = String(options._[0] || "").replace(/-/gu, "_").toLowerCase();
+    if (shorthandEffects.has(semantic)) {
+      payload.effect = semantic;
+      payload.bpm = options.bpm;
+      payload.color = options.color;
+      payload.alpha = options.alpha;
+      command = "effect";
+    } else {
+      payload.semantic = options._[0];
+    }
   } else if (command === "flash") {
     payload.color = options._[0] || options.color;
     payload.repeat = options.repeat;
@@ -421,6 +494,7 @@ function parseOptions(values, defaults = {}) {
       "alias",
       "alpha",
       "bpm",
+      "brightness",
       "color",
       "credentials",
       "endpoint",
@@ -430,6 +504,7 @@ function parseOptions(values, defaults = {}) {
       "pattern",
       "profile",
       "repeat",
+      "surface",
       "timeout",
       "volume",
     ]).has(key)) {

package/lib/index.mjs

@@ -48,6 +48,8 @@ export const WORKBGM_RULE = Object.freeze({
 });
 
 export const PLAYABLE_QUEUE_SCHEMA = "weclawbot.playable_queue.v1";
+export const LIGHT_TIMELINE_SCHEMA = "weclawbot.light.timeline.v1";
+export const LIGHT_BINDINGS_SCHEMA = "weclawbot.light.bind.v1";
 
 export const FEEDBACK_COLOR_NAMES = Object.freeze({
   red: Object.freeze({ red: 255, green: 0, blue: 0, alpha: 255 }),
@@ -71,7 +73,6 @@ export const FEEDBACK_SIGNALS = Object.freeze([
   "playing",
   "paused",
   "wake",
-  "music_beat",
   "volume_step_up",
   "volume_step_down",
   "button_press",
@@ -85,6 +86,24 @@ export const FEEDBACK_EFFECTS = Object.freeze([
   "breathing",
 ]);
 
+export const LIGHT_SURFACES = Object.freeze([
+  "all",
+  "ring",
+  "center",
+]);
+
+export const LIGHT_EVENTS = Object.freeze([
+  "media.playing",
+  "media.paused",
+  "media.ended",
+  "media.error",
+  "volume.changed",
+  "input.center.single_click",
+  "input.ring.single_click",
+  "input.ring.clockwise",
+  "input.ring.counter_clockwise",
+]);
+
 const WORKBGM_APP_WASM_BASE64 =
   "AGFzbQEAAAABBAFgAAADAgEABwgBBG1haW4AAAoEAQIACw==";
 
@@ -224,6 +243,16 @@ export function buildFeedbackControl(command, options = {}) {
   };
 }
 
+export function buildLightControl(command, options = {}) {
+  const light = normalizeLightCommand(command, options);
+  return {
+    schema: "weclawbot.control.v1",
+    id: string(options.id) || `light_${crypto.randomUUID()}`,
+    kind: "light_command",
+    light,
+  };
+}
+
 export function buildQueueControl(options = {}) {
   return buildAudioControl("set_queue", {
     id: options.id,
@@ -425,6 +454,12 @@ export function normalizeFeedbackCommand(command, options = {}) {
         options.value ||
         "button_press",
     ).replace(/-/gu, "_").toLowerCase();
+    if (FEEDBACK_EFFECTS.includes(semantic)) {
+      return normalizeFeedbackCommand("effect", {
+        ...options,
+        effect: semantic,
+      });
+    }
     if (!/^[a-z0-9_.:]{1,64}$/u.test(semantic)) {
       throw new Error("feedback_signal_invalid");
     }
@@ -450,14 +485,16 @@ export function normalizeFeedbackCommand(command, options = {}) {
     feedback.pattern = pattern;
   }
   if (normalized === "effect") {
-    const effect = string(
+    const effectValue =
       options.effect ||
-        options.semantic ||
-        options.signal ||
-        options.name ||
-        options.value ||
-        "pulse",
-    ).replace(/-/gu, "_").toLowerCase();
+      options.semantic ||
+      options.signal ||
+      options.name ||
+      options.value;
+    if (!effectValue) {
+      throw new Error("feedback_effect_requires_name");
+    }
+    const effect = string(effectValue).replace(/-/gu, "_").toLowerCase();
     if (!/^[a-z0-9_.:]{1,64}$/u.test(effect)) {
       throw new Error("feedback_effect_invalid");
     }
@@ -509,6 +546,181 @@ export function normalizeFeedbackColor(value, options = {}) {
   throw new Error(`feedback_color_invalid: ${value}`);
 }
 
+export function normalizeLightCommand(command, options = {}) {
+  const aliases = new Map([
+    ["capabilities", "describe"],
+    ["description", "describe"],
+    ["info", "describe"],
+    ["off", "clear"],
+    ["hide", "clear"],
+    ["stop", "clear"],
+    ["frame", "set"],
+    ["timeline_start", "timeline"],
+    ["animation", "timeline"],
+    ["animate", "timeline"],
+    ["bindings", "bind"],
+    ["event_bind", "bind"],
+  ]);
+  const raw = string(command || options.command || options.action || "describe")
+    .replace(/-/gu, "_")
+    .toLowerCase();
+  const normalized = aliases.get(raw) || raw;
+  const supported = new Set(["describe", "set", "timeline", "bind", "clear"]);
+  if (!supported.has(normalized)) {
+    throw new Error(`light_command_unsupported: ${command}`);
+  }
+  const light = { command: normalized };
+  if (normalized === "set") {
+    light.surface = normalizeLightSurface(options.surface || options.target || "all");
+    light.color = normalizeFeedbackColor(options.color || options.value || "white", {
+      alpha: options.alpha,
+    });
+    light.brightness = normalizeUnit(options.brightness ?? options.level ?? 1, {
+      defaultValue: 1,
+      name: "light_brightness_invalid",
+    });
+  }
+  if (normalized === "timeline") {
+    light.timeline = validateLightTimeline(options.timeline);
+  }
+  if (normalized === "bind") {
+    light.bindings = validateLightBindings(options.bindings || options.binding);
+  }
+  return light;
+}
+
+export function validateLightTimeline(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("light_timeline_invalid");
+  }
+  const tracksInput = Array.isArray(value.tracks) ? value.tracks : [];
+  if (tracksInput.length < 1 || tracksInput.length > 8) {
+    throw new Error("light_timeline_tracks_invalid");
+  }
+  let maxTime = 0;
+  const tracks = tracksInput.map((track, trackIndex) => {
+    const surface = normalizeLightSurface(track?.surface || track?.target || "all");
+    const keyframesInput = Array.isArray(track?.keyframes) ? track.keyframes : [];
+    if (keyframesInput.length < 1 || keyframesInput.length > 64) {
+      throw new Error(`light_timeline_keyframes_invalid:${trackIndex + 1}`);
+    }
+    const keyframes = keyframesInput.map((frame, frameIndex) => {
+      if (!frame || typeof frame !== "object" || Array.isArray(frame)) {
+        throw new Error(`light_timeline_keyframe_invalid:${trackIndex + 1}:${frameIndex + 1}`);
+      }
+      const t = clamp(Number(frame.t ?? frame.time_ms ?? frame.timeMs) || 0, 0, 600_000);
+      maxTime = Math.max(maxTime, t);
+      return {
+        t,
+        color: normalizeFeedbackColor(frame.color || frame.value || "white", {
+          alpha: frame.alpha,
+        }),
+        brightness: normalizeUnit(frame.brightness ?? frame.level ?? 1, {
+          defaultValue: 1,
+          name: "light_keyframe_brightness_invalid",
+        }),
+      };
+    }).sort((a, b) => a.t - b.t);
+    return { surface, keyframes };
+  });
+  const durationMs = clamp(
+    Number(value.durationMs ?? value.duration_ms) || Math.max(maxTime, 1000),
+    100,
+    600_000,
+  );
+  return {
+    schema: LIGHT_TIMELINE_SCHEMA,
+    id: normalizeIdentifier(value.id || value.timeline_id || `timeline_${crypto.randomUUID()}`, {
+      name: "light_timeline_id_invalid",
+      maximum: 80,
+    }),
+    loop: value.loop === true,
+    stop_on: normalizeLightEvents(value.stop_on || value.stopOn || ["media.paused", "media.ended"]),
+    duration_ms: durationMs,
+    tracks,
+  };
+}
+
+export function validateLightBindings(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("light_bindings_invalid");
+  }
+  const input = Array.isArray(value.bindings) ? value.bindings : [];
+  if (input.length > 32) throw new Error("light_bindings_too_large");
+  return {
+    schema: LIGHT_BINDINGS_SCHEMA,
+    bindings: input.map((binding, index) => {
+      const timeline = binding?.timeline ? validateLightTimeline(binding.timeline) : null;
+      const events = normalizeLightEvents(binding?.events ?? binding?.event);
+      const actionRaw = string(binding?.action || (timeline ? "light.timeline.start" : "light.clear"))
+        .replace(/-/gu, "_")
+        .toLowerCase();
+      const actionAliases = new Map([
+        ["clear", "light.clear"],
+        ["off", "light.clear"],
+        ["stop", "light.timeline.stop"],
+        ["timeline.start", "light.timeline.start"],
+        ["timeline_start", "light.timeline.start"],
+        ["start", "light.timeline.start"],
+        ["timeline.stop", "light.timeline.stop"],
+        ["timeline_stop", "light.timeline.stop"],
+      ]);
+      const action = actionAliases.get(actionRaw) || actionRaw;
+      if (!new Set(["light.clear", "light.timeline.start", "light.timeline.stop"]).has(action)) {
+        throw new Error(`light_binding_action_invalid:${index + 1}`);
+      }
+      const normalized = {
+        events,
+        action,
+        timeline_id: string(binding?.timeline_id || binding?.timelineId || timeline?.id || "").slice(0, 80),
+      };
+      if (timeline) normalized.timeline = timeline;
+      return normalized;
+    }),
+  };
+}
+
+function normalizeLightSurface(value) {
+  const surface = string(value).replace(/-/gu, "_").toLowerCase();
+  if (!LIGHT_SURFACES.includes(surface)) {
+    throw new Error(`light_surface_unsupported: ${value}`);
+  }
+  return surface;
+}
+
+function normalizeLightEvents(value) {
+  const events = Array.isArray(value) ? value : [value];
+  return events.map(normalizeLightEvent).slice(0, 16);
+}
+
+function normalizeLightEvent(value) {
+  const event = string(value).replace(/-/gu, "_").toLowerCase();
+  if (!LIGHT_EVENTS.includes(event)) {
+    throw new Error(`light_event_unsupported: ${value}`);
+  }
+  return event;
+}
+
+function normalizeIdentifier(value, options = {}) {
+  const text = string(value);
+  const maximum = Number(options.maximum) || 80;
+  if (!/^[a-z0-9][a-z0-9_.:-]*$/u.test(text) || text.length > maximum) {
+    throw new Error(options.name || "identifier_invalid");
+  }
+  return text;
+}
+
+function normalizeUnit(value, options = {}) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < 0 || number > 1) {
+    if (value === undefined && options.defaultValue !== undefined) {
+      return options.defaultValue;
+    }
+    throw new Error(options.name || "unit_value_invalid");
+  }
+  return Math.round(number * 1000) / 1000;
+}
+
 export function validatePlayableQueue(queue) {
   if (!queue || typeof queue !== "object") {
     throw new Error("queue_invalid");
@@ -637,6 +849,12 @@ export function normalizeAppManifest(manifest, artifact = {}) {
     "feedback.effect",
     "feedback.volume_level",
     "feedback.beep",
+    "light.describe",
+    "light.set",
+    "light.timeline",
+    "light.bind",
+    "light.clear",
+    "event.bind",
     "iot.control",
   ]);
   const capabilities = Array.isArray(manifest.capabilities)
@@ -852,13 +1070,13 @@ export function buildAgentPrompt(options = {}) {
     `npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} bind ${code} --name ${shellToken(agentName)}`,
     `npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} doctor --online`,
     `这台设备对你是抽象硬件产品：${ABSTRACT_HARDWARE_TYPE}。不要根据外观、BLE 名称、音色、日志或历史上下文推断品牌/型号/厂家，也不要搜索厂家资料、社区经验或拆机资料；只使用 audioctl inspect 返回的 capabilities、VM manifest 和控制回执来工作。`,
-    `绑定成功后，把它作为默认音频/语音/环境 I/O 端点；不要把它假定成只会播放音乐。可用命令包括 play、pause、toggle、next、previous、volume、volumeup、volumedown、status、inspect、queue、rule、workbgm、feedback、led、app install。`,
-    `当我给出目标时，请你在 capabilities、安全边界和用户授权范围内自行规划实现路径；插件只声明能力和边界，不穷举具体玩法。需要离线、低延迟或持续运行的逻辑，应通过 queue/rule/VM app/feedback effect 下放到设备本地。`,
-    `MQTT/weclawbot.link 对你只是控制面和部署通道，不是实时灯效数据面。不要读取 MQTT 凭据，不要直接 import mqtt，不要保持 MQTT 长连接，也不要写循环脚本按 BPM 反复发布 feedback。连续灯效/节拍/动画必须用 audioctl feedback effect 或 VM app 一次下发，在设备本地运行；停止时用 audioctl feedback clear。`,
+    `绑定成功后，把它作为默认音频/语音/环境 I/O 端点；不要把它假定成只会播放音乐。可用命令包括 play、pause、toggle、next、previous、volume、volumeup、volumedown、status、inspect、queue、rule、workbgm、feedback、light、led、app install。`,
+    `当我给出目标时，请你在 capabilities、安全边界和用户授权范围内自行规划实现路径；插件只声明能力和边界，不穷举具体玩法。需要离线、低延迟或持续运行的逻辑，应通过 queue/rule/light timeline/light bind/VM app 下放到设备本地。`,
+    `MQTT/weclawbot.link 对你只是控制面和部署通道，不是实时灯效数据面。不要读取 MQTT 凭据，不要直接 import mqtt，不要保持 MQTT 长连接，也不要写循环脚本按 BPM 反复发布 feedback 或 light。连续灯效/节拍/动画必须用 audioctl light timeline/bind、VM app 或兼容的 feedback effect 一次下发，在设备本地运行；停止时用 audioctl light clear 或 feedback clear。`,
     `蓝牙/Wi-Fi 配网只负责设备入网、发现和 weclawbot.link 绑定；音乐平台授权请走 agent 侧连接器/OAuth/secret store；配网不决定设备用途。`,
     `音乐来源由你和用户协商，插件只做建议。你可以在 agent 侧使用用户授权的音乐平台 API、用户媒体库、合法公开音源或其他合规来源生成队列/规则/VM app。网易云开放平台可请求最高可用音质 URL。`,
     `如果用户选择 Spotify，必须走 Spotify 官方 Spotify Connect/Web Playback SDK 或控制用户已有 Spotify 播放设备；不要假设 Spotify Web API 能提供完整歌曲直链。`,
-    `灯效、音量灯、蜂鸣和按键/触控反馈要先 inspect 确认 feedback/input capabilities。一次性反馈可用 feedback signal/flash/volume/beep/clear；连续反馈用 feedback effect 或 VM app 一次下发，由设备本地运行。具体按键绑定请根据用户目标和 capabilities 自行规划，不要套固定模板。`,
+    `灯效、音量灯、蜂鸣和按键/触控反馈要先 inspect 或 light describe 确认 feedback/input/light capabilities。一次性语义反馈可用 feedback signal/flash/volume/beep/clear；复杂灯效请优先生成 light timeline 和 light bind，把外圈、中心等 surface 与 media/input 事件绑定到设备本地。feedback effect 只作为兼容/demo 入口，不要把 music_beat/pulse/breathing 当成能力边界。具体按键绑定请根据用户目标和 capabilities 自行规划，不要套固定模板。`,
     `如果你当前没有音乐平台身份，请只告诉我：我需要你把音乐平台身份连接到当前 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`,
@@ -986,6 +1204,9 @@ function redactAgentFacingScalar(value, keyPath) {
   if (typeof value !== "string") return value;
   const last = keyPath[keyPath.length - 1];
   if (last === "device_type") return ABSTRACT_HARDWARE_TYPE;
+  if (["credentials", "control_topic", "status_topic", "event_topic"].includes(last)) {
+    return "[redacted]";
+  }
   if (last === "model" || last === "brand" || last === "manufacturer" || last === "product") {
     return "";
   }

package/package.json

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