AI Agent+RAG+MCP实战：基于Harness架构的学习助手搭建指南

这次我们来看一个把 AI Agent、RAG、MCP、Embedding、上下文工程全部串到一个实战项目里的课程设计：基于 Harness 架构的学习助手。它不是一个只能跑 Demo 的玩具项目，而是一条从代码分析到实战落地的完整技术链路。如果你正在学 AI Agent，想搞懂 RAG 知识库到底怎么搭，或者想知道 MCP 在真实项目里怎么接入、Skills 技能怎么封装，这篇内容可以直接收藏。

这个项目的重点不是概念堆得多全，而是能不能把概念变成一条可运行的链路。课程设计上，它从最底层的代码分析开始，逐步搭建一个“学习助手 Agent”，知识库构建用 Embedding 向量化，检索生成用 RAG，工具调用走 MCP 协议，复杂任务用 Skills 封装，最后还要考虑上下文工程和接口 API 化。整条链路覆盖了当前 AI 应用开发最核心的几个关键词：Harness 架构、AI Agent、RAG、MCP、Embedding。

本文会围绕这条链路拆解三件事：第一，这套体系里每个技术点解决什么问题；第二，如何在本地把“Embedding → 向量库 → RAG 检索 → Agent 规划 → MCP 工具调用 → Skills 封装 → API 服务”的最小可运行链路跑通；第三，做知识库问答和代码分析时，哪些参数和配置会影响效果，哪些坑最常见。适合已经开始学 AI 应用开发、想从单个 API 调用进阶到完整项目落地的读者。

1. 核心能力速览

先把项目涉及的能力和使用门槛整理成一张表，方便快速判断值不值得投入时间。

需要说明的是，这个项目本身是一个“课程实战”定位，而不是某个现成的一键安装产品。它更重要的价值在于，让你把 Harness 架构下每个模块亲手搭一遍。因此下面的部署步骤和代码示例，遵循的是当前 AI Agent 与 RAG 工程的主流实践，具体项目里的目录名、端口和模型名需要按实际 README 调整。

2. 适用场景与使用边界

2.1 适合谁用

这类项目最适合三类人：一是刚学完 Prompt Engineering，想进入 Agent 开发的开发者，可以在项目里看到 Agent 如何调用工具、如何维护多轮上下文；二是团队里要做知识库问答原型的工程师，可以直接用这套链路验证企业内部文档问答的可行性；三是正在准备 AI Agent 面试或做课程设计的学生，把 Harness 架构、RAG、MCP、Embedding 这些关键词落到一个可运行项目里，比背概念更有说服力。

2.2 能解决什么问题

• 知识库问答：把课程资料、技术文档、内部手册写入向量库，用户提问后通过 Embedding 检索再交给大模型生成。
• 代码分析：把代码文件切片、向量化，Agent 可以定位指定函数、解释模块逻辑、对比实现方案。
• 工具调用：通过 MCP 协议接入数据库、文件系统、外部 API，让 Agent 不只是“聊天”，而是能执行动作。
• 技能复用：把固定的复杂任务封装成 Skills，比如“梳理项目结构”“生成测试用例”“按模板写周报”，一次封装，反复调用。

2.3 不适合什么场景

• 不适合对实时性要求极高的场景，RAG 检索和 Agent 多轮规划都会带来额外延迟。
• 不适合纯规则业务流程，如果逻辑完全确定，传统代码比 Agent 更便宜、更稳定。
• 不适合需要严格数据合规的刚上线生产系统，本地知识库中的数据、代码切片、日志都可能涉及敏感信息，需要先做权限和脱敏设计。
• 如果知识库只有几十条文本，RAG 收益有限，直接写进 Prompt 可能更快。

2.4 安全与合规边界

这个项目涉及文档解析、代码分析和知识库构建，使用时要特别注意：涉及企业内部资料、代码仓库、个人数据时，必须获得合法授权；在公开平台部署时要避免把敏感内容写入知识库；如果后续扩展语音、数字人、人脸相关能力，必须确认肖像权和声音授权。所有上传到云端模型的文本，都要先确认是否符合公司数据安全规范。

3. Harness 架构与项目技术拆解

3.1 什么是 Harness 架构

