​

桌面应用（Tauri）

Tauri 桌面客户端不仅仅是一个 GUI 壳 — 它是一个拥有 25+ 项原生系统能力的真正 Agent OS。所有数据留在你的机器上，三个内置 Sidecar（Python 后端、Next.js 前端、Agent Runner）均打包为独立二进制，零外部依赖。

​

下载与安装

Myrm Desktop 具备智能跨平台分发能力：

1. 智能硬件匹配：WebGL 探测绕过浏览器限制（如 Safari 在 M 系列芯片上伪装 Intel），确保一键获取针对你设备的最优二进制。
2. 无竞态自动更新：Map-Reduce CI/CD 流水线保证各平台可靠、静默的后台更新，无 manifest 冲突。

从 Myrm 官网 或 GitHub Releases 获取最新版本。

​

原生 OS 能力

桌面应用提供深度系统集成，远超任何浏览器端 AI 工具：

​

屏幕与输入

• 全局快捷键 — 动态注册系统级快捷键，切换窗口或触发 Appshot
• Appshot 截屏 — 全局快捷键截取当前窗口 + 通过无障碍 API 提取文字，一键完成
• 剪贴板集成 — Agent 可写入你的真实 OS 剪贴板（而非沙箱剪贴板）
• Deep Link 协议 — 通过专属 myrmagent:// URL 打开对话或触发操作（5 种 intent：chat、agent、ask、oauth、install-skill），配合单实例互斥锁实现热启动参数安全转交，杜绝多应用 Scheme 注册冲突与劫持，内置协议白名单硬拦截非法路径注入。

​

电源与安全

• 智能防休眠 — Agent 执行任务时自动阻止系统休眠（macOS IOKit、Linux systemd-inhibit、Windows SetThreadExecutionState）
• 屏幕锁定管理 — 检测锁定状态、为 Computer Use 会话解锁、在系统 Keychain 中安全存储凭证
• 原生提权 — 必要时请求管理员权限（如 macOS 隔离属性修复）
• OTA 自动更新与结果反馈 — Tauri 更新器 + 公钥安全校验，防止供应链攻击；结合冷启动更新交接协议（Update Handoff），跨版本升降级后毫秒级弹出更新结果反馈，并提供版本详情与安全回滚防护

​

视觉与交互

• 系统托盘与双层版本透明度 — 托盘置顶与 WebUI「关于」面板同步展示 Desktop Shell: v1.0.0 与 Engine Sidecar: v0.1.0 双层版本，消除多环境版本混淆；支持一键复制标准排障诊断报告；原生 Rust 托盘支持就地定点更新状态，后台热升级动态投递进度，配合 macOS 模板图标与 Windows 高 DPI 图标，自适应系统深浅色。
• 任务栏进度条 — Agent 或后台任务运行时，任务栏/Dock 图标显示不确定进度指示器；任务在窗口最小化时完成，Dock 图标自动弹跳提醒
• 完整的 SubagentDashboard 桌面端可用 — Tauri WebView 渲染完整的 Next.js 前端，所有子代理监控功能（取消、转向、Gantt 时间线、排序/过滤、停滞告警）在桌面端完全可用——零额外代码
• 视觉审批 Overlay — OS 级透明红框覆盖在目标显示器上，即使聊天窗口被遮挡也可见
• 桌面宠物精灵 — 透明置顶窗口 + Canvas 2D 渲染的伙伴宠物系统
• 最小化到托盘 — 关闭窗口时最小化到系统托盘而非退出

​

启动体验

• 单实例互斥与二次启动唤醒 — 原生 Rust 进程锁（< 15ms 极速互斥），彻底防止多开导致的 Sidecar 端口冲突；二次启动自动唤醒并置顶已有主窗口，并将命令行参数和上下文原生透传给前端
• 窗口位置/尺寸跨重启恢复 — 关闭后再打开，窗口自动回到上次的位置和大小，多显示器用户尤其受益
• 冷启动零白屏 — 暗色背景预渲染，启动瞬间不会看到刺眼白闪
• Tab 路由跨重启记忆 — 崩溃、更新或重启后自动回到上次浏览的页面（Chat/Work/Projects 三 tab 独立记忆）

​

基础设施

