Balanov/shim

项目介绍

Shim 是一个单文件、零依赖的终端 AI 代理框架。它通过受支持的 HTTP API 连接模型，原生支持 OpenAI 兼容接口和 Anthropic，并为 Ollama、LM Studio、llama.cpp、OpenAI、OpenRouter、Gemini、GitHub Models、Hugging Face 及自定义端点提供预设；同时可加载 MCP 服务器和 Agent Skills，对外提供可脚本化的 CLI 与自然语言管理命令。

自然语言层是一个白名单命令路由：常见英文和俄文管理语句可离线处理，其他语言可以指定本地模型做路由。会改变状态的命令需要确认。Shim 本身不是推理引擎，GGUF 等本地权重需要由 Ollama、llama.cpp 等推理服务器承载。

快速使用

从 Releases 下载 Windows、macOS 或 Linux 的静态二进制，放入 PATH，然后运行配置向导并进入交互终端：

shim setup
shim

使用 Go 1.25 及以上时，也可以安装固定版本：

go install github.com/Balanov/shim/cmd/shim@v0.1.0
shim setup

从源码构建：

git clone https://github.com/Balanov/shim.git
cd shim
go test ./...
go build -trimpath -ldflags="-s -w" -o shim ./cmd/shim
./shim setup

配置完成后添加模型。API Key 从环境变量读取，不会写入 Shim 的配置文件：

$env:OPENROUTER_API_KEY = "..."
shim model add openrouter your/model --name main --use
shim model test main

本地推理服务器可用 shim model discover --add 自动发现。之后既可以进入交互会话输入自然语言，也可以执行一次性任务，例如 shim run --read-only "explain this repository"。完整命令面用 shim help 查看（命令示例、提供商表）。

权限与安全

默认 ask 模式允许读取、列出和搜索工作区文件；写文件、执行 Shell 命令和调用 MCP 工具都需要确认。shim permissions read-only、ask、auto 修改全局默认值，--read-only 和 --yes 只作用于单次运行。文件工具会拒绝工作区内的词法路径穿越和符号链接逃逸。

Shim 不是操作系统级沙箱：Shell 命令和 MCP 服务器以当前用户权限运行，路径检查无法限制恶意进程。处理不可信工作负载应使用容器、虚拟机或系统沙箱，模型输出、仓库文本、Skills 和 MCP 响应都应视为不可信数据（权限说明）。Skills 本身也是不可信指令，使用前应审查，尤其是请求 Shell 或网络访问的 Skills。

配置与会话

配置位于操作系统用户配置目录下的 shim/config.json，可用 SHIM_CONFIG 或 --config 覆盖；会话是旁边的追加式 JSONL 文件。可用 shim session list、shim session new 和 shim run --resume SESSION_ID 管理，shim status、shim doctor、shim config show 用于检查状态。网络流量只发生在显式模型调用、Skill 下载、本地发现和已配置的 MCP 服务器。

MCP 服务器可通过 stdio 或 Streamable HTTP 注册，工具以 mcp_<server>_<tool> 命名；HTTP 头与 stdio 环境变量支持 ${ENV_VAR} 展开。Skills 会从全局 skills/ 目录、.shim/skills/、.agents/skills/ 和 .claude/skills/ 发现，只有名称和描述进入提示词，完整指令按需加载。

使用约束

项目使用 Go 标准库实现，README 给出的本地测量结果是：维护者 Windows 机器上 v0.1.0 精简二进制 7.29 MiB，shim --version 30 次运行的中位启动时间 9.96 ms；这不是跨平台性能保证。流式输出与取消仍在路线图中，OS 级沙箱配置和远程 MCP 的 OAuth 辅助也尚未完成。许可证为 MIT。

HotRepo 点评

Shim 在 2026-11-02 进入 HotRepo 新项目快照，约四小时窗口内新增 117 Star，Fork 为 0，暂无 GitHub 日榜名次记录。这是一次单点观察，样本很小，不足以说明采用情况。README 中更具体的差异点在于设计取舍：用无 TUI、无守护进程、无运行时依赖的静态小二进制，在可脚本化 CLI 之上加一层白名单自然语言控制，并通过适配器接入模型、MCP 和 Skills，而不是做一个完整的终端工作空间。