XIAOSUO 记录个人学习的足迹

摘要：一、终端智能体运行机制基础 终端智能体是基于大语言模型的复杂控制系统，依赖三大技术支柱：自动化控制循环逻辑、标准化的工具交互协议，以及严密的安全权限隔离机制。 1. 控制循环 智能体的自主性建立在 “感知 → 思考 → 执行 → 反馈” 的持续循环之上。只要目标未达成或系统未强制停止，循环就会不断重复。 四个核心步骤： 步骤 说明 感知 收集系统环境状态：读取目录结构、配置文件（.csproj）、环境变量、Git 状态、剪贴板内容，并转为结构化文本。 思考 将数据与用户指令一同发送给 LLM，进行任务规划与决策，输出结构化的执行计划（明确要调用的函数）。 执行 客户端执行动作：调用 OS 文件接口、启动子进程（如 dotnet run）、根据 Diff 直接重写源码文件。 反馈 捕获执行结果：文件内容、终端输出、退出码（0 成功，非 0 失败）。若报错，则进入自我纠错闭环。 2. MCP 协议（Model Context Protocol） MCP 是一个开源标准化通信协议，用于统一大语言模型与外部数据源、本地工具的交互方式。 架构组成 MCP Client（终端智能体），管理控制循环，与云端 LLM 通信，向 MCP Server 发送 JSON 请求。 MCP Server（本地/远程服务），将工具或数据源封装成标准接口，提供三类能力： 资源读取：读取静态数据（本地文件、企业知识库）。 工具调用：执行有副作用的操作（git commit、git push）。 提示词模板：提供预定义任务模板，规范业务流程。 核心价值：企业只需编写一个 MCP Server，任何支持 MCP 的智能体即可直接连接，获得运行内部测试用例的能力。 3. 权限管理 权限管理分为四个层级： 白名单操作（静默放行）：只读命令自动执行，无需确认，ls、dir、cat、type、git status。 拦截与授权（人工确认）：破坏性命令触发暂停，需用户输入 Y/N，curl、安装包、删除文件、复杂 Shell 脚本。 文件系统隔离：权限严格限制在启动时的项目文件夹内，无法使用绝对路径访问上级目录。 敏感数据脱敏：发送到云端前，使用正则扫描并替换密码、密钥为 [REDACTED_SECRET]。 二、Claude Code 简介…… 阅读全文

摘要：一、AI 辅助编程技术演进 1. 什么是 AI 辅助编程 传统开发中，程序员是“翻译官”——把模糊的业务需求逐字翻译成计算机能理解的语法。AI 辅助编程在人与计算机之间安插了一个超级智能中间层，我们只需用自然语言表达意图，AI 完成枯燥的翻译工作。 AI 辅助编程的本质：让机器听懂人类的意图，自动将其转化为计算机可执行的指令。 传统开发 vs AI 开发 维度 传统开发流 AI 开发流 工作方式 手动查文档、搜函数 自然语言描述需求即可 节奏 频繁被打断，碎片化工作 完整逻辑几分钟生成 心智负担 重，注意力分散 断崖式下降 关注点 少一个分号就报错 专注架构、业务与体验 角色比喻 体力与脑力消耗 导演与剧组 2. Copilot 时代：代码自动补全 从“死记硬背”的基于规则和 AST 的字典式补全，到基于深度学习的多行逻辑预测——AI 像一个阅读过几十亿行代码的“老中医”，不仅猜下一个词，更猜整段逻辑。 补全技术演进： 规则补全：基于 AST 和词典（精准但无智商） 单行补全：基于深度学习 多行预测：多行逻辑生成 3. Chat 时代：对话式代码助手 当 Copilot 只能被动等待你敲键盘时，Chat 让 AI 变成了随时在线的资深技术导师。 核心能力： 代码解释：高亮任意代码，AI 即时解释其功能与上下文关系。 重构建议：在对话中讨论重构方案，AI 提供多种优化路径。 内联编辑 + Diff 审查：AI 直接在代码区修改，红绿对比一目了然，人类保留最终控制权。 - const color = #3366FF; - btn.addEventListener(click, handler); + const color = #FF4444; + btn.addEventListener(click, shakeAnimation); 4. Agent 时代：自主智能体 Agent 与 AI 助手的本质区别：它长出了手和脚，具备规划能力。 工作流程： 接收任务 → 拆解规划 → 搜索文件 → 执行修改 → 运行测试 → 交付报告 人类从“监督者”升级为“项目经理”。 5. Context 时代：模型上下文协议 (MCP) Agent 撞上了**“上下文缺失”**的墙。MCP 就像 AI 的 USB 接口标准—…… 阅读全文

