ztting01/dsh-agentenv-sandbox

dsh-agentenv-sandbox

用于 DeepSeek Harness 的 AgentENV 执行环境捆绑包。它用官方 Harness E2B 适配器替换本地文件系统和子进程提供程序，并由一个 AgentENV Firecracker microVM 提供支持。Bash 命令、文件工具、持久终端和提供程序中立的 LSP 进程随后共享同一个远程 Linux 环境。

状态

这是面向 DeepSeek Harness 0.1.0-rc.7、匹配的已发布 E2B 提供程序系列 0.1.0-rc.7 以及 E2B SDK 2.29.1 的 MVP。它针对 AgentENV 0.1.0 和 0.1.3 具有实时兼容性覆盖；0.1.3 测试覆盖了经过身份验证的沙箱创建、工作区上传、文件系统操作、非交互式命令、持久 PTY、拆除以及真实的 Harness Web 配置文件启动。其捆绑包组合也已通过 Harness 0.1.0-rc.8 源代码检出进行了检查。请在 WSL 2 或 Linux 中运行 Harness。原生 Windows 执行会被拒绝，因为一个 Harness 会话 cwd 必须同时是宿主进程和远程 Linux 环境中的有效路径。

该捆绑包采用故障关闭策略：它会禁用本地文件系统、本地子进程和本地 shell 沙箱提供程序。AgentENV 创建、设置或工作区上传失败会阻止远程提供程序加载；它绝不会回退到宿主机执行。

哪些内容保留在宿主机上

Harness 进程、模型调用、Cordis 服务、会话持久化、技能、UI 和 SDK 缓冲区保留在宿主机上。官方 Bash、文件、PTY 和 LSP 使用方通过 AgentENV 内的 ctx.fs 和 ctx.subprocess 执行其操作系统工作。直接导入 Node.js fs 或 child_process 的第三方插件可以绕过这些提供程序接缝，不在本保证范围内。

先决条件

- WSL 2 或 Linux，配备 Node.js 22.19+ 或 24+。不支持原生 Windows 执行。
- DeepSeek Harness 0.1.0-rc.7，已安装并可作为 dsh 命令使用。
- AgentENV 0.1.3 已安装、已通过身份验证并正在运行（0.1.0 仍受支持）。本插件不会安装或启动 AgentENV。
- 在首次启动 Harness 之前构建的 AgentENV 模板。本插件从现有模板创建沙箱；它不会自动构建模板。

简而言之，先部署 AgentENV 和 DeepSeek Harness，然后构建一次模板，将本插件安装到 Harness 配置文件中，并从项目目录启动 Harness。

这些是独立产品，不随本插件捆绑。在继续之前，请按照其官方文档安装它们：

- AgentENV v0.1.3 源代码和部署文档
- DeepSeek Harness 官方快速开始和源代码安装

首次设置

1. 验证 AgentENV 和 DeepSeek Harness

确认 AgentENV CLI 可用且其服务器正在运行：

command -v aenv
curl -f http://127.0.0.1:8000/health

确认已安装的 Harness CLI 可用：

command -v dsh
dsh --version
AgentENV 身份验证和服务器部署是由 AgentENV 自身提供的前提条件。在继续之前，请按照适用于你平台的 AgentENV 安装说明进行操作。该插件仅连接到由此产生的 AgentENV API。

2. 一次性构建 AgentENV 模板

模板是可复用的基础镜像，AgentENV 从中创建全新的沙箱。它不是一个正在运行的沙箱。本仓库包含 sandbox/Dockerfile，其中安装了 Node.js 24、Bash、Git、ripgrep、Python、构建工具，以及官方 Harness E2B 适配器所需的进程工具。

在 AgentENV 安装、身份验证并运行后，从本仓库的根目录运行以下命令：

aenv build ./sandbox/Dockerfile \
--name dsh-agentenv-node24 \
--cpu 2 \
--memory 4096

此命令使用本插件测试过的 AgentENV 0.1.3 CLI 语法。AgentENV 0.1.0 使用 --tag 而不是 --name；请始终使用与所部署服务器版本匹配的 CLI 语法。

该命令将 dsh-agentenv-node24 注册为 AgentENV 中的模板别名。通常只需运行一次。当你更改 Dockerfile、升级其工具，或部署一个尚未包含此模板的新 AgentENV 服务器时，请重新构建该模板。

如果你只安装了发布版压缩包而没有源代码检出，请解压它以访问其中包含的 Dockerfile：

mkdir dsh-agentenv-template
tar -xzf dsh-agentenv-sandbox-0.1.5.tgz -C dsh-agentenv-template
cd dsh-agentenv-template/package
aenv build ./sandbox/Dockerfile --name dsh-agentenv-node24 --cpu 2 --memory 4096

3. 配置 AgentENV 连接

在每个启动 Harness 的 shell 中设置这些值，或将它们添加到用于启动 Harness 的 shell 启动/配置中：

