langchain-agentx-python 2.2.3__py3-none-any.whl → 2.2.5__py3-none-any.whl

langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "2.2.3"
+__version__ = "2.2.5"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

langchain_agentx/tools/grep/backend.py

@@ -6,7 +6,7 @@ tools/grep/backend.py — RipgrepBackend（ripgrep 子进程封装）
 
 在整体链路中的位置：
     GrepRuntimeTool.invoke() -> RipgrepBackend.search() -> run_ripgrep_lines（可选 ctx.cancel_event）
-    -> RgSubprocessController 或 TextSubprocessRunner
+    -> RgSubprocessController（有界 stdout）或 TextSubprocessRunner（测试注入）
 
 对应 CC：src/utils/ripgrep.ts + GrepTool.ts call() 中参数拼装。
 """
@@ -16,7 +16,6 @@ from __future__ import annotations
 import os
 import subprocess
 import threading
-from typing import Any
 
 from langchain_agentx.tool_runtime.errors import ToolRuntimeError
 from langchain_agentx.utils.rg_executable import default_rg_executable
@@ -26,6 +25,7 @@ from langchain_agentx.utils.subprocess_text import (
 )
 
 from .models import GrepOutputMode
+from .ripgrep_stdout_cap import RipgrepStdoutCap
 
 
 def resolve_ripgrep_subprocess_cwd(search_path: str) -> str:
@@ -58,6 +58,11 @@ class GrepCancelledError(ToolRuntimeError):
         super().__init__(message, code="GREP_CANCELLED")
 
 
+def _uses_injected_subprocess_run(text_runner: TextSubprocessRunner) -> bool:
+    """测试注入自定义 ``subprocess_run`` 时走 text_runner；生产默认走有界 controller。"""
+    return getattr(text_runner, "_subprocess_run", None) is not subprocess.run
+
+
 def run_ripgrep_lines(
     rg_path: str,
     args: list[str],
@@ -70,21 +75,25 @@ def run_ripgrep_lines(
 ) -> list[str]:
     """
     执行 [rg_path, *args, search_path]，解析 stdout 为行列表。
