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 接口标准—…… 阅读全文

摘要：一、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…… 阅读全文

摘要：一、A2A 协议 1. 为什么需要 A2A 协议？ 随着 AI 技术的发展，企业中的 AI Agent 数量不断增加。这些 Agent 可能来自不同的团队、不同的技术栈，甚至不同的组织： flowchart LR subgraph 企业A A1[客服 Agent] A2[销售 Agent] end subgraph 企业B B1[物流 Agent] B2[库存 Agent] end subgraph 第三方服务 C1[支付 Agent] C2[天气 Agent] end A1 -.->|如何通信?| B1 A2 -.->|如何协作?| C1 B2 -.->|如何发现?| C2 style A1 fill:#e1f5ff style A2 fill:#e1f5ff style B1 fill:#ffe1e1 style B2 fill:#ffe1e1 style C1 fill:#e1ffe1 style C2 fill:#e1ffe1 在没有标准协议的情况下，Agent 之间的互联面临诸多挑战： 问题 描述 影响 协议不统一 每个 Agent 使用不同的 API 格式 集成成本高，难以扩展 发现困难 无法自动发现其他 Agent 的能力 需要人工配置，耦合度高 状态不透明 无法追踪跨 Agent 任务的执行状态 调试困难，可靠性差 安全性参差 缺乏统一的认证授权机制 安全风险高 Agent-to-Agent (A2A) Protocol 提供了一套标准化的解决方案，核心价值： 统一发现机制：通过 Agent Card 声明和发现能力 标准化通信：基于 JSON-RPC 2.0 的统一消息格式 任务生命周期：完整的任务状态管理和追踪 流式支持：SSE 实时事件推送 安全机制：内置认证和授权方案 2. 什么是 A2A 协议？ Agent-to-Agent (A2A) Protocol 是由 Google 发起并开源的一个开放协议，旨在实现 AI Agent 之间的标准化通信与协…… 阅读全文

摘要：一、自定义工作流事件 1. 为什么需要自定义事件？ 场景 内置事件 自定义事件 粒度 Executor 级别 业务逻辑级别 语义 系统通用 (调用、完成) 业务特定 (审核通过、风险预警) 数据 执行元数据 业务数据 (敏感词、风险分数) 监控 技术监控 业务监控 + 审计 前端 通用进度条 具体业务状态展示 2. 自定义事件类定义 基本定义模式：自定义事件本质上就是继承 WorkflowEvent 的普通 C# 类。让我们从最简单的开始： /// summary /// 表示检测到敏感词的事件 /// /summary public class SensitiveWordDetectedEvent : WorkflowEvent { public SensitiveWordDetectedEvent(string word, int position) : base(data: null) // 可以传递简单数据到 base { Word = word; Position = position; } public string Word { get; } public int Position { get; } } 设计原则 DO (推荐做法)： 类名以 Event 结尾，语义清晰 使用只读属性 ({ get; })，确保事件不可变 添加 XML 注释说明事件的业务含义 属性类型尽量简单（string, int, DateTime 等可序列化类型） DON'T (避免做法)： 不要在事件类中包含方法逻辑 不要引用不可序列化的对象（如 DbContext, HttpClient） 不要使用可变属性（{ get; set; }） 不要在构造函数中执行耗时操作 3. 携带复杂数据的事件 当需要传递更复杂的业务数据时，有两种设计模式： 模式 1: 使用属性传递结构化数据 /// summary /// 风险评估完成事件 /// /summary public class RiskAssessmentCompletedEvent : WorkflowEvent { public RiskAssessmentCom…… 阅读全文

