上一篇我们搞清了 Agent 的四个器官：大脑、双手、笔记本、工作循环。本篇做三件事：定需求、画架构、配环境。磨刀不误砍柴工。
一、定需求：我们要做一个什么 Agent？
新手最容易犯的错是"我想做一个啥都会的 Agent"——啥都会等于啥都不精。正确的做法是：从一个真实场景出发，把功能列成清单。
我们的目标场景：个人全能助手。功能清单：
| 需求 | 对应器官 |
|---|---|
| 能聊，且聊得像个人 | 大脑（LLM） |
| 能查时间、算数、管待办 | 工具 |
| 能读写文件、上网 | 工具 |
| 记住我上次说过的话 | 记忆（会话历史） |
| 记住我的偏好（跨天有效） | 记忆（长期记忆） |
| 能回答我私有文档里的问题 | RAG |
| 会按规范写周报、润色英文 | 技能系统 |
| 有个像样的界面 | CLI + Web |
看到规律了吗？每一条需求都精确映射到一个模块。这就是架构设计：不是画漂亮的图，而是让每个需求都有去处。
二、整体架构图
你（用户）
│ 输入
▼
┌───────────── CLI (main.py) / Web (web/server.py) ─────────────┐
│ │
│ ┌────────────────── Agent 核心循环 (agent/core.py) ──────┐ │
│ │ │ │
│ │ 1. 组装上下文：系统提示 + 记忆 + 检索结果 │ │
│ │ 2. 调 LLM → 模型要么回答，要么"点菜"（要工具） │ │
│ │ 3. 执行工具 ← tools/registry.py 统一调度 │ │
│ │ 4. 结果回填 → 回到 2（循环，直到模型给出最终回答） │ │
│ └────────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ agent/llm.py agent/memory.py agent/rag.py agent/skills.py
│ 大模型客户端 三层记忆 TF-IDF检索 技能加载 │
│ │
│ 持久层：storage/（记忆、会话、待办） knowledge/（知识库） │
└────────────────────────────────────────────────────────────────────┘
对应到磁盘上的目录（先混个脸熟，每篇教程会各自展开）：
zhiliao/
├── main.py ← CLI 入口（装配各模块）
├── config.py ← 读 .env 配置
├── agent/
│ ├── core.py ← ★ 核心循环，整个项目的心脏
│ ├── llm.py ← 大模型客户端
│ ├── memory.py ← 记忆
│ ├── rag.py ← 知识库检索
│ ├── skills.py ← 技能系统
│ ├── prompts.py ← 系统提示词
│ └── assemble.py ← 工具装配车间
├── tools/ ← 13 个工具 + 注册表
├── skills/ ← 技能文件（markdown）
├── knowledge/ ← 知识库文档（markdown）
├── web/ ← Web 版界面
└── tests/ ← 离线测试
三、技术选型：每个选择背后的"为什么"
1. 语言选 Python？ 生态最全（大模型 SDK 都是 Python 优先）、语法接近自然语言、出了问题网上答案最多。JavaScript 也可以，但教程得选一头扎下去。
2. 模型接口选"OpenAI 兼容协议"？
这是本教程最重要的一个工程决策。OpenAI 的 /chat/completions 接口格式已经成了行业事实标准——智谱、DeepSeek、Kimi、通义、本地 Ollama 全都兼容它。所以：
# agent/llm.py 里的全部秘密：换模型 = 换三个配置，代码零改动
client = OpenAI(base_url=cfg.base_url, api_key=cfg.api_key)
.env 里改三个值，今天用 GLM，明天换 DeepSeek，周末用本地模型跑。
3. 为什么不用 LangChain？ 三个理由：① 教学的目的是让你理解原理，框架把原理藏起来了；② 本项目全部核心代码加起来几百行，引入框架反而更重；③ 框架抽象会漏水，不懂原理的人用框架只会调不动参。第 9 篇我们会认真对比"什么时候值得上框架"。
4. 为什么不用向量数据库？ 你的个人知识库大概就几十篇文档，手写的 TF-IDF 检索（第 6 篇）完全够用，零部署零依赖。等真到了百万级文档，再上向量库不迟——那时你已经懂原理了。
5. 数据全用本地文件（JSON/markdown）？ 够用 + 可见。你的记忆、待办都是能直接打开看的文本文件，调试时眼睛看得见，比数据库友好得多。
四、配环境：10 分钟搞定
1. 装 Python：到 python.org 装 3.10 以上（Windows 安装时勾选 "Add Python to PATH"）。
2. 装依赖：
cd zhiliao
pip install -r requirements.txt
3. 申请 API Key（拿一把"大脑"的钥匙）
任何 OpenAI 兼容平台都行，推荐新手用智谱 GLM（对新手友好，注册后有免费额度，具体以官网为准）：
- 打开
open.bigmodel.cn→ 注册 → 控制台 → API Keys → 创建并复制 - 其他选择：DeepSeek（
platform.deepseek.com，便宜）、Kimi（platform.moonshot.cn）、本地 Ollama（免费不联网）
4. 写配置：把 zhiliao/.env.example 复制成 .env，填三行：
LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
LLM_API_KEY=粘贴你的密钥
LLM_MODEL=glm-4-flash
⚠️
.env就是你的钥匙串：不要提交到 Git、不要截图发群里。项目的.gitignore已经把它排除。
5. 先跑测试，再谈人生：python tests/test_basic.py 和 python tests/test_agent_loop.py——48 项检查全部通过（后者用假模型模拟"调工具循环"），说明骨架是好的。都不需要 API Key。
五、一个值得提前理解的思想：依赖注入
看 main.py 的装配代码：
llm = LLMClient(cfg.base_url, cfg.api_key, cfg.model) # 大脑
memory = Memory.load_session(...) # 笔记本
rag = load_knowledge_dir(cfg.knowledge_dir) # 资料库
skills = SkillBook(cfg.skills_dir) # 秘籍
registry = build_registry(cfg, rag, skills) # 工具箱（含技能/知识库工具）
build_memory_tools(registry, memory) # 把记忆也注册成工具
agent = Agent(cfg, llm, memory, rag, skills, registry) # 组装！
每个模块都不自己创建依赖，而是由"装配处"递进去——这叫依赖注入。好处马上能看到：测试时可以塞一个假 LLM、假记忆进去，所以我们的 48 项测试一个 API Key 都不用。这也是"模块解耦"最朴素的样子。
本篇作业
- 跑通
tests/test_basic.py和tests/test_agent_loop.py，确认全部 PASS。 - 打开
zhiliao/.env.example通读一遍注释，理解"换模型 = 换配置"。 - 思考题：如果让你给自己的 Agent 加一个"提醒我喝水"的功能，你觉得需要动哪几个模块？（不用做，带着这个问题进入下一篇）
下一篇预告：《03 · 核心循环》——本系列最重要的一篇。我们逐行剖析 Function Calling 协议，亲手写出"思考→行动→观察"的 ReAct 循环。看懂这一篇，你就看懂了所有 Agent 产品的底层。