Bitzsoft.Integrations.AI.Skills 1.1.0

Bitzsoft.Integrations.AI.Skills

面向企业多租户 AI 应用的技能（Skill）与智能体（Agent）声明式基础设施包。统一封装双格式 Markdown 前置元数据手写解析器（兼容业务宿主存量格式与 Agent Skills 开放标准）、规范校验与标准格式无损导出、带长度预算的 L0 技能目录提示词生成、自动联动治理目录的 ai_load_skill 按需加载元工具，以及支持防抖热重载与轮询降级的目录扫描托管服务。

版本与兼容性

dotnet add package Bitzsoft.Integrations.AI.Skills

• 目标框架：net8.0;net10.0；
• 依赖：Bitzsoft.Integrations.AI.Governance、Microsoft.Extensions.Hosting.Abstractions；
• 零第三方 YAML 解析库依赖：沿用并加固确定性手写行式前置元数据解析器，兼容 UTF-8 BOM、CRLF、单双引号转义、行内方括号数组、缩进 metadata: 子键值块及缺失 --- 分隔线的容错降级；
• 不依赖 SqlSugar、EntityFrameworkCore 或任何业务宿主实体。

设计边界

本包负责的能力

• 统一声明解析（AIDefinitionMarkdownParser）：消除宿主中技能与智能体各自维护一套重复解析器的技术债，统一产出 AISkillDefinition（含原始 Body 以及按二级标题自动切分的 RoleDirective 与 PromptTemplate）与 AIAgentDefinition（含 RecommendedModel 并自动剥离前导 ## 系统提示词 / ## 角色定义 标题行）。
• 开放标准校验、无损导出与模板渲染：
  • AISkillValidator：校验 name（小写字母、数字与连字符，长度 <= 64，不以连字符起止）、description（<= 1024）及非空正文；当 description 缺少“何时使用”触发语（如 当…时使用、Use when）时给出可配置的 Warning 而不阻断存量技能加载；
  • AISkillExporter.ToAgentSkillsMarkdown：将任意 Legacy 技能一键无损转换为 Agent Skills 标准 Markdown；
  • AISkillTemplateRenderer：同时支持 {{variable}} 显式字典替换与自然语言对话意图引导包装。
• L0 渐进式披露目录（AISkillCatalogPromptBuilder）：仅输出技能编码与单行描述，严格执行最大条目数与总字符预算上限，并按 Order 升序、Code 字典序确定性排列。
• 按需加载元工具（AISkillLoadTool）：固定工具名 ai_load_skill，返回 JSON 字段（loaded、skillCode、name、category、roleDirective、sopGuide、recommendedTools、errorCode、message）与宿主既有协议逐字段一致；AddBitzsoftAISkills() 自动通过 PostConfigure<AIToolCatalogOptions> 将 ai_load_skill 注册为 Read + Public，杜绝误触发人工审批闸。
• 目录热重载扫描器（AddBitzsoftAIDefinitionScanner）：启动期全量扫描并支持运行期文件增删改防抖同步；单个损坏文件仅记录告警并跳过，不阻断其余文件；当容器只读卷或网络挂载盘导致 FileSystemWatcher 失败时，自动降级至基于 TimeProvider 的定时轮询。
• 三级星标置顶元数据（IsSystemFeatured / DefaultPinnedRoles）：解析器与 AISkillExporter 原生支持 is_system_featured（featured）与 default_pinned_roles（兼容内联数组与多行 - item 序列）无损往返，无缝对接工作台三级星标集合运算。
• 技能与智能体工具交叉引用完整性自检器（AIToolReferenceIntegrityValidator）：对技能与智能体绑定的工具集及技能交叉引用执行零数据库耦合校验，支持历史别名表映射、Controller_GetAction -> controller_action 蛇形动态工具回退、client:* 客户端委托动作放行以及悬空幽灵工具自动剥离。
• 多源定义存储与三层合并引擎（IAISkillDefinitionStore / IAIAgentDefinitionStore + IMultiSourceDefinitionMergeEngine / MultiSourceDefinitionMergeEngine + StoreBackedAIDefinitionSink）：支持 BuiltIn -> Global ("0") -> TenantOverride 三层优先合并、租户层 IsEnabled = false 或 Archived 墓碑禁用防回退语义、基于 AIEpochSingleFlightCache<T> 与 IAICacheEpochCoordinator 的 L1/L2 单航班缓存防击穿、全局变更级联失效租户缓存，以及扫描器基于 IServiceScopeFactory 隔离作用域的同步写入。
• 多租户智能体目录与运行时装配解析器（ITenantAgentCatalog / TenantAgentCatalog + IAgentRuntimeResolver / AgentRuntimeResolver）：提供按租户发布状态、分类与关键词过滤、非系统租户默认智能体优先回落选举、未找到/已禁用标准化领域异常（AI.AgentNotFound / AI.AgentDisabled）、结合 AITenantSolutionManifest 的技能与智能体白名单过滤、工具前缀白名单（AllowedToolPrefixes）裁剪及 ModelBindings 模型槽位解析。
• 租户声明式解决方案清单默认提供器与验证器（InMemoryAITenantSolutionManifestProvider / CompositeAITenantSolutionManifestProvider / AITenantSolutionManifestValidator）：内置全局基线与租户覆写合并语义、写入及启动期强约束校验（ManifestInvalid）及分布式纪元缓存支持。

