klarkxy/dsh-spaces

DSH Spaces

兼容 DSH 应用程序内的多空间插件。你自己的桌面端是可选的发行方式，而非必需的客户端。

当前定位与受支持的适配器：宿主嵌入契约。此分支为普通回环 Web 宿主添加了就地侧栏；官方桌面端自定义协议适配器和第三方原生适配器仍未经验证。

蓝图用户与作者： 请从 BLUEPRINT.md 开始，这是用于以 JSON 或可复制代码共享插件组合与配置预设的一级指南和格式契约。实现与验收状态：蓝图工作记录。

从 GitHub Releases 下载桌面端构建。当前工作台契约：docs/workbench.md、tasks/workbench-contract.md、tasks/merge-contract-v2.md。故障策略：docs/let-it-crash.md。合并验收：tasks/merge-execution.md。历史恢复文档保持其历史性质——请从 tasks/history-recovery.md 开始，不要将其视为当前的门禁。

插件安装：标准安装指南。运行 pnpm run pack:plugin，使用官方 CLI 安装打印出的 tarball，然后在普通 DSH Web 中执行 工作台 → 初始化 Spaces。原应用程序保持原位；同一窗口显示空间侧栏和所包含的管理器。默认 CLI 版本：官方 0.1.7-alpha.1，为新安装固定。本地插件不在 npm 上。

打开桌面端会连接到健康的工作台，或在无服务且运行时已就绪时启动一次。首次环境安装会自动继续进入工作台。服务已停止不是错误；真正的启动失败和所有权冲突仍会可见，且不会自动重试或接管锁。

一个 Supervisor 拥有 Home 运行权限和管理写入权。桌面端是本地外壳（窗口、托盘、首次 Node/pnpm/CLI 准备、连接）。工作台页面在浏览器和沙盒化桌面视图中是同一个 spaces-hub UI。普通空间获得的是视图桥接，而非第二个管理器。

DSH Spaces 不承诺任意插件组合都能运行。失败会被记录并报告。Spaces 不会恢复失败的环境。

中文说明见下方 中文.

为什么

官方 DSH 配置文件隔离的是插件栈，而非会话或工作区分组。Spaces 将每个工作台的会话、存储和本地凭据保存在 $DSH_HOME/hub// 下；alpha 设置通过原生 ConfigEditor 持久化到 profiles//cordis.patch.yml。共享的 LLM 连接位于 Home 级目录中。命名空间永不导入根 Home 的 settings.yaml，也不写入默认的 web 配置文件。参见 alpha 迁移与验收记录。
web 是唯一的 home 配置文件。Spaces 从不写入其隔离补丁。管理器配置文件为 spaces-hub（若被占用则加后缀）。普通空间安装 @dsh-spaces/view-bridge。将完整的 @dsh-spaces/plugin 安装到普通空间属于误装。

安全

- 无 Spaces 遥测。 模型调用和插件使用各自的网络设置。
- web 隔离保护。 不覆盖存储根目录，不迁移聊天记录。
- 写入前备份。 cordis.patch.yml.bak- 是提交前副本，并非产品还原。
- 原子写入。 同卷临时文件 + 重命名。准备失败不会替换先前的文件。
- 启动门禁。 先执行 dsh --profile  --dump-config；缺失或错误的行 id 会拒绝启动。
- 开发沙箱。 未打包的构建使用 .sandbox/dsh-home。测试拒绝真实的 ~/.dsh。

每个 Home 一个 Supervisor。当其健康时，桌面端和浏览器连接到该进程。关闭标签页或退出桌面客户端不会停止服务。停止所有空间和停止服务（service.shutdown）是分开的、显式的操作。未注册的手动 DSH 进程是一个已知缺口 —— 外部发现。

故障

参见 docs/let-it-crash.md。错误操作为查看错误详情和复制脱敏日志。用户启动 / 停止 / 重启 / 安装 / 卸载 / 配置仍属普通管理。公共还原 API 会显式失败。剩余未运行的 CLI/浏览器项目：tasks/q-coverage.md。

桌面 shell 更新、Spaces 组件更新和官方 DSH 运行时升级是不同的流程。一个从未成为当前的候选版本是失败的准备，而非还原。在提交指针切换后，后续故障会就地报告。

当前架构（本分支）

协议 2。管理状态携带 protocolVersion、serviceEpoch、revision 和 availability。普通写入使用 { serviceEpoch, expectedRevision }。旧协议、缺失上下文或 epoch/revision 不匹配会被拒绝。不存在公共的 controller.acquire / controller.release / recovery.* / snapshot.restore / config.restore。

用于 supervisor、jobs、products 和 upgrade 的共享 Node 模块位于 src/adapters/node 下（从 src/main 移入）。仅 Electron 的代码保留在桌面 shell 中。

构建在 lib/supervisor/manifest.json（schemaVersion 2）中列出五个不可变组件：Supervisor、manager plugin、view-bridge、llm-bridge、installation worker。冷启动和打包消费该组。Bootstrap 传递 --component-payload 以及同一组的 plugin / view-bridge / llm-bridge 产物，外加 --snapshot-worker。

--snapshot-worker 对于普通 Home 快照和剩余的安装 IO 仍然是必需的。运行时安装已被提取；该 worker 不是还原产品。
在用户确认组件升级后，旧服务会暂存候选版本、停止其拥有的进程，并将 Home 锁交给一次性启动器，由后者选择新载荷并启动一次 Supervisor。验收覆盖真实的组件交接、标准插件安装，以及一个打包的 Windows 桌面端与 Chromium 共享活动任务。确切构建版本和平台限制见验收记录。

要求

