知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# 07 - 最小完整项目、测试与上线 > 导读:本文从"面试官说『别讲概念了,现场给我讲一个你自己写过的、能跑起来的 Agent 图,并说清它怎么上线』"这个最能验证真实能力的场景出发,把一份可以直接运行的工单处理图完整拆解、把 State 与七类节点的职责逐个讲透、把"如何把确定性节点替换为模型 / 检索 / 通知"的对照关系和上线前五个层级的检查清单逐项讲清,最后给出工程实践与踩坑。适合准备 AI 应用 / Agent 方向面试、以及想把练手代码推进到可上线状态的同学。 ## 一、先建立全局认知 ### Q:为什么这个"最小完整项目"要刻意不接 LLM、不依赖网络和 API Key? A:结论先行——**因为这样才能先验证"图本身"的能力:状态流转、条件分支、循环退出、持久化与流式输出;把模型这个最大不确定性因素推迟到最后一步引入,调试范围会小得多**。 这个取舍背后的方法论值得讲清楚。一个完整项目要同时验证很多件事: ```text 图的正确性:边连对了没有、分支覆盖了没有、循环能不能退出 状态的正确性:字段有没有被正确写入、合并规则对不对 流程的完整性:成功、失败、重试耗尽是否都能到达明确终态 持久化与流式:checkpoint 能否恢复、事件能否被消费 模型能力:输出质量、格式稳定性、成本 前提:把前四项用确定性代码先钉死,最后一项才可归因 ``` **如果一开始就把模型接进来,那么任何一个异常都可能是"图错了"或"模型不稳定",你需要花大量时间做二分排查。** 而当你用纯函数把流程跑通后,再接模型就变成了"替换一个节点的实现"——这体现的正是工程上的可调试性意识。 它带来的第二个好处是**示例的可复现性**:不需要 API Key、不需要网络,任何人克隆代码都能跑出同样的结果。这在教学、代码评审、CI(持续集成)里都非常有价值——**确定性让"能跑"这件事可以被断言,而不是"在我机器上能跑"。** ### Q:这个工单处理流程的拓扑长什么样? A:结论先行——**一条主线加三条出口:分类 → 查知识库 → 生成答复 → 校验,校验后按结果分流到"已解决""修复重试""处理失败",其中"修复"会回到校验形成有限循环**。  *图:validate 之后的三条条件边:resolved、improve、failed* ```text START → classify → lookup → draft → validate ├→ resolved → END ├→ improve ─┘ └→ failed → END ``` 把这个拓扑与前面讲过的几条原则对照,可以看到它把所有关键要素都放进了一个小项目里: | 要素 | 在这个项目里的体现 | |---|---| | 状态契约 | `TicketState` 是唯一的节点通信契约 | | 显式路由 | `route_after_validation` 返回有限枚举 | | 循环退出 | `MAX_ATTEMPTS` 限制重试,超限走 `failed` | | 流式输出 | `stream(..., stream_mode="updates")` 逐节点输出进度 | | 持久化 | `InMemorySaver` 通过 `thread_id` 保存执行快照 | | 可替换性 | 所有节点都是确定性函数,便于逐个替换为模型 / RAG / 工具 | **面试里这张表本身就是一段很好的回答框架**:它说明你不是"只会写 demo",而是知道每个设计点对应哪条工程原则。 ### Q:怎么运行它? A:结论先行——**安装依赖后,把代码保存为 `ticket_graph.py`,直接执行即可看到按节点输出的状态更新与最终答复**。 ```powershell pip install langgraph python ticket_graph.py ``` 预期会看到按节点输出的状态更新,以及最终答复。代码中复用了同一 `thread_id`,便于后续把 `InMemorySaver` 替换为生产 checkpointer。 需要提醒两点:**第一,运行前应确认 Python 版本符合当前 LangGraph 版本的要求**(本项目示例要求较新的 Python 版本,**具体要求需结合版本确认**);**第二,示例刻意不绑定某个 LangGraph 版本号**,因为该框架 API 会演进,尤其是 checkpoint 实现与流事件格式——升级前应查对应当前安装版本的官方文档。 ## 二、完整代码与逐段解读 ### Q:State 是怎么定义的?每个字段的定位是什么? A:结论先行——**`TicketState` 用 `total=False` 声明为"字段可选",并按"入口字段 / 中间事实 / 终态"三类组织,每个字段都标注了唯一写入方**。 ```python from typing import Literal, TypedDict from langgraph.checkpoint.memory import InMemorySaver from langgraph.graph import END, START, StateGraph # ---------- 常量 ---------- MAX_ATTEMPTS = 2 # 最大重试次数,防止无限循环 # ---------- State(节点间的数据契约)---------- class TicketState(TypedDict, total=False): """ total=False:所有字段都是可选的,调用 invoke/stream 时不需要一次性填满。 原则: - State 只包含可序列化的业务数据 - 不要把数据库连接、模型对象、锁等塞进 State - 每个字段只被特定节点写入,职责清晰 """ ticket_id: str # 工单唯一标识(入口传入) request: str # 用户原始请求(入口传入) category: Literal["billing", # 工单分类:账单 / 技术 / 其他 "technical", "other"] knowledge: str # 知识库匹配到的标准答复素材 answer: str # 最终生成的答复文本 validation_error: str | None # 校验发现的问题(None = 通过) attempts: int # 当前已重试次数(用于循环退出判定) status: Literal["resolved", "failed"] # 工单终态 ``` 逐点解读: 1. **`total=False` 让"逐步填充"成为可能**:调用时只需要给 `ticket_id` 和 `request` 两个入口字段,其余字段由节点在执行过程中补齐。这贴合真实执行过程。 2. **只放可序列化的业务数据**:注释明确写了"不要把数据库连接、模型对象、锁等塞进 State"——这是能顺利写 checkpoint 的前提。 3. **分类与终态用 `Literal` 收窄**:`category` 只能是三个取值,`status` 只能是两种终态。**类型收窄让"路由分支"和"字段取值"天然对齐**,也让替换为模型结构化输出时有明确的 Schema。 4. **`attempts` 是循环退出的唯一依据**:它的写入方是修复节点,读取方是路由函数。 5. **注释标注了每个字段的来源与用途**:例如"入口传入""用于循环退出判定"。**这些注释就是契约文档**,成本极低但价值很高。 ### Q:七个节点各自做什么?职责是怎么划分的? A:结论先行——**四个业务节点(分类、查库、起草、校验)+ 一个修复节点 + 两个终态节点;每个函数遵循"读 State → 做业务 → 返回增量更新"的统一形态**。 ```python # ---------- 节点:每个函数 = 读 State → 做业务 → 返回增量更新 ---------- def classify_ticket(state: TicketState) -> dict: """ 分类节点:根据用户请求中的关键词判断工单类别。 - 读取:state["request"] - 写入:state["category"], state["attempts"] - 生产可替换为 LLM 结构化输出(Function Calling) """ request = state["request"].lower() if any(word in request for word in ("账单", "付款", "发票", "扣费")): category: Literal["billing", "technical", "other"] = "billing" elif any(word in request for word in ("登录", "密码", "错误", "无法访问")): category = "technical" else: category = "other" return {"category": category, "attempts": state.get("attempts", 0)} def lookup_knowledge(state: TicketState) -> dict: """ 知识库查询节点:根据分类匹配对应的标准答复模板。 - 读取:state["category"] - 写入:state["knowledge"] - 生产可替换为 RAG(向量检索 + 内部知识库 API) """ knowledge_base = { "billing": "账单通常在扣费后 24 小时内生成;如有异常,请提供订单号。", "technical": "请先确认网络连接,再重置密码并重新登录。", "other": "我们已收到你的问题,客服会在一个工作日内回复。", } return {"knowledge": knowledge_base[state["category"]]} def draft_answer(state: TicketState) -> dict: """ 答复生成节点:将工单号和知识库内容拼装为最终答复。 - 读取:state["ticket_id"], state["knowledge"] - 写入:state["answer"], state["validation_error"](重置为 None) - 生产可替换为 ChatModel + prompt 模板 """ return { "answer": f"工单 {state['ticket_id']}:{state['knowledge']}", "validation_error": None, # 新生成的答复先假设没问题 } def validate_answer(state: TicketState) -> dict: """ 校验节点:检查答复是否符合基本规则(长度 + 是否包含工单号)。 - 读取:state["answer"], state["ticket_id"] - 写入:state["validation_error"] - 没有报错 = 返回 None,被条件边路由到 resolved """ answer = state.get("answer", "") if len(answer) < 20: return {"validation_error": "答复过短"} if state["ticket_id"] not in answer: return {"validation_error": "答复缺少工单号"} return {"validation_error": None} def improve_answer(state: TicketState) -> dict: """ 修复节点:在校验未通过时,对答复追加提示文本并递增重试计数。 - 读取:state["answer"], state["attempts"] - 写入:state["answer"], state["attempts"] - 写入不同字段 → 与其他节点并行写入不会冲突 """ return { "answer": state.get("answer", "") + " 如未解决,请回复工单号以便人工跟进。", "attempts": state.get("attempts", 0) + 1, } def route_after_validation(state: TicketState) -> Literal["resolved", "improve", "failed"]: """ 条件路由:根据 validation_error 和 attempts 决定下一步。 - 无错误 → "resolved"(成功结束) - 有错误 + 未超 MAX_ATTEMPTS → "improve"(修复后重试) - 有错误 + 已达 MAX_ATTEMPTS → "failed"(失败结束) """ if not state.get("validation_error"): return "resolved" if state.get("attempts", 0) >= MAX_ATTEMPTS: return "failed" return "improve" def mark_resolved(_: TicketState) -> dict: """ 成功终态节点:标记工单为已解决。 - 不读取 State(_ 忽略),只写入 status - 生产可扩展为:写工单系统、发送通知、记录审计日志 """ return {"status": "resolved"} def mark_failed(state: TicketState) -> dict: """ 失败终态节点:重试耗尽后,标记失败并给出兜底答复。 - 读取:state["validation_error"] - 写入:state["status"], state["answer"] - 生产可扩展为:转入人工队列、发送告警 """ error = state.get("validation_error", "unknown error") return {"status": "failed", "answer": f"处理失败:{error}"} ``` 这七段代码里有四个设计点特别值得在面试里展开: **第一,`classify_ticket` 顺手把 `attempts` 初始化了**。它返回 `"attempts": state.get("attempts", 0)`——**如果这个字段已经有值就保持不动,没有就初始化为 0**。这样后续节点不必再担心"字段不存在",同时也不会让分类节点误递增计数。这是一个很实用的技巧:**让"入口附近"的节点负责补齐默认值,而不是让每个读取方都写 `get(..., 0)`。** **第二,`draft_answer` 主动把 `validation_error` 重置为 `None`**。注释写得很清楚:"新生成的答复先假设没问题"。**这一步是防止"幽灵分支"的关键**——如果旧错误残留,路由就会基于上一轮的错误做判断。这条纪律在讲循环与容错时反复强调过。 **第三,路由函数的判断顺序是先"是否无错",再"是否超限",最后才是"修复"**。它的可读性很好:成功 → 预算耗尽 → 修复。而且因为"无错"优先,成功路径永远不会被预算拦截,语义是合理的。 **第四,两个终态节点都非常薄**:`mark_resolved` 只写一个 `status`,`mark_failed` 写 `status` 加一个兜底答复。**终态节点的职责就是"记录结果",所有复杂逻辑都应该在中间节点完成。** 这样终态语义清晰,也便于生产环境在这里挂上"写工单系统、发通知、转人工队列"等副作用。 ### Q:图是怎么构建的?`compile` 时注入了什么? A:结论先行——**注册七个节点、连上主线顺序边、把校验后的分支用条件边声明出来、用一条回边闭合重试循环、最后在 `compile` 时注入 `InMemorySaver`**。 ```python # ---------- 图构建:注册节点 + 边 + 条件分支 ---------- def build_graph(): """ 图的拓扑结构: START → classify → lookup → draft → validate ├─ resolved → END (校验通过) ├─ improve ─┘ (修复 + 重试,循环回到 validate) └─ failed → END (重试耗尽) """ builder = StateGraph(TicketState) # 注册所有节点 builder.add_node("classify", classify_ticket) builder.add_node("lookup", lookup_knowledge) builder.add_node("draft", draft_answer) builder.add_node("validate", validate_answer) builder.add_node("improve", improve_answer) builder.add_node("resolved", mark_resolved) builder.add_node("failed", mark_failed) # 主线顺序边 builder.add_edge(START, "classify") builder.add_edge("classify", "lookup") builder.add_edge("lookup", "draft") builder.add_edge("draft", "validate") # 条件分支:validate 之后根据校验结果分叉 builder.add_conditional_edges( "validate", route_after_validation, # 路由函数 {"resolved": "resolved", # 校验通过 → 成功结束 "improve": "improve", # 校验失败 + 未超限 → 修复 "failed": "failed"}, # 重试耗尽 → 失败结束 ) # improve 执行后回到 validate(形成重试循环) builder.add_edge("improve", "validate") # 两个终态节点 → END builder.add_edge("resolved", END) builder.add_edge("failed", END) # compile 时注入 InMemorySaver(Checkpointer) # 生产环境替换为 SqliteSaver 或 PostgresSaver return builder.compile(checkpointer=InMemorySaver()) ``` 解读三个结构层面的决策: 1. **主线用普通边,分叉用条件边**:`classify → lookup → draft → validate` 是固定顺序,用 `add_edge` 最清晰;`validate` 之后的三个走向由数据决定,用条件边表达。**不要为了"统一"把顺序边也写成条件边**,那只会增加噪音。 2. **回边闭合循环**:`builder.add_edge("improve", "validate")` 是唯一一条"往回走"的边。整个图的循环只有一个,出口由路由函数与 `MAX_ATTEMPTS` 共同保证。**能画得出来的循环,就是可审查的循环。** 3. **`build_graph()` 返回编译后的 `app`**:把"建图"封装在一个函数里,调用方只拿到可运行的 `app`,这与"建图期与运行期分离"的原则一致。 **版本提示**:`InMemorySaver` 的导入路径与命名在不同版本可能不同(旧版本有 `MemorySaver` 之名),**请与安装版本的 API 对齐**;生产环境应替换为数据库类或托管实现。 ### Q:运行入口为什么用 stream + get_state 两个动作? A:结论先行——**`stream` 用来观察"过程"(逐节点更新),`get_state` 用来取"结果"(从检查点读取最终快照);两者组合正好演示了"流式"与"持久化"两个能力**。 ```python # ---------- 运行入口 ---------- if __name__ == "__main__": app = build_graph() # config 中的 thread_id 是 checkpoint 的隔离键 # 同一个 thread_id 可以跨多次调用恢复上下文 config = {"configurable": {"thread_id": "ticket-demo-001"}} # 初始 State:只填入入口必需的字段,其余字段节点会逐步填充 initial_state: TicketState = { "ticket_id": "T-1001", "request": "我无法登录账户,应该怎么处理?", } # stream(stream_mode="updates"):逐节点输出增量更新 # 便于调试、前端展示进度条、日志记录 print("== 节点更新 ==") for update in app.stream(initial_state, config=config, stream_mode="updates"): print(update) # 每个 dict 是单个节点的返回 # get_state():无需重新运行,直接从 checkpoint 中读取历史快照 final_state = app.get_state(config).values print("\n== 最终结果 ==") print(final_state["status"]) # "resolved" 或 "failed" print(final_state["answer"]) # 最终答复文本 ``` 三个细节值得注意:**第一,初始 State 只填两个入口字段**,这正是 `total=False` 的价值兑现。**第二,`config` 里的 `thread_id` 是固定值 `ticket-demo-001`**,注释说明了它的用途——同一个键可以跨多次调用恢复上下文,也方便演示时重复运行。**第三,`get_state` 不需要重新执行图**,它直接从检查点读取快照,这正是"状态可查询"在长任务里的实用价值:用户刷新页面时,你不必重跑任务,直接读就好。 **版本提示**:读取状态的接口形态(返回值结构、是否需要取 `.values`)可能与版本相关,**细节需结合版本确认**。 ## 三、这段代码覆盖了什么、没覆盖什么 ### Q:这份实现完整覆盖了哪些能力? A:结论先行——**它覆盖了状态契约、显式路由、有限循环、流式进度与本地持久化五件事,但刻意没有覆盖模型、检索、外部副作用与生产级持久化**。  *图:五节点主流程,validate 决定终态或回到 improve* ```text START → classify → lookup → draft → validate ├→ resolved → END ├→ improve ─┘ └→ failed → END ``` - `TicketState` 是唯一的节点通信契约;字段都是可序列化业务数据。 - `route_after_validation` 返回有限枚举,且有 `MAX_ATTEMPTS` 保护循环。 - `stream(..., stream_mode="updates")` 让调用方看到节点级进度。 - `InMemorySaver` 通过 `thread_id` 保存执行快照;仅适用于本地演示。 - 所有节点都是确定性函数,方便先验证图,再替换为真实模型、RAG 和工具。 **"没覆盖什么"同样重要**:它没有真实的外部副作用(所以不存在幂等问题)、没有模型(所以不存在输出格式不稳定与成本问题)、没有多租户与权限(所以不存在隔离问题)、用的是内存持久化(所以不存在恢复演练与版本兼容问题)。**清楚地知道示例的边界,才不会把 demo 当成生产方案**——这一点在面试中尤其重要。 ## 四、如何替换为真实能力 ### Q:每个节点替换为生产能力时,必须配套哪些防线? A:结论先行——**替换本身很简单,难的是配套的防线:模型要有 Schema 校验与未知兜底、检索要有租户过滤与超时、生成要有内容安全与 token 预算、终态副作用要有幂等键与权限校验、持久化要有保留策略与迁移演练**。 | 当前节点 | 生产替换方式 | 必需防线 | |---|---|---| | `classify_ticket` | 模型结构化输出 `category` 枚举 | Schema 校验、未知类别 fallback | | `lookup_knowledge` | 向量检索 / 内部知识库 API | 租户过滤、超时、结果引用 | | `draft_answer` | ChatModel + prompt 模板 | 内容安全、token 预算、敏感信息过滤 | | `mark_resolved` | 写工单系统、发送通知 | 幂等键、权限校验、必要时 interrupt | | `InMemorySaver` | PostgreSQL 等生产 checkpointer | 数据保留、加密、迁移与恢复演练 | 逐行解释"为什么这些防线是必需的": - **`classify_ticket`**:模型可能输出一个不在枚举内的类别(如 `refund`)。必须有 Schema 校验把非法值拦下来,并归到 `other` 这个安全兜底,**绝不能把非法值直接透传给下游**(否则查库节点会 KeyError)。 - **`lookup_knowledge`**:检索最容易出的安全问题是跨租户串数据,所以必须在检索层强制租户过滤;同时要有超时(避免一个慢查询拖垮整个任务),以及结果引用(便于最终答复给出出处)。 - **`draft_answer`**:引入模型后就同时引入了内容安全、成本与数据泄漏三个风险,因此需要内容安全检查、token 预算上限,以及敏感信息过滤(尤其是输出侧)。 - **`mark_resolved`**:一旦它开始"真的干活"(写系统、发通知),就产生了副作用,因此必须有幂等键、权限校验,必要时加人工审批。 - **`InMemorySaver`**:换成生产实现后,数据保留、加密、迁移与恢复演练都必须补齐——否则状态会变成新的数据风险面。 ### Q:为什么外发通知必须带幂等键? A:结论先行——**因为恢复与重放会让节点被重复执行,如果不带幂等键,用户会收到重复通知,甚至重复扣款**。 例如,外发通知必须使用稳定幂等键,不能因为 checkpoint 恢复而重复发送: ```python def send_notification(state: TicketState) -> dict: idempotency_key = f"ticket-notify:{state['ticket_id']}" # notifier.send(state["answer"], idempotency_key=idempotency_key) return {"notification_key": idempotency_key} ``` 这段代码有三个可学习的点:**第一,幂等键由业务标识推导**(`ticket-notify:` + 工单号),因此"第一次执行"和"重放时再执行"算出来是同一个键,下游据此去重;**第二,通知内容走 `state["answer"]`**,而不是重新计算——保证重放时发出去的内容一致;**第三,把键写回 State**(`notification_key`),这样审计时能查证"这次通知用的是哪个键"。**"确定性的键 + 幂等的下游"是长任务系统里副作用安全的通用解法**,不限于通知。 ## 五、测试与上线检查清单 ### Q:上线前应该按哪几个层级验证? A:结论先行——**五个层级:节点单测、图路径测试、集成测试、评测、以及运维监控**。 | 层级 | 验证内容 | |---|---| | 节点单测 | 输入 State、输出更新、route、reducer 与错误码 | | 图路径测试 | 成功、重试耗尽、超时、取消和权限拒绝均能到达明确结束状态 | | 集成测试 | checkpointer、真实工具、幂等键和 interrupt 在隔离环境运行 | | 评测 | 固定数据集上的完成率、路由正确率、工具正确率与安全拒绝率 | | 运维 | trace/thread/run 关联、成本、延迟、失败率、审批积压和恢复率告警 | 逐层理解它们的"分工": **节点单测**是最便宜的一层,输入一个字典、断言一个字典,毫秒级完成,且不需要任何外部依赖。它覆盖的是"局部逻辑对不对",包括路由函数和 reducer。**图路径测试**是这一层的升级——它把整个图跑起来,但所有节点仍是确定性(或打桩)的,目的是确认"每一条路径都能到达明确终态",包括成功、重试耗尽、超时、取消、权限拒绝这些分支。**集成测试**才开始接触真实依赖:真实 checkpointer、真实工具、真实的幂等键与 `interrupt`,并且必须在隔离环境里跑,避免污染生产数据。 **评测**是 AI 应用特有的一层:它不看"代码有没有错",而看"效果好不好"——用固定数据集测完成率、路由正确率、工具调用正确率、以及安全拒绝率。**运维**则把前面讲过的可观测性落地:trace / thread / run 的关联、成本与延迟的分位数、失败率、审批积压(说明人跟不上机器)、以及恢复成功率。 一句经验之谈:**这五层里,前面几层是能力,最后一层是保障;很多团队只做了后面两层(上线后才看效果),结果问题定位成本极高。** 把测试重心前移,是让 Agent 能做进生产的唯一路径。 ### Q:"评测"这一层具体该怎么做才有效? A:结论先行——**用固定数据集 + 明确指标 + 可比较的基线:数据集要覆盖正常、边界和恶意输入;指标要区分"完成率"和"正确率";每次改动都要能跑出可对比的数字**。 先看指标该怎么拆。以这个工单项目为例: ```text 完成率 有多少请求最终到达 resolved(而不是 failed) 路由正确率 classify 给出的 category 是否与人工标注一致 工具正确率 检索到的 knowledge 是否确实来自正确分类的知识库 安全拒绝率 越权 / 敏感 / 恶意输入被正确拦截的比例 成本 平均 token 与平均耗时 ``` 这五类指标各有用途:**完成率**告诉你系统"办成事的比例",是业务最关心的;**路由正确率**告诉你"分支判断准不准",它是可单独优化的一层;**工具正确率**定位"检索/调用对不对";**安全拒绝率**是安全底线,**它必须单独统计,因为"把不该答的也答了"往往不会体现在完成率里**;**成本**则决定这套方案能不能规模化。 再说数据集。数据集至少要包含三类样本:**正常样本**(验证主流程)、**边界样本**(空输入、超长输入、多语言、重复工单)和**恶意/越权样本**(提示注入、越权访问他人订单)。**最后这一类最容易被忽略,却恰恰是上线后风险最高的一类。** 最后是"可比性"。评测真正的价值在于"改动前后能对比"——因此每次评测都要记录:数据集版本、图版本、模型版本、以及各项指标数值。**没有版本记录的评测结论是不可复现的,也就无法支撑发布决策。** 这也呼应了前面反复出现的主题:**确定性是可验证性的前提。** ### Q:生产防线的底线是什么? A:结论先行——**为请求与工具设置 deadline(截止时间);限制循环、token、工具调用与并行度;对工具输入做 Schema 和权限双重校验;用队列承载长任务;发布新图版本时保持旧 checkpoint 的恢复或迁移策略**。 把这五条对应到具体事故: | 底线 | 防住的事故 | |---|---| | 请求与工具设 deadline | 慢工具拖垮请求、用户无限等待 | | 限制循环 / token / 工具调用 / 并行度 | 成本爆炸、下游被打挂、无限循环 | | 工具输入做 Schema + 权限双重校验 | 越权操作、参数注入、误删数据 | | 用队列承载长任务 | HTTP 超时、任务无法恢复、无法削峰 | | 保持旧 checkpoint 的恢复或迁移策略 | 发版后老任务集体失效 | **这五条合起来表达的是同一个立场:模型可以是开放的,但运行它的系统必须是闭合的。** 所谓闭合,就是"输入的取值范围有限、消耗有上限、后果有兜底、版本兼容有安排"。这也正好回答了"Agent 到底怎么才能上线"这个终极问题——**不是靠更聪明的模型,而是靠更严的边界。** ### Q:这份项目还有哪些容易被忽略的坑? A:结论先行——**四个:把示例的 `InMemorySaver` 直接带进生产、把终态节点的副作用写成非幂等、只测成功路径、以及把 `thread_id` 写成固定值或随机值**。 | 坑 | 现象 | 正确做法 | |---|---|---| | 内存持久化进生产 | 发布重启后任务全丢、多副本读不到状态 | 换数据库类 / 托管实现 | | 终态副作用非幂等 | 重放导致重复通知、重复扣款 | 由业务标识推导稳定幂等键 | | 只测成功路径 | 重试耗尽、超时、取消等分支上线才暴露 | 路径测试覆盖全部终止位置 | | `thread_id` 固定或随机 | 不同任务串状态、恢复时找不到 | 由业务标识确定性派生 | 第二个坑最容易被忽视,因为**在确定性示例里它根本不表现出来**——示例中 `mark_resolved` 只写一个状态字段,重复执行没有后果。但一旦你在那里加了"发送通知",重复执行就变成了重复打扰用户。**"从 demo 到生产"的很多事故,都发生在"把一个纯函数节点改成有副作用节点"的那一刻。** 这也是本篇把幂等键单独拿出来讲的原因。 ## 小结 - 最小完整项目刻意不接 LLM:先钉死图、状态、路径、持久化与流式,再接模型,调试范围会小得多。 - 拓扑是一条主线加三个出口;`TicketState` 是唯一契约,字段按"入口 / 中间事实 / 终态"组织,分类与终态用 `Literal` 收窄。 - 七个节点职责清晰:四个业务节点、一个修复节点、两个终态节点;路由函数先判成功、再判预算、最后修复。 - `draft_answer` 重置 `validation_error`、`classify_ticket` 补齐默认值,是避免"幽灵分支"和"字段缺失"的两个小技巧。 - 替换为真实能力时,难点在配套防线:Schema 校验、租户过滤、内容安全、幂等键、生产持久化,一个都不能少。 - 上线前按五层验证:节点单测 → 图路径测试 → 集成测试 → 评测 → 运维告警;底线是 deadline、预算上限、双重校验、队列承载与 checkpoint 迁移策略。 ## 思考题 1. 如果把 `draft_answer` 里那句 `"validation_error": None` 删掉,循环会出现什么现象?请描述一次完整的执行过程。 2. `classify_ticket` 为什么要返回 `"attempts": state.get("attempts", 0)`,而不是直接返回 `0` 或者干脆不返回?两种改法分别会引发什么问题? 3. 假设把 `mark_resolved` 改成"发送通知并关闭工单",请列出你需要的全部防线,并说明每个防线防的是哪一类事故。 4. 为什么"只测成功路径"的测试套件在生产上几乎必然出问题?请举出至少三个会漏掉的分支。 5. 如果面试官要求你"用三分钟讲清这个项目怎么上线",请用状态契约、显式路由、幂等、持久化与五层检查这五个关键词组织回答。
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入