主题
需求分析：我们到底要造什么？
读完这篇文档，你会明白 AI Agent 是什么、为什么值得从零构建一个、以及 miniOpenClaw 要解决的核心问题。
一、从聊天机器人到 AI Agent
1.1 你可能已经用过的"聊天机器人"
打开 ChatGPT，输入一个问题，它回答你——这就是最简单的聊天机器人。它的工作方式很单一：
你说话 → AI 想一想 → AI 回话这就像一个只会动嘴皮子的人：你问他"今天天气怎么样"，他只能凭记忆猜，因为他没法打开手机查天气 App。
1.2 AI Agent 是什么？——一个"能干活的智能员工"
AI Agent（智能体）在聊天机器人的基础上，加了两样关键能力：
| 对比维度 | 聊天机器人 | AI Agent |
|---|---|---|
| 有没有"脑子" | 有（LLM 大模型） | 有（同样的 LLM） |
| 能不能"动手" | 不能，只会说 | 能！可以调用工具（查天气、算数学、读文件……） |
| 有没有"记性" | 有限（一次对话内） | 有！短期+长期记忆 |
| 能不能"学新技能" | 不能 | 能！可以加载技能包 |
用一个生活类比来说：
聊天机器人 = 一个只能打电话聊天的朋友 AI Agent = 一个能帮你跑腿办事的私人助理
这个"私人助理"：
- 有脑子（LLM）：能理解你说的话，思考该怎么做
- 有手（Tools）：能上网查资料、做计算、发请求
- 有记性（Memory）：记得你上次说过什么、你的偏好是什么
- 有技能证书（Skills）：遇到翻译任务自动切换到"翻译模式"
- 有通讯录（MCP）：还能联系外部的专业服务来帮忙
1.3 AI Agent 的思考方式：ReAct
AI Agent 不是一口气回答你的问题，而是像人类一样边想边做。这个模式叫 ReAct（Reasoning + Acting，推理 + 行动）：
你问："北京现在几度？比昨天高还是低？"
Agent 的脑回路：
1. 想一想：用户问北京温度和昨天对比，我需要查天气
2. 动手做：调用"天气查询工具" → 拿到结果：今天 25°C
3. 再想想：还需要昨天的温度才能对比
4. 再动手：调用"历史天气工具" → 昨天 22°C
5. 最终回答：北京现在 25°C，比昨天高 3 度这种"想一步做一步"的工作方式，就是 miniOpenClaw 要实现的核心逻辑。
二、为什么要从零构建？
2.1 "买家具"还是"学木工"？
市面上有很多现成的 AI Agent 框架（LangChain、AutoGen、CrewAI 等），就像宜家的成品家具——买回来直接用。那为什么还要自己从零开始？
| 对比 | 用现成框架（买家具） | 从零构建（学木工） |
|---|---|---|
| 速度 | 快，几行代码就能跑 | 慢，要一步步搭建 |
| 理解深度 | 浅，知道怎么用不知道为什么 | 深，每一行代码都是自己写的 |
| 灵活性 | 受框架限制 | 完全可控 |
| 出问题时 | 很难定位，依赖框架社区 | 自己写的自己最清楚 |
| 学习价值 | 学会了"用框架" | 学会了"造框架" |
miniOpenClaw 选择"学木工"路线：不使用任何 AI Agent 框架，只用基础工具库（如 WebSocket 库、HTTP 库），从第一行代码开始搭建。
2.2 这就像学做菜
你可以买预制菜，加热就能吃。但如果你想成为一个好厨师，你需要从洗菜、切菜、控火开始学。miniOpenClaw 就是那本"从零开始的菜谱"。
三、核心需求：我们的"私人助理"需要哪些能力？
我们用"用户故事"的方式来梳理需求——每个需求都从"作为用户，我希望..."开始：
3.1 需求清单
| 编号 | 用户故事 | 对应模块 | 章节 |
|---|---|---|---|
| N1 | 作为用户，我希望通过网络和 AI 助理实时对话 | Gateway（网关） | Day 1 |
| N2 | 作为用户，我希望通过命令行、网页、甚至微信都能找到 AI 助理 | Channel（渠道） | Day 2 |
| N3 | 作为用户，我希望 AI 助理记住我们的对话历史，不要每次都从头开始 | Session（会话） | Day 3 |
| N4 | 作为用户，我希望 AI 助理不只是聊天，还能帮我做事（查信息、做计算） | Agent（推理引擎） | Day 4 |
| N5 | 作为开发者，我希望能方便地给 AI 助理添加新能力（新工具） | Tools（工具） | Day 5 |
| N6 | 作为开发者，我希望能用一个文件就定义一种"AI 人设"（翻译官、程序员...） | Skills（技能） | Day 6 |
| N7 | 作为用户，我希望 AI 助理能记住我的偏好，下次聊天时还记得 | Memory（记忆） | Day 7 |
| N8 | 作为开发者，我希望能接入社区里别人写好的工具服务 | MCP（协议） | Day 8 |
3.2 为什么是这个顺序？
这 8 个模块不是随便排列的，而是有严格的依赖关系——就像盖房子，必须先打地基：
- Day 1-3 是"基础设施"：消息怎么传、从哪来、对话怎么管理——没有这些，Agent 连用户说了什么都收不到
- Day 4 是"核心大脑"：有了基础设施，才能开始做推理——这是整个系统的心脏
- Day 5-6 是"能力扩展"：大脑有了，给它装上"手"和"知识"
- Day 7-8 是"进阶增强"：让 Agent 有记忆、能和外部生态对接
四、名词表：把"黑话"翻译成人话
在后续的学习中，你会频繁遇到以下术语。这里先统一给出通俗解释，遇到不理解的随时回来查：
| 术语 | 英文 | 通俗解释 | 生活类比 |
|---|---|---|---|
| Gateway | 网关 | 系统的"大门"，所有消息都从这里进出 | 小区门卫室，所有快递都从这里收发 |
| Channel | 渠道 | 用户和系统交互的方式（命令行、网页、微信等） | 寄快递的方式：上门取件、驿站寄件、合作网点 |
| Session | 会话 | 一次完整的对话过程，包含所有聊天历史 | 银行客户档案，记录了你所有的交易记录 |
| Agent | 智能体 | 能自主思考和行动的 AI 程序 | 一个能帮你跑腿办事的私人助理 |
| LLM | 大语言模型 | 像 ChatGPT 这样的 AI 大脑 | Agent 的"脑子" |
| ReAct | 推理+行动 | Agent 的思考方式：想一步做一步 | 员工处理问题的方式：先想再做 |
| Tool | 工具 | Agent 能调用的外部能力（查天气、算数学等） | 员工工具箱里的锤子、螺丝刀 |
| Skill | 技能 | 预定义的 Agent 行为模式（翻译模式、编程模式等） | 员工的技能证书（翻译证、编程证） |
| Memory | 记忆 | Agent 记住信息的能力 | 员工的笔记本（便签纸 + 档案柜） |
| MCP | 模型上下文协议 | Agent 和外部工具服务通信的标准格式 | 公司之间合作的标准合同模板 |
| EventBus | 事件总线 | 组件之间传递通知的机制 | 公司内部的广播系统 |
| WebSocket | 全双工通信协议 | 客户端和服务端可以随时互相发消息 | 打电话（双方随时说话） |
| Pydantic | 数据校验库 | 确保数据格式正确的工具 | 快递单格式检查（重量、地址都要填对） |
| JSON Schema | JSON 格式描述 | 描述"某个数据应该长什么样"的规范 | 工具使用说明书上的"参数列表" |
| Token | 令牌 | LLM 处理文本的最小单位（大约 1 个汉字 = 1-2 个 token） | 打字计费的"字数" |
| TTL | 生存时间 | 数据的有效期，过了就自动删除 | 银行卡的有效期 |
| ABC | 抽象基类 | 定义"接口规范"的 Python 类，子类必须实现指定方法 | 模具：规定了产品的形状，具体材料由子类决定 |
| async/await | 异步编程 | 让程序在等待时去做别的事，而不是干等着 | 服务员在等菜的时候去招待其他桌 |
五、项目边界：我们不做什么
明确边界和明确需求一样重要：
| 不做的事 | 原因 |
|---|---|
| 不做多模型切换（同时用多个不同的 LLM） | 聚焦核心逻辑，保持简单 |
| 不做用户认证和权限管理 | 这是 Web 框架的事，不是 Agent 框架的核心 |
| 不做前端 UI 框架（React/Vue 等） | 有独立的可视化页面辅助理解，但核心价值在后端逻辑 |
| 不做分布式部署 | 教学项目聚焦单机，生产环境再考虑扩展 |
| 不做向量数据库集成 | 长期记忆用简单的文件存储，避免引入额外基础设施 |
六、学完之后你能获得什么？
完成这 8 天的学习后，你将：
- 理解 AI Agent 的完整架构：从消息接收到推理回复的每一个环节
- 掌握异步编程实践：Python asyncio 的真实应用场景
- 具备框架设计能力：理解"抽象基类 → 具体实现 → 注册管理"的设计模式
- 能独立扩展系统：自己写新工具、新技能、新渠道
- 看懂主流 Agent 框架：理解 LangChain、AutoGen 等框架"在帮你做什么"