摘要VibeStick 最初围绕 Mac Bridge 与 HUD 构建后来增加 Windows Codex、语音输入、诊断、托盘和安装器。本文按源码复盘跨平台移植中的进程、路径、网络、粘贴、打包与本地 ASR 问题。跨平台移植从来不是“复制文件”而是重写一整套操作系统接触面。读完本文你将带走三条核心原则先盘点平台耦合点再动手改代码——进程识别、数据目录、粘贴注入、网络诊断每一处都可能藏着平台专属的坑把状态与配置交给用户目录而不是安装目录——避开管理员权限也避免升级时覆盖用户的 Token 与密钥网络可达性必须有一键诊断——监听0.0.0.0只是开始Windows 防火墙与网络类别才是真正的关卡。VibeStick 的 Bridge 核心确实是 PythonHTTP 与状态模型也能复用。但从 macOS 跑到 Windows真正需要移植的是一整套操作系统接触面。一、先列出平台耦合点源码中的主要差异可以归为六类能力macOSWindowsAgent 进程识别ps -axo commandPowerShell/CIM 进程查询数据目录~/Library/Application Support/VibeStick%LOCALAPPDATA%\VibeStick粘贴pbcopy、pbpaste、AppleScriptPowerShell Clipboard、SendKeysHUD/后台Swift HUD、LaunchAgentPowerShell 托盘、启动项网络诊断本机地址与端口再加网络类别、防火墙规则发布脚本安装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先保存旧剪贴板写入转写文本发送CtrlV可选再发送Enter最后恢复原剪贴板。恢复动作避免一次语音输入永久占领用户剪贴板。不过当前两端仍依赖“焦点窗口就是目标窗口”这一假设。如果用户在转写期间切到密码框系统也可能非常听话地把需求贴过去。未来应增加前台进程白名单、粘贴预览或 VS Code 扩展 IPC而不是继续对焦点窗口抱有浪漫信任。五、网络0.0.0.0只是第一关设备访问电脑上的 Bridge服务必须监听 LAN 地址但 Windows 还区分 Public、Private、Domain 网络并由防火墙决定 TCP8765和 UDP8766是否可达。diagnostics.py会检查当前平台、Python 版本与监听地址LAN IPv4 地址和 TokenCodex 状态与 ASR 配置Windows 网络类别TCP8765入站规则UDP8766自动发现规则。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 和存储位置。八、这次移植留下的通用经验平台差异应该收敛在路径、进程、输入注入和生命周期模块核心状态协议保持不变网络可达性必须有一键诊断不能让用户靠串口日志猜防火墙安装、升级、卸载和隐私数据保留是功能的一部分不是发版当天的包装纸本地 AI 能力要计算模型体积、冷启动和硬件兼容不能只看开发机跑通截图自动化脚本解决开发者问题安装器才开始解决普通用户问题。下一篇将把视线从“移植完成”移到“产品毕业”OTA、安全配对、设备抽象、多 Agent、多设备与可观测性哪些应该先做哪些适合晚一点再热闹。本文基于当前仓库中的 Windows 实现与打包骨架。正式分发前仍应完成代码签名和干净系统测试。