@openbrt/audioctl 0.1.6 → 0.1.8

package/README.md

@@ -52,6 +52,11 @@ 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.
+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.
 
 ## Commands
 

package/agent-plugin.json

@@ -6,7 +6,12 @@
   "bin": "audioctl",
   "description": "Bind and drive WeClawBot-compatible audio, voice, and ambient I/O devices from user-owned AI agents.",
   "transport": "weclawbot.link/mqtt",
+  "hardware_abstraction": {
+    "agent_facing_type": "audio_voice_ambient_endpoint",
+    "rule": "agent 只通过 audioctl、VM manifest、capabilities 和控制回执理解设备；不要推断、询问或搜索品牌、型号、厂家资料、社区经验或拆机资料。"
+  },
   "user_contract": "用户只需要给出设备身份和目标；agent 负责选择合法平台 API、通过 agent 自己的连接器/OAuth/secret store 获取平台身份、构建最小权限脚本/队列、推送到设备 VM、诊断和报告结果。",
+  "runtime_note": "audioctl 会在本机自动串行化同一 MQTT 绑定凭据的并发控制命令，避免多个 agent 工具进程使用同一个 broker client_id 时互相踢下线。",
   "separation_of_concerns": {
     "provisioning": "蓝牙/Wi-Fi 配网只负责设备入网、发现和 weclawbot.link 绑定，不承载音乐平台授权，也不决定设备用途。",
     "music_platform_auth": "音乐平台授权属于 agent 侧能力，由 agent 的连接器、OAuth、secret store 或用户明确提供的运行环境凭据完成。",
@@ -68,7 +73,7 @@
     {
       "intent": "帮我在音箱建立一个工作 BGM 歌单，持续播放",
       "primary_command": "audioctl queue QUEUE.json --play --json",
-      "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；蓝牙配网和设备入网不是音乐平台授权入口。",
+      "agent_strategy": "先运行 audioctl inspect --json。把设备只当成 audio_voice_ambient_endpoint；不要推断或搜索品牌、型号、厂家资料、社区经验。音乐来源由 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 等官方连接器/OAuth/secret store 完成授权；完成后只需回复“已授权”。音乐授权不属于蓝牙/Wi-Fi 配网范围，也不要把 AppSecret、PrivateKey、accessToken、refreshToken、Wi-Fi 密码或 MQTT 凭据粘贴到聊天里。",

package/bin/audioctl.mjs

@@ -20,6 +20,7 @@ import {
   normalizeCredentials,
   publishAudioControl,
   readCredentials,
+  redactAgentFacingValue,
   remediationForStatus,
   summarizeInspect,
   summarizePlayback,
@@ -163,7 +164,7 @@ async function commandInspect(values) {
     inspect.remediation = remediation;
   }
   if (options.json) {
-    process.stdout.write(`${JSON.stringify(inspect)}\n`);
+    process.stdout.write(`${JSON.stringify(redactAgentFacingValue(inspect))}\n`);
     return;
   }
   const summary = summarizeInspect(inspect);
@@ -465,10 +466,11 @@ function print(value, json) {
 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;
+  const redacted = redactAgentFacingValue(value);
+  if (remediation.length === 0) return redacted;
+  if (Array.isArray(redacted.remediation) && redacted.remediation.length > 0) return redacted;
   return {
-    ...value,
+    ...redacted,
     remediation,
   };
 }

package/lib/index.mjs

@@ -14,6 +14,8 @@ export const DEFAULT_CREDENTIALS_PATH = path.join(
   "weclawbot",
   "audio-mqtt.json",
 );
+export const ABSTRACT_HARDWARE_TYPE = "audio_voice_ambient_endpoint";
+export const ABSTRACT_HARDWARE_NAME = "Audio Voice Ambient Endpoint";
 
 export const DEEPNIGHT_RULE = Object.freeze({
   schemaVersion: 1,
@@ -719,24 +721,26 @@ export async function publishAudioControl(credentials, control, options = {}) {
     throw new Error("status_topic_missing");
   }
   const timeoutMs = Math.max(1000, Number(options.timeoutMs) || 12_000);
-  const client = connectMqtt(profile, { timeoutMs });
-  try {
-    await onceConnected(client, timeoutMs);
-    if (options.wait === false) {
+  return withMqttClientLock(profile.clientId, timeoutMs, async () => {
+    const client = connectMqtt(profile, { timeoutMs });
+    try {
+      await onceConnected(client, timeoutMs);
+      if (options.wait === false) {
+        await publishJson(client, profile.controlTopic, control);
+        return { ok: true, published: true, applied: null };
+      }
+      await subscribe(client, profile.statusTopic);
+      const statusPromise = waitForStatus(client, {
+        correlationId: control.id,
+        timeoutMs,
+      });
       await publishJson(client, profile.controlTopic, control);
-      return { ok: true, published: true, applied: null };
+      const status = await statusPromise;
+      return { ok: status.kind === "applied", published: true, applied: true, status };
+    } finally {
+      client.end(true);
     }
-    await subscribe(client, profile.statusTopic);
-    const statusPromise = waitForStatus(client, {
-      correlationId: control.id,
-      timeoutMs,
-    });
-    await publishJson(client, profile.controlTopic, control);
-    const status = await statusPromise;
-    return { ok: status.kind === "applied", published: true, applied: true, status };
-  } finally {
-    client.end(true);
-  }
+  });
 }
 
 export function remediationForStatus(status) {
@@ -810,6 +814,7 @@ 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`,
+    `这台设备对你是抽象硬件产品：${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。`,
     `蓝牙/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。`,
@@ -839,6 +844,7 @@ export function summarizePlayback(status) {
 }
 
 export function summarizeInspect(inspect) {
+  inspect = redactAgentFacingValue(inspect);
   const wifi = inspect?.wifi || {};
   const bluetooth = inspect?.bluetooth || {};
   const ble = bluetooth.ble || {};
@@ -858,7 +864,7 @@ export function summarizeInspect(inspect) {
       `${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"}`
+      `${wakeword.available ? "available" : "unavailable"} ${Array.isArray(wakeword.wake_words) && wakeword.wake_words.length ? wakeword.wake_words.join("/") : "-"} wake_runtime=${wakeword.services?.wake_runtime?.active || "unknown"} voice_runtime=${wakeword.services?.voice_runtime?.active || "unknown"}`
         .trim(),
     playback:
       `${playback.desired}, volume ${playback.volume ?? "-"}, ${playback.track || "no track"}`,
@@ -870,6 +876,106 @@ export function summarizeInspect(inspect) {
   };
 }
 
+export function redactAgentFacingValue(value, keyPath = []) {
+  if (Array.isArray(value)) {
+    const last = keyPath[keyPath.length - 1];
+    if (last === "wake_words" || last === "exit_words") return [];
+    return value.map((item) => redactAgentFacingValue(item, keyPath));
+  }
+  if (!value || typeof value !== "object") {
+    return redactAgentFacingScalar(value, keyPath);
+  }
+
+  const result = {};
+  for (const [key, child] of Object.entries(value)) {
+    result[key] = redactAgentFacingValue(child, [...keyPath, key]);
+  }
+  const last = keyPath[keyPath.length - 1];
+  if (last === "device") {
+    result.name = ABSTRACT_HARDWARE_NAME;
+    result.abstract_hardware = ABSTRACT_HARDWARE_TYPE;
+    result.vendor_name_redacted = true;
+    result.model = "";
+    result.platform = result.platform && !containsHardwareBrand(result.platform)
+      ? result.platform
+      : "embedded_linux";
+    delete result.brand;
+    delete result.manufacturer;
+    delete result.product;
+  }
+  if (last === "ble") {
+    result.name = redactBleName(result.name);
+    result.vendor_name_redacted = true;
+  }
+  if (last === "wakeword") {
+    const wakeWordCount = Array.isArray(value.wake_words) ? value.wake_words.length : result.wake_word_count || 0;
+    const exitWordCount = Array.isArray(value.exit_words) ? value.exit_words.length : result.exit_word_count || 0;
+    result.engine = "wakeword_runtime";
+    result.wake_words = [];
+    result.exit_words = [];
+    result.wake_words_redacted = true;
+    result.wake_word_count = wakeWordCount;
+    result.exit_word_count = exitWordCount;
+    result.build = "";
+    if (result.services) {
+      result.services = {
+        wake_runtime:
+          result.services.wake_runtime ||
+          result.services.homebase ||
+          { active: "unknown" },
+        voice_runtime:
+          result.services.voice_runtime ||
+          result.services.openvoice_proc ||
+          { active: "unknown" },
+      };
+    }
+  }
+  if (Object.hasOwn(result, "device_type")) {
+    result.device_type = ABSTRACT_HARDWARE_TYPE;
+  }
+  if (Object.hasOwn(result, "driver") && containsHardwareBrand(result.driver)) {
+    result.driver = last === "input"
+      ? "touch_surface"
+      : last === "feedback"
+        ? "led_ring+speaker_prompt"
+        : "hardware_adapter";
+  }
+  return result;
+}
+
+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 (last === "model" || last === "brand" || last === "manufacturer" || last === "product") {
+    return "";
+  }
+  if (last === "name" && keyPath[keyPath.length - 2] === "device") {
+    return ABSTRACT_HARDWARE_NAME;
+  }
+  if (last === "name" && keyPath[keyPath.length - 2] === "ble") {
+    return redactBleName(value);
+  }
+  if (last === "driver" && containsHardwareBrand(value)) {
+    const parent = keyPath[keyPath.length - 2];
+    if (parent === "input") return "touch_surface";
+    if (parent === "feedback") return "led_ring+speaker_prompt";
+    return "hardware_adapter";
+  }
+  if (last === "build" && containsHardwareBrand(value)) return "";
+  return value;
+}
+
+function redactBleName(value) {
+  const text = string(value);
+  const suffix = text.match(/[-_]?([0-9A-Za-z]{4,8})$/u)?.[1] || "device";
+  return containsHardwareBrand(text) ? `BLE-Audio-${suffix}` : text;
+}
+
+function containsHardwareBrand(value) {
+  return /rokid|RokidMusic|若琪|洛奇/iu.test(String(value || ""));
+}
+
 function normalizeMediaUrl(value, trackNumber) {
   const raw = string(value);
   let parsed;
@@ -993,6 +1099,48 @@ function waitForStatus(client, options) {
   });
 }
 
+async function withMqttClientLock(clientId, timeoutMs, task) {
+  const lockRoot = path.join(os.tmpdir(), "openbrt-audioctl-locks");
+  await fs.mkdir(lockRoot, { recursive: true, mode: 0o700 });
+  const lockName = crypto
+    .createHash("sha256")
+    .update(String(clientId || "default"))
+    .digest("hex")
+    .slice(0, 24);
+  const lockDirectory = path.join(lockRoot, `${lockName}.lock`);
+  const started = Date.now();
+  while (true) {
+    try {
+      await fs.mkdir(lockDirectory, { mode: 0o700 });
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      try {
+        const stats = await fs.stat(lockDirectory);
+        if (Date.now() - stats.mtimeMs > Math.max(60_000, timeoutMs * 3)) {
+          await fs.rm(lockDirectory, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        // Race with another process removing the lock. Try again.
+      }
+      if (Date.now() - started > timeoutMs) {
+        throw new Error("mqtt_client_busy");
+      }
+      await sleep(120);
+    }
+  }
+  try {
+    return await task();
+  } finally {
+    await fs.rm(lockDirectory, { recursive: true, force: true });
+  }
+}
+
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
 function shellToken(value) {
   const text = string(value) || "agent";
   if (/^[A-Za-z0-9_./:@+-]+$/u.test(text)) return text;

package/package.json

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