大家好，我是Edison。

最近我一直在跟着圣杰的《.NET+AI智能体开发进阶》课程学习MAF开发智能体应用，我强烈推荐你也上车跟我一起出发！

MAF 1.1.0 对 Agent Skill 的补全绝对是工程化的典范，今天我们来看看如何整合多个Skill来源实现企业级多技能控制。

1 企业级需求：多个Skill来源管控

在写Agent Skill的时候，我就在想企业级应用中应该需要一个Skill管控，维护一些中央可复用Skill推送到各个员工的Agent中，而各个员工也会自己写一些自己任务的Skill 或者 重写远程Skill来覆盖实现自己的任务。

这种多级Skill来源的控制设计已经在MAF中被考虑进来了，我们可以通过自定义AgentSkillsSource来实现，这意味着我们可以从任何地方为Agent提供Skill，包括但不限于：HTTP API、数据库、配置中心等等。

2 快速开始：整合多个来源Skill

这里我们来做一个企业HR助手，整合以下3个来源的Skill。

1. 全局技能库（假设通过Remote HTTP API来获取）：它是所有员工通用的政策和流程；

2. 本地技能库（假设通过InMemory来获取）：它是各个员工自己定制的任务技能

3. 用户角色技能（假设通过自定义Source来获取）：根据当前用户角色做动态过滤

在这个案例中，我们想要实现只有 全局通用技能 + 角色专属技能 对Agent可见，且本地的同名称技能可以覆盖远程的全局技能。

本文案例使用的模型为：Qwen3.5-35B-A3B

准备工作

在开始之前，我们创建了一个控制台应用，并安装了以下NuGet包：

<PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.1.0" />

假设我们的企业员工角色定义有三种：员工、经理 和 HR管理员

public enum EmployeeRole{    Employee,    Manager,    HRAdmin}

为了方便实现Skill的角色过滤，我们实现一个方法来判断：

