learn-agent · 从零写一个能活下来的 AI Agent

简体中文 · English

快速跳转　·　适合谁读　·　30 秒跑起来　·　全部目录　·　完整实现 Reina　·　给个 Star

一个 while 循环是 agent 的全部秘密——但只够它活 5 分钟。 剩下的部分——让它在真实任务里活过 5 小时——就是这一系列笔记记的东西。

想搞懂 Claude Code、Codex、opencode 这类 coding agent 内部到底怎么实现？这个仓库是我从 0 开发自己的 agent 时的踩坑笔记：一系列渐进式笔记，每篇配一份零依赖、单文件、直接能跑的代码，每篇解决一个真实翻车现场。

[!IMPORTANT] 和别的"手写 agent"教程不一样的地方：这里的机制不是照着 API 文档想象的，而是从一个真实在跑、完整开源的桌面 coding agent 产品——Reina——简化移植而来，每一条报错、每一个机制优化，都是线上踩过的坑。 学完这些笔记想看生产级完整源码，直接去 👉 Reina-Agent/Reina

这份笔记适合你吗

对着下面三条自查，中一条就值得读：

• 你照教程写过 agent demo，但一上真实任务就失控：空转烧钱、上下文爆窗、跑半小时忘了最初任务；
• 你每天在用 Claude Code，想知道压缩、缓存、子代理、权限审批这些"魔法"内部到底怎么做的；
• 你要在工作里落地 agent，想要一份被生产环境验证过的机制清单，而不是再看一遍 hello world。

Agent 看起来很简单，真去实现才发现里面大有可学。从"能跑"到"能用"，中间隔着一整层没人系统讲过的工程——它会空转烧钱、会吃撑爆窗、会跑半小时忘了最初任务、会因为不懂缓存贵 10 倍、会被卡死的子任务拖住。每一篇解决一个这样的真实问题。

30 秒跑起来

代码全部零依赖、单文件、Node 18+ 直接跑，任何 OpenAI 兼容的 key 都行（DeepSeek / Kimi / GLM / OpenRouter / 本地 Ollama）：

git clone https://github.com/7-e1even/learn-agent && cd learn-agent
AGENT_API_KEY=sk-xxx node s01_agent_loop/agent.mjs

手上一时没有 key？s12 的自测模式不需要任何 key 也能端到端跑通全部机制。

跑起来后，从 s01 顺着往后读，每篇边读 README 边跑代码即可。

目录

循环在第 1 篇写完，之后尽量不改——所有机制都围着它长。每篇的结构一致：踩过的坑 → 设计决定 → 可跑代码走读 → 真实产品对照 → 动手挑战。

完整实现：Reina —— 这些机制在真实产品里的样子

这些笔记不是凭空写的——它们全部来自我做 Reina 时的踩坑记录。Reina 是一个完整开源、能装能用的桌面 AI agent（Electron + React + TypeScript）；本仓库是我把它的核心机制剥出来、简化成单文件后留下的学习笔记。想看这些机制在生产代码里真正的样子，去主仓一一对照：

👉 喜欢这套笔记，别忘了给完整版 Reina-Agent/Reina 点个 ⭐——笔记帮你想清"为什么这么做"，主仓给你"直接拿去用"的生产级代码。

如果它帮到了你

这个仓库不卖课、不引流，只有笔记和代码。如果它帮你少踩了一个坑，顺手点个 ⭐——这是让更多人看到它的唯一方式。发现笔记里有事实错误或代码 bug，直接开 issue，当面对线。

License

本项目基于 MIT License 开源，© 2026 7-e1even。