从零开始构建 Manus 系统：03-Sandbox Filesystem从零开始构建 Manus 系统：03-Sand

从零开始构建 Manus 系统：03-Sandbox Filesystem

📍 导航指南

在集成了浏览器操控能力后，我们继续为 AI Agent 扩展能力边界。这次，我们要赋予它"文件专家"的身份——能够读取代码、写入文档、搜索内容、甚至重构整个项目。

🔍 为什么需要文件系统？ → 第一部分：背景与架构 - 理解 AI 访问文件系统的必要性
🛠️ 如何集成？ → 第二部分：环境构建 - Node.js MCP Filesystem Server 配置
⚙️ 怎么管理？ → 第三部分：服务编排 - Supervisor 进程管理和权限控制
🔌 如何连接？ → 第四部分：MCP集成 - MCP Filesystem 的工作原理
🧪 验证测试 → 第五部分：测试验证 - 完整的功能测试和应用场景

引言

在从零开始构建 Manus 系统：02-Sandbox Chrome 中，我们让 AI Agent 能够浏览互联网。现在，我们要让它成为真正的"文件专家"——能够读取源代码、分析项目结构、修改文件、甚至进行大规模的重构。

文件系统操作是 AI Agent 最基础但也最强大的能力之一。从简单的文件读取，到复杂的代码分析和重构，文件系统 MCP 为 AI 提供了与开发者相同的文件操作权限。

第一部分：背景与架构 🔍

为什么要给沙盒装文件系统？

对于人类开发者来说，文件系统是我们日常工作的基础。对于 AI Agent 而言，集成文件系统能力意味着：

代码理解与分析：读取源代码、理解项目结构、分析依赖关系。
文档生成与维护：创建 README、API 文档、配置文件。
项目重构与优化：大规模代码修改、文件重组、架构调整。
数据处理与存储：读取配置文件、处理数据文件、生成报告。
开发环境管理：安装依赖、运行构建脚本、管理项目文件。

架构设计：MCP Filesystem

我们的文件系统集成基于以下设计：

graph LR
    Agent[AI Agent] --MCP Protocol--> MCP_Server[MCP Filesystem Server]
    MCP_Server --POSIX API--> Filesystem[(Linux Filesystem)]
    Filesystem --Volume Mount--> Host_Workspace[/host/workspace/]

关键设计决策：

官方 MCP 实现：使用 @modelcontextprotocol/server-filesystem，确保协议兼容性和功能完整性
受限工作区：所有操作限制在 /root/shared/workspace/ 目录，防止越权访问
POSIX 兼容：标准的文件系统操作，支持权限、所有者、时间戳等元数据
异步操作：支持大文件的异步读取和写入

第二部分：环境构建 🛠️

Node.js MCP Filesystem Server

文件系统 MCP 是官方提供的 Node.js 实现，我们已经在 Dockerfile 中安装了它：

# 全局安装 MCP Filesystem Server
RUN npm install -g @modelcontextprotocol/server-filesystem@latest

这个包提供了 8 个核心文件操作工具：

读取操作
- read_file - 读取文件内容
- read_directory - 列出目录内容
- get_file_info - 获取文件元数据
写入操作
- write_file - 创建或覆盖文件
- create_directory - 创建目录
修改操作
- search_replace - 在文件中进行精确的字符串替换
- move_file - 移动或重命名文件
删除操作
- delete_file - 删除文件或目录

权限和安全配置

文件系统操作的安全性至关重要：

# 创建受限的工作区目录
RUN mkdir -p /root/shared/workspace /root/shared/workspace/screenshots /root/shared/workspace/downloads

安全措施：

路径限制：所有操作都被限制在 /root/shared/workspace/ 及其子目录
权限检查：服务器会验证文件访问权限
资源限制：防止读取过大的文件或进行无限递归
审计日志：所有文件操作都会记录到 supervisord 日志

第三部分：服务编排 ⚙️

Supervisor 配置

在 supervisord.conf 中，我们配置了 MCP Filesystem Server：

; MCP Filesystem Server (Official - Node.js)
[program:mcp-filesystem]
command=/usr/bin/npx -y @modelcontextprotocol/server-filesystem /root/shared/workspace
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=601
startsecs=5

进程依赖管理

文件系统服务器的优先级设置为 601，高于基础服务但低于应用服务：

xvfb (100) → fluxbox (200) → chrome (200) → x11vnc (400) → websockify (500)
mcp-shell (600) → mcp-filesystem (601) → mcp-chrome (602) → mcp-manager (603)

这种优先级确保了：

基础环境先就绪：X11 和网络服务先启动
MCP 服务顺序启动：Shell 基础功能 → 文件系统 → 浏览器 → 管理器
依赖关系正确：文件系统服务不需要等待其他服务，可以独立启动

第四部分：MCP集成 🔌

MCP Filesystem 配置

MCP Filesystem Server 通过以下参数启动：

npx @modelcontextprotocol/server-filesystem /root/shared/workspace

关键参数：

工作目录：/root/shared/workspace - 所有操作的根目录
协议版本：自动协商最新的 MCP 协议版本
并发限制：内置的并发控制，防止文件系统过载

