Linux 桌面移植补丁 lql341/deepseek-harness-linux-desktop

deepseek-harness-linux-desktop

非官方补丁集，为 DeepSeek Harness 桌面应用 提供 Linux x64 发布目标（AppImage + deb），并使其行为与 macOS 构建保持一致。

上游仅发布 macOS 和 Windows —— 其自身的 apps/desktop/README.md 中声明 “Linux 不是受支持的桌面发布目标”，并且打包测试断言必须拒绝 linux-x64 目标。本仓库就是打开这条路径的差异补丁集。

状态：仅补丁，未在 Linux 上验证。
这些补丁是针对上游标签编写的，并在 macOS 上进行了检查（语法层面，外加树哈希验证其可干净应用）。它们从未在 Linux 上编译、打包或运行过。首次构建时请预留一些小的修复工作 ——故障排查表列出了预期会遇到的问题。

基线：上游标签 dsh-v0.2.0-rc.2（提交 639ed0153972），5 个补丁，33 个文件， +798 / −119。

目录

- 1. 你将获得什么
- 2. 要求与固定路径
- 3. 构建 —— 一键脚本
- 4. 构建 —— 分步进行（含成功条件）
- 5. 验收清单（7 项行为）
- 6. 产物及其落盘位置
- 7. 故障排查
- 8. 已验证 / 未验证
- 9. 已知限制
- 10. 布局、许可证、署名

1. 你将获得什么

| # | macOS 行为 | 补丁集如何在 Linux 上实现 |
| 1 | 应用启动 | 桌面策略门禁在 Linux 上不再抛出 desktop policy: unsupported platform |
| 2 | 窗口边框 | titleBarStyle: 'hidden' + titleBarOverlay（与 Windows 使用的相同机制），因此页面拥有标题栏区域；DSH_DESKTOP_LINUX_NATIVE_FRAME=1 可恢复桌面边框 |
| 3 | 关闭最后一个窗口后任务继续运行 | window-all-closed 现在仅在 Windows 上退出；应用程序及其 Host 保持存活，并提供 Show Window 菜单项以恢复窗口 |
| 4 | PATH 上的 dsh 命令 | 新增 POSIX 启动器以及命令安装器的 Linux 分支（~/.local/bin/dsh）；已存在的外部命令会被报告并备份，绝不会被静默覆盖 |
| 5 | dsh:// 深链接 | 桌面条目带有 MimeType=x-scheme-handler/dsh；shell 已注册该 scheme |
| 6 | 捆绑运行时 | 运行时准备按目标平台选择 Linux 载荷（Node/pnpm/Python、Electron 二进制、原生包），而不是假定 macOS 或 Windows |
| 7 | 更新 | Linux 包不带 feed；设置 DSH_DESKTOP_LINUX_UPDATE_ORIGIN 可选择加入自托管的通用（AppImage）feed |

Office 文档转换开箱即用：Linux 使用捆绑的 WASM LibreOffice 引擎（@deepseek-ai/libreoffice-kit-wasm），而非系统 LibreOffice。

2. 要求与固定路径

构建主机必须是 Linux x86_64。 该补丁保留了上游的规则，即 linux-x64 拒绝在其他任何地方构建，因此无法从 macOS 交叉构建。linux-arm64 不属于本系列。

| 要求 | 值 | 检查 |
| 主机 | Linux x86_64 | uname -sm → Linux x86_64 |
| Node | ^22.19.0 \|\| >=24.0.0 | node -v |
| pnpm | 11.7.0 | corepack enable && pnpm -v |
| git | 任意较新版本 | git --version |
| 可用磁盘 | ≥ 15 GB（检出约 200 MB，依赖 + Electron + 运行时负载数 GB） | df -h "$HOME" |
| 网络 | registry.npmjs.org、nodejs.org、Python 独立构建、github.com（Electron）、electron-builder 自身的下载 | 取决于代理；参见故障排查 |
| 冒烟运行所需的显示 | X11/Wayland，或 xvfb-run | echo "$DISPLAY$WAYLAND_DISPLAY" |

本文档通篇使用的路径——请先设置它们：

export PATCH_REPO="$HOME/src/deepseek-harness-linux-desktop" # 本仓库
export SRC="$HOME/src/deepseek-harness" # 上游检出（在下方创建）
export TARGET_DIR="$SRC/apps/desktop/.desktop-build/targets/linux-x64"
export ARTIFACTS="$TARGET_DIR/artifacts"

3. 构建——一次性脚本

代理可以按原样执行此代码块（它会在第一个失败的断言处中止）：

set -euo pipefail