摘要：一、快速开始 1. 什么是 Workflow Orchestration 在企业级 AI 应用开发中，我们经常面临以下挑战： 单个 Agent 难以处理复杂任务：一个 Agent 无法同时擅长需求分析、代码生成、测试等多个领域 业务逻辑与 AI 调用耦合：复杂的条件判断、循环、并发控制分散在代码各处 流程难以可视化和维护：多步骤的 AI 处理流程缺乏清晰的结构 缺乏统一的状态管理：多个步骤之间的数据传递和状态共享容易出错 Workflow Orchestration (工作流编排) 正是为了解决这些问题而生： 模块化设计：将复杂任务拆分为独立的 Executor 和 Agent 清晰的流程定义：使用 Builder API 构建可读、可维护的流程图 灵活的流程控制：支持条件分支、循环迭代、并发执行等复杂模式 统一的状态管理：内置 WorkflowContext 管理跨步骤的状态和数据 实时流式反馈：通过事件机制实时监控工作流的执行进度 MAF Workflow 位于应用层和 Agent 层之间，负责： 编排多个 Agent：决定 Agent 的执行顺序、条件和并发策略 管理数据流：在 Agent 和 Executor 之间传递数据 监控执行状态：实时报告工作流的执行进度和结果 错误处理：统一处理执行过程中的异常和重试逻辑 2. 第一个工作流：文本处理管道 业务场景：将用户输入的文本 → 转为大写 → 反转顺序 步骤 1：定义第一个 Executor - 大写转换。 继承 ExecutorTInput, TOutput： TInput = string：接收字符串输入 TOutput = string：返回字符串输出 构造函数传入 UppercaseExecutor 作为唯一标识符 实现 HandleAsync 方法： message：接收上一个步骤传递的数据 (对于第一个 Executor,是工作流的输入) context：工作流上下文,用于访问共享状态、发布事件等 (后续课程详解) cancellationToken：用于取消操作 返回值：会自动作为消息沿着 Edge 传递给下一个 Executor 业务逻辑： 使用 ToUpperInvariant() 进行文化无关的大写转换 返回 ValueTask (高性能异…… 阅读全文

摘要：一、核心概念 1. Executor（执行器） Executor（执行器） 是 Workflow 中的最小工作单元，类似于： 类比 说明 工厂里的工人 每个工人负责一道工序 乐高积木块 每个积木有特定功能，组合成整体 电路中的元件 接收输入信号，输出处理结果 flowchart LR Input[输入消息] --> Executor[Executor\n执行器] Executor --> Output[输出消息] style Executor fill:#4CAF50,color:white Executor 的核心特征 唯一标识（Id）：每个 Executor 有一个唯一的 ID，用于在 Workflow 中引用 消息处理：接收特定类型的输入消息，处理后产生输出消息 路由配置：通过 ConfigureRoutes 方法定义能处理哪些类型的消息 状态感知：可以通过 IWorkflowContext 访问和修改工作流状态 Executor 的类型层次：MAF 提供了多种 Executor 类型，满足不同场景需求 classDiagram class Executor { +string Id +ExecuteAsync() #ConfigureRoutes() } class Executor~TInput~ { +HandleAsync(TInput) } class Executor~TInput,TOutput~ { +HandleAsync(TInput) TOutput } class FunctionExecutor~TInput~ { +委托函数处理 } class FunctionExecutor~TInput,TOutput~ { +委托函数处理 } class StatefulExecutor~TState~ { +TState State +ReadStateAsync() …… 阅读全文

摘要：一、自定义 Agent 的实现 1. 场景分析 在大多数场景下，使用 chatClient.CreateAIAgent() 创建的标准 Agent 已经足够强大。但在某些特殊场景下，自定义 Agent 实现能带来更大的价值： 场景 1：规则引擎替代 AI（成本优化） 问题：客服系统每天处理数万次重复性问题(营业时间？，退货流程？)，每次调用 AI 模型都会产生成本。 解决方案：自定义 Agent 使用 FAQ 知识库进行关键词匹配，只在无法匹配时才调用 AI。 收益： 成本降低 70-90%（高频简单问题零成本） 响应速度提升 10 倍（无需等待 AI 推理） 答案一致性更高（预定义标准答案） 场景 2：遗留系统集成（ERP/CRM/工作流引擎） 问题：企业内部有成熟的审批工作流引擎，需要将其包装为 Agent 供统一调度。 解决方案：自定义 Agent 作为适配器，将工作流引擎的 API 转换为 Agent 接口。 收益： 无缝集成现有系统（无需重构） 复用企业级规则引擎（审批、权限、流程） 数据安全可控（不发送敏感数据到外部 AI） 场景 3：测试模拟（Mock Agent） 问题：开发和测试环境中，不希望调用真实 AI 模型（成本、稳定性、可预测性）。 解决方案：自定义 Agent 返回固定或可配置的测试数据。 收益： 单元测试更可靠（确定性输出） 开发环境零成本 CI/CD 管道更快（无需等待 AI 响应） 场景 4：混合模式（规则 + AI） 问题：希望结合规则引擎的确定性和 AI 的灵活性。 解决方案：自定义 Agent 先尝试规则匹配，失败后转发给 AI Agent。 收益： 平衡成本与效果 灵活的分流策略（按优先级、置信度） 逐步优化规则库（分析 AI 处理的高频问题） 对比: 标准 Agent vs 自定义 Agent 特性 ChatClientAgent(标准) 自定义 Agent 说明 创建方式 chatClient.CreateAIAgent() 继承 AIAgent 抽象类 标准方式更简单 开发复杂度 低 高 自定义需实现所有核心方法 灵活性 受限于 IChatClient 能力 完全可控 自定义可实现任意逻辑 成本 按 Token 计费…… 阅读全文

摘要：一、自定义文件消息存储 1. ChatMessageStore 架构概览 classDiagram class ChatMessageStore { abstract>> #IChatReducer? ChatReducer +AddMessagesAsync(messages) +GetMessagesAsync() +ClearAsync() +Serialize() +Deserialize(state) } class InMemoryChatMessageStore { -List~ChatMessage~ _messages +AddMessagesAsync() +GetMessagesAsync() +ClearAsync() } class FileChatMessageStore { -string _filePath -SemaphoreSlim _lock +AddMessagesAsync() +GetMessagesAsync() +ClearAsync() } class RedisChatMessageStore { -IConnectionMultiplexer _redis +AddMessagesAsync() +GetMessagesAsync() +ClearAsync() } ChatMessageStore |-- InMemoryChatMessageStore ChatMessageStore |-- FileChatMessageStore ChatMessageStore |-- RedisChatMessageStore ChatMessageStore 抽象类核心方法职责 方法 职责 使用场景 AddMessagesAsync 添加新消…… 阅读全文