基于.NET原生AI编码智能体运行时SharpClawCode的设计与实践-平芜编程栈

1. 项目概述：为什么我们需要一个原生的AI编码智能体运行时？

在.NET生态里摸爬滚打了十几年，从WinForm到WPF，再到ASP.NET Core，我见证了C#从一门企业级后端语言，逐渐渗透到桌面、移动、云原生乃至AI的边缘。最近一年，AI编程助手（或者说“智能体”）的火爆程度有目共睹，GitHub Copilot、Cursor、Claude Code几乎成了我们这行人的标配。但不知道你有没有和我一样的痛点：这些工具要么是云端服务，代码要“出国”兜一圈，安全和延迟心里没底；要么是本地大模型，但集成到开发流程里总感觉隔了一层，启动慢、资源占用高，写个简单的业务逻辑还要等模型“思考”几秒钟。

这就是我动手搞SharpClawCode的初衷。这个名字有点中二，“Sharp”代表C#，“Claw”是爪子，寓意它能像爪子一样牢牢抓住你的代码上下文，进行快速、精准的“抓取”和“操作”。本质上，它是一个完全用C#/.NET原生编写的、轻量级的AI编码智能体运行时。它不是另一个大模型，而是一个“大脑”与“手”之间的高效协调器。你可以把它想象成你本地IDE里的一个超级插件引擎，它负责加载AI模型（无论是云端API还是本地轻量模型）、理解你的自然语言指令、分析当前项目上下文、生成并安全地执行代码修改——所有这一切，都在你的.NET进程内完成，没有额外的Python环境、没有复杂的服务部署，就是纯粹的C#。

为什么非得是原生？我经历过太多混合栈的痛。用Python写AI服务，用gRPC或者HTTP和C#通信，调试起来像在解谜，内存泄漏都找不到源头。SharpClawCode的目标是“零胶水代码”，让AI能力成为你C#工具箱里一个顺手的内置扳手，而不是需要额外组装的外挂设备。这对于开发C#上位机软件、工业控制系统、或者对网络隔离有严格要求的企业内部工具来说，意义非凡。

2. 核心架构设计：如何让C#“理解”并“执行”AI的意图？

一个智能体运行时，核心要解决三个问题：感知（Perception）、思考（Reasoning）、执行（Action）。SharpClawCode的架构就是围绕这三点展开的。

2.1 感知层：项目上下文的动态捕捉与编码

AI不是神仙，它需要知道“我在哪”、“我在干什么”。SharpClawCode的感知层负责将你的整个解决方案（Solution）或项目（Project）的上下文，以一种模型能理解的方式“喂”给它。

核心组件：Roslyn工作区（Workspace）动态分析器我直接利用了.NET编译器平台（Roslyn）的Microsoft.CodeAnalysis库。这是C#编译器的官方API，能让我们以编程方式访问代码的语法树（Syntax Tree）和语义模型（Semantic Model）。SharpClawCode启动时，会为当前项目创建一个AdhocWorkspace，并持续监听文件变化。

// 示例：创建并加载一个项目到工作区 using Microsoft.CodeAnalysis; using Microsoft.CodeAnalysis.MSBuild; var workspace = MSBuildWorkspace.Create(); var project = await workspace.OpenProjectAsync(@"YourProject.csproj"); var compilation = await project.GetCompilationAsync(); // 获取所有语法树 foreach (var syntaxTree in compilation.SyntaxTrees) { // 分析当前文件的结构、类、方法、引用等 var root = await syntaxTree.GetRootAsync(); var model = compilation.GetSemanticModel(syntaxTree); // ... 将分析结果转换为上下文信息 }

但这还不够。我们还需要理解代码的“活”状态——比如当前光标位置、断点信息、最近的编译错误、单元测试结果、甚至NuGet包的依赖关系。SharpClawCode通过实现ITextBuffer事件监听和集成MSBuild诊断管道来收集这些动态信息。最终，所有这些上下文会被序列化成一种结构化的提示词（Prompt），比如：

