# 从 50 行代码到生产级 Agent 框架——12 章完整教程
> 新年开局，我决定把 2025 年在企业级 AI 产品上踩过的坑，系统总结成一份教程。
## 为什么要认真对待 Agent 工程？
去年我们用 Claude Code 落地了三个企业级 AI 产品：智能知识库、地址解析引擎、智能匹配系统。
踩过的坑包括：
- 🔴 **流式处理问题**：模型回复快，但前端卡死？一个 AsyncGenerator 设计问题
- 🔴 **并发执行混乱**：5 个工具同时调用，怎么既要并行又要安全？
- 🔴 **权限控制缺失**：给用户 Agent 权限，结果他删了整个数据库
- 🔴 **上下文溢出**：100 轮对话后，token 暴增到 50 万？需要自动压缩
- 🔴 **工具管理低效**：100+ 个工具怎么有序注册、发现、优先级排序？
大多数 Agent 项目死在这些"不是算法问题"的工程问题上。
## 这个教程教什么？
我把 Agent 工程拆成 12 个核心问题，逐章递进：
### 🟢 第一部分：核心引擎（Ch1-4）
从最小实现开始，理解 Agent 的本质：
- **Ch01：最小可运行的 Agent**（50 行代码）
- Agent 就是 `while(true)` 循环
- 掌握消息-工具-循环的基本模式
- **Ch02：类型化的 Tool 接口**
- `Tool<Input, Output>` 泛型设计
- buildTool() 安全默认值模式
- **Ch03：Tool 注册与发现**
- ToolRegistry 三层设计（收集-过滤-排序）
- 缓存优化实战
- **Ch04：消息流与流式处理**
- AsyncGenerator 模式（不只是 Promise）
- 一个接口服务多个消费者（CLI、SDK、Web）
### 🟡 第二部分：执行与安全（Ch5-8）
处理工程级系统的复杂性：
- **Ch05：Tool 执行与并发控制**
- 并发分区算法（谁能并行，谁只能串行）
- StreamingToolExecutor 流式执行编排
- **Ch06：权限系统**
- PermissionEngine 三层门控
- 从"允许所有"到"最小权限原则"
- **Ch07：系统提示词与上下文工程**
- 三段式提示词构建（稳定层 + 系统动态层 + 用户动态层）
- 与模型缓存友好的提示词设计
- **Ch08：上下文窗口管理**
- 自动压缩：何时触发、怎么压
- 错误恢复：token 溢出时的降级方案
### 🔴 第三部分：扩展与生产化（Ch9-12）
从单 Agent 到企业系统：
- **Ch09：全局状态管理**
- 三层状态架构（进程级 / 会话级 / 轮次级）
- 不可变配置的实战价值
- **Ch10：Sub-Agent 系统**
- 主 Agent 自动委托子任务
- 权限继承与隔离
- **Ch11：MCP 集成**
- 工具市场不用自己建
- 一行代码接入 100+ 开源工具
- **Ch12：生产化与框架封装**
- AgentFramework 公共 API
- 权限、Hook、状态、压缩的统一协调
## 核心特色
✅ **代码可直接复用**
- 每章都是可运行的完整项目
- 12 章代码从 50 行进化到 2000 行框架
- MIT 许可证，可商用
✅ **支持所有 OpenAI 兼容的 LLM**
- OpenAI、DeepSeek、Qwen、Ollama，一套代码走天下
- 只需改环境变量，无需改代码
✅ **工程级细节**
- 不讲虚的概念，只讲"怎么做"和"为什么这样做"
- 每个设计决策都有背后的权衡
✅ **递进式学习**
- Ch1 是 50 行代码，Ch12 是完整框架
- 前后不脱节，每章都能单独运行
