用途
SandBase Harness 是一个本地优先（local-first）、自托管的 AI 智能体运行时（runtime）和 MCP 桥接层。它面向需要将 AI 智能体投入生产的开发者：模型 SDK 负责模型循环，而生产级智能体还需要持久会话、工具治理、沙箱边界、凭据处理、记忆、可审计性以及供人查看运行过程的 UI，这套运行时正是承担这一层职责。官方明确说明它不是可视化工作流构建器，也不是另一个模型 SDK。
主要能力
- 兼容 Claude Managed Agents 风格的 /v1 API，并提供本地 Console。
- 默认使用 SQLite 存储元数据，涵盖智能体（agents）、会话（sessions）、环境（environments）、凭据保管库（credential vaults）、记忆存储（memory stores）、文件、技能（skills）和 API 密钥；文件/技能的字节内容存放在工作区状态目录中。
- 支持可恢复的 Server-Sent Events（SSE），用于会话重放与调试。
- 通过 Settings V2 配置单一活动模型提供商边界。
- 沙箱后端：本地进程、Docker（按会话隔离容器）、Kubernetes（kubectl exec/cp）、自托管 worker 队列。
- 支持 MCP 工具集、权限策略、内置工具和技能包。
- 在 managed-agents/sdk 提供 TypeScript SDK。
- 发布门禁命令：npm run release:check。
环境要求与安装
要求 Node.js 22+、npm 10+，以及模型提供商 API 密钥（OpenAI、Anthropic、MiniMax 或任意 OpenAI 兼容端点）。Docker 为可选项，仅在需要 Docker 沙箱后端时使用。
init 命令会在你执行它的目录中写入工作区：一个智能体、一个 skills 文件夹，以及 config.yaml，其中 provider 引用的是 ${OPENAI_API_KEY} 环境变量。start 命令在 http://127.0.0.1:3000 提供 API 和 Console 服务。
设置分两步，均在 http://127.0.0.1:3000/dashboard 的 Settings > Setup 中完成：
- 提供商（provider）：将 API 密钥粘贴到提供商表单并保存。页面随后会提示保存的配置尚未生效，需要重启运行时——用 Ctrl+C 停止后再次运行 start 命令，或使用重启按钮。保存的设置仅在启动时生效。如果提供商不在列表中，选择 OpenAI 兼容厂商并设置其 base URL。
- 模型（model）：在 Agent models 面板中，设置你的提供商实际提供的模型 ID——例如 DeepSeek 使用 deepseek-chat。智能体自带模型 ID，因此 init 写入的 gpt-4o 并非对所有提供商有效，错误的 ID 会导致该轮对话以 model_not_found 失败。
从 Console 发送第一条消息：打开 Sessions，为智能体创建会话，然后在输入框中输入。从终端只需一条命令： chat 发送该条消息，并在该轮结束后退出；不带 --message 时，它会保持会话打开并持续流式输出，直到你中断。--tool-approval allow 会预授权智能体可能发起的工具调用（init 模板默认会将工具调用挂起等待人工批准）；详见 CLI 文档。
注意：npm 上未加作用域（unscoped）的 managed-agents 名称并非本项目。在本仓库正式发布官方作用域包之前，请仅从上方所示带标签的 GitHub 源码发布安装。不要运行 npx managed-agents 或 npm install managed-agents。
在 Codespaces 中试用
随附的开发容器会安装依赖并构建运行时。终端就绪后，在转发端口上启动服务器，然后打开转发的 SandBase Harness Console 端口，并在 Settings > Setup 中配置模型。Codespaces 使用可能由 GitHub 计费；上述本地快速开始仍然免费，并将所有运行时数据保存在你的机器上。
使用官方 SDK
运行时在同一端口上响应自己的 /v1 API，官方 Anthropic TypeScript SDK 客户端可以不加改动地驱动它：将客户端的 baseURL 指向运行时，提供运行时 API 密钥，examples/official-sdk 中的 quickstart 即可对运行时跑完一整轮（消息、工具调用、工具结果、最终回复）。该示例在每次拉取请求时由 tests/conformance/official-sdk-quickstart.test.ts 执行，因此它描述的兼容性是经过测试的兼容性，而非声称的兼容性。同一接口在 docs/api.md 中有规范说明，本仓库自己的 TypeScript SDK 记录在下方 SDK 部分。
CMA 兼容性
对已发布的 Claude Managed Agents 契约的覆盖情况在 src/core/capabilities/matrix.ts 中逐条声明：在官方 SDK 的路由面（截至 SDK 0.131.0 为 110 个方法/路径对）中，90 条路由已挂载，20 条按名称拒绝；没有任何路由被推迟。Partial 和 Unsupported 条目始终说明原因。下表由 npm run docs:compat 生成，当它与矩阵不一致时，契约诚实性测试会失败。
apply 声明式用法
apply 是同一 API 的声明式形式：一个 Markdown 文件，其 frontmatter 是智能体定义（--- 下方的正文成为系统提示），一个 .yaml 环境文档，或一个 Markdown 部署清单（frontmatter 携带 name、agent、environment、schedule；正文成为初始的 user.message）。解析后的 id 落到文件旁的 managed-agents-lock.json，因此编辑后重新运行 apply 会更新同一资源而非创建重复资源——请将锁文件与清单一起提交。后续文件可以按名称引用更早的文件，因此 apply coding-assistant.md environment.yaml deployment.md 可将部署关联到前两个文件创建的行。
工具审批行为
某轮对话中如果需要审批的工具调用，会挂起而非失败；chat 会在运行前询问，然后让运行时继续同一轮对话。--tool-approval allow 会预先决定所有此类调用（脚本或 CI 任务使用此方式），deny 则拒绝它们。在没有终端可提示时，默认的 ask 不回答任何内容并以非零状态退出，同时列出正在等待的调用，因此脚本需要明确声明其策略而非继承默认策略。自定义工具是例外：只有你自己的客户端能产生其结果，chat 会说明这一点并以非零状态退出。
API 与鉴权
/v1 API 遵循 Claude Managed Agents 的资源形态，因此你也可以将 Anthropic SDK 指向本地运行时。默认开放：当至少存在一个 API 密钥时鉴权激活；客户端发送 Authorization: Bearer <key>。
集成与示例
- DeepSeek Harness 插件——将此运行时作为 DSH 插件通过 MCP stdio 运行：安装、预检、工具列表和故障排查见 examples/deepseek-harness。DSH 项目也可以从 GitHub 源码获取可移植技能，例如 npx --yes github:sandbaseai/sandbase-skills add multi-source-search 会安装到 .dsh/skills/multi-source-search。
- Agent Plugins 1.0 客户端（Copilot CLI、VS Code）和独立 MCP 桥接容器——见 agent-plugin/PLUGIN.md。
使用场景与配置
- 用例——Showcase 演示了可审计的编码智能体、作为交互前端的 DSH，以及在 Local、Docker、Kubernetes 和自托管沙箱中受控执行代码。
- 智能体配置——YAML 智能体定义、config.yaml 和工作区布局见使用指南；每个资源的 curl 演练见 docs/api.md。
机器可读的项目元数据
- 智能体 / MCP 安装指南
- Agent Plugin 市场清单
- DeepSeek Harness 集成
- 引用元数据
release:check 会运行类型检查、测试、两次构建、npm pack --dry-run、CLI init 冒烟测试以及 examples/basic 启动冒烟测试。生态系统目录、社区指南和相关项目见 docs/ecosystem.md。社区用例讨论包括：在 Codex、Claude Code 和 DSH 之间迁移记忆；第三方插件的沙箱与文件系统保护。
限制与说明
- 官方资料未提供具体的收费、价格信息。
- 官方资料未提供平台支持列表（除 Node.js 22+、npm 10+ 与可选 Docker 外）。
- 官方资料未提供性能指标或效果数据。
- 请勿从 npm 安装未加作用域的 managed-agents 包，目前仅支持从本仓库带标签的 GitHub 源码发布安装。
