🎓 教程设计

# ❌ 坏的 Quick Start（至少 15 分钟） ## 前置条件 - Node.js >= 18 - PostgreSQL >= 14 - Redis >= 7 - Docker & Docker Compose ## 步骤 1: 克隆仓库 git clone https://github.com/... ## 步骤 2: 安装依赖 cd project && npm install ## 步骤 3: 配置数据库 cp .env.example .env # 编辑 .env 文件，填入以下 12 个环境变量... ## 步骤 4: 初始化数据库 npm run db:migrate npm run db:seed # ... 还要 10 步 ... --- # ✅ 好的 Quick Start（5 分钟完成） npx create-my-app@latest # 🎉 打开 http://localhost:3000 → 看到你的第一个 Agent 运行！ # # 想自定义？编辑 app.config.ts → 保存 → 自动热重载 # # 下一步: [添加自己的工具](/docs/custom-tools) | [连接数据库](/docs/database)

# 渐进式教程的文件结构 /docs/ /getting-started/ quickstart.mdx ← L0: 5 分钟上手 installation.mdx ← 详细安装选项 /tutorials/ 01-first-agent.mdx ← L1: 创建你的第一个 Agent 02-custom-tools.mdx ← L1: 添加自定义工具 03-memory.mdx ← L1: 让 Agent 记住上下文 04-multi-agent.mdx ← L2: 多 Agent 协作 05-production.mdx ← L2: 生产环境部署 06-custom-llm.mdx ← L3: 自定义 LLM Provider /guides/ authentication.mdx ← L2: 认证最佳实践 error-handling.mdx ← L2: 错误处理策略 performance.mdx ← L3: 性能优化 architecture.mdx ← L3: 内部架构 /api/ reference.mdx ← L4: API 参考（自动生成） /examples/ cookbook.mdx ← 复制粘贴即可运行的代码片段

# 代码块 6 原则 1. **完整性**: 每个代码块都是完整可运行的 # ❌ 不完整 agent.run("do something") # agent 从哪来？ # ✅ 完整 from mylib import Agent agent = Agent(model="gpt-4") agent.run("do something") 2. **显式 import**: 所有依赖都列出 # ✅ import os from dotenv import load_dotenv load_dotenv() 3. **环境变量有默认值**: 不让用户猜 # ✅ API_KEY = os.getenv("API_KEY", "sk-your-key-here") 4. **输出示例**: 展示预期输出 # 运行结果: # > Agent started... # > Task: do something # > Result: ✅ Done! 5. **版本标注**: 代码基于哪个版本 6. **一键复制**: 文档框架提供复制按钮 # 所有主流文档框架都支持

# 学习路径设计示例 ## 🟢 新手路径（第 1 天） 目标: 能用产品完成基本任务 Quick Start (5min) → 基础概念 (15min) → 第一个项目 (30min) → 常见问题 FAQ (10min) ## 🟡 进阶路径（第 1 周） 目标: 能在项目中深度使用 自定义配置 (30min) → 集成第三方服务 (1h) → 生产环境部署 (1h) → 最佳实践 (30min) ## 🔴 专家路径（第 1 月） 目标: 能扩展和贡献 架构深入 (2h) → 插件开发 (2h) → 性能优化 (1h) → 贡献代码 (30min) ## 每个节点的格式 | 路径节点 | 预计时间 | 前置条件 | 产出物 | |----------|---------|---------|--------| | Quick Start | 5min | 无 | 第一个运行的 Demo | | 第一个项目 | 30min | Quick Start | 完整的小项目 | | 集成第三方 | 1h | 第一个项目 | 集成代码 + 测试 |