-    对齐 CC ripgrep.ts：returncode 1 -> []；EAGAIN 时以 -j 1 重试一次。
+    对齐 CC ripgrep.ts：returncode 1 -> []；EAGAIN 时以 -j 1 重试一次；
+    stdout 硬顶 ``MAX_STDOUT_BUFFER_SIZE``（20MB）。
     供 RipgrepBackend 与 Glob 的 rg --files 列文件共用。
 
     SDK 补充：``subprocess cwd`` 对齐搜索根目录（目录本身，或文件的父目录）。
     CC 隐式依赖进程 cwd≈searchDir；编排布局 ``state_root≠repo`` 时须显式设 cwd，
     否则 Windows 上目录前缀 glob（如 ``alpha/*``）误空。
 
-    若 ``cancel_event`` 非空，使用可中断子进程路径（``RgSubprocessController``），
-    不再走 ``text_runner.run``（便于测试 mock 时仅覆盖无取消路径）。
+    生产路径使用 ``RgSubprocessController`` 边收边截；仅当测试注入自定义
+    ``text_runner.subprocess_run`` 时走 ``text_runner.run``（事后硬顶）。
     """
     search_target = os.path.realpath(search_path)
     search_cwd = resolve_ripgrep_subprocess_cwd(search_path)
     cmd = [rg_path, *args, search_target]
-    if cancel_event is not None:
-        if cancel_event.is_set():
+    stdout_truncated = False
+
+    use_text_runner = cancel_event is None and _uses_injected_subprocess_run(text_runner)
+    if not use_text_runner:
+        if cancel_event is not None and cancel_event.is_set():
             raise GrepCancelledError("ripgrep cancelled before start")
         from langchain_agentx.tools.grep.rg_subprocess_controller import RgSubprocessController
 
@@ -100,6 +109,7 @@ def run_ripgrep_lines(
             raise
         except GrepCancelledError:
             raise
+        stdout_truncated = bool(getattr(result, "stdout_truncated", False))
     else:
         try:
             result = text_runner.run(
@@ -134,10 +144,7 @@ def run_ripgrep_lines(
         raise GrepExecutionError(f"ripgrep failed: {stderr or f'exit code {result.returncode}'}")
 
     out = result.stdout or ""
-    if not out.strip():
-        return []
-    lines = [ln.rstrip("\r") for ln in out.rstrip("\n").split("\n")]
-    return [ln for ln in lines if ln]
+    return RipgrepStdoutCap.lines_from_text(out, truncated=stdout_truncated)
 
 
 class RipgrepBackend:

langchain_agentx/tools/grep/rg_subprocess_controller.py

@@ -3,10 +3,11 @@ tools/grep/rg_subprocess_controller.py — ripgrep 子进程 timeout + 协作取
 
 职责：
     在无法使用单次 ``subprocess.run(..., timeout=)`` 响应协作取消时，用 Popen + 后台
-    ``communicate`` 与主线程轮询 ``cancel_event``，对齐 CC ``ripGrep(..., abortSignal)``。
+    有界 stdout/stderr 读取与主线程轮询 ``cancel_event``，对齐 CC ``ripGrep(..., abortSignal)``
+    与 ``MAX_BUFFER_SIZE`` 边收边截。
 
 链路位置：
-    ``grep.backend.run_ripgrep_lines`` 在传入非空 ``cancel_event`` 时委托本类；
+    ``grep.backend.run_ripgrep_lines`` 在生产路径（或传入 ``cancel_event``）时委托本类；
     ``RipgrepBackend.search_stream_limited`` 在读取 stdout 时轮询同一事件。
 
 当前裁剪范围：
@@ -24,13 +25,17 @@ from langchain_agentx.tools.grep.backend import (
     GrepExecutionError,
     GrepTimeoutError,
 )
+from langchain_agentx.tools.grep.ripgrep_stdout_cap import RipgrepStdoutCap
 
 
 class RgSubprocessController:
-    """封装可中断的阻塞式子进程等待（timeout + ``threading.Event``）。"""
+    """封装可中断的阻塞式子进程等待（timeout + ``threading.Event`` + stdout 硬顶）。"""
 
     _poll_interval_s = 0.05
 
+    def __init__(self, *, stdout_cap_factory: type[RipgrepStdoutCap] = RipgrepStdoutCap) -> None:
+        self._stdout_cap_factory = stdout_cap_factory
+
     def run_argv_wait_completed(
         self,
         argv: list[str],
@@ -42,8 +47,11 @@ class RgSubprocessController:
         """
         启动 ``argv``，在 ``timeout`` 秒内等待结束；若 ``cancel_event`` 被 set 则 terminate/kill。
 
+        stdout/stderr 边收边截（``RipgrepStdoutCap``），避免无界 ``communicate`` 打爆内存。
+
         Returns:
             ``CompletedProcess``（text stdout/stderr），供上层解析 returncode。
+            额外属性 ``stdout_truncated`` / ``stderr_truncated``（bool）。
         """
         if cancel_event is not None and cancel_event.is_set():
             raise GrepCancelledError("ripgrep cancelled before start")
@@ -64,19 +72,33 @@ class RgSubprocessController:
                 "'rg.exe' is on PATH; on Unix ensure 'rg' is on PATH."
             ) from e
 
-        out_box: list[str | None] = [None]
-        err_box: list[str | None] = [None]
+        stdout_cap = self._stdout_cap_factory()
+        stderr_cap = self._stdout_cap_factory()
         thread_exc: list[BaseException | None] = [None]
 
-        def _communicate_worker() -> None:
+        def _readers_worker() -> None:
             try:
-                o, e = proc.communicate()
-                out_box[0] = o
-                err_box[0] = e
+                assert proc.stdout is not None
+                assert proc.stderr is not None
+                out_t = threading.Thread(
+                    target=stdout_cap.drain_text_stream,
+                    args=(proc.stdout,),
+                    daemon=True,
+                )
+                err_t = threading.Thread(
+                    target=stderr_cap.drain_text_stream,
+                    args=(proc.stderr,),
+                    daemon=True,
+                )
+                out_t.start()
+                err_t.start()
+                out_t.join()
+                err_t.join()
+                proc.wait()
             except BaseException as ex:  # noqa: BLE001 — 必须兜住线程内异常
                 thread_exc[0] = ex
 
-        worker = threading.Thread(target=_communicate_worker, daemon=True)
+        worker = threading.Thread(target=_readers_worker, daemon=True)
         worker.start()
         deadline = time.monotonic() + timeout
 
@@ -98,12 +120,16 @@ class RgSubprocessController:
             if thread_exc[0] is not None:
                 raise thread_exc[0]
 
-            return subprocess.CompletedProcess(
+            result = subprocess.CompletedProcess(
                 args=argv,
                 returncode=proc.returncode if proc.returncode is not None else -1,
-                stdout=out_box[0] or "",
-                stderr=err_box[0] or "",
+                stdout=stdout_cap.text(),
+                stderr=stderr_cap.text(),
             )
+            # 供 run_ripgrep_lines 决定是否丢弃残缺末行
+            setattr(result, "stdout_truncated", stdout_cap.truncated)
+            setattr(result, "stderr_truncated", stderr_cap.truncated)
+            return result
         finally:
             if proc.poll() is None:
                 try:

langchain_agentx/tools/grep/ripgrep_stdout_cap.py

@@ -0,0 +1,93 @@
+"""
+tools/grep/ripgrep_stdout_cap.py — ripgrep stdout/stderr 字节硬顶
+
+职责：
+    对齐 CC ``src/utils/ripgrep.ts`` 的 ``MAX_BUFFER_SIZE = 20_000_000``：
+    边收边截，超限停止 append；解析行时若已截断则丢弃可能残缺的末行。
+
+链路位置：
+    ``run_ripgrep_lines`` / ``RgSubprocessController`` 共用；Grep 与 Glob 列文件同路径受益。
+
+当前裁剪：
+    按 Unicode 字符长度计量（对齐 CC JS string ``.length``）；不在此杀进程。
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# 对齐 CC ripgrep.ts：large monorepos can have 200k+ files
+MAX_STDOUT_BUFFER_SIZE = 20_000_000
+
+
+class RipgrepStdoutCap:
+    """可复用的有界 stdout/stderr 收集器（feed 后 to_lines / text）。"""
+
+    def __init__(self, max_size: int = MAX_STDOUT_BUFFER_SIZE) -> None:
+        if max_size <= 0:
+            raise ValueError("max_size must be positive")
+        self._max_size = max_size
+        self._parts: list[str] = []
+        self._size = 0
+        self.truncated = False
+
+    @property
+    def max_size(self) -> int:
+        return self._max_size
+
+    @property
+    def size(self) -> int:
+        return self._size
+
+    def feed(self, chunk: str) -> None:
+        """追加 chunk；已截断时忽略内容（调用方仍应继续读以排空管道）。"""
+        if self.truncated or not chunk:
+            return
+        remaining = self._max_size - self._size
+        if len(chunk) <= remaining:
+            self._parts.append(chunk)
+            self._size += len(chunk)
+            return
+        if remaining > 0:
+            self._parts.append(chunk[:remaining])
+            self._size = self._max_size
+        self.truncated = True
+
+    def text(self) -> str:
+        return "".join(self._parts)
+
+    def to_lines(self) -> list[str]:
+        """拆成非空行；截断时丢弃末行（对齐 CC buffer overflow / timeout 处理）。"""
+        return self.lines_from_text(self.text(), truncated=self.truncated)
+
+    @staticmethod
+    def lines_from_text(out: str, *, truncated: bool = False) -> list[str]:
+        """对已物化字符串做硬顶 + 分行（text_runner / mock 路径）。"""
+        if not out:
+            return []
+        was_truncated = truncated
+        if len(out) > MAX_STDOUT_BUFFER_SIZE:
+            out = out[:MAX_STDOUT_BUFFER_SIZE]
+            was_truncated = True
+        if not out.strip():
+            return []
+        lines = [ln.rstrip("\r") for ln in out.rstrip("\n").split("\n")]
+        lines = [ln for ln in lines if ln]
+        if was_truncated and lines:
+            lines = lines[:-1]
+        if was_truncated:
+            logger.warning(
+                "ripgrep stdout truncated at %s chars (CC MAX_BUFFER_SIZE alignment)",
+                MAX_STDOUT_BUFFER_SIZE,
+            )
+        return lines
+
+    def drain_text_stream(self, stream) -> None:
+        """从文本流按块读取并 feed，超限后继续排空但不入库。"""
+        while True:
+            chunk = stream.read(64 * 1024)
+            if not chunk:
+                break
+            self.feed(chunk)

langchain_agentx/workflow/base.py

@@ -65,7 +65,7 @@ from .execution import (
 )
 from .memory_drain_registry import MemoryDrainRegistry
 from .memory_session_policy import collect_agent_nodes, validate_loop_session_ids
-from .state import WorkflowState
+from .state import WorkflowState, project_workflow_node_update
 
 # Lazy import for event_adapter（避免循环依赖）
 # 实际使用时通过 _get_event_adapter() 延迟导入
@@ -453,21 +453,22 @@ class BaseWorkflow(ABC):
 
         与 run() 的区别：
             - run(): 返回完整 WorkflowState（用于顶层调用）
-            - as_node(): 返回完整 WorkflowState（作为其他 Workflow 的节点）
+            - as_node(): 返回相对父 state 的 channel delta（供 LangGraph reducer 合并）
 
         实现原理：
-            - 直接调用 run() 返回完整 state
+            - 调用 run() 得到子图终态
+            - 经 project_workflow_node_update 将 messages / item_results 投影为增量
             - 传递 parent_workflow 构建层级关系
             - 使用 outer_semaphore 控制并发（如果提供）
-            - LangGraph 的 reducer 会自动处理合并
 
         并发控制（问题 19）：
             - 如果 outer_workflow 提供 semaphore，子 workflow 的执行会被限流
             - 这解决了 DeepSearch 场景下 45 个 sub-workflow 同时启动的问题
 
-        注意（问题 18 - as_node() diff 算法硬 bug）：
-            - ✅ 新设计（正确）：直接返回完整 state，让 LangGraph reducer 处理合并
-            - ❌ 旧设计（错误）：手算 diff，硬编码字段名，假设 reducer 是 list append
+        注意（聚合通道契约 · 2026-09-04）：
+            - 节点必须返回 delta，禁止把父 state 全量回写进 messages / item_results
+            - 手写节点请用 delta_messages / delta_item_results
+            - as_node 已自动投影，避免嵌套子图 2^N 膨胀
         """
         async def node_fn(state: dict) -> dict:
             # 入口即快照父 _active_run_config，避免 run() 内 set/restore 与父并发时读漂移。
@@ -475,16 +476,18 @@ class BaseWorkflow(ABC):
             # === 并发控制（问题 19）===
             if outer_semaphore is not None:
                 async with outer_semaphore:
-                    return await self.run(
+                    result = await self.run(
                         state,
                         parent_workflow=parent_workflow,
                         run_config=inherited_run_config,
                     )
-            return await self.run(
-                state,
-                parent_workflow=parent_workflow,
-                run_config=inherited_run_config,
-            )
+            else:
+                result = await self.run(
+                    state,
+                    parent_workflow=parent_workflow,
+                    run_config=inherited_run_config,
+                )
+            return project_workflow_node_update(state, result)
 
         return node_fn
 

langchain_agentx/workflow/node.py

@@ -93,16 +93,22 @@ class AgentNode:
         ctx: WorkflowNodeContext,
         invocation: LoopInvocation,
     ) -> dict[str, Any]:
-        del state, ctx
-        return {
-            "messages": graph_result.get("messages", []),
-            "item_results": [
+        from .state import delta_item_results, project_workflow_node_update
+
+        del ctx
+        update = project_workflow_node_update(
+            {"messages": state.get("messages", [])},
+            {"messages": graph_result.get("messages", [])},
+        )
+        update.update(
+            delta_item_results(
                 {
                     "node": self.name,
                     "session_id": invocation.session_id,
                 }
-            ],
-        }
+            )
+        )
+        return update
 
     def map_error(
         self,
@@ -110,16 +116,16 @@ class AgentNode:
         exc: Exception,
         ctx: WorkflowNodeContext,
     ) -> dict[str, Any]:
-        return {
-            "messages": state.get("messages", []),
-            "item_results": [
-                {
-                    "node": self.name,
-                    "session_id": ctx.loop_session_id,
-                    "error": str(exc),
-                }
-            ],
-        }
+        from .state import delta_item_results
+
+        del state
+        return delta_item_results(
+            {
+                "node": self.name,
+                "session_id": ctx.loop_session_id,
+                "error": str(exc),
+            }
+        )
 
     def _resolve_graph_factory(
         self,

langchain_agentx/workflow/state.py

@@ -1,10 +1,11 @@
 """
-state.py — Workflow 状态定义
+state.py — Workflow 状态定义与聚合通道契约
 
 职责：
     - 定义 WorkflowState 基类（TypedDict + Annotated reducer）
-    - 规范 Workflow 状态字段命名与 reducer 使用
-    - 提供文档模式定义，不强制继承
+    - item_results 按身份键幂等合并（防 2^N 全量回写 OOM）
+    - 提供 delta_messages / delta_item_results 增量构造接口（防误用）
+    - as_node 用 project_workflow_node_update 将终态投影为 delta
 
 链路位置：
     - 被 BaseWorkflow 和所有特殊 Workflow 使用
@@ -13,44 +14,268 @@ state.py — Workflow 状态定义
 当前裁剪范围：
     - 仅包含基础字段（messages, item_results, workflow_id 等）
     - 业务特定字段由具体 Workflow 自行扩展
-
-设计说明（问题 10）：
-    - WorkflowState 使用 TypedDict，这是 LangGraph 的最佳实践
-    - TypedDict + Annotated reducer 是 LangGraph 官方推荐的状态定义方式
-    - 不要使用普通 dict（没有类型检查和 reducer 支持）
-    - 不要使用 dataclass（LangGraph StateGraph 不直接支持）
+    - 通道预算上限（P2）未做
 """
 
 from __future__ import annotations
 
-from typing import Annotated, TypedDict
-from operator import add
+import logging
+import os
+from typing import Annotated, Any, Hashable, Mapping, Sequence, TypedDict
 
 from langgraph.graph.message import add_messages
 from langchain_core.messages import AnyMessage
 
+logger = logging.getLogger(__name__)
+
+_STRICT_DELTA_ENV = "LANGCHAIN_AGENTX_WORKFLOW_STRICT_DELTA"
+
+# 显式主键优先；其次 task（编排任务）；再 node/repo/session 等复合键
+_EXPLICIT_IDENTITY_KEYS: tuple[str, ...] = ("result_id", "item_key", "id")
+_COMPOSITE_IDENTITY_KEYS: tuple[str, ...] = (
+    "node",
+    "repo_id",
+    "repo",
+    "session_id",
+    "from",
+)
+
+
+def item_result_identity(item: Any) -> Hashable | None:
+    """提取 item_results 条目的合并身份；无身份则返回 None（走 append）。"""
+    if not isinstance(item, dict):
+        try:
+            hash(item)
+        except TypeError:
+            return None
+        return ("value", item)
+
+    for key in _EXPLICIT_IDENTITY_KEYS:
+        value = item.get(key)
+        if value is not None:
+            return (key, value)
+
+    task = item.get("task")
+    if task is not None:
+        return ("task", task)
+
+    parts = tuple(
+        (key, item[key])
+        for key in _COMPOSITE_IDENTITY_KEYS
+        if item.get(key) is not None
+    )
+    if parts:
+        return ("composite", parts)
+    return None
+
+
+def _looks_like_full_rewrite(left: Sequence[Any], right: Sequence[Any]) -> bool:
+    """检测典型反模式：提交值 = 旧列表前缀 + 增量（state.get(...) + [...]）。"""
+    if not left or len(right) <= len(left):
+        return False
+    return list(right[: len(left)]) == list(left)
+
+
+def _maybe_raise_or_warn_full_rewrite(left: list[Any], right: list[Any]) -> None:
+    if not _looks_like_full_rewrite(left, right):
+        return
+    message = (
+        "item_results full-rewrite antipattern detected: "
+        f"submitted len={len(right)} looks like prior len={len(left)} + suffix. "
+        "Return delta only via delta_item_results(...); "
+        "do not submit state.get('item_results', []) + [...]."
+    )
+    if os.environ.get(_STRICT_DELTA_ENV, "").strip() in {"1", "true", "TRUE", "yes", "YES"}:
+        raise ValueError(message)
+    logger.warning(message)
+
+
+class ItemResultsMerge:
+    """item_results 通道归约器：按身份键幂等合并，并检测全量回写。"""
+
+    def __call__(
+        self,
+        left: list[Any] | None,
+        right: list[Any] | None,
+    ) -> list[Any]:
+        return self.merge(left, right)
+
+    def merge(
+        self,
+        left: list[Any] | None,
+        right: list[Any] | None,
+    ) -> list[Any]:
+        left_list = list(left or [])
+        right_list = list(right or [])
+        if not right_list:
+            return left_list
+        if not left_list:
+            return list(right_list)
+
+        _maybe_raise_or_warn_full_rewrite(left_list, right_list)
+
+        keyed: dict[Hashable, int] = {}
+        merged: list[Any] = []
+        for item in left_list:
+            identity = item_result_identity(item)
+            if identity is None:
+                merged.append(item)
+                continue
+            if identity in keyed:
+                merged[keyed[identity]] = item
+            else:
+                keyed[identity] = len(merged)
+                merged.append(item)
+
+        for item in right_list:
+            identity = item_result_identity(item)
+            if identity is None:
+                merged.append(item)
+                continue
+            if identity in keyed:
+                merged[keyed[identity]] = item
+            else:
+                keyed[identity] = len(merged)
+                merged.append(item)
+        return merged
+
+
+merge_item_results = ItemResultsMerge()
+
+
+def _normalize_varargs(items: tuple[Any, ...]) -> list[Any]:
+    if len(items) == 1 and isinstance(items[0], list):
+        return list(items[0])
+    return list(items)
+
+
+def delta_messages(*messages: Any) -> dict[str, list[Any]]:
+    """构造 messages 通道增量（节点应 return 本 dict 或其展开）。
+
+    只接收本次新增消息，禁止传入 state['messages'] 全量历史。
+    """
+    return {"messages": _normalize_varargs(messages)}
+
+
+def delta_item_results(*items: Any) -> dict[str, list[Any]]:
+    """构造 item_results 通道增量（节点应 return 本 dict 或其展开）。
+
+    只接收本次新增/更新条目；条目宜带身份键（result_id / item_key / task / node+…）。
+    禁止传入 state.get('item_results', []) + [...] 全量历史。
+    """
+    return {"item_results": _normalize_varargs(items)}
+
+
+def _message_identity(message: Any) -> Hashable | None:
+    msg_id = getattr(message, "id", None)
+    if msg_id is not None:
+        return ("id", msg_id)
+    return None
+
+
+def _messages_delta(before: Sequence[Any] | None, after: Sequence[Any] | None) -> list[Any]:
+    before_list = list(before or [])
+    after_list = list(after or [])
+    if not after_list:
+        return []
+    seen: set[Hashable] = set()
+    for message in before_list:
+        identity = _message_identity(message)
+        if identity is not None:
+            seen.add(identity)
+    delta: list[Any] = []
+    for message in after_list:
+        identity = _message_identity(message)
+        if identity is None:
+            # 无 id：仅当不在 before 相等集合中时纳入（弱 diff）
+            if message not in before_list:
+                delta.append(message)
+            continue
+        if identity not in seen:
+            seen.add(identity)
+            delta.append(message)
+    return delta
+
+
+def _item_results_delta(
+    before: Sequence[Any] | None,
+    after: Sequence[Any] | None,
+) -> list[Any]:
+    before_list = list(before or [])
+    after_list = list(after or [])
+    if not after_list:
+        return []
+
+    before_by_key: dict[Hashable, Any] = {}
+    before_unkeyed: list[Any] = []
+    for item in before_list:
+        identity = item_result_identity(item)
+        if identity is None:
+            before_unkeyed.append(item)
+        else:
+            before_by_key[identity] = item
+
+    delta: list[Any] = []
+    after_unkeyed: list[Any] = []
+    for item in after_list:
+        identity = item_result_identity(item)
+        if identity is None:
+            after_unkeyed.append(item)
+            continue
+        prior = before_by_key.get(identity)
+        if prior is None or prior != item:
+            delta.append(item)
+
+    remaining_unkeyed = list(before_unkeyed)
+    for item in after_unkeyed:
+        if item in remaining_unkeyed:
+            remaining_unkeyed.remove(item)
+        else:
+            delta.append(item)
+    return delta
+
+
+def project_workflow_node_update(
+    before: Mapping[str, Any],
+    after: Mapping[str, Any],
+) -> dict[str, Any]:
+    """将子 workflow 终态投影为父图节点应提交的 channel delta。
+
+    聚合通道（messages / item_results）只提交相对 before 的增量；
+    其它字段在值变化时原样写入（last-write-wins）。
+    """
+    update: dict[str, Any] = {}
+    for key, value in after.items():
+        if key == "messages":
+            delta = _messages_delta(before.get("messages"), value)
+            if delta:
+                update["messages"] = delta
+            continue
+        if key == "item_results":
+            delta = _item_results_delta(before.get("item_results"), value)
+            if delta:
+                update["item_results"] = delta
+            continue
+        if before.get(key) != value:
+            update[key] = value
+    return update
+
 
 class WorkflowState(TypedDict, total=False):
     """Workflow 状态 schema，支持并发写入。
 
     字段说明：
-    - messages: 消息列表（所有节点都会追加消息，使用 reducer）
-    - item_results: 并行任务结果列表（聚合所有 item 的输出，使用 reducer）
-    - workflow_id: 当前 Workflow ID（单写，由 BaseWorkflow 设置）
-    - task_key: 当前任务标识符（单写，Phase 2+）
-    - current_step: 当前步骤（单写，用于顺序 Workflow）
-    - error: 错误信息（单写，用于错误处理）
-
-    使用方式：
-    - 基础类型：WorkflowState（本定义）
-    - 扩展类型：class MyState(WorkflowState, total=False) 添加业务字段
+    - messages: 消息列表（add_messages 按 id 幂等合并）
+    - item_results: 并行/叶节点产出（merge_item_results 按身份键幂等合并）
+    - workflow_id / task_key / current_step / orchestration_round / error: 单写字段
+
+    节点写入约定：
+    - 使用 delta_messages / delta_item_results 构造增量，禁止 {**state} 全量回写聚合通道
     """
 
-    # === 并发聚合字段（使用 reducer）===
     messages: Annotated[list[AnyMessage], add_messages]
-    item_results: Annotated[list[dict], add]
+    item_results: Annotated[list[dict], merge_item_results]
 
-    # === 单写字段（无需 reducer）===
     workflow_id: str
     task_key: str | None
     current_step: str | None
@@ -58,4 +283,12 @@ class WorkflowState(TypedDict, total=False):
     error: str | None
 
 
-__all__ = ["WorkflowState"]
+__all__ = [
+    "WorkflowState",
+    "ItemResultsMerge",
+    "merge_item_results",
+    "item_result_identity",
+    "delta_messages",
+    "delta_item_results",
+    "project_workflow_node_update",
+]

{langchain_agentx_python-2.2.3.dist-info → langchain_agentx_python-2.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 2.2.3
+Version: 2.2.5
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License: Apache License

{langchain_agentx_python-2.2.3.dist-info → langchain_agentx_python-2.2.5.dist-info}/RECORD

@@ -1,4 +1,4 @@
-langchain_agentx/__init__.py,sha256=bMHXxvdlfRUJK-ZT43f2Hgef2tNuOs5bc3mv-F4BQRc,1614
+langchain_agentx/__init__.py,sha256=FDi8b0l3oV8v5zS-G33Yb0qoKw5-jje_-Rfu9sxHzOY,1614
 langchain_agentx/command/__init__.py,sha256=Ej260S5uFQcmEtGZQG_NH7BYjHoStrpBLtGUsBTxyZk,631
 langchain_agentx/command/allowed_tools.py,sha256=TVA0VM8rm98H-QbLK_GRiX5RhEAZFxKawliMi4kk96A,3359
 langchain_agentx/command/context.py,sha256=DIGOGPBw5UGDBm0WNNJlKx1h_9rCRmcdROv4DT61Qug,731
@@ -581,10 +581,11 @@ langchain_agentx/tools/glob/rg_list_backend.py,sha256=gTyFQE0eYHl-7LkSdah76S8bQn
 langchain_agentx/tools/glob/rg_pattern.py,sha256=YOV-1gdxC52vzdAwgz27l7mzPJvVuHqpqeWhiEnWQJs,1377
 langchain_agentx/tools/glob/tool.py,sha256=m746Vl_aI9eFmrXYECkg16zMln9YPVxqjtijPlc5ALA,14868
 langchain_agentx/tools/grep/__init__.py,sha256=AA9qa42Ap9tw6lPQkNgKzYmr4hu44eP93qVdyP-eFNU,162
-langchain_agentx/tools/grep/backend.py,sha256=bzwRUJ_aZjs84oIG3l6IAVygGiLDyNsHPePiMaFMo-4,14539
+langchain_agentx/tools/grep/backend.py,sha256=12BHyDZccr7Hzvfumj3zGpXrSRNV_LiCbYYyG2Y3BCg,15062
 langchain_agentx/tools/grep/models.py,sha256=6fTSux0COK06weQ7PWYqCGBQx60OaNtqC5q7xKtf5i0,3860
 langchain_agentx/tools/grep/prompt.py,sha256=Euo1NErphk5WHxaKXwJH-1v7joblfwEFWHIYNthKkzo,1336
-langchain_agentx/tools/grep/rg_subprocess_controller.py,sha256=ijMJnKPo7iEDFBz-_YipTiPusrL6OO2XbWxHUuwpMfA,4056
+langchain_agentx/tools/grep/rg_subprocess_controller.py,sha256=A4RGCiZaIo8lrohqftzrOcDmU8VVDlSic1Pqy5ZF5Js,5315
+langchain_agentx/tools/grep/ripgrep_stdout_cap.py,sha256=b7krKaCXYMjkecRwhpB1a8gaJ96BW0oyvxhrlDMQTtA,3149
 langchain_agentx/tools/grep/tool.py,sha256=S_nGFqFgGHx9UhnXJdNvkdoHCJxLRZBDoPDd-Pxms0g,20513
 langchain_agentx/tools/plan_mode/__init__.py,sha256=wO5FX24xEB0Dx9h6bysBt1ql3wn0rjPYsg70mbl4S_0,402
 langchain_agentx/tools/plan_mode/constants.py,sha256=vBjcx9JTSOhU9jfCJ4RKnCxVQPn0HzHapouKxRf2Zns,293
@@ -695,7 +696,7 @@ langchain_agentx/utils/permissions/filesystem.py,sha256=79vRSRPnPadHlDOOYvvbuJaJ
 langchain_agentx/utils/settings/__init__.py,sha256=UXzHZmrBJsO8ZpDmHfclHXpS7rfpmqRoXEnmTFbtVpE,172
 langchain_agentx/utils/settings/managed_path.py,sha256=MVcw4F9bTrhKqTLom8ZiiqSqCREMbGcAK9Lt8hkD67M,1155
 langchain_agentx/workflow/__init__.py,sha256=wgjJM2wW0DbFHjsNbq2bKYgFs3BIPFRuQbH8Ry5kfys,4324
-langchain_agentx/workflow/base.py,sha256=rzZTH0ciepTglXfhDMkhl1uiJV4d_bXkOgpHlmu-N0w,33409
+langchain_agentx/workflow/base.py,sha256=g4U7hO4fNRBiwh8Y3yLiU8Rgo1AgahaXV1L7lPob32c,33600
 langchain_agentx/workflow/batch.py,sha256=rdE9xbQ2-SI3-6yNTsKoSylDoTD5B0djLSKwqy1BdZ8,5474
 langchain_agentx/workflow/catalog_registry.py,sha256=tYUny5FkHwQU-RRUxOdxaJhiRV_9VRXU636Yn_Gzt-g,2109
 langchain_agentx/workflow/dag.py,sha256=Y1IR1IwnM79Xuev6HZnOvAE3Q23MRnA9lu4vg2Cie48,4469
@@ -705,7 +706,7 @@ langchain_agentx/workflow/execution.py,sha256=iCEkPgLkaoEM4cB6o7KAqIaBpFuY5HtGGI
 langchain_agentx/workflow/loop_factory.py,sha256=hCShf_gDnesW2A9JspaUY3upp3NCIguII_wRiXnSIUM,3954
 langchain_agentx/workflow/memory_drain_registry.py,sha256=Xm_ytbB-BbRIu3-h-KhptsCsmmueOiNZePUuG1hk8zk,1681
 langchain_agentx/workflow/memory_session_policy.py,sha256=2FI0ZbAA6MnxJexnLYLadQpiqipPQwVnUrTWgl55A74,3333
-langchain_agentx/workflow/node.py,sha256=0lFVxCKzCsrN61wBkZpniWwLVXPEwvedmCnqtljIvL8,4891
+langchain_agentx/workflow/node.py,sha256=03DtGBYkpFIv_XWMwLQsgWgS0aK4eHxvMfCI5DiBEmE,5069
 langchain_agentx/workflow/node_adapter.py,sha256=3ZjXhN-Yqg2JzYpRsvnhOvw8-gvGdzmFYkDG2AFndX4,5330
 langchain_agentx/workflow/projection_isolation.py,sha256=kx6cM8ZtZAFA2VZ8yBIgVaIQE5o4ZfvSoY3mcxSe3hk,634
 langchain_agentx/workflow/r8_event_stream_benchmark.py,sha256=VdDOWoK3yoGjYyVpAIN3qoQrChz6Ot8sxDw7Uh8RdhU,6562
@@ -715,7 +716,7 @@ langchain_agentx/workflow/run_session.py,sha256=LuFY52uvYfOBGD_Yi878pO5N2bVWJnVG
 langchain_agentx/workflow/runtime.py,sha256=DdL66SlcvTyU9KxA-JAS4dFxWuJXlYGQdtmBmZfk3dc,3267
 langchain_agentx/workflow/runtime_scope_path.py,sha256=k1PLnHK-xFEui6birSCWPZeKKV4_oXIip3mst_xDICo,2687
 langchain_agentx/workflow/runtime_scope_registry.py,sha256=WgyWAWTuM6xZl6ik2pAZCWBwToeTOaSu94kYqJKY2jU,2945
-langchain_agentx/workflow/state.py,sha256=zdtf2x547iAyLKBza2Ye0ROOkeSLoWEkNMUVbLfb1g4,2105
+langchain_agentx/workflow/state.py,sha256=PCSqwlJIP2rMg-TFhDFK2KzWXTC2dEn1q7eVCK1z4SY,9155
 langchain_agentx/workflow/structure_collector.py,sha256=w2ryitiR9t48DrYGBbR4zlSBOaa7dtrD0XqR23BbSHk,13574
 langchain_agentx/workflow/structure_errors.py,sha256=yYulfRRc70RU2rKjyJYEIhIspCH5taRa72kAwl3nOAA,941
 langchain_agentx/workflow/structure_validation.py,sha256=resy8jK_V1mKd_BQykwmpbesg6Yl2QbLavEUEQB2O_w,17698
@@ -760,8 +761,8 @@ langchain_agentx/workspace/root_grant_manager.py,sha256=W3gy8HTevbERbXqIgRcjzOXO
 langchain_agentx/workspace/tool_boundary.py,sha256=UDwX6swpSLsx9HNkYuuRRiV5o7ZZG_Bru2Yn0c5kNX8,5724
 langchain_agentx/workspace/validators.py,sha256=tQt-6TOcL8Fw7Ig5ebA9S7vGWh1rby920eFW6x8Tk9E,1439
 langchain_agentx/workspace/view.py,sha256=PGasqTaqhlD03SXXazHuw4RHfV681AIdlsYqL70pEjc,4774
-langchain_agentx_python-2.2.3.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-langchain_agentx_python-2.2.3.dist-info/METADATA,sha256=VcuvJI240NmP2VxSl2xxXD2BTvpnCLxnkXjg5aHzmQE,24250
-langchain_agentx_python-2.2.3.dist-info/WHEEL,sha256=51RkbunBAw4BWsgaQWTpPhg4Diwp3c9P5iaLk67Hdtg,92
-langchain_agentx_python-2.2.3.dist-info/top_level.txt,sha256=Ge284pniNt8xea0OLk2o9o32GqVpDhOYk20fwE-0xxA,17
-langchain_agentx_python-2.2.3.dist-info/RECORD,,
+langchain_agentx_python-2.2.5.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+langchain_agentx_python-2.2.5.dist-info/METADATA,sha256=H6Y0pRHIIab1cfuQGeOYWKXCW0WcbzoFI3fDduI-uDM,24250
+langchain_agentx_python-2.2.5.dist-info/WHEEL,sha256=51RkbunBAw4BWsgaQWTpPhg4Diwp3c9P5iaLk67Hdtg,92
+langchain_agentx_python-2.2.5.dist-info/top_level.txt,sha256=Ge284pniNt8xea0OLk2o9o32GqVpDhOYk20fwE-0xxA,17
+langchain_agentx_python-2.2.5.dist-info/RECORD,,