您的位置: 首页> Python

从零开始构建 Manus 系统：04-Sandbox Shell

匿名上传

发布时间:2026-01-27 10:06:02

从零开始构建 Manus 系统：04-Sandbox Shell

导航指南

在赋予了 AI Agent 文件操作能力之后，我们面临的下一个挑战是：如何让 Agent 不仅仅是"写代码"，还能"运行代码"？Shell MCP 就是这一环节的关键拼图。

为什么需要 Shell？ → 第一部分：背景与架构 - 理解命令执行的必要性
️ 如何构建？ → 第二部分：环境构建 - Shell MCP Server 安装与配置
️ 怎么管理？ → 第三部分：服务编排 - Supervisor 进程管理
如何连接？ → 第四部分：MCP集成 - Shell MCP 的工作原理与工具
验证测试 → 第五部分：测试验证 - 实际运行命令测试

引言

在之前的文章中，我们的 AI Agent 已经学会了上网（从零开始构建 Manus 系统：02-Sandbox Chrome）和管理文件（从零开始构建 Manus 系统：03-Sandbox Filesystem）。然而，对于一个全栈工程师 Agent 来说，仅仅能修改代码文件是不够的。

它还需要能够：

安装项目依赖 (npm install, pip install)
运行构建脚本 (npm run build, make)
启动开发服务器 (python manage.py runserver)
检查系统状态 (ps aux, top)

这就是 Shell MCP 发挥作用的地方。它为 AI Agent 提供了一个受控的终端接口，使其能够像人类开发者一样执行各种系统命令。

第一部分：背景与架构

为什么 AI 需要终端权限？

虽然文件系统操作允许 Agent 修改代码，但无法验证代码是否能正常运行。集成 Shell 能力使得 Agent 能够：

闭环开发：编写代码 -> 运行测试 -> 读取报错 -> 修复代码。
环境配置：自动安装缺失的库和工具。
动态调试：通过打印日志或运行调试命令来诊断问题。
项目部署：执行构建和部署脚本。

架构设计：Shell MCP

我们的 Shell 集成方案如下：

graph LR
    Agent[AI Agent] --MCP Protocol--> MCP_Shell[Shell MCP Server]
    MCP_Shell --spawn--> Shell_Process[Bash/Zsh Process]
    Shell_Process --exec--> System_Commands[System Commands]
    System_Commands --stdout/stderr--> MCP_Shell

关键设计决策：

基于 Node.js：使用 @kevinwatt/shell-mcp 实现，易于与现有的 Node.js 生态集成。
Docker 隔离：所有的命令执行都限制在 Docker 容器内，即使 Agent 执行了 rm -rf /，也只会影响临时的沙盒环境，不会危及宿主机。
非交互式执行：主要针对一次性命令执行（exec），而非交互式终端（TTY），这简化了协议处理并减少了卡死的风险。

第二部分：环境构建 ️

Shell MCP Server 安装

我们在 Dockerfile 中安装了基于 Node.js 的 Shell MCP Server：

# Install official MCP servers
RUN npm install -g @kevinwatt/shell-mcp@latest

这个包提供了一个标准的 MCP 服务器，能够接收客户端的请求并在本地执行 Shell 命令。

安全沙盒机制

给予 AI Shell 权限是高风险的，因此我们通过多层防御来确保安全：

容器隔离：Agent 只能操作容器内的文件和进程。
网络限制：容器网络通过 Docker 网络进行隔离（虽然 Agent 可以上网，但无法访问宿主机内网服务）。
超时控制：在客户端层面（如 mcp_client.py）设置了命令执行超时（通常为 120秒），防止命令无限挂起。

第三部分：服务编排 ️

Supervisor 配置

在 supervisord.conf 中，我们配置了 Shell MCP Server 的启动参数：

; MCP Shell Command Server (Official)
[program:mcp-shell]
command=/usr/bin/node /usr/lib/node_modules/@kevinwatt/shell-mcp/build/index.js
directory=/root/shared/workspace
environment=NODE_ENV="production"
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0
priority=600
startsecs=5