export AENV_API_KEY=''
export E2B_API_URL=http://127.0.0.1:8000
export E2B_SANDBOX_URL="$E2B_API_URL"
export E2B_API_KEY="$AENV_API_KEY"
export AENV_TEMPLATE_ID=dsh-agentenv-node24

| 变量 | 值 | 含义 |
| --- | --- | --- |
| AENV_API_KEY | 由 AgentENV 服务器生成的密钥 API 密钥 | 主机侧 AgentENV 凭据。请对其保密，不要提交。 |
| E2B_API_URL | AgentENV 控制平面 URL，例如 http://127.0.0.1:8000 | 用于创建、连接、续期、暂停和删除沙箱的 E2B 兼容 API 端点。 |
| E2B_SANDBOX_URL | AgentENV 沙箱数据平面 URL；对于本地部署，它通常与 E2B_API_URL 相同 | 用于沙箱命令、文件系统和终端流量的端点。 |
| E2B_API_KEY | 与 AENV_API_KEY 相同的密钥值 | 本插件内部使用的 E2B SDK 所期望的凭据名称。 |
| AENV_TEMPLATE_ID | 现有的 AgentENV 模板 ID 或别名，例如 dsh-agentenv-node24 | 选择插件从中创建 Harness 沙箱的模板。 |
使用你的 AgentENV 部署生成的 API 密钥。运行 aenv auth 会配置 CLI，但启动 Harness 的 shell 也必须通过 AENV_API_KEY 或 E2B_API_KEY 提供该密钥；插件不会读取 CLI 凭据文件。对于远程 AgentENV 部署，请将 localhost URL 和模板别名替换为该部署提供的值。aenv CLI 对设置和管理很有用，但插件运行时通过 E2B SDK 与 AgentENV API 通信，并不会为每条命令调用 aenv。

安装

4. 将插件安装到 Harness 配置文件中

对于正常使用，请下载预构建的发布 tarball 并将其添加到 Harness 配置文件中。发布版用户不需要克隆此仓库、运行 npm install 或运行 npm run check；该 tarball 已包含编译好的 lib 文件：

curl -LO https://github.com/ztting01/dsh-agentenv-sandbox/releases/download/v0.1.5/dsh-agentenv-sandbox-0.1.5.tgz
dsh plugin --profile web add "$PWD/dsh-agentenv-sandbox-0.1.5.tgz"
dsh --profile web --dump-config

仅限插件源码开发

以下命令仅适用于克隆或修改了插件源码的贡献者。请从插件仓库根目录运行它们——即包含此插件 package.json 的目录——而不是从普通项目工作区运行：

cd /absolute/path/to/dsh-agentenv-sandbox
npm install
npm run check
dsh plugin --profile web add /absolute/path/to/dsh-agentenv-sandbox
dsh --profile web --dump-config

npm install 会读取此仓库的 package.json 和 lockfile，从 npm registry 下载插件的 Node.js 运行时和开发依赖，并将它们放置在此仓库的 node_modules 下。这些依赖包括 E2B SDK、官方 DSH E2B 提供程序、TypeScript、Vitest 及其传递依赖包。它不会安装 AgentENV、构建 AgentENV 模板、安装 DeepSeek Harness 应用程序，或将此插件安装到 Harness 配置文件中。

npm run check 会依次运行 TypeScript 类型检查、单元测试和生产构建。它会创建直接从源码目录安装时所需的编译后 lib 输出。它不会启动 AgentENV 或执行实时 AgentENV 冒烟测试；请在完成 AgentENV 设置后单独使用 npm run smoke:agentenv 进行该测试。

5. 从项目目录启动 Harness

从你想要上传的项目目录启动 Harness：

cd /absolute/path/to/project
dsh --profile web

必需的工作区路径不变式

在 Web 客户端中为对话选择的工作区必须与启动 DSH 进程的目录具有完全相同的绝对路径：

DSH process.cwd()
= Web client conversation workspace path
= AgentENV sandbox cwd

工作区显示名称无关紧要；必须匹配的是绝对路径。例如，在使用以下命令启动 DSH 后：

cd /home/user/project-a
dsh --profile web

在 Web 客户端中选择 /home/user/project-a 作为会话工作区，然后创建或打开属于该工作区的会话。不要选择 /home/user/project-b，即使两个工作区都显示在侧边栏中。重启 DSH 不会删除已保存的会话，也不会更改现有会话所记录的工作区。

此 MVP 为每个 DSH 进程拥有一个沙箱和一个固定的 cwd。将 Web 客户端切换到不同的工作区不会重新创建沙箱，也不会上传新选择的目录。不匹配通常会失败并报错，例如：

Error: [invalid_argument] cwd '/different/workspace' does not exist

要同时使用多个工作区，请为每个工作区在不同的 Web 端口上启动一个 DSH 进程，并在每个客户端页面中使用匹配的工作区：

cd /home/user/project-a
dsh --profile web --port 3080 --no-open

cd /home/user/project-b
dsh --profile web --port 3081 --no-open

