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助手，整合以下多个来源的Skill并实现角色管控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