)
如果你維護(hù)過(guò)大型 .NET 解決方案一定遇到過(guò)這樣的場(chǎng)景項(xiàng)目里有幾十個(gè) csproj類與類之間的依賴關(guān)系盤(pán)根錯(cuò)節(jié)方法調(diào)用鏈跨越了三四個(gè)程序集。本地調(diào)試還能靠 IDE 的“轉(zhuǎn)到定義”一點(diǎn)點(diǎn)摸但當(dāng)你試圖讓 AI 編程助手幫你改代碼、做重構(gòu)、解釋業(yè)務(wù)邏輯時(shí)它卻常常答非所問(wèn)——因?yàn)?AI 看到的只是你貼給它的那幾個(gè)文件它看不到整個(gè)解決方案的依賴關(guān)系和調(diào)用上下文。這個(gè)問(wèn)題的本質(zhì)是傳統(tǒng) AI 編程工具缺少對(duì)代碼庫(kù)全局結(jié)構(gòu)的感知能力。最近在 Hacker News 看到的一個(gè)項(xiàng)目很有意思Slnmap一個(gè)基于 Roslyn 的 code graph MCP server專門(mén)為 .NET 代碼庫(kù)服務(wù)。它把 Roslyn 的語(yǔ)法樹(shù)和符號(hào)分析能力與 MCPModel Context Protocol結(jié)合起來(lái)讓 AI 編程助手可以按需查詢代碼庫(kù)的依賴圖、調(diào)用關(guān)系、類型結(jié)構(gòu)等語(yǔ)義信息。這篇文章會(huì)從實(shí)際工程角度拆解 Slnmap它解決的是什么問(wèn)題、核心原理是什么、怎么配置和啟動(dòng)、如何在 Cursor / Claude Desktop / 自研 Agent 中接入它以及真實(shí)項(xiàng)目中的坑和最佳實(shí)踐。1. 這篇文章真正要解決的問(wèn)題先說(shuō)一個(gè)經(jīng)常被忽略的事實(shí)給 AI 編程助手“喂文件”和讓它“理解代碼庫(kù)”是兩回事。如果你用過(guò) Copilot Chat、Cursor 或 Claude Code 處理大型解決方案大概率遇到過(guò)以下幾種情況上下文窗口不夠用。一個(gè)大型 .NET 解決方案可能有幾百個(gè)源文件全部塞進(jìn)上下文既不可能也沒(méi)必要但 AI 需要的那幾個(gè)關(guān)鍵文件恰恰不在上下文里。缺少依賴關(guān)系信息。AI 看到一個(gè)OrderService類但它不知道OrderService依賴了哪些倉(cāng)儲(chǔ)接口、被哪個(gè)控制器調(diào)用、實(shí)現(xiàn)了哪個(gè)抽象基類。這些信息不直接寫(xiě)在當(dāng)前文件里卻決定了重構(gòu)時(shí)會(huì)不會(huì)破壞其他模塊。符號(hào)解析不準(zhǔn)確。同名類、Partial 類、通過(guò)依賴注入注冊(cè)的接口實(shí)現(xiàn)只看源碼文本很難判斷運(yùn)行時(shí)真正用的是哪個(gè)實(shí)現(xiàn)。人工挑選上下文太累。讓開(kāi)發(fā)者手動(dòng)把相關(guān)文件拖進(jìn)對(duì)話在大型代碼庫(kù)里篩選成本極高。Slnmap 的思路是把代碼庫(kù)的圖譜信息通過(guò) MCP 協(xié)議暴露給 AI 助手讓 AI 按需查詢而不是靠猜。Roslyn 在這里起到的作用是“語(yǔ)義分析引擎”。它不是簡(jiǎn)單讀取文本而是能夠解析出完整的符號(hào)信息類型在哪里定義、方法被誰(shuí)調(diào)用、項(xiàng)目之間誰(shuí)引用誰(shuí)。Slnmap 把 Roslyn 分析出的這些信息構(gòu)造成一張 code graph再通過(guò) MCP server 提供給 AI 客戶端查詢。換句話說(shuō)Slnmap 讓 AI 從“讀文件”升級(jí)為“讀代碼庫(kù)”。這是本篇要講的核心判斷。2. 三個(gè)繞不開(kāi)的概念Roslyn、代碼圖與 MCP在動(dòng)手操作之前需要先弄清楚三個(gè)基礎(chǔ)概念。如果這三個(gè)概念沒(méi)有對(duì)齊后面配置和調(diào)試的時(shí)候會(huì)很難受。2.1 Roslyn不只是編譯器Roslyn 是微軟開(kāi)源的 C# 和 Visual Basic 編譯器平臺(tái)但它和傳統(tǒng)編譯器最大的區(qū)別是Roslyn 把自己做成了一組 API。傳統(tǒng)編譯器是“源碼進(jìn)、程序集出”的黑盒你很難在編譯過(guò)程中拿到中間信息。Roslyn 則把編譯過(guò)程拆成多個(gè)可訪問(wèn)的階段Syntax Tree語(yǔ)法樹(shù)代碼的語(yǔ)法結(jié)構(gòu)比如類聲明、方法聲明、語(yǔ)句塊。Symbol符號(hào)語(yǔ)法樹(shù)背后的語(yǔ)義信息比如OrderService這個(gè)類名對(duì)應(yīng)哪個(gè)類型、GetOrderById這個(gè)方法的完整簽名是什么。Semantic Model語(yǔ)義模型把語(yǔ)法樹(shù)和符號(hào)關(guān)聯(lián)起來(lái)告訴你某個(gè)標(biāo)識(shí)符在特定上下文里到底引用了哪個(gè)類型或方法。Slnmap 用 Roslyn 不是為了編譯出 DLL而是利用 Roslyn 的語(yǔ)義分析能力構(gòu)建一個(gè)可供查詢的代碼關(guān)系網(wǎng)絡(luò)。2.2 代碼圖Code Graph把代碼變成關(guān)系數(shù)據(jù)“代碼圖”可以理解為代碼庫(kù)的“關(guān)系型抽象”。它關(guān)注的是實(shí)體之間的關(guān)系而不是具體代碼內(nèi)容。在 .NET 代碼庫(kù)中常見(jiàn)的圖關(guān)系包括項(xiàng)目之間的 ProjectReference。類型之間的繼承關(guān)系和接口實(shí)現(xiàn)。方法之間的調(diào)用關(guān)系Caller / Callee。類型之間的屬性引用、方法參數(shù)引用、字段類型引用。舉個(gè)例子CustomerController依賴ICustomerServiceCustomerService實(shí)現(xiàn)了ICustomerService并依賴ICustomerRepositorySqlCustomerRepository實(shí)現(xiàn)了ICustomerRepository。這段依賴鏈如果靠人肉梳理需要打開(kāi)三四個(gè)文件來(lái)回跳。而代碼圖可以把這些關(guān)系直接輸出為結(jié)構(gòu)化數(shù)據(jù){ type: CustomerController, dependsOn: [ICustomerService], implementedBy: [], references: [CustomerService, CustomerRepository] }2.3 MCPAI 世界的“USB-C 接口”MCPModel Context Protocol是 Anthropic 提出的開(kāi)放協(xié)議目的是統(tǒng)一 AI 應(yīng)用與外部數(shù)據(jù)、工具之間的連接方式?？梢园阉斫獬?AI 領(lǐng)域的 USB-C 標(biāo)準(zhǔn)不同的工具通過(guò)統(tǒng)一協(xié)議接入不同的 AI 客戶端不需要為每一個(gè) AI 產(chǎn)品單獨(dú)定制集成。MCP 協(xié)議中有幾個(gè)核心角色MCP Server提供服務(wù)的一方把某個(gè)能力封裝成協(xié)議接口。Slnmap 就是一個(gè) MCP Server。MCP Client消費(fèi)服務(wù)的一方比如 Claude Desktop、Cursor或者你自己寫(xiě)的 Agent。ToolServer 暴露給 Client 調(diào)用的具體能力比如“查詢類型依賴”“查找方法調(diào)用鏈”。Slnmap 屬于 MCP Server它把 Roslyn 分析結(jié)果包裝成若干 ToolAI 客戶端通過(guò)標(biāo)準(zhǔn)協(xié)議調(diào)用這些 Tool就能拿到結(jié)構(gòu)化的代碼圖譜信息。2.4 三者的關(guān)系用一句話概括Roslyn 負(fù)責(zé)分析代碼圖負(fù)責(zé)存儲(chǔ)MCP 負(fù)責(zé)傳輸。Slnmap 啟動(dòng)時(shí)先用 Roslyn 加載目標(biāo)解決方案或項(xiàng)目分析出符號(hào)和關(guān)系構(gòu)建代碼圖然后啟動(dòng)一個(gè) MCP ServerAI 編程助手通過(guò) MCP 協(xié)議向 Server 發(fā)起查詢請(qǐng)求Server 返回圖譜數(shù)據(jù)。整個(gè)過(guò)程不需要把整個(gè)代碼庫(kù)塞進(jìn)上下文。3. Slnmap 工作原理與架構(gòu)拆解從架構(gòu)上看Slnmap 可以分為三個(gè)層次分析層、圖構(gòu)建層、服務(wù)層。3.1 分析層Roslyn 項(xiàng)目加載與符號(hào)解析Slnmap 首先需要定位目標(biāo)代碼庫(kù)這一步通常通過(guò)傳入.sln或.csproj文件路徑來(lái)完成。Roslyn 提供了MSBuildWorkspace類可以從解決方案文件加載項(xiàng)目并獲取每個(gè)項(xiàng)目的Compilation對(duì)象。Compilation是所有語(yǔ)義分析的入口// 示意代碼使用 MSBuildWorkspace 加載解決方案 using Microsoft.CodeAnalysis; using Microsoft.CodeAnalysis.MSBuild; var workspace MSBuildWorkspace.Create(); var solution await workspace.OpenSolutionAsync(path/to/YourSolution.sln); foreach (var project in solution.Projects) { var compilation await project.GetCompilationAsync(); // 拿到 compilation 后可以遍歷語(yǔ)法樹(shù)、獲取符號(hào)、分析依賴 }這里的關(guān)鍵點(diǎn)是Slnmap 分析的是Roslyn 的語(yǔ)義模型Semantic Model而不是簡(jiǎn)單的文本匹配。這意味著它能準(zhǔn)確區(qū)分兩個(gè)同名但來(lái)自不同命名空間的類型。通過(guò)別名引用的類型。泛型實(shí)例化后的實(shí)際類型參數(shù)。擴(kuò)展方法實(shí)際調(diào)用的靜態(tài)類。這些信息僅靠 GPT 的文本理解是拿不到的而 Roslyn 可以精確給出。3.2 圖構(gòu)建層提取并存儲(chǔ)關(guān)系拿到Compilation之后Slnmap 會(huì)遍歷所有語(yǔ)法樹(shù)提取兩類信息類型級(jí)信息類型名稱、命名空間、文件路徑。基類、實(shí)現(xiàn)的接口。類型中聲明的成員屬性、方法、字段。每個(gè)成員的類型引用。依賴級(jí)信息類 A 是否在方法體內(nèi)調(diào)用了類 B 的方法。類 A 是否在屬性類型中引用了類 B。項(xiàng)目 X 是否引用了項(xiàng)目 Y。方法 M 被哪些方法調(diào)用。這些關(guān)系會(huì)組織成一個(gè)圖數(shù)據(jù)結(jié)構(gòu)。在實(shí)際存儲(chǔ)上可以選擇內(nèi)存數(shù)據(jù)結(jié)構(gòu)適合單次會(huì)話分析也可以序列化成 JSON、圖數(shù)據(jù)庫(kù)或內(nèi)存數(shù)據(jù)庫(kù)以便反復(fù)查詢。3.3 服務(wù)層MCP 工具暴露Slnmap 啟動(dòng) MCP Server 后會(huì)暴露一組查詢工具。根據(jù)項(xiàng)目定位常見(jiàn)工具包括get_project_structure獲取解決方案的項(xiàng)目列表和依賴關(guān)系。get_type_info按名稱查詢類型的定義位置、基類、接口和成員。get_dependencies查詢某個(gè)類型的直接依賴和反向依賴。get_callers查詢某個(gè)方法被誰(shuí)調(diào)用。get_callees查詢某個(gè)方法調(diào)用了哪些方法。AI 客戶端拿到這些工具后就能在對(duì)話中按需調(diào)用。例如用戶問(wèn)“OrderService 的 ExecuteAsync 被哪些地方調(diào)用了”AI 不會(huì)自己瞎猜而是調(diào)用get_callers工具拿到 Slnmap 返回的結(jié)構(gòu)化方法調(diào)用列表。3.4 為什么這個(gè)設(shè)計(jì)比“貼文件”更好這里做一個(gè)對(duì)比更容易理解對(duì)比維度傳統(tǒng)方式把文件貼給 AISlnmap 方式MCP 查詢上下文占用隨文件數(shù)量線性增長(zhǎng)只占用查詢結(jié)果關(guān)系準(zhǔn)確性依賴 AI 推斷容易出錯(cuò)Roslyn 語(yǔ)義分析精確大型代碼庫(kù)支持很差窗口很快打滿按需查詢天然支持信息完整度只看到貼進(jìn)去的文件能看到全庫(kù)關(guān)系交互體驗(yàn)用戶手動(dòng)挑選文件AI 自主調(diào)用工具這個(gè)設(shè)計(jì)的核心價(jià)值是上下文窗口不再是代碼庫(kù)大小的瓶頸。4. 環(huán)境準(zhǔn)備與前置條件Slnmap 是面向 .NET 生態(tài)的工具所以環(huán)境準(zhǔn)備以 .NET SDK 為核心。4.1 運(yùn)行環(huán)境清單依賴項(xiàng)說(shuō)明.NET SDK建議使用當(dāng)前 LTS 版本實(shí)際項(xiàng)目請(qǐng)以官方 README 要求為準(zhǔn)操作系統(tǒng)Windows、macOS、Linux 均可.NET 本身跨平臺(tái)目標(biāo)代碼庫(kù)需要分析解決方案中包含 .NET 項(xiàng)目.NET Framework 或 .NET / .NET Core 均可MCP 客戶端Claude Desktop、Cursor、自研 MCP Client 等4.2 安裝與啟動(dòng)如果目標(biāo)是快速體驗(yàn)一般方式是從源碼運(yùn)行或安裝發(fā)布包。這里給出通用的啟動(dòng)方式# 克隆代碼庫(kù)如果 Slnmap 是開(kāi)放源碼項(xiàng)目 git clone https://github.com/your-repo/slnmap.git cd slnmap # 還原依賴并構(gòu)建 dotnet restore dotnet build # 啟動(dòng) MCP Server 并指定要分析的目標(biāo)解決方案 dotnet run --project src/Slnmap -- --solution /path/to/YourSolution.sln --transport stdio另一種常見(jiàn)方式是通過(guò)npx或其他包管理工具直接運(yùn)行具體取決于項(xiàng)目發(fā)布形式。無(wú)論哪種方式核心啟動(dòng)參數(shù)都會(huì)包括--solution或--project指定要分析的代碼庫(kù)入口。--transportMCP 傳輸方式常見(jiàn)有stdio標(biāo)準(zhǔn)輸入輸出和sseHTTP 流式。4.3 驗(yàn)證 MCP Server 是否啟動(dòng)成功對(duì)于stdio傳輸模式啟動(dòng)后進(jìn)程會(huì)等待標(biāo)準(zhǔn)輸入上的 JSON-RPC 消息。你可以在終端里手動(dòng)輸入一條 MCPinitialize請(qǐng)求來(lái)驗(yàn)證{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0.0}}}如果服務(wù)正常你會(huì)收到包含 server 信息和 capabilities 的響應(yīng)。如果沒(méi)有任何輸出說(shuō)明啟動(dòng)階段就失敗了優(yōu)先檢查路徑參數(shù)和依賴還原是否成功。5. 核心流程拆解讓 Slnmap 跑起來(lái)這一節(jié)我們拆解一個(gè)完整的最小流程從準(zhǔn)備測(cè)試代碼庫(kù)到啟動(dòng) Slnmap再到通過(guò) MCP 調(diào)用工具獲取代碼圖。5.1 準(zhǔn)備一個(gè)示例解決方案為了演示我們創(chuàng)建一個(gè)最簡(jiǎn)但包含依賴關(guān)系的解決方案MyShop/ ├── MyShop.sln ├── src/ │ ├── MyShop.Domain/ │ │ └── Customer.cs │ ├── MyShop.Application/ │ │ └── CustomerService.cs │ └── MyShop.Api/ │ ├── Controllers/ │ │ └── CustomerController.cs │ └── MyShop.Api.csproj各文件內(nèi)容如下// 文件路徑src/MyShop.Domain/Customer.cs namespace MyShop.Domain; public class Customer { public int Id { get; set; } public string Name { get; set; } string.Empty; }// 文件路徑src/MyShop.Application/CustomerService.cs using MyShop.Domain; namespace MyShop.Application; public interface ICustomerRepository { TaskCustomer? GetByIdAsync(int id); } public class CustomerService { private readonly ICustomerRepository _repository; public CustomerService(ICustomerRepository repository) { _repository repository; } public async TaskCustomer? GetCustomerAsync(int id) { return await _repository.GetByIdAsync(id); } }// 文件路徑src/MyShop.Api/Controllers/CustomerController.cs using Microsoft.AspNetCore.Mvc; using MyShop.Application; namespace MyShop.Api.Controllers; [ApiController] [Route(api/customers)] public class CustomerController : ControllerBase { private readonly CustomerService _service; public CustomerController(CustomerService service) { _service service; } [HttpGet({id})] public async TaskActionResultCustomer? Get(int id) { var customer await _service.GetCustomerAsync(id); if (customer is null) return NotFound(); return Ok(customer); } }三個(gè)項(xiàng)目之間的依賴關(guān)系很清晰MyShop.Api引用MyShop.Application。MyShop.Application引用MyShop.Domain。CustomerController依賴CustomerService。CustomerService依賴ICustomerRepository。這個(gè)例子雖然小但已經(jīng)包含項(xiàng)目引用、接口依賴、類依賴、方法調(diào)用四種圖關(guān)系。5.2 啟動(dòng) Slnmap 并指向示例解決方案dotnet run --project src/Slnmap -- \ --solution /path/to/MyShop/MyShop.sln \ --transport stdio啟動(dòng)日志如果顯示類似“MCP server started”的信息說(shuō)明服務(wù)已經(jīng)就緒。在stdio模式下你會(huì)看到進(jìn)程掛起等待輸入這是正常行為。5.3 調(diào)用工具查詢項(xiàng)目依賴MCP 協(xié)議中調(diào)用工具使用tools/call方法。假設(shè) Slnmap 暴露了get_project_dependencies工具請(qǐng)求格式如下{jsonrpc:2.0,id:2,method:tools/call,params:{name:get_project_dependencies,arguments:{projectName:MyShop.Api}}}預(yù)期響應(yīng)中會(huì)包含 MyShop.Api 直接和間接依賴的項(xiàng)目信息類似{ jsonrpc: 2.0, id: 2, result: { content: [ { type: text, text: [{\Project\:\MyShop.Api\,\DependsOn\:[\MyShop.Application\,\MyShop.Domain\]}] } ] } }這個(gè)查詢結(jié)果說(shuō)明MyShop.Api不僅直接引用了MyShop.Application還通過(guò)傳遞引用依賴了MyShop.Domain。5.4 查詢類型反向依賴假設(shè)你想知道CustomerService被誰(shuí)用到可以調(diào)用對(duì)應(yīng)的反向依賴查詢工具{jsonrpc:2.0,id:3,method:tools/call,params:{name:get_reverse_dependencies,arguments:{typeName:CustomerService}}}從代碼庫(kù)結(jié)構(gòu)看CustomerController構(gòu)造時(shí)注入了CustomerService所以查詢結(jié)果會(huì)指向CustomerController。這個(gè)能力在重構(gòu)時(shí)非常有價(jià)值改一個(gè)構(gòu)造函數(shù)簽名前先查一下誰(shuí)在用它。6. 在 AI 編程助手中接入 SlnmapSlnmap 的價(jià)值要在 AI 客戶端中才能真正體現(xiàn)。這里分別說(shuō)明在兩種場(chǎng)景下的接入方式。6.1 在 Claude Desktop 中注冊(cè) MCP ServerClaude Desktop 支持通過(guò)配置文件注冊(cè) MCP Server。如果你把 Slnmap 編譯成可執(zhí)行文件可以將其注冊(cè)為一個(gè)command類型的 MCP Server。配置位置通常為claude_desktop_config.json示例{ mcpServers: { slnmap: { command: dotnet, args: [ /path/to/Slnmap.dll, --solution, /path/to/MyShop/MyShop.sln, --transport, stdio ] } } }重啟 Claude Desktop 后會(huì)話中就能看到 Slnmap 提供的工具列表。之后你可以直接在對(duì)話里提問(wèn)Claude 會(huì)在需要時(shí)自動(dòng)調(diào)用工具。6.2 在 Cursor 中配置Cursor 的 MCP 配置入口在 Settings → MCP選擇 Add New MCP Server填寫(xiě)NameslnmapTypecommandCommand啟動(dòng)命令例如dotnet /path/to/Slnmap.dll --solution /path/to/MyShop/MyShop.sln --transport stdio保存后Cursor 會(huì)自動(dòng)發(fā)現(xiàn) Slnmap 暴露的工具。在寫(xiě)代碼時(shí)AI 就能調(diào)用工具查詢代碼庫(kù)關(guān)系而不是只依賴當(dāng)前打開(kāi)的文件。6.3 在自研 Agent 中調(diào)用如果你在寫(xiě)自己的 AI Agent可以用 C# 或其他語(yǔ)言構(gòu)造 MCP 標(biāo)準(zhǔn) JSON-RPC 請(qǐng)求通過(guò)標(biāo)準(zhǔn)輸入輸出與 Slnmap 通信。核心邏輯如下// 示意代碼發(fā)送 MCP initialize 請(qǐng)求 var process new Process { StartInfo new ProcessStartInfo { FileName dotnet, Arguments Slnmap.dll --solution /path/to/MyShop/MyShop.sln --transport stdio, RedirectStandardInput true, RedirectStandardOutput true, UseShellExecute false } }; process.Start(); var request {\jsonrpc\:\2.0\,\id\:1,\method\:\initialize\,\params\:{}}; await process.StandardInput.WriteLineAsync(request); var response await process.StandardOutput.ReadLineAsync(); Console.WriteLine(response);自研接入時(shí)需要注意 MCP 協(xié)議要求先完成initialize握手再發(fā)送notifications/initialized通知最后才能調(diào)用工具。7. 運(yùn)行結(jié)果與效果驗(yàn)證7.1 驗(yàn)證項(xiàng)目依賴查詢啟動(dòng) Slnmap 并完成一次initialize握手之后調(diào)用get_project_dependencies。如果返回結(jié)果中包含了 MyShop.Api 對(duì) MyShop.Application 和 MyShop.Domain 的依賴說(shuō)明 Roslyn 正確解析了解決方案中的ProjectReference。7.2 驗(yàn)證類型信息查詢調(diào)用類型查詢工具傳入CustomerService{jsonrpc:2.0,id:4,method:tools/call,params:{name:get_type_info,arguments:{typeName:CustomerService}}}預(yù)期結(jié)果包括類型所在命名空間MyShop.Application定義文件路徑src/MyShop.Application/CustomerService.cs構(gòu)造函數(shù)參數(shù)類型ICustomerRepository公開(kāi)方法GetCustomerAsync這些信息說(shuō)明 Slnmap 不只是做了文本索引而是真的解析了語(yǔ)義模型。如果 Slnmap 只是簡(jiǎn)單做正則匹配它是無(wú)法告訴你構(gòu)造函數(shù)參數(shù)類型的。7.3 驗(yàn)證方法調(diào)用鏈如果你在示例代碼里讓CustomerService.GetCustomerAsync調(diào)用_repository.GetByIdAsync那么通過(guò)方法調(diào)用查詢工具可以得到CustomerService.GetCustomerAsync調(diào)用了ICustomerRepository.GetByIdAsync。這個(gè)信息對(duì) AI 助手理解代碼執(zhí)行路徑非常關(guān)鍵。沒(méi)有代碼圖AI 可能看到_repository.GetByIdAsync卻不知道調(diào)用的目標(biāo)是接口方法。7.4 如何判斷 Slnmap 是否正常工作判斷標(biāo)準(zhǔn)有三條能返回結(jié)構(gòu)化結(jié)果返回的是 JSON 而不是報(bào)錯(cuò)信息。結(jié)果與代碼庫(kù)實(shí)際一致對(duì)照源碼項(xiàng)目依賴、類型信息、調(diào)用關(guān)系都正確。查詢響應(yīng)及時(shí)MCP 調(diào)用沒(méi)有明顯超時(shí)。如果其中任何一條不滿足優(yōu)先查看啟動(dòng)日志和標(biāo)準(zhǔn)錯(cuò)誤輸出。8. 常見(jiàn)問(wèn)題與排查思路問(wèn)題現(xiàn)象可能原因排查方式解決方案啟動(dòng)后沒(méi)有任何輸出解決方案路徑錯(cuò)誤或依賴還原失敗檢查--solution路徑在項(xiàng)目目錄手動(dòng)執(zhí)行dotnet restore確保路徑正確先還原依賴再啟動(dòng)MCP initialize 請(qǐng)求無(wú)響應(yīng)傳輸模式不匹配確認(rèn)客戶端用 stdio 連接時(shí)服務(wù)端也用 stdio統(tǒng)一傳輸模式檢查啟動(dòng)參數(shù)查詢類型時(shí)返回空結(jié)果類型名稱寫(xiě)錯(cuò)或代碼庫(kù)不是 Roslyn 可加載的 .NET 項(xiàng)目確認(rèn)類型全名含命名空間檢查目標(biāo)項(xiàng)目能否在命令行下編譯使用全名查詢先確認(rèn)項(xiàng)目可以dotnet build分析大型解決方案時(shí)耗時(shí)過(guò)長(zhǎng)代碼庫(kù)規(guī)模大Roslyn 全量分析需要時(shí)間查看啟動(dòng)日志中的分析進(jìn)度檢查是否重復(fù)分析同一項(xiàng)目明確分析范圍必要時(shí)先分析子集項(xiàng)目客戶端顯示工具不存在MCP Server 版本與客戶端不兼容或工具名稱變化查看 MCP Server 的tools/list響應(yīng)按實(shí)際工具名稱調(diào)用不要寫(xiě)死.NET Framework 項(xiàng)目加載失敗目標(biāo)項(xiàng)目需要 MSBuild 相關(guān)組件檢查是否安裝了對(duì)應(yīng)版本的 .NET Framework Developer Pack在具備構(gòu)建該項(xiàng)目的環(huán)境中運(yùn)行分析一個(gè)很關(guān)鍵的經(jīng)驗(yàn)是Slnmap 能不能正確分析首先取決于目標(biāo)代碼庫(kù)能不能被 Roslyn 正確加載。如果命令行下連dotnet build都過(guò)不了Slnmap 大概率也會(huì)失敗。所以在排查 MCP 層問(wèn)題之前先確認(rèn)代碼庫(kù)本身可用。9. 最佳實(shí)踐與工程建議9.1 按需分析不要全量加載對(duì)大型企業(yè)級(jí)解決方案不要一次加載所有項(xiàng)目再查詢。Slnmap 這類工具必然受 Roslyn 編譯時(shí)間和內(nèi)存的約束。如果你的解決方案包含幾十甚至上百個(gè)項(xiàng)目?jī)?yōu)先考慮啟動(dòng)時(shí)指定要分析的子集例如只分析應(yīng)用層和 API 層。按需增量加載先拿到項(xiàng)目列表再針對(duì)特定項(xiàng)目做深度分析。把分析結(jié)果緩存下來(lái)重復(fù)使用。9.2 使用全名查詢避免歧義在 MCP 調(diào)用時(shí)類型名盡量帶命名空間。因?yàn)椴煌臻g下可能有同名類型只傳CustomerService可能命中多個(gè)結(jié)果。推薦格式{name:get_type_info,arguments:{typeName:MyShop.Application.CustomerService}}9.3 與代碼搜索工具配合使用Slnmap 提供的是語(yǔ)義圖譜信息它不一定包含“某個(gè)字符串出現(xiàn)在哪些文件”這種文本搜索能力。與 grep、ripgrep 等文本搜索工具配合才能覆蓋代碼理解和代碼定位的完整鏈路。9.4 安全邊界與權(quán)限控制MCP Server 本質(zhì)上是本機(jī)代碼執(zhí)行服務(wù)。在使用 Slnmap 時(shí)要注意不要在未授權(quán)的情況下分析敏感項(xiàng)目的完整依賴圖尤其是包含密鑰、連接字符串、內(nèi)部實(shí)現(xiàn)細(xì)節(jié)的代碼庫(kù)。如果 Slnmap 部署為遠(yuǎn)程服務(wù)必須做訪問(wèn)控制避免任意 MCP 客戶端都能查詢代碼庫(kù)結(jié)構(gòu)。在用 AI 助手時(shí)注意不要把不應(yīng)暴露的代碼內(nèi)容發(fā)送給云端大模型。9.5 制定 MCP 工具命名規(guī)范如果你在團(tuán)隊(duì)內(nèi)推廣 Slnmap 或自研類似的工具給 MCP 工具命名時(shí)盡量遵循統(tǒng)一模式get_前綴的查詢工具get_type_info、get_dependencies。find_前綴的探索工具find_callers、find_references。list_前綴的枚舉工具list_projects、list_members。規(guī)范命名不僅讓 AI 更容易理解工具用途也能減少把參數(shù)傳錯(cuò)的概率。10. 總結(jié)與后續(xù)學(xué)習(xí)方向Slnmap 代表了一類新的 .NET 開(kāi)發(fā)工具方向用編譯器級(jí)的語(yǔ)義分析能力為 AI 編程助手補(bǔ)上代碼庫(kù)全局視角。它的意義不在于“又一個(gè) MCP Server”而在于它把 Roslyn 多年積累的代碼分析能力通過(guò)標(biāo)準(zhǔn)協(xié)議開(kāi)放給了 AI 工具鏈。對(duì)于維護(hù)大型 .NET 解決方案的開(kāi)發(fā)者這種能力意味著 AI 不再是一個(gè)“只看局部文件的實(shí)習(xí)生”而是一個(gè)“能隨時(shí)查詢?nèi)株P(guān)系的高級(jí)助手”。如果你正在做 .NET 開(kāi)發(fā)并且頻繁使用 AI 編程助手建議按這篇文章的流程把 Slnmap 跑起來(lái)。先在小解決方案上驗(yàn)證工具能力再逐步引入到真實(shí)項(xiàng)目中。理解 Roslyn 語(yǔ)義模型是 .NET 開(kāi)發(fā)者被低估的一項(xiàng)技能Slnmap 恰好是理解 Roslyn 能力邊界的一個(gè)極好入口。后續(xù)可以繼續(xù)探索的方向包括基于代碼圖做架構(gòu)守護(hù)、自動(dòng)生成依賴文檔、將代碼圖導(dǎo)出到圖數(shù)據(jù)庫(kù)做更深度的分析或者把 Slnmap 集成到 CI 流水線中對(duì)每次變更做影響范圍分析。對(duì)這個(gè)領(lǐng)域有興趣的開(kāi)發(fā)者值得持續(xù)關(guān)注。 Slnmap：基于Roslyn的Code Graph MCP Server，讓AI讀懂.NET大型代碼庫(kù)
如果你維護(hù)過(guò)大型 .NET 解決方案一定遇到過(guò)這樣的場(chǎng)景項(xiàng)目里有幾十個(gè) csproj類與類之間的依賴關(guān)系盤(pán)根錯(cuò)節(jié)方法調(diào)用鏈跨越了三四個(gè)程序集。本地調(diào)試還能靠 IDE 的“轉(zhuǎn)到定義”一點(diǎn)點(diǎn)摸但當(dāng)你試圖讓 AI 編程助手幫你改代碼、做重構(gòu)、解釋業(yè)務(wù)邏輯時(shí)它卻常常答非所問(wèn)——因?yàn)?AI 看到的只是你貼給它的那幾個(gè)文件它看不到整個(gè)解決方案的依賴關(guān)系和調(diào)用上下文。這個(gè)問(wèn)題的本質(zhì)是傳統(tǒng) AI 編程工具缺少對(duì)代碼庫(kù)全局結(jié)構(gòu)的感知能力。最近在 Hacker News 看到的一個(gè)項(xiàng)目很有意思Slnmap一個(gè)基于 Roslyn 的 code graph MCP server專門(mén)為 .NET 代碼庫(kù)服務(wù)。它把 Roslyn 的語(yǔ)法樹(shù)和符號(hào)分析能力與 MCPModel Context Protocol結(jié)合起來(lái)讓 AI 編程助手可以按需查詢代碼庫(kù)的依賴圖、調(diào)用關(guān)系、類型結(jié)構(gòu)等語(yǔ)義信息。這篇文章會(huì)從實(shí)際工程角度拆解 Slnmap它解決的是什么問(wèn)題、核心原理是什么、怎么配置和啟動(dòng)、如何在 Cursor / Claude Desktop / 自研 Agent 中接入它以及真實(shí)項(xiàng)目中的坑和最佳實(shí)踐。1. 這篇文章真正要解決的問(wèn)題先說(shuō)一個(gè)經(jīng)常被忽略的事實(shí)給 AI 編程助手“喂文件”和讓它“理解代碼庫(kù)”是兩回事。如果你用過(guò) Copilot Chat、Cursor 或 Claude Code 處理大型解決方案大概率遇到過(guò)以下幾種情況上下文窗口不夠用。一個(gè)大型 .NET 解決方案可能有幾百個(gè)源文件全部塞進(jìn)上下文既不可能也沒(méi)必要但 AI 需要的那幾個(gè)關(guān)鍵文件恰恰不在上下文里。缺少依賴關(guān)系信息。AI 看到一個(gè)OrderService類但它不知道OrderService依賴了哪些倉(cāng)儲(chǔ)接口、被哪個(gè)控制器調(diào)用、實(shí)現(xiàn)了哪個(gè)抽象基類。這些信息不直接寫(xiě)在當(dāng)前文件里卻決定了重構(gòu)時(shí)會(huì)不會(huì)破壞其他模塊。符號(hào)解析不準(zhǔn)確。同名類、Partial 類、通過(guò)依賴注入注冊(cè)的接口實(shí)現(xiàn)只看源碼文本很難判斷運(yùn)行時(shí)真正用的是哪個(gè)實(shí)現(xiàn)。人工挑選上下文太累。讓開(kāi)發(fā)者手動(dòng)把相關(guān)文件拖進(jìn)對(duì)話在大型代碼庫(kù)里篩選成本極高。Slnmap 的思路是把代碼庫(kù)的圖譜信息通過(guò) MCP 協(xié)議暴露給 AI 助手讓 AI 按需查詢而不是靠猜。Roslyn 在這里起到的作用是“語(yǔ)義分析引擎”。它不是簡(jiǎn)單讀取文本而是能夠解析出完整的符號(hào)信息類型在哪里定義、方法被誰(shuí)調(diào)用、項(xiàng)目之間誰(shuí)引用誰(shuí)。Slnmap 把 Roslyn 分析出的這些信息構(gòu)造成一張 code graph再通過(guò) MCP server 提供給 AI 客戶端查詢。換句話說(shuō)Slnmap 讓 AI 從“讀文件”升級(jí)為“讀代碼庫(kù)”。這是本篇要講的核心判斷。2. 三個(gè)繞不開(kāi)的概念Roslyn、代碼圖與 MCP在動(dòng)手操作之前需要先弄清楚三個(gè)基礎(chǔ)概念。如果這三個(gè)概念沒(méi)有對(duì)齊后面配置和調(diào)試的時(shí)候會(huì)很難受。2.1 Roslyn不只是編譯器Roslyn 是微軟開(kāi)源的 C# 和 Visual Basic 編譯器平臺(tái)但它和傳統(tǒng)編譯器最大的區(qū)別是Roslyn 把自己做成了一組 API。傳統(tǒng)編譯器是“源碼進(jìn)、程序集出”的黑盒你很難在編譯過(guò)程中拿到中間信息。Roslyn 則把編譯過(guò)程拆成多個(gè)可訪問(wèn)的階段Syntax Tree語(yǔ)法樹(shù)代碼的語(yǔ)法結(jié)構(gòu)比如類聲明、方法聲明、語(yǔ)句塊。Symbol符號(hào)語(yǔ)法樹(shù)背后的語(yǔ)義信息比如OrderService這個(gè)類名對(duì)應(yīng)哪個(gè)類型、GetOrderById這個(gè)方法的完整簽名是什么。Semantic Model語(yǔ)義模型把語(yǔ)法樹(shù)和符號(hào)關(guān)聯(lián)起來(lái)告訴你某個(gè)標(biāo)識(shí)符在特定上下文里到底引用了哪個(gè)類型或方法。Slnmap 用 Roslyn 不是為了編譯出 DLL而是利用 Roslyn 的語(yǔ)義分析能力構(gòu)建一個(gè)可供查詢的代碼關(guān)系網(wǎng)絡(luò)。2.2 代碼圖Code Graph把代碼變成關(guān)系數(shù)據(jù)“代碼圖”可以理解為代碼庫(kù)的“關(guān)系型抽象”。它關(guān)注的是實(shí)體之間的關(guān)系而不是具體代碼內(nèi)容。在 .NET 代碼庫(kù)中常見(jiàn)的圖關(guān)系包括項(xiàng)目之間的 ProjectReference。類型之間的繼承關(guān)系和接口實(shí)現(xiàn)。方法之間的調(diào)用關(guān)系Caller / Callee。類型之間的屬性引用、方法參數(shù)引用、字段類型引用。舉個(gè)例子CustomerController依賴ICustomerServiceCustomerService實(shí)現(xiàn)了ICustomerService并依賴ICustomerRepositorySqlCustomerRepository實(shí)現(xiàn)了ICustomerRepository。這段依賴鏈如果靠人肉梳理需要打開(kāi)三四個(gè)文件來(lái)回跳。而代碼圖可以把這些關(guān)系直接輸出為結(jié)構(gòu)化數(shù)據(jù){ type: CustomerController, dependsOn: [ICustomerService], implementedBy: [], references: [CustomerService, CustomerRepository] }2.3 MCPAI 世界的“USB-C 接口”MCPModel Context Protocol是 Anthropic 提出的開(kāi)放協(xié)議目的是統(tǒng)一 AI 應(yīng)用與外部數(shù)據(jù)、工具之間的連接方式?？梢园阉斫獬?AI 領(lǐng)域的 USB-C 標(biāo)準(zhǔn)不同的工具通過(guò)統(tǒng)一協(xié)議接入不同的 AI 客戶端不需要為每一個(gè) AI 產(chǎn)品單獨(dú)定制集成。MCP 協(xié)議中有幾個(gè)核心角色MCP Server提供服務(wù)的一方把某個(gè)能力封裝成協(xié)議接口。Slnmap 就是一個(gè) MCP Server。MCP Client消費(fèi)服務(wù)的一方比如 Claude Desktop、Cursor或者你自己寫(xiě)的 Agent。ToolServer 暴露給 Client 調(diào)用的具體能力比如“查詢類型依賴”“查找方法調(diào)用鏈”。Slnmap 屬于 MCP Server它把 Roslyn 分析結(jié)果包裝成若干 ToolAI 客戶端通過(guò)標(biāo)準(zhǔn)協(xié)議調(diào)用這些 Tool就能拿到結(jié)構(gòu)化的代碼圖譜信息。2.4 三者的關(guān)系用一句話概括Roslyn 負(fù)責(zé)分析代碼圖負(fù)責(zé)存儲(chǔ)MCP 負(fù)責(zé)傳輸。Slnmap 啟動(dòng)時(shí)先用 Roslyn 加載目標(biāo)解決方案或項(xiàng)目分析出符號(hào)和關(guān)系構(gòu)建代碼圖然后啟動(dòng)一個(gè) MCP ServerAI 編程助手通過(guò) MCP 協(xié)議向 Server 發(fā)起查詢請(qǐng)求Server 返回圖譜數(shù)據(jù)。整個(gè)過(guò)程不需要把整個(gè)代碼庫(kù)塞進(jìn)上下文。3. Slnmap 工作原理與架構(gòu)拆解從架構(gòu)上看Slnmap 可以分為三個(gè)層次分析層、圖構(gòu)建層、服務(wù)層。3.1 分析層Roslyn 項(xiàng)目加載與符號(hào)解析Slnmap 首先需要定位目標(biāo)代碼庫(kù)這一步通常通過(guò)傳入.sln或.csproj文件路徑來(lái)完成。Roslyn 提供了MSBuildWorkspace類可以從解決方案文件加載項(xiàng)目并獲取每個(gè)項(xiàng)目的Compilation對(duì)象。Compilation是所有語(yǔ)義分析的入口// 示意代碼使用 MSBuildWorkspace 加載解決方案 using Microsoft.CodeAnalysis; using Microsoft.CodeAnalysis.MSBuild; var workspace MSBuildWorkspace.Create(); var solution await workspace.OpenSolutionAsync(path/to/YourSolution.sln); foreach (var project in solution.Projects) { var compilation await project.GetCompilationAsync(); // 拿到 compilation 后可以遍歷語(yǔ)法樹(shù)、獲取符號(hào)、分析依賴 }這里的關(guān)鍵點(diǎn)是Slnmap 分析的是Roslyn 的語(yǔ)義模型Semantic Model而不是簡(jiǎn)單的文本匹配。這意味著它能準(zhǔn)確區(qū)分兩個(gè)同名但來(lái)自不同命名空間的類型。通過(guò)別名引用的類型。泛型實(shí)例化后的實(shí)際類型參數(shù)。擴(kuò)展方法實(shí)際調(diào)用的靜態(tài)類。這些信息僅靠 GPT 的文本理解是拿不到的而 Roslyn 可以精確給出。3.2 圖構(gòu)建層提取并存儲(chǔ)關(guān)系拿到Compilation之后Slnmap 會(huì)遍歷所有語(yǔ)法樹(shù)提取兩類信息類型級(jí)信息類型名稱、命名空間、文件路徑。基類、實(shí)現(xiàn)的接口。類型中聲明的成員屬性、方法、字段。每個(gè)成員的類型引用。依賴級(jí)信息類 A 是否在方法體內(nèi)調(diào)用了類 B 的方法。類 A 是否在屬性類型中引用了類 B。項(xiàng)目 X 是否引用了項(xiàng)目 Y。方法 M 被哪些方法調(diào)用。這些關(guān)系會(huì)組織成一個(gè)圖數(shù)據(jù)結(jié)構(gòu)。在實(shí)際存儲(chǔ)上可以選擇內(nèi)存數(shù)據(jù)結(jié)構(gòu)適合單次會(huì)話分析也可以序列化成 JSON、圖數(shù)據(jù)庫(kù)或內(nèi)存數(shù)據(jù)庫(kù)以便反復(fù)查詢。3.3 服務(wù)層MCP 工具暴露Slnmap 啟動(dòng) MCP Server 后會(huì)暴露一組查詢工具。根據(jù)項(xiàng)目定位常見(jiàn)工具包括get_project_structure獲取解決方案的項(xiàng)目列表和依賴關(guān)系。get_type_info按名稱查詢類型的定義位置、基類、接口和成員。get_dependencies查詢某個(gè)類型的直接依賴和反向依賴。get_callers查詢某個(gè)方法被誰(shuí)調(diào)用。get_callees查詢某個(gè)方法調(diào)用了哪些方法。AI 客戶端拿到這些工具后就能在對(duì)話中按需調(diào)用。例如用戶問(wèn)“OrderService 的 ExecuteAsync 被哪些地方調(diào)用了”AI 不會(huì)自己瞎猜而是調(diào)用get_callers工具拿到 Slnmap 返回的結(jié)構(gòu)化方法調(diào)用列表。3.4 為什么這個(gè)設(shè)計(jì)比“貼文件”更好這里做一個(gè)對(duì)比更容易理解對(duì)比維度傳統(tǒng)方式把文件貼給 AISlnmap 方式MCP 查詢上下文占用隨文件數(shù)量線性增長(zhǎng)只占用查詢結(jié)果關(guān)系準(zhǔn)確性依賴 AI 推斷容易出錯(cuò)Roslyn 語(yǔ)義分析精確大型代碼庫(kù)支持很差窗口很快打滿按需查詢天然支持信息完整度只看到貼進(jìn)去的文件能看到全庫(kù)關(guān)系交互體驗(yàn)用戶手動(dòng)挑選文件AI 自主調(diào)用工具這個(gè)設(shè)計(jì)的核心價(jià)值是上下文窗口不再是代碼庫(kù)大小的瓶頸。4. 環(huán)境準(zhǔn)備與前置條件Slnmap 是面向 .NET 生態(tài)的工具所以環(huán)境準(zhǔn)備以 .NET SDK 為核心。4.1 運(yùn)行環(huán)境清單依賴項(xiàng)說(shuō)明.NET SDK建議使用當(dāng)前 LTS 版本實(shí)際項(xiàng)目請(qǐng)以官方 README 要求為準(zhǔn)操作系統(tǒng)Windows、macOS、Linux 均可.NET 本身跨平臺(tái)目標(biāo)代碼庫(kù)需要分析解決方案中包含 .NET 項(xiàng)目.NET Framework 或 .NET / .NET Core 均可MCP 客戶端Claude Desktop、Cursor、自研 MCP Client 等4.2 安裝與啟動(dòng)如果目標(biāo)是快速體驗(yàn)一般方式是從源碼運(yùn)行或安裝發(fā)布包。這里給出通用的啟動(dòng)方式# 克隆代碼庫(kù)如果 Slnmap 是開(kāi)放源碼項(xiàng)目 git clone https://github.com/your-repo/slnmap.git cd slnmap # 還原依賴并構(gòu)建 dotnet restore dotnet build # 啟動(dòng) MCP Server 并指定要分析的目標(biāo)解決方案 dotnet run --project src/Slnmap -- --solution /path/to/YourSolution.sln --transport stdio另一種常見(jiàn)方式是通過(guò)npx或其他包管理工具直接運(yùn)行具體取決于項(xiàng)目發(fā)布形式。無(wú)論哪種方式核心啟動(dòng)參數(shù)都會(huì)包括--solution或--project指定要分析的代碼庫(kù)入口。--transportMCP 傳輸方式常見(jiàn)有stdio標(biāo)準(zhǔn)輸入輸出和sseHTTP 流式。4.3 驗(yàn)證 MCP Server 是否啟動(dòng)成功對(duì)于stdio傳輸模式啟動(dòng)后進(jìn)程會(huì)等待標(biāo)準(zhǔn)輸入上的 JSON-RPC 消息。你可以在終端里手動(dòng)輸入一條 MCPinitialize請(qǐng)求來(lái)驗(yàn)證{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0.0}}}如果服務(wù)正常你會(huì)收到包含 server 信息和 capabilities 的響應(yīng)。如果沒(méi)有任何輸出說(shuō)明啟動(dòng)階段就失敗了優(yōu)先檢查路徑參數(shù)和依賴還原是否成功。5. 核心流程拆解讓 Slnmap 跑起來(lái)這一節(jié)我們拆解一個(gè)完整的最小流程從準(zhǔn)備測(cè)試代碼庫(kù)到啟動(dòng) Slnmap再到通過(guò) MCP 調(diào)用工具獲取代碼圖。5.1 準(zhǔn)備一個(gè)示例解決方案為了演示我們創(chuàng)建一個(gè)最簡(jiǎn)但包含依賴關(guān)系的解決方案MyShop/ ├── MyShop.sln ├── src/ │ ├── MyShop.Domain/ │ │ └── Customer.cs │ ├── MyShop.Application/ │ │ └── CustomerService.cs │ └── MyShop.Api/ │ ├── Controllers/ │ │ └── CustomerController.cs │ └── MyShop.Api.csproj各文件內(nèi)容如下// 文件路徑src/MyShop.Domain/Customer.cs namespace MyShop.Domain; public class Customer { public int Id { get; set; } public string Name { get; set; } string.Empty; }// 文件路徑src/MyShop.Application/CustomerService.cs using MyShop.Domain; namespace MyShop.Application; public interface ICustomerRepository { TaskCustomer? GetByIdAsync(int id); } public class CustomerService { private readonly ICustomerRepository _repository; public CustomerService(ICustomerRepository repository) { _repository repository; } public async TaskCustomer? GetCustomerAsync(int id) { return await _repository.GetByIdAsync(id); } }// 文件路徑src/MyShop.Api/Controllers/CustomerController.cs using Microsoft.AspNetCore.Mvc; using MyShop.Application; namespace MyShop.Api.Controllers; [ApiController] [Route(api/customers)] public class CustomerController : ControllerBase { private readonly CustomerService _service; public CustomerController(CustomerService service) { _service service; } [HttpGet({id})] public async TaskActionResultCustomer? Get(int id) { var customer await _service.GetCustomerAsync(id); if (customer is null) return NotFound(); return Ok(customer); } }三個(gè)項(xiàng)目之間的依賴關(guān)系很清晰MyShop.Api引用MyShop.Application。MyShop.Application引用MyShop.Domain。CustomerController依賴CustomerService。CustomerService依賴ICustomerRepository。這個(gè)例子雖然小但已經(jīng)包含項(xiàng)目引用、接口依賴、類依賴、方法調(diào)用四種圖關(guān)系。5.2 啟動(dòng) Slnmap 并指向示例解決方案dotnet run --project src/Slnmap -- \ --solution /path/to/MyShop/MyShop.sln \ --transport stdio啟動(dòng)日志如果顯示類似“MCP server started”的信息說(shuō)明服務(wù)已經(jīng)就緒。在stdio模式下你會(huì)看到進(jìn)程掛起等待輸入這是正常行為。5.3 調(diào)用工具查詢項(xiàng)目依賴MCP 協(xié)議中調(diào)用工具使用tools/call方法。假設(shè) Slnmap 暴露了get_project_dependencies工具請(qǐng)求格式如下{jsonrpc:2.0,id:2,method:tools/call,params:{name:get_project_dependencies,arguments:{projectName:MyShop.Api}}}預(yù)期響應(yīng)中會(huì)包含 MyShop.Api 直接和間接依賴的項(xiàng)目信息類似{ jsonrpc: 2.0, id: 2, result: { content: [ { type: text, text: [{\Project\:\MyShop.Api\,\DependsOn\:[\MyShop.Application\,\MyShop.Domain\]}] } ] } }這個(gè)查詢結(jié)果說(shuō)明MyShop.Api不僅直接引用了MyShop.Application還通過(guò)傳遞引用依賴了MyShop.Domain。5.4 查詢類型反向依賴假設(shè)你想知道CustomerService被誰(shuí)用到可以調(diào)用對(duì)應(yīng)的反向依賴查詢工具{jsonrpc:2.0,id:3,method:tools/call,params:{name:get_reverse_dependencies,arguments:{typeName:CustomerService}}}從代碼庫(kù)結(jié)構(gòu)看CustomerController構(gòu)造時(shí)注入了CustomerService所以查詢結(jié)果會(huì)指向CustomerController。這個(gè)能力在重構(gòu)時(shí)非常有價(jià)值改一個(gè)構(gòu)造函數(shù)簽名前先查一下誰(shuí)在用它。6. 在 AI 編程助手中接入 SlnmapSlnmap 的價(jià)值要在 AI 客戶端中才能真正體現(xiàn)。這里分別說(shuō)明在兩種場(chǎng)景下的接入方式。6.1 在 Claude Desktop 中注冊(cè) MCP ServerClaude Desktop 支持通過(guò)配置文件注冊(cè) MCP Server。如果你把 Slnmap 編譯成可執(zhí)行文件可以將其注冊(cè)為一個(gè)command類型的 MCP Server。配置位置通常為claude_desktop_config.json示例{ mcpServers: { slnmap: { command: dotnet, args: [ /path/to/Slnmap.dll, --solution, /path/to/MyShop/MyShop.sln, --transport, stdio ] } } }重啟 Claude Desktop 后會(huì)話中就能看到 Slnmap 提供的工具列表。之后你可以直接在對(duì)話里提問(wèn)Claude 會(huì)在需要時(shí)自動(dòng)調(diào)用工具。6.2 在 Cursor 中配置Cursor 的 MCP 配置入口在 Settings → MCP選擇 Add New MCP Server填寫(xiě)NameslnmapTypecommandCommand啟動(dòng)命令例如dotnet /path/to/Slnmap.dll --solution /path/to/MyShop/MyShop.sln --transport stdio保存后Cursor 會(huì)自動(dòng)發(fā)現(xiàn) Slnmap 暴露的工具。在寫(xiě)代碼時(shí)AI 就能調(diào)用工具查詢代碼庫(kù)關(guān)系而不是只依賴當(dāng)前打開(kāi)的文件。6.3 在自研 Agent 中調(diào)用如果你在寫(xiě)自己的 AI Agent可以用 C# 或其他語(yǔ)言構(gòu)造 MCP 標(biāo)準(zhǔn) JSON-RPC 請(qǐng)求通過(guò)標(biāo)準(zhǔn)輸入輸出與 Slnmap 通信。核心邏輯如下// 示意代碼發(fā)送 MCP initialize 請(qǐng)求 var process new Process { StartInfo new ProcessStartInfo { FileName dotnet, Arguments Slnmap.dll --solution /path/to/MyShop/MyShop.sln --transport stdio, RedirectStandardInput true, RedirectStandardOutput true, UseShellExecute false } }; process.Start(); var request {\jsonrpc\:\2.0\,\id\:1,\method\:\initialize\,\params\:{}}; await process.StandardInput.WriteLineAsync(request); var response await process.StandardOutput.ReadLineAsync(); Console.WriteLine(response);自研接入時(shí)需要注意 MCP 協(xié)議要求先完成initialize握手再發(fā)送notifications/initialized通知最后才能調(diào)用工具。7. 運(yùn)行結(jié)果與效果驗(yàn)證7.1 驗(yàn)證項(xiàng)目依賴查詢啟動(dòng) Slnmap 并完成一次initialize握手之后調(diào)用get_project_dependencies。如果返回結(jié)果中包含了 MyShop.Api 對(duì) MyShop.Application 和 MyShop.Domain 的依賴說(shuō)明 Roslyn 正確解析了解決方案中的ProjectReference。7.2 驗(yàn)證類型信息查詢調(diào)用類型查詢工具傳入CustomerService{jsonrpc:2.0,id:4,method:tools/call,params:{name:get_type_info,arguments:{typeName:CustomerService}}}預(yù)期結(jié)果包括類型所在命名空間MyShop.Application定義文件路徑src/MyShop.Application/CustomerService.cs構(gòu)造函數(shù)參數(shù)類型ICustomerRepository公開(kāi)方法GetCustomerAsync這些信息說(shuō)明 Slnmap 不只是做了文本索引而是真的解析了語(yǔ)義模型。如果 Slnmap 只是簡(jiǎn)單做正則匹配它是無(wú)法告訴你構(gòu)造函數(shù)參數(shù)類型的。7.3 驗(yàn)證方法調(diào)用鏈如果你在示例代碼里讓CustomerService.GetCustomerAsync調(diào)用_repository.GetByIdAsync那么通過(guò)方法調(diào)用查詢工具可以得到CustomerService.GetCustomerAsync調(diào)用了ICustomerRepository.GetByIdAsync。這個(gè)信息對(duì) AI 助手理解代碼執(zhí)行路徑非常關(guān)鍵。沒(méi)有代碼圖AI 可能看到_repository.GetByIdAsync卻不知道調(diào)用的目標(biāo)是接口方法。7.4 如何判斷 Slnmap 是否正常工作判斷標(biāo)準(zhǔn)有三條能返回結(jié)構(gòu)化結(jié)果返回的是 JSON 而不是報(bào)錯(cuò)信息。結(jié)果與代碼庫(kù)實(shí)際一致對(duì)照源碼項(xiàng)目依賴、類型信息、調(diào)用關(guān)系都正確。查詢響應(yīng)及時(shí)MCP 調(diào)用沒(méi)有明顯超時(shí)。如果其中任何一條不滿足優(yōu)先查看啟動(dòng)日志和標(biāo)準(zhǔn)錯(cuò)誤輸出。8. 常見(jiàn)問(wèn)題與排查思路問(wèn)題現(xiàn)象可能原因排查方式解決方案啟動(dòng)后沒(méi)有任何輸出解決方案路徑錯(cuò)誤或依賴還原失敗檢查--solution路徑在項(xiàng)目目錄手動(dòng)執(zhí)行dotnet restore確保路徑正確先還原依賴再啟動(dòng)MCP initialize 請(qǐng)求無(wú)響應(yīng)傳輸模式不匹配確認(rèn)客戶端用 stdio 連接時(shí)服務(wù)端也用 stdio統(tǒng)一傳輸模式檢查啟動(dòng)參數(shù)查詢類型時(shí)返回空結(jié)果類型名稱寫(xiě)錯(cuò)或代碼庫(kù)不是 Roslyn 可加載的 .NET 項(xiàng)目確認(rèn)類型全名含命名空間檢查目標(biāo)項(xiàng)目能否在命令行下編譯使用全名查詢先確認(rèn)項(xiàng)目可以dotnet build分析大型解決方案時(shí)耗時(shí)過(guò)長(zhǎng)代碼庫(kù)規(guī)模大Roslyn 全量分析需要時(shí)間查看啟動(dòng)日志中的分析進(jìn)度檢查是否重復(fù)分析同一項(xiàng)目明確分析范圍必要時(shí)先分析子集項(xiàng)目客戶端顯示工具不存在MCP Server 版本與客戶端不兼容或工具名稱變化查看 MCP Server 的tools/list響應(yīng)按實(shí)際工具名稱調(diào)用不要寫(xiě)死.NET Framework 項(xiàng)目加載失敗目標(biāo)項(xiàng)目需要 MSBuild 相關(guān)組件檢查是否安裝了對(duì)應(yīng)版本的 .NET Framework Developer Pack在具備構(gòu)建該項(xiàng)目的環(huán)境中運(yùn)行分析一個(gè)很關(guān)鍵的經(jīng)驗(yàn)是Slnmap 能不能正確分析首先取決于目標(biāo)代碼庫(kù)能不能被 Roslyn 正確加載。如果命令行下連dotnet build都過(guò)不了Slnmap 大概率也會(huì)失敗。所以在排查 MCP 層問(wèn)題之前先確認(rèn)代碼庫(kù)本身可用。9. 最佳實(shí)踐與工程建議9.1 按需分析不要全量加載對(duì)大型企業(yè)級(jí)解決方案不要一次加載所有項(xiàng)目再查詢。Slnmap 這類工具必然受 Roslyn 編譯時(shí)間和內(nèi)存的約束。如果你的解決方案包含幾十甚至上百個(gè)項(xiàng)目?jī)?yōu)先考慮啟動(dòng)時(shí)指定要分析的子集例如只分析應(yīng)用層和 API 層。按需增量加載先拿到項(xiàng)目列表再針對(duì)特定項(xiàng)目做深度分析。把分析結(jié)果緩存下來(lái)重復(fù)使用。9.2 使用全名查詢避免歧義在 MCP 調(diào)用時(shí)類型名盡量帶命名空間。因?yàn)椴煌臻g下可能有同名類型只傳CustomerService可能命中多個(gè)結(jié)果。推薦格式{name:get_type_info,arguments:{typeName:MyShop.Application.CustomerService}}9.3 與代碼搜索工具配合使用Slnmap 提供的是語(yǔ)義圖譜信息它不一定包含“某個(gè)字符串出現(xiàn)在哪些文件”這種文本搜索能力。與 grep、ripgrep 等文本搜索工具配合才能覆蓋代碼理解和代碼定位的完整鏈路。9.4 安全邊界與權(quán)限控制MCP Server 本質(zhì)上是本機(jī)代碼執(zhí)行服務(wù)。在使用 Slnmap 時(shí)要注意不要在未授權(quán)的情況下分析敏感項(xiàng)目的完整依賴圖尤其是包含密鑰、連接字符串、內(nèi)部實(shí)現(xiàn)細(xì)節(jié)的代碼庫(kù)。如果 Slnmap 部署為遠(yuǎn)程服務(wù)必須做訪問(wèn)控制避免任意 MCP 客戶端都能查詢代碼庫(kù)結(jié)構(gòu)。在用 AI 助手時(shí)注意不要把不應(yīng)暴露的代碼內(nèi)容發(fā)送給云端大模型。9.5 制定 MCP 工具命名規(guī)范如果你在團(tuán)隊(duì)內(nèi)推廣 Slnmap 或自研類似的工具給 MCP 工具命名時(shí)盡量遵循統(tǒng)一模式get_前綴的查詢工具get_type_info、get_dependencies。find_前綴的探索工具find_callers、find_references。list_前綴的枚舉工具list_projects、list_members。規(guī)范命名不僅讓 AI 更容易理解工具用途也能減少把參數(shù)傳錯(cuò)的概率。10. 總結(jié)與后續(xù)學(xué)習(xí)方向Slnmap 代表了一類新的 .NET 開(kāi)發(fā)工具方向用編譯器級(jí)的語(yǔ)義分析能力為 AI 編程助手補(bǔ)上代碼庫(kù)全局視角。它的意義不在于“又一個(gè) MCP Server”而在于它把 Roslyn 多年積累的代碼分析能力通過(guò)標(biāo)準(zhǔn)協(xié)議開(kāi)放給了 AI 工具鏈。對(duì)于維護(hù)大型 .NET 解決方案的開(kāi)發(fā)者這種能力意味著 AI 不再是一個(gè)“只看局部文件的實(shí)習(xí)生”而是一個(gè)“能隨時(shí)查詢?nèi)株P(guān)系的高級(jí)助手”。如果你正在做 .NET 開(kāi)發(fā)并且頻繁使用 AI 編程助手建議按這篇文章的流程把 Slnmap 跑起來(lái)。先在小解決方案上驗(yàn)證工具能力再逐步引入到真實(shí)項(xiàng)目中。理解 Roslyn 語(yǔ)義模型是 .NET 開(kāi)發(fā)者被低估的一項(xiàng)技能Slnmap 恰好是理解 Roslyn 能力邊界的一個(gè)極好入口。后續(xù)可以繼續(xù)探索的方向包括基于代碼圖做架構(gòu)守護(hù)、自動(dòng)生成依賴文檔、將代碼圖導(dǎo)出到圖數(shù)據(jù)庫(kù)做更深度的分析或者把 Slnmap 集成到 CI 流水線中對(duì)每次變更做影響范圍分析。對(duì)這個(gè)領(lǐng)域有興趣的開(kāi)發(fā)者值得持續(xù)關(guān)注。