UFO 项目 LinuxAgent MCP 命令体系实战：execute_command 与 get_system_info 完整指南

UFO 项目 LinuxAgent MCP 命令体系实战execute_command 与 get_system_info 完整指南【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO导读在 UFO 开源仓库UFO³: Weaving the Digital Agent Galaxy中LinuxAgent是一个专为 Linux 命令行环境设计的轻量级单智能体它通过MCPModel Context Protocol工具与 Linux 系统交互。本文以仓库文档 documents/docs/linux/commands.md 为核心深入剖析 LinuxAgent 的两大原子工具——execute_command通用 Shell 命令执行与get_system_info系统信息采集并结合 linux_mcp_server.py 源码揭示其安全模型与实现原理。读完本文你将掌握如何通过Command消息与命令调度器驱动 LinuxAgent 执行 CLI 任务、如何解读结构化返回结果与退出码、如何基于顺序/条件/错误恢复策略组合命令完成多轮迭代任务以及 MCP 服务器层的命令白名单、危险模式拦截与 API 密钥认证机制。LinuxAgent 命令架构MCP Server 集成LinuxAgent 与 Linux 系统的所有交互均通过Linux MCP Server提供的 MCP 工具完成。这些工具是 CLI 任务执行的原子构建块把系统相关的操作全部隔离在 MCP 服务器层这种架构带来两个直接收益可测试性命令可以被 mockAgent 层的单元测试无需真实执行 Shell 命令可移植性MCP 服务器可以远程部署Agent 与具体操作系统解耦。从源码看该 MCP 服务器的实现位于 ufo/client/mcp/http_servers/linux_mcp_server.py基于fastmcp构建默认以streamable-http传输方式运行在localhost:8010。Command Dispatcher命令通过Command消息统一封装后交给调度器Command Dispatcher执行。Command是 aip/messages.py 中定义的 Pydantic 模型包含四个字段tool_name要执行的工具名称如execute_commandparameters工具参数字典如{command: df -h, timeout: 30}tool_type工具类型取值data_collection或actioncall_id可选的调用唯一标识用于与执行结果Result的call_id对应。典型用法from aip.messages import Command # Create command command Command( tool_nameexecute_command, parameters{command: df -h, timeout: 30}, tool_typeaction ) # Execute command via dispatcher results await command_dispatcher.execute_commands([command]) execution_result results[0].result调度器支持一次提交多个Command返回对应的Result列表每个Result包含statussuccess/failure/skipped/none、error、result实际结果载荷等字段见 aip/messages.py。execute_command通用 Shell 命令执行用途执行任意的白名单内的Shell 命令并捕获结构化结果。工具规范tool_name execute_command parameters { command: df -h, # Shell command to execute timeout: 30, # Execution timeout (seconds, default: 30) cwd: /home/user # Optional working directory }参数说明结合源码 linux_mcp_server.pycommand必填要执行的命令字符串api_key必填API 密钥必须与服务器端环境变量UFO_MCP_API_KEY一致否则认证失败timeout可选默认 30最长执行秒数服务器会将其钳制在1–120秒范围内cwd可选执行时的工作目录必须是存在的绝对路径服务器会先解析并校验防止路径穿越。执行流程结果结构命令执行结果统一结构化为{ success: True, # Boolean indicating success exit_code: 0, # Process exit code stdout: Filesystem Size Used Avail Use% Mounted on\n/dev/sda1 100G 50G 46G 52% /\n, stderr: # Standard error output }其中success由exit_code 0推导得出stdout/stderr均以 UTF-8 解码errorsreplace避免编码异常导致整体失败。当校验或执行异常时返回{success: False, error: ...}形式。常见用例Use CaseCommand ExampleDescriptionFile Operationsls -la /home/userList directory contentsText Processinggrep error /var/log/syslogSearch log filesSystem Monitoringtop -bn1Check system processesDisk Managementdf -hCheck disk spaceNetwork Operationsping -c 4 example.comTest network connectivityArchive Creationtar -czf backup.tar.gz /dataCreate compressed archivesPackage Managementapt list --installedList installed packages注意上表中的命令示例对应文档语义。在当前仓库的实际实现中execute_command采用严格白名单策略仅允许一组只读/诊断型基础命令如ls、cat、grep、find、df、ps、ping等并以shellFalse方式执行详见下文「源码级安全模型」一节。错误处理退出码解读Unix 惯例0成功1-125命令特定错误126命令不可执行127命令未找到128n被信号 n 终止错误结果示例{ success: False, error: Command not found: invalid_cmd }另外当命令执行超过timeout时服务器会杀掉子进程并返回Timeout after {timeout}s.的错误信息避免悬挂进程。安全注意事项!!!warning Command Safety MCP 服务器会拦截危险命令包括- rm -rf / - 递归删除根目录 - Fork bombs - :(){ :|: };: - mkfs - 文件系统格式化 - dd if/dev/zero - 设备覆写 - shutdown、reboot - 系统关机 命令以用户权限执行不自动提权。超时保护可防止进程悬挂。get_system_info系统信息采集用途用标准命令收集基础 Linux 系统信息。工具规范tool_name get_system_info parameters {} # No parameters required除必填的api_key外无需其他参数。服务器端使用固定参数列表执行命令无用户输入、无 shell 解释天然避免注入。采集的信息Info TypeCommandData Returnedunameuname -aSystem and kernel informationuptimeuptimeSystem uptime and load averagesmemoryfree -hMemory usage statistics (human-readable)diskdf -hDisk space for all mounted filesystems执行流程结果示例{ uname: Linux hostname 5.15.0-91-generic #101-Ubuntu SMP x86_64 GNU/Linux, uptime: 14:23:45 up 5 days, 3:12, 2 users, load average: 0.52, 0.58, 0.59, memory: total used free shared buff/cache available\nMem: 15Gi 8.2Gi 1.5Gi 256Mi 5.8Gi 7.0Gi\nSwap: 8.0Gi 512Mi 7.5Gi, disk: Filesystem Size Used Avail Use% Mounted on\n/dev/sda1 100G 50G 46G 52% /\n/dev/sdb1 500G 200G 276G 42% /data }单个命令执行失败不会导致整体失败对应键会填充Error: exception文本便于后续诊断。命令执行流水线原子构建块execute_command与get_system_info是 LinuxAgent 的两个原子操作它们在 CONTINUE 状态下被反复编排系统操作隔离将系统操作隔离在 MCP 服务器层后架构实现了清晰分层Agent 层专注于 LLM 推理与工作流编排MCP 层处理系统相关的命令执行。这提供了可测试性命令可 mock与可移植性MCP 服务器可远程部署。命令组合从单条命令到多轮任务LinuxAgent 在 CONTINUE 状态下逐轮执行命令每轮结果写入内存memory供下一轮决策使用。以下三种组合模式来自 commands.md 的实战范式。顺序执行基于上一轮结果决定本轮命令# Round 1: Check disk space { action: { tool: execute_command, arguments: {command: df -h /data} } } # Result: 276GB available # Round 2: Create backup (informed by Round 1 result) { action: { tool: execute_command, arguments: { command: tar -czf /data/backup.tar.gz /home/user } } }条件执行LLM 依据命令结果特别是exit_code做分支决策# Round 1: Check if file exists { action: { tool: execute_command, arguments: {command: ls /data/backup.tar.gz} } } # Result: exit_code2 (file not found) # Round 2: File doesnt exist, create it { thought: Backup doesnt exist, creating new one, action: { tool: execute_command, arguments: {command: tar -czf /data/backup.tar.gz /home/user} } }错误恢复主方案失败时切换到备选方案# Round 1: Try privileged command { action: { tool: execute_command, arguments: {command: systemctl restart nginx} } } # Result: successFalse, errorPermission denied # Round 2: Switch to user-level alternative { thought: Dont have sudo access, using alternative approach, action: { tool: execute_command, arguments: {command: kill -HUP $(cat /var/run/nginx.pid)} } }源码级安全模型linux_mcp_server.py 深入剖析ufo/client/mcp/http_servers/linux_mcp_server.py 是 Linux MCP Server 的完整实现其安全模型远比文档列举的危险命令拦截更严格共分四层1. 命令白名单Allow-list服务器维护ALLOWED_SHELL_COMMANDS集合linux_mcp_server.py#L116-L170只放行只读/诊断型基础命令例如文件类ls、pwd、cat、head、tail、搜索类grep、find、which、文本处理类wc、sort、uniq、cut、tr、系统信息类uname、uptime、free、df、ps、网络诊断类ping、traceroute、nslookup、dig以及echo、date、stat、diff等。校验时对基础命令做os.path.basename归一化防止/usr/bin/bash这类路径绕过。2. 危险模式扫描Dangerous-pattern scan_DANGEROUS_PATTERNSlinux_mcp_server.py#L173-L189拦截Shell 元字符;|、命令替换$(/${、find -exec/-execdir、反向 Shell 特征/dev/tcp/、/dev/udp/、I/O 重定向/ 以及换行/空字节注入。3. 逐命令参数策略Argument policies对python/python3只允许--version/-V防止python3 -c执行任意代码对find禁止-exec、-delete、-ok、-fprint*等副作用参数linux_mcp_server.py#L192-L238。4. 执行与传输层防护shellFalse通过asyncio.create_subprocess_exec直接执行 token 列表Shell 元字符永远不会被解释linux_mcp_server.py#L417-L425API 密钥认证_validate_api_key使用hmac.compare_digest做常数时间比较且未配置UFO_MCP_API_KEY时默认拒绝所有请求fail-closedlinux_mcp_server.py#L308-L320cwd 校验_validate_cwd解析绝对路径并确保目录存在防止路径穿越linux_mcp_server.py#L323-L338DNS-rebinding 防护LocalhostGuardMiddleware拒绝 Host/Origin 非本地的请求拦截跨域fetchlinux_mcp_server.py#L69-L110。服务器启动入口linux_mcp_server.py#L492-L524在未设置UFO_MCP_API_KEY时直接报错退出可用如下方式启动export UFO_MCP_API_KEYyour-secret-key python -m ufo.client.mcp.http_servers.linux_mcp_server --port 8010提示create_bash_mcp_server默认绑定localhost如需远程访问可指定--host 0.0.0.0但源码会打印显式警告——这会暴露到所有网络接口仅在确实需要远程调用时才应启用。最佳实践工具使用需要快速概览系统状态时优先用get_system_info一次调用拿到 uname/uptime/内存/磁盘自定义或复杂操作使用execute_command务必检查success字段和exit_code判断是否真正成功尽量解析stdout中的结构化数据如df -h的输出合理设置timeout防止命令悬挂拖死整个任务循环。安全!!!warning Security Best Practices MCP 服务器自带防护但仍需谨慎- 危险命令会被自动拦截 - 命令仅以用户权限执行 - 尽量不使用 sudo需要用户交互 - 日志输出前应对输出做脱敏可能包含敏感数据错误处理先检查success再认定命令成功解析stderr获取错误细节对瞬时错误实现重试主方案失败时提供替代方案错误恢复模式。与其他 Agent 命令对比AgentCommand TypesExecution LayerResult FormatLinuxAgentCLI SysInfoMCP serversuccess/exit_code/stdout/stderrAppAgentUI APIAutomator MCPUI state API responsesHostAgentDesktop ShellAutomator MCPDesktop state resultsLinuxAgent 的命令集刻意保持精简execute_command通用命令执行get_system_info标准化系统信息这种简洁性正对应 CLI 环境以文本和命令驱动为本质的特点。从状态机角度看命令执行发生在 CONTINUE 状态的三阶段流水线中LLM 决策 → 命令执行 → 内存更新LLM 返回的status决定下一轮状态是 CONTINUE、FINISH 还是 FAIL相关实现见 ufo/agents/states/linux_agent_state.py 与策略文档 documents/docs/linux/strategy.md。延伸阅读State Machine - 理解命令执行如何融入 3 态 FSMProcessing Strategy - 命令如何集成进三阶段流水线LinuxAgent Overview - 回到 LinuxAgent 架构总览MCP Overview - MCP 服务器实现细节linux_mcp_server.py - 本主题核心源码aip/messages.py -Command/Result消息模型定义【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考