• Python Sidecar — 受管的 FastAPI 后端进程，含健康检查
• Next.js Sidecar — 受管的 Standalone 前端服务器（WebUI 模式）
• Agent Runner Sidecar — Bun 编译的独立二进制，CLI 智能体集成
• Windows 进程树递归销毁 — 彻底解决 Windows 子进程幸存者锁定文件导致的 OTA 更新失败
• 幸存者智能识别与端口自愈 — 启动时若端口被占，自动识别是否为 Myrm 旧实例，智能执行 Re-kill 并在 100ms 退避轮询下等待端口完全释放，杜绝端口冲突报错
• 端口冲突检测 — 启动前检查端口占用
• 开箱即用 API 对齐 — 默认桌面模式下 UI 自动连接 127.0.0.1:8080 后端，无需手动改端口。启用 WebUI 模式 进行远程访问时，UI 从系统配置读取你设定的端口（如 25808）
• Boot 屏后端门控 — 冷启动时 Boot 动画会等待 Python 后端 /health 就绪后再进入主界面，避免 ECONNREFUSED 报错；Rust 侧亦最多 30s 健康轮询
• 本地浏览器开发一致 — 使用 bun run dev 在 :3000 联调时，即使 macOS 代理以 IPv4-mapped 回环（::ffff:127.0.0.1）连接后端，Settings/ConfigSync 也不会再出现首屏 401
• Sidecar 构建命令 — 维护者可用 ./myrm desktop sidecar 构建 release 二进制；./myrm desktop check-sidecar 校验非空占位
• 公网 Ingress — 粘贴自选 HTTPS 穿透地址（cpolar、NATAPP、frp 等）；见隧道指南
• macOS 隔离修复 — 检测并自动修复 com.apple.quarantine 属性

​

全局截屏 AI（Appshot + FlowPad）

桌面端独有的 Appshot 功能让你无需离开当前应用即可与 AI 交互：

1. 全局快捷键截屏：在任意应用中按下快捷键，系统级监听截取当前活动窗口
2. 自动文字提取：通过无障碍 API 自动提取窗口中的文字内容
3. 选中文本高优先级上下文：截屏时自动捕获你当前选中的文本（macOS 通过 AXSelectedText、Windows 通过 Ctrl+C 剪贴板），选中内容作为最高优先级上下文注入 AI，FlowPad 中以醒目的 Context Chip 展示——AI 精准理解你关注的重点
4. FlowPad 浮窗：截屏后自动弹出 AI 提问面板，直接输入问题并发送至对话
5. Quick Actions 快捷操作：截屏后显示一键预设按钮（回复/总结/翻译/解释），零输入完成高频操作
6. 多次截屏叠加：支持连续截取多个窗口（上限 10 张），统一发送给 AI 分析
7. 图片预览与管理：在 FlowPad 中预览已截取的图片，可单独删除或点击放大查看
8. 隐私黑名单保护：敏感应用（1Password、银行等）被截屏时自动拦截并警告，支持”仍然截取”一键绕过
9. Inline Input 模式（Option+I）：全局快捷键触发截屏后进入 Inline 模式，AI 结果实时流式显示在 FlowPad 内，完成后一键 Paste 回写到原应用，窗口自动隐藏——全程不离开当前应用
10. Inline Agent Switcher + Profile 路由：在 Inline 模式下可按单条消息切换目标 Agent Profile（例如 Writer/Coder），且不会污染主聊天会话的 Agent 配置

典型使用场景：选中一段代码后按快捷键让 AI 直接解释选中内容、截取邮件后点击「回复」让 AI 起草回复、截取外文页面点击「翻译」即时翻译、截取错误日志点击「解释」快速诊断、写文档时 Option+I 提问后一键 Paste 将结果直接写入编辑器。

​

设置

1. 为你的平台安装应用
2. 从应用程序菜单启动 Myrm
3. 在设置中配置至少一个 LLM API Key

​

macOS 系统权限（桌面自动化）

桌面自动化（Computer Use）需要两项 macOS 权限：辅助功能（Accessibility） 和 屏幕录制（Screen Recording）。Myrm 自动检测并引导你完成授权：

