第 11 周 · Day 7：周复盘方法论，谁在替你干活

手册任务：周复盘 + 整理。用 Excalidraw 画一张「裸 API → AI SDK → LangGraph」抽象层次图，标注每层帮你解决了什么问题，写 300 字周记，当日产出：抽象层次图 + 周记。本篇解决的问题只有一个：本周你用三种姿势写了同一件事，把它们摆进一张图，看清每一层替你挡掉了什么、又藏起了什么。

今日目标

不看教程，凭记忆画出「裸 API → AI SDK → LangGraph」三层抽象层次图，导出 PNG 存档
按四段模板写一篇 300 字周记
过一遍 10 题自检清单，答不上来的标记题号，回读对应 Day 的教程

概念讲解：复盘抽象层次，就是复盘「谁在替你干活」

先搬第 1 周 Day 7 立下的规矩（传送门）：识别不等于提取。你觉得「messages、流式、FC、useChat 我都过了一遍」，这个感觉不可信，它的依据只是「看懂了教程」。检验标准一年不变：合上资料，图画得出、题答得出，才算数。方法也不变：画图、写作、自测，三种输出逼三种提取。今天只是把这套流程套在第 11 周的主题上。

第 11 周的复盘有专属抓手：你其实把同一个功能写了三遍。Day 1、Day 2 用裸 API 手写了多轮对话、流式拼接、FC 五步循环；Day 4、Day 5 用 AI SDK 把同样的事重写一遍，代码短了一大截；下周的 LangGraph 还要在这之上再包一层编排。三遍写下来，最值钱的收获不是「会用了三个工具」，而是一个判断力：每往上叠一层抽象，代码变短，同时你离协议变远。什么时候该往上走求快，什么时候该往下退排查，前提都是能说清每层替你做了什么、没做什么。

这就是今天这张图要回答的问题。图画得出来，说明「哪层管哪事」在你脑中成了结构；画不出来，说明你记住的只是一堆 API 名字，报错一来照样抓瞎。

核心知识

1. 三层抽象对照总表

先上总表，画图前把每一行读顺：

层	一句话定位	这层替你解决什么	这层不解决什么
裸 API（openai SDK 直连）	一切的地基，全手写	什么都不替你做。换来完全透明：每个 chunk、每次 tool 回填、每轮 token 账单都看得见	所有工程问题全是你的：FC 循环自己 while、流式分片自己拼、结构化自己校验重试、SSE 自己转发、历史自己裁剪
AI SDK	单 Agent 快速上线的全栈胶水	四件重复劳动全包：FC 消息循环（streamText 自动跑到底）、流协议（后端发数据流，前端 useChat 拼增量）、UI 状态（messages、status、输入框）、供应商差异（provider 一层切换）	长流程的确定性编排、跨会话状态持久化、任意节点中断恢复、多 Agent 协作。流程一复杂，循环里套循环就开始缠线
LangGraph（下周主角）	多步多 Agent 的编排引擎	流程显式画成状态机：节点、边、共享 state；checkpointer 落库，断点可续跑；interrupt 原生支持人工介入；多 Agent 各占节点协作	不提升模型本身能力，也不替代 AI SDK 的流式渲染。一问一答的简单场景上它，杀鸡用牛刀

读这张表有两个方向：从下往上是逐步交出控制权换效率，从上往下是排查问题时逐层退回底层。给两个判断锚点：上线一个带工具的客服机器人，停在 AI SDK 层性价比最高；要做「查资料、写草稿、人工审、定稿」这种流水线，就得进 LangGraph 层。

再按本周天天碰的关注点拆一张细表，画图时它就是素材库：

关注点	裸 API	AI SDK	LangGraph
FC 循环	自己 while，盯 finish_reason	streamText 自动循环到终态	图的条件边路由
流式 tool_calls 分片	按 index 手动拼	useChat 替你拼	不再是你的问题
结构化输出	prompt 咒语加手动重试	generateObject 配 schema	state 里存校验后的结果
前端	SSE 自己写，状态自己管	useChat 一把抓	后端为主，前端仍配 AI SDK
换供应商	改 base_url 三件套	换 provider	换接入的 chat model

2. 抽象层次图：Excalidraw 要素清单

工具还是 excalidraw.com，手绘风，10 分钟草稿。一张合格的抽象层次图要有什么？照着这份清单画：

text

三层横条（自下而上，方框表示，逐层加宽表示封装面变大）：
  ① 底层：裸 API，标 openai SDK 直连
  ② 中层：AI SDK，标 streamText / generateObject / useChat / provider
  ③ 顶层：LangGraph，标 StateGraph / checkpointer / interrupt，旁注「下周主角」

每层右侧标注（3 处，写这层替你解决什么）：
  裸 API：什么都不替你做，全手写，换完全可控
  AI SDK：消息循环、流协议、UI 状态、供应商切换
  LangGraph：状态机编排、检查点、人工介入、多 Agent