[项目上下文] - 当前文件：OrderService.cs - 光标所在方法：ProcessPayment(Order order) - 最近错误：CS1061 ‘string’ 不包含 ‘ToCurrency’ 的定义 - 相关文件：CurrencyHelper.cs, ILogger.cs - 项目类型：.NET 6 Web API - 测试状态：PaymentTests.ProcessPayment_ShouldSucceed 通过

这个提示词的构建策略是关键。你不能把整个项目几万行代码都塞进去。SharpClawCode实现了一套启发式算法：优先包含当前编辑的文件、最近修改的文件、编译错误涉及的文件，以及通过语义分析找到的强关联文件（比如同一个命名空间下，或有继承/接口实现关系的文件）。

实操心得：上下文窗口的权衡大模型的上下文窗口（如128K）很诱人，但把所有代码都扔进去会导致响应速度变慢，且无关信息会干扰模型判断。我的经验是，对于代码补全或单文件重构，限制在5-10个相关文件内；对于跨文件的重构或功能添加，可以扩展到20-30个文件，但需要先让模型输出一个“分析计划”，再分步加载所需上下文。SharpClawCode内置了这种“分步加载”策略。

2.2 思考层：轻量级推理引擎与工具调用（Tool Calling）

这是智能体的“大脑”。SharpClawCode设计了一个插件化的模型提供商（IModelProvider）接口。目前主要支持两类：

云端API提供商：如OpenAI GPT-4、Claude 3、DeepSeek等。通过标准的HttpClient调用，但所有通信都经过本地代理配置和安全检查。
本地模型提供商：这是重点。我们集成了通过ML.NET或ONNX Runtime加载的轻量级代码模型。例如，基于CodeGen或StarCoder系列微调的小模型（2B-7B参数），它们专门针对代码生成任务优化，在消费级GPU甚至CPU上都能获得可接受的推理速度。

推理引擎的工作流程：

接收指令：用户输入“为ProcessPayment方法添加货币转换逻辑，调用CurrencyHelper.Convert方法”。
组装提示：感知层提供的项目上下文 + 用户指令 + 系统指令（如“你是一个C#专家，只输出代码差异...”）。
调用模型：将提示发送给配置的模型提供商，获取模型回复。
解析与规划：模型回复可能是一个直接的代码块，也可能是一个包含工具调用的JSON。SharpClawCode内置了一个简单的JSON解析器，来识别模型是否在请求执行某个操作（如“读取文件X的第Y行”、“运行测试Z”）。

工具调用（Tool Calling）的实现：这是让智能体从“空谈”到“实干”的关键。SharpClawCode预定义了一系列“工具”，每个工具都是一个C#类和方法，标注了特定的属性，并提供了自然语言描述。

