@openbrt/audioctl 0.1.2 → 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
@@ -60,8 +69,9 @@ device, writes the bundled 工作 BGM playlist rule through the device-side musi
 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
+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.
 

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/lib/index.mjs

@@ -464,11 +464,14 @@ export function remediationForStatus(status) {
       safe_to_retry_without_user: false,
       summary:
         "设备内的网易云用户授权已过期，refresh token 没有续上；agent 不能凭空恢复用户授权。",
+      user_message:
+        "请在手机上打开音箱配网/授权入口，重新完成网易云音乐授权。完成后回到 agent 说“已授权”。不要发送任何密钥、token 或密码。",
+      agent_after_user_confirms: "audioctl workbgm --play --json",
       steps: [
-        "请用户在可信的维护环境或设备配网/授权界面重新完成网易云音乐开放平台用户授权。",
-        "授权完成后，通过设备的安全授权导入流程把新的 OpenAPI session 写回音箱。",
-        "不要把 AppSecret、PrivateKey、accessToken、refreshToken 或 Wi-Fi 密码粘贴到聊天窗口。",
-        "授权恢复后重新运行 audioctl doctor --online，再执行 audioctl workbgm --play。",
+        "告诉用户：请在手机上的音箱配网/授权入口重新完成网易云音乐授权。",
+        "告诉用户：授权完成后只需要回复“已授权”。",
+        "不要要求用户理解内部授权包，也不要让用户粘贴 AppSecret、PrivateKey、accessToken、refreshToken、Wi-Fi 密码或 MQTT 凭据。",
+        "用户回复已授权后，agent 自动重试 audioctl workbgm --play --json，并报告结果。",
       ],
     });
   }
@@ -509,7 +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 发到聊天里。`,
+    `如果返回 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.2",
+  "version": "0.1.3",
   "description": "Generic WeClawBot audio-output control CLI and AI-agent plugin.",
   "type": "module",
   "license": "MIT",