✨ 添加 GM_audio 与 GM.audio 支持 (TM)

[cyfung1031]

Checklist / 检查清单

• Fixes API Compatibility Issue (TM)
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

背景

Tampermonkey 提供了用于控制和监听当前标签页音频状态的 GM_audio API。ScriptCat 此前缺少对应实现，用户脚本无法通过统一接口完成标签页静音、音频状态读取以及状态变化监听。

https://www.tampermonkey.net/documentation.php?locale=en&q=GM_audio

本 PR 为 ScriptCat 补充回调风格的 GM_audio 和 Promise 风格的 GM.audio，并处理 Manifest V3 Service Worker 可能被回收、监听连接意外断开、异步连接迟到以及注册完成前取消等生命周期问题。

本次改动

• 实现以下回调风格 API：

  • GM_audio.setMute
  • GM_audio.getState
  • GM_audio.addStateChangeListener
  • GM_audio.removeStateChangeListener

• 实现对应的 Promise 风格 API：

  • GM.audio.setMute
  • GM.audio.getState
  • GM.audio.addStateChangeListener
  • GM.audio.removeStateChangeListener

• Service Worker 使用 chrome.tabs.update 和 chrome.tabs.get 控制、读取当前标签页的音频状态。

• 通过 chrome.tabs.onUpdated 监听当前标签页的 mutedInfo 和 audible 变化。

• 多个状态监听器复用同一个长连接，最后一个监听器移除后主动断开连接并清理后台监听。

• Service Worker 意外断线时保留脚本监听器并自动恢复连接；恢复期间连续断线或连接创建失败时使用指数退避重试。

• 使用注册生命周期对象和世代边界丢弃迟到的异步连接，避免“移除后立即重新添加”产生连接泄漏或污染新一轮注册。

• 支持在注册完成前移除监听器，并保证待处理的 Promise 或回调能够立即、且仅一次地正常结束。

• 重复添加同一个监听函数不会创建重复监听或额外连接，并会复用当前注册结果。

• 脚本上下文失效时主动断开连接并清除全部音频监听状态。

• 隔离完成回调和状态监听器自身抛出的异常，避免影响 API 状态、连接恢复或其他监听器。

• 补充英文及简体中文类型声明，并为所有编辑器语言加入 @grant GM_audio 提示。

• 新增 Content、Context 和 Service Worker 测试，覆盖正常行为、错误路径、连接恢复、连续故障、取消竞态、迟到连接和资源释放。

实现考虑

1. 回调风格与 Promise 风格共用同一套实现

GM_audio 和 GM.audio 共用底层消息及监听管理逻辑，避免两种调用风格出现行为差异。

无论脚本声明 @grant GM_audio 还是 @grant GM.audio，上下文都会注入完整的 GM_audio 和 GM.audio 方法集合。

回调风格遵循以下行为：

• setMute 成功时以 undefined 调用回调，失败时传入错误字符串；
• getState 成功时传入状态对象，失败时传入 undefined；
• addStateChangeListener 在后台确认注册后调用完成回调，失败时传入错误字符串；
• removeStateChangeListener 完成清理后调用回调。

Promise 风格则直接 resolve 对应结果或 reject 原始操作错误。

2. API 只作用于当前脚本所在标签页

Service Worker 从消息发送者中取得当前标签页 ID，所有操作均限定在该标签页：

• setMute 使用 chrome.tabs.update(tabId, { muted })；
• getState 使用 chrome.tabs.get(tabId)；
• 状态监听只接受相同 tabId 的 chrome.tabs.onUpdated 事件。

没有有效标签页的后台上下文不能使用 GM_audio，以避免误操作其他标签页。

setMute 仅接受布尔类型的 isMuted。无效参数会返回明确错误，而不是依赖浏览器 API 的隐式转换。

addStateChangeListener 仅接受函数类型的监听器，并要求通过长连接调用。

3. 状态字段与浏览器标签页状态对应

getState 返回以下可选字段：

• isMuted：标签页当前是否静音；
• muteReason：静音原因，可能为 user、capture 或 extension；
• isAudible：标签页当前是否正在产生可听音频。

状态变化监听使用与 Tampermonkey 接口相近的字段：

• muted：取消静音时为 false，静音时为对应的静音原因；
• audible：标签页的最新发声状态。

后台会过滤其他标签页以及不包含 mutedInfo 或 audible 的更新，避免向脚本发送无关事件。

如果标签页处于静音状态但浏览器没有提供具体原因，状态变化事件会使用 "extension" 作为回退值。

4. 多个监听器共享一个长连接

同一脚本上下文中的全部音频状态监听器保存在一个 Set 中，并共享一条与 Service Worker 的长连接。

后台完成 chrome.tabs.onUpdated 注册后发送 registered 消息。只有收到该消息后，addStateChangeListener 的 Promise 或完成回调才会结束，避免把“连接对象已创建”错误地视为“后台监听已经注册”。

移除监听器时：

