Nexus-Aethra/DSHBox

DSH Box

受管理的 DeepSeek Harness 桌面运行时 —— 在你自己的机器上运行、隔离并扩展多个 DeepSeek Harness 环境，无需浏览器标签页。

DSH Box 是一个使用 Tauri 2 构建的轻量级桌面外壳，用于安装、启动和管理相互独立的 DSH 容器（Container） —— 每个容器都有自己的 DSH 版本、配置文件、插件、技能、工作区和日志 —— 并在内嵌的 WebView 中渲染它们。

亮点

- 隔离的 DSH 容器 —— 并排安装多个 DSH 版本，并为每个项目创建独立的容器。每个容器都有自己的配置文件（web / headless / 自定义）、工作区、插件集和宿主进程，因此实验之间绝不会相互污染。
- 内嵌 WebView，无需浏览器 —— DSH 前端在由 DSH Box 管理的原生 WebView 窗口中打开。无需端口转发，无需复制粘贴 URL，也没有标签页杂乱。
- 零依赖安装 —— 每个发行版都捆绑了私有的 Node、npm、pnpm 和 Git（Windows）运行时。无需系统 Node，无需手动配置工具链，无需折腾 PATH。由 Git 支持的 Boxfile 源（github.com/owner/repo:tag）通过 DSH Box 洁净室环境中的受管理二进制文件进行解析 —— 宿主机的 ~/.gitconfig 绝不会泄漏到构建中。在 Linux 上，DSH Box 使用你的系统 Git（apt install git），同时仍将其配置隔离在运行时目录下。
- 内置版本管理器 —— 浏览来自 deepseek-ai/deepseek-harness 的 DSH 发行版，一键安装或卸载任意标签，并为每个容器固定一个版本。
- Boxfile / 密封模板流水线 —— 用一个小型声明式 .dsh 脚本（FROM + PROFILE + ADD plugin|skill|data）描述容器；dshbox build 生成可复用的源配方，dshbox run  在最终容器目录中一次性准备好它。参见架构 → Boxfile。
- 可移植的已构建模板 —— 构建 Boxfile 会将其插件、技能和数据载荷物化到模板中。容器会收到自己复制的载荷，因此它们不依赖于工作区路径、pnpm 链接或可变的扩展仓库。
- Windows 优先的运行时恢复 —— 在 Windows 上，DSH Box 可在依赖已物化后从首次运行的 pnpm junction 校验失败中恢复，并在 Host 启动前立即分配一个新的回环端口。临时的回环绑定失败会被重试，而无需重建前端。
- 容器内智能体感知 —— DSH Box 会向每个容器注入一个 dsh-box-context 插件，使会话内的智能体能够看到 paths.dshboxHome 和 paths.dshboxCli，即使它没有继承一个合理的 PATH，也能管理 DSH Box（容器、模板、插件）。
- 扩展与技能仓库 — 从 GitHub URL、本地目录或 tarball 导入插件和技能，然后一键安装到任意容器的配置文件中。技能会自动归类到容器的技能根目录。
- 整合包（Bundle）工作流 — 将任意插件和技能组合成一个命名的整合包，然后通过两种方式导出：
- 快速导出：来自 GitHub 的条目保留为 URL，使归档文件保持极小体积。
- 完整导出：所有内容打包成一个可移植的 .tar.gz。
- 整合包可以重新导入（名称冲突时你可选择覆盖或保留）并安装到任意容器 — 插件进入配置文件，技能自动归类。
- 智能后台任务 — 每个长时间操作（安装、启动、重建、导入、导出）都作为可见的排队任务运行，带有实时滚动日志、取消/重试/删除以及历史分页。不会有任何操作让人感觉“卡死了”。
- 双模式 RPC + 实时事件流 — 守护进程掌控所有状态变更，并通过单一的 POST /rpc（同步或异步 — 由守护进程决定）和长期存活的 GET /events?token=… SSE 流对外暴露。CLI、UI 和外部代理都与相同的端点通信；UI 页面不包含任何业务逻辑。
- 网络友好 — 自动为 GitHub 克隆检测代理，可配置 GitHub 镜像，以及用于 DSH 内部安装的 npm registry 镜像。
- 后台服务与托盘 — 一个小巧的 dshboxd sidecar 保持一切井然有序，系统托盘图标让你无需保持主窗口打开即可控制它。
- 轻量设计 — 基于 Tauri，因此安装包很小，内存占用远低于 Electron 替代方案。
- 双语 UI — 英语和简体中文，可在设置中切换。

