最近，各种开源 Agent 框架（OpenClaw、hermes 等）爆火。它们确实强大，但对想要学习原理的开发者来说，学起来太重了。
几百上千行的抽象层、回调链、多 Agent 编排……新人连“Agent 到底怎么工作的”都没搞清，就被淹没在代码海里了。
所以我做了一个极简的开源学习项目：Agent-Base-Zero。
🔗 GitHub: [github.com/frecol/Agen…]
它的核心理念是：拒绝历史包袱，每一次 Git Commit 就是一个完整的 Agent 版本，且只增加一个核心概念。
你可以直接 git checkout 到过去的任何一个版本，在没有冗余代码干扰的情况下，阅读最干净的代码。
目前项目已迭代到 v0.5。以下是这 5 个版本的核心实现精髓，带你看透 Agent 的进化过程：
🛠️ v0.1 最小可用版：看透 Agent 的底层循环本质
剥开各种高大上的概念，Agent 的本质其实不过是一个 while 循环 + if 判断。v0.1 仅用 300 行 Python 代码实现了一个极简大循环（接收输入 → 调 LLM → 判断并执行工具 → 结果送回 LLM 继续循环），外加一个即插即用的字典式工具注册表。没有复杂的链式抽象，让你一眼看穿 Agent 最底层的运行逻辑。
🧠 v0.2 思考与触网：实时渲染思维链与外部搜索
这一版的精髓在于过程可视化与连接真实世界。我们引入了流式输出（Streaming），通过解析底层的 StreamEvent，在终端实时渲染出类似 DeepSeek 的推理过程（Thinking），让你清晰看到大模型的每一步决策逻辑；同时配合免 Key 搜索与时间工具，让 Agent 从封闭的语言模型变成了能主动探索互联网的实体。
💾 v0.3 记忆系统：自主记忆与 Token 无损压缩
精髓：不粗暴截断，让 LLM 自己管理记忆边界与上下文。
- 自主长期记忆： 抛弃了传统“每轮固定提取关键词”的死板做法。我们特意实现了一个 memory_save 工具，把决定权交给大模型。什么是用户偏好？什么是重要环境配置？让 LLM 自己判断并调用工具持久化到本地文件，下次会话自动无缝注入。注意，是每次启动会话的时候加载一次，并不会在单次会话中实时加载更新的记忆，一方面避免破坏提示词缓存，其次，本次对话中新增的记忆本就处于对话记录中，并不会被遗忘。
- 智能上下文压缩： 对话长了必爆显存。v0.3 实现了一个巧妙的“掐头去尾”算法：当 Token 达到 95% 上限时，系统会自动将“首部 3 条（System设定）”和“尾部 20 条（最近对话）”保留，把中间庞大的冗长对话抽离，发给 LLM 做结构化摘要。这样既保住了核心语境，又把 Token 占用从几万瞬间降到几千。(参考hermes的做法)
🎭 v0.4 动态技能：无缝角色切换与前缀缓存优化
精髓：通过巧妙的系统设计，在实现无缝角色切换的同时，死死保住大模型的 Prefix Cache（前缀缓存），极大降低 API 成本。
- 痛点： 传统的做法是在 System Prompt 里塞满各种专家人设，一旦切换角色就得重写 System Prompt，导致大模型的前缀缓存瞬间失效，不仅慢，还极其烧钱。
- 解法（参考 Claude/Hermes）： 我们将 System Prompt 精简到了极致——只放技能的“一句话索引” （如：research -> 搜索专家）。
- 特制加载工具： 我们特意实现了一个 activate_skill 工具。当用户要求写代码时，LLM 发现索引匹配，会自主调用这个工具，去读取本地完整的 SKILL.md 指令文件。
- 精妙之处： 这些海量的专家指令是作为“工具返回结果（Tool Response）”追加到消息记录尾部的，系统提示词（System Prompt）自始至终一个字都没变！ 这样无论你怎么切换技能，大模型的 Prefix Cache 永远 100% 命中。
🛡️ v0.5 规划与执行：双模式物理隔离防“幻觉”翻车
精髓：规划与执行严格分离，双重锁死 Agent 的破坏力。
- Plan / Normal 双模式隔离： Agent 最怕产生幻觉后一顿瞎操作乱改代码。v0.5 引入 Plan 模式，在这个模式下，所有破坏性的“写操作”工具在** API 层面直接被没收**（不传给 LLM）。Agent 只能在一个纯粹的“只读沙箱”里探索文件树、用 grep 搜索，从而生成一份绝对安全的行动计划。
- 强制结构化计划： 通过 Prompt 级优化，强制 LLM 生成的计划必须精细到“文件路径、行号、精确修改内容”，绝不允许出现“待定”、“再问用户”等模棱两可的话。
- 防误判“双保险”： 就算模型在 Plan 模式下严重幻觉，非要调用 Write 工具，底层的执行器还有一道硬防护直接拦截。
- 优雅的执行层： 用户审阅计划无误后，切回 Normal 模式执行。这里引入了 8fps 的实时进度条和状态机（Pending → In Progress → Done/Failed），每一步操作清晰可见，失败可跳过。宁可多一轮人工确认，绝不让不可逆的错误发生。
与其在一团乱麻的成熟框架里死磕，不如从 300 行代码开始，跟着 Git Commit 日志自己“造一遍轮子”。 如果你对 Agent 底层逻辑和这些魔鬼细节感兴趣，欢迎 Clone 体验：git clone github.com/frecol/Agen… ， 然后 git checkout v0.1，我们从头开始！如果觉得有启发，也欢迎去 GitHub 赏个 ⭐！