--- 预检 -------------------------------------------------------------
[ "$(uname -s)" = "Linux" ] || { echo "FAIL: host is not Linux"; exit 1; }
[ "$(uname -m)" = "x86_64" ] || { echo "FAIL: host is not x86_64"; exit 1; }
command -v git >/dev/null || { echo "FAIL: git missing"; exit 1; }
command -v node >/dev/null || { echo "FAIL: node missing"; exit 1; }
corepack enable >/dev/null 2>&1 || true
[ "$(pnpm -v)" = "11.7.0" ] || echo "WARN: pnpm is $(pnpm -v), expected 11.7.0"

export PATCH_REPO="${PATCH_REPO:-$HOME/src/deepseek-harness-linux-desktop}"
export SRC="${SRC:-$HOME/src/deepseek-harness}"

--- 获取补丁集并应用它 --------------------------------------
[ -d "$PATCH_REPO/.git" ] || git clone https://github.com/lql341/deepseek-harness-linux-desktop.git "$PATCH_REPO"
sh "$PATCH_REPO/apply.sh" "$SRC"

--- 证明补丁已落地 ---------------------------------------------
[ "$(git -C "$SRC" rev-parse HEAD^{tree})" = "0c006d75f9a36f3e428f51364b59bf3e63770484" ] \
|| { echo "FAIL: patched tree hash mismatch"; exit 1; }
[ -f "$SRC/apps/desktop/.env.linux" ] || { echo "FAIL: .env.linux missing"; exit 1; }

--- 依赖 ----------------------------------------------------------
cd "$SRC"
pnpm install --frozen-lockfile

--- 低成本预检：验证 .env.linux 和构建工具链 ---------
pnpm --dir apps/desktop run check:package # 预期："would publish 0.2.0-rc.2 ... valid"

--- 先做目录构建：它到底能不能启动？ ----------------------------
pnpm --dir apps/desktop run package:linux:x64:dir

--- 真实产物 --------------------------------------------------------
pnpm --dir apps/desktop run package:linux:x64
ls -l "$SRC/apps/desktop/.desktop-build/targets/linux-x64/artifacts"

4. 构建 — 分步进行（含成功条件）

步骤 0 — 主机预检

uname -sm # 预期：Linux x86_64
node -v # 预期：v22.19+ 或 v24+
corepack enable && pnpm -v # 预期：11.7.0
df -h "$HOME" # 预期：可用空间 >= 15G

如果 uname -m 是 aarch64，或者 uname -s 是 Darwin，请停止：本补丁集不涵盖该组合。在 macOS 上你仍然可以应用这些补丁（步骤 1 在任何系统上都可用），但 package:linux:x64 会拒绝运行。

步骤 1 — 克隆本仓库并应用补丁系列

git clone https://github.com/lql341/deepseek-harness-linux-desktop.git "$PATCH_REPO"
sh "$PATCH_REPO/apply.sh" "$SRC"

apply.sh 会在标签 dsh-v0.2.0-rc.2 处克隆上游，创建分支 linux-desktop，对所有 5 个补丁运行 git am，并将 .env.linux.example 复制为 .env.linux（打包代码需要该文件，缺少它会中止）。

成功条件 — 以下四项必须全部成立：

git -C "$SRC" log --oneline | head -1
预期："docs(desktop): describe the Linux build and its known limits"
git -C "$SRC" rev-parse HEAD^{tree}
预期：0c006d75f9a36f3e428f51364b59bf3e63770484
git -C "$SRC" status --porcelain # 预期：为空
test -f "$SRC/apps/desktop/.env.linux" && echo env-ok

若要审查而非直接信任：git -C "$SRC" log --stat 会显示这 5 个主题提交。

步骤 2 — 安装依赖

cd "$SRC"
pnpm install --frozen-lockfile

预期退出码为 0。如果默认 registry 较慢，可以使用镜像 — 要么在 apps/desktop/.env.linux 中设置 DSH_DESKTOP_NPM_REGISTRY（供捆绑运行时安装使用），要么为 Electron 下载设置 ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/。

步骤 3 — 低成本预检（不构建，仅需数秒）

pnpm --dir apps/desktop run check:package

这会校验 .env.linux、发布设置和主机工具链，然后打印类似 desktop package: linux-x64 would publish 0.2.0-rc.2; local configuration and toolchain valid 的内容。在花费时间进行真实构建之前，先修复它报告的任何问题 — 这是发现 pnpm 版本错误、缺少 .env.linux 或其中条目有误的最廉价方式。

步骤 4 — 目录构建（第一次真实构建）

pnpm --dir apps/desktop run package:linux:x64:dir

每个打包命令都会自行构建整个仓库、准备 Electron 发行版、从 registry 安装生产运行时闭包，并写入解包后的应用程序。预期需要数分钟并产生大量输出；退出码为 0 即通过条件。

成功条件：