摘要：一、MCP概述 1. MCP协议 我们示例到目前所有的功能都是在项目内部开发完成的，如果一个 AI 应用只能使用内部功能，那它还达不到企业级 AI 的要求。因为企业内部会有各种各样的应用软件，虽然前面我们介绍了通过使用 AI 访问数据库来读取业务数据，但那只能满足简单的读取数据库的需求。 真实业务场景会复杂得多，比如希望在数据库中查找最新的销售报告，并将其通过电子邮件发送给指定的角色用户。这里发送邮件是企业内部邮箱服务的功能，而指定角色是身份服务的功能。这些功能在企业内部对应的应用中已经实现了，我们不可能在 AI 系统中再实现一次，而是需要让 AI 拥有调用其他系统的能力。 类似于 Web 系统中的 API 接口一样，AI 也有专门外部系统接入的协议，它就是 MCP 协议。 关于 MCP 的内容，我已经在前面的文章中详细介绍过了，请跳转到 MCP大模型外挂商店 阅读。 2. MCP 交互流程 我们用前面说的“在数据库中查找最新的销售报告，并将其通过电子邮件发送给指定的角色用户”来举例： 初始化：MCP 客户端连接到 MCP 服务器 LLM推理：查询数据库 + 查询角色 + 发送邮件 工具调用：MCP 客户端负责接受指令，发送给MCP服务器 执行：MCP 服务器负责执行，返给结果给客户端，返回给LLM 生成最终答复 3. MCP 服务生态 官方代码库 ：由 MCP 维护的 GitHub 代码库是首选的起点 。这里包含了许多常用服务的参考实现，例如本地文件系统、GitHub、Git、PostgreSQL 和用于浏览器自动化的 Puppeteer。这些官方服务器是学习和理解 MCP 最佳实践的绝佳范例。 社区精选列表 ：这是一个由社区驱动和维护的 GitHub 列表，它展示了 MCP 生态系统的广度和创造力 。在这里，可以找到从浏览器自动化、数据库交互到智能家居控制和特定应用（如 Bilibili 内容搜索）的各种服务器 。 MCP市场：一个第三方的 MCP 服务器和客户端市场，聚合了大量的服务器和客户端，并提供了分类和搜索功能 。 4. 安装 MCP 文件系统服务 这里我们从 github 中下载 modelcontextprotocol 提供的 filesystem 来做示例。 安装这个文件系统服务提供了很多种方式，细…… 阅读全文

摘要：一、前端环境搭建 1. 技术选型 前端 UI 我们采用 VUE + TS + Vite + Element Plus + ECharts + Pinia + SPA 来实现。 步骤 1，创建 Vue 项目，在 src 目录下执行： npm create vue@latest 项目名称: Qjy.AICopilot.VueUI 功能：TypeScript、Pinia、ESLint、Prettier 步骤 2，安装项目依赖包，我们进入到刚刚创建的 vue 项目，分别执行下面命令 cd Qjy.AICopilot.VueUI npm install npm install element-plus @element-plus/icons-vue npm install echarts npm install markdown-it @microsoft/fetch-event-source npm install -D @types/markdown-it 步骤 3，启用 pinia 和 element-plus //Qjy.AICoplot.VueUI/src/main.ts import { createApp } from 'vue' import { createPinia } from 'pinia' import ElementPlus from 'element-plus' import 'element-plus/dist/index.css' import App from './App.vue' const app = createApp(App) // 创建应用实例 app.use(createPinia()) // 注册状态管理插件 app.use(ElementPlus) // 注册 ElementPlus 插件 app.mount('#app') // 挂载到 index.html 的 #app 节点 2. Aspire 集成 步骤 4，使用 Aspire 启动 vue 项目。先在 Asprise 项目安装 nuget 包：CommunityToolkit.Aspire.Hosting.NodeJS.Extensions //Qjy.AICopilot.AppHost/AppHost.cs bui…… 阅读全文

