@openbrt/audioctl 0.1.1 → 0.1.3

package/README.md

@@ -10,10 +10,19 @@ audio command envelope can use the same package.
 ## Tell your agent
 
 ```text
-Install npm package @openbrt/audioctl, bind my audio device with pairing code 123456,
-run doctor, then use it as my default BGM/music output device.
+帮我在音箱建立一个工作 BGM 歌单，持续播放。请使用 @openbrt/audioctl 最新版。
 ```
 
+Agent contract:
+
+- If already bound, run the high-level task directly with `audioctl workbgm --play --json`.
+- If not bound, ask the user only for the short binding code, then bind and continue.
+- If NetEase Music authorization is expired, tell the user to reopen the speaker
+  provisioning/authorization entry on their phone and complete NetEase Music
+  authorization. After the user says “已授权”, retry the task.
+- Never ask the user to paste AppSecret, PrivateKey, accessToken, refreshToken,
+  Wi-Fi passwords, MQTT credentials, or other secrets into chat.
+
 ## Install and bind
 
 ```bash
@@ -59,6 +68,12 @@ 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 from
+the phone provisioning/authorization entry. The user only needs to come back and
+say “已授权”; the agent then retries `workbgm --play`. 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/agent-plugin.json

@@ -6,6 +6,7 @@
   "bin": "audioctl",
   "description": "Bind and control WeClawBot-compatible audio output devices from user-owned AI agents.",
   "transport": "weclawbot.link/mqtt",
+  "user_contract": "用户只需要给出设备身份和目标；agent 负责安装工具、绑定、执行、诊断和报告结果。",
   "device_classes": [
     "audio_output",
     "music_player"
@@ -40,6 +41,15 @@
     "credentials_env": "WEC_AUDIO_CREDENTIALS",
     "code_pattern": "^[A-Za-z0-9_-]{6,64}$"
   },
+  "natural_language_tasks": [
+    {
+      "intent": "帮我在音箱建立一个工作 BGM 歌单，持续播放",
+      "primary_command": "audioctl workbgm --play --json",
+      "if_unbound": "只向用户索要绑定码，然后运行 audioctl bind CODE --name AGENT；不要要求用户理解 MQTT、topic 或凭据文件。",
+      "if_netease_auth_failed": "告诉用户：请在手机上的音箱配网/授权入口重新完成网易云音乐授权，完成后回复“已授权”。不要要求用户粘贴 AppSecret、PrivateKey、accessToken、refreshToken、Wi-Fi 密码或 MQTT 凭据。",
+      "after_user_confirms_authorized": "重新运行 audioctl workbgm --play --json，然后报告是否 active/degraded。"
+    }
+  ],
   "commands": [
     {
       "name": "bind",

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,59 @@ 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 不能凭空恢复用户授权。",
+      user_message:
+        "请在手机上打开音箱配网/授权入口，重新完成网易云音乐授权。完成后回到 agent 说“已授权”。不要发送任何密钥、token 或密码。",
+      agent_after_user_confirms: "audioctl workbgm --play --json",
+      steps: [
+        "告诉用户：请在手机上的音箱配网/授权入口重新完成网易云音乐授权。",
+        "告诉用户：授权完成后只需要回复“已授权”。",
+        "不要要求用户理解内部授权包，也不要让用户粘贴 AppSecret、PrivateKey、accessToken、refreshToken、Wi-Fi 密码或 MQTT 凭据。",
+        "用户回复已授权后，agent 自动重试 audioctl workbgm --play --json，并报告结果。",
+      ],
+    });
+  }
+  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 +512,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.3",
   "description": "Generic WeClawBot audio-output control CLI and AI-agent plugin.",
   "type": "module",
   "license": "MIT",