启动顺序与优先级

Shell MCP 的优先级设置为 600，是所有 MCP 服务中优先级最高的（启动最早）：

mcp-shell (600)：基础能力，不依赖其他服务。
mcp-filesystem (601)：文件操作。
mcp-chrome (602)：浏览器操作。
mcp-manager (603)：管理服务。

这种设计是因为后续的某些服务初始化可能需要依赖 Shell 命令来检查环境或预处理数据。

第四部分：MCP集成

核心工具：run_command

Shell MCP 主要暴露了一个核心工具（具体名称取决于版本，通常为 run_command 或 execute）：

`run_command`

执行指定的 Shell 命令并返回结果。

参数：
- command: (string) 要执行的命令字符串。
- cwd: (string, optional) 执行命令的工作目录。
返回：
- stdout: 标准输出内容。
- stderr: 标准错误内容。
- exit_code: 退出码（0 表示成功）。

实际应用场景

检查环境版本:

{ "name": "run_command", "args": { "command": "node --version" } }

安装依赖:

{ "name": "run_command", "args": { "command": "npm install lodash" } }

运行测试:

{ "name": "run_command", "args": { "command": "pytest tests/" } }

第五部分：测试验证

测试脚本：test_shell.py

我们可以编写一个 Python 脚本来验证 Shell MCP 的功能：

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_shell_operations():
    """Test MCP Shell Server operations."""
    # Configure connection to containerized MCP server
    server_params = StdioServerParameters(
        command="docker",
        args=[
            "exec", "-i",
            "sandbox-sandbox-os-1",
            "node", "/usr/lib/node_modules/@kevinwatt/shell-mcp/build/index.js"
        ],
        env=None
    )

    print(" Connecting to MCP Shell Server...")

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List tools
            tools = await session.list_tools()
            print(f" Connected! Found tools: {[t.name for t in tools.tools]}")

            # Test 1: Simple echo
            print("n Test 1: Echo command")
            result = await session.call_tool("run_command", {
                "command": "echo 'Hello from MCP Shell!'"
            })
            print(f"Result: {result}")

            # Test 2: Check system info
            print("n Test 2: System info")
            result = await session.call_tool("run_command", {
                "command": "uname -a"
            })
            print(f"System Info: {result}")

            # Test 3: Create a file via shell
            print("n Test 3: Create file via shell")
            await session.call_tool("run_command", {
                "command": "echo 'Created via shell' > /root/shared/workspace/shell_test.txt"
            })
            
            # Verify file creation
            verify = await session.call_tool("run_command", {
                "command": "cat /root/shared/workspace/shell_test.txt"
            })
            print(f"File content: {verify}")

if __name__ == "__main__":
    asyncio.run(test_shell_operations())

安全边界验证

在测试中，我们应当确认：

权限限制：Agent 应该是以 root 身份在容器内运行（这是 Docker 默认行为），但因为容器是隔离的，所以是安全的。
环境隔离：验证无法访问宿主机文件系统。
资源清理：命令执行结束后，进程是否正确退出，没有产生僵尸进程。

常见问题 FAQ

Q: 支持交互式命令吗（如 vim, top）？

A: 不支持。MCP Shell 主要设计用于非交互式的命令执行。对于像 vim 这样的工具，应该使用 Filesystem MCP 的 write_file 或 search_replace 来修改文件。对于 top，可以使用 top -b -n 1 这种批处理模式来获取一次性输出。

Q: 命令执行超时了怎么办？

A: 长时间运行的命令（如大型构建或服务器进程）可能会导致超时。对于启动服务器（如 npm start），建议使用后台运行的方式（nohup ... &），或者由 MCP 客户端层实现特殊的长连接处理逻辑。

Q: 如何处理需要输入密码的命令（sudo）？

A: 容器内默认是 root 用户，通常不需要 sudo。如果确实需要交互式输入密码，目前的 Shell MCP 实现不支持标准输入流的交互，建议通过免密配置或环境变量来解决。