• 主动检测 — 启用 computer_use 后状态条呈现四态：已验证（捕获可用）、未验证（授权齐全但尚未探测）、捕获不可用（勾选看似正常但实时帧失败）、缺权限
• 授权 ≠ 可捕获 — 系统设置开关为开仍可能假绿；点「重新检查」会做按需捕获探测，避免带着假绿开跑桌面任务
• 一键跳转 — 点击「打开系统设置」直接跳到 macOS 隐私设置对应面板
• 重新检查 — 授权或修复陈旧授权后，点「重新检查」立即验证，无需重启应用
• 运行时提醒 — 如果在使用桌面面板时权限被撤销，会显示上下文引导横幅

​

Desktop Inspector：编号叠加（SOM）

在 Desktop Inspector 面板点击刷新时，Myrm 会在实时截图的可交互控件上叠加 [N] 编号角标。同一编号会出现在无障碍结构树与审批卡片中——你始终能看清 Agent 要点哪里。

• 省 Token 默认 — Agent 工具调用默认 include_screenshot=false；仅在 Inspector 刷新或显式请求截图时生成 SOM 叠加
• 语义优先 — @dref 仍是主操作路径；编号是给人看的「翻译层」，不替代语义引用
• 智能过滤 — 静态文本与非交互节点不标号，避免满屏数字干扰

​

跨平台目标窗口后台自愈（Zero-Token 架构）

在进行目标应用操作（如操作计算器、Excel 或微信等）时，即使该窗口处于最小化或后台挂起状态：

• 无感自愈唤醒：底层 SDC 引擎自动感知 WindowVisualState.Minimized、负坐标挂起（Windows）或 AXMinimized 属性（macOS），原子化解冻恢复窗口；
• 渲染微防抖就绪：自愈后自动等待 50ms 渲染加载，确保 UI 树完整生成后再抓取，彻底告别空树崩溃；
• 零 Token 膨胀：无需大模型额外学习或调用复杂的外部应用管理工具，降低决策出错率。

​

权限系统

桌面应用为 Agent 操作提供三级权限模型：

​

远程服务器网关

将桌面客户端连接至远程 VPS 或 NAS 上运行的 Myrm 服务器，用原生桌面体验管理远端 Agent：

1. 进入 设置 → 系统 → 服务器连接
2. 将模式从 本地 切换为 远程
3. 输入远程服务器地址（如 https://your-vps.example.com）
4. 点击 测试连接 验证服务器可达
5. 点击 连接 — 应用重载，所有 API 请求指向远程服务器
6. 使用远程服务器凭据登录（Setup Token + 密码）

一个桌面管所有机器——本机、自托管服务器（VPS、NAS、家庭服务器）或云托管，随时切换。首次打开 设置 → 系统 → 服务器连接 时会询问助手运行在哪里：本机、远端服务器或云托管，之后可随时在同一处更改。 远端服务器档案： 可保存多台服务器并一键切换，每条自带健康检查；不可达时内联提示附带「切回本地模式」按钮。连接远端时本地后端自动休眠以节省端口与电量，切回本地时自动重启。切换时自动备份本地认证 Token，断开后自动恢复。切换进行中其余连接操作会被锁定；若在「有会话正在运行」确认框中选择取消，则立即解锁——连点或在切换途中再点另一台服务器，都不会触发两次切换。 云托管： 同一设置卡的 云托管 区输入云地址，查看登录方式后在浏览器登录并点击 回到桌面端 交回会话；已登录可直接点击 发现我的沙箱 自动建档。 顺手了解：

• 远程连接时导航栏显示插头图标，点击直达连接设置。
• 定时任务在远端服务器或云沙箱上运行，即使本机关机或离线也不会停。
• 看到的能力来自所连服务器，桌面是它的窗口，不是第二份拷贝。

​

堆栈更新面板

设置 → 系统 → 关于集中了更新真相表：桌面更新器状态、服务端/引擎版本与过期徽章、云沙箱版本（控制平面契约落地前显示未知）、FIXED / Other 分组日志（可展开全文）。

• 推迟 + 免打扰 — 推迟某版本或夜间静默提醒；安全更新不可推迟。
• 空聊提醒 — 堆栈落后时横幅直达面板。
• 更新自检 — 一键验证发布源可达。

​

更新前快照

桌面更新前可自动给工作区拍照（在堆栈更新面板开一次即可）：本地数据库＋会话检查点，打上 pre-update:{from}->{to} 标签，只留最近 5 份。更新搞坏数据时，Doctor → 恢复一把拉回双库，重启应用生效。向量索引除外（自动重建）。

