合并来自 feat/ppt-agent-build 的合并请求 #2
欢迎来到 AI Agent 开发教程！本教程将带你从零开始，一步步构建一个最小可运行的命令行 AI 智能体（Agent），帮助你从代码层面理解AI Agent的逻辑。
你将不仅仅是调用 API，而是深入理解 Agent 的核心架构：大脑（LLM）、记忆（Context）、手脚（Tools）和技能（Skills）。
这是一个可运行的代码库，教程中的每个阶段都对应 Git 历史中的关键 Commit。你可以通过 git checkout 切换到对应状态，亲自修改代码并观察效果。
最终你将获得：
- 一个能够执行 Shell 命令的 AI Agent
- 支持多模型切换（Gemini、DeepSeek、智谱、腾讯混元）
- 完整的工具系统（文件读写、命令执行等）
- MCP 协议集成能力
- Sub-Agent 协作模式
- 可扩展的 Skill 系统
# 1. 克隆项目
git clone <repository-url>
cd try_agent
# 2. 安装依赖
npm install
# 3. 配置环境变量（至少配置一个模型的 API Key）
cp .env.example .env # 或手动创建 .env，填入至少一个 API Key
# 例如: echo "GEMINI_API_KEY=your_api_key_here" > .env
# 4. 运行
npm start
详细配置请参考 环境配置 (Setup)。
- Node.js: v18 或更高版本
- Git: 用于版本控制
- API Key: 至少一个模型供应商的 API Key（Gemini / DeepSeek / 智谱 / 腾讯混元）
建议按以下顺序阅读和实践：
- 环境配置 (Setup) - 安装依赖，获取 API Key，跑通 Hello World。
- 第 0 章：核心概念 (Concepts) - 什么是 LLM、Context、Agent、MCP？这里有最通俗易懂的解释。
- 第 1 阶段：让 AI 开口说话 (Hello AI) - 第一次调用 LLM API，体验不同的系统提示词 (Persona)。
- 第 1.5 阶段：给 AI 换个"大脑" (Multi-Model) - 支持多模型切换，体验不同模型的特点。
- 第 2 阶段：让 AI 记住上下文 (Memory) - 解决 LLM "健忘"的问题，实现多轮对话。
- 第 3 阶段：给 AI 一双手 (Tools) - 实现 Tool Calling，让 AI 能执行 Shell 命令。
- 第 4 阶段：Agent Loop (ReAct) - 构建 "思考-行动-观察" 循环，让 AI 自主完成多步任务。
- 第 4.5 阶段：工程化完善 (Refinement) - 注入项目上下文、优化文件工具、提升交互体验。
- 第 5 阶段：上下文管理 (Context Management) - 摘要压缩、工具输出截断，解决 Token 限制问题。
- 第 6 阶段：MCP 协议 (Model Context Protocol) - 学习 AI 时代的 "USB 标准"，连接万物。
- 第 7 阶段：Sub-Agent 模式 (子智能体) - 让多个 AI 专家分工协作，解决复杂任务。
- 第 8 阶段：Agent Skill (技能) - 封装自动化流程，让 Agent 掌握 "一键大招"。
- 第 9 阶段：TUI 交互界面 (Terminal UI) - 用 Ink/React 构建终端 UI，事件驱动渲染，斜杠命令补全。
- 第 10 阶段：流式输出与并行工具调用 (Streaming) - AsyncGenerator + SSE 实现逐字输出，Promise.all 并行执行工具调用。
本项目不仅仅是文档，更是一个可运行的代码库。
教程中的每个阶段都对应 Git 历史中的关键 Commit。你可以通过 git checkout 切换到对应状态，亲自修改代码并观察效果。
推荐学习路径：
- 先阅读 核心概念 建立认知基础
- 按顺序完成实战开发章节，每章都有对应的 Git Branch
- 动手修改代码，观察变化
- 尝试进阶架构，扩展 Agent 能力
try_agent/
├── docs/ # 文档
├── src/ # 源代码
│ ├── index.ts # 入口文件
│ ├── chat.ts # Agent 核心逻辑（ReAct 循环）
│ ├── chat-events.ts # 事件总线（TUI 解耦）
│ ├── mcp-client.ts # MCP 协议客户端
│ ├── project-context.ts # 项目上下文注入
│ ├── system-prompt.ts # 系统提示词管理
│ ├── tool-registry.ts # 工具注册中心
│ ├── context/ # 上下文管理
│ │ └── chat-compress-service.ts # 对话历史压缩服务
│ ├── model/ # 模型客户端
│ │ ├── client.ts # 模型注册与切换（多模型适配）
│ │ └── providers/ # 模型供应商实现
│ │ ├── types.ts # 供应商接口定义
│ │ ├── gemini.ts # Google Gemini
│ │ ├── deepseek.ts # DeepSeek
│ │ ├── zhipu.ts # 智谱 AI
│ │ ├── tencent.ts # 腾讯混元
│ │ └── openai-compatible.ts # OpenAI 兼容接口
│ ├── tools/ # 工具实现
│ │ ├── run-shell-command.ts # Shell 命令执行
│ │ ├── read-file.ts # 文件读取
│ │ ├── write-file.ts # 文件写入
│ │ ├── edit-file.ts # 文件编辑
│ │ ├── read-folder.ts # 目录读取
│ │ ├── sub-agent-tool.ts # Sub-Agent 调用工具
│ │ └── skill-tool.ts # Skill 调用工具
│ ├── subagents/ # 子智能体系统
│ │ ├── sub-agent-types.ts # Sub-Agent 类型定义
│ │ ├── sub-agent-registry.ts # Sub-Agent 注册中心
│ │ └── codebase-investigator.ts # 代码库调查员
│ ├── skills/ # 技能系统
│ │ ├── skill-types.ts # Skill 类型定义
│ │ ├── skill-registry.ts # Skill 注册中心
│ │ └── skill-loader.ts # Skill 加载器
│ ├── tui/ # TUI 交互界面
│ │ ├── index.tsx # TUI 入口
│ │ ├── types.ts # UI 类型定义
│ │ ├── slash-commands.ts # 斜杠命令注册表
│ │ ├── use-chat.ts # Chat 状态管理 hook
│ │ ├── use-command-list.ts # 命令补全 hook
│ │ └── components/ # Ink/React 组件
│ ├── prompts/ # 系统提示词模板
│ │ ├── gemini-cli.md # Gemini CLI 风格
│ │ ├── coding-mentor.md # 编程导师
│ │ ├── strict-engineer.md # 严格工程师
│ │ ├── personal-assistant.md # 个人助手
│ │ ├── sarcastic-friend.md # 毒舌朋友
│ │ └── anime-girl.md # 二次元少女
│ └── utils/ # 工具函数
│ └── frontmatter.ts # Frontmatter 解析
├── .agent/ # Agent 配置（技能和代理）
├── .env # 环境变量配置
├── .mcp.json # MCP 服务器配置
├── package.json # 项目依赖
└── tsconfig.json # TypeScript 配置
| 命令 | 说明 |
|---|---|
npm start | 启动 Agent |
Q: 启动后没有反应？
A: 检查 .env 文件是否正确配置了 API Key。
Q: 如何切换模型？
A: 运行时使用 /use <model-name> 命令（如 /use deepseek-v3.2），或在 .env 中设置 MODEL 环境变量。（在 第 9 部分：TUI 中，/use 将升级为交互式的 /model 命令）
Q: Token 超限怎么办？ A: 参考 上下文管理 章节。
本项目采用 MIT 许可证。
开始你的 AI Agent 之旅吧！ 🚀
Sponsor
About
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