Harness 架构可以理解为一个围绕大模型构建的智能体运行框架。它把模型调用、上下文管理、技能注册、工具调用、记忆存储等能力放进一套可插拔的“调控层”中。学习助手项目以 Harness 架构作为主干，意味着它不是简单地“调用一次 API 生成答案”，而是由一套编排逻辑控制 Agent 的思考方式与执行动作。

对比直接调用 LLM API，Harness 架构多出的核心价值是：

• 上下文工程：系统性地组织 user message、system prompt、工具结果、检索片段，避免上下文爆炸。
• 工具调用管理：Agent 决定需要调用哪个工具时，框架负责执行并回填结果。
• Skills 封装：把高频任务固化为“技能”，Agent 根据任务自动选择。
• 可观测性：每一步决策和中间结果可记录、可调试。
• 多 Agent 协作：后续如果要扩展成多智能体企业采购助手，可以在 Harness 层增加任务拆分与结果汇总机制。

3.2 项目链路拆解

整个学习助手从代码分析到实战落地，可以拆成下面这条链路：

代码/文档输入 ↓ 文本解析与切片 ↓ Embedding 向量化 ↓ 向量库存储与索引 ↓ RAG 检索（多路召回 + 重排） ↓ Agent 任务规划（Harness 架构） ↓ MCP 工具调用 / Skills 技能执行 ↓ 上下文组装 + LLM 生成 ↓ Web 页面 / API 服务 / 批量脚本

这一串里，最容易做“通”的是 Embedding 和向量库检索，最需要调试的是 Agent 规划与工具调用。实际项目落地时，通常先跑通 RAG 基础问答，再逐步接入 MCP 和 Skills。

3.3 各技术点的作用

• Embedding：将文本映射成高维向量，让语义相近的内容在向量空间中距离更近，是 RAG 检索的基础。
• 向量库：存储 Embedding 向量并提供相似度检索，常见选择有 Chroma、FAISS、Milvus、Qdrant 等。
• RAG：检索增强生成，先从知识库拿相关片段，再让大模型基于片段生成答案，减少幻觉。
• Agent：在大模型基础上增加任务规划、工具调用和结果校验能力。
• MCP：模型上下文协议，Model Context Protocol，统一 Agent 与数据源、工具之间的连接方式。
• Skills：把提示词、参数和脚本封装成可复用的技能单元。
• 上下文工程：控制哪些内容进入上下文、以什么顺序进入、如何压缩和裁剪。

4. 环境准备与前置条件

4.1 开发环境清单

这个项目没有强制要求特定操作系统，但建议按下面的清单准备：

4.2 Python 环境与依赖

建议先创建虚拟环境，避免污染系统 Python。

conda create -n harness-agent python=3.11 -y conda activate harness-agent

再到项目目录安装核心依赖。因为不同项目的 requirements 差异很大，这里给出一套通用依赖组合，实际以项目要求为准：

pip install openai langchain langchain-community chromadb faiss-cpu pip install mcp fastapi uvicorn pydantic requests

如果使用 Ollama 管理本地模型：

# 安装 Ollama 后拉取模型示例 ollama pull qwen2.5:7b

4.3 模型与向量库准备

学习助手项目通常需要两类模型：

• 生成模型：负责最终回答、代码解释和 Agent 决策。可以选云端 API，也可以选本地 Qwen、Llama 系列。
• Embedding 模型：负责将文档和问题转为向量。本地常用的开源模型有 bge-m3、m3e-base，云端可以用 OpenAI 的 text-embedding-3-small。

向量库建议先用 Chroma 本地模式。它不需要额外启动服务，Python 进程内即可运行，适合验证链路。等到知识库规模变大，再迁移到 Milvus 或 Qdrant。

5. 安装部署与启动流程

5.1 目录结构规划

一个推荐的最小项目结构如下：

harness-learning-assistant/ ├── agent/ │ ├── core.py # Harness 架构核心编排逻辑 │ ├── planner.py # 任务规划 │ ├── skills/ # 技能目录 │ │ ├── code_analyzer/ │ │ └── rag_qa/ │ └── memory.py # 会话记忆 ├── rag/ │ ├── ingest.py # 文档入库 │ ├── retriever.py # 检索器 │ └── embedder.py # Embedding 封装 ├── mcp/ │ ├── server.py # MCP Server │ └── client.py # MCP Client 接入 ├── api/ │ ├── main.py # FastAPI 服务 │ └── schemas.py ├── config/ │ └── settings.yaml ├── data/ │ ├── sources/ # 原始文档 │ └── db/ # 向量库存储 └── scripts/ ├── batch_qa.py └── ingest_all.py