层间箭头（2 条，向上，标注躲开了什么坑）：
  裸 API → AI SDK：躲开手写 SSE、分片拼接、循环重试
  AI SDK → LangGraph：躲开长流程状态管理、中断恢复

贯穿虚线（1 条，从底层纵贯顶层）：
  FC 五步循环：所有层的发动机

画的时候心里要有三个要素：层是分工，箭头是躲开的坑，虚线是发动机。少了右侧标注，这张图退化成技术名词堆叠；少了那条贯穿虚线，看图的人会以为 LangGraph 有别的魔法，其实三层跑的都是 Day 2 你手写过的那个环。

画完导出 PNG，命名 week11-abstraction.png，.excalidraw 源文件一起存。下周学 LangGraph 时回来改这张图，把顶层的「下周主角」换成实证细节。

3. 300 字周记模板

规则第 1 周讲过：周记记认知变化，不记日程。四段结构：最大收获、卡得最久、还含糊、下周前补。第 11 周示例，照这个密度写：

text

① 本周最大收获：模型的「记性」是客户端自己拼出来的，每轮把全部历史
塞回 messages，它才「记得」你。所谓 Agent 框架，管理的本质就是 FC 那
个五步循环的状态，没有别的魔法。
② 卡得最久：流式下的 tool_calls 分片。arguments 分三片到，流里
json.loads 必炸。最后按 index 归位、等流结束再解析才跑通，也才看懂
框架替我拼的是什么。
③ 还含糊：json_schema 严格模式的写法限制没记全；AI SDK 数据流协议里
各消息类型的分工，只会用没细看。
④ 下周前补：把 Day 2 的 FC 循环脱稿重写一遍；翻一眼 LangGraph 首页，
认识 StateGraph 长什么样。

300 字是刻意限制，逼你想清楚哪个收获才配写进「最大」。

4. 第 11 周知识自检清单

规则不变：每题先口头回答，说完整了再点开对照。

问题 1：messages 里 system、user、assistant 三种角色各是什么语义？（Day 1）

答案

system 定规矩：人设、语气、输出格式、禁令，放数组最前面，整场对话长效生效，不算对话内容。user 是用户这一方说的话。assistant 是模型此前说的话，第一轮没有，从第二轮起是你自己把上一轮的回复塞回数组的。模型只认数组内的内容：历史里有它就知道，没有就不知道。

问题 2：为什么说模型无状态？既然无状态，多轮对话怎么成立？（Day 1）

答案

LLM API 是无状态 HTTP 接口，每次调用互相独立，服务端不保存任何对话，这次说了什么下次一无所知。多轮对话靠客户端：每轮把 system 加全部历史加新问题整个 messages 数组重新发过去，模型现读现答。代价是 token 成本随轮数线性上涨，怎么裁剪历史是后面记忆周的事。

问题 3：temperature 控制什么？不同任务怎么选值？和 top_p 什么关系？（Day 1）

答案

控制采样随机性，范围 0 到 2，默认 1。模型每步给候选 token 算概率再抽样：温度低，高概率 token 接近必中，输出稳、保守、易重复；温度高，概率摊平，冷门候选也有机会，输出发散，幻觉跟着涨。选值：分类、信息抽取、写代码 0 到 0.3；日常对话 0.7 上下；创意头脑风暴可到 1.0 以上。官方建议和 top_p 二选一调，别同时动。

问题 4：拿到 finish_reason="tool_calls" 时，接下来你要做哪几步？（Day 2）

答案

模型这轮不说话，只要工具。你要：解析 tool_calls 数组，拿到 id、function.name、arguments（JSON 字符串）；json.loads(arguments) 后本地执行对应函数；往 messages 追加两条消息，assistant 消息（带 tool_calls）和 role:tool 消息（tool_call_id 加执行结果）；再次请求模型，拿到自然语言最终答案，finish_reason 回到 stop。

问题 5：流式模式下 tool_calls 分片怎么拼？哪一步做早了会炸？（Day 2）

答案

按 index 归位：每个分片带 index，指明属于第几个调用，先按 index 占坑；id 和 name 一般只在第一个分片出现，用 += 累积，兼容把它们拆开传的端点；arguments 是 JSON 字符串切片，一截截 += 拼完整。做早了会炸的一步：流没结束就 json.loads(arguments)。必须等 finish_reason="tool_calls" 落地、字符串拼完再解析。

问题 6：让模型输出结构化 JSON 的三条路线，按可靠性排序并说原因。（Day 3）

答案

从低到高：prompt 里叮嘱「只输出 JSON」；response_format 的 json_object 模式；response_format 的 json_schema 严格模式。第一条看模型心情，格式字段全没保证。第二条保证整体是合法 JSON，但字段名、类型、缺不缺仍不管。第三条把 schema 交给服务端约束解码，逐 token 保证输出符合 schema。工程上再叠一层 Pydantic 校验加失败重试，给最后一条上保险。

