@openbrt/audioctl 0.1.1 → 0.1.2

package/README.md

@@ -59,6 +59,11 @@ without receiving Wi-Fi passwords, MQTT credentials, or music-platform secrets.
 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

package/bin/audioctl.mjs

@@ -18,6 +18,7 @@ import {
   normalizeCredentials,
   publishAudioControl,
   readCredentials,
+  remediationForStatus,
   summarizeInspect,
   summarizePlayback,
   testConnection,
@@ -125,6 +126,7 @@ async function commandDoctor(values) {
     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;
@@ -146,6 +148,10 @@ async function commandInspect(values) {
     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;
@@ -339,6 +345,7 @@ function credentialsPath() {
 }
 
 function print(value, json) {
+  value = decorateForAgent(value);
   if (json) {
     process.stdout.write(`${JSON.stringify(value)}\n`);
     return;
@@ -358,3 +365,14 @@ function print(value, json) {
   }
   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

@@ -442,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");
@@ -459,6 +509,7 @@ export function buildAgentPrompt(options = {}) {
     `npm exec --package ${PACKAGE_NAME} -- ${COMMAND_NAME} doctor --online`,
     `绑定成功后，把它作为默认 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");

package/package.json

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