第 20 周 · Day 1：全栈 Agent 模板结构分析——读源码是最快的架构课

对应手册任务：学习「full-stack-ai-agent-template 结构分析」，动手用模板的 Configurator 生成一个项目，通读 backend/app/ 和 frontend/ 的结构，当日产出一份「模板分析笔记」。本篇只解决一个问题：前 19 周零件你都亲手练过了，但一个生产级全栈 Agent 项目长什么样、别人怎么组织这些零件，你还没见过全景。今天用一份成熟开源模板把这块拼图补上。

今日目标

1. 说得清为什么阶段五从「读模板」开始，而不是从「写代码」开始
2. 掌握一套可复用的方法：怎么找到合适的模板、怎么用 Configurator 跑起来、怎么用「分析框架四问」拆解它
3. 独立完成一页纸「模板分析笔记」：结构图、数据流、亮点借鉴清单、可吐槽点各就各位

概念讲解：为什么从读模板开始

先盘点家底。19 周下来，你手里的零件清单已经不短：第 1 周的泛型工具函数、后来的后端路由、前端组件、Agent 循环、LLM 调用、工具注册、记忆、检索。每一件都写过，也都跑通过。

但它们是散的。路由的练习住在路由的目录里，Agent 循环的练习住在 Agent 的目录里，从来没在同一个项目里同时上过班。就像学做菜，切菜、颠勺、调味你都会了，可你没见过一桌菜怎么排：哪道先做、哪道并行、灶台怎么分配。

为什么这时候不直接开写，先读别人的项目？三个理由。

第一，自己瞎组装要走弯路，而这些弯路别人已经替你走完了。生产级项目里的每个目录、每层封装，几乎都是踩坑踩出来的：密钥放前端被扒过，所以改走后端代理；配置散在各文件改不动了，所以收拢集中管理。这些经验书上也有讲，但书是压缩饼干，源码是原味现场。

第二，这是企业的真实工作方式。入职一家公司，第一件事往往不是从零写新项目，而是接手老项目，或者「参考那个开源项目搭一个」。读陌生代码库的速度，直接决定你上手任务的速度。这个能力前 19 周没练过，本周补上。

第三，读源码是最快的架构课。架构书讲分层，讲得再好也是抽象名词；一个几千 star 的模板摆在眼前，分层是看得见的目录，数据流是追得着的调用链。通读一遍，胜过读十章架构文章。

所以阶段五这四周（第 20 到 23 周）的打开方式是：先读，再抄，后改。今天解决「读」。

核心知识

1. 怎么找：关键词加筛选

这类项目在 GitHub 上有一批，通用的叫法是 full-stack-ai-agent-template、ai agent boilerplate、llm app starter。搜索就用这些词的组合：

• full-stack ai agent template
• production ready ai agent
• llm agent boilerplate / ai saas starter

搜出来一大把，怎么挑？star 数只是第一道滤网，真正值得看的信号按优先级排：

1. 技术栈匹配度。它用的前后端框架、LLM SDK，最好和你练的一致或接近。一个 500 star 但技术栈全对的模板，好过一个 5000 star 但你要现学两门框架的。
2. 最近提交时间。半年没动的模板，依赖早烂掉了，跑都跑不起来。
3. README 质量。好的模板 README 会画架构图、给快速开始步骤、讲清 Configurator 用法。README 都写不利索的项目，代码大概率也乱。
4. issue 区。看看最近有没有人报「跑不起来」，有没有人管。

本篇教的是分析方法，不绑死某个仓库。按流程选定一个就别再犹豫，分析能力的增长来自分析的深度，不来自选哪个仓库。

2. 怎么跑：Configurator 交互式生成

成熟模板的 README 里通常带一个 Configurator：一个交互式问答，问你要什么前端框架、什么后端语言、接哪家 LLM、用什么数据库，答完生成一份定制脚手架，下载下来就是你的起点。标准流程五步：

1. 通读 README 的 Quick Start，把 Python/Node 版本、API key 要求这些前置条件看清楚再动手
2. 打开 Configurator，选项尽量和自己练过的技术栈对齐，为的是后面好对照，不是追新
3. 生成项目，按 README 给的命令装依赖
4. 把 .env.example 复制成 .env，填上 LLM 的 API key。密钥永远不进 git，模板留 example 文件就是提醒你这一点的
5. 起本地服务，打开发一个页面，随便发条消息，确认能跑

跑不起来的处理原则：先查 issue 区有没有同款问题，再查版本匹配。实在卡住就退一步，今天的任务是读结构，不是调环境，跑不起来不影响读代码。这句话不是安慰，是优先级判断。

3. 分析框架四问

项目跑起来后，别从第一个文件顺次往下读。带着四个问题读，一问一个视角。