- 参与贡献需 Node 24；首次桌面启动可安装受管 Node、pnpm 和 DSH CLI
- 包源：中国（npmmirror）或官方（npmjs / nodejs.org）
- 首次安装使用 @deepseek-ai/dsh@0.1.7-alpha.1；已选定的现有运行时会显式升级
- Workbench 写入门禁接受任何确切已安装的 DSH CLI 版本。标签不是绑定版本。本仓库构建的插件对等依赖 SDK 0.1.7-alpha.1；这不是 CLI 允许列表

开发

npm install
node scripts/setup-sandbox.mjs
npm test
npm run test:llm
npm run typecheck
npm run validate:isolation
npm run validate:llm:secrets
npm run dev
npm run dev:web

npm run dev（或 pnpm run dev）会构建当前组件组，然后针对现有的 .sandbox/dsh-home 打开 Electron。获取桌面实例锁后，它会将已安装内容与构建进行比较，通常会停止空闲的较旧服务、安装当前管理器包，并选择匹配的 Supervisor。内容未变化则跳过安装。空间数据保持原位；默认 web 配置文件不会被修改。Electron 浏览器存储使用 .sandbox/electron-user-data；DSH_SPACES_HOME 和 DSH_SPACES_USER_DATA 可覆盖开发路径。

在启动另一个构建之前，请退出先前的开发命令；在更新组件之前，通常应停止活动的普通空间。已打开的开发窗口、活动任务、归属不明确或未完成的维护都会导致显式拒绝。更新失败会保留证据且不会重放。管理器插件更改会在下一次显式 dev 启动时生效；这不是插件热重载。npm run test:development 会检查此工作流。

npm run dev:web 会重新创建 .sandbox/dsh-web-home，将此检出项的插件安装到官方 web，并启动 dsh web。在浏览器中点击 初始化 Spaces / Initialize Spaces。Supervisor 标志：docs/workbench.md。当应用使用相同的沙箱配置文件时，不要运行隔离/生命周期脚本。活动台账：tasks/todo.md。

构建

npm run build
npx electron-builder --win   # or --mac / --linux

安装程序会生成到 release/。本地 win-unpacked 目录树是构建产物，不是 GitHub 发布版本。

许可证

MIT。见 LICENSE。

DSH Spaces (中文)

安装在兼容 DSH 应用内的多空间插件：左侧切空间，右侧使用 WebUI，不要求打开专属客户端。

新定位及支持边界见 宿主嵌入合同。本批支持普通 loopback Web 宿主内的空间栏；官方 Desktop 自定义协议与第三方原生适配仍待实现、验收。
使用或开发蓝图能力，请先阅读根目录 BLUEPRINT.md。 蓝图以 JSON 或分享码分发插件组合与配置预设。实现与验收状态见蓝图实施记录。

桌面安装包见 GitHub Releases。现行工作台说明：docs/workbench.md，合同：tasks/workbench-contract.md、tasks/merge-contract-v2.md。故障政策：docs/let-it-crash.md。本次合并验证见 验收记录。历史恢复文档只作追溯，从 tasks/history-recovery.md 进入，不是现行门槛。

打开桌面会连接健康的工作台；确认没有后台且运行环境就绪时，正常启动一次。首次安装环境完成后会自动进入工作台。尚未启动不再显示成错误；真正的启动失败与运行权冲突仍明确报告，不自动重试或接管锁。

一个 Supervisor 持有 Home 运行权和管理写入。桌面是本地壳（窗口、托盘、首次 Node/pnpm/CLI 准备、连接服务）。浏览器和桌面沙箱 view 使用同一套 spaces-hub 工作台。普通空间只装 view-bridge。

插件组合可以失败。Spaces 记录并说明已知原因或明确未知，不提供自动或手动恢复。

数据规则

- web 是唯一根 profile，使用官方默认 $DSH_HOME/sessions/ 与 $DSH_HOME/storages/，永不打 patch。
- 其它工作台的会话、存储、settings 和本地凭据在 $DSH_HOME/hub//。
- 共享的是 Home 级 LLM 连接库，不是整份 settings.yaml。
- 管理工作台是专用 profile spaces-hub。普通空间只装 @dsh-spaces/view-bridge。

现行行为

协议版本 2。变更带 serviceEpoch 与 expectedRevision。公开合同没有 controller.acquire / release、没有恢复命令。关标签或退出桌面客户端不停止后台。停止全部空间和停止服务（service.shutdown）是两个独立操作。

通用 Node 模块在 src/adapters/node。构建清单覆盖 Supervisor、管理插件、view-bridge、llm-bridge、安装 worker 五组件。启动仍需要同组 --snapshot-worker，运行时安装 IO 已抽出。组件升级采用一次性启动器交接，新管理器就绪后才确认成功。本次源码测试、标准插件、组件更新和桌面包的验证范围见 合并验收记录。

npm run dev / pnpm run dev 先构建当前组件，再打开 Electron，沿用 .sandbox/dsh-home。取得桌面单实例锁后，按内容比较已安装组件；有变化时正常停止空闲旧服务、安装管理插件并选择匹配的 Supervisor，没有变化则跳过安装。保留空间数据，不修改默认 web。开发窗口的浏览器数据位于 .sandbox/electron-user-data，可通过 DSH_SPACES_HOME / DSH_SPACES_USER_DATA 指定开发目录。

启动下一次开发构建前，退出上一次开发命令；更新组件前正常停止运行中的普通空间。已有开发窗口、执行中的任务、归属不明或中断维护都会明确拒绝；失败留证，不续跑。管理插件源码改动在下一次主动运行 dev 时生效，不提供插件热重载。定向验证：npm run test:development。

npm run dev:web 每次重建 .sandbox/dsh-web-home，把当前仓库插件装进官方 web，再启动 dsh web。浏览器里点 初始化 Spaces。监督进程参数见 docs/workbench.md。活动账本：tasks/todo.md。