@openbrt/audioctl 0.1.0 → 0.1.2

package/README.md

@@ -20,6 +20,7 @@ run doctor, then use it as my default BGM/music output device.
 npm install -g @openbrt/audioctl
 audioctl bind 123456 --name codex
 audioctl doctor --online
+audioctl inspect
 ```
 
 One-shot usage:
@@ -42,11 +43,28 @@ audioctl volume 48
 audioctl volumeup
 audioctl volumedown
 audioctl status
+audioctl inspect --json
+audioctl workbgm --play
 audioctl rule ./my-playlist-rule.json
 audioctl deepnight
 audioctl prompt 123456 --agent codex --alias 视听房音箱
 ```
 
+`inspect` asks the device for a redacted configuration/status snapshot over the
+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.
+
+`workbgm --play` installs a persistent `work-bgm-autopilot` VM app on the audio
+device, writes the bundled 工作 BGM playlist rule through the device-side music
+adapter, requests a refresh, and starts playback once. The app expresses a
+continuous BGM intent and respects later user-initiated pause/resume controls.
+If the device reports `netease_auth_refresh_failed`, the agent should stop
+retrying and tell the user to complete the NetEase Music authorization flow in a
+trusted device/provisioning or maintenance environment. The agent must not ask
+the user to paste AppSecret, PrivateKey, accessToken, refreshToken, Wi-Fi
+passwords, or MQTT credentials into chat.
+
 `deepnight` pushes the bundled “深夜工作” playlist rule and asks the device to
 refresh/play according to its local runtime. The package never contains music
 platform private keys.

package/agent-plugin.json

@@ -27,8 +27,12 @@
     "audio.previous",
     "audio.seek",
     "audio.set_volume",
+    "device.inspect",
+    "music.autopilot",
     "music.set_rule",
-    "music.status"
+    "music.work_bgm",
+    "music.status",
+    "app.install"
   ],
   "pairing": {
     "endpoint": "https://weclawbot.link/byoa",
@@ -45,6 +49,10 @@
       "name": "doctor",
       "usage": "audioctl doctor --online"
     },
+    {
+      "name": "inspect",
+      "usage": "audioctl inspect --json"
+    },
     {
       "name": "control",
       "usage": "audioctl play|pause|toggle|next|previous|volumeup|volumedown|status"
@@ -56,6 +64,14 @@
     {
       "name": "rule",
       "usage": "audioctl rule RULE.json"
+    },
+    {
+      "name": "app install",
+      "usage": "audioctl app install MANIFEST.json APP.wasm"
+    },
+    {
+      "name": "workbgm",
+      "usage": "audioctl workbgm --play"
     }
   ]
 }

package/bin/audioctl.mjs

