AI项目实战（2）起点：在动手之前，先看清全图

本章是全书的「技术地图」。它不写代码，但会帮你建立一个清晰的认知框架——
我们到底要解决什么问题、用哪些技术手段、沿什么路线进化。
读完之后，你会知道后面每一个项目在「全局版图」中处于什么位置，为什么它出现在那里。

如果你已经读过上一本理论篇，本章可以快速浏览。如果你是从这一本开始，本章是必读的。

开篇：一个真实的下午

先讲个真事。

某公司运营小李，下午三点收到老板一条消息：「分析一下上个月广告投放数据，明天开会要用。」换作以前，小李要登录广告后台、导数据、开 Excel、做透视表、查行业经验、再写成报告，断断续续忙到晚上九点。

这次他试着把任务丢给了一个刚搭好的 AI Agent。他只打了一句话：

帮我分析上个月广告投放数据，找出问题，生成优化建议报告。

然后他去倒了杯咖啡。回来时，屏幕上已经躺着一份分章节、带数据、有建议的报告——还顺手提醒他：「计划 B 的 ROI 是负的，建议先暂停。」

小李愣了一下：它什么时候学会干这个的？

这个问题，正是这本书要回答的。一个大语言模型，本来只会「文字接龙」——你给一句话，它接一句话。它不会上网、不会读文件、不会算数、记不住昨天的事。可就在你倒杯咖啡的工夫，它却能像个老练的运营一样，把一整套活儿干完。

秘密不在于模型变聪明了，而在于我们一层一层地给它装上了手脚、记忆、工具和队友。这本书的十个项目，就是这条「进化之路」上的十个里程碑。

而在踏上这条路之前，我们得先看清整张地图。

1.1 全书主线：从单兵到团队

回到小李的那个下午。如果让一个「裸」的大模型直接干这活，它会立刻露馅：它不知道「上个月」是哪个月、读不到你的广告后台、算不对 ROI、更不知道什么算「问题」。它顶多凭记忆编一份听起来头头是道、实则全是 hallucination（幻觉）的报告。

所以真正能干活的，从来不是一个孤零零的模型，而是一个被层层武装起来的系统。我们不妨把这个武装过程，想象成「培养一个新员工」：

