企业官网建设流程全解析

WorkBuddy Switch 是什么？为什么需要会话悬浮窗

WorkBuddy Switch 是一款面向 WorkBuddy、CodeBuddy 的开源账号切换工具，支持积分到期监控、积分统计与 Token 统计。而它的桌面版还内置了一个非常实用的功能——Agent Companion 会话悬浮窗：把 Codex、WorkBuddy、CodeBuddy、Codeg 等多个 AI Agent 的任务状态集中到桌面的一条悬浮栏里，一眼就能看出谁还在运行、谁在等你确认、谁已经跑完。

如果你同时开着多个 Agent 干活、频繁在不同项目间切换，就不必再反复切窗口盯进度——这是本文要带你完整走一遍的集成与使用指南。

Agent Companion 悬浮窗能做什么

Agent Companion 是一条常驻桌面的悬浮栏（rail），每个正在被监听的任务会显示为一个"小伙伴"头像，配合状态提示卡工作：

上面截图中，右上角的悬浮栏集中展示了多个 Agent 会话状态：已完成的 Codex 会话弹出信息卡并带有绿色对勾，运行失败的 WorkBuddy 会话则显示红色叉号。

三步开启 WorkBuddy Switch 会话悬浮窗

1. 安装桌面版：悬浮窗是桌面版专属功能，网页版（WebUI）不提供服务悬浮窗。
2. 找到开关：两种入口任选其一——
   • 主界面左下角的悬浮窗图标；
   • 设置 → Agent Companion卡片，打开开关即可。
3. 完成接入：首次使用点击「悬浮窗设置」，在其中选择要监听的 Agent 来源（依赖对应客户端的 Hooks / Webhook），并调整外观风格、显示数量与动画。

⚠️ 注意：仅打开监听开关并不代表接入成功，还需确保对应客户端的 Hook / Webhook 已正确安装，并发起新任务让悬浮栏收到事件。

开启状态的读取与切换由前端状态 Hook use-companion-enabled.ts 与设置页 SettingsPage.tsx 驱动，界面即时响应托盘菜单的变化。

核心功能详解：状态总览、提醒与一键回跳

🔍 状态总览：悬浮栏按会话来源显示三种状态——运行中、待确认、已完成，并标识会话来自哪个 Agent。透明区域可点击穿透，不会挡住你操作桌面上的其他窗口。

🔔 提问与完成提醒：Agent 需要你确认时会弹出提示卡（可关闭本轮提示）；任务完成时自动弹出卡片并在头像上打标记，错过窗口也不怕漏掉结果。

↩️ 一键回到原会话：有可用跳转链接时，点击头像或卡片直接回到原会话。各来源的跳转行为如下表：

🖱️ 悬浮交互：悬浮栏可拖动到桌面任意位置；右键任意任务头像可关闭该任务的本次监听；托盘菜单可随时显示 / 隐藏整条悬浮栏。

📦 WorkBuddy 沙箱审批特写：WorkBuddy 的沙箱类审批不发送 Hook 事件，悬浮窗会通过其运行日志识别，在弹框后十几秒到半分钟内显示"待确认"状态，延迟主要来自 WorkBuddy 自身的日志落盘缓冲。

支持范围与已知限制

• CodeBuddy 接入面向CodeBuddy IDE 与 VS Code 插件，不包含独立 CodeBuddy CLI；JetBrains 插件不在监听范围内。
• 悬浮栏根据新事件更新状态，不会导入全部历史会话；重启后只恢复此前已跟踪的任务状态。
• Codex 监听保持轻量：状态只由 Hook 更新，不读取任务数据库或会话文件；权限检查期间会先显示"权限检查中"。

源码结构：WorkBuddy Switch 如何集成 Agent Companion

桌面版通过一份版本锁定的源码快照集成 Agent Companion，整个构建过程是离线、确定性的：

构建时tauri build会把组件前端产物复制到companion/目录，并捆绑目标平台的原生运行时（agent-studio-runtime）作为外部二进制；快照更新由脚本 scripts/vendor-agent-companion.mjs 完成，通过git archive保证只把已提交的内容打进快照。安装后的应用只有 wb-switch 一个托盘，组件不会额外创建托盘或登录项，也不会在运行时下载可执行代码。

更多技术细节可查阅 docs/agent-companion-integration.md。

常见问题

Q：网页版为什么看不到悬浮窗入口？悬浮窗是桌面版专属能力，WebUI 界面与桌面版一致但不包含该卡片。

Q：开了开关却没有会话显示？依次检查：对应 Agent 客户端是否在运行、该来源监听是否开启、Hooks / Webhook 是否安装成功，最后发起一次新任务触发事件。

Q：如何临时把悬浮栏藏起来？使用托盘菜单即可显示 / 隐藏，不会关闭监听。

总结

WorkBuddy Switch 桌面版把 Agent Companion 集成得非常克制：同一个托盘管理、离线锁定的组件快照、透明的宿主边界。开启悬浮窗后，多 Agent 并行工作就从"反复切窗口查进度"变成"瞥一眼桌面"——状态总览、确认提醒、一键回跳三件事，悬浮栏全帮你盯住了。