sandbaseai/sandbase-harness · 上手攻略

  • 仓库：sandbaseai/sandbase-harness
  • 链接：https://github.com/sandbaseai/sandbase-harness
  • 分类：AI Agent Runtime / 本地优先 / MCP
  • 作者：spark
  • 更新：2026-08-31

数据速览（截至 2026-08-30 GitHub 公开计数）：637 stars · 61 forks · 186 commits · 当前 release v0.3.8（MCP 镜像 ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8，SkillsLLM 缓存稍旧到 0.3.7，按 GitHub README 取 0.3.8）。

⚠️ 仓库 README 列出了 ~50 条独立 ecosystem 索引链接（含 awesome 列表、DSH 系列插件目录、MCP 注册表镜像），是社区曝光的主要来源；本节不逐条核验每个目录快照是否同步。

一、是什么

SandBase Harness 是一个本地优先的 AI agent 运行时。它把一个完整 agent 跑起来需要的所有"非模型本身"的东西——会话持久化、sandbox（Docker / K8s / 自建 worker）、工具集、凭据保险库、权限策略、审批、审计回放、MCP 暴露——全部装进一个 Node.js 进程，自带 Console UI。模型层面接 OpenAI、Anthropic、MiniMax、DeepSeek V4 以及任何 OpenAI 兼容端点。

二、解决什么问题

写一个能"用工具、调 LLM"的 agent loop 一晚上能搭起来，但把它做成生产可用要解决 5 件事——SandBase Harness 是这 5 件事的打包解决方案：

  1. 安全执行生成的代码——本地 / Docker / K8s / 自建 worker 沙箱
  2. 长会话可观测——持久化会话、可恢复事件流、审计、回放
  3. 工具访问可控——MCP toolsets + 凭据保险库 + 权限策略 + 审批
  4. 模型层无关——OpenAI / Anthropic / MiniMax / DeepSeek V4 / OpenAI 兼容
  5. 基础设施自留——本地优先 SQLite + 文件存储，无强制托管控制面

三、快速安装

前置：Node.js（仓库未在 README 首段硬性标注具体版本；MCP 镜像 0.3.8 已 build，可推断 ≥18 LTS 即可起手）。

git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build

mkdir ../my-agents && cd ../my-agents
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start

# 打开 http://127.0.0.1:3000/dashboard

也可以直接拉 MCP 镜像跑（不编译源码）：

# ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8
# Linux 注意 plugin 用 host.docker.internal → host-gateway 映射

详细安装 + 多 client 配置参考仓库 llms-install.md。

四、核心用法

1. 五大能力模块（README 自陈）

能力 SandBase Harness 提供
安全执行生成的代码 本地 / Docker / K8s / 自建 worker 沙箱
检视长跑 agent 持久会话、可恢复事件流、审计、回放
工具访问控制 MCP toolsets、凭据保险库、权限策略、审批
任意模型 OpenAI / Anthropic / MiniMax / DeepSeek V4 / OpenAI 兼容
基础设施自留 本地优先 SQLite + 文件存储，无强制托管控制面

2. CLI 入口

# 初始化工作区
node ../sandbase-harness/dist/index.js init

# 启动 runtime + Console UI
node ../sandbase-harness/dist/index.js start
# 默认监听 127.0.0.1:3000，Console 路径 /dashboard

3. 模型接入

模型供应商在 init / start 之间通过环境变量或 init 提示配置。README 列出的现成支持：

  • OpenAI：原生 OpenAI API
  • Anthropic：Claude Messages API
  • MiniMax：本仓 MiniMax/M3（知识库方所用模型）
  • DeepSeek V4：DeepSeek 系列
  • OpenAI 兼容端点：任何 OpenAI Chat Completions 协议兼容服务（本地 vLLM、Together、Groq、自建代理）

4. MCP 集成

仓库自身被列入 Official MCP Registry。同时它消费其他 MCP server——init 阶段可声明 toolsets，把外部 MCP 工具纳入统一权限 / 凭据 / 审批管线。

