LangChain 06：端到端项目蓝图——把知识库客服做成可上线服务

#1、本篇任务：把前五课装成一个能维护的后端

这一篇不再介绍新概念，而是给出项目边界、目录、API 和迭代顺序。目标是把退款政策与订单助手做成可运行服务，而不是继续在 Notebook 中调用 agent.invoke()。

#2、先确定第一版做什么、不做什么

第一版支持：政策 RAG、当前用户订单查询、结构化回答、SSE 流式事件、退款草案与审批、会话恢复、trace 和最小评测。

第一版不做：多渠道、语音、自动退款、多 Agent、任意 MCP、自动学习所有用户信息。明确不做的事能让权限和测试范围保持可控。

#3、推荐架构

复制Web / App
  ↓ HTTPS + 登录态
API：鉴权、限流、输入 schema、request_id、SSE
  ↓ 注入 RequestContext
Agent Application
  ├─ triage / answer schema
  ├─ get_order → OrderService → DB
  ├─ search_policy → Retriever → Vector DB
  ├─ draft/submit refund → Approval + Domain Service
  └─ checkpointer / store
  ↓
LangSmith trace + 应用日志 + metrics

模型永远不直接连接数据库。工具调用领域服务；领域服务可以脱离 Agent 单独测试和复用。

#4、目录按责任拆，而不是按框架名堆文件

复制src/
  api/          # HTTP、认证、SSE、公共错误
  agent/        # Agent 装配、prompt、middleware、事件适配
  domain/       # OrderService、RefundService、业务不变量
  tools/        # 领域服务到 Agent tool 的薄适配
  retrieval/    # ingestion、retriever、引用验证
  persistence/  # thread、checkpoint、outbox、repository
  contracts/    # Pydantic/Zod/OpenAPI schema
tests/
  unit/         # 无模型的领域、路径、权限测试
  integration/  # DB、向量库、工具、checkpoint
  evals/        # Agent/RAG 固定案例

Python 和 TypeScript 版本采用相同边界；区别只是 Pydantic/FastAPI 与 Zod/Fastify/Nest 等实现选择。

#5、公共 API 合同

复制POST /conversations                 创建会话，返回 conversationId
POST /conversations/:id/messages    创建 run，立即返回 runId
GET  /runs/:id/events?after=42      SSE，支持从 sequence 恢复
POST /runs/:id/decisions            提交 approve/edit/reject
GET  /conversations/:id             恢复消息、当前 run 和待审批动作

请求 body 不接受 userId/tenantId/roles。这些值由认证中间件放入 RequestContext。公共事件只暴露产品状态，不暴露 LangGraph 节点对象、原始 prompt、密钥或工具堆栈。

#6、一次请求的完整时序

1. API 验证登录态和消息长度，生成 request_id/run_id。
2. 确认 conversation 属于当前用户，加载 thread_id。
3. Agent 根据问题调用政策或订单工具。
4. 后端把框架 stream 转为带 sequence 的公共事件并持久化必要状态。
5. 普通问答完成后保存结构化 answer 与引用。
6. 遇到退款草案时 run 进入 waiting_for_approval。
7. 决策 API 校验身份、action 和过期时间，恢复同一 thread。
8. 写工具通过 action ID 幂等执行，最终发 run.completed。

#7、迭代顺序与每步验收

不要先写完整 UI 再补安全，也不要一次接入十个工具。每个迭代都应该能部署、回滚和单独验证。

#8、前后端共享的结果合同

复制type Answer = {
  text: string;
  citations: { documentId: string; chunkId: string; title: string }[];
  confidence: "high" | "medium" | "low";
  needsHuman: boolean;
};

Python 用 Pydantic 定义同样字段，并通过 OpenAPI 或 schema 生成保持同步。不要让前端从模型 Markdown 猜引用、订单号或审批动作。

#9、上线前最小门禁

必须验证：跨租户隔离；提示注入无副作用；模型、工具和向量库超时有降级；checkpoint 可恢复；密钥和 PII 不进入 trace；P95、token 和工具调用有预算；prompt、模型、索引、代码都带版本；旧版本可回滚。

下一课只关注前端如何消费这些稳定事件。后端内部实现可以变化，前端合同不应跟着 LangChain API 一起变化。

官方阅读：Agents、Context Engineering。