AI导哈

AI代理安全命令行工具

smartsh是一个为AI编码代理设计的命令行执行工具，通过本地守护进程提供安全、高效的命令执行和结果摘要功能。

  • by BegaDeveloper
  • Go
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 BegaDeveloper/smartsh

使用说明

>聪明_

用于AI编码代理的安全、紧凑的命令执行。

MCP服务器+本地守护进程 光标 和 克劳德代码 一种安全、令牌高效的方式来运行shell命令。

为什么聪明？

当AI代理运行终端命令时，它们会转储 巨大的原木 进入上下文——燃烧令牌并混淆模型。

聪明 修复此问题：

  • 通过本地守护进程运行命令(smartshd)
  • 退货 紧凑结构JSON 而不是原始产量
  • 用途 奥拉玛 用于命令结果的智能摘要
  • 适用于 安全检查 执行前（阻止危险命令）
  • 支持 风险审批工作流程 用于破坏性操作
  • 自动截断输出 大量代币储蓄

安装（3个步骤）

第一步：安装Ollama（必填）

smartsh使用Ollama进行智能命令输出摘要。先安装。

macOS/Linux：

curl -fsSL https://ollama.com/install.sh | sh
ollama serve
ollama pull llama3.2:3b

窗户：

  1. 从下载并安装https://ollama.com/download
  2. 然后在PowerShell中：
ollama serve
ollama pull llama3.2:3b

步骤2：安装smartsh

如果Ollama已经安装，这是用户安装smartsh时需要运行的唯一终端命令。

macOS/Linux：

curl -fsSL https://raw.githubusercontent.com/BegaDeveloper/smartsh/main/scripts/install.sh | sh

Windows（PowerShell）：

powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/BegaDeveloper/smartsh/main/scripts/install.ps1 | iex"

通过Go安装：

go install github.com/BegaDeveloper/smartsh/cmd/smartsh@latest
go install github.com/BegaDeveloper/smartsh/cmd/smartshd@latest
smartsh setup-agent

安装程序正在运行 setup-agent 自动。安装完成后，您可以将这些文件放入 ~/.smartsh/:

文件 与一起使用
cursor-mcp.json 光标
claude-code-mcp.json 克劳德代码
agent-instructions.txt 粘贴到Cursor/Claude规则中

步骤3：连接到Cursor或Claude代码

对于光标：

复制 cursor-mcp.json 进入您的项目：

# macOS / Linux
cp ~/.smartsh/cursor-mcp.json /path/to/your/project/.cursor/mcp.json

# Windows
copy %USERPROFILE%\.smartsh\cursor-mcp.json C:\path\to\your\project\.cursor\mcp.json

然后粘贴 ~/.smartsh/agent-instructions.txt 进入光标→ 设置→ 规则。

克劳德代码：

复制 claude-code-mcp.json 作为您的Claude桌面配置：

# macOS / Linux
cp ~/.smartsh/claude-code-mcp.json ~/.claude/claude_desktop_config.json

# Windows
copy %USERPROFILE%\.smartsh\claude-code-mcp.json %USERPROFILE%\.claude\claude_desktop_config.json

验证

smartsh doctor

生成的MCP JSON（参考）

如果您更喜欢手动设置，以下是生成的 cursor-mcp.json / claude-code-mcp.json 看起来像：

如果您手动编写JSON，请使用您自己的绝对值 smartsh 二进制路径 command （它因用户和操作系统而异）。

{
  "mcpServers": {
    "smartsh": {
      "command": "/ABSOLUTE/PATH/TO/smartsh",
      "args": ["mcp"],
      "env": {
        "SMARTSH_DAEMON_URL": "http://127.0.0.1:8787",
        "SMARTSH_DAEMON_TOKEN": "<auto-generated-token>",
        "SMARTSH_SUMMARY_PROVIDER": "ollama",
        "SMARTSH_OLLAMA_REQUIRED": "true",
        "SMARTSH_OLLAMA_ALWAYS": "true",
        "SMARTSH_OLLAMA_URL": "http://127.0.0.1:11434",
        "SMARTSH_OLLAMA_MODEL": "llama3.2:3b",
        "SMARTSH_MCP_HTTP_TIMEOUT_SEC": "900",
        "SMARTSH_MCP_DEFAULT_UNSAFE": "true",
        "SMARTSH_MCP_DEFAULT_REQUIRE_APPROVAL": "false",
        "SMARTSH_MCP_DEFAULT_ALLOWLIST_MODE": "off"
      }
    }
  }
}

令牌由以下人员自动生成 smartsh setup-agent 并存储在 ~/.smartsh/config.

规则片段（粘贴到Cursor/Claude规则中）

For command execution, always use the smartsh MCP tool (smartsh_run).
In some clients it appears as smartsh-local_smartsh_run.
Never use direct shell execution unless explicitly requested by the user.
Do not use run_terminal_cmd when the smartsh MCP tool is available.
Prefer summarized tool output and avoid dumping full terminal logs.

运作原理

┌─────────────┐     MCP JSON-RPC      ┌─────────┐     HTTP      ┌──────────┐
│ Cursor /     │ ──────────────────▶  │ smartsh  │ ──────────▶  │ smartshd │
│ Claude Code  │ ◀──────────────────  │   mcp    │ ◀──────────  │  daemon  │
└─────────────┘   compact summary     └─────────┘   execute     └──────────┘
  1. 代理发送命令 通过MCP工具(smartsh_run)
  2. smartsh mcp 转发到本地守护进程
  3. smartshd 验证安全性→ 执行→ 通过Ollama总结
  4. 压缩JSON 返回给代理（不是原始日志）

