sandbase-harness 是什么？本地优先的 AI Agent 运行时

sandbase-harness 是 DeepSeek Harness（DSH Plugin）生态中的本地优先 AI Agent 运行时插件，把模型循环扩展为生产级 Agent 基础设施：持久会话、沙箱化工具、记忆、凭据保险库、审计回放与内置控制台，全部运行在你自己的机器或基础设施上，数据默认留在本地。 本文基于官方 README 介绍它是什么、核心功能、安装启用、典型用法与常见排错。

sandbase-harness 是什么？

sandbase-harness 解决「Agent SDK 只处理模型循环，而生产级 Agent 还需要持久会话、工具治理、沙箱边界、凭据处理与可审计性」的问题：把运行层补全为本地优先的 Agent 运行时，自带一个供人检查的控制台。 以下定位与事实均来自官方 README（来源）：

sandbase-harness 由 sandbaseai 团队用 TypeScript 开发、以 Apache-2.0 协议开源。它的定位是「本地优先的 AI Agent 运行时」——不是可视化工作流搭建器，也不是另一个模型 SDK。运行时提供 Claude Managed Agents 风格的 /v1 API 与本地控制台，支持 OpenAI、Anthropic、MiniMax 以及任何 OpenAI 兼容端点（包括 DeepSeek V4）。默认使用 SQLite 存储元数据、本地文件保存技能与文件字节，没有必须连接的托管控制平面；需要 Node.js 22+ 与 npm 10+。它既是独立运行时，也可作为 DSH 插件运行，通过 MCP stdio 桥接让 DSH 原生调用 mcp__sandbase__* 工具。

sandbase-harness 的核心功能有哪些？

sandbase-harness 的核心能力是「沙箱化执行、持久会话、工具治理、凭据保险库、多模型接入与本地优先存储」：让长时运行的 Agent 可安全执行、可控可查、数据不离开你的机器。 这些能力全部来自官方 README（来源）：

• 沙箱化执行：支持本地进程、Docker（每会话容器）、Kubernetes（kubectl exec/cp）与自托管 worker 队列四种沙箱后端，安全运行生成的代码。
• 持久会话与回放：基于 SQLite 的会话元数据 + 可恢复的 Server-Sent Events，支持会话回放、审计与调试；本地文件与技能字节存储在工作区状态目录。
• 工具治理：MCP 工具集、权限策略、内置工具与技能包，配合审批流程控制 Agent 的工具访问。
• 凭据保险库：集中管理 API 密钥与敏感信息，支持审批流程，调用方不直接持有密钥。
• 多模型支持：通过 OpenAI 兼容接口接入 OpenAI、Anthropic、MiniMax 与 DeepSeek V4；每个工作区一次激活一个模型供应商（Settings V2 边界）。
• 本地优先存储：SQLite 元数据 + 本地文件存储，无托管控制平面；同时提供 TypeScript SDK（managed-agents/sdk）与 Anthropic SDK 兼容的 /v1 API。

怎么安装与启用 sandbase-harness？

安装 sandbase-harness 分两步：先用 DSH CLI 安装插件，再启动运行时并在内置控制台配置模型；也可以脱离 DSH 独立运行。 以下命令与事实均来自官方 README（来源）：

1. 用 DSH 安装插件：在 DeepSeek Harness 终端执行安装命令：

dsh plugin --profile web add github:sandbaseai/sandbase-harness

等待命令输出安装完成，重启 dsh web 后即完成插件接入；运行时会通过 MCP stdio 桥接向 DSH 暴露 mcp__sandbase__* 工具。

2. 启动运行时与控制台：启动后打开内置控制台：

export MANAGED_AGENTS_URL=http://127.0.0.1:3000
dsh web

或脱离 DSH 独立启动：

node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start

3. 配置模型供应商：打开 http://127.0.0.1:3000/dashboard，进入 Settings > Models 粘贴 API 密钥即可开始使用；沙箱、存储、记忆等高级配置在 Settings V2 中调整（支持表单与 JSON 模式，自动重启）。

4. 更新 sandbase-harness：更新插件用 DSH 的 update 命令：

dsh plugin --profile web update sandbase-harness

5. 卸载 sandbase-harness：从当前 profile 移除插件：

dsh plugin --profile web remove sandbase-harness

sandbase-harness 典型用法

sandbase-harness 的典型用法是「创建 Agent 与环境、启动会话、查看回放」：先定义 Agent 和沙箱环境，再开一个会话与 Agent 对话，最后用事件流回放检查发生了什么。（来源）以下步骤覆盖从创建到审计的日常用法。

