摘要：VibeStick 最初围绕 Mac Bridge 与 HUD 构建，后来增加 Windows Codex、语音输入、诊断、托盘和安装器。本文按源码复盘跨平台移植中的进程、路径、网络、粘贴、打包与本地 ASR 问题。
跨平台移植从来不是“复制文件”，而是重写一整套操作系统接触面。读完本文，你将带走三条核心原则：
VibeStick 的 Bridge 核心确实是 Python，HTTP 与状态模型也能复用。但从 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 和存储位置。
八、这次移植留下的通用经验
下一篇将把视线从“移植完成”移到“产品毕业”：OTA、安全配对、设备抽象、多 Agent、多设备与可观测性，哪些应该先做，哪些适合晚一点再热闹。
本文基于当前仓库中的 Windows 实现与打包骨架。正式分发前仍应完成代码签名和干净系统测试。