1. 只删除对应的原始函数；
2. 仍有其他监听器时继续复用现有连接；
3. 最后一个监听器被移除时断开连接；
4. Service Worker 收到断开事件后移除对应的 chrome.tabs.onUpdated 监听器；
5. 脚本上下文失效时也会主动断开连接并清空状态。

重复添加同一个监听函数不会创建重复监听或额外连接；注册仍在进行时，重复添加会复用当前注册 Promise。

5. 处理 Service Worker 意外断线

Manifest V3 Service Worker 可能因闲置而被浏览器终止，因此已经成功注册的连接意外断开时，不能直接丢弃脚本监听器。

实现会区分两类断线：

• 本端主动断开，例如最后一个监听器被移除或脚本上下文失效：直接清理，不重新连接；
• 非本端断开且当前监听生命周期至少成功收到过一次 registered：保留监听器并自动重新连接。

已确认过的连接意外断开后，会立即开启新一轮注册。

恢复连接如果在收到 registered 前再次断开，或者恢复期间的 connect() 失败，则从 250 毫秒开始指数退避，并逐步增加到最多 8 秒，避免 Service Worker 持续不可用时发生忙等。

每次成功收到 registered 后，退避延迟都会重置。

6. 每轮恢复使用独立的注册 episode

一个已经成功注册的连接断开后，旧的 addStateChangeListener Promise 已经完成。

恢复过程需要创建新一轮注册 episode，使恢复期间新增的监听器可以等待当前连接真正重新注册，而不是错误复用一个已经 resolve 的旧 Promise。

同一轮恢复过程中，如果连接在收到 registered 前连续失败，重试会共享同一个 deferred Promise，并在闭包内通过定时器迭代。

这样可以避免长期故障时每次重试都递归创建新的 Promise 链，造成不可回收的状态堆积。

7. 防止异步连接竞态和资源泄漏

connect() 返回 Promise，在以下情况下可能产生迟到连接：

1. 添加监听器并开始建立连接；
2. 连接尚未完成时移除最后一个监听器；
3. 随即添加新的监听器并开始第二轮连接；
4. 第一轮连接之后才完成。

实现以当前 audioStateChange 状态对象作为生命周期边界。

监听器归零或上下文失效时会丢弃整个旧状态；迟到连接发现自己不再属于当前生命周期后，会立即主动断开，不会覆盖或泄漏到新的监听生命周期中。

监听器全部移除后，包含 everRegistered、retryDelay、当前连接和注册 Promise 在内的状态都会被整体丢弃。

之后重新添加监听器会创建全新的注册生命周期，而不会继承旧连接的恢复状态。

8. 允许取消尚未完成的注册

监听器可能在后台发送 registered 前被移除，包括：

• connect() 仍未返回；
• 连接已经建立，但后台尚未确认注册。

对于这种情况：

• GM.audio.addStateChangeListener 返回的待处理 Promise 会正常 resolve；
• GM_audio.addStateChangeListener 的完成回调会以 undefined 调用一次；
• 已建立的对应连接会被断开；
• 尚未完成的迟到连接会在返回后自行断开；
• 后续迟到的注册或断线结果不会再次结算 Promise 或重复调用回调。

状态对象会保存当前注册 episode 的 settlement 函数，使最后一个监听器移除时可以直接结束待处理注册，而不必依赖可能已被连接守卫忽略的 onDisconnect 回调。

9. 首次注册失败与恢复故障使用不同策略

首次注册期间发生以下情况时，会结束当前注册并清除监听状态：

• connect() 创建失败；
• 后台明确返回错误；
• 在从未成功收到 registered 的情况下连接断开。

只有当前监听生命周期至少成功注册过一次后，后续的连接失败或意外断线才会被视为暂时性故障并自动重试。

彻底放弃某一轮首次注册时，会先确定 Promise 的失败结果，再断开连接，避免同步触发的 onDisconnect 抢先使用其他错误原因结算同一 Promise。

10. 隔离用户脚本回调异常

脚本传入的完成回调或状态监听器可能自行抛出异常。

这些异常会被捕获并输出到控制台，但不会：

• 被误判为底层 API 操作失败；
• 导致同一完成回调再次以错误参数调用；
• 阻止其他状态监听器收到事件；
• 破坏连接和监听器的内部状态；
• 中止 Service Worker 断线后的恢复流程。

已知限制

1. 仅支持标签页脚本上下文

GM_audio 依赖消息发送者的标签页 ID，因此不能在没有对应标签页的后台上下文中使用。

本 PR 不提供指定任意标签页 ID 的能力，所有操作始终作用于当前用户脚本所在标签页。

2. 状态变化取决于浏览器事件

状态监听基于 chrome.tabs.onUpdated。

浏览器只会提供本次实际发生变化的字段，因此状态变化对象中的 muted 和 audible 都是可选的，脚本不应假设每次事件都会同时包含两个字段。

3. 首次注册失败不会无限自动重试

只有至少成功收到过一次 registered 后发生的非本端断线或连接失败，才会被视为暂时性故障并保留监听器恢复。

