feat：新增代码注释

app/processor/graph.py

@@ -48,10 +48,11 @@ def route_after_scope(state: QueryState) -> str:
 def build_graph(checkpointer=None):
     from app.config import settings
 
+    # 最大重试次数
     max_retries = settings.max_action_retries
 
     def route_failure(state: QueryState) -> str:
-        # 上限检查放在 Reflection 前，避免最后一次无效模型调用
+        # 上限检查，放在 Reflection 前，避免最后一次无效模型调用
         return (
             "reflection_node"
             if state.get("retry_count", 0) < max_retries
@@ -59,8 +60,13 @@ def build_graph(checkpointer=None):
         )
 
     def route_after_action(state: QueryState) -> str:
+        # 如果动作节点已明确标记失败，直接收尾，不再进入内容修正
         if state.get("status") == "failed":
             return "fallback_node"
+
+        # validation_passed 为 False：动作生成时解析或结构校验失败，未达重试上限则进入修正分析，已达上限则失败收尾
+        # validation_passed 为 None：动作已生成但尚未模拟执行，进入 validator_node 检查动作范围和执行结果
+        # 必须用 is False 区分失败与尚未校验，不能将 None 也当作失败
         return (
             route_failure(state)
             if state["validation_passed"] is False
@@ -68,16 +74,20 @@ def build_graph(checkpointer=None):
         )
 
     def route_after_validation(state: QueryState) -> str:
+        # 整批动作通过校验则结束，否则根据剩余重试次数决定修正或失败收尾
         return END if state["validation_passed"] else route_failure(state)
 
     def route_after_reflection(state: QueryState) -> str:
+        # 获取失败分析产生的修正建议，生成建议失败时该字段可能为空
         plan = state.get("repair_plan")
+
+        # 只有存在建议且明确允许重试时才重新生成动作，其余情况统一失败收尾
         return "action_node" if plan is not None and plan.retryable else "fallback_node"
 
-    # 定义工作流
+    # 使用 QueryState 定义节点之间共享的状态结构
     workflow = StateGraph(QueryState)
 
-    # 实例化节点
+    # 为本次构建的图创建节点实例，字典键同时作为注册名称和路由目标
     nodes = {
         "input_node": InputNode(),
         "intent_node": IntentNode(),
@@ -96,14 +106,17 @@ def build_graph(checkpointer=None):
 
     # 注册节点，异步节点使用 BaseNode 的异步入口
     for node_name, node in nodes.items():
+        # 根据 process 是否为异步函数选择调用入口，保留 BaseNode 的统一执行封装
         action = node._acall if inspect.iscoroutinefunction(node.process) else node
+        # 将节点名称与实际调用对象绑定，供后面的边引用
         workflow.add_node(node_name, action)
 
-    # 定义入口
+    # 首次执行从输入节点开始，完成上下文校验后再判断意图
     workflow.set_entry_point("input_node")
 
-    # 添加业务边
+    # 输入处理完成后固定进入意图判断
     workflow.add_edge("input_node", "intent_node")
+
     # 新建和修改进入需求理解，意图不明进入澄清
     workflow.add_conditional_edges(
         source="intent_node",
@@ -115,13 +128,20 @@ def build_graph(checkpointer=None):
             "unclear": "clarify_node",
         },
     )
+
+    # 需求信息不足时提问，信息完整时继续判断修改范围
     workflow.add_conditional_edges(
         source="requirement_node",
         path=route_after_requirement,
         path_map={True: "clarify_node", False: "scope_node"},
     )
+
+    # 先保存澄清问题和等待状态，再进入调用 interrupt 的节点暂停执行
     workflow.add_edge("clarify_node", "wait_for_user_node")
+
+    # 问答生成文本后直接结束，不进入规划和动作流程
     workflow.add_edge("qa_node", END)
+
     # 先读取组件能力再规划，规划后的业务数据查询后续接入
     workflow.add_conditional_edges(
         "scope_node",
@@ -132,12 +152,18 @@ def build_graph(checkpointer=None):
             "fallback_node": "fallback_node",
         },
     )
+
+    # 组件目录查询成功才允许规划，未找到或不支持时进入失败收尾
     workflow.add_conditional_edges(
         "component_resource_node",
         lambda state: state["component_resources"].status == "resolved",
         {True: "planner_node", False: "fallback_node"},
     )
+
+    # 规划完成后交给动作节点转换，动作节点还会检查规划是否可执行
     workflow.add_edge("planner_node", "action_node")
+
+    # 动作生成后按结果进入校验、修正分析或失败收尾
     workflow.add_conditional_edges(
         "action_node",
         route_after_action,
@@ -147,6 +173,8 @@ def build_graph(checkpointer=None):
             "fallback_node": "fallback_node",
         },
     )
+
+    # 校验成功结束，失败则在重试上限内分析修正原因
     workflow.add_conditional_edges(
         "validator_node",
         route_after_validation,
@@ -156,6 +184,8 @@ def build_graph(checkpointer=None):
             "fallback_node": "fallback_node",
         },
     )
+
+    # 修正分析允许重试时回到动作生成，形成生成、校验、分析的循环
     workflow.add_conditional_edges(
         "reflection_node",
         route_after_reflection,
@@ -164,14 +194,21 @@ def build_graph(checkpointer=None):
             "fallback_node": "fallback_node",
         },
     )
+
+    # 失败节点统一写入最终失败状态后结束流程
     workflow.add_edge("fallback_node", END)
+
+    # 用户补充后重新合并输入并判断意图，取消则直接结束
     workflow.add_conditional_edges(
         "wait_for_user_node",
         route_after_wait,
         {"input_node": "input_node", END: END},
     )
+
     # TODO 本地默认保存在内存，可传入持久化 checkpointer
+    # 仅在调用方未提供检查点存储时创建默认实现，外部传入的存储直接复用
     if checkpointer is None:
+        # 允许恢复状态中使用的业务模型类型，使检查点读取后仍可按模型对象访问字段
         serde = JsonPlusSerializer(
             allowed_msgpack_modules=[
                 ("app.schemas.input_context", "InputContext"),
@@ -193,16 +230,20 @@ def build_graph(checkpointer=None):
                 ("app.schemas.clarification_reply", "ClarificationReply"),
             ]
         )
+
+        # 将检查点保存在当前进程内存中，支持暂停恢复，但进程退出后不会保留
         checkpointer = InMemorySaver(serde=serde)
 
+    # 编译节点和边，并绑定检查点存储，供执行时按 thread_id 保存和恢复状态
     return workflow.compile(checkpointer=checkpointer).with_config(
         {
+            # 随修正上限增加图执行步数预算，每轮预留分析、生成、校验三步，至少允许 25 步
             "recursion_limit": max(25, 12 + 3 * max_retries),
         }
     )
 
 
-# 创建全局图实例
+# 模块加载时创建共享图实例，复用该实例的调用也共用其检查点存储
 query_app = build_graph()