摘要：NL2SQL（Natural Language to SQL） 是一项将人类自然语言问题自动转换为结构化 SQL 查询语句的技术。简单来说，就是让用户用大白话（如“上个月销售额最高的产品是什么？”）直接查询数据库，无需学习 SQL 语法。 今天我们的任务就是给我们的企业智能助理扩展 NL2SQL 的能力。 一、动态数据源架构 1. 面向多数据库源的架构 一家企业会有很多不同的系统，而各个系统所用的数据库会是各种各样的，它们不仅数据库产品不一样，同产品的数据库可能版本也不一样，查询数据的时候可能存在一些差别。 我们智能助理需要拥有以下这些功能： 动态配置多个业务数据库 通过自然语言，分析全局源数据，定位到需要链接的数据库（如 ERP\HR\OA） 最小权限连接上数据库（只读，禁止使用 DDL、DML） 分析目标库内部的表结构信息 方言适配（不同类型的数据库 SQL 语法差异） ps：只做只读的实现，并不是模型不能生成插入、更新、删除等 SQL，主要是不建议用自然语言来做数据库的操作，主要是： 模型会有幻觉，操作数据库存在风险 无法保证事务 无法触发一些关联任务，比如生成订单后，需要通知扣减库存。如果是直接操作订单表，库存的扣减事件就无法触发 如果需要实现自然语音操作数据，可以使用工具调用或者 MCP 来完成，我们的项目只实现生成 SQL 查询语句。 2. ReAct 认知模型 ReAct 模型就是一个会动脑筋、会动手、还会从错误中学习的超级助理的工作方法！ 它的任务就是听懂你的话，然后从数据库里找到答案。它可聪明了，做事非常有条理，就像一个大侦探，每次破案都遵循三个步骤： 思考（Think - 推理） 当用户说“帮我查一下仓库里还有多少台 iPhone 15？” 助理就会想一想：“这个问题是什么意思呢？我需要去“库存表”里看看，要找“iPhone 15”的数量”。 行动（Act - 行动） 想好之后，它就立刻行动起来！也就是生成 SQL 查询语句去查找。 检查（Observe - 观察）：行动之后，它会仔细检查结果。比如，它可能发现“生成的 SQL ”写错了，它会进行修正。 总之，当你告诉它要什么，它就用这个“思考-行动”的魔法，自己想办法从数据库里把答案给你找出来。 3. 多态数据库设计 全局数据源元数据注册表： 身份标识与路由 语义描…… 阅读全文

摘要：一、理论基础 1. RAG 概述 RAG：检索增强生成技术，我们先用一个例子来介绍一下什么是检索增强生成。 想象一下，你是一个很聪明的小学生，但你的知识都记在脑子里。如果老师问你一个很难的问题，比如：“恐龙是怎么消失的？”。你可能记得一些，但不完整。 这时候老师说：“来，我们开卷考！你可以去书架上查百科全书，然后再回答。” RAG 就是这样： 你有大脑（AI 的记忆）→ 你本来就知道很多事。 但遇到不知道的问题→ 你先跑去“书库”（数据库、网络等）快速查找相关的资料。 把查到的资料和你原来的知识合在一起，用你自己的话给出一个更好的答案。 所以，RAG 就是：先查资料，再结合自己的知识回答问题。这样就不会瞎编，答案更准确、更新鲜！是不是很像写作业时“先翻书，再总结”呢？ 企业应用使用大模型时，至少会遇到下面2个问题： 大模型一旦训练结束，它就不会在知道结束时间之后发生的事了，也就是它有时效性缺失 另外，通用的大模型是使用公共数据来训练的，它没有企业私有的数据，也就是私有领域空白 为了解决上面2类问题，我们可以使用 RAG 技术，为模型提供一个图书馆，也就是通常说的企业知识库。 2. RAG 工作流程 在让 LLM 回答问题之前，先去外部知识库中检索相关的信息，然后将检索到的信息作为参考资料喂给LLM，让它基于资料生成答案。RAG 分为2个阶段： 索引阶段：后台异步运行的数据处理流程，将文本转换为向量，构建语义索引。 检索与生成阶段：能够在线实时响应用户请求的流程 ETL（提取、转换、加载）流： 加载：格式解析、编码标准化、元数据提取； 分割：LLM的上下文窗口有限，所以需要递归字符分割，分割可能造成语义不完整，所以在分割的2段语句通常会添加重叠窗口； 嵌入：人类语言翻译成机器语言，使用嵌入模型，将文本转换为高维向量，即高维的语义空间，后续可以使用余弦相似度 -1 ~ 1进行检索； 存储：将文本块内容、向量数据、元数据，持久化存储到向量数据库。 3. 嵌入模型选型 我们把文本转换成高维向量时，需要使用嵌入模型，那如何选择嵌入模型呢？ 我们先看一下都有哪些选择： 闭源厂商云端模型 API： 优势：接入成本低、弹性扩展 劣势：数据隐私风险、长期成本不可控、网络延迟 开源模型本地私有化： 优势：绝对的数据安全、零增量成本、高性能与低延迟 劣…… 阅读全文

