C#原生AI编码智能体运行时：基于Roslyn与LLM的自动化代码重构实践

1. 项目缘起为什么我们需要一个C#原生的AI编码智能体运行时最近在折腾一个自动化代码生成和重构的项目发现市面上围绕Python生态的AI编码工具比如Cursor、Claude Code、甚至是GitHub Copilot的底层调用已经非常成熟但一旦涉及到企业级、需要深度集成到现有.NET/C#技术栈的场景就总感觉隔了一层。要么是调用外部API带来的延迟和成本问题要么是Python与C#进程间通信的复杂性和性能损耗。尤其是在处理大型遗留代码库、需要实时分析项目结构、理解复杂的领域逻辑时这种“隔靴搔痒”的感觉尤为明显。于是一个想法自然浮现能不能有一个完全用C#编写、原生运行在.NET环境下的AI编码智能体运行时它应该能直接理解C#的语法树Roslyn、能无缝操作解决方案.sln和项目文件.csproj、能直接调用本地的或内网部署的大语言模型LLM并且整个控制流、工具调用、状态管理都用C#来实现。这样它就能像一名真正的C#开发者一样“思考”和“操作”我们的代码库。这就是“SharpClawCode”这个项目名字的由来——用C#Sharp打造的、具备“利爪”Claw般精准代码操作能力的智能体Code Agent运行时。它瞄准的不是一个简单的代码补全插件而是一个可以自主或半自主执行复杂编码任务的“副驾驶”甚至“初级工程师”。比如给你一个模糊的需求描述它能自动分析现有代码规划修改步骤调用代码分析、生成、重构、测试等一系列工具最终提交一个完整的Pull Request。这一切都发生在你熟悉的Visual Studio或者Rider里或者作为一个后台服务集成在你的CI/CD流水线中。2. SharpClawCode的核心架构设计一个可插拔的智能体执行引擎SharpClawCode的设计核心是一个轻量级、高内聚、松耦合的智能体运行时引擎。它的目标不是重新发明AI模型而是为AI模型特别是LLM提供一个在C#世界里安全、高效、可控地执行编码任务的“身体”和“工具库”。2.1 运行时核心AgentRuntime与Orchestrator整个系统的基石是AgentRuntime类。你可以把它想象成一个微型的操作系统内核负责智能体生命周期的管理、资源分配和基础服务的提供。它内部的核心是Orchestrator编排器这是真正的大脑。Orchestrator的工作流程借鉴了ReActReasoning and Acting等框架的思想但完全用C#异步编程模型async/await和响应式扩展Rx来实现以贴合.NET的开发范式。其核心循环大致如下public class Orchestrator { private readonly ILLMService _llmService; private readonly IToolRegistry _toolRegistry; public async TaskAgentResult ExecuteAsync(AgentContext initialContext) { var context initialContext; int step 0; const int maxSteps 50; // 防止无限循环 while (step maxSteps !context.IsCompleted) { // 1. 规划与推理让LLM根据当前上下文决定下一步做什么 var reasoningResult await _llmService.ReasonAsync(context); context.AppendToHistory($思考: {reasoningResult.Thoughts}); // 2. 行动决策LLM决定调用哪个工具参数是什么 var action reasoningResult.ProposedAction; if (action.ActionType ActionType.Complete) { context.MarkAsCompleted(reasoningResult.FinalAnswer); break; } // 3. 工具执行在沙箱/安全上下文中调用注册的工具 ITool tool; if (!_toolRegistry.TryGetTool(action.ToolName, out tool)) { context.AppendToHistory($错误: 未找到工具 {action.ToolName}); continue; } try { var toolResult await tool.ExecuteAsync(action.Parameters, context); context.AppendToHistory($执行 {action.ToolName}: {toolResult.Summary}); context.UpdateState(toolResult.NewState); } catch (Exception ex) { context.AppendToHistory($工具执行失败: {ex.Message}); // 将错误信息反馈给LLM进入下一轮循环 } step; } return new AgentResult { Context context, StepsTaken step }; } }这个循环的关键在于AgentContext对象它封装了当前任务的所有状态原始目标、对话历史、当前代码库的快照、已收集的信息等。Orchestrator每次迭代都将最新的上下文喂给LLM让它基于全部历史做出下一个最合理的决策。2.2 工具系统让LLM拥有操作现实世界的能力智能体的强大与否很大程度上取决于它拥有什么“工具”。SharpClawCode的工具系统设计为完全可插拔的。所有工具都实现一个简单的ITool接口。public interface ITool { string Name { get; } string Description { get; } ToolParameterSchema ParameterSchema { get; } TaskToolResult ExecuteAsync(Dictionarystring, object parameters, AgentContext context); }一个核心的设计考量是工具的安全性。我们绝不允许LLM直接执行任意Shell命令或进行危险的文件操作。所有工具的执行都在一个受控的“沙箱”环境中。例如我们提供的“文件读写工具”会限制操作路径必须在当前工作目录或指定目录下并且会进行路径遍历攻击的检查。SharpClawCode预置了一套针对C#开发的“王牌工具集”Roslyn代码分析工具 (RoslynAnalysisTool)这是核心中的核心。它可以直接在内存中加载C#项目获取完整的语法树SyntaxTree和语义模型SemanticModel。LLM可以通过它来查询“这个类有哪些方法”“这个方法在哪里被调用”“这两个类型之间有没有继承关系” 这相当于给了AI一双能直接“看懂”C#代码的“眼睛”而不是基于文本的正则匹配。代码生成与转换工具 (CodeGenerationTool)基于Roslyn的语法工厂SyntaxFactory和格式化器Formatter可以精准地生成、插入、修改或删除代码片段。例如LLM可以指令它“在CustomerService类中添加一个名为ValidateEmailAsync的异步方法。” 工具会确保生成的代码语法正确、格式规范并自动添加到正确的位置。项目与解决方案操作工具 (ProjectManagementTool)可以读取、修改.csproj文件添加或移除NuGet包引用创建新的项目或文件甚至调整项目间的引用关系。这让智能体能够进行项目级别的重构。单元测试运行器工具 (TestRunnerTool)可以调用dotnet test或集成xUnit/nUnit/MSTest的测试运行器执行特定的测试用例或整个测试项目并捕获测试结果和代码覆盖率报告。这使得智能体可以实现“测试驱动开发”的循环写代码 - 运行测试 - 根据失败信息修复代码。Git操作工具 (GitClientTool)封装了LibGit2Sharp等库允许智能体执行基本的Git操作如git status,git diff,git add,git commit甚至创建分支和PR。这为自动化代码审查和集成铺平了道路。注意工具设计的“提示工程”。每个工具的Description和ParameterSchema至关重要它们是给LLM看的“说明书”。描述必须清晰、无歧义参数定义必须明确类型和约束。例如RoslynAnalysisTool的描述会是“分析C#代码。可以获取类型信息、查找引用、分析符号。重要所有文件路径必须是相对于解决方案根目录的路径。” 好的工具描述能极大提升LLM调用工具的准确率。2.3 模型层抽象兼容本地与云端LLMSharpClawCode并不绑定任何特定的LLM提供商。它定义了一个通用的ILLMService接口用于处理与LLM的通信。public interface ILLMService { TaskLLMResponse ReasonAsync(AgentContext context); // 请求LLM进行下一步推理 Taskstring GenerateCodeAsync(string prompt, CodeGenerationContext context); // 专用于代码生成的调用 // ... 其他可能的方法 }目前我们实现了以下几种服务OpenAI API服务 (OpenAIService)兼容GPT-4、GPT-4o、GPT-3.5-Turbo等模型。这是最直接的方式适合快速原型验证和网络环境好的场景。Ollama本地服务 (OllamaService)通过HTTP调用本地运行的Ollama支持CodeLlama、DeepSeek-Coder、Qwen-Coder等开源代码模型。这是保证数据隐私和降低延迟的关键方案。Azure OpenAI服务 (AzureOpenAIService)为企业级部署提供Azure集成支持虚拟网络、私有端点等安全特性。这种设计使得切换模型就像更改配置文件一样简单。你可以在开发时用快速的GPT-3.5-Turbo部署时切换到更强大的GPT-4或者在完全离线的环境中使用本地的CodeLlama 34B模型。3. 实战演练用SharpClawCode自动化一个常见的重构任务理论说了这么多我们来点实际的。假设我们有一个常见的任务“将项目中所有同步的数据库查询方法例如GetUserById改为异步版本GetUserByIdAsync并更新所有调用处。”这是一个典型的、繁琐但规则相对明确的重构任务非常适合交给SharpClawCode。3.1 任务拆解与智能体规划我们不会直接对智能体说上面那句模糊的话。我们需要将它分解成一个结构化的“任务描述”AgentGoal并配置好初始上下文。var goal new AgentGoal { Id refactor-sync-to-async, Description 重构数据访问层将所有同步的数据库查询方法改为异步模式。, SuccessCriteria new Liststring { 1. 所有以Get Find Query开头且返回T或ListT的同步公共方法应被改为返回TaskT或TaskListT的异步方法并添加Async后缀。, 2. 方法内部如果调用了DbContext.SaveChanges() DbSet.Find等EF Core同步方法需改为对应的SaveChangesAsync FindAsync等。, 3. 更新所有调用这些方法的地方使用await调用新方法。, 4. 确保调用方的上层方法也相应地改为异步传播async/await。, 5. 所有改动必须通过现有的单元测试。 }, // 指定工作目录和解决方案文件 WorkingDirectory C:\MyProject\src, SolutionPath C:\MyProject\src\MyCompany.sln }; var initialContext new AgentContext { Goal goal, // 可以预先注入一些领域知识比如“本项目使用Entity Framework Core 6.0” Knowledge 本项目使用Entity Framework Core 6.0进行数据访问。DbContext类位于Data项目下的AppDbContext.cs中。 };3.2 运行智能体并观察其“思考”过程我们将这个上下文交给AgentRuntime去执行。通过配置日志我们可以观察到智能体实际上是背后的LLM的完整思考链Chain-of-Thought[Step 1] 思考: 用户希望将同步数据库查询方法改为异步。我需要先理解项目结构。我应该使用RoslynAnalysisTool来扫描解决方案找出所有可能的数据访问层项目和类。 行动: 调用工具 RoslynAnalysisTool参数: {operation: scan_solution, target: all_projects}。 结果: 已扫描解决方案。发现主要数据访问类位于 MyCompany.Data 项目的 Repositories 文件夹下包括 UserRepository.cs, OrderRepository.cs。 [Step 2] 思考: 找到了目标文件。现在需要分析 UserRepository.cs识别出符合条件公共的、以Get/Find/Query开头、返回非Task类型的同步方法。 行动: 调用工具 RoslynAnalysisTool参数: {operation: analyze_file, filePath: MyCompany.Data/Repositories/UserRepository.cs, analysisType: method_signatures}。 结果: 在UserRepository.cs中发现以下候选方法public User GetUserById(int id), public ListUser GetActiveUsers()。 [Step 3] 思考: 确认了目标方法。现在需要修改第一个方法 GetUserById。首先我需要生成它的异步版本签名和实现。这涉及到将返回类型改为 TaskUser方法名加 Async并在方法体内将同步调用改为异步。 行动: 调用工具 CodeGenerationTool参数: {operation: refactor_method, filePath: MyCompany.Data/Repositories/UserRepository.cs, methodName: GetUserById, newSignature: public async TaskUser GetUserByIdAsync(int id), newBody: return await _dbContext.Users.FindAsync(id);}。 结果: 方法 GetUserById 已成功重构为 GetUserByIdAsync。原方法已被注释或标记为[Obsolete]。 [Step 4] 思考: 第一个方法修改成功。现在需要找到所有调用 GetUserById 的地方并将它们更新为调用 GetUserByIdAsync 并使用 await。 行动: 调用工具 RoslynAnalysisTool参数: {operation: find_references, symbolName: UserRepository.GetUserById, projectName: MyCompany.Data}。 结果: 找到15处引用分布在 MyCompany.WebApi\Controllers\UserController.cs 和 MyCompany.Services\UserService.cs 等文件中。 [Step 5] 思考: 引用很多我需要批量更新。我可以使用代码转换工具将形如 var user repo.GetUserById(id); 的语句替换为 var user await repo.GetUserByIdAsync(id);。但要注意调用方方法本身可能需要改为 async。 行动: 调用工具 CodeGenerationTool参数: {operation: replace_invocation, oldMethodName: GetUserById, newMethodName: GetUserByIdAsync, addAwait: true, files: [MyCompany.WebApi/Controllers/UserController.cs, ...]}。 结果: 已成功更新10处引用。有5处引用所在的父方法不是异步的需要进一步处理。 [Step 6] 思考: 有5个调用点所在的封装方法还是同步的。我需要将这些上层方法也改为异步。这是一个递归过程。我将逐一处理这些方法... 智能体会继续循环处理 GetActiveUsers处理其他Repository并最终运行测试验证 ... [Step N] 思考: 所有目标方法已重构调用链已更新。现在应该运行单元测试以确保没有引入回归错误。 行动: 调用工具 TestRunnerTool参数: {projectPath: C:\\MyProject\\tests\\MyCompany.Data.Tests\\MyCompany.Data.Tests.csproj}。 结果: 测试通过。所有78个测试用例均成功。 行动: 调用工具 Complete参数: {final_answer: 重构任务已完成。已成功将UserRepository和OrderRepository中的12个同步查询方法转换为异步方法并更新了共计45处调用点。所有现有单元测试均已通过。}。这个过程清晰地展示了智能体如何将一个大问题分解利用工具进行探索、分析、修改和验证最终完成任务。它并不是一次生成所有代码而是通过多轮“感知-思考-行动”的循环像一名谨慎的开发者一样逐步推进。3.3 关键细节与避坑指南在实际运行上述任务时有几个坑是必须要注意的1. 上下文长度Context Window的管理LLM的上下文是有限的比如8K、32K、128K tokens。SharpClawCode在处理大型项目时不能一次性把整个解决方案的代码都塞给LLM。我们的策略是增量式加载只在需要分析某个具体文件时才通过RoslynAnalysisTool提取该文件的摘要信息如类名、方法签名、关键注释而不是全部源代码。符号化引用当LLM询问“这个ICustomerService接口在哪里定义的”时工具返回的是它的完全限定名Fully Qualified Name和所在文件路径而不是整个接口文件内容。只有当LLM明确请求查看实现细节时才加载具体内容。历史摘要AgentContext中的对话历史会随着步骤增长。我们需要一个IHistorySummarizer组件定期将冗长的历史对话压缩成简洁的要点以节省宝贵的上下文空间。2. 工具调用的准确性与错误处理LLM可能会“幻觉”出不存在工具或参数格式错误。SharpClawCode的Orchestrator必须包含强大的验证和回退机制。结构化输出JSON Mode强制要求LLM以严格的JSON格式返回ProposedAction。我们使用System.Text.Json进行强类型反序列化任何格式错误都会立即被捕获并作为“工具调用格式错误”反馈给LLM让它重试。参数验证在工具执行前根据ToolParameterSchema对传入的参数进行类型和范围校验。例如文件路径参数必须确保在允许的目录内。优雅降级如果某个复杂工具如自动重命名调用失败可以回退到更简单、更可控的工具组合如先分析引用再逐个文件修改。3. 异步重构的“传染性”问题这是将同步方法改为异步时最经典的难题。一个底层方法的异步化会要求所有直接或间接调用它的方法都变成异步。SharpClawCode的策略是广度优先逐层向上首先识别出所有最底层的、直接操作数据库的同步方法将它们改为异步。然后利用RoslynAnalysisTool的“查找引用”功能找到所有直接调用者。对于每个调用者判断其是否已经是异步方法。如果不是则将其也重构为异步方法这本身可能又是一个工具调用。重复这个过程形成一个“重构波”直到传播到入口点如Controller的Action。SharpClawCode需要设置一个最大传播深度防止在循环依赖或复杂调用链中陷入死循环。4. 进阶应用构建自定义智能体工作流与集成SharpClawCode的威力不仅在于执行单个任务更在于可以将多个智能体编排成复杂的工作流并集成到现有的开发体系中。4.1 自定义工作流代码审查助手我们可以创建一个专精于代码审查的智能体CodeReviewAgent。它的工具集可能包括StaticAnalysisTool运行Roslynator或SonarC#等静态分析规则。StyleCopTool检查代码风格一致性。SecurityScanTool集成Security Code Scan等工具检查安全漏洞。CommentGenerationTool对复杂代码段自动生成解释性注释。然后在CI/CD流水线中配置一个钩子每当有新的Pull Request时就自动启动CodeReviewAgent。它会拉取代码差异运行上述工具生成一份包含问题描述、严重等级和修复建议的审查报告并自动评论到PR中。这比单纯的规则检查更智能因为它可以用自然语言解释为什么某段代码可能有问题。4.2 与IDE深度集成实时结对编程伙伴SharpClawCode可以打包成一个Visual Studio或Rider的扩展插件。在这个模式下它不再是执行一次性任务而是作为一个常驻的后台服务。上下文感知插件可以实时获取开发者当前打开的文档、光标位置、选中的代码块作为智能体的初始上下文。自然语言指令开发者可以在IDE中直接输入“为这个Customer类添加一个基于邮箱地址验证格式的方法”智能体通过分析当前类结构立即生成代码建议并插入。解释代码选中一段复杂的LINQ查询或并发代码问“这段代码是做什么的有没有性能问题”智能体调用分析工具后用自然语言给出清晰的解释和优化建议。这种集成将SharpClawCode从一个“任务执行器”变成了一个“实时协作的智能副驾驶”极大地提升开发者的日常效率。4.3 模型微调与领域适配要让SharpClawCode在特定领域如金融、医疗、物联网表现更好可以考虑对底层代码LLM进行微调Fine-tuning。构建领域代码数据集收集你所在公司的核心业务模块代码、领域实体定义、常用的设计模式和工具库代码。微调模型使用这些数据对开源的CodeLlama或DeepSeek-Coder模型进行轻量级微调。微调后的模型会对你的代码规范、命名习惯、业务术语有更深的理解。更新SharpClawCode配置将ILLMService指向你微调后的模型端点。你会发现智能体生成的代码更符合内部规范对业务逻辑的理解也更准确。5. 性能、安全与部署考量将这样一个智能系统引入开发流程我们必须严肃考虑其运行时开销和安全性。性能优化Roslyn编译复用RoslynAnalysisTool在加载和分析项目时会创建编译Compilation对象。这个操作比较重。SharpClawCode内部实现了一个轻量级的编译缓存池对于同一个项目文件的多次分析请求会复用编译结果显著提升响应速度。工具调用并行化某些工具调用是独立的可以并行执行。例如在扫描整个解决方案寻找某种模式时可以并行分析多个项目。Orchestrator可以利用TPLTask Parallel Library来管理并行任务但需要小心处理共享上下文的状态更新。LLM响应流式处理对于需要生成较长代码或解释的任务可以让LLM服务支持流式响应Server-Sent Events让用户或调用方能实时看到生成过程提升体验。安全沙箱这是重中之重。SharpClawCode默认运行在一个严格的沙箱环境中。文件系统隔离智能体的工作目录被严格限制在一个临时或指定的沙箱目录内。所有工具的文件操作路径都会被规范化并检查是否试图逃逸../等。网络访问控制默认禁止所有出站网络连接除非是明确配置的、用于调用LLM API的端点。这防止了智能体被恶意提示词诱导去访问外部危险资源。进程执行限制没有提供直接执行Shell命令的通用工具。如果确实需要比如运行dotnet build会通过一个高度受限的ProcessTool来执行该工具只允许预定义的白名单命令和参数。提示词注入防护对从外部如用户输入、文件内容获取并即将拼接成LLM提示词Prompt的文本进行基本的清洗和转义防止攻击者通过精心构造的输入劫持智能体的目标。部署模式桌面模式作为开发者机器上的一个本地服务或IDE插件运行。数据完全本地模型使用Ollama本地部署隐私性最好。服务器模式部署在内网服务器上作为一个RESTful API服务。开发者的IDE插件或CI/CD脚本通过HTTP调用它。这种模式便于集中管理模型、工具和权限。混合模式轻量级分析工具在客户端执行重度的代码生成和模型推理调用服务器端API。平衡了响应速度和计算资源。SharpClawCode代表了一种思路的转变AI编程助手不应该只是一个在编辑器中弹出建议的“黑盒”而应该是一个可以用我们熟悉的语言C#进行编程、扩展和深度集成的“开源组件”。它把大语言模型的推理能力与.NET生态强大的工具链Roslyn、EF Core、ASP.NET Core等和成熟的工程实践结合了起来为构建下一代智能化的软件开发平台提供了一个坚实的C#原生基础。它的价值不在于替代开发者而在于放大开发者的能力将我们从重复、繁琐、模式化的编码劳动中解放出来去专注于更核心的架构设计和业务创新。