内容
<div align="center">
# 🛡️ 斯卡恩
**一款快速、操作系统沙盒化的模型上下文协议网关，内置代码模式引擎和 shell 输出令牌压缩 — 仅需一个 Rust 二进制文件。**
[](https://github.com/Rani367/Skarn/actions/workflows/ci.yml)
[](https://www.rust-lang.org)
[](#license)
*降低代理的 API 费用，同时物理阻止它删除磁盘或泄露您的秘密。*
</div>
---
## 为什么
自主 AI 编码代理有三个昂贵且危险的习惯：
1. **令牌膨胀** — 它们直接将原始 `cargo test` / `npm install` 输出和 *数百* 个 MCP 工具模式发送到上下文窗口。
2. **MCP 缩放墙** — 连接几个 MCP 服务器，模型现在需要携带每个工具的 JSON 模式，每次调用都如此。
3. **远程代码执行设计** — 让代理运行 shell 命令或 LLM 生成的代码 *就是* RCE 在您的机器上。
**斯卡恩** 是一个二进制文件，它解决了这三个问题：
- **聚合** 下游 MCP 服务器到一个小而恒定的工具表面（`search` / `read_tool_docs` / `execute`）使用 **代码模式** — 模型编写一个短脚本，在沙盒中协调工具，因此兆字节的中间有效载荷永远不会到达上下文窗口。
- **压缩** shell 输出，使用声明性、每个工具的过滤器 — 通常 **70–90% 更少的令牌**，同时 *保证* 错误和警告存活。
- **沙盒** 执行所有操作，使用 **操作系统原生内核原语** — macOS 上的 Seatbelt，Linux 上的 Landlock + seccomp，Windows 上的 AppContainer — **无需 Docker，无需守护进程，无需 VM**。
```
┌──────────────────────────── 斯卡恩（一个二进制文件） ────────────────────────────┐
│ │
AI 代理 ─┼─▶ search / execute ──▶ 代码模式隔离 ──▶ skarn.callTool() ──┐ │
（Claude │ （≈1k 令牌， （QuickJS，密封， │ │ │
Code， │ 不是 30k） 操作系统沙盒） ▼ │ │
Cursor…） │ ┌────────────┐ ┌────────────┐ │
│ 压缩的 15 令牌 ◀── 返回摘要 ──┤ MCP 客户端 │… │ MCP 客户端 │ │
│ 结果，不是 15k （大数据留在 └─────┬──────┘ └─────┬──────┘ │
│ 日志转储 盒子里） ▼ ▼ │
└────────────────────────────────────────────── Postgres MCP GitHub MCP ──────┘
```
## 安装
```bash
# 一行命令（macOS / Linux）：
curl -fsSL https://raw.githubusercontent.com/Rani367/Skarn/main/install.sh | sh
# 或使用 Cargo：
cargo install skarn
```
这会安装 `skarn` 二进制文件。
## 快速开始
```bash
# 1. 搭建一个配置文件并查看集成代码片段
skarn init
# 2. 检查您的机器上激活了哪个内核沙盒
skarn doctor
# 3. 将您的代理指向网关（Claude Code / Cursor / Windsurf）：
# 添加到您的 MCP 配置：
# { "mcpServers": { "skarn": { "command": "skarn", "args": ["serve"] } } }
# 4. （可选）尝试针对您配置的服务器运行代码模式脚本：
skarn exec --code 'return (await skarn.listTools()).length'
# 5. （可选）直接压缩和沙盒代理的 shell 命令：
skarn run --net deny -- cargo test
```
下游服务器可以是本地的（`transport = "stdio"`）或远程的
（`transport = "http"`，带有可选的 bearer auth）— 参见
[`skarn.example.toml`](skarn.example.toml)。
## 您获得的内容
### 1. 代码模式 — 给代理一个 API，而不是模式转储
与其注入每个工具的模式，网关暴露三个元工具。模型调用 `search()` 来查找工具，然后编写一个短脚本并将其交给 `execute()`：
```ts
// 模型编写的内容；斯卡恩在密封、操作系统沙盒隔离中运行它。
const issues = await skarn.server("github").search_issues({ q: "is:open label:bug" });
const stale = issues.filter(i => daysSince(i.updated_at) > 90); // 筛选在这里进行
await skarn.server("slack").post_message({ channel: "#triage", text: summarize(stale) });
return { staleCount: stale.length }; // 只有这个返回给模型
```
1,000 行的中间结果永远不会触及上下文窗口。
| 场景 | 经典 MCP（输入令牌） | 斯卡恩代码模式 | 减少 |
|---|---:|---:|---:|
| 16 个服务器 / 508 个工具，多步骤任务 | ~150,000 | ~2,000 | **~99%** |
| 单个 3 工具工作流 | ~20,700 | ~1,100 | **~95%** |
*（数据来自已发布的代码模式文献 — 参见 [docs/adr/0001](docs/adr/0001-quickjs-over-deno-core.md)。您的里程碑可能会因目录大小而有所不同。）*
### 2. 原始 shell 输出的令牌压缩
```bash
skarn run --stats -- cargo test
```
| 命令 | 原始令牌 | 压缩 | 减少 |
|---|---:|---:|---:|
| `cargo test` | ~25,000 | ~2,500 | **~90%** |
| `npm install` | ~16,000 | ~3,200 | **~80%** |
| `git diff` | ~10,000 | ~2,500 | **~75%** |
| `ls` / `tree` | ~2,000 | ~400 | **~80%** |
错误、警告和失败 *始终* 被保留 — 即使从截断的中间恢复。
### 3. 操作系统原生沙盒 — 无需 Docker
`skarn run -- <cmd>` 将命令限制在您的项目目录内，并拒绝网络出口，由内核强制执行：
| 平台 | 机制 | 冷启动 |
|---|---|---|
| macOS | Seatbelt (`sandbox_init`) | < 5 ms |
| Linux | Landlock LSM + seccomp-bpf | < 5 ms |
| Windows | AppContainer + Job Object | < 10 ms |
与 Docker 的 200 ms+ 冷启动、根守护进程和每个座位许可相比。
代码模式 `execute` 获得相同的保护：在 macOS 和 Linux 上，网关在专用 **工作进程中运行每个脚本，该进程自我沙盒化** （拒绝网络，无工作区写入），然后再处理模型生成的代码，因此隔离逃逸仍会降级为内核限制的进程。在 `skarn.toml` 中使用 `isolation` 配置（`auto` / `worker` / `in_process`）。
## 它如何适应您的代理
- **Claude Code / Codex CLI** — 运行 `skarn hook` 以获取一个 PreToolUse 钩子，该钩子通过 `skarn run` （沙盒 + 压缩，无需提示更改）路由 shell 命令。参见 [docs/integrations/claude-code.md](docs/integrations/claude-code.md)。
- **Cursor / Windsurf** — 在 IDE 配置中将 Skarn 设置为 MCP 服务器，以获取代码模式 + 聚合。参见 [docs/integrations/cursor-windsurf.md](docs/integrations/cursor-windsurf.md)。
## 架构
一个 Cargo 工作区，包含严格分离、独立可用的 crate：
| Crate | 责任 |
|---|---|
| [`skarn-sandbox`](crates/skarn-sandbox) | 操作系统原生沙盒抽象（Seatbelt / Landlock+seccomp / AppContainer） |
| [`skarn-compress`](crates/skarn-compress) | YAML 驱动的 shell 输出令牌压缩 |
| [`skarn-codemode`](crates/skarn-codemode) | 密封 QuickJS 隔离 + `oxc` TS-strip & AST 验证 + 工具桥 |
| [`skarn-gateway`](crates/skarn-gateway) | MCP 服务器/客户端聚合在官方 `rmcp` SDK 上 |
| [`skarn`](crates/skarn) | 将所有功能结合在一起的 `skarn` CLI |
参见 [架构决策记录](docs/adr/) 以获取工程原理。
## 安全
Skarn 按设计运行不受信任的、模型生成的代码。阅读 [SECURITY.md](SECURITY.md) 以获取威胁模型、防御内容和漏洞报告方式。
## 从源代码构建
```bash
git clone https://github.com/Rani367/Skarn
cd skarnmcp
cargo build --release # 二进制文件位于 target/release/skarn
cargo test --workspace # macOS 沙盒在此处运行时验证
```
需要 Rust 1.95+。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。问题和 PR 欢迎。
## 许可证
根据 [MIT](LICENSE-MIT) 或 [Apache-2.0](LICENSE-APACHE) 许可证授权，任选其一。
