内容
# Slnmap
*Slnmap（sln-map）— 您的.sln的语义地图，供AI编码代理使用。*
**在 [MIT 许可证](LICENSE) 下开源。**
[](https://github.com/EMahmoudNabil/slnmap/actions/workflows/ci.yml)
[](https://www.nuget.org/packages/Slnmap)
[](LICENSE)
**您的AI代理无法重构它看不到的.NET代码。** 请代理 *"如果我更改此接口会发生什么？"*，它会根据其上下文中的文件进行猜测 — 缺少其他项目和文件中从未打开的调用者。Slnmap为代理提供精确、编译器准确的整个解决方案地图，因此它能正确回答：每个调用者，每个实现，跨越每个项目。更少的破坏性更改，没有虚构的依赖关系。它在本地运行，并通过 [MCP](https://modelcontextprotocol.io) 将地图提供给您的代理或编辑器。
## 快速入门（3 步）
**1. 安装** 全局工具（需要 [.NET SDK](https://dotnet.microsoft.com/download) 9.0+）：
```console
dotnet tool install --global Slnmap
```
**2. 分析** 您的解决方案（或单个 `.csproj`）— 这会在当前文件夹中生成 `slnmap.db`：
```console
slnmap analyze path/to/YourSolution.sln
```
**3. 连接** 您的MCP客户端。对于Claude Code，请在项目的 `.mcp.json` 中添加以下内容。使用您刚刚生成的`slnmap.db`的**绝对**路径 — MCP客户端的工作目录通常不是您的项目文件夹，因此相对路径可能会无声地解析为错误（或不存在）的文件：
```json
{
"mcpServers": {
"slnmap": {
"command": "slnmap",
"args": ["serve", "--db", "C:/path/to/your/project/slnmap.db"]
}
}
}
```
在macOS/Linux上，请使用POSIX绝对路径，例如 `/home/you/project/slnmap.db`。
就这样。询问您的代理一个架构问题，它将调用Slnmap。（如果有问题，请先运行`slnmap doctor` — 请参阅[故障排除](#故障排除)。）
## 您可以用什么问
服务器暴露了五个只读工具。给予它们完全合格的名称；结果有上限，优先显示数量。（工具还附带一个注释：完全合格的名称并不揭示成员是否是显式接口实现。）
| 工具 | 示例问题 |
|---|---|
| `find_symbol` | "查找 `IBasketService` 接口。" |
| `get_dependencies` | "`CartController.Index` 依赖于什么？" |
| `impact_analysis` | "如果我更改 `IBasketService` 会发生什么？" |
| `get_architecture_overview` | "显示项目及其相互依赖关系。" |
| `find_usages` | "`BasketService.GetBasket` 在哪里使用？" |
对于接口（或接口成员），`impact_analysis` 遵循接口的调用者和具体实现/重写 — 因此答案包括跨项目、文件中 nobody 打开的代码，这些代码仅触及接口。
## 命令行界面
```console
slnmap analyze <solution> # 构建或更新代码图（增量重新运行）
slnmap serve # 通过stdio向MCP客户端提供图
slnmap status # 显示节点/边计数及上次分析时间
slnmap doctor # 检查环境是否可以运行Slnmap
```
`--db <path>` 选择数据库文件（默认为`slnmap.db`）。
## 从源代码构建
Slnmap是一个标准的.NET解决方案 — 克隆、构建并使用SDK测试：
```console
git clone https://github.com/EMahmoudNabil/slnmap.git
cd slnmap
dotnet build -c Release
dotnet test -c Release
```
在不安装全局工具的情况下运行CLI：
```console
dotnet run --project src/Slnmap.Cli -- analyze path/to/YourSolution.sln
```
## 兼容性
分析针对.NET 8和.NET 9的C#解决方案（早期目标未测试 — 欢迎反馈）；在Windows、macOS和Linux上运行；与任何MCP客户端配合使用（已与Claude Code测试）。
## 隐私
**100% 本地 — 现在您可以验证。** Slnmap在您的机器上运行，使用Roslyn读取您的源代码，并写入单个本地SQLite文件。MCP服务器仅读取该本地文件。没有遥测，没有网络调用，也没有云服务 — 分析完全离线。现在CLI和MCP服务器是开源的，因此该声明是可审计的：阅读代码或观察进程 — 没有任何内容离开您的机器。
## 性能
在 [`eShopOnWeb`](https://github.com/dotnet-architecture/eShopOnWeb) （10个项目，`net8.0`）上测量，.NET 9 SDK，在2核笔记本电脑上。每个计时是3次运行的中位数；完整的方法论，机器规格和固定的提交记录在 [BENCHMARKS.md](BENCHMARKS.md) 中。
| 指标 | 结果 |
|---|---|
| 图大小 | 1,107 个节点 / 2,168 个边 |
| 冷分析（10个项目） | ~25.6 秒（3次运行的中位数） |
| 重新分析一个文件更改后 | ~27.1 秒（3次运行的中位数 — 见注释） |
| `impact_analysis` 在 `IBasketService` 上（18个依赖） | ~270 毫秒（端到端MCP往返） |
**增量重新分析。** 重新分析仅重新遍历更改的文件及其依赖项，但每次运行仍支付整个工作区的完整加载费用 — 因为CLI是运行-退出，不会保持工作区热度。在实践中，这意味着重新分析目前**与冷运行速度相同，不是更快**。常驻 **`watch` 模式** 保持工作区热度（目标是亚秒级重新分析）是路线图上的首要事项。
## 故障排除
运行 **`slnmap doctor`** 首先 — 它检查实际阻止分析的三个问题，并为每个问题打印修复程序：
```console
$ slnmap doctor
[ok] .NET SDK: 1 SDK(s) installed; newest: 9.0.314 …
[ok] MSBuild workspace: Roslyn MSBuild workspace initialized …
[ok] Graph directory: Writable: /path/to/cwd
```
- **"没有安装.NET SDK" / MSBuild无法加载项目。** Slnmap通过 `MSBuildWorkspace` 进行分析，该工作区使用已安装的.NET SDK运行设计时构建。 从 <https://dotnet.microsoft.com/download> 安装SDK（不仅仅是运行时）。在 **Windows** 上，如果项目仍无法加载，请安装 **Visual Studio Build Tools** （或Visual Studio），以便MSBuild和目标包解析。
- **分析报告警告但完成。** 这是预期且安全的：无法加载的项目（例如缺少SDK或目标包）被报告为警告并跳过 — Slnmap索引所有加载的内容，而不是使整个运行失败（*部分加载*）。默认情况下，这些警告被压缩为单个 `Warnings: N (M unique)` 汇总行；运行 `slnmap analyze --verbose` 获取完整、分组的详细信息。
- **大型解决方案的第一次分析需要一段时间。** 冷分析编译每个项目一次。重新运行在图上速度更快，但仍重新加载工作区 — 请参见上面的性能说明。图形缓存在 `slnmap.db` 中，适用于后续运行。
- **`slnmap: command not found` 在安装后。** 确保.NET全局工具目录（`~/.dotnet/tools`）在您的 `PATH` 上，然后打开一个新终端。
## 它是如何工作的
Slnmap使用Roslyn编译器平台构建您解决方案的精确语义图 — 每个类型和成员，以及它们之间的关系（调用、实现、继承、引用）。该图存储在本地，并通过MCP提供给您的AI代理或编辑器。更新是增量的，崩溃安全的：中断的运行永远不会损坏现有的图。
## 许可证和支持
Slnmap在 [MIT 许可证](LICENSE) 下开源。
CLI和MCP服务器采用MIT许可证，并将保持该状态。未来的托管或团队导向功能可能是商业性的。
对于问题或报告问题，请打开 [GitHub问题](https://github.com/EMahmoudNabil/slnmap/issues) 或联系 **hello@slnmap.dev**。欢迎贡献 — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
