# Fuse
Fuse 是一个针对 AI 辅助开发的深度 .NET 原生上下文优化器。它收集源文件，为提高 token 效率对其进行缩减，并输出单个结构化的内容，让 agent 可以在一次调用中获取，而无需逐个阅读成千上万个文件。
与通用的仓库打包工具（Repomix、Code2Prompt、Gitingest）不同，Fuse 理解 C# 结构：依赖图、骨架提取、BM25 查询范围界定、git 变更检测以及约定模式。可选的 Roslyn 精度层级和混合检索重排序器进一步提高了准确性，此外，目录概览、`fuse_ask` 自动范围界定工具以及会话差异输出减少了 agent 所需的往返次数。它以 .NET 全局工具 (`fuse`) 和包含八个工具的 MCP 服务器形式发布，支持 Cursor、Claude Code 和 GitHub Copilot。
由 [Litenova Solutions](https://github.com/Litenova-Solutions) 维护。
## 为什么选择 Fuse
基于固定的四个真实 .NET 库（MediatR、FluentValidation、AutoMapper、Newtonsoft.Json）语料库进行测量，使用 `o200k_base` 分词器进行统计。即使绝对 token 计数不同，缩减比例在不同模型间也是通用的。每个数据都可以使用一条命令重现，并在[基准测试页面](docs/project/benchmarks.md)上完整报告，包括 Fuse 打平或落后于对比项的情况。
- **在不丢失 API 的前提下削减 token。** 默认缩减会移除 7% 到 10% 的 token，`--all` 会移除 21% 到 40% 的 token，同时保留 99% 到 100% 的公共类型和方法。`--skeleton` 可移除 66% 到 93% 的 token 以生成架构图。
- **比通用打包工具更小。** 在这些代码库中，Repomix 的输出比原始拼接大 1.3% 到 3.9%；而 Fuse 在每种模式下都比原始拼接更小。
- **找出变更涉及的文件。** 在 24 个真实的已合并 pull request 中，变更范围界定以 61% 的精度召回了 88% 的文件，并且所有三种范围界定模式都优于 agent 风格的 grep 基准。
- **在复杂代码上生成可靠的骨架。** 可选的 Roslyn 层级在所有四个库中保留了 100% 的方法签名，包括 Newtonsoft.Json，而基于正则表达式的骨架仅保留了 4%。
- **低成本的重复调用。** 磁盘上的分析索引将整个会话期间的热调用实际耗时大致减少了一半，因此多调用任务只需支付一次分析成本。
- **原生 AOT，默认路径上无运行时反射。** 快速路径作为预先编译的二进制文件发布；Roslyn 和向量重排序器是与其隔离的可选层级。
使用 `pwsh -File tests/benchmarks/harness/run-all.ps1` 重现每个数字。
## 安装
**前提条件：** [.NET SDK 10.0](https://dotnet.microsoft.com/download) 或更高版本。
### 从 NuGet 安装
```
dotnet tool install -g Fuse
```
通过 .NET 10 SDK 无需全局安装即可运行：
```
dnx Fuse -- serve
```
### 从源码构建 (Windows)
```
install.bat
```
### 从源码构建 (任何操作系统)
```
dotnet pack src/Host/Fuse.Cli/Fuse.Cli.csproj -c Release
dotnet tool install -g Fuse --add-source src/Host/Fuse.Cli/nupkg
```
验证：
```
fuse --help
```
## CLI 快速入门
使用 DotNet 模板融合一个 .NET 项目：
```
fuse dotnet --directory ./src
```
最大程度的 C# token 缩减：
```
fuse dotnet --directory ./src --all
```
架构概览（仅签名）：
```
fuse dotnet --directory ./src --all --skeleton
```
获取文件前的低成本概览（目录树、符号大纲、每个文件的 token 成本）：
```
fuse dotnet --directory ./src --toc
```
使用可选的 Roslyn 精度层级获取准确的骨架和依赖边：
```
fuse dotnet --directory ./src --skeleton --semantic
```
PR 范围融合，包含差异块和每个更改文件的调用者：
```
fuse dotnet --directory ./src --changed-since main --review
```
查询范围融合：
```
fuse dotnet --directory ./src --query "payment gateway" --query-top 10
```
初始化项目配置文件：
```
fuse init
```
输出默认为 `Documents/Fuse`。使用 `--output` 和 `--name` 控制目标位置。
## 命令
| 命令 | 用途 |
|---------|---------|
| `fuse` | 通用融合。除非设置 `--only-extensions`，否则包含所有扩展名。 |
| `fuse dotnet` | .NET 项目：C# 缩减、结构图、依赖感知范围界定。 |
| `fuse wiki` | Azure DevOps wikis：仅 Markdown。 |
| `fuse init` | 在当前目录创建 `fuse.json`。 |
| `fuse serve` | 在 stdio 上启动 MCP 服务器。 |
完整的选项列表：[命令](docs/reference/commands.md) 和 [选项](docs/reference/options.md)。
## 推荐的 Agent 工作流
对于大型 .NET 代码库，请按以下顺序使用 MCP 工具：
1. **概览** 使用 `fuse_toc`（目录树、符号大纲、每个文件的 token 成本）或使用 `fuse_skeleton` 生成低 token 架构图。
2. **深入** 使用 `fuse_focus`（类型/文件种子）或 `fuse_search`（自然语言查询，使用 `rerank` 进行混合检索）。
3. **PR 审查** 使用 `fuse_changes`（git 差异范围界定，`review=true` 包含差异块和直接调用者）。
4. **完全控制** 当您需要组合所有选项时，使用 `fuse_dotnet`。
或者跳过编排：使用任务和 token 预算调用 `fuse_ask`，Fuse 会自动选择策略并将上下文打包至预算范围内。在一个任务中的多次调用之间，传递一个 `session` ID，这样已经返回的文件就不会被再次发送。
有关 token 预算和组合规则，请参见 [Agent 工作流](docs/agent-integration/workflows.md)。
## MCP 设置
运行 `fuse serve` 并从您的 AI 客户端连接。
### Claude Code
添加到项目根目录的 `.mcp.json` 中：
```
{
"mcpServers": {
"fuse": {
"type": "stdio",
"command": "fuse",
"args": ["serve"]
}
}
}
```
或者：`claude mcp add fuse --scope project -- fuse serve`
### Cursor
添加到 `.cursor/mcp.json`：
```
{
"mcpServers": {
"fuse": {
"command": "fuse",
"args": ["serve"]
}
}
}
```
### GitHub Copilot (VS Code)
添加到 `.vscode/mcp.json`：
```
{
"servers": {
"fuse": {
"type": "stdio",
"command": "fuse",
"args": ["serve"]
}
}
}
```
工具目录和参数：[工具参考](docs/agent-integration/tools.md) 和 [资源参考](docs/agent-integration/resources.md)。客户端设置详情：[MCP 概览与设置](docs/agent-integration/overview.md)。MCP Registry 清单：[docs/mcp-registry/server.json](docs/mcp-registry/server.json)。
## Fuse 的功能
融合是一个四阶段的 pipeline：
1. **收集** - 扫描源目录，应用过滤器（扩展名、`.gitignore`、二进制检测、测试项目、glob 匹配）。
2. **过滤** - 可选的范围界定：焦点、git 变更或带依赖扩展的 BM25 查询。
3. **缩减** - 规范化空白字符，运行语言和格式 reducer，应用骨架/标记/脱敏。
4. **输出** - 编写融合后的输出，包含 token 计数、清单 header、可选的拆分以及基于大小的排序。
架构详情：[架构](docs/architecture/pipeline.md)。功能参考：[指南](docs/guides/index.md) 和 [参考](docs/reference/index.md)。
## 输出格式
每个文件都被包裹在一个带有路径标签的块中（默认为 XML）：
```
public class OrderService { }
```
还支持：`--format markdown` 和 `--format json`。默认情况下会预置一个清单 header（文件树和 token 成本）；使用 `--no-manifest` 可禁用此功能。
磁盘输出文件名包含 token 估算值，例如 `MyProject_2026-06-19_0130_22k.txt`。
## 仓库结构
```
src/
Core/ Pipeline libraries
Fuse.Collection/ File discovery, filters, templates
Fuse.Reduction/ Content pipeline, caching, redaction
Fuse.Emission/ Output writers, token budget, manifest
Fuse.Fusion/ Orchestration, scoping, analysis, enrichment, DI
Host/
Fuse.Cli/ CLI and MCP server
Plugins/ Extension-keyed capability providers
Fuse.Plugins.Abstractions/ Capability interfaces (shared contract)
Fuse.Plugins.Languages.CSharp/ C# language plugin (regex, AOT-clean default)
Fuse.Plugins.Languages.CSharp.Roslyn/ Opt-in Roslyn precision tier (excluded from the AOT build)
Fuse.Plugins.Formats.Web/ Format reducers (HTML, JSON, YAML, SQL, TS/JS, etc.)
tests/ Unit and integration tests
docs/ Full documentation
```
## 开发
```
dotnet build Fuse.slnx --configuration Release
dotnet test Fuse.slnx --configuration Release --no-build
dotnet format Fuse.slnx --verify-no-changes
```
贡献工作流：[贡献](docs/project/contributing.md)。Agent 说明：[AGENTS.md](AGENTS.md)。
## 文档
| 章节 | 内容 |
|---------|----------|
| [文档主页](docs/index.md) | 完整文档导航图 |
| [快速入门](docs/getting-started/introduction.md) | 安装、首次运行、核心概念 |
| [指南](docs/guides/index.md) | 缩减、范围界定、格式、配置 |
| [Agent 集成](docs/agent-integration/overview.md) | MCP 服务器、工具、资源、工作流 |
| [参考](docs/reference/index.md) | 命令、选项、模板、reducer、输出 |
| [架构](docs/architecture/pipeline.md) | Pipeline、能力模型、内部机制 |
| [扩展 Fuse](docs/extending/language-plugin.md) | 语言插件、模板、reducer |
| [项目](docs/project/performance.md) | 性能、路线图、贡献 |
| [基准测试](docs/project/benchmarks.md) | 可重现的 token 缩减、保真度以及与原始文件和 Repomix 对比的召回率 |
| [更新日志](CHANGELOG.md) | 版本历史和迁移说明 |
## 许可证
MIT。版权所有 (c) 2026 Litenova Solutions。请参见 [LICENSE](LICENSE)。