Shell Proxy

shellproxy

shellproxy 是一款简洁的命令执行代理，可解决 AI Agent 的“终端盲区”问题——垃圾字符、ANSI 转义码、Shell 初始化噪声和编码问题都会导致 AI Agent 无法读取终端输出。

它位于 AI Agent 与终端之间，在干净、可控的环境中执行命令，并返回结构化的 JSON 输出。

---

功能

• ANSI 清理 — 移除所有颜色代码、光标移动和控制序列
• 绕过 Shell 初始化 — 使用 bash --norc --noprofile 运行，PowerShell 使用 -NoProfile 等
• 自动检测 Shell — 在 Windows 上优先使用 WSL bash，无法使用时回退到 cmd；在 Unix 上使用 bash/sh
• 结构化 JSON 输出 — exit_code、stdout、stderr、duration_ms、shell、truncated
• 流式模式 — 长时间运行的命令按行输出
• 文件输出 — 除 stdout 外，还可将结果写入文件
• MCP 服务 — 将 run_command 和 run_command_stream 作为 MCP 工具提供
• 可配置 — 支持环境变量、配置文件 ~/.shellproxy.json 或 CLI 标志

---

安装

Unix（Linux、macOS、WSL）

curl -sSL https://raw.githubusercontent.com/aliforever/shellproxy/main/install.sh | sh

Windows（PowerShell）

irm https://raw.githubusercontent.com/aliforever/shellproxy/main/install.ps1 | iex

从源码安装

git clone https://github.com/aliforever/shellproxy
cd shellproxy
go build -o shellproxy .

---

使用方法

运行命令（缓冲模式）

shellproxy run "echo hello world"

输出：

{
  "exit_code": 0,
  "stdout": "hello world\n",
  "stderr": "",
  "duration_ms": 12,
  "shell": "wsl",
  "truncated": false
}

以纯文本格式输出

shellproxy run --output text "ls -la"

按行流式输出

shellproxy run --stream "npm install"

输出：

[stdout] added 342 packages in 4.2s
[stdout] found 0 vulnerabilities
--- exit_code: 0 | duration: 4213ms | shell: wsl ---

将结果写入文件

shellproxy run --file /tmp/result.json "go build ./..."

显式指定 Shell

shellproxy run --shell cmd "dir"
shellproxy run --shell bash "cat /etc/os-release"
shellproxy run --shell pwsh "Get-Date"

注入环境变量

shellproxy run --env "NODE_ENV=production" --env "PORT=8080" "node server.js"

设置超时

shellproxy run --timeout 30 "long-running-command"

截断较大的输出

shellproxy run --truncate 4096 "cat large-file.log"

---

MCP 服务模式

通过 stdio 将 shellproxy 启动为 MCP 服务：

shellproxy serve

AI 客户端配置

将 shellproxy 添加到 AI 客户端的 MCP 配置中：

{
  "mcpServers": {
    "shellproxy": {
      "command": "shellproxy",
      "args": ["serve"],
      "env": {
        "SHELLPROXY_SHELL": "auto",
        "SHELLPROXY_TIMEOUT": "60"
      }
    }
  }
}

可用的 MCP 工具

工具	描述
run_command	执行命令并返回完整的 JSON 结果
run_command_stream	执行命令并逐行返回输出

run_command 参数：

参数	类型	必填	描述
command	string	✓	要执行的 Shell 命令
shell	string		auto、cmd、bash、wsl、pwsh、sh
cwd	string		工作目录
timeout_seconds	number		超时时间（0 = 不限时）
env	object		额外的环境变量，格式为 {"KEY": "VALUE"}
truncate_bytes	number		输出的最大字节数

---

配置

shellproxy 可通过环境变量或 JSON 配置文件进行配置。

配置文件：~/.shellproxy.json

{
  "shell": "auto",
  "timeout_seconds": 60,
  "strip_ansi": true,
  "output_mode": "buffered",
  "output_file": "",
  "truncate_bytes": 0
}

环境变量

变量	默认值	描述
SHELLPROXY_SHELL	auto	要使用的 Shell
SHELLPROXY_TIMEOUT	60	超时时间（秒）
SHELLPROXY_STRIP_ANSI	true	清理 ANSI 代码（设为 0/false 可禁用）
SHELLPROXY_OUTPUT_MODE	buffered	buffered、stream 或 file
SHELLPROXY_OUTPUT_FILE		文件输出模式下的文件路径
SHELLPROXY_TRUNCATE_BYTES	0	将输出截断为 N 字节
SHELLPROXY_CONFIG	~/.shellproxy.json	覆盖配置文件路径

---

全局标志

Flags:
  --shell string    Shell to use: auto, cmd, bash, wsl, pwsh, sh (default "auto")
  --timeout int     Command timeout in seconds 0 = no timeout (default 60)
  --strip-ansi      Strip ANSI escape codes from output (default true)
  -h, --help        help for shellproxy

---

从源码构建

# Build for current platform
make build

# Build for all platforms
make build-all

# Run tests
make test

# Run specific test suites
make test-strip      # ANSI stripping tests
make test-detect     # Shell detection tests
make test-exec       # Integration exec tests

---

许可证

MIT