提供function call文件注释

src/gcode/graph.py

@@ -1,4 +1,13 @@
-"""LangGraph ReAct heart: START → llm_call ⇄ tool_node → END. No global llm/agent."""
+"""LangGraph ReAct 核心：START → llm_call ⇄ tool_node → END。
+
+Function Call 在这里怎么走：
+  1. 模型不会自己执行 Python，只会在回复里写出 tool_calls（函数名 + 参数）。
+  2. _should_continue 看到 tool_calls，就把控制权交给 tool_node。
+  3. tool_node 按名字找到真正的函数并执行，结果写成 ToolMessage 交回模型。
+  4. 再进 llm_call：模型看观察结果，决定继续调工具还是直接回答。
+
+这就是 ReAct：Reason（想）→ Act（调工具）→ Observe（看结果）→ 再 Reason。
+"""
 
 from __future__ import annotations
 
@@ -16,12 +25,20 @@ from gcode.models.openai_compatible import extract_reasoning, extract_text
 from gcode.prompt import dynamic_context, static_system_prompt
 from gcode.session import Session
 
+# 同一轮对话最多问模型这么多次，防止「调工具 → 再想 → 再调」死循环烧钱。
+# 40 不是官方标准，也不是 LangGraph / OpenAI 的规定，只是本项目初始化时拍的经验上限：
+#   - 日常改文件大概 5～15 次就够（读 → 改 → 跑 → 修）
+#   - 再大的任务应拆成下一轮，而不是一轮里无限转
+# 容易混淆的官方数字：LangGraph 的 recursion_limit（默认曾是 25，1.0.6+ 改为 1000）
+# 数的是图节点步数（llm_call 和 tool_node 各算一步），不是「问模型几次」。
+# 本常量只拦 llm_call；图本身没改 recursion_limit，复杂一轮仍可能先撞框架上限。
 MAX_LLM_CALLS = 40
 
 
 class MessagesState(TypedDict):
+    # operator.add：节点返回的新消息会「追加」到列表，而不是覆盖整段历史。
     messages: Annotated[list[AnyMessage], operator.add]
-    llm_calls: int
+    llm_calls: int  # 本轮已经调用模型的次数
 
 
 class Agent:
@@ -35,7 +52,9 @@ class Agent:
         has_browser: bool = False,
         cwd: Path | None = None,
     ) -> None:
+        # 运行时按名字找函数：模型只输出 "read_file"，这里才能对上真正的 Python 工具。
         self._tools = {t.name: t for t in tools}
+        # 把工具的 schema（名字、参数、说明）告诉模型，它才会在回复里生成 tool_calls。
         self._model = model.bind_tools(tools)
         self._session = session
         self._model_id = model_id
@@ -46,24 +65,28 @@ class Agent:
         self._graph = self._build(checkpointer)
 
     def _build(self, checkpointer: Any) -> Any:
+        # 搭一张状态图：两个节点，一条条件边决定「调工具」还是「结束」。
         builder = StateGraph(MessagesState)
         builder.add_node("llm_call", self._llm_call)
         builder.add_node("tool_node", self._tool_node)
         builder.add_edge(START, "llm_call")
         builder.add_conditional_edges(
             "llm_call",
-            self._should_continue,
+            self._should_continue,  # 看最后一条消息有没有 tool_calls
             {"tool_node": "tool_node", END: END},
         )
+        # 工具跑完必须再回模型，否则观察结果没人读。
         builder.add_edge("tool_node", "llm_call")
         return builder.compile(checkpointer=checkpointer)
 
     def _graph_config(self) -> dict[str, Any] | None:
+        # checkpointer 需要 thread_id 才能把同一会话的消息存下来、下次接着聊。
         if self._session and self._session.checkpointer:
             return self._session.config()
         return None
 
     async def invoke_turn(self, user_text: str) -> list[AnyMessage]:
