第19章 Omnigent 桌面应用：原生通知、多窗口与嵌入式浏览器
桌面应用 Omnigent 桌面应用将完整的 Web UI 封装在原生窗口中，并提供浏览器无法实现的操作系统级功能：当 Agent 需要关注时推送通知、在 Dock 图标上显示待处理会话数，以及支持多个独立窗口。 [下载 Apple 芯片版] [下载 Intel 版]
为什么选择桌面应用而非浏览器？
操作系统通知。当 Agent 完成任务、请求输入或 runner 断开连接时，你会收到通知。通知会展示 Agent 消息的前几行内容，且仅在你未主动查看对应会话时触发。 Dock 徽标。无需切换至应用，即可一目了然地看到有多少会话需要你关注。 多窗口管理。按 Cmd+N 打开额外窗口，并排查看多个会话或服务器。 最近会话切换器。按住 Ctrl 并点击 Tab 键，可快速在五个最近会话间切换——详见“键盘快捷键”。 一键重新连接 Host。若会话所在 Host 为当前机器且已离线，应用会自动重启该 Host，无需在终端中手动执行命令。
其他功能（会话、文件编辑器、行内评论、协作）与 Web UI 完全一致。
嵌入式浏览器 桌面应用内置了嵌入式浏览器面板，Agent 可直接驱动该面板。 以下五个由框架托管的工具对所有 Agent 始终可用——你无需在 Agent YAML 中声明它们：
[工具] [功能] browser_navigate | 打开或导航至 URL，若面板未展开则自动打开 browser_snapshot | 捕获可访问性树快照：包括 snapshot_id、当前 URL 和标题、以及以 YAML 格式呈现的交互元素树，每个元素均标记有 [ref=N] ID browser_click | 通过 ref（首选）或 CSS 选择器点击元素。请将 snapshot_id 与 ref 一同传入，以便拒绝过期快照并返回精确错误 browser_type | 聚焦输入框并输入文本，通过 ref 或选择器标识 browser_screenshot | 捕获面板的 PNG 截图以用于视觉检查。选择待操作元素时，建议优先使用 browser_snapshot——截图不包含 refs
相对于针对生成类名和 Shadow DOM 的 CSS 选择器，快照中的 refs 稳定性更高。因此常规流程为：browser_navigate，随后通过 browser_snapshot 查看页面内容，最后使用返回的 refs 执行 browser_click / browser_type。 由于浏览器运行在桌面窗口内，这些工具要求 Omnigent 桌面应用已启动且会话处于打开状态。若没有桌面窗口订阅，操作将明确失败并报错“browser action timed out — is the session open in the Omnigent desktop app?”，而非无响应挂起。
本地网络权限 嵌入式面板中的网站可申请本地网络访问权限——例如访问本地环回辅助工具（如 Okta Verify）的登录页面。此时，浏览器工具栏下方会弹出一个紧凑的 Chrome 风格气泡，询问针对该请求源是否“允许本地网络访问？”，并提供三个选项：
仅此次允许 — 授予该面板当前访问的权限。重载和同源导航不会使权限失效，但离开该网站或关闭面板后权限将过期。 始终允许 — 记住该精确源在所有会话和应用重启中的决定。 拒绝 — 在所有会话浏览器和应用重启中阻止该源的权限请求。
关闭气泡、按 Esc 或点击外部区域将关闭请求而不保存决定；网站在下一次导航前不会被再次询问。仅可见且活动的面板可发起新请求，但在网站后台运行时，现有的“仅此次允许”或“始终允许”授权保持有效。HTTPS 站点和 HTTP 环回页面可请求权限；嵌入式子框架无法独立请求。 某些登录流程会在请求权限前进行检查。由于 Electron 仅能以“允许”或“拒绝”回答此类检查——永远无法回答“询问”——气泡将显示“允许将重新加载此页面”，无论点击哪个允许按钮，页面都会重新加载以便网站使用新决定重试。若后台页面的登录流程已放弃，请将其面板切换至前台并重新加载。 保存的选择项存储在桌面应用的 settings.json 文件中的 browser_local_network_permissions 键下，格式为 origin → true/false 的映射。若要重置已保存的选择项，请退出应用，删除该 origin 的条目，然后重新打开。 这些选择项不会改变面板按会话隔离的 cookie 和存储策略，摄像头、麦克风、通知及其他所有浏览器权限仍处于拒绝状态。 这控制的是 Chromium 对本地网络权限询问的回答——它并非网络防火墙。并非所有 Electron 版本的每次本地网络获取都受此权限限制，且批准后也不绕过 CORS、TLS 证书验证或 Agent 的导航策略。若本地辅助工具通过自身的 CORS 策略拒绝该网站，需自行配置该辅助工具以允许访问；面板不会重写这些头部信息。
键盘快捷键 桌面应用支持所有 Web UI 快捷键，并新增两个独有快捷键。这两个快捷键仅在运行桌面应用时显示于应用内快捷键覆盖层（⌘/ 或 Ctrl+/）。
切换最近会话 按住 Control 并点击 Tab（macOS 上为 ⌃Tab，Windows/Linux 上为 Ctrl+Tab——此组合键在所有平台均使用 Control，而非 ⌘），打开列有五个最近会话的切换器，按最后活动时间排序，并显示每个会话的 Agent 名称。在按住 Control 期间：
再次点击 Tab 在列表中向下移动，或 Shift+Tab 向上移动（选择项循环）； 松开 Control 切换至高亮显示的会话； 按 Esc 取消并保持在当前会话。
高亮起始位置为你当前查看会话之后的那个，因此快速 Ctrl+Tab 并松开可跳回上一次使用的会话。已归档的会话不在列表中。即使嵌入式 Browser 页面具有键盘焦点，该手势也有效——应用会将其转发给切换器，而非让页面处理。
打开新的浏览器标签页 按 ⌘⌥B（Windows/Linux 上为 Ctrl+Alt+B）在 Workspace 侧边栏中打开一个新的 Browser 软标签页——这与侧边栏菜单中“+ → Browser”的操作相同，菜单中“Browser”选项旁显示相应按键。若侧边栏被折叠或被 Terminal 面板遮挡，新标签页将被选中并显示。在代码编辑器或终端中输入时，该快捷键失效；且仅在嵌入式浏览器可用处绑定。 Cmd+N 仍然用于打开新窗口；开始新会话的快捷键为 ⌘⌥N（Ctrl+Alt+N），与 Web UI 一致。
先决条件
运行中的服务器。服务器用于存储你的会话并提供桌面应用连接的 UI；请通过 omni server start 在本地运行，或将应用指向已部署的 URL。 至少一个 runner。Runner 是实际执行 Agent 的进程。若已配置云端沙箱 host，即可从应用中启动；否则，通过 CLI 运行 omni host 注册你的机器。
安装
[平台] [格式] [状态] macOS | .dmg | [下载 Apple 芯片版] · [下载 Intel 版] Linux | .AppImage 或 .deb | [下载 .deb] · [下载 .AppImage] Windows | 安装程序 (.exe) | [下载]
快速上手
启动应用。首次启动时，你将看到设置界面。 输入服务器 URL。本地运行使用 http://localhost:6767，或输入已部署的服务器 URL（如 https://your-app.onrender.com）。 开始工作。应用连接成功后，将显示与浏览器中相同的 UI。
应用会记住服务器 URL 以供后续启动使用。如需更改，请前往“Server > Change Server”。
处理多个服务器 每个窗口连接一个服务器。若要同时处理多个服务器：
前往“Server > New Window on Different Server” 输入第二个服务器的 URL
通知和徽标计数将合并所有已连接服务器。
托管服务器 (macOS MDM) 在 macOS 上，管理员可通过 MDM Managed Preferences 发布服务器 URL 列表，让用户选择组织的服务器而非手动输入。该偏好域为桌面应用的 bundle identifier：ai.omnigent.desktop 将 serverUrls 键设置为服务器 URL 数组，按优先顺序排列：
[键] [类型] [是否必填] [默认值] [描述] serverUrls | 字符串数组 | 否 | [] | 提供的服务器 URL，按优先顺序排列。每个必须使用 https://。最多 10 个。
无 scheme 的主机名被接受并解释为 https://。路径保留，因此管理员可直接指向工作区挂载点，如 https://my-workspace.cloud.databricks.com/ml/omnigents。共享 origin 的条目将合并，保留第一个。若任一项类型无效、不安全或格式错误——或列表超过 10 项——整个列表将被拒绝。 托管服务器仅在 macOS 上只读；其他平台忽略该偏好设置。
显示名称 若需为服务器添加显示名称，请在其 serverUrls 条目中添加 omnigentServerName 查询参数。Omnigent 在连接前移除该参数，因此它不会到达服务器： https://my-workspace.cloud.databricks.com/?o=123&omnigentServerName=Engineering 将空格编码为 %20，在 plist 内将 & 写为 &。未命名服务器显示其主机名。首个托管服务器的名称作为连接界面“Join your team”按钮的标签；名称也用于组织下拉菜单和应用内服务器切换器中标识组织服务器。
显示方式 托管服务器显示在连接界面和应用内服务器切换器的“Provided by your organization”下。它们是建议而非强制：
Omnigent 永不自动连接。 用户仍可输入其他服务器 URL。 托管工作区路径按配置加载，不会简化为其 origin。 数值从 macOS 按需读取，而非复制到应用设置中，因此应用或移除配置文件后，将在下次加载连接界面或打开服务器切换器时生效。
MDM 配置示例
使用标准的 com.apple.ManagedClient.preferences 负载，指定 ai.omnigent.desktop 应用偏好域（大多数 MDM 产品将其作为自定义设置或托管偏好负载公开）：
通过链接打开会话 桌面应用注册了 omnigent:// URL scheme，因此链接可像 Web 链接打开页面一样，在特定服务器上打开特定会话。链接通过主机名标识服务器，通过 conversation id 标识会话： omnigent://localhost:6767/c/conv_abc omnigent://my-workspace.cloud.databricks.com/c/conv_xyz
链接不包含 http/https——应用与设置界面相同的方式推断：环回主机（localhost, 127.0.0.1）为 http，远程主机为 https。Databricks 工作区挂载点自动发现，无需包含在链接中。仅识别 /c/
点击链接的行为类似打开已知站点的页面：
若窗口已连接该服务器，应用复用该窗口并就地导航至会话。 若此前连接过该服务器但无窗口打开，应用在新窗口中打开。 若从未连接过该服务器，应用将要求先确认，因为连接服务器会授予通知和注册该机器为 runner 等权限。默认选项为取消；仅打开来自可信服务器的链接。一旦允许，服务器将被记住，后续链接无需提示直接打开。
