企业官网建设流程全解析

前面七篇咱们把 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定义，覆盖全链路字段：

表格

这里有个新手容易忽略的细节：logs字段绑了一个简单的 Reducer，让每个节点都能往日志里追加信息，最后在前端展示完整执行轨迹。这就是咱们第二篇讲过的 Reducer 的实战用法 —— 多个节点写同一个字段，必须定义合并规则。

四、业务逻辑层：确定性的事别交给模型

这是整个项目最重要的设计原则之一：能写死规则判断的，就别让大模型猜。logic/目录下三个模块全是确定性 Python 逻辑：

• policy_rules.py：理赔资格校验。判断商品品类是不是虚拟商品等不可理赔类型，返回eligible / ineligible+ 原因。规则不通过就直接进拒绝分支，后面的风险评估、案例检索、大模型生成全都不用跑，省 token 又可控。
• risk_rules.py：风险等级评估。综合理赔率、最近 30 天理赔次数、总订单量等多维度指标，算出 low /medium/high，并生成解释性理由。高风险会触发人工审批。
• cases_store.py：相似案例检索。从 JSON 加载案例，按 "品类一致、金额接近" 做轻量评分，挑出最相关的几条，格式化成可读摘要写回状态。

这三个模块都返回结构化结果，不是自然语言 —— 因为结构化结果后面要用来做分支判断、要写进状态、要给大模型当参考。

五、封装成三个子图

业务逻辑写好了，接下来把它们分别封装成三个独立的 LangGraph 子图（就是咱们第七篇讲的 Subgraph）：

• policy_graph.py：用精简的PolicyState（只保留规则相关字段），单一节点调用evaluate_policy，写完结果和日志就结束。
• risk_graph.py：用独立的RiskState，节点调用evaluate_risk，返回风险等级、原因和日志。
• cases_graph.py：节点加载案例、筛选相似案例、生成similar_cases_summary文本写回状态。

每个子图都只关注自己那一类业务，输入输出边界清晰，用自己的精简 State，不碰主图的其他字段。这就是子图的价值 —— 模块化、可复用、可单独测试。

六、老哥的叮嘱

上篇到这儿，骨架就搭完了。给你三个记住的点：

1. 确定性逻辑和模型逻辑分离：规则判断用 Python 写死，大模型只负责 "生成策略" 和 "写话术" 这种创造性工作。
2. 状态是整个项目的脊梁：ClaimState设计清楚了，节点和子图之间的数据交换就顺了；logs加 Reducer 是可观测性的关键。
3. 子图边界要窄：每个子图只干一件事，用自己的精简 State，别什么字段都往里塞。

骨架搭好了，下篇咱们就讲最精彩的部分 ——主图怎么把三个子图并行跑起来、怎么在高金额时触发人工审批、怎么用 Streamlit 做前端、怎么测试五个真实场景。到时候你会看到，前面学的所有知识点（并行、Reducer、interrupt、checkpointer、流式输出）全在这个项目里用上了。