FastGPT Sealos Sandbox Provider 实现指南基于 sandbox-adapter 的 Sealos Devbox 接入方案【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT导读本文围绕 FastGPT 仓库中.agents/issue/implement-sealos-provider.md的实现方案系统讲解 FastGPT 如何通过统一的fastgpt-sdk/sandbox-adapter接入两种 Agent Sandbox Provider——自研的 OpenSandbox 与 Sealos Devbox。文章覆盖 Provider 能力对比、统一 Create Spec 设计、Sealos FastGPT Runtime 约定、SandboxEditor文件通道架构以及 FastGPT 侧的环境变量与 API 改造点并结合仓库内sdk/sandbox-adapter的实际源码适配器、HTTP 客户端、契约与类型定义给出可验证的实现细节。读完本文你将掌握 FastGPT 多 Provider 沙箱的抽象边界、Sealos Devbox 的字段映射规则以及 Skill 编辑器脱离 iframe 后基于 FastGPT API 的文件操作链路。1. 设计基线所有 Sandbox 请求统一走 sandbox-adapter方案的第一条基线非常明确FastGPT 不直接请求任何 Provider 的 API所有沙箱访问都收敛到fastgpt-sdk/sandbox-adapter这个 SDK 包。FastGPT - fastgpt-sdk/sandbox-adapter - OpenSandboxAdapter - OpenSandbox - fastgpt-agent-sandbox - SealosDevboxAdapter - Sealos Devbox - frameworks/sandbox/fastgpt设计文档中的几个已确认结论OpenSandbox 和 Sealos 都必须走sandbox-adapterFastGPT 不直接请求 Provider API。projects/agent-sandbox只用于 OpenSandbox 场景。Sealos 场景下Devbox 本身就是 Agent Sandbox 方案。Sealos 新 runtime 使用labring-actions/devbox-runtime#122新增的frameworks/sandbox/fastgpt不是 FastGPT 自维护的fastgpt-agent-sandbox镜像。这一分层在源码中得到完整印证。sdk/sandbox-adapter/src/adapters/index.ts提供了统一的工厂函数createSandbox根据provider分派到OpenSandboxAdapter或SealosDevboxAdapter并定义了联合类型SandboxFactoryConfigexport type SandboxProviderType opensandbox | sealosdevbox; export function createSandbox(config: SandboxFactoryConfig): ISandbox { switch (config.provider) { case opensandbox: return new OpenSandboxAdapter(config.connectionConfig, config.createConfig); case sealosdevbox: return new SealosDevboxAdapter(config.connectionConfig, config.createConfig); default: throw new Error(Unknown sandbox provider); } }SDK 对外暴露的契约是ISandbox见sdk/sandbox-adapter/src/contracts/sandbox.ts它是生命周期lifecycle、命令执行command、文件系统filesystem、健康检查health四个契约的交叉类型并额外要求provider标识、capabilities能力声明和可选的getEndpoint(port)端口访问能力。FastGPT 上层只依赖这个统一接口从而做到上层无感、Provider 可插拔。2. Provider 能力对比OpenSandbox 与 Sealos Devbox2.1 OpenSandbox 能力OpenSandbox 使用 FastGPT 自己维护的fastgpt-agent-sandbox镜像当前 FastGPT 依赖的 create 能力包括imageentrypointenvmetadatavolumesresourceLimits相关环境变量AGENT_SANDBOX_OPENSANDBOX_IMAGEFASTGPT_WORKDIRFASTGPT_ENABLE_CODE_SERVER设计文档特别强调这些是 OpenSandbox Provider 的实现细节不应直接套用到 Sealos。在sdk/sandbox-adapter/src/adapters/opensandbox/adapter.ts中可以看到OpenSandbox 的capabilities声明了command: { streaming: true, background: true, interrupt: true }、metrics: true和expirationRenewal: true即它支持 SSE 流式命令、后台执行、会话中断、指标采集与过期续期其文件系统能力直接透传底层 SDK 的sandbox.files读写、目录枚举、移动、权限、搜索等命令执行则消费 OpenSandbox 的execution_complete/error终态事件后主动关闭 SSE 响应体避免等待 Provider 延迟关闭造成固定尾延迟。2.2 Sealos Devbox 能力Sealos Devbox v2 server 的 create API 支持以下字段nameimageupstreamIDenvkubeAccesspauseAtarchiveAfterPauseTimelabelsSealos Devbox info API 返回statesshgateway.urlgateway.tokengateway.portgateway.uniqueIDSealos Devbox server 已原生提供 exec/file 能力POST /api/v1/devbox/{name}/execPOST /api/v1/devbox/{name}/files/uploadGET /api/v1/devbox/{name}/files/download这些接口内部转发到 Pod 内devbox-sdk-server:9757FastGPT 不需要自己实现 exec/file 通道。该结论在sdk/sandbox-adapter/src/adapters/sealos-devbox/client.ts中得到完整验证——DevboxClient实现了与上述 REST 端点一一对应的方法create、info、pause、resume、delete、exec、uploadFile、downloadFile并额外提供downloadFileStream通过原生 HTTP 响应流逐块 yield 数据避免大文件在 Node 内存中整体缓冲。请求统一携带Authorization: Bearer token。对应地SealosDevboxAdapter的capabilities见sdk/sandbox-adapter/src/adapters/sealos-devbox/adapter.ts声明为readonly capabilities: SandboxCapabilities { command: { streaming: false, background: false, interrupt: false }, filesystem: { streamingRead: true, streamingWrite: true }, metrics: true, expirationRenewal: false };即 Sealos 场景下命令执行是非流式的一次性返回 stdout/stderr/exitCode文件系统支持流式读写但不支持过期续期——生命周期由 Devbox 的pauseAt/archiveAfterPauseTime策略托管。由于 Devbox 在Running后其 exec 通道仍可能短暂不可用适配器内部实现了 Provider 专属的就绪探测waitUntilCommandReady()超时 300s、间隔 1s通过反复执行true命令探测 exec 通道同时getInfoWithProviderRetry会在 gateway 重启期间对 502/503/504 及no healthy upstream做有限重试但重试仅限初始 info 探测避免 create/resume/delete 等生命周期变更被重复执行。2.3 Devbox FastGPT Runtime 约定frameworks/sandbox/fastgptruntime 的关键约定codex-gateway默认监听1317Devbox v2 server gateway 固定反代 Pod 内1317code-server是 runtime 的可选浏览器编辑服务当前 FastGPT Skill 编辑页不再依赖它如果未来恢复 Provider 页面嵌入code-server可通过CODE_SERVER_ENABLEDtrue启动默认工作目录是/home/devbox/workspace默认 Codex home 是/codex-home。设计文档建议的 Sealos runtime env{ CODEX_GATEWAY_CWD: /home/devbox/workspace, CODEX_GATEWAY_CODEX_HOME: /codex-home }当前SandboxEditor文件 API 链路不需要启动code-server。如果后续重新接入 Provider 浏览器页面再额外传入{ CODE_SERVER_ENABLED: true }3. Adapter 方案统一 Create Spec 与字段映射3.1 统一 Create Spec 设计create spec 抽象放在agent-sandbox-adaptor。设计文档建议保留一个统一 schema不拆 Provider-specific schemaProvider 支持范围用 typed metadata 描述。文档中给出的核心 zod schema 结构const SandboxCreateSpecSchema z.object({ image: z .object({ repository: z.string(), tag: z.string().optional(), digest: z.string().optional() }) .optional(), env: z.record(z.string(), z.string()).optional(), metadata: z.record(z.string(), z.string()).optional(), labels: z.array(z.object({ key: z.string(), value: z.string() })).optional(), lifecycle: z .object({ pauseAt: z.string().optional(), archiveAfterPauseTime: z.string().optional() }) .optional(), kubeAccess: z .object({ enabled: z.boolean().optional(), roleTemplate: z.enum([view, edit, admin]).optional() }) .optional(), entrypoint: z.array(z.string()).optional(), workingDir: z.string().optional(), volumes: z.array(z.unknown()).optional(), resourceLimits: z.unknown().optional() });在仓库当前的 TypeScript 实现中这一契约以SandboxCreateSpec类型的形式落地于sdk/sandbox-adapter/src/types/sandbox.ts字段不仅覆盖文档列出的内容还包含timeoutSeconds、networkPolicy、extensions、upstreamID、skipHealthCheck、readyTimeoutSeconds、healthCheckPollingInterval等扩展项。类型注释明确写道The surface is intentionally wider than any single provider API: FastGPT builds one runtime profile and maps it to a provider-specific create config before it reaches the adapter factory.这个表面刻意比任何一个 Provider API 都宽FastGPT 构建统一的 runtime profile在到达适配器工厂前映射为 Provider 专属的 create config。这正是统一 schema typed metadata 描述支持范围设计意图的代码体现。3.2 OpenSandbox Adapter 映射OpenSandbox adapter 支持从统一 spec 中映射以下字段imageentrypointenvmetadatavolumesresourceLimits3.3 SealosDevbox Adapter 映射SealosDevbox adapter 的映射规则image→ Devboximage仅使用 Sealos 专用 runtime imageenv→ Devboxenvmetadata.sessionId或显式字段 → DevboxupstreamIDworkingDir→env.CODEX_GATEWAY_CWDlabels→ DevboxlabelskubeAccess→ DevboxkubeAccesslifecycle.pauseAt→ DevboxpauseAtlifecycle.archiveAfterPauseTime→ DevboxarchiveAfterPauseTime。Sealos adapter 不支持entrypoint、volumes、resourceLimits。源码SealosDevboxAdapter.buildCreateRequest()完整实现了上述映射workingDir会被写入env.CODEX_GATEWAY_CWD若调用方未显式传入该 envimage仅在repository存在时通过formatImageSpec序列化labels、upstreamID、kubeAccess、pauseAt、archiveAfterPauseTime按名透传。值得注意的是虽然设计文档称 Sealos 不支持resourceLimits当前源码的SealosDevboxCreateConfig已通过PickSandboxCreateSpec, ...包含了resourceLimits并将其映射为 Devbox 的cpu如2、memory如4096Mi和storageLimit如5G/10GiK8s resource quantity 格式同时对 cpu/memory 做正数校验、对 storage 做非空校验——从源码结构看这是后续在 Devbox API 支持资源限制后补充的能力。3.4 Sealos Image 配置策略默认让 Devbox server 的createDefaults.image配成frameworks/sandbox/fastgpt对应镜像FastGPT 创建 Devbox 时不传image。agent-sandbox-adaptor仍保留 Sealosimage映射能力用于调试、灰度或多 runtime 场景。如果 FastGPT 需要显式控制 runtime 镜像再新增 Sealos 专用配置AGENT_SANDBOX_SEALOS_IMAGE不要复用AGENT_SANDBOX_OPENSANDBOX_IMAGE这一约定在 FastGPT 侧的环境变量与 runtime profile 中均有体现详见第 5 节。4. 编辑器访问与文件通道4.1 当前产品形态不再嵌入 Provider 页面当前 FastGPT不再使用SandboxIframe嵌入code-server也不再要求浏览器直接访问 Provider endpoint。Skill 编辑页使用 FastGPT 自己的SandboxEditor文件树和 Monaco 编辑器Skill detail page - SandboxEditor - /api/core/ai/skill/edit 创建或复用 edit-debug sandbox - /api/core/ai/sandbox/listRecursive 递归读取 workspace 文件树 - /api/core/ai/sandbox/read 读取文件 - /api/core/ai/sandbox/write 写入文件 - /api/core/ai/sandbox/fileOp mkdir/delete/move/copy/upload - /api/core/ai/sandbox/download 下载文件或目录 - /api/core/ai/skill/save-deploy 从 workspace 打包并发布版本因此首期 Sealos 接入的验收重点是Provider adapter 的生命周期、exec 和文件系统能力而不是code-serveriframe、WebSocket 或 cookie/session 隔离。4.2 Backend 文件通道所有浏览器操作都回到 FastGPT API由后端鉴权后通过 sandbox adapter 操作远端文件系统Browser - FastGPT API - authSandboxSession - getSandboxClient(appId/userId/chatId 或 edit-debug) - ISandbox.execute / readFiles / writeFiles / listDirectory / getFileInfo / moveFiles - OpenSandboxAdapter 或 SealosDevboxAdapter关键边界浏览器只知道 FastGPT 的 API不持有 Provider endpoint、proxy target 或 Provider pathauthSandboxSession统一区分普通 chat sandbox 和 Skilledit-debugsandboxgetSandboxClient负责确保 sandbox 可用并刷新本地agent_sandbox_instances记录SandboxEditor只处理文件树/文件内容 UI不承担 Provider endpoint 解析。4.3 Adapter Endpoint 能力可选ISandbox.getEndpoint(port)可以作为 Provider 暴露端口的可选能力保留用于未来诊断或额外服务访问。当前 Skill 编辑链路不依赖getProxyTarget(service)sandbox-proxy/__fastgpt_proxy/code-server/SandboxIframe.tsxcode-serverHTTP/WS 访问如果后续重新引入code-server或codex-gateway的浏览器访问再单独设计 service-level endpoint/proxy target该设计不应混入当前SandboxEditor文件 API 链路。源码层面两个适配器都已实现getEndpointOpenSandbox 通过底层 SDK 的sandbox.getEndpointUrl(selector)返回SealosDevbox 则从 info API 的gateway.url推导 httpgate endpoint——解析出uniqueID优先取gateway.uniqueID否则从 gateway pathname 末段提取和 httpgate 域名支持httpgateDomain配置覆盖否则从-gateway.分隔符后的 host 截取拼装为devbox-uniqueID-port.domain形式的访问地址。这正是设计文档 TODO 第 4 条支持从gateway.url推导 httpgate endpoint用于未来端口访问或诊断的实现。4.4 Sealos runtime 服务划分Sealosframeworks/sandbox/fastgptruntime 仍可能包含两个服务codex-gateway1317code-server1318但它们不是当前 FastGPT Skill 编辑 UI 的首期依赖。当前 Sealos Provider 首期需要保证Devbox 可创建、恢复、暂停、删除execute可运行 shell 命令readFiles、writeFiles、listDirectory、getFileInfo、moveFiles等文件能力满足SandboxEditorworkingDir正确映射到/home/devbox/workspace并和 Skill 包解压、保存发布使用同一个 workspace。从SealosDevboxAdapter源码看rootPath的取值逻辑正是优先使用createConfig.workingDir去除末尾斜杠缺省回退到/home/devbox/workspace与 runtime 约定完全一致。文件能力中writeFiles将文件内容通过 Devboxfiles/upload上传支持流式 body 与duplex: halfreadFiles通过files/download拉取listDirectory、getFileInfo、moveFiles等操作由基类BaseSandboxAdapter通过CommandFilesystemPolyfill见sdk/sandbox-adapter/src/polyfills/command-filesystem.ts在 exec 通道之上合成实现。5. FastGPT 改造点5.1 Provider 配置新增或整理 Sealos 专用配置AGENT_SANDBOX_PROVIDERsealosdevbox AGENT_SANDBOX_SEALOS_BASEURL AGENT_SANDBOX_SEALOS_TOKEN AGENT_SANDBOX_SEALOS_IMAGE # 可选AGENT_SANDBOX_SEALOS_TOKEN是 Devbox server JWTnamespace 来自 token claims。首期 Sealos Provider 使用全局固定 token 和固定 namespace所有 FastGPT team/user 的 Devbox 都创建在该 namespace 下通过upstreamID和 labels 标记归属。这些环境变量在 FastGPT 服务端有完整的 schema 声明与校验packages/service/env.tsAGENT_SANDBOX_PROVIDERz.enum([sealosdevbox, opensandbox])为空时不启用沙箱AGENT_SANDBOX_SEALOS_BASEURLSealos Devbox 服务地址UrlSchemaAGENT_SANDBOX_SEALOS_TOKENSealos Devbox 访问 TokenAGENT_SANDBOX_SEALOS_WORK_DIRECTORY默认/home/devbox/workspaceAGENT_SANDBOX_SEALOS_IMAGESealos Devbox 运行态镜像启用sealosdevbox时必填与文档可选的表述相比当前实现要求配置该值才能通过校验说明该镜像现在由 FastGPT 侧显式注入。Provider 配置读取集中在packages/service/core/ai/sandbox/infrastructure/provider/config.tsgetConfiguredSandboxProvider()在AGENT_SANDBOX_PROVIDER缺失时直接抛错sealosdevbox分支读取AGENT_SANDBOX_SEALOS_BASEURL与AGENT_SANDBOX_SEALOS_TOKEN并执行validateSandboxConfig校验与 OpenSandbox 分支的AGENT_SANDBOX_OPENSANDBOX_*系列配置完全隔离印证了不要复用 OpenSandbox image env的设计要求。5.2 Sandbox 创建FastGPT 上层继续传递统一 create specOpenSandbox 使用现有镜像与 entrypoint 逻辑Sealos 只传支持字段{ image: sealosImageIfConfigured, env: { CODEX_GATEWAY_CWD: /home/devbox/workspace, CODEX_GATEWAY_CODEX_HOME: /codex-home }, metadata: { sessionId } }Provider 与 runtime profile 的映射由packages/service/core/ai/sandbox/infrastructure/provider/runtimeProfile统一负责.agents/design/core/ai/sandbox/index.md明确要求业务层不能根据 Provider 名称自行拼默认镜像、工作目录、HOME 和环境变量。其中sealosdevbox.ts的buildSealosRuntimeProfile()以AGENT_SANDBOX_SEALOS_WORK_DIRECTORY || /home/devbox/workspace为工作目录、以AGENT_SANDBOX_SEALOS_IMAGE为默认镜像。5.3 SandboxEditor 文件 APISkill 编辑页不再嵌入 Provider 页面前端固定使用SandboxEditor所有文件操作走 FastGPT API。首期需要保证以下接口在 Sealos Provider 下行为一致/api/core/ai/skill/edit创建或复用 edit-debug sandbox并把当前版本包解压到 workspace/api/core/ai/sandbox/listRecursive展示 Skill 文件树/api/core/ai/sandbox/read//api/core/ai/sandbox/write读写编辑器内容/api/core/ai/sandbox/fileOp目录和文件的创建、删除、移动、复制、上传/api/core/ai/sandbox/download下载 workspace 文件或目录/api/core/ai/skill/save-deploy从 sandbox workspace 打包 ZIP上传对象存储并切换当前版本。在仓库中可确认这些 API 的真实落点projects/app/src/pages/api/core/ai/skill/save-deploy.tsSkill 保存发布、projects/app/src/pages/api/core/ai/sandbox/download.ts文件/目录下载、upload.ts上传以及checkExist.ts、keepalive.ts、getTicket.ts、verifyTicket.ts、getHtmlPreviewLink.ts等配套接口Skill 侧还有debugChat.ts、runtime/init.ts、runtime/getStatus.ts、runtime/upgrade.ts、version/*等编辑调试与版本管理接口。整体目录结构符合设计文档中API 边界负责 parseApiInput 校验、sourceType/sourceId 转换、权限校验与 ticket 签发/验证的描述。后续如果要接入code-server或codex-gateway浏览器页面再新增对应 endpoint/proxy 设计。6. 集成测试待办与验收闭环设计文档末尾给出了完整的实施清单其中已完成项覆盖agent-sandbox-adaptor定义统一SandboxCreateSpecSchemaagent-sandbox-adaptorSealosDevbox adapter 支持env/upstreamID/kubeAccess/pauseAt/archiveAfterPauseTime/labels/imageagent-sandbox-adaptor保留getEndpoint(port)作为可选端口访问能力agent-sandbox-adaptorSealosDevbox adapter 支持从gateway.url推导 httpgate endpointagent-sandbox-adaptorOpenSandbox adapter 内收 direct endpoint 解析逻辑FastGPTSkill 编辑页改为SandboxEditor文件 API 链路不再依赖SandboxIframeFastGPT新增 Sealos runtime 配置避免复用 OpenSandbox image envFastGPTSealos provider 不再拒绝所有 create spec而是只传支持字段FastGPT新增 provider-aware sandbox 文件 API覆盖文件树、读写、文件操作和下载删除旧sandbox-proxy/SandboxIframe依赖路径。尚未完成的是最后一项11增加集成测试创建 Devbox、exec、upload/download、listDirectory、getFileInfo、moveFiles并通过SandboxEditor相关 API 验证编辑/发布闭环。从源码结构看上述 110 条已在sdk/sandbox-adapter与 FastGPT 服务端落地适配器、DevboxClient、runtime profile、SandboxEditor相关 API 均已存在集成测试是后续补充的验收环节。感兴趣的同学可以在此基础上编写针对 Sealos Devbox 的端到端用例覆盖创建 → 就绪探测 → exec → 文件读写 → 打包发布的完整生命周期。7. 总结两条关键边界回顾整份方案可以提炼出两条贯穿始终的设计边界Provider 抽象边界FastGPT 只面向ISandbox统一契约编程OpenSandbox 与 SealosDevbox 的差异能力声明、字段映射、生命周期语义、就绪探测全部封装在sdk/sandbox-adapter的适配器内业务层甚至不接触 Provider 的 API 地址。编辑器访问边界浏览器永远只访问 FastGPT 自己的 API由后端鉴权后通过 adapter 操作远端沙箱文件系统code-server/codex-gateway的浏览器访问属于可选的未来能力与当前SandboxEditor文件 API 链路严格隔离。对 Sealos 场景而言接入的本质是把 FastGPT 的 Skill 编辑工作区映射到 Devbox 的/home/devbox/workspace用upstreamID和 labels 做业务归属通过pauseAt/archiveAfterPauseTime托管生命周期——其余的 exec、文件、端口访问细节都由SealosDevboxAdapter与DevboxClient代为处理。深入阅读sdk/sandbox-adapter/src/adapters/sealos-devbox/adapter.ts、sdk/sandbox-adapter/src/adapters/sealos-devbox/client.ts、sdk/sandbox-adapter/src/adapters/index.ts、sdk/sandbox-adapter/src/types/sandbox.ts、sdk/sandbox-adapter/src/contracts/sandbox.ts、packages/service/core/ai/sandbox/infrastructure/provider/config.ts、packages/service/core/ai/sandbox/infrastructure/provider/runtimeProfile/sealosdevbox.ts、packages/service/env.ts、.agents/design/core/ai/sandbox/index.md以及projects/app/src/pages/api/core/ai/skill/save-deploy.ts与projects/app/src/pages/api/core/ai/sandbox/目录下的文件 API。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
