graph TD
    subgraph 新增文件["🆕 新增文件"]
        A1["packages/service/core/ai/sandbox/schema.ts"]
        A2["packages/service/core/ai/sandbox/controller.ts\n(含 SandboxClient 类 + cronJob)"]
        A4["packages/global/core/ai/sandbox/constants.ts"]
        A5["projects/app/src/pages/api/core/ai/sandbox/webideUrl.ts"]
        A6["packages/service/.../agent/sub/sandbox/utils.ts"]
    end

    subgraph 改造文件["✏️ 改造文件"]
        B1["packages/global/core/workflow/constants.ts"]
        B1b["packages/global/.../agent/constants.ts\n(SubAppIds + systemSubInfo)"]
        B3["packages/service/.../agent/utils.ts\n(getSubapps)"]
        B4["packages/service/.../agent/master/call.ts"]
        B5["packages/service/.../agent/master/prompt.ts"]
        B6["packages/service/.../ai/tool/index.ts"]
        B7["packages/service/.../ai/tool/toolCall.ts"]
        B9["projects/app/.../system/cron.ts"]
        B10["projects/app/.../chat/history/batchDelete.ts"]
        B11["packages/service/core/app/controller.ts"]
    end

    A6 -.-> B3
    A2 -.-> B4
    A2 -.-> B9
    A2 -.-> B10
    A2 -.-> B11
    A4 -.-> B5

// 沙盒系统提示词（useComputer=true 时追加到 System Prompt）
export const SANDBOX_SYSTEM_PROMPT = `你拥有一个独立的 Linux 沙盒环境（Ubuntu 22.04），可通过 shell 工具执行命令：
- 预装：bash / python3 / node / git / curl / wget
- 工作目录：/workspace（文件在本次会话内持久保留）
- 可自行安装软件包（apt / pip / npm）
- 可通过 timeout 参数指定命令超时时间`;

// 内置 shell 工具的 function calling schema
export const SANDBOX_SHELL_TOOL_SCHEMA = {
  type: 'function' as const,
  function: {
    name: 'sandbox_shell',
    description: '在独立 Linux 环境中执行 shell 命令，支持文件操作、代码运行、包安装等',
    parameters: {
      type: 'object',
      properties: {
        command: { type: 'string', description: '要执行的 shell 命令' },
        timeout: { type: 'number', description: '超时秒数（可选，由上游沙盒服务控制）' }
      },
      required: ['command']
    }
  }
};

// 沙盒状态枚举
export const SandboxStatusEnum = {
  running: 'running',
  stoped: 'stoped'
} as const;

// 沙盒默认配置
export const SANDBOX_SUSPEND_MINUTES = 5;

export const AGENT_SANDBOX_PROVIDER = process.env.AGENT_SANDBOX_PROVIDER
export const AGENT_SANDBOX_SEALOS_BASEURL = process.env.AGENT_SANDBOX_SEALOS_BASEURL
export const AGENT_SANDBOX_SEALOS_TOKEN = process.env.AGENT_SANDBOX_SEALOS_TOKEN

// 集合名: sandbox_instances
// 字段: sandboxId(唯一), appId, userId, chatId, status('running'|'stoped'), lastActiveAt, createdAt
// 索引: sandboxId(unique), chatId, appId, { status, lastActiveAt }

POST /api/core/ai/sandbox/file
Body: {
  appId: string;
  chatId: string;
  action: 'list' | 'read' | 'write';
  path: string;
  content?: string;  // write 时必需
  outLinkAuthData?: object;
}
Auth: authChatCrud
Response:
  - list: { action: 'list', files: Array<{ name, path, type, size }> }
  - read: { action: 'read', content: string }
  - write: { action: 'write', success: boolean }

POST /api/core/ai/sandbox/download
Body: {
  appId: string;
  chatId: string;
  path: string;  // 文件或目录路径
  outLinkAuthData?: object;
}
Auth: authChatCrud
Response: 文件流或 ZIP 压缩包

// 沙盒状态枚举
export const SandboxStatusEnum = {
  running: 'running',
  stoped: 'stoped'
} as const;

// 沙盒默认配置
export const SANDBOX_SUSPEND_MINUTES = 5;

// sandboxId 生成函数
export const generateSandboxId = (appId: string, userId: string, chatId: string): string => {
  return hashStr(`${appId}-${userId}-${chatId}`).slice(0, 16);
};

// 工具名称和图标
export const SANDBOX_NAME: I18nStringType = {
  'zh-CN': '虚拟机',
  'zh-Hant': '虛擬機',
  en: 'Sandbox'
};
export const SANDBOX_ICON = 'core/app/sandbox/sandbox';
export const SANDBOX_TOOL_NAME = 'sandbox_shell';

// 系统提示词
export const SANDBOX_SYSTEM_PROMPT = `你拥有一个独立的 Linux 沙盒环境（Ubuntu 22.04），可通过 ${SANDBOX_TOOL_NAME} 工具执行命令：
- 预装：bash / python3 / node / bun / git / curl
- 工作目录：/workspace（文件在本次会话内持久保留）
- 可自行安装软件包（apt / pip / npm）`;

