smartsh (Bega Developer)

>聪明\_

用于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/:

步骤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": "",
        "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

______________________________________________________________________

配置

环境变量

危险命令

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

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

______________________________________________________________________

手册下载

下载自 发布.

______________________________________________________________________

从源头构建

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构建。专为人工智能辅助开发而设计。