+        """整轮跑完再返回全部消息（测试 / 非流式用）。"""
         payload: MessagesState = {
             "messages": [HumanMessage(content=user_text)],
             "llm_calls": 0,
@@ -73,6 +96,7 @@ class Agent:
         return list(result["messages"])
 
     async def stream_turn(self, user_text: str) -> AsyncIterator[AgentEvent]:
+        """边跑边吐事件：思考文字、工具开始/结束，给 TUI 用。"""
         payload: MessagesState = {
             "messages": [HumanMessage(content=user_text)],
             "llm_calls": 0,
@@ -88,6 +112,7 @@ class Agent:
             yield AgentEvent(type="error", text=f"{type(exc).__name__}: {exc}")
 
     async def _llm_call(self, state: MessagesState) -> dict[str, Any]:
+        """问模型一次。返回值只含「本节点新增」的字段，messages 会被 append。"""
         calls = int(state.get("llm_calls") or 0)
         if calls >= MAX_LLM_CALLS:
             return {
@@ -103,10 +128,12 @@ class Agent:
         messages = _repair_incomplete_tool_calls(messages)
 
         try:
+            # response 可能是普通文字，也可能带 tool_calls（只声明要调谁，还没执行）。
             response = await self._model.ainvoke(messages)
             return {"messages": [response], "llm_calls": calls + 1}
         except Exception as exc:
             err = str(exc)
+            # 常见 400：历史里有 tool_calls 却缺对应的 ToolMessage，补占位后再试一次。
             if "tool_calls" in err and "tool_call_id" in err:
                 try:
                     repaired = _repair_incomplete_tool_calls(messages)
@@ -118,6 +145,7 @@ class Agent:
             return {"messages": [AIMessage(content=friendly)], "llm_calls": calls + 1}
 
     async def _tool_node(self, state: MessagesState) -> dict[str, Any]:
+        """真正执行函数：读上一轮 AIMessage.tool_calls，按名字 ainvoke。"""
         import asyncio
 
         last = state["messages"][-1]
@@ -141,15 +169,18 @@ class Agent:
                 observation = f"工具 '{name}' 调用失败: {type(exc).__name__}: {exc}"
             if not isinstance(observation, str):
                 observation = str(observation)
+            # tool_call_id 必须对上模型那次声明，否则下一轮 llm_call 会 400。
             return ToolMessage(content=observation, tool_call_id=call_id, name=name)
 
         if len(tool_calls) <= 1:
             results = [await one(tool_calls[0])] if tool_calls else []
         else:
+            # 模型一轮里可能同时要读文件 + 列目录，并行跑。
             results = list(await asyncio.gather(*[one(tc) for tc in tool_calls]))
         return {"messages": results}
 
     def _should_continue(self, state: MessagesState) -> Literal["tool_node", "__end__"]:
+        """条件边：有 tool_calls → 去执行；没有 → 本轮结束（纯文字回答）。"""
         messages = state.get("messages") or []
         if not messages:
             return END
@@ -160,6 +191,11 @@ class Agent:
 
 
 def _assemble_messages(static: str, dyn: str, history: list[AnyMessage]) -> list[AnyMessage]:
+    """拼出发给模型的完整上下文：固定系统提示 + 动态环境 + 对话历史。
+
+    动态部分（cwd、模型 id）每次 llm_call 都重算，所以嵌进第一条用户消息，
+    而不是单独一条 SystemMessage（避免历史里叠很多条过期系统提示）。
+    """
     out: list[AnyMessage] = [SystemMessage(content=static)]
     if not history:
         out.append(HumanMessage(content=dyn))
@@ -177,6 +213,7 @@ def _assemble_messages(static: str, dyn: str, history: list[AnyMessage]) -> list
 
 
 def _strip_images(messages: list[AnyMessage]) -> list[AnyMessage]:
+    """当前走纯文本接口：用户消息里如果夹了图片块，只留下 text。"""
     cleaned: list[AnyMessage] = []
     for msg in messages:
         if isinstance(msg, HumanMessage) and isinstance(msg.content, list):
@@ -193,6 +230,11 @@ def _strip_images(messages: list[AnyMessage]) -> list[AnyMessage]:
 
 
 def _repair_incomplete_tool_calls(messages: list[AnyMessage]) -> list[AnyMessage]:
+    """补齐「声明了 tool_calls 但没有 ToolMessage」的缺口。
+
+    典型场景：上次对话做到一半退出，checkpoint 里留下 AIMessage.tool_calls，
+    却没有对应结果。OpenAI 兼容接口要求每条 tool_call 都有一条同 id 的 ToolMessage。
+    """
     declared: set[str] = set()
     for msg in messages:
         if isinstance(msg, AIMessage) and getattr(msg, "tool_calls", None):
@@ -228,6 +270,7 @@ def _repair_incomplete_tool_calls(messages: list[AnyMessage]) -> list[AnyMessage
 
 
 def _map_stream_event(ev: dict[str, Any]) -> AgentEvent | None:
+    """把 LangGraph 底层事件收成 TUI 认识的几种：thinking / text / tool_start / tool_end。"""
     kind = ev.get("event") or ""
     meta = ev.get("metadata") or {}
     node = meta.get("langgraph_node")