stonehfzs/deepseek-harness-fedora

DeepSeek Harness — Fedora 打包

为 DeepSeek Harness（dsh）构建 Fedora RPM（以及可移植的 Windows/macOS 捆绑包），它是带有浏览器 UI 的智能体编程助手。

该软件包是自包含的：它自带 Node.js 以及完整的插件依赖闭包，因此安装它不需要 nodejs、不需要 npm、不需要 pnpm，也不需要网络访问。安装 RPM 后，运行 dsh，或从应用程序菜单启动 DeepSeek Harness，浏览器 UI 就会打开。

$ make rpm          # build build/rpmbuild/RPMS/x86_64/deepseek-harness-.rpm
$ make smoke        # unpack the RPM and prove it works (no root needed)
$ sudo dnf install ./build/rpmbuild/RPMS/x86_64/deepseek-harness-.rpm
$ dsh web           # or: dsh --profile headless "summarize this repository"

安装内容

| 路径 | 用途 |
| --- | --- |
| /usr/bin/dsh | 启动器：定位运行时，设置默认 DSH_HOME，应用打包的覆盖层，exec 运行时 |
| /usr/libexec/dsh/dsh-runtime | 上游自包含运行时（约 262 MiB，自带 Node.js + 虚拟文件系统） |
| /usr/libexec/dsh/dsh-runtime-rg | ripgrep sidecar，由运行时解析为 -rg |
| /usr/libexec/dsh/patches/00-packaged-workarounds.yml | 补丁覆盖层，使随附的 profiles 能在 0.1.5rc1 上启动 |
| /usr/share/applications/io.github.deepseek-harness.desktop | 运行 dsh web 的菜单项 |
| /usr/share/icons/hicolor/scalable/apps/deepseek-harness.svg | 图标（上游前端资源） |
| /usr/share/metainfo/io.github.deepseek-harness.metainfo.xml | AppStream 元数据 |
| /usr/share/man/man1/dsh.1 | 手册页 |

运行时状态位于 $DSH_HOME（默认 ~/.dsh）；运行时写入的唯一其他目录是 $XDG_CACHE_HOME/pkg（默认 ~/.cache/pkg），它会在首次启动时在其中物化原生插件。工作区之外的任何其他内容都不会被改动。

构建出的 RPM 在磁盘上为 56 MiB，安装后为 267 MiB——几乎全部是运行时二进制文件，它是一个 Node.js 单文件应用程序，携带了整个插件闭包。它被有意以未剥离（unstripped）的方式打包：剥离它会破坏内嵌的文件系统，结果会导致段错误（参见 docs/packaging-notes.md）。

工作原理

上游以两种方式发布 DeepSeek Harness：一种是需要系统 Node.js 的 npm 依赖树，另一种是 PyPI wheel deepseek-harness-runtime-bin 中的按平台划分的单文件运行时。本仓库打包的是第二种，因为它在 Fedora 上提供了与官方 Windows/macOS 构建在其他平台上相同的下载即运行体验——无需工具链，安装时无需解析依赖。