不在本包内的职责

• 技能与智能体数据库表结构（DDL）、ORM 实体映射与后台管理 CRUD HTTP 接口；
• 用户级或角色级技能可见性 RBAC 规则（由宿主在 IAISkillReader 或授权守卫中实现）；
• 会话流式响应投影、思考标签拆分与 SSE 写出；
• RAG 向量知识库绑定与检索（暂不接线）。

双格式前置元数据映射表

解析器根据前置元数据是否包含 name / allowed-tools / license / compatibility / metadata 自动判定 AIDefinitionFormat.AgentSkills 或 AIDefinitionFormat.Legacy：

宿主端口清单与双 ORM（SqlSugar / EF Core）实现走查

双宿主数据库实现要点

1. IAISkillReader（请求级读取）：
   • SqlSugar 宿主：优先查询当前租户启用记录（TenantId == context.TenantId && IsEnabled），未命中再回退平台内置记录（TenantId == 0），映射为 AISkillContent。
   • EF Core 宿主：在当前请求 Scope 的 DbContext 上使用 .AsNoTracking() 查询租户覆盖与平台默认记录并投影为 AISkillContent。
2. IAIDefinitionSink（托管服务启动与热重载幂等写入）：
   • 由于 AIDefinitionFileScannerHostedService 是 IHostedService（根容器 Singleton），EF Core 宿主在实现 IAIDefinitionSink 时切勿直接构造函数注入 Scoped 的 DbContext，应注入 IServiceScopeFactory 或 IDbContextFactory<TDbContext>，在 UpsertAsync 内部开启独立 Scope，仅对 Source == BuiltIn 的记录按 Code 幂等新增或更新，保留租户在管理端手工微调过的副本；
   • SqlSugar 宿主在 IAIDefinitionSink 内调用 _sqlSugarClient.CopyNew() 获取独立上下文，按 (TenantId = 0, Code, Source = BuiltIn) 执行 Storageable 幂等合并。

完整最小示例

以下示例演示解析 Agent Skills 标准 Markdown、拼装 L0 技能目录提示词，并通过挂载 GuardedAIFunction 治理管线的 ai_load_skill 元工具按需读取技能 SOP：

using Bitzsoft.Integrations.AI.Governance;
using Bitzsoft.Integrations.AI.Skills;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;