ls -d "$ARTIFACTS"/linux-unpacked # 解包后的应用程序markdown
ls -l "$ARTIFACTS/linux-unpacked/DeepSeek Harness" # Electron 二进制文件，可执行

步骤 5 — AppImage + deb sh
pnpm --dir apps/desktop run package:linux:x64
ls -l "$ARTIFACTS"/.AppImage "$ARTIFACTS"/.deb

预期恰好有两个产物，名称来自产品版本（参见 §6）。
Linux 不运行签名或公证，因此这里不需要其他操作。

如果你想使用自己的编号，请传入 --build-version，例如
pnpm --dir apps/desktop run package:linux:x64 -- --build-version 0.2.0-rc.2.linux.1；
如果不传，产物将携带上游产品版本。

步骤 6 — 冒烟运行 sh 目录构建，无头主机： xvfb-run -a "$ARTIFACTS/linux-unpacked/DeepSeek Harness"

或者安装 deb（这也是让 dsh 命令可用的方式，参见 §9）：
sudo apt install ./"$ARTIFACTS"/deepseek-harness--linux-x64.deb
dpkg -L deepseek-harness | grep -E '/(bin|opt)/' # 找到已安装的可执行文件然后从桌面菜单启动它，或运行上面打印的路径（要加引号：它包含一个空格）

前 30 秒内需要观察的事项：

- 它必须到达工作区/欢迎界面，并且不能打印 desktop policy: unsupported platform；
- 窗口不应有系统标题栏，并且原生控件位于右上角（如果桌面环境绘制了奇怪的东西，请使用
DSH_DESKTOP_LINUX_NATIVE_FRAME=1 重试）；
- 在没有用户命名空间的容器中，Chromium 的沙箱可能拒绝启动——优先使用 deb，或者仅作为最后手段添加 --no-sandbox（这会降低安全性）。

5. 验收清单（7 项行为）

按顺序运行这些检查；每一项都对应 patches/ 中的一个补丁。

| # | 检查 | 命令 / 观察 | 预期 |
| 1 | 启动 | 按步骤 6 启动 | 工作区打开，没有 unsupported platform 错误 |
| 2 | 窗口镶边 | 查看窗口；切换 DSH_DESKTOP_LINUX_NATIVE_FRAME=1 | 叠加式标题栏 + 原生控件；环境变量可恢复边框 |
| 3 | 保持存活 | 关闭最后一个窗口，然后运行 pgrep -af "DeepSeek Harness" | 进程仍在运行；Show Window* 菜单项会重新显示窗口；显式 Quit 会真正退出 |
| 4 | dsh 在 PATH 中 | 从应用 UI 安装命令，然后在一个新 shell 中运行：command -v dsh && dsh --version | ~/.local/bin/dsh，运行捆绑的 CLI（确保 ~/.local/bin 在 PATH 中） |
| 5 | 深度链接 | xdg-mime query default x-scheme-handler/dsh 然后 xdg-open 'dsh://open' | 已注册 desktop 文件，并且窗口获得焦点 |
| 6 | 运行时 + Office | 在会话中运行 shell 工具；请求 DOCX→PDF 转换 | bash 工具可用（Landlock，内核 ≥ 5.13）；通过捆绑的 WASM 引擎转换成功 |
| 7 | 更新 | 在没有 DSH_DESKTOP_LINUX_UPDATE_ORIGIN 的情况下启动 | 不检查更新；设置自托管的通用 feed origin 后，应用会读取 latest-linux.yml |

6. 产物及其落盘位置

所有内容都写入 apps/desktop/.desktop-build/targets/linux-x64/ 下：

| 路径 | 内容 |
| artifacts/linux-unpacked/ | 解包后的应用程序（来自 :dir）；可执行文件 DeepSeek Harness |
| artifacts/deepseek-harness--linux-x64.AppImage | AppImage |
| artifacts/deepseek-harness--linux-x64.deb | Debian 包 |
| runtime/ | 为此目标准备的 Electron + pnpm + 启动器 |
| dsh/ | 捆绑的 dsh 运行时树，将成为 app.asar/dsh |
| package-set/、downloads/ | 中间包集合和已下载的归档 |
| packaging-runs/ | 每次运行的日志和发布记录 |

使用默认版本时，这些是 deepseek-harness-0.2.0-rc.2-linux-x64.AppImage 和 …-linux-x64.deb。

7. 故障排查