scripts/versions.env          pinned release + per-target URL/SHA256
│
├─ scripts/build-rpm.sh ──► rpmbuild ──► deepseek-harness-.fc44.x86_64.rpm
│        spec 从 wheel 中提取 deepseek_harness_runtime/runtime/*
│
└─ scripts/build-portable.sh ──► dist/deepseek-harness--.tar.gz|.zip

spec 是磁盘上最终落地内容的唯一事实来源，并且在没有本仓库脚本的情况下，它仍可独立用于 COPR 或 rpmbuild。它直接从经过校验和固定的 wheel 中提取载荷，因此 RPM 所发布的字节与上游发布的字节完全一致。

仓库布局

packaging/rpm/          RPM 资源：spec、启动器、桌面条目、AppStream、man 手册页、overlay、图标
packaging/portable/     Windows/macOS 启动器和便携包 README
scripts/versions.env    唯一事实来源：版本 + 5 行目标 URL/SHA256
scripts/fetch-runtime.sh    下载并校验固定的 wheel（带缓存，会重新校验）
scripts/build-rpm.sh        构建二进制 RPM / SRPM / 从 SRPM 重建
scripts/build-portable.sh   为任意目标组装便携包
scripts/smoke-test.sh       解包已构建的 RPM 并端到端验证其可运行
scripts/lint.sh             spec↔versions 漂移、不变量、shell/desktop/AppStream 检查
docs/                   设计、打包约束、跨平台说明、测试

要求

* 构建 RPM — Fedora（已在 Fedora 44 上测试）：rpm-build、unzip、
desktop-file-utils、appstream。构建需要约 1 GiB 可用空间，以及
几分钟来处理 262 MiB 的载荷。
* 运行它 — Fedora 40+ / 任何 glibc ≥ 2.28 的 x86_64。bubblewrap（硬
依赖：首选沙箱后端）和 xdg-utils（打开浏览器）会被自动拉入。pnpm
仅在 dsh plugin 时推荐使用。
* 构建便携包 — Linux 或 macOS，需具备 curl、unzip、tar；
Windows 目标还需要 zip。

跨平台

相同的固定 wheel 机制可为五个上游目标生成便携包：

| 目标 | 产物 |
| --- | --- |
| linux-x64 | RPM，或 dist/-linux-x64.tar.gz |
| linux-arm64 | dist/-linux-arm64.tar.gz |
| macos-arm64 | dist/-macos-arm64.tar.gz（可双击的 DeepSeek Harness.command） |
| macos-x64 | dist/-macos-x64.tar.gz |
| windows-x64 | dist/-windows-x64.zip（dsh.cmd） |

$ make portable TARGET=windows-x64

关于哪些内容已验证、哪些尚未验证，请参阅 docs/cross-platform.md。

此处规避的已知上游问题

上游 0.1.5rc1 存在一个缺陷，导致每一个随附的 profile 都无法启动：
运行时闭包缺少对等包
@deepseek-ai/dsh-session-title-llm，而
@deepseek-ai/dsh-session-title-first-prompt-llm 在加载时会导入该包。

打包的 overlay 禁用了那一行，回退到非 LLM 的会话
标题。其他一切均未改动。
* scripts/smoke-test.sh --probe-overlay 会断言该规避措施仍然必要，
这样未来修复后的版本会明确失败，而不是留下无用负担。
* 设置 DSH_PACKAGED_PATCH=0 可在不使用 overlay 的情况下启动。
docs/packaging-notes.md 记录了这一点以及打包过程中发现的所有其他非显而易见的约束，包括最重要的一条：运行时绝不能剥离——rpmbuild 默认的 brp-strip 会破坏嵌入式文件系统，导致生成的二进制文件发生段错误。

打包新的上游版本

1. 更新 scripts/versions.env：DSH_RUNTIME_VERSION、DSH_CLI_VERSION、
DSH_RPM_VERSION 以及目标行（名称、SHA256、URL）。
2. 在 packaging/rpm/deepseek-harness.spec 中同步版本宏
（Version:、%global pypi_ver、%global cli_version、Source0）。
3. make lint && make rpm && make smoke -- --probe-overlay。

如果 spec 和 versions.env 不一致，make lint 会失败，因此第 2 步不能只做一半。如果 overlay 探测现在通过了，说明上游修复了闭包：删除
packaging/rpm/00-packaged-workarounds.yml，从 spec 中移除 Source5 行及其安装步骤，并移除启动器的注入逻辑。

故障排除

dsh 退出时发生段错误或提示 "cannot execute binary file"。 运行时被剥离了。确认 spec 仍然禁用了 __brp_strip* 并重新构建。

启动失败并提示 ERR_MODULE_NOT_FOUND: @deepseek-ai/dsh-session-title-llm。
overlay 未应用——检查
/usr/libexec/dsh/patches/00-packaged-workarounds.yml 是否存在，以及
DSH_PACKAGED_PATCH 是否未设置为 0。

启动失败并提示 ENOENT: mkdir '.../.cache/pkg/...'。 $HOME（或
$XDG_CACHE_HOME）不可写；运行时需要在首次启动时用它来实体化原生插件。

浏览器显示 dsh web authentication required。 Web UI 位于浏览器信任围栏之后：普通请求会得到 401，你必须使用 dsh web 打印的带令牌 URL（它会为你打开）。请通过桌面条目或
dsh web 启动它，不要直接访问端口。

许可证和商标

此处的打包采用 MIT 许可证（见 LICENSE）。捆绑的运行时是上游的
MIT 许可产物，未经修改地重新分发。DeepSeek、DeepSeek 鲸鱼标志以及 Harness/DSH 是其各自所有者的商标，仅用于标识所打包的软件。