Ubuntu 的系统声音：ALSA 既没有回录标志，也不枚举 PulseAudio/PipeWire 的 monitor 源 —— monitor 正是「录下这个输出在放什么」的设备，pavucontrol 里能选到的就是它。所以 Linux 的系统声音 不走 cpal，而是直接跟声音服务器说话（src-tauri/src/pulse.rs）：

• pactl list sources 列出全部源，带 Monitor of Sink 的就是 monitor，直接进设备下拉框
• parec 录其中一个，raw PCM 走 stdout。直接问它要 s16le / 单声道 / 当前接口要的采样率（16k 或 24k），降混和重采样由声音 服务器做完，样本到手就是上行要的形状，跳过我们自己那套管线

这俩工具说的是 PulseAudio 协议，PipeWire 也提供（pipewire-pulse），一条路覆盖两个声音服务器。 它们来自 pulseaudio-utils，已写进 .deb 的 depends。

只有在没有声音服务器应答时（无桌面环境的机器）才回到老办法：设备列表里不给系统声音， 界面提示你自己在 pavucontrol →「录制」标签把 ReaLingo 的来源改成输出设备的 Monitor。

朗读时为什么不会录回去：朗读在 Rust 里用 cpal 播放（src-tauri/src/player.rs），不交给 webview。 排除是按进程算的，而 webview 的声音来自另一个 WebView2 / WebKit 进程。

• Windows（src-tauri/src/wasapi.rs）：process loopback 的 EXCLUDE_TARGET_PROCESS_TREE 模式， 录「默认输出设备上除了本进程树以外的所有声音」。它只能录默认设备，而朗读也放在默认设备上， 所以只有选中的就是默认设备时才走这条路；选了别的设备本来就录不到朗读，仍走普通 loopback
• macOS（src-tauri/src/tap.rs）：系统声音一律走自建的 tap，包成私有聚合设备交给 cpal 当普通输入读； 朗读时把本进程列进排除名单。本进程要先在 Core Audio 里出现才查得到，所以先开播放再开采集。 不用 cpal 0.17 自带的 tap：它建聚合设备时关了 tap 自动启动，只录到静音；设备 UID 是写死的， 又不销毁，第二次开始就报 Illegal operation。新建的聚合设备要过一小会儿才报得出输入配置， 所以建好后会等它就绪再交给 cpal

macOS 签名：没有 Apple 开发者证书，.app 用 ad-hoc 签名（signingIdentity: "-"）。 不签的话只有可执行文件带着链接器加的签名，Info.plist 和资源没被封进去，系统记不住授过的权限， 麦克风会一直重复申请。hardened runtime 关掉：它只对公证有意义，开着还得另配录音的 entitlement。 下载后首次打开会被 Gatekeeper 拦住，执行 xattr -dr com.apple.quarantine /Applications/ReaLingo.app， 或在「系统设置 → 隐私与安全性」里点「仍要打开」。

macOS 权限：麦克风和系统声音是两个独立的 TCC 权限，分别对应 src-tauri/Info.plist 里的 NSMicrophoneUsageDescription 和 NSAudioCaptureUsageDescription。后者缺失时 macOS 不会报错，只会一直给全静音的音频缓冲区；而且权限弹窗只对已签名的二进制出现。

Linux 托盘：AppIndicator 不支持左键单击事件，所以左键唤回主窗在 Ubuntu 上不生效， 用右键菜单里的「显示主窗口」。

各平台构建依赖：

# Ubuntu
sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf \
                 libasound2-dev libssl-dev build-essential curl wget file

# macOS
xcode-select --install

# Windows：Visual Studio Build Tools（C++ 桌面开发）+ WebView2（Win11 自带）

调试运行中的界面（tools/cdp.mjs）—— WebView2 里看不到 DevTools 时很有用， 可以直接在真实应用的页面里求值，而不是靠猜：

# 带远程调试端口启动
WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222 npm run tauri dev
# 另开一个终端
node tools/cdp.mjs --list                 # 列出可调试页面
node tools/cdp.mjs probe.js               # 在主窗口求值
node tools/cdp.mjs probe.js subtitle      # 在字幕窗求值

macOS 和 Ubuntu 的安装包没法在 Windows 上交叉编译，由 .github/workflows/build.yml （build & release）在 GitHub Actions 上出三份：

发布流程是「先建草稿 → 各平台分别上传 → 三个平台全部成功后才转正式发布」， 所以任一平台挂掉时 release 会停在草稿状态，不会放出半套包。tag 与 src-tauri/Cargo.toml 里的 version 不一致会直接失败，避免发出版本号对不上的包。

版本号只有一处：src-tauri/Cargo.toml 的 [package] version。tauri.conf.json 不写 version 字段，Tauri 会回落到 Cargo.toml；package.json 是 private 的，也不带版本号。 CI 就按这一处校验 tag。

发布说明写在 .github/release-notes/v<版本号>.md，随 tag 一起提交；CI 建 release 时把它放在最前面， 后面接 GitHub 自动生成的提交列表。没有这个文件就只有自动生成的部分。

# 改完 src-tauri/Cargo.toml 里的 version，写好 .github/release-notes/v0.2.1.md
git tag v0.2.1 && git push origin v0.2.1

macOS 不再单独跑 Intel job —— macos-13 runner 已于 2025-12 退役，x86_64 的 job 只会一直排队； 改为在 Apple Silicon 上交叉编译出 universal 二进制，一个 DMG 通吃。

Linux 只出 .deb：它在 tauri.conf.json 里声明了 libwebkit2gtk-4.1-0 与 libayatana-appindicator3-1，装的时候 apt 会自己把依赖拉下来 ——

sudo apt install ./ReaLingo_0.2.1_amd64.deb   # 用 apt 而不是 dpkg -i，才会解析依赖