[Tool("file_reader", "读取指定文件的全部内容")] public class FileSystemTools { [ToolMethod] public async Task<string> ReadFileAsync([ToolArgument("文件的完整路径")] string filePath) { return await File.ReadAllTextAsync(filePath); } } [Tool("test_runner", "运行指定的单元测试方法")] public class TestTools { [ToolMethod] public async Task<TestResult> RunTestAsync([ToolArgument("测试类的完全限定名")] string className, [ToolArgument("测试方法名")] string methodName) { // 使用dotnet test命令或VSTest API运行特定测试 // ... } }

当模型在思考过程中认为需要更多信息时，它会在回复中输出一个结构化的工具调用请求。SharpClawCode的运行时识别到这个请求，动态调用对应的C#方法，将执行结果（如文件内容、测试结果）再次组装进上下文，送回给模型进行下一步推理。这就形成了一个“思考-行动-观察”的循环。

2.3 执行层：安全、可撤销的代码操作

这是最敏感也最重要的一层。让AI直接修改你的生产代码？想想都头皮发麻。SharpClawCode的执行核心原则是：一切操作皆可预览、可撤销、可审计。

核心机制：代码差异（Diff）应用与事务模型生成的代码修改建议，不会直接覆盖原文件。SharpClawCode要求模型以“统一差异格式（Unified Diff）”输出变更。就像Git提交时看到的@@ -10,5 +10,10 @@那样。

// SharpClawCode内部处理Diff的简化流程 public class CodeApplicator { public async Task<ApplyResult> ApplyDiffAsync(string originalFilePath, string unifiedDiff) { // 1. 解析Diff，计算出要添加/删除的行 var parsedDiff = DiffParser.Parse(unifiedDiff); // 2. 备份原文件 var backupPath = CreateBackup(originalFilePath); // 3. 在内存中应用Diff，生成新内容 var newContent = ApplyDiffToContent(File.ReadAllText(originalFilePath), parsedDiff); // 4. 触发“预览”事件，让IDE或UI显示变更 OnPreviewGenerated(new CodePreview { FilePath = originalFilePath, OldContent = ..., NewContent = newContent }); // 5. 等待用户确认（或配置为自动应用） if (await WaitForUserConfirmationAsync()) { File.WriteAllText(originalFilePath, newContent); LogTransaction(originalFilePath, backupPath, unifiedDiff); // 记录审计日志 return ApplyResult.Success; } else { RestoreFromBackup(backupPath); // 用户取消，回滚 return ApplyResult.Cancelled; } } }

对于更复杂的操作，比如重命名一个被多处引用的类，SharpClawCode会将其分解为多个Diff步骤，并包装在一个“重构事务”中。要么全部成功，要么利用备份全部回滚。

避坑指南：模型输出的Diff可能“不干净”早期测试中，模型经常输出格式错误或上下文行号不匹配的Diff，直接应用会导致文件损坏。我们的解决方案是引入一个“Diff验证和修复”阶段。利用Roslyn在应用前先尝试编译修改后的内存代码，如果编译失败，则尝试自动调整行号或通过启发式算法匹配最近的正确代码块。同时，我们强制模型在输出Diff时必须包含至少3行未改变的上下文行，以提高匹配成功率。

3. 实战集成：将SharpClawCode嵌入你的开发流

架构讲完了，我们来点实际的。SharpClawCode被设计成一个类库（NuGet包），你可以用几种方式把它用起来。

3.1 方式一：作为Visual Studio或VS Code扩展

这是最无缝的体验。我们提供了一个扩展项目模板，开发者可以快速创建一个VSIX包或VS Code插件。扩展的核心是注册一个自定义的ICompletionSource和ICommandHandler。

// 在VS扩展中注册一个命令，触发智能体 [Command(PackageGuids.SharpClawCodePackage, PackageIds.InvokeSharpClawCommand)] internal sealed class InvokeSharpClawCommand : BaseCommand<InvokeSharpClawCommand> { protected override async Task ExecuteAsync(OleMenuCmdEventArgs e) { var docView = await VS.Documents.GetActiveDocumentViewAsync(); var selection = docView.TextView.Selection; var userPrompt = await GetUserInputAsync(); // 弹窗获取用户指令 // 初始化SharpClawCode运行时 var runtime = new SharpClawRuntime(); runtime.InitializeWithCurrentSolution(); // 执行指令 var result = await runtime.ExecuteInstructionAsync(userPrompt); // 将结果（可能是Diff）展示在预览窗格 await ShowPreviewWindowAsync(result); } }

用户可以在代码编辑器里选中一段代码，右键点击“SharpClaw: 优化此方法”或“解释这段代码”，也可以通过一个快捷键调出指令输入框，输入复杂的任务，如“为所有Repository类添加异步版本的方法”。

3.2 方式二：作为独立控制台应用或后台服务

对于自动化场景，比如每日代码审查、自动生成单元测试、批量代码迁移（例如从.NET Framework升级到.NET Core），你可以编写一个控制台程序。

class Program { static async Task Main(string[] args) { var solutionPath = args[0]; var instruction = "扫描所有Controller，为没有[Authorize]属性的、以Post/Delete/Put开头的方法添加它。"; var config = new SharpClawConfig { ModelProvider = new LocalModelProvider("path/to/your/model.onnx"), MaxIterations = 5, // 最多进行5轮“思考-行动”循环 AutoApplySafeChanges = true // 对于仅添加属性的简单变更，自动应用 }; using var runtime = new SharpClawRuntime(config); await runtime.LoadSolutionAsync(solutionPath); var report = await runtime.ExecuteInstructionAsync(instruction); Console.WriteLine($"任务完成。修改了{report.ModifiedFiles.Count}个文件。"); Console.WriteLine("变更日志："); foreach (var log in report.ChangeLogs) { Console.WriteLine($"- {log}"); } } }

这种模式非常适合集成到CI/CD管道中。你可以设置一个夜间任务，让SharpClawCode自动扫描新提交的代码，检查是否遵循了新的代码规范，并自动创建修复提交（Pull Request）。

3.3 方式三：在Blazor或WPF应用中作为智能辅助组件

想象一下，你正在开发一个内部低代码平台或数据配置工具。用户可以在UI上描述他们想要的业务逻辑，比如“当订单金额超过1000时，需要经理审批”。你可以用SharpClawCode在后台将这段描述转换成一段可执行的C#校验规则代码，并动态编译、加载到你的应用中。

// 在Blazor服务端 public class CodeGenerationService { private SharpClawRuntime _runtime; public CodeGenerationService() { _runtime = new SharpClawRuntime(); // 加载一个预定义的规则模板项目 _runtime.LoadProjectAsync("Templates/RuleTemplate.csproj"); } public async Task<string> GenerateBusinessRuleAsync(string naturalLanguageRule) { var instruction = $"基于以下业务规则，在RuleTemplate项目的`BusinessRule.cs`文件的`Execute`方法中实现逻辑。只输出完整的`Execute`方法体。规则：{naturalLanguageRule}"; var result = await _runtime.ExecuteInstructionAsync(instruction); // 从结果中提取生成的代码 var generatedCode = ExtractCodeFromResult(result); // 动态编译生成代码（使用CSharpScript或Roslyn） var compiledRule = CompileAndLoadRule(generatedCode); return compiledRule; } }

4. 性能优化与资源管理：在有限资源下流畅运行

让一个AI运行时在开发者的本地机器上保持响应，是个不小的挑战。尤其是集成本地模型时，内存和CPU占用必须可控。

4.1 模型加载与推理优化

延迟加载与模型缓存：SharpClawCode不会在启动时就加载巨大的模型文件。只有当第一次需要执行推理任务时，才会初始化模型提供商。对于本地模型，我们利用ONNX Runtime的会话（Session）池，将加载好的模型会话缓存起来，供后续请求复用，避免重复加载的开销。

量化与硬件加速：我们强烈推荐使用经过量化的模型格式（如INT8）。一个7B参数的模型，经过量化后，模型文件可能从14GB缩小到4GB以下，并且推理速度显著提升。SharpClawCode的本地提供商会自动检测系统是否有可用的GPU（通过CUDA或DirectML），并优先将模型推理任务卸载到GPU上。对于纯CPU环境，我们会启用ONNX Runtime的CPU优化执行提供程序（Execution Provider），并利用多线程进行批处理。

// 配置本地模型提供商的示例 var localConfig = new LocalModelProviderConfig { ModelPath = @".\Models\codegen-2b-fp16.onnx", ExecutionProvider = ExecutionProvider.AutoDetect, // 自动检测CUDA/DirectML/CPU EnableMemoryPattern = true, // 启用内存模式优化，减少碎片 IntraOpNumThreads = Environment.ProcessorCount / 2 // 设置计算线程数 };

4.2 工作区与上下文管理的内存优化

Roslyn工作区如果加载一个大型解决方案（几十个项目），内存占用可能达到数百MB甚至上GB。SharpClawCode采用惰性加载和按需释放策略。

项目级惰性加载：初始化时只加载解决方案文件（.sln）和项目引用关系。具体的语法树和编译信息，等到某个文件被上下文分析需要时，才加载到内存中。
上下文缓存与过期：为每个文件的分析结果（如类结构、方法签名）设置一个带时间戳的缓存。当文件被IDE修改并保存后，对应的缓存项会标记为脏数据，下次需要时重新分析。
主动释放：当智能体任务完成后，如果一段时间内没有新任务，运行时会主动释放当前不活跃的项目工作区内存，只保留最基本的元信息。

4.3 异步与响应式设计

所有耗时的操作，包括模型推理、文件读取、代码分析，都被设计为完全的异步（async/await）操作，确保UI线程不会被阻塞。SharpClawCode的核心API返回的都是Task或IObservable，方便集成到各种异步前端框架中。

例如，在执行一个长时间的重构任务时，运行时可以通过IProgress<T>接口实时报告当前进度（“正在分析项目A...”、“正在生成Diff...”、“正在应用更改到文件X...”），让用户界面能够更新进度条或状态信息。

5. 安全与可靠性保障：让AI成为可信赖的搭档

让AI修改代码，安全是头等大事。SharpClawCode从设计之初就贯彻了“最小权限”和“防御性编程”原则。

5.1 操作沙箱与权限控制

SharpClawCode定义了一个明确的“操作边界”。智能体只能在其加载的解决方案目录及其子目录下进行文件读写操作。任何尝试访问此边界之外路径的请求（无论是来自模型输出还是工具调用），都会被运行时直接拒绝并记录安全警告。

工具调用也受到严格管控。像“执行Shell命令”、“删除文件”这类高危工具默认是禁用的。你需要在配置文件中显式地启用它们，并可以指定允许执行的命令白名单或允许删除的文件模式。

// SharpClawCode配置文件示例 (appsettings.json) { "SharpClaw": { "Security": { "AllowedFileSystemRoots": [ "C:\\MyProjects\\CurrentSolution" ], "EnableShellTool": false, "AllowedShellCommands": [ "git status", "dotnet build" ], "EnableNetworkTool": false, "MaxAutoApplyChangeSize": 50 // 自动应用的最大Diff行数，超过需人工确认 } } }

5.2 代码变更的审查与回滚机制

如前所述，所有变更都以Diff形式呈现，并必须经过预览。SharpClawCode集成了一个简单的代码变更预览器（可作为独立窗口或嵌入IDE），用绿色和红色高亮显示即将进行的增删。

变更集（Changeset）与版本快照：每次应用一组Diff前，运行时都会为涉及的文件创建一个Git风格的版本快照（实际上就是拷贝到临时目录）。这个快照与本次任务的所有Diff、使用的提示词、模型响应一起，被保存为一个“变更集”对象。如果应用后发现问题，用户可以通过IDE菜单或命令行，选择回滚到任何一个历史变更集。

编译与测试的自动门禁：在配置了自动应用（Auto-Apply）的场景下，SharpClawCode会在真正写文件之前，在内存中尝试编译修改后的整个项目。如果编译失败，变更会被自动拒绝。更进一步，如果项目中有测试项目，还可以配置为在应用变更后自动运行相关的单元测试，只有测试通过，变更才被视为成功。

5.3 审计日志与可解释性

AI的决策过程有时像个黑盒。SharpClawCode致力于提高可解释性。每一次智能体交互的完整记录都会被结构化地记录下来：

输入：完整的提示词（包含项目上下文和用户指令）。
模型交互：每一轮模型请求和响应的原始内容。
工具调用：调用了哪个工具，输入参数是什么，输出结果是什么。
决策：最终生成的Diff是什么，为什么生成这个Diff（可以从模型响应中提取理由）。
结果：变更是否被应用，编译和测试结果如何。

这些日志可以输出到文件、数据库或像Seq这样的日志服务器。当一段AI生成的代码引入了一个Bug时，你可以通过审计日志追溯当时AI“看到”的上下文和“思考”的过程，这对于调试和优化提示词工程至关重要。

6. 进阶玩法与生态展望

一个运行时成功与否，很大程度上取决于它的扩展性。SharpClawCode被设计成高度模块化的。

6.1 自定义工具与技能扩展

除了内置的文件读写、测试运行工具，你可以轻松地为你自己的领域添加专用工具。比如，如果你在开发物联网应用，可以创建一个“设备模拟器工具”，让AI智能体在编写设备控制代码时，能先启动一个模拟器测试一下通信协议。

// 自定义工具示例：数据库架构查看器 [Tool("db_schema", "获取指定数据库表的结构信息")] public class DatabaseTools { private readonly IDbConnectionFactory _connectionFactory; public DatabaseTools(IDbConnectionFactory factory) => _connectionFactory = factory; [ToolMethod] public async Task<string> GetTableSchemaAsync([ToolArgument("表名")] string tableName) { using var conn = await _connectionFactory.CreateConnectionAsync(); // 查询系统表或INFORMATION_SCHEMA获取表结构 var schema = await conn.QueryAsync<ColumnInfo>(@" SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = @tableName", new { tableName }); return JsonSerializer.Serialize(schema); } } // 注册自定义工具到运行时 runtime.RegisterTool(new DatabaseTools(myConnectionFactory));

现在，你可以对智能体说：“请为Products表生成一个对应的C#实体类。”智能体会先调用db_schema工具获取表结构，然后根据结构生成格式正确的Product类代码。

6.2 提示词模板与场景化工作流

不同的开发任务需要不同的提示词策略。SharpClawCode支持提示词模板。你可以创建针对“代码重构”、“Bug修复”、“单元测试生成”、“代码审查”等不同场景的模板。

# 模板：code_review.yaml name: CodeReview system_prompt: > 你是一个经验丰富的C#首席架构师。你的任务是对给定的代码片段进行严格的代码审查。 请专注于：1.性能问题（如重复查询、非托管资源未释放）。2.潜在的空引用异常。3.不符合团队编码规范的地方（如命名、注释）。4.安全漏洞（如SQL注入风险）。 请以列表形式指出问题，并为每个问题提供具体的修改建议代码片段。 context_include: - current_file - related_files: [".cs", ".cshtml"] - compilation_errors output_format: markdown_list_with_code_suggestions

在IDE中，你可以为选中的代码快速应用这个模板，获得一份即时的、上下文相关的代码审查报告。

6.3 与现有AI生态的融合

SharpClawCode并不想取代GitHub Copilot或Cursor。相反，它可以与它们协同工作。例如，你可以配置SharpClawCode使用OpenAI的API作为模型提供商，这样它就拥有了GPT-4的强大推理能力。同时，Copilot负责行内代码补全，而SharpClawCode则处理更宏观的、需要多步推理和工具调用的复杂任务（比如“将这个同步方法改为异步，并更新所有调用者”）。

未来，我们计划让SharpClawCode能够读取和分析Copilot或Cursor的编辑历史，从中学习开发者的个人编码风格和项目特定模式，从而生成更个性化、更贴合项目上下文的代码。

7. 常见问题与故障排除实录

在实际使用和内部测试中，我们踩过不少坑。这里记录一些典型问题和解决方法，希望能帮你绕开这些弯路。

7.1 模型响应慢或无响应

问题现象：执行一个简单指令，等待几十秒都没有结果，或者直接超时。
排查步骤：
1. 检查网络（云端模型）：首先确认你的网络连接正常，并且能访问对应的API端点（如api.openai.com）。如果是企业环境，检查代理设置。SharpClawCode的配置中有一个HttpClientFactory选项，可以配置自定义的HttpClientHandler来处理代理。
2. 检查模型加载（本地模型）：查看日志文件中是否有模型加载错误。确保模型文件路径正确，并且有读取权限。对于ONNX模型，确认安装的ONNX Runtime版本与模型兼容（例如，某些量化模型需要特定版本的ORT）。
3. 检查资源占用：打开任务管理器，查看CPU、内存和GPU（如果使用）的占用率。本地模型推理可能非常消耗资源。尝试在配置中降低MaxTokens（生成的最大令牌数）或启用StreamingResponse（流式响应）来尽早获取部分结果。
4. 简化上下文：过大的项目上下文是导致响应慢的主要原因。尝试在指令中明确指定范围，或者修改配置，减少ContextIncludedFiles的数量。
一个具体案例：有用户反馈，在分析一个超过50个项目的解决方案时，智能体卡住。原因是默认的上下文收集策略试图分析所有项目的依赖。我们在配置中增加了ContextScanDepth选项，将其设为CurrentProject后，速度恢复正常。

7.2 生成的代码不正确或无法编译

问题现象：AI生成的代码看起来合理，但存在语法错误、类型不匹配，或者引入了不存在的API引用。
排查与解决：
1. 强化系统提示词：在系统提示词中明确强调“你必须输出能够直接通过C#编译的、语法正确的代码”。可以加入项目特定的约束，如“本项目使用.NET 6，请不要使用System.Web命名空间下的已过时API”。
2. 启用编译前校验：务必开启SharpClawCode的ValidateCompilationBeforeApply配置项。这会在内存中尝试编译生成的代码，捕获大部分语法和类型错误，并在预览中高亮显示。
3. 提供更精确的上下文：很多时候模型“胡编”API是因为它没“看到”正确的引用。确保你的项目文件（.csproj）被正确加载，并且感知层能够将项目中实际引用的NuGet包和程序集信息包含在上下文中。你可以手动在指令中补充：“本项目引用了Newtonsoft.Json版本13.0.1和Dapper版本2.0.123。”
4. 迭代式修正：不要期望一次生成完美的代码。利用SharpClawCode的交互特性。当生成的代码有误时，不要直接修改，而是对智能体给出新的指令：“上一段生成的代码中，CalculateDiscount方法引用了不存在的Customer.PreferredLevel属性。请查看Customer类的实际定义，并修正该方法。”
我的经验：对于复杂的代码生成任务，我习惯采用“分步指导”策略。先让智能体生成一个接口或类的大纲，审查无误后，再让它填充具体的方法实现。这样更容易控制生成质量。

7.3 工具调用失败或产生意外结果

问题现象：模型请求读取一个文件，但工具调用返回“文件不存在”；或者运行测试的工具超时。
排查步骤：
1. 检查工具参数：查看审计日志中工具调用的详细记录。模型给出的文件路径是否是相对路径？SharpClawCode会将其解析为相对于解决方案根目录的路径。有时模型会生成类似“../Models/Product.cs”的路径，需要确保这个路径在允许的根目录内。
2. 检查工具权限：确认该工具在安全配置中已被启用。例如，shell_tool默认是关闭的。
3. 检查工具执行环境：对于test_runner工具，它可能依赖于项目是否已经成功构建。如果项目编译失败，测试自然无法运行。在调用此类工具前，可以先用指令让智能体尝试修复编译错误。
4. 处理超时：工具调用（特别是执行外部命令）可能有超时设置。如果任务长时间挂起，SharpClawCode会抛出TaskCanceledException。你需要根据日志判断是命令本身执行慢，还是出现了死锁。对于已知耗时的操作（如完整构建），可以配置更长的ToolExecutionTimeout。
设计建议：为你自定义的工具编写健壮的异常处理和日志。工具方法的返回值应该包含成功/失败状态和明确的错误信息，这些信息会被传回给模型，帮助它理解哪里出错了，并调整后续策略。

7.4 内存使用量持续增长（疑似内存泄漏）

问题现象：长时间运行SharpClawCode，或连续执行多个复杂任务后，进程内存占用不断上升。
可能原因与解决：
1. Roslyn工作区未释放：这是最常见的原因。确保在完成一个解决方案的分析后，如果不再需要，调用runtime.UnloadSolution()或直接Dispose掉运行时实例。对于长期运行的服务，考虑为每个任务创建独立的运行时实例，任务完成后销毁。
2. 模型会话缓存：本地模型提供商缓存了ONNX Runtime会话。如果加载了多个不同模型，缓存会增长。可以通过配置ModelSessionCacheSize来限制缓存数量，采用LRU（最近最少使用）策略进行淘汰。
3. 大对象堆（LOH）碎片：频繁处理大型代码字符串和Diff可能会在LOH上产生碎片。确保使用StringBuilder来拼接大型字符串，并关注.NET的垃圾回收性能计数器。在.NET Core 3.1+中，可以启用GCSettings.LargeObjectHeapCompactionMode在必要时压缩LOH，但这会影响性能，需谨慎使用。
4. 事件订阅未取消：如果扩展了SharpClawCode，监听了文件变化等事件，务必在适当的时候取消订阅，避免静态事件导致对象无法被回收。