这样的目录结构把 Agent、RAG、MCP、API 分层隔离，方便后续替换任意一个模块。

5.2 文档入库

先准备一批学习资料，比如技术文档、Markdown 笔记、Python 源码文件。入库脚本的核心逻辑是读取文件、切片、计算 Embedding、写入向量库。

# rag/ingest.py 示例 from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings embedding_model = HuggingFaceEmbeddings( model_name="BAAI/bge-m3", model_kwargs={"device": "cpu"} ) text_splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=100 ) docs = text_splitter.split_text(source_text) vectorstore = Chroma.from_texts( texts=docs, embedding=embedding_model, persist_directory="./data/db" ) vectorstore.persist() print(f"已入库 {len(docs)} 个文本切片")

代码中的 model_name、切片大小和向量库目录，需要按实际项目替换。

5.3 启动 RAG 检索服务

文档入库后，先单独验证检索效果，再启动 Agent。检索测试脚本：

from langchain_community.vectorstores import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings embedding_model = HuggingFaceEmbeddings(model_name="BAAI/bge-m3") vectorstore = Chroma( persist_directory="./data/db", embedding_function=embedding_model ) query = "什么是 Harness 架构？" results = vectorstore.similarity_search(query, k=4) for idx, doc in enumerate(results): print(f"--- 结果 {idx + 1} ---") print(doc.page_content)

这一步重点看两个东西：检索结果的相关度是否可接受；返回的片段是否包含足够上下文。如果相关度差，优先调整切片大小和召回数量。

5.4 启动 Agent 主服务

Agent 主服务把检索结果、用户提问和工具调用整合到 Harness 架构的上下文中。启动命令通常是：

# 通用启动方式，具体以项目 README 为准 python agent/core.py --config config/settings.yaml

如果项目提供 Web UI，启动后浏览器访问提示的本地地址即可。如果没有 Web UI，可以直接通过 Python 脚本交互。

6. 功能测试与效果验证

6.1 基础知识问答测试

测试目标：验证 RAG 检索链路是否打通。

from rag.retriever import Retriever retriever = Retriever() query = "RAG 和 Fine-tuning 有什么区别？" context = retriever.search(query, top_k=5) for i, chunk in enumerate(context): print(f"[片段 {i+1}] {chunk[:200]}")

判断标准：检索出的片段是否提到“检索增强生成”“微调”“幻觉”等关键概念。如果检索片段明显不相关，问题可能出在 Embedding 模型或切片方式上，而不是大模型。

6.2 代码分析测试

测试目标：验证 Agent 能否完成代码级任务。

输入示例：

请分析 agent/planner.py 中 plan_tasks 函数的执行流程，并指出可能出现异常的地方。

预期行为：Agent 先定位文件，再读取代码片段，通过 RAG 检索同类代码模式，最终生成结构化的分析结果。判断是否成功的标准是：回答中是否包含对函数输入、分支逻辑、返回值以及异常点的具体描述，而不是泛泛而谈。

如果 Agent 回答太泛，可以在 System Prompt 中增加约束，要求“必须引用代码行号”或“必须先展示读取到的代码片段”。

6.3 多轮对话测试

测试目标：验证上下文工程和记忆能力。

用户第一轮：帮我总结一下这个项目的目录结构。 用户第二轮：刚才说的 skills 目录具体放什么？ 用户第三轮：那如果要新增一个技能，我需要改哪些文件？

多轮对话的难点在于，后续问题往往依赖前文信息。Harness 架构下，上下文工程要解决的是“每轮携带哪些历史信息”。如果回答忘记前文，需要检查记忆模块是否把关键信息放进了上下文。

6.4 参数调整验证

针对 RAG 检索，建议测试以下几组参数：

调整时每次只改一个参数，并记录一组测试问题，便于对比效果。

7. RAG 检索优化与上下文工程

7.1 从单路召回升级到多路召回

基础 RAG 通常只用向量相似度检索，也就是标题里提到的 dense vector search。但真实知识库中，纯向量检索存在漏检问题，尤其是专有名词、代码标识符、精确匹配场景。实战中可以升级为多路召回：