安装

从本仓库的 Releases 页面下载适用于你平台的安装程序：

| 平台 | 产物 | 说明 |
|---|---|---|
| Windows (x64) | dshbox__x64_.msi | 附带捆绑运行时和 sidecar 的 MSI 安装程序 |
| Linux (x64) | dshbox--amd64.deb | Debian/Ubuntu 软件包 |
| macOS (arm64) | dshbox--arm64.dmg | Apple Silicon |

从 Releases 页面获取最新版本 — 产物名称遵循 -- 约定，可能因版本而异。其他格式（.msi、.rpm、.AppImage）在支持的情况下按版本生成。

Windows 上无需运行时前置条件 — 捆绑的 Node/npm/pnpm/Git 运行时随安装程序一同分发。Linux 需要系统 Git（apt install git 或你的发行版等效命令）；其配置按运行时目录隔离，因此你的主机 ~/.gitconfig 永远不会被 DSH Box 构建读取。

快速开始

1. 启动 DSH Box，并在提示时选择一个可写的运行时目录（所有 DSH 数据都存放在那里）。
2. 打开 Resources → DSH Versions → Load versions，然后安装你想要的 DSH 标签。
3. 打开 Resources → Templates，然后拉取一个官方 DSH 模板，或从 Boxfile 构建一个可复用模板。
4. 打开 Container → 从该模板创建一个 Container（名称和配置）。
5. 首次创建会在其最终目录中准备 Container（离线依赖安装、本地插件、前端构建）。按 Start —— DSH Box 会启动该已准备好的副本，并在嵌入式 WebView 中打开 DSH UI。
6. 使用 Resources 导入插件/技能、组装 bundles，或创建 Boxfiles 以生成可复用的、启用插件的模板。

Tray

应用在关闭时会最小化到系统托盘。使用托盘菜单可打开窗口，或启动/停止/重启 dshboxd 后台服务。

Architecture

DSH Box 将 Tauri desktop shell、一个无框架的 Rust workspace、一个后台 daemon（dshboxd）以及一个小型 React 前端分离。这种拆分的存在是为了让所有业务逻辑——插件获取、容器生命周期、模板解析、后台任务——都可以在没有 UI 的情况下测试，并且让 CLI 或外部 agent 能够驱动与 UI 相同的流程。

Layered components

| Layer | What lives here | Why |
|---|---|---|
| Frontend (React 18 + Vite, src/) | 页面、组件、useTaskQueue/useContainers/useResources/useSettings hooks。无业务逻辑 —— 页面发起 RPC 请求并对 daemon SSE 事件作出反应。 | 保持 Box UI 轻量，并让任何客户端（UI/CLI/agent）共享同一代码路径。 |
| Desktop shell (Tauri 2, src-tauri/src/) | 浏览器窗口、托盘、Tauri IPC 适配器。监听 127.0.0.1 上 daemon 的 loopback HTTP 服务器。所有实际工作都通过 HTTP RPC 委托给 dshboxd。 | 状态变更只有一个事实来源 —— UI 和 CLI 不会产生偏差。 |
| Daemon (src-tauri/crates/dshboxd) | 长期运行的后台服务。拥有队列、数据存储、模板索引、容器注册表和 SSE 事件总线。单一 HTTP 入口点（POST /rpc）以及 GET /events?token=…。 | 后台工作（安装、重建、卸载）在桌面窗口关闭后仍能继续。 |
| Crate workspace (src-tauri/crates/) | 无框架的 Rust crates：box-foundation、box-runtime、box-scheduler、box-state、box-toolchains、box-dsh-versions、box-containers、box-extensions、box-image、box-template-core、box-data-scheduler、box-logger、box-dsh-context、box-server-core、box-api、box-client。 | 纯函数 + 单元测试；只有顶层 dshbox 二进制文件和 dshboxd 链接 Tauri/HTTP。 |

依赖方向是单向的：foundation / runtime / scheduler / state → 功能 crates → Tauri/desktop 适配器。功能 crates 不依赖 Tauri，也不依赖彼此的可变状态。