%%{init: {'theme':'base','flowchart':{'useMaxWidth':true,'htmlLabels':true}}}%%
graph LR
    S1["🛠️ 单工具 Agent
会用一种工具"] --> S2["🔧 多工具 Agent
会选工具、组合使用"]
    S2 --> S3["🔄 循环 Agent
会想-做-看-再想"]
    S3 --> S4["📚 知识 Agent
会查资料、引经据典"]
    S4 --> S5["🧠 自主 Agent
会规划、有记忆"]
    S5 --> S6["🤝 Multi-Agent
会分工协作"]

    classDef s fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1
    class S1,S2,S3,S4,S5,S6 s

• 刚入职，他啥也不会，你先教他用一种工具（比如查订单系统）——这是「单工具 Agent」。
• 熟练了，你给他一抽屉工具，他得学会挑哪个、怎么组合——「多工具 Agent」。
• 任务变复杂，他得边做边想：查一步、看结果、再决定下一步——「循环 Agent」。
• 光会动手不够，遇到公司内部规矩，他得会翻资料、引经据典——「知识 Agent」。
• 再进一步，你扔给他一个模糊目标，他能自己拆任务、记得你的偏好——「自主 Agent」。
• 最后，活儿一个人干不过来，他学会拉团队分工——「Multi-Agent」。

这条进化线就是全书的主线。十个项目沿着它依次展开：

💡 一个提醒：这张表里每个项目都不是孤立的「Demo」。它们是同一条路上的不同站点——前一个项目教的能力，后一个项目会默认你已经会了。所以强烈建议按顺序读，哪怕快速过一遍。跳着读的人，往往会在第六章困惑「它怎么突然就会多步循环了」，其实那只是第五章练过的本事。

接下来的十四个章节，每一章都是在这条主线上的一步。

1.2 核心概念速览：八张拼图，一张全景图

在动手写代码之前，我们需要先认识这八张 “拼图”——它们就是全书要教你的全部核心技术。每个概念我们先用一句话抓住本质，然后在后面的项目里反复实践、逐步加深理解。

拼图 1：大模型（LLM）—— Agent 的大脑

大语言模型是 Agent 的 “大脑”：理解用户意图、推理下一步该做什么、生成回复。但纯大模型天生有三件事做不了：

• 不能行动（只能输出文字，不能上网、不能读文件）
• 没有记忆（关掉对话全忘）
• 知识会过时（训练完了就不再更新）

我们后面所有的技术，本质上都是在给这个大脑 装补丁——让它能做事、记得住、查得着。但补丁不能乱打。下面这八张「拼图」，是业界摸索出来的、公认好用的八块补丁。我们先一眼看懂每块补丁要补什么缺口，等到后面的项目里亲手缝上去，你就彻底明白了。

拼图 1：大模型（LLM）—— Agent 的大脑

大语言模型是 Agent 的 “大脑”：理解用户意图、推理下一步该做什么、生成回复。但纯大模型天生有三件事做不了：

• 不能行动（只能输出文字，不能上网、不能读文件）
• 没有记忆（关掉对话全忘）
• 知识会过时（训练完了就不再更新）

我们后面所有的技术，本质上都是在给这个大脑 装补丁——让它能做事、记得住、查得着。

拼图 2：Prompt 工程—— 学会 “好好说话”

同样一个博学的大脑，你问「什么是期权」和问「你是 15 年经验的交易员，请用买股票打比方，给完全不懂金融的新手讲讲期权」——答案质量天差地别。Prompt 工程研究的就是怎么把话说到位：角色设定、任务描述、举几个例子（Few-shot）、让它一步步想（思维链）。

本质：不改动模型本身，只优化输入，把模型能力压榨到极致。这是成本最低、见效最快的一块补丁。

拼图 3：Tool / Function Calling—— 给大脑装手脚

模型不能上网、不能查数据库、不能发邮件。但你不能要求它「学会」这些——它就是个文字机器。怎么办？换个思路：告诉它「你有一个叫 search_web 的工具，需要查东西就喊我，我替你执行」。模型于是输出一段结构化的「调用请求」，外部程序真正执行后，把结果喂回去。

本质：模型不自己执行，而是 表达调用意图，由外部程序真正动手。它不会变成程序员，但它学会了「求助」。

拼图 4：RAG（检索增强生成）—— 给大脑接上外部图书馆

模型知识停在训练那天，也不知道你公司的内部规章。更要命的是，它不知道时不会说「不知道」，而是会一本正经地编——这就是令所有 AI 应用头疼的「幻觉」。

RAG 的思路朴素得惊人：提问之前，先把相关资料从知识库里搜出来，和问题一起递给模型，让它看着资料回答。好比把闭卷考试改成开卷考试——学生不用背，翻到那一页照着抄就行，既准又有出处。

本质：检索 + 生成，用外部知识库弥补模型的知识盲区，同时压制幻觉。

拼图 5：Harness（运行外壳）—— 让大脑 “循环” 起来

查个天气，模型调一次工具就够了。但要它「整理一个项目里所有旧 API 并改掉」，就得：先搜文件、再读内容、再改、再跑测试、失败再改……这是个「想一步、做一步、看结果、再想下一步」的循环。单次问答的模型扛不住这种活。

Harness 就是那个驱动模型反复跑「思考 → 行动 → 观察 → 再思考」循环的外壳程序。它像 Agent 的神经系统，把零散的「一问一答」缝合成「坚持把一件事干完」的能力。

本质：Agent Loop（智能体循环），是 Agent 的 “神经系统”。

拼图 6：MCP（模型上下文协议）—— 工具世界的 “USB 接口”

Tool 解决了「会用工具」，但很快冒出新麻烦：AI 应用有很多个，外部工具也有几百个，难道每个应用接每个工具都得单独写一套代码？那是 N×M 套对接的噩梦。

MCP 干的事，和当年 USB 一模一样——定一个标准接口，工具方只要做成「MCP Server」，任何支持 MCP 的应用都能即插即用，不用再为它单独写对接。

本质：AI 世界的统一工具接口标准，把 N×M 的乱局变成 N+M 的清爽。

拼图 7：记忆系统—— 让 Agent 不再 “失忆”

你昨天告诉助理「我对花生过敏」，今天再问它推荐菜，它却给你推了宫保鸡丁——这种「失忆」是纯大模型的硬伤。记忆系统分两层补这个缺口：短期记忆（这次任务的对话，放在上下文窗口里）和长期记忆（你的偏好、过往经验，存到外部，用时检索回来）。

有意思的是：长期记忆的底层实现，本质上就是拼图 4 的 RAG——把经验存进知识库，需要时检索。八块拼图在这里第一次「咬合」上了。

本质：让 Agent 的交互有连续性，能 “记住” 用户和过往经验。

拼图 8：Skill（技能）—— 把 “经验” 打包复用

最后一块。你花大力气教会 Agent「怎么做微信支付接入」，换一次对话它又忘了，又得从头教——这谁受得了。Skill 的办法是：把完成某类任务所需的方法论 + 工具 + 示例 + 资源打包成一个可复用单元，平时只放个「目录索引」，用到时才加载完整内容。Agent 一加载，瞬间「变身」专家。

本质：把 “做事方法论” 沉淀为可复用、可分享的模块，让经验不再随会话蒸发。

全景图：八张拼图如何协同

读完八张拼图，你可能还是觉得它们「各管各的」。别急，看这张全景图——它们是怎么咬合成一个完整 Agent 的：

%%{init: {'theme':'base','flowchart':{'useMaxWidth':true,'htmlLabels':true}}}%%
graph TD
    User["👤 用户：给出目标"] --> Prompt["✍️ Prompt 工程
把意图表达清楚"]
    Prompt --> Agent["🎯 Agent（运行在 Harness 之上）"]
    
    Agent --> Brain["🧠 大模型（大脑）"]
    Brain --> Loop["🔄 Harness 循环"]
    Loop --> Tools["🔧 Tool 工具调用"]
    Tools --> MCP["🔌 MCP 标准接入"]
    Tools --> RAG["📚 RAG 检索知识"]
    Brain --> Mem["💾 记忆系统"]
    Mem --> RAG
    Brain --> Skill["📖 Skill 技能"]
    
    Agent --> Result["✅ 交付结果"]

    classDef uN fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1
    classDef pN fill:#fce4ec,stroke:#d81b60,stroke-width:2px,color:#880e4f
    classDef aN fill:#ede7f6,stroke:#5e35b1,stroke-width:3px,color:#311b92
    classDef cN fill:#e0f2f1,stroke:#00897b,stroke-width:2px,color:#004d40
    classDef tN fill:#e0f7fa,stroke:#00acc1,stroke-width:2px,color:#006064
    classDef rN fill:#e8f5e9,stroke:#43a047,stroke-width:2px,color:#1b5e20
    class User uN
    class Prompt pN
    class Agent,Brain aN
    class Loop,Mem cN
    class Tools,MCP,RAG,Skill tN
    class Result rN

1.3 技术基准：本书选型与官方建议

⚠️ 重要声明：以下内容在写作时（2026 年 6 月）已与官方文档核实。AI 框架迭代迅速，如遇 API 变化，请以各项目官方最新文档为准。

1.3.1 为什么选 LangChain v1.0 的 create_agent

市面上很多教程还在用 langgraph.prebuilt.create_react_agent，但根据 LangChain 官方 v1.0 文档（https://docs.langchain.com/oss/python/releases/langchain-v1），这个 API 已被标记为 deprecated（废弃）。

官方现在推荐统一使用 langchain.agents.create_agent：

“create_agent is the standard way to build agents in LangChain 1.0. It provides a simpler interface than langgraph.prebuilt.create_react_agent while offering greater customization potential by using middleware.”
—— 来源：LangChain v1 官方发布说明

本书全书统一使用 create_agent，不使用已废弃的 API。

1.3.2 全书技术栈一览

1.3.3 关键 API 表单（已核对官方文档）

1.3.4 版本锁定

本书代码基于以下大版本编写（详见仓库 requirements.txt）：

1
2
3
4
5
6

langchain >= 1.0.0
langgraph >= 1.0.0
langchain-anthropic >= 1.0.0
langgraph-checkpoint-sqlite >= 2.0.0
llama-index >= 0.12.0
langchain-mcp-adapters >= 0.1.0

1.4 统一工程模板：如何阅读后面的项目章节

从第 2 章开始，每个项目章节都采用固定的 七段式结构，不再单独说明：

%%{init: {'theme':'base','flowchart':{'useMaxWidth':true,'htmlLabels':true}}}%%
graph LR
    A["1. 诉求
主角想要什么"] --> B["2. 画个样子"]
    B --> C["3. 拆开看"]
    C --> D["4. 动手写"]
    D --> E["5. 跑一跑"]
    E --> F["6. 送上线"]
    F --> G["7. 回头看"]

    classDef s fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1
    class A,B,C,D,E,F,G s

这不是为了套模板，而是因为——这就是真实工业界做一个 AI 项目的标准流程。读完十四章，你不仅会做技术，也会做产品、做项目。

1.5 阅读路径建议

根据你的背景和目标，可以选择不同的阅读路径：

1.6 回头看：学到了什么

这一章我们做了三件事：

1. 确立了全书主线：从单兵到团队——让 AI Agent 从"会用工具"逐步进化到"能协作的智能体团队"。
2. 快速过了一遍八张核心拼图：大模型、Prompt、Tool、RAG、Harness、MCP、记忆、Skill——以及它们如何协同工作。
3. 建立了全书技术基准：基于 LangChain v1.0 官方推荐的 create_agent，统一技术栈，所有关键 API 已经过官方文档校对。

现在，你已经有了全书的「认知地图」。下一章，我们将把这个认知框架落地为实际可运行的工程代码——搭建一个能承载十个项目的通用脚手架。

📌 第 1 章（基础铺垫）到此结束。

接下来进入第 2 章：通用脚手架——我们将搭建贯穿全书的 AgentCore 基类、配置管理、统一 API 和前端管理台。

• ← Previous Post
• Next Post →