.NET AI 进阶实战基于类的技能开发 - 打造可治理的 Agent 能力模块导语如果说 Inline Skill 解决了“能不能用”File-based Skill 解决了“能不能沉淀”那么今天要聊的 Class-based Skill解决的就是“能不能在工程中长期治理”的问题。它不是另一种炫技的写法而是面向生产环境、面向复杂业务系统的一套类型驱动的解决方案。一、回顾从“接入”到“资产”的演进我们梳理了 Agent Skill 的两种主要形态Inline Skill直接在对话上下文中拼凑 Prompt 和代码。定位先把能力接进来。File-based Skill将 Skill 标准化为目录文件SKILL.md 资源。定位把能力沉淀为可分发、可复用的资产。File-based Skill 已经很优雅了它让 Skill 变成了独立的文件包。但当我们把视角从“个人开发者”切换到“大型业务系统团队”时新的诉求出现了这个物流换算的 Skill 马上要接入订单中心了能不能写单元测试业务规则变了我要改系数能不能让 IDE 帮我检查所有引用点这个 Skill 需要调用内部 API 和日志组件怎么优雅地注入 HttpClient 和 ILogger这时候Class-based Skill登场了。它的载体不再是目录里的 Markdown 文件而是一个强类型的 C# 类。二、初见把 Skill 写成一个 C# 类是什么体验在 Microsoft.Extensions.AI 体系中AgentClassSkillT提供了一种新的声明方式。我们来看一个物流单位换算的完整示例csharp#pragmawarning disable MAAI001usingSystem.ComponentModel;usingSystem.Text.Json;internalsealedclassUnitConverterClassSkill:AgentClassSkillUnitConverterClassSkill{// 1. 元数据清晰、编译期可校验publicoverrideAgentSkillFrontmatterFrontmatter{get;}new(unit-converter,Convert between common logistics units.);// 2. 指令与逻辑代码同文件维护成本低protectedoverridestringInstructions 当用户询问距离或重量换算时1.先读取 conversion-table2.再调用 convert3.回复中包含原始值、系数和结果;// 3. 资源通过 Attribute 标记强类型字符串[AgentSkillResource(conversion-table)][Description(距离与重量换算系数表)]publicstringConversionTable miles-kilometers1.60934kilograms-pounds2.20462;// 4. 脚本/动作纯 C# 方法享受重构和测试便利[AgentSkillScript(convert)][Description(按 value × factor 执行换算)]privatestaticstringConvert(doublevalue,doublefactor){returnJsonSerializer.Serialize(new{value,factor,resultMath.Round(value*factor,4)});}}这种写法的本质变化是什么边界收敛将Frontmatter描述信息、Instructions指令集、Resource资源和Script动作脚本全部封装在一个类中实现功能聚合。类型安全采用double类型作为方法参数避免AI猜测字符串含义。当参数类型不匹配时编译器会立即报错确保类型安全性。三、原理拆解它是如何跑进 Agent 大脑的虽然它采用类形式封装但底层实现依然基于 Agent Context 的挂载机制。框架会通过 Attribute 扫描自动识别类成员并将其转换为模型可识别的 Function Calling Schema 和 Resource 上下文。集成过程非常简单只需将其作为 AIContextProvider 挂载varclassSkillnewUnitConverterClassSkill();varprovidernewAgentSkillsProvider(classSkill);varagentOptionsnewChatClientAgentOptions{NameLogisticsAgent,AIContextProviders[provider]};这种设计保持了协议的一致性Class-based Skill 并非创建新协议而是通过工程化手段自动生成标准协议。模型接收到的仍然是标准 Tool 描述而开发者维护的则是可调试、可重构的 C# 代码文件。相关NetAI智能体开源框架NetCoreKevin框架下的kevin.AI.AgentFramework模块基于.NET构建的企业级SaaSAI智能体应用架构采用前后端分离设计具备以下核心特性AI智能体框架RAG检索增强AI知识库AI智能体技能集成多级缓存机制SignalR实时通信等等…项目地址githubhttps://github.com/junkai-li/NetCoreKevinGitee: https://gitee.com/netkevin-li/NetCoreKevin四、为什么它更适合工程化这正是 Class-based Skill 的核心价值所在。当 Skill 采用标准 C# 类实现时开发者将自动获得诸多 File-based 方案难以提供的优势✅ 编译时类型检查✅ IDE 智能重构✅ 便捷的单元测试✅ 无缝的依赖注入✅ 轻松集成日志、安全等治理组件换言之Class-based Skill 的真正优势不在于分发而在于治理。它特别适合那些已趋于稳定但需要长期维护和持续演进的核心业务能力。从定位角度区分File-based Skill 侧重能力的外部化共享Class-based Skill 强调系统的内部治理前者注重可移植性后者专注可维护性。五、结语从 Inline 到 File-based 架构我们实现了 Skill 的结构化与资产化管理从 File-based 到 Class-based 架构我们进一步解决了 Skill 的工程化与治理问题。AgentClassSkill 的推出展现了 .NET 社区在 AI 应用开发领域的务实创新不仅要让 AI 生成代码更要确保 AI 调用的代码具备健壮性、可维护性和可扩展性。当您的 Skill 趋于稳定并准备作为核心功能长期使用时建议将其重构为 Class-based Skill。届时您会发现它已不再是简单的 Prompt 文件而是业务系统中一个可靠的核心模块真正成为系统的一等公民。