桌面应用

Melso Desktop 提供 macOS、Windows 和 Linux 版本。它和 Web 版使用相同的账号与工作区数据，但会在本机自动管理守护进程，并为不同工作区保留各自的标签页。

Desktop 与 Web

临时查看或在公共电脑上使用时，Web 更方便。

两者可以同时登录。只要连接的是同一个 Melso 服务，看到的数据就是共享的。

安装

从 Melso 下载页 选择与系统和处理器架构对应的安装包：

安装后使用和 Web 版相同的邮箱登录。登录后，Desktop 会启动自己内置的 Melso CLI，并检测本机已有的 AI 编程工具。

桌面标签页

Desktop 会为每个工作区单独保存标签页。例如，你在工作区 A 打开了三个 issue，切到工作区 B 后会看到 B 自己的标签页；切回 A 时，之前的三个标签页仍然保留。

同一资源只会在当前工作区打开一次。标签页可以重新排序、固定、关闭，也会保留各自的前进、后退和滚动位置。点击或粘贴本部署的应用链接会直接在标签页中打开，不会跳转到浏览器。

退出登录会清除本机保存的所有标签页，避免下一位登录者看到上一个账号留下的页面。

内置守护进程

登录后，Desktop 会为当前 Melso 服务创建一个专用 CLI profile，并用它启动守护进程。这个 profile 位于：

~/.multica/profiles/desktop-<host>/

它不会读取或覆盖你在终端中使用的默认 profile。如果你同时手动启动了另一个守护进程，Melso 会把它们显示为不同的运行时。

可以在 Desktop 的设置中查看运行状态和日志。工具没有被检测到时，先确认它能在普通终端中运行并且已经登录，再重启 Desktop 的守护进程。

更新 Desktop

自动更新默认开启。应用会在后台检查并下载新版本，下载完成后可以立即重启安装，也可以等下次退出时安装。你也可以在 设置 → 更新中关闭自动检查或手动检查新版本。

更新按操作系统和处理器架构分发：

• Windows arm64 和 macOS x64（Intel）使用各自独立的更新源；
• 其余架构使用默认更新源；
• 应用会自动匹配更新源，无需手动选择；
• Linux 上自动更新只对 .AppImage 生效，.deb 和 .rpm 通过下载新安装包覆盖安装；
• 自动更新失败时，同样从下载页获取对应安装包覆盖安装。

连接自托管实例

Desktop 默认连接 Melso Cloud。连接自托管实例时，在用户目录的 .multica 下创建 desktop.json：

以上是默认位置。用户目录被迁移或重定向过的话，用实际路径。

{
  "schemaVersion": 1,
  "apiUrl": "https://api.example.com"
}

apiUrl 是 backend 的公开地址，必须填写，且必须使用 http 或 https。另外两个地址可以省略，Desktop 会自动推导：

• wsUrl：把 apiUrl 的协议换成 ws 或 wss，并在路径后追加 /ws；
• appUrl：域名以 api. 开头且至少三段时去掉 api. 前缀（api.example.com → example.com），否则保持与 apiUrl 相同。

通常只写 apiUrl 即可。推导不符合预期时再显式覆盖，常见情况有三类：

• Web 与 API 不同域；
• WebSocket 单独部署；
• 域名不满足剥前缀的约定（api.local 这类两段域名不会去掉前缀）。

{
  "schemaVersion": 1,
  "apiUrl": "https://api.example.com",
  "appUrl": "https://app.example.com",
  "wsUrl": "wss://ws.example.com/socket"
}

保存后重启 Desktop，配置只在启动时读取一次。两种失败的表现不同，据此可以快速区分：

• 文件没找到（目录不对，或文件名不是 desktop.json）：Desktop 使用默认的 Cloud 配置，不报错。所以如果 Desktop 仍然显示 Cloud 地址且没有任何配置错误，说明文件不在 Desktop 查找的位置。
• 文件找到但无效（JSON、版本或 URL 有问题）：Desktop 显示配置错误，不会自动回退到 Cloud。

删除该文件并重启即可恢复默认的 Cloud 配置。

Windows：检查文件名和编码

Windows 上两个编辑器默认行为会悄悄生成 Desktop 用不了的文件：

• 记事本会补 .txt 后缀。存成 desktop.json 可能实际得到 desktop.json.txt，Desktop 会当作没找到。在资源管理器里打开文件扩展名显示，或在保存对话框里选所有文件。想确认真实文件名，在 PowerShell 里运行 Get-ChildItem "$env:USERPROFILE\.multica" -Filter "desktop.json*"，Name 一列必须正好是 desktop.json。
• PowerShell 重定向会写成 UTF-16 或带 BOM。> desktop.json 和 Out-File 可能生成无法解析的编码，表现为配置错误。

用 PowerShell 一步创建可以同时避开这两个坑：

$dir = "$env:USERPROFILE\.multica"
New-Item -ItemType Directory -Force $dir | Out-Null
$json = @'
{
  "schemaVersion": 1,
  "apiUrl": "https://api.example.com"
}
'@
[System.IO.File]::WriteAllText("$dir\desktop.json", $json)

Windows Defender 把 Melso 报成病毒

现象：Windows 安全中心报出 Trojan:Script/Wacatac.B!ml 之类的威胁，并隔离 Desktop 安装目录里的某个文件。被隔离的通常是内置的 CLI，而不是应用主程序：

C:\Users\<你>\AppData\Local\Programs\@multicadesktop\resources\app.asar.unpacked\resources\bin\multica.exe

Melso 的生产 Windows 构建使用 Authenticode 签名，发布工作流会在上传前验证签名。如果 Defender 仍然报警，请先确认 Windows 显示有效的 Melso 发布者签名，并确认 SHA-256 与公开校验和一致；任一检查失败时都不要添加排除项。

可以自己校验 —— Melso 的公开发布渠道提供覆盖全部 CLI 压缩包的 checksums.txt：

Get-FileHash .\multica-cli-<version>-windows-amd64.zip -Algorithm SHA256

把输出的哈希和公开的 checksums.txt 对应行进行比较。

怎么解决：

1. 把隔离的文件恢复回来 —— Windows 安全中心 → 病毒和威胁防护 → 保护历史记录 → 选中 Melso 那一条 → 操作 → 还原。

2. 加排除项，避免再次被隔离 —— 病毒和威胁防护 → 管理设置 → 排除项 → 添加或删除排除项 → 文件夹，两个都要加：

   • %LOCALAPPDATA%\Programs\@multicadesktop
   • %APPDATA%\Melso

   两个路径缺一不可：内置 CLI 被删掉后，Desktop 会把替换版本下载到 %APPDATA%\Melso\bin，只排除安装目录的话，下载下来的副本还会再被隔离一次，陷入循环。

3. 把误报提交给微软 —— 在 Microsoft Security Intelligence 文件提交页选择 Software developer 和 Incorrectly detected as malware。这一步才是让检测对所有用户撤销的办法，一般几天内生效。

接下来

• 快速上手 — 首次连接流程。
• 守护进程与运行时 — 内置守护进程的机制。
• 故障排查 — 连接问题排查。