16b · 框架这层皮

⏱ 54 分钟 ｜ ⭐ 不是教你用框架，是给你一张对回机制的地图

🎯 一句话

框架不是新知识，是你前面十几章学过的机制被打了个包。 这一章不教 API（写了半年就过期），只做一件事：把你上班第一周就会撞见的那些名字，一个一个对回本教程讲过的哪一节机制。

🧭 一、先把立场说清楚

第 00 章的陷阱表写着：「先学完 LangChain/框架再说——框架把机制藏起来了，出问题你不知道在哪」。第 18 章更狠，让你从裸 HTTP 请求开始把框架造出来，目标是那句「啊，原来 LangChain 就这？」。

这一章不推翻它，它是这个立场的下半句：你终究会撞上这些框架，手里得有张对回机制的地图——因为定位问题的前提，就是知道这层封装的是哪个机制。也因为框架会过期而原理不会，这章只写映射和坑，一行 API 都不写。

⭐ 框架是词汇表，机制是语法。 只背词汇表的人写不出句子；懂语法的人翻一下词汇表就能读懂任何一段。

🗺️ 二、对照表：每个名字对回哪一节

先记这张表，其余都是注脚。

每行都要问第二个问题：它没替你做什么。

① LangGraph ≈ 第 12 章的状态机与恢复

第 12 章说 Harness 由四样组成：循环、工具、上下文管理、护栏。LangGraph 主攻第一样里最难的半截：状态怎么外置、断了怎么接着跑——正对上五头怪里的「状态丢失」和第 13 章的「状态错误会复利，要从出错点恢复而不是从头重跑」。

没替你做的：护栏（max_steps / 超时 / 预算）还得你定；第 12 章的过早宣告完成，没有框架能救。

② LangChain ≈ 第 7 章工具 + 第 4 章上下文 + 第 3 章模板

它不是「一个 Agent 框架」，是一堆胶水的集合：工具装饰器和自动生成 schema = 第 7 章（也就是第 18 章 T1 的 @tool）；消息拼装、历史管理、摘要 = 第 4 章的压缩与外置笔记；提示词模板、变量填充、输出解析 = 第 3 章的骨架与预填响应。

没替你做的：第 7 章说「工具描述就是提示词」，仅仅精化描述就曾拿下 SWE-bench SOTA——这件投产比最高的事，它一个字都不替你写。

③ LlamaIndex ≈ 第 11 章 RAG 管线的封装

第 11 章把 RAG 拆成五环节，框架只包了前两个的一半：

⚠️ 最危险的错配：第 11 章的铁律是「答案不对，先查检索」。 框架把切分和检索藏进一行调用，于是所有人第一反应都去调提示词——本章的事故复盘死的就是这个。

④ CrewAI / AutoGen ≈ 第 13 章的协作模式

CrewAI 的「角色 + 任务 + 流程」≈ Agent 团队（持久化工作者）叠编排器；AutoGen 的「多 Agent 同场发言」≈ 消息总线——连局限也照单全收：执行路径难追踪、路由错误会静默失败。

没替你做的：第 13 章最贵的两条——等预算对照实验（把 15 倍 token 全给单 Agent 看差距还剩多少）和结构化委派（目标 + 输出格式 + 工具指引 + 边界）——它一条不管，反而让你更容易跳过第一条：「拉三个 Agent」只要三行。

⑤ Ragas / promptfoo / DeepEval ≈ 第 14 章的评测

第 14 章八步里它只管评分器实现 + 跑批出表，最贵的三步一步不管：第 2 步无歧义任务 + 参考解、第 3 步正反平衡（只测正例会学成「什么都做」）、第 6 步读转录（「最容易跳过也最有价值」的一步）。

💀 第 14 章讲过 pass@k 和 pass^k 讲的是相反的故事（单次 75% 时 pass@3 = 98.4%，pass^3 = 42.2%）。评测框架的默认报表大多只给一个平均分，面向客户的 Agent 必须看 pass^k，这得你自己配。

⑥ Dify / Coze ≈ 第 6 章工作流的可视化版

第 6 章的判断技巧是「我能提前画出这个任务的流程图吗」。可视化平台妙就妙在它逼你把图画出来——所以天然只覆盖能画上画布的前三种（提示词链、路由、并行化）。后两种画不出来：编排器-工作者的子任务不可预先确定。