一问：目录怎么分层？

这类模板的后端几乎都有类似 backend/app/ 的应用根目录，里面按职责分包。下面是一棵示意树，名字以你实际生成的项目为准，但分层的意图基本一致：

backend/
└── app/
    ├── api/        # 路由层：收请求、验参数、返响应
    ├── services/   # 业务层：编排数据与 Agent
    ├── agents/     # Agent 层：循环、提示词、工具注册
    ├── models/     # 数据模型与数据库表
    └── core/       # 配置、密钥、依赖注入等横切关注点

frontend/
└── src/
    ├── components/ # 组件
    ├── pages/      # 页面（或 app/ 路由目录）
    ├── api/        # 调后端接口的封装层
    └── stores/     # 前端状态

对照我们自己：前 19 周练分层是「按周练」，路由周练路由，Agent 周练 Agent，零件各住各家。模板给的全景是这些层在同一个屋檐下怎么划边界：api 只管 HTTP 进出不写业务，services 做编排，agents 专注循环和工具。边界靠目录物理隔开，而不是靠自觉。

二问：数据流怎么走？

挑一个最典型的功能，比如「发送一条聊天消息」，把它的完整链路追出来。追法很机械：在前端搜发请求的那行代码（fetch 或 axios），拿到 URL；去后端搜这个 URL 对应的路由；顺着 import 一路往下读。追完把链路压成一行：

前端组件 → 前端 api 封装 → HTTP → 后端 api 路由 → services 编排 → agents 循环 → LLM API → 原路返回 → 页面更新

注意一个关键点：LLM 调用发生在后端，前端从头到尾没碰过 API key。消息是用户在前端发的，但和 LLM 对话的活全在幕后。这就是 BFF（Backend For Frontend）思想的落点，明天起我们把它装进自己的项目。

三问：配置怎么管？

把模板里所有「可变的东西」找出来：LLM 的 base URL 和模型名、数据库连接串、前端指向的后端地址、各种功能开关，看它们都住在哪。成熟模板的答案通常是 .env.example 加一个集中读取配置的模块，业务代码只从这个模块拿配置，不直接碰环境变量。再想想你自己练项目时配置怎么放的，多半散在各个文件里。这一问的产出，直接决定后面改造自己项目的清单。

四问：它和我们的差异在哪？

前三问收集事实，第四问做判断。列一张表，示例格式如下，内容以你实际读到的为准：

维度	它的做法	我们前 19 周的练法	判断
LLM 密钥	只在后端，前端零接触	练习时偶尔图省事前端直连	抄它
配置	.env.example 加集中配置模块	散落各文件	抄它
分包	api/services/agents 物理隔离	零件各住各家	抄它
依赖注入	core 统一供给	手动实例化	看情况

「判断」一列是这张表的灵魂：每行都要给结论，抄、不抄、还是看情况，逼自己做决定，而不是抄完表格就散场。

4. 产出：一页纸「模板分析笔记」

四问答完，材料齐了，收进一页纸。固定四个区块：

# 模板分析笔记：<模板名>（附仓库链接、生成日期）

## 1. 结构图
目录树，每个包后面一句话标注职责

## 2. 数据流
一行写完那条链路，关键节点另起一行标注

## 3. 亮点借鉴清单
- 亮点 A：它怎么做的一句话 → 我们什么时候抄的一句话
- 3~5 条，每条都这么两句话，缺一句就不算数

## 4. 可吐槽点
2~3 条：哪里过度设计、哪里命名看不懂、哪里文档和代码对不上

为什么硬性限定一页？页数就是提炼的压力。写成三页的过程文档很容易，但这份笔记是给下周动手的自己看的，每一条都要能直接变成待办。

特别说说「可吐槽点」。能看出一个几千 star 的项目哪里过度设计、哪里写得啰嗦，说明你真读懂了，而不是跪着读完的。尊敬但平视，这是读开源项目的正确姿势。

动手任务：生成并拆解一个模板 一步一步

手册任务：用 Configurator 生成一个项目，读 backend/app/ 和 frontend/ 的结构，产出模板分析笔记。拆成 6 步，全程约 60 分钟。

第 1 步：选定模板（15 分钟）。 按核心知识第 1 节的流程，列 2~3 个候选，用四个信号筛掉，留下一个。把选它的理由写进笔记开头，一句话就够。

第 2 步：跑 Configurator（10 分钟）。 选项和自己技术栈对齐。生成后装依赖、配 .env、起服务，发一条消息确认能跑。跑不起来就按「先查 issue、再查版本、实在不行纯读代码」的顺序处理。

