内容
<p align="center">
<img src="assets/distill-logo.png" alt="Distill" width="130" />
</p>
<h1 align="center">Distill</h1>
<p align="center">
<b>大幅减少LLM令牌使用量，最高可达98% — 在上下文窗口填满之前。</b>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/distill-mcp"><img alt="npm version" src="https://img.shields.io/npm/v/distill-mcp?color=cb3837&logo=npm"></a>
<a href="https://www.npmjs.com/package/distill-mcp"><img alt="npm downloads" src="https://img.shields.io/npm/dm/distill-mcp?color=cb3837"></a>
<a href="https://github.com/ArthurDEV44/distill/actions/workflows/build.yml"><img alt="CI" src="https://github.com/ArthurDEV44/distill/actions/workflows/build.yml/badge.svg"></a>
<a href="https://smithery.ai/server/@ArthurDEV44/distill-mcp"><img alt="Smithery" src="https://smithery.ai/badge/@ArthurDEV44/distill-mcp"></a>
<a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
<img alt="Node.js" src="https://img.shields.io/node/v/distill-mcp">
</p>
<p align="center">
<a href="#快速开始">快速开始</a> ·
<a href="#三大工具">三大工具</a> ·
<a href="#适用场景">适用场景</a> ·
<a href="https://distill-mcp.com">文档</a> ·
<a href="https://github.com/ArthurDEV44/distill/discussions">讨论</a>
</p>
**Distill** 是一个开源的 [MCP](https://modelcontextprotocol.io) 服务器，它在源头上压缩上下文。构建输出、日志、差异和整个文件读取都被提炼成真正有用的令牌 — 因此您的代理可以读取更多内容、花费更少，并在一个会话中保持敏锐。三款始终加载的工具，从第一回合开始就存在，取代了数十个独立的调用。与 Claude Code、Cursor 和 Windsurf 兼容。
```ts
// 在 Distill 之前 — 7 次工具调用，约 2,500 个令牌开销：
// 读取 ×3 → Grep → 读取 → 读取 → 压缩
// 使用 Distill — 1 次调用，约 500 个令牌：
code_execute(`
const files = ["server.ts", "registry.ts", "executor.ts"];
return ctx.compress.auto(
files.map(f => ctx.code.skeleton(ctx.files.read(f), "typescript")).join("\n")
);
`)
// ▲ 约 80% 的开销减少，相同的答案
```
## 为什么选择 Distill？
Claude Code 已经在上下文进入窗口后压缩上下文（autocompact）。Distill 在此之前进行压缩 — 在源头捕获大输出，因此昂贵的令牌根本不会进入上下文。
| 问题 | Distill 工具 | 方法 | 节省 |
|---------|-------------|-----|---------|
| 大型构建输出、日志、差异 | `auto_optimize` | 自动检测类型，应用最佳压缩器 | 40–95% |
| 读取整个文件以获取一个函数 | `smart_file_read` | 7 种语言的 AST 提取 | 50–90% |
| 链接 5–10 次工具调用 | `code_execute` | 沙箱中的 TypeScript SDK — 一次调用 | **最高可达 98%** |
## 适用场景
Distill 不会取代您的工具 — 它位于其输出和上下文窗口之间，过滤掉噪音。
| 方法 | 您得到的结果 | Distill 适用场景 |
|---|---|---|
| 原始工具调用（`Read` / `Grep` / `Bash`） | 完整的保真度，完整的令牌成本 | 在上下文进入之前压缩输出 |
| Claude Code 自动压缩 | 在窗口填满后重新获得空间 | Distill 在之前工作 — 这些令牌从未进入 |
| 手动上下文修剪 | 繁琐且容易出错 | 内容感知压缩器自动完成 |
| 一堆单一用途的 MCP 工具 | 广泛的表面，约 500 个令牌开销 * 每个 | 3 个始终加载的工具，约 2,000 个令牌合计 |
## 快速开始
```bash
# 直接使用 npx 运行
npx distill-mcp
# 或全局安装
npm install -g distill-mcp
# 自动配置您的 IDE（Claude Code、Cursor、Windsurf）
distill-mcp setup
```
### 添加到 Claude Code
```bash
claude mcp add distill -- npx distill-mcp
```
所有 3 个工具都立即可用 — 无需发现步骤，无需加载模式。
## 三大工具
### `auto_optimize` — 压缩任何内容
自动检测内容类型并应用最佳压缩策略。
| 策略 | 内容类型 | 典型节省 |
|----------|-------------|-----------------|
| `build` | 编译器错误（tsc、rustc、webpack） | 95% |
| `logs` | 服务器 / 测试 / 构建日志 | 80–90% |
| `errors` | 重复错误行 | 70–90% |
| `diff` | Git 差异 | 60–80% |
| `stacktrace` | 堆栈跟踪 | 50–80% |
| `code` / `semantic` | 源代码（TF-IDF） | 40–60% |
| `config` | JSON / YAML 配置 | 30–60% |
| `auto` | 自动检测最佳策略 | 变化 |
```
auto_optimize content="<大型构建输出>" strategy="auto"
```
### `smart_file_read` — AST 驱动的代码读取
精确读取代码 — 提取您需要的确切内容。
**5 种模式：**
- `skeleton` — 仅限函数 / 类签名（深度 1–3）
- `extract` — 按名称提取特定函数、类或接口
- `search` — 查找匹配查询的元素
- `full` — 完整的文件结构概述
- `auto` — 从参数中检测模式
**7 种语言：** TypeScript、JavaScript、Python、Go、Rust、PHP、Swift
```
smart_file_read filePath="src/server.ts" mode="skeleton"
smart_file_read filePath="src/server.ts" mode="extract" target={"type":"function","name":"createServer"}
smart_file_read filePath="src/server.ts" mode="search" query="register"
```
### `code_execute` — 沙箱中的 TypeScript SDK
编写 TypeScript 而不是链接工具调用。通过 `ctx.*` SDK 访问文件、git、搜索和压缩。
```
code_execute code="return ctx.compress.auto(ctx.files.read('build.log'))"
```
**批量多个操作：**
```typescript
// 读取 3 个文件，提取关键签名，压缩结果 — 1 次工具调用而不是 7 次
const files = ["src/server.ts", "src/registry.ts", "src/executor.ts"];
const skeletons = files.map(f => ctx.code.skeleton(ctx.files.read(f), "typescript"));
return ctx.compress.auto(skeletons.join("\n---\n"));
```
**SDK API：**
```typescript
// 文件操作
ctx.files.read(path) // 读取文件内容
ctx.files.glob(pattern) // 按模式查找文件
ctx.files.exists(path) // 检查文件是否存在
// 代码分析
ctx.code.parse(content, lang) // 解析为结构
ctx.code.extract(content, lang, {type, name}) // 提取元素
ctx.code.skeleton(content, lang) // 仅限签名
// 压缩
ctx.compress.auto(content, hint?) // 自动检测和压缩
ctx.compress.logs(logs) // 日志总结
ctx.compress.diff(diff) // 差异压缩
ctx.compress.semantic(content, ratio?) // TF-IDF 压缩
// Git
ctx.git.diff(ref?) // 获取差异
ctx.git.log(limit?) // 提交历史
ctx.git.blame(file, line?) // 责备信息
ctx.git.status() // 工作树状态
ctx.git.branch() // 当前分支信息
// 搜索
ctx.search.grep(pattern, glob?) // 搜索文件内容
ctx.search.symbols(query, glob?) // 查找代码符号
ctx.search.files(pattern) // 按模式查找文件
ctx.search.references(symbol, glob?) // 查找符号引用
// 分析
ctx.analyze.dependencies(file) // 文件依赖
ctx.analyze.callGraph(fn, file, depth?) // 调用图
ctx.analyze.exports(file) // 导出的符号
ctx.analyze.structure(dir, depth?) // 目录结构
// 管道
ctx.pipeline(steps) // 运行步骤数组
ctx.pipeline.codebaseOverview(dir?) // 快速概览
ctx.pipeline.findUsages(symbol) // 查找所有用法
ctx.pipeline.analyzeDeps(file) // 依赖分析
// 实用工具
ctx.utils.countTokens(text) // 计算令牌
ctx.utils.detectType(content) // 检测内容类型
ctx.utils.detectLanguage(path) // 从路径检测语言
```
## 令牌开销
Distill 的 3 个工具为每个 API 调用添加了最小的开销：
| | 工具模式 | 描述 |
|--|-------------|-------------|
| **Distill** | 约 2,000 个令牌 | 3 个始终加载的工具 |
| **等效** | 约 10,000+ 个令牌 | 20+ 个独立工具执行相同的操作 |
所有 3 个工具都使用 `_meta['anthropic/alwaysLoad']` — 从第 1 回合开始存在，零发现摩擦。
## CLI 命令
```bash
distill-mcp setup # 自动配置检测到的 IDE
distill-mcp setup --claude # 仅配置 Claude Code
distill-mcp setup --cursor # 仅配置 Cursor
distill-mcp doctor # 验证安装
distill-mcp serve # 启动 MCP 服务器
distill-mcp analyze # 分析代码库令牌使用情况
distill-mcp --help # 显示帮助
```
## IDE 配置
### Claude Code
运行 `distill-mcp setup` 后，您的配置将包括：
```json
{
"mcpServers": {
"distill": {
"command": "npx",
"args": ["distill-mcp", "serve"]
}
}
}
```
### Cursor / Windsurf
配置将自动添加到相应的设置文件中。
## 安全
`code_execute` 在具有 7 个安全层的沙箱环境中运行：
- **静态分析** 阻止 `eval`、`require`、`import()`、`process`、`Reflect`、`Proxy`
- **QuickJS WASM 隔离** — 无 `fetch`、`fs`、`主机访问`
- **文件访问** 限制在工作目录内（解析符号链接）
- **敏感文件** 阻止（`.env`、`凭证`、`密钥`）
- **Git 命令** 允许列出（无 `push`、`fetch`、`clone`）
- **内存限制** 128 MB · **超时** 30 秒 · **输出上限** 4,000 个令牌（自动压缩）
发现漏洞？请参阅 [SECURITY.md](.github/SECURITY.md) — 请不要公开提出问题。
## 开发
```bash
bun install # 安装依赖
bun run build # 构建所有软件包
bun run test # 运行测试
bun run dev # 启动开发模式（监视）
bun run check-types # TypeScript 类型检查
bun run lint # ESLint
```
使用 Bun 工作区 + Turborepo 构建。发布的软件包位于 `packages/mcp-server/`。
## 社区
- **[GitHub 讨论](https://github.com/ArthurDEV44/distill/discussions)** — 问题、想法、反馈
- **[问题](https://github.com/ArthurDEV44/distill/issues)** — 错误报告
- **[文档](https://distill-mcp.com)** — 完整文档站点
## 贡献
欢迎贡献 — 请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。
**优先级领域：**
- `smart_file_read` 的新语言解析器（Java、C#、Kotlin）
- `code_execute` 的 SDK 扩展
- 文档
如果 Distill 为您节省了令牌，⭐️ 帮助其他人找到它。
## 许可证
[MIT](LICENSE) © Arthur Jean
---
<p align="center">
<a href="https://www.npmjs.com/package/distill-mcp">npm</a> ·
<a href="https://github.com/ArthurDEV44/distill">GitHub</a> ·
<a href="https://distill-mcp.com">文档</a> ·
<a href="https://github.com/ArthurDEV44/distill/discussions">讨论</a>
</p>