• 向量召回：语义相似度检索，适合“意思相近但用词不同”的问题。
• 关键词召回：BM25 或 Elasticsearch 精确匹配，适合代码函数名、型号、生僻词。
• 重排：将多路召回结果合并后，用 rerank 模型重新打分，保留最相关的片段。

多路召回 + 重排是当前 RAG 实战中效果提升最明显的一组改动。如果课程项目里做了这个点，可以重点说明实现方式和效果对比。

7.2 上下文工程核心原则

上下文工程不是简单地把所有检索结果拼到 Prompt 里。核心原则有三条：

• 相关性优先：无关片段会显著干扰大模型输出，宁肯只给 3 个高质量片段，也不要把 10 个低质量片段全部塞进去。
• 结构清晰：用明确的标记区分“用户问题”“检索片段”“工具结果”“历史对话”，降低模型理解成本。
• 控制总量：大模型上下文窗口有限，检索片段按长度排序，超长部分压缩或截断。

7.3 上下文组装示例

# 构建 RAG 上下文的伪代码示例 context_blocks = [] for i, doc in enumerate(results[:4]): block = f"[知识片段 {i+1}]\n来源: {doc.metadata.get('source', 'unknown')}\n内容: {doc.page_content}" context_blocks.append(block) context_text = "\n\n".join(context_blocks) prompt = f"""你是学习助手，请基于以下知识片段回答问题。 {context_text} 用户问题：{user_query} 回答要求： 1. 优先引用知识片段中的内容。 2. 如果片段不足以回答，明确说明“知识库中未找到相关信息”。 3. 不编造不存在的概念。"""

这套思路同样适用于代码分析任务，只是把“知识片段”换成“代码片段”和“解析结果”。

7.4 Agentic Rag

如果有余力，可以在检索前增加 Agent 判断。基础 RAG 对“一句话问题”效果尚可，但复杂问题需要拆分子问题。Agentic RAG 的思路是：让 Agent 先判断“这个问题需要检索吗？需要检索哪些主题？”，然后动态决定执行一次还是多次检索。这个模式从效果上更接近学习助手这类场景，因为用户提问往往不是孤立的一句话，而是一连串探索性学习问题。

8. MCP 工具接入与 Skills 技能封装

8.1 MCP 是什么

MCP，全称 Model Context Protocol，模型上下文协议。它解决的核心问题是：Agent 要访问数据库、文件系统、外部 API 时，不需要为每个工具写一套私有调用逻辑，而是通过统一的协议接入 MCP Server。

从学习助手项目看，一个典型用法是让 Agent 能读取本地文件、查询数据库、执行代码搜索。前端问“README 里的安装步骤是什么”，Agent 不再只靠 RAG 片段，而是主动调用文件读取工具拿到原文。

8.2 MCP Server 配置模板

如果是基于 Node.js 的 MCP Server，配置通常长这样：

{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "./data/sources" ] } } }

如果是 Python 实现，也可以在 Agent 代码中直接初始化 MCP 客户端：

# mcp/client.py 示例 from mcp import ClientSession, StdioServerParameters server_params = StdioServerParameters( command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "./data/sources"] ) # 建立会话后，将工具列表交给 Agent 调度 session = ClientSession(server_params)

需要说明的是，MCP 生态更新很快，不同语言的 SDK 接口存在差异，实际运行时以 MCP 官方文档和项目依赖版本为准。

8.3 Skills 技能封装

Skills 把“固定的复杂任务”沉淀为可复用模块。一个技能通常包含三个部分：

agent/skills/code_analyzer/ ├── SKILL.md # 技能说明、触发条件和参数定义 ├── prompt.md # 给 LLM 的任务指令模板 └── execute.py # 执行脚本，可选

SKILL.md 示例：

--- name: code_analyzer description: 分析指定代码文件的结构、函数逻辑和潜在问题 triggers: - "分析代码" - "这段代码" - "这个函数" - "代码结构" params: file_path: type: string required: true --- 分析任务说明： 1. 先读取目标文件。 2. 列出文件中定义的类和函数。 3. 对每一个主要函数，说明输入、处理逻辑和输出。 4. 指出可能出现的边界条件和异常。

Agent 收到用户消息后，先通过触发词匹配技能，再把技能参数解析出来，最后由 Harness 框架执行技能流程。这种方式最大的收益是：同样的代码分析逻辑不需要在每次对话中重新生成一遍 Prompt，可维护性和稳定性都会好很多。