5. Console UI

/dashboard 提供：

  • 当前会话列表 + 状态
  • 事件流（可恢复 / 可回放）
  • 工具调用历史
  • 审批 pending 队列
  • 凭据与权限矩阵

6. 配套资源

  • 仓库 llms.txt / llms-install.md：AI 可读的元数据 + 安装指引
  • SandBase CLI：配套"轻量 MCP 桥"，连接 25 个 AI client（Codex / Claude Code / Cursor / Windsurf / Gemini CLI / OpenCode…）到 2,000+ model / API
  • deepseek-plugin.org 等第三方 ecosystem 索引（README 列出 ~50 条）

五、典型适用场景

  • 想跑一个"能调工具、能审计、可回放"的本地 agent，但不想被 Cloud / Bedrock / Vertex 锁死
  • 用 DeepSeek V4 / MiniMax 等国产 / 自托管模型，但想要 LangChain / Agno 那种"工具调用 + 长会话"框架的等价物
  • 团队需要"模型层无关 + MCP 统一治理"——后期换模型不再重写业务
  • 已有 K8s / Docker 基础设施，需要 worker 沙箱跑生成的代码
  • 想把 agent 暴露给 IDE 类 client（Claude Code / Codex / Cursor）但不让它们直连模型 API——通过本地 MCP 桥接 + 凭据保险库统一管

六、坑与注意

  • ⚠️ Stars 数据双源漂移：README llms.txt 与 SkillsLLM 8/15 缓存均给 637 stars，GitHub About 区当前也是 637 stars（截至 2026-08-30）。README 列了约 50 条 ecosystem 链接，本文未逐条抓取验证每个目录快照是否同步——若要用某个索引的徽章做背书，建议先 curl -I 一下
  • ⚠️ MCP 镜像版本：GitHub README 当前用 0.3.8；SkillsLLM 缓存（2026-08-15）还显示 0.3.7——以 GitHub README 为准
  • ⚠️ 本地 Docker 沙箱 + Linux：plugin 把 host.docker.internal 映射到 host-gateway，但 README 没明确写每个发行版的 systemd 配置路径；如果你的 Linux 用 rootless Docker / Podman，要自测
  • ⚠️ README 把"本地优先 + 自托管"作为差异化卖点——但同时被列入大量 DeepSeek Harness（DSH）系列插件目录（DSH Plugin / DSH Hub / DSH Market 等），意味着在 DSH 生态里它的定位偏向"运行时"而非"插件"；选型时如果团队已有 DSH 全家桶，可评估是否冲突
  • 没有内置 TUI——所有交互走 127.0.0.1:3000/dashboard Web UI；要 TUI 习惯需要自接 OpenTUI / Ink 之类的层
  • "内置审计 + 回放"≠ 完整 observability——它只覆盖 agent 自己的事件，不含底层 LLM provider 的成本 / 延迟可视化。要这块接 Langfuse / OpenLLMetry

七、与同类对比

维度 SandBase Harness Agno (ex-Agents) LangGraph LangChain deepagents
部署 本地优先（Docker / K8s / 进程内沙箱） 本地 / 云 本地 / 云 本地 / 云
沙箱 内置（Docker / K8s / 自建 worker） 需自己接 需自己接 需自己接
模型层 OpenAI / Anthropic / MiniMax / DeepSeek V4 / OpenAI 兼容 多家 多家 多家
MCP 注册为 MCP server + 消费 MCP tools 仅消费 仅消费 仅消费
Console UI 内置 /dashboard 无 LangGraph Studio 无
凭据保险库 内置 无 无 无
自带回放 是 否 Studio 内 否

八、一句话推荐结论

如果你要的是"本地起一个生产可用、能调工具、能审计、能换模型、不锁云"的 agent 运行时——SandBase Harness 是当下少数把这五件事一次性配齐的开源项目；如果只是写个 demo 验证 prompt 效果，它的 init + start 两步也太轻了，直接当 demo 框架用也不算重。