| 症状 | 原因 | 操作 |
| desktop package: unsupported target "linux-x64" | 补丁未应用 | 重新运行步骤 1；验证树哈希 |
| desktop package: cannot read …/.env.linux; copy … | 缺少必需的环境文件 | cp apps/desktop/.env.linux.example apps/desktop/.env.linux |
| desktop package: linux-x64 requires a Linux x64 build host | 在 macOS/arm64 上构建 | 在 Linux x86_64 上构建 |
| desktop package: unsupported setting X in …/.env.linux | 键不在 Linux 模板中 | 仅使用 DSH_DESKTOP_APP_ID、DSH_DESKTOP_NPM_REGISTRY、DSH_DESKTOP_LINUX_UPDATE_ORIGIN、策略来源 |
| ERR_PNPM_UNSUPPORTED_ENGINE / 奇怪的依赖错误 | Node 或 pnpm 错误 | Node ^22.19 \|\| >=24，pnpm 11.7.0 |
| Electron 下载超时 / 404 | 代理或镜像 | ELECTRON_MIRROR，或导出 HTTPS_PROXY |
| missing required LibreOffice engine wasm | 运行时树中缺少 WASM 套件 | 确认已安装 @deepseek-ai/libreoffice-kit-wasm（它是 @deepseek-ai/libreoffice-kit 的可选依赖） |
| main.ts 中来自 tsc 的类型错误 | 第一次真正的类型检查 | 报告它们；策略分支收窄是最可能的位置 |
| AppImage 拒绝启动（沙箱 / 用户命名空间） | Ubuntu 23.10+ AppArmor 限制 | 安装 deb，或添加 AppArmor 配置文件；--no-sandbox 仅作为最后手段 |
| dsh 安装被拒绝，提示 "transient AppImage mount" | AppImage 资源位于临时挂载中 | 安装 deb，或解压 AppImage 并设置 DSH_DESKTOP_RESOURCES |
| 深度链接无任何作用 | 桌面文件未注册 | 确认 xdg-mime query default x-scheme-handler/dsh；重新安装 deb |

8. 已验证 / 未验证

已验证：

- 该系列补丁在 dsh-v0.2.0-rc.2 上干净应用；git am 后生成的树哈希为 0c006d75f9a36f3e428f51364b59bf3e63770484，没有遗留更改。
- apply.sh 在 C locale 且未配置 git 身份的情况下端到端运行：全新浅克隆 → 5 个补丁 → 创建 .env.linux → 退出码 0。
- 每个更改的文件都通过语法检查；所有原生依赖均已针对
npm registry 解析（存在 Linux 变体，node-pty 提供 linux-x64/arm64 预构建）。

未验证（需要 Linux 主机）：

- pnpm install、check:package、编译和类型检查。
- Electron 的 titleBarOverlay 在各桌面环境下的外观；两种主题下的窗口拖拽/调整大小和标题栏尺寸。
- landlock-run 解包和 bash 沙箱、deb 元数据、XDG 深度链接关联。
- 桌面测试套件，上游从未在 Linux 上运行过，且可能存在预先存在的失败。在未打补丁的标签上运行一次以获取基线，然后再进行比较。

9. 已知限制

- 无法 1:1 实现：macOS 红绿灯按钮、侧边栏 vibrancy、Dock 弹跳。该补丁集以原生覆盖窗口控件、扁平侧边栏和通知作为替代。
- dsh 命令需要 deb：AppImage 的资源位于临时挂载中，因此从中安装命令会被拒绝，并给出可操作的提示信息（DSH_DESKTOP_RESOURCES 是用于已解包目录树的逃生通道）。
- 平台标识：Linux 构建会向 DeepSeek Platform 报告 macOS 桌面标识，因为共享账户包只为 x-client-platform 定义了 darwin/win32（省略它会降级为 web）。
- 强制更新策略在 Linux 上无效（没有官方 Linux 更新源）。
- 仅支持 linux-x64；linux-arm64 不属于本系列。
- 欢迎窗口的标题栏颜色仅在创建时跟随系统调色板。
- deb 维护者字段是占位符（DeepSeek Harness）。

10. 布局、许可证、署名

patches/0001..0005*.patch git format-patch 系列，按文件名顺序应用 apply.sh 在基础标签处克隆上游，应用该系列，创建 .env.linux LINUX-DESKTOP.md 长篇指南：逐文件说明、已验证事实、待办事项 LICENSE MIT（上游 DeepSeek + 本补丁集）

每个补丁对应一个主题：(1) 接受目标，(2) 安装 dsh 命令，
(3) 准备 Linux 运行时负载，(4) 类 macOS 外壳行为，(5) 文档。

本补丁集在 MIT 许可证下分发（见 LICENSE）。这些补丁是针对 deepseek-ai/deepseek-harness 的差异补丁，该项目采用 MIT 许可证，版权所有 (c) 2026 DeepSeek；该声明在此保留。

与 DeepSeek 无关联、未获其认可或支持。上游处于开发者预览阶段且迭代迅速，因此在变基到更新的标签时预计会出现冲突。