⭐ 反过来用这个信号：当需求在画布上画不出来时，第 6 章那道判断题已经替你答了——你要的不是工作流，是 Agent。

⑦ Agent SDK ≈ 第 1 章循环 + 第 12 章 Harness

第 1 章末尾已经写过：真实开发会用官方 tool use API 或 Agent SDK，「循环都帮你写好了」。你手写的那 60 行——发历史、判断是工具调用还是最终答案、执行、回填、max_steps 兜底——就是它的 run()。

没替你做的：第 12 章的核心命题依然生效——每个组件都编码了一个会过时的假设。SDK 的默认 harness 也是一堆假设，也要定期做「体检五问」。

🧰 三、框架到底替你做了什么（六类，附行数量级）

行数是量级感，基准来自第 1 章那个 60 行的完整 Agent 和第 18 章约 90 行的 MiniAgent。

🔑 ①–③ 你在第 18 章已经亲手写过，加起来不过几百行——框架在这三类省下的时间，抵不过它的学习成本。 真正值得白嫖的是 ④⑤⑥：枯燥、没创造性、写错了还很难发现。

📋 四、该不该上框架：一个判断清单

每项 0–2 分，总分 ≥ 6 才值得上框架。

   ☐ 团队规模         0=1-2人  1=3-5人  2=6人以上或跨团队
   ☐ 要不要换供应商    0=锁死一家 1=可能换 2=已在做A/B或多供应商灰度
   ☐ 调试频率         0=每天改循环内部 1=偶尔 2=循环不动只改提示词和工具
   ☐ 人工介入/断点续跑  0=不需要 1=偶尔要 2=核心需求（审批、长任务恢复）
   ☐ 上线时间压力      0=有时间打磨 1=一两个月 2=两周内要上

四条「手搓更快」的判据（命中任意两条，别上框架）：

⚠️ 一个高频误判：「团队新人多，用框架好上手」。恰恰相反—— 抽象泄漏会让新人同时要懂两层（坑①）。新人多，更该给他们一个几百行、读得完的手搓循环。

🛑 读到这里可以停 —— 前半章讲完了。 后半章还有：框架的六个共同坑（全章最值钱的一节） · 一个事故复盘 · 上线前的四个动作 · 务实的结论 回来的时候不用重读，直接从下一节接着看就行。

⚠️ 五、框架的六个共同坑（全章最值钱的一节）

坑① 抽象泄漏

框架承诺「你不用管下面」，兑现的却是「顺利的时候你不用管下面」。一出问题，你要同时懂框架和底层——比只懂底层更难。

🔑 自检：你能说出「框架的这一行，对应第 X 章的哪个机制」吗？ 说不出来 = 你现在依赖的是运气，不是理解。

坑② 调试链路变长

坑③ 版本变动快

教程和示例的过期速度远快于原理。更麻烦的是：语义化版本号管的是 API 兼容，不管行为兼容——补丁号变了、签名没变，但默认值变了、重试策略变了、截断行为变了，于是CI 全绿，线上悄悄退化。

⚠️ 三条最低纪律：① 锁死版本，lockfile 进仓库，不做 -U 式例行升级； ② 升级前读 changelog 里所有带 default / behavior 字样的条目； ③ 升级和上线分成两次发布，中间跑一遍评测（第 14 章）。

坑④ 供应商锁定

框架的承诺是「换模型只要改一个字符串」，真实情况是这层抽象保不住你：它确实抹平了工具调用的格式和字段名，但提示词该怎么写（第 3 章）、缓存前缀布局（第 4 章要求逐字节相同，第 12 章明说「不要中途换模型」）、哪些 harness 组件已经多余（第 12 章体检五问）——一个都不管。

抽象层只抹平了「怎么调」，抹不平「怎么调得好」，而后者是换模型时 90% 的工作量。

坑⑤ 默认值是坑

默认值是框架作者为「一般情况」选的，而你的场景不是一般情况。 下面每一个都直接决定质量：

   切分：chunk_size / overlap / 切分策略     → 第 11 章：切分是最被低估的环节
   检索：top_k / 混合检索开没开 / 有没有重排  → 第 11 章：重排是性价比最高的一步
   生成：temperature / max_tokens           → 太高会飘，太低会僵
   循环：max_steps / 超时 / 重试次数与退避    → 第 1、12 章的护栏
   上下文：压缩触发阈值 / 摘要提示词          → 第 4 章：笼统的摘要会丢关键事实