8.4 多智能体扩展思路

热搜词里提到的“基于 Harness 架构的多智能体企业采购助手”，本质上就是在这套单 Agent 能力上增加任务分发与结果汇总。比如一个采购助手可以拆成“需求理解 Agent”“供应商检索 Agent”“价格对比 Agent”“合规检查 Agent”，由 Harness 架构统一调度。学习助手项目练熟之后，往多智能体方向扩展是比较自然的一步，核心改动是增加 Agent 间的消息传递和任务结果聚合逻辑。

9. 接口 API 与批量任务

9.1 用 FastAPI 封装查询接口

学习助手做好之后，最好提供 HTTP 接口，这样前端、脚本和第三方工具都能接入。推荐用 FastAPI 封装一个统一查询接口。

# api/main.py 示例 from fastapi import FastAPI from pydantic import BaseModel from agent.core import LearningAssistant app = FastAPI() assistant = LearningAssistant() class QueryRequest(BaseModel): question: str use_rag: bool = True tools: list[str] = [] session_id: str = "default" class QueryResponse(BaseModel): answer: str sources: list[str] = [] agent_trace: list[str] = [] @app.post("/query", response_model=QueryResponse) async def query_learning_assistant(req: QueryRequest): result = assistant.ask( question=req.question, use_rag=req.use_rag, tools=req.tools, session_id=req.session_id ) return QueryResponse( answer=result["answer"], sources=result["sources"], agent_trace=result["trace"] ) @app.get("/health") async def health_check(): return {"status": "ok"}

启动方式：

# 在项目根目录执行 uvicorn api.main:app --host 0.0.0.0 --port 8000

启动后可以用 curl 验证：

curl -X POST http://127.0.0.1:8000/query \ -H "Content-Type: application/json" \ -d '{"question": "解释一下项目中的 RAG 检索流程", "use_rag": true}'

9.2 批量任务设计

批量任务主要分两类：一类是批量文档入库，另一类是批量问答验证。

批量问答脚本的核心逻辑：

import json import time import requests questions = [ "什么是 RAG？", "MCP 协议解决了什么问题？", "如何选择 Embedding 模型？", "上下文工程有哪些核心原则？" ] results = [] for q in questions: payload = { "question": q, "use_rag": True, "session_id": "batch-test" } resp = requests.post("http://127.0.0.1:8000/query", json=payload, timeout=60) if resp.status_code == 200: item = { "question": q, "answer": resp.json()["answer"], "sources": resp.json()["sources"] } results.append(item) print(f"[OK] {q}") else: print(f"[FAIL] {q}, status={resp.status_code}") # 避免请求过快，简单限速 time.sleep(0.5) with open("batch_output.jsonl", "w", encoding="utf-8") as f: for item in results: f.write(json.dumps(item, ensure_ascii=False) + "\n") print(f"完成 {len(results)}/{len(questions)} 条任务")

批量任务有两个关键点：一是输出要写日志，记录哪些问题成功、哪些失败；二是失败要有重试机制，单次超时可以单独重试，不要整个脚本从头跑。

9.3 失败重试建议

如果接口调用超时或返回 500，先区分是模型服务挂了还是 Agent 链路异常。可以加一层简单重试：

def query_with_retry(url, payload, max_retries=3, timeout=60): for attempt in range(max_retries): try: resp = requests.post(url, json=payload, timeout=timeout) if resp.status_code == 200: return resp.json() print(f"attempt {attempt+1} failed, status={resp.status_code}") except requests.exceptions.Timeout: print(f"attempt {attempt+1} timeout") time.sleep(2 * (attempt + 1)) return None

这里要特别提醒：接口服务如果部署在服务器上，不要直接暴露到公网，至少要加 Token 鉴权或限制访问 IP，否则容易被刷接口。

10. 资源占用与性能观察

10.1 观察哪些指标

运行学习助手项目时，重点看四类资源指标：

• 内存占用：文档入库时，大批量文本会一次性加载到内存，容易造成 OOM。
• 显存占用：本地跑 7B 模型时，显存占用通常在 6GB 到 12GB 之间，具体取决于量化精度和上下文长度。
• CPU 占用：Embedding 模型在 CPU 上运行速度较慢，批量入库时 CPU 会接近打满。
• 延迟：单次问答包含“向量检索 + 模型生成 + 工具调用”，总延迟比单次 LLM API 调用高很多。

