@openbrt/audioctl 0.1.13 → 0.1.14

package/README.md

@@ -89,6 +89,7 @@ audioctl wakeword bind ./wakeword-bindings.json --json
 audioctl wakeword trigger work_mode --source agent --json
 audioctl firmware check --json
 audioctl firmware update --yes --json
+audioctl report "center LED active=true but user cannot see it" --kind capability_mismatch --area light --include-inspect --json
 audioctl feedback signal ready
 audioctl feedback flash cyan --repeat 2
 audioctl feedback volume 66
@@ -324,6 +325,35 @@ Light messages use a distinct command envelope:
 Supported light commands are `describe`, `set`, `timeline`, `bind`, and
 `clear`. Continuous light timing and event reactions run on the device VM.
 
+## Agent feedback reports
+
+`audioctl report` is the agent-to-maintainer feedback channel for issues,
+suggestions, capability mismatches, UX gaps, and documentation gaps. It writes a
+redacted JSON report to `~/WeClawBot/agent-feedback` by default, or to
+`WEC_AUDIO_REPORTS_DIR` / `--reports-dir DIR` when set.
+
+User observation wins over status. A device returning `applied`, `active=true`,
+or a capability entry only means the runtime accepted the command; it does not
+prove the user can physically see, hear, or feel the result. If a user reports
+that a center LED is not visible, a touch gesture is unreliable, or a beep is not
+audible, agents should fall back to a confirmed visible/audible/controllable
+behavior, then create a local report:
+
+```bash
+audioctl report "center LED surface is reported active but not visually observable by the user" \
+  --kind capability_mismatch \
+  --area light \
+  --observed "light_active=true, user still cannot see center LED" \
+  --expected "visible center-light cue or capability should be marked unavailable" \
+  --include-inspect \
+  --json
+```
+
+Reports are local by default. Agents must ask the user before posting a report
+to a public issue tracker, chat, email, or any other external system. Reports
+must not include MQTT credentials, music-platform tokens, Wi-Fi passwords, or
+other secrets.
+
 Wakeword messages configure the logical voice-trigger layer:
 
 ```json

package/agent-plugin.json

@@ -39,6 +39,17 @@
     "music_platform_auth": "音乐平台授权属于 agent 侧能力，由 agent 的连接器、OAuth、secret store 或用户明确提供的运行环境凭据完成。",
     "device_purpose": "设备用途由 agent 安装的 VM app 和显式 capabilities 决定，不由配网流程决定。"
   },
+  "agent_feedback_channel": {
+    "purpose": "让用户 agent 在能力声明、控制回执、真实体验、文档或插件引导不一致时留下结构化反馈。",
+    "primary_command": "audioctl report \"MESSAGE\" --kind issue --area other --json",
+    "rules": [
+      "用户的现场视觉、听觉、触控反馈优先于设备返回的 active=true、applied 或 capability 声明。",
+      "如果用户说某个 surface 看不到、按键不灵、蜂鸣不明显或体验不符合目标，agent 不要继续用状态回执证明它应该可用；先降级到用户确认可见/可听/可控的方案。",
+      "出现 capability mismatch 时运行 audioctl report \"MESSAGE\" --kind capability_mismatch --area light --include-inspect --json 生成本地脱敏报告。",
+      "报告默认只保存到本机，不自动提交外部系统；外发前必须获得用户确认。",
+      "报告不得包含 MQTT 凭据、音乐平台 token、Wi-Fi 密码、AppSecret、PrivateKey 或其他密钥。"
+    ]
+  },
   "device_classes": [
     "audio_io",
     "audio_output",
@@ -117,8 +128,14 @@
     {
       "intent": "帮我把设备灯效、音量灯和按键反馈音接上",
       "primary_command": "audioctl feedback signal ready",
-      "agent_strategy": "先运行 audioctl inspect --json 或 audioctl light describe --json 读取 light.surfaces、events、limits 以及 feedback/input capabilities。MQTT 是控制面，不是实时灯效数据面；不要读取 MQTT 凭据、不要 import mqtt、不要保持 MQTT 长连接、不要写 agent 端 BPM/while/sleep 循环去刷 LED。一次性语义提示可用 audioctl feedback signal/flash/volume/beep/clear；复杂灯效优先使用 audioctl light timeline 和 audioctl light bind，把外圈、中心等 surface 的 keyframes 与 media/input 事件绑定到设备本地。feedback effect 只是兼容/demo 入口，不要把 music_beat/pulse/breathing 当成能力边界。物理按键/触控属于 VM app 的 input.button.bind 能力，具体绑定由 agent 根据用户目标和 capabilities 自行规划。",
-      "if_missing_capability": "不要伪造灯效或按键能力；如果 inspect 未报告对应 capability，只说明当前设备适配未提供该能力，并建议安装或升级设备 VM。"
+      "agent_strategy": "先运行 audioctl inspect --json 或 audioctl light describe --json 读取 light.surfaces、events、limits 以及 feedback/input capabilities。MQTT 是控制面，不是实时灯效数据面；不要读取 MQTT 凭据、不要 import mqtt、不要保持 MQTT 长连接、不要写 agent 端 BPM/while/sleep 循环去刷 LED。一次性语义提示可用 audioctl feedback signal/flash/volume/beep/clear；复杂灯效优先使用 audioctl light timeline 和 audioctl light bind，把外圈、中心等 surface 的 keyframes 与 media/input 事件绑定到设备本地。feedback effect 只是兼容/demo 入口，不要把 music_beat/pulse/breathing 当成能力边界。物理按键/触控属于 VM app 的 input.button.bind 能力，具体绑定由 agent 根据用户目标和 capabilities 自行规划。用户的现场视觉/听觉/触控反馈优先于 active=true、applied 或 capability 声明；如果用户说 center LED 或任何 surface 肉眼不可见，不要继续堆亮度并声称成功，先降级到可见的 ring/all/声音反馈，再生成本地报告。",
+      "if_missing_capability": "不要伪造灯效或按键能力；如果 inspect 未报告对应 capability，只说明当前设备适配未提供该能力，并建议安装或升级设备 VM。",
+      "if_user_reports_mismatch": "运行 audioctl report \"User reports requested feedback is not physically observable despite applied/active status\" --kind capability_mismatch --area light --include-inspect --json；报告只保存本机，外发前必须问用户。"
+    },
+    {
+      "intent": "反馈设备、插件或 VM app 的问题/建议",
+      "primary_command": "audioctl report \"MESSAGE\" --kind issue --area other --json",
+      "agent_strategy": "把用户反馈整理为 observed/expected/reproduction/recommendation。需要设备状态佐证时加 --include-inspect；报告会脱敏并默认保存到本机。不要把 MQTT 凭据、音乐平台 token、Wi-Fi 密码或私钥写进报告；外发到 issue、聊天、邮件或其他系统前必须获得用户明确确认。"
     },
     {
       "intent": "让音箱作为语音遥控、家庭智能或语音互动端点",
@@ -192,6 +209,10 @@
       "name": "firmware",
       "usage": "audioctl firmware check [--manifest URL] | firmware update [--manifest URL] --yes"
     },
+    {
+      "name": "report",
+      "usage": "audioctl report MESSAGE [--kind issue|suggestion|capability_mismatch|ux_feedback|docs_feedback] [--area light|audio|input|wakeword|firmware|vm|plugin|docs|other] [--include-inspect] --json"
+    },
     {
       "name": "workbgm",
       "usage": "audioctl workbgm --play"

package/bin/audioctl.mjs

@@ -8,6 +8,7 @@ import {
   DEFAULT_CREDENTIALS_PATH,
   DEFAULT_ENDPOINT,
   DEFAULT_FIRMWARE_MANIFEST_URL,
+  DEFAULT_REPORTS_DIR,
   DEEPNIGHT_RULE,
   PACKAGE_NAME,
   bindAgent,
@@ -28,6 +29,7 @@ import {
   readCredentials,
   redactAgentFacingValue,
   remediationForStatus,
+  saveAgentFeedbackReport,
   summarizeInspect,
   summarizePlayback,
   testConnection,
@@ -53,6 +55,7 @@ async function run(name, values) {
   if (name === "inspect") return commandInspect(values);
   if (name === "prompt") return commandPrompt(values);
   if (name === "manifest") return commandManifest();
+  if (name === "report") return commandReport(values);
   if (name === "firmware") return commandFirmware(values);
   if (name === "app") return commandApp(values);
   if (name === "queue") return commandQueue(values);
@@ -73,6 +76,7 @@ function usage(exitCode = 0) {
   ${COMMAND_NAME} doctor [--online] [--json]
   ${COMMAND_NAME} inspect [--json]
   ${COMMAND_NAME} prompt CODE [--agent AGENT] [--alias NAME]
+  ${COMMAND_NAME} report MESSAGE [--kind issue|suggestion|capability_mismatch|ux_feedback|docs_feedback] [--area light|audio|input|wakeword|firmware|vm|plugin|docs|other]
   ${COMMAND_NAME} play|pause|toggle|next|previous|volumeup|volumedown|status
   ${COMMAND_NAME} volume 0..100
   ${COMMAND_NAME} seek MILLISECONDS
@@ -105,6 +109,7 @@ Options:
   --credentials FILE   override audioctl-managed local credential file
   --endpoint URL       default: ${DEFAULT_ENDPOINT}
   --manifest URL       default: ${DEFAULT_FIRMWARE_MANIFEST_URL}
+  --reports-dir DIR    default: ${DEFAULT_REPORTS_DIR}
   --timeout SECONDS    default: 12
   --json               machine-readable output
   --nowait             publish without waiting for device status
@@ -223,6 +228,45 @@ async function commandManifest() {
   process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
 }
 
+async function commandReport(values) {
+  const options = parseOptions(values, {
+    credentials: credentialsPath(),
+    timeout: 12,
+    json: false,
+    include_inspect: false,
+    kind: "issue",
+    area: "other",
+    severity: "medium",
+    reports_dir: process.env.WEC_AUDIO_REPORTS_DIR || DEFAULT_REPORTS_DIR,
+  });
+  const message = String(options._.join(" ") || options.message || "").trim();
+  if (!message) throw new Error("report_requires_message");
+  let inspect = null;
+  if (options.include_inspect) {
+    const credentials = await readCredentials(options.credentials);
+    const delivery = await publishAudioControl(credentials, buildAudioControl("status"), {
+      timeoutMs: Number(options.timeout) * 1000,
+    });
+    inspect = delivery.status?.inspect || delivery.status || null;
+  }
+  const saved = await saveAgentFeedbackReport({
+    kind: options.kind || options.type,
+    area: options.area || options.component,
+    severity: options.severity,
+    title: options.title,
+    message,
+    observed: options.observed || options.actual,
+    expected: options.expected,
+    reproduction: options.reproduction || options.steps,
+    recommendation: options.recommendation || options.suggestion,
+    agent: options.agent || options.name,
+    inspect,
+  }, {
+    reportsDir: options.reports_dir,
+  });
+  print(saved, options.json);
+}
+
 async function commandFirmware(values) {
   const subcommand = String(values[0] || "check").replace(/-/gu, "_").toLowerCase();
   if (!new Set(["check", "update", "upgrade"]).has(subcommand)) {
@@ -621,8 +665,8 @@ function parseOptions(values, defaults = {}) {
       options._.push(value);
       continue;
     }
-    const key = value.slice(2);
-    if (key === "json" || key === "online" || key === "nowait" || key === "play" || key === "yes" || key === "force") {
+    const key = value.slice(2).replace(/-/gu, "_");
+    if (key === "json" || key === "online" || key === "nowait" || key === "play" || key === "yes" || key === "force" || key === "include_inspect") {
       options[key] = true;
       continue;
     }
@@ -637,16 +681,31 @@ function parseOptions(values, defaults = {}) {
       "endpoint",
       "effect",
       "channel",
+      "actual",
+      "area",
+      "component",
+      "expected",
+      "kind",
       "level",
       "manifest",
+      "message",
       "name",
+      "observed",
       "pattern",
       "profile",
       "repeat",
       "phrase",
+      "recommendation",
+      "reports_dir",
+      "reproduction",
+      "severity",
       "source",
+      "steps",
+      "suggestion",
       "surface",
       "timeout",
+      "title",
+      "type",
       "volume",
       "word",
     ]).has(key)) {

package/lib/index.mjs

@@ -16,6 +16,11 @@ export const DEFAULT_CREDENTIALS_PATH = path.join(
   "weclawbot",
   "audio-mqtt.json",
 );
+export const DEFAULT_REPORTS_DIR = path.join(
+  os.homedir(),
+  "WeClawBot",
+  "agent-feedback",
+);
 export const ABSTRACT_HARDWARE_TYPE = "audio_voice_ambient_endpoint";
 export const ABSTRACT_HARDWARE_NAME = "Audio Voice Ambient Endpoint";
 
@@ -1344,6 +1349,187 @@ export async function publishAudioControl(credentials, control, options = {}) {
   });
 }
 
+export function buildAgentFeedbackReport(options = {}) {
+  const kind = normalizeFeedbackReportKind(options.kind || options.type || "issue");
+  const area = normalizeFeedbackReportArea(options.area || options.component || "other");
+  const severity = normalizeFeedbackReportSeverity(options.severity || "medium");
+  const title = textField(options.title || summarizeReportTitle(kind, area, options.message), 120);
+  const message = textField(options.message || options.summary || options.description, 2000);
+  if (!message) throw new Error("report_message_required");
+  const inspect = options.inspect ? redactAgentFacingValue(options.inspect) : null;
+  return redactAgentFeedbackReport({
+    schema: "weclawbot.agent_feedback.v1",
+    id: string(options.id) || `report_${crypto.randomUUID()}`,
+    package: PACKAGE_NAME,
+    command: COMMAND_NAME,
+    device_type:
+      textField(options.deviceType || inspect?.device?.abstract_hardware || inspect?.device_type, 80) ||
+      ABSTRACT_HARDWARE_TYPE,
+    kind,
+    area,
+    severity,
+    title,
+    message,
+    observed: textField(options.observed || options.actual, 2000),
+    expected: textField(options.expected, 2000),
+    reproduction: textField(options.reproduction || options.steps, 2000),
+    recommendation: textField(options.recommendation || options.suggestion, 2000),
+    evidence: Array.isArray(options.evidence)
+      ? options.evidence.map((item) => textField(item, 240)).filter(Boolean).slice(0, 12)
+      : [],
+    inspect,
+    agent: textField(options.agent || options.agentName || process.env.WEC_AGENT_NAME || "", 80),
+    local_context: {
+      os: `${os.platform()} ${os.release()}`,
+      arch: os.arch(),
+      node: process.version,
+      cwd: textField(options.cwd || process.cwd(), 240),
+    },
+    privacy: {
+      secrets_redacted: true,
+      user_permission_required_before_external_submission: true,
+      note:
+        "audioctl saves this report locally. The agent must ask the user before posting it to a public issue tracker, chat, email, or other external system.",
+    },
+    created_at: new Date().toISOString(),
+  });
+}
+
+export async function saveAgentFeedbackReport(report, options = {}) {
+  const normalized = buildAgentFeedbackReport(report);
+  const reportsDir = expandReportDirectory(options.reportsDir || options.directory);
+  await fs.mkdir(reportsDir, { recursive: true, mode: 0o700 });
+  const file = path.join(
+    reportsDir,
+    `${normalized.created_at.replace(/[:.]/gu, "-")}-${normalized.id}.json`,
+  );
+  await fs.writeFile(file, `${JSON.stringify(normalized, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  await fs.chmod(file, 0o600);
+  return {
+    schema: "weclawbot.agent_feedback.saved.v1",
+    ok: true,
+    report_path: file,
+    report: normalized,
+    next_step:
+      "Tell the user this local feedback report was created. Ask before submitting it externally.",
+  };
+}
+
+export function expandReportDirectory(value) {
+  const directory =
+    string(value) ||
+    string(process.env.WEC_AUDIO_REPORTS_DIR) ||
+    DEFAULT_REPORTS_DIR;
+  return expandPath(directory);
+}
+
+function normalizeFeedbackReportKind(value) {
+  const kind = string(value).replace(/-/gu, "_").toLowerCase();
+  const aliases = new Map([
+    ["bug", "issue"],
+    ["problem", "issue"],
+    ["capability_gap", "capability_mismatch"],
+    ["gap", "capability_mismatch"],
+    ["feature", "suggestion"],
+    ["idea", "suggestion"],
+  ]);
+  const normalized = aliases.get(kind) || kind;
+  if (!new Set([
+    "issue",
+    "suggestion",
+    "capability_mismatch",
+    "ux_feedback",
+    "docs_feedback",
+  ]).has(normalized)) {
+    throw new Error("report_kind_invalid");
+  }
+  return normalized;
+}
+
+function normalizeFeedbackReportArea(value) {
+  const area = string(value).replace(/-/gu, "_").toLowerCase();
+  const normalized = area || "other";
+  if (!new Set([
+    "audio",
+    "music",
+    "light",
+    "led",
+    "feedback",
+    "input",
+    "wakeword",
+    "firmware",
+    "vm",
+    "plugin",
+    "docs",
+    "provisioning",
+    "other",
+  ]).has(normalized)) {
+    throw new Error("report_area_invalid");
+  }
+  return normalized;
+}
+
+function normalizeFeedbackReportSeverity(value) {
+  const severity = string(value).replace(/-/gu, "_").toLowerCase() || "medium";
+  if (!new Set(["low", "medium", "high", "critical"]).has(severity)) {
+    throw new Error("report_severity_invalid");
+  }
+  return severity;
+}
+
+function summarizeReportTitle(kind, area, message) {
+  const text = textField(message, 80);
+  return text || `${kind}:${area}`;
+}
+
+function textField(value, maximum) {
+  return redactReportText(String(value ?? ""))
+    .replace(/[\u0000-\u001f\u007f]+/gu, " ")
+    .replace(/\s+/gu, " ")
+    .trim()
+    .slice(0, maximum);
+}
+
+function redactAgentFeedbackReport(report) {
+  return redactAgentFacingValue(redactReportValue(report));
+}
+
+function redactReportValue(value) {
+  if (Array.isArray(value)) return value.map(redactReportValue);
+  if (!value || typeof value !== "object") {
+    return typeof value === "string" ? redactReportText(value) : value;
+  }
+  const result = {};
+  for (const [key, child] of Object.entries(value)) {
+    const normalizedKey = key.toLowerCase();
+    if (normalizedKey === "secrets_redacted") {
+      result[key] = child === true;
+      continue;
+    }
+    if (
+      normalizedKey.includes("password") ||
+      normalizedKey.includes("secret") ||
+      normalizedKey.includes("token") ||
+      normalizedKey.includes("privatekey") ||
+      normalizedKey.includes("credential")
+    ) {
+      result[key] = "[redacted]";
+      continue;
+    }
+    result[key] = redactReportValue(child);
+  }
+  return result;
+}
+
+function redactReportText(value) {
+  return String(value || "")
+    .replace(/(access[_-]?token|refresh[_-]?token|app[_-]?secret|private[_-]?key|password|passwd|pwd)\s*[:=]\s*([^\s,;]+)/giu, "$1=[redacted]")
+    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]{16,}/gu, "Bearer [redacted]")
+    .replace(/[A-Za-z0-9+/]{32,}={0,2}/gu, "[redacted-long-token]");
+}
+
 export function remediationForStatus(status) {
   const problems = Array.isArray(status?.health?.problems)
     ? status.health.problems
@@ -1416,13 +1602,14 @@ export function buildAgentPrompt(options = {}) {
     `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、light、led、wakeword、app install、firmware check/update。`,
+    `绑定成功后，把它作为默认音频/语音/环境 I/O 端点；不要把它假定成只会播放音乐。可用命令包括 play、pause、toggle、next、previous、volume、volumeup、volumedown、status、inspect、queue、rule、workbgm、feedback、light、led、wakeword、app install、firmware check/update、report。`,
     `当我给出目标时，请你在 capabilities、安全边界和用户授权范围内自行规划实现路径；插件只声明能力和边界，不穷举具体玩法。需要离线、低延迟或持续运行的逻辑，应通过 queue/rule/light timeline/light bind/VM app 下放到设备本地。`,
     `MQTT/weclawbot.link 对你只是控制面和部署通道，不是实时灯效数据面。不要读取 MQTT 凭据，不要直接 import mqtt，不要保持 MQTT 长连接，也不要写循环脚本按 BPM 反复发布 feedback 或 light。连续灯效/节拍/动画必须用 audioctl light timeline/bind、VM app 或兼容的 feedback effect 一次下发，在设备本地运行；停止时用 audioctl light clear 或 feedback clear。`,
     `蓝牙/Wi-Fi 配网只负责设备入网、发现和 weclawbot.link 绑定；音乐平台授权请走 agent 侧连接器/OAuth/secret store；配网不决定设备用途。`,
     `音乐来源由你和用户协商，插件只做建议。你可以在 agent 侧使用用户授权的音乐平台 API、用户媒体库、合法公开音源或其他合规来源生成队列/规则/VM app。网易云开放平台可请求最高可用音质 URL。`,
     `如果用户选择 Spotify，必须走 Spotify 官方 Spotify Connect/Web Playback SDK 或控制用户已有 Spotify 播放设备；不要假设 Spotify Web API 能提供完整歌曲直链。`,
     `灯效、音量灯、蜂鸣和按键/触控反馈要先 inspect 或 light describe 确认 feedback/input/light capabilities。一次性语义反馈可用 feedback signal/flash/volume/beep/clear；复杂灯效请优先生成 light timeline 和 light bind，把外圈、中心等 surface 与 media/input 事件绑定到设备本地。feedback effect 只作为兼容/demo 入口，不要把 music_beat/pulse/breathing 当成能力边界。具体按键绑定请根据用户目标和 capabilities 自行规划，不要套固定模板。`,
+    `用户的现场视觉、听觉、触控反馈优先于设备返回的 active=true、applied 或 capability 声明。如果用户说某个 surface 看不到、按键不灵或反馈不明显，不要用状态回执反驳用户；先降级到用户确认可见/可听/可控的方案，再运行 audioctl report "..." --kind capability_mismatch --area light --include-inspect --json 生成本地脱敏报告。报告默认只保存在本机，外发前必须获得用户确认。`,
     `唤醒词/语音触发配置要通过 inspect 读取 wakeword.configurable、wakeword.commands 和 capabilities。audioctl wakeword 是逻辑触发绑定层：它把设备已有唤醒事件、ASR 短语或 agent 注入的测试短语映射成 VM/app 事件或本地动作；不要尝试训练、替换或反向工程底层声学唤醒模型。`,
     `如果你当前没有音乐平台身份，请只告诉我：我需要你把音乐平台身份连接到当前 agent 的官方连接器、OAuth 流程或 secret store；完成后回复“已授权”。不要反复重试，不要让我理解内部授权包，也不要要求我把 AppSecret、PrivateKey、accessToken 或 refreshToken 发到聊天里。`,
     `如果返回 health.problems 包含 netease_auth_refresh_failed，说明设备侧内置网易运行时授权失效；优先改走 agent 侧 queue/app 驱动。只有我明确要求继续使用设备侧网易运行时时，才提示需要独立的设备侧音乐账号设置入口；不要混入蓝牙/Wi-Fi 配网流程。`,

package/package.json

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