dsh-box-context/src-tauri/crates/box-dsh-context/dsh-box-context

一句话定位

把 DSH Box 容器自身的元数据（容器 ID、名称、DSH 版本、profile、工作区/插件/技能/日志路径以及凭据对应的环境变量名）以结构化形式注入宿主 DSH 的系统提示，使代理能稳定地"看到"自己所在的容器上下文，而不是把它当成普通叙述文字。

核心能力

• 注入容器结构化上下文：注册 dsh-box:container 这条 systemPrompt.context 区段，按 key = value 形式输出容器与路径信息，代理可直接读取
• 自动跟随容器变更：使用 fs.watch 监听 Box 写入的 JSON 快照文件，Box 重写时立即重渲染，无需重启 DSH
• 监听失败自动降级：监听器创建异常或失效时，切换为每 30 秒轮询重读，保证信息最终一致
• 凭据环境变量透出：把 <DSH_HOME>/.credentials.yaml 里各 provider 对应的环境变量名（不包含真实密钥）写入提示，供代理安全引用
• 越权写入约束：在提示中明确"项目/创建模式改动只在 paths.workspace、profile/插件/技能改动只在本容器内"，避免代理误改其它容器或系统路径
• 无客户端 bundle：仅 host 半，不在 WebView 端渲染任何 UI；Box 没有可扩展的 WebView 标签

技术实现

• 语言: TypeScript（ESM，tsdown 打包）
• 关键依赖: @deepseek-ai/cordis ^4.0.1（注册 systemPrompt context 服务）、@deepseek-ai/schemastery ^3.18.1（Config Schema 校验）、Node 内置 node:fs（readFileSync + watch）
• 架构模式: Cordis 插件；通过 package.json#dsh.bundle.patch 指向 cordis.patch.yml，Box 启动容器时由 Rust 端覆盖 contextFile/order 后让 DSH loader 把插件挂入 host；apply(ctx, config) 注册一个 ctx.systemPrompt.context(...) 区段 + 一个 fs.watch（或降级 setInterval）副作用，通过 ctx.effect(...) 绑定清理
• 入口文件: dsh-box-context/src/index.ts（主 apply + Config Schema）；配套 dsh-box-context/src/invariant.ts（占位 register，当前为空实现）；Rust 端常量与渲染器在 src-tauri/crates/box-dsh-context/src/lib.rs

适用场景

在使用 DSH Box 桌面端同时维护多个 DSH 容器（如不同 DSH 版本、不同 profile）的用户。每个 Box 容器启动时 Box 都会把它的身份和路径信息写到一个 JSON 快照，本插件负责把这张快照翻译成 DSH 代理能稳定读取的系统提示上下文，让代理明确知道"我当前在哪个容器、能改哪些路径、不应该动其它容器"。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Nexus-Aethra/DSHBox/src-tauri/crates/box-dsh-context/dsh-box-context

该安装命令适用于把插件作为独立 DSH 插件加载的场景。DSH Box 桌面端用户无需手动安装，Box 已自带并自动注入。

配置项

以上为插件集成层面字段；普通用户无需手动配置，DSH Box 桌面端在容器启动时会自动生成 patch 覆盖文件注入正确路径。

常见问题

Q: 我是 DSH Box 桌面端用户，需要单独安装这个插件吗？

A: 不需要。Box 桌面端在每次容器启动时由 Rust 端生成 patch 覆盖文件，自动把插件挂入宿主 DSH；单独从插件市场安装仅适用于脱离 Box 使用的研发或烟测场景。

Q: 容器信息多久会更新一次？

A: 默认使用 fs.watch 监听 JSON 文件，Box 重新写入时立刻重渲染；如果监听器因平台/编辑器行为（macOS FSEvents、Windows 原子重命名）创建或触发失败，会自动降级为每 30 秒轮询一次。

Q: 凭据密钥会不会出现在提示词里？

A: 不会。快照里 credentials.providers[*].apiKeyEnv 只携带环境变量名（如 MINIMAX_CN_API_KEY），真实密钥始终留在 <DSH_HOME>/.credentials.yaml，代理只能"知道有某个环境变量承载了密钥"。

Q: 卸载这个插件会有什么后果？

A: 它是 DSH Box 自带的桥接件，单独卸载会让 Box 启动容器时缺失容器上下文注入，Box 的多容器语义会受影响；正常用户场景不建议单独卸载。

Q: 这个插件有 Web 端 UI 吗？

A: 没有。README 明确说明 Box 没有可扩展的 WebView 标签页，所以只发布 host 半（Node 端），不打包任何 client bundle。

Q: 它和 Box 的 systemPrompt 配额有什么关系？

A: order=130 落在沙箱策略 110、审批策略 115、子代理委派 120 与 100–199 的工具指南带之间，刻意保留空位避免与已有权威段碰撞（详见 Rust 端 DEFAULT_ORDER 注释）。

上手难度