🔑 可以直接执行的纪律：上面这些参数一个都不许用默认值，全部显式写在你自己的配置里。 哪怕写的值和默认值一模一样——显式写出来，升级时 diff 才看得见。

坑⑥ 提示词被藏起来

你不知道框架实际发出去的提示词长什么样。 它可能加了自己的系统提示、重排了工具描述顺序、追加了格式要求，甚至在稳定前缀前插了个时间戳（第 4 章：缓存 100% 失效）。

通用办法：不读源码，直接拦截真实发出去的 HTTP 请求。 和框架无关、和版本无关、永不过期。Python 生态里几乎所有 LLM SDK 底层都走 httpx：

# 打印框架真正发出去的请求体 —— 对任何基于 httpx 的 SDK 都有效
import json
import httpx

_orig = httpx.Client.send

def _spy(self, request, **kwargs):
    raw = request.content.decode("utf-8", "replace")
    try:
        raw = json.dumps(json.loads(raw), ensure_ascii=False, indent=2)
    except json.JSONDecodeError:
        raw = raw[:4000]
    print(request.url, "\n", raw)
    return _orig(self, request, **kwargs)

httpx.Client.send = _spy      # ⚠️ 只在开发环境开，别带上生产

老一些的 SDK 走 requests，把同样的逻辑贴到 requests.adapters.HTTPAdapter.send 上，请求体在 request.body。

打印出来后按优先级盯五件事：system 段被框架加了什么（塞进来的模板常和你的指令打架）、稳定内容是不是真在最前面（第 4 章缓存铁律，动态内容混进前缀就全废）、工具描述是不是你写的那版（被改写等于换了提示词）、塞进去的检索块长什么样（半句话的块 = 切分参数错了）、实际的 temperature / max_tokens。

⭐ 把它做成随时能打开的开关，而不是一次性的调试动作。 再把框架版和第 18 章手搓版的请求体 diff 一下——那个 diff 就是「框架替你做了什么」最诚实的答案。

💀 六、一个事故复盘

下面是把常见形态归并后的典型复盘，数字是量级感。

背景与触发：内部文档问答 Agent，2.4 万篇文档，日均约 6000 次提问，稳跑三个月。周二例行依赖更新，检索框架从 0.11.3 升到 0.11.7——补丁版本号，CI 全绿，代码一行没改。这个版本悄悄改了默认切分器：chunk_size 从 1024 降到 512、overlap 从 200 降到 20，而团队从没显式配过这两个参数（坑⑤）。当晚重建索引，块数从 8.7 万涨到 19.6 万——没人看这个数。

症状：不报错、不抛异常、延迟正常。只是回答变短，「资料里没有相关内容」从 4% 涨到 17%，满意度按周从 82% 掉到 71%。没有告警，因为没有任何指标在盯检索。

代价：约 3 人周工程师时间 + 一次全库 embedding 重算的白花费。而修复只改了两行配置。

💀 四个坑同时发作：坑③ 补丁版本改了行为 → 坑⑤ 默认值本就不该信 → 坑⑥ 提示词被藏起来，让 D8 的发现推迟七天 → 坑① 抽象泄漏让所有人都在错误的层里找原因。

最该带走的一条：⭐ 没有评测就没有告警——索引重建后自动跑 Recall@K，跌 5 个点就阻断上线（第 14 章）。

🔑 如果第一天就打开了「打印真实请求」的开关，D8 的发现会在 D1 出现，9 天变 1 天。 掀开框架的通路，要在出事之前就修好。

🧷 七、掀开它：上线前的四个动作

   ① 锁版本 + lockfile 进仓库，升级走单独的发布窗口
   ② 影响质量的参数全部显式配置，一个默认值都不留
   ③ 第一天就把「打印真实请求」做成开关，而不是出事再现搭
   ④ 留一条 50–100 行的手搓兜底路径，评测集要能同时跑框架版和手搓版

第 ④ 条不是炫技，是逃生舱：框架挂了、供应商要临时切、或你要证明「这个 bug 是框架的不是模型的」——手上有一条不经过框架的路径，就永远有的可比。

🎓 八、务实的结论

不是「别用框架」。 六类表已经说明白：重试、可观测性、供应商适配这三类，自己写既枯燥又容易错，该白嫖就白嫖。

