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

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

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

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

这里我们来做一个企业HR助手，整合以下多个来源的Skill并实现角色管控Skill可见。

全局技能库（假设通过Remote HTTP API来获取）：它是所有员工通用的政策和流程；
本地技能库（假设通过InMemory来获取）：它是各个员工自己定制的任务技能
用户角色技能（假设通过自定义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}");
    }
}

测试结果如下图所示：