首次注册失败、后台明确返回错误或从未完成注册的连接断开时，会结束当前注册并清理监听状态。脚本需要再次调用 addStateChangeListener 才能重新注册。

4. 兼容目标

本实现以当前 Tampermonkey GM_audio 的 API 形状和主要行为作为兼容目标，同时结合 ScriptCat 的消息系统和 Manifest V3 生命周期实现连接管理。

不在类型声明或文档中承诺与某个特定 Tampermonkey 版本的所有边缘行为完全一致。

建议审查重点

• @grant GM_audio 与 @grant GM.audio 的注入范围和回调、Promise 行为是否符合项目现有约定；
• registered 确认、监听器共享和最后一个监听器移除时的清理顺序；
• Service Worker 意外断线后的自动恢复和指数退避逻辑；
• 恢复期间新增监听器是否会等待当前注册 episode，而不是复用过期 Promise；
• 生命周期状态对象能否完整覆盖异步 connect() 迟到以及移除后重新添加的竞态；
• 注册完成前取消时，Promise 和回调是否始终只结算一次；
• 首次注册失败和已成功注册后的恢复故障是否被正确区分；
• 后台是否正确过滤标签页及非音频状态更新；
• 用户脚本回调抛出异常时，是否与底层操作和其他监听器充分隔离；
• 新增公开类型、状态字段及错误字符串是否符合 Tampermonkey 兼容策略。

参考

https://developer.chrome.com/docs/extensions/reference/api/tabs#method-update

https://developer.chrome.com/docs/extensions/reference/api/tabs#method-get

https://developer.chrome.com/docs/extensions/reference/api/tabs#event-onUpdated

[cyfung1031]

按 PickInvariant 的 DELTA_AUDIT，对 base 3fc6ced2a16ca6abfbc7bfefaa66d1cc97343e34 → head fd6172b938460dd612b7891113a0806ab91fa45d 做了语义族审查（API 注入/类型、权限路由、连接注册与重连、取消/迟到连接、Service Worker 清理、回调隔离）。

结论：正常路径与声明基本一致，但仍有以下生命周期缺口：

• [P1，确认] 迟到或已关闭连接会让注册悬挂。 src/app/service/content/gm_api/gm_api.ts:755-787 在 a.connect().then(...) 内直接注册 onMessage/onDisconnect，而底层连接若在注册前已关闭，这些方法会抛错。该 fulfillment 链没有本地 catch，也不会结算 :708 创建的 registration episode；因此 add listener 的 Promise/回调可能永远不结束，恢复也可能停止。建议把 setup 异常纳入统一的失败/重试/清理路径。

• [P1，确认] Service Worker 向已关闭端口转发状态时未隔离发送异常。 src/app/service/service_worker/gm_api/gm_api.ts:1288 的 sendMessage 在底层端口已关闭、但断开回调尚未到达的窗口可能同步抛错；当前 connected 与 tabs.onUpdated 监听不会立即清理，事件处理器会出现未处理异常。建议按发送失败处理为断线并进入清理/重连路径。

• [P2，潜在] 上下文失效时未结算 pending registration。 src/app/service/content/create_context.ts:55 清除了音频状态并断开已有连接，但没有结算 gm_api.ts:742-757 中仍在等待的注册；迟到连接可能错误地报告成功，或该 Promise/回调悬挂。需要补充失效取消语义或证明该竞态不可能发生。

• **[P2，潜在/既有接缝被本 PR 使用] tab ID 为 0 时会被 packages/message/server.ts:51,101 的 || -1 折叠成后台上下文，随后 gm_api.ts:1248-1249 拒绝 GM_audio。建议保留合法的 0；目前未做真实浏览器运行时验证。

已检查：注入别名、类型声明、权限路由、正常共享连接/重连/移除和回调异常隔离。未验证：真实跨上下文桥接、关闭端口时序及 tab ID 0 的浏览器可达性；现有测试未覆盖上述 adverse races。

[cyfung1031]

已将 PR 分支同步到最新 main（88e73d8aeef2929e7fabf6f1552c8ea018dd1078），并在原 PR 分支上保留原有实现后追加以下修正 commits：

• 8c55e058：处理 Content/Context 侧 GM_audio 连接建立异常和上下文失效。连接关闭或异步连接迟到时不再让注册 Promise/回调悬挂；待处理注册会及时结算，并清理对应连接。
• 5b30f174：处理 Service Worker 转发状态时端口已关闭的异常，清理监听器并避免异常冒泡。
• f481446b：保留合法的 tabId: 0 / windowId: 0，避免被错误识别为后台上下文。

验证结果：

• 相关回归测试：6 个 test files，107 tests passed。
• pnpm run typecheck passed；每个 correction commit 的 pre-commit checks 也通过。
• 全量 Vitest 为 3747/3750 tests passed；3 个无关 UI 测试在全量并行运行时触发 850ms timeout，随后分别单独重跑均通过。
• 尚未进行真实 Chrome extension runtime 验证；该部分仍应由 CI/人工环境确认。

当前已发布 PR head：f481446b55e3dbe0729fc581c487a9194b4d759c。