默认配置会将项目（包括 .git）上传到全新 microVM 内相同的绝对 POSIX 路径。它会排除 node_modules、Python 虚拟环境、缓存和 .dsh-agentenv。指向工作区内文件或目录的符号链接会作为常规副本上传。悬空链接、指向工作区外部的链接、造成目录循环的链接、解析为不支持的文件类型的链接，或指向被排除路径的链接都会中止启动。将 symlinkPolicy 设置为 error 以严格拒绝，或仅在有意省略时设置为 skip。

初始上传成功后，插件会将一份不含密钥的完成摘要写入 microVM 内的 .dsh-e2b/workspace-upload.json。它的存在意味着有界扫描和每个上传批次均已完成；它对于启动诊断也很有用。

配置

覆盖配置文件 cordis.patch.yml 中的 agentenv-runtime 行。后一个补丁会替换完整配置，因此请重新声明你需要的每个值。

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| apiUrl | E2B_API_URL 或 http://127.0.0.1:8000 | AgentENV 控制平面 |
| sandboxUrl | E2B_SANDBOX_URL 或 apiUrl | AgentENV 数据平面 |
| apiKey | E2B_API_KEY，然后是 AENV_API_KEY | 仅主机端 API 凭据 |
| template | AENV_TEMPLATE_ID | 必需的模板 ID 或别名 |
| sandboxId | 省略 | 重新连接而不是创建 |
| cwd | Harness process.cwd() | 共享的绝对远程 cwd |
| timeoutMs | 3600000 | 滚动沙箱租约，在 Harness 运行期间续期 |
| secure | true | 保护 envd 控制流量 |
| onDispose | kill | kill 或 AgentENV pause |
| uploadWorkspace | true | 初始的有界主机到沙箱上传 |
| uploadMaxFiles | 50000 | 上传文件数量上限 |
| uploadMaxBytes | 512 MiB | 上传总大小上限 |
| uploadMaxFileBytes | 256 MiB | 单文件上传大小上限 |
| symlinkPolicy | copy-internal | 复制安全的内部文件/目录链接，或使用 error/skip |
要在 Harness 重启后保留沙箱，请设置 onDispose: pause，然后使用记录的 sandboxId 启动。自动发现和主机回写有意不作为此 MVP 的一部分。

安全模型

Harness 报告 danger-full-access，因为其当前的受限模式会解析主机路径，并且不强制远程文件系统路径。只有在 AgentENV microVM 内部才具有完全访问权限；主机工作区未被挂载。该 bundle 禁用了 permission-presets，因为该服务需要一个具有可变 sandboxMode 的主机受限 Bash 执行器；而 AgentENV 则是一个固定的隔离边界。审批策略仍为 never，并且 Web 权限选择器有意不可用。API 密钥保留在主机 SDK 连接中，此插件不会将其插入沙箱命令环境。

初始上传是一个显式的控制平面例外：该插件会读取所选主机工作区一次，并将有界常规文件内容发送到 AgentENV。设置完成后，面向模型的文件和进程操作将使用远程提供程序。不会自动回写到主机。

实时冒烟测试

在构建包和模板后，无需模型 API 密钥即可验证运行时所有者以及官方 FS、命令和 PTY 提供程序：

export AENV_TEMPLATE_ID=dsh-agentenv-node24
npm run smoke:agentenv

当两者都设置时，该脚本使用 E2B_API_URL 以及 E2B_API_KEY/AENV_API_KEY。否则，它会读取现有的 aenv auth 凭据文件，或由 AENV_CREDENTIALS_PATH 指定的文件。它绝不会打印 API 密钥。该测试会创建一个短生命周期沙箱，验证 ctx.fs 与 ctx.subprocess 之间的双向可见性，验证 PTY 输出，证明不存在主机回写，并在拆卸期间删除该沙箱。

已知限制

- 一个 DSH 进程拥有一个 AgentENV 沙箱，且 cwd 固定。除非所选工作区路径与启动 DSH 时所在的目录完全相同，否则不支持 Web 客户端工作区切换。
- 没有自动沙箱发现、重连重试、快照 UI 或增量同步。
- 不会自动将远程更改下载或合并到主机工作区。
- 此 MVP 使用的 E2B 文件系统 API 无法复现符号链接。
- 在当前版本中，Harness tool-fs-search 可能仍会解析其打包的主机 rg 路径。在上游使搜索可执行文件解析具备提供程序感知能力之前，请在 AgentENV 模板中使用已安装 rg 二进制文件的 Bash。
- 绕过 ctx.fs 或 ctx.subprocess 的进程内工作流/代码运行时以及第三方插件仍保留在主机侧。
- 官方 E2B 子进程适配器将 SDK 命令传输缓冲区保留在主机上，并继承其已发布的 PTY/进程限制。
- AgentENV 0.1.0 和 0.1.3 附带 envd 0.5.15，而官方 FS provider 请求的是 envd 0.6.2 中引入的文件元数据。该插件仅对那个明确不受支持的元数据写入进行重试，且不带元数据。普通元数据指纹仍能检测外部更改，但在极其粗糙的时间戳窗口内，相同大小的写入的过期版本检测能力较弱，直到 AgentENV 升级 envd。