const string skillMarkdown = """
    ---
    name: contract-clause-check
    description: "当用户要求核查采购或销售合同关键风险条款时使用。"
    allowed-tools: contract_detail clause_benchmark
    metadata:
      title: "合同关键条款核查"
      category: Legal
      version: "1.2.0"
    ---

    ## 角色定义
    你是严谨的企业法务合同审阅专家。

    ## 任务指令
    请围绕违约责任、争议管辖与付款节点逐条核查合同文本，并引用条款原文编号。
    """;

// 1. 解析并校验技能声明文件。
var parseResult = AIDefinitionMarkdownParser.ParseSkill(skillMarkdown, fallbackName: "contract-clause-check");
if (!parseResult.Succeeded || parseResult.Value is null)
{
    return;
}

AISkillDefinition parsedSkill = parseResult.Value;
IReadOnlyList<AIDefinitionIssue> issues = AISkillValidator.Validate(parsedSkill);

// 2. 生成注入系统提示词的轻量 L0 技能目录（仅含编码与单行描述）。
string l0CatalogPrompt = AISkillCatalogPromptBuilder.BuildL0Catalog(
[
    new AISkillSummary(parsedSkill.Code, parsedSkill.Description, parsedSkill.Order),
]);

// 3. 注册治理与技能服务（AddBitzsoftAISkills 会自动将 ai_load_skill 标记为 Public + Read）。
var services = new ServiceCollection();
services.AddLogging();
services.AddBitzsoftAIGovernance();
services.AddBitzsoftAISkills();
services.AddSingleton<IAISkillReader>(new InMemoryDemoSkillReader(parsedSkill));

await using var provider = services.BuildServiceProvider(
    new ServiceProviderOptions { ValidateOnBuild = true, ValidateScopes = true });

using var scope = provider.CreateScope();
var toolContextAccessor = scope.ServiceProvider.GetRequiredService<IAIToolExecutionContextAccessor>();
var skillContextAccessor = scope.ServiceProvider.GetRequiredService<IAISkillRequestContextAccessor>();
var skillReader = scope.ServiceProvider.GetRequiredService<IAISkillReader>();

AIFunction rawLoadTool = AISkillLoadTool.Create(skillReader, skillContextAccessor);
GuardedAIFunction guardedLoadTool = GuardedAIFunction.Wrap(rawLoadTool, scope.ServiceProvider);

using (toolContextAccessor.Push(new AIToolExecutionContext(TenantId: "tenant-01", UserId: "user-01")))
using (skillContextAccessor.Push(new AISkillRequestContext(
    TenantId: "tenant-01",
    UserId: "user-01",
    AllowedSkillCodes: new HashSet<string>(StringComparer.OrdinalIgnoreCase) { parsedSkill.Code })))
{
    object? fencedResponse = await guardedLoadTool.InvokeAsync(new AIFunctionArguments
    {
        ["skillCode"] = parsedSkill.Code,
        ["userIntent"] = "请重点核查设备采购合同中的逾期交付违约金上限",
    });

    Console.WriteLine($"校验告警数：{issues.Count}，L0 目录长度：{l0CatalogPrompt.Length}");
    Console.WriteLine(fencedResponse);
}

sealed class InMemoryDemoSkillReader(AISkillDefinition skill) : IAISkillReader
{
    public ValueTask<AISkillContent?> ReadAsync(
        string code,
        AISkillRequestContext context,
        CancellationToken ct = default)
    {
        ct.ThrowIfCancellationRequested();
        if (!string.Equals(code, skill.Code, StringComparison.OrdinalIgnoreCase))
        {
            return ValueTask.FromResult<AISkillContent?>(null);
        }

        return ValueTask.FromResult<AISkillContent?>(new AISkillContent(
            Code: skill.Code,
            Name: skill.Title,
            Category: skill.Category,
            RoleDirective: skill.RoleDirective,
            PromptTemplate: skill.PromptTemplate,
            RecommendedTools: skill.AllowedTools));
    }
}