前面七篇咱们把 LangGraph 的概念、组件、机制都讲了一遍。但老哥一直说光看不练假把式。今天开始咱们用一个完整的真实项目把所有知识串起来 ——破损商品智能理赔助手。这个项目要干的事很接地气电商到货破损是高频售后场景人工客服要判断规则、查历史案例、评估风险、写解释说明又慢又容易出错。我们用 LangGraph 做一个智能体自动完成规则校验、风险评估、相似案例检索、方案生成关键节点支持人工审批最后直接输出能发给用户的客服话术。这篇是上篇咱先把骨架搭起来 —— 目录、状态、业务规则、子图。下篇再讲主图怎么串、怎么跑起来。一、先看项目长什么样整个项目叫damage_claim_flow目录是分层设计的老哥先给你画个地图damage_claim_flow/ ├── agent/ # 智能体核心逻辑层 │ ├── graphs/ # 子图与主图编排 │ │ ├── policy_graph.py # 规则校验子图 │ │ ├── risk_graph.py # 风险评估子图 │ │ ├── cases_graph.py # 相似案例检索子图 │ │ └── main_graph.py # 主业务图 │ ├── logic/ # 业务逻辑层确定性规则 │ │ ├── policy_rules.py │ │ ├── risk_rules.py │ │ └── cases_store.py │ ├── persistence.py # 持久化checkpointer │ ├── prompts.py # 提示词集中管理 │ ├── runner.py # 智能体调度器 │ └── state.py # 状态建模 ClaimState ├── app_streamlit.py # Streamlit 可视化前端 ├── config.py # 全局配置模型、阈值 ├── data/ │ └── cases_examples.json # 历史理赔案例数据 └── requirements.txt这个分层的核心思想就一句话确定性的业务规则和不确定的大模型调用分开子图和主图分开调度和业务分开。后面你会看到这个结构让项目可维护、可扩展。二、配置和基础数据config.py是全局配置中心管三件事DeepSeek 模型参数和 API Key、业务阈值高金额审批线、高风险判定线、统一的Settings数据类。阈值是后面主图判断 要不要人工审批 的依据所以单独拎出来集中管理别散落在代码里。data/cases_examples.json是历史理赔案例库每条案例包含订单品类、金额、破损描述、历史处理方式、案例总结。它是相似案例检索子图的 知识库现在用本地 JSON 是为了项目能独立跑未来可以换成向量数据库。三、状态建模ClaimState整个项目所有节点、子图之间传递数据全靠一个统一的状态 ——ClaimState用TypedDict定义覆盖全链路字段表格字段类别包含内容基础信息订单号、用户 ID、金额、品类、破损描述、历史理赔数据规则结果理赔资格eligible /ineligible 原因风险结果风险等级low /medium/high 原因案例结果相似历史案例摘要策略与审批推荐方案、是否需要审批、人工审批结果最终输出给用户的客服话术日志logs带 Reducer 自动累积这里有个新手容易忽略的细节logs字段绑了一个简单的 Reducer让每个节点都能往日志里追加信息最后在前端展示完整执行轨迹。这就是咱们第二篇讲过的 Reducer 的实战用法 —— 多个节点写同一个字段必须定义合并规则。四、业务逻辑层确定性的事别交给模型这是整个项目最重要的设计原则之一能写死规则判断的就别让大模型猜。logic/目录下三个模块全是确定性 Python 逻辑policy_rules.py理赔资格校验。判断商品品类是不是虚拟商品等不可理赔类型返回eligible / ineligible 原因。规则不通过就直接进拒绝分支后面的风险评估、案例检索、大模型生成全都不用跑省 token 又可控。risk_rules.py风险等级评估。综合理赔率、最近 30 天理赔次数、总订单量等多维度指标算出 low /medium/high并生成解释性理由。高风险会触发人工审批。cases_store.py相似案例检索。从 JSON 加载案例按 品类一致、金额接近 做轻量评分挑出最相关的几条格式化成可读摘要写回状态。这三个模块都返回结构化结果不是自然语言 —— 因为结构化结果后面要用来做分支判断、要写进状态、要给大模型当参考。五、封装成三个子图业务逻辑写好了接下来把它们分别封装成三个独立的 LangGraph 子图就是咱们第七篇讲的 Subgraphpolicy_graph.py用精简的PolicyState只保留规则相关字段单一节点调用evaluate_policy写完结果和日志就结束。risk_graph.py用独立的RiskState节点调用evaluate_risk返回风险等级、原因和日志。cases_graph.py节点加载案例、筛选相似案例、生成similar_cases_summary文本写回状态。每个子图都只关注自己那一类业务输入输出边界清晰用自己的精简 State不碰主图的其他字段。这就是子图的价值 —— 模块化、可复用、可单独测试。六、老哥的叮嘱上篇到这儿骨架就搭完了。给你三个记住的点确定性逻辑和模型逻辑分离规则判断用 Python 写死大模型只负责 生成策略 和 写话术 这种创造性工作。状态是整个项目的脊梁ClaimState设计清楚了节点和子图之间的数据交换就顺了logs加 Reducer 是可观测性的关键。子图边界要窄每个子图只干一件事用自己的精简 State别什么字段都往里塞。骨架搭好了下篇咱们就讲最精彩的部分 ——主图怎么把三个子图并行跑起来、怎么在高金额时触发人工审批、怎么用 Streamlit 做前端、怎么测试五个真实场景。到时候你会看到前面学的所有知识点并行、Reducer、interrupt、checkpointer、流式输出全在这个项目里用上了。