使用说明
🚀 古巴执行官
AI代理的高级shell命令执行 --具有安全策略引擎、进程生命周期管理、有界输出捕获、POSIX信号和令牌高效响应的模型上下文协议（MCP）服务器。
6个工具。零配置。POSIX原生。默认安全。
为什么选择古巴执行官？
现有的命令执行MCP是精简的包装 subprocess.run.Cuba Exec解决了真正的问题：
| 问题 | 现有MCP | 古巴执行官 |
|---|---|---|
| 输出溢出（cat/dev/urandom） | ❌ OOM崩溃 | ✅ 64KB已绑定 |
| 后台进程 | ❌ 仅同步 | ✅ 启动/状态/信号 |
| 杀死子进程（npm run-dev） | ❌ 孤儿 | ✅ 进程组终止（setsid） |
| 发送stdin（REPL、提示） | ❌ 不支持 | ✅ 全标准输入管 |
| POSIX信号（SIGTERM、SIGKILL） | ❌ 不支持 | ✅ 5个信号+优雅关机 |
| 命令分配列表/块列表 | ⚠️ 一些 | ✅ Both+shell运算符验证 |
| 目录限制 | ⚠️ 罕见 | ✅ 路径解析反遍历 |
| 审计日志 | ❌ 无 | ✅ 结构化JSON到stderr |
| 令牌高效输出 | ❌ 详细JSON | ✅ TOON紧凑格式 |
| 空闲进程清理 | ❌ 资源泄漏 | ✅ 1小时TTL自动清理 |
| 叉式炸弹防护 | ❌ 无 | ✅ 信号量（20） |
| 进程发现 | ❌ 无 | ✅ 列出所有管理流程 |
快速开始
1.先决条件
- Python 3.14+
- Linux/macOS （进程组需要POSIX）
2.安装
git clone https://github.com/LeandroPG19/cuba-exec.git
cd cuba-exec
uv venv && uv pip install -e .
3.配置您的AI编辑器
{
"mcpServers": {
"cuba-exec": {
"command": "/path/to/cuba-exec/.venv/bin/python",
"args": ["-m", "cuba_exec"]
}
}
}
无需任何环境变量。零配置文件。它只是正常工作——默认情况下会阻止25个危险命令。
6工具
run --执行并等待
run(command="ls -la", cwd="/tmp", timeout_ms=5000)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
command |
字符串 | 必需的 | Shell命令 |
cwd |
string | 无 | 工作目录 |
env |
dict | None | 环境变量（与当前变量合并） |
timeout_ms |
int | 30000 | 超时（毫秒） |
max_output |
int | 65536 | 输出缓冲区大小（字节） |
shell |
string | /bin/sh | Shell可执行文件 |
答复：
[exit:0 time:12ms trunc:no]
total 156
drwxrwxrwt 22 root root 4096 Mar 8 2026 .
...
start --后台流程
start(command="npm run dev", cwd="/app")
答复：
[pid:12345 state:running]
Background process started. Use status(12345) to check output.
status --检查后台进程
status(pid=12345, tail_bytes=4096)
答复：
[pid:12345 state:running exit:- time:5432ms bytes:8192 trunc:no]
Server running on http://localhost:3000
send_signal --POSIX信号
send_signal(pid=12345, sig="SIGTERM")
SIGTERM触发器 优雅关闭：SIGTERM→ 等待5秒→ 西格尔。
有效信号： SIGTERM, SIGKILL, SIGINT, SIGHUP, SIGQUIT.
send_input --stdin管
send_input(pid=12345, stdin="print('hello')\n")
用于交互式进程（Python REPL、bash提示符等）。
list_processes --流程发现
list_processes()
答复：
[processes:2]
pid:12345 state:running exit:- time:5432ms bytes:8192 cmd:npm run dev
pid:12346 state:completed exit:0 time:1200ms bytes:256 cmd:echo done
🛡️ 安全策略引擎
Cuba Exec包含一个多层安全引擎，是所有MCP命令服务器中最全面的。
安全层
| 图层 | 描述 | 配置 |
|---|---|---|
| 命令允许列表 | 只能执行列出的命令 | CUBA_EXEC_ALLOWED_COMMANDS |
| 命令阻止列表 | 危险命令总是被拒绝 | CUBA_EXEC_BLOCKED_COMMANDS |
| 壳牌操作员验证 | 在以下时间验证每个子命令 ;, &&, ||, | |
自动 |
| 目录限制 | 限制 cwd 到允许的路径（反遍历） |
CUBA_EXEC_ALLOWED_DIRS |
| 审计日志 | 每次执行的结构化JSON日志 | CUBA_EXEC_AUDIT |
默认行为（零配置）
开箱即用，Cuba Exec阻止25个危险命令：
rm, dd, mkfs, shutdown, reboot, halt, poweroff, init, systemctl,
passwd, chown, chmod, chgrp, mount, umount, fdisk, parted,
iptables, nft, ip6tables, crontab, at, useradd, userdel,
groupadd, groupdel, visudo
生产硬化
export CUBA_EXEC_ALLOWED_COMMANDS="ls,cat,echo,grep,find,head,tail,wc,git,python3,node,npm"
export CUBA_EXEC_BLOCKED_COMMANDS="rm,dd,mkfs,shutdown"
export CUBA_EXEC_ALLOWED_DIRS="/home/user/project,/tmp"
export CUBA_EXEC_AUDIT=1
壳牌操作员旁通预防
ls && rm -rf / --the rm 之后 && 也根据blocklist/allowlist进行验证。
已解析的运算符： ;, &&, ||, | --每个子命令都独立检查。
审核日志（stderr）
{"ts":"2026-03-08T15:00:00-0600","event":"exec","command":"ls -la","pid":12345,"exit":0,"ms":12,"ok":true}
输出格式（TOON）
所有响应都使用面向令牌的对象表示法——紧凑的标头，与冗长的JSON相比，每次工具调用可节省约200个令牌。
[exit:0 time:1543ms trunc:no]
...output...
错误代码
| 错误 | 退出代码 | 字段 | 示例 |
|---|---|---|---|
| 未找到命令 | 127 | ENOENT |
nonexistent_binary |
| 权限被拒绝 | 126 | EACCES |
cat /etc/shadow |
| 超时 | -1 | TIMEOUT |
sleep 60 1秒超时 |
| 信号消失 | -9 | SIGKILL |
进程被信号终止 |
| 被政策封锁 | — | BLOCKED |
rm -rf / |
头+尾输出缓冲器——香农（1948）
命令输出已 极端情况下的高熵 （前序+结果/错误）和中间的低熵（进度条、重复日志）。
┌─────────────┬───────────────────────────────┬──────────────────────────────────────────┐
│ Head (25%) │ Truncated middle │ Tail (75%) │
│ ~16KB │ [... N bytes truncated ...] │ ~48KB (ring buffer) │
└─────────────┴───────────────────────────────┴──────────────────────────────────────────┘
- 头部：缓冲区的前25%——捕获标头、版本信息
- 尾部：最后75%通过环形缓冲区捕获结果、错误（最高熵）
- 环形缓冲区：O（1）写，O（C）存储器（Cormen等人，CLRS第4版）
- 默认：每个进程64KB。最大内存：20×64KB=1.28MB
POSIX过程组——IEEE标准1003.1
npm run dev 生成子进程。向父母发送SIGTERM不会杀死孩子。
Cuba Exec通过以下方式创建流程组 setsid:
asyncio.create_subprocess_exec(..., start_new_session=True)
os.killpg(os.getpgid(pid), signal.SIGTERM) # Kills entire tree
优雅地关闭
SIGTERM → wait 5s → SIGKILL (if still alive)
两阶段关机（Stevens&Rago，2013）：SIGTERM允许清理，SIGKILL是不可捕捉的。
配置
所有默认值都是开箱即用的。通过环境变量进行覆盖：
| 设置 | 默认值 | 环境变量 |
|---|---|---|
| 最大并发进程数 | 20 | CUBA_EXEC_MAX_PROCS |
| 输出缓冲区大小 | 64KB | CUBA_EXEC_BUFFER_SIZE |
| 空闲过程TTL | 1小时 | CUBA_EXEC_TTL |
| 关机超时 | 5s | CUBA_EXEC_SHUTDOWN_TIMEOUT |
| 允许的命令 | --（全部） | CUBA_EXEC_ALLOWED_COMMANDS |
| 已阻止的命令 | 25个默认值 | CUBA_EXEC_BLOCKED_COMMANDS |
| 允许的目录 | --（全部） | CUBA_EXEC_ALLOWED_DIRS |
| 审核日志记录 | 关闭 | CUBA_EXEC_AUDIT |
建筑
cuba-exec/
├── pyproject.toml # 1 dependency: fastmcp
└── src/
└── cuba_exec/
├── __init__.py
├── __main__.py # Entry point
├── server.py # FastMCP 6 tool definitions (~105 LOC)
├── security.py # SecurityPolicy engine (~135 LOC)
├── process_manager.py # Lifecycle FSM + signals + TTL (~520 LOC)
└── output_buffer.py # Head+Tail ring buffer (~110 LOC)
总计：约880 LOC。 FastMCP SDK处理协议样板。
依赖关系（共1个）
| 包装 | 用途 |
|---|---|
fastmcp |
MCP协议服务器——来自类型提示的自动工具模式，Pydantic验证 |
其他都是Python stdlib： asyncio, os, signal, time, json, re, pathlib.
古巴生态系统的一部分
| 项目 | 目的 |
|---|---|
| 古巴记忆 | 持久记忆——知识图谱、Hebbian学习 |
| 古巴思考 | 顺序推理——认知引擎、NLI、MCTS |
| 古巴搜索 | 网络搜索——研究、抓取、验证、文档查找 |
| 古巴执行官 | Shell执行——进程生命周期、安全性、有界输出、POSIX信号 |
一起： 记忆+推理+搜索+执行 --有能力的人工智能代理的四大支柱。
学术参考文献
| # | 引文 | 用于 |
|---|---|---|
| 1 | Yang等人（2024）。“SWE代理：代理计算机接口。”NeurIPS | ACI设计、输出截断、护栏 |
| 2 | 香农（1948）。“传播的数学理论” | 信息论输出策略 |
| 3 | IEEE标准1003.1-2024。“POSIX.1:系统接口” | 进程组、集合ID、信号 |
| 4 | Cormen等人（2022）。《算法导论》第4版 | 环形缓冲区O（1）分析 |
| 5 | 迪杰斯特拉（1965）。“协作顺序进程” | 信号量并发限制 |
| 6 | 史蒂文斯和拉戈（2013）。“APUE”第3版 | 流程生命周期，优雅关机 |
| 7 | 卡通（2025）。“面向令牌的对象表示法” | 令牌减少95-97% |
| 8 | OWASP（2025）。“代理应用程序前10名” | 安全策略设计，允许列表/阻止列表 |
许可证
CC BY NC 4.0 --免费使用和修改， 非商业用途.
作者
莱安德罗·佩雷斯G。
- github： @LeandroPG19
- 电子邮件： leandropatodo@gmail.com