// 工具定义
export const SANDBOX_SHELL_TOOL: ChatCompletionTool = {
  type: 'function',
  function: {
    name: SANDBOX_TOOL_NAME,
    description: '在独立 Linux 环境中执行 shell 命令，支持文件操作、代码运行、包安装等',
    parameters: {
      type: 'object',
      properties: {
        command: { type: 'string', description: '要执行的 shell 命令' },
        timeout: { type: 'number', description: '超时秒数', max: 300, min: 1 }
      },
      required: ['command']
    }
  }
};

// Zod Schema 用于参数验证
export const SandboxShellToolSchema = z.object({
  command: z.string(),
  timeout: z.number().optional()
});

// 新增
useAgentSandbox = 'useAgentSandbox',   // 启用沙盒（Computer Use）

export const env = createEnv({
  server: {
    AGENT_SANDBOX_PROVIDER: z.enum(['sealosdevbox']).optional(),
    AGENT_SANDBOX_SEALOS_BASEURL: z.string().optional(),
    AGENT_SANDBOX_SEALOS_TOKEN: z.string().optional(),
    // ...其他环境变量
  }
});

import type { ChatCompletionTool } from '@fastgpt/global/core/ai/type';
import { SubAppIds } from '@fastgpt/global/core/workflow/node/agent/constants';
import z from 'zod';

// Agent 调用时传递的参数
export const SandboxShellToolSchema = z.object({
  command: z.string(),
  timeout: z.number().optional()
});

// ChatCompletionTool 定义
export const sandboxShellTool: ChatCompletionTool = {
  type: 'function',
  function: {
    name: SubAppIds.sandboxShell,
    description: '在独立 Linux 环境中执行 shell 命令，支持文件操作、代码运行、包安装等',
    parameters: {
      type: 'object',
      properties: {
        command: { type: 'string', description: '要执行的 shell 命令' },
        timeout: { type: 'number', description: '超时秒数（可选，由上游沙盒服务控制）' }
      },
      required: ['command']
    }
  }
};

// 参数新增
export const getSubapps = async ({
  // ...现有参数...
  useAgentSandbox   // 新增
}: {
  // ...现有类型...
  useAgentSandbox?: boolean;  // 新增
}) => {
  // ...现有逻辑...

  /* Sandbox Shell */        // 新增，与 Dataset Search 同级
  if (useAgentSandbox) {
    completionTools.push(sandboxShellTool);
  }

  // ...后续不变...
};

位置：约第 440 行附近，工具调用分发逻辑
当前：已有 plan / dataset / file / model / tool 等分支
新增：if (toolName === SubAppIds.sandboxShell) { 调用 execShell() 并返回结果 }

// 新增参数 useAgentSandbox?: boolean
// 当 useAgentSandbox=true 时，追加 SANDBOX_SYSTEM_PROMPT
export const getMasterSystemPrompt = (
  systemPrompt?: string,
  hasUserTools: boolean = true,
  useAgentSandbox?: boolean  // 新增
) => {
  let prompt = `...现有逻辑...`;
  if (useAgentSandbox) {
    prompt += `\n\n${SANDBOX_SYSTEM_PROMPT}`;
  }
  return prompt;
};

位置：函数入口处，从 inputs 中读取 useAgentSandbox
传递给 runToolCall() 调用

位置：约第 58-109 行（构建 tools 参数处）和第 205-267 行（处理工具响应处）

import { cronJob } from '@fastgpt/service/core/ai/sandbox/controller';

export const startCron = () => {
  // ...现有定时任务...
  cronJob();  // 新增：注册沙盒停止定时任务
};

import { deleteSandboxesByChatIds } from '@fastgpt/service/core/ai/sandbox/controller';

// 在现有删除逻辑之后，异步触发（不 await，不阻塞主流程）
deleteSandboxesByChatIds(appId, chatIds).catch(console.error);

import { deleteSandboxesByAppId } from '../ai/sandbox/controller';

export const deleteAppDataProcessor = async ({ app, teamId }) => {
  const appId = String(app._id);

  // ...现有删除逻辑...

  // 新增：删除该应用下所有沙盒
  await deleteSandboxesByAppId(appId);

  await MongoApp.deleteOne({ _id: appId });
};

# Sealos devbox
AGENT_SANDBOX_PROVIDER=sealos-devbox
AGENT_SANDBOX_SEALOS_BASEURL=
AGENT_SANDBOX_SEALOS_TOKEN=

graph LR
    P1["Phase 1\n基础设施"] --> P2["Phase 2\n核心调度"] --> P3["Phase 3\n生命周期"] --> P4["Phase 4\n前端/API"]

    P1 --- P1a["constants.ts\nschema.ts\ncontroller.ts\n(含 cronJob)"]
    P2 --- P2a["NodeInputKeyEnum\nAgent 模板\ncall.ts / prompt.ts\ntoolCall.ts"]
    P3 --- P3a["注册 cronJob\nbatchDelete.ts\napp/controller.ts"]
    P4 --- P4a["webideUrl API\n前端入口（后续）"]