Agent入门教程，读前须知
开发 Agent 入门教程
这是什么
这是一套基于当前项目整理出来的 Agent 开发入门教程。
它不是零散笔记，也不是只讲概念的“平台畅想”，而是一套按顺序展开的系列文章。
整套内容都围绕当前仓库这个真实项目来写，目标是带你从 0 到 1 做出一个：
- 本地可运行
- 浏览器可操作
- 支持多 Agent 协作
- 支持模型配置
- 支持规则文件
- 支持失败重试、中断、回收站、数据导出
的 Agent 产品原型。
项目原型就是当前仓库中的：
Python + FastAPI + SQLite- 面向“技术 / AI 自媒体文章写作”的多 Agent 系统
这套教程适合谁
适合下面几类人：
- 想做自己的第一个 Agent 产品
- 想理解多 Agent 产品应该怎么收敛 MVP
- 想从“只是会调模型 API”走到“做出一个可用系统”
- 想学习 Agent 产品的工程拆分，而不是只看 prompt
你会学到什么
这套教程重点不在“模型有多强”，而在这些工程问题：
- 如何选一个合适的 Agent MVP 场景
- 为什么先做产品，而不是先做平台
- 如何定义多个 Agent 的职责边界
- 如何让任务、上下文、日志、规则文件都能跑起来
- 如何给系统补上重试、中断、回收站和导出
- 如何把规则从代码中抽出来，做成可编辑的
rules.md
这套教程怎么组织
这 8 篇教程是按“产品从无到有”的顺序串起来的。
阅读节奏大致是：
- 先解决“为什么做这个”
- 再解决“做什么场景”
- 再解决“用什么技术栈”
- 然后进入“怎么把执行流跑起来”
- 再把它补成“可用产品”
- 最后再讨论“可配置”和“怎么演进”
每一章最后都有“下一章看什么”，可以顺着读下去。
教程目录
1. 为什么先做一个多 Agent 产品，而不是平台
讲清楚为什么一开始不要做“大而全 Agent 平台”，而应该先做一个有明确任务闭环的产品。
2. MVP 场景怎么选：为什么选技术 / AI 自媒体写作
讲清楚为什么文章写作是一个很适合多 Agent 的入门场景，以及场景收敛的方法。
3. 技术栈怎么定：为什么选 FastAPI + SQLite
讲清楚为什么要先用最小技术栈把产品跑起来，而不是一开始就上复杂架构。
4. 第一个可运行版本：任务、Agent、执行流
讲清楚如何搭出最初的任务执行流，让多个 Agent 真正协作起来。
5. 把它做成产品：后台、任务中心、模型配置
讲清楚为什么一个 Agent 系统必须做成后台工作台，而不是只做一个表单页。
6. 让系统可用：失败重试、中断、回收站、导出
讲清楚产品从“能跑”到“可用”之间，必须补上的容错与运维能力。
7. 让 Agent 真正可配置：规则文件、版本历史、diff
讲清楚如何把 Agent 规则从代码里抽出来，做成真正可配置、可回滚、可对比的系统。
8. 下一步怎么演进：上下文、质量闸门、部署与测试
讲清楚从当前 MVP 出发，未来最值得继续投入的方向是什么，包括上下文系统、质量控制、自动化测试和部署升级。
9. 输入上下文怎么设计：从 Prompt 到上下文系统
讲清楚为什么 Agent 的稳定性很多时候不是 Prompt 决定的，而是上下文系统决定的，以及当前项目里 task_context_snapshots / effective_feedback / Context Breakdown 的意义。
10. 多轮反馈与冲突怎么处理：从 feedback 到 issue board
讲清楚多轮 reject 为什么不能只累积文本，以及当前项目里的 issue_board / effective_feedback / conflict_resolution 是怎么协同工作的。
11. 质量闸门怎么做：生成、校验与自动回炉
讲清楚为什么生成和校验最好分开，以及当前项目里的 Dispatcher 一致性检查、Reviewer 质量闸门和自动回炉 Writer。
12. Agent 调试体系怎么搭：日志、快照、Context Breakdown
讲清楚一个真实 Agent 产品为什么不能只靠看 Prompt 调试，以及当前项目里的步骤日志、LLM Call、Context Breakdown 和快照体系。
13. 自动回炉与失败重试怎么设计：从“能重试”到“按语义恢复”
讲清楚自动回炉为什么不能只靠通用重试逻辑，以及当前项目里 auto_rewrite_pending、回炉阶段单独参数和恢复语义的设计。
14. Agent 项目怎么补自动化测试：先锁关键语义，再谈覆盖率
讲清楚 Agent 项目的测试应该从哪里开始补，以及当前项目里自动回炉闭环、冲突确认写回上下文这类测试为什么最值得优先保护。
如何阅读
如果你是第一次看，我推荐完整按顺序读完前 8 篇，再继续读第 9 到第 14 篇。
因为这套教程的设计就是一条完整主线：
- 为什么不先做平台
- 为什么选这个场景
- 为什么用这套技术栈
- 为什么执行流要先固定
- 为什么必须做成工作台
- 为什么要补重试、中断、冲突处理
- 为什么规则不能写死在代码里
- 后面最合理的演进顺序是什么
- 为什么上下文系统会成为新的核心
- 为什么多轮反馈必须进入问题管理模式
- 为什么系统要先做质量闸门，再交给用户
- 为什么 Agent 产品必须有完整调试体系
- 为什么自动回炉和失败恢复必须按语义设计
- 为什么 Agent 项目要先用测试锁关键链路
如果你更偏工程落地，也可以从第 3 章开始，再回头补前两章。
配套文档
如果你想看当前项目的其他文档，可以继续参考：
一句话总结
如果你想从 0 开始做一个 Agent 产品，最好的方式不是先做平台，而是先把一个具体场景做成真实可用的产品，然后再把里面沉淀出的能力抽成系统。