# DeepSeek Harness · Linux 桌面端 [English](README.md) | 中文 > **本仓库说明**:这是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的下游社区项目,专注于 Linux 桌面端打包适配。官方桌面端仅提供 macOS / Windows,本仓库在此基础上新增 Linux(x64 / ARM64)的 AppImage / .deb / .tar.gz 打包与自动构建。agent 内核、插件体系等核心功能均来自上游,本仓库不做修改。 DeepSeek Harness(`dsh`)是由 [DeepSeek AI](https://deepseek.com) 开发的开源 agent harness(智能体框架 / AI 智能体)。 它既可以通过 `npx @deepseek-ai/dsh web` 在本机一键拉起 Web UI 自托管运行,也可以在 Linux(Ubuntu 24.04 / Debian / 树莓派 5 / ARM 服务器)上打包成桌面客户端(AppImage / `.deb` / `.tar.gz`)使用 —— 一个开源、可本地部署的 DeepSeek 客户端与 AI 助手框架。 它构建于**一切皆插件**的架构之上,由 [Cordis](https://github.com/cordiverse/cordis) 驱动,其设计参见论文 [_A Programming Paradigm for Spatiotemporal Composability_](https://arxiv.org/abs/2608.25512)。 文档:[https://deepseek-harness.github.io/deepseek-harness/](https://deepseek-harness.github.io/deepseek-harness/) ## 开发者预览 DeepSeek Harness 处于 _开发者预览_ 阶段,正在快速迭代。**未来将出现破坏兼容性的变更。** 运行本项目前,请阅读[安全说明](SAFETY.zh.md)。 ## 运行 ### 通过 `npm` 运行 安装 `Node.js`,然后运行: ```sh npx @deepseek-ai/dsh web ``` 该命令默认会在 `http://127.0.0.1:3080` 启动 Web UI,本机启动时还会用默认浏览器打开页面。通过 SSH 启动时只打印宿主机 URL,因为本地转发地址由 SSH 客户端或编辑器持有。传入 `--no-open` 可仅运行服务器而不打开浏览器。详见 [Web UI 指南](docs/user/guide/index.zh.md)。 ### 从源码运行 如需从仓库源码运行: ```sh git clone https://github.com/Zhou-Yujing114514/deepseek-harness-linux.git cd deepseek-harness-linux pnpm install pnpm run build pnpm dsh web ``` `pnpm run build` 会准备仓库产物。`pnpm dsh web` 会直接使用这些已构建产物,不会重新构建。 ### Linux 桌面端(本仓库新增) 桌面应用可在 Ubuntu 24.04(或兼容发行版)上打包,支持两种架构(x64/ARM64),每种架构产出三种安装格式(AppImage、Debian `.deb`、便携 `.tar.gz`): ```sh pnpm install cp apps/desktop/.env.linux.example apps/desktop/.env.linux # 然后填入发布配置 pnpm --dir apps/desktop run package:linux:x64 # x64(AMD/Intel):AppImage + deb + tar.gz pnpm --dir apps/desktop run package:linux:arm64 # ARM64:AppImage + deb + tar.gz ``` 打包 AppImage 时构建机需要 FUSE 2(`libfuse2`);`.deb` 打包需要 maintainer 字段(Linux 配置中已内置)。Linux 构建不做代码签名:自动更新走 `electron-updater` 的 AppImage 渠道,链路依赖 HTTPS 与 `nightly-linux.yml` 元数据、无签名校验,若要向第三方分发,这是需要评估的供应链环节。`.deb` 与 `.tar.gz` 作为同版本安装包一并发布。仓库内置 `Desktop (Linux)` 工作流可在原生双架构 runner 上一键构建。发布版本号、上传与各平台环境变量文件详见[桌面端打包说明](apps/desktop/README.md)。 ### 插件在 Linux 上的兼容性 官方桌面端只发布 macOS / Windows,本仓库是在上游基础上做的 Linux 移植,**agent 内核与插件体系均来自上游、本仓库不做修改**。因此第三方插件默认按 win/mac 编写,在 Linux 上可能出现"装得上但用不了",甚至完全不兼容。已知的三类边界: | 现象 | 原因 | 现状 | |---|---|---| | 插件装上后加载失败或静默失灵 | 插件声明 `os: ["darwin","win32"]`、只带 macOS 原生二进制、或要求更高的 Node 版本,而现有预检只校验 `engines.dsh` 与 peer 版本 | 用下面的诊断工具提前发现 | | 插件窗口"看得见但点不动" | 原生 Wayland 会话下,透明 / 置顶窗口无法由应用控制层叠与输入区域 | 用下面的兼容启动参数绕过 | | 读取本地图片时 Host 进程退出 | `sharp` / libvips 内嵌 glib 与 Electron 加载的系统 glib 冲突,进程内解码图片触发 SIGSEGV([#24](https://github.com/Zhou-Yujing114514/deepseek-harness-linux/issues/24)) | 尚未修复,需独立 Node 运行 Host 并调整打包,属于待评估项 | **先诊断,再逐个排查。** 诊断工具只读插件的 `package.json`,不加载插件代码、不修改任何文件: ```sh # 默认读取 $DSH_HOME/profiles/desktop;也可显式指定 profile 目录 node apps/desktop/scripts/plugin-linux-compat.mjs node apps/desktop/scripts/plugin-linux-compat.mjs --profile /path/to/profiles/desktop --target linux-arm64 node apps/desktop/scripts/plugin-linux-compat.mjs --json # 输出结构化结果,便于脚本处理 ``` `--profile` 指向的目录需包含 `package.json`(其 `dependencies` / `optionalDependencies` 列出已装插件)与对应的 `node_modules/`;还可用 `--target linux-x64|linux-arm64`、`--node <版本>` 指定目标平台与运行时。输出按"明确不兼容 / 需要人工确认 / 看起来可用"分组,并给出每条的原因。存在明确不兼容插件时退出码为 1。 全新的桌面 profile 通常只有 `dsh.profile.bundles`(应用自带的内置 bundle),`dependencies` 为空;这时报告会明确说明"没有第三方插件可诊断"并列出内置 bundle,**内置 bundle 不参与平台检查**,避免把空结果误读成扫描失败。第三方插件装进 profile 后才需要体检。注意:**静态检查只能判断能否装上/加载,不能替代真机运行验证**。 **Wayland 下插件窗口无法点击**时,用兼容参数走 XWayland 启动: ```sh ./deepseek-harness-0.2.1-rc.2-linux-x86_64.AppImage --ozone-platform=x11 # 或让辅助脚本判断会话类型并给出建议 node apps/desktop/scripts/linux-launch-compat.mjs ./deepseek-harness-0.2.1-rc.2-linux-x86_64.AppImage # 还要给 AppImage 传自己的参数时,必须用 -- 分隔,否则会被当成辅助脚本的选项而报 Unknown option node apps/desktop/scripts/linux-launch-compat.mjs ./deepseek-harness-0.2.1-rc.2-linux-x86_64.AppImage -- --enable-logging # 确认无误后真正启动;--exec 必须写在 -- 之前 node apps/desktop/scripts/linux-launch-compat.mjs --exec ./deepseek-harness-0.2.1-rc.2-linux-x86_64.AppImage -- --enable-logging ``` 辅助脚本默认只打印建议、不启动进程,加 `--exec` 才会真正带参数启动;`--exec` 与 `--` 的顺序不能颠倒,写反了 `--exec` 会被当成应用参数而不生效。代价是原生 Wayland 的分数缩放会失效(HiDPI 可能略模糊),且机器需装有 XWayland;因此**没有把它设为默认启动方式**。X11 会话无需此参数。 ## 社区与支持 - 通过 [GitHub Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions) 提交反馈或 bug 报告。 - 为你的插件仓库添加 [`dsh-plugin`](https://github.com/topics/dsh-plugin) 话题,便于被发现。 - 欢迎加入 DeepSeek Harness 企微群!扫描下方二维码填写入群问卷,小助手会定期发送入群邀请。
入群问卷 微信公众号
DeepSeek Harness 入群问卷二维码 DeepSeek Harness 团队微信公众号二维码
## 参与贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.zh.md)。 ## 开发 请先阅读[开发指南](docs/development.zh.md)与[架构文档](docs/architecture.zh.md)。 `pnpm run dev:web` 会在一个终端里完成构建、启动,并在源码修改时重建 client bundle;`make help` 列出 Web 与 Desktop 对应的 Make target。完整表格见开发指南的「应用命令」一节。 面向 agent:请遵循 [AGENTS.md](AGENTS.md)。 ## 引用 ```bibtex @misc{deepseek-harness2026, title={DeepSeek Harness: Everything is a Plugin}, author={DeepSeek-AI}, year={2026}, publisher={GitHub}, howpublished={\url{https://github.com/deepseek-ai/deepseek-harness}}, } ``` ## 如果你在搜索这些词 - **DeepSeek Linux** / **DeepSeek 桌面端 Linux** / **DeepSeek on Linux** - **DeepSeek 客户端下载** / **DeepSeek 桌面客户端** / **DeepSeek 安装包** - **DeepSeek AppImage** / **DeepSeek .deb** / **Ubuntu 安装 DeepSeek** / **Debian DeepSeek** - **树莓派 DeepSeek** / **ARM64 DeepSeek** / **DeepSeek Linux 安装** - **开源 DeepSeek** / **本地部署 DeepSeek** / **自托管 AI 助手** / **DeepSeek 智能体** > 说明:本项目是**桌面客户端**,模型能力由 DeepSeek 官方 API 提供,**不内置离线模型**,也不等同于"在本地跑模型";"本地部署 / 自托管"指的是客户端与 Web UI 部署在你自己的机器上。如需接入自托管或第三方模型,请在客户端内自行配置对应的 API 端点与密钥。 ## 许可证 [MIT](LICENSE) 第三方依赖及其许可证见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。