摘要：上一篇我们已经搭建好了 AI 应用的基础设施，今天我们开始创建企业助理智能体。 一、AI 网关集成 Agent 框架 关于 MAF 部分的内容，可以查看 Agent 智能体 ，我们这里直接上代码。 我们在 Qjy.AICopilot.AiGatewayService 项目添加一个 Agents 文件夹。 1. 创建聊天智能体 由于我们是一个多模型聊天应用，聊天模型数据是从数据库动态加载的。因而我们首先要创建一个工厂类，用来根据数据库中的数据来动态创建 Agent。 //Qjy.AICopilot.AiGatewayService/Agents/var httpClientFactory = serviceProvider.GetRequiredServiceIHttpClientFactory();ChatAgentFactory.cs public class ChatAgentFactory(IServiceProvider serviceProvider) { public ChatClientAgent CreateAgentAsync( LanguageModel model, ConversationTemplate template, ActionChatOptions? configureOptions = null, bool isSaveChatMessage = true) { var httpClientFactory = serviceProvider.GetRequiredServiceIHttpClientFactory(); // 创建专属 HttpClient 对象 var httpClient = httpClientFactory.CreateClient(OpenAI); var chatClientBuilder = new OpenAIClient( new ApiKeyCredential(model.ApiKey ?? string.Empty), new OpenAIClientOptions …… 阅读全文

摘要：前面我做了一个使用 LangChain 做的 AI 通用聊天平台的示例，接下来我们回到 .NET 环境，完成一个企业级的 .NET+AI 的项目。目标是为企业通电，完成一个可扩展、可私有化部署的 AI 应用。让企业能用自然语音操作内部其他系统（ERP/CRM/OA）、获取知识、分析报告。 一、项目分析 1. 背景 我们需要完成一个AI企业助理系统，在现有的系统之上，覆盖一层“智能化层”，完成： 智能体和工具调用：赋予 AI 行动能力。 检索增强生成，企业知识中枢：赋予 AI 记忆和知识能力 AI数据分析，一句话生成可视化报表：赋予 AI 分析能力，如 NL2SQL 2. 需求分析 通过背景分析，我们梳理一下大致需要完成的功能： 智能助理（Agent）：AI 交互入口（大脑） 对话与上下文管理：支持多轮上下文 意图识别：准确分析用户的输入，判断命令意图 工具调用：调用通过 MCP 接入的外部插件 富响应生成：响应不能局限于纯文本，包含表格、图表 企业知识中枢（RAG）：处理非结构化知识（记忆） 文档处理流程：支持多种文档格式上传，实现自动解析、自动分块、向量化计算（嵌入）、向量存储 检索与回答：支持语义搜索，结合LLM生成精准、有来源依据的问答 企业级特性：权限控制、数据时效性 数据报表分析（NL2SQL）：处理结构化数据（分析） NL2SQL引擎：自然语言翻译成 SQL 查询 多数据源支持 自动化分析与可视化：自动生成可视化图表，利用LLM总结图表中的趋势 报告导出 MCP 接入管理（Tools）：负责连接外部系统（行动） 服务发现与管理：实现 MCP 服务的注册，注册到AI的能力库 调试与权限：确保操作安全 3. 技术选型 后端框架：ASP.NET Core（.NET 10） AI 框架：Semantic Kernerl（SK）、Agent Framework 知识库：向量数据库（Qdrant）+关系型数据库（PostgreSQL + pgvector） 大模型：兼容 OpenAI 接口、支持私有化部署 安全方案：Jwt + RABC 开发方式：云原生开发 .NET Aspire 部署方案：容器化部署 4. 开发流程 搭建环境与项目骨架 实现核心服务（认证 + AI 网关） 构建知识中枢（RAG …… 阅读全文