10.2 性能优化手段

显存不够时，可以按顺序尝试：

1. 用量化版本模型，比如 Q4_K_M、Q8 等 GGUF 量化版本。
2. 缩小上下文长度，减少输入 token。
3. 关闭多进程并行推理，减少显存峰值。
4. 把 Embedding 模型放到 CPU，把生成模型放到 GPU。

批量文档入库速度慢时，可以批量计算 Embedding，而不是一条文本调用一次模型接口。

10.3 如何定位性能瓶颈

• 如果检索慢：排查 Embedding 模型和向量库。
• 如果生成慢：排查大模型服务和上下文长度。
• 如果工具调用慢：排查 MCP Server 的启动速度和外部接口延迟。
• 如果整体卡顿：先看是不是本地模型推理占满了全部资源。

不建议一上来就追求极致性能。先跑通最小链路，再根据日志耗时逐步优化。

11. 常见问题与排查方法

补充两个比较隐蔽的问题：

第一，本地模型和 Embedding 模型的设备不一致会导致首次调用很慢。比如 Embedding 用 CPU，生成模型用 GPU，第一次加载都会有几秒到几十秒的冷启动时间，不要误判为死机。

第二，多 Agent 扩展时，任务间日志顺序容易混乱。建议每一步都加上 trace_id 和 agent 名称，便于复盘。

12. 最佳实践与合规建议

12.1 工程化建议

• 第一次跑不要追求功能全，先把“文档入库 → 检索 → 问答”这条最短链路跑通，再加 MCP 和 Skills。
• 保留一套最小可运行配置，记录在一个配置文件里，出现问题时可以快速回退。
• 模型文件、输入素材、输出结果分目录管理，避免把 GB 级模型文件放进代码仓库。
• 批量任务要加日志和失败重试，输出结果使用 JSONL 格式，方便后续分析。
• 接口服务要限制访问范围，至少配置 Token 鉴权，不要把调试端口暴露到公网。
• 所有涉及知识库更新的操作，先做小规模验证再全量执行。

12.2 RAG 效果评估

课程项目里应该加入一个简单的评估集，而不是只看一两个问题回答得好不好。构建方式：

• 准备 20 到 50 个标准问题。
• 每个问题记录正确答案来源。
• 跑完 RAG 后，统计“答案包含正确来源”的比例。
• 修改参数后重复测试，对比指标变化。

这个评估集虽然简单，但比人工“感觉变好了”可靠得多。后续如果要进阶，可以引入 RAG 测评维度的自动化打分。

12.3 合规要点

这个项目会涉及文档解析、代码切片和知识库管理，必须确认资料来源合法。企业内部使用时，不要在未授权情况下把私有代码仓库、商业文档写入知识库；如果使用云端大模型 API，要注意提交的文本内容是否符合数据安全规范。项目扩展语音、声音克隆、数字人等功能时，必须获得相关人员和版权的明确授权。商用前需要进行效果复核，不能直接依赖未经评估的模型输出。

13. 总结与下一步

这个项目最值得尝试的点，是把 AI Agent 学习中容易“飘在概念层”的知识全部落了地。通过一个学习助手项目，你可以亲手把 Embedding、RAG、MCP、Skills、上下文工程串成一条可运行链路，而 Harness 架构提供的编排能力，则为后续扩展多智能体协作打下了基础。

建议第一步先验证两件事：RAG 检索能不能在自己的测试资料上返回相关内容；Agent 能不能在检索结果基础上生成有用答案。这两个点验证通过后，再逐步接入 MCP 工具和 Skills 技能。

最容易踩的坑有三个：一是文档切片参数不合理导致检索效果差；二是一上来就追求多智能体复杂编排，链路太长排错困难；三是忽略上下文中无关片段对回答质量的干扰。

后续可以扩展的方向包括：用 rerank 模型优化 RAG 效果、把单 Agent 升级为多智能体协作、增加语音交互入口、把学习助手接入企业采购或文档管理等业务场景。只要先把这套 Harness 架构下的最小链路吃透，后续所有扩展都会变得顺理成章。建议收藏备用，动手跑通一次比看十遍概念都有用。