最近关注 AI 领域尤其是通用智能体构建的小伙伴们，大概率见过各种开源 Agent 框架：OpenCode、OpenManus、OpenClaw、hermes-agent……
它们功能强大，但有一个共同的问题——**学起来太重了。**
几百上千行的抽象层、回调链、记忆模块、多 Agent 编排……一个新人在这些框架面前，连"Agent 到底怎么工作的"都搞不清，就被淹没在抽象里了。就拿 hermes 来说，仅单个 run_agent.py 文件就包含上万行代码。
所以我尝试 **从最基础的范式完成一个简单Agent，并通过版本控制逐步引入新功能，任何人都可以通过 git checkout 回到过去的任何一个版本，在没有冗余代码干扰的情况下，学习最精简的代码实现**。
一、项目细节
项目： **Agent-Base-Zero**，
GitHub 地址：https://github.com/frecol/Agent-Base-Zero。
介绍：这是一个**学习项目**。目的是帮助小伙伴们一起理解 Agent 本质、一起构造 Agent。
与其写一堆文档解释最终成品，不如把构建过程本身作为学习材料。每一版代码都完整可运行，每一版都比前一版多一个核心概念。
- 核心理念：每个 commit 都是一个至简的版本。
大多数开源项目，commit 的信息是 "fix bug"、"refactor xxx"、"update deps"。 clone 下来，面对的是最终成品，中间怎么一步步搭起来的？不知道。而 Agent-Base-Zero 反其道而行：**每个 commit 代表一个完整的 Agent 版本。**
| 版本 | 主题 | 核心概念 |
| v0.1 | 最小可用 Agent | Agent 循环、工具调用、CLI、工具注册表 |
| v0.2 | 流式与思维链 | 流式输出、DeepSeek 思维链模式、联网搜索、时间工具 |
| v0.3 | 记忆系统 | 会话持久化、长期记忆、上下文压缩 |
| v0.4 | 技能系统 | 技能注册、PromptManager、LLM 自动激活、组合工具 |
| v0.5 | 规划与执行 | 任务分解、多步规划、自我反思 |
| v0.6 | 社交媒体接入 | API 集成、异步操作 |
| v0.7 | 多智能体协作 | Agent 协同、任务路由 |
目前已经实现到v0.5版本，想学哪一版，直接 `git checkout` 到对应的 commit，读的就是对应版本的完整代码。没有历史包袱，没有未完成的抽象，每一版都是**可运行、可理解**的。
二、版本基础讲解
2.1 版本v0.1：300 行，让你看懂 Agent 的本质
AI Agent 听起来高大上，剥开来其实就是两个东西：
1. **一个循环**：接收输入 → 调 LLM → 执行工具 → 再调 LLM → 直到出结果
2. **一个工具注册表**：告诉 LLM 有什么工具可用，按名字派发调用
v0.1 用 300 行 Python 实现了这两件事：
for _ in range(MAX_ITERATIONS): response = client.chat(messages, tools=tools) if response.has_tool_calls: execute_tool_calls(response.tool_calls) # 继续循环，把工具结果送回 LLM else: return response.text # 最终回复没有复杂的链式调用，没有抽象的 Agent Executor，就是 **while 循环 + if 判断**。任何会 Python 的人看完都能理解 Agent 的原理。
工具注册也是极简模式：在 `tools/` 目录下放一个 Python 文件，定义 `SCHEMA` (描述如何填写参数)和 `handler`(执行逻辑)，import 时自动注册。写新工具就像填空。
2.2 版本v0.2：让 Agent 学会"思考"和"上网"
这版加了三个关键能力：
**流式输出** — 不是一次性等 LLM 吐出全部结果，而是逐 token 渲染。我把每次流式输出结构化成了 `StreamEvent`（thinking/content/done 三种事件），CLI 层根据事件类型分别展示思考过程和最终回复。
**Thinking** — DeepSeek 的 `reasoning_content` 字段让 LLM 在回答前先输出推理过程。你可以在终端里实时看到它"在想什么"，对理解 LLM 的决策逻辑非常有帮助。
**联网搜索** — 用了 DuckDuckGo 的搜索 API（无需 Key），加上一个 `current_time` 工具配合。用户说"搜一下今天的新闻"，Agent 先获取当前时间，再带着日期去搜索。
2.3 版本v0.3：让 Agent 拥有"记忆"
这是最实用的一个版本。三个能力：
**会话持久化** — 每次对话自动保存到 `.genesis/sessions/{session_id}.json`。可以 `/sessions` 列出所有历史会话，`/resume <id>` 恢复到之前的对话继续聊。用原子写入（先写 tmp 文件再 rename），防止崩溃丢数据。
**长期记忆** — 不是每轮自动提取关键词那种粗暴方式，而是给 LLM 一个 `memory_save` 工具，由它自己判断什么值得记住。用户偏好、环境配置、常用约定……LLM 自主决定保存。下个会话启动时自动注入。
**上下文压缩** — 对话长了 token 不够？当达到 95% 上限时，自动把中间部分发给 LLM 做结构化摘要，保留头部 3 条和尾部 20 条完整消息。压缩后 token 占用从几万降到几千。
2.4 版本v0.4：让 Agent 具备"角色切换"能力(引入skills)
这是目前已经实现的最新版。核心是技能系统。
每个技能是一个 `SKILL.md` 文件（兼容 Claude Code 的标准格式），定义了 LLM 在特定场景下的行为模式：
skills/ ├── research/ # → "你现在是搜索研究专家" │ └── SKILL.md └── code_assistant/ # → "你现在是代码助手专家" └── SKILL.mdLLM 启动时看到所有技能的索引（名称 + 一句话描述）。当用户说"帮我搜一下 Python 最新版本"，LLM 发现 `research` 技能匹配，就自主调用 `activate_skill("research")`，加载完整的专家指令(这是参考hermes的实现方式，由LLM自主通过工具加载skill，保持前缀缓存不被破坏)。
这套设计的巧妙之处在于 **缓存友好**：
- 系统提示词（含技能索引）在整个会话中保持不变 → LLM 提供商的 prefix cache 始终命中，省钱
- 技能详细指令通过 `activate_skill` 工具结果传递，不污染 system prompt
- 切换技能只需一次工具调用，无需重发整个系统提示词
2.5 版本v0.5：Plan/Normal 双模式、只读探索、结构化规划、逐步执行
之前的 Agent 拿到任务就直接动手改文件，改错了只能撤回。v0.5 引入了 Plan/Normal
双模式，把工作分成两步：先只读探索、生成计划，确认后再执行。
用户按 Shift+Tab 或输入 /plan 切换到 Plan 模式：
Plan 模式下 Agent 只能用只读工具（read_file, grep_search, tree...）
→ 探索代码库，理解结构
→ 生成结构化计划（Goal + 编号 Steps）
→ 用户审阅：Accept / Modify / Cancel
→ 确认后切回 Normal 模式，逐步执行
工具分类 是安全的基础。所有工具在注册表中被标记为 read_only 或 write。Plan 模式下 LLM 根本收不到写工具的定义——API层面就不传。怕模型"幻觉"出写工具调用？执行层还有一道硬防护拦截。双重保障，Plan 模式下绝不会误改文件。
计划提示词 经过专门优化，强制要求每个步骤信息完整：必须包含具体文件路径、行号、精确变更内容，禁止出现"确认"、"询问用户"、"待定"等措辞。这意味着计划一旦生成，执行阶段无需再问用户任何问题，直接按步骤跑就行。如果用户需求有歧义，Agent 会基于代码上下文做出合理推断并在计划中标注假设前提，而不是在执行时停下来问。执行阶段 用 Rich Live 实现 8fps 实时进度条，每个步骤的状态（Pending → In Progress → Done/Failed/Skipped）带 Shimmer 光扫描动画实时更新。某步失败时用户可以选择跳过继续或停止剩余步骤。
这套设计的核心思想是 规划与执行分离：
- Plan 模式 = 只读沙箱，Agent 可以放心探索，不会产生任何副作用
- 用户审阅 = 人工把关，避免 Agent 走偏
- 逐步执行 = 每步结果可追踪，失败可控
本质上就是给 Agent 加了一道"确认"机制——不是弹窗确认，而是生成一份完整的执行方案让用户审核。代价是多一轮交互，收益是避免 Agent盲目操作导致不可逆的变更。
三、快速体验
本项目内置LLM仅支持了deepseek，一方面其价格较低，其次在不需要兼容大量模型厂商输出模式的情况下，代码量可以进行极大的精简，可以更专注于逻辑实现，而非大量的容错机制(可能会在后续版本补充)。
git clone https://github.com/frecol/Agent-Base-Zero.git cd Agent-Base-Zero uv sync echo "DEEPSEEK_API_KEY=你的Key" > .env uv run genesis推荐使用 uv 进行环境管理，如果没有的话也可以安装依赖后直接执行 main.py 文件。
python -m main。
觉得有用的话可以给我的 github 项目点个 Star ⭐，这是对我最好的鼓励，谢谢大家。
