AI 编程 | 概念全景梳理
因为自己不太懂 AI 相关的一些概念，问了问 AI，看了些文章，然后整理成这篇笔记。本文主要讲 AI 相关的核心概念，以及从用户发出需求开始，背后究竟发生了哪些事。定位偏基础，适合前端 / 全栈工程师建立 AI 工程视角。如有错误，欢迎各位看官不吝指教！🙏🏻
一、先看历史：技术是怎么一步步走到今天的
理解现在，得先知道来路。
很多人第一次接触这些概念时，会以为"向量数据库催生了大模型"——其实顺序正好相反，是大模型的爆火让向量数据库找到了用武之地。把时间线梳理清楚，后面每个概念"为什么存在"就自然而然想明白了。
┌─────────────────────────────────────────────────────────────────────────────┐
│ AI 技术发展时间线 │
├──────────┬──────────────────────────────────────────────────────────────────┤
│ 2017 │ Google 发布论文《Attention Is All You Need》 │
│ │ → Transformer 架构诞生，奠定现代 LLM 的基石 │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ 2018~20 │ BERT（Google）、GPT-1/2/3（OpenAI）相继问世 │
│ │ → 预训练 + 微调范式确立，涌现能力（Emergent Ability）初步展现 │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ 2022.11 │ ChatGPT 发布，LLM 进入大众视野 │
│ │ → 开发者开始大量接入 LLM API，工程化需求爆发 │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ 2022~23 │ 向量数据库（Pinecone / Milvus / Chroma）大规模普及 │
│ │ RAG 范式兴起，旨在解决 LLM 知识过期 & 幻觉问题 │
│ │ LangChain / LlamaIndex 等 Agent 框架相继出现 │
│ │ Cursor 发布（Anysphere，2023），AI 编码工具元年 │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ 2024.11 │ Anthropic 发布 MCP 协议（Model Context Protocol） │
│ │ → 工具调用标准化，Agent 生态走向统一 │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ 2025 │ Claude Code 发布（Anthropic，终端 CLI Agent） │
│ │ → Agent 落地加速，多 Agent 协作成为新议题 │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ 2025.3~4 │ IBM Research 发布 ACP（Agent Communication Protocol） │
│ │ Google 发布 A2A（Agent2Agent）协议，超 50 家厂商联署 │
│ │ → MCP 解决了"Agent 用工具"的问题，这两个协议解决"Agent 找 Agent"│
├──────────┼──────────────────────────────────────────────────────────────────┤
│ 2025.9 │ IBM ACP 正式并入 A2A，纳入 Linux Foundation 统一治理 │
│ │ Zed Industries 同月发布 ACP（Agent Client Protocol） │
│ │ → 前者统一 Agent 间通信；后者定义了编辑器与 Agent 的对接标准 │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ 2026.1 │ ACP Registry 上线，Claude Code / Gemini CLI / Copilot CLI 入驻 │
│ │ → Agent 有了统一分发层，无需在每款编辑器单独发布 │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ 2026.3 │ Claude Code npm 包意外附带 source map，约 51.2 万行 TS 源码公开│
│ │ → 揭示了系统提示词动态拼装机制、工具并行调用、反蒸馏策略等 │
│ │ 内部实现细节，随后被大量镜像存档 │
└──────────┴──────────────────────────────────────────────────────────────────┘
用一句话把上面的链条串起来：
LLM 是地基 → RAG 给 LLM 接入外部知识库，突破知识截止与私域知识的限制 → MCP 让工具调用有了统一标准 → Agent 把大脑、记忆和手脚整合成一个自主系统 → Zed ACP 让智能体与各类 IDE 编辑器实现了无缝对接→ Skills / AGENTS.md 给 Agent 装上了项目规则手册
二、核心概念逐个拆解
2.1 LLM — 大语言模型
LLM（Large Language Model） 是基于 Transformer 架构、经过海量文本预训练的大规模语言模型，代表产品有 GPT-4、Claude、Gemini。
训练目标是预测下一个 token，但通过这种目标学习到了语言结构、知识和推理能力——通过对海量人类文本的学习，把语法、逻辑、常识都压缩进数百亿个神经网络参数（Weights）里。这些参数在训练完成后就固定下来，模型"出厂"后不会自动更新。
交互模式极其简单：
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
│ Prompt In │ ────► │ LLM 推理引擎 │ ────► │ Text Out │
│ （输入） │ │ 理解 · 推理 · 生成│ │ （输出） │
└─────────────┘ └──────────────────┘ └─────────────┘
把 LLM 理解成大脑是一个很贴切的比喻——它能理解你说的话、写代码、做逻辑推理。但光有大脑还不够，它不能主动翻文件、执行命令、访问网络，这些能力需要外部系统配合，这也是 RAG、MCP、Agent 存在的根本原因。
LLM 是如何理解自然语言的？
LLM "理解"语言并非真的像人类一样读懂含义，而是一套数学流程：将文字逐步转化为高维数值，再通过注意力机制（注意力是核心但不是唯一组件）捕获词语之间的关联。整个过程分为四步：
① 分词（Tokenization）
┌─────────────────────────────────────────────────┐
│ 原始文本："今晚想吃点清淡的" │
│ ↓ Tokenizer（分词器） │
│ Token 序列：["今晚", "想", "吃", "点", │
│ "清", "淡", "的"] │
│ 每个 Token 映射到一个整数 ID │
└─────────────────────────────────────────────────┘
② 向量化（Embedding）
┌─────────────────────────────────────────────────┐
│ 每个 Token ID → 高维浮点向量 │
│ "清淡" → [0.23, -0.81, 0.44, ...]（768~4096 维）│
│ │
│ 注意，这里不是"找相似文档"（那是 RAG 的逻辑） │
│ 向量只是为下一步注意力计算做数学准备 │
└─────────────────────────────────────────────────┘
③ 注意力计算（Self-Attention）— Transformer 核心
┌─────────────────────────────────────────────────┐
│ 模型对每个 Token 计算它与其他所有 Token 的 │
│ "相关程度"（注意力权重） │
│ │
│ "清淡" 会把注意力集中到 "吃" 和 "今晚" 上 │
│ → 理解这不是"性格清淡"，而是"口味清淡" │
│ │
│ 多头注意力（Multi-Head Attention）： │
│ 同时从多个维度捕获语义、句法、指代等不同关系 │
└─────────────────────────────────────────────────┘
④ 自回归生成（Auto-regressive Generation）
┌─────────────────────────────────────────────────┐
│ 基于以上所有上下文，预测"下一个 Token"的概率分布 │
│ → 采样 / 取最高概率 → 追加到序列 → 再次预测 │
│ → 循环生成："可以试试粥、蒸鱼或者豆腐汤……" │
│ → 直到生成 <EOS>（结束符） │
└─────────────────────────────────────────────────┘
💡 LLM 本质上在做的事是：从海量文本中学习"哪些词在什么语境下应该出现在一起"，然后在推理时根据上下文，给出统计上最合理的续写。它没有主观理解，但因为训练数据足够大，涌现出了很强的"仿理解"能力。
LLM 的固有局限：
| 缺陷 | 说明 |
|---|---|
| 知识截止（Knowledge Cutoff） | 训练数据有时间截止点，对最新事件一无所知 |
| 幻觉（Hallucination） | 可能生成看起来合理但实际错误的内容 |
| 领域知识不足 | 企业私有文档、内部代码库完全不了解 |
| 上下文窗口有限 | 单次推理能处理的文本量存在上限 |
| 推理成本高 | 按 token 计费，长对话成本显著 |
正是这些局限，推动了后续一系列工程技术的诞生。
2.2 Prompt — 提示词
Prompt 就是你发给模型的输入内容。它不只是一句话，而是模型"看到"的全部信息的总称——包括角色定义、背景上下文、任务指令和输出格式要求。
┌──────────────────────────────────────────────────────┐
│ 一个完整的 Prompt │
├─────────────────────┬────────────────────────────────┤
│ System Prompt │ 角色定义、能力边界、输出格式 │
│ （系统提示词） │ 行为约束、禁止项 │
├─────────────────────┼────────────────────────────────┤
│ History │ 历史对话记录（多轮上下文） │
│ （对话历史） │ │
├─────────────────────┼────────────────────────────────┤
│ Context │ RAG 检索到的相关文档片段 │
│ （增强上下文） │ 当前项目代码 / 文件内容 │
├─────────────────────┼────────────────────────────────┤
│ User Query │ 用户当前的问题 / 需求 │
│ （用户输入） │ │
└─────────────────────┴────────────────────────────────┘
模型给出的答案质量，很大程度上取决于 Prompt 的质量，这也是「提示词工程（Prompt Engineering）」这个方向存在的原因。同一个需求，描述得越清晰、上下文越充分，模型的输出就越准确。
2.3 Token 与 Context Window
Token
中国发展高层论坛2026年会上，国家数据局局长刘烈宏也给出了token的中文官方翻译：词元
Token 是模型内部处理文本的最小单位，可以理解为"子词"。不同模型的 tokenizer 分词规则有差异，大致参考：
- 英文单词：
running≈ 1 token - 中文汉字：1 个汉字 ≈ 1~2 token（视 tokenizer 而定）
- 常见短语可能被合并为 1 个 token
💡 费用计算 = 输入 token 数 + 输出 token 数，发送的 Prompt 和模型返回的文本都算在内。可用
tiktoken（OpenAI）等工具库在本地预估消耗。
Context Window（上下文窗口）
上下文窗口是模型单次推理能"看到"的最大 token 数量，等同于它的工作记忆——不仅仅是当前这一条消息，而是所有塞进去的内容总和：
┌──────────────────────────────────────────────────────────────────────┐
│ Context Window │
│ │
│ System │ 对话 │ RAG 检索 │ 工具返回 │ 当前输入 │ 输出 │
│ Prompt │ 历史 │ 上下文 │ 结果 │ │ 预留 │
│ │
│ ◄──────────────── 最大 Token 限制（不同模型不同）────────────────► │
└──────────────────────────────────────────────────────────────────────┘
主流模型上下文窗口参考（2026年年初）：
| 模型类别 | 模型名称 | 上下文窗口 (Context Window) | 备注 |
|---|---|---|---|
| OpenAI | GPT-5.2 (Garlic) | 400K tokens | 相比 GPT-4o 提升了 3 倍以上，输出长度大幅增至 128K |
| GPT-5 | 400K tokens | 2026 标准旗舰版，强化了 Agent 执行能力 | |
| Anthropic | Claude Opus 4.6 | 1M tokens (Beta) | Opus 级模型首次支持百万级上下文，默认 GA 版本为 200K |
| Claude 4.6 Sonnet | 1M tokens (Beta) | 兼顾速度与长文本，支持上下文压缩 (Context Compaction) | |
| Claude 4.5 Haiku | 200K tokens | 依然保持极高的性价比和响应速度 | |
| Gemini 3 Pro | 1M - 2M tokens | 视频与超大规模工程代码库处理的标杆 | |
| Gemini 3 Flash | 1M tokens | 在长文本检索（Needle In A Haystack）中表现极稳 | |
| 国产模型 | Kimi K2.5 (Reasoning) | 2M - 10M tokens | 月之暗面依然在长文本领域保持量级领先 |
| DeepSeek-V3 | 128K - 256K tokens | 极致性价比，在长文本内检索的精度极高 | |
| 通义千问 Qwen 3.5 | 1M tokens | 阿里云最新旗舰，对大规模代码库的对齐效果出色 | |
| 豆包 (Doubao-Seed-Code) | 256K tokens | 字节跳动针对编程场景优化的长文本版本 |
当对话内容超出窗口上限时，Agent 通常会采用两种策略兜底：
- 滑动窗口（Sliding Window）：丢弃最早的对话轮次，只保留最近 N 条
- 自动摘要（Auto Summary）：把早期对话压缩成摘要，保留语义而非原文
2.4 Vector Embeddings — 向量嵌入
向量嵌入（Vector Embeddings） 是把文本、图片等非结构化内容，转换为一组高维数值数组的过程。这个数组就是"向量"，由 Embedding 模型生成，维度一旦确定就固定不变。
为什么需要向量？因为计算机无法直接比较两段文字的"语义相似度"，但可以计算两个向量的距离（余弦相似度 / 欧氏距离）。Embedding 的核心意义就是：把语义相似的内容，映射到向量空间中相近的位置。
文本空间（无法直接比较语义） 向量空间（可以度量距离）
┌──────────────────────┐ ┌────────────────────────────────┐
│ "今天天气真好" │ │ [0.82, -0.31, 0.56, ...] ◄──┼─ 距离近
│ "阳光明媚的一天" │ Embed ► │ [0.79, -0.28, 0.61, ...] ◄──┼─ 语义相似
│ "股票大跌了" │ │ [-0.44, 0.91, -0.20, ...] ◄──┼─ 距离远
└──────────────────────┘ └────────────────────────────────┘
💡 向量的每一个维度本身没有具体含义，是神经网络在训练过程中自动学习到的抽象语义特征，单个维度通常不可解释，但整体空间具有语义结构，且维度数由 Embedding 模型决定（固定不变，如 text-embedding-3-small 输出 1536 维）。
2.5 Vector Database — 向量数据库
向量数据库（如 Milvus、Pinecone、Qdrant，本地可用 Chroma）是专门为高效相似度检索而设计的存储层，支持 ANN（近似最近邻）算法，能在毫秒级别从海量向量中找到最相似的 K 个结果。
它的存储结构很简洁，核心就三个字段：唯一 ID、向量数组、原始内容或元数据。
// 基础结构（以 Qdrant 字段命名为例）
{
"id": "doc_12_chunk_3",
"vector": [0.012, -0.88, 0.34, ...], // Embedding 模型生成的高维向量
"payload": {
"text": "LangChain 是一个 LLM 应用框架...",
"source": "langchain.pdf",
"chunk_index": 3,
"created_at": 1710000000
}
}
💡 存储策略：小文本直接放在 payload 里；大文本存关系型数据库，向量库只存 ID 引用，避免单条记录过大影响检索性能。
向量数据库能存哪些东西：
| 类别 | 示例 |
|---|---|
| 文档知识库 | 技术文档、产品手册、法律条文 |
| 对话历史 | 用户历史对话的语义摘要 |
| 企业内部知识 | 内部 Wiki、会议记录、邮件摘要 |
| 代码库 | 函数、类的代码块及注释 |
| 网页内容 | 爬取并切块后的网页段落 |
| 用户画像 | 用户偏好、行为模式的向量表示 |
| 多模态内容 | 图片 / 视频的文本描述向量 |
数据库膨胀的管理策略：
随着时间推移，向量数量会持续增长，常用三种策略控制规模：
- 滑动窗口（Sliding Window）：只保留最近 N 天的数据，到期删除
- 重要性降权（Importance Decay）：旧向量降低检索权重而非直接删除，保留但弱化影响
- 分层存储（Tiered Storage）：近 7 天热存储、7~30 天温存储、30 天以上归档，按访问频率分层
此外，随着数据量增大，可通过分片、倒排索引、聚类等技术解决性能扩展问题——这不是简单的二维坐标检索，而是有一整套工程体系支撑的。
2.6 RAG — 检索增强生成
RAG（Retrieval-Augmented Generation，检索增强生成） 是一种独立的技术范式，可以单独使用（比如企业知识库问答系统），也常作为 Agent 的检索模块集成。它的核心思路是：先检索，再生成——在调用 LLM 推理之前，先从外部知识库拉取相关内容，一起塞进 Prompt，让模型"有据可查"地回答，而不是靠训练时的记忆凭空生成。
RAG 分为两个阶段，时序上完全分离：
━━━━━━━━━━━━━━━━━━━━━━ 阶段一：知识库构建（离线，一次性） ━━━━━━━━━━━━━━━━━━━━━━
原始数据源 文档解析 Chunk 切分
┌──────────┐ ┌──────────┐ ┌──────────┐
│ PDF / MD │ │ 文字 │ │ 段落切块 │
│ 代码/Wiki │ ─────► │ 提取 │ ─────►│(~512 tok)│
└──────────┘ └──────────┘ └────┬─────┘
│
Embedding 模型向量化
│
▼
┌──────────┐
│ Vector DB│ ← 写入，离线完成
└──────────┘
━━━━━━━━━━━━━━━━━━━━━━ 阶段二：知识查询（在线，每次请求） ━━━━━━━━━━━━━━━━━━━━━━
用户提问 临时向量化（只读） 相似度检索 精排
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│"如何使用 │ │ Embedding│ │ top-k │ │Reranker │
│ Vue 3 │ ─────► │（不写入 │ ─────► │ 相关文档 │ ─────► │ 精排打分 │
│ 响应式？"│ │ DB） │ │ │ └────┬─────┘
└──────────┘ └──────────┘ └──────────┘ │
┌────────▼───────┐
│ 拼入 Prompt │
│ 送给 LLM 生成 │
└────────────────┘
知识库由谁来建，什么时候建？
离线构建阶段与大模型训练完全解耦——模型只提供理解和生成能力，知识库由使用方自己负责。开发者或企业在拿到模型 API 之后，根据自身业务需求，随时可以构建或更新知识库。
两个例子：
Cursor（编程场景） 开发者打开一个项目后，Cursor 会在本地实时扫描代码文件，自动完成切片、向量化，并存入本地临时索引。目的是让模型"读懂"你当前的项目上下文——当你问"这个函数在哪里被调用"时，模型能基于你的真实代码回答，而不是凭空猜测。这里知识库的内容就是你自己的项目，每个用户的库都不一样，构建过程对用户无感，自动发生。
企业内部问答（非编程场景） 某保险公司想让员工能用自然语言查询内部理赔规则。IT 团队将数百份 Word 版本的操作手册、产品条款导入系统，完成切片和向量化后存入向量数据库。此后员工提问"轻症赔付比例是多少"，系统先从库里检索相关条款，再交给模型组织成自然语言回答。知识库可以随着文件更新而重新构建，无需重新训练模型。
💡 在线查询阶段，用户问题会被临时向量化用于检索，这个向量不会写入数据库，只是一次性的检索 key。写入操作仅发生在离线的构建阶段。
Top-K 文档是什么？
在相似度检索这一步，系统会把用户问题的向量与知识库中所有文档 Chunk 的向量逐一比较相似度（余弦相似度等），然后按相似度从高到低排序，取出得分最高的前 K 个文档片段，这就是 Top-K 文档。
向量数据库中有 10000 个 Chunk (当询问 "番茄炒蛋怎么做才好吃")
─────────────────────────────────────────────────────
相似度排名 │ Chunk 内容摘要 │ 相似度得分
─────────────────────────────────────────────────────
#1 │ 番茄炒蛋的家常做法 │ 0.94
#2 │ 番茄的挑选与去皮技巧 │ 0.91
#3 │ 鸡蛋嫩滑的火候控制方法 │ 0.87
··· │ ··· │ ···
#10000 │ 红酒醒酒时间与温度指南 │ 0.03
─────────────────────────────────────────────────────
Top-K（K=3）→ 取 #1 #2 #3，拼入 Prompt 交给 LLM
K 值是一个可调参数，通常取 3~10。K 越大，检索到的上下文越丰富，但也会消耗更多 Context Window 空间并引入噪音；K 越小，精准度高但可能遗漏关键信息。以菜谱场景为例，K=3 只取番茄炒蛋最核心的三条内容，K=8 则可能额外纳入"鸡蛋的营养成分"或"番茄的品种介绍"——相关但未必有用。
实际工程中通常还会在 Top-K 后接一个 Reranker（精排模型），对这 K 个候选片段做二次评分重排，进一步提升最终送入 LLM 的文档质量。
在菜谱问答场景下，RAG 的"检索"就是：接收到你的问题后，扫描整个菜谱知识库，找到相关的食材处理、烹饪步骤和火候技巧，作为上下文一起发给模型——这是模型能给出"符合你口味和实际情况"的具体建议，而不是泛泛而谈的根本原因。
⚠️ RAG 并不总是有效：检索失败的常见原因
虽然 RAG 能显著提升回答的准确性，但在实际工程中，检索效果高度依赖数据处理质量，常见问题包括：
-
Embedding 不准确:
-
使用的 embedding 模型与业务语料不匹配
-
导致语义相似内容无法被正确召回
-
-
Chunk 切分不合理
- 切分过大 → 引入噪音
- 切分过小 → 语义不完整
- 都会影响检索质量
-
Top-K 噪音问题
- K 值过大 → 引入不相关内容
- K 值过小 → 可能遗漏关键信息
-
Query 表达问题
- 用户问题本身语义模糊
- 导致 embedding 后偏离真实意图
💡 因此，RAG 的效果本质上是一个“数据工程问题”，而不仅仅是模型能力问题。
2.7 MCP — 模型上下文协议
MCP（Model Context Protocol） 是 Anthropic 于 2024 年 11 月发布的开放协议，定义了 Agent 与外部工具之间的通信标准。打个比方：USB 出现之前，每个设备都要配专属接口；MCP 做的是同一件事，只是连接的对象变成了 AI 和各类工具。 有了 MCP，文件系统、GitHub、数据库这些工具只需实现一次 MCP Server，任何支持 MCP 的 Agent 就能直接接入，不用每家 IDE 自己再实现一遍。
MCP = 工具 / 系统 与 LLM 之间的统一通信标准
MCP 三层架构
┌───────────────────────────────────────────────────────────────────┐
│ Host（主机） │
│ 运行环境 Cursor / VS Code / Claude Code │
│ · Agent 的载体，用户交互的 UI 界面 │
│ · 协调和管理多个 Client 实例 │
└───────────────────────────┬───────────────────────────────────────┘
│ 管理（1 Host : N Client）
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ...
│ Client A │ │ Client B │
│ 大模型的"网卡" │ │ 大模型的"网卡" │
│ · 转发 tool_call │ │ · 转发 tool_call│
│ · 回传执行结果 │ │ · 回传执行结果 │
└────────┬─────────┘ └────────┬─────────┘
│ 1:1 连接 │ 1:1 连接
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Server A │ │ Server B │
│ 文件系统插件 │ │ GitHub 插件 │
│ read/write_file │ │ clone/push/PR │
└──────────────────┘ └──────────────────┘
MCP Host（宿主）：发起连接并消费工具能力的应用程序实体。
MCP Client（客户端）：Host 内部用于建立 MCP 协议连接、执行具体通信逻辑的实现模块。
MCP Server（服务端）：提供具体能力（如本地文件系统、数据库访问、GitHub API 等）的外部独立程序。
Host 负责整个生命周期
三层结构里，Host 不只是"UI 界面"，它还是整个 MCP 运行环境的管理者。用户打开 Cursor 时，Host 会读取配置文件，把需要的 Server 作为子进程在后台拉起来，同时创建对应的 Client 实例与之建立连接——这一切对用户无感。用户关闭编辑器时，Host 也负责断开连接、回收所有 Server 进程。Agent 本身不管这些，它只管"通过 Client 要结果"。
Server 有两种形态：一种是 Host 启动的本地子进程（Stdio 通信），生命周期完全跟着 Host；另一种是远程独立部署的服务（HTTP/SSE 通信），Host 只负责连接，不负责启动和关闭。
如果某个工具因环境原因无法使用——比如系统缺少依赖、API Key 未配置——规范的 Server 会在启动阶段做环境检测，不满足条件的工具直接不注册进列表，Client 拿到的 tools/list 就不会包含它。若工具已暴露但执行时才报错，Server 会返回标准错误，由 Host 或 Agent 决定下一步：重试、换工具或提示用户。
你可以开发自己的server服务，但是需要满足MCP相应的规定，因为MCP是业界普遍采用的通信协议。现在各类场景基本都有对应的server了(比如filesystem，GitHub / GitLab， Puppeteer)，开发者和大厂也在持续的贡献新的server
通信协议（JSON-RPC 格式）：
{
"method": "tools/call",
"params": {
"name": "write_file",
"arguments": { "path": "src/app.js", "content": "..." }
}
}
MCP 支持两种传输机制：
| 传输方式 | 适用场景 | 特点 |
|---|---|---|
| Stdio（标准输入输出） | 本地进程通信 | 性能最优，无网络开销，通常 1:1 服务单个 Client |
| HTTP / SSE（流式） | 远程工具调用 | 支持多 Client 并发连接，适合云端部署的 MCP Server |
MCP Server 支持的工具能力（举例）：
文件系统 read_file(path) / write_file(path, content) / list_dir(path)
终端执行 run_shell(cmd) ← 必须在安全隔离环境下运行
Git 操作 clone / commit / push / create_pr
HTTP 请求 http_get(url) / headless 浏览器（处理动态页面）
向量检索 vector_search(query_embedding, top_k)
数据库 直接连接 DB 驱动执行 SQL
CI/CD 调用云 provider SDK（aws cli、gcloud 等）
代码执行 code_executor(code, language)
双向工作流（Sampling）： MCP 还支持"反向请求"——Server 可以发起对 LLM 的调用请求，实现更复杂的递归 Agent 行为：
正向（工具调用）： Host ──► Client ──► Server（执行工具）
反向（Sampling）： Server ──► Client ──► Host ──► LLM（发起 LLM 推理）
实现 MCP Server 常用的工具库：
- 系统操作：
subprocess/child_process（执行 Shell），os/pathlib（文件系统） - HTTP：
requests/httpx（Python），axios/fetch（JavaScript） - 云服务：
boto3（AWS）、google-cloud-*（GCP）、paramiko（SSH） - 浏览器自动化：Playwright、Puppeteer、Selenium
2.8 Guardrails — 护栏
高速公路的护栏是为了防止车辆偏离轨道。AI 里的护栏，是为了防止模型的输入和输出偏离安全、合规、准确的边界。它既是概念，也是工程上的独立模块，通常集成在 Agent 或平台层中。
Guardrails 覆盖整条链路，从用户输入到最终输出都有介入：
用户输入
│
▼
┌─────────────────────────────────────────────────────┐
│ 输入层（pre-prompt） │
│ 敏感词过滤 · 注入攻击检测 · 格式校验 │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 工具声明层 │
│ 白名单约束可调用工具 · 参数类型校验 │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 模型交互层（runtime） │
│ tool_call 权限校验 · 高危命令二次确认 │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 后处理层（post-generation） │
│ 规则匹配 · 合规检查 · 敏感数据过滤 │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 审计层 │
│ 记录所有调用日志，支持人工审计与回滚 │
└─────────────────────────────────────────────────────┘
按作用分类（参考 McKinsey 框架）：
| 类型 | 作用 |
|---|---|
| 适当性（Appropriateness） | 检测内容是否有毒、有害、带偏见，拦截不当内容 |
| 幻觉（Hallucination） | 确保生成内容不含事实错误或误导性信息 |
| 合规性（Regulatory-compliance） | 验证内容是否符合行业监管要求 |
| 对齐（Alignment） | 确保输出不偏离用户的原始意图 |
| 验证（Validation） | 检查内容是否满足特定标准，可触发修正循环 |
四个核心组件：
- Checker（检查器）：扫描 AI 生成内容，检测错误并标记问题
- Corrector（校正器）：Checker 发现问题后，对输出进行润色和修正
- Rail（轨道）：管理 Checker 与 Corrector 的交互循环，未达标则反复触发修正
- Guard（守卫）：统筹协调以上三者，汇总结果，输出最终内容
2.9 AI Agent — 智能体
前面提到，LLM 本身只能"问答"，它不会主动做事。AI Agent 就是在 LLM 之上构建的自主系统，赋予了模型"主动推进任务"的能力。
在当前主流的大模型技术架构中，Agent（智能体）通常被定义为：以大语言模型（LLM）为核心推理引擎，具备自主规划（Planning）、记忆（Memory）以及工具调用（Tool Use / Action）能力的程序实体。
AI Agent = LLM（大脑）
+ Memory（记忆） ← Context Window（短期）+ Vector DB（长期）
+ Tool Layer / MCP（手脚）← 文件读写、终端、网络、Git...
+ Planning & Execution ← 拆解目标、循环执行、自我纠错
一个典型的例子：输入"帮我实现用户登录逻辑"
用户输入："帮我实现用户登录逻辑"
│
▼
① 感知 & 理解：读取项目结构，了解技术栈和现有代码
│
▼
② 规划：拆解任务步骤 → 选择需要调用的工具
│
▼
③ 执行工具调用：
read_file("src/router/index.ts") → 了解现有路由结构
read_file("src/types/user.ts") → 了解用户类型定义
write_file("src/api/auth.ts", ...) → 生成认证 API 层
write_file("src/views/Login.vue", .) → 生成登录页面
│
▼
④ 观察 & 反馈：
run_shell("npm run build") → 验证编译
→ 发现类型错误 → 自动修复 → 再次验证
│
▼
⑤ 任务完成 or 继续下一轮循环
这个 "感知 → 规划 → 执行 → 观察 → 反馈" 的循环，叫做 ReAct（Reasoning + Acting）框架，是 Agent 行动的基本模式，可能循环多轮直到任务完成或触发终止条件。
Agent 内部模块结构：
┌────────────────────────────────────────────────────────────────────┐
│ Agent Runtime │
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌──────────────────────┐ │
│ │ Planner │ │ Router │ │ Memory │ │
│ │ │ │ │ │ │ │
│ │ · 分解任务 │ │ · 直接回答？ │ │ · short-term │ │
│ │ · 制定步骤 │ │ · 需要 RAG？ │ │ (Context Window) │ │
│ │ · 选择工具 │ │ · 需要工具？ │ │ · long-term │ │
│ └───────────────┘ └───────────────┘ │ (Vector DB / 文件) │ │
│ └──────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Tool Manager │ │
│ │ · 维护可用工具列表（tool schema） │ │
│ │ · 通过 MCP Client 发起工具调用，接收执行结果 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Prompt Builder │ │
│ │ System Prompt + 对话历史 + RAG 文档 + 工具结果 + 用户输入 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────┘
Agent 目前已具备多模态能力，能查看图片内容、读取代码截图。音频、视频等模态的支持也在持续推进中。
2.10 Skills — 技能规范文件
Skills 是一种「技能能力包」，让 AI 编程助手理解某个技术、规范、工具或最佳实践的正确使用方式，并在必要时直接执行相关工具。它的工作方式是按需加载——Claude 判断当前任务与哪些 Skill 相关，再动态载入对应内容，避免无效占用上下文。
一个 Skill 本质上是一个文件夹，由三个核心部分构成：
- 指令（Instructions）：核心文件
SKILL.md，包含 YAML frontmatter（定义名称、描述及触发条件）和 Markdown 正文（编码标准、最佳实践、API 正确用法及需规避的坑） - 脚本（Scripts）：可直接运行的自动化脚本，让 Claude 不只是「读规则」，还能「跑工具」——比如检测依赖版本、执行格式化、生成模板文件等
- 资源（Resources）：
references/目录下的参考文档、API 手册、示例代码，作为 Claude 的上下文补充知识
说人话就是：当我写 Vue 项目时，Claude 会参考我给的 Vue 规则集（API、写法推荐、最佳实践）来给方案，而不是靠训练时学到的旧知识；遇到需要自动化的任务，它还可以直接调用 Skill 内置的脚本来执行。
Agent Skills 是由 Anthropic 主导推动的开放标准，规范发布在 agentskills.io，这意味着按此标准创建的 Skill 不局限于 Claude，支持该标准的其他 AI 平台和工具同样可以复用。Anthropic 官方在 anthropics/skills 仓库中维护了一批示例和生产级 Skill 实现，涵盖文档创建、数据分析、企业工作流等场景，可直接取用或作为自定义 Skill 的参考。社区开源项目 antfu/skills（由 Vue 核心团队成员 Anthony Fu 发起）则将规则文件打包成 npm 包，方便前端开发者复用现成规范，无需从头搭建。
Skills 支持三种来源：
- Anthropic 官方 Skill：由 Anthropic 维护，在 Claude 中自动触发，无需手动安装（如 Word、Excel、PDF 文档能力）
- 自定义 Skill：由个人或团队编写，用于封装特定业务规范、数据分析流程或个人工作习惯
- 合作伙伴 Skill：来自 Notion、Figma、Atlassian 等第三方，与对应 MCP 连接器配合使用，实现集成工作流
创建一个最简 Skill 只需一个带 frontmatter 的 SKILL.md 文件：
---
name: vue-best-practices
description: 当项目使用 Vue 3 时加载，提供 Composition API、script setup 及响应式 API 的最佳实践
---
# Vue 3 最佳实践
## 组件写法
- 优先使用 `<script setup>` 语法
- 使用 `defineProps` 和 `defineEmits` 替代选项式写法
## 响应式
- 对象/数组用 `reactive()`，基础类型用 `ref()`
- 避免直接解构 reactive 对象，使用 `toRefs()`
frontmatter 中只有两个必填字段：name（唯一标识符）和 description（同时作为 Claude 判断是否激活该 Skill 的依据）。对于需要执行能力的 Skill，可在文件夹中额外附加脚本文件。
以 antfu/skills 为例，安装使用方式如下：
# 安装 vue、vite、vue-best-practices 三个 skill
# 正确写法
npx skills add antfu/skills --skill vue --skill vite --skill vue-best-practices
安装时会交互式询问你要支持哪些 Agent，根据选择生成对应目录：
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ──────────────
│ • Amp • Codex • Cursor • Gemini CLI
│ • GitHub Copilot • Kimi Code CLI • OpenCode
│
│ ── Additional agents ─────────────────────────
│ ❯ ● Claude Code (.claude/skills)
│ ○ Cline (.cline/skills)
│ ○ Continue (.continue/skills)
│ ↓ 24 more
└
安装后生成的目录结构：
.agents/skills/ ← 通用目录，Cursor / Copilot / Codex / Gemini CLI 等都读这里
├── vue/
│ ├── references/ ← 资源：API 手册、示例代码
│ │ ├── core-new-apis.md
│ │ ├── advanced-patterns.md
│ │ └── script-setup-macros.md
│ ├── scripts/ ← 脚本：可运行的自动化工具
│ │ └── check-version.sh
│ └── SKILL.md ← 指令：规范约束 + 触发条件
└── vite/
├── references/
│ └── core-features.md
└── SKILL.md
.claude/skills/ ← Claude Code 专用目录（部分 Agent 有独立目录）
可以把 Skill 理解为：给 Agent 的工作手册 + 工具箱——既告诉它「在这个项目里该怎么写代码」，也给它可以直接调用的工具完成自动化任务，还会在恰当时机自动激活，而不是始终占用上下文。
2.11 ACP — 智能体客户端协议
ACP（Agent Client Protocol） 是 Zed Industries 于 2025 年 9 月发布的开放标准，定义了编辑器与 AI Agent 进程之间的标准通信接口。
先说一个容易踩的坑：ACP 这个缩写同期有两个不同协议在用，语境不同含义完全不同。本文这里的 ACP 是 Zed 的 Agent Client Protocol，解决的是编辑器和 Agent 怎么对接的问题；IBM Research 的 Agent Communication Protocol 缩写也是 ACP，但解决的是 Agent 和 Agent 怎么通信的问题，已在 2025 年 9 月并入了 Google 的 A2A。
理解 ACP 最快的方式是类比 LSP（Language Server Protocol）。2016 年，LSP 把语言智能从单体 IDE 里抽离出来，每个语言工具只需实现一次，就能接入所有编辑器。ACP 想在 AI Agent 时代做同样的事：让 Agent 和编辑器各自只实现一次接口，然后任意组合。
没有 ACP 的时候，Cursor 有自己的 Agent Engine、VS Code 有自己的 Copilot 实现，互不通用，N 个编辑器 × M 个 Agent = N×M 套独立集成。ACP 出现后变成了加法，不是乘法。
没有 ACP：N 个编辑器 × M 个 Agent = N×M 套独立集成。 有了 ACP：N 个编辑器 + M 个 Agent = N+M 套实现。
ACP 的另一个价值在于统一了 Agent 的输出语义，定义了几种标准消息类型： - diff：代码变更块，编辑器直接渲染成 diff 视图 - stream chunk：流式推理内容，实时展示 Agent 思考过程 - tool request：Agent 申请执行工具，等待编辑器授权 - diagnostic：诊断信息，与编辑器的报错体系对接 无论底层 Agent 是谁，用户看到的交互体验保持一致。
两种工程场景
场景 A — 高度集成型（Cursor / Windsurf）
[ Cursor 进程 ]
Editor Core
└── Agent Engine（内置，与 Editor 同进程）
└── 工具调用层（进程内直接调用，不需要 ACP）
场景 B — 彻底解耦型（Zed + Claude Code）
[ Zed 进程 ] [ Claude Code 进程 ]
Editor Core Agent Engine
ACP Client ◄──────────────► ACP Server（兼任 MCP Host）
(发起请求) JSON-RPC (处理请求 + 管理工具调用)
│
外部工具（文件/GitHub...）
Zed 的方案里，Agent 是真正独立的进程，编辑器和 Agent 可以分别升级，互不干扰。Cursor 那种内嵌方式性能更优，代价是 Agent 和编辑器绑死了，换 Agent 就得换整个 IDE。
ACP 与 MCP 的关系
两个协议解决不同层级的问题，相互独立：
| 协议 | 连接方 | 解决什么 |
|---|---|---|
| MCP | Agent ↔ 工具/数据源 | Agent 怎么调用外部工具 |
| ACP | 编辑器 ↔ Agent | 编辑器怎么跟 Agent 对话 |
实际工作流：编辑器通过 ACP 把任务发给 Agent → Agent 通过 MCP 调用工具 → 工具结果回传 → Agent 整理后经 ACP 返回 diff，编辑器渲染。两层协议各司其职，ACP 不感知、也不依赖 MCP，只是当前主流 Agent 恰好都用 MCP 做工具层，所以经常同时出现。
生态现状（截至 2026 年初）
2026 年 1 月，ACP Registry 上线，解决了 Agent 的分发问题。之前 Agent 需要在每款编辑器单独发布扩展，有了 Registry，提交一次就能被所有兼容编辑器发现和安装，类似 npm 对 Node 生态的作用。
目前已入驻的 Agent 包括 Claude Code、Gemini CLI、Codex CLI、GitHub Copilot CLI、Cline、OpenCode、Goose 等；支持的编辑器有 Zed（协议发起方）、JetBrains 全系、Neovim（通过 CodeCompanion / avante.nvim）、marimo 等。
2.12 其他词汇
Vibe Coding（氛围编程） 一种以自然语言为主导的编程方式：开发者用日常语言描述想要实现的功能，由 AI 自动生成对应代码，开发者的核心工作从"写代码"转变为"审查代码、纠正方向"。它不要求你逐行手写，而是更像在给 AI 当"产品经理"——你负责提需求和把关，AI 负责实现。名字里的"氛围"，指的是这种模糊但有方向感的协作状态。
Multimodal（多模态） 指 AI 模型能同时理解和处理多种类型信息的能力，包括文字、图片、音频、视频等。传统模型往往只能处理一种类型（如纯文字），而多模态模型可以做到"看图说话"、"听录音总结"等跨类型任务。GPT-4o、Claude 3、Gemini 等主流模型均已支持图文混合输入。
Fine-tuning（微调） 大模型经过海量数据的预训练后，已具备通用能力，但在特定领域（如医疗、法律、客服）可能表现不够精准。微调就是在这个基础上，用该领域的专属数据对模型进行"二次训练"，让它在特定场景下表现得更专业、更符合需求。可以类比为：通用大学毕业生入职后接受的岗位专项培训。
Distillation / Knowledge Distillation（知识蒸馏） 一种模型压缩技术。核心思路是：用一个能力强但体积大的"教师模型"来指导训练一个更小、更轻量的"学生模型"，让小模型尽量学到大模型的推理能力，同时大幅降低计算成本和部署门槛。结果是：小模型的体积可能只有大模型的几十分之一，但在很多任务上仍能达到接近的效果。DeepSeek-R1 就采用了这一技术。
三、项目中的上下文配置文件
这些文件的共同目的只有一个：为 Agent / 模型提供额外上下文、规范和快速索引，减少模型反复推断、猜测项目规则的成本。
┌────────────────────────────────────────────────────────────────┐
│ 项目配置文件 · 作用层级 │
├────────────────────┬───────────────────────────────────────────┤
│ llms.txt │ 三方库级别：告知 AI 哪里找最新文档 │
├────────────────────┼───────────────────────────────────────────┤
│ AGENTS.md │ 项目级别：构建命令、规范、约定 │
├────────────────────┼───────────────────────────────────────────┤
│ CLAUDE.md │ 工具级别：特定 Agent 的偏好配置 │
│ .cursorrules │ │
├────────────────────┼───────────────────────────────────────────┤
│ .agents/skills/ │ 技术栈级别：框架 API 规范和最佳实践 │
└────────────────────┴───────────────────────────────────────────┘
AGENTS.md
专门给 AI 编码 Agent 看的项目说明文件，类似"AI 专用 README"，聚焦机器执行的细节：构建命令、测试流程、代码风格规范、commit message 格式等。Agent 启动时会优先读取，避免反复询问或靠训练知识猜测项目约定。
可分层嵌套使用——在 monorepo 的子包目录里也可以放 AGENTS.md，Agent 会优先使用距当前编辑文件最近的那一个。
llms.txt / llms-full.txt
为大语言模型优化的依赖库文档索引文件，以简洁 Markdown 格式提供结构化清单，告知 AI 哪里能找到该库的 API 文档、最佳实践和核心架构说明。
当你的项目用到某个库时，AI 会读取该库的 llms.txt，确保使用的是最新 API 而非训练数据里的旧版本。（还记得 Tailwind CSS 因流量经济考虑拒绝添加 llms.txt 的 PR 吗？😂）
CLAUDE.md / Copilot Instructions
针对特定 Agent 的默认上下文和指令集，用于持久化用户的偏好配置——比如"所有组件必须用 <script setup> 语法"、"禁止使用 any 类型"等。
.cursorrules / .skills
工具特有的规则文件，在特定环境下约束 Agent 的自动行为。例如 .cursorrules 可强制要求"使用 TypeScript 严格模式"、"禁止直接操作 DOM"、"组件必须放在 src/components 目录下"。
四、Agent 完整交互流程
掌握了前面所有概念后，来看一次完整的 Agent 执行过程究竟是什么样的。
前提：向量数据库已完成离线知识库构建；Agent 启动时已将 AGENTS.md 内容注入 System Prompt；MCP Client 已初始化并与各 MCP Server 建立连接。
一个典型的Agent 架构如下：
┌─────────────────────────────────┐
│ 客户端层（IDE / UI） │ ← 用户交互、结果渲染
├─────────────────────────────────┤
│ 编排层（Orchestrator） │ ← 调度核心：驱动整条流程
│ · 触发输入护栏 │
│ · 调用记忆服务 │
│ · 调用语义路由 │
│ · 构建 Prompt │
│ · 驱动 ReAct 循环 │
│ · 管理工具权限与调用 │
│ · 触发输出护栏 │
│ · 触发记忆写回 │
├─────────────────────────────────┤
│ 模型层（LLM） │ ← 纯推理，无主动 IO 能力
├─────────────────────────────────┤
│ 工具层（MCP Server） │ ← 物理执行各类工具
├─────────────────────────────────┤
│ 基础设施层 │ ← DB · VectorDB · Redis · 审计
├─────────────────────────────────┤
│ 审计层（全链路横切，异步旁路） │ ← 监听所有层，不阻塞主流程
└─────────────────────────────────┘
编排层为调度枢纽，直接与模型层、工具层、基础设施层交互，各层之间无直接依赖。
上下文优先级（从高到低）
Agent 在任何时候都会综合多个信息源做判断，优先级依次是：
- 当前对话窗口——最新、最权威的信息
- AGENTS.md / 系统提示词——启动时就注入好的角色定义和规则
- RAG 检索结果——按需从文档库里临时捞出来的相关内容
- 向量数据库里的长期记忆——历史对话的语义摘要
- 模型本身的训练知识——静态的，不会实时更新
主流程
① 用户发出需求 → 输入护栏
用户说了一句话（比如"帮我给登录接口加上 rate limiting"），这句话不会直接进大模型，而是先过输入护栏这道关：
- 检查有没有恶意指令（Prompt Injection）或敏感词
- 校验格式是否合法、Token 长度有没有超限
❌ 如果不合规：直接拦截，返回提示，终止流程，并异步写入审计日志。
✅ 如果合规：继续往下走。
② 读取记忆
**编排层（Orchestrator）**在输入合规后，主动调用记忆服务接口；记忆服务负责从各存储后端读取并组装三类记忆，返回给编排层，由编排层在后续 Prompt 构建时注入。`
- 短期记忆：这次会话聊了什么
- 长期记忆：用户的偏好、项目上下文（历史积累的）
- 工作记忆：上一轮工具调用返回了什么结果
这些记忆后面会一起打包进 Prompt。
编排层（Orchestrator） → 主动调用记忆服务接口 → 记忆服务从各自的存储后端读取 （短期：Redis / 会话缓冲 长期：关系型 DB 工作：上轮工具结果缓存） → 组装后统一返回给编排层 → 编排层将结果打包进后续 Prompt
③ 语义路由——判断这个任务该怎么处理
拿到用户的输入后，一个轻量的语义路由模块（不是主 LLM，用小模型或规则引擎，省成本）会分析这个请求是什么类型的任务，然后分流：
| 任务类型 | 走哪条路 |
|---|---|
| 💬 简单问答/推理 | 直接用最小 Prompt + 思维链（CoT）调模型 |
| 📄 文档/知识查询 | 走上下文组装 → 触发 RAG 检索 |
| 🔍 代码审查 | 先做 AST/lint 静态分析，注入 .skills 规范，再调模型 |
| ⚙️ 复杂/需要操作的任务 | 走上下文组装 → 可能触发 RAG → 进入 ReAct 循环 |
④ 上下文组装——把所有材料拼成一个完整的 Prompt
这里要纠正一个常见误解：系统提示词并不是一段写死的静态文本，而是运行时动态拼装的结果。2026 年 3 月，Claude Code 源码意外公开，里面有个细节值得注意——实际的系统提示词由几十个模块按需组合，且内部有一条 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 分隔线。分隔线之前的内容（通用指令、工具定义）跨会话全局缓存，避免每次推理都重新计算这些不变的 Token；分隔线之后的部分（CLAUDE.md、git 状态、当前日期、工作目录等）则每次会话重新注入。这是一个实用的成本优化——只缓存不变的部分，把会话相关的信息留给动态注入。
拼装时打包的内容：
-
系统提示词（角色定义、行为边界、
AGENTS.md规则，静态部分已缓存） -
刚才读取的记忆
-
用户偏好 &
.skills规范 -
可用工具的描述清单（Tool Schema，告诉模型"你能用哪些工具、每个工具需要什么参数"）
-
当前环境上下文（工作目录、git 状态、平台信息等，动态注入）
保证了即使是简单的代码插错，也不会丢失项目级的 .skills 或 AGENTS.md 规范约束
⑤ 判断是否需要 RAG 检索
上下文组装完后，判断这个任务需不需要去文档库里查资料：
不需要 → 直接给大模型推理。
需要 RAG：
- 把用户的问题临时转成向量（注意：这个向量不会存到数据库，只是临时用）
- 拿这个向量去 Vector DB 里做相似度检索，找出最相关的 Top-K 段落（Chunk）
- 可选：用 Reranker 精排模型对这些结果重新排序，挑最相关的
- 把检索到的内容合并注入 Prompt，同时标注来源引用
- 然后再给大模型推理
📌 RAG 的文档是怎么进 Vector DB 的？
Vector DB 有两条写入路径：
- 离线索引：外部文档（PDF / Wiki / 代码库等）经"文档加载 → 切分成小 Chunk（带重叠，避免上下文断裂）→ 向量化 → 存入 Vector DB"流水线预处理，与实时请求无关，提前跑好。
- 在线写回：每轮对话结束后（第 ⑪ 步），对话摘要同样会被向量化写入 Vector DB，作为长期记忆。这条路径是实时触发的，下次对话的 RAG 检索就可能命中它。
⑥ LLM 推理（ReAct 循环入口）—— 整条链路最核心的节点
大模型拿到完整的 Prompt（系统提示、记忆、RAG 结果、用户输入、工具清单）后，进入 ReAct 推理循环：
Step 1：Thought——CoT 推理
ReAct 的 Thought 步骤本质上是 CoT 推理，基于当前上下文逐步拆解任务意图、制定执行计划，并判断是否需要调用工具。每轮循环都会依据最新上下文重新执行，而非一次性完成。
Step 2：决策分支（Action or Answer）
模型基于当前 Thought 的推理结果，输出两类结果之一：
- 直接输出文本（无需工具）→ 进入输出护栏
- 输出
tool_call（声明调用工具 + 携带参数）→ 进入工具权限校验
Step 3：等待 Observation → 进入下一轮 Thought
工具调用发出后，模型等待执行结果（Observation）回注上下文，再次进入 Thought 推理，形成完整循环：
Thought → Action → Observation → Thought → ...
Observation 的收集、错误处理与熔断机制，见 ⑨ 结果回传。
用伪代码表达该循环：
while (!done) {
thought = llm.reason(context) // CoT 推理
if (thought.needTool) {
observation = exec(thought.toolCall)
context.append(observation) // Observation 回注上下文
} else {
return thought.answer
}
}
ReAct = CoT（多轮推理） + Tool Use（行动） + Observation（环境反馈）
⑦ 工具权限校验
模型说"我要调用这个工具"之后，不会直接就跑，先过权限检查：
-
系统级校验： 检查该工具是否被注册，传入参数是否合法。
-
用户授权确认： 如果涉及高危操作（如
rm -rf，修改数据库，向远端git push等），系统会通过 ACP 协议向客户端（IDE/编辑器）发送tool_use_approval请求。此时 Agent 暂停推理，等待用户在界面上点击“允许”或“拒绝”。
❌ 无权限 / 参数违规：拒绝执行，把错误信息返回给模型，让它重新想。
✅ 通过：判断这次要不要并行调多个工具，然在MCP工具层去执行。
⑧ MCP 工具执行
通过 MCP Client 把工具调用指令路由到对应的 MCP Server，真正在宿主环境里执行各类操作，支持多工具并行分发、异步等待合并结果。。以下是主要工具类型：
🗂️ 文件 & 本地环境
- 文件读写：读取源码、配置文件，写入生成内容，支持指定路径和编码
- Shell 命令执行：运行脚本、编译构建、执行测试，获取 stdout/stderr
- Git 操作：查看 diff、提交记录、分支信息，辅助代码审查
注：写入结果通过 OS 文件系统事件通知 IDE，与 ACP 通道独立
🌐 网络 & 第三方 API
-
GitHub / GitLab API：创建 PR、查看 Issue、触发 CI/CD 流水线
-
第三方 HTTP 服务：调用业务 API、消息推送（Gmail / Outlook、Slack / 钉钉、Google Calendar）、支付 / 短信等接口
注：通知/推送类工具通常作为任务收尾动作触发，而非推理过程中的信息获取
🕷️ 网页数据爬取
当需要从公开网页获取实时信息时（如竞品分析、文档抓取、价格监控），Agent 会调用爬取工具：
- 轻量抓取（HTTP Fetch）：直接发 HTTP 请求拿 HTML，适合静态页面；速度快，无需浏览器环境
- 无头浏览器（Headless Browser）：启动 Puppeteer / Playwright，适合 JS 渲染的 SPA 页面；可模拟点击、滚动、等待异步加载
- 内容解析：拿到原始 HTML 后，用 CSS Selector 或 XPath 提取正文、表格、链接等结构化字段，过滤掉导航栏/广告等噪声
- 反爬处理：必要时设置请求头（User-Agent、Referer）、控制请求频率、处理 Cookie / Session，避免被封禁
- 结果回传：将解析后的结构化文本或 JSON 追加至上下文，供模型进一步分析
⚠️ 爬取工具的输出通常是"原始"内容，后续还需经模型提炼后再注入上下文，避免 Token 膨胀（考虑到噪音和token成本）。
🗄️ 数据库查询
数据库查询分两种场景，底层机制完全不同：
1. 关系型数据库（SQL）
适用于结构化数据查询，例如查订单、查用户信息、做报表统计。
- 工具收到指令后，生成 SQL 语句（可由 LLM 辅助生成 Text-to-SQL）
- 通过数据库连接池（pg / mysql2 / prisma 等）执行查询
- 返回结构化的行列数据（JSON 或 CSV 格式）
- 注意事项：
- 写操作（INSERT / UPDATE / DELETE）需要严格权限控制，通常设为只读账户
- 复杂查询应加超时限制，防止慢查询阻塞
- 返回结果过大时需截断，只取前 N 行喂给模型
| 典型数据库 | 适用场景 |
|---|---|
| PostgreSQL / MySQL | 业务数据、用量统计、日志查询 |
| SQLite | 本地轻量存储、开发调试 |
| ClickHouse | 大规模分析型查询、时序数据 |
2. 向量数据库（Vector DB / RAG 检索）
适用于语义相似度查询，例如"找出和这段描述最相关的文档片段"，这就是第 ⑤ 步 RAG 流程里用到的那个数据库。
- 查询时先把问题文本转成向量（Embedding）
- 用 ANN（近似最近邻）算法在向量库中检索语义最相近的 Top-K 条目
- 返回的不是精确匹配的行，而是"语义上最接近"的文本块
- 可选接 Reranker 进一步精排，提升相关性
| 典型实现 | 特点 |
|---|---|
| Pinecone | 全托管，开箱即用 |
| Weaviate | 支持混合检索（关键词 + 向量） |
| Qdrant | 高性能，支持过滤条件 |
| pgvector | 在 PostgreSQL 上扩展，无需额外服务 |
| Chroma | 轻量，适合本地开发 |
📌 两种数据库的核心区别：关系型数据库回答"精确是什么"，向量数据库回答"语义上最像什么"。实际项目中二者经常配合使用——先用向量库找出相关文档，再用 SQL 查询文档对应的结构化元数据。
多个工具可以并行分发，异步等待全部结果返回。
⑨ 结果回传——ReAct 的"观察"步骤
工具执行完了，把结果（stdout 输出、文件内容、API 响应、报错信息等）收集起来：
- 有错误：触发错误处理（重试 / 降级 / 换一个工具，并且会将错误做记忆更新），然后继续
- 正常：把工具结果追加到 Prompt 的上下文里，同时触发工作记忆更新
然后旁路触发工作记忆同步： 最新一次的工具结果会被异步更新到内存（如 Redis），确保下一次 ReAct 循环或突然的终端刷新能保持状态连续。此处为 in-memory 写入（如 Redis），作用域仅限当前会话的 ReAct 循环状态保持，不持久化落盘，与 ⑪ 的持久化写回是两个独立操作。
接着判断：
- ✅ 任务完成了：进入输出护栏，准备返回结果
- ❌ 还没完成：把新上下文重新喂给大模型，继续推理（回到第 ⑥ 步，形成
tool_call → 执行 → 观察 → 回传 → 继续推理的闭环） - ⚠️ 循环次数超上限：强制终止，返回已完成的部分
⚠️ 循环次数超上限（Max Steps 熔断）：这是框架层的硬性保护机制，防止以下情况导致无限运行：工具死循环调用、持续报错重试、模型推理自我矛盾、输出护栏反复拦截、任务缺乏明确终止条件等。触发后强制中断，返回当前已完成的部分内容，并告知用户任务未完整执行。
⑩ 输出护栏
模型最终的输出在返回给用户前，还要过一道检测：
- 合规性校验（有无违规内容）
- PII 过滤（有没有暴露隐私信息）
- Hallucination 检测（有没有明显的幻觉）
- 有害内容过滤
❌ 检测不通过：触发修复器（Corrector），尝试修正 / 重写 / 截断内容，修复后重新检测。如果修复次数超限，就降级返回一个兜底响应，引导用户重新描述需求。
✅ 检测通过：进入记忆写回。
⑪ 记忆写回(异步非阻塞)
为了极致的响应速度，当任务在第 ⑩ 步通过输出护栏后，主线程会立即向客户端返回完成信号。同时在后台异步触发数据落盘：
- 对话摘要 → 写入关系型数据库（长期记忆）
- 用户行为信号 → 偏好更新
这样下次对话时，Agent 就能"记得"这次发生了什么。
在实际部署中，推荐采用
PostgreSQL + pgvector统一存储方案：对话摘要的结构化字段与向量数据可在同一事务内写入，规避了跨存储系统的分布式一致性问题，并支持通过<->运算符在同一 SQL 查询中混合结构化过滤与向量相似度检索。
⑫ 审计日志（Audit Log）
审计系统与 Agent 主流程完全解耦。整条链路全程有审计层在旁路异步记录（完全不阻塞主流程）：
- 完整的调用链路和输入输出快照
- Token 用量、延迟、安全事件
审计日志数据库主要记录的就是每次执行过程，存储过程由审计层监听并记录，而非agent发起。审计系统主要用途是合规审查、故障排查、用量统计、安全溯源。
流程图示
这里有一份可视化的 流程图：
%%{init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#ffffff',
'primaryTextColor': '#334155',
'primaryBorderColor': '#cbd5e1',
'lineColor': '#94a3b8',
'secondaryColor': '#f8fafc',
'tertiaryColor': '#f1f5f9',
'background': '#ffffff',
'mainBkg': '#f8fafc',
'nodeBorder': '#cbd5e1',
'clusterBkg': '#f1f5f9',
'clusterBorder': '#e2e8f0',
'titleColor': '#0f172a',
'edgeLabelBackground': '#ffffff',
'fontFamily': 'ui-sans-serif, system-ui, -apple-system, sans-serif',
'fontSize': '14px'
},
'flowchart': {
'nodeSpacing': 55,
'rankSpacing': 65,
'padding': 22,
'curve': 'basis'
}
}}%%
flowchart TD
%% ==========================================
%% 1. 节点与子图声明区
%% ==========================================
subgraph CLIENT_IN ["💻 客户端层 (IDE / 编辑器) — 发起侧"]
USER_INPUT(["🙋 用户输入"])
end
START(["🟢 Agent 核心接入点"])
subgraph BLOCK_1 ["① 输入护栏 — Input Guardrails"]
GUARD_IN["🛡️ 敏感词 · Prompt Injection · Token 限制 · 格式校验"]
CHECK_IN{"输入合规?"}
REJECT(["🔴 拒绝，返回拦截提示"])
GUARD_IN --> CHECK_IN
CHECK_IN --"❌ 不合规"--> REJECT
end
subgraph BLOCK_MEM ["② 记忆读取 — 编排层调用 Memory Service（独立后台）"]
MEMORY_READ["🧠 短期：当前会话 · 长期：偏好/项目上下文<br/>工作：上轮工具结果（in-memory）"]
end
subgraph BLOCK_2 ["③ 语义路由 — Semantic Router（轻量模块）"]
ROUTER["🔀 意图 & 复杂度分析（小模型 / 规则引擎）"]
ROUTE_BRANCH{"任务类型?"}
SIMPLE["💬 最小 Prompt + CoT<br/>简单问答 / 推理"]
CODE_CHECK["🔍 AST/lint 静态分析<br/>+ .skills 规范注入"]
ROUTER --> ROUTE_BRANCH
ROUTE_BRANCH --"💬 简单问答"--> SIMPLE
ROUTE_BRANCH --"🔍 代码审查"--> CODE_CHECK
end
subgraph BLOCK_3 ["④ 上下文组装 — Prompt Builder"]
CTX_BUILD["📦 System + 记忆 + 偏好/.skills<br/>Tool Schema + 环境上下文（动态注入）"]
RAG_CHECK{"需要知识检索?"}
CTX_BUILD --> RAG_CHECK
end
subgraph BLOCK_4 ["⑤ RAG 在线检索（只读）"]
RAG_EMBED["🔍 查询向量化（临时，不持久化）"]
RAG_SEARCH["📊 ANN 相似度检索 Top-K"]
RERANK_CHECK{"启用 Reranker?"}
RERANKER["🎯 精排模型：重新评分排序"]
RAG_MERGE["🔗 合并注入 Prompt，标注来源"]
RAG_EMBED --> RAG_SEARCH --> RERANK_CHECK
RERANK_CHECK --"是"--> RERANKER --> RAG_MERGE
RERANK_CHECK --"否"--> RAG_MERGE
end
subgraph BLOCK_5 ["⑥ LLM 推理 — ReAct 循环（Agent 核心）"]
LLM_INFER["🧩 Thought — CoT 推理<br/>拆解意图 · 制定计划 · 判断工具调用<br/>每轮循环依据最新上下文重新执行"]
TOOL_NEED{"Action or Answer?"}
GEN_RESULT["✍️ LLM 原始输出（未校验）"]
LLM_INFER --> TOOL_NEED
TOOL_NEED --"否，直接生成"--> GEN_RESULT
end
subgraph BLOCK_AUTH ["⑦ 工具权限校验 — Tool Auth Guard"]
TOOL_AUTH{"🔐 工具注册 · 参数合法性<br/>高危操作 → ACP 请求用户授权"}
TOOL_DENY["⛔ 拒绝执行<br/>错误信息返回 LLM"]
TOOL_PARALLEL{"多工具并行?"}
TOOL_AUTH --"❌ 无权限/违规"--> TOOL_DENY
TOOL_AUTH --"✅ 通过"--> TOOL_PARALLEL
end
subgraph BLOCK_6 ["⑧ MCP 工具执行（Client → Server）"]
TOOL_CALL["📋 单工具指令分发"]
PARALLEL_EXEC["⚡ 并行分发 · 异步等待合并"]
MCP_DISPATCH["🔌 MCP 路由匹配"]
MCP_EXEC["⚡ Server 物理执行<br/>─────────────────────────<br/>🗂️ 文件读写 / Shell / Git<br/>🌐 GitHub · GitLab · CI/CD<br/>📨 邮件 / Slack / 日历<br/>🗄️ SQL 查询 / 向量写回<br/>🕷️ HTTP Fetch / Headless Browser"]
TOOL_CALL --> MCP_DISPATCH
PARALLEL_EXEC --> MCP_DISPATCH
MCP_DISPATCH --> MCP_EXEC
end
subgraph BLOCK_7 ["⑨ 结果回传 — ReAct 观察步（Observation）"]
TOOL_RESULT["📥 收集执行结果<br/>stdout · 文件内容 · API 响应 · 报错"]
TOOL_ERR{"执行出错?"}
ERR_HANDLE["🔧 重试 / 降级 / 换工具<br/>错误写入工作记忆"]
APPEND_CTX["📎 tool_result 追加至上下文<br/>工作记忆 in-memory 同步（如 Redis）<br/>⚠️ 作用域限当前会话，不持久化落盘"]
LOOP_CHECK{"任务完成 / 达最大循环?"}
TOOL_RESULT --> TOOL_ERR
TOOL_ERR --"⚠️ 有错误"--> ERR_HANDLE --> APPEND_CTX
TOOL_ERR --"✅ 正常"--> APPEND_CTX
APPEND_CTX --> LOOP_CHECK
end
%% TIMEOUT 移出 BLOCK_7，作为顶层独立节点
%% 避免与 LOOP_CHECK→GEN_RESULT 的跨子图连线交叉
TIMEOUT(["⚠️ Max Steps 熔断<br/>强制终止，返回已完成部分"])
subgraph BLOCK_8 ["⑩ 输出护栏 — Output Guardrails"]
GUARD_OUT["🔍 合规校验 · PII 过滤 · 幻觉检测 · 有害内容"]
CHECK_OUT{"输出合规?"}
CORRECTOR["🔄 修复器：修正 / 重写 / 截断"]
CORRECTOR_LIMIT{"校正超限?"}
FALLBACK(["⚠️ 降级响应，提示重新描述"])
USER_RETRY(["🔁 用户重新输入"])
GUARD_OUT --> CHECK_OUT
CHECK_OUT --"❌"--> CORRECTOR --> CORRECTOR_LIMIT
CORRECTOR_LIMIT --"未超限"--> GUARD_OUT
CORRECTOR_LIMIT --"⚠️ 兜底"--> FALLBACK --> USER_RETRY
end
subgraph BLOCK_MEM_WRITE ["⑪ 记忆写回 — 异步非阻塞持久化"]
MEM_WRITE["💾 对话摘要 → 长期记忆（持久化）<br/>摘要向量化 → pgvector 同库事务写入<br/>用户行为信号 → 偏好更新"]
end
END_NODE(["🏁 Agent 任务完成"])
subgraph CLIENT_OUT ["💻 客户端层 (IDE / 编辑器) — 接收侧"]
UI_RENDER(["🖥️ Markdown / Diff / 授权弹窗 / 进度条"])
end
subgraph BLOCK_AUDIT ["⑫ 审计层 — 全程旁路异步（不阻塞主流程）"]
direction LR
AUDIT_LOG["📋 全链路日志采集<br/>调用链路 · Token 用量 · 延迟 · 安全事件"]
AUDIT_DB[("📋 Audit DB<br/>PG / ES / ClickHouse")]
AUDIT_LOG -.->|"持久化写入"| AUDIT_DB
end
subgraph BLOCK_RAG_OFFLINE ["📦 RAG 离线预处理 — 异步旁路（与实时请求无关）"]
direction LR
DOC_LOAD["📄 加载文档<br/>PDF · MD · Code · Web"]
DOC_CHUNK["✂️ 切分 Chunk<br/>带重叠避免断裂"]
DOC_EMBED["🔢 离线向量化"]
VECTOR_DB[("🗄️ PostgreSQL + pgvector<br/>关系型 + 向量统一存储")]
DOC_LOAD --> DOC_CHUNK --> DOC_EMBED --> VECTOR_DB
end
%% ==========================================
%% 2. 核心主流程连线区
%% ==========================================
USER_INPUT --"ACP 协议 session/prompt"--> START
START --> GUARD_IN
CHECK_IN --"✅ 合规"--> MEMORY_READ
MEMORY_READ --> ROUTER
ROUTE_BRANCH --"📄 文档/知识"--> CTX_BUILD
ROUTE_BRANCH --"⚙️ 复杂/操作"--> CTX_BUILD
SIMPLE --> LLM_INFER
CODE_CHECK --> LLM_INFER
RAG_CHECK --"否"--> LLM_INFER
RAG_CHECK --"是"--> RAG_EMBED
RAG_MERGE --> LLM_INFER
TOOL_NEED --"是，输出 tool_call"--> TOOL_AUTH
TOOL_DENY --> APPEND_CTX
TOOL_PARALLEL --"单一"--> TOOL_CALL
TOOL_PARALLEL --"并行"--> PARALLEL_EXEC
MCP_EXEC --> TOOL_RESULT
LOOP_CHECK --"❌ 未完成"--> LLM_INFER
LOOP_CHECK --"✅ 完成"--> GEN_RESULT
LOOP_CHECK --"⚠️ 超限"--> TIMEOUT
GEN_RESULT --> GUARD_OUT
CHECK_OUT --"✅ 合规"--> MEM_WRITE
MEM_WRITE --> END_NODE
END_NODE --"ACP stop_reason"--> UI_RENDER
%% ==========================================
%% 3. 异步、旁路及跨层连线区
%% ==========================================
REJECT -.->|"旁路事件"| AUDIT_LOG
LLM_INFER -.->|"推理日志（异步）"| AUDIT_LOG
MCP_EXEC -.->|"调用日志（异步）"| AUDIT_LOG
MEM_WRITE -.->|"触发审计记录"| AUDIT_LOG
VECTOR_DB -.->|"实时读取"| RAG_SEARCH
USER_RETRY -.->|"ACP 重新发起"| USER_INPUT
GEN_RESULT -."ACP 流式文本推送".-> UI_RENDER
TOOL_CALL -."ACP 工具状态回显".-> UI_RENDER
TOOL_AUTH -."ACP 请求并等待用户授权".-> UI_RENDER
MCP_EXEC -."OS 文件系统事件<br/>(FSWatcher，非 ACP)".-> UI_RENDER
%% ==========================================
%% 4. 样式渲染映射区
%% ==========================================
classDef startEnd fill:#dcfce7,stroke:#22c55e,stroke-width:2px,color:#166534
classDef reject fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#991b1b
classDef warning fill:#fef9c3,stroke:#eab308,stroke-width:2px,color:#854d0e
classDef process fill:#ffffff,stroke:#94a3b8,stroke-width:2px,color:#334155
classDef decision fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af
classDef rag fill:#faf5ff,stroke:#a855f7,stroke-width:2px,color:#6b21a8
classDef tool fill:#ecfeff,stroke:#06b6d4,stroke-width:2px,color:#155e75
classDef memory fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#166534
classDef audit fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#334155
classDef db fill:#fdf4ff,stroke:#d946ef,stroke-width:2px,color:#86198f
classDef llm fill:#fffbeb,stroke:#f59e0b,stroke-width:3px,color:#92400e
classDef client fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#075985
class START,END_NODE startEnd
class REJECT,TOOL_DENY reject
class TIMEOUT,FALLBACK,USER_RETRY warning
class GUARD_IN,ROUTER,CTX_BUILD,CODE_CHECK,SIMPLE,GEN_RESULT,ERR_HANDLE,GUARD_OUT,CORRECTOR,APPEND_CTX process
class CHECK_IN,ROUTE_BRANCH,RAG_CHECK,RERANK_CHECK,TOOL_NEED,TOOL_PARALLEL,LOOP_CHECK,CHECK_OUT,CORRECTOR_LIMIT,TOOL_ERR,TOOL_AUTH decision
class RAG_EMBED,RAG_SEARCH,RERANKER,RAG_MERGE,DOC_LOAD,DOC_CHUNK,DOC_EMBED rag
class TOOL_CALL,MCP_DISPATCH,MCP_EXEC,PARALLEL_EXEC,TOOL_RESULT tool
class MEMORY_READ,MEM_WRITE memory
class AUDIT_LOG,AUDIT_DB audit
class VECTOR_DB db
class LLM_INFER llm
class USER_INPUT,UI_RENDER client
这里还有一份流程在架构中的归属映射的图示
%%{init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#ffffff',
'primaryTextColor': '#334155',
'primaryBorderColor': '#94a3b8',
'lineColor': '#64748b',
'secondaryColor': '#f8fafc',
'tertiaryColor': '#f1f5f9',
'fontFamily': 'ui-sans-serif, system-ui, -apple-system, sans-serif',
'fontSize': '14px'
},
'flowchart': {
'curve': 'linear',
'rankSpacing': 60,
'nodeSpacing': 50,
'padding': 24
}
}}%%
flowchart TB
%% ==========================================
%% 样式与类定义预设
%% ==========================================
classDef default fill:#ffffff,stroke:#94a3b8,stroke-width:1px,color:#334155,rx:4,ry:4;
classDef decision fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af,rx:4,ry:4;
classDef terminal fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#166534,rx:16,ry:16;
classDef storage fill:#fdf4ff,stroke:#d946ef,stroke-width:1px,color:#86198f;
classDef layerClient fill:#f8fafc,stroke:#cbd5e1,stroke-width:2px,rx:8,ry:8;
classDef layerOrch fill:#f8fafc,stroke:#94a3b8,stroke-width:2px,rx:8,ry:8,stroke-dasharray: 5 5;
classDef layerModel fill:#fffbeb,stroke:#fcd34d,stroke-width:2px,rx:8,ry:8;
classDef layerTool fill:#ecfeff,stroke:#67e8f9,stroke-width:2px,rx:8,ry:8;
classDef layerInfra fill:#f3e8ff,stroke:#d8b4fe,stroke-width:2px,rx:8,ry:8;
classDef layerAudit fill:#fef2f2,stroke:#fca5a5,stroke-width:2px,rx:8,ry:8,stroke-dasharray: 5 5;
%% ==========================================
%% 节点声明与层级划分
%% ==========================================
subgraph CLIENT ["💻 客户端层 (Client Layer)"]
direction LR
C_IN(["🙋 用户请求"])
C_AUTH{"🛡️ 授权高危操作"}
C_OUT(["📺 渲染视图"])
end
subgraph ORCH ["⚙️ 编排层 (Orchestrator Layer) — 无状态控制流"]
direction TB
O_1["① 输入护栏"]
O_2["② 记忆读取"]
O_3{"③ 语义路由"}
O_4["④ 上下文组装"]
O_5{"⑤ RAG 决策"}
O_6["⑥ ReAct 引擎\n(状态机规划)"]
O_7{"⑦ 权限校验"}
O_8["⑧ MCP Client\n(指令分发)"]
O_9["⑨ 结果回注"]
O_10{"⑩ 输出护栏\n(Corrector)"}
O_11["⑪ 异步写回"]
%% 主干垂直链路
O_1 --> O_2 --> O_3 --> O_4 --> O_5 --> O_6
O_6 --> O_7 --> O_8
O_8 -.->|等待| O_9
O_9 -->|未完成: 回调推理| O_6
O_9 -->|已完成: 验证输出| O_10
O_10 --> O_11
end
subgraph MODEL ["🧠 模型层 (Model Layer)"]
direction TB
M_SUB["辅助轻模型\n(意图/合规)"]
M_MAIN["主力大模型\n(Thought/Action)"]
end
subgraph TOOL ["🛠️ 工具层 (MCP Server Layer)"]
direction TB
T_HOST["宿主工具\n(File/Git)"]
T_WEB["网络工具\n(API/爬虫)"]
T_DB["数据工具\n(SQL)"]
end
subgraph INFRA ["🗄️ 基础设施层 (Infrastructure Layer)"]
direction LR
I_MEM[("In-memory 缓存\n(如 Redis)")]
I_VEC[("向量数据库\n(知识检索)")]
I_DB[("关系型数据库\n(偏好/存储)")]
end
subgraph AUDIT ["🛡️ 审计层 (Audit Layer)"]
A_LOG["旁路审计系统\n(全链路日志/合规)"]
end
%% ==========================================
%% 跨层逻辑调用
%% ==========================================
%% 客户端进出
C_IN --> O_1
O_10 -->|通过验证| C_OUT
O_7 <-->|ACP 弹窗| C_AUTH
%% 模型交互
O_3 <-.-> M_SUB
O_10 <-.-> M_SUB
O_6 <--> M_MAIN
%% 工具分发
O_8 === T_HOST
O_8 === T_WEB
O_8 === T_DB
%% 数据存取
O_2 <--> I_DB
O_5 -->|"只读"| I_VEC
O_9 <--> I_MEM
O_11 -.->|"摘要落盘"| I_DB
O_11 -.->|"摘要向量化"| I_VEC
%% 审计旁路
O_1 -.-> A_LOG
O_8 -.-> A_LOG
O_6 -.-> A_LOG
O_11 -.-> A_LOG
%% 应用样式
class C_IN,C_OUT terminal;
class O_3,O_5,O_7,O_10 decision;
class I_MEM,I_VEC,I_DB storage;
class CLIENT layerClient;
class ORCH layerOrch;
class MODEL layerModel;
class TOOL layerTool;
class INFRA layerInfra;
class AUDIT layerAudit;
五、主流工具横向对比
这些工具都内置了 Agent，但各有侧重：
| 工具 | 类型 | 核心特点 |
|---|---|---|
| Cursor | IDE（基于 VS Code） | Anysphere 公司，2023 年发布。理解完整项目上下文，Agent 模式可自主完成多步任务 |
| Windsurf | IDE（基于 VS Code） | Codeium 公司出品。内置 Cascade Agent，实时感知编辑器状态（光标位置、控制台信息） |
| GitHub Copilot | 插件 | 最早的 AI 编程助手，主要做代码补全建议，支持 VS Code、JetBrains 等主流编辑器 |
| Claude Code | 终端 CLI | Anthropic，2025 年发布。纯终端 Agent，深度感知未打开的文件，完整支持 MCP 和 Skills |
社区开源项目：
| 项目 | 定位 |
|---|---|
| OpenCode | 开源终端 Agent，类 Claude Code，model-agnostic，支持多种 LLM 后端 |
| OpenHands | 开源"全栈 AI 工程师"，内置 Docker 沙盒隔离，面向团队 / 企业的编码 Agent 平台 |
| OpenClaw | 面向个人的全能自动化助理，支持通过聊天 / 短信 / WhatsApp 触发日常任务自动化 |
六、生态全景总结
读完全文，把各个部分的分工再整理一遍：
┌────────────────────────────────────────────────────────────────────┐
│ AI 工程生态 · 各层分工 │
├─────────────────┬──────────────────────────────────────────────────┤
│ LLM │ Reasoning — 理解语言、逻辑推理、生成内容 │
├─────────────────┼──────────────────────────────────────────────────┤
│ RAG │ Knowledge — 外挂知识库，突破知识截止限制和大幅降低幻觉 │
├─────────────────┼──────────────────────────────────────────────────┤
│ MCP │ Tool Interface — 标准化工具调用，扩展执行能力 │
├─────────────────┼──────────────────────────────────────────────────┤
│ Agent │ Planning + Execution — 自主拆解任务并推进完成 │
├─────────────────┼──────────────────────────────────────────────────┤
│ Skills / │ Context + Rules — 注入项目规范，约束生成行为 │
│ AGENTS.md │ │
├─────────────────┼──────────────────────────────────────────────────┤
│ Guardrails │ Safety — 输入输出双向防护，保障安全与合规 │
└─────────────────┴──────────────────────────────────────────────────┘
它们之间的依赖关系，形成一个完整的闭环：
LLM（推理引擎）
│
┌────────────────┼────────────────┐
▼ ▼ ▼
RAG MCP Guardrails
检索知识 执行工具 安全防护
(Vector DB) (Tool Server)
│ │
└────────────────┘
│
▼
Agent
协调以上一切，主动推进任务
│
┌────────┴────────┐
▼ ▼
Skills AGENTS.md
框架规范 项目约定
七、常见误区
❎ LLM = 知识库
LLM 并不会“存储事实”，它只是学习了语言模式。 真正的知识更新需要依赖 RAG 或外部系统。
❎ RAG = 数据库
RAG 不是数据库，而是一种“检索 + 生成”的组合范式。 数据库只是其中的一个组件（向量数据库）。
❎ Agent = 自动执行
Agent 并不是完全自主的系统， 其行为仍受到 Prompt、工具权限和护栏的强约束。
❎ 上下文越大越好
上下文过大会引入噪音，反而降低模型效果。 合理裁剪比盲目扩展更重要。
❎ Prompt 写得越复杂越好
复杂 Prompt 并不一定更好， 清晰、结构化、可控才是关键。
结语
AI 工程的本质，是把 LLM 的推理能力，通过一系列工程组件放大成自主行动能力。
我们正在经历的不只是工具的更新——更像是一次开发范式的迁移：从人写每一行代码，到人描述意图、AI 执行实现，再到 AI 自主规划、人审查结果。
随着 Agent 越来越成熟，机器人（不只是人形机器人，还有工业机械臂、农业辅助器械）越来越智能，AI 在人类重复性工作中的参与度也会越来越高。带来的是效率还是新的复杂性？可能两者都有。但这大概率是接下来的方向。