public static class UserRoleHelper{    public static bool IsSkillVisibleTo(AgentSkill skill, EmployeeRole role)    {        var name = skill.Frontmatter.Name;        // 管理技能仅经理和HR可见        if (name.StartsWith("manager-") && role == EmployeeRole.Employee)             return false;        // HR管理技能仅HR可见        if (name.StartsWith("hr-admin-") && role != EmployeeRole.HRAdmin)             return false;        return true;    }}

可以看到，我们这里针对管理技能仅能经理和HR可见，而HR相关技能则仅能HR可见。

实现远程SkillSource

这里我们定义一个企业的远程SkillSource，模拟从远程API拉取统一定义的技能。在实际项目中，通常会使用HttpClient来访问一个注册中心来实现。

public sealed class SimulatedRemoteApiSkillsSource : AgentSkillsSource{    private readonly string _apiEndpoint;    public SimulatedRemoteApiSkillsSource(string apiEndpoint)    {        _apiEndpoint = apiEndpoint;    }    public override async Task<IList<AgentSkill>> GetSkillsAsync(CancellationToken cancellationToken = default)    {        Console.WriteLine($"📡 [RemoteApiSource] 从 {_apiEndpoint} 拉取技能列表...");        await Task.Delay(500, cancellationToken); // 模拟网络延迟        var entries = GetMockGlobalSkills();        var skills = new List<AgentSkill>();        foreach (var entry in entries)        {            try            {                var skill = new AgentInlineSkill(entry.Name, entry.Description, entry.Instructions);                skills.Add(skill);            }            catch (ArgumentException ex)            {                Console.WriteLine($"⚠️ [RemoteApiSource] 跳过非法技能 '{entry.Name}': {ex.Message[..Math.Min(60, ex.Message.Length)]}");            }        }        Console.WriteLine($"✅ [RemoteApiSource] 已成功加载 {skills.Count} 个远程技能");        return skills;    }    private static IList<SkillApiEntry> GetMockGlobalSkills()    {        return new List<SkillApiEntry>        {            new("expense-report",  "（全局v1）企业费用报销政策",    "全局版报销规则：..."),            new("hr-onboarding",   "（全局）新员工入职流程",         "入职材料清单：..."),            new("leave-policy",    "（全局）请假制度和申请流程",      "年假/病假/事假规则：..."),            new("manager-review",  "（全局）绩效评估指南",           "季度评估流程：..."),            new("hr-admin-audit",  "（全局）HR 审计和合规",          "合规审查清单：..."),        };    }}

这里SkillApiEntry模型的定义如下：

public sealed record SkillApiEntry(  string Name,   string Description,   string Instructions,   string[]? Tags = null);

实现远程Skills的缓存化

远程Skills具有时效性，需要定期更新来同步，因此弄一个带TTL（Time-To-Live）缓存的装饰器，它可以强制Agent客户端定期刷新远程Skills来保持同步。

public sealed class CachingSkillsSource : AgentSkillsSource{    private readonly AgentSkillsSource _innerSource;    private readonly TimeSpan _ttl;    private IList<AgentSkill>? _cache;    private DateTime _cacheExpiresAt = DateTime.MinValue;    private readonly SemaphoreSlim _lock = new(1, 1);        public CachingSkillsSource(AgentSkillsSource innerSource, TimeSpan ttl)    {        _innerSource = innerSource;        _ttl = ttl;    }        public override async Task<IList<AgentSkill>> GetSkillsAsync(CancellationToken cancellationToken = default)    {        if (_cache != null && DateTime.UtcNow < _cacheExpiresAt)        {            Console.WriteLine($"⚡ [CachingSource] 命中缓存（过期时间: {_cacheExpiresAt.ToLocalTime():HH:mm:ss}）");            return _cache;        }        await _lock.WaitAsync(cancellationToken);        try        {            // 双重检查锁（避免并发刷新）            if (_cache != null && DateTime.UtcNow < _cacheExpiresAt)                return _cache;            Console.WriteLine("🔄 [CachingSource] 缓存未命中，从内层 Source 刷新...");            _cache = await _innerSource.GetSkillsAsync(cancellationToken);            _cacheExpiresAt = DateTime.UtcNow.Add(_ttl);            Console.WriteLine($"✅ [CachingSource] 缓存已更新，{_cache.Count} 个技能，有效至 {_cacheExpiresAt.ToLocalTime():HH:mm:ss}");            return _cache;        }        finally        {            _lock.Release();        }    }        public void InvalidateCache() { _cache = null; _cacheExpiresAt = DateTime.MinValue; }    public bool IsCacheValid => _cache != null && DateTime.UtcNow < _cacheExpiresAt;}

实现本地Skills

这里我们定义一些本地Skills，通过Inline Skill的方式增加一个本地任务技能 和 覆盖一个同名的远程仅能。

public class SimulatedLocalApiSkillsFactory{    public static async Task<IList<AgentInlineSkill>> GetSkillsAsync(CancellationToken cancellationToken = default)    {        Console.WriteLine("🏠 [LocalApiFactory] 正在从本地获取技能列表...");
        var localSkills = new List<AgentInlineSkill>        {            // 覆盖全局 expense-report，使用 Contoso 定制规则            new AgentInlineSkill("expense-report", "（Contoso定制v2）企业费用报销政策",                """                # Contoso 定制报销规则（2025版）                - 差旅费上限提升至 8000 元/次                - 新增"远程协作设备补贴"类目，≤3000元免审批                - 年末报销截止日期：12月25日                """),            // 新增：Contoso 特有的技能            new AgentInlineSkill("contoso-benefits", "Contoso 员工福利计划详情", "福利：弹性办公、年度体检、学习补贴..."),        };        Console.WriteLine($"✅ [LocalApiFactory] 已成功加载 {localSkills.Count} 个本地技能");        return localSkills;    }}

Agent客户端加载Skills

这里我们在Agent客户端加载本地 和 远程技能，同时对远程技能做1小时的缓存代理。

// ── Source 1：本地定制技能（覆盖全局版，注册顺序靠前 → 优先）──var localCustomSkills = await SimulatedLocalApiSkillsFactory.GetSkillsAsync();// ── Source 2：模拟全局技能库（Remote API，通用政策）──var globalSource = new SimulatedRemoteApiSkillsSource("https://global-skills.contoso.com/api");// ── Source 3：带缓存的远程 Source（生产环境推荐）──var cachedGlobalSource = new CachingSkillsSource(globalSource, TimeSpan.FromMinutes(60));

构建针对角色的SkillsProvider工厂

这里我们用MAF提供的Builder模式来实现一个面向指定角色的SkillsProvider工厂方法：

AgentSkillsProvider BuildProviderForRole(EmployeeRole role){    Console.WriteLine($"\n🔨 开始构建 {role} 角色的 Provider...");    return new AgentSkillsProviderBuilder()        // 本地定制优先（先注册 → first-wins）        .UseSkills(localCustomSkills)        // 全局技能库（带缓存）        .UseSource(cachedGlobalSource)        // 角色感知过滤        .UseFilter(s => UserRoleHelper.IsSkillVisibleTo(s, role))        // 自定义 Prompt：企业内部语气        .UsePromptTemplate("""            你是 Contoso 集团的企业服务助手。            ## 你掌握的企业知识库            {skills}            ## 工作原则            遇到政策性问题，**先加载该技能的详细指引**，再作答。请确保所有建议符合 Contoso 最新官方规定。            {resource_instructions}            {script_instructions}            """)        .Build();}

测试验证各个角色的技能可见范围

这里通过下面的测试代码来创建三个角色使用的SkllsProvider，通过获取其Skills可见范围来进行验证：

// 验证三个角色看到的技能集合foreach (var role in Enum.GetValues<EmployeeRole>()){    var provider = BuildProviderForRole(role);    var srcField = typeof(AgentSkillsProvider).GetField("_source", BindingFlags.Instance | BindingFlags.NonPublic);    var src = (AgentSkillsSource?)srcField?.GetValue(provider);    var skills = src is null ?         new List<AgentSkill>() : (await src.GetSkillsAsync()).ToList();    Console.WriteLine("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");    Console.WriteLine($"👤 [{role}] 可见技能（{skills.Count} 个）：");    foreach (var s in skills)    {        string origin = s.Frontmatter.Description.StartsWith("（Contoso") ? "（本地定制）" :                        s.Frontmatter.Description.StartsWith("（全局") ? "（全局库）" : "（其他）";        Console.WriteLine($"    • {s.Frontmatter.Name} {origin}");    }}

测试结果如下图所示：

3 小结

本文介绍了MAF如何整合多个Agent Skill Source实现企业级Skill管控 和 角色Skill可见性控制，这在企业级应用中是非常实用的特性和实践。

不过，目前MAF的Agent Skills仍然属于实验性支持阶段，生产落地还需谨慎。

示例源码

Github:  https://github.com/EdisonTalk/MAFD

参考资料

圣杰，《.NET + AI 智能体开发进阶》