dynworkflow 0.1.2__tar.gz → 0.1.4__tar.gz

{dynworkflow-0.1.2 → dynworkflow-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dynworkflow
-Version: 0.1.2
+Version: 0.1.4
 Summary: Dynamic Workflow Library for Alkaid0
 Author: cxykevin
 Author-email: cxykevin <cxykevin@yeah.net>
@@ -40,18 +40,18 @@ def summarize() -> d.TaskGenerator:
 flow.execute(summarize())
 ```
 
-使用 `@flow.node(name)` 声明节点。普通节点可以返回 `None`、`Result` 或一个或多个下游 `Execute` 任务。生成器节点可以 `yield Agent` 或 `MultiAgent`，接收 Agent 结果后返回节点结果。
+使用 `@flow.node(name)` 声明节点。普通节点可以返回 `None`、`Result`、一个或多个下游 `Execute` 任务，或它们的组合（例如 `return d.Result(value), next_node(x=value)`）。`Result` 只记录本节点结果，不会阻止下游调度。生成器节点可以 `yield Agent` 或 `MultiAgent`，接收 Agent 结果后返回节点结果。
 
 ## 公共 API
 
 - `Flow`：创建并执行工作流。
 - `Flow.node(name)`：注册节点函数。
 - `Flow.execute(*tasks)`：在当前进程中执行任务，并在所有节点结束后抛出节点异常。
-- `Flow.run(*tasks)`：在 fork 子进程中运行工作流，并监听 stdin 中的 JSONL 控制命令。
+- `Flow.run(*tasks)`：运行工作流，并监听 stdin 中的 JSONL 控制命令。支持 fork 的平台在 fork 子进程中运行，其他平台（如 Windows）在当前进程中运行。
 - `Agent`：描述一次 Agent 请求。
 - `MultiAgent`：并发运行多个 Agent 请求。
 - `AgentClient`：连接 ACP WebSocket 端点。
-- `Result`：保存节点的最终结果。
+- `Result`：保存节点结果；可与下游任务同时返回。
 
 ## 执行语义
 
@@ -65,7 +65,7 @@ flow.execute(summarize())
 
 缓存默认启用。可以使用 `Flow(..., cache=False)` 关闭缓存。缓存文件位于 `.alkaid0/workflow.db`；设置 `ALKAID0_WORKFLOW_SESSION_ID` 可以隔离不同会话。
 
-可以通过 `Flow(..., report=True)` 或环境变量 `ALKAID0_WORKFLOW_REPORT=1` 开启 JSONL 状态上报。`Flow.run()` 会自动开启上报。事件包括 `graph`、`node`、`agent`、`agents_start`、`node_code` 和 `node_log`。
+可以通过 `Flow(..., report=True)` 或环境变量 `ALKAID0_WORKFLOW_REPORT=1` 开启 JSONL 状态上报。`Flow.run()` 会自动开启上报。事件包括 `graph`、`node`、`node_result`、`agent`、`agents_start`、`node_code` 和 `node_log`。
 
 ## 示例
 

{dynworkflow-0.1.2 → dynworkflow-0.1.4}/README.md

@@ -30,18 +30,18 @@ def summarize() -> d.TaskGenerator:
 flow.execute(summarize())
 ```
 
-使用 `@flow.node(name)` 声明节点。普通节点可以返回 `None`、`Result` 或一个或多个下游 `Execute` 任务。生成器节点可以 `yield Agent` 或 `MultiAgent`，接收 Agent 结果后返回节点结果。
+使用 `@flow.node(name)` 声明节点。普通节点可以返回 `None`、`Result`、一个或多个下游 `Execute` 任务，或它们的组合（例如 `return d.Result(value), next_node(x=value)`）。`Result` 只记录本节点结果，不会阻止下游调度。生成器节点可以 `yield Agent` 或 `MultiAgent`，接收 Agent 结果后返回节点结果。
 
 ## 公共 API
 
 - `Flow`：创建并执行工作流。
 - `Flow.node(name)`：注册节点函数。
 - `Flow.execute(*tasks)`：在当前进程中执行任务，并在所有节点结束后抛出节点异常。
-- `Flow.run(*tasks)`：在 fork 子进程中运行工作流，并监听 stdin 中的 JSONL 控制命令。
+- `Flow.run(*tasks)`：运行工作流，并监听 stdin 中的 JSONL 控制命令。支持 fork 的平台在 fork 子进程中运行，其他平台（如 Windows）在当前进程中运行。
 - `Agent`：描述一次 Agent 请求。
 - `MultiAgent`：并发运行多个 Agent 请求。
 - `AgentClient`：连接 ACP WebSocket 端点。
-- `Result`：保存节点的最终结果。
+- `Result`：保存节点结果；可与下游任务同时返回。
 
 ## 执行语义
 
@@ -55,7 +55,7 @@ flow.execute(summarize())
 
 缓存默认启用。可以使用 `Flow(..., cache=False)` 关闭缓存。缓存文件位于 `.alkaid0/workflow.db`；设置 `ALKAID0_WORKFLOW_SESSION_ID` 可以隔离不同会话。
 
-可以通过 `Flow(..., report=True)` 或环境变量 `ALKAID0_WORKFLOW_REPORT=1` 开启 JSONL 状态上报。`Flow.run()` 会自动开启上报。事件包括 `graph`、`node`、`agent`、`agents_start`、`node_code` 和 `node_log`。
+可以通过 `Flow(..., report=True)` 或环境变量 `ALKAID0_WORKFLOW_REPORT=1` 开启 JSONL 状态上报。`Flow.run()` 会自动开启上报。事件包括 `graph`、`node`、`node_result`、`agent`、`agents_start`、`node_code` 和 `node_log`。
 
 ## 示例
 

{dynworkflow-0.1.2 → dynworkflow-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dynworkflow"
-version = "0.1.2"
+version = "0.1.4"
 description = "Dynamic Workflow Library for Alkaid0"
 readme = "README.md"
 authors = [{ name = "cxykevin", email = "cxykevin@yeah.net" }]

{dynworkflow-0.1.2 → dynworkflow-0.1.4}/src/dynworkflow/cache.py

@@ -4,8 +4,9 @@
 缓存内容分两类：
 - ``agent_cache``：Agent 运行结果（MultiAgent 按单个 agent 分别缓存），
   以及未正常结束会话的 ACP sessionId（供下次按需 ACP load 续跑）；
-- ``node_cache``：节点执行结果——终值（Result/None）或下游调度描述
-  （Execute 链序列化为 [目标节点 id + 调用时参数]，命中时重建重放）。
+- ``node_cache``：节点执行结果——终值（Result/None）、下游调度
+  （Execute 链序列化为 [目标节点 id + 调用时参数]），或两者的组合；
+  命中时重建重放。
 
 联合键统一为 [会话作用域 + 工作流名 + 节点 ID + 载荷 hash]；节点载荷
 包含函数源码体 hash（代码变更即失效）与全部有效参数。
@@ -204,11 +205,24 @@ class WorkflowCache:
             return False
         return self._put("agent_cache", info, serialized, extra_kind=kind)
 
+    @staticmethod
+    def _valid_execute_items(items: Any) -> bool:
+        """_valid_execute_items() 校验下游调度条目列表是否合法"""
+        if not isinstance(items, list):
+            return False
+        for item in items:
+            if (not isinstance(item, dict)
+                    or not isinstance(item.get("node_id"), str)
+                    or not isinstance(item.get("args"), dict)):
+                return False
+        return True
+
     def get_node(self, info: CacheKey) -> dict[str, Any] | None:
         """get_node() 查询节点条目。
 
-        返回形如 ``{"kind": "none"}``、``{"kind": "result", "value": ...}``
-        或 ``{"kind": "executes", "items": [{"node_id": ..., "args": ...}]}``；
+        返回形如 ``{"kind": "none"}``、``{"kind": "result", "value": ...}``、
+        ``{"kind": "executes", "items": [{"node_id": ..., "args": ...}]}``
+        或 ``{"kind": "items", "items": [...]}``（Result 与下游调度组合）；
         格式非法视为未命中。
         """
         conn = self._conn
@@ -232,17 +246,32 @@ class WorkflowCache:
         if not isinstance(parsed, dict):
             return None
         kind = parsed.get("kind")
-        if kind not in {"none", "result", "executes"}:
+        if kind not in {"none", "result", "executes", "items"}:
             return None
         if kind == "executes":
+            if not self._valid_execute_items(parsed.get("items")):
+                return None
+        elif kind == "items":
             items = parsed.get("items")
-            if not isinstance(items, list):
+            if not isinstance(items, list) or not items:
                 return None
+            result_count = 0
             for item in items:
-                if (not isinstance(item, dict)
-                        or not isinstance(item.get("node_id"), str)
-                        or not isinstance(item.get("args"), dict)):
+                if not isinstance(item, dict):
+                    return None
+                item_kind = item.get("kind")
+                if item_kind == "result":
+                    if "value" not in item:
+                        return None
+                    result_count += 1
+                elif item_kind == "execute":
+                    if (not isinstance(item.get("node_id"), str)
+                            or not isinstance(item.get("args"), dict)):
+                        return None
+                else:
                     return None
+            if result_count > 1:
+                return None
         return parsed
 
     def put_node(self, info: CacheKey, descriptor: dict[str, Any]) -> bool:

{dynworkflow-0.1.2 → dynworkflow-0.1.4}/src/dynworkflow/flow.py

@@ -11,6 +11,7 @@ import threading
 import time
 import ast
 import textwrap
+import traceback
 from enum import Enum
 
 from .agent import (Agent, AgentClientInterface, MultiAgent, AgentStatus,
@@ -43,7 +44,7 @@ class Graph(TypedDict):
 
 
 class Result:
-    "Result 向 Main Agent 返回结果"
+    "Result 保存节点结果；节点可同时继续调度下游任务"
 
     def __init__(self, result: Any) -> None:
         self.result_val = result
@@ -52,7 +53,7 @@ class Result:
         return f"Result({self.result_val})"
 
     def __str__(self) -> str:
-        return str(self.result)
+        return str(self.result_val)
 
     def result(self) -> Any:
         "Result.result() 获取结果"
@@ -76,20 +77,54 @@ class NodeStatus(Enum):
     ERROR = "error"      # 完成
 
 
+def _split_node_result(
+        ret: 'NodeResult') -> "tuple[list[Any], list[Execute]]":
+    '"_split_node_result() 拆分节点返回值为 (Result 值列表, 下游任务列表)"'
+
+    if ret is None:
+        return [], []
+    if isinstance(ret, (Result, Execute)):
+        items: list[Any] = [ret]
+    elif isinstance(ret, (list, tuple)):
+        items = list(ret)
+    else:
+        raise ValueError(f"Invalid node result: {ret!r}")
+    results: list[Any] = []
+    executes: list[Execute] = []
+    for item in items:
+        if isinstance(item, Result):
+            results.append(item.result())
+        elif isinstance(item, Execute):
+            executes.append(item)
+        else:
+            raise ValueError(f"Invalid node result item: {item!r}")
+    if len(results) > 1:
+        raise ValueError("A node may return at most one Result")
+    return results, executes
+
+
 def _describe_node_result(ret: 'NodeResult') -> "dict[str, Any] | None":
     '"_describe_node_result() 把节点返回值序列化为缓存描述符；不可缓存时返回 None'
 
-    if ret is None:
-        return {"kind": "none"}
-    if isinstance(ret, Result):
+    results, executes = _split_node_result(ret)
+    exec_items: list[dict[str, Any]] = [
+        {"node_id": item._node._node_id, "args": dict(item._args)}
+        for item in executes
+    ]
+    if not results:
+        if not exec_items:
+            return {"kind": "none"}
+        return {"kind": "executes", "items": exec_items}
+    if not exec_items:
         # value 含不可序列化对象时由 put_node 整体放弃写入
-        return {"kind": "result", "value": ret.result()}
-    items = list(ret) if isinstance(ret, (list, tuple)) else [ret]
-    exec_items: list[dict[str, Any]] = []
-    for item in items:
-        exec_items.append(
-            {"node_id": item._node._node_id, "args": dict(item._args)})
-    return {"kind": "executes", "items": exec_items}
+        return {"kind": "result", "value": results[0]}
+    items: list[dict[str, Any]] = [
+        {"kind": "result", "value": results[0]}]
+    items.extend(
+        {"kind": "execute", "node_id": item._node._node_id,
+         "args": dict(item._args)}
+        for item in executes)
+    return {"kind": "items", "items": items}
 
 
 class Node():
@@ -182,6 +217,13 @@ class Node():
         flow._reporter.report_node(flow._workflow_id, self._node_id,
                                    state.value, args, cached=cached)
 
+    def _report_result(self, flow: 'Flow', value: Any) -> None:
+        "_report_result() 推送一次节点终值事件（未启用上报时为空操作）"
+        if flow._reporter is None:
+            return
+        flow._reporter.report_node_result(flow._workflow_id, self._node_id,
+                                          value)
+
     def _run(self, flow: 'Flow') -> None:
         "Node.run() 执行节点，并把异常延迟到工作流结束统一抛出。"
         try:
@@ -300,6 +342,9 @@ class Node():
             self._report_status(flow, NodeStatus.ERROR, dic)
             return
 
+        # 先校验返回值：多个 Result 或非法元素在此失败并转为节点错误
+        results, executes = _split_node_result(ret)
+
         self.status = NodeStatus.DONE
         # 推送：节点执行完成
         self._report_status(flow, NodeStatus.DONE, dic)
@@ -310,49 +355,70 @@ class Node():
             if descriptor is not None:
                 flow.cache.put_node(node_info, descriptor)
 
-        # 无返回值
-        if ret is None:
-            return
-        # 返回值处理
-        if isinstance(ret, Result):
-            flow._result[self._node_id] = ret.result()
-            return
+        # 记录 Result；与下游调度互不排斥，可同时生效
+        if results:
+            value = results[0]
+            flow._result[self._node_id] = value
+            # 推送：节点终值（宿主据此在 workflow 视图里展示 Result）
+            self._report_result(flow, value)
 
         # 执行流程下一步
-        if isinstance(ret, Execute):
-            ret = [ret]
-        for i in ret:
-            i.run(flow)
+        for item in executes:
+            item.run(flow)
 
     def _replay_cached(self, flow: 'Flow', cached: dict[str, Any]) -> None:
-        "Node._replay_cached() 重放缓存的节点结果（终值或下游调度）"
+        "Node._replay_cached() 重放缓存的节点结果（终值/下游调度/两者组合）"
         kind = cached.get("kind")
         if kind == "none":
             return
         if kind == "result":
-            flow._result[self._node_id] = cached.get("value")
+            self._replay_result(flow, cached.get("value"))
             return
+        known = {node._node_id: node for node in flow._nodes}
         if kind == "executes":
-            known = {node._node_id: node for node in flow._nodes}
             items = cached.get("items")
             if not isinstance(items, list):
                 items = []
-            items = cast(list[dict[str, Any]], items)
-            for item in items:
-                target_id = str(item.get("node_id"))
-                target = known.get(target_id)
-                if target is None:
+            self._replay_executes(flow, known,
+                                  cast(list[dict[str, Any]], items))
+            return
+        if kind == "items":
+            raw_items = cached.get("items")
+            if not isinstance(raw_items, list):
+                raw_items = []
+            for item in cast(list[dict[str, Any]], raw_items):
+                item_kind = item.get("kind")
+                if item_kind == "result":
+                    self._replay_result(flow, item.get("value"))
+                elif item_kind == "execute":
+                    self._replay_executes(flow, known, [item])
+                else:
                     raise ValueError(
-                        f"Cached target node not found: {target_id}")
-                # 重建调用点参数并走正常填充/调度路径，
-                # 完整保留跨节点部分参数累积语义。
-                args: Any = item.get("args")
-                args_value: dict[str, Any] = dict(cast(dict[str, Any], args)) if isinstance(
-                    args, dict) else {}
-                Execute(target, args_value).run(flow)
+                        f"Invalid cached node item kind: {item_kind!r}")
             return
         raise ValueError(f"Invalid cached node result kind: {kind!r}")
 
+    def _replay_result(self, flow: 'Flow', value: Any) -> None:
+        "_replay_result() 写入并上报缓存中的节点终值"
+        flow._result[self._node_id] = value
+        # 缓存命中同样上报终值，宿主视图与真实执行保持一致
+        self._report_result(flow, value)
+
+    def _replay_executes(self, flow: 'Flow', known: "dict[str, Node]",
+                         items: list[dict[str, Any]]) -> None:
+        "_replay_executes() 重放缓存中的下游调度"
+        for item in items:
+            target_id = str(item.get("node_id"))
+            target = known.get(target_id)
+            if target is None:
+                raise ValueError(f"Cached target node not found: {target_id}")
+            # 重建调用点参数并走正常填充/调度路径，
+            # 完整保留跨节点部分参数累积语义。
+            args: Any = item.get("args")
+            args_value: dict[str, Any] = dict(
+                cast(dict[str, Any], args)) if isinstance(args, dict) else {}
+            Execute(target, args_value).run(flow)
+
     def _create_thread_task(self, flow: 'Flow') -> threading.Thread:
         "Node.thread_tast() 启动线程"
         if (self._thread is not None and self._thread.is_alive()):
@@ -427,11 +493,14 @@ type Agents = (
     MultiAgent |
     Agent
 )  # Agents 子 Agent 对象
-type NodeResult = (
+type NodeResultItem = (
     Execute |
-    list[Execute] |
-    tuple[Execute, ...] |
-    Result |
+    Result
+)  # NodeResultItem 节点返回的单个元素
+type NodeResult = (
+    NodeResultItem |
+    list[NodeResultItem] |
+    tuple[NodeResultItem, ...] |
     None
 )  # Nodes 节点返回对象
 type TaskGenerator = (Generator[
@@ -579,7 +648,7 @@ class Flow:
         return {
             "nodes": {
                 node._node_id: {  # 节点信息
-                    "name": node._node_id,
+                    "name": node._node_name,  # 显示名（@flow.node("...") 的名字）
                 } for node in self._nodes
             },
             "edges": edges,
@@ -614,7 +683,11 @@ class Flow:
         self._raise_exceptions()
 
     def run(self, *tasks: Execute) -> NoReturn:
-        """Node.run() 在 fork 子进程执行工作流，主进程监听 stdin JSONL。"""
+        """Flow.run() 运行工作流，同时监听 stdin JSONL 控制命令。
+
+        支持 fork 的平台（Linux/macOS）在 fork 子进程内执行工作流；
+        没有 fork 的平台（如 Windows）在当前进程内执行工作流。
+        """
         sys.stdout.write("\x1edynworkflow\x1f\n")
         sys.stdout.flush()
         self._report = True
@@ -622,6 +695,26 @@ class Flow:
             self._reporter = optional_reporter(True)
         if self._agent is None:
             raise ValueError("No availble agent found!")
+        if "fork" in multiprocessing.get_all_start_methods():
+            self._run_forked(tasks)
+        else:
+            # Windows 等平台既没有 fork，spawn 又无法序列化 Flow 状态与
+            # 节点函数，因此退化为在当前进程内执行工作流。
+            self._run_in_current_process(tasks)
+
+    def _exit(self, code: int) -> NoReturn:
+        "_exit() 强制刷新输出并短暂等待后退出，避免宿主漏读最后一批事件"
+        try:
+            sys.stdout.flush()
+            sys.stderr.flush()
+        except Exception:
+            # 管道已关闭等情况不影响退出流程。
+            pass
+        time.sleep(0.2)
+        sys.exit(code)
+
+    def _run_forked(self, tasks: tuple[Execute, ...]) -> NoReturn:
+        "_run_forked() 在 fork 子进程执行工作流，当前进程监听 stdin JSONL。"
         control: Any = multiprocessing.get_context("fork").Queue()
         process = multiprocessing.get_context("fork").Process(
             target=self._execute_child, args=(tasks, control))
@@ -657,7 +750,37 @@ class Flow:
                 process.terminate()
                 process.join(2)
         # Preserve a non-zero exit status when the child failed unexpectedly.
-        sys.exit(process.exitcode if process.exitcode is not None else 0)
+        self._exit(process.exitcode if process.exitcode is not None else 0)
+
+    def _run_in_current_process(self, tasks: tuple[Execute, ...]) -> NoReturn:
+        "_run_in_current_process() 在没有 fork 的平台于当前进程内执行工作流，"
+        "stdin 由 daemon 线程转发到控制队列。"
+        control: Any = queue.Queue()
+
+        def read_stdin() -> None:
+            try:
+                for line in sys.stdin:
+                    try:
+                        command = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    if isinstance(command, dict):
+                        command = cast(dict[str, str], command)
+                        control.put(command)
+                        if command.get("cmd") == "shutdown":
+                            return
+            finally:
+                # stdin 结束视为关闭请求，与 fork 版本父进程的清理行为一致。
+                control.put({"cmd": "shutdown"})
+
+        threading.Thread(target=read_stdin, daemon=True).start()
+        try:
+            self._execute_child(tasks, control)
+        except BaseException:
+            # 保留非零退出码，行为与 fork 子进程异常退出保持一致。
+            traceback.print_exc()
+            self._exit(1)
+        self._exit(0)
 
     def _execute_child(self, tasks: tuple[Execute, ...], control: Any) -> None:
         def listen() -> None:

{dynworkflow-0.1.2 → dynworkflow-0.1.4}/src/dynworkflow/reporter.py

@@ -156,6 +156,20 @@ class StatusReporter:
             "code": code,
         }])
 
+    def report_node_result(self, workflow_id: str, node_id: str,
+                           result: Any) -> None:
+        """report_node_result() 上报节点终值（`Result` 携带的 value）。
+
+        值不可 JSON 序列化时由 `emit` 的 `default=str` 兜底；上报失败不影响执行。
+        """
+        self.emit([{
+            "type": "node_result",
+            "time": _utc_now(),
+            "workflow": workflow_id,
+            "nodeId": node_id,
+            "result": result,
+        }])
+
     def report_graph(self, workflow_id: str, graph: Graph) -> None:
         """report_graph() 上报 Flow 生成的流程图（set 序列化为有序列表）。"""
         self.emit([{