实际应用场景

当 MCP Filesystem 集成完成后，AI Agent 就可以执行以下操作：

代码分析:

{ "name": "read_file", "args": { "path": "src/main.py", "encoding": "utf-8" } }

Agent 可以读取源代码文件，理解项目结构和实现逻辑。

项目文档生成:

{ "name": "write_file", "args": { "path": "README.md", "content": "# My Project\n\n..." } }

Agent 可以创建和维护项目文档。

批量重构:

{ "name": "search_replace", "args": {
  "file_path": "config.py",
  "old_string": "DEBUG = True",
  "new_string": "DEBUG = False"
}}

Agent 可以进行精确的代码修改。

文件管理:

{ "name": "read_directory", "args": { "path": "." } }

Agent 可以浏览目录结构，了解项目组织。

第五部分：测试验证 🧪

测试脚本：test_filesystem.py

为了验证文件系统 MCP 的功能，我们可以创建一个测试脚本：

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

async def test_filesystem_operations():
    """Test MCP Filesystem Server operations."""
    # Configure connection to containerized MCP server
    server_params = StdioServerParameters(
        command="docker",
        args=[
            "exec", "-i",
            "sandbox-sandbox-os-1",  # Container name
            "npx", "-y", "@modelcontextprotocol/server-filesystem",
            "/root/shared/workspace"
        ],
        env=None
    )

    print("🔌 Connecting to MCP Filesystem Server...")

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # 1. Initialize connection
            await session.initialize()

            # 2. List available tools
            tools = await session.list_tools()
            print(f"✨ Connected! Found {len(tools.tools)} filesystem tools")

            # 3. Test directory listing
            print("📁 Listing workspace directory...")
            dir_result = await session.call_tool("read_directory", {
                "path": "."
            })
            print(f"Directory contents: {dir_result}")

            # 4. Test file creation
            print("📝 Creating test file...")
            await session.call_tool("write_file", {
                "path": "test_file.txt",
                "content": "Hello from MCP Filesystem!"
            })

            # 5. Test file reading
            print("📖 Reading test file...")
            file_result = await session.call_tool("read_file", {
                "path": "test_file.txt"
            })
            print(f"File content: {file_result}")

            # 6. Test file search and replace
            print("🔍 Testing search and replace...")
            await session.call_tool("search_replace", {
                "file_path": "test_file.txt",
                "old_string": "Hello from MCP Filesystem!",
                "new_string": "Modified by MCP Filesystem Server!"
            })

            # 7. Verify modification
            modified_result = await session.call_tool("read_file", {
                "path": "test_file.txt"
            })
            print(f"Modified content: {modified_result}")

            print("✅ All filesystem operations completed successfully!")

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

性能和安全验证

性能测试：

文件大小限制：测试大文件的读取性能
并发操作：测试多个文件操作的并发处理
搜索效率：测试在大型代码库中的搜索性能

安全验证：

路径遍历防护：确保无法访问 ../ 等上级目录
权限检查：验证文件权限的正确处理
资源限制：测试对大文件的处理限制

常见问题 FAQ

Q: MCP Filesystem 和传统的文件操作工具有什么区别？

A: MCP Filesystem 提供了标准化的 AI 友好的接口。传统的文件操作工具（如 cat, ls, sed）需要 AI 理解 shell 命令，而 MCP Filesystem 直接提供语义化的工具（如 read_file, search_replace），让 AI 能够更直观地表达意图。

Q: 如何处理大文件？

A: MCP Filesystem 内置了文件大小限制（通常在几MB以内）。对于超大文件，服务器会返回错误提示。建议将大文件拆分处理，或使用流式处理方式。

Q: 支持哪些文件编码？

A: 主要支持 UTF-8 编码。对于其他编码的文件，需要在读取时指定编码参数，或预先转换编码。

Q: 如何处理二进制文件？

A: MCP Filesystem 主要设计用于文本文件。对于二进制文件（如图片、压缩包），建议使用其他专门的工具。服务器会检测文件类型并给出相应提示。

Q: 文件权限如何处理？

A: 服务器会检查文件权限，但不会尝试提升权限。如果 AI 需要修改只读文件，需要先通过 shell 工具修改文件权限。

Q: 如何实现文件的版本控制？

A: MCP Filesystem 本身不提供版本控制功能。但 AI 可以结合 git 命令（通过 MCP Shell）来实现文件的版本管理。

📝 结语

通过集成 MCP Filesystem，我们的沙盒环境从"命令执行器"进化为真正的"文件专家"。AI Agent 现在不仅能运行命令，还能深入理解和修改代码，成为开发者的真正合作伙伴。

在下一篇文章中，我们将探讨 MCP Manager 的实现，看看 AI 如何智能地管理其他 MCP 服务器，实现更高级的元编程能力。

📚 技术参考

实现时间: 2026-01-23 MCP 工具数量: 8 个文件操作工具 安全等级: 🛡️ 高 (路径限制 + 权限检查)

从零开始构建 Manus 系统：03-Sandbox Filesystem