摘要：一、Agent Skill 协议概述 1. Agent 的知识困境 假设你正在为公司开发一个 AI 助手，老板要求它能回答费用报销相关的问题： 员工: 出差期间的小费可以报销吗？ AI 助手: 一般来说，合理的小费可以报销…… ← ❌ 太模糊！ 期望回答: 根据公司政策，餐饮消费中 20% 以内的小费可以报销， 超过 $50 的单笔餐饮需要附上收据。 ← ✅ 精准！ 问题在于：模型的参数里没有你们公司的报销政策。 能力与知识的区别，我们先做一个关键区分——这是理解 Agent Skills 的基础： 能力 (Capability) 知识 (Knowledge) 含义 Agent 能做什么 Agent 知道什么 类比 给员工配一台电脑 给员工发一本操作手册 AI 例子 调用天气 API、发送邮件、执行 SQL 公司政策、操作流程、领域规范 技术手段 Function Calling / MCP Tools ??? Function Calling 解决了能做什么的问题——让 Agent 可以调用 API、查数据库、发邮件。 但知道什么呢？这正是 Agent Skills 要解决的问题。 现有方案的局限 方案 做法 问题 ❌ 塞进 System Prompt 把整个政策文档放到系统提示里 Token 浪费严重！20 个领域的知识全量加载，每次请求可能消耗数万 Token ❌ 硬编码 用 if-else 把规则写到代码里 不灵活，业务人员无法维护，改个限额就要重新部署 ⚠️ RAG 建向量索引，语义检索 对结构化的政策文档来说过于复杂，且检索结果不可控 ⚠️ 微调 (Fine-tuning) 收集数据训练模型 成本高（$10K+），周期长（数周），需要 ML 专家 我们需要一种方式：像插 U 盘一样，把领域知识按需加载给 Agent，简单、标准化、人人可维护。 2. 什么是 Agent Skills 定义：Agent Skills 是一种开放规范，定义了如何将领域知识打包为模块化、可复用的知识包，供 AI Agent 按需使用。 A simple, open format for giving agents new capabilities and exp…… 阅读全文

摘要：一、AG-UI 协议概览 1. 为什么需要 AG-UI 随着 AI Agent 技术的发展，传统的 Web 应用交互模式面临新的挑战。AI Agent 的响应具有以下特点： flowchart LR subgraph 传统API A1[请求] --> B1[处理] --> C1[响应] end subgraph AI Agent A2[请求] --> B2[思考...] B2 --> C2[工具调用] C2 --> D2[中间结果] D2 --> E2[继续思考...] E2 --> F2[流式输出] F2 --> G2[最终响应] end style A1 fill:#e1f5ff style C1 fill:#e1f5ff style A2 fill:#ffe1e1 style G2 fill:#ffe1e1 在构建 AI Agent 应用界面时，传统 API 模式面临诸多挑战： 问题 传统 API AI Agent 需求 影响 响应模式 请求/响应（阻塞等待） 流式实时响应 用户体验差，等待时间长 中间过程 无法展示 需要可视化思考/工具调用 用户无法理解 Agent 行为 状态同步 单次请求完成 需要持续状态同步 复杂 UI 状态管理困难 交互模式 确定性 UI 非确定性（Agent 决定 UI） 难以提前规划界面 长时间任务 超时问题 需要进度反馈 无法处理复杂任务 AG-UI (Agent User Interaction Protocol) 专为 AI Agent 与用户界面的交互而设计： flowchart TB subgraph AG-UI协议 direction LR Streaming[流式响应] Events[事件系统] State[状态同步] Tools[工具可视化] end UI[用户界面] -->|AG-UI 协议| AG-UI协议 AG-UI协议 -->|实时交互| Agent[A…… 阅读全文