​

手动恢复（应用无法启动时）

快照在<数据目录>/snapshots/<快照id>/下（默认 ~/.myrm），内含 data.db、checkpoints.db 与 meta.json。重装后：先停应用，把两个 .db 文件拷回数据目录，再重启。

​

资源压力横幅

内存告急或数据盘打满时，聊天区出现横幅，最重的问题排第一（磁盘写满静默丢数比重启更毒）。忽略仅本会话有效，升级自动重开。压力严重时重型定时任务自动延后，缓解即补跑。

​

信任徽章与崩溃恢复

打开 设置 → 系统 → 关于：

• 信任徽章 — 显示当前构建的更新器签名是否校验通过（正式签名 / 开发构建 / 非官方 / 未知）。验不出来就老实说“未知”，绝不冒充“安全”。
• 恢复指南 — 后端停止或崩溃时给出失败原因 + 一键重试；重试只动后端，不碰你的会话和数据。正在跟随远端服务器时，重试会自动让路，不会重启错后端。

​

远程访问（Mobile Hub）

使用自选穿透工具实现远程访问，并可用手机指挥正在运行的 Agent：

1. 进入 设置 → 系统 → 访问
2. 启用 WebUI 模式与密码保护
3. 对端口 3000 启动穿透（Cloudflare Tunnel、cpolar、NATAPP、frp 等）
4. 将 HTTPS 地址粘贴到 公网 Ingress 并执行连通性测试
5. 用手机扫 Mobile Hub 二维码 — 选择活跃会话进入 Status Board（实时进度、审批、steer、停止、Browser/Desktop Live Preview — Agent 操作画面实时截图预览，支持全屏放大和浏览器/桌面切换）

​

远程派活（Remote Spawn）

无需回到电脑，直接在手机上创建新任务：

1. 在 Mobile Hub 中点击 新建远程任务
2. 选择 Agent 和可选的 Project
3. 输入任务消息并点击 发送
4. Agent 立即开始执行 — 你将被重定向到 Status Board 监控进度

后端为新会话签发 scoped pair token，限流 30 次/分钟。你的初始消息通过 autoStart 机制传递，Agent 在 Status Board 加载后立即开始工作。

​

Mobile Artifact 交付物查看

Agent 完成任务后，生成的文件（文档、代码、HTML 页面、图片等）直接以 Artifact 卡片 的形式展示在手机的 Status Board 中：

• 一目了然的 图标 + 文件名 + 类型 + 大小
• 点击 预览 按钮在新浏览器标签页中查看文件
• 点击 下载 按钮保存到本地

支持全部 16 种 artifact 类型，无需后端改动 — 数据已在消息流中。这意味着你可以在手机上查看、确认或要求修改 AI 交付物 — 不再需要「回工位验收」。 配对令牌分级：Hub 列表令牌不能直接控制会话；打开会话后才签发绑定 chat_id 的控制令牌。详见隧道指南。 诚实说明：隧道由你自选，Myrm 不托管流量。端到端加密中继（G2）在路线图中 — 当前安全依赖 HTTPS + 分级配对令牌 + 会话绑定。

​

Agent 干活时你在屏幕上看到什么

一个正在忙的桌面端 Agent，不该看起来像闲着；而它没在忙的时候，也不该看起来像很忙。三件事在界面上有保证：

• 你看得见「过程」，而不只是「结果」。 对话区有一条并发子代理的横向泳道条（myrm-agent-frontend/src/components/features/chat-window/in-flight-steer/ActiveSubagentSwimlanesBar.tsx，由 ChatWindowSatellites.tsx:37 挂载），正在跑的子代理一目了然，你还能直接就地 steer，不必猜它在忙什么；侧栏里置顶会话可拖拽排序、时间分组可折叠，你在意的会话永远一个拖拽就能到。
• 你的密钥待在该待的地方。 Agent 在终端里跑的任何东西，都从一个刻意收窄的环境出发：带凭据的环境变量不会被继承，所以登录令牌不会顺带漂到某个恰好会记录它的 shell 里。
• 桌面专属的行为只留在桌面。 桌面操控指令只在任务确实需要操控桌面时才注入，因此你的 Agent 在浏览器、定时任务与渠道聊天里表现完全一致。