24-Workbench源码对照学习

核对日期：2026-05-18
官方资料：LangChain JS overview https://docs.langchain.com/oss/javascript/langchain/overview；Agents https://docs.langchain.com/oss/javascript/langchain/agents；Middleware https://docs.langchain.com/oss/javascript/langchain/middleware/overview；Runtime https://docs.langchain.com/oss/javascript/langchain/runtime。

官方概念

../LangChain/ 是当前工作区里更完整的 LangChain Agent Workbench 参考实现。它不是官方 LangChain SDK 本身，但它把官方概念落成了工程结构：agents、tools、runtime、middleware、memory、RAG、eval、API、MCP mock 和 team collaboration。

本章把官方模块映射到本地源码，解决“文档看懂了，但不知道实际项目里放在哪”的问题。

机制

源码地图

官方能力	本地文件	学习重点
Agent runtime	LangChain/src/agents/base-agent.ts	Agent 输入输出、工具调用、运行结果
Domain agents	kb-specialist.ts、learning-coach.ts、task-ops.ts、critic.ts	专家 Agent 如何拆职责
Tools	src/tools/tool.ts、gateway.ts、registry.ts	工具 schema、网关、注册表
Runtime	src/runtime/types.ts、factory.ts、checkpoint-port.ts	mock/live 模式、上下文、checkpoint
Middleware	src/middleware/*.ts	ACL、guardrails、HITL、tracing、pipeline
RAG	src/core/rag.ts	ACL 检索、评分、citation、conflict
Memory	src/core/memory-store.ts	长期记忆存取
Messages	src/core/messages.ts	message role 与上下文形状
Eval	src/core/eval.ts、scripts/run-eval.ts	eval case、汇总、失败处理
API	src/api/server.ts、streaming.ts	HTTP/streaming 接入
MCP	src/mcp/mock-server.ts	mock MCP server 和工具边界
Team	src/team/*.ts	多 Agent 协作、planner、supervisor、synthesizer

TypeScript 读码路径

路径 1：从一次请求看 Agent

1. 读 src/app.ts，看应用如何组装。
2. 读 src/runtime/factory.ts，看 runtime mode 如何选择。
3. 读 src/agents/base-agent.ts，看 Agent 执行入口。
4. 读 src/tools/registry.ts，看工具如何注册和暴露。
5. 读 src/middleware/pipeline.ts，看中间件如何串联。
6. 读 test/integration/*，看集成行为如何验收。

路径 2：从 RAG 问答看知识库

1. 读 fixtures/novacorp-kb.json。
2. 读 src/core/rag.ts。
3. 读 src/agents/kb-specialist.ts。
4. 读 eval cases。
5. 修改一条文档权限，跑测试。

路径 3：从多 Agent 看协作

1. 读 src/team/types.ts。
2. 读 src/team/planner.ts。
3. 读 src/team/supervisor.ts。
4. 读 src/team/synthesizer.ts。
5. 跑 serial/parallel integration tests。

官方组件对照

官方概念	Workbench 做法	差距/下一步
createAgent	自研 BaseAgent 风格执行器	接官方 SDK 时替换模型/工具绑定
Tools	自研 typed tool + gateway	可迁移到官方 tool API
Middleware	自研 pipeline	可对照官方 createMiddleware hook
Runtime context	runtime/types.ts	可补 contextSchema 风格校验
Checkpointer	checkpoint-port.ts	可接 LangGraph checkpointer
Store	memory-store.ts	可接 LangGraph store / Postgres
Streaming	api/streaming.ts	可对照官方 stream modes
MCP	mock server	可替换为真实 MCP client/server

Python 差异

如果用 Python 重写 Workbench，目录结构可以保持：agents、tools、runtime、middleware、core、eval、api、team。但实现会变成 Pydantic schema、create_agent、Python checkpointer/store、FastAPI 或类似框架。源码组织可复用，API 名称不应硬翻。

工程边界

• Workbench 是参考实现，不是官方 SDK 复制。
• 它的价值在于把官方概念工程化：测试、eval、runtime modes、team collaboration。
• 接官方 LangChain 时，不要丢掉 Workbench 里的 ACL、HITL、trace 和 eval 设计。

常见反模式

反模式	后果
看官方文档不看源码	不知道如何组织真实工程
看源码不对照官方概念	接 SDK 时概念错位
只改 Agent 不改 eval	行为回归无法发现
把 mock 当生产	没有 provider 差异和真实延迟

练习任务

1. 在 LangChain/src/core/rag.ts 中为 KnowledgeDocument 增加 tenantId，同步修测试。
2. 在 LangChain/src/middleware/tracing.ts 增加 requestId。
3. 对照官方 middleware 文档，为 LangChain/src/middleware/pipeline.ts 写 hook mapping 注释。
4. 把一次失败 eval 转成 docs/15-故障排查与反模式手册.md 的复盘模板。