Lzq.Extensions.AI 0.4.0

Lzq.Extensions.AI — AgentSkill 技能引擎

基于 Microsoft.Agents.AI 构建的 AI Agent 扩展库，提供多模型对话、技能调用、MCP 工具集成、流式输出与会话持久化。

快速开始

// DI 注册
services.AddLzqAI();
// 使用 SQL 持久化历史（可选）
services.AddLzqAI().AddSqlSugarChatHistoryProvider();

// 创建 Agent 并执行
var (response, sessionKey) = await runner.RunAsync(
    new AISetting
    {
        ConfigId = "default",
        Url = "https://api.siliconflow.cn/v1/",
        KeySecret = "sk-xxx",
        Model = "deepseek-v4-flash"
    },
    new AIAgentModel
    {
        Name = "助手",
        Description = "通用 AI 助手",
        SelectedSkills = { new SkillMethodEntry { SkillName = "time-master" } }
    },
    "北京时间现在几点？");

核心架构

┌─────────────────────────────────────────────────────┐
│                    DI Container                      │
├─────────────────────────────────────────────────────┤
│  IChatClientFactory → ChatClientFactory             │
│    ├── OpenAI 兼容 API (OpenAIClient)               │
│    └── Ollama (OllamaApiClient)                     │
│                                                     │
│  IAIAgentFactory → AIAgentFactory                   │
│    ├── 绑定技能 (AgentSkillProvider)                │
│    ├── 绑定 MCP 工具 (McpToolProvider)              │
│    └── 日志中间件                                   │
│                                                     │
│  IAIAgentRunner → AIAgentRunner                     │
│    ├── 同步对话 (RunAsync)                          │
│    ├── 流式对话 (RunStreamingAsync)                 │
│    └── 原始流 (RunStreamingUpdatesAsync)            │
│                                                     │
│  AgentSkillProvider                                  │
│    ├── 内部 C# 技能 (AgentSkills/*.dll)             │
│    ├── 外部 MD 技能 (ExternalSkills/**/SKILL.md)    │
│    └── 文件热重载 (FileSystemWatcher)               │
│                                                     │
│  ChatHistoryProvider                                 │
│    ├── VectorChatHistoryProvider (默认)              │
│    └── SqlSugarChatHistoryProvider (可选)            │
│                                                     │
│  McpToolProvider                                     │
│    ├── HTTP (HostedMcpServerTool)                   │
│    └── Stdio (本地进程)                             │
└─────────────────────────────────────────────────────┘

1. 多模型支持

内置预设：

ChatClientConst.DeepSeek_V4_Flash  // SiliconFlow + DeepSeek-V4-Flash
ChatClientConst.DeepSeek_V32       // SiliconFlow + DeepSeek-V3.2
ChatClientConst.MiniMaxM25         // SiliconFlow + MiniMax-M2.5

2. AgentSkill 技能系统

2.1 内部 C# 技能（强类型 · DI 注入）

[GeneralSkill]  // 每次对话自动加载
public class TimeSkill : LzqAgentSkillBase<TimeSkill>
{
    protected override string SkillName => "time-master";
    protected override string SkillDescription => "时间查询与时区转换";

    [AgentSkillScript("GetCurrentTime")]
    [Description("获取指定时区的当前时间")]
    public async Task<string> GetCurrentTime(string timezoneId = "Asia/Shanghai")
    {
        var time = TimeZoneInfo.ConvertTime(
            DateTime.UtcNow,
            TimeZoneInfo.FindSystemTimeZoneById(timezoneId));
        return $"{timezoneId} 当前时间: {time:yyyy-MM-dd HH:mm:ss}";
    }
}

技能分类：

内置演示技能：

• TimeSkill (Core) — 时区时间查询/转换/计算
• WebSearchSkill (Network) — 多引擎搜索 + URL 内容抓取
• QueryWorkOrderSkill (Office) — 工单进度/列表查询
• GenericDataAnalysisSkill (Visual) — ECharts JSON 图表生成

2.2 外部 Markdown 技能（零代码 · 热加载）

ExternalSkills/
├── lzq-dev-handbook/
│   ├── SKILL.md
│   ├── specs/
│   └── extensions/
├── mes-operation-handbook/
│   ├── SKILL.md
│   └── operations/
└── vben-frontend-dev/
    ├── SKILL.md
    ├── patterns/
    └── components/

• FileSystemWatcher 监听，300ms 防抖热重载
• NoOpScriptRunner 禁用脚本执行，安全可控

2.3 技能热重载与管理

// 枚举技能
var skills = skillManager.GetSkills();

// 手动执行技能工具
var result = await skillManager.ExecuteAsync("time-master", "GetCurrentTime", args);

// 上传 DLL 插件
await skillManager.UploadPluginAsync("my-skill.dll", stream);

// 上传 ZIP 外部技能
await skillManager.UploadExternalSkillZipAsync("docs.zip", stream);

3. MCP 工具集成

支持两种传输模式：

new McpModel
{
    McpName = "database-mcp",
    McpType = McpTypeEnum.Stdio,
    Url = "npx",
    Args = "-y @modelcontextprotocol/server-postgres",
    AllowedTools = ["query", "list-tables"]
}

4. 流式对话

var (text, sessionKey) = await runner.RunStreamingAsync(
    setting, model, "分析销售数据并生成图表",
    async args =>
    {
        switch (args.EventType)
        {
            case StreamingEventType.Thinking:
                Console.WriteLine($"思考中: {args.Content}");
                break;
            case StreamingEventType.TextChunk:
                Console.Write(args.Content);
                break;
            case StreamingEventType.ToolCallStart:
                Console.WriteLine($"调用工具: {args.ToolName}");
                break;
            case StreamingEventType.ToolCallEnd:
                Console.WriteLine($"工具返回: {args.ToolResult}");
                break;
            case StreamingEventType.EchartsStart:
                Console.WriteLine("生成图表...");
                break;
        }
    });

5. 会话历史

• 基于 turn 追踪（用户消息开启新 turn）
• 滑动窗口保留最近 10 轮会话

6. 配置模型

AISetting

AIAgentModel

7. 关键接口

8. 相关项目

环境要求

• .NET 8.0+ / .NET 9.0 / .NET 10.0
• 依赖：Microsoft.Agents.AI、ModelContextProtocol、OllamaSharp、SemanticKernel