不出 AppImage 是因为它存在的意义就是自带一份 WebKitGTK 去伺候没有该库的发行版， 而我们的目标是 Ubuntu 22.04+（libwebkit2gtk-4.1-0 从 22.04 起就在源里）， 那 90 MB 纯属白背。要覆盖 Fedora/Arch 的话，workflow 里 --bundles deb 后面 补 ,rpm 或 ,appimage 即可。

打包：

npm run tauri build

测试（重采样、地址拼接、各接口的消息格式与字幕切分）：

cd src-tauri && cargo test

图标：源文件是 brand/ReaLingo.png（完整 logo，带文字）。应用图标只取上半部分的图形标 —— 「ReaLingo」那行字在 32×32 任务栏尺寸下会糊成一团，所以裁掉，并把图形放到白色圆角底板上 （直接抠白底会在抗锯齿边缘留白边）。logo 换了就重跑：

node tools/make-icon.mjs brand/ReaLingo.png app-icon.png 1024
npx tauri icon app-icon.png

应用内标题栏的 logo 不走这条路：白底板是给 OS 图标网格用的，放进界面里就是块贴在标题栏上的 白卡片，深色主题下尤其突兀。它由 make-banner.mjs 的 --mark 模式出，只取图形、透明底：

node tools/make-banner.mjs brand/ReaLingo.png src/assets/mark.png 256 --mark

README 顶部的横版 logo 由 make-banner.mjs 把上下堆叠的原 logo 重排成「图形在左、彩色字在右」， 并按连通性（从边缘 flood fill）抠掉白底 —— 不能按颜色抠，否则气泡里白色的 A 和 文 会一起没掉， 在深色主题下变成黑窟窿。make-anim.mjs 再给它加一道循环掠过的高光：

node tools/make-banner.mjs brand/ReaLingo.png brand/banner.png 160
node tools/make-anim.mjs brand/banner.png brand/banner-animated.png

抠白底对两半用了不同规则，因为没有单一规则能同时做对：图形里气泡中的白色 A / 文 是内容， 按连通性（从边缘 flood fill）保留；而文字里 R、e、a、o 的内腔是背景，只是恰好被笔画围住， 连通性会把它们留成白块，所以那一半按颜色全抠。两边都按白底解算出渐变 alpha 而不是非黑即白 —— 二值遮罩会让抗锯齿的那圈薄边保持不透明的近白色，在深色主题下就是一圈光晕。

README 默认用静态版（117 KB）。动图版 brand/banner-animated.png（478 KB）也在仓库里， 把头部的 banner.png 换成 banner-animated.png 即可启用。用 APNG 而不是 GIF： GIF 只有 256 色，渐变字会断层，且 1-bit 透明会在深色底上留白边；APNG 全彩 + 完整 alpha， 后缀仍是 .png，不支持动画的地方退化成第一帧（即静态 logo）。

麦克风 ──┐
系统声音 ─┤→ 降混单声道 → 窗化 sinc 重采样 16/24kHz → i16 → 100ms 分块 ─┐
音频文件 ─┘   (cpal / symphonia)                                        │
                                                                        ▼
              前端 ←── rt://event ── 事件解析 ←── WebSocket ←── base64 + 各接口的音频帧
             (Vue)                   (realtime.rs)

• WebSocket 放在 Rust 侧：百炼和 OpenAI 的实时接口用 Authorization 请求头鉴权，浏览器 WebSocket 构造函数无法设置请求头。附带好处是 API Key 不进 webview。
• 各接口的差异集中在 src-tauri/src/config.rs：上行采样率（OpenAI 24kHz，其余 16kHz）、 音频帧与结束帧的格式、会话配置、怎样算结束。Gemini 的 Key 走 URL 参数而不是请求头， 且只在连接时拼上，不出现在设置页的地址预览里。
• 字幕配对：Qwen 按服务端的轮次 id 配对原文和译文；OpenAI 和 Gemini 只给两条增量文字流， 按句末标点切出轮次，原文在自己最后一个句末处切开，余下的带进下一行。
• Gemini 的收尾：它不发结束信号，停止后还会一直推静音帧，所以停止时先补约 3 秒静音 （不然最后半句出不来），之后连续 4 秒没有新文字、也没有非静音音频就结束会话。
• 系统声音：三个平台都是「对输出设备建 input stream」这一个调用，后端各自处理 —— Windows 加 AUDCLNT_STREAMFLAGS_LOOPBACK，macOS 建 Core Audio process tap， Linux 没有对应机制（细节见 src-tauri/src/audio.rs 的模块注释）。
• 重采样：直接窗化 sinc，截止频率取两端奈奎斯特的较小者，任意比率都抗混叠 （48000/16000 = 3，44100/16000 = 2.75625）。

直觉做法是监听转写事件里的 language，发现说的是目标语言就补发一条 session.update 把 translation.language 换到另一边。实测不行 —— 用 examples/probe.rs 打真实端点：

-> {"type":"session.update","session":{...,"translation":{"language":"en"},...}}
← {"type":"error","error":{"code":"invalid_value",
   "message":"Session update error: session already started or finished or failed."}}
← close  (服务端直接断开连接)

translation.language 是会话级不可变配置；错误里的 "started" 指会话已开始送音频， 不是当前 turn，所以「等这句 done 了再改」同样会被拒。而且它不只是报错，是会把正在跑的 会话打断。

可行方案是双通道：同一份音频扇出喂两条并行会话（A→B 和 B→A），按 ASR 报的语种采纳 其中一条的输出。代价是输入音频 token 翻倍（7 → 14 token/秒），输出也是双份。 设计细节记在项目计划里，等确有对话式互译需求时再做。