第 3 步：画结构图（10 分钟）。 只看目录名，先把 backend/app/ 和 frontend/ 的目录树抄下来，再逐个打开包，补一句话职责标注。遇到看不懂命名的包，标个问号，别急着深挖。

第 4 步：追一条数据流（15 分钟）。 用「发送一条聊天消息」当线索，按二问的机械追法，从 fetch 一路追到 LLM 调用，每经过一层就记下文件路径。追完把链路压成一行写进笔记。

第 5 步：填差异表（5 分钟）。 四列表，每行给判断。写不出判断的行，说明材料没读够，回第 3 步补。

第 6 步：收一页纸（5 分钟）。 按笔记模板的四个区块收拢，超出一页就删：删形容词，删背景介绍，只留「它怎么做」和「我们什么时候抄」。

别掉进「通读」陷阱

今天的目标不是把模板每个文件读完，是回答四问。带着问题读，答案到手就停。完整通读是以后维护它时的事，不是今天的事。

常见踩坑

坑 1：按 star 数选项目。 star 衡量的是知名度，不是适配度。技术栈不匹配的模板，读起来一半精力花在现学它的框架上，四问反而答不利索。先想清楚「我练过什么」，再去找「和它对齐的」。

坑 2：从第一个文件顺读到最后一个。 读代码不是读小说，没有情节推着你走，线性通读两小时后你会发现什么都没记住。永远从问题出发：问分层就只看目录，问数据流就只追一条链路。

坑 3：环境跑不起来就死磕。 一下午耗在依赖报错上，笔记一个字没写。记住优先级：读结构大于跑起来。issue 区找不到答案就果断转纯读代码，读代码不依赖 dev server。

坑 4：全盘照抄，不记吐槽。 模板是参考答案，不是圣旨。它为了通用会做你用不上的抽象，比如为多租户预留的复杂度，这些对你是负担不是资产。不吐槽的阅读是跪着阅读，笔记里「可吐槽点」空着，说明你还没读出自己的判断。

坑 5：笔记写成文档搬运。 把 README 翻译一遍、把目录树原样全贴，这不叫分析笔记。检验标准：合上笔记，你能白板画出结构图、说出那条数据流吗？能，才叫你的东西。

自测问题

先自己答，再展开对照。答不上来的，回对应小节看一遍。

1. 为什么说读源码是「最快的架构课」？它比读架构书快在哪？

参考答案

架构书把分层讲成抽象名词，得靠想象补全；源码把分层落成看得见的目录、追得着的调用链。书里的最佳实践是别人给的结论，源码里的目录结构是踩坑后固化的现场。认知负担更低，印象更深。

2. 挑选开源模板时，比 star 数更值得先看的信号是什么？

参考答案

技术栈匹配度，它决定你的精力是花在分析结构上还是现学框架上。其次是最近提交时间（依赖还活着吗）、README 质量（有没有架构图和快速开始）、issue 区活跃度（跑不起来有人管吗）。

3. 分析框架四问是哪四问？各自回答什么？

参考答案

一问目录怎么分层，回答项目骨架长什么样；二问数据流怎么走，回答一条请求从前端到 LLM 的完整链路；三问配置怎么管，回答可变的东西住哪、密钥怎么隔离；四问它和我们的差异在哪，用带判断列的表格把前三问的事实变成「抄不抄」的决定。

4. 追数据流时，为什么建议从 API 路由入口开始，而不是从 Agent 代码开始？

参考答案

路由入口是链路的天然起点，顺着 import 一路向下读，方向单一不会迷路。从 Agent 代码入手等于从链路中段插入，不知道上游怎么进来，也不知道下游返回给谁，容易读成孤立碎片。从起点追到终点，拿到的才是完整路径。

5. 一页纸笔记的四个区块是什么？为什么硬性限定一页？

参考答案

结构图、数据流、亮点借鉴清单、可吐槽点。限定一页是把「提炼」变成硬约束：这份笔记的读者是下周动手的自己，每条都要能直接转成待办。写长容易，写短才逼你想清楚，判断标准是合上笔记还能不能复述。

延伸阅读

• GitHub 仓库搜索：full-stack ai agent template，按第 1 节的四个信号现场筛一遍，比看任何「十大推荐」都管用
• The Twelve-Factor App：Config，配置放环境变量、不进代码库，第三问「配置怎么管」的理论源头
• 你选定的那个模板的 README，别只看 Quick Start，把架构图和目录说明部分也读了，对照自己的四问答案

前 19 周攒零件，这周开始装机器。今天的借鉴清单不是收藏品：明天起逐条落地，第一刀就是 BFF 代理和配置集中管理，之后再按需把多租户的思路裁剪着搬进来，把 第 1 周以来一路攒下的散装零件，装成一个正经平台。本周完整路线见 第 20 周总览。