摘要：VibeStick 最初围绕 Mac Bridge 与 HUD 构建，后来增加 Windows Codex、语音输入、诊断、托盘和安装器。本文按源码复盘跨平台移植中的进程、路径、网络、粘贴、打包与本地 ASR 问题。

跨平台移植从来不是“复制文件”，而是重写一整套操作系统接触面。读完本文，你将带走三条核心原则：

1. 先盘点平台耦合点，再动手改代码——进程识别、数据目录、粘贴注入、网络诊断，每一处都可能藏着平台专属的坑；
2. 把状态与配置交给用户目录，而不是安装目录——避开管理员权限，也避免升级时覆盖用户的 Token 与密钥；
3. 网络可达性必须有一键诊断——监听 0.0.0.0 只是开始，Windows 防火墙与网络类别才是真正的关卡。
   VibeStick 的 Bridge 核心确实是 Python，HTTP 与状态模型也能复用。但从 macOS 跑到 Windows，真正需要移植的是一整套操作系统接触面。

一、先列出平台耦合点

源码中的主要差异可以归为六类：

能力	macOS	Windows
Agent 进程识别	ps -axo command=	PowerShell/CIM 进程查询
数据目录	~/Library/Application Support/VibeStick	%LOCALAPPDATA%\VibeStick
粘贴	pbcopy、pbpaste、AppleScript	PowerShell Clipboard、SendKeys
HUD/后台	Swift HUD、LaunchAgent	PowerShell 托盘、启动项
网络诊断	本机地址与端口	再加网络类别、防火墙规则
发布	脚本安装	PyInstaller EXE + Inno Setup

把这些边界先找全，比看到第一个 platform.system() 就开始复制文件靠谱得多。

二、Codex 在线检测：VS Code 插件不按剧本出牌

macOS 可通过 ps 命令行识别 Codex 进程；Windows 场景中则可能出现 codex.exe、codex-app-server.exe 等进程。更麻烦的是，VS Code 插件形态与 CLI 不完全一致。

当前观察器增加 _windows_codex_process_running()，同时保留“最近四分钟有会话事件即视为在线”的兜底。这样即便进程名再次换马甲，只要本地 session 仍在持续写入，屏幕不会轻易把正在工作的 Agent 判成失业。

这也说明跨平台检测应组合多个弱信号，而不是把一个进程名当圣旨。

三、配置路径：别把 .env 放在安装目录里

Windows 运行入口 windows_runtime.py 将每用户配置放到：

%LOCALAPPDATA%\VibeStick\bridge.env

首次运行会生成 URL-safe 随机 Token，并写入默认配置；如果 Token 为空或仍是占位值，会自动替换。状态、录音和日志也落到用户可写目录，而不是 Program Files。

这既避开管理员权限问题，也保证升级安装不会顺手覆盖用户的 ASR Key 和配对 Token。安装目录负责程序，用户目录负责状态，这是 Windows 产品化里最不花哨、也最值得坚持的一条规矩。

四、粘贴注入：剪贴板恢复很重要

PasteInjector 根据平台选择实现。Windows 版通过 PowerShell STA 加载 System.Windows.Forms，先保存旧剪贴板，写入转写文本，发送 Ctrl+V，可选再发送 Enter，最后恢复原剪贴板。
恢复动作避免一次语音输入永久占领用户剪贴板。不过当前两端仍依赖“焦点窗口就是目标窗口”这一假设。如果用户在转写期间切到密码框，系统也可能非常听话地把需求贴过去。未来应增加前台进程白名单、粘贴预览或 VS Code 扩展 IPC，而不是继续对焦点窗口抱有浪漫信任。

五、网络：0.0.0.0 只是第一关

设备访问电脑上的 Bridge，服务必须监听 LAN 地址；但 Windows 还区分 Public、Private、Domain 网络，并由防火墙决定 TCP 8765 和 UDP 8766 是否可达。

diagnostics.py 会检查：

• 当前平台、Python 版本与监听地址；
• LAN IPv4 地址和 Token；
• Codex 状态与 ASR 配置；
• Windows 网络类别；
• TCP 8765 入站规则；
• UDP 8766 自动发现规则。

Inno Setup 脚本只为 Private profile 创建两条规则，卸载时删除规则。这个限制很重要：为了让一块小屏联网，不必顺手把公共咖啡馆网络也开放成技术交流会。

六、从 Python 项目到独立 EXE

当前仓库使用 VibeStickBridge.spec 构建 PyInstaller 单文件 EXE，入口是 packaging/windows/bridge_entry.py。随后由 Inno Setup 生成安装包，完成：

• 安装 VibeStickBridge.exe 与托盘脚本；
• 可选创建登录启动项；
• 可选添加 Private 网络防火墙规则；
• 添加开始菜单入口与本机管理页；
• 卸载时停止进程并清理防火墙规则；
• 附带 Python、qrcode、jsQR 等第三方许可证。

这样目标机不需要预装 Python。源码中的 requirements-build.txt 与 PowerShell 构建脚本则把构建环境固定下来。

不过“生成了 Setup.exe”不等于“已经可以放心群发”。正式发布还需要代码签名、SmartScreen 验证、杀毒软件误报测试，以及干净 Windows 虚拟机上的安装、升级、开机启动和卸载矩阵。

七、本地 ASR：功能移植成功，体积可能当场反击

Windows 可以通过 VIBE_STICK_TRANSCRIBE_CMD 接入 scripts/transcribe_faster_whisper.py，也可以继续使用云端 OpenAI-compatible ASR。仓库还提供本地 ASR 文档和独立虚拟环境方案。

为什么主安装包没有直接塞进 faster-whisper、CTranslate2 和模型？因为它们可能让安装包从“小工具”膨胀为“顺便附赠几 GB”。合理策略是：主包保持轻量，离线 ASR 作为可选组件，明确显示模型下载大小、进度、compute type 和存储位置。

八、这次移植留下的通用经验

1. 平台差异应该收敛在路径、进程、输入注入和生命周期模块，核心状态协议保持不变；
2. 网络可达性必须有一键诊断，不能让用户靠串口日志猜防火墙；
3. 安装、升级、卸载和隐私数据保留是功能的一部分，不是发版当天的包装纸；
4. 本地 AI 能力要计算模型体积、冷启动和硬件兼容，不能只看开发机跑通截图；
5. 自动化脚本解决开发者问题，安装器才开始解决普通用户问题。

下一篇将把视线从“移植完成”移到“产品毕业”：OTA、安全配对、设备抽象、多 Agent、多设备与可观测性，哪些应该先做，哪些适合晚一点再热闹。

---

本文基于当前仓库中的 Windows 实现与打包骨架。正式分发前仍应完成代码签名和干净系统测试。