入门 — 仅需理解 JSON 快照路径与 systemPrompt 区段顺序两个概念，Box 用户完全无需手动配置。

已知问题与限制

• fs.watch 在 macOS FSEvents 与某些 Windows 编辑器（使用原子重命名）的场景下可能丢失事件，源码已通过 30 秒轮询回退兜底（src/index.ts:107-117）
• invariant.ts 是占位文件，目前 register() 为空实现；如果未来迭代引入跨 apply 生命周期的注册，需要替换其实现（src/invariant.ts:1-26）
• Box 启动时若生成的 patch YAML 缩进被 \ 行续行打平，会导致 DSH 启动失败（Rust 端 render_patch_yml 用 concat! 显式禁用行续行规避此问题，见 lib.rs:91-96）
• 凭据只透出环境变量名，若用户把密钥直接写在 JSON 快照里仍会被代理看到——该路径由 Box Rust 端保证只输出 apiKeyEnv，使用方需保持契约

Managed DeepSeek Harness desktop runtime — run, isolate, and extend multiple DeepSeek Harness environments on your own machine, no browser tab required.

DSH Box is a lightweight desktop shell built with Tauri 2 that installs, launches, and manages independent DSH Containers — each with its own DSH version, profile, plugins, skills, workspace, and logs — and renders them in an embedded WebView.

---

Highlights

• Isolated DSH Containers — install multiple DSH versions side by side and create independent Containers per project. Every Container gets its own profile (web / headless / custom), workspace, plugin set, and host process, so experiments never cross-contaminate.
• Embedded WebView, no browser needed — the DSH frontend opens in a native WebView window managed by DSH Box. No port-forwarding, no copy-pasting URLs, no tab clutter.
• Zero-dependency install — a private Node, npm, and pnpm runtime is bundled with every release. No system Node, no manual toolchain setup, no PATH hacking.
• Version manager built in — browse DSH releases from deepseek-ai/deepseek-harness, install or uninstall any tag with one click, and pin a version per Container.
• Extension & Skill repository — import plugins and skills from a GitHub URL, a local directory, or a tarball, then install them into any Container's profile with a single click. Skills are auto-sorted into the Container's skill root.
• Bundle (整合包) workflow — group any mix of plugins and skills into a named bundle, then export it two ways:
  • Quick export: GitHub-sourced entries are kept as URLs, keeping the archive tiny.
  • Full export: everything is packed into one portable .tar.gz.
  • Bundles can be re-imported (with your choice of overwrite or keep on name clashes) and installed into any Container — plugins land in the profile, skills are sorted automatically.
• Smart background tasks — every long operation (install, start, rebuild, import, export) runs as a visible queued task with real-time scrolling logs, cancel/retry/delete, and history paging. Nothing feels like it "just froze".
• Network-friendly — automatic proxy detection for GitHub clones, configurable GitHub mirror, and npm registry mirror for installs inside DSH.
• Background service & tray — a small dshboxd sidecar keeps things tidy, and a system tray icon lets you control it without keeping the main window open.
• Lightweight by design — Tauri-based, so the installer is small and the memory footprint stays far below Electron alternatives.
• Bilingual UI — English and 简体中文, switchable in Settings.

---

Install

Download the installer for your platform from the Releases page of this repository:

Grab the latest version from the Releases page — artifact names follow the <product>-<version>-<arch> convention and may differ per release. Other formats (.msi, .rpm, .AppImage) are produced per release where supported.

No runtime prerequisites — the bundled Node/npm/pnpm runtime travels inside the installer.

---

Quick start

1. Launch DSH Box and pick a writable runtime directory when prompted (all DSH data lives there).
2. Open DSH Version → Load versions → install the DSH tag you want.
3. Open DSH Container → create a Container (name, profile, DSH version).
4. Press Start — DSH Box builds the frontend if needed (or launches the cached build directly), then opens the DSH UI in the embedded WebView.
5. Head to Plugin Repository to import plugins/skills or assemble bundles, then add them to any Container.

Tray

The app minimizes to the system tray on close. Use the tray menu to open the window or start/stop/restart the dshboxd background service.

---

Technology

The Rust codebase is organized as a workspace of focused crates (box-foundation, box-scheduler, box-runtime, box-toolchains, box-dsh-versions, box-containers, box-extensions, box-state, box-server-core) with a thin desktop adapter layer — task scheduling, extension transfer, and container lifecycle logic are framework-free and unit-tested.

---

Building from source

Prerequisites: Node.js 20+ with pnpm, and the Tauri 2 prerequisites for your platform.

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

Release bundles (per platform):

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

Run the test suite:

cd src-tauri && cargo test --workspace

---

Repository layout

src/                       React/TypeScript management UI
src-tauri/                 Rust workspace + Tauri shell
  crates/                  focused, framework-free crates
  src/desktop/app/         domain modules (containers, extensions, tasks, …)
docs/HANDOFF.md            architecture & operation notes

---

License

Proprietary — see repository owner for licensing terms.

© Nexus-Aethra