A4 · LangChain 生态与 Framework Adapter

本模块产出：langchain-adapter、迁移测试报告 · 对应总课表：第 12 周 · 建议压缩为 2 到 3 天

学前自测

1. 什么是 Anti-Corruption Layer？为什么叫反腐？

领域驱动设计里的概念：在两个模型之间放一层翻译，防止外部系统的概念污染自己的领域模型。腐化指的是外部类型渗透进核心业务代码之后，你的模型逐渐变成外部系统的形状，最后想换掉它却发现改不动了。你从程序员基础版第 1 周立下的「业务包不 import 框架私有类型」这条规矩，就是在防这个。

2. LangChain 生态里，哪部分是真正值得接的，哪部分应该跳过？

值得接的是连接器生态：Document Loader、Retriever、各种第三方数据源集成，这些自己写一遍纯属浪费。应该跳过的是高层 Agent 封装，因为你已经有自己的 Harness 了，再套一层只会让事件和预算控制变复杂。这个取舍判断是这个模块的核心产出。

3. Runnable 的 invoke、batch、stream 三个方法，对你的 Adapter 意味着什么工作量？

意味着取消语义要在三条路径上分别验证。batch 尤其容易漏：取消一个 batch 时，已经发出的子请求怎么办、部分成功怎么表达。Adapter 的复杂度往往不在正常路径，而在这类边界。

4. 框架大版本升级把你的 Adapter 搞挂了，怎么才能提前发现？

Contract Test：用同一批输入输出契约测试 Adapter，锁版本 + CI 里跑升级预演。没有 contract test 的 Adapter，升级就是赌博。这也是评估「引入这个框架的长期成本」的量化依据。

学习目标

掌握 LangChain 最有价值的组件生态，并用反腐层接入而不污染平台核心类型。

课程内容

1. Chat Model、Message 与 Structured Output
2. RunnableSequence / Parallel / Branch
3. invoke、batch、stream 与 cancellation
4. Tool 与 Retriever 生态
5. Document Loader 和 Parser 适配边界
6. Middleware、Callback 与 Trace
7. Config、metadata 与 runtime context
8. Framework Adapter / Anti-Corruption Layer
9. LangChain 类型到统一契约的映射
10. Provider 与 Retriever 连接器的价值
11. 版本升级和 contract test
12. 何时直接使用原生 SDK
13. 何时避免高层 Agent 封装
14. 依赖退出与迁移策略

实施任务

实现 langchain-adapter：

• 把统一 ModelRequest、ToolContract、RetrieverContract 转换为 LangChain 类型
• 使用 Runnable 组合商品研究流程，但复用程序员基础版第 3 周 Tool Runtime
• 将 Callback / Stream Event 转换为统一 AgentEvent
• 运行 Native 与 LangChain 配对基准，并执行升级兼容测试

框架对照

动手挑战

真的把 LangChain 删掉一次，测量退出成本。

具体做法：在 Adapter 完成并通过全部测试之后，执行一次删除演练：

1. 从 package.json 里移除所有 LangChain 依赖，删掉 packages/adapter-langchain/
2. 跑 pnpm typecheck 和 pnpm test
3. 记录报错数量、涉及文件数、修复耗时

理想结果是：只有 Adapter 包自身和它的测试报错，业务包零报错，git revert 之前的耗时不超过十分钟。

如果业务包有报错，那些报错点就是你的抽象漏洞清单，必须修完再往下走。这个演练是 A5 的 framework exit drill 的预演，也是能写进对照报告的硬数据。

Agent OS 里程碑

完成 langchain-adapter 与迁移测试报告。

验收标准

• 同一 Agent Definition 可通过 Native 与 LangChain Adapter 运行
• 核心 packages 不导入 LangChain 类型
• 两种实现使用同一 Tool Runtime、Dataset 和 Eval Gate
• 对照报告量化代码量、延迟、事件完整性与升级成本

学后自测

1. 删除演练里业务包报了几个错？错在哪一类地方？

零最好。如果有，最常见的泄漏点是：某个业务函数的参数类型直接用了 LangChain 的 Message、Retriever 返回值没走自己的契约、以及测试文件里图省事直接构造了 LangChain 对象。测试文件也算泄漏，因为它同样阻碍退出。

2. LangChain 的 Retriever 生态里，你实际接了哪几个？自己写要多久？

要能报具体数字。这是判断「引入这个依赖值不值」的唯一诚实方式：省下的开发时间对比多出的升级维护成本和退出成本。凭感觉说生态好，在架构评审上是站不住的。

3. 你的 contract test 覆盖了 invoke、batch、stream 三条路径的取消吗？

三条都要覆盖，batch 最容易漏。检验方式：在 batch 执行到一半时取消，验证未发出的子请求不再发出、已发出的被中断、返回结果明确标记为部分完成而不是伪装成全部成功。

本模块作业

1. packages/adapter-langchain/ 扩展：模型、工具、检索、事件四方面的完整适配
2. Contract Test：三条路径的取消语义 + 版本锁 + 升级预演
3. docs/langchain-exit-drill.md：删除演练报告，含报错数量、涉及文件、修复耗时
4. Native 与 LangChain 配对基准数据

面试考点

这个模块对应面试里的依赖治理与架构边界考察，是 Senior 面试的高频区。

• 「你们怎么控制第三方框架的侵入？」：答反腐层，然后拿删除演练的数据说话。能报出「删掉框架业务包零报错、恢复耗时十分钟」这种数字的候选人极少。
• 「LangChain 值得用吗？」：这题有陷阱，两边站队都不对。答分层：连接器生态值得接，高层 Agent 封装不值得，因为我们已经有自己的 Harness。给边界不给结论。
• 「框架升级怎么办？」：答 contract test 加版本锁加升级预演。讲你的 batch 取消语义在升级后变过（或者你担心它变），说明你真在维护而不只是接过。
• 「你怎么评估引入一个依赖的成本？」：答三个量化维度：省下的开发时间、升级维护成本、退出成本。退出成本用删除演练测量。这是很成熟的架构回答。
• 反向陷阱：面试官可能说「你这个 Adapter 层是不是多余的抽象」。答用退出演练的数据反驳，同时承认如果确定十年不换框架，这层确实是浪费。承认前提比死守立场更显判断力。

复习与延伸

官方文档

• LangChain 文档
• LangChain JS Runnable 接口

本仓库对应源码

• packages/adapter-langchain/src/messages.ts：消息类型的反腐层映射
• packages/adapter-langchain/src/tool.ts：工具适配，执行仍走 @agent-os/tool-runtime
• packages/adapter-langchain/src/messages.test.ts 与 tool.test.ts：contract test 写法

下一步：A5 · Runtime 平台化与 framework exit drill