@@ -10,12 +10,16 @@ import {
   DEEPNIGHT_RULE,
   PACKAGE_NAME,
   bindAgent,
+  buildAppInstallControl,
   buildAgentPrompt,
   buildAudioControl,
+  buildWorkBgmAppInstallControl,
   expandPath,
   normalizeCredentials,
   publishAudioControl,
   readCredentials,
+  remediationForStatus,
+  summarizeInspect,
   summarizePlayback,
   testConnection,
   validateRule,
@@ -37,9 +41,12 @@ if (!command || new Set(["help", "-h", "--help"]).has(command)) {
 async function run(name, values) {
   if (name === "bind") return commandBind(values);
   if (name === "doctor") return commandDoctor(values);
+  if (name === "inspect") return commandInspect(values);
   if (name === "prompt") return commandPrompt(values);
   if (name === "manifest") return commandManifest();
+  if (name === "app") return commandApp(values);
   if (name === "rule") return commandRule(values);
+  if (name === "workbgm") return commandWorkBgm(values);
   if (name === "deepnight") return commandDeepnight(values);
   if (name === "volume") return commandVolume(values);
   if (name === "seek") return commandSeek(values);
@@ -50,11 +57,14 @@ function usage(exitCode = 0) {
   process.stdout.write(`Usage:
   ${COMMAND_NAME} bind CODE [--name AGENT]
   ${COMMAND_NAME} doctor [--online] [--json]
+  ${COMMAND_NAME} inspect [--json]
   ${COMMAND_NAME} prompt CODE [--agent AGENT] [--alias NAME]
   ${COMMAND_NAME} play|pause|toggle|next|previous|volumeup|volumedown|status
   ${COMMAND_NAME} volume 0..100
   ${COMMAND_NAME} seek MILLISECONDS
   ${COMMAND_NAME} rule RULE.json
+  ${COMMAND_NAME} app install MANIFEST.json APP.wasm
+  ${COMMAND_NAME} workbgm [--play]
   ${COMMAND_NAME} deepnight
   ${COMMAND_NAME} manifest
 
@@ -110,8 +120,52 @@ async function commandDoctor(values) {
   if (options.online) {
     await testConnection(credentials, { timeoutMs: Number(options.timeout) * 1000 });
     status.online = true;
+    const delivery = await publishAudioControl(credentials, buildAudioControl("status"), {
+      timeoutMs: Number(options.timeout) * 1000,
+    });
+    status.device_status = delivery.status || null;
+    status.healthy = delivery.status?.health?.ok !== false;
+    status.ok = status.healthy;
+    status.remediation = remediationForStatus(delivery.status);
   }
   print(status, options.json);
+  if (options.online && status.healthy === false) process.exitCode = 1;
+}
+
+async function commandInspect(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    timeout: 12,
+    json: false,
+  });
+  const credentials = await readCredentials(options.credentials);
+  const delivery = await publishAudioControl(credentials, buildAudioControl("status"), {
+    timeoutMs: Number(options.timeout) * 1000,
+  });
+  if (delivery.status?.kind === "rejected") {
+    print(delivery.status, options.json);
+    process.exitCode = 1;
+    return;
+  }
+  const inspect = delivery.status?.inspect || delivery.status || {};
+  const remediation = remediationForStatus(inspect);
+  if (remediation.length > 0 && !Array.isArray(inspect.remediation)) {
+    inspect.remediation = remediation;
+  }
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(inspect)}\n`);
+    return;
+  }
+  const summary = summarizeInspect(inspect);
+  process.stdout.write(
+    `device: ${summary.device}\n` +
+      `wifi: ${summary.wifi}\n` +
+      `bluetooth: ${summary.bluetooth}\n` +
+      `wakeword: ${summary.wakeword}\n` +
+      `playback: ${summary.playback}\n` +
+      `vm: ${summary.vm}\n` +
+      `health: ${summary.health}\n`,
+  );
 }
 
 async function commandPrompt(values) {
@@ -148,6 +202,35 @@ async function commandRule(values) {
   await send("set_rule", options, { rule });
 }
 
+async function commandApp(values) {
+  const subcommand = String(values[0] || "");
+  if (subcommand !== "install") {
+    throw new Error("app_subcommand_unsupported");
+  }
+  const options = parseOptions(values.slice(1), {
+    credentials: credentialsPath(),
+    timeout: 12,
+    json: false,
+    nowait: false,
+  });
+  const manifestFile = String(options._[0] || "");
+  const wasmFile = String(options._[1] || "");
+  if (!manifestFile || !wasmFile) {
+    throw new Error("app_install_requires_manifest_and_wasm");
+  }
+  const control = buildAppInstallControl({
+    manifest: JSON.parse(await fs.readFile(manifestFile, "utf8")),
+    wasm: await fs.readFile(wasmFile),
+  });
+  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 commandDeepnight(values) {
   const options = parseOptions(values, {
     credentials: credentialsPath(),
@@ -158,6 +241,27 @@ async function commandDeepnight(values) {
   await send("set_rule", options, { rule: DEEPNIGHT_RULE });
 }
 
+async function commandWorkBgm(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    timeout: 20,
+    json: false,
+    nowait: false,
+    play: false,
+  });
+  const credentials = await readCredentials(options.credentials);
+  const delivery = await publishAudioControl(
+    credentials,
+    buildWorkBgmAppInstallControl({ play: options.play }),
+    {
+      timeoutMs: Number(options.timeout) * 1000,
+      wait: !options.nowait,
+    },
+  );
+  print(delivery.status || delivery, options.json);
+  if (delivery.status?.kind === "rejected") process.exitCode = 1;
+}
+
 async function commandVolume(values) {
   const options = parseOptions(values, {
     credentials: credentialsPath(),
@@ -211,7 +315,7 @@ function parseOptions(values, defaults = {}) {
       continue;
     }
     const key = value.slice(2);
-    if (key === "json" || key === "online" || key === "nowait") {
+    if (key === "json" || key === "online" || key === "nowait" || key === "play") {
       options[key] = true;
       continue;
     }
@@ -241,6 +345,7 @@ function credentialsPath() {
 }
 
 function print(value, json) {
+  value = decorateForAgent(value);
   if (json) {
     process.stdout.write(`${JSON.stringify(value)}\n`);
     return;
@@ -248,12 +353,26 @@ function print(value, json) {
   if (value?.kind === "applied" || value?.kind === "rejected") {
     const playback = summarizePlayback(value);
     const track = playback.track || "no track";
+    const problems = Array.isArray(value.health?.problems)
+      ? value.health.problems
+      : [];
     process.stdout.write(
       `${value.kind}: ${value.detail || ""}\n` +
-        `playback: ${playback.desired}, volume ${playback.volume ?? "-"}, ${track}\n`,
+        `playback: ${playback.desired}, volume ${playback.volume ?? "-"}, ${track}\n` +
+        (problems.length > 0 ? `health: ${problems.join(", ")}\n` : "health: ok\n"),
     );
     return;
   }
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 
+function decorateForAgent(value) {
+  if (!value || typeof value !== "object") return value;
+  const remediation = remediationForStatus(value);
+  if (remediation.length === 0) return value;
+  if (Array.isArray(value.remediation) && value.remediation.length > 0) return value;
+  return {
+    ...value,
+    remediation,
+  };
+}

package/lib/index.mjs

@@ -30,6 +30,24 @@ export const DEEPNIGHT_RULE = Object.freeze({
   refreshHintSeconds: 21600,
 });
 
+export const WORKBGM_RULE = Object.freeze({
+  schemaVersion: 1,
+  title: "工作 BGM",
+  source: "网易云音乐官方歌单：深夜刷题党｜轻缓律动伴你专注学习",
+  sourcePlaylist: Object.freeze({
+    originalId: "8383869866",
+    encryptedId: "661561242F7B3CE80B5AB760DB171EB4",
+  }),
+  fetchLimit: 80,
+  targetTrackCount: 24,
+  minimumTrackCount: 8,
+  qualityPolicy: "highest-available",
+  refreshHintSeconds: 21600,
+});
+
+const WORKBGM_APP_WASM_BASE64 =
+  "AGFzbQEAAAABBAFgAAADAgEABwgBBG1haW4AAAoEAQIACw==";
+
 export function validateBindingCode(code) {
   const value = string(code).replace(/\s/gu, "");
   if (!/^[A-Za-z0-9_-]{6,64}$/u.test(value)) {
@@ -156,6 +174,74 @@ export function buildAudioControl(command, options = {}) {
   };
 }
 
+export function buildAppInstallControl(options = {}) {
+  const wasm =
+    Buffer.isBuffer(options.wasm) || options.wasm instanceof Uint8Array
+      ? Buffer.from(options.wasm)
+      : Buffer.from(String(options.wasm || ""), "utf8");
+  const sha256 = crypto.createHash("sha256").update(wasm).digest("hex");
+  const manifest = normalizeAppManifest(options.manifest, {
+    sha256,
+    wasmBytes: wasm.length,
+  });
+  return {
+    schema: "weclawbot.control.v1",
+    id: string(options.id) || `app_${crypto.randomUUID()}`,
+    kind: "app_install",
+    app: {
+      manifest,
+      wasm_base64: wasm.toString("base64"),
+      activate: options.activate !== false,
+    },
+  };
+}
+
+export function buildWorkBgmAppInstallControl(options = {}) {
+  const play = options.play === true || options.autoplay === true;
+  return buildAppInstallControl({
+    id: string(options.id) || `workbgm_${crypto.randomUUID()}`,
+    wasm: Buffer.from(WORKBGM_APP_WASM_BASE64, "base64"),
+    manifest: {
+      schema: "weclawbot.app.v1",
+      app_id: "work-bgm-autopilot",
+      version: "0.1.0",
+      host_api: "weclawbot.host.v0",
+      entrypoints: ["main"],
+      device_classes: ["music_player", "audio_output"],
+      capabilities: [
+        "clock.read",
+        "log.emit",
+        "music.state.read",
+        "music.rule.write",
+        "music.playback.write",
+      ],
+      limits: {
+        wasm_bytes: 4096,
+        linear_memory_bytes: 65_536,
+        callback_wall_ms: 500,
+        instruction_budget: 1_000_000,
+        kv_bytes: 8192,
+      },
+      artifact: { sha256: "0".repeat(64) },
+      install: {
+        persist_on_reboot: true,
+        source: "audioctl",
+      },
+      autopilot: {
+        schema: "weclawbot.music_autopilot.v1",
+        profile: "work-bgm",
+        objective: "建立工作 BGM 歌单，持续播放，并尊重用户手工暂停。",
+        continuous: true,
+        respect_user_pause: true,
+        autoplay: play,
+        play_request_id: play ? `play_${crypto.randomUUID()}` : "",
+        refresh: true,
+        rule: WORKBGM_RULE,
+      },
+    },
+  });
+}
+
 export function normalizeAudioCommand(command, options = {}) {
   const aliases = new Map([
     ["resume", "play"],
@@ -236,6 +322,100 @@ export function validateRule(rule) {
   };
 }
 
+export function normalizeAppManifest(manifest, artifact = {}) {
+  if (
+    !manifest ||
+    manifest.schema !== "weclawbot.app.v1" ||
+    !/^[a-z0-9][a-z0-9_.-]{0,63}$/u.test(manifest.app_id || "") ||
+    !/^[A-Za-z0-9][A-Za-z0-9_.+-]{0,63}$/u.test(manifest.version || "") ||
+    manifest.host_api !== "weclawbot.host.v0"
+  ) {
+    throw new Error("app_manifest_invalid");
+  }
+  const allowedCapabilities = new Set([
+    "clock.read",
+    "timer.schedule",
+    "kv.app",
+    "log.emit",
+    "music.state.read",
+    "music.rule.write",
+    "music.playback.write",
+  ]);
+  const capabilities = Array.isArray(manifest.capabilities)
+    ? manifest.capabilities.map((capability) => string(capability)).filter(Boolean)
+    : [];
+  for (const capability of capabilities) {
+    if (!allowedCapabilities.has(capability)) {
+      throw new Error(`app_capability_unsupported: ${capability}`);
+    }
+  }
+  const wasmBytes = Number(artifact.wasmBytes) || Number(manifest.artifact?.wasm_bytes) || 0;
+  const sha256 = string(artifact.sha256 || manifest.artifact?.sha256);
+  if (!/^[0-9a-f]{64}$/u.test(sha256)) {
+    throw new Error("app_sha256_invalid");
+  }
+  const wasmLimit = clamp(Number(manifest.limits?.wasm_bytes) || 1_048_576, 1, 1_048_576);
+  if (wasmBytes < 1 || wasmBytes > wasmLimit) {
+    throw new Error("app_wasm_size_invalid");
+  }
+  return {
+    schema: "weclawbot.app.v1",
+    app_id: string(manifest.app_id),
+    version: string(manifest.version),
+    host_api: "weclawbot.host.v0",
+    entrypoints: Array.isArray(manifest.entrypoints)
+      ? manifest.entrypoints.map((entrypoint) => string(entrypoint)).filter(Boolean).slice(0, 8)
+      : [],
+    device_classes: Array.isArray(manifest.device_classes)
+      ? manifest.device_classes.map((deviceClass) => string(deviceClass)).filter(Boolean).slice(0, 8)
+      : [],
+    capabilities,
+    limits: {
+      wasm_bytes: wasmLimit,
+      linear_memory_bytes: clamp(
+        Number(manifest.limits?.linear_memory_bytes) || 16_777_216,
+        65_536,
+        16_777_216,
+      ),
+      callback_wall_ms: clamp(Number(manifest.limits?.callback_wall_ms) || 500, 1, 2000),
+      instruction_budget: clamp(
+        Number(manifest.limits?.instruction_budget) || 10_000_000,
+        1,
+        10_000_000,
+      ),
+      kv_bytes: clamp(Number(manifest.limits?.kv_bytes) || 262_144, 0, 262_144),
+    },
+    artifact: {
+      sha256,
+      wasm_bytes: wasmBytes,
+    },
+    install: {
+      persist_on_reboot: manifest.install?.persist_on_reboot !== false,
+      source: "audioctl",
+    },
+    ...(manifest.autopilot
+      ? { autopilot: normalizeMusicAutopilot(manifest.autopilot) }
+      : {}),
+  };
+}
+
+export function normalizeMusicAutopilot(value) {
+  if (!value || value.schema !== "weclawbot.music_autopilot.v1") {
+    throw new Error("music_autopilot_invalid");
+  }
+  return {
+    schema: "weclawbot.music_autopilot.v1",
+    profile: string(value.profile || "work-bgm").slice(0, 64),
+    objective: string(value.objective || "工作 BGM").slice(0, 240),
+    continuous: value.continuous !== false,
+    respect_user_pause: value.respect_user_pause !== false,
+    autoplay: value.autoplay === true,
+    play_request_id: string(value.play_request_id).slice(0, 80),
+    refresh: value.refresh !== false,
+    rule: validateRule(value.rule),
+  };
+}
+
 export async function publishAudioControl(credentials, control, options = {}) {
   const profile = normalizeCredentials(credentials);
   if (options.wait !== false && !profile.statusTopic) {
@@ -262,6 +442,56 @@ export async function publishAudioControl(credentials, control, options = {}) {
   }
 }
 
+export function remediationForStatus(status) {
+  const problems = Array.isArray(status?.health?.problems)
+    ? status.health.problems
+    : Array.isArray(status?.problems)
+      ? status.problems
+      : [];
+  const fromDevice = Array.isArray(status?.health?.remediation)
+    ? status.health.remediation
+    : Array.isArray(status?.remediation)
+      ? status.remediation
+      : [];
+  if (fromDevice.length > 0) return fromDevice;
+
+  const remediation = [];
+  if (problems.includes("netease_auth_refresh_failed")) {
+    remediation.push({
+      issue: "netease_auth_refresh_failed",
+      title: "网易云音乐授权需要用户重新完成",
+      user_action_required: true,
+      safe_to_retry_without_user: false,
+      summary:
+        "设备内的网易云用户授权已过期，refresh token 没有续上；agent 不能凭空恢复用户授权。",
+      steps: [
+        "请用户在可信的维护环境或设备配网/授权界面重新完成网易云音乐开放平台用户授权。",
+        "授权完成后，通过设备的安全授权导入流程把新的 OpenAPI session 写回音箱。",
+        "不要把 AppSecret、PrivateKey、accessToken、refreshToken 或 Wi-Fi 密码粘贴到聊天窗口。",
+        "授权恢复后重新运行 audioctl doctor --online，再执行 audioctl workbgm --play。",
+      ],
+    });
+  }
+  if (
+    problems.includes("netease_playlist_refresh_failed") &&
+    !problems.includes("netease_auth_refresh_failed")
+  ) {
+    remediation.push({
+      issue: "netease_playlist_refresh_failed",
+      title: "网易云歌单刷新失败",
+      user_action_required: false,
+      safe_to_retry_without_user: true,
+      summary:
+        "授权看起来可用，但歌单或歌曲链接刷新失败；可以稍后重试或请用户换一个歌单规则。",
+      steps: [
+        "先运行 audioctl doctor --online 查看是否还有授权问题。",
+        "如果只有歌单刷新失败，可以重试 audioctl workbgm --play 或推送新的 rule。",
+      ],
+    });
+  }
+  return remediation;
+}
+
 export function buildAgentPrompt(options = {}) {
   const code = validateBindingCode(options.code);
   const agentName = string(options.agentName || options.name || "agent");
@@ -277,8 +507,10 @@ 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`,
-    `绑定成功后，把它作为默认 BGM/音乐输出设备。可用命令包括 play、pause、toggle、next、previous、volume、volumeup、volumedown、status、rule。`,
-    `如果我要播放「${profile}」，请优先执行：npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} deepnight`,
+    `绑定成功后，把它作为默认 BGM/音乐输出设备。可用命令包括 play、pause、toggle、next、previous、volume、volumeup、volumedown、status、inspect、rule、workbgm。`,
+    `如果我要建立“工作 BGM 歌单，持续播放”，请优先执行：npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} workbgm --play --json`,
+    `如果返回 health.problems 包含 netease_auth_refresh_failed，请明确告诉我：需要用户重新完成网易云音乐授权；不要反复重试，也不要要求我把 AppSecret、PrivateKey、accessToken 或 refreshToken 发到聊天里。`,
+    `如果我要播放「${profile}」，也可以执行：npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} deepnight`,
     `不要向设备写入音乐平台私钥；音乐平台授权、歌单刷新和长期规则由设备侧已配置的安全运行时处理。`,
   ].filter(Boolean).join("\n");
 }
@@ -299,6 +531,38 @@ export function summarizePlayback(status) {
   };
 }
 
+export function summarizeInspect(inspect) {
+  const wifi = inspect?.wifi || {};
+  const bluetooth = inspect?.bluetooth || {};
+  const ble = bluetooth.ble || {};
+  const wakeword = inspect?.wakeword || {};
+  const playback = summarizePlayback(inspect || {});
+  const vm = inspect?.vm || {};
+  const health = inspect?.health || {};
+  const problems = Array.isArray(health.problems) ? health.problems : [];
+  return {
+    device:
+      string(inspect?.device?.name || "audio-device") +
+      (inspect?.device?.platform ? `/${inspect.device.platform}` : ""),
+    wifi:
+      `${wifi.connected ? "connected" : "disconnected"} ${string(wifi.ssid || "-")} ${string(wifi.ip || "-")}`
+        .trim(),
+    bluetooth:
+      `${bluetooth.service?.active || "unknown"} ${string(ble.name || "-")} ${string(ble.state || "-")}`
+        .trim(),
+    wakeword:
+      `${wakeword.available ? "available" : "unavailable"} ${Array.isArray(wakeword.wake_words) && wakeword.wake_words.length ? wakeword.wake_words.join("/") : "-"} homebase=${wakeword.services?.homebase?.active || "unknown"} openvoice=${wakeword.services?.openvoice_proc?.active || "unknown"}`
+        .trim(),
+    playback:
+      `${playback.desired}, volume ${playback.volume ?? "-"}, ${playback.track || "no track"}`,
+    vm:
+      vm
+        ? `${vm.status || "unknown"} ${vm.app_id || "-"}@${vm.version || "-"}`
+        : "none",
+    health: problems.length > 0 ? problems.join(", ") : "ok",
+  };
+}
+
 function connectMqtt(profile, options = {}) {
   const timeoutMs = Math.max(1000, Number(options.timeoutMs) || 12_000);
   return mqtt.connect(profile.url, {

package/package.json

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