关于利用AI Agent转译程序——WorkBuddy-Linux

技术交流与探讨 应用程序与桌面环境
1

写在正文开始前，因为工作的关系需要参与一个关于使用办公 AI智能体的WorkBuddy的培训，实在没办法找来找去找到了GitHub上的JipZeonGit/workbuddy-linux，发现貌似可以用，就安装跑了一下。结果...

以下内容也是WorkBuddy根据任务的实际情况写下的说明

0. 先说喜悦

WorkBuddy 官方目前只出 macOS / Windows 版，Linux 只有个老旧的官方 AppImage（版本落后）。
但我发现 GitHub 上有位大佬写了转换工具 workbuddy-linux，能把 macOS x64 的 .dmg 安装包 解包，
套进 Linux 原生的 Electron 运行时重新打包——Mac 的 Mach-O 二进制当然跑不了，真正移植的是它的应用资源（app.asar），
而运行时换成我们自己的 Linux Electron。

实测跑通后，新版本功能比官方 Linux AppImage 新一大截，日常用完全没问题。
下面是完整方法 + 我踩的坑 + 修好的两个 Bug，希望能帮到同样在 Linux 上"馋"这个工具的朋友。

1. 原理（一句话）

macOS .dmg  ──解包──▶  app.asar (应用资源, 版本 5.3.14)
                              │
              Linux Electron 37.10.3 (原生 x86_64 ELF)
                              │
                         打补丁 + 重编译原生模块
                              │
                        可用的 Linux 版 WorkBuddy

关键点：转换工具不是做二进制转译，而是"借壳"——用 Linux 的 Electron 跑 Mac 版的应用逻辑。

2. 准备

  • 一个 macOS x64 的 WorkBuddy .dmg（从 Mac 上拖出来，或从官网下载 macOS 版）
  • 构建机装好：git、node、npm、make、g++、python3、7z、以及 dpkg（解 DMG 用）
  • 国内网络注意：GitHub 与 Electron 官方源直连不稳，需要镜像（见下）

3. 构建步骤

# 1) 克隆转换工具（原项目已归档，但代码可正常克隆；用镜像站）
git clone https://gitclone.com/github.com/JipZeonGit/workbuddy-linux
cd workbuddy-linux

# 2) 设置镜像环境变量（重要，否则 Electron / npm 包会卡死）
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
export ELECTRON_HEADERS_URL="https://artifacts.electronjs.org/headers/dist"
export npm_config_registry="https://registry.npmmirror.com/"

# 3) 指定安装目录并开跑
export WORKBUDDY_INSTALL_DIR="$HOME/Applications/WorkBuddy-5.3.14"
bash install.sh /path/to/WorkBuddy-darwin-x64-5.3.14.dmg

工具会自动完成：DMG 解包 → 下载 Linux Electron → 复制 app.asar → 编译原生模块(node-pty / better-sqlite3 等) → 应用 Linux 补丁 → 生成图标/启动器/桌面入口。

构建完直接：

# 命令行启动
$HOME/Applications/WorkBuddy-5.3.14/start.sh

# 或从应用菜单搜 "WorkBuddy 5.3.14"

:warning: 注意：转换版和官方版共用 ~/.workbuddy 数据目录（单实例锁），两者不能同时运行，切换时要先退出另一个。

4. 我遇到的两个 Bug 及修复（这部分最值得分享）

Bug 1：执行任务时整个网页卡死

  • 根因：start.sh 里带了 --in-process-gpu，把 GPU 渲染跑在了浏览器主进程里。
    任务执行时大量渲染（流式 markdown、代码高亮）直接把 UI 线程堵死。
  • 修复：移除该 flag，改回独立 GPU 进程；并保留无 GPU 时自动回退 --disable-gpu。
  • 验证：进程列表里能看到独立的 --type=gpu-process，卡死现象消失。

Bug 2：最小化/最大化/关闭按钮偶尔消失，只能重启恢复

  • 根因：无边框窗口的三个按钮，是渲染进程用 JS 注入到 document.body 上的独立 React root（WindowControls 组件）。
    一旦渲染进程重建了 body 或容器被移除，按钮就永久消失——因为没有任何逻辑去重建它。
  • 修复：在 renderer/assets/index-*.js 里注入了一个自愈 watchdog——
    用 MutationObserver + 兜底 setInterval 持续监测按钮容器，一旦丢失就自动重建并重挂载。
  • 验证：补丁标记写入线上 app.asar，多日运行未再复发。

asar 重打包的坑：手写 asar 头部字节会静默失败（它比标准格式多一层 pickle，JSON 从第 16 字节才开始）。
正确姿势是用 @electron/asar 库：extract 改文件后 createPackageWithOptions(src, dest, { unpackDir: "{node_modules,cli,native,resources}" })，
原生模块必须 unpacked 落地真实磁盘，否则 .node 动态库 dlopen 失败。

5. 已知限制（诚实交代）

移植版不是完美平替，这些功能是 Mac 独占或暂未适配的：

功能 状态 原因
腾讯文档引擎 :cross_mark: 不可用 仅 macOS arm64 的 .dylib
AI 代码沙盒 :warning: 降级 无 Linux 版运行时
自动更新 :cross_mark: 已禁用 避免覆盖我们的补丁
An object could not be cloned 报错 :warning: 偶发 app.asar 层 IPC 序列化竞态，仅启动瞬间出现、不影响使用

日常对话、文件读写、MCP 工具、自动化任务等核心能力完全正常。

6. 现状

目前我长期跑着这个 5.3.14 移植版，两个原 Bug 已修复且多日未复发，稳定可用。
唯一的小瑕疵是启动时一条无害的 IPC 警告，不影响任何功能。

7. 结语

能在纯 Linux 桌面上用上最新的 WorkBuddy，确实挺爽的 :slightly_smiling_face:
感谢 JipZeonGit 的开源转换工具，也欢迎大家一起在 Linux 上把更多"Mac/Win 独占"的好工具抢救回来。

2

你直接安装AUR里的就行了

4

:blush:，我的主力系统并不是Arch linux。而且这个思路相当不错，通过改造Mac版的部分小工具，让agent工作重构一些工具挺好的。我有个便携宏键盘，就是用这个思路转译了一个键盘编辑软件。我认为这个思路也是一种扩展生态的方式