⭐ 先懂机制 → 再用框架当加速器 → 出问题时你要能掀开它。 顺序不能颠倒。先学框架的人，缺的不是知识，是把现象对回机制的能力。

第 18 章那个项目的价值就在这里：做完之后，你看框架源码的感受会从「框架很神秘」变成「框架就是我写的这几个机制 + 一堆适配器和边界处理」。这一章的对照表，就是那个顿悟的速查版。

🔗 这一章连到哪里

✅ 检查点

1. 这一章和第 00 章「先学完框架再说是陷阱」是什么关系？用「词汇表 / 语法」那个说法解释一遍。
2. LangGraph 对回第 12 章 Harness 四件套里的哪一件？它替你做的具体是哪两个机制？
3. Dify / Coze 覆盖了第 6 章五种工作流模式里的哪几种？画不出来的时候说明什么？
4. 框架替你做的六类里，哪三类最值得白嫖？为什么另外三类不值得？
5. 「手搓更快」的四条判据是什么？为什么「团队新人多所以用框架」是误判？
6. 六个共同坑分别是什么？事故复盘里同时发作的是哪四个？
7. 为什么「补丁版本号 + CI 全绿」不能保证安全？该有哪三条纪律？
8. 怎么把框架真正发出去的提示词打印出来？打印后优先盯哪几件事？
9. 事故复盘里 Recall@10 从多少掉到多少？如果第一天就打开请求打印开关，9 天会变成几天？
10. 上线前的四个动作是什么？为什么要留一条手搓的兜底路径？

🛑 可以停在这里

⚡ 走神救援

这一章不教框架 API，只给一张把框架对回机制的地图，延续第 00 章「别先学框架」的立场——框架是词汇表，机制是语法。对照表七行：LangGraph≈第12章 Harness 四件套里的循环（状态外置检查点 + 从出错点恢复）；LangChain≈第7章工具定义+第4章上下文拼装+第3章提示词模板（但「工具描述就是提示词」它一个字不替你写）；LlamaIndex≈第11章 RAG 五环节的封装（只包了切分和检索，重排和评估还得自己接）；CrewAI≈Agent团队+编排器、AutoGen≈消息总线（第13章的等预算对照实验和结构化委派它都不管）；Ragas/promptfoo/DeepEval≈第14章评测（只管评分器和跑批，任务集、正反平衡、读转录三步一步不管，默认报表也不给 pass^k）；Dify/Coze≈第6章工作流的可视化版（只覆盖链式/路由/并行三种；画不出来就说明你要的是 Agent）；Agent SDK≈第1章那60行循环+第12章 Harness。六类活及行数量级：循环60行、工具注册40–80行、上下文拼装50–150行（这三类第18章你写过，不值得白嫖）；重试150–300行、可观测性从80行到数千行、供应商抽象500行以上（这三类才值得白嫖）。该不该上：五项打分≥6；四条手搓判据——工具<10个且单供应商、要在循环内插逻辑超3处、没人读过框架源码、路径基本固定。「新人多所以用框架」是误判，抽象泄漏会让新人同时要懂两层。六个共同坑：①抽象泄漏（出问题要同时懂两层）②调试链路变长（18帧里17帧是框架代码）③版本变动快（语义化版本管 API 不管行为，CI 全绿也会悄悄退化）④供应商锁定（抽象层抹平「怎么调」，抹不平提示词怎么写和缓存前缀布局）⑤默认值是坑（chunk_size/top_k/temperature/max_steps/重试/压缩阈值——一个都不许用默认值，全部显式写死，升级时 diff 才看得见）⑥提示词被藏起来（对策：不读源码，猴补 httpx.Client.send 打印真实请求体，再和手搓版 diff）。事故复盘：补丁版本 0.11.3→0.11.7 悄悄把默认 chunk_size 从1024改成512、overlap 从200改成20，块数8.7万→19.6万，不报错只是回答变短、拒答率4%→17%、满意度82%→71%；排查9天（前3天错在调提示词——第11章铁律是答案不对先查检索，D4白换了 embedding，D6 才建评测发现 Recall@10 从88%掉到61%，D8 打印真实请求看到全是半句话的块，D9 锁版本+写死参数回到87%），代价约3人周而修复只改两行，四坑同时发作。结论不是别用框架，而是先懂机制→框架当加速器→出问题能掀开它，并留一条50–100行的手搓兜底路径当逃生舱。

下一节 👉 16c-接进真实产品.md