示例响应

{
  "status": "failed",
  "exit_code": 1,
  "summary": "command failed (exit code 1): Cannot find module '@app/auth'",
  "error_type": "compile",
  "primary_error": "Cannot find module '@app/auth'",
  "next_action": "Fix TypeScript compiler errors and rerun build/test.",
  "failed_files": ["src/app/auth/auth.service.ts"],
  "top_issues": ["TS2307: Cannot find module '@app/auth'"]
}

与500多行原始数据相比 tsc 代理通常会转储的输出。

特性

安全与政策

  • 阻止危险命令(rm -rf /、特权升级、管道到外壳）
  • 风险审批工作流程——代理必须在运行破坏性操作之前进行确认
  • 命令分配模式(off / warn / enforce)
  • 项目级政策通过 .smartsh-policy.yaml

代币节省

  • 成功运行返回 仅摘要 （无输出尾）
  • 运行失败返回 截尾 +结构化错误信息
  • 默认情况下启用MCP紧凑模式
  • 可通过以下方式配置尾部尺寸 SMARTSH_MCP_MAX_OUTPUT_TAIL_CHARS

Ollama总结

  • Ollama是默认摘要提供程序
  • 仅将截断、编辑的输出发送到本地Olama
  • 强制执行严格的JSON响应模式
  • 如果Ollama不可用，则返回确定性解析

Daemon功能

  • BoltDB中的持久作业（重新启动后仍然存在）
  • 异步执行 job_id 轮询
  • SSE状态流
  • PTY互动会议
  • 执行隔离（超时、内存、CPU、环境分配列表）
  • 默认情况下需要令牌身份验证
  • 普罗米修斯指标 /metrics

配置

环境变量

变量 默认值 描述
SMARTSH_DAEMON_URL http://127.0.0.1:8787 守护进程地址
SMARTSH_DAEMON_TOKEN （自动生成） 身份验证令牌（必需）
SMARTSH_DAEMON_DISABLE_AUTH false 禁用身份验证（不推荐）
SMARTSH_SUMMARY_PROVIDER ollama deterministic, ollama，或 hybrid
SMARTSH_OLLAMA_URL http://127.0.0.1:11434 奥拉马终点
SMARTSH_OLLAMA_MODEL llama3.2:3b Ollama模型
SMARTSH_OLLAMA_REQUIRED true 如果Ollama不可用，则失败
SMARTSH_OLLAMA_ALWAYS false 对于成功的跑步，也使用Ollama总结
SMARTSH_OLLAMA_TIMEOUT_SEC 8 Ollama请求超时
SMARTSH_MCP_COMPACT_OUTPUT true 启用紧凑的响应
SMARTSH_MCP_MAX_OUTPUT_TAIL_CHARS 600 最大输出尾部字符数
SMARTSH_MCP_HTTP_TIMEOUT_SEC 300 MCP→守护进程HTTP超时（秒）
SMARTSH_MCP_DEFAULT_UNSAFE false 默认值 unsafe 用于MCP工具调用
SMARTSH_MCP_DEFAULT_REQUIRE_APPROVAL true MCP工具调用的默认风险批准要求
SMARTSH_MCP_DEFAULT_ALLOWLIST_MODE warn MCP工具调用的默认分配列表模式(off/warn/enforce)
SMARTSH_DAEMON_ADDR 127.0.0.1:8787 守护进程监听地址

危险命令

当代理试图运行破坏性命令时（例如。 rm -rf)，smartsh返回 status=needs_approval 带着一个 approval_id。然后，代理人会打电话 smartsh_approve 随着 decision=yes 或 decision=no.

使用 unsafe=true 仅当您想完全绕过审批步骤时，才在工具调用中使用。

手册下载

平台 文件
macOS苹果硅（M1/M2/M3） smartsh_darwin_arm64.tar.gz
macOS英特尔 smartsh_darwin_amd64.tar.gz
Linux x64 smartsh_linux_amd64.tar.gz
Linux arm64 smartsh_linux_arm64.tar.gz
Windows x64 smartsh_windows_amd64.zip

下载自 发布.

从源头构建

go build -o smartsh ./cmd/smartsh
go build -o smartshd ./cmd/smartshd

# Cross-platform release archives
./scripts/build.sh        # macOS/Linux
.\scripts\build.ps1       # Windows

释放流程（维护人员）

git checkout main && git pull
go test ./...
./scripts/build.sh
git add . && git commit -m "release: vX.Y.Z"
git push origin main
git tag vX.Y.Z
git push origin vX.Y.Z

如果自动释放未触发：

gh release create vX.Y.Z \
  dist/release/smartsh_darwin_amd64.tar.gz \
  dist/release/smartsh_darwin_arm64.tar.gz \
  dist/release/smartsh_linux_amd64.tar.gz \
  dist/release/smartsh_linux_arm64.tar.gz \
  dist/release/smartsh_windows_amd64.zip \
  dist/release/checksums.txt \
  --title vX.Y.Z --generate-notes

发布 · 问题 · 许可证

用Go构建。专为人工智能辅助开发而设计。

相关 MCP