1. 创建 Agent：通过 /v1/agents 接口定义一个 Agent（名称、模型、系统提示词与工具集）：

curl -X POST http://127.0.0.1:3000/v1/agents \
  -H "Content-Type: application/json" \
  -d '{"name":"Incident commander","model":"gpt-4o","system":"You are an on-call incident commander."}'

2. 创建沙箱环境：用 Docker 隔离环境运行生成的代码：

curl -X POST http://127.0.0.1:3000/v1/environments \
  -H "Content-Type: application/json" \
  -d '{"name":"Docker sandbox","config":{"sandbox_provider":"docker","image":"node:22-slim"}}'

3. 启动会话并发消息：创建会话后发送消息，Agent 在沙箱中执行任务：

curl -X POST http://127.0.0.1:3000/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"agent":"agent_...","environment_id":"env_...","title":"Triage SENTRY-123"}'
curl -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -d '{"content":"Investigate the alert."}'

4. 回放会话事件流：通过可恢复的 Server-Sent Events 流式查看并回放会话（Last-Event-ID 支持断点续传）：

curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
  -H "Last-Event-ID: 42"

5. 用 CLI 管理运行时：managed-agents list 查看 Agent，managed-agents chat <agent-id> --message "hello" 直接对话，managed-agents reload 热重载配置。

sandbase-harness 常见问题与排错

sandbase-harness 最常见的四类问题及其典型症状与解决办法：控制台无法访问、Docker 沙箱失败、模型调用无响应与 git 源安装报错，分别对应端口/主机配置、Docker 前置条件、模型密钥与 pnpm 构建白名单。（来源）

1. 控制台无法访问：症状是浏览器打不开 http://127.0.0.1:3000/dashboard；原因多为端口被占用或只绑定了 127.0.0.1；解决是启动时用 --host 0.0.0.0 --port <新端口> 指定监听地址与端口，或在 Settings V2 中调整端口配置。

2. Docker 沙箱创建失败：症状是创建 docker 环境报错；原因是本机未安装/未运行 Docker，或 DSH 进程无权限访问 Docker 守护进程；解决是先确认 docker info 可用，再授予进程访问 Docker daemon 的权限。

3. 模型调用无响应：症状是发送消息后 Agent 不回复；原因是 API 密钥无效、供应商未配置，或工作区同时激活了多个模型供应商；解决是到 Settings > Models 核对密钥并确保每工作区只激活一个供应商。

4. git 源安装报 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED：症状是第一次 dsh plugin --profile web add 失败并打印 exact key；原因是 pnpm 构建白名单未放行 git 依赖；解决是把报错中打印的 key 加到 profile 的 pnpm-workspace.yaml 的 allowBuilds: 下，再重跑同一条 add 命令。

适用场景与注意

sandbase-harness 适合「需要长时运行、可审计、可沙箱化执行的 Agent 工作流，且希望数据留在自己机器上」的场景；注意默认无认证开放，生产使用需开启密钥认证。（来源）

适用场景：可审计的编码 Agent、受控代码执行（本地/Docker/Kubernetes/自托管沙箱）、需要会话回放与审计的自动化任务、把 DeepSeek Harness 作为交互前端接入完整运行时。注意事项：

1. 运行时默认开放无认证，一旦创建至少一个 API 密钥即启用认证，客户端通过 Authorization: Bearer <key> 访问——生产环境务必配置密钥。
2. npm 上无作用域的 managed-agents 包名与本项目无关，请只从本仓库 tagged GitHub 源码安装，不要运行 npx managed-agents。
3. Docker 与 Kubernetes 沙箱有前置条件（Docker daemon 访问权限、kubectl 集群权限），本地进程沙箱最轻量但隔离性最弱。
4. git 源安装第一次 add 可能因 pnpm 构建白名单失败，需要按报错把 key 加入 pnpm-workspace.yaml 的 allowBuilds: 后重跑，属正常流程而非安装失败。

项目链接

sandbase-harness 是 sandbaseai 团队维护的开源项目（Apache-2.0）。 插件详情页：sandbase-harness 插件详情。

本页是基于该插件官方 README 独立重写的导读——权威文档和最新变更请以源头为准：sandbaseai/sandbase-harness。插件是安装时就在你机器上运行的第三方代码；收录不代表背书——安装前请自行审阅源码。