Daemon — dual-mode RPC + SSE event stream
每个 UI / CLI 操作都会以 JSON 请求体 {"method": "...", "params": {...}, "token": "..."} 的形式落到 POST /rpc 上。守护进程的分发表会为每个处理程序决定是同步返回 JSON（List templates、Read settings 等），还是异步将任务入队给 worker（Install、Build、Start container、Rebuild、Uninstall 等）。异步处理程序会立即返回一个 TaskRecord；客户端订阅 GET /events?token=… 以接收 task:stage / task:log / task:finished / resource:added|updated|removed 事件。

这意味着同一个 HTTP 接口服务于所有消费者——桌面应用的 Tauri IPC 处理程序、CLI（dshbox rpc …），以及通过 curl -d '…' http://127.0.0.1:7923/rpc 调用的外部代理。不存在“客户端回退”或本地状态分歧：守护进程的资源映射和任务队列是唯一的事实来源。

Boxfile 与已构建模板流水线

boxfile（.dsh）是描述你想要实例化的 Container 的声明式脚本。dshbox build 会将其解析为一个密封的模板配方：不含 node_modules 的物理 Harness 源码，加上其 ADD 指令所需的 profile、本地插件产物、skills 和数据。dshbox run  会将其复制到最终的 Container 目录，执行离线安装，添加本地产物，并构建一次；之后的启动不会执行这些步骤中的任何一步。

完整语法见 docs/template-system.md；规范参考示例（涵盖每一种源形态）见 examples/boxfile-plugin-chains.dsh。以下是最简形式：

FROM github.com/deepseek-ai/deepseek-harness:latest
PROFILE web
NAME my-team

ADD plugin github.com/owner/cordis-plugin-foo:1.2.3
ADD plugin npm:@linxin666/dsh-web-ui-all
ADD plugin ./plugins/secret
ADD skill team-conventions

| 指令 | 是否必需 | 说明 |
|---|---|---|
| FROM  | 是（恰好一次） | GitHub 短形式（github.com/owner/repo[:tag|@ref]），或本地模板名称（例如 web-base）。最多支持四级模板继承。 |
| PROFILE  | 是（恰好一次） | 目标 DSH profile（web、headless 等）。 |
| NAME  | 否 | 默认为脚本文件的主文件名。 |
| VERSION  | 否 | 默认为 latest。 |
| LABEL key=value | 可重复 | 附加到已构建模板上的自由形式元数据。 |
| DEF  @ | 可重复 | 定义一个路径别名，可在后续 ADD 行中作为 @ 使用。 |
| ADD plugin\|skill\|data  [@] | 一个或多个 | 你希望烘焙进由该模板生成的每个 Container 中的资源。 |
| CP  [@] | ADD plugin 的别名 | 为向后兼容而保留。 |

接受四种形态：
1. GitHub 短形式 —— github.com/owner/repo[:tag|@ref]。GitHub 分支通过 pnpm pack 以及和 npm 相同的获取/导入流水线进行解析；带标签的 release 会成为 ParsedSource::Github 上的一个 ref_。
2. Tarball — https://…/pkg.tgz、./relative.tgz、/abs/path.tgz。任何以 tarball 形式获取并解包的内容。
3. 本地目录 — ./plugins/foo / /abs/path/foo。直接导入（无需归档往返）——适用于正在开发中的插件。
4. 裸名称 — name[@version] 或 @scope/name[@version]，用于已在 Repository 中的插件。
5. 显式前缀 — git:…（通过 libgit2 克隆，无需猜测）和 npm:…（注册表规范转发给 pnpm）。

:latest 标签和显式的 latest 关键字可以互换；两者都固定到 harness 仓库的主分支。

每个 ADD 的存储方式很重要：
- ADD plugin — 源被导入到共享的 Repository 中，作为不可变的本地 artifact.tgz，由密封配方记录，然后仅在准备 Container 时按其最终路径添加。没有正在运行的 Container 拥有绝对仓库路径或运行插件依赖安装。
- ADD skill 和 ADD data — 快照到数据存储（/data//），在构建的模板中物化，并复制到 Container 配置文件中。
- 捆绑的 dsh-box-context 插件（@deepseek-ai/dsh-box-context）会自动复制——你无需 ADD 它。