问题 7：json_object 和 json_schema 严格模式差在哪？严格模式要付什么代价？（Day 3）

答案

json_object 只承诺输出是合法 JSON，内容仍由模型自由发挥，字段可能缺、类型可能错。json_schema 严格模式把你的 schema 传给服务端做约束解码，字段、类型、结构都有保证。代价是 schema 要按它的规矩写：对象所有字段进 required、additionalProperties 关掉，部分复杂特性不支持，写 schema 更费劲。

问题 8：前端用了 useChat，你实际拿到什么？它替你做了哪些事？（Day 5）

答案

拿到一组响应式状态和方法：messages 消息列表（含流式增量）、input 加 handleSubmit 输入处理、status 状态流转、append/reload/stop 等控制方法，工具调用还有 onToolCall 和结果回填。它替你做的事：向后端 /api/chat 发请求、解析 AI SDK 数据流协议的分片、维护全部对话 UI 状态。组件里只剩渲染。

问题 9：都说 Qwen/DeepSeek/GLM 兼容 OpenAI 协议，换供应商时到底改什么？（Day 6）

答案

改三样：base_url、api_key、model 名。裸 SDK 里就是 OpenAI(base_url=..., api_key=...) 加换个模型名；AI SDK 里换成对应 provider，或用 openai-compatible 传 baseURL。messages 结构、流式协议、FC 协议、业务代码全不动。能这么换，是因为各家都实现了同一套 OpenAI 兼容协议。

问题 10：工具上的 needsApproval 是干什么的？什么场景该开？（Day 5）

答案

工具执行的审批开关。设为 true 后，模型选中这个工具不会自动执行，而是先挂起，把调用摆到用户面前等批准：点批准才跑，拒绝就不执行。给有副作用的操作用：发邮件、下单、删数据这类错了没法回滚的动作，加一道人审闸门，实现 human in the loop。

10 题全对也别飘

全对说明本周及格。图、周记、git 三件事做完，本周才算收口。哪题答不上，就回读对应 Day 的教程，回读也是复盘的一部分。

动手任务：完成本周复盘

按顺序五步，预计 60 到 90 分钟。

第一步：画抽象层次图（20 分钟）

关掉教程，打开 excalidraw.com，对照要素清单凭记忆画：三层横条、三处右侧标注、两条带坑位说明的向上箭头、一条贯穿虚线。卡住翻 Day 1 到 Day 6 的教程确认，合上继续画。

第二步：导出存档（5 分钟）

导出 PNG，命名 week11-abstraction.png，存笔记目录，源文件一起留。

第三步：写 300 字周记（20 分钟）

四段模板，对照示例密度写。「还含糊」那段别敷衍，它是下周的补课清单。

第四步：做自检清单（15 分钟）

10 题逐个口头回答，答不上的记下题号和对应 Day，回读该 Day 教程的对应小节。

第五步：git 提交整理（15 分钟）

本周产出零散：裸 API 脚本、结构化模块、AI SDK 前后端、多模型 CLI。别改历史，把未提交的按类型分开提交，打 tag 收口：

bash

git add raw-chat.py raw-fc-loop.py
git commit -m "feat(week11): 裸 API 多轮对话与 FC 循环"
git add apps/
git commit -m "feat(week11): AI SDK 版流式接口与对话页"
git tag week11-done

原则还是那句：一个提交只做一件事。

常见踩坑

抽象层次图画成功能清单。 每层罗列一堆 API 名字，箭头随手一画。这张图的灵魂是右侧标注和箭头上的坑位说明：每层解决什么、躲开什么。少了这些，画的是产品目录，不是认知。

把 LangGraph 画成「更高级的 AI SDK」。 两层性质不同：AI SDK 是替你省重复代码的库，LangGraph 是管流程状态的运行时。一个把循环包短，一个把流程画成图。顶层标注要体现这个差别。

周记写成本周目录。 「周一学了 messages，周二学了流式」，这是日程表不是认知。四段里「卡得最久」和「还含糊」最值钱，写不出多半是在回避。

自检先看答案。 点开 details 一看「哦这个我知道」，认得和说得出隔着一条鸿沟。先口头答再对照，顺序不能反。

第 11 周 · Day 7：周复盘方法论，谁在替你干活 ​

今日目标 ​

概念讲解：复盘抽象层次，就是复盘「谁在替你干活」 ​

核心知识 ​

1. 三层抽象对照总表 ​

2. 抽象层次图：Excalidraw 要素清单 ​

3. 300 字周记模板 ​

4. 第 11 周知识自检清单 ​

动手任务：完成本周复盘 ​

常见踩坑 ​

延伸阅读 ​