# `@deepseek-ai/dsh-sandbox-mxc`

[English](README.md) | 中文

这是一个 Stent sidecar：在不修改 DeepSeek Harness 源码的前提下，让 DSH bash、PowerShell 和持久终端载荷通过 MXC 执行。该包是显式 opt-in bundle；`ctx.sandbox`、subprocess 的 I/O、deadline、signal、终端会话和 teardown 仍由 DSH 持有，Stent 只在加载时把受控 Hook 安装到现有消费路径。

## 包结构

```text
package.json              # 可发布 bundle 与公开依赖
cordis.patch.yml          # profile 行与 config.stent.patches 描述
src/stent-entry.ts        # 命名导出的 Stent function plugin
src/stent-handlers.ts     # descriptor 与生命周期安全的 handler
src/index.ts              # MXC 策略编译器与兼容 provider
src/invariant.ts          # 包 invariant companion
tests/                    # 策略、provider、Hook 与发布路径测试
legacy/                   # 历史宿主补丁；bundle 永不应用
```

包根是 Stent function plugin，刻意不提供 default export。兼容 provider 与策略编译器还可从 `@deepseek-ai/dsh-sandbox-mxc/provider` 获取；新 profile 应通过 bundle 行加载包根。

MXC runtime 使用公开的 `@omdsh-dev/mxc-sdk` `0.7.0` GitHub Release asset：

```text
https://github.com/omdsh-dev/sandbox-mxc/releases/download/v0.7.0/omdsh-dev-mxc-sdk-0.7.0.tgz
sha256: ffd9a83b9f6a509ee99a59e60ab6bd68889c106d5d8f14d1fa402efd157e8c72
```

包在 `dependencies` 中保留不可变的 v0.7.0 release URL，并在 `bundleDependencies` 中列出 `@omdsh-dev/mxc-sdk`。因此 `npm pack` 会把 SDK、native executor 和 denial-capture asset 放进发布 tarball 的 `node_modules/@omdsh-dev/mxc-sdk`；消费者不需要再次解析 GitHub URL。`@oh-my-dsh/stent` 是可安装的 host-facing peer；`@deepseek-ai/dsh-sandbox`、`@deepseek-ai/dsh-subprocess` 和 `@deepseek-ai/dsh-invariants` 是由 DSH 宿主提供的 runtime contract，不会被复制进本包，也不会 patch 宿主源码。

## Stent bundle 行为

普通 profile 中该行保持关闭。`stent-dsh` 从 `config.stent.patches` 读取 descriptor，在目标模块加载前安装转换，并仅在 Stent composition 中启用该行：

```yaml
- id: sandbox-mxc
  name: '@deepseek-ai/dsh-sandbox-mxc'
  disabled: true
  config:
    enabled: true
    useResultEnvelope: true
    stent:
      patches:
        # 完整 descriptor 列表随 cordis.patch.yml 发布。
```

Handler 覆盖现有公开 seam：

- `@deepseek-ai/dsh-bash-sandbox` 的前台和后台调用；
- `@deepseek-ai/dsh-pwsh-sandbox` 的前台和后台调用；
- bash 与 PowerShell local executor 的进程结算 Hook；
- `terminal-bash` backend 在 local terminal primitive spawn 前的创建路径；
- `dsh-subprocess-local.spawnTerminal` 的参数替换；
- `@deepseek-ai/dsh-sandbox-local.confine` 的 terminal-only 绕过，避免原始 terminal 路径再次包装 MXC launch。

每个受约束调用都会以精确 argv、cwd 和 scrubbed+explicit 环境准备一个独立 MXC controller；controller 从 versioned result envelope 结算，并且只释放一次。宿主 subprocess 或 terminal service 继续拥有进程树、超时、signal、stdio 和 quiescence。`danger-full-access` 直接委托原始宿主调用，不启动 MXC。任何 MXC qualification 或 runner failure 都抛出 `SANDBOX_UNAVAILABLE`，绝不回退到无约束载荷。

workspace 使用 pnpm 的 `nodeLinker: hoisted`，因为 isolated linker 无法物化 `bundleDependencies`。该设置需要保留给开发安装；最终 bundled artifact 应使用 `npm pack`/`npm publish`，因为当前 pnpm packer 会把 nested bundled executable 的权限规范化。

## 开发

```sh
pnpm install
pnpm run typecheck
pnpm run build
pnpm test
pnpm run prepare
npm pack --dry-run
pnpm run test:e2e
```

真实 executor 测试在当前平台没有对应 binary 时会自跳过。Release asset 已包含 native executor 与 denial-capture 文件；不需要 GitHub Packages 凭据或 `.npmrc` scope 覆盖。

## 模型体验

此包不增加任何 model-visible prompt、tool 或 result 文本。现有 DSH bash 与 terminal consumer 继续负责渲染和错误语义；sandbox seam 负责 `SANDBOX_UNAVAILABLE` 诊断。

#### KV 缓存效果

无直接失效；现有 consumer 拥有请求前缀变化。

## 已知限制与暂缓事项

- Linux MXC qualification 需要可用的 Bubblewrap/user namespace；macOS 与 Windows 验收仍依赖宿主条件，Windows Tier 3 需要显式宿主 DACL 权限。
- SDK release 仍是 Public Preview。策略 schema 与 native backend 可能在后续 minor 版本变化；升级必须同步审查依赖和 policy version。
- Stent descriptor 因 DSH 按平台选择 bash 或 PowerShell 而设为可选。若 profile 启用 bundle 但没有加载匹配 consumer，不会得到对应 Hook；宿主仍需组合受支持的 sandbox consumer。
- `legacy/mxc-host-integration.patch` 仅是历史证据；Stent bundle 不读取、不应用、也不依赖它。