dshbox build 写入一个按摘要寻址的密封模板。然后 dshbox run ：
1. 解析模板的 FROM 链（最大深度 4），
2. 创建 /instances//{profile,workspace,state,logs}，
3. 将模板中物化的 plugins/skills/data 复制到配置文件中，
4. 在宿主启动前立即分配一个回环端口，
5. 从 Container 的 Harness 副本启动捆绑的 pnpm dsh web 并等待就绪，
6. 将 paths.dshboxHome + paths.dshboxCli 写入快照，以便容器内的 agent 可以找到 CLI。

完整的存储、事务和迁移契约见 docs/specs/prepared-template-runtime.md。这是一次 schema 破坏性变更：新的构建不再使用旧的共享 runtimes//source 布局。

数据调度器和引用计数

Container、模板、插件和技能包都共享一个按 id 索引的单一 resource-map.json。删除流程为 soft-delete → fast queue → permanent delete；Container ↔ 模板 ↔ 插件之间的引用保持同步，因此仍在使用中的实体永远不会被垃圾回收。完整设计见 docs/specs/data-scheduler.md。

日志

tracing + tracing-subscriber 将结构化日志输出到 /logs/.log（按日滚动）并镜像到 stderr。使用 RUST_LOG 进行过滤，例如 RUST_LOG=info,dshboxd=debug,box_template_core=debug。

技术

| 层 | 技术栈 |
|---|---|
| 桌面外壳 | Tauri 2、Rust（src-tauri/ 下的 Cargo workspace） |
| UI | React 18、TypeScript、Vite |
| 后台服务 | dshboxd sidecar（单一 HTTP 入口：POST /rpc + GET /events） |
| 捆绑运行时 | Node / npm / pnpm / Git-仅限 Windows（按平台归档，SHA-256 固定于 runtime-lock.json） |
| 目标平台 | Windows x64/arm64、Linux x64/arm64、macOS x64/arm64 |

从源码构建

前置条件：Node.js 20+ 及 pnpm、适用于你平台的 Tauri 2 前置条件，以及 7-Zip（runtime:prepare 解压 Windows PortableGit 归档时需要用到一次——从 7-zip.org 安装，或执行 apt install p7zip-full，并确保 7z 在 PATH 中）。7-Zip 仅是构建期工具；它永远不会随安装程序分发。

pnpm install
pnpm runtime:prepare    # fetch + verify + extract the bundled Node/pnpm/Git runtime
pnpm server:prepare     # build the dshboxd sidecar
pnpm tauri dev          # run in development

runtime:prepare 在解压前会根据 runtime-lock.json 中的 SHA-256 固定值校验每个归档，并在不匹配时中止。如果缺少 7-Zip，Git 步骤会被跳过并给出警告（Node/pnpm 仍会准备）；安装后重新运行即可。

发布捆绑包（按平台）：

pnpm bundle:windows     # Windows MSI installer
pnpm bundle:linux       # Linux .deb
pnpm bundle:macos       # macOS .dmg

运行测试套件：

cd src-tauri && cargo test --workspace

仓库布局

src/                       React/TypeScript management UI
src-tauri/                 Rust workspace + Tauri shell
crates/                  focused, framework-free crates
box-foundation         config, paths, JSON persistence
box-runtime            absolute-path process exec
box-scheduler          persisted task queue + locks
box-state              ResourceStateManager (read model)
box-toolchains         bundled Node/pnpm resolver
box-dsh-versions       DSH GitHub catalogue (harness tag + installs)
box-containers         Container metadata + active Host registry
box-extensions         repository plugin/skill scan + transfer
box-image              .dsh parser, manifest v6, gzip tar I/O
box-template-core      root/common template install/uninstall core
box-data-scheduler     soft-delete + dual-queue async hard-delete
box-logger             tracing init + daily-rolled log files
box-dsh-context        dsh-box-context plugin (paths.dshboxHome/dshboxCli)
src/desktop/app/         domain modules (containers, extensions, tasks, …)
examples/                  boxfile.dsh + plugin-chains example
docs/                      HANDOFF.md, architecture.md, template-system.md,
specs/, design/, notes/

boxfile 语法的权威参考是 docs/template-system.md；镜像/已构建模板的设计位于 docs/specs/image-build.md；完整的 RPC + 事件流接口位于 docs/design/rpc-and-events.md。

许可证

专有——